Documentation Repository Contents
=================================
This repository is intended for storage of Liferay product documentation.
Documents are to be comprised of chapter source files in Markdown format.
Images referenced in the documents are to be stored in the appropriate images
directories.  Document sources are stored in directories for their appropriate
language (e.g. 'en' for English).

Directory Structure
===================
liferay-docs/
 |____ <document dir>/ (e.g. adminGuide)
 |      |____ <language dir>/ (e.g. 'en' for English, 'es' for Spanish)
 |      |      |
 |      |      |____ chapters/
 |      |      |      |____ [0-9][0-9]-<chapter subject>.markdown
 |      |      |
 |      |      |____ images/ (override images - language specific)
 |      |
 |      |____ images/ (default images)
 |      |____ build.xml
 |
 |____ build-common.xml
 |____ build.properties
 |____ build.<username>.properties
 |____ liferay-book-template.ott
 |____ liferay-book-template-tradepaperback.ott
 |____ README

Document Format Conversion
==========================
Documents can be converted from markdown to HTML, epub and ODT formats using ant
and the targets found in build-common.xml. To override common properties found
in build.properties, create your own properties file
(e.g. build.<username>.properties) and specify desired property values.

A build directory is created by the targets and holds the Markdown source
file consisting of all of the document's chapters, the language specific image
files and the resulting document in its newly converted format.

Required Software
-----------------
* Ant: Required for executing Ant targets.  Download from ...
  http://ant.apache.org/bindownload.cgi

* Pandoc: Used in our Ant targets for conversions from Markdown to various
formats. See installation instructions at ...
  http://johnmacfarlane.net/pandoc/installing.html

Conversion Steps
----------------
1. Go to the directory of the document to be converted.

  Example,
    cd liferay-docs/adminGuide

2. Concatenate the chapters into the complete Markdown document.

  Example,
    ant concat-markdown-files

3. Execute the target to produce the desired format of the document.

  Example,
    ant markdown-to-html

  Example,
    ant markdown-to-odt

To get a complete listing of targets execute ...

    ant -projecthelp

To override the language property (i.e. lang) specified in the build.properties
either pass a property to ant from the commandline (e.g. -Dlang=es) or
specify your desired language property value (e.g. lang=es) in your
build.<user>.properties.

To do conversions on Windows, execute the Windows specific targets
(e.g. concat-markdown-files-win and markdown-to-html-win)

Results are produced in the respective liferay-docs/<doc.name>/build/<lang>/
  Example,

    liferay-docs/
     |____ adminGuide/
            |____ build/
            |      |____ en/
            |      |      |____ adminGuide.html
            |      |      |____ adminGuide.markdown
            |      |      |____ adminGuide.odt
            |      |
            |      |____ images/ (language specific overrides)
            |
            |____ images/