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

[John McCall]

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.

  C<clang> is intended to be broadly compatible with GCC, using the
  same option syntax, providing most of the major language extensions,
  and producing code that is ABI-compatible with that compiler.

  The C<clang> command is a I<driver> which can perform many
  different operations depending on how it is invoked.  C<clang> itself
  includes a preprocessor, parser, static analyzer, optimizer, and
  code generator.  It also includes an assembler for some targets;  for
  others, it relies on the L<as(1)> utility.  For linking, it relies on the
  L<ld(1)> utility.  For more information, see ARCHITECTURE below.

After that, I'd go into the stuff about clang++ and the major driver options,
and then dive into the detailed options reference.  Only after all that
would you put the ARCHITECTURE section which would talk about
LLVM and IR-generation and so on.

John.