<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; color: rgb(0, 0, 0); font-size: 14px; font-family: Calibri, sans-serif; ">
<div>
<div>
<div>That looks good. </div>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>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. </div>
<div><br>
</div>
<div>itemizedlist_service_list.xml (for example)</div>
<div>table_server_status.xml</div>
<div><br>
</div>
<div>Oh, and for prefaces, I just use</div>
<div><br>
</div>
<div>preface.xml</div>
<div><br>
</div>
<div><br>
</div>
<div>
<div>
<div style="color: rgb(0, 0, 0); "><font class="Apple-style-span" color="rgb(0, 0, 0)" face="Apple Chancery"><i>Diane</i></font></div>
<div style="font-family: Calibri, sans-serif; font-size: 14px; color: rgb(0, 0, 0); ">
<font class="Apple-style-span" color="rgb(0, 0, 0)"><i>----------------------------------------------</i></font></div>
<div style="font-family: Calibri, sans-serif; font-size: 14px; color: rgb(0, 0, 0); ">
<font class="Apple-style-span" color="rgb(0, 0, 0)">Diane Fleming</font></div>
<div style="font-family: Calibri, sans-serif; font-size: 14px; ">
<div style="color: rgb(0, 0, 0); ">Software Developer II - US</div>
</div>
diane.fleming@rackspace.com</div>
<div>Cell 512.323.6799</div>
<div>Office 512.874.1260<br>
<span class="Apple-style-span" style="font-family: Calibri, sans-serif; ">
<div style="font-family: Calibri, sans-serif; font-size: 14px; ">
<div style="color: rgb(0, 0, 0); ">Skype drfleming0227</div>
<div style="color: rgb(0, 0, 0); ">Google-plus diane.fleming@gmail.com</div>
</div>
</span></div>
</div>
</div>
</div>
<div><br>
</div>
<span id="OLK_SRC_BODY_SECTION">
<div style="font-family:Lucida Grande; font-size:11pt; text-align:left; color:black; BORDER-BOTTOM: medium none; BORDER-LEFT: medium none; PADDING-BOTTOM: 0in; PADDING-LEFT: 0in; PADDING-RIGHT: 0in; BORDER-TOP: #b5c4df 1pt solid; BORDER-RIGHT: medium none; PADDING-TOP: 3pt">
<span style="font-weight:bold">From: </span>Anne Gentle <<a href="mailto:anne@openstack.org">anne@openstack.org</a>><br>
<span style="font-weight:bold">Date: </span>Wednesday, May 28, 2014 9:04 AM<br>
<span style="font-weight:bold">To: </span>Nick Chase <<a href="mailto:nchase@mirantis.com">nchase@mirantis.com</a>><br>
<span style="font-weight:bold">Cc: </span>Andreas Jaeger <<a href="mailto:aj@suse.com">aj@suse.com</a>>, "<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>" <<a href="mailto:openstack-docs@lists.openstack.org">openstack-docs@lists.openstack.org</a>><br>
<span style="font-weight:bold">Subject: </span>Re: [Openstack-docs] Conventions for filenames and chapter/section IDs<br>
</div>
<div><br>
</div>
<div>
<div>
<div dir="ltr">Here's what I'll update in the Documentation/Conventions page if everyone agrees:<br>
<div><br>
</div>
<div>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.</div>
<div><br>
</div>
<div>For xml:id creation, follow these guidelines. </div>
<div> - xml:id must be unique across a built deliverable, otherwise you get build errors</div>
<div> - xml:id creates the HTML file name so it should be human-readable, not codified like the file name</div>
<div> - xml:id should closely follow the actual title in the text, using dashes for spaces</div>
<div> - xml:id creation should consider search and find-ability as well as human-readability</div>
<div><br>
</div>
<div>I prefer not to document the use a processing instruction like <?dbhtml filename="name"> as that should be the rare exception.</div>
<div><br>
</div>
<div>Thanks,</div>
<div>Anne</div>
</div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Mon, May 26, 2014 at 11:13 AM, Nick Chase <span dir="ltr">
<<a href="mailto:nchase@mirantis.com" target="_blank">nchase@mirantis.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">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.<span class="HOEnZb"><font color="#888888">
<div><br>
</div>
<div>---- Nick</div>
</font></span></div>
<div class="HOEnZb">
<div class="h5">
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Mon, May 26, 2014 at 11:43 AM, David Cramer <span dir="ltr">
<<a href="mailto:david.cramer@rackspace.com" target="_blank">david.cramer@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div>On 5/26/14, 10:07 AM, Nick Chase wrote:<br>
> Plus my concern in changing Id values is breaking any references.<br>
<br>
</div>
You can reduce (but not eliminate) the impact of a file name change by<br>
changing the file names via a processing instruction:<br>
<br>
<section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>...<br>
<br>
If you use <?dbhtml filename="..."?> you'll get the aesthetically<br>
pleasing intro.html file name without having to change the xml:id and<br>
break xrefs to the section. However, if you have external links to<br>
some-dumb-id.html from other documents, those links would obviously break.<br>
<br>
Regardless of the publishing tool chain, when changing the names of<br>
existing resources on the web, the best approach is to add 301 redirects<br>
to avoid breaking bookmarks, links, and losing SEO karma.<br>
<br>
Regards,<br>
David<br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</div>
<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br>
</blockquote>
</div>
<br>
</div>
</div>
</div>
</span>
</body>
</html>