Jose' M. Perez wrote:
The format looks good, but I would suggest several changes. First, if "Reference-Card" is the version number, put the version number in the page footer. Second, replace "Theme" with "Subject" or "Command", "Function", or something more suitable.
Actually, in the GPC manual reference we now use (just changed) the following structure, very similar to the man page format:
- Synopsis
How the thing would be declared in Pascal (sometimes a little pseudo Pascal if it has special magic, e.g. accepts integer or real parameters) -- for functions, procedures, etc., or how it is used -- for control structures like `for'.
- Description
Well, the description (-: with all special cases and variants and whatever)...
- Conforming to
Which of the various Pascal standards and de-facto standards contained the thing (or parts of it).
- Example
A complete, compileable demo program (that usually does nothing interesting, just demonstrates the use of the thing).
- See also
Cross references to related entries and to other parts of the manual (often a section of the `Programming' chapter, describing the topic the feature belongs to).
As Peter pointed out, Uwe's format is very similar and probably automatically convertible. For the `See also' section, you might want them separated into references to other reference entries and to other parts of the GPC manual. This should also not be too difficult, e.g. we could use @ref for reference entries and something else (@gref or whatever) for other references.
For the manual, we can define @gref equivalent to @ref, and for your reference cards, you can either define @gref to do nothing, or to output something like: "See chapter foo in the GPC manual."
Concerning the Nassi-Shneiderman and syntax diagrams: Do you use them only for control structures etc. (which are relatively few), or also for other things (what would they look like there)?
I have the idea of generating syntax diagrams directly from the bison source, and have been pointed to two projects to generate syntax diagrams as LaTeX graphics. I'll check them out more thoroughly when I find the time. Maybe the results will be useful here as well...
Frank