1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
]>
<section id="sect-Users_Guide-Pre_release_software_and_draft_documentation">
<title>Pre-release software and draft documentation</title>
<para>
Completed documentation for pre-release software is not the same thing as draft documentation.
</para>
<para>
Drafts are unfinished versions of a book or article, and their unfinished state is unrelated to the status of the software they document.
</para>
<para>
In both circumstances, however, it is important to make the status of the software, documentation or both clear to users, developers, readers and reviewers.
</para>
<section id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">
<title>Denoting pre-release software</title>
<para>
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.
</para>
<para>
To create that mark do the following:
</para>
<procedure>
<step>
<para>
Add the software's pre-release version number, or equivalent state information, to the subtitle in your <filename>Book_Info.xml</filename> file. Place this additional text in <sgmltag><remark></sgmltag> tags. For example:
</para>
<programlisting language="XML"><subtitle>Using Red Hat Enterprise Warp Drive<remark> Version 1.1, Beta 2</remark></subtitle>
</programlisting>
</step>
<step>
<para>
add <varname>show_remarks</varname> to the <filename>publican.cfg</filename> file and set it to '1':
</para>
<programlisting>show_remarks: 1
</programlisting>
</step>
</procedure>
<para>
When you build your book with this <sgmltag><remark></sgmltag> tag and the <varname>show_remarks</varname> 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 <filename>index.html</filename>.
</para>
<para>
Because this approach makes no changes to the information in <filename>Book_Info.xml</filename> used to generate RPMs, it also ensures there is no ambiguity in the RPM subsystem's operation.
</para>
<important>
<title>Important</title>
<para>
It is the writer's responsibility to remove the <sgmltag><remark></sgmltag> tag and its contents and remove or turn off <varname>show_remarks</varname> when documentation is updated for use with the release version of the software.
</para>
</important>
</section>
<section id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">
<title>Denoting draft documentation</title>
<para>
Unfinished documentation made available to others for review should be labeled clearly as such.
</para>
<procedure>
<step>
<para>
To add the draft watermark to your documentation add the <userinput>status="draft"</userinput> attribute to the <sgmltag><article></sgmltag>, <sgmltag><book></sgmltag> or <sgmltag><set></sgmltag> tag in your document's root node. For example:
</para>
<programlisting language="XML"><book status="draft">
</programlisting>
</step>
</procedure>
<para>
By default, your root node is the <sgmltag><book></sgmltag> tag in your <filename><replaceable>Doc_Name</replaceable>.xml</filename> file.
</para>
<para>
If you are working on an article or set, the root node is the <sgmltag><article></sgmltag> or <sgmltag><set></sgmltag> tag in <filename><replaceable>Doc_Name</replaceable>.xml</filename>.
</para>
<para>
Adding the <userinput>status="draft"</userinput> attribute causes each page of the document to show the draft watermark. This is by design.
</para>
<para>
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.
</para>
</section>
<section id="sect-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">
<title>Denoting draft documentation of pre-release software</title>
<para>
To denote unfinished documentation of pre-release software properly, do both previously noted procedures.
</para>
</section>
</section>
|
