Utility scripts for external HTML help controller.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@1860 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/utils/HelpHTML/README b/utils/HelpHTML/README
new file mode 100644 (file)
index 0000000..32c637c
--- /dev/null
+++ b/utils/HelpHTML/README
@@ -0,0 +1,58 @@
+
+HelpHTML : Support scripts for generating external HTML help files
+------------------------------------------------------------------
+
+The scripts in this directory can be used to generate external HTML
+help files for use with wxHTMLHelpControllerBase derived help implemen-
+tations. Currently the only implementation using this is the
+wxExtHelpController class, using an external HTML browser. I hope to 
+add a class using a wxWindows-built-in HTML viewer soon.
+
+These viewers need a "wxhelp.map" file in the help directory which
+maps numeric help IDs to relative URLs, having entries like:
+
+1000           overview.html;Overview
+1010            mainmanu.html;Main Menu
+...
+
+The numeric help ids are used to refer to the help in the application,
+the URL specifies the file to be displayed, relative to the help base
+directory (extended by the locale name if that directory exists) and the
+text behind the semicolon is used to display and search a list of all help
+topics.
+
+html2wxhelp:
+------------
+The html2wxhelp script in this directory allow you to automatically generate
+this file from a set of HTML pages. All you need is to append the numeric ID
+to the section header in the HTML file like this:
+<H1>Overview_1000_</H1>
+
+html2wxhelp will scan all html files in the directory in which it is called
+and find these lines. It will create a wxhelp.map file and strip the help 
+IDs from the HTML files. So you should have a backup of the files before
+running it, or a way to regenerate them.
+
+striphelpids:
+-------------
+
+Called with the name of a .tex file, it will strip the help IDs from the file,
+so the IDs do not show up in the printed documentation.
+
+
+How to use them:
+----------------
+
+I use LyX to generate the docs, export the text as LaTeX. I then use
+latex2html to generate the set of HTML pages and html2wxhelp to generate
+the map file from them. Then I run striphelpids on the .tex file before
+generating PostScript documentation from that.
+The whole process can easily be automated with a Makefile. For an example
+of how to do this, see the source of my mail program, available from
+http://www.phy.hw.ac.uk/~karsten/M/
+
+
+Karsten Ballueder      <Ballueder@usa.net>
+
+
+

diff --git a/utils/HelpHTML/html2wxhelp b/utils/HelpHTML/html2wxhelp
new file mode 100755 (executable)
index 0000000..d2569d1
--- /dev/null
+++ b/utils/HelpHTML/html2wxhelp
@@ -0,0 +1,44 @@
+#!/bin/sh
+#
+# $Id$
+#
+# html2wxhelp Creates a wxhelp.map file from a directory full of html files.
+# It takes header lines, extracts the NAME=xxx section for the URL and the help
+# id which must be added to the header using _ID_.
+#
+# It also removes all _ID_ tags from the html sources.
+
+
+make_map()
+{
+  cat $1 | tr -d '\n' | \
+  sed "1,$ s/^.*<[hH][0-9]\([^<].*\)<\/[hH][0-9]>.*$/
+#__#\1
+/g" | \
+  fgrep \#__\# | tr '
+' '\n' | egrep -v '^$' | \
+  sed "1,$ s/^.*NAME=\"\([^\"]*\)\".*>\([^>]*\)<.*$/$1#\1;\2/g" | \
+  sed "1,$ s/^\#__\#[^>]*>\([^<>][^<>]*\)<.*$/;\1/g" | \
+  sed "1,$ s/^\(.*\);\(.*\)_\(.*\)_.*$/\3      \1      ;\2/g" | \
+  sed "1,$ s/^\([^+-0123456789]\)\(.*\);\(.*\)$/-1     \1\2    ;\3/g" | \
+  fgrep -v \#__\#
+}
+
+remove_ids()
+{
+       cat $1 | \
+       sed "1,$ s/_[0-9][0-9]*_//g" > tmp$$ && mv tmp$$ $1
+#  cat $1 | tr -d '\n' | \
+#  sed "1,$ s/^\(.*<[hH][0-9]\)\([^<_][^_]*\)_.*_*\(<\/[hH][0-9]>.*\)$/\1\2\3
+/g" | \
+#  tr '
+' '\n'  > tmp$$ \
+#  && mv tmp$$ $1
+}
+
+for i in *.html
+do
+       make_map $i
+        remove_ids $i
+done
+

diff --git a/utils/HelpHTML/striphelpids b/utils/HelpHTML/striphelpids
new file mode 100755 (executable)
index 0000000..c523b92
--- /dev/null
+++ b/utils/HelpHTML/striphelpids
@@ -0,0 +1,17 @@
+#!/bin/sh
+# $Id$
+# small script to strip wxhelp IDs from latex source
+
+cat $1 | \
+sed '1,$ s/\(^.*\\part{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\chapter{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\section{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\subsection{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\subsubsection{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\paragraph{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g'  | \
+sed '1,$ s/\(^.*\\part\*{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\chapter\*{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\section\*{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\subsection\*{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\subsubsection\*{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' | \
+sed '1,$ s/\(^.*\\paragraph\*{.*\)\\_[0-9][0-9]*\\_\(.*$\)/\1\2/g' >/tmp/strip$$ && mv /tmp/strip$$ $1