In the past, we used to document changes of the document itself in an appendix (so called "changelog"). However, this has some issues:
The appendix is usually at the end and people can miss that
It adds an additional entry in the table of content. This may or may not be wanted.
An appendix can contain anything, so the structure tend to be inconsistent with other docs.
An appendix is maybe not something we want in a Smart Doc.
To streamline and make it consistent with other docs, <revhistory> is the traditional way in DocBook to add changes.
Benefits
Could be used for a "latest changes" for the upcoming doc portal
With the parameters, it can be flexible. Depending on the documents you can enable or disable this feature
Structure is more consistent than an appendix. Parsing with XSLT it is easier.
Is not be added in the TOC (although this could be considered "bad" as it can be easily missed)
Possible solutions
Once it is enabled, the revision history can be displayed in two ways:
Put everything in a separate file
On the title page of the document, a "Revision History" link is displayed (see section "Proof of concept" below).
Put it on the title page and make it collapsable
By default, all entries are hidden under a title "Revision History" (similar like the previous case). However, once the user click it, the title expands and reveals the entries therein. Through parameters, the number of entries can be limited.
Implementation
The stylesheet of version 2.92.7 doesn't support (yet) <revhistory> tags. I've tried it out for the style guide and these are the things that needs to be changed/added:
[x] Set generate.revhistory.link=1
This generates a separate file that is linked from the title page. Although you can use a revision history without setting this parameter, the title page becomes crowded the more entries you have. Not recommended.
[x] Create additional parameter generate.revhistory
This parameter is used to enable/disable revhistory generation completely. Can be helpful if we want to be flexible and enable it in one doc and disable it in another.
[x] Integrate <revhistory> in title page
Integrate the tag into book and article pages (regardless if it's all on the title page or in a separate file).
[x] Style the revhistory link of the title page
It's there, but it isn't really visually distinctive. Maybe we need to add more space, color it differently etc.?
[x] Style the separate revhistory file
When you set generate.revhistory.link=1, the stylesheets create a separate file. However, this separate file does not really contain much styling. Maybe it's not that much needed, but it looks a bit meager.
[x] Add parameter revhistory.number and revistory.method
Cut X entries from revhistory. The method can be distinguish between number and date.
[x] Use parameter use.revhistory to enable/disable revhistory generation.
[x] Propagate it through the style guide
Encourage writers to use <revhistory> where appropriate and share best practices.
Proof of concept
First POC in SUSE/doc-styleguide#268
After the user clicks the link, the following page is shown:
Background
This came up in a 1:1 session with @dariavladykina.
Problem Description
In the past, we used to document changes of the document itself in an appendix (so called "changelog"). However, this has some issues:
To streamline and make it consistent with other docs,
<revhistory>is the traditional way in DocBook to add changes.Benefits
Possible solutions
Once it is enabled, the revision history can be displayed in two ways:
Put everything in a separate file On the title page of the document, a "Revision History" link is displayed (see section "Proof of concept" below).
Put it on the title page and make it collapsable By default, all entries are hidden under a title "Revision History" (similar like the previous case). However, once the user click it, the title expands and reveals the entries therein. Through parameters, the number of entries can be limited.
Implementation
The stylesheet of version 2.92.7 doesn't support (yet)
<revhistory>tags. I've tried it out for the style guide and these are the things that needs to be changed/added:[x] Set
generate.revhistory.link=1This generates a separate file that is linked from the title page. Although you can use a revision history without setting this parameter, the title page becomes crowded the more entries you have. Not recommended.[x] Create additional parameter
generate.revhistoryThis parameter is used to enable/disable revhistory generation completely. Can be helpful if we want to be flexible and enable it in one doc and disable it in another.[x] Integrate
<revhistory>in title page Integrate the tag into book and article pages (regardless if it's all on the title page or in a separate file).[x] Style the revhistory link of the title page It's there, but it isn't really visually distinctive. Maybe we need to add more space, color it differently etc.?
[x] Style the separate revhistory file When you set
generate.revhistory.link=1, the stylesheets create a separate file. However, this separate file does not really contain much styling. Maybe it's not that much needed, but it looks a bit meager.[x] Add parameter
revhistory.numberandrevistory.methodCut X entries from revhistory. The method can be distinguish betweennumberanddate.[x] Use parameter
use.revhistoryto enable/disable revhistory generation.[x] Propagate it through the style guide Encourage writers to use
<revhistory>where appropriate and share best practices.Proof of concept
First POC in SUSE/doc-styleguide#268
After the user clicks the link, the following page is shown:
Background
This came up in a 1:1 session with @dariavladykina.