[cfe-dev] User Manual (mail-embedded)

[Joerg Sonnenberger]

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