<commit_before><?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_pdf2_files">
      <title>Why not edit default pdf2 files?</title>
      <p>When first experimenting with PDF customization, novice users are often tempted to simply edit the default
          <codeph>org.dita.pdf2</codeph> files in place to <xref
          href="https://twitter.com/ThePracticalDev/status/720257210161311744" format="html" scope="external">see what
          happens</xref>.</p>
      <p>As practical as this approach may seem, the DITA-OT project does not recommend changing any of the files in the
          <codeph>plugins</codeph> folder.</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>
      <p>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.</p>
    </section>

    <section id="using_customization_folders">
      <title>Using Customization folders</title>
      <p>Early releases of the <codeph>org.dita.pdf2</codeph> plug-in supported the use of dedicated folders within the
        plug-in to store customized files. Files in <codeph>Customization</codeph> folders automatically 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>
      <p>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 <codeph>org.dita.pdf2/Customization</codeph> folder is located
        within the plug-in’s parent directory, users must be take care to preserve the contents of this folder when
        upgrading to new toolkit versions.</p>
    </section>

    <section id="specifying_remote_customization_folders_via_customization_dir">
      <title>Specifying remote customization folders via customization.dir</title>
      <p>To ensure that overrides in customization folders are not overwritten when upgrading the DITA-OT to a new
        release, a remote customization folder can be specified at build time or in build scripts via the
          <codeph>customization.dir</codeph> parameter.</p>
      <p>This method is preferable to the use of the <codeph>org.dita.pdf2/Customization</codeph> folder, as the
        contents of remote 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 or access rights prevent changes to the toolkit
        installation.</p>
    </section>

    <section id="combining_custom_plug_ins_customization_folders">
      <title>Combining custom plug-ins &amp; customization folders</title>
      <p>A common custom plug-in may be used to store base overrides that are applicable to all company publications,
        and the <codeph>customization.dir</codeph> parameter can be passed at build time to override individual settings
        as necessary for a given project or publication.</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>
      <p>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.</p>
    </section>
  </conbody>
</concept><commit_msg>Copyedit customization approaches draft for 2.3<commit_after><?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
          <codeph>org.dita.pdf2</codeph> 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
          <codeph>plugins</codeph> folder.</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>
      <p>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.</p>
    </section>

    <section id="using_customization_folders">
      <title>Using Customization folders</title>
      <p>Early releases of the <codeph>org.dita.pdf2</codeph> plug-in supported the use of dedicated folders within the
        plug-in to store customized files. Files in <codeph>Customization</codeph> folders automatically 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>
      <p>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 <codeph>org.dita.pdf2/Customization</codeph> folder is located
        within the plug-in’s parent directory, users must be take care to preserve the contents of this folder when
        upgrading to new toolkit versions.</p>
    </section>

    <section id="specifying_remote_customization_folders_via_customization_dir">
      <title>Specifying remote customization folders via <parmname>customization.dir</parmname></title>
      <p>To ensure that overrides in customization folders are not overwritten when upgrading the DITA-OT to a new
        release, a remote customization folder 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 <codeph>org.dita.pdf2/Customization</codeph> folder, as the
        contents of remote 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 or access rights prevent changes to the toolkit
        installation, which may prohibit the installation of custom plug-ins.</p>
    </section>

    <section id="combining_custom_plug_ins_customization_folders">
      <title>Combining custom plug-ins &amp; customization folders</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>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>
      <p>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.</p>
    </section>
  </conbody>
</concept>
{'fraction_non_alphanumeric': 0.061712846347607056, 'fraction_numerical': 0.0034876961829102887, 'mean_word_length': 3.713698630136986, 'pattern_counts': {'":': 0, '<': 145, '<?xml version=': 2, '>': 145, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '660977', 'n_tokens_mistral': 2610, 'n_tokens_neox': 2484, 'n_words': 1236}