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.attributes
Docbook 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.
From ded965fc90b223a834ac52d55512587b7a6ea139 Mon Sep 17 00:00:00 2001
From: Corey Huinker <corey@paribus.co>
Date: Fri, 18 Oct 2019 06:15:10 -0400
Subject: [PATCH] add document change badges
---
doc/src/sgml/acronyms.sgml | 6 +++---
doc/src/sgml/stylesheet-html-common.xsl | 10 ++++++++++
doc/src/sgml/stylesheet.css | 10 ++++++++++
3 files changed, 23 insertions(+), 3 deletions(-)
diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index f638665dc9..87bfef04be 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -10,7 +10,7 @@
<variablelist>
<varlistentry>
- <term><acronym>ANSI</acronym></term>
+ <term revision="test badge on term"><acronym>ANSI</acronym></term>
<listitem>
<para>
<ulink url="https://en.wikipedia.org/wiki/American_National_Standards_Institute";>
@@ -19,7 +19,7 @@
</listitem>
</varlistentry>
- <varlistentry>
+ <varlistentry revision="v15 on varlistentry">
<term><acronym>API</acronym></term>
<listitem>
<para>
@@ -31,7 +31,7 @@
<varlistentry>
<term><acronym>ASCII</acronym></term>
<listitem>
- <para>
+ <para revision="badge on para">
<ulink url="https://en.wikipedia.org/wiki/Ascii";>American Standard
Code for Information Interchange</ulink>
</para>
diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl
index 9edce52a10..cb04cb7f0d 100644
--- a/doc/src/sgml/stylesheet-html-common.xsl
+++ b/doc/src/sgml/stylesheet-html-common.xsl
@@ -289,4 +289,14 @@ set toc,title
</xsl:choose>
</xsl:template>
+<!--<xsl:template name="revision.badge">-->
+<xsl:template match="//*[@revision]">
+ <xsl:param name="node" select="."/>
+ <xsl:variable name="revision" as="xs:string?" select="$node/@revision"/>
+ <xsl:if test="$revision">
+ <span class="revision-badge"><xsl:value-of select="$revision"/></span>
+ </xsl:if>
+ <xsl:apply-templates/>
+</xsl:template>
+
</xsl:stylesheet>
diff --git a/doc/src/sgml/stylesheet.css b/doc/src/sgml/stylesheet.css
index 1a66c789d5..d0cae2f59f 100644
--- a/doc/src/sgml/stylesheet.css
+++ b/doc/src/sgml/stylesheet.css
@@ -109,3 +109,13 @@ acronym { font-style: inherit; }
width: 75%;
}
}
+
+/* version badge styling */
+span.revision-badge {
+ visibility: visible ;
+ color: white;
+ background-color: #00933C;
+ border: 1px solid #000000;
+ border-radius: 2px;
+ padding: 1px;
+}
--
2.14.1
