On Wed, Jun 18, 2014 at 5:56 PM, Adrian Prantl <[email protected]> wrote:
> > > On Jun 15, 2014, at 1:07 PM, Alp Toker <[email protected]> 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 > >> [email protected] > >> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits > > > > -- > > http://www.nuanti.com > > the browser experts > > > _______________________________________________ > cfe-commits mailing list > [email protected] > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits >
_______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
