This is the mail archive of the systemtap@sourceware.org mailing list for the systemtap project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: Language Reference Guide


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.

2. Creating a separate document makes it easier to add necessary text
and examples without overwhelming the other material in the man page. 
Mega-man-pages like bash(1) reflect the pre-www era where a man page was
your only choice for online docs.  stap(1) is well written, but
sometimes too terse.  Examples are lacking.  (E.g., if you didn't
already know how to use a foreach statement, stap(1) may not convey
everything you need to know.)

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.

"Competing with dtrace" was not a motivator for me in this particular
issue, but I can see how moving beyond a man page to a complete lang ref
mnl (web page) could help SystemTap's image.

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.

Jim


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]