Language Reference Guide

[Frank Ch. Eigler]

jkenisto wrote:

> [...]
> 1. Freeing ourselves from the man macros can help make the document more
> useful -- e.g., more easily navigated and more legible.  Man pages have
> to be legible on an ACSII terminal.  [...]
> I believe that we can convey all the info we need in 2 fonts (monospace
> and variable-space) and plain, italic, and bold variations thereon.  And
> the man macros support all those, I think.  But on an ASCII terminal,
> the monospace/variable-space distinction is lost.

Surely that does not imply that nroff/man is the wrong tool for the
job.  One can use nroff to make things look pretty in pdf/html forms.
No matter what other markup format one writes a replacement document,
an ASCII rendering will still lack italics etc.  So this issue is a
red herring.  (The relative barqueness of nroff, and its current
amateur use in the systemtap man pages is of course a fair criticism.)

> [...]  Once the lang ref mnl is in good shape and available on the
> SystemTap web site, I would prefer to see the whole "SCRIPT
> LANGUAGE" section ripped out of the man page and replace with the
> URL of the lang ref mnl. [...]

Replacing installed, instantly-available documentation with something that
relies on internet access is not the kind of improvement I'd like to see.


- FChE