[cfe-commits] Updated and expanded Clang manual page (docs/tools/clang.pod)

[John McCall]

On Nov 28, 2012, at 4:10 AM, Jean-Daniel Dupas <devlists at shadowlab.org> wrote:
> Le 28 nov. 2012 à 01:37, John McCall <rjmccall at apple.com> a écrit :
>> On Nov 21, 2012, at 10:40 AM, Jonathan de Boyne Pollard <J.deBoynePollard-newsgroups at NTLWorld.COM> wrote:
>>> On 2012-11-21 16:19, Chris Lattner wrote:
>>>> Definitely! Please send patches to the cfe-commits mailing list! 
>>> 
>>> The output of svn diff turns out to be larger, at 28KiB, than the file itself, which is 27KiB.  So I'm attaching the file as-is. Enjoy.  I might be persuaded to fill in some more of the missing bits.  (-:
>>> <clang.pod>
>> 
>> First of all, thank you for doing this.  I think this is an excellent start.
>> 
>> I haven't read through the entire page yet, but I do have a major
>> piece of feedback which (to be clear) I don't think should necessarily
>> block this going into trunk.
>> 
>> The major complaint is about your audience.  Manual pages are
>> user documentation, but you've got a lot in here that's more of a
>> description of the clang *project* than a reference for the clang
>> *program*.  For example, a typical user of this manual page does
>> not need to know straight off that Clang is built on top of the LLVM
>> project and that we have separate stages of compilation that build
>> semantically-rich ASTs and then translate them into LLVM IR.
>> 
>> The man page should look basically like this:
>> 
>> 1.  Synopsis
>> 2.  Brief description (a few paragraphs, easily scrolled past) of
>>    capabilities of tool, possibly with copious forward-references
>> 3.  Discussion of basic usage
>> 4.  Detailed options reference
>> 5.  Architectural details if user-relevant
>> 6.  End-matter
>> 
>> So personally I would rewrite the introduction somewhat like this:
>> 
>> B<clang> is a C, C++, Objective-C, and Objective-C++ compiler.  It
>> fully supports the C11 and C++11 language standards as well as a
>> robust set of language extensions.  Its option syntax is (with one
>> exception, see OPTIONS below) a superset of that of the the
>> POSIX.1:2008 C<c99> utility.
> 
> Maybe this introduction is a little too optimistic about the C11 full support.
> While clang supports the most useful C11 extensions, I'm not sure it can claim full support yet (for instance, _Noreturn and _Thread_local keywords support is not implemented at all).

Good point;  we should only claim C99 conformance.  Would you mind filing PRs about the missing extensions, though?  Both of those should be quite straightforward.

John.