From 486887b80ed5fed21d7326ea1c89e512bafbe444 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Sun, 6 Nov 2016 22:43:10 +0100 Subject: [PATCH 01/17] Bump 'release' & 'maintenance-version' keys to 2.4 Signed-off-by: Roger Sheen --- resources/key-definitions.ditamap | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap index b390a0d01..ac7364e65 100644 --- a/resources/key-definitions.ditamap +++ b/resources/key-definitions.ditamap @@ -39,7 +39,7 @@ - 2.3 + 2.4 @@ -48,7 +48,7 @@ - 2.3.3 + 2.4 From f550a29f95c8863379ec65ae0df15e3ba6cd3a16 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 7 Nov 2016 14:42:31 +0100 Subject: [PATCH 02/17] Archive 2.3 Release Notes for posterity Signed-off-by: Roger Sheen --- release-notes/rel2.3.dita | 659 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 659 insertions(+) create mode 100644 release-notes/rel2.3.dita diff --git a/release-notes/rel2.3.dita b/release-notes/rel2.3.dita new file mode 100644 index 000000000..6320392ea --- /dev/null +++ b/release-notes/rel2.3.dita @@ -0,0 +1,659 @@ + + + + + + DITA Open Toolkit <keyword keyref="maintenance-version"/> Release Notes + + + DITA Open Toolkit is a maintenance release that fixes issues + reported in DITA-OT , which includes . +

Issue numbers correspond to the tracking number in the + GitHub issues tracker.

+ + + + Maintenance Release <keyword keyref="maintenance-version"/> + +
+

DITA Open Toolkit Release includes the following bug fixes.

+
    +
  • Lax processing now tolerates hyperlink references with leading or trailing whitespace in the + href attribute value, such as: + <xref href=" http://www.example.com" format="html"> Earlier versions of DITA-OT + would convert the space to its URL-encoded equivalent %20 and fail with an error. The URI + validation routines have been modified to issue a warning and continue processing in lax mode, but still + fail in strict mode. + #2440, + #2488 +
    • +
  • In certain cases, earlier versions of DITA-OT resolved relative paths to related links from the + temporary directory rather than from the input DITA map file. Processing has been modified to ensure that + links are generated correctly regardless of the target file location. + #2017, + #2444 +
    • +
  • Several errors in the DITA 1.3 subjectScheme catalog file were corrected to + ensure that the module files and entities for the DITA Map Subject Classification Domain are properly + resolved. Corresponding errata have been submitted to OASIS to ensure the fixes are applied to the official + catalogs. + #2458 +
    • +
  • Related link processing has been adjusted to handle cases that generate empty related links + groups. + #2464 +
    • +
  • The mappull preprocessing step that pulls content from referenced topics into + maps has been updated to use the XML catalog to resolve external entity references to their locally cached + equivalents. + #2470 +
    • +
  • In PDF output generated by earlier versions of DITA-OT, roman numerals were used to number pages + in the Notices section, assuming notices are most commonly located in the front matter, which uses roman + numbering by default. The toolkit now checks whether the notices element is inside + backmatter, and uses arabic numbering as appropriate. + #2474 +
    • +
  • When processing topics with unsupported languages, DITA-OT erroneously claimed it couldn't find + the language en_us rather than mentioning the unsupported language. The + DOTX001W message now includes the original, most complete value of the ancestor language + to assist in troubleshooting. + #2477 +
    • +
  • In DITA-OT 2.3.2, reference targets for link-like elements such as + abbreviated-form in short descriptions were incorrectly calculated in some cases. + Processing has been updated to ensure that links are correctly resolved by adjusting references as necessary + to match the path to the target document. + #2482 +
    • +
  • The copy-to processing routine failed to update image paths, resulting in invalid references in + topics copied to locations other than the original or peer directories. Processing has been updated to + ensure that image references are adjusted as necessary to reflect the location of the referencing document. + #2486 +
    • +
  • PDF: Definitions for several missing localization variables have been added to the Finnish, + Romanian, Russian, and Swedish strings files. + #2487 +
    • +
+

For the complete list of changes since the previous release, see the + + changelog on GitHub.

+
+ + + + + Maintenance Release 2.3.2 + +
+

DITA Open Toolkit Release 2.3.2 included the following bug fixes.

+
    +
  • In earlier versions of DITA-OT, relative paths to cross-references from short descriptions were + sometimes interpreted incorrectly if the source and target topics were located in different directories. New + XSL functions now ensure that these references are correctly resolved. + #1599 +
    • +
  • In DITA-OT 2.3, the HTML5 transtype failed on topics with tables when the + args.xhtml.classattr parameter was set to . Processing has been + updated to handle these cases and correctly exclude the DITA class ancestry information when publishing + HTML5 output. + #2413, + #2424 +
    • +
  • In DITA-OT 2.3, the PDF2 build target dependency list contained redundant entries. The + integration process has been corrected to remove the duplicates. + #2439, + #2451 +
    • +
  • The script that checks for Antenna House installations has been updated to include installation + paths with spaces as used by recent versions of Antenna House for Windows – + C:\Program Files\Antenna House and the (x86) equivalent. + #2441 +
    • +
+

For the complete list of changes since the previous release, see the + + changelog on GitHub.

+
+ + + + + Maintenance Release 2.3.1 + +
+

DITA Open Toolkit Release 2.3.1 included the following bug fixes.

+
    +
  • The distribution package for the 2.3 release included several unnecessary subfolders and + appended the Git commit ID to the version number in the lib/configuration.properties + file. The extra directories have been removed and the otversion in the properties file has + been corrected. + #2395 +
    • +
  • In DITA-OT 2.3, temporary file folders specified via the dita.temp.dir + parameter were interpreted as relative to the folder where the Java process started. This regression has + been fixed to ensure that temporary folders are once again interpreted as relative to the base directory of + the Ant process as in previous toolkit versions. + #2398 +
    • +
  • On Windows, the dita command would not run correctly if the name of a folder + in the path to the DITA-OT 2.3 installation directory included spaces. The dita.bat + script has been modified to support installation paths with spaces. + #2400 +
    • +
  • The DITA 1.3 DTD, Schema, and RNG files have been updated to the final "OASIS Standard" copy; + this change updates the OASIS link and date in many header files, but does not affect how the grammar files + work. In addition, the catalog has been updated to restore two entries that will eventually be shipped in + the DITA 1.3 Errata from OASIS. + #2401 +
    • +
  • Fixed an issue where some front-matter sections, such as draftintro and + bookabstract, caused page numbering to switch back and forth between Roman + numerals and body-style Arabic numerals. + #2408 +
    • + +
+

For the complete list of changes since the previous release, see the + + changelog on GitHub.

+
+ + + + + Requirements + +
+ Add info on new minimum Java version or any other requirements that have changed + since previous release. +

DITA Open Toolkit Release requires the Java Runtime Environment (JRE) version + or later.

+
+ + + + + Release Highlights + DITA-OT includes enhanced HTML5 output, new language support + and additional internationalization improvements. + +
+ Single .zip distribution package +

DITA Open Toolkit now ships as a single distribution package in a .zip + archive, as modern versions of Linux and OS X no longer have the file permission issues that originally + required the additional .tar.gz distribution package. + #2269 +

+
+
+ Enhanced HTML5 output +

The table processing has been refactored to use valid HTML5 markup, HTML5 + best practices, and better CSS properties for styling. + BEM-style CSS classes are + now generated with the name of the containing element, the name of the attribute, and the value of the + attribute. + #2239 +

+

Common CSS files are now generated using separate modules for each DITA domain, implemented as + partials to better support extensions with CSS frameworks, custom plug-ins and + future toolkit versions. + #2195, + #2196, + #2218, + #2369 +

+
+
+ New language support +

The transformation has been extended to support additional languages with + localized strings files and index collation. + #2137, + #2344 +

    +
  • Belarusian
    • +
  • Bulgarian
    • +
  • Chinese (traditional), with limited support for index sorting
    • +
  • Estonian
    • +
  • Greek
    • +
  • Hindi
    • +
  • Indonesian
    • +
  • Kazakh
    • +
  • Korean
    • +
  • Lithuanian
    • +
  • Macedonian
    • +
  • Malay
    • +
  • Serbian (Cyrillic script)
    • +
  • Serbian (Latin script)
    • +
  • Thai
    • +
  • Ukrainian
    • +
  • Urdu
    • +
+

+

, , and transformation types have been + updated to support Bosnian, Montenegrin, and Vietnamese, including localized string files and (for + ) index collation. + #2150, + #2360 +

+
+
+ Internationalization improvements +

Along with the new languages supported by the and transformations, + DITA Open Toolkit Release provides additional internationalization improvements, + including: +

    +
  • When testing for bi-directional content, more languages are now recognized as right-to-left. + No additional support is added (for example, generated strings for new languages will appear using the + DITA-OT default language), but otherwise content will use the proper direction by default. Arabic, Urdu, + and Hebrew are already recognized by default; this change recognizes an additional 14 languages. + #1710, + #2267 +
    • +
  • PDF: Additional fallback fonts have been specified in the + font-mappings.xml file to provide better out-of-the-box support for Asian + characters. + #2279, + #2280, + #2296 +
    • +
  • HTML: Earlier releases of DITA-OT 2.x generated a style attribute with + text-align:left on table cells, regardless of whether the align + attribute was set in the source. This caused problems with right-to-left languages. The default entry + alignment has been removed, so the values of the xml:lang and dir + attributes on the root of the topic will be respected. (This allows the browser to infer the value for the + text-align property from the parent elements/styles.) + #2302, + #2368 +
    • +
  • PDF: The Dutch variable file now includes translations for Glossary, List of tables, and List + of figures. In addition, German, Italian, French, and Spanish have been updated to define missing + variables, including one that previously resulted in a build error ("Table of Contents Notices"). + #2131, + #2343 +
    • +
  • The DITA-OT configuration value default.language is now used as the default + language in all output formats. The value ships as en, but can be changed in + configuration.properties or specified as a parameter to the build. For HTML output, + the default is now the closest specified language; if a document does not specify + xml:lang, default.language is used. For PDF output, the default is the + closest specified language; if a document does not specify xml:lang, the root map is + used; if the root map does not specify xml:lang, default.language is + used. + #1476, + #2201, + #2356, + #2357 +
    • +
+

+
+ + + + + Resolved issues + In addition to the highlights mentioned above, DITA Open Toolkit Release + includes the following changes. + +
+ Features +

DITA Open Toolkit Release includes the following new features:

+
    +
  • The args.eclipsehelp.toc parameter for Eclipse Help, which has not worked + properly for several releases after it was made obsolete in DITA-OT 1.3, has been removed. + #1116, + #2354 +
    • +
  • DITA 1.3: Initial support has been added for the orient attribute on + table elements. These changes allow Antenna House Formatter to render tables in + landscape mode when the orient attribute is set to . A future release + will provide extended support for multi-page landscape tables with additional rendering engines. + #1777, + #2387 +
    • +
  • To permit automated building and testing on any platform, the HTMLHelp version of the + documentation is no longer included in the distribution package. An HTMLHelp version of the documentation + can still be built on Windows using the downloaded distribution package. + #2130 +
    • +
  • SAX pipes can now be configured in Ant pipeline tasks. This allows new + tasks to take advantage of in-memory processing without the need to write out files to disk. + #2144 +
    • +
  • The process for generating topic headers in the transformation type has + been simplified to use a single template with mode="insertTopicHeaderMarker". This reduces + the amount of work needed to format titles differently in the header and body. + #2155 +
    • +
  • The transformation type supports two new extension points + dita.conductor.html5.param and dita.conductor.html5.toc.param, allowing + plugins to provide new parameters for HTML5 processing. + #2185 +
    • +
  • Processing for copy-to has been moved out of the gen-list + preprocessing module and into a separate step. This improves processing for + topicref elements that use copy-to and keyref. + #2210 +
    • +
  • The DITA-OT preprocessing step that reads images for information about height and width now + supports reading dimension metadata from SVG images. + #2230 +
    • +
  • The transformation type has been updated to support the + expanse value "page" for elements that use the attribute. In addition, the + msgblock element has been updated to support frame and + scale, which generally appear on the same elements that use expanse. + #2317, + #2352 +
    • +
  • Cross-references to footnotes now generate hyperlinks in PDF output. + #2359, + #2364 +
    • +
+
+ +
+ Enhancements +

DITA Open Toolkit Release includes the following enhancements and changes to + existing features:

+
    +
  • PDF: Information from the README.txt files in the + org.dita.pdf2 plugin have been moved to the “PDF plug-in structure” topic in the DITA + Open Toolkit Developer Reference. Now that all useful information is available in the + documentation, the README.txt files have been removed. + #1860 +
    • +
  • PDF: In earlier versions of DITA-OT, filtering out all rows from a + simpletable element resulted in invalid XSL-FO. When all rows are filtered out, + the XSL-FO file now contains an empty (but valid) table so that processing can continue. + #1924, + #1950 +
    • +
  • Guava libraries are now used to simplify access to collections in Java code (among other + things). + #2122 +
    • +
  • HTML: The documentation for the and options + now clarifies that header and footer files must be specified using an absolute path. The options have always + required an absolute path, but the documentation for earlier releases did not include this requirement. + #2133 +
    • +
  • The dita command will now run using Java headless mode by default. This + optimizes the use of system resources during a build and prevents the build process from stealing focus from + other applications. + #2140 +
    • +
  • HTML: Static text for XHTML tables and figures (such as "Table 5") is now surrounded with a + span element, making it easier to style or hide the static text using CSS. In + addition, HTML5 output is updated to use semantic elements for figure and table captions. + #2160 +
    • +
  • Two members of the AbstractPipelineModuleImpl class have been marked as + protected, to allow plugins to access them from derived classes. + #2177 +
    • +
  • PDF: The I18N Java and XSLT processing code has been merged into single task. This is not + visible to most users of the PDF code, apart from a reduction in processing time. It also eliminates the + need for a stage3.fo file in the temporary directory; instead, + topic.fo is generated directly from stage2.fo. + #2179 +
    • +
  • In a previous release, the HTML5 extension point dita.conductor.html5.param was + declared but not implemented. The improper declaration was removed and the extension was properly + implemented. + #2181 +
    • +
  • HTML: In previous releases, short descriptions in abstract elements + were rendered as division elements (div), rather than paragraphs + (p). Processing has been revised to ensure that short descriptions are + consistently rendered as paragraphs, regardless of whether they appear in abstract + elements. + #2191 +
    • +
  • The order of the chunk and move-meta-entries pre-processing + stages has been switched so that chunk comes first. This ensures that metadata is properly + pulled or pushed into the chunked version of DITA topics. + #2207 +
    • +
  • HTML: The process for handling othertype on a note + element in HTML has been updated to use XSLT 2.0 best practices. + #2217 +
    • +
  • PDF: Earlier versions used an fo:inline element as a link target within + topic titles, which can result in extra white space for certain common customizations. The process now + places an ID on fo:wrapper, which removes the extra element and extra white space. + #2229 +
    • +
  • XSLT processing now uses a single parameter for message IDs rather than combining one parameter + for the error number with another parameter for severity. This simplifies message processing and allows a + greater range of message IDs in the future. In addition, the DOTX071W message will display + a warning for customizations that use the older, deprecated parameters. + #2231 +
    • +
  • Common XSLT utility templates have been rewritten as functions. In addition, XSpec tests have + been created so that the functions are now covered by automated DITA-OT testing. + #2233 +
    • +
  • The distribution integration and docs stages of the build process are now run in a forked JVM . + #2241 +
    • +
  • PDF: A reference to the PDF2 catalog has been added to catalog-dita.xml. In + previous releases, running topic2fo_shell.xsl directly would fail because the XSLT + processor couldn't resolve paths that use the cfg: scheme. + #2249 +
    • +
  • The distribution package is now built via a fully automated Continuous Integration process. + #2268 +
    • +
  • HTML5: A new stable ID generation process has been implemented, instead of relying on the + generate-id() function. By removing reliance on a dynamic value, this change enables + automated testing of id and headers (generated for table accessibility). + This also speeds up regression testing when comparing HTML output with previous versions. + #2276 +
    • +
  • A new ditaFileset function has been implemented to replace list files. This has no visible + impact for builds, but improves the processing model overall and allows the older way of working with + individual list files to be deprecated in a future release. + #2277 +
    • +
  • The build script for HTMLHelp, build_dita2htmlhelp.xml, now uses an + environment variable to locate the HTMLHelp compiler. This allows the process to build a CHM file when the + HTML Help Workshop is not installed on the C: drive. + #2288 +
    • + +
  • HTML5: new extension points allow for customization of HTML5 output, HTML5 TOC processing, and + HTML5 cover processing. These extension points were declared (but not implemented) in DITA-OT 2.2; this was + addressed in 2.2.5 by removing the declarations. In DITA-OT 2.3, the declarations are restored and properly + implemented. + #2305 +
    • +
  • The startcmd scripts are now generated by the DITA-OT integration process. + This ensures that the CLASSPATH setting in the scripts is updated with any new or required + Java libraries referenced by custom plug-ins. + #2341 + Users who still run DITA-OT using a custom start script based on a copy of + startcmd may need to update their script after installing custom plug-ins. The + CLASSPATH declarations are stored in alphabetical order, so they should only change + when new plug-in libraries are added. To avoid these issues, run DITA-OT using the dita + command instead of the deprecated startcmd scripts.
    • +
  • PDF: Index group headings now appear in the PDF bookmarks. The new bookmarks will always appear + in collapsed form under the Index heading. For example, a large index that covers every heading in English + will now have bookmarks for "Special characters", "Numerics", and every letter from "A" to "Z". + #2350 +
    • +
  • PDF: The antiquewhite background color has been removed from table heads and + key column contents in simpletable and properties tables + to synchronize presentation with choicetable and provide a more uniform + customization baseline between PDF output and HTML-based formats. + #2382, + #2386 +
    • +
  • Localization variables that are no longer used in PDF processing have been deprecated and will + be removed in an upcoming release. + #2383 +
    • +
+
+ +
+ Bugs +

DITA Open Toolkit Release provides fixes for the following bugs:

+
    +
  • PDF: The message "No topicTitleNumber mode template" has been removed. This removes extraneous + messages that appeared when processing a bookmap with notices or + bookabstract, or which refers to a subject scheme map. + #1931 +
    • +
  • HTML: trademark symbols previously only appeared for tm elements in + English and a select few languages. This was a legacy of processing carried over from beta processing before + DITA-OT 1.0; HTML trademark processing will now work the same regardless of document language. + #2065 +
    • +
  • Processing for coderef elements could be broken when the + coderef was part of a larger section reused by conref. This is fixed by resolving + coderef during the topic-fragment step of preprocessing. + #2141 +
    • +
  • The AXF document-info attribute title is deprecated; XSL-FO output for Antenna + House output should use the document-title attribute instead. + #2161, + #2162 +
    • +
  • When using keys, referencing a file outside of the current directory causes processing to fail. + Previously, the target file URI was resolved against the root of the temp directory. This has been updated + to resolve the URI against the source file URI, which should always yield the correct result. + #2190, + #2223 +
    • +
  • In previous releases, specializations of the link element did not work + as intended. The corresponding XSLT template mode related-links:link has been modified to + properly handle new elements that are based on the link element. + #2197, + #2199 +
    • +
  • Circular key definitions, when an element used keyref to refer to a key on the + same element, resulted in a stack overflow in KeydefReader. This construct is now reported as an error with + message DOTJ069E. + #2227 +
    • + +
  • Publishing failed when using term with keyref and chunking, as the + chunking module created file references with backslashes. Processing has been updated to convert any + backslashes to slashes before using the resolve-uri function in XSLT. This ensures that the + attribute values are valid URI references according to + . + #2243 +
    • +
  • PDF: In the simplified Chinese variables file (zh-CN), additional translations have been + provided for some static strings that previously appeared in English. + #2294, + #2353 +
    • +
  • Resource-only topic references were considered duplicates by key processing, resulting in + renamed output files in some cases. The resource-only instances are now ignored when determining whether to + rename output files. + #2304 +
    • +
  • PDF code was cleaned up to remove a broken message that could not be triggered + #2326, + #2351 +
    • +
  • In previous releases, specifying a keyscope attribute on the root + map element would cause builds to fail. Processing has been modified to handle + this situation correctly. + #2339 +
    • +
+
+ +
+ Contributors +

DITA Open Toolkit Release includes + by the following people:

+ +
    +
  1. Jarno Elovirta
    2. +
  2. Robert D. Anderson
    3. +
  3. Eero Helenius
    4. +
  4. Roger Sheen
    5. +
  5. Eliot Kimber
    6. +
  6. Radu Coravu
    7. +
  7. Shane Taylor
    8. +
  8. Stefan Eike
    9. +
  9. George Bina
    10. +
  10. Kristen James Eberlein
    11. +
+

For the complete list of changes since the previous release, see the + + changelog on GitHub.

+
+ +
+ Documentation updates +

The documentation for DITA Open Toolkit Release includes corrections and + improvements to existing topics, along with several notable enhancements, including:

+
    +
  • The DITA Open Toolkit User Guide includes new topics on additional methods of publishing via + the dita command: +
      +
    • + +
      • +
    • + +
      • +
    +
    • +
  • The DITA Open Toolkit Developer Reference includes several new sections dedicated to + customization: +
      +
    • + provides an overview of approaches commonly used to customize the + default PDF output and includes recommendations on best practices and additional resources.
      • +
    • + highlights customization-related changes in recent releases to assist plug-in + developers in updating overrides to work with the latest toolkit versions.
      • +
    +
    • +
  • +

    + Travis CI continuous integration + is used to automatically publish the latest development version of the documentation on the project + website at + dita-ot.org/dev whenever + changes are pushed to the develop branch of the + dita-ot/docs repository + on GitHub.

    • +
  • +

    In the latest + development version of the + documentation, page footers now include Edit this page links that open the DITA + source file for the topic in + oXygen XML Web + Author.

    +

    The web-based authoring workflow prompts users to log in to GitHub and fork the + dita-ot/docs repository + if necessary. Changes saved in the authoring environment are committed to a new branch, and a pull request + is created to submit changes for review by the DITA-OT documentation team.

    +
    • +
+

For additional information on documentation issues resolved in DITA Open Toolkit Release , see the + + milestone in the documentation repository.

+

For the complete list of documentation changes since the previous release, see the + + changelog.

+
+ + + From dbd01911eb332614c6f49cf036c7fc1eee5cb8dc Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 7 Nov 2016 15:19:30 +0100 Subject: [PATCH 03/17] Update FOP version key & add FOP Release Notes keys Signed-off-by: Roger Sheen --- resources/key-definitions.ditamap | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap index ac7364e65..6de413817 100644 --- a/resources/key-definitions.ditamap +++ b/resources/key-definitions.ditamap @@ -115,7 +115,7 @@ - 1.1 + 2.1 @@ -136,6 +136,21 @@ + + + + + Apache FOP 2.0 Release Notes + + + + + Apache FOP 2.1 Release Notes + + + From c6c13063df2e9cdc60f93e7777bc6f1434680f13 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 7 Nov 2016 19:34:04 +0100 Subject: [PATCH 04/17] Add IDs to facilitate re-use Signed-off-by: Roger Sheen --- user-guide/extended-functionality.dita | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/user-guide/extended-functionality.dita b/user-guide/extended-functionality.dita index 3524c9faa..f34ae6b07 100644 --- a/user-guide/extended-functionality.dita +++ b/user-guide/extended-functionality.dita @@ -58,12 +58,14 @@ Line range by content

Instead of specifying line numbers, you can also select lines to include in the code reference by specifying keywords (or “tokens”) that appear in the referenced file.

-

DITA-OT supports the token pointer in the URI fragment to extract a line range based on the - file content. The format for referencing a range of lines by content is:

- uri ("#token=" start? ("," end)? )? -

Lines identified using start and end tokens are exclusive: the lines that contain the start token and end token - will be not be included. If the start token is omitted, the range starts from the first line in the file; if the - end token is omitted, the range ends on the last line of the file.

+
+

DITA-OT supports the token pointer in the URI fragment to extract a line range based on the + file content. The format for referencing a range of lines by content is:

+ uri ("#token=" start? ("," end)? )? +

Lines identified using start and end tokens are exclusive: the lines that contain the start token and end + token will be not be included. If the start token is omitted, the range starts from the first line in the + file; if the end token is omitted, the range ends on the last line of the file.

+

Given a Haskell source file named fact.hs with the following content,

@@ -78,9 +80,10 @@ fact :: Int -> Int fact 0 = 1 fact n = n * fact (n-1) - This approach can be used to reference code samples that are frequently edited. In these cases, - referencing line ranges by line number can be error-prone, as the target line range for the reference may shift - if preceding lines are added or removed. Specifying ranges by line content makes references more robust, as long - as the token keywords are preserved when the referenced resource is modified. + This approach can be used to reference code samples that are + frequently edited. In these cases, referencing line ranges by line number can be error-prone, as the target line + range for the reference may shift if preceding lines are added or removed. Specifying ranges by line content + makes references more robust, as long as the token keywords are preserved when the referenced + resource is modified. From 9a682b73fec49a38b0c4acc7091e4e0973c51ed8 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Mon, 7 Nov 2016 21:31:08 +0100 Subject: [PATCH 05/17] Draft 2.4 Release Highlights Signed-off-by: Roger Sheen --- release-notes/index.dita | 624 +++--------------------------- resources/key-definitions.ditamap | 7 + 2 files changed, 64 insertions(+), 567 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index 6320392ea..0cb76f29e 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -2,170 +2,16 @@ - + DITA Open Toolkit <keyword keyref="maintenance-version"/> Release Notes - DITA Open Toolkit is a maintenance release that fixes issues - reported in DITA-OT , which includes . + DITA Open Toolkit is a feature release that provides new features and + enhancements, including .

Issue numbers correspond to the tracking number in the GitHub issues tracker.

 - - Maintenance Release <keyword keyref="maintenance-version"/> - -
-

DITA Open Toolkit Release includes the following bug fixes.

-
    -
  • Lax processing now tolerates hyperlink references with leading or trailing whitespace in the - href attribute value, such as: - <xref href=" http://www.example.com" format="html"> Earlier versions of DITA-OT - would convert the space to its URL-encoded equivalent %20 and fail with an error. The URI - validation routines have been modified to issue a warning and continue processing in lax mode, but still - fail in strict mode. - #2440, - #2488 -
    • -
  • In certain cases, earlier versions of DITA-OT resolved relative paths to related links from the - temporary directory rather than from the input DITA map file. Processing has been modified to ensure that - links are generated correctly regardless of the target file location. - #2017, - #2444 -
    • -
  • Several errors in the DITA 1.3 subjectScheme catalog file were corrected to - ensure that the module files and entities for the DITA Map Subject Classification Domain are properly - resolved. Corresponding errata have been submitted to OASIS to ensure the fixes are applied to the official - catalogs. - #2458 -
    • -
  • Related link processing has been adjusted to handle cases that generate empty related links - groups. - #2464 -
    • -
  • The mappull preprocessing step that pulls content from referenced topics into - maps has been updated to use the XML catalog to resolve external entity references to their locally cached - equivalents. - #2470 -
    • -
  • In PDF output generated by earlier versions of DITA-OT, roman numerals were used to number pages - in the Notices section, assuming notices are most commonly located in the front matter, which uses roman - numbering by default. The toolkit now checks whether the notices element is inside - backmatter, and uses arabic numbering as appropriate. - #2474 -
    • -
  • When processing topics with unsupported languages, DITA-OT erroneously claimed it couldn't find - the language en_us rather than mentioning the unsupported language. The - DOTX001W message now includes the original, most complete value of the ancestor language - to assist in troubleshooting. - #2477 -
    • -
  • In DITA-OT 2.3.2, reference targets for link-like elements such as - abbreviated-form in short descriptions were incorrectly calculated in some cases. - Processing has been updated to ensure that links are correctly resolved by adjusting references as necessary - to match the path to the target document. - #2482 -
    • -
  • The copy-to processing routine failed to update image paths, resulting in invalid references in - topics copied to locations other than the original or peer directories. Processing has been updated to - ensure that image references are adjusted as necessary to reflect the location of the referencing document. - #2486 -
    • -
  • PDF: Definitions for several missing localization variables have been added to the Finnish, - Romanian, Russian, and Swedish strings files. - #2487 -
    • -
-

For the complete list of changes since the previous release, see the - - changelog on GitHub.

-
- - - - - Maintenance Release 2.3.2 - -
-

DITA Open Toolkit Release 2.3.2 included the following bug fixes.

-
    -
  • In earlier versions of DITA-OT, relative paths to cross-references from short descriptions were - sometimes interpreted incorrectly if the source and target topics were located in different directories. New - XSL functions now ensure that these references are correctly resolved. - #1599 -
    • -
  • In DITA-OT 2.3, the HTML5 transtype failed on topics with tables when the - args.xhtml.classattr parameter was set to . Processing has been - updated to handle these cases and correctly exclude the DITA class ancestry information when publishing - HTML5 output. - #2413, - #2424 -
    • -
  • In DITA-OT 2.3, the PDF2 build target dependency list contained redundant entries. The - integration process has been corrected to remove the duplicates. - #2439, - #2451 -
    • -
  • The script that checks for Antenna House installations has been updated to include installation - paths with spaces as used by recent versions of Antenna House for Windows – - C:\Program Files\Antenna House and the (x86) equivalent. - #2441 -
    • -
-

For the complete list of changes since the previous release, see the - - changelog on GitHub.

-
- - - - - Maintenance Release 2.3.1 - -
-

DITA Open Toolkit Release 2.3.1 included the following bug fixes.

-
    -
  • The distribution package for the 2.3 release included several unnecessary subfolders and - appended the Git commit ID to the version number in the lib/configuration.properties - file. The extra directories have been removed and the otversion in the properties file has - been corrected. - #2395 -
    • -
  • In DITA-OT 2.3, temporary file folders specified via the dita.temp.dir - parameter were interpreted as relative to the folder where the Java process started. This regression has - been fixed to ensure that temporary folders are once again interpreted as relative to the base directory of - the Ant process as in previous toolkit versions. - #2398 -
    • -
  • On Windows, the dita command would not run correctly if the name of a folder - in the path to the DITA-OT 2.3 installation directory included spaces. The dita.bat - script has been modified to support installation paths with spaces. - #2400 -
    • -
  • The DITA 1.3 DTD, Schema, and RNG files have been updated to the final "OASIS Standard" copy; - this change updates the OASIS link and date in many header files, but does not affect how the grammar files - work. In addition, the catalog has been updated to restore two entries that will eventually be shipped in - the DITA 1.3 Errata from OASIS. - #2401 -
    • -
  • Fixed an issue where some front-matter sections, such as draftintro and - bookabstract, caused page numbering to switch back and forth between Roman - numerals and body-style Arabic numerals. - #2408 -
    • - -
-

For the complete list of changes since the previous release, see the - - changelog on GitHub.

-
- - - Requirements @@ -180,118 +26,56 @@ Release Highlights - DITA-OT includes enhanced HTML5 output, new language support - and additional internationalization improvements. + DITA-OT includes Apache FOP , + a new long-form syntax for dita command options, and additional code referencing + extensions. -
- Single .zip distribution package -

DITA Open Toolkit now ships as a single distribution package in a .zip - archive, as modern versions of Linux and OS X no longer have the file permission issues that originally - required the additional .tar.gz distribution package. - #2269 -

-
-
- Enhanced HTML5 output -

The table processing has been refactored to use valid HTML5 markup, HTML5 - best practices, and better CSS properties for styling. - BEM-style CSS classes are - now generated with the name of the containing element, the name of the attribute, and the value of the - attribute. - #2239 -

-

Common CSS files are now generated using separate modules for each DITA domain, implemented as - partials to better support extensions with CSS frameworks, custom plug-ins and - future toolkit versions. - #2195, - #2196, - #2218, - #2369 -

+
+ Apache FOP <ph keyref="tool.fop.version"/> +

DITA-OT bundles the latest version of Apache FOP (Formatting Objects Processor). + #1958, + #2399

+

FOP builds on the OpenType CFF font support added in FOP 2.0, with additional + font support and enhancements for PDF accessibility, including PDF/UA (PDF/Universal Accessibility) and + PDF/A-3.

+

For details on recent changes in FOP, see the Release Notes for versions + 2.0 and + 2.1.

+ To conserve memory, accessible PDF output is disabled by default in FOP 2.1. To generate accessible PDFs + from DITA-OT, set the args.fo.userconfig parameter and include the + option in your custom FOP configuration file. +

For more information, see + .
-
- New language support -

The transformation has been extended to support additional languages with - localized strings files and index collation. - #2137, - #2344 -

    -
  • Belarusian
    • -
  • Bulgarian
    • -
  • Chinese (traditional), with limited support for index sorting
    • -
  • Estonian
    • -
  • Greek
    • -
  • Hindi
    • -
  • Indonesian
    • -
  • Kazakh
    • -
  • Korean
    • -
  • Lithuanian
    • -
  • Macedonian
    • -
  • Malay
    • -
  • Serbian (Cyrillic script)
    • -
  • Serbian (Latin script)
    • -
  • Thai
    • -
  • Ukrainian
    • -
  • Urdu
    • -
-

-

, , and transformation types have been - updated to support Bosnian, Montenegrin, and Vietnamese, including localized string files and (for - ) index collation. - #2150, - #2360 +

+ New long-form syntax for <cmdname>dita</cmdname> command options +

All dita command options can now be specified with a GNU-style option keyword preceded by + two hyphens. For example:

+

+ dita --input=userguide.ditamap --format=

+

DITA-OT parameters can now be passed to the dita command with this same syntax: + --parameter=value.

+

When set with this method, properties are validated against the toolkit’s plug-in configuration. An error + message appears if a property is not recognized or if an enumerated property value is invalid. + #2422, + #2492 + Unix-style single-letter options (preceded by a single hyphen) are also available in + some cases for backwards compatibility. The X-Toolkit–style single-hyphen keyword variants supported by + previous releases (such as -input) have been deprecated and may be removed in an + upcoming release.

-
- Internationalization improvements -

Along with the new languages supported by the and transformations, - DITA Open Toolkit Release provides additional internationalization improvements, - including: -

    -
  • When testing for bi-directional content, more languages are now recognized as right-to-left. - No additional support is added (for example, generated strings for new languages will appear using the - DITA-OT default language), but otherwise content will use the proper direction by default. Arabic, Urdu, - and Hebrew are already recognized by default; this change recognizes an additional 14 languages. - #1710, - #2267 -
    • -
  • PDF: Additional fallback fonts have been specified in the - font-mappings.xml file to provide better out-of-the-box support for Asian - characters. - #2279, - #2280, - #2296 -
    • -
  • HTML: Earlier releases of DITA-OT 2.x generated a style attribute with - text-align:left on table cells, regardless of whether the align - attribute was set in the source. This caused problems with right-to-left languages. The default entry - alignment has been removed, so the values of the xml:lang and dir - attributes on the root of the topic will be respected. (This allows the browser to infer the value for the - text-align property from the parent elements/styles.) - #2302, - #2368 -
    • -
  • PDF: The Dutch variable file now includes translations for Glossary, List of tables, and List - of figures. In addition, German, Italian, French, and Spanish have been updated to define missing - variables, including one that previously resulted in a build error ("Table of Contents Notices"). - #2131, - #2343 -
    • -
  • The DITA-OT configuration value default.language is now used as the default - language in all output formats. The value ships as en, but can be changed in - configuration.properties or specified as a parameter to the build. For HTML output, - the default is now the closest specified language; if a document does not specify - xml:lang, default.language is used. For PDF output, the default is the - closest specified language; if a document does not specify xml:lang, the root map is - used; if the root map does not specify xml:lang, default.language is - used. - #1476, - #2201, - #2356, - #2357 -
    • -
+
+ Extended code reference processing +

DITA-OT provides additional support for extracting a range of lines from code + references based on the content of the target file. Instead of specifying line numbers, you can now also + select lines to include in the code reference by specifying keywords (or “tokens”) that appear in + the referenced file. + #2469

+
+
@@ -305,57 +89,7 @@ Features

DITA Open Toolkit Release includes the following new features:

    -
  • The args.eclipsehelp.toc parameter for Eclipse Help, which has not worked - properly for several releases after it was made obsolete in DITA-OT 1.3, has been removed. - #1116, - #2354 -
    • -
  • DITA 1.3: Initial support has been added for the orient attribute on - table elements. These changes allow Antenna House Formatter to render tables in - landscape mode when the orient attribute is set to . A future release - will provide extended support for multi-page landscape tables with additional rendering engines. - #1777, - #2387 -
    • -
  • To permit automated building and testing on any platform, the HTMLHelp version of the - documentation is no longer included in the distribution package. An HTMLHelp version of the documentation - can still be built on Windows using the downloaded distribution package. - #2130 -
    • -
  • SAX pipes can now be configured in Ant pipeline tasks. This allows new - tasks to take advantage of in-memory processing without the need to write out files to disk. - #2144 -
    • -
  • The process for generating topic headers in the transformation type has - been simplified to use a single template with mode="insertTopicHeaderMarker". This reduces - the amount of work needed to format titles differently in the header and body. - #2155 -
    • -
  • The transformation type supports two new extension points - dita.conductor.html5.param and dita.conductor.html5.toc.param, allowing - plugins to provide new parameters for HTML5 processing. - #2185 -
    • -
  • Processing for copy-to has been moved out of the gen-list - preprocessing module and into a separate step. This improves processing for - topicref elements that use copy-to and keyref. - #2210 -
    • -
  • The DITA-OT preprocessing step that reads images for information about height and width now - supports reading dimension metadata from SVG images. - #2230 -
    • -
  • The transformation type has been updated to support the - expanse value "page" for elements that use the attribute. In addition, the - msgblock element has been updated to support frame and - scale, which generally appear on the same elements that use expanse. - #2317, - #2352 -
    • -
  • Cross-references to footnotes now generate hyperlinks in PDF output. - #2359, - #2364 -
    • +
@@ -364,142 +98,7 @@

DITA Open Toolkit Release includes the following enhancements and changes to existing features:

    -
  • PDF: Information from the README.txt files in the - org.dita.pdf2 plugin have been moved to the “PDF plug-in structure” topic in the DITA - Open Toolkit Developer Reference. Now that all useful information is available in the - documentation, the README.txt files have been removed. - #1860 -
    • -
  • PDF: In earlier versions of DITA-OT, filtering out all rows from a - simpletable element resulted in invalid XSL-FO. When all rows are filtered out, - the XSL-FO file now contains an empty (but valid) table so that processing can continue. - #1924, - #1950 -
    • -
  • Guava libraries are now used to simplify access to collections in Java code (among other - things). - #2122 -
    • -
  • HTML: The documentation for the and options - now clarifies that header and footer files must be specified using an absolute path. The options have always - required an absolute path, but the documentation for earlier releases did not include this requirement. - #2133 -
    • -
  • The dita command will now run using Java headless mode by default. This - optimizes the use of system resources during a build and prevents the build process from stealing focus from - other applications. - #2140 -
    • -
  • HTML: Static text for XHTML tables and figures (such as "Table 5") is now surrounded with a - span element, making it easier to style or hide the static text using CSS. In - addition, HTML5 output is updated to use semantic elements for figure and table captions. - #2160 -
    • -
  • Two members of the AbstractPipelineModuleImpl class have been marked as - protected, to allow plugins to access them from derived classes. - #2177 -
    • -
  • PDF: The I18N Java and XSLT processing code has been merged into single task. This is not - visible to most users of the PDF code, apart from a reduction in processing time. It also eliminates the - need for a stage3.fo file in the temporary directory; instead, - topic.fo is generated directly from stage2.fo. - #2179 -
    • -
  • In a previous release, the HTML5 extension point dita.conductor.html5.param was - declared but not implemented. The improper declaration was removed and the extension was properly - implemented. - #2181 -
    • -
  • HTML: In previous releases, short descriptions in abstract elements - were rendered as division elements (div), rather than paragraphs - (p). Processing has been revised to ensure that short descriptions are - consistently rendered as paragraphs, regardless of whether they appear in abstract - elements. - #2191 -
    • -
  • The order of the chunk and move-meta-entries pre-processing - stages has been switched so that chunk comes first. This ensures that metadata is properly - pulled or pushed into the chunked version of DITA topics. - #2207 -
    • -
  • HTML: The process for handling othertype on a note - element in HTML has been updated to use XSLT 2.0 best practices. - #2217 -
    • -
  • PDF: Earlier versions used an fo:inline element as a link target within - topic titles, which can result in extra white space for certain common customizations. The process now - places an ID on fo:wrapper, which removes the extra element and extra white space. - #2229 -
    • -
  • XSLT processing now uses a single parameter for message IDs rather than combining one parameter - for the error number with another parameter for severity. This simplifies message processing and allows a - greater range of message IDs in the future. In addition, the DOTX071W message will display - a warning for customizations that use the older, deprecated parameters. - #2231 -
    • -
  • Common XSLT utility templates have been rewritten as functions. In addition, XSpec tests have - been created so that the functions are now covered by automated DITA-OT testing. - #2233 -
    • -
  • The distribution integration and docs stages of the build process are now run in a forked JVM . - #2241 -
    • -
  • PDF: A reference to the PDF2 catalog has been added to catalog-dita.xml. In - previous releases, running topic2fo_shell.xsl directly would fail because the XSLT - processor couldn't resolve paths that use the cfg: scheme. - #2249 -
    • -
  • The distribution package is now built via a fully automated Continuous Integration process. - #2268 -
    • -
  • HTML5: A new stable ID generation process has been implemented, instead of relying on the - generate-id() function. By removing reliance on a dynamic value, this change enables - automated testing of id and headers (generated for table accessibility). - This also speeds up regression testing when comparing HTML output with previous versions. - #2276 -
    • -
  • A new ditaFileset function has been implemented to replace list files. This has no visible - impact for builds, but improves the processing model overall and allows the older way of working with - individual list files to be deprecated in a future release. - #2277 -
    • -
  • The build script for HTMLHelp, build_dita2htmlhelp.xml, now uses an - environment variable to locate the HTMLHelp compiler. This allows the process to build a CHM file when the - HTML Help Workshop is not installed on the C: drive. - #2288 -
    • - -
  • HTML5: new extension points allow for customization of HTML5 output, HTML5 TOC processing, and - HTML5 cover processing. These extension points were declared (but not implemented) in DITA-OT 2.2; this was - addressed in 2.2.5 by removing the declarations. In DITA-OT 2.3, the declarations are restored and properly - implemented. - #2305 -
    • -
  • The startcmd scripts are now generated by the DITA-OT integration process. - This ensures that the CLASSPATH setting in the scripts is updated with any new or required - Java libraries referenced by custom plug-ins. - #2341 - Users who still run DITA-OT using a custom start script based on a copy of - startcmd may need to update their script after installing custom plug-ins. The - CLASSPATH declarations are stored in alphabetical order, so they should only change - when new plug-in libraries are added. To avoid these issues, run DITA-OT using the dita - command instead of the deprecated startcmd scripts.
    • -
  • PDF: Index group headings now appear in the PDF bookmarks. The new bookmarks will always appear - in collapsed form under the Index heading. For example, a large index that covers every heading in English - will now have bookmarks for "Special characters", "Numerics", and every letter from "A" to "Z". - #2350 -
    • -
  • PDF: The antiquewhite background color has been removed from table heads and - key column contents in simpletable and properties tables - to synchronize presentation with choicetable and provide a more uniform - customization baseline between PDF output and HTML-based formats. - #2382, - #2386 -
    • -
  • Localization variables that are no longer used in PDF processing have been deprecated and will - be removed in an upcoming release. - #2383 -
    • +
@@ -507,70 +106,7 @@ Bugs

DITA Open Toolkit Release provides fixes for the following bugs:

    -
  • PDF: The message "No topicTitleNumber mode template" has been removed. This removes extraneous - messages that appeared when processing a bookmap with notices or - bookabstract, or which refers to a subject scheme map. - #1931 -
    • -
  • HTML: trademark symbols previously only appeared for tm elements in - English and a select few languages. This was a legacy of processing carried over from beta processing before - DITA-OT 1.0; HTML trademark processing will now work the same regardless of document language. - #2065 -
    • -
  • Processing for coderef elements could be broken when the - coderef was part of a larger section reused by conref. This is fixed by resolving - coderef during the topic-fragment step of preprocessing. - #2141 -
    • -
  • The AXF document-info attribute title is deprecated; XSL-FO output for Antenna - House output should use the document-title attribute instead. - #2161, - #2162 -
    • -
  • When using keys, referencing a file outside of the current directory causes processing to fail. - Previously, the target file URI was resolved against the root of the temp directory. This has been updated - to resolve the URI against the source file URI, which should always yield the correct result. - #2190, - #2223 -
    • -
  • In previous releases, specializations of the link element did not work - as intended. The corresponding XSLT template mode related-links:link has been modified to - properly handle new elements that are based on the link element. - #2197, - #2199 -
    • -
  • Circular key definitions, when an element used keyref to refer to a key on the - same element, resulted in a stack overflow in KeydefReader. This construct is now reported as an error with - message DOTJ069E. - #2227 -
    • - -
  • Publishing failed when using term with keyref and chunking, as the - chunking module created file references with backslashes. Processing has been updated to convert any - backslashes to slashes before using the resolve-uri function in XSLT. This ensures that the - attribute values are valid URI references according to - . - #2243 -
    • -
  • PDF: In the simplified Chinese variables file (zh-CN), additional translations have been - provided for some static strings that previously appeared in English. - #2294, - #2353 -
    • -
  • Resource-only topic references were considered duplicates by key processing, resulting in - renamed output files in some cases. The resource-only instances are now ignored when determining whether to - rename output files. - #2304 -
    • -
  • PDF code was cleaned up to remove a broken message that could not be triggered - #2326, - #2351 -
    • -
  • In previous releases, specifying a keyscope attribute on the root - map element would cause builds to fail. Processing has been modified to handle - this situation correctly. - #2339 -
    • +
@@ -578,21 +114,17 @@ Contributors

DITA Open Toolkit Release includes by the following people:

- +
  1. Jarno Elovirta
  2. Robert D. Anderson
    3. +
  3. Eliot Kimber
  4. Eero Helenius
  5. Roger Sheen
    6. -
  6. Eliot Kimber
  7. Radu Coravu
    8. -
  8. Shane Taylor
    9. -
  9. Stefan Eike
    10. -
  10. George Bina
    11. -
  11. Kristen James Eberlein

For the complete list of changes since the previous release, see the - + changelog on GitHub.

@@ -601,57 +133,15 @@

The documentation for DITA Open Toolkit Release includes corrections and improvements to existing topics, along with several notable enhancements, including:

    -
  • The DITA Open Toolkit User Guide includes new topics on additional methods of publishing via - the dita command: -
      -
    • - -
      • -
    • - -
      • -
    -
    • -
  • The DITA Open Toolkit Developer Reference includes several new sections dedicated to - customization: -
      -
    • - provides an overview of approaches commonly used to customize the - default PDF output and includes recommendations on best practices and additional resources.
      • -
    • - highlights customization-related changes in recent releases to assist plug-in - developers in updating overrides to work with the latest toolkit versions.
      • -
    -
    • -
  • -

    - Travis CI continuous integration - is used to automatically publish the latest development version of the documentation on the project - website at - dita-ot.org/dev whenever - changes are pushed to the develop branch of the - dita-ot/docs repository - on GitHub.

    • -
  • -

    In the latest - development version of the - documentation, page footers now include Edit this page links that open the DITA - source file for the topic in - oXygen XML Web - Author.

    -

    The web-based authoring workflow prompts users to log in to GitHub and fork the - dita-ot/docs repository - if necessary. Changes saved in the authoring environment are committed to a new branch, and a pull request - is created to submit changes for review by the DITA-OT documentation team.

    -
    • +

For additional information on documentation issues resolved in DITA Open Toolkit Release , see the - milestone in the documentation repository.

For the complete list of documentation changes since the previous release, see the - + changelog.

 diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap index 6de413817..8710ff364 100644 --- a/resources/key-definitions.ditamap +++ b/resources/key-definitions.ditamap @@ -150,6 +150,13 @@ Apache FOP 2.1 Release Notes + + + + Apache FOP Accessibility + + Date: Tue, 8 Nov 2016 00:23:27 +0100 Subject: [PATCH 06/17] List remaining issues resolved in v2.4 (annotations to follow) Signed-off-by: Roger Sheen --- release-notes/index.dita | 68 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index 0cb76f29e..6847e64d6 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -89,7 +89,20 @@ Features

DITA Open Toolkit Release includes the following new features:

    -
  • +
  • Remove dependency to XHTML from HTML5 + #2405, + #2511 +
    • +
  • Move to Java 8 + #2026 +
    • +
  • Remove completely from the DITA OT distribution the plugin for generating Eclipse Content + #1542 +
    • +
  • TM output + #1245, + #2404 +
@@ -98,7 +111,49 @@

DITA Open Toolkit Release includes the following enhancements and changes to existing features:

    -
  • +
  • Bug in "dita-utilities.xsl" getVariable when called from string context + #2512, + #2513 +
    • +
  • HTML5 generates duplicate class attributes + #2503 +
    • +
  • Use Sass `// comment` syntax for partials copyrights # + #2502 +
    • +
  • Change HTML5 to use libsass instead of Compass + #2499 +
    • +
  • Add sign-off requirement to contribution + #2471 +
    • +
  • Add copyright based on Git history + #2467 +
    • +
  • Run dita command with only properties file + #2465, + #2468 +
    • +
  • Map temporary files to source/result files using job configuration + #2462 +
    • +
  • Use job mapper when transforming topics to final output + #2453 +
    • +
  • Move chunk target detection to chunk module + #2437 +
    • + +
  • Replace named template with mode for easy override of static content + #2412 +
    • +
  • Remove lax integration process + #2151 +
@@ -106,7 +161,14 @@ Bugs

DITA Open Toolkit Release provides fixes for the following bugs:

    -
  • +
  • Fix error when linktext contains tm #2303 + #2394 +
    • +
  • Build fails when navtitle in relcell has child + elements + #2347, + #2390 +
From 779553363ff0bd64c8183a1d5c185bbfe54cb53e Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Tue, 8 Nov 2016 01:22:07 +0100 Subject: [PATCH 07/17] =?UTF-8?q?Add=20=E2=80=9CExtension=20points=20by=20?= =?UTF-8?q?plug-in=E2=80=9D=20to=20docs=20updates?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Roger Sheen --- release-notes/index.dita | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index 6847e64d6..60d03d52d 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -193,9 +193,13 @@
Documentation updates

The documentation for DITA Open Toolkit Release includes corrections and - improvements to existing topics, along with several notable enhancements, including:

+ improvements to existing topics, along with new content.

    -
  • +
  • Like the generated + and + topics, a new + section is now generated from the installed DITA-OT plug-ins to + provide an overview of the extension points supported by each plug-in.

For additional information on documentation issues resolved in DITA Open Toolkit Release , see the From 8a6ceb8a763a84abf3f2e6eaa1ffbe9eed0ae2d9 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Tue, 8 Nov 2016 01:38:08 +0100 Subject: [PATCH 08/17] Use new double-hyphen syntax in parameters intro Signed-off-by: Roger Sheen --- parameters/parameters_intro.dita | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/parameters/parameters_intro.dita b/parameters/parameters_intro.dita index 7b8a42971..bb6d9551c 100644 --- a/parameters/parameters_intro.dita +++ b/parameters/parameters_intro.dita @@ -7,13 +7,13 @@ Certain parameters apply to all DITA-OT transformations. Other parameters are common to the HTML-based transformations. Some parameters apply only to specific transformation types. These parameters can be passed as - options to the dita command using the syntax or included + options to the dita command using the --parameter=value syntax or included in build scripts as Ant properties.

-

If your toolkit installation includes custom plug-ins that define additional parameters, you can - add entries to the following topics by rebuilding the DITA-OT documentation.

+

If your toolkit installation includes custom plug-ins that define additional parameters, you can add entries to + the following topics by rebuilding the DITA-OT documentation.

From 87a64b1dce95e9d2d0381779f82f948271bd6eaa Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Tue, 8 Nov 2016 01:39:15 +0100 Subject: [PATCH 09/17] Remove reference to obsolete command line tool Signed-off-by: Roger Sheen --- user-guide/log-files.dita | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/user-guide/log-files.dita b/user-guide/log-files.dita index 89d63f059..5203f93d8 100644 --- a/user-guide/log-files.dita +++ b/user-guide/log-files.dita @@ -8,8 +8,8 @@ a log file. If you encounter a problem, you can analyze this information to determine the source of the problem and then take action to resolve it. -

The logging behavior varies depending on whether you use the dita command, DITA-OT - command-line tool, or Ant to invoke a toolkit build.

+

The logging behavior varies depending on whether you use the dita command or Ant to invoke a + toolkit build.

dita command
By default, only warning and error messages are written to the screen. If you use the @@ -23,13 +23,6 @@ that you specified. (You also can use other Ant loggers; see the Ant documentation for more information.)
 -

+ + + DITA features in the documentation + + DITA features in docs + + The DITA Open Toolkit uses various recent DITA features in the project documentation. + + +

The + source files for the DITA-OT + documentation include examples of the following DITA features (among others):

+
    +
  • subjectScheme classification for controlling available attributes
    • +
  • profiling and branch filtering (novice/expert content)
    • +
  • extending topics with conref push
    • +
  • keys and key references
    • +
  • XML mention domain
    • +
+
+ Subject schemes +

Various topics, sections and elements in the docs are profiled by audience:

+ <li id="novice-variables-last" audience="novice"> + <p id="common-format-info"> + <varname>format</varname> is the output format (transformation type). + Use the same values available for the <parmname>transtype</parmname> + build parameter, for example, <codeph>html5</codeph> or <codeph>pdf</codeph>. + </p> +</li> +

An “audience” subject scheme controls the values that are available for the audience + attribute:

+ <subjectdef keys="audience"> + <subjectdef keys="novice"/> + <subjectdef keys="expert"/> + <subjectdef keys="xslt-customizer"/> +</subjectdef> +
+
+ Branch filtering: re-using profiled content +
+
+

The Getting Started section pulls a subset of the build description from the User + Guide, filtered to display only content deemed suitable for novice users under + :

+ <topicref href="../user-guide/using-dita-command.dita" + copy-to="using-dita-command.dita" keys="first-build-using-dita-command"> + <topicmeta> + <navtitle>Building output</navtitle> + </topicmeta> + + <ditavalref href="../resources/novice.ditaval"> + <ditavalmeta> + <dvrResourcePrefix>first-build-</dvrResourcePrefix> + </ditavalmeta> + </ditavalref> +</topicref> +

The same content appears later in the User Guide with additional information on arguments, options + and examples (see + ).

+
+
+ Conref push +
+
+

The docs build uses the conref push mechanism (specifically + conaction="pushafter") to extend the parameter descriptions embedded in the + default plug-ins:

+ <plentry id="args.csspath"> + <pt> + <parmname>args.csspath</parmname> + </pt> + <pd conaction="mark" + conref="parameters-base-html.dita#base-html/args.csspath.desc"/> + <pd conaction="pushafter" audience="xslt-customizer"> + Corresponds to the XSLT parameter <parmname>CSSPATH</parmname>. + DITA-OT will copy the file to this location.</pd> +</plentry> +

The pushed content appears in the output after the default description. (See + .)

+ You could also use the same mechanism to extend the documentation with custom information that + applies only to your company's toolkit distribution. +
+
+ Keys and key references +
+
+

The key-definitions.ditamap defines keys for version references, re-usable links, etc.

+

This key definition defines the maintenance release version:

+ <keydef keys="maintenance-version"> + <topicmeta> + <keywords> + <keyword>2.3.3</keyword> + </keywords> + </topicmeta> +</keydef> +

In topics, the keyword is used in place of hard-coded version references:

+ <title>DITA Open Toolkit <keyword keyref="maintenance-version"/> Release Notes</title> +
+
+ XML mention domain +
+
+

The docs use the + XML mention domain to mark up XML elements and attributes:

+ <li id="1777"> + DITA 1.3: Initial support has been added for the <xmlatt>orient</xmlatt> + attribute on <xmlelement>table</xmlelement> elements. These changes allow + Antenna House Formatter to render tables in landscape mode when the + <xmlatt>orient</xmlatt> attribute is set to <option>land</option>. […] +</li> +

When the toolkit generates output for the sample above:

+
    +
  • the XML element name is wrapped in angle brackets as table +
    • +
  • the attribute name is prefixed with an “at” sign as orient
    • +
+
+ + diff --git a/user-guide/spec-support.ditamap b/user-guide/spec-support.ditamap index f19ba8b26..0016f15e1 100644 --- a/user-guide/spec-support.ditamap +++ b/user-guide/spec-support.ditamap @@ -9,5 +9,6 @@ + From d825304f9dbb0d9b147936529361e45f737dc81f Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Fri, 11 Nov 2016 15:54:28 +0100 Subject: [PATCH 13/17] Link to new topic on DITA features used in docs Signed-off-by: Roger Sheen --- release-notes/index.dita | 3 +++ 1 file changed, 3 insertions(+) diff --git a/release-notes/index.dita b/release-notes/index.dita index 9f54e68f3..ad69a48f4 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -200,6 +200,9 @@ topics, a new section is now generated from the installed DITA-OT plug-ins to provide an overview of the extension points supported by each plug-in. +
  • A new + topic provides examples of how the project documentation uses various + recent DITA features.

    • For additional information on documentation issues resolved in DITA Open Toolkit Release , see the From b9fb89ebe292762e432aeca10cc3ff722aa3fb62 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Fri, 11 Nov 2016 16:29:47 +0100 Subject: [PATCH 14/17] Add keys to migration map Signed-off-by: Roger Sheen --- dev_ref/migration.ditamap | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/dev_ref/migration.ditamap b/dev_ref/migration.ditamap index 2bf30237b..e545ec165 100644 --- a/dev_ref/migration.ditamap +++ b/dev_ref/migration.ditamap @@ -5,15 +5,15 @@ Migrating customizations - + - - - - + + + + - - + + From 7c0ac369adfead8438579b62c7c5f47264da5c8e Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Fri, 11 Nov 2016 17:52:09 +0100 Subject: [PATCH 15/17] Add topic on migrating to 2.4 Signed-off-by: Roger Sheen --- dev_ref/migrating-to-2.4.dita | 89 +++++++++++++++++++++++++++++++ dev_ref/migration.ditamap | 1 + release-notes/index.dita | 2 + resources/key-definitions.ditamap | 5 ++ 4 files changed, 97 insertions(+) create mode 100644 dev_ref/migrating-to-2.4.dita diff --git a/dev_ref/migrating-to-2.4.dita b/dev_ref/migrating-to-2.4.dita new file mode 100644 index 000000000..fc2d76b13 --- /dev/null +++ b/dev_ref/migrating-to-2.4.dita @@ -0,0 +1,89 @@ + + + + + + + Migrating to release 2.4 + + In DITA-OT 2.4, the transformation was refactored as an independent plug-in that no + longer depends on the plug-in. + + +

    + This topic provides a summary of changes in DITA-OT 2.4 that may require modifications to custom stylesheets + or plug-ins. For more information on changes in this release, see the + . +
    +
    + HTML5 +
      +
    • +
      +

      The transformation introduced in release 2.0 as part of the + plug-in was moved to a separate plug-in in release 2.2, but that version of the + transformation still depended on the plug-in for certain + common processing.

      +

      In release 2.4, all dependencies between and have been + removed to ensure that HTML5 processing can be further refactored in the future without affecting XHTML + output, or other HTML-based transformations such as , + or .

      +
      +

      Customizations that extended the previous HTML5 output under the plug-in (as + provided in releases 2.0 and 2.1) or the plug-in that shipped with release 2.2 will + need to be refactored to build on the new HTML5 plug-in.

      • +
    • +

      Note title processing was revised in release 2.2 to include a common note__title class for + note elements of all types. The legacy {$type}title classes (such as + .notetitle, .cautiontitle, .tiptitle, etc.) were + included in release 2.2 for backwards compatibility, but have now been removed in release 2.4.

      +

      Stylesheets that apply formatting overrides to note titles should be revised to replace the deprecated + class selectors with the equivalent descendant selectors, for example:

      +
        +
      • .note_note .note__title
        • +
      • .note_caution .note__title
        • +
      • .note_tip .note__title
        • +
      +
      • +
    +
    +
    + Legacy plug-ins removed +

    DITA-OT 2.4 no longer includes the following legacy transformation plug-ins in the default distribution:

    + + Legacy plug-ins + + + + + + Plug-in + Source code location + + + + + DocBook + + + + + Eclipse Content + + + + + Word RTF + + + + + +
    + If necessary, they may be re-installed from earlier DITA-OT distributions, but they are no longer actively + maintained or supported by the core toolkit committers. The source code is available on GitHub for anyone + interested in maintaining the plug-ins for use with future toolkit versions. +
    + + + diff --git a/dev_ref/migration.ditamap b/dev_ref/migration.ditamap index e545ec165..1a85fce57 100644 --- a/dev_ref/migration.ditamap +++ b/dev_ref/migration.ditamap @@ -5,6 +5,7 @@ Migrating customizations + diff --git a/release-notes/index.dita b/release-notes/index.dita index ad69a48f4..55782852d 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -203,6 +203,8 @@
  • A new topic provides examples of how the project documentation uses various recent DITA features.
    • +
  • A new topic provides information on + Migrating to release 2.4.

    • For additional information on documentation issues resolved in DITA Open Toolkit Release , see the diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap index 8710ff364..01e781e2e 100644 --- a/resources/key-definitions.ditamap +++ b/resources/key-definitions.ditamap @@ -255,5 +255,10 @@ DITA-OT 2.3 Release Notes + + + DITA-OT 2.4 Release Notes + + From 12bc7af007a3ed3090ee9dbbb1a684d10ca94a27 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Fri, 11 Nov 2016 17:52:43 +0100 Subject: [PATCH 16/17] Split contribution info between core & docs Signed-off-by: Roger Sheen --- release-notes/index.dita | 9 +++++++++ resources/key-definitions.ditamap | 8 +++++++- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index 55782852d..0797506ec 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -177,6 +177,7 @@

    DITA Open Toolkit Release includes by the following people:

    + NOTE: This lists contributions to the core toolkit, not docs.
    1. Jarno Elovirta
    2. Robert D. Anderson
      3. @@ -211,6 +212,14 @@ milestone in the documentation repository.

      +

      DITA Open Toolkit Release includes + by the following people:

      + NOTE: This lists contributions to docs, not to the core toolkit. +
        +
      1. Roger Sheen
        2. +
      2. Jarno Elovirta
        3. +
      3. Mark Giffin
        4. +

      For the complete list of documentation changes since the previous release, see the changelog.

      diff --git a/resources/key-definitions.ditamap b/resources/key-definitions.ditamap index 01e781e2e..c5f74acac 100644 --- a/resources/key-definitions.ditamap +++ b/resources/key-definitions.ditamap @@ -230,7 +230,13 @@ - contributions + code contributions + + + + + documentation contributions From f04c510300f2b2df57ce25d56e83fa1fc4c38283 Mon Sep 17 00:00:00 2001 From: Roger Sheen Date: Fri, 11 Nov 2016 18:13:08 +0100 Subject: [PATCH 17/17] Re-use migration info on HTML5 & legacy plug-ins Move remaining Feature orphans to Enhancements Signed-off-by: Roger Sheen --- release-notes/index.dita | 43 +++++++++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/release-notes/index.dita b/release-notes/index.dita index 0797506ec..61ec8208d 100644 --- a/release-notes/index.dita +++ b/release-notes/index.dita @@ -77,6 +77,20 @@
    +
    + Standalone <option>HTML5</option> plug-in +
    +

    + #2405, + #2511 +

    +
    + +
    +
    +

    + #1542

    +
    @@ -85,32 +99,29 @@ In addition to the highlights mentioned above, DITA Open Toolkit Release includes the following changes. + +
    - Enhancements + Enhancements and changes

    DITA Open Toolkit Release includes the following enhancements and changes to existing features:

      +
    • Move to Java 8 + #2026 +
      • +
    • TM output + #1245, + #2404 +
    • Bug in "dita-utilities.xsl" getVariable when called from string context #2512, #2513 @@ -118,7 +129,7 @@
    • HTML5 generates duplicate class attributes #2503
      • -
    • Use Sass `// comment` syntax for partials copyrights # +
    • Use Sass // comment syntax for partials copyrights #2502
    • Change HTML5 to use libsass instead of Compass