[cfe-commits] r170132 - in /cfe/trunk/docs: AutomaticReferenceCounting.html AutomaticReferenceCounting.rst

[Jordan Rose]

On Dec 17, 2012, at 18:41 , John McCall <rjmccall at apple.com> wrote:

> On Dec 16, 2012, at 3:32 AM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
>> On Sun, Dec 16, 2012 at 2:38 AM, Sean Silva <silvas at purdue.edu> wrote:
>>> This completely breaks the front page toctree structure since each of
>>> the "sections" of this document appear as top-level entities there (I
>>> already fixed it to use the correct adornments in r170278.
>>> 
>>> My recommendation is to show the title with over+under ====== instead
>>> of '.. title::', kill the `.. sectnum::` , and explicitly show the
>>> `[foo.bar]` "human-readable" section names in the section titles.
>>> Automatic numbering is extremely brittle anyway (from the perspective
>>> of citing the document) since adding or removing a section will change
>>> all the numbers (that's why the "human readable" identification
>>> exists, I presume). Maybe add the section numbering back with some JS
>>> like the original document did or with CSS
>>> (<http://dev.opera.com/articles/view/automatic-numbering-with-css-counters/>).
>> 
>> CSS section numbering introduced in r170283, thanks for the idea!
>> 
>> @John:
>> The ARC document contains human-readable section names (like
>> meta.purpose, objects.operands.consumed etc.)  Is it OK to put them at
>> the end of section titles?
> 
> The intent is for them to be stable links.  I don't see much purpose
> in otherwise exposing them to users.

Citation, a la the C++ standard? I can understand if we don't care in this case (the ARC document is much more compact, and the paragraphs aren't numbered), but it's not as if there's no use.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20121218/c5069769/attachment.html>