R-alpha: HTML help

[Paul Gilbert]

Below is a copy of the script I mentioned a few days ago, and Kurt
suggested I should post. It takes as input a single file of all the
html formatted function help, divides this into single files with
non-descriptive but unique and dos8.3 compatable names, and generates
both name and title indexes. It also changes the "see also"
functions to be links to the appropriate place in the name index.
(This is a compromise which was easier to do then link directly to the
appropriate file.) 

If you want to see how this approach to help works, look at

http://www.bank-banque-canada.ca/pgilbert/help/dsehome.htm

The indexes are generated from two html "NAME" tags I have written into
the html files, one for the function name and one for the function
title. eg.

<A NAME=stability><H1>stability</H1></A>
<A NAME=CalculatestabilityofaTSmodel>Calculate stability of a TSmodel</A><BR><HR>

The "see also" links are generated from the HREF tag, eg.

<H2>See Also</H2>
<UL>
<A HREF="#stability">stability</A>
</UL>


I have used a convention of .htm instead of .html because I wanted this
to work in DOS too. (I just noticed this has not been done in the R
html help.)

The generated files have "dse" prefixed to indicate my library. I tried
to make the prefix variable, but so far I haven't had any luck.

Another convention I have found very useful in maintaining help is to
embed the help directly into my coded files using /* */ multi-line
style comments to separate it from code. I then run these files through
an awk filter to separate the help into one file and the code into a
second. This can be done with a modified source() function within R or
S. Before I started to use this convention I found that I was
duplicating much of the documentation into comments in the code, and in
fact the comments in the code were often much more accurate than the
help files.


Paul Gilbert

______
#!/bin/sh

if [ $# -ne 2 ]; then
  echo usage:
  echo "  build.HTML.help2  sourcefile targetlocation"
  echo "   where sourcefile is a file of all the HTML help and"
  echo "       targetlocation is the target directory"
  exit
fi 


# I haven't been able to get the variable substitution to work 
#    in some places where there are quotes
# PREFIX is added to the beginning of all generated help files
# PREFIX should not be more than 3 character for dos compliance
# PREFIX=dse

#intro is an html file used as the starting point for 
#   a browser (eg home.htm or index.htm)
#intro=dsehome.htm

tmphelp=$1
help=$2
mkdir -p $help
cd $help  

echo help directory set to $help
# This script expects to find the two files:
#     $tmphelp (all function help) and dsehome.htm (the introduction)
# The function help in the file $tmphelp is broken into individual files and
# an indexes built. $tmphelp is removed on completion.

# A function index is built from the <A NAME= ... ><H1> lines
# and  title index is built from the other <A NAME=  lines.
# These are put in the file dsefidx.htm and dsetidx.htm respectively

echo "number of NAME lines in $tmphelp " `grep NAME $tmphelp | wc -l`
echo "(The number of NAME lines is aprox. 2 times the number of help functions)"

#  Step 1 -  break up  functions into alphabetical sub-files.

sed  "s/<A NAME=\(.*\)><H1>\(.*\)/@<A NAME=\1><H1>\2/g" $tmphelp >zot2$$

# The next line converts line breaks to ; then converts @ to line breaks
tr '\012'  '\073' <zot2$$ | tr '@' '\012'  >zot3$$

echo "1st check: the number of help functions is about " `wc -l <zot3$$`

split -1 zot3$$ $help/dseH
rm zot2$$ zot3$$

echo "2nd check: the number of help functions is about " `ls -l dseH* | wc -l`


#  Step 2 - convert See Also references to point to the function index, eg:
# <A HREF="#TSmodel"> TSmodel</A>
# or
# <A HREF=#TSmodel> TSmodel</A>
# or
# <A HREF=TSmodel> TSmodel</A>

# to
# <A HREF="dsefidx.htm#TSmodel"> TSmodel</A>

# and first convert ; back to <cr>

for f in `ls dseH[a-z]*`
do
  tr '\073' '\012'<$f | sed 's/<A HREF="\(.*\)">\(.*\)/<A HREF="\1">\2/g' >zotaa
  sed 's/<A HREF="#\(.*\)">\(.*\)/<A HREF="#\1">\2/g' zotaa >zotbb
  sed 's/<A HREF="#\(.*\)">\(.*\)/<A HREF="dsefidx.htm#\1">\2/g' zotbb >$f.htm
  echo '<HR><A HREF="dsehome.htm#ToC">return to Table of Contents</A><HR>' >>$f.htm
  rm $f
done
rm  zotaa zotbb 

# Step 3 - build Function and Title indexes dsefidx.htm and dsetidx.htm

grep "<A NAME=" dseH[a-z]*.htm | grep -v "<H1>" >zotT$$
grep "<A NAME=" dseH[a-z]*.htm | grep "<H1>" >zotN$$

# build Index to functions by Name


echo '<HR><A HREF="dsehome.htm#ToC">return to Table of Contents</A><HR><A NAME=IndexbyFunctionName><H1>Index to Functions by Name</H1></A><HR><HR>' >dsefidx.htm

# use grep output of file name in eg
# dseHaa.htm:<A NAME=arma><H1>ARMA</H1></A>
#           \1              \2       \3

# to insert HREF links (but leave NAME for jump into index) eg
# <A NAME=->arma</A><A HREF=dse1.htm>ARMA</A><BR>
#            \2                \1       \3
 
sed 's/<H1>//g' zotN$$ | sed 's/<\/H1>//g' | sed 's/<HR>//g' | sed 's/<BR>//g' >zotN5$$
sed 's/\(.*\):<A NAME=\(.*\)>\(.*\)<\/A>/<A NAME=\2>-<\/A><A HREF=\1>\3<\/A><BR>/g' zotN5$$ >zotN6$$

sort -f <zotN6$$ >>dsefidx.htm
rm zotN[1-6]*$$

echo '<HR><A HREF="dsehome.htm#ToC">return to Table of Contents</A><HR>' >>dsefidx.htm


# build Index to functions by Title

echo '<HR><HR><A HREF="dsehome.htm#ToC">return to Table of Contents</A><HR><A NAME=IndexbyTitle><H1>Index to Functions by Title</H1></A><HR><HR>' >dsetidx.htm

sed "s/<HR>//g" zotT$$  >zotT2$$
sed "s/<BR>//g" zotT2$$ >zotT3$$
sed "s/\(.*\):<A NAME=\(.*\)>\(.*\)<\/A>/<A NAME=\2>-<\/A><A HREF=\1>\3<\/A><BR>/g" zotT3$$ >zotT4$$

sort -f <zotT4$$ >>dsetidx.htm
rm zotT[1-6]*$$

echo '<HR><A HREF="dsehome.htm#ToC">return to Table of Contents</A><HR>' >>dsetidx.htm

rm zot?$$
#  $tmphelp

echo "number of help functions in title index    " `wc -l <dsetidx.htm` "-2"
echo "number of help functions in function index " `wc -l <dsefidx.htm` "-2"
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
r-devel mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-devel-request@stat.math.ethz.ch
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-