Open Stack

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.

Thanks,
Anne


On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com> wrote:

> My concern on this is that it raises a barrier to entry for contributors.
>  It's not intuitive.  As a fix in an emergency, sure.  But I'd be concerned
> about building this out as the standard way we do things.
>
> ----  Nick
>
>
> On Mon, May 26, 2014 at 11:43 AM, David Cramer <david.cramer at rackspace.com
> > wrote:
>
>> On 5/26/14, 10:07 AM, Nick Chase wrote:
>> > Plus my concern in changing Id values is breaking any references.
>>
>> You can reduce (but not eliminate) the impact of a file name change by
>> changing the file names via a processing instruction:
>>
>> <section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>...
>>
>> If you use <?dbhtml filename="..."?> you'll get the aesthetically
>> pleasing intro.html file name without having to change the xml:id and
>> break xrefs to the section. However, if you have external links to
>> some-dumb-id.html from other documents, those links would obviously break.
>>
>> Regardless of the publishing tool chain, when changing the names of
>> existing resources on the web, the best approach is to add 301 redirects
>> to avoid breaking bookmarks, links, and losing SEO karma.
>>
>> Regards,
>> David
>>
>>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140528/d517f9c0/attachment.html>