Open Stack

On Wed, May 28, 2014 at 11:59 AM, Andreas Jaeger <aj at suse.com> wrote:

> 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.
>
> Agreed (with using section as mentioned as followup)
>
> > 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
>
> I normally use underscores for spaces.
>

Ah, okay. I was thinking of Drupal/Wordpress convention and wondering if
one is preferred over the other for search optimization, anyone know?


>
> >  - 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.
> >
>
> Agreed, thanks,
>
> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/bc01b895/attachment.html>