forked from apache/cloudstack
-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.txt
325 lines (221 loc) · 13.1 KB
/
README.txt
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
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
Author: Jessica Tomechak
Updated: August 8, 2012
-------------------------------------------
WHAT'S IN THIS REPOSITORY: WORK IN PROGRESS
-------------------------------------------
This repository contains the source files for CloudStack documentation. The files are currently incomplete as we are in the process of converting documentation from an outdated file format into XML files for this repo.
The complete documentation can be seen at docs.cloudstack.org.
----------------------------------
DOCUMENTATION SUBDIRECTORIES
----------------------------------
United States English language source files are in the en-US subdirectory.
Additional language subdirectories can be added.
Each file in a language subdirectory contains one chunk of information that may be termed a section, module, or topic. The files are written in Docbook XML, using the Docbook version and tag supported by the Publican open-source documentation tool.
----------------------------------
VALID XML TAGS
----------------------------------
Certain tags are disallowed by Publican. Please consult their documentation for more details.
https://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/
Your best bet is to copy an existing XML file and fill in your own content between the tags.
At the bottom of this README, there is a fill-in-the-blanks XML template that you can go from. It shows the commonly used tags and explains a bit about how to use them.
----------------------------------
SECTIONS, CHAPTERS, AND BOOK FILES
----------------------------------
The files for every topic and audience are in a single directory. The content is not divided into separate subdirectories for each book, or separate repositories for each book. Therefore, the content can be flexibly and easily re-used. In most cases, a file contains a single section that can be assembled with other sections to build any desired set of information. These files contain <section> ... </section> tags.
Some of the XML files contain only a series of include tags to pull in content from other files. Such an "include file" is either a major section, a chapter in a book, or the master book file. A chapter contains <chapter> ... </chapter> tags.
The master book file contains <book> ... </book> tags. This file is referred to in the Publican configuration file, and is used as the controlling file when building the book.
Document names are derived from the docname setting in the appropriate .cfg file.
This should not have CloudStack in the name (which is redundant because of
the CloudStack brand that the documentation is built with. The docname variable
sets the name in the doc site table of contents. This name also needs to exist
as .xml and .ent in the en-US directory. Examples of appropriate docnames:
Admin_Guide
API_Developers_Guide
Installation_Guide
A Publican book file must also have certain other tags that are expected by
Publican when it builds the project. Copy an existing master book file to
get these tags.
----------------------------------
CONFIG FILES
----------------------------------
For each book file, there must be a corresponding publican.cfg (or
<other_name>.cfg) file in order to build the book with Publican. The
docname: attribute in the config file matches the name of the master book file;
for example, docname: cloudstack corresponds to the master book file
cloudstack.xml.
The .cfg files reside in the main directory, docs. To build a different book,
just use the Publican command line flag --config=<filename>.cfg. (We also
need per-book entities, Book_Info, Author_Info, and other Publican files.
The technique for pulling these in is TBD.)
----------------------------------
TO BUILD A BOOK
----------------------------------
We will set up an automatic Publican job that generates new output whenever we
check in changes to this repository. You can also build a book locally as
follows.
First, install Publican, and get a local copy of the book source files.
Put the desired publican.cfg in the docs directory. Go to the command line, cd
to that directory, and run the publican build command. Specify what output
format(s) and what language(s) you want to build. Always start with a test
run. For example:
publican build --formats test --langs en-US
...followed by this command if the test is successful:
publican build --formats html,pdf --langs en-US
Output will be found in the tmp subdirectory of the docs directory.
----------------------------------
LOCALIZATION
----------------------------------
Localized versions of the documentation files can be stored in appropriately
named subdirectories parallel to en-US. The language code names to use for
these directories are listed in Publican documentation,
https://jfearn.fedorapeople.org/en-US/Publican/2.7/html/Users_Guide/appe-Users_Guide-Language_codes.html.
For example, Japanese XML files would be stored in the docs/ja-JP directory.
Localization currently happens using Transifex and you can find the strings
to be translated at this location:
https://www.transifex.com/projects/p/ACS_DOCS/
In preparation for l10n, authors and docs folks must take not of a number of
things.
All .xml files must contain a translatable string. <xi:include> tags are not enough.
All new .xml files must have a corresponding entry in docs/.tx/config
Filenames should be less than 50 characters long.
To generate new POT files and upload source do the following:
publican update_pot --config=./publican-all.cfg
tx push -s
To receive translated files from publican, run the following command:
tx pull
----------------------------------
CONTRIBUTING
----------------------------------
Contributors can create new section, chapter, book, publican.cfg, or localized
.xml files at any time. Submit them following the same patch approval procedure
that is used for contributing to CloudStack code. More information for
contributors is available at
https://cwiki.apache.org/confluence/display/CLOUDSTACK/Documentation+Team.
----------------------------------
TAGS FOR A SECTION
----------------------------------
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "https://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!-- Please keep the doctype and license declarations above intact in each doc file. -->
<!-- Make your modifications below this line. -->
<section id="INSERT A UNIQUE SECTION ID HERE, PROBABLY MATCHING THE TITLE BELOW. KEEP THE QUOTE MARKS.">
<title>Text of the section title</title>
<para>Here's the text of a paragraph in this section.</para>
<para>Always use &PRODUCT; rather than typing CloudStack.</para>
<para>Indent with 4 spaces, not with tab characters.</para>
<para>To hyperlink to a URL outside this document: <ulink url="https://external URL here">Display text of the link here</ulink></para>
<para>To hyperlink to another section in this document: <xref linkend="SECTION ID OF THE OTHER SECTION GOES HERE." />
The publication tools will automatically insert the display text of the link for you.</para>
<note><para>Use this for all tips and asides. Don't use other tags such as tip.
Our publication tool (publican) prefers the note tag. The tool will
automatically insert the text NOTE: for you, so please don't type it.</para></note>
<warning><para>Use this for anything that is vital to avoid runtime errors. Don't use
other tags such as caution. Our publication tool (publican) prefers the warning tag. The tool will automatically insert the text WARNING: for you, so please don't type it.</para></warning>
<para>Here's how to do a bulleted list:</para>
<itemizedlist>
<listitem><para>Bulleted list item text.</para></listitem>
</itemizedlist>
<para>Here's how to do a numbered list. These are used for step by step instructions
or to describe a sequence of events in time. For everything else, use a bulleted list.</para>
<orderedlist>
<listitem><para>Text of the step</para></listitem>
<listitem><para>You might also want a sub-list within one of the list items. Like this:</para>
<orderedlist numeration="loweralpha">
<listitem><para>Inner list item text.</para></listitem>
</orderedlist>
</listitem>
</orderedlist>
<para>Here's how to insert an image. Put the graphic file in images/, a subdirectory of the directory where this XML file is.
Refer to it using this tag. The tag is admittedly complex, but it's the one we need to use with publican:</para>
<mediaobject>
<imageobject>
<imagedata fileref="./images/YOUR_FILENAME_HERE.png" />
</imageobject>
<textobject><phrase>YOUR_FILENAME_HERE.png: Alt text describing this image, such as
structure of a zone. Required for accessibility.</phrase></textobject>
</mediaobject>
<para>A section can contain sub-sections. Please make each sub-section a separate file to enable reuse.
Then include the sub-section like this:</para>
<xi:include href="SUBSECTION_FILE_NAME.xml" xmlns:xi="https://www.w3.org/2001/XInclude" />
</section>
----------------------------------
TAGS FOR A CHAPTER
----------------------------------
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "https://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!-- Please keep the doctype and license declarations above intact in each doc file. -->
<!-- Make your modifications below this line. -->
<chapter id="INSERT A UNIQUE SECTION ID HERE, PROBABLY MATCHING THE TITLE BELOW. KEEP THE QUOTE MARKS.">
<title>Text of the chapter title</title>
<xi:include href="SECTION_ONE_FILENAME.xml" xmlns:xi="https://www.w3.org/2001/XInclude" />
<xi:include href="SECTION_TWO_FILENAME.xml" xmlns:xi="https://www.w3.org/2001/XInclude" />
</chapter>
----------------------------------
TAGS FOR A BOOK
----------------------------------
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "https://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>
<!-- Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
https://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!-- Please keep the doctype and license declarations above intact in each doc file. -->
<!-- Make your modifications below this line. -->
<book>
<xi:include href="Book_Info.xml" xmlns:xi="https://www.w3.org/2001/XInclude" />
<xi:include href="CHAPTER_ONE_FILENAME.xml" xmlns:xi="https://www.w3.org/2001/XInclude" />
<xi:include href="CHAPTER_TWO_FILENAME.xml" xmlns:xi="https://www.w3.org/2001/XInclude" />
</book>
----------------------------------
BASIC RULES FOR INCLUDE STATEMENTS
----------------------------------
A book file must include chapter files.
A chapter file must include section files.
A section file can include other section files, but it doesn't have to.