[publican-list] Proposed changes to Book_Info.xml

[David O'Brien]

Jeff Fearn wrote:
> 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.
>
I don't mind the idea of using the build date. I actually prefer that to 
using the Revision History. Build dates (generally) don't lie, but 
writers are responsible for maintaining the Revision History file. I 
think I know which is more reliable  :)

-- 

David O'Brien
IPA Content Author
Red Hat Asia Pacific

"We couldn't care less about comfort. We make you feel good."
Federico Minoli CEO Ducati Motor S.p.A.