CMake: Enable DocBook on Windows.

Add a wrapper script and CMake macros which lets us run Cygwin's a2x
from Windows. Add *another* wrapper script that ignores the return value
of hhc.exe.

Move the ASCIIDOC2DOCBOOK macro to FindASCIIDOC.cmake. Add FindHHC.cmake.
Add hints to FindFOP.cmake.

Use unique file names in the HTML Help chain in an attempt to avoid a
race condition.

To do:
- Fix curly quote in HHC title.

Change-Id: I9b154b7fbd02703656e2ab380199ec0a6db4e36d
Reviewed-on: https://code.wireshark.org/review/6379
Reviewed-by: Gerald Combs <gerald@wireshark.org>

4 files changed, 202 insertions, 38 deletions

diff --git a/cmake/modules/FindASCIIDOC.cmake b/cmake/modules/FindASCIIDOC.cmake
index d957aec51c..a857188af2 100644
--- a/cmake/modules/FindASCIIDOC.cmake
+++ b/cmake/modules/FindASCIIDOC.cmake
@@ -3,28 +3,52 @@
 # This module looks for some usual Unix commands.
 #
 
-# XXX Trying to get this to work with Cygwin is going to be problematic.
-# /usr/bin/a2x is a symlink to /usr/bin/a2x.py. I.e. we can't just call
-# directly from Windows.
-# Possible solutions:
-# - Call a2x.py instead.
-# - Wait for someone to create Chocolatey AsciiDoc + DocBook packages
-
 INCLUDE(FindCygwin)
 
 FIND_PROGRAM(A2X_EXECUTABLE
-  NAMES
-    a2x
-  PATHS
-    ${CYGWIN_INSTALL_PATH}/bin
-    /bin
-    /usr/bin
-    /usr/local/bin
-    /sbin
+    NAMES
+        a2x
+    PATHS
+        ${CYGWIN_INSTALL_PATH}/bin
+        /bin
+        /usr/bin
+        /usr/local/bin
+        /sbin
 )
 
-# Make sure we don't get language specific quotes
-set( A2X_EXECUTABLE LC_ALL=C ${A2X_EXECUTABLE} )
+if (WIN32 AND NOT "${CYGWIN_INSTALL_PATH}" STREQUAL "" AND ${A2X_EXECUTABLE} MATCHES "${CYGWIN_INSTALL_PATH}")
+    FIND_PROGRAM(CYGPATH_EXECUTABLE
+        NAMES cygpath
+        PATHS ${CYGWIN_INSTALL_PATH}/bin
+    )
+
+    MACRO( TO_A2X_COMPATIBLE_PATH _cmake_path _result )
+        execute_process(
+            COMMAND ${CYGPATH_EXECUTABLE} -u ${_cmake_path}
+            OUTPUT_VARIABLE _cygwin_path
+        )
+        # cygpath adds a linefeed.
+        string(STRIP "${_cygwin_path}" _cygwin_path)
+
+        set( ${_result} ${_cygwin_path} )
+    ENDMACRO()
+
+    TO_A2X_COMPATIBLE_PATH( ${CMAKE_SOURCE_DIR}/tools/runa2x.sh RUNA2X_CYGWIN_PATH )
+
+    # It's difficult or impossible to call /usr/bin/a2x directly from
+    # Windows because:
+    # - /usr/bin/a2x, which is a symlink to /usr/bin/a2x.py.
+    # - We need to set environment variables (LC_ALL, PATH, TZ, PYTHONHOME)
+    # so we use a wrapper script.
+    set( A2X_EXECUTABLE ${SH_EXECUTABLE} ${RUNA2X_CYGWIN_PATH} )
+else()
+    # Make sure we don't get language specific quotes
+    set( A2X_EXECUTABLE LC_ALL=C TZ=UTC ${A2X_EXECUTABLE} )
+
+    MACRO( TO_A2X_COMPATIBLE_PATH _cmake_path _result )
+        set( ${_result} ${_cmake_path} )
+    ENDMACRO()
+endif()
 
 # Handle the QUIETLY and REQUIRED arguments and set ASCIIDOC_FOUND to TRUE if
 # all listed variables are TRUE
@@ -33,6 +57,48 @@ FIND_PACKAGE_HANDLE_STANDARD_ARGS(ASCIIDOC DEFAULT_MSG A2X_EXECUTABLE)
 
 MARK_AS_ADVANCED(A2X_EXECUTABLE)
 
+TO_A2X_COMPATIBLE_PATH( ${CMAKE_CURRENT_BINARY_DIR} _a2x_current_binary_dir )
+
+MACRO( ASCIIDOC2DOCBOOK _asciidocsource _conf_files )
+    GET_FILENAME_COMPONENT( _source_base_name ${_asciidocsource} NAME_WE )
+    set( A2X_HTML_OPTS --stylesheet=ws.css )
+    set( _output_xml ${_source_base_name}.xml )
+    set( _output_dbk ${_source_base_name}.dbk )
+
+    foreach(_conf_file ${_conf_files})
+        TO_A2X_COMPATIBLE_PATH ( ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} _a2x_conf_file )
+        set( _conf_opts_list ${_conf_opts_list} --conf-file=${_a2x_conf_file})
+    endforeach()
+    string( REPLACE ";" " " _conf_opts "${_conf_opts_list}")
+
+    foreach(_conf_file ${_conf_files})
+        set( _conf_deps ${_conf_deps} ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file})
+    endforeach()
+
+    TO_A2X_COMPATIBLE_PATH ( ${CMAKE_CURRENT_SOURCE_DIR}/${_asciidocsource} _a2x_asciidocsource )
+
+    ADD_CUSTOM_COMMAND(
+        OUTPUT
+            ${_output_xml}
+        # XXX - Output to a specific directory, e.g. wsdg_generated_src
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMAND ${A2X_EXECUTABLE}
+            --verbose
+            --attribute=build_dir=${_a2x_current_binary_dir}
+            --attribute=docinfo
+            --destination-dir=${_a2x_current_binary_dir}
+            --asciidoc-opts=${_conf_opts}
+            --no-xmllint
+            --format=docbook
+            --fop
+            ${A2X_HTML_OPTS}
+            ${_a2x_asciidocsource}
+        DEPENDS
+            ${CMAKE_CURRENT_SOURCE_DIR}/${_asciidocsource}
+            ${_conf_deps}
+    )
+ENDMACRO()
+
 MACRO( ASCIIDOC2HTML _output _asciidocsource _conf_files )
     GET_FILENAME_COMPONENT( _source_base_name ${_asciidocsource} NAME_WE )
     set( A2X_HTML_OPTS --stylesheet=ws.css )
@@ -41,7 +107,8 @@ MACRO( ASCIIDOC2HTML _output _asciidocsource _conf_files )
 
     SET( _conf_opts_list )
     FOREACH( _conf_file ${_conf_files} )
-        SET( _conf_opts_list ${_conf_opts_list} --conf-file=${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} )
+        TO_A2X_COMPATIBLE_PATH ( ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} _a2x_conf_file )
+        SET( _conf_opts_list ${_conf_opts_list} --conf-file=${_a2x_conf_file})
     ENDFOREACH()
     STRING( REPLACE ";" " " _conf_opts "${_conf_opts_list}" )
 
@@ -50,17 +117,19 @@ MACRO( ASCIIDOC2HTML _output _asciidocsource _conf_files )
         SET( _conf_deps ${_conf_deps} ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} )
     ENDFOREACH()
 
+    TO_A2X_COMPATIBLE_PATH ( ${_asciidocsource} _a2x_asciidocsource )
+
     ADD_CUSTOM_COMMAND(
         OUTPUT
             ${_output}
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
         COMMAND ${A2X_EXECUTABLE}
             --format=xhtml
-            --destination-dir=${CMAKE_CURRENT_BINARY_DIR}
+            --destination-dir=${_a2x_current_binary_dir}
             --asciidoc-opts=${_conf_opts}
             --fop
             ${A2X_HTML_OPTS}
-            ${_asciidocsource}
+            ${_a2x_asciidocsource}
         # Replacing file with itself will fail
         # COMMAND ${CMAKE_COMMAND} -E rename
         #     ${CMAKE_CURRENT_BINARY_DIR}/${_source_base_name}.html
@@ -84,7 +153,8 @@ MACRO( ASCIIDOC2TXT _output _asciidocsource _conf_files )
 
     SET( _conf_opts_list )
     FOREACH( _conf_file ${_conf_files} )
-        SET( _conf_opts_list ${_conf_opts_list} --conf-file=${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} )
+        TO_A2X_COMPATIBLE_PATH ( ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} _a2x_conf_file )
+        SET( _conf_opts_list ${_conf_opts_list} --conf-file=${_a2x_conf_file})
     ENDFOREACH()
     STRING( REPLACE ";" " " _conf_opts "${_conf_opts_list}" )
 
@@ -93,18 +163,20 @@ MACRO( ASCIIDOC2TXT _output _asciidocsource _conf_files )
         SET( _conf_deps ${_conf_deps} ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} )
     ENDFOREACH()
 
+    TO_A2X_COMPATIBLE_PATH ( ${_asciidocsource} _a2x_asciidocsource )
+
     ADD_CUSTOM_COMMAND(
         OUTPUT
             ${_output}
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-        COMMAND TZ=UTC ${A2X_EXECUTABLE}
+        COMMAND ${A2X_EXECUTABLE}
             --format=text
-            --destination-dir=${CMAKE_CURRENT_BINARY_DIR}
+            --destination-dir=${_a2x_current_binary_dir}
             --asciidoc-opts=${_conf_opts}
             --fop
             ${A2X_TEXT_OPTS}
-            --xsltproc-opts '--stringparam generate.toc "article nop"'
-            ${_asciidocsource}
+            --xsltproc-opts "--stringparam generate.toc \"article nop\""
+            ${_a2x_asciidocsource}
         COMMAND ${CMAKE_COMMAND} -E rename
             ${CMAKE_CURRENT_BINARY_DIR}/${_source_base_name}.text
             ${CMAKE_CURRENT_BINARY_DIR}/${_output}
@@ -124,7 +196,8 @@ MACRO( ASCIIDOC2PDF _output _asciidocsource _conf_files _paper )
 
     SET( _conf_opts_list )
     FOREACH( _conf_file ${_conf_files} )
-        SET( _conf_opts_list ${_conf_opts_list} --conf-file=${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} )
+        TO_A2X_COMPATIBLE_PATH ( ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} _a2x_conf_file )
+        SET( _conf_opts_list ${_conf_opts_list} --conf-file=${_a2x_conf_file})
     ENDFOREACH()
     STRING( REPLACE ";" " " _conf_opts "${_conf_opts_list}")
 
@@ -133,19 +206,21 @@ MACRO( ASCIIDOC2PDF _output _asciidocsource _conf_files _paper )
         SET( _conf_deps ${_conf_deps} ${CMAKE_CURRENT_SOURCE_DIR}/${_conf_file} )
     ENDFOREACH()
 
+    TO_A2X_COMPATIBLE_PATH ( ${_asciidocsource} _a2x_asciidocsource )
+
     ADD_CUSTOM_COMMAND(
         OUTPUT
             ${_output}
         WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
         COMMAND ${A2X_EXECUTABLE}
             --format=pdf
-            --destination-dir=${CMAKE_CURRENT_BINARY_DIR}
+            --destination-dir=${_a2x_current_binary_dir}
             --asciidoc-opts=${_conf_opts}
             --fop
             ${A2X_HTML_OPTS}
             --xsltproc-opts "--stringparam paper.type ${_paper} --nonet"
             --xsl-file=custom_layer_pdf.xsl
-            ${_asciidocsource}
+            ${_a2x_asciidocsource}
         COMMAND ${CMAKE_COMMAND} -E rename
             ${CMAKE_CURRENT_BINARY_DIR}/${_source_base_name}.pdf
             ${CMAKE_CURRENT_BINARY_DIR}/${_output}
diff --git a/cmake/modules/FindFOP.cmake b/cmake/modules/FindFOP.cmake
index 1b654ab6e9..31127687fc 100644
--- a/cmake/modules/FindFOP.cmake
+++ b/cmake/modules/FindFOP.cmake
@@ -5,6 +5,10 @@
 
 INCLUDE(FindCygwin)
 
+INCLUDE(FindWSWinLibs)
+FindWSWinLibs("fop-1.1" "FOP11_HINTS")
+FindWSWinLibs("fop-1.0" "FOP10_HINTS")
+
 FIND_PROGRAM(FOP_EXECUTABLE
   NAMES
     fop
@@ -14,6 +18,9 @@ FIND_PROGRAM(FOP_EXECUTABLE
     /usr/bin
     /usr/local/bin
     /sbin
+  HINTS
+    ${FOP11_HINTS}
+    ${FOP10_HINTS}
 )
 
 INCLUDE(FindPackageHandleStandardArgs)
@@ -24,4 +31,3 @@ IF(${FOP_EXECUTABLE})
 	SET(FOP_EXECUTABLE FOP_OPTS=${FOP_OPTS} JAVA_OPTS=${FOP_OPTS} ${FOP_EXECUTABLE})
 ENDIF()
 MARK_AS_ADVANCED(FOP_EXECUTABLE)
-
diff --git a/cmake/modules/FindHHC.cmake b/cmake/modules/FindHHC.cmake
new file mode 100644
index 0000000000..427002f831
--- /dev/null
+++ b/cmake/modules/FindHHC.cmake
@@ -0,0 +1,30 @@
+#
+# - Find the Microsoft HTML Help compiler.
+# Sets HHC_EXECUTABLE to the path to hhc.exe
+# Sets HHC_WRAPPER to a wrapper script that ignores hhc.exe's return value.
+#
+
+FIND_PROGRAM(HHC_EXECUTABLE
+  NAMES
+    hhc
+  HINTS
+    $ENV{PROGRAMFILES}/HTML Help Workshop
+)
+
+INCLUDE(FindPackageHandleStandardArgs)
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(HHC DEFAULT_MSG HHC_EXECUTABLE)
+
+MARK_AS_ADVANCED(HHC_EXECUTABLE)
+
+if(WIN32)
+  # hhc.exe returns 1 on success. Create a wrapper script that ignores
+  # this.
+  set(HHC_WRAPPER ${CMAKE_BINARY_DIR}/tools/hhc.cmd)
+  file(TO_NATIVE_PATH "${HHC_EXECUTABLE}" HHC_EXECUTABLE_NATIVE_WINDOWS_PATH)
+  configure_file(${CMAKE_SOURCE_DIR}/tools/hhc.cmd.in
+    ${HHC_WRAPPER}
+    NEWLINE_STYLE WIN32
+  )
+  FIND_PACKAGE_HANDLE_STANDARD_ARGS(HHC DEFAULT_MSG HHC_WRAPPER)
+  MARK_AS_ADVANCED(HHC_WRAPPER)
+endif()
diff --git a/cmake/modules/FindXSLTPROC.cmake b/cmake/modules/FindXSLTPROC.cmake
index c780dcd5d8..99f860dfca 100644
--- a/cmake/modules/FindXSLTPROC.cmake
+++ b/cmake/modules/FindXSLTPROC.cmake
@@ -23,7 +23,31 @@ FIND_PACKAGE_HANDLE_STANDARD_ARGS(XSLTPROC DEFAULT_MSG XSLTPROC_EXECUTABLE)
 
 MARK_AS_ADVANCED(XSLTPROC_EXECUTABLE)
 
-# Translate xml to html
+set (_common_xsltproc_args
+    --stringparam use.id.as.filename 1
+    --stringparam admon.graphics 1
+    --stringparam admon.graphics.extension .svg
+    --stringparam section.autolabel 1
+    --stringparam section.label.includes.component.label 1
+    --stringparam html.stylesheet ws.css
+    )
+
+#set (WSUG_XSLTPROC_ARGS
+#	--stringparam admon.graphics.path wsug_graphics/
+#
+#WSDG_XSLTPROC_ARGS = \
+#	--stringparam admon.graphics.path wsdg_graphics/
+#
+#SINGLE_XSLTPROC_ARGS = \
+#	--nonet http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl
+#
+#CHUNKED_XSLTPROC_ARGS = \
+#	--nonet http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl
+#
+#HTMLHELP_XSLTPROC_ARGS = \
+#
+
+# Translate XML to HTML
 #XML2HTML(
 #        wsug or wsdg
 #        single-page or chunked
@@ -79,14 +103,8 @@ MACRO(XML2HTML _guide _mode _xmlsources _gfxsources)
         COMMAND ${XSLTPROC_EXECUTABLE}
             --path "${CMAKE_CURRENT_SOURCE_DIR}:${CMAKE_CURRENT_BINARY_DIR}:${CMAKE_CURRENT_BINARY_DIR}/wsluarm_src"
             --stringparam base.dir ${_basedir}/
-            --stringparam use.id.as.filename 1
-            --stringparam admon.graphics 1
+	    ${_common_xsltproc_args}
             --stringparam admon.graphics.path ${_gfxdir}/
-            --stringparam admon.graphics.extension .svg
-            --stringparam section.autolabel 1
-            --stringparam section.label.includes.component.label 1
-            --stringparam html.stylesheet ws.css
-            --nonet
             ${_modeparams}
             ${_STYLESHEET}
             ${_source}
@@ -99,7 +117,7 @@ MACRO(XML2HTML _guide _mode _xmlsources _gfxsources)
     )
 ENDMACRO(XML2HTML)
 
-
+# Translate XML to FO to PDF
 #XML2PDF(
 #       user-guide-a4.fo or user-guide-us.fo
 #       WSUG_SOURCE
@@ -135,3 +153,38 @@ MACRO(XML2PDF _output _sources _stylesheet _paper)
             ${_stylesheet}
     )
 ENDMACRO(XML2PDF)
+
+# Translate XML to HHP
+#XML2HHP(
+#       wsug or wsdg
+#       user-guide.xml or developer-guide.xml
+#)
+MACRO(XML2HHP _guide _docbooksource)
+    GET_FILENAME_COMPONENT( _source_base_name ${_docbooksource} 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(_gfxdir ${_guide}_graphics)
+    SET(_basedir ${_guide}_chm)
+    ADD_CUSTOM_COMMAND(
+        OUTPUT
+            ${_output_hhp}
+	COMMAND ${CMAKE_COMMAND} -E make_directory ${_basedir}
+	COMMAND ${CMAKE_COMMAND} -E make_directory ${_basedir}/${_gfxdir}
+	COMMAND ${CMAKE_COMMAND} -E copy_directory ${_gfxdir} ${_basedir}/${_gfxdir}
+	COMMAND ${CMAKE_COMMAND} -E copy_directory common_graphics ${_basedir}
+        COMMAND ${XSLTPROC_EXECUTABLE}
+            --path "${CMAKE_CURRENT_SOURCE_DIR}:${CMAKE_CURRENT_BINARY_DIR}:${CMAKE_CURRENT_BINARY_DIR}/wsluarm_src"
+            --stringparam base.dir ${_basedir}/
+	    --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
+	    ${_docbooksource}
+        DEPENDS
+            ${_docbooksource}
+    )
+ENDMACRO(XML2HHP)