fix several Windows Help issues

crosswire · May 21, 2018 · 13eb868 · 13eb868
1 parent 8aed941
commit 13eb868
Show file tree

Hide file tree

Showing 14 changed files with 1,864 additions and 859 deletions.
diff --git a/mhelp/C/index.page b/mhelp/C/index.page
@@ -6,7 +6,9 @@
 
   <info>
     <revision pkgversion="4.1.0" date="2018-04-24" status="draft"/>
-    <desc>Xiphos is an application to aid in study of the Bible.</desc>
+<!--    <desc>Xiphos is an application to aid in study of the Bible.</desc> -->
+    <desc>Bible study tool for reading, study, and research using modules from
+    The SWORD Project and elsewhere.</desc>
 
     <title type='link' role="trail">
       <media type="image" its:translate="no" src="figures/xiphos-trail-icon.png"/>

diff --git a/mhelp/C/legal.xml b/mhelp/C/legal.xml
@@ -1,5 +1,6 @@
+<!-- <license href="https://www.gnu.org/licenses/gpl-2.0.html"> -->
 <license xmlns="http://projectmallard.org/1.0/"
-href="http://www.gnu.org/licenses/" >
+href="http://www.gnu.org/licenses/gpl-2.0.html">
   <p>
     Permission is granted to copy, distribute and/or modify this document
     under the terms of the GNU General Public License (GPL), Version 2 or

diff --git a/mhelp/C/xiphos-01-introduction.page b/mhelp/C/xiphos-01-introduction.page
@@ -64,19 +64,21 @@
 
       <media type="image" mime="image/png" style="floatstart" src="figures/sword3.png" />
 
-      <p>"The SWORD Project" is based at <link href="http://www.crosswire.org">
-      http://www.crosswire.org</link>. Other apps under the same banner are
-      <app>MacSword</app> for the Macintosh, <app>BibleDesktop</app>, a Java
-      app, <app>BibleTime</app> (another Linux program), and <app>The SWORD
-      Project for Windows</app> (aka <app>BibleCS</app> or <app>WinSword</app>).
+      <p>"The SWORD Project" is based at <link href="http://www.crosswire.org"
+      its:translate="no">http://www.crosswire.org</link>. Other apps under the
+      same banner are <app>MacSword</app> for the Macintosh, <app>BibleDesktop
+      </app>, a Java app, <app>BibleTime</app> (another Linux program), and
+      <app>The SWORD Project for Windows</app> (aka <app>BibleCS</app> or
+      <app>WinSword</app>).
       </p>
 
       <!-- Where important notices are kept regarding Xiphos  -->
       <note style="warning">
         <p>Xiphos is currently in development, so this manual may not
         reflect the program as you see it. If it does not, please file a
-        bug at the <link href="https://github.com/crosswire/xiphos">
-	project website</link>, or email <sys>xiphos-devel@crosswire.org</sys>.
+        bug at the <link href="https://github.com/crosswire/xiphos"
+	its:translate="no">project website</link>, or email
+	<sys its:translate="no">xiphos-devel@crosswire.org</sys>.
         All help is appreciated, as it will improve the software.</p>
       </note>
 

diff --git a/mhelp/C/xiphos-21-modules-configuration.page b/mhelp/C/xiphos-21-modules-configuration.page
@@ -44,7 +44,8 @@
     the modules available from other repositories do not represent content
     officially sanctioned by Crosswire. On the web, see this page for list of
     those repositories known:
-    <link href="http://www.crosswire.org/wiki/Module_Repositories">
+    <link href="http://www.crosswire.org/wiki/Module_Repositories"
+	  its:translate="no">
     http://www.crosswire.org/wiki/Module_Repositories</link></p>
 
     <p>The list of standard repositories is maintained at CrossWire. Xiphos

diff --git a/mhelp/C/xiphos-60-online-help.page b/mhelp/C/xiphos-60-online-help.page
@@ -41,10 +41,10 @@
 
     <p>One way you can get help with Xiphos is using our low-traffic users'
     mailing list. You can sign up by clicking
-    <link href="http://www.crosswire.org/mailman/listinfo/xiphos-users/">this
-    link</link>. Once you are signed up, you can email the list with any
-    problems you are having and other users or the developers will respond,
-    typically within a day.</p>
+    <link href="http://www.crosswire.org/mailman/listinfo/xiphos-users/"
+	  its:translate="no">this link</link>. Once you are signed up, you can
+    email the list with any problems you are having and other users or the
+    developers will respond, typically within a day.</p>
   </section>
 
   <section id="xiphos-live-chat">
@@ -53,9 +53,9 @@
 
     <p>Another way to get help is with online chat. Xiphos has an IRC channel
     on freenode, #xiphos. If you don't know what that means, it's ok. Just click
-    <link href="http://webchat.freenode.net/?randomnick=1&amp;channels=xiphos&amp;prompt=1">this
-    link</link> (it will open your web browser), type a nickname or accept the
-    default, and click "Click to join chatroom".
+    <link href="http://webchat.freenode.net/?randomnick=1&amp;channels=xiphos&amp;prompt=1"
+	  its:translate="no">this link</link> (it will open your web browser),
+    type a nickname or accept the default, and click "Click to join chatroom".
     This will take you to a chatroom where the developers and other users are
     available to help you with issues you may be having. Although many times
     someone will answer your question immediately, sometimes you may have to

diff --git a/mhelp/C/xiphos-90-credits.page b/mhelp/C/xiphos-90-credits.page
@@ -0,0 +1,123 @@
+<page xmlns="http://projectmallard.org/1.0/"
+      xmlns:its="http://www.w3.org/2005/11/its"
+      xmlns:ui="http://projectmallard.org/ui/1.0/"
+      type="topic"
+      id="xiphos-90-credits">
+
+  <info>
+    <desc>Credits and contact information.</desc>
+
+    <link type="guide" xref="index"/>
+
+    <revision pkgversion="4.1.1" date="2018-05-20" status="draft"/>
+
+    <title type='link' role="trail"></title>
+    <title type='text'>Xiphos</title>
+
+    <credit type="author" its:translate="no">
+      <name>Andy Piper</name>
+    </credit>
+    <credit type="author" its:translate="no">
+      <name>Pierre Benz</name>
+    </credit>
+    <credit type="author" its:translate="no">
+      <name>Dr Peter von Kaehne</name>
+    </credit>
+    <credit type="author" its:translate="no">
+      <name>Karl Kleinpaste</name>
+    </credit>
+    <credit type="author" its:translate="no">
+      <name>Matthew Talbert</name>
+    </credit>
+
+    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+  </info>
+
+  <title>Credits and Acknowledgment</title>
+
+  <section id="license">
+    <title>License</title>
+    <p>
+      Permission is granted to copy, distribute and/or modify this document
+      under the terms of the GNU General Public License (GPL), Version 2 or
+      any later version published by the Free Software Foundation. You can
+      find a copy of the GPL at this
+      <link href="http://www.gnu.org/licenses/gpl-2.0.html"
+	    its:translate="no">link</link> or in the file COPYING distributed
+      with this manual.
+    </p>
+  </section>
+
+  <section id="current">
+    <title>Authors of the <app>Xiphos</app> User Documentation</title>
+    <p>This manual was written by:</p>
+    <list>
+      <item its:translate="no">
+	<p>Andy Piper</p>
+      </item>
+      <item its:translate="no">
+	<p>Pierre Benz</p>
+      </item>
+      <item its:translate="no">
+	<p>Dr Peter von Kaehne</p>
+      </item>
+      <item its:translate="no">
+	<p>Karl Kleinpaste</p>
+      </item>
+      <item its:translate="no">
+	<p>Matthew Talbert</p>
+      </item>
+    </list>
+  </section>
+
+
+  <section id="contact">
+    <title>Contact information</title>
+    <p>The <app>Xiphos</app> software and Manual:</p>
+    <list>
+      <item>
+	<p>
+	  <link href="http://xiphos.org/" its:translate="no">
+	    Website
+	  </link>
+	</p>
+      </item>
+      <item>
+	<p>
+	  <link href="https://www.crosswire.org/mailman/listinfo/xiphos-users/"
+		its:translate="no">
+	    Mailing list
+	  </link>
+	</p>
+      </item>
+      <item>
+	<p>
+	  <link href="https://github.com/crosswire/xiphos/issues"
+		its:translate="no">
+	    <app>Xiphos</app> Issues and Bug reports
+	  </link>
+	</p>
+      </item>
+    </list>
+
+    <p>The SWORD Project:</p>
+    <list>
+      <item>
+	<p>
+	  <link href="http://www.crosswire.org" its:translate="no">
+	    Crosswire website
+	  </link>
+	</p>
+      </item>
+      <item>
+	<p>
+	  <link href="http://tracker.crosswire.org/browse/MOD/"
+		its:translate="no">
+	    Modules Issues and Bug tracking
+	  </link>
+	</p>
+      </item>
+    </list>
+  </section>
+</page>
diff --git a/mhelp/CMakeLists.txt b/mhelp/CMakeLists.txt
@@ -51,6 +51,7 @@ if (HELP)
     xiphos-52-preferences-fonts-colors.page
     xiphos-53-preferences-modules.page
     xiphos-60-online-help.page
+    xiphos-90-credits.page
     )
 
   # list of figures
@@ -170,7 +171,8 @@ if (HELP)
   set (mallard-schema ${CMAKE_CURRENT_SOURCE_DIR}/xml/mallard-1.0.rng)
   foreach (lang ${help_all_langs})
     add_custom_command (OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${lang}/validate.txt
-      COMMAND ${XMLLINT} --noout --xinclude --noent --relaxng ${mallard-schema} *.page > ${CMAKE_CURRENT_BINARY_DIR}/${lang}/validate.txt 2>&1
+#      COMMAND ${XMLLINT} --noout --xinclude --noent --relaxng ${mallard-schema} *.page > ${CMAKE_CURRENT_BINARY_DIR}/${lang}/validate.txt 2>&1
+      COMMAND ${XMLLINT} --noout --xinclude --noent --relaxng ${mallard-schema} *.page
       DEPENDS help-${lang}-pages
       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${lang}
       COMMENT "'${lang}' help - mallard pages validation report"
@@ -241,7 +243,7 @@ if (HELP)
 
 
   ### optional features
-  # TODO: switch from yelp-x utilities which are bash script to plain XSLT
+  # TODO: in th future, switch from yelp-x utilities which are bash script to plain XSLT
 
   # export mallard files to epub
 
@@ -286,32 +288,29 @@ if (HELP)
     # TODO: switch to plain XSLT
     message(STATUS "Configuring Help to HTML export")
     foreach (lang ${help_all_langs})
+
       # list help pages to convert
       set (mallard_pages)
       foreach(page ${help_pages})
 	list(APPEND mallard_pages ${CMAKE_CURRENT_BINARY_DIR}/${lang}/${page})
       endforeach(page)
 
-      # convert Mallard pages into html files
+      # convert Mallard pages into html files using a custom css
+      set(custom_css ${CMAKE_CURRENT_SOURCE_DIR}/xml/html.css.custom.xsl)
       add_custom_command (OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${lang}/html.timestamp
-	COMMAND ${YELP_BUILD} html ${mallard_pages}
-	COMMAND ${CMAKE_COMMAND} -E remove ${lang}.css
-	COMMAND ${CMAKE_COMMAND} -E touch ${lang}.css
+	COMMAND ${YELP_BUILD} html -x ${custom_css} ${mallard_pages}
 	DEPENDS validate-${lang}-pages
 	WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${lang}
 	COMMENT "Generating '${lang}' html files"
 	)
-
       add_custom_target(${lang}-html-files
 	DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${lang}/html.timestamp
 	)
-
       add_dependencies(handbook ${lang}-html-files)
 
     endforeach ()
 
     set (have_html_help ON PARENT_SCOPE)
-
   endfunction (xiphos_export_to_html)
 
 
@@ -330,27 +329,27 @@ if (HELP)
     if (NOT have_html_help)
       xiphos_export_to_html()
     endif ()
-    # generate .chm file for each <lang>
+
+    # generate a .chm file for each <lang>
     foreach (lang ${help_all_langs})
       message(STATUS "Configuring Windows© Help file for '${lang}'")
 
-      # 1. format lang to MS pattern
-      string(REGEX REPLACE "[_]" "-" ms_lang ${lang})
-      # find MS language code for ms_lang
-      file(STRINGS ms_langcodes_file ms_found_code REGEX "^${ms_lang}[ ]")
-      # if empty, default to en-US
-      if (NOT ms_found_code)
-	set(ms_found_code "C 0x0409 English (United States)")
+      # Create xiphos.hhp file (PROJECT)
+      # 1. find the according Microsoft language ID
+      file(STRINGS win32/ms-langID ms_langID REGEX "^${lang}[ ]")
+      # if empty, default to the en-US langID
+      if (NOT ms_langID)
+	set(ms_langID "C 0x0409 English (United States)")
       endif ()
-      # format to HHP style
-      string(LENGTH ${ms_lang} len_lang)
+      # remove lang, keep only langID and country values
+      string(LENGTH ${lang} len_lang)
       math(EXPR len_lang "${len_lang} + 1")
-      string(SUBSTRING ${ms_found_code} ${len_lang} -1 MS_LANGUAGE_CODE)
+      string(SUBSTRING ${ms_langID} ${len_lang} -1 MS_LANGUAGE_CODE)
 
-      # 2. set output file name
+      # 2. set the .chm output file name
       set(MS_COMPILED_FILE "xiphos_${lang}.chm")
 
-      # 3. set list of files to compile
+      # 3. set the list of files to compile
       foreach(line ${help_pages})
 	set(MS_FILES_LIST "${MS_FILES_LIST}${line}\n")
       endforeach()
@@ -359,20 +358,38 @@ if (HELP)
       endforeach()
 
       # 4. create HHP file (Project file)
-      configure_file(${PROJECT_SOURCE_DIR}/mhelp/xiphos.hhp.in
+      configure_file(${PROJECT_SOURCE_DIR}/mhelp/win32/xiphos.hhp.in
 	${CMAKE_CURRENT_BINARY_DIR}/${lang}/xiphos.hhp)
 
-      # 5. Create HHC file (TOC)
+      # Create xiphos.hhc (TOC)
+      # 1. find MS codepage for lang
+      file(STRINGS win32/ms-codepages ms_codepage REGEX "^${lang}[ ]")
+      # if codepage unset, default to windows-1252
+      if (${lang} STREQUAL ${ms_codepage})
+	message(WARNING "No codepage set for ${lang}, please add it to the win32/ms-codepages file")
+	set(ms_codepage "${lang} windows-1252")
+      endif ()
+      # remove lang
+      string(LENGTH ${lang} len_lang)
+      math(EXPR len_lang "${len_lang} + 1")
+      string(SUBSTRING ${ms_codepage} ${len_lang} -1 MS_WINDOWS_CODEPAGE)
+
+      # 3. create XSLT file
+      configure_file(${CMAKE_CURRENT_SOURCE_DIR}/win32/toc.xsl.in
+	${CMAKE_CURRENT_BINARY_DIR}/${lang}/toc.xsl)
+
+      # 4. build HHC file
       add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${lang}/xiphos.hhc
 	  # Create HHC file (TOC)
-	  COMMAND ${XSLTPROC} --html ${CMAKE_CURRENT_SOURCE_DIR}/xml/mhtmlhelp.xsl ${CMAKE_CURRENT_BINARY_DIR}/${lang}/index.html > ${CMAKE_CURRENT_BINARY_DIR}/${lang}/xiphos.hhc
+	  COMMAND ${XSLTPROC} --html ${CMAKE_CURRENT_BINARY_DIR}/${lang}/toc.xsl ${CMAKE_CURRENT_BINARY_DIR}/${lang}/index.html > ${CMAKE_CURRENT_BINARY_DIR}/${lang}/xiphos.hhc
 	  # Compile HTML files
 	  DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${lang}/html.timestamp
 	  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${lang}
-	  COMMENT "Generating '${lang}' Windows© HHC (Table of Contents) file"
+	  COMMENT "Generating '${lang}' Windows HHC (Table of Contents) file"
 	  )
 
-      # 6. TODO: Create HHK file (Index file) - workaround:
+	# 6. TODO: Create a HHK file (Index file)
+	# here is a workaround:
       file (WRITE ${CMAKE_CURRENT_BINARY_DIR}/${lang}/xiphos.hhk
 	"<!DOCTYPE html>"
 	"<html>"
@@ -388,7 +405,7 @@ if (HELP)
 
       # 7. Build CHM
       if (WIN32 AND NOT CMAKE_CROSSCOMPILING)
-	# pure Windows©: building help with HHC.EXE [NOTE: First switch to XSLT]
+	# pure Windows: building help with HHC.EXE [NOTE: First switch to XSLT]
 	add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${lang}/${MS_COMPILED_FILE}
 	  COMMAND ${HHC_EXE} xiphos.hhp
 	  WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${lang}
@@ -423,6 +440,7 @@ if (HELP)
   endif (MSHELP)
 
   # create PDF (experimental)
+  # needs htmldoc > 1.9.0
 
   if (PDFHELP)
     set(lang "C")
@@ -433,11 +451,11 @@ if (HELP)
       xiphos_export_to_html()
     endif ()
     # create PDF file
-    # TODO: htmldoc is not utf-8 aware, we needs to run iconv first
-    # NOTE: another option is to run: COMMAND ${WKHTMLTOPDF} *.html xiphos.pdf
-    # but actually it needs a patched version of QT (and its dependencies)
+    # TODO: htmldoc is not full utf-8 aware, we needs to run iconv first
+    # NOTE: a better option is to run: COMMAND ${WKHTMLTOPDF} *.html xiphos.pdf
+    # but actually it needs a patched version of QT.
     add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${lang}/xiphos.pdf
-      COMMAND ${HTMLDOC} --webpage --linkstyle plain -f xiphos.pdf *.html
+      COMMAND ${HTMLDOC} --webpage --continuous --browserwidth 1200  --footer : --fontsize 8 --headfootsize 8 --no-jpeg --no-strict --linkstyle plain -f xiphos.pdf xiphos*.html
       DEPENDS ${lang}-html-files
       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/${lang}
       COMMENT "Generating '${lang}' PDF file"