[cfe-dev] cfe-dev Digest, Vol 59, Issue 42

[Ran Regev]

1. While emphasizing manual work for documantation, how do you explain the
fact that there is no user manul for clang?

2. I really don't want to go into implementation details. We could extend
current implementation or switch to a super-high-end-class-documentation
tool -

The idea of seperating the data from its representation is the important
issue.

>From my point of view all we need is an index, a pointer, a key into a
database of data regarding the compilation option.
This is the o-help key/index that must be embedded in code and by using it
we enter a world of data regarding the option.

I think that "Options.td should still contain a small, one-line description
of each option for the purpose of --help etc" is the root of the problem.
We couple the use to the data.

There are many developers that don't use command line and still want to
have short description of a compilation option (for example by a tool-tip
when hovering over a checkbox with the mouse).

The discussion should be therefore:
What fields/data/column/properties/name-it-as-you-like should be part of
the database of each option?
What are the fields that when having them we can generate any
representation we love?
What is the underlaying data that can keep a good documentation with time?

For example, if we want the data to be structured later by some sort of
hierarchy, as suggested below, we must then add hierarchy-value. I thought
that the 'group' property is enough, creating one-level-hierarchy. But if
someone think that more is needed, please explain and give an example.


And remember, I really don't want this discussion to be on the 'How' side
at the moment. Let's close the 'What' first.


Ran.




> ---------- Forwarded message ----------
> From: Joerg Sonnenberger <joerg at britannica.bec.de>
> To: cfe-dev at cs.uiuc.edu
> Cc:
> Date: Thu, 10 May 2012 10:54:02 +0200
> Subject: Re: [cfe-dev] User Manual (mail-embedded)
> On Thu, May 10, 2012 at 08:19:15AM +0300, Ran Regev wrote:
> > -- Technique --
> > Extend current implementation.
> > Current implementation has few advantages that we should adhere:
> > It is simple, uses TableGen.
> > It is commonly used in LLVM.
>
> I'll comment on this part, since it is the heart. Let's take a look at
> GCC's
> info and man page for a moment to see what is wrong with and what works.
> The man page tends to be abysmal. It is created automatically from the
> info page with a fancy and somewhat broken toolchain. It has lots of
> structural (and lack thereof) and syntactical issues. It certainly
> proves that a man page listening thousands of options has very limited
> use. The info page is somewhat better, since it is hierachical and
> navigable. How do you want to get a well structured document by
> semi-automatically rearranging entries from *Options.td? I consider this
> the same problem as with Doxygen style documentation. It is nice if you
> want to document the available methods of a class, but starts to become
> limiting when you want to give a more high level discription of a
> system.
>
> I would:
>
> - *de*couple the manual from *Options.td and choose the right tools (as
> in format) for the job. Plain HTML, docbook, sphinx -- many options
> exits for this
>
> - require (comment) markers in the manual to identify which options are
> documented
>
> - provide automated tools to verify consistency between the set of
> documented and implemented options
>
> *Options.td should still contain a small, one-line description of each
> option for the purpose of --help etc, but I expect most options to end
> up with a more detailed text than that.
>
> To summarize: being able to freely shuffle texts around is critical for
> documentation. Source code is not the best tool for documentation.
> Coherency issues can be avoided by using appropiate markers.
>
> Joerg
>
>
>
> ---------- Forwarded message ----------
> From: "David Röthlisberger" <david at rothlis.net>
> To: cfe-dev at cs.uiuc.edu
> Cc:
> Date: Thu, 10 May 2012 11:36:13 +0100
> Subject: Re: [cfe-dev] scan-build man page
> Hi James
>
> Don't let yourself be discouraged by these people expecting some kind of
> "perfect" solution... it is far too hard to get even the smallest change
> in, but do persevere. :-)
>
> --Dave.
>
>
> On 7 May 2012, at 22:36, James K. Lowden wrote:
> > On Mon, 07 May 2012 10:21:01 -0700
> > Ted Kremenek <kremenek at apple.com> wrote:
> >
> > Hi Ted,
> >
> >> The man page looks really great.
> >
> > Thanks.  I'm glad to start a conversation with it.
> >
> >> My main concern, however, is
> >> supporting divergent documents.  Ideally we want the documentation
> >> for scan-build, the man page, etc., to all be in sync.
> >
> > Having maintained a 90-page user guide for 10 years, I understand that
> > concern.  I want to suggest, though, that "keeping it in sync" not as
> > big a deal as most people think.  Documentation is not very redundant
> > because it's labor-intensive, and labor, as you know, is scarce.
> > Therefore overlap is inherently self-limiting.
> >
> > Documentation is also not amenable to automation.  We want it to be; we
> > want the code to be self-documenting.  And good code (by definition)
> > is self-documenting.  But what we want from documentation isn't *in* the
> > code (or shouldn't be).  It has to be written.  Asking for
> > self-generating documentation is a bit like asking for self-generating
> > code.
> >
> > That said, the most tedious part of maintaining a reference manual is
> > documenting all the options and ensuring 1) all options are documented
> > and 2) all documented options are implemented.  Keeping the man page
> > synchronized with the implementation can, in principle, be automated.
> > But it doesn't follow that the man page must therefore be generated,
> > even in part; it might be better simply to have a system that compared
> > the two and reported on the differences.  For a small number of man
> > pages, that "system" might be just eyeballs, and some vigilance when
> > options are added/deleted.
> >
> >> My main concern about having a separate man page file is that someone
> >> is now responsible for keeping it up-to-date.
> >
> > True.  Documentation even introduces bugs, because undocumented
> > functionality never contradicted observed behavior.  ;-)
> >
> >> It's a bit of engineering, but I'd prefer we go in a direction where
> >> the man page and the scan-build documentation on the website (or at
> >> least part of it) were machine generated from some common description
> >
> > I would like to convince you that's both unnecessary and infeasible.
> >
> > First, it's an optimization of labor with labor, right?  And the rule
> > for optimization is to measure first.  How much do the man page and the
> > website have in common?  I don't see much, nor need for more.
> >
> > Even the obvious overlap -- command-line options -- doesn't warrant
> > wholesale duplication.  A guide properly presents some of the
> > options in an order chosen for ease of learning.  Rather than interrupt
> > the text with an exhaustive list of every option and its synonym, a
> > guide serves the user better by referring him to the reference manual
> > for complete details.  As soon as you're selecting *some* options in a
> > pedagogical order, you might as well just do it by hand.  The time
> > spent getting that information into a back-end database and building
> > the integration system will never be repaid.
> >
> > Keep in mind Vint Cerf's dictum, too.  If you reject documentation
> > because it's not in the "right" form, you restrict the number of
> > contributors.  Not everyone willing and able to document will be
> > interested in learning a specialized technology to do so.
> >
> >> It sounds like you had a fairly mechanical process for generating the
> >> man page (you took scan-build's output and manually post processed
> >> it).  Do you think we could automate this with a script, so the man
> >> page could just be a product of the build?
> >
> > Mechnical, yes, but it can't be automated.  The text from scan-build
> > lacks the very markers I added: the headings, that "model" is an
> > argument, that [=title] is optional, and so on.
> >
> > In principle the text could remain embedded in scan-build and extracted
> > to generate a man page.  But you'd have to re-invent half of -mdoc in
> > the process, without any improvement in the outcome.  Perldoc is a
> > good example.
> >
> >> Alternatively, since scan-build generates most of this text, maybe it
> >> could generate the options part of the man page itself (as an option
> >> to its output format), and have that output concatenated with some
> >> common preamble.  What do you think?
> >
> > I would remove the help text from scan-build.  You don't need it
> > anymore.  "man scan-build" is easier to use, and everyone knows how.
> > Maintaining the man page is trivial next to the effort that goes into
> > the scanner.
> >
> > Besides, I'm allergic to so-called "help" that scrolls off my screen
> > and destroys the 23 lines of context I had before it took over.  Be
> > warned: for reasons science has been totally unable to explain, that
> > allergy has been observed to be contagious.  I think I got it from
> > Subversion.
> >
> > Someone will be tempted to suggest that if the documentation is amid
> > the code, the programmer will be more likely to keep it up to date.
> > That proposition is contradicted by vast collective experience.  We both
> > know huge projects with enviable (never perfect) documentation
> > maintained as man pages.  I don't know of any that owe their
> > documentation to how easy it is to maintain.
> >
> > Again: I do think that reference documentation can and should be
> > synchronized with the code.  Better tools could make that more
> > convenient than anything available today by reducing redundancy, by not
> > requiring, for instance, that function and argument names be restated.
> > Clang promises to make that possible for C++.  It's one of the reasons
> > I'm interested.
> >
> > Regards,
> >
> > --jkl
> > _______________________________________________
> > cfe-dev mailing list
> > cfe-dev at cs.uiuc.edu
> > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>
>
>
>
>
> _______________________________________________
> cfe-dev mailing list
> cfe-dev at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120510/f84dd539/attachment.html>