[Openstack-docs] Conventions for filenames and chapter/section IDs
Anne Gentle
anne at openstack.org
Wed May 28 14:20:00 UTC 2014
On Wed, May 28, 2014 at 9:10 AM, Diane Fleming
<diane.fleming at rackspace.com>wrote:
> That looks good.
>
> My only change would be that sections should be section_*, only because
> that's how most of them are named at the moment so it would save a lot of
> work to keep what we already have.
>
Ha, oops, I should have known that, sorry.
>
> I have also used created other files for content sharing, such as
> itemized lists or tables. I usually prefix the file name with the object
> type in the file.
>
>
itemizedlist_service_list.xml (for example)
> table_server_status.xml
>
>
Makes sense. The table_prefix is very helpful.
> Oh, and for prefaces, I just use
>
> preface.xml
>
>
Ok, I'll note in the wiki page. Thanks!
>
> *Diane*
> *----------------------------------------------*
> Diane Fleming
> Software Developer II - US
> diane.fleming at rackspace.com
> Cell 512.323.6799
> Office 512.874.1260
> Skype drfleming0227
> Google-plus diane.fleming at gmail.com
>
> From: Anne Gentle <anne at openstack.org>
> Date: Wednesday, May 28, 2014 9:04 AM
>
> To: Nick Chase <nchase at mirantis.com>
> Cc: Andreas Jaeger <aj at suse.com>, "openstack-docs at lists.openstack.org" <
> openstack-docs at lists.openstack.org>
> Subject: Re: [Openstack-docs] Conventions for filenames and
> chapter/section IDs
>
> 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/b76bd876/attachment.html>
More information about the Openstack-docs
mailing list