User Manual (mail-embedded)

Here is the document, pasted into the mail instead of being attached:

– Proposal –
User Manual for Clang.

– Intent –
Create and maintain help and maual pages for clang.

– Motivation –

  • There is no decent manual that includes everything that clang has to offer.
  • Knowladge is spread among few places.
  • There are options that are not documented.
  • Clang’s users are using GNU’s manuals !$;~(.

– Requirments –

  • Accessible documentation for clang.
  • Up-to-Date documentation now and in the future.
  • Ease of use for developers.

– Background –
When dealing with a compiler, most of the documentation needed by users
is how to use its various options. Developers of the compiler need other
information - this paper does not address them.
A manual is considered a good one if it is being used over and over again,
if one can find everything she needs inside it and, if it gives the right
answer in a short time.

– Technique –
Extend current implementation.
Current implementation has few advantages that we should adhere:
It is simple, uses TableGen.
It is commonly used in LLVM.

– Design –

  • Coupling between a compilation option and its help text (hereinafter “o-help”,
    read: option-help).
    Adding/fixing/updating a compilation option must include activity on its o-help.
    This way documentation keep being relevant.

  • Decoupling between the o-help and its view. The same o-help may be presented
    in various ways. It is one thing to write the documentation and another thing
    to present it to the user. We shouldn’t couple between the two. The o-help on its
    own shoudln’t have any representation intent. See ‘o-help properties’ below.

  • Create some sort of enforcememt on developers for actually supply the o-help for
    their option. Nice-to-have / optional / not mandatory activities are tend to be
    neglected… ending with not up to date documentation.

– O-help properties –
Here is a list of suggested o-help properties to keep along with each compilation option.

  • group : as implemented today. the group this option belong to.
  • short description : as implemented today. a short description of the option.
  • long description : detailed explnation of the option.
  • common use : text that describes common use of the option.
  • example : the output with and the output without this option.
  • commonality (0-2) : how common this option is: 0-most, 1-somtimes, 2-rarely/developers only
  • known issues : bugs, limits, etc.

– O-help example –
option : -c

group : compile only

short description : Only run preprocess, compile, and assemble steps

long description :
Compile or assemble the source files, but do not link.
The linking stage simply is not done.
The ultimate output is in the form of an object file for each source file.
By default, the object file name for a source file is made by replacing
the suffix .c, .i, .s, etc., with .o.
Unrecognized input files, not requiring compilation or assembly, are ignored.

common use :

  • compiling a single file for the sake of syntactic problems.
    not as part of a big-building-process.
  • creating objects that are later linked, as a step in a big-building-process

example :
with: clang++ -c foo.cpp
output: foo.o - the object file generated from foo.cpp
without: clang++ foo.cpp
output: a.out - an executable file generated from foo.cpp

commonality (0-2) : 0

known issues : this is a fundamental option, no kwnon issues.

– Uses of o-help –
Since we decouple the o-help from its use,
the usage may vary and evolve with time.

Few usages that are currently in mind:

  • generating manual pages. o-help properties:
    short description, long description, common use, example and known issues

  • generating --help 's result. o-help properties:
    group, short description, commonality(=0)

  • generating --help

    's result. o-help properties:
    group, short description, commonality(=0-details)

  • generating html pages. o-help properties:
    group, short description, long description,
    common use, exampe, commonality (0-2), known issues

imagination is the limit once we have the data.

– Transition –
To transit from current state to fully-up-to-date-documentation state we’ll just
insert some defaults and fill them with time with real, good documentation.
It might look strange a bit at first glance, but what would you prefer as a user:
no documentation at all or ‘will be written soon’?

– Implementation –
Implementation issues will be discussed in a smaller group and will start once the concept is closed.

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