Re: Changing the naming convention for Publican book files

[David Nalley <da...@gnsa.us>]

On Thu, Oct 4, 2012 at 3:09 PM, Jessica Tomechak
<Je...@citrix.com> wrote:
> David,
>
> I see in your recent commit that you’re changing the names of the main book
> files in the docs directory. For example, rather than cloudstack_admin.xml
> we would have Admin_Guide.xml. This is fine with me, if it makes life easier
> for users, but could you please (a) change docs/README.txt to that effect
> and (b) advise the mailing list?
>
>
>
> README.txt now contains a sentence about the naming convention for  book
> files starting with cloudstack_ . I picked that convention to make it easier
> to spot the files in the docs/ directory.
>


Moving this to -dev.

Sorry, didn't realize this was documented in readme.txt - I'll updated
the document.
The problem is that the document name in the publican .cfg file is the
name of the document in the table of contents in publican published
website, so something like "cloudstack_admin" looks like "cloudstack
admin" in the table of contents, which doesn't tell you if it's a
guide, a web UI, and fails the capitalization guidelines for literary
works. The word CloudStack is already heavily used on the site, and
the site is all about CloudStack, thus it's redundant, and there's a
limit on length anyway. So changing things like cloudstack_admin to
Admin_Guide deals with the problem. However, publican also uses the
document name and looks for a .xml and .ent to define the document -
so those file names had to match the name entry in the .cfg - and
hence the change. I'll update the README momentarily.

--David