DejaVU Online: HUSH

The DejaVU Framework -- hush 3.1

[.] Papers Tutorials Examples Manuals Interfaces Sources Packages Resources ?

Manual: `LITERATE`

[.] [man] man1 man2 man3 man4 man5 man6 man7 man8 man9 manl mann ?

NAME

literate -- a question of style: literate or littered

DESCRIPTION

This manual section describes the collection of tools (or part thereof) that has been used in producing this documentation. The document processing model applied can be depicted by the following pipeline:

      {.c|.h|.java|.mk} -[cc-t]->  .t  -[ht-ml]-> .html
      {.1-.9.n}         -[man-t]-> .t  -[ht-ml]-> .html
  
      .html  -[html-latex]-> .tex

As you can see, an intermedia format is used, that we are now referring to as the dot-tee format, which is converted to html. The dot-tee format itself strongly resembles html but contains some addition features. For example there is the document tag that allows you to impose a common style by appending a header and footer to the document.

USAGE

In most cases you don't need to apply the ht-ml filter, since what is produced gives already suffiently html-like output. Nevertheless, the best result is obtained (for code) by for example

      cc-t.flt < main.c | ht-ml.flt > main-c.html

As concerns conventions, in my experience it is best to leave the original suffix, in this case dot-cee, to allow for multiple html files having the same base name, for example a dot-ache file.

COMMENTS

Writing tools is one thing, documenting them is a completely different, and less exciting, affair. So apart from the scanty documentation that you find here, you must find out the functionality of these tools by looking at examples, doing some experiments, and as a last resort looking at the code in sources/util/filters

STYLE GUIDELINES

Don't litter. Use comments to explain the code, and adapt the organisation of your source code to the literate reader.