<div dir="ltr">Here is the document, pasted into the mail instead of being attached:<div><br><div>-- Proposal --</div><div>User Manual for Clang.</div><div><br></div><div>-- Intent --</div><div>Create and maintain help and maual pages for clang.</div>
<div><br></div><div>-- Motivation --</div><div>* There is no decent manual that includes everything that clang has to offer.</div><div>* Knowladge is spread among few places.</div><div>* There are options that are not documented.</div>
<div>* Clang's users are using GNU's manuals !$;~(.</div><div><br></div><div>-- Requirments --</div><div>* Accessible documentation for clang.</div><div>* Up-to-Date documentation now and in the future.</div><div>
* Ease of use for developers.</div><div><br></div><div>-- Background --</div><div>When dealing with a compiler, most of the documentation needed by users</div><div>is how to use its various options. Developers of the compiler need other</div>
<div>information - this paper does not address them.</div><div>A manual is considered a good one if it is being used over and over again,</div><div>if one can find everything she needs inside it and, if it gives the right</div>
<div>answer in a short time.</div><div><br></div><div>-- Technique --</div><div>Extend current implementation.</div><div>Current implementation has few advantages that we should adhere:</div><div>It is simple, uses TableGen.</div>
<div>It is commonly used in LLVM.</div><div><br></div><div>-- Design --</div><div>* Coupling between a compilation option and its help text (hereinafter "o-help",</div><div>read: option-help).</div><div>Adding/fixing/updating a compilation option must include activity on its o-help.</div>
<div>This way documentation keep being relevant.</div><div><br></div><div>* Decoupling between the o-help and its view. The same o-help may be presented</div><div>in various ways. It is one thing to write the documentation and another thing</div>
<div>to present it to the user. We shouldn't couple between the two. The o-help on its</div><div>own shoudln't have any representation intent. See 'o-help properties' below.</div><div><br></div><div>* Create some sort of enforcememt on developers for actually supply the o-help for</div>
<div>their option. Nice-to-have / optional / not mandatory activities are tend to be</div><div>neglected... ending with not up to date documentation.</div><div><br></div><div>-- O-help properties --</div><div>Here is a list of suggested o-help properties to keep along with each compilation option.</div>
<div>- group : as implemented today. the group this option belong to.</div><div>- short description : as implemented today. a short description of the option.</div><div>- long description : detailed explnation of the option.</div>
<div>- common use : text that describes common use of the option.</div><div>- example : the output with and the output without this option.</div><div>- commonality (0-2) : how common this option is: 0-most, 1-somtimes, 2-rarely/developers only</div>
<div>- known issues : bugs, limits, etc.</div><div><br></div><div>-- O-help example --</div><div>option : -c</div><div><br></div><div>group : compile only</div><div><br></div><div>
short description : Only run preprocess, compile, and assemble steps</div><div><br></div><div>long description :</div><div>Compile or assemble the source files, but do not link.</div><div>The linking stage simply is not done.</div>
<div>The ultimate output is in the form of an object file for each source file.</div><div>By default, the object file name for a source file is made by replacing</div><div>the suffix .c, .i, .s, etc., with .o.</div><div>Unrecognized input files, not requiring compilation or assembly, are ignored.</div>
<div><br></div><div>common use :</div><div>* compiling a single file for the sake of syntactic problems.</div><div>not as part of a big-building-process.</div><div>* creating objects that are later linked, as a step in a big-building-process</div>
<div><br></div><div>example :</div><div>with: clang++ -c foo.cpp</div><div>output: foo.o - the object file generated from foo.cpp</div><div>without: clang++ foo.cpp</div><div>output: a.out - an executable file generated from foo.cpp</div>
<div><br></div><div>commonality (0-2) : 0</div><div><br></div><div>known issues : this is a fundamental option, no kwnon issues.</div><div><br></div><div>-- Uses of o-help --</div><div>Since we decouple the o-help from its use,</div>
<div>the usage may vary and evolve with time.</div><div><br></div><div>Few usages that are currently in mind:</div><div><br></div><div>- generating manual pages. o-help properties:</div><div>short description, long description, common use, example and known issues</div>
<div><br></div><div>- generating --help 's result. o-help properties:</div><div>group, short description, commonality(=0)</div><div><br></div><div>- generating --help <details> 's result. o-help properties:</div>
<div>group, short description, commonality(=0-details)</div><div><br></div><div>- generating html pages. o-help properties:</div><div>group, short description, long description,</div><div>common use, exampe, commonality (0-2), known issues</div>
<div><br></div><div>imagination is the limit once we have the data.</div><div><br></div><div>-- Transition --</div><div>To transit from current state to fully-up-to-date-documentation state we'll just</div><div>insert some defaults and fill them with time with real, good documentation.</div>
<div>It might look strange a bit at first glance, but what would you prefer as a user:</div><div>no documentation at all or 'will be written soon'?</div><div><br></div><div>-- Implementation --</div><div>Implementation issues will be discussed in a smaller group and will start once the concept is closed.</div>
<br><br><div class="gmail_quote">On 9 May 2012 15:22, Ran Regev <span dir="ltr"><<a href="mailto:regev.ran@gmail.com" target="_blank">regev.ran@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr"><div>All,</div><div><br><div>Attached is a document describing a suggestion for handling the user manual.</div><div>Please take a few minutes to review the file and comment.</div><div><br></div><div>EVERY LINE in the document can be criticised!</div>
<div>(And the idea as a whole may too...)</div><span class="HOEnZb"><font color="#888888"><div><br></div><div><br></div><div><br></div><div>Ran.</div></font></span></div></div>
</blockquote></div><br></div></div>