Attached is a patch to implement change badges in our documentation.
What's a change badge? It's my term for a visual cue in the documentation used to indicate that the nearby section of documentation is new in this version or otherwise changed from the previous version.
One example of change badges being used is in the DocBook documentation reference:
https://tdg.docbook.org/tdg/4.5/ref-elements.html#common.attributesDocbook used graphical badges, which seemed to be a bad idea. Instead, I went with a decorated text span like one finds in gmail labels or Reddit "flair".
The badges are implemented via using the "revision" attribute available on all docbook tags. All one needs to do to indicate a change is to change one tag, and add a revision attribute. For example:
<varlistentry revision="new in 13">
will add a small green text box with the tex "new in 13" immediately preceding the rendered elements. I have attached a screenshot (badges_in_acronyms.png) of an example of this from my browser viewing changes to the acronyms.html file. This obviously lacks the polish of viewing the page on a full website, but it does give you an idea of the flexibility of the change badge, and where badge placement is (and is not) a good idea.
What are the benefits of using this?
I think the benefits are as follows:
1. It shows a casual user what pieces are new on that page (new functions, new keywords, new command options, etc).
2. It also works in the negative: a user can quickly skim a page, and lacking any badges, feel confident that everything there works in the way that it did in version N-1.
3. It also acts as a subtle cue for the user to click on the previous version to see what it used to look like, confident that there will be a difference on the previous version.
How would we implement this?
1. All new documentation pages would get a "NEW" badge in their title.
2. New function definitions, new command options, etc would get a "NEW" badge as visually close to the change as is practical.
3. Changes to existing functions, options, etc. would get a badge of "UPDATED"
4. At major release time, we could do one of two things:
4a. We could keep the NEW/UPDATED badges in the fixed release version, and then completely remove them from the master, because for version N+1, they won't be new anymore. This can be accomplished with an XSL transform looking for any tag with the "revision" attribute
4b. We could code in the version number at release time, and leave it in place. So in version 14 you could find both "v13" and "v14" badges, and in version 15 you could find badges for 15, 14, and 13. At some point (say v17), we start retiring the v13 badges, and in v18 we'd retire the v14 badges, and so on, to keep the clutter to a minimum.
Back to the patch:
I implemented this only for html output, and the colors I chose are very off-brand for postgres, so that will have to change. There's probably some spacing/padding issues I haven't thought of. Please try it out, make some modifications to existing document pages to see how badges would work in those contexts.
