dita-ot / docs Goto Github PK
View Code? Open in Web Editor NEWDITA Open Toolkit documentation
Home Page: https://www.dita-ot.org/dev
License: Apache License 2.0
DITA Open Toolkit documentation
Home Page: https://www.dita-ot.org/dev
License: Apache License 2.0
The mainarch.gif
diagram in the Processing structure topic should be updated to reflect recent changes to the toolkit architecture and prepared in a format such as SVG to ensure optimum quality in all docs output formats.
An editable source file for the diagram should be added to the repository to facilitate future updates.
Based on: dita-ot/dita-ot#1887
The official parameter for controlling related links generation is "args.rellinks". But some people who publish output might want a more precise way of controlling the generated links by setting directly the parameter "include.rellinks" which specifies in clear what types of links are allowed for generation.
In the example section, the path to sequence.ditamap is wrong. It should be ../samples/sequence.ditamap
Refers to the startcmd.bat and startcmd.sh files that are no longer shipped with the DITA-OT.
The documentation currently refers to HTML-based transformation types in different ways, sometimes using the generic "HTML" form, while in other places mentioning specific flavors XHTML and HTML5.
These occurrences should be reviewed to use the generic "HTML" form where all HTML-based transformations are implied, and only mention XHTML or HTML5 where the implementation details are relevant.
The JavaHelp transformation is missing from the list of available transformations in publishing.ditamap, though the topic itself exists and is referenced in reltable.ditamap.
Many files in the docs
subrepository do not contain any reference to the project's license.
Others contain comments that still refer to SourceForge hosting or a license.txt
file that is not present in the repository. Update files to point to the current license file LICENSE.md
.
Based on http://jelovirt.github.io/2013/11/25/reducing-processing-time.html per @jelovirt's suggestion.
Consider adding as subsection of Configuring the DITA Open Toolkit.
The PDF version of the User Guide contains an appendix with links to the old IBM developerWorks articles, but the URLs have since changed, so all the old links currently redirect to the IBM home page.
We should either update the links to point to new URLs (if available) or remove the topic entirely. The topic no longer appears any of the HTML-based output formats.
Confirmed w/ @robander during 2015-02-03 contributor call: remove topic, since these articles were written for early versions of DITA, and best practices have evolved significantly since then.
Now that the main DITA-OT repo uses Gradle to build, we should prepare a build.gradle
file for docs
to employ the DITA Open Toolkit Gradle Plugin for better performance, incremental builds and continuous builds via the Gradle Daemon.
This solution would facilitate local testing by rebuilding docs whenever source files change, and could also serve as a foundation for continuous integration of changes to Development docs on the project website at www.dita-ot.org/dev per dita-ot/website#9.
NOTE: To prevent code duplication and still allow users that don't have Gradle to build the docs, it might be best if the build.gradle
file could call the existing Ant build file, or re-use the targets it defines.
It looks like the element in plugin.xml is not documented on this page:
https://github.com/dita-ot/docs/blob/develop/dev_ref/plugin-configfile.dita
An example of this element is here:
https://github.com/oxygenxml/dita-css/blob/master/com.oxygenxml.pdf.css/plugin.xml
Thanks,
Mark
@georgebina reported:
The documentation for the
configuration.properties
file lists a few properties but fromConfiguration.java
it looks like there are also entries likeprint_transtypes
,plugin.[name].dir
andparser.[format]=[value]
The existing topics in the Configuration properties section of the Parameter Reference should be updated to cover the missing properties, explain how properties files are used internally by the toolkit, and clarify the difference between configuration properties and argument properties that users can set at transformation time.
We should also consider extending this section to cover not only configuration properties, but also include information on how users can use property files to specify transformation parameters by passing a property file as an argument to the dita command:
dita -propertyfile file
Load all properties from a file. Properties specified with the -D option take precedence.
The page Modifying or adding generated text contains multiple documentation errors.
For example, the files previously living in xsl\common
have moved to cfg\common\vars
. Further on, some file names have changed. I didn't check the whole page yet. Is anybody working on this? Otherwise I'd send you a pull request.
In dita-ot/website#7, @liujason writes:
It seems there are a few elements in plugins.xml are updated.
For example, the http://www.dita-ot.org/2.1/dev_ref/plugin-newtranstype.html seems out dated. In plugins/org.dita.xhtml/plugin.xml, there's a new element, with elements underneath. I can't find any documentation on how they are used.
Commit 864dad6 extends the Plug-in configuration file topic with a description of the new <transtype>
element and provides an example, but further information may be necessary.
The DITA-OT preprocess adds several items that later rendering steps can make use of, and which might change the content to be not-quite-pure DITA. This can simplify the shipped rendering in many ways, such as eliminating any need to process a DITAVAL file to support flagging.
We should document these changes so that developers of new transform types are aware of them. This lets them take advantage of the updates, and also lets them know what has changed that might not be "pure DITA".
I don't think we need to list all of the stuff that is already covered / assumed, such as "conref is resolved". Offhand the things I know of that we need to document are:
Also considering an update that would add things like @dita-ot:href
in this newly opened issue; if we move forward it would need to be documented as well: dita-ot/dita-ot#1837
Since many contributors use oXygen, a project file should be added to store common settings like line width, etc.
Transformation scenarios and/or external tool scripts can be used to build output by calling the project build scripts from the oXygen UI.
There is a Relax NG schema (plugin.rnc) that can be used to validate plugin.xml
files. This schema should be mentioned in the Plug-in configuration file topic.
Include link to chunking info in the implementation dependent features topic with additional information on pros, cons, side effects & any caveats w/r/t the DITA-OT implementation of chunking.
The focus here should be on specific considerations related to how DITA-OT handles chunking, as more general DITA best practices tutorials are beyond the scope of the OT docs.
The landing page that serves as the introduction to the toolkit docs should provide an overview of the documentation structure rather than duplicating information from the project home page www.dita-ot.org.
The page should provide a direct link to the latest release notes and pull in the short descriptions from each of the documentation parts that appear in the top level of the site navigation (ToC).
To assist users in migrating from OT v1.x to v2.x, the documentation should include an overview of the types of changes required to update existing projects for use with v2.0.
Topics may include:
Separate topics should be created with migration info for each 2.x release:
On Wednesday, 2015-09-02, at 16:30 CEST, @jelovirt wrote:
We will probably need to update http://www.dita-ot.org/dev/dev_ref/DITA1.2-implementation-dependent-features.html to fill in how we implement DITA 1.3
Basically, we’d need to go though the 1.3 spec and find all places that state that an implementation MAY do X. Then just list what we do.
Topic describes what lists are generated, and is out of date for 2.0. [Noticed by Kris, thanks!]
The contribution guidelines outlined in the README should be moved to a CONTRIBUTING.md
file in the root of the repository to display a banner when a contributor creates an Issue or opens a Pull Request.
I think we need a set of topics helping users understand how to use the logs to identify and troubleshoot build problems. This should follow the tutorial approach outlined in #37.
After separating the docs
repository from the parent dita-ot
repository, build scripts should be refactored to reduce dependencies on the main repo to ensure that new contributors can just clone docs
and build documentation output without cloning the the parent dita-ot
repository.
User-defined customizations in the org.dita.pdf2/Customization
directory or custom locations specified via the customization.dir
parameter should be migrated to custom PDF plugins.
Add a topic that describes the differences between the customization folder approach and plugins, and the changes required to port customization folders to plugins.
The PDF2 transform handles a special syntax for the @changebar
attribute in order to generate revision bars with FO when it is supported (AHF, XEP). This appears to be undocumented. I will document it.
Format & indent current source files for readability.
Hard-wrap lines @ 120 characters to avoid horizontal scrolling in GitHub's edit & unified diff views
The docs subrepository currently contains many obsolete files that are no longer referenced in recent versions of the documentation. Most are remnants of earlier documentation releases that no longer apply to the current toolkit distributions and can be safely removed.
Unreferenced content may be preserved if useful as a basis for new topics, but should probably be moved to a dedicated subdirectory.
The Ant parameter args.xhtml.toc.xsl is missing from the docs. It specifies a custom XSLT file to use for the TOC (index.html).
A topic with a list of all extension points is now generated automatically when the documentation build process runs.
The extension point descriptions are generated from the name
attribute of each <extension-point>
element in the plugin.xml
configuration file for each plugin.
The conref mechanism should be used to expand or override the descriptions for the default toolkit plugins as used for the generated parameter listings and messages topics.
Pending modifications to build scripts in #3.
Kris provided updated versions of the topics in the plug-in section of the Developer Reference in response to #20.
This work-in-progress should be merged with the latest versions of the topics.
Live code references should be used for sample files wherever possible to ensure that examples are updated automatically.
This would also facilitate testing, as the code samples for things like Ant scripts could be run directly to verify they work as intended.
The docs should be extended with a dedicated topic or set of topics that describes how the DITA-OT documentation uses certain DITA and DITA-OT features, such as:
Wherever possible, these topics should use <coderef>
elements to link directly to live source files rather than copying code (see #49).
After the approval of DITA 1.3 as an OASIS standard, links to the spec should be updated to point to the final standard documents once these are published by the TC.
Existing text references should be reviewed and revised to reflect the final approved standard status.
Since recent versions of the documentation no longer include an archive of the Release Notes from prior releases, there is no single source of information on the changes required to port earlier customizations to recent toolkit versions.
To facilitate and encourage upgrades, the Developer Reference should include a dedicated section on Migrating Customizations with the migration-related information from the Release Notes of recent releases.
This information is available for v1.5.4 onward, and will be added for v2.0 for #29.
A topic that lists books about DITA and the DITA-OT should be added to the DITA and DITA-OT Resources section.
The DITA generator is the starting point to create a specialization or a PDF plugin. Starters waste a lot of time (trust me) when trying to write a specialization or a PDF plugin the first time, because there is only little information out there, e.g. Eliots DITA Configuration and Specialization Tutorials.
There seems to be a topic on globalizing the DITA OT:
http://www.dita-ot.org/2.0/readme/DITA-globalization.html
But it does not seem to say anything about how to contribute new translations as a plugin for example.
We probably need to have separate explanations for the PDF processing and for the other transformations.
Based on this question on the DITA Users List:
https://groups.yahoo.com/neo/groups/dita-users/conversations/messages/37719
I am currently adding a few languages to my documentation set.
Some of these languages are not supported by my DITAOT.
Does anyone know if there are resources that can allow me to add more languages?
As part of other updates to troff, I've declared extension points that let the troff XSL accept overrides like any other XSL output. They should be added to this topic:
http://www.dita-ot.org/2.0/dev_ref/plugin-overridestyle.html
Specifically:
"dita.xsl.troff-ast" Overrides the intermediate block-and-phrase format generated as input to troff processing.
"dita.xsl.troff" Overrides the XSL that converts block-and-phrase intermediate markup into troff.
For example, for my own domain, I'd add this extension to get formatting tweaks into the intermediate format:
<feature extension="dita.xsl.troff-ast" file="xsl/our-domain.xsl"/>
Several locations in the documentation still point to the SourceForge site.
Replace links to http://sourceforge.net/projects/dita-ot/files/DITA-OT%20Stable%20Release [...] with https://github.com/dita-ot/dita-ot/releases/tag/2.0
On 2016-01-2, at 13:08 CET, @xephon2 wrote:
Is Tested platforms and tools up to date?
The test environment still covers Windows XP but no Windows 10?
Several of the operating systems and other listed tools are a bit dated.
We need to review the list, prune older versions we no longer intend to support, and add latest supported versions.
The OT docs should be extended with a dedicated Tutorials section that guides the reader through common use cases for new toolkit users, such as:
dita
commanddita
builds with scriptsSeveral similar topics are currently available elsewhere in the docs (checked in the list above), but a dedicated Tutorials section would make them easier to find and provide a more task-oriented approach to learning.
For those familiar with earlier toolkit releases, tutorials could also serve to illustrate new approaches in recent toolkit versions, such as:
.properties
filesPlease add comments below to suggest additional topics.
dita-ot/dita-ot/issues/1799 changes generate-debug-attributes
and processing-mode
configuration options to be runtime properties; there is no change in functionality on either property.
After consolidation of distribution packages for dita-ot/dita-ot#1914, references to the obsolete standard
and minimal
distribution packages should be removed from the documentation.
Remaining references to the client
package should be verified & simplified accordingly.
For example all the extension points in the pdf2 plugin:
<extension-point id="org.dita.pdf2.xsl.topicmerge" name="PDF2 topic merge XSLT import"/>
<extension-point id="depend.org.dita.pdf2.format.pre" name="Formatting pre-target"/>
<extension-point id="depend.org.dita.pdf2.format" name="Formatting target"/>
<extension-point id="depend.org.dita.pdf2.format.post" name="Formatting post-target"/>
<extension-point id="org.dita.pdf2.catalog.relative" name="Configuration XML catalog"/>
<extension-point id="dita.conductor.pdf2.param" name="PDF XSLT parameters"/>
I cannot find them anywhere in the docs. Actually I cannot find in the docs a list with all extension points anymore.
Create a new DITA Specification Support section with two children:
1.3 Support topic should provide an overview of supported 1.3 features.
Consider including status of planned feature support w/ links to related issues per @raducoravu's suggestion.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.