-
Notifications
You must be signed in to change notification settings - Fork 96
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'develop' into release/2.3
* develop: (28 commits) Split Migration section into submap Implement additional review feedback Refactor nested <simpletable> in <dl> Refactor long <dl> instances to <parml> Implement review feedback Fix quotes Refactor customization resources Add info on folder structure alternatives Copyedit short descriptions Revise topic order Revise plug-in structure from Customization info Tag file paths & XML mentions Clarify recommendations & adjust terms Add info on migrating PDF customization folders Copyedit customization approaches draft for 2.3 Copyedit plug-in history draft for 2.3 release Adjust notes for recommended resources Add topic on PDF customization approaches for #70 Add content from `pdf2` ReadMe files (Fixes #69) Refactor submap to remove empty topic stubs ...
- Loading branch information
Showing
16 changed files
with
679 additions
and
225 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> | ||
| <!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.--> | ||
|
|
||
| <map> | ||
| <title>Migrating customizations</title> | ||
| <topicref href="migration.dita" locktitle="yes"> | ||
| <topicref href="migrating-to-2.2.dita" navtitle="To 2.2"/> | ||
| <topicref href="migrating-to-2.1.dita" navtitle="To 2.1"/> | ||
| <topicref href="migrating-to-2.0.dita" navtitle="To 2.0"/> | ||
| <topicref href="migrating-to-1.8.dita" navtitle="To 1.8"/> | ||
| <topicref href="migrating-to-1.7.dita" navtitle="To 1.7"> | ||
| <topicref rev="1.7" href="flagging-migration.dita" navtitle="Flagging updates"/> | ||
| </topicref> | ||
| <topicref href="migrating-to-1.6.dita" navtitle="To 1.6"/> | ||
| <topicref href="migrating-to-1.5.4.dita" navtitle="To 1.5.4"/> | ||
| </topicref> | ||
| </map> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.--> | ||
|
|
||
| <concept id="pdf_customization_approaches"> | ||
| <title>PDF customization approaches</title> | ||
| <shortdesc>Various methods may be used to customize the PDF output produced by the DITA Open Toolkit. Each of these | ||
| approaches have advantages and shortcomings that should be considered when preparing a customization project. Some | ||
| of these methods are considered “anti-patterns” with disadvantages that outweigh their apparent appeal. In most | ||
| cases, you should create a custom PDF plug-in.</shortdesc> | ||
|
|
||
| <conbody> | ||
| <section id="why_not_edit_default_files"> | ||
| <title>Why not edit default files?</title> | ||
| <p>When first experimenting with PDF customization, novice users are often tempted to simply edit the default | ||
| <filepath>org.dita.pdf2</filepath> files in place to see what happens.</p> | ||
| <p>As practical as this approach may seem, the DITA-OT project does not recommend changing any of the files in the | ||
| default plug-ins.</p> | ||
| <p>While this method yields quick results and can help users to determine which files and templates control | ||
| various aspects of PDF output, it quickly leads to problems, as any errors may prevent the toolkit from | ||
| generating PDF output.</p> | ||
| <note type="warning">Any changes made in this fashion would be overwritten when upgrading to newer versions of | ||
| DITA-OT, so users that have customized their toolkit installation in this way are often “stuck” on older | ||
| versions of the toolkit and unable to take advantage of improvements in recent versions of DITA-OT.</note> | ||
| </section> | ||
|
|
||
| <section id="the_customization_folder"> | ||
| <title>Using the <filepath>Customization</filepath> folder</title> | ||
| <p>The original Idiom plug-in used its own extension mechanism to provide overrides to the PDF transformation. | ||
| With this approach, a dedicated folder within the plug-in is used to store customized files.</p> | ||
| <p>Files in the <filepath>org.dita.pdf2/Customization</filepath> folder can override their default counterparts, | ||
| allowing users to adjust certain aspects of PDF output without changing any of the plug-in’s default files, or | ||
| specifying additional parameters when generating output.</p> | ||
| <note type="important">While this approach is slightly better than editing default files in place, it can still | ||
| cause problems when upgrading the toolkit to a new version. Since the <filepath>Customization</filepath> folder | ||
| is located within the <filepath>org.dita.pdf2</filepath> plug-in’s parent directory, users must be take care to | ||
| preserve the contents of this folder when upgrading to new toolkit versions.</note> | ||
| <p>Although recent versions of DITA-OT still support this mechanism to ensure backwards compatibility, this | ||
| practice is deprecated in favor of custom PDF plug-ins.</p> | ||
| <note type="tip">Users who have used the <filepath>Customization</filepath> folder to modify the default PDF | ||
| output are encouraged to create a custom PDF plug-in instead. In many cases, this may be as simple as copying | ||
| the contents of the <filepath>Customization</filepath> folder to a new subfolder in the | ||
| <filepath>plugins</filepath> folder and creating the necessary <filepath>plugin.xml</filepath> file and an Ant | ||
| script to define the transformation type as described in the following example.</note> | ||
| </section> | ||
|
|
||
| <section id="external_customization_directories"> | ||
| <title>Specifying an external customization directory</title> | ||
| <p>To ensure that overrides in customization folders are not overwritten when upgrading the DITA-OT to a new | ||
| release, an external customization directory can be specified at build time or in build scripts via the | ||
| <parmname>customization.dir</parmname> parameter.</p> | ||
| <p>This method is preferable to the use of the <filepath>org.dita.pdf2/Customization</filepath> folder, as the | ||
| contents of external folders are unaffected when upgrading DITA-OT. In distributed environments, users can use | ||
| local installations of the DITA-OT, yet still take advantage of common customizations stored in a network | ||
| location available to the entire team, such as a shared drive.</p> | ||
| <p>It can also be useful in environments where corporate policy, CMS permissions, or network access rights prevent | ||
| changes to the toolkit installation, which may prohibit the installation of custom plug-ins.</p> | ||
| <note type="tip">Users who specify external customization directories via <parmname>customization.dir</parmname> | ||
| are encouraged to create a custom PDF plug-in if possible.</note> | ||
| </section> | ||
|
|
||
| <section id="plug_ins_and_customization_folders"> | ||
| <title>Combining custom plug-ins & customization directories</title> | ||
| <p>A common custom plug-in may be used to store base overrides that are applicable to all company publications, | ||
| and the <parmname>customization.dir</parmname> parameter can be passed at build time to override individual | ||
| settings as necessary for a given project or publication.</p> | ||
| <p>In this case, any settings in the customization directory will take precedence over their counterparts in the | ||
| custom plug-in or default <filepath>org.dita.pdf2</filepath> plug-in.</p> | ||
| <p>This approach allows a single custom plug-in to be shared between multiple publications or the entire company, | ||
| without the need to create additional plug-in dependencies per project.</p> | ||
| <p>However, the use of multiple customization mechanisms can make it difficult to debug the precedence cascade and | ||
| determine the origin of local formatting or processing overrides.</p> | ||
| <note type="tip">In most scenarios, the use of dedicated PDF customization plug-ins is preferable. Common | ||
| customizations can be bundled in one plug-in, and any project-specific overrides can be maintained in separate | ||
| plug-ins that build on the base branding or other settings in the common custom plug-in.</note> | ||
| </section> | ||
| </conbody> | ||
| </concept> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.--> | ||
|
|
||
| <concept id="best-practices-pdf-customization-plugins"> | ||
| <title>Best practices for custom PDF plug-ins</title> | ||
| <shortdesc>Adhering to certain development practices will properly isolate your code from that of the DITA Open | ||
| Toolkit. This will make it easier to you to upgrade to new versions of the DITA-OT when they are | ||
| released.</shortdesc> | ||
| <conbody> | ||
| <ul> | ||
| <li>Use a properly-constructed DITA-OT plug-in.</li> | ||
| <li>Use a version control system to store your code.</li> | ||
| <li>Never modify any of the core DITA-OT code.<note type="tip">You may want to set the permissions on the | ||
| <filepath>org.dita.pdf2</filepath> directory to “read-only” to ensure that you do not accidentally modify | ||
| the files within as you develop your customized plug-in.</note></li> | ||
| <li>Avoid copying entire DITA-OT files into your customization plug-in. When you only copy the attribute sets and | ||
| templates that you need to override, there is less risk of impact from new features or fixes in the base code, | ||
| making your code more stable and easier to upgrade between releases.</li> | ||
| <li>If you only need to change a few attribute sets and templates, you may prefer to store your overrides in | ||
| <filepath>custom.xsl</filepath> files, or a simple folder hierarchy within your custom plug-in.</li> | ||
| <li>In cases that require substantial customizations, you may prefer to organize the files in a folder structure | ||
| that mimics the hierarchy of the default PDF plug-in. This method facilitates comparisons with the default | ||
| settings in the base PDF plug-in and makes it easier to migrate customizations to new toolkit versions.</li> | ||
| <li>Upgrade your customization plug-in to new versions of the DITA-OT regularly. Do not wait through several major | ||
| releases before upgrading.</li> | ||
| </ul> | ||
| </conbody> | ||
| </concept> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> | ||
| <!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.--> | ||
|
|
||
| <task id="creating-pdf-customization-plugin"> | ||
| <title>Creating a custom PDF plug-in</title> | ||
| <shortdesc>This topic provides an outline of the primary tasks that are involved in creating a PDF customization | ||
| plug-in.</shortdesc> | ||
| <taskbody> | ||
| <steps> | ||
| <step> | ||
| <cmd>Create a basic DITA-OT plug-in.</cmd> | ||
| <info> | ||
| <p>This requires the following files:</p> | ||
| <ul> | ||
| <li><filepath>plugin.xml</filepath></li> | ||
| <li>Ant build script (some people name this <filepath>build.xml</filepath>; others name this<filepath> | ||
| integrator.xml</filepath>.)<draft-comment author="Kristen Eberlein" time="15 February 2016"> | ||
| <p>I always create a template file. What should we be telling people to do?</p> | ||
| </draft-comment></li> | ||
| </ul> | ||
| </info> | ||
| </step> | ||
| </steps> | ||
| <example/> | ||
| </taskbody> | ||
| </task> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| <?xml version="1.0" encoding="UTF-8"?> | ||
| <!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> | ||
| <!--This file is part of the DITA Open Toolkit project. See the accompanying LICENSE.md file for applicable licenses.--> | ||
|
|
||
| <concept id="types-pdf-customization-plugins"> | ||
| <title>Types of custom PDF plug-ins</title> | ||
| <shortdesc>There are two common types of plug-ins: A plug-in that simply sets the DITA-OT parameters to be used when a | ||
| PDF is generated, and a plug-in that overrides aspects of the base DITA-OT PDF transformation. A plug-in can, of | ||
| course, do both of these things.</shortdesc> | ||
| <conbody> | ||
| <section> | ||
| <title>Plug-in that only provides DITA-OT parameters</title> | ||
| <p>You might want to build a transformation type that uses a transformation as-is; however, you might want ensure | ||
| that certain DITA-OT parameters are used. For example, consider the following scenario:</p> | ||
| <p>You want to ensure that PDFs generated for internal review have the following characteristics:</p> | ||
| <ul> | ||
| <li>Use company style sheets</li> | ||
| <li>Make draft comments visible to the reviewers, as they contain queries from the information developers</li> | ||
| <li>Print the file names of the graphics underneath figures, so that graphic artists can more quickly respond to | ||
| requested changes</li> | ||
| </ul> | ||
| <p>To accomplish this, you can create a new plug-in. In the Ant script that defines the transformation type, | ||
| specify the DITA-OT parameters. For example, to render draft comments and art labels, add | ||
| <xmlelement>property</xmlelement> elements to specify the DITA-OT parameters:</p> | ||
| <codeblock><?xml version='1.0' encoding='UTF-8'?> | ||
| <project name="com.example.draft.pdf"> | ||
| <target name="dita2draft.pdf.init"> | ||
| <property name="customization.dir" location="${dita.plugin.com.example.draft.pdf.dir}/cfg"/> | ||
| <b><property name="args.draft" value="yes"/></b> | ||
| <b><property name="args.artlbl" value="yes"/></b> | ||
| </target> | ||
| <target name="dita2draft.pdf" depends="dita2draft.pdf.init, dita2production.pdf,dita2pdf2"/> | ||
| </project></codeblock> | ||
| </section> | ||
| <section> | ||
| <title>Plug-in that overrides the base PDF transformation</title> | ||
| <p>Production uses of the DITA-OT typically rely on a custom PDF plug-in to render PDFs that are styled to | ||
| match corporate or organizational guidelines. Such customization plug-ins often override the following aspects | ||
| of the DITA-OT's default output:</p> | ||
| <ul> | ||
| <li>Generated text strings</li> | ||
| <li>XSL templates</li> | ||
| <li>XSL-FO attribute sets</li> | ||
| </ul> | ||
| </section> | ||
| </conbody> | ||
| </concept> |
Oops, something went wrong.