<commit_before>Welcome to Idiom's FO output for the DITA Open Toolkit
======================================================

Idiom Technologies has donated its production quality PDF output for use with 
the DITA Open Toolkit. This has been integrated into the Toolkit as a plugin. 
Features of this code include:

- Index (with extensions) and table of contents generation
- Font mapping: characters can be remapped to different fonts. This is 
  particularly useful for CJK font support, and is configured per-locale.
- Extensive customization of publishing output by setting variables
  (67 of them) and attribute-sets (391 of them).
- A catalog-based customization framework where you can customize variables, 
  attribute-sets and XSLs without modifying Open Toolkit code: your custom 
  settings live in files in a separate customization hierarchy.
- Bookmap/bookinfo support.

This plugin has only been tested with Sun's JDK 1.4 and may not work
with the IBM JDK due to a conflict with XEP's crimson.jar.

Building and installing Idiom's FO output
=========================================

You will need the following software, which we cannot include with
this plugin due to licensing and redistribution restrictions:

- RenderX XEP: Idiom's FO output currently requires RenderX XEP to
  convert FO to PDF. The personal edition of XEP can be obtained for
  free from RenderX (http://www.renderx.com). XEP comes with Saxon
  6.5.3, which this plugin also needs. But if you are using JDK 1.5 or 
  newer, you will need Saxon 6.5.5 or newer which has fixes for JDK 1.5
  compatibility. Download Saxon 6.5.5 from http://saxon.sourceforge.net.

- ICU4J: You can find this library by clicking on the "Download ICU" link
  at http://icu.sourceforge.net. Look for the ICU4J downloads. ICU4J is
  an optional jar that will give you better collation of index entries.

 To install and use with the Open Toolkit's distribution,

1. Install the DITA Open Toolkit.
2. Unzip this plugin into an Open Toolkit installation's
   demo directory.
3. Install XEP personal edition and license into demo/fo/lib/xep.
4. If you are using JDK 1.5, install saxon.jar in demo/fo/lib/xep/lib.
5. Install the ICU4j jar (optional) as demo/fo/lib/icu4j.jar
6. From the Open Toolkit directory, run "ant -f integrator.xml"

At this point, the FO output is fully integrated into the Open
Toolkit's pipeline. The plugin infrastructure will detect the FO
plugin in step 5 and provide a "pdf2" output: this will invoke this FO
output instead of the previous FOP-based output. Invoke with a command
line like:

java -jar lib/dost.jar /i:doc/DITA-readme.ditamap /transtype:pdf2

If you are using the startcmd.bat/sh script, make sure the classpath in that 
script lists saxon.jar before xalan.jar. 

About the index extensions
==========================

The index generation feature adds extensions to DITA's indexterm that can be
expressed as content of that element. These extensions are expressed in a 
FrameMaker-like syntax in the element's textual content, and provide 
functionality not yet available in the standard indexterm element. They also
help migration from legacy FrameMaker content. For example, the following 
generates a "see also" entry:

	<indexterm>Carp:<$nopage>see also Goldfish</indexterm>
	
As:

	Carp, 34
	   see also Goldfish	
	
The extended syntax consists of:

	: (colon)       Separates levels in an entry
	; (semicolon)   Separates entries in a marker
	[] (brackets)   Specifies a special sort order for the entry
	<$startrange>   Indicates the beginning of a page range
	<$endrange>     Indicates the end of a page range
	<$nopage>       Suppresses the page number in the entry (for example, in
	                a See entry)
	<$singlepage>   In a marker that contains several entries, restores the 
	                page number for an entry that follows a <$nopage>
	                building block

DITA 1.1 indexing elements have been implemented in this plugin that
should make these extensions unnecessary. You can now express see/see
also, sort order and page ranges using standard DITA 1.1 elements.

About /Customization
====================

This directory is where the custom files live that make up customized
versions of the FO publishing outputs.  Idiom's FO publishing output will 
look for certain files here to override the standard ones. Things you can 
currently override include:

  - Custom XSL via fo/xsl/custom.xsl and fo/attrs/custom.xsl
  - Layout overrides via fo/layout-masters.xml
  - Font overrides via fo/font-mappings.xml
  - Per-locale variable overrides via common/vars/[locale].xml
  - I18N configuration via fo/i18n/[locale].xml
  - Index configuration via fo/index/[locale].xml

When customizing any of these areas, modify the relevant file(s) in
/Customization.  Then, to enable the changes in the publishing process, 
you find the corresponding entry for each file you modified in 
/Customization/catalog.xml. It should look like this:

    <!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/-->

Remove the comment markers "!--" and "--" to enable the change:

    <uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/>

Your customization should now be enabled as part of the publishing process.

Idiom has provided template files that you can start with throughout
this directory structure.  These files end in the suffix ".orig" (for
example, "catalog.xml.orig").  To enable these files, make a copy of
them and remove the ".orig" suffix.  For example, copy
"catalog.xml.orig" to "catalog.xml".  You can then make modifications
to the copy.

Idiom's FO output also provides a general configuration file called
"build.properties" that allows you to control the publishing process.
To modify these settings, copy "build.properties.orig" to
"build.properties" and then modify the relevant options.

History
=======

FO Plugin Release 1.4.2

- Misc internal fixes.

Sourceforge bug fixes:
- 1710233: summary element in bookmeta not handled properly (15251)

FO Plugin Release 1.4.1
Available since Oct 5, 2007

- more flexible index configuration (see common/index/zh_CN.xml for example)

Sourceforge bug fixes:
- 1793307: issue with topicref in bookmap's <notices> (16587)
- 1791403: invalid column-width attribute value (16586)
- 1805389: XSLT errors in FO plugin
- 1694607: Use-by-reference footnotes not rendered correctly (15249)

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

FO Plugin Release 1.4

- Rebased with Idiom's internal code as of August 28, 2007.
- Updated DITA 1.1 support: new bookmap and indexing elements.
- Minor fixes

Sourceforge bug fixes:
- 1686323: Idiom FO plug-in fails during pdf2 build (15348)
- 1729594: Topichead not supported in pdf2 output (15247) 
- 1647267: Single-step tasks numbers the step (15248)

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

FO Plugin Release 1.2.1

- rebased with Idiom's internal code as of Nov 6, 2006.
- updated copyright/licensing notices in files.
- fixed image copying task for customization.

Sourceforge bug fixes:
- 1574115: Using 1.3 and Idiom FO 1.2 plugin fail
- 1523653: pdf2 transform assumes basedir = ditadir (for real, this time!)

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

FO Plugin Release 1.2
Available since Sept 29, 2006
<commit_msg>Update for release<commit_after>Welcome to Idiom's FO output for the DITA Open Toolkit
======================================================

Idiom Technologies has donated its production quality PDF output for use with 
the DITA Open Toolkit. This has been integrated into the Toolkit as a plugin. 
Features of this code include:

- Index (with extensions) and table of contents generation
- Font mapping: characters can be remapped to different fonts. This is 
  particularly useful for CJK font support, and is configured per-locale.
- Extensive customization of publishing output by setting variables
  (67 of them) and attribute-sets (391 of them).
- A catalog-based customization framework where you can customize variables, 
  attribute-sets and XSLs without modifying Open Toolkit code: your custom 
  settings live in files in a separate customization hierarchy.
- Bookmap/bookinfo support.

This plugin has only been tested with Sun's JDK 1.4 and may not work
with the IBM JDK due to a conflict with XEP's crimson.jar.

Building and installing Idiom's FO output
=========================================

You will need the following software, which we cannot include with
this plugin due to licensing and redistribution restrictions:

- RenderX XEP: Idiom's FO output currently requires RenderX XEP to
  convert FO to PDF. The personal edition of XEP can be obtained for
  free from RenderX (http://www.renderx.com). XEP comes with Saxon
  6.5.3, which this plugin also needs. But if you are using JDK 1.5 or 
  newer, you will need Saxon 6.5.5 or newer which has fixes for JDK 1.5
  compatibility. Download Saxon 6.5.5 from http://saxon.sourceforge.net.

- ICU4J: You can find this library by clicking on the "Download ICU" link
  at http://icu.sourceforge.net. Look for the ICU4J downloads. ICU4J is
  an optional jar that will give you better collation of index entries.

 To install and use with the Open Toolkit's distribution,

1. Install the DITA Open Toolkit.
2. Unzip this plugin into an Open Toolkit installation's
   demo directory.
3. Install XEP personal edition and license into demo/fo/lib/xep.
4. If you are using JDK 1.5, install saxon.jar in demo/fo/lib/xep/lib.
5. Install the ICU4j jar (optional) as demo/fo/lib/icu4j.jar
6. From the Open Toolkit directory, run "ant -f integrator.xml"

At this point, the FO output is fully integrated into the Open
Toolkit's pipeline. The plugin infrastructure will detect the FO
plugin in step 5 and provide a "pdf2" output: this will invoke this FO
output instead of the previous FOP-based output. Invoke with a command
line like:

java -jar lib/dost.jar /i:doc/DITA-readme.ditamap /transtype:pdf2

If you are using the startcmd.bat/sh script, make sure the classpath in that 
script lists saxon.jar before xalan.jar. 

About the index extensions
==========================

The index generation feature adds extensions to DITA's indexterm that can be
expressed as content of that element. These extensions are expressed in a 
FrameMaker-like syntax in the element's textual content, and provide 
functionality not yet available in the standard indexterm element. They also
help migration from legacy FrameMaker content. For example, the following 
generates a "see also" entry:

	<indexterm>Carp:<$nopage>see also Goldfish</indexterm>
	
As:

	Carp, 34
	   see also Goldfish	
	
The extended syntax consists of:

	: (colon)       Separates levels in an entry
	; (semicolon)   Separates entries in a marker
	[] (brackets)   Specifies a special sort order for the entry
	<$startrange>   Indicates the beginning of a page range
	<$endrange>     Indicates the end of a page range
	<$nopage>       Suppresses the page number in the entry (for example, in
	                a See entry)
	<$singlepage>   In a marker that contains several entries, restores the 
	                page number for an entry that follows a <$nopage>
	                building block

DITA 1.1 indexing elements have been implemented in this plugin that
should make these extensions unnecessary. You can now express see/see
also, sort order and page ranges using standard DITA 1.1 elements.

About /Customization
====================

This directory is where the custom files live that make up customized
versions of the FO publishing outputs.  Idiom's FO publishing output will 
look for certain files here to override the standard ones. Things you can 
currently override include:

  - Custom XSL via fo/xsl/custom.xsl and fo/attrs/custom.xsl
  - Layout overrides via fo/layout-masters.xml
  - Font overrides via fo/font-mappings.xml
  - Per-locale variable overrides via common/vars/[locale].xml
  - I18N configuration via fo/i18n/[locale].xml
  - Index configuration via fo/index/[locale].xml

When customizing any of these areas, modify the relevant file(s) in
/Customization.  Then, to enable the changes in the publishing process, 
you find the corresponding entry for each file you modified in 
/Customization/catalog.xml. It should look like this:

    <!--uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/-->

Remove the comment markers "!--" and "--" to enable the change:

    <uri name="cfg:fo/attrs/custom.xsl" uri="fo/attrs/custom.xsl"/>

Your customization should now be enabled as part of the publishing process.

Idiom has provided template files that you can start with throughout
this directory structure.  These files end in the suffix ".orig" (for
example, "catalog.xml.orig").  To enable these files, make a copy of
them and remove the ".orig" suffix.  For example, copy
"catalog.xml.orig" to "catalog.xml".  You can then make modifications
to the copy.

Idiom's FO output also provides a general configuration file called
"build.properties" that allows you to control the publishing process.
To modify these settings, copy "build.properties.orig" to
"build.properties" and then modify the relevant options.

History
=======

FO Plugin Release 1.4.2
Available since Feb 26, 2008

- Misc internal fixes.

Sourceforge bug fixes:
- 1710233: summary element in bookmeta not handled properly (15251)
- 1744350: Navtitle not supported in PDF2
- 1807277: FO topicmerge needs to discard reltables

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

FO Plugin Release 1.4.1
Available since Oct 5, 2007

- more flexible index configuration (see common/index/zh_CN.xml for example)

Sourceforge bug fixes:
- 1793307: issue with topicref in bookmap's <notices> (16587)
- 1791403: invalid column-width attribute value (16586)
- 1805389: XSLT errors in FO plugin
- 1694607: Use-by-reference footnotes not rendered correctly (15249), (not quite right).

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

FO Plugin Release 1.4

- Rebased with Idiom's internal code as of August 28, 2007.
- Updated DITA 1.1 support: new bookmap and indexing elements.
- Minor fixes

Sourceforge bug fixes:
- 1686323: Idiom FO plug-in fails during pdf2 build (15348)
- 1729594: Topichead not supported in pdf2 output (15247) 
- 1647267: Single-step tasks numbers the step (15248)

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

FO Plugin Release 1.2.1

- rebased with Idiom's internal code as of Nov 6, 2006.
- updated copyright/licensing notices in files.
- fixed image copying task for customization.

Sourceforge bug fixes:
- 1574115: Using 1.3 and Idiom FO 1.2 plugin fail
- 1523653: pdf2 transform assumes basedir = ditadir (for real, this time!)

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

FO Plugin Release 1.2
Available since Sept 29, 2006

{'fraction_non_alphanumeric': 0.1129721073001468, 'fraction_numerical': 0.027425597224075803, 'mean_word_length': 3.330251372435712, 'pattern_counts': {'":': 0, '<': 25, '<?xml version=': 0, '>': 25, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 22}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 6, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1023814', 'n_tokens_mistral': 4432, 'n_tokens_neox': 3924, 'n_words': 1973}