osmocom
/
wireshark
11
0
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity

Windows: Switch from HTML Help to plain HTML. 

Switch from HTML Help to plain HTML files. In the NSIS and WiX installers,
place the help assets in a directory with a friendly name.
This commit is contained in:
Gerald Combs 2021-06-01 17:02:08 -07:00 committed by Wireshark GitLab Utility
parent 6846271b76
commit 6bfab69d14
16 changed files with 46 additions and 302 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
cmake/modules/FindHTMLHelp.cmake
View File

@ -1,58 +0,0 @@
# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or https://cmake.org/licensing for details.
#.rst:
# FindHTMLHelp
# ------------
#
# This module looks for Microsoft HTML Help Compiler
#
# It defines:
#
# ::
#
# HTML_HELP_COMPILER : full path to the Compiler (hhc.exe)
# HTML_HELP_INCLUDE_PATH : include path to the API (htmlhelp.h)
# HTML_HELP_LIBRARY : full path to the library (htmlhelp.lib)
if(WIN32)
find_program(HTML_HELP_COMPILER
NAMES hhc
PATHS
"[HKEY_CURRENT_USER\\Software\\Microsoft\\HTML Help Workshop;InstallDir]"
PATH_SUFFIXES "HTML Help Workshop"
)
get_filename_component(HTML_HELP_COMPILER_PATH "${HTML_HELP_COMPILER}" PATH)
find_path(HTML_HELP_INCLUDE_PATH
NAMES htmlhelp.h
PATHS
"${HTML_HELP_COMPILER_PATH}/include"
"[HKEY_CURRENT_USER\\Software\\Microsoft\\HTML Help Workshop;InstallDir]/include"
PATH_SUFFIXES "HTML Help Workshop/include"
)
find_library(HTML_HELP_LIBRARY
NAMES htmlhelp
PATHS
"${HTML_HELP_COMPILER_PATH}/lib"
"[HKEY_CURRENT_USER\\Software\\Microsoft\\HTML Help Workshop;InstallDir]/lib"
PATH_SUFFIXES "HTML Help Workshop/lib"
)
# handle the QUIETLY and REQUIRED arguments and set HTMLHelp_FOUND to TRUE if
# all listed variables are TRUE
INCLUDE(FindPackageHandleStandardArgs)
FIND_PACKAGE_HANDLE_STANDARD_ARGS(HTMLHelp
REQUIRED_VARS HTML_HELP_COMPILER HTML_HELP_INCLUDE_PATH HTML_HELP_LIBRARY
)
mark_as_advanced(
HTML_HELP_COMPILER
HTML_HELP_INCLUDE_PATH
HTML_HELP_LIBRARY
)
endif()

55
cmake/modules/FindXSLTPROC.cmake
View File

@ -145,58 +145,3 @@ MACRO(XML2HTML _target_dep _dir_pfx _mode _dbk_source _gfx_sources)
)
ENDIF()
ENDMACRO(XML2HTML)
# Translate XML to HHP
#XML2HHP(
# wsug or wsdg
# user-guide.xml or developer-guide.xml
#)
MACRO(XML2HHP _target_dep _guide _title _dbk_source)
# We depend on the docbook target to avoid parallel builds.
SET(_dbk_dep ${_target_dep}_docbook)
GET_FILENAME_COMPONENT( _source_base_name ${_dbk_source} NAME_WE )
set( _output_chm ${_source_base_name}.chm )
set( _output_hhp ${_source_base_name}.hhp )
set( _output_toc_hhc ${_source_base_name}-toc.hhc )
set( _docbook_plain_title ${_source_base_name}-plain-title.xml )
get_docbook_xml_depends(_dbk_xml_deps "${_dbk_source}")
SET(_gfxdir ${_guide}_graphics)
SET(_basedir ${_guide}_chm)
ADD_CUSTOM_COMMAND(
OUTPUT
${_output_hhp}
${_output_toc_hhc}
COMMAND ${CMAKE_COMMAND} -E make_directory ${_basedir}
COMMAND ${CMAKE_COMMAND} -E make_directory ${_basedir}/${_gfxdir}
COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/${_gfxdir} ${_basedir}/${_gfxdir}
COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/common_graphics ${_basedir}/${_gfxdir}
# Dumb down our title. HTML Help can render most of our content
# correctly because we tell it to use the IE9 rendering engine in
# custom_layer_chm.xsl. However, this doesn't apply to the window
# title or TOC. Neither "’" nor "’" will render correctly,
# so just add a _title argument and set it in CMakeLists.txt.
COMMAND ${PERL_EXECUTABLE} -p
-e "s|<title>Wireshark.*s Guide</title>|<title>${_title}</title>|"
< ${_dbk_source}
> ${_docbook_plain_title}
COMMAND ${XSLTPROC_EXECUTABLE}
--path "${_xsltproc_path}"
--stringparam base.dir ${_basedir}/
--stringparam htmlhelp.title ${_title}
--stringparam htmlhelp.chm ${_output_chm}
--stringparam htmlhelp.hhp ${_output_hhp}
--stringparam htmlhelp.hhc ${_output_toc_hhc}
${_common_xsltproc_args}
--stringparam admon.graphics.path ${_gfxdir}/
--nonet custom_layer_chm.xsl
${_docbook_plain_title}
DEPENDS
${_dbk_xml_deps}
${_dbk_dep}
# AsciiDoc uses UTF-8 by default, which is unsupported by HTML
# Help. We may want to render an ISO-8859-1 version, or get rid
# of HTML Help.
custom_layer_chm.xsl
)
ENDMACRO(XML2HHP)

12
cmake/modules/hhc.cmake
View File

@ -1,12 +0,0 @@
# hhc.exe returns 1 on success - which cmake instprets as failure in case
# of add_custom_command.
# Params are
# cmake -P /path/to/hhc.cmake "/path/to/hhc.exe" project.hhp
set(_hhc_executable ${CMAKE_ARGV3})
set(_project_file ${CMAKE_ARGV4})
execute_process(
COMMAND ${_hhc_executable} ${_project_file}
RESULT_VARIABLE _return_code
)

53
docbook/CMakeLists.txt
View File

@ -21,35 +21,6 @@ function(set_docbook_target_properties _target)
)
endfunction(set_docbook_target_properties)
if(WIN32)
find_package( HTMLHelp )
if(HTML_HELP_COMPILER)
# We do not need the HTML Help headers and library, just the
# compiler. To avoid confusion, report the package as found.
# https://gitlab.kitware.com/cmake/cmake/issues/15886
set(HTMLHelp_FOUND 1)
endif()
macro( HHP2CHM _hhpsource )
get_filename_component( _source_base_name ${_hhpsource} NAME_WE )
add_custom_command(
OUTPUT ${_output_chm}
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
# The number and order of arguments MUST match hhc.cmake.
COMMAND ${CMAKE_COMMAND} -P
${CMAKE_SOURCE_DIR}/cmake/modules/hhc.cmake
"${HTML_HELP_COMPILER}"
${_hhpsource}
DEPENDS
${_hhpsource}
)
endmacro()
else()
macro( HHP2CHM _hhpsource )
# Dummy.
endmacro()
endif()
set(COMMON_FILES
common_src/GPL_appendix.adoc
)
@ -425,18 +396,6 @@ if(ASCIIDOCTOR_FOUND AND ASCIIDOCTOR_PDF_EXECUTABLE)
add_dependencies(user_guides user_guide_pdf)
endif()
if(WIN32 AND ASCIIDOCTOR_FOUND)
XML2HHP(user_guide wsug "Wireshark User's Guide" user-guide.xml)
HHP2CHM(user-guide.hhp)
add_custom_target(
user_guide_chm
DEPENDS
user-guide.chm
)
set_docbook_target_properties(user_guide_chm)
add_dependencies(user_guides user_guide_chm)
endif()
# Developer's Guide chain.
if(ASCIIDOCTOR_FOUND AND XSLTPROC_EXECUTABLE)
XML2HTML(
@ -477,18 +436,6 @@ if(ASCIIDOCTOR_FOUND AND ASCIIDOCTOR_PDF_EXECUTABLE)
add_dependencies(developer_guides developer_guide_pdf)
endif()
if(WIN32 AND ASCIIDOCTOR_FOUND)
XML2HHP(developer_guide wsdg "Wireshark Developer's Guide" developer-guide.xml)
HHP2CHM(developer-guide.hhp)
add_custom_target(
developer_guide_chm
DEPENDS
developer-guide.chm
)
set_docbook_target_properties(developer_guide_chm)
add_dependencies(developer_guides developer_guide_chm)
endif()
if (GUIDE_INSTALL_DIRS)
# The installation location and DOC_DIR in ui/help_url.c must
# match.

41
docbook/custom_layer_chm.xsl
View File

@ -1,41 +0,0 @@
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<!-- copied from custom_layer_pdf.xsl -->
<!-- import the main stylesheet -->
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl"/>
<xsl:param name="htmlhelp.window.geometry">[160,100,950,750]</xsl:param>
<!--
Tell the WebBrowser control to use the IE9 rendering engine if present so
that our admonition graphics (which are SVG) show up. We might be able to
get away with "IE=8" if needed.
http://stackoverflow.com/questions/4612255/regarding-ie9-webbrowser-control/4613025#4613025
-->
<xsl:template name="system.head.content">
<meta http-equiv="X-UA-Compatible" content="IE=9" />
</xsl:template>
<xsl:template name="user.head.content">
<style type="text/css">
html body, h1, h2, h3, h4, h5, h6,
div.toc p b,
div.list-of-figures p b,
div.list-of-tables p b,
div.abstract p.title
{
font-family: 'Segoe UI', 'Lucida Grande', Verdana, Arial, Helvetica, sans-serif;
font-size: 14px;
}
</style>
</xsl:template>
<!-- reduce the size of programlisting to make them fit the page -->
<xsl:attribute-set name="monospace.verbatim.properties">
<xsl:attribute name="font-size">80%</xsl:attribute>
</xsl:attribute-set>
</xsl:stylesheet>

29
docbook/wsdg_src/WSDG_chapter_tools.adoc
View File

@ -287,9 +287,6 @@ compiler (MSVC), you'll need:
. Windows platform headers and libraries (e.g.
_windows.h_, _WS2_32.lib_)
+
// Can we drop support for CHM?
. HTML help headers and libraries (_htmlhelp.h_, _htmlhelp.lib_)
==== Official Toolchain Packages And Alternatives
@ -469,7 +466,6 @@ Man page HTML:: pod2html
Guide HTML:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL
Guide PDF:: Asciidoctor
Guide HTML Help:: Asciidoctor → _DocBook XML_ → xsltproc + DocBook XSL → HHC
Release notes HTML:: Asciidoctor
Release notes text:: Asciidoctor → _HTML_ → html2text.py
@ -491,9 +487,9 @@ but _not_ with Asciidoctor.
==== DocBook XML and XSL
Converting from DocBook to HTML and CHM requires the DocBook DTD
(http://www.sagehill.net/docbookxsl/ToolsSetup.html) and DocBook
stylesheets
Converting from DocBook to HTML requires the DocBook DTD
(http://www.sagehill.net/docbookxsl/ToolsSetup.html)
and DocBook stylesheets
(http://www.sagehill.net/docbookxsl/InstallStylesheets.html).
These are available via installable packages on most Linux distributions, Chocolatey, and Homebrew.
@ -502,25 +498,6 @@ These are available via installable packages on most Linux distributions, Chocol
http://xmlsoft.org/xslt/[xsltproc] converts DocBook XML to various formats based on XSL stylesheets.
It either ships as part of the operating system or is available via an installable package on most Linux distributions, Chocolatey, and Homebrew.
==== HTML Help
HTML Help is used to create the User’s and Developer’s Guide in .chm format.
The User’s Guide .chm file is included with the NSIS and WiX installers and
is used as Wireshark's built-in help on Windows.
This compiler is used to generate a .chm file from a bunch of HTML files -- in
our case to generate the User’s and Developer’s Guide in .chm format.
The compiler is only available as the free (as in beer) "HTML Help Workshop"
download. If you want to compile the guides yourself, you need to download and
install this. If you don't install it into the default directory, you may also
have a look at the HHC_DIR setting in the file docbook/Makefile.
The files `htmlhelp.c` and `htmlhelp.lib` are required to
be able to open .chm files from Wireshark and show the
online help. Both files are part of the SDK (standalone (P)SDK or MSVC
since 2002).
[[ChToolsDebugger]]
=== Debugger

2
packaging/nsis/CMakeLists.txt
View File

@ -229,7 +229,7 @@ macro( ADD_NSIS_PACKAGE_TARGET )
DEPENDS
${NSIS_FILES}
copy_data_files
user_guide_chm
user_guide_html
faq_html
${DATAFILE_DIR}/uninstall.exe
)

2
packaging/nsis/uninstall.nsi
View File

@ -232,6 +232,7 @@ Delete "$INSTDIR\wka"
Delete "$INSTDIR\services"
Delete "$INSTDIR\pdml2html.xsl"
Delete "$INSTDIR\pcrepattern.3.txt"
Delete "$INSTDIR\Wireshark User's Guide\*.*"
Delete "$INSTDIR\user-guide.chm"
Delete "$INSTDIR\example_snmp_users_file"
Delete "$INSTDIR\ipmap.html"
@ -291,6 +292,7 @@ RMDir "$INSTDIR\styles\translations"
RMDir "$INSTDIR\styles"
RMDir "$SMPROGRAMS\${PROGRAM_NAME}"
RMDir "$INSTDIR\help"
RMDir "$INSTDIR\Wireshark User's Guide"
RMDir "$INSTDIR\diameter"
RMDir "$INSTDIR\snmp\mibs"
RMDir "$INSTDIR\snmp"

4
packaging/nsis/wireshark.nsi
View File

@ -1200,8 +1200,10 @@ SectionGroupEnd ; "Tools"
!ifdef DOCBOOK_DIR
Section "Documentation" SecDocumentation
;-------------------------------------------
SetOutPath "$INSTDIR\Wireshark User's Guide"
File /r "${DOCBOOK_DIR}\wsug_html_chunked\*.*"
SetOutPath $INSTDIR
File "${DOCBOOK_DIR}\user-guide.chm"
File "${DOCBOOK_DIR}\faq.html"
SectionEnd
!endif

14
packaging/wix/CMakeLists.txt
View File

@ -16,6 +16,7 @@ set(WIX_GENERATED_FILES
${CMAKE_CURRENT_BINARY_DIR}/QtTranslation.wxs
${CMAKE_CURRENT_BINARY_DIR}/RadiusDict.wxs
${CMAKE_CURRENT_BINARY_DIR}/SNMPMibs.wxs
${CMAKE_CURRENT_BINARY_DIR}/UsersGuide.wxs
)
set(WIX_GENERATED_FILES ${WIX_GENERATED_FILES} PARENT_SCOPE)
@ -47,6 +48,7 @@ set(WIX_OUT_FILES
${CMAKE_CURRENT_BINARY_DIR}/QtTranslation.wixobj
${CMAKE_CURRENT_BINARY_DIR}/RadiusDict.wixobj
${CMAKE_CURRENT_BINARY_DIR}/SNMPMibs.wixobj
${CMAKE_CURRENT_BINARY_DIR}/UsersGuide.wixobj
${CMAKE_CURRENT_BINARY_DIR}/Wireshark.wixobj
${CMAKE_CURRENT_BINARY_DIR}/WiresharkOptionsDlg.wixobj
${CMAKE_CURRENT_BINARY_DIR}/WiresharkWixUI.wixobj
@ -217,6 +219,7 @@ set(WIX_CANDLE_DEFINES
-dQtTranslationDir=${ARCHIVE_OUTPUT_PATH}/${CMAKE_BUILD_TYPE}/translations
-dRadiusDictDir=${ARCHIVE_OUTPUT_PATH}/${CMAKE_BUILD_TYPE}/radius
-dSnmpMibDir=${ARCHIVE_OUTPUT_PATH}/${CMAKE_BUILD_TYPE}/snmp/mibs
-dUsersGuideDir=${ARCHIVE_OUTPUT_PATH}/${CMAKE_BUILD_TYPE}/docbook/wsug_html_chunked
-dVCRedistVersion=${MSVC_CRT_VERSION}
-dVCRedistDir=${MERGE_MODULE_DIR}
${d_smi_dir}
@ -269,6 +272,14 @@ macro( ADD_WIX_PACKAGE_TARGET )
DEPENDS "${_wix_source_dir}/windeployqt-to-wix.ps1"
)
# UsersGuide.wxs. Collects the contents of wsug_html_chunked.
# Generated with heat.exe
add_custom_command(OUTPUT ${_wix_binary_dir}/UsersGuide.wxs
COMMAND ${WIX_HEAT_EXECUTABLE} dir ${CMAKE_BINARY_DIR}/docbook/wsug_html_chunked
${WIX_HEAT_FLAGS} -cg CG.Documentation -dr dirUsersGuide -var var.UsersGuideDir
-out ${_wix_binary_dir}/UsersGuide.wxs
)
# SNMPMibs.wxs. Collects all MIBs in "output" snmp/mibs
# directory. Generated with heat.exe
add_custom_command(OUTPUT ${_wix_binary_dir}/SNMPMibs.wxs
@ -308,7 +319,7 @@ macro( ADD_WIX_PACKAGE_TARGET )
DEPENDS
${WIX_FILES}
copy_data_files
user_guide_chm
user_guide_html
faq_html
)
set_target_properties(wix_package_prep PROPERTIES
@ -340,6 +351,7 @@ endmacro( ADD_WIX_PACKAGE_TARGET )
set(CLEAN_FILES
DependentComponents.wxs
QtDependentComponents.wxs
UsersGuide.wxs
SNMPMibs.wxs
RadiusDict.wxs
Diameter.wxs

10
packaging/wix/ComponentGroups.wxi
View File

@ -566,14 +566,7 @@
</Fragment>
<?ifdef DOCBOOK_DIR?>
<!-- User Guide -->
<Fragment>
<DirectoryRef Id="INSTALLFOLDER">
<Component Id="cmpUserGuide_chm" Guid="*">
<File Id="filUserGuide_chm" KeyPath="yes" Source="$(var.DOCBOOK_DIR)\user-guide.chm" />
</Component>
</DirectoryRef>
</Fragment>
<!-- User Guide is created by heat -->
<!-- FAQ -->
<Fragment>
<DirectoryRef Id="INSTALLFOLDER">
@ -584,7 +577,6 @@
</Fragment>
<Fragment>
<ComponentGroup Id="CG.Documentation">
<ComponentRef Id="cmpUserGuide_chm" />
<ComponentRef Id="cmpFAQ_html" />
</ComponentGroup>
</Fragment>

1
packaging/wix/DirectoryStructure.wxi
View File

@ -23,6 +23,7 @@
<Directory Id="dirPluginsVersionCodecs" Name="codecs"/>
</Directory>
</Directory>
<Directory Id="dirUsersGuide" Name="Wireshark User's Guide"/>
<Directory Id="dirProfiles" Name="profiles"/>
<Directory Id="dirSnmp" Name="snmp">
<Directory Id="dirSnmpMibs" Name="mibs"/>

8
packaging/wix/README.adoc
View File

@ -8,10 +8,10 @@ It might one day replace the NSIS installer, but needs to be a little more compl
. You need the https://wixtoolset.org/[WiX toolset] to build the .msi installer.
Version 3.10 or later is recommended.
. SNMP, Radius, Diameter, and Qt translations files are harvested to be included in
the installer. Any custom/additional files just need to be written to the appropriate
build output directory and the installer will pick them up. NSIS required modifying
a file (custom_mibs.txt, etc) for inclusion
. The User's Guide, SNMP, Radius, Diameter, and Qt translations files are harvested to
be included in the installer. Any custom/additional files just need to be written to the
appropriate build output directory and the installer will pick them up. NSIS required
modifying a file (custom_mibs.txt, etc) for inclusion
. Plugin DLLs are not automatically harvested. To include your DLL, modify Plugins.wxi.

5
ui/CMakeLists.txt
View File

@ -92,11 +92,6 @@ endif()
target_link_libraries(ui wsutil caputils)
if (HTML_HELP_COMPILER)
add_definitions(-DHHC_DIR)
target_link_libraries(ui Htmlhelp.lib)
endif()
target_include_directories(ui SYSTEM
PRIVATE
${WINSPARKLE_INCLUDE_DIRS}

44
ui/help_url.c
View File

@ -19,12 +19,6 @@
#include "urls.h"
#include "wsutil/filesystem.h"
#ifdef HHC_DIR
#include <windows.h>
#include <htmlhelp.h>
#include <wsutil/unicode-utils.h>
#endif
// To do:
// - Automatically generate part or all of this, e.g. by parsing
// the DocBook XML or the chunked HTML.
@ -36,40 +30,30 @@ gchar *
user_guide_url(const gchar *page) {
GString *url = g_string_new("");
#if defined(WIN32)
/*
* Try to open local .chm file. This is not the most intuitive way to
* go about this but it fits in with the rest of the _url functions.
* The User's Guide is in a directory named "Wireshark User's Guide" in
* the program directory.
*/
#ifdef HHC_DIR
HWND hw;
g_string_printf(url, "%s\\user-guide.chm::/wsug_chm/%s>Wireshark Help",
get_datafile_dir(), page);
hw = HtmlHelpW(NULL,
utf_8to16(url->str),
HH_DISPLAY_TOPIC, 0);
/* if the .chm file could be opened, stop here */
if(hw != NULL) {
g_string_free(url, TRUE /* free_segment */);
return NULL;
GString *ug_dir = g_string_new("");
g_string_printf(ug_dir, "%s\\Wireshark User's Guide", get_datafile_dir());
if (g_file_test(ug_dir->str, G_FILE_TEST_IS_DIR)) {
g_string_printf(url, "file:///%s/%s", ug_dir->str, page);
}
#endif /* HHC_DIR */
#ifdef DOC_DIR
g_string_free(ug_dir, TRUE);
#elif defined(DOC_DIR)
if (g_file_test(DOC_DIR "/guides/wsug_html_chunked", G_FILE_TEST_IS_DIR)) {
/* try to open the HTML page from wireshark.org instead */
g_string_printf(url, "file://" DOC_DIR "/guides/wsug_html_chunked/%s", page);
} else {
#endif /* ifdef DOC_DIR */
/* try to open the HTML page from wireshark.org instead */
g_string_printf(url, WS_DOCS_URL "/wsug_html_chunked/%s", page);
#ifdef DOC_DIR
}
#endif /* ifdef DOC_DIR */
#endif /* WIN32 / DOC_DIR */
/* Fall back to wireshark.org. */
if (url->len == 0) {
g_string_printf(url, WS_DOCS_URL "/wsug_html_chunked/%s", page);
}
return g_string_free(url, FALSE);
}

10
ui/help_url.h
View File

@ -111,9 +111,8 @@ typedef enum {
HELP_STAT_FLOW_GRAPH
} topic_action_e;
/** Given a page in the Wireshark User's Guide return its URL. On Windows
* an attempt will be made to open User Guide URLs with HTML Help. If
* the attempt succeeds NULL will be returned.
/** Given a page in the Wireshark User's Guide return its URL. If the
* attempt succeeds NULL will be returned.
*
* @param page A page in the User's Guide.
* @return A static URL or NULL. A non-NULL return value must be freed
@ -121,9 +120,8 @@ typedef enum {
*/
gchar *user_guide_url(const gchar *page);
/** Given a topic action return its URL. On Windows an attempt will be
* made to open User Guide URLs with HTML Help. If the attempt succeeds
* NULL will be returned.
/** Given a topic action return its URL. If the attempt succeeds NULL
* will be returned.
*
* @param action Topic action.
* @return A static URL or NULL. A non-NULL return value must be freed