This directory contains the Apache ANT-based build infrastructure for transforming Perforce guides authored in DocBook XML into PDF and HTML. The following provides a brief overview of the structure and content of this directory.
| File/Folder | Description |
|---|---|
assets/ |
directory contains one directory for each available transformation target. |
common_adoc/ |
directory contains common AsciiDoc files that many guides require. |
common_xml/ |
directory contains common DocBook XML files that many guides require. |
ad_generator.rb |
Ruby post-processor for AsciiDoctor-generated DocBook. |
build.properties |
declares properties that are transformation-independent, e.g. specifying which XSLT processor to use. |
build.xml |
contains the ANT targets used to transform guides into various forms. |
global.properties |
declares a mix of ANT and DocBook XML properties that provide defaults for all transformations. |
indexer.py |
a Python script that indexes the generated HTML, to facilitate live searching within a guide. |
sample_oxygen.catalog |
See catalogs, below. |
<a name="transformation_targets"></a>
A transformation target is a combination of an ANT build target and the
assets in the identically named folder. For example, to produce a PDF
version of a guide, within the guide's directory you would invoke ant pdf, which executes the pdf target in build.xml, which uses the asset
files within assets/pdf.
<a name="catalogs"></a>
If you use the oXygen XML editor, customize the sample_oxygen.catalog
file to specify where the common_xml and manuals directories exist on
your system. Then configure oXygen to use this catalog file to allow
oXygen to validate our DocBook XML guides. This is necessary because the
paths to each directory can vary depending on how you have installed them,
and oXygen won't be able to find them without this configuration.
<a name="ant"></a>
A word on ANT properties, for the unintiated: ANT properties are mostly immutable; the first definition wins. This makes the handling of per-guide property settings, combined with reasonable defaults for per-format guide transformations, combined with common defaults for any transformation, appear rather convoluted.
Using the suggested sample guide directory structure, properties are read in the following order:
<a name="params"></a>
Many, but not all, DocBook parameters can be specified within a guide's
build.properties file (or more likely, the guide's
assets/build target/build.properties file. If you need to set a specific
parameter but it does not seem to take effect, add it to the guide's
assets/build target/build target.xsl file.
<!--- vim: set ts=2 sw=2 tw=74 ai si: -->
# Perforce This directory contains the Apache ANT-based build infrastructure for transforming Perforce guides authored in DocBook XML into PDF and HTML. The following provides a brief overview of the structure and content of this directory. | File/Folder | Description | | --------------------- | ----------- | | `assets/` | directory contains one directory for each available [transformation target](#transformation_targets). | | `common_adoc/` | directory contains common AsciiDoc files that many guides require. | | `common_xml/` | directory contains common DocBook XML files that many guides require. | | `ad_generator.rb` | Ruby post-processor for AsciiDoctor-generated DocBook. | | `build.properties` | declares properties that are transformation-independent, e.g. specifying which XSLT processor to use. | | `build.xml` | contains the ANT targets used to transform guides into various forms. | | `global.properties` | declares a mix of ANT and DocBook XML properties that provide defaults for all transformations. | | `indexer.py` | a Python script that indexes the generated HTML, to facilitate live searching within a guide. | | `sample_oxygen.catalog` | See catalogs, [below](#catalogs). | <a name="transformation_targets"></a> ## Transformation Targets A transformation target is a combination of an ANT build target and the assets in the identically named folder. For example, to produce a PDF version of a guide, within the guide's directory you would invoke `ant pdf`, which executes the `pdf` target in `build.xml`, which uses the asset files within `assets/pdf`. <a name="catalogs"></a> ## Catalogs If you use the oXygen XML editor, customize the `sample_oxygen.catalog` file to specify where the `common_xml` and manuals directories exist on your system. Then configure oXygen to use this catalog file to allow oXygen to validate our DocBook XML guides. This is necessary because the paths to each directory can vary depending on how you have installed them, and oXygen won't be able to find them without this configuration. <a name="ant"></a> ## ANT Processing Notes A word on ANT properties, for the unintiated: ANT properties are mostly immutable; the first definition wins. This makes the handling of per-guide property settings, combined with reasonable defaults for per-format guide transformations, combined with common defaults for any transformation, appear rather convoluted. Using the suggested [sample guide](../sample_guide/README.md) directory structure, properties are read in the following order: 1. _guide_/build.properties 1. perforce/build.properties 1. _guide_/assets/_build target_/build.properties 1. perforce/global.properties <a name="params"></a> ## DocBook Parameter Notes Many, but not all, DocBook parameters can be specified within a guide's `build.properties` file (or more likely, the guide's assets/_build target_/build.properties file. If you need to set a specific parameter but it does not seem to take effect, add it to the guide's assets/_build target_/_build target_.xsl file. <!--- vim: set ts=2 sw=2 tw=74 ai si: -->
| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #1 | 26953 | Paul Allen | Move //guest/perforce_software/p4convert to //guest/perforce_software/p4convert/main | ||
| //guest/perforce_software/p4convert/docs/perforce/README.md | |||||
| #2 | 14806 | Paul Allen | Update docs and add +w. | ||
| #1 | 13919 | Paul Allen | part 1 of copy | ||
| //guest/paul_allen/p4convert-maven/docs/perforce/README.md | |||||
| #1 | 13895 | Paul Allen | Copying using p4convert-docbook | ||
| //guest/perforce_software/doc_build/main/perforce/README.md | |||||
| #1 | 12842 | eedwards |
Add Markdown docs for the doc infrastructure (which will be easy to read within the Workshop). This should be sufficient to point users in the right direction, but there is certainly room for expansion. |
||
| //guest/perforce_software/doc_build/main/perforce/README | |||||
| #2 | 12798 | eedwards |
Follow-on to @935187: handle @guides-dir@ in addition to @common-xml@. Also, fixup an xml:id problem. |
||
| #1 | 12797 | eedwards |
Update the handling of @common-xml@ paths to permit using an XML Catalog file to resolve these references in the oXygen XML editor. A sample catalog file is included, which needs to be customized on your system to reflect the actual local filesystem path to the common_xml directory, and then oXygen needs to be configured to use this catalog file. Once these steps are done, oXygen should be able to validate the guides. Each guide that uses this facility has been updated accordingly. |
||