[publican-list] Proposed changes to Book_Info.xml

[Jeff Fearn]

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?

Just to come back to pubsnumber, I don't think it would be useful as a visual indication that a book has changed. Having 2 numbers on the cover page may be confusing.

I think a better way of doing this would be to set a publishing date, either in the xml, or as I prefer in the build process, to indicate when the book was last built. People will grok that a new publication date may mean things have been updated.

Another way would be to grab the latest revision number from the Revision_History file and not use pubsnumber at all.

Then we could add 'Revision: "??"' to the cover pages.

Cheers, Jeff.

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