<div dir="ltr"><div class="gmail_quote"><div><br></div><div>1. While emphasizing manual work for documantation, how do you explain the fact that there is no user manul for clang?</div><div><br></div><div>2. I really don't want to go into implementation details. We could extend current implementation or switch to a super-high-end-class-documentation tool -</div>
<div><br></div><div>The idea of seperating the data from its representation is the important issue.</div><div><br></div><div>From my point of view all we need is an index, a pointer, a key into a database of data regarding the compilation option. </div>
<div>This is the o-help key/index that must be embedded in code and by using it we enter a world of data regarding the option.</div><div><br></div><div>I think that "Options.td should still contain a small, one-line description of each option for the purpose of --help etc" is the root of the problem. We couple the use to the data.</div>
<div><br></div><div>There are many developers that don't use command line and still want to have short description of a compilation option (for example by a tool-tip when hovering over a checkbox with the mouse).</div>
<div><br></div><div>The discussion should be therefore:</div><div>What fields/data/column/properties/name-it-as-you-like should be part of the database of each option?</div><div>What are the fields that when having them we can generate any representation we love?</div>
<div>What is the underlaying data that can keep a good documentation with time?</div><div><br></div><div>For example, if we want the data to be structured later by some sort of hierarchy, as suggested below, we must then add hierarchy-value. I thought that the 'group' property is enough, creating one-level-hierarchy. But if someone think that more is needed, please explain and give an example.</div>
<div><br></div><div><br></div><div>And remember, I really don't want this discussion to be on the 'How' side at the moment. Let's close the 'What' first.</div><div><br></div><div><br></div><div>Ran.</div>
<div><br></div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">---------- Forwarded message ----------<br>From: Joerg Sonnenberger <<a href="mailto:joerg@britannica.bec.de">joerg@britannica.bec.de</a>><br>
To: <a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>Cc: <br>Date: Thu, 10 May 2012 10:54:02 +0200<br>Subject: Re: [cfe-dev] User Manual (mail-embedded)<br>On Thu, May 10, 2012 at 08:19:15AM +0300, Ran Regev wrote:<br>

> -- Technique --<br>
> Extend current implementation.<br>
> Current implementation has few advantages that we should adhere:<br>
> It is simple, uses TableGen.<br>
> It is commonly used in LLVM.<br>
<br>
I'll comment on this part, since it is the heart. Let's take a look at GCC's<br>
info and man page for a moment to see what is wrong with and what works.<br>
The man page tends to be abysmal. It is created automatically from the<br>
info page with a fancy and somewhat broken toolchain. It has lots of<br>
structural (and lack thereof) and syntactical issues. It certainly<br>
proves that a man page listening thousands of options has very limited<br>
use. The info page is somewhat better, since it is hierachical and<br>
navigable. How do you want to get a well structured document by<br>
semi-automatically rearranging entries from *Options.td? I consider this<br>
the same problem as with Doxygen style documentation. It is nice if you<br>
want to document the available methods of a class, but starts to become<br>
limiting when you want to give a more high level discription of a<br>
system.<br>
<br>
I would:<br>
<br>
- *de*couple the manual from *Options.td and choose the right tools (as<br>
in format) for the job. Plain HTML, docbook, sphinx -- many options<br>
exits for this<br>
<br>
- require (comment) markers in the manual to identify which options are<br>
documented<br>
<br>
- provide automated tools to verify consistency between the set of<br>
documented and implemented options<br>
<br>
*Options.td should still contain a small, one-line description of each<br>
option for the purpose of --help etc, but I expect most options to end<br>
up with a more detailed text than that.<br>
<br>
To summarize: being able to freely shuffle texts around is critical for<br>
documentation. Source code is not the best tool for documentation.<br>
Coherency issues can be avoided by using appropiate markers.<br>
<br>
Joerg<br>
<br>
<br><br>---------- Forwarded message ----------<br>From: "David Röthlisberger" <<a href="mailto:david@rothlis.net">david@rothlis.net</a>><br>To: <a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
Cc: <br>Date: Thu, 10 May 2012 11:36:13 +0100<br>Subject: Re: [cfe-dev] scan-build man page<br>Hi James<br>
<br>
Don't let yourself be discouraged by these people expecting some kind of "perfect" solution... it is far too hard to get even the smallest change in, but do persevere. :-)<br>
<br>
--Dave.<br>
<br>
<br>
On 7 May 2012, at 22:36, James K. Lowden wrote:<br>
> On Mon, 07 May 2012 10:21:01 -0700<br>
> Ted Kremenek <<a href="mailto:kremenek@apple.com">kremenek@apple.com</a>> wrote:<br>
><br>
> Hi Ted,<br>
><br>
>> The man page looks really great.<br>
><br>
> Thanks.  I'm glad to start a conversation with it.<br>
><br>
>> My main concern, however, is<br>
>> supporting divergent documents.  Ideally we want the documentation<br>
>> for scan-build, the man page, etc., to all be in sync.<br>
><br>
> Having maintained a 90-page user guide for 10 years, I understand that<br>
> concern.  I want to suggest, though, that "keeping it in sync" not as<br>
> big a deal as most people think.  Documentation is not very redundant<br>
> because it's labor-intensive, and labor, as you know, is scarce.<br>
> Therefore overlap is inherently self-limiting.<br>
><br>
> Documentation is also not amenable to automation.  We want it to be; we<br>
> want the code to be self-documenting.  And good code (by definition)<br>
> is self-documenting.  But what we want from documentation isn't *in* the<br>
> code (or shouldn't be).  It has to be written.  Asking for<br>
> self-generating documentation is a bit like asking for self-generating<br>
> code.<br>
><br>
> That said, the most tedious part of maintaining a reference manual is<br>
> documenting all the options and ensuring 1) all options are documented<br>
> and 2) all documented options are implemented.  Keeping the man page<br>
> synchronized with the implementation can, in principle, be automated.<br>
> But it doesn't follow that the man page must therefore be generated,<br>
> even in part; it might be better simply to have a system that compared<br>
> the two and reported on the differences.  For a small number of man<br>
> pages, that "system" might be just eyeballs, and some vigilance when<br>
> options are added/deleted.<br>
><br>
>> My main concern about having a separate man page file is that someone<br>
>> is now responsible for keeping it up-to-date.<br>
><br>
> True.  Documentation even introduces bugs, because undocumented<br>
> functionality never contradicted observed behavior.  ;-)<br>
><br>
>> It's a bit of engineering, but I'd prefer we go in a direction where<br>
>> the man page and the scan-build documentation on the website (or at<br>
>> least part of it) were machine generated from some common description<br>
><br>
> I would like to convince you that's both unnecessary and infeasible.<br>
><br>
> First, it's an optimization of labor with labor, right?  And the rule<br>
> for optimization is to measure first.  How much do the man page and the<br>
> website have in common?  I don't see much, nor need for more.<br>
><br>
> Even the obvious overlap -- command-line options -- doesn't warrant<br>
> wholesale duplication.  A guide properly presents some of the<br>
> options in an order chosen for ease of learning.  Rather than interrupt<br>
> the text with an exhaustive list of every option and its synonym, a<br>
> guide serves the user better by referring him to the reference manual<br>
> for complete details.  As soon as you're selecting *some* options in a<br>
> pedagogical order, you might as well just do it by hand.  The time<br>
> spent getting that information into a back-end database and building<br>
> the integration system will never be repaid.<br>
><br>
> Keep in mind Vint Cerf's dictum, too.  If you reject documentation<br>
> because it's not in the "right" form, you restrict the number of<br>
> contributors.  Not everyone willing and able to document will be<br>
> interested in learning a specialized technology to do so.<br>
><br>
>> It sounds like you had a fairly mechanical process for generating the<br>
>> man page (you took scan-build's output and manually post processed<br>
>> it).  Do you think we could automate this with a script, so the man<br>
>> page could just be a product of the build?<br>
><br>
> Mechnical, yes, but it can't be automated.  The text from scan-build<br>
> lacks the very markers I added: the headings, that "model" is an<br>
> argument, that [=title] is optional, and so on.<br>
><br>
> In principle the text could remain embedded in scan-build and extracted<br>
> to generate a man page.  But you'd have to re-invent half of -mdoc in<br>
> the process, without any improvement in the outcome.  Perldoc is a<br>
> good example.<br>
><br>
>> Alternatively, since scan-build generates most of this text, maybe it<br>
>> could generate the options part of the man page itself (as an option<br>
>> to its output format), and have that output concatenated with some<br>
>> common preamble.  What do you think?<br>
><br>
> I would remove the help text from scan-build.  You don't need it<br>
> anymore.  "man scan-build" is easier to use, and everyone knows how.<br>
> Maintaining the man page is trivial next to the effort that goes into<br>
> the scanner.<br>
><br>
> Besides, I'm allergic to so-called "help" that scrolls off my screen<br>
> and destroys the 23 lines of context I had before it took over.  Be<br>
> warned: for reasons science has been totally unable to explain, that<br>
> allergy has been observed to be contagious.  I think I got it from<br>
> Subversion.<br>
><br>
> Someone will be tempted to suggest that if the documentation is amid<br>
> the code, the programmer will be more likely to keep it up to date.<br>
> That proposition is contradicted by vast collective experience.  We both<br>
> know huge projects with enviable (never perfect) documentation<br>
> maintained as man pages.  I don't know of any that owe their<br>
> documentation to how easy it is to maintain.<br>
><br>
> Again: I do think that reference documentation can and should be<br>
> synchronized with the code.  Better tools could make that more<br>
> convenient than anything available today by reducing redundancy, by not<br>
> requiring, for instance, that function and argument names be restated.<br>
> Clang promises to make that possible for C++.  It's one of the reasons<br>
> I'm interested.<br>
><br>
> Regards,<br>
><br>
> --jkl<br>
> _______________________________________________<br>
> cfe-dev mailing list<br>
> <a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
> <a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br>
<br>
<br>
<br>
<br>
<br>_______________________________________________<br>
cfe-dev mailing list<br>
<a href="mailto:cfe-dev@cs.uiuc.edu">cfe-dev@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev</a><br>
<br></blockquote></div><br></div>