r210936 - Copy the documentation of -fstandalone-debug from the man page to the user

[Adrian Prantl]

> On Jun 15, 2014, at 1:07 PM, Alp Toker <alp at nuanti.com> wrote:
> 
> 
> On 14/06/2014 00:12, Adrian Prantl wrote:
>> Author: adrian
>> Date: Fri Jun 13 16:12:31 2014
>> New Revision: 210936
>> 
>> URL: http://llvm.org/viewvc/llvm-project?rev=210936&view=rev
>> Log:
>> Copy the documentation of -fstandalone-debug from the man page to the user
>> manual.
> 
> Hi Adrian,
> 
> It bothers me that we now have two copies of this documentation in-tree.
> 
> There are readily available tools to generate man pages from rst files. The cost of hooking a doc tool up to the build system is certainly lower than having skilled compiler engineers maintain two divergent copies of the documentation (history shows we have a hard enough time maintaining a single set of quality docs, let alone two).
> 
> Do you have a timeline to remove one of the duplicate copies?

Hi Alp,

I think this is a reasonable suggestion, but after comparing the user manual and the man page, I’m unsure what the best way to proceed here is. There obviously is some overlap between user manual and man page, and we might be able to extract a common core that is shared between user manual and man page and automatically inserted into both at documentation build time. But the man page can also be seen as a condensed version of the user manual that only briefly lists all the options and everything that is necessary to invoke the various tools on the command line, and form that point of view, it is not clear whether it is even desirable to unify those two texts.

-- adrian

> 
> Alp.
> 
> 
> 
>> 
>> rdar://problem/17307006
>> 
>> Modified:
>>     cfe/trunk/docs/UsersManual.rst
>> 
>> Modified: cfe/trunk/docs/UsersManual.rst
>> URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/UsersManual.rst?rev=210936&r1=210935&r2=210936&view=diff
>> ==============================================================================
>> --- cfe/trunk/docs/UsersManual.rst (original)
>> +++ cfe/trunk/docs/UsersManual.rst Fri Jun 13 16:12:31 2014
>> @@ -1298,6 +1298,22 @@ below. If multiple flags are present, th
>>    doesn't contain any other data (e.g. description of local variables or
>>    function parameters).
>>  +.. option:: -fstandalone-debug -fno-standalone-debug
>> +
>> +  Clang supports a number of optimizations to reduce the size of debug
>> +  information in the binary. They work based on the assumption that
>> +  the debug type information can be spread out over multiple
>> +  compilation units.  For instance, Clang will not emit type
>> +  definitions for types that are not needed by a module and could be
>> +  replaced with a forward declaration.  Further, Clang will only emit
>> +  type info for a dynamic C++ class in the module that contains the
>> +  vtable for the class.
>> +
>> +  The ``-fstandalone-debug`` option turns off these optimizations.
>> +  This is useful when working with 3rd-party libraries that don't come
>> +  with debug information.  Note that Clang will never emit type
>> +  information for types that are not referenced at all by the program.
>> +
>>  .. option:: -g
>>      Generate complete debug info.
>> 
>> 
>> _______________________________________________
>> cfe-commits mailing list
>> cfe-commits at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
> 
> -- 
> http://www.nuanti.com
> the browser experts