Re: [Bug documentation/11684] eliminate duplication between language reference guide and generated tapset docs

["Frank Ch. Eigler" <fche at redhat dot com>]

Hi -

lberk wrote: (http://sourceware.org/bugzilla/show_bug.cgi?id=11684)

> http://fpaste.org/Lrw7/ contains a diff of changes(In reply to comment #0)

Thanks!

It would help to see samples of the rendered versions of the two
documents before & after your change.  The markup alone makes it a bit
hard to see the impact.  A few questions come to mind reading just the
diffs though.

What is "\comment098" and "\comment089" (in the langref .tex file)?

Is there necessarily a need to even enumerate tapset functions there,
each with a "see .../tapset/foo.stp for more information"?  Maybe just
enumerate the *tapsets*, not their contents.  Also, to a user,
"$PREFIX" is not informative; just say .../systemtap/tapset/foo.stp
or even "the tapset::foo.3stap man page" if such exists.

Where did the idea for "General Syntax:" piece for the tapset /* */
docs come from?  It is only used in the langref file, not in the
normal generated docs.  Is it necessary?  There is already a generated
SYNOPSYS section, IIRC.

- FChE