[publican-list] Proposed changes to Book_Info.xml

[Paul W. Frields]

On Tue, 2008-08-05 at 21:49 +1000, David O'Brien wrote:
> Jeff Fearn wrote:
> > A bug has been raised about how the titles currently differ between 
> > the HTML and PDF outputs, this has lead to a review to the way the 
> > Book_Info.xml files are structured.
> >
> > https://bugzilla.redhat.com/show_bug.cgi?id=456497
> >
> > Currently the usage is:
> >
> > title: the name of the Product the book is about.
> > subtitle: the actual title of the book.
> > issuenum: the version of the Product the book is about.
> > productnumber: the release of the book for this Product version.
> >
> > This is somewhat confusing and I'd like to change it to:
> >
> > productname: the name of the product this book is about.
> > productnumber: the version of the product this book is about.
> > pubsnumber: the release of this book for this products version. (Only 
> > used for rpm)
> > title: the title of this book.
> > subtitle: a secondary title for this book.
> >
> > This would then lead to a restructuring of the way the titles are 
> > displayed.
> >
> > The cover page display would be:
> >
> > Top of page centered, font size 2em, colored block: ProductName 
> > ProductVersion
> > Below that block, centered, font size 2em: BookTitle
> > Below that, centered, font size 1.8em: BookSubTitle
> >
> > The centering is because the current layout makes it hard to separate 
> > the titles from the content, this small changes highlights the titles 
> > and brings the HTML and PDF in to alignment.
> >
> > No feedback means I am right and should proceed however I want :D
> >
> > Cheers, Jeff.
> >
> Mostly that looks fine to me, but not 100% sure about the pubsnumber. 
> Why would you only use that for the rpm? If you provide updates to the 
> original release of a manual, but where there are no changes to the 
> product, how is this indicated? Only in the Revision History? Can we not 
> provide something more obvious?
> 
> I admit to not spending much time looking at the final output, though, 
> such as size and placement of titles, etc.; that's not my "forte".  ^^
> 
> Any thoughts on whether we should effect any changes to RH entity names 
> at the same time? A bit more work involved, to be sure, but I always 
> like to raise the consistency questions. We have a bit of a mixture at 
> present. Some that I use look like:
> <!ENTITY TITLE "Installation and Deployment Guide">
> <!ENTITY PRODUCT "Red_Hat_Enterprise_IPA">
> <!ENTITY PRODNAME "Red Hat Enterprise IPA">
> <!ENTITY VER "1.0">
> <!ENTITY PRODVER "&PRODNAME; &VER;">
> <!ENTITY FULLTITLE "<citetitle>&PRODNAME; &TITLE;</citetitle>">
> 
> I bet Jeff's next salary that every other non-IPA .ent file is different :-)

How does this affect books which are about a nonversioned (i.e. generic
platform) feature?  An example that comes to mind is the Fedora
Documentation Guide, which doesn't map one-to-one to a product.

-- 
Paul W. Frields
  gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233  5906 ACDB C937 BD11 3717
  http://paul.frields.org/   -  -   http://pfrields.fedorapeople.org/
  irc.freenode.net: stickster @ #fedora-docs, #fedora-devel, #fredlug
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/publican-list/attachments/20080805/337f12dc/attachment.sig>