On Thu, 2006-10-19 at 12:19, Frank Ch. Eigler wrote:
Robb Romans <FMJ@us.ibm.com> writes:
I have been asked to help put together a Language Reference Guide
for SystemTap. I've taken a suggested table of contents from Jim
Keniston and put together a very early version based on existing
SystemTap documentation to get feedback from the list. [...]
Perhaps it would be appropriate to expand or reorganize the man page
(which is clearly the basis of your writeup) in place rather than
start a brand new document. (It is easily converted to pdf or html or
even latex.)
- FChE
For me, here are the reasons for moving the language reference material
to a separate document:
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. As a result, for example, the
tendency when writing a man page is to avoid the use of anything other
than the basic font. (In stap(1), note the use of caps for terms like
PROBEPOINT when italic+lowercase better conveys that "probepoint" is a
type of language construct.)
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.
Frank didn't say it, but I suspect that he is worried about stap(1) --
which he has been very faithful about keeping in sync with the
translator -- being hijacked and replaced with something that is
technically or stylistically inferior. We need to be sure not to let
that happen. One way to help keep that from happening is to make sure
Robb gets the reviews he needs. Also, we would like the lang ref mnl to
live in systemtap CVS, so that it's easy for team members to update as
they see fit.