[publican-list] Proposed changes to Book_Info.xml

[Paul W. Frields]

On Wed, 2008-08-06 at 15:17 +1000, Jeff Fearn wrote:
> Paul W. Frields wrote:
> > 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
> >>>
> >> 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.
> 
> This field is currently mandatory, so we'd have to add an exception
> for this practice.
> 
> The output would just skip the version, since XSL is tolerant that
> way.
> 
> The RPMs require this field, so you would not be able to create
> desktop RPMs with such a book.
> 
> We could probably hack in a way to have the version in the Makefile
> instead of the Book_Info.xml. I've been trying to keep as much in the
> xml files as I can to avoid having writers edit the makefile, since I
> get lots of flack every time I make them do that :D

I can definitely understand not wanting people to do this in the
Makefile.  Maybe I'm misunderstanding the usage -- if pubsnumber maps to
a revision of the publication (i.e. Documentation Guide 0.5), and the
version of the product is missing (which in the example is the case),
does the new usage fit properly?

-- 
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/20080806/39416a25/attachment.sig>