|
mkhtmldoc
|
mkhtmldoc generate html documentation tree
mkhtmldoc, from=, to=, keywords=, packinfo= nosrc=, nofunc=
generates html documentation from yorick files in selected directories.
Without any arguments the subdirectories i0, i, and contrib
of Y_SITE are scanned for function definitions, and the documentation is
created in subdirectories of the current directory.
If specified, the 'from' keyword should be a string array of
directories to scan. The 'to' keyword can be used to set a
destination directory other than the current directory.
A keyword keywords= can be used to specify a file containing a list
of keywords from which to create a crude index. If not specified, and
if there is a file keywords.txt in the current directory, then that is
used. Likewise, the packinfo= can be used to specify a file containing
further information on some or all of the files in the source directories.
It defaults to packinfo.txt if not specified.
The keywords nosrc and nofunc, if non null cut out the slowest parts
of the document creation process - crossreferencing the source files,
and creating function pages. They can be useful when checking the
format of a source file without recreating the whole document set.
When source files do not match the formats mkhtmldoc is expecting,
warnings are printed to standard output, or to a file specified by
the warn keyword. Note that non-compliance with the expected format
is not necessarily an indication of errors in the source files - simply
that mkhtmldoc can't make sense of them. Generally, however, it is
far easier to make one's own files follow the format of the
yorick i0 files more closely than it is to modify mkhtmldoc
to cope with them.
The documentation tree is generated in seven stages.
1 - read through all the source files, extracting function names
extern declarations of builtin functions, and document comments
2 - reread the source files writing them out as preformatted html with
anchors for each function declaration and links to the (as yet
unwritten) function documentation
3 - for each source file, compile a series of html pages of the document
comments for the functions in that file. One html file is generated
for each first letter.
4 - compile a series of html pages for all the functions together, again
grouped into pages according to first letters.
5 - if a keywords file is available, match keywords in the document
comments, and compile a keyword index pointing to all the matched
functions.
6 - if a packinfo file is available, match source file names with
the packinfo file and compile a package list with the corresponding
descriptions. Alternatively, if a document comments appears near
the top of a source files, unattached to a function, this will be used
instead.
By default, mkhtmldoc, will create links to the yorick manual, but
it does nothing to the manual itself. To get the manual in the right place,
run texi2html on the texinfo file yorick.tex putting the files in
the 'manual' directory. To put an index bar at the top of each page
and set up a margin and background colours, run hdoc_wrap on the manual
directory
eg, if you are creating the documentation in the current directory,
and Y_SITE is where yorick i installed, then
> cp Y_SITE/doc/yorick.tex manual
> cd manual
> texi2html yorick.tex
then in yorick,
> hdoc_wrap, manual
So as not to overwrite carefully modified pages, the "home" link
on the indexbar points to index.html in the documentation directory, but
mkhtmldoc writes its template to index-raw.html.
This should be moved to index.html and edited by hand as necessary
KEYWORDS: keywords, packinfo, from, to, nosrc, nofunc
interpreted function, defined at contrib/htmldoc.i line 24
|
