functions in htmldoc.i -

            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.  

            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.  
       

            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%.  

            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 " 
").  
      Certain patterns are recognized when they are found at the  
      beginning of a line:  
        %onlydoc:doc% where DOC is a short document ID: the remaining  
        of the line will appear only in files pertaining to the  
        document DOC. Certain IDs are predefined: "index" for the main  
        index and "xref" for most of the pages produced by  
        mkhtmldoc. In addition, "manual" is used for the Yorick Manual  
        (see mktexi2html_init) and "qref" is reserved for the  
        reference card. You can use other IDs for use e.g. with your  
        custom embedded documents (see hdoc_extract_embedded).  
        %embedded:....% is used to define embedded documents, see  
        hdoc_extract_embedded.  
      Finally, a few patterns are recognized anywhere in the document:  
        %title% is replaced with the (long) document title. It should  
        probably be used at least once, between .  
        %toroot% is replaced with the path from the current file to  
        the HTML root. It is often "../" and sometimes empty.  
        

             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  

            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%".  

            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.   

            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