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

[Sean Silva]

On Wed, Jun 18, 2014 at 5:56 PM, Adrian Prantl <aprantl at apple.com> wrote:

>
> > 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


Users expect a manpage to be an authoritative references for the
commandline options of a program. It is not a "condensed" version of
anything. It is the reference documentation for the option.

That being said, clang's manpage is pretty sad and we currently do not
maintain it aiming for the goal I set out in the previous paragraph.

-- Sean Silva


> 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
>
>
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20140620/b048c0bd/attachment.html>