Re: clang manual page?

On 6 Apr 2018, at 07:20, David Chisnall <theraven_at_FreeBSD.org> wrote:
> 
> On 6 Apr 2018, at 01:30, Pete Wright <pete_at_nomadlogic.org> wrote:
>> 
>> On 04/05/2018 17:15, Steve Kargl wrote:
>>> This assumes that a gcc(1) is available on the system.
>>> 
>>> % man gcc
>>> No manual entry for gcc
>>> 
>>> If the system compiler is clang/clang++, then it ought to be
>>> documented better than it currently is.  Ian's suggests for
>>> 'clang --help' is even worse
>>> 
>>> %  clang --help | grep -- -std
>>>  -cl-std=<value>         OpenCL language standard to compile for.
>>>  -std=<value>            Language standard to compile for
>>>  -stdlib=<value>         C++ standard library to use
>>> 
>>> Does <value> == <language>?
>>> 
>> a quick google search turns up the following additional information:
>> 
>> "clang supports the -std option, which changes what language mode clang uses. The supported modes for C are c89, gnu89, c99, gnu99, c11, gnu11, c17, gnu17, and various aliases for those modes. If no -std option is specified, clang defaults to gnu11 mode. Many C99 and C11 features are supported in earlier modes as a conforming extension, with a warning. Use |-pedantic-errors| to request an error if a feature from a later standard revision is used in an earlier mode."
>> 
>> https://clang.llvm.org/docs/UsersManual.html
> 
> I believe that the clang user manual referenced here is written in Sphynx, which is able to generate mandoc output as well as HTML.  Perhaps we should incorporate the generated file in the next import?

Yes, but that manual is also pretty much incomplete, so with the last
import I decided to stay with the older perl doc based one.  Upstream
is pretty bad at writing detailed documentation, certainly in the form
of man pages.

With lld there wasn't even *any* form of command line documentation
yet, which is why Ed slapped together a man page (that could probably
still use more details).  It should really be upstreamed, in Sphinx's
RST format, or since they appear to gravitate towards Markdown now,
maybe already in that format.

For a clang man page I'd really prefer working with upstream to get
some more details in there, like an exhaustive list of which -std=
options are supported.  But it's quite a lot of effort.

-Dimitry