Frequently asked questions

[raducoravu]

Maybe you could have a DITA OT frequently asked questions topic in the documentation. I did something similar on my blog post:
http://blog.oxygenxml.com/2016/04/dita-open-toolkit-frequently-asked.html
You are welcomed to use any questions or answers you want from there, of course replacing links I made to Oxygen resources with links to the official docs.

[infotexture]

Thanks for the input, looks like a good starting point indeed. 👍

We have a similar issue on the site backlog, but that languished as one of the main difficulties of the FAQ format is that many of the questions are not really all that “frequently asked.”

We'll discuss with the @dita-ot/docs team whether to include this within the docs, or elsewhere on the project website.

[raducoravu]

Maybe then you can close this one as a duplicate.

[infotexture]

Actually, I'll close the other & leave this open, as I'd prefer to view this as a documentation issue.

[stale]

This issue has been automatically marked as stale because it has not been updated recently. It will be closed soon if no further activity occurs. Thank you for your contributions.

[CsatariGergely]

We would be happy to work on creating a FAQ page, and reuse @raducoravu -s blogpost as the seed of one. Are there any objections?

[raducoravu]

@CsatariGergely do you mean this older blog post I made:
https://blog.oxygenxml.com/topics/ditaOTFAQ.html
?
It's probably out of date in some parts but personally I do not object to you using its contents or starting from it to create an improved FAQ.

[CsatariGergely]

Yes, exactly, thanks for the offer to use your blog as a starting point.

[infotexture]

@CsatariGergely Thanks for picking this one up. I'll reopen the issue.

Radu's post is a good start.

See also dita-ot/website#1 for additional suggestions.

[EditKoselak]

Hello,

Do we want this to be a part of the documentation, or should it appear somewhere else on the website?
I assume this determines the format we use. If it will be a part of the website, we could go with the original suggestion and create it as an .md file, otherwise we could use a .dita topic, possibly one with a Questions and Answers topic type, and we could add it as a new main chapter before Resources.

What do you think?

I noticed there is an FAQ.md file in the repository: FAQ.md
I don't see its content in the published documentation, and I'm not sure if it's meant for customers. Is that related to this issue?

I went through the questions in @raducoravu's blog and the ones in the original issue, here is a proposal on which questions to include:

What is DITA?
DITA is the Darwin Information Typing Architecture, an XML standard for authoring modular documents with an emphasis on reuse, maintained by the DITA Technical Committee at OASIS.

What is the DITA Open Toolkit?
The DITA Open Toolkit (DITA-OT) is a publishing tool used to convert DITA content into various output formats. It's official web site, containing download links and documentation can be found here: http://www.dita-ot.org/.

How do I use the DITA Open Toolkit?
You can download, install and build output from DITA content using the command line.
Besides this, there are applications which come with the DITA Open Toolkit bundled. For example Oxygen XML Editor comes bundled usually with the latest bundled DITA Open Toolkit. Oxygen provides visual means to run the bundled DITA Open Toolkit using a concept called transformation scenarios.

What version of DITA Open Toolkit should I use?
You should try to use the latest DITA Open Toolkit release available on the official download page.

What outputs can I obtain using the DITA Open Toolkit?
The entire set of default available output formats is available here: https://www.dita-ot.org/dev/topics/output-formats.html. But the DITA Open Toolkit can be enhanced by installing plugins to provide additional output formats.

What is the general architecture of the DITA Open Toolkit?
The DITA Open Toolkit is a quite large mixture of ANT build scripts, Java libraries and XSLT scripts. It has a pipeline-based architecture which uses plugins to publish DITA content to various output formats. Most of the DITA Open Toolkit customizations that you want to make in order to add new publishing capabilities or to customize existing publishing choices can be made without modifying its internal core.

What is a DITA Open Toolkit plugin?
A DITA Open Toolkit plugin can either provide a new publishing format, customize an existing publishing stage or provide a DITA specialization vocabulary. The plugin can use one of the numerous extension points available in the DITA Open Toolkit: https://www.dita-ot.org/dev/extension-points/plugin-extension-points.html.
Once you have created a plugin you can install it in the DITA Open Toolkit either by manual installation or using the new automated installation procedure.

How do I customize the HTML-based outputs?
There are a number of parameters which can be set to customize the HTML-based outputs: http://www.dita-ot.org/dev/parameters/parameters-base-html.html. For example you can specify your own CSS stylesheet to be used with the generated HTML output.
You can also create a plugin to customize the HTML outputs by adding a custom XSLT stylesheet: Creating a simple DITA Open Toolkit plugin to customize published HTML and PDF content.

How do I customize the PDF output?
Oxygen comes bundled with a DITA Open Toolkit plugin which uses CSS to style the DITA content and produce PDF: https://www.oxygenxml.com/doc/ug-editor/topics/pdf-css-customization.html. This plugin is free to use from inside Oxygen but is part of a commercial product if you want to automate the publishing on the server side. This is our recommended plugin for publishing DITA to PDF.
In addition the DITA Open Toolkit comes bundled with a free PDF generation plugin which uses XSL-FO. The PDF output is obtained by passing the original DITA content to XSL-FO and then generating PDF using an XSL-FO processor. The default bundled and used XSL-FO processor is the Apache FOP but you can also install separately and use commercial PDF processors like Antenna House or RenderX XEP.
You can customize the PDF output either using a PDF customization folder or by creating a PDF customization plugin.
There are a number of other solutions for obtaining PDF from DITA: Possibilities to obtain PDF from DITA.

The list of questions that aren't included in the suggestion:

1. How does the DITA-OT relate to DITA on the whole?
   The DITA Open Toolkit is an open source implementation of the DITA standard. The Open Toolkit only processes DITA XML files into output, like PDF and HTML.
2. What's required to run the OT? What platforms are supported?
   • java 6+
     The DITA-OT will run most places that Java will run.
3. What are some alternatives to the OT?
   • Ditac
   • DITA2GO
   • FrameMaker v11+
4. What stages of the processing are usually [loaded term perhaps?] extended by users?
5. What skills are needed for administering use of the OT
   An understanding of java/Ant errors and the DITA build process.
6. What skills are needed extending the OT?
   An understanding of XSLT, Ant, and possibly java, depending on the nature of your extension.

[raducoravu]

The java 6+ part is incorrect, the most recent DITA OT version requires Java 17 or later:
https://www.dita-ot.org/dev/release-notes/#ariaid-title2

[infotexture]

@EditKoselak Thanks for picking this up.

Do we want this to be a part of the documentation, or should it appear somewhere else on the website?

We've gone back and forth on this over the years, but we discussed again and agreed that since the answers here aren't specific to any particular version of the docs, the content would probably be better published on the project website as originally suggested in dita-ot/website#1.

So the next step would be to submit a pull request for the dita-ot/website repository that creates a new faq.md file at the root level of the repo. I would then take care of linking that in the site navigation.

I noticed there is an FAQ.md file in the repository: FAQ.md

This is an unrelated file from the DITA-OT PDF Plug-in Generator wiki, which is not included in the published version of the DITA-OT documentation.

[EditKoselak]

Hello,

We've created a new pull request in the website's repo: dita-ot/website#805