Description of problem: OpenStack docs team wants to include the Rev number and the pubdate on the cover page of a doc in the following format: Revision 1.0-26, January 8 2014 The date and the rev number should be picked from the last entry in the Revision_History.xml file. This should also be just before the author group tag. Some of the other doc teams seem to be using edition tags instead. So if this change is included as a flag, it would be optional and only the teams that need this format can set the flag and make use of it.
Hi Deepti, without a rationale as to why you want this it is hard to give feedback. What you are describing seems to be the combination of the "edition" and "pubdate" tags. Have you tried them? Was there anything wrong with them? The revision history gets automatically updated when we do mass rebuilds, it's highly unlikely you'd want the cover material updated in those circumstances. "releaseinfo" is another tag that could be used, it's not standard to put such information before the author list though. The revision number used in translations is going to look bad, have you considered that?
(In reply to Jeff Fearn from comment #1) > Hi Deepti, without a rationale as to why you want this it is hard to give > feedback. OpenStack docs team wants to include dates to mark the different versions of the guides being published. So as a practice, we have been manually adding the date (https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Linux_OpenStack_Platform/4/html-single/Getting_Started_Guide/index.html). Most of the times, we do the packaging and while checking on docs-devel, realize that we have missed updating the date in Author_Group.xml file. So we have to repeat the whole process again. We wanted this to be automated so as to pick the latest date and edition number from the Revision_History.xml file. Summer and Rudi have had a conversation regarding the same and I was asked to raise bug to get a new flag option in Publican to include this information. > > What you are describing seems to be the combination of the "edition" and > "pubdate" tags. Have you tried them? Was there anything wrong with them? Yes, we have been adding the 'pubdate' manually for the last release, but we tend to forget to make this change and end up doing the process multiple times (on the release day) losing time. > > The revision history gets automatically updated when we do mass rebuilds, > it's highly unlikely you'd want the cover material updated in those > circumstances. We were thinking that this option would be a flag. So the date would be updated only on using the flag. So as long as the mass builds don't use the flags, we should be good. > > "releaseinfo" is another tag that could be used, it's not standard to put > such information before the author list though. Checked in different doc suites and looks like the edition or date is always before the author list. > > The revision number used in translations is going to look bad, have you > considered that? Is there a format that we can use that would not affect the translation? We are ok with modifying the format if it means this info in included. Also, the reason to have both date and the build number is that the whole team works on pretty much all the docs, as a result, sometimes there are multiple builds for a single doc within a day. Having both date and build makes it easier to point out the version to the tech or QE reviewers.
IMO we shouldn't be changing the cover material presented to users for development purposes. We could make this one of the effects of marking a document as draft. Maybe print the current revision and date in the footer of every page? If we want to do it this way then there may be other things it would be handy to have displayed/offered in draft mode?
We would never include the date programatically, because we need to mass rebuild docs when we make infrastructure changes. If we were to include dates programatically, we would end up misleading users about when a book was last updated. That is, a book that has perhaps not been updated in many years would carry a notice on its cover that suggests that it had been revised and reissued maybe just this week. I concur with Jeff that if this request is only of benefit for development, the cover is the wrong place to implement it. The suggested additions to draft mode are nice though!
Hi Jeff, Both devs and PMs have asked for a distinguishing mark on the front cover, so they don't have to troll through to the revision history, and this is requested for both drafts and final versions. A date is just obvious. pubdate only shows up on the second page, right above the Abstract. Is there a way to flag pubdate to make it appear on the front cover? thanks, Summer
(In reply to Summer Long from comment #5) > Hi Jeff, > Both devs and PMs have asked for a distinguishing mark on the front cover, > so they don't have to troll through to the revision history, and this is > requested for both drafts and final versions. A date is just obvious. The latest revision is at the top of the revision history, you click one link and it's there, you don't even need to scroll, let alone troll. > pubdate only shows up on the second page, right above the Abstract. > Is there a way to flag pubdate to make it appear on the front cover? > thanks, Summer For the HTML this can be changed in the brands XSL files and doesn't require a change to publican. For the PDF it requires a change to the data being sent to the cover template, then a brand will be able to override the cover template and add it.
Jeff, can you please pass any content of <releaseinfo> (if it exists) through to the PDF cover so that brands can style it? (basically the same way we handle <edition> right now)
(In reply to Ruediger Landmann from comment #7) > Jeff, can you please pass any content of <releaseinfo> (if it exists) > through to the PDF cover so that brands can style it? (basically the same > way we handle <edition> right now) Currently edition is displayed on the cover and on the first title page, do you want the same for releaseinfo?
Ah; so not quite how we handle <edition> then :) No, this should just appear on the cover. (Like you say, it's already redundant. We don't need to add redundant redundancy.)
Added support for releaseinfo tag. Duplicated all titlepage edition styles for this tag. Brands that change title colours or override the cover templates or titlepage XSL will need to be adjusted accordingly. To ssh://git.fedorahosted.org/git/publican.git 62b41f3..fec47f7 devel -> devel
A fix for this shipped in Publican 4.1.0.