[publican-list] Proposed changes to Book_Info.xml

[Jeff Fearn]

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
>>>
>>> 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.

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

Cheers, Jeff.

-- 
Jeff Fearn <jfearn at redhat.com>
Software Engineer
Engineering Operations
Red Hat, Inc