c2html Proposal

The following are the proposed tags that will be parsed from comments in "C" files by the c2html perl script. HTML documents for WWW viewing will result.


Recognized Tags

The tags listed below will be recognized by the c2html converter.

<HTML>
Extract subsequent lines verbatim, up to a </HTML> tag. The user can insert formal HTML in this section. NOTE: Characters to the right of the <HTML> tag (or to the left of </HTML>) will also be extracted and any "C" comment characters (/* or */) will be removed.
<INTRO>
Extract subsequent lines verbatim, up to a </INTRO> tag or the end of the comment. No HTML is accepted, and only the first <INTRO> block is understood. NOTE: Characters to the right of the <INTRO> tag (or to the left of </INTRO>) will also be extracted and any "C" comment characters (/* or */) will be removed.
<PRE>
Extract subsequent lines verbatim, up to a </PRE> or </HTML> tag. Here too, the user can insert formal HTML, but it's within the <PRE> context. NOTE: This is an obsolete c2html tag, maintained for backwards compatibility. Also note that all characters to the right or left of the <PRE> and </PRE> tags are ignored.
<AUTO>
Extract subsequent lines and covert appropriate lines to HTML (according to the rules described below), up to an end comment or the </AUTO> tag. Formal HTML within this section will NOT function properly, as it will be within the <LISTING> context.

The AUTO Tag

The <AUTO> tag is used to identify comment sections describing individual "C" routines and "C"-based TCL verbs, that will be extracted by the c2html parser. No particular commenting style is assumed by the AUTO tag, although one is available if you want to use it; this style is is best illustrated by example (see link below). In general, an <AUTO> section can be used once for each routine and must be within a single comment located just prior to the routine declaration.

The syntax of the <AUTO> tag is:

<AUTO [EXTRACT]>
If the optional EXTRACT keyword is present, then the routine declaration or the TCL verb usage information may also be automatically extracted, depending on the type of section.

If you use the approved commenting style, you must specify the <AUTO> section's type by including one of the following lines after the <AUTO> tag:

ROUTINE: name      (Used for describing a C routine)
TCL VERB: name     (Used for describing a TCL verb)
FILE: name         (Used at top of file to describe a module.
Note that the EXTRACT keyword has no effect on MODULE sections.

If none of these types is specified, AUTO assumes that it's dealing with a C function, and finds the function's name by reading the code.

At this point, if you want to specify a type it's probably easiest to just look at an example of the <AUTO> tag, but for the masochists, there's the list of translations that c2html will perform. Keep scrolling down in either case.


AUTO Tag Example

  • "C" input file (full markup)
  • Resulting HTML output

  • "C" input file (minimal markup)
  • Resulting HTML output

  • AUTO Tag Translation Rules

    Don't read this if you can avoid it - look at the example instead. The following translations/rules apply to <AUTO> sections:

  • Each <AUTO> section must be contained within a single "C" style comment.
  • Sections should start with a line specifying the section's type, which is described above (i.e., ROUTINE:, TCL VERB:, or FILE:). All comments prior to these lines will be ignored.
  • Lines containing all uppercase alpha characters and ending in a ":" will be left justified (and highlighted ?).
  • Non-alphanumeric characters in the first four columns will be ignored.
  • Formal HTML is allowed as long as it is surrounded by <HTML> and </HTML> tags.
  • For FILE:, the name will be highlighted (as an H1 tag).
  • For ROUTINE: or TCL VERB: sections, the following occur:
  • name will be highlighted (as an H2 tag).
  • A single hypertext list containing all name's in the file will automatically be generated and inserted before the first occurrence of either type.
  • If EXTRACT was specified in the <AUTO> tag, then either the routine declaration or the TCL verb syntax is extracted. It is assumed the routine declaration or the TCL verb syntax immediately follows the end comment. NOTE: All text between the </AUTO> and the end comment is ignored.