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

[Ran Regev]

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 <details> '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.


On 9 May 2012 15:22, Ran Regev <regev.ran at gmail.com> wrote:

> All,
>
> Attached is a document describing a suggestion for handling the user
> manual.
> Please take a few minutes to review the file and comment.
>
> EVERY LINE in the document can be criticised!
> (And the idea as a whole may too...)
>
>
>
> Ran.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20120510/a8252a91/attachment.html>