Discusses the challenges for HTML-type presentations caused by the DITA 1.3 branch filtering feature, in particular, the fact that the same topic can result in different renderings when used in different filtered branches or different key scopes.

1. The Many-Headed Hydra of Branch Filtering
Rendering Reused DITA Topics to
HTML With Different Filtering
Eliot Kimber
Contrext
DITA Europe 2016

2. About the Author
• Independent consultant focusing on DITA analysis,
design, and implementation
• Doing SGML and XML for cough 30 years cough
• Founding member of the DITA Technical Committee
• Founding member of the XML Working Group
• Co-editor of HyTime standard (ISO/IEC 10744)
• Primary developer and founder of the DITA for
Publishers project (dita4publishers.org)
• Author of DITA for Practitioners, Vol 1 (XML Press)
DITA Europe 20162

3. Agenda
• Reuse and EPPO
• Branch filtering and key scopes change
everything
• Recap and discussion
DITA Europe 20163

4. A BRANCH FILTERING TALE
DITA Europe 20164

5. Topics That Apply to Multiple
Conditions
DITA Europe 20165
<topic>
Installation
Text for Windows
Text for macOS
Text for Linux
Text applicable to all
conditions.
</topic>
<topic>
Getting Started for
WindowsmacOSLinux
</topic>

6. Used With Branch Filtering
DITA Europe 20166
<topic>
Installation
Text for Windows
Text for macOS
Text for Linux
Text applicable to all conditions.
</topic>
<map>
Getting Started
<topicref>
<ditavalref/> (Windows)
<ditavalref/> (macOS)
<ditavalref/> (Linux)
<topicref/>
</topicref>
</map>
<topic>
Getting Started for
WindowsmacOSLinux
</topic>

7. Publish to HTML
DITA Europe 20167
Generate
HTML
<topic>
Installation
Text for Windows
Text for macOS
Text for Linux
Text applicable to all
conditions.
</topic>
<map>
Getting Started
<topicref>
<ditavalref/> (Windows)
<ditavalref/> (macOS)
<ditavalref/> (Linux)
<topicref/>
</topicref>
</map>
<topic>
Getting Started for
WindowsmacOSLinux
</topic>
Getting Started
For macOS
Installation
Text for macOS
Text applicable to
all conditions.
Installation
Text for Windows
Getting Started
for Windows
Text applicable to
all conditions.
Installation
Text for Linux
Getting Started
for Linux
Text applicable to
all conditions.

8. What Did We Get?
• Six result HTML files where we started with
two source files
• Three HTML pages all with the title
“Installation” — bad
• Platform-specific text in each HTML — good
• Three almost-identical navitation patterns —
may be good, may be bad
DITA Europe 20168

9. What Would Be Better?
• A single result HTML file
• Text as shown in the browser that reflects the
user’s desired platform
• A single ToC structure in the top-level HTML
page
• Or, per-platform navigation structures with
links from the one HTML page to other pages
that reflect a specific use context
DITA Europe 20169

10. In Short: Dynamic HTML
• One HTML page that reflects all the conditions
• Dynamic display of the content to reflect
user’s current condition set
• Dynamic display of links to reflect the user’s
current condition set
DITA Europe 201610

11. Dynamic HTML Reflecting Reader-
Specified Conditions
DITA Europe 201611
Getting Started
For macOS Users
For Windows Users
For Linux Users
Installation
Text for Windows
Text for macOS
Text for Linux
Text applicable to
all conditions.
Platform
Windows
macOS
Linux
macOS
Windows
Linux

12. How To Get This?
• Requires a different way of thinking about
HTML generation
• Requires more sophisticated HTML delivery
details to enable dynamic display
• Reader user interfaces for selecting current
conditions
• Appropriate display of conditional content
when no filtering is applied in the browser.
DITA Europe 201612

13. Every Page is Page One
DITA Europe 201613
“Include it all. Filter it
afterward”
http://everypageispageone.com
Mark Baker

14. REUSE AND DELIVERABLE
PUBLISHING
DITA Europe 201614

15. Publications
• DITA content has value because we publish it
• “publication”: Result of processing a root map
into a deliverable
– E.g., HTML, PDF, EPUB, online help, non-DITA XML,
etc.
• Specifically concerned with publishing for the
purpose of reading the content
DITA Europe 201615

16. Deliverable Types and Reuse
• “Monolithic” deliverable types:
– PDF, EPUB, etc.
– Reuse not an issue because the result is a single unified
narrative flow
– Navigation position is always unambiguous
• “Multi-file” deliverable types:
– HTML, etc.
– “one result file per source topic”
– Navigation position may be ambiguous for re-used topics
• For simplicity going to use “HTML” to represent all
multi-file deliverable types
DITA Europe 201616

17. DITA Versions and Reuse Features
• DITA 1.0, 1.1: Can’t actually do reuse reliably
(shhh don’t tell anyone)
• DITA 1.2: Addition of global keys enables
reliable reuse within limits
• DITA 1.3: Addition of key scopes and branch
filtering enables basically all reuse use cases
DITA Europe 201617

18. Re-Use Use Cases
• Same content used multiple times and filtered
different ways
• Same link from re-used topic resolved to
different targets in different use contexts
• Cross-deliverable links
DITA Europe 201618

19. DITA 1.2: Global Filtering
• Global filtering meant same topic used multiple
times must have exactly the same rendered result
in all use contexts
– Can have a single result HTML file regardless of
number of uses
– No way to have a single topic reflect different
conditions in different parts of the same publication
– Possible navigation ambiguity
• For topics that are mostly the same but need to
reflect different conditions must make copies.
DITA Europe 201619

20. DITA 1.3: Branch Filtering
• Different branches within a map can have
different filtering conditions
• A single topic reflecting multiple conditions can
produce different rendered results in different
use contexts
• Removes need for copies of topics that differ only
in conditional content
• Cannot have a single result HTML file in this
case…
…or so it would appear
DITA Europe 201620

21. Key Scopes: Same Implication as
Branch Filtering
• Different branches in the map may have
different key scopes
• Key reference in a topic used in different
scopes may resolve to different topics
• Same topic used in different contexts may
have different rendered results in different
contexts
• Again appears to require distinct result files in
the output
DITA Europe 201621

22. RECAP: WHAT DOES THIS ALL
MEAN?
DITA Europe 201622

23. Recap: Implications of Branch
Filtering
• A single source topic or branch can result in
multiple result HTML files
• Allows single publications that reflect different
conditions in different parts of the publication
• Can result in proliferation of almost-the-same
topics
– May be bad for search
• Suggests need for more sophisticated HTML
delivery
• Not a problem for monolithic deliverables
DITA Europe 201623

24. Implications for HTML Delivery
• Generate single HTML result files for given
filtered branch
• Include data in HTML needed to dynamically
render the result
– Filtering on the fly
– Flagging on the fly
• Provide user interfaces and access paths that
establish user’s current filtering content
• Need fallbacks for limited browser environments
DITA Europe 201624

25. As A Community
• Need to establish appropriate user interaction
approaches, principles, implementations
• Need library of common JavaScript and CSS
code to enable this type of delivery
• Need to enhance the Open Toolkit to produce
this type of HTML
DITA Europe 201625

26. Questions?
DITA Europe 201626

27. Resources
• Original WEK blog post:
http://drmacros-xml-
rants.blogspot.com/2016/05/delivering-html-
from-dita-in-face-of.html
• Every Page is Page One (Mark Baker):
http://everypageispageone.com/publications/
DITA Europe 201627