You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by hu...@apache.org on 2012/10/06 00:32:45 UTC
[20/49] git commit: fixing README to reflect TOC issues around
docname variable
fixing README to reflect TOC issues around docname variable
Project: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/commit/1176572f
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/tree/1176572f
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/diff/1176572f
Branch: refs/heads/maven-to-rpm
Commit: 1176572f0733d9e8deebf05bf1306ca087d1920c
Parents: 742d9bb
Author: David Nalley <da...@gnsa.us>
Authored: Thu Oct 4 23:33:23 2012 -0400
Committer: Hugo Trippaers <ht...@schubergphilis.com>
Committed: Sat Oct 6 00:30:27 2012 +0200
----------------------------------------------------------------------
docs/README.txt | 39 ++++++++++++++++++++++++++++++++-------
1 files changed, 32 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-cloudstack/blob/1176572f/docs/README.txt
----------------------------------------------------------------------
diff --git a/docs/README.txt b/docs/README.txt
index 41bf749..113cfed 100644
--- a/docs/README.txt
+++ b/docs/README.txt
@@ -57,10 +57,21 @@ Some of the XML files contain only a series of include tags to pull in content f
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.
-As a naming convention, start the name of a book file with cloudstack_ ; for example, cloudstack_installation.
+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.
+
+
+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.
----------------------------------
@@ -71,10 +82,15 @@ 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.
+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.)
+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.)
----------------------------------
@@ -83,13 +99,18 @@ 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.
+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:
+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
@@ -141,7 +162,11 @@ 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.
+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.
----------------------------------