Completed documentation for pre-release software is not the same thing as draft documentation.
Drafts are unfinished versions of a book or article, and their unfinished state is unrelated to the status of the software they document.
In both circumstances, however, it is important to make the status of the software, documentation or both clear to users, developers, readers and reviewers.
Documentation for pre-release software, especially pre-release software being distributed to testers, customers and partners, should carry a clear mark denoting the beta-status of the software.
To create that mark do the following:
Add the software's pre-release version number, or equivalent state information, to the <subtitle>
tag in your Book_Info.xml
file. Place this additional text in <remark>
tags. For example:
<subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
add show_remarks
to the publican.cfg
file and set it to '1':
show_remarks: 1
When you build your book with this <remark>
tag and the show_remarks
setting in place, the pre-release nature of the software is displayed clearly and unmistakably. PDF builds display the remark on their cover and title pages. HTML builds (both single-page HTML and multiple-page HTML) display the remark near the beginning of index.html
.
Because this approach makes no changes to the information in Book_Info.xml
used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.
Example 4.7. An example of an inline remark
Here is an example of an inline remark.
It is the writer's responsibility to remove the <remark>
tag and its contents and remove or turn off show_remarks
when documentation is updated for use with the release version of the software.
Unfinished documentation made available to others for review should be labeled clearly as such.
To add the draft watermark to your documentation add the status="draft"
attribute to the <article>
, <book>
or <set>
tag in your document's root node. For example:
<book status="draft">
By default, your root node is the <book>
tag in your Doc_Name.xml
file.
If you are working on an article or set, the root node is the <article>
or <set>
tag in Doc_Name.xml
.
Adding the status="draft"
attribute causes each page of the document to show the draft watermark. This is by design.
Even if you change only a portion of a work before sending it out for review, marking every page as draft will encourage reviewers to report errors or typos they spot in passing. It will also ensure non-reviewers who encounter the work do not mistake a draft for a finished version.
Example 4.8. An example of a block marked up as draft
This is an example of a block that is marked as draft
Isn't it pretty!
To denote unfinished documentation of pre-release software properly, do both previously noted procedures.
DocBook allows setting the revisionflag
on many elements to allow easier reviewing on changed documents. Publican, as of version 4.1, will add highlighting to these elements if the book is in draft mode. e.g. revisionflag="added"
This is how an element that has been added to a new revision is marked-up.
This is how an element that has been changed in a new revision is marked-up.
This is how an element that has been marked for deletion from a new revision is marked-up. Publican will not automatically delete or hide this content, you have to ensure this is done before publication.