<commit_before>Author: <NAME>

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.
http://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.


As a naming convention, start the name of a book file with cloudstack_ ; for example, cloudstack_installation.


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.



----------------------------------

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, 
http://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
----------------------------------<commit_msg>fixing README to reflect TOC issues around docname variable<commit_after>Author: <NAME>

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.
http://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.



----------------------------------

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, 
http://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
----------------------------------
{'fraction_non_alphanumeric': 0.14559386973180077, 'fraction_numerical': 0.002165583874729302, 'mean_word_length': 2.543978748524203, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 9}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6489326', 'n_tokens_mistral': 2932, 'n_tokens_neox': 2784, 'n_words': 1587}