Open Stack

On 05/28/2014 04:04 PM, Anne Gentle wrote:
> Here's what I'll update in the Documentation/Conventions page if
> everyone agrees:
> 
> For file names, use bk_ ch_ and sec_ at the beginning of the file name
> to indicate the type of file it is in the hierarchy of the build. For
> further organization, you can use subdirectories to organize the files
> by a particular grouping such as project or topic.
> 
> For xml:id creation, follow these guidelines. 
>  - xml:id must be unique across a built deliverable, otherwise you get
> build errors
>  - xml:id creates the HTML file name so it should be human-readable, not
> codified like the file name
>  - xml:id should closely follow the actual title in the text, using
> dashes for spaces
>  - xml:id creation should consider search and find-ability as well as
> human-readability
> 
> I prefer not to document the use a processing instruction like <?dbhtml
> filename="name"> as that should be the rare exception.

I've added a section now to the conventions page for this:
https://wiki.openstack.org/wiki/Documentation/Conventions#Source_file_names_and_xml:id_creation

I used "section_" instead of "sec_" since that's our current usage,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126