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
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter [
<!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;
]>
<chapter conformance="212" version="5.0" xml:id="chap-Publican-Users_Guide-Using_sets" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<info>
<title>Using sets</title>
</info>
<para>
A <firstterm>set</firstterm> is a collection of books, published as a single output. The <citetitle>Services Plan</citetitle> for example is a set comprised of many books such as the <citetitle>Developer Guide</citetitle>, <citetitle>Engineering Content Services Guide</citetitle> and the <citetitle>Engineering Operations Guide</citetitle> to name just a few. The <prompt>$</prompt> <command>create_book</command> command creates a template for a set by setting the <parameter>type</parameter> parameter to <literal>Set</literal>.
</para>
<para>
There are two types of set:
</para>
<itemizedlist>
<listitem>
<para>
<firstterm>stand-alone sets</firstterm>
</para>
</listitem>
<listitem>
<para>
<firstterm>distributed sets</firstterm>
</para>
</listitem>
</itemizedlist>
<section conformance="213" xml:id="sect-Publican-Users_Guide-Using_sets-Stand_alone_sets">
<info>
<title>Stand-alone sets</title>
</info>
<para>
A stand-alone set contains the XML files for each book, all of which are located inside the directory of the set. Stand-alone sets are always built as a set; you cannot build the individual books on their own without modification.
</para>
<para>
The procedure that follows will guide you through the process of creating a stand-alone set named <citetitle>My Set</citetitle> located in a directory called <filename>books/My_Set/</filename>. The set will contain <citetitle>Book A</citetitle> and <citetitle>Book B</citetitle> both of which will be manually created inside the <filename>books/My_Set/en-US</filename> directory.
</para>
<procedure conformance="214" xml:id="proc-Publican-Users_Guide-Stand_alone_sets-Creating_a_stand_alone_set">
<title>Creating a stand-alone set</title>
<step>
<para>
Run the following command in a shell in the <filename>books/</filename> directory to create a set named <literal>My_Set</literal> branded in the Red Hat style and in which the XML will be written in American English.
</para>
<programlisting>publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US</programlisting>
</step>
<step>
<para>
<prompt>$</prompt> <command>cd</command> into the <filename>My_Set/en-US</filename> directory and create two <emphasis>directories</emphasis> (not books) called <filename>Book_A</filename> and <filename>Book_B</filename>.
</para>
<screen><prompt>$</prompt> <command>cd</command> <filename>My_Set/en-US</filename>
<prompt>$</prompt> <command>mkdir</command> <filename>Book_A</filename> <filename>Book_B</filename></screen>
</step>
<step>
<para>
<prompt>$</prompt> <command>cd</command> into the <filename>books/My_Set/en-US/Book_A</filename> directory. Create and edit the <filename>Book_A.xml</filename>, <filename>Book_Info.xml</filename>, and any other xml files required for your book such as those required for individual chapters. Ensure that <filename>Book_A.xml</filename> contains the correct <tag>xi:include</tag> references to all of your xml files in the directory. For example, if <citetitle>Book A</citetitle> contained <filename>Book_Info.xml</filename> and <filename>Chapter_1.xml</filename>, the <filename>Book_A.xml</filename> file would look like this:
</para>
<programlisting language="xml"><?xml version='1.0'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<book>
<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
<xi:include href="Chapter_1.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</book></programlisting>
</step>
<step>
<para>
Use the same process for <citetitle>Book_B</citetitle>, located in the <filename>books/My_Set/en-US/Book_B</filename> directory, as per the step above.
</para>
</step>
<step>
<para>
Open the <filename>books/My_Set/en-US/My_Set.xml</filename> file in an editor. For each book in the set, add an <tag>xi:include</tag> reference to the primary xml file from the book. The primary xml file for <citetitle>Book A</citetitle> will be <filename>Book_A.xml</filename> and for <citetitle>Book B</citetitle>, <filename>Book_B.xml</filename>. The <filename>My_Set.xml</filename> file should now look like this:
</para>
<programlisting language="XML"><xi:include href="extras/Set_Name.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</step>
<step>
<para>
To make your set XML valid, you will need to change the following:
</para>
<substeps>
<step>
<para>
In <filename>My_Set.xml</filename>, comment out the following lines:
</para>
<programlisting language="XML"><remark>NOTE: the href does not contain a language! This is CORRECT!</remark>
<remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark>
<setindex></setindex></programlisting>
</step>
<step>
<para>
In the <filename>Preface.xml</filename> and <filename>Book_Info.xml</filename> for each book you are using, add ../../ to the front of every Common_Content string you see. For example:
</para>
<programlisting language="XML"><xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
This will need to become:
</para>
<programlisting language="XML"><xi:include href="../../Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
<para>
This is because in a standalone set, the Common Content folder is two directories further away from where Publican usually looks for it, so it has to be told manually. To build your book individually, without building the entire set, undo this step.
</para>
</step>
</substeps>
</step>
<step>
<para>
Test your set by running the <command>publican build --formats=test --langs=en-US</command> command.
</para>
</step>
</procedure>
<para>
If you are using pre-existing books, you will need to rearrange them so the XML files are at the level of the set and all images are inside the images directory at the same level. For example:
</para>
<programlisting> -- My_Set
|-- en-US
| |-- Author_Group.xml
| |-- Book_A.ent
| |-- Book_A.xml
| |-- Book_B.ent
| |-- Book_B.xml
| |-- Book_Info_A.xml
| |-- Book_Info_B.xml
| |-- chapter_A.xml
| |-- chapter_B.xml
| |-- images
| | |-- icon.svg
| | `-- image1.png
| |-- My_Set.ent
| |-- My_Set.xml
| |-- Preface.xml
| |-- Revision_History.xml
| `-- Set_Info.xml
`-- publican.cfg</programlisting>
<para>
The XML files can also be within sub-folders to keep them separate. This is true within the images directory, as well. For example:
</para>
<programlisting> -- My_Set
|-- en-US
| |-- Author_Group.xml
| |-- Book_A
| | |-- Book_A.ent
| | |-- Book_A.xml
| | |-- Book_Info.xml
| | `-- chapter.xml
| |-- Book_B
| | |-- Book_B.ent
| | |-- Book_B.xml
| | |-- Book_Info.xml
| | `-- chapter.xml
| |-- images
| | |-- icon.svg
| | `-- image1.png
| |-- My_Set.ent
| |-- My_Set.xml
| |-- Preface.xml
| |-- Revision_History.xml
| `-- Set_Info.xml
`-- publican.cfg</programlisting>
</section>
<section conformance="215" xml:id="sect-Publican-Users_Guide-Using_sets-Distributed_sets">
<info>
<title>Distributed sets</title>
</info>
<para>
A <firstterm>distributed set</firstterm> contains books that are located in a version-controlled repository. Although several version control systems exist, this version of <application>Publican</application> supports only one: <application>Subversion</application> (<application>SVN</application>). By setting the repository location and titles of the included books in the <filename>publican.cfg</filename> file, each book can be exported to build the entire set. The procedure that follows will guide you through the process of creating a set named <citetitle>My Set</citetitle> containing <citetitle>Book A</citetitle> and <citetitle>Book B</citetitle>.
</para>
<important>
<para>
The following procedure assumes that <citetitle>Book A</citetitle> and <citetitle>Book B</citetitle> already exist and are available in your <application>SVN</application> repository. Currently <application>Publican</application> only supports <application>SVN</application>.
</para>
</important>
<procedure conformance="216" xml:id="proc-Publican-Users_Guide-Distributed_sets-Creating_a_set">
<title>Creating a set</title>
<step>
<para>
Run the following command in a shell to create a set named <literal>My_Set</literal> branded in the Red Hat style and in which the XML will be written in American English.
</para>
<programlisting>$ publican create --type=Set --name=My_Set --brand=RedHat --lang=en-US</programlisting>
</step>
<step>
<para>
Add the following lines to the <filename>publican.cfg</filename> file:
</para>
<programlisting>books: Book_A Book_B
repo: <replaceable>http://PATH-TO-YOUR-SVN-REPOSITORY</replaceable>
scm: SVN</programlisting>
<para>
Your repository path should end in the directory before the book you need.
</para>
</step>
<step>
<para>
Open the <filename>My_Set.xml</filename> file in an editor. For each book in the set, add an <tag>xi:include</tag> reference to the primary XML file from the book. The primary XML file for <citetitle>Book A</citetitle> will be <filename>Book_A.xml</filename> and for <citetitle>Book B</citetitle>, <filename>Book_B.xml</filename>. The <filename>My_Set.xml</filename> file should now look like this:
</para>
<programlisting language="XML"><xi:include href="extras/Set_Name.xmlt" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude" /></programlisting>
</step>
<step>
<para>
To make your set XML valid, you will need to comment out the following lines in <filename>My_Set.xml</filename>
</para>
<programlisting language="XML"><remark>NOTE: the href does not contain a language! This is CORRECT!</remark>
<remark><xi:include href="My_Other_Book/My_Other_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></remark>
<setindex></setindex></programlisting>
</step>
<step>
<para>
Test your set by running the <command>publican build --formats=test --langs=en-US</command> command.
</para>
<important>
<para>
When building a set, the <command>publican clean_ids</command> command will be run over each book because of the constraint that IDs must be unique across all books. Be careful of creating IDs that rely on content that may not be available when building books independently of the set.
</para>
</important>
</step>
</procedure>
</section>
</chapter>
|
