Re: Language Reference Guide

[Mike Mason <mmlnx at us dot ibm dot com>]

Jim Keniston wrote:
> 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.

I agree, the man macros are too limiting, though that's not my primary 
concern with just having a man page (see below).

> 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.)

I agree.  I'm not a fan of huge man pages.  I view man pages more as quick 
references.  For something like systemtap, I like to learn through user 
guides/tutorials with lots of hands-on examples.  I also like the option of 
pulling up a man page as a quick refresher for language elements and 
syntax, command line options, etc. There's a place for both.

> 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.

I disagree with removing the SCRIPT LANGUAGE section completely.  I'd still 
like to see quick reference info in the man page.

> "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.

I may be in the minority, but I think "competing with dtrace" *is* 
important. The entire package known as "SystemTap" will be compared against 
all aspects of Dtrace, including the documentation. In the end, it won't 
matter to the customer if Dtrace has had more time to mature or Sun has 
more resources or we do things differently in Linux. All they'll care about 
is can they get the information they need in a timely manner.  Good 
comprehensive documentation will help them achieve that.  That being said, 
I realize we don't have the resources to do everything at once, but it's 
good to have a goal, even if it takes a while to reach it.

> 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.

This is a valid concern.  It's one of my biggest concerns about open source 
software. The documentation is almost always out-of-date and lacking in one 
way or another. You're right, I think the man pages and tutorial have been 
kept up-to-date pretty well for systemtap. When we throw other docs in the 
mix, we have to make sure they stay in sync as well.

- Mike

> Jim