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 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
R-alpha: HTML help
1 message · Paul Gilbert