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
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section [
<!ENTITY % BOOK_ENTITIES SYSTEM "Users_Guide.ent">
%BOOK_ENTITIES;
<!ENTITY % sgml.features "IGNORE">
<!ENTITY % xml.features "INCLUDE">
<!ENTITY % DOCBOOK_ENTS PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN" "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
%DOCBOOK_ENTS;
]>
<section conformance="140" version="5.0" xml:id="sect-Publican-Users_Guide-Pre_release_software_and_draft_documentation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info>
<title>Pre-release software and draft documentation</title>
</info>
<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 conformance="141" xml:id="sect-Publican-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_pre_release_software">
<info>
<title>Denoting pre-release software</title>
</info>
<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 <tag><subtitle></tag> tag in your <filename>Book_Info.xml</filename> file. Place this additional text in <tag><remark></tag> 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 <tag><remark></tag> 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>
<example>
<title>An example of an inline remark</title>
<para>
Here is an <application role="remark">example</application> of an inline remark.
</para>
</example>
<important>
<info>
<title>Important</title>
</info>
<para>
It is the writer's responsibility to remove the <tag><remark></tag> 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 conformance="142" xml:id="sect-Publican-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation">
<info>
<title>Denoting draft documentation</title>
</info>
<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 <tag><article></tag>, <tag><book></tag> or <tag><set></tag> 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 <tag><book></tag> 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 <tag><article></tag> or <tag><set></tag> 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>
<example>
<title>An example of a block marked up as draft</title>
<literallayout role="draft">This is an example of a block that is marked as draft
Isn't it pretty!
</literallayout>
</example>
</section>
<section conformance="143" xml:id="sect-Publican-Users_Guide-Pre_release_software_and_draft_documentation-Denoting_draft_documentation_of_pre_release_software">
<info>
<title>Denoting draft documentation of pre-release software</title>
</info>
<para>
To denote unfinished documentation of pre-release software properly, do both previously noted procedures.
</para>
</section>
<section>
<info>
<title>Denoting changed content <remark>New section</remark>
</title>
</info>
<para revisionflag="added">
DocBook allows setting the <tag>revisionflag</tag> on many elements to allow easier reviewing on changed documents. <application>Publican</application>, as of version 4.1, will add highlighting to these elements if the book is in draft mode. e.g. <userinput>revisionflag="added"</userinput> <variablelist>
<varlistentry>
<term>added</term>
<listitem>
<para role="added">
This is how an element that has been added to a new revision is marked-up.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>changed</term>
<listitem>
<para role="changed">
This is how an element that has been changed in a new revision is marked-up.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>deleted</term>
<listitem>
<para role="deleted">
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.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
</section>
|
