-
Notifications
You must be signed in to change notification settings - Fork 96
Meeting minutes 2016 05 05
- Attendance
- OT project status updates
- New issues since last call
- Fixed issues since last call
- Backlog review
- Issue prioritization
- Kris
- Roger
- Shane
The DITA-OT contributor call was held immediately prior to the docs call. Meeting minutes are available at https://github.com/dita-ot/dita-ot/wiki/Meeting-minutes-2016-05-05.
- 2.2.5 hotfix to be finalized on Monday, May 9.
- 2.3 currently scheduled for May 29.
3 new issues & pull requests were created since the last call.
In #94, Radu proposes adding an FAQ section to the docs, and offers the content of his blog post as raw material.
We should discuss whether to include this within the docs, or elsewhere on the project website.
2 pull requests were submitted:
- #93 by Shane with some improvements to the “Creating plug-ins” section
- #95 by Robert with some updates to the messages topic to clarify the errors as suggested by Radu in dita-ot/dita-ot#1709.
Currently 27 Open Issues, 43 Closed, no open PRs: https://github.com/dita-ot/docs/issues.
The main focus areas for the next few weeks leading up to the 2.3 release will be issue #70: Extend section on “Customizing PDF output” and related subtasks:
- Overview of customization approaches, with pros, cons & recommendations for each approach:
- Editing default
org.dita.pdf2files in place — why not to! - Placing custom files in
org.dita.pdf2/Customizationfolders, editingcustom.xsl.orig - Specifying remote customization folders via
customization.dir
- Editing default
- Best practices: Creating custom PDF plug-ins
- Link to the PDF plugin generator #57
- Relevant content from
pdf2ReadMe files #69 - Migrating PDF customization folders to plugins #43
Draft content based on input from Kris & additions by Roger is available for review on a staging fork of the project website at http://infotexture.github.io/dita-ot.github.io/dev/dev_ref/pdf-customization.html .
During the call, we discussed the pros & cons of various PDF customization approaches & best practices. There appears to be consensus among the docs team and other DITA-OT collaborators that we should strongly urge users to customize only individual templates rather than duplicating entire stylesheets.
While we may not want to treat other approaches as wrong, we agree the docs should explain their disadvantages so users understand the reasoning for the recommended approach.
Roger has adapted content from the pdf2 ReadMe files for #69 that explains the structure of the former Customization folder.
One option would be to use this content as a recommendation for the folder structure of custom plug-ins:
PDF customization plug-ins typically organize 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.
However, some users may find this structure unnecessarily complex.
Shane suggests adapting this content as an explanation of the structure of the default plug-in. As with customization approaches, we may want to explain the pros & cons of different folder structures, point out how the default structure facilitates diffs for complex plug-ins and add a topic on 3-way diff & merge.
You may want to structure your plug-in differently.
Discussion of how PDF customization is related to the "Creating plug-ins" section:
- it is related, but we don't want to bury it
- remind users much of this info is not specific to PDF customization,
but also applicable to plug-ins in general - should we move some of the examples into a dedicated section?
The contents of the “Customizing PDF output” section will be further refined based on our discussion.
Additional comments and feedback are welcome over the next few weeks, as we'd like to include this content for the 2.3 release.
View the latest DITA Open Toolkit docs at www.dita-ot.org/dev.