functions in htmldoc.i -
hdoc_extract_embedded
|
NT hdoc_extract_embedded [,template_file, to=to] extract documents embedded in the HTML documentation template. If TEMPLATE_FILE is specified, load this file as a template first. A template may have one or two line identical to "%content%". Everything above the first one is used as a header (see hdoc_head), everything after the last one as a footer (see hdoc_tail). Between these two line, it is possible to embed the content of one or several files. This function extract these files, setting their header and footer accordingly to the template. The definition of each of these files starts with a line of the form: %embedded:file_name:doc:toroot%Nice Long Title and finishes with the beginning of the next embedded file or with the last %content% line. The first '%' character must be the first character of the line. FILE_NAME is the actual filename to which the file will be extracted (as usual, TO is prepended to FILE_NAME. DOC is used for %onlydoc:doc% lines (see hdoc_read_template). TOROOT is the path from FILE_NAME to the root of the documentation tree. Except for this special first line, each line of the embedded document is parsed for occurrences of e.g. %title% or %toroot% using hdoc_parse and written fo FILE_NAME. | |
SEE ALSO: |
hdoc_read_template,
mktexi2html_init,
low,
level:, hdoc_head, hdoc_tail, hdoc_parse |
hdoc_headtail
|
NT hdoc_headtail, src, dest [, rm, title= , toroot=, doc=] Adds HTML header and footer specified by currently loaded template to file SRC. Saves the result to DEST. Removes SRC unless "rm=0" is specified. |
hdoc_parse
|
NT hdoc_parse, g, spec, title=title [, toroot=toroot, doc=docid, text=text] Parse lines specified by index specification SPEC from the string array TEXT (defaults to currently loaded template) write them to file stream G. TITLE has no default and must be set, TOROOT defaults to "../", DOC is the doc ID for %onlydoc:doc% matching: a line starting with "%onlydoc:line_doc_id" will be output only if LINE_DOC_ID == DOCID. This function implements some of the special strings detailed in hdoc_read_template: %startbody%, %indexbar%, %skip%, %onlydoc:...%, %title% and %toroot%. | |
SEE ALSO: | hdoc_read_template |
hdoc_read_template
|
NT hdoc_read_template, fname load an HTML template for htmldoc.i functions. FNAME is the name of an HTML file, from which the layout of the documentation (navigation bars etc.) will be determined. The functions in htmldoc.i treat certain strings in the template in a special way. The first few of them must e alone on the line, wihtout heading or trailing blank: Either one or two lines must contain exactly the text "%content%". The content of each page will be placed there, replacing anything between the first and last line equal to "%content%". The space in-between can be used to embed documents, see hdoc_extract_embedded for details. %startbody% will be replaced using _hdoc_startbody. This special line should be used at most once. %indexbar% produces a simple index bar using _hdoc_indexbar. %skip% skips a line (replaced with " | |
SEE ALSO: | hdoc_extract_embedded, mktexi2html_init |
mkhtmldoc
|
mkhtmldoc generate html documentation tree mkhtmldoc, from=, to=, xref_dir=, keywords=, packinfo=, aliases=, template=, nosrc=, nofunc=, quiet=, warn= generates html documentation from yorick files in selected directories. Without any arguments the subdirectories i0 and i of Y_SITE are scanned for function definitions, and the documentation is created in subdirectories of the current directory. The page layout is defined in a template file, which defaults to "template.html" if this file exists. A builtin fallback is used if no file is provided. The template can also be set using hdoc_read_template. 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. The cross-reference DOCUMENT comments are extracted into TO/XREF_DIR, where XREF_DIR defaults to "html_xref". 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. An "aliases" file can also be specified to merge the functions from several .i files in a single .html file. It defaults to aliases.txt in the current directory if this file exists. 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 five stages. 1 - read through all the source files, extracting function names extern declarations of builtin functions, and document comments 2 - 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. 3 - compile a series of html pages for all the functions together, again grouped into pages according to first letters. 4 - if a keywords file is available, match keywords in the document comments, and compile a keyword index pointing to all the matched functions. 5 - 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. Unless QUIET is set to 1, mkhtmldoc outputs a lot of information, including warnings. These warnings can be redirected to a file using the WARN keyword (it is the only way to get them if QUIET is set). KEYWORDS: keywords, packinfo, aliases, template, from, to, nosrc, nofunc, quiet, warn, xref_dir | |
SEE ALSO: |
mkdoc,
tagscan,
srcanchor,
hdoc_read_template, mktexi2html_init, hdoc_extract_embedded |
mktexi2html_init
|
NT mktexi2html_init [, infile, outfile] create a TeXi2HTML init file using the currently loaded HTML template (see hdoc_read_template). mktexi2html_init will parse the hdoc template to fill these TeXi2HTML variables (see "info texi2html"): $EXTRA_HEAD, $AFTER_BODY_OPEN, $PRE_BODY_CLOSE. mktexi2html_init needs an input file INFILE (default: "texi2html.tpl"), which is a complete, valid TeXi2HTML init file except that these three variables are defined with the following syntax: $VARIABLE = <<'EOF'; %variable% EOF Therefore, OUTFILE is a copy of INFILE with the three special lines %extra_head% %after_body_open% %pre_body_close% have been replaced with parts of the hdoc template. These three lines must appear in that order. mktexi2html_init works by detecting certain strings in the hdoc template. EXTRA_HEAD is everything between and AFTER_BODY_OPEN is everything between either %startbody% or and %content% PRE_BODY_CLOSE is everything between the last %content% and The case is not important for the HTML tags (but it is for the %...% special strings). The HTML tags must be alone on their line as any leading or trailing text will not be output (see below for a PHP trick, though). The entire tag must be on a single line, but can contain complex definitions (these definitions will be ignored). If your template does not contain these strings, for instance because your HTML code is really PHP, you can try to put something like "%onlydoc:never%" where you would like them to be (see hdoc_read_template). As long as you dont declare any embedded document with "never" as a short doc ID, these lines will never appear in any of the produced documentation, Once mktexi2html_init has determined which lines to put in which variable, it does parse them for replacing the special strings such as %title%, %toroot% and %onlydoc:doc%. mktexi2html_init is meant for typesetting the Yorick Manual, so the doc ID it uses is "manual". Therefore, lines beginning with "%onlydoc:" will not be output, unless they actually start with "%onlydoc:manual%". | |
SEE ALSO: | hdoc_read_template, hdoc_extract_embedded |
srcanchor
|
NT srcanchor, infile, outfile, tags convert yorick source to html Copy infile to outfile quoting any html special characters, inserting anchors at function definitions/declarations, and cross-referencing function calls to definitions. Tags should be a two dimensional string array containing in tags (1,) the function names, and in tags(2,), tags(3,) and tags(4,) the directory, file, and line where each functions is defined/declared. | |
SEE ALSO: | mkhtmldoc, tagscan, mkdoc |
tagscan
|
NT tags = tagscan, filename scan file filename for function declarations/definitions. Returns a (6, nfunc) string array containing, for each function, the function name, then the directory name, file name, and line where it appears, its DOCUMENT comment and type. As with the mkdoc function, if subsequent extern lines precede the DOCUMENT | |
SEE |
comment,
generate,
a,
cross-reference,
...,
to, the, first, extern |