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

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

[fche at redhat dot com]

doc/langref.tex contains a lot of tapset details that have become
obsolete and duplicative of the generated stuff in the tapset/*.stp
files and the hand-made stuff in man/tapset::*.

Let's shrink doc/langref.tex to eliminate the duplication.

-- 
           Summary: eliminate duplication between language reference guide
                    and generated tapset docs
           Product: systemtap
           Version: unspecified
            Status: NEW
          Severity: normal
          Priority: P2
         Component: documentation
        AssignedTo: systemtap at sources dot redhat dot com
        ReportedBy: fche at redhat dot com


http://sourceware.org/bugzilla/show_bug.cgi?id=11684

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

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

[lberk at redhat dot com]

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
         AssignedTo|systemtap at sources dot    |lberk at redhat dot com
                   |redhat dot com              |
             Status|NEW                         |ASSIGNED


http://sourceware.org/bugzilla/show_bug.cgi?id=11684

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

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

[Frank Ch. Eigler]

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