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

[John McCall]

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.

John.