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
|
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter 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;
]>
<chapter id="chap-Users_Guide-Creating_a_document">
<title>Creating a document</title>
<para>
This chapter describes creating books and articles: the main configuration files, example document files, and how to build a document.
</para>
<para>
Use the <command>publican create</command> command to create a new document, including all the necessary files for the document.
</para>
<para>
The <command>publican create</command> command accepts several options, detailed in this chapter. When an option can accept a value, separate the option from the value with a space or an equals sign; for example, <command>publican create --name New_Book</command> or <command>publican create --name=New_Book</command>.
</para>
<variablelist>
<varlistentry>
<term><option>--help</option></term>
<listitem>
<para>
print a list of all <command>publican create</command> command options.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--name<replaceable> Doc_Name</replaceable></option></term>
<listitem>
<para>
set <replaceable>Doc_Name</replaceable> as the name of the book or article. This variable must not contain any spaces. For example, the command <command>create_book --name Test_Book</command> creates a book named <literal>Test_Book</literal> with all the necessary files to build the book, and sets the <parameter>BOOKID</parameter> in the <filename>Test_Book.ent</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--lang<replaceable> Language_Code</replaceable></option></term>
<listitem>
<para>
set <replaceable>Language_Code</replaceable> as the language code of the language in which the book or article will be authored. If you do not specify a language code, <application>Publican</application> defaults to <literal>en-US</literal> (American English). The <option>--lang</option> option sets the <parameter>xml_lang</parameter> in the <filename>publican.cfg</filename> file and creates a directory with this name in the document directory. When initially created, this directory contains some boilerplate XML files. Refer to <xref linkend="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" /> for more information on <filename>publican.cfg</filename> parameters and <xref linkend="appe-Users_Guide-Language_codes" /> for more detail on language codes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--version<replaceable> version</replaceable></option></term>
<listitem>
<para>
set <replaceable>version</replaceable> as the version number of the product that the book describes. For example, for Red Hat Enterprise Linux 5.1 you would use <literal>5.1</literal>. The default version is <literal>0.1</literal>. The <option>--version</option> option sets the <sgmltag><productnumber></sgmltag> tag in the <filename>Book_Info.xml</filename> or <filename>Article_Info.xml</filename> file. For more information refer to <xref linkend="sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml" />.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--edition<replaceable> edition</replaceable></option></term>
<listitem>
<para>
set <replaceable>edition</replaceable> as the edition number of the book. This number indicates to users when a new edition of the book is released. The initial <firstterm>general availability</firstterm> (GA) release of the book should be edition <literal>1.0</literal>. The default value is <literal>0</literal>. The <option>--edition</option> option sets the <sgmltag><edition></sgmltag> tag in the <filename>Book_Info.xml</filename> or <filename>Article_Info.xml</filename> file. For more information refer to <xref linkend="sect-Users_Guide-Files_in_the_book_directory-Book_Info.xml" />.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--product<replaceable> Product_Name</replaceable></option></term>
<listitem>
<para>
set <replaceable>Product_Name</replaceable> as the name of the product that the book describes. This variable must not contain any spaces. For example, set this to <literal>Fedora</literal> for core Fedora documentation, and the name of the product for other products, for example, <literal>Fedora_Directory_Server</literal>. The default value is <literal>Documentation</literal>. The <option>--product</option> option sets the <sgmltag><product name></sgmltag> tag in the <filename>Book_Info.xml</filename> file or <filename>Article_Info.xml</filename> file and the <parameter>PRODUCT</parameter> entity in the <filename><replaceable>Doc_Name</replaceable>.ent</filename> file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--type Article --name<replaceable> Article_Name</replaceable></option></term>
<listitem>
<para>
create an article instead of a book. Replace <replaceable>Article_Name</replaceable> with the article name. This variable must not contain any spaces. The <option>--type</option> option sets the <parameter>type</parameter> in the <filename>publican.cfg</filename> file. Refer to <xref linkend="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" /> for more information on <filename>publican.cfg</filename> parameters.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--type Set --name<replaceable> Set_Name</replaceable></option></term>
<listitem>
<para>
create a set of documents instead of a book. Replace <replaceable>Set_Name</replaceable> with the set name. This variable must not contain any spaces. The <option>--type</option> option sets the <parameter>type</parameter> in the <filename>publican.cfg</filename> file. Refer to <xref linkend="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" /> for more information on <filename>publican.cfg</filename> parameters and to <xref linkend="chap-Users_Guide-Using_sets" /> for details on using sets.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--brand <replaceable>brand</replaceable></option></term>
<listitem>
<para>
set <replaceable>brand</replaceable> as the <firstterm>brand</firstterm> to use to style the output of this document, for example, <literal>RedHat</literal>, <literal>fedora</literal>, <literal>JBoss</literal>, <literal>oVirt</literal>, or <literal>GIMP</literal>. The default value is <literal>common</literal>, a default brand shipped with <application>Publican</application>. The <option>--brand</option> option sets the <parameter>brand</parameter> parameter in the <filename>publican.cfg</filename> file. Refer to <xref linkend="sect-Users_Guide-Files_in_the_book_directory-The_publican.cfg_file" /> for more information on <filename>publican.cfg</filename> parameters. This option requires the appropriate <application>Publican</application> brand package to be installed. For example, to build Red Hat branded books, you must install the <package>publican-redhat</package> package. Refer to <xref linkend="sect-Users_Guide-Installing_a_brand" /> for instructions on installing brand packages for <application>Publican</application>. If you do not specify a brand, <application>Publican</application> uses its built-in, default brand. Refer to <xref linkend="chap-Users_Guide-Branding" /> for more information.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Before running the <command>publican create</command> command, use the <command>cd</command> command to change into the directory where you want the book to be created. For example, to create a book named <literal>Test_Book</literal> in the <filename>my_books/</filename> directory, run the following commands:
</para>
<screen><command>cd my_books/</command>
<command>publican create --name Test_Book</command></screen>
<para>
To see the results of this command on a computer with a Linux operating system, run the following:
</para>
<screen><command>ls</command></screen>
<para>
The output should be similar to the following:
</para>
<screen><computeroutput>Test_Book/</computeroutput></screen>
<para>
To see the contents of the new <filename>Test_Book/</filename> directory on a computer with a Linux operating system, run the following:
</para>
<screen><command>cd Test_Book/</command>
<command>ls</command></screen>
<para>
The output should be similar to the following:
</para>
<screen><computeroutput>en-US/ publican.cfg</computeroutput></screen>
<xi:include href="Files_in_the_Book_Directory.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Adding_Images.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Adding_Code_Samples.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Adding_Files.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Renaming_a_document.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Preparing_a_Book_for_Translation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Building_a_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Packaging_a_Book.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Conditionaltagging.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Draft.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</chapter>
|
