Add Known DITA-OT Issues to Docs

[shaneataylor]

Probably in the Troubleshooting section, not every issue but those that are common and which users might reasonably expect to work, but either don't, or don't work as expected.

Some possible candidates:

• Generating "accessible" PDFs with FOP
• Cases where reltables don't work
• Cases with keyref / conref resolution not working as expected

[shaneataylor]

As a matter of process, probably a specific ticket should be opened for each potential OT known issue to address in the docs, but this ticket can serve to start the work.

[infotexture]

👍 Makes sense.

Larger topics may require dedicated issues, but we can link to them here so we have an overview.

Once we have a section in place with initial topics, this issue can be closed and future topics can be proposed with new issues.

[shaneataylor]

Another issue for inclusion here: directory structure and map traversal. There are still problems that can occur with hierarchical directory structures — I encountered one when trying to use keys and keyrefs for the sample files in the docs.

[keberlein]

I think we certainly should have more robust troubleshooting information; the current content is weak. I think it needs to be grouped as "Troubleshooting"; we most definitely should avoid labeling it as "Known issues.

@shaneataylor I'm quite honestly not sure what you mean by the following items that you listed:

• Generating "accessible" PDFs with FOP

• Cases where reltables don't work
  

• Cases with keyref / conref resolution not working as expected
  

[infotexture]

See #64 for info on the first item. We plan to close that when FOP 2.1 is bundled.

[keberlein]

OK, so it looks to me as if "Generating "accessible" PDFs with FOP" is no longer an issue. What about the two other ones?

[keberlein]

On a different note, do we document anywhere the limitations of using FOP to generate PDF? Is that something that we should do? There are some things that require using a commercial tool (XEP or AH) ...

[shaneataylor]

Actually, those limitations are a good example of the intent of this issue.

I agree it's appropriate to include this information in Troubleshooting,
even if the resolution is simply to understand that a particular behavior
is not supported.

Regarding the first two items, I don't recall the specifics; I think they
were issues we had discussed around the tone this issue was created.

Another specific issue that occurs to me under this rubric is the OT has
limitations on processing glossary topics and keyrefs to them, without
additional customization.

[drmacro]

I'm implementing a new plugin that enables glossary sorting as we speak: org.dita-community.i18n

With that in place will be easy enough to implement general glossary generation and sorting in a separate plugin.

[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.