Using the status attribute

Using the status attribute
	Chapter 29. Revision control

The status attribute is available on all hierarchical elements, from set and book down to section and refentry. It is generally used to indicate the current status of production for an element, such as whether it is in draft, edited, or final state. But you can use it for any kind of status that you want. This attribute can take any text value, so you might want to decide on a few enumerated values and use those consistently. You could also customize the DTD to change the attribute declaration to your set of enumerated values.

You can use the status attribute in several ways:

Profile a document on the status attribute. See the section “Profiling on status”.
Highlight parts of a document. See the section “Highlighting status”.
Control the draft page markings, as described in the the section “Draft mode”.

Keep in mind that status attributes can get out of date, so if you use them, be prepared to spend the time to maintain them.

Profiling on status

The status attribute is one that the DocBook stylesheets support for profiling (conditional text). You might need to do such profiling to produce different versions of a document. For example, while a document is under development, you may want to include unfinished sections for reviewers, but exclude them for customers. If the unfinished sections all have a status="draft" attribute, then you can profile them out for the customer version.

To include all content marked with status="draft", run the profiling process while setting the stylesheet parameter profile.status to draft. That will include any elements with status="draft" or no status attribute, and exclude those elements with any other value of status.

You might also set the draft.mode parameter to maybe, which will mark as draft only those sections with the draft attribute. See the section “Draft mode” for more information.

When you want to exclude draft sections to produce the non-draft version, then set the profile.status parameter to any other value (except blank). That will deselect all the content marked with status="draft".

Highlighting status

Although setting the draft.mode parameter to maybe will print a background image, this method has limitations. For print output, it puts the background image on the body region of the page-master, which means all the pages in a page-sequence will have the background image. Also, it only works for a value of status="draft", not other attribute values.

For finer control, more attribute values, and different presentation, you can customize the stylesheets. For example, you may want to show elements in different colors for different status values. The following customization works in print output:

Example 29.1. Highlighting status attributes with color

<xsl:param name="enable.status.coloring">1</xsl:param> 

<xsl:template name="set.status.color"> 
  <xsl:param name="node" select="."/>
  <xsl:choose>
    <xsl:when test="$enable.status.coloring = 0">inherit</xsl:when>  
    <xsl:when test="$node/@status = 'deleted'">#EEEEEE</xsl:when>  
    <xsl:when test="$node/@status = 'reviewed'">green</xsl:when>
    <xsl:when test="$node/@status = 'draft'">blue</xsl:when>
    <xsl:otherwise>inherit</xsl:otherwise>  
  </xsl:choose>
</xsl:template>

<xsl:attribute-set name="section.properties">  
  <xsl:attribute name="color">
    <xsl:call-template name="set.status.color"/>  
  </xsl:attribute>
</xsl:attribute-set>

<xsl:template name="set.flow.properties">  
  <xsl:param name="element" select="local-name(.)"/>
  <xsl:param name="master-reference" select="''"/>

  <xsl:attribute name="color">
    <xsl:call-template name="set.status.color"/>
  </xsl:attribute>
  ...

	Create a new stylesheet parameter so you can turn the status coloring on and off from the command line.
	Create a template that returns a color value based on the value of the `status` attribute.
	Skip the color choices if the coloring parameter is turned off.
	Select a color based on the value of the `status` attribute.
	Be sure to include `inherit` as a default value to avoid empty attribute errors.
	Add a `color` attribute in the `section.properties` attribute-set, which is used by sections at all levels.
	Call the color choice template. The attribute-set is processed each time it is used, so the template will be called for each section element.
	The `set.flow.properties` template can set a property on an entire page-sequence, such as for `chapter`, `appendix`, or other components.

For HTML output, a different approach using CSS works best. You can create a customization of templates using mode="class.value" to create new class values for different values of status (this mode is first available in version 1.72 of the stylesheets).

The following example customizes the original template in html/html.xsl to append the status value to the element name to form a class value:

<xsl:template match="*" mode="class.value">
  <xsl:param name="class" select="local-name(.)"/>
  <!-- permit customization of class value only -->
  <!-- Use element name by default -->
  <xsl:value-of select="$class"/>
  <xsl:if test="@status">
    <xsl:value-of select="concat('-', @status)"/>
  </xsl:if>
</xsl:template>

For each section element with status="deleted", this will generate a class="section-deleted" attribute on its div element. Then you can add a CSS selector to your CSS stylesheet to color the element:

div.section-deleted {
  color: #EEEEEE;
}

You can add other CSS selectors and properties for other combinations of element name and status value. Since this is a mode, you can also create custom templates that match on specific elements to customize the class value per element.


Draft mode		Highlighting changes