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

[John McCall]

On Dec 18, 2012, at 9:11 AM, Jordan Rose <jordan_rose at apple.com> wrote:
> 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.

The standard's online;  my thinking was that they can link to the appropriate
section as part of the citation.

I would prefer that the names not show up in the user-visible document.

John.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20121218/777423ee/attachment.html>