openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

Indexing means several things:

1. A Table of contents list for each chapter or book or section

2. Headings with military-style numbered headings as unique
identifiers such as 4.3.1.

3. An index of keywords with page number references at the back of a
traditional print or PDF book

Based on your examples I'm going to say you mean 2 but let me know if
you mean 1. An index like 3 is useful but not what you are asking for
I believe.

I have had many conversations about heading numbering styles. Our
current approach is to have numbered headings for API docs but not for
Admin docs. I currently prefer non-numbered heading styles for
web-based deliverables written with modular information that can be
re-used in more than one context, as we need to do.

For referring to specific sections for doc bugs, please use the full
URL as the identifier. Each section in the document has an xml:id that
uniquely identifies it for reference purposes (and for maintaining doc
comments with the correct page). I much prefer an HTML reference to
the docs rather than PDF page numbers or numbered headings for
sections.

Thanks,
Anne

P.S.

If you prefer to output PDFs with numbered heading styles for your
use, modify the pom.xml.

Change these lines:
<!-- The following elements sets the autonumbering of sections in
output for chapter numbers but no numbered sections-->
                            <sectionAutolabel>0</sectionAutolabel>

<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>

To this:

<!-- The following elements sets the autonumbering of sections in
output for chapter numbers but no numbered sections-->
                            <!--<sectionAutolabel>0</sectionAutolabel>

<sectionLabelIncludesComponentLabel>0</sectionLabelIncludesComponentLabel>-->

In other words, comment out the sectionAutolabel and
sectionLabelIncludesComponentLabel elements.

On Mon, Feb 27, 2012 at 9:46 AM, Alexey Eromenko <al4321@xxxxxxxxx> wrote:
> As the OpenStack documentation becomes increasingly complex,
> I would like to introduce indexing there.
>
> Currently only major chapters have indeces, while *all* sub-chapters do not.
> Lack of indexing makes it difficult to open specific bugs, and
> difficult to share specific configuration settings on IRC.
>
> Currently it looks like: (tested both HTML and PDF versions)
>
> Chapter 7. Networking
> Configuring Networking on the Compute Node->
> Configuring Flat DHCP Networking
>
> OpenStack docs should look like:
>
> Chapter 7. Networking
> 7.3. Configuring Networking on the Compute Node->
> 7.3.2 Configuring Flat DHCP Networking
>
> How-to patch the docs to introduce multi-level indexing ?
>
> --
> -Alexey Eromenko "Technologov"
>
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp