This is the mail archive of the
systemtap@sourceware.org
mailing list for the systemtap project.
Re: Language Reference Guide
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