Styleguide in DITA framework

[Frank Ralf]

Hello,

I've stumbled across the styleguide folder in oXygen's DITA framework ({installation_dir}\Oxygen XML Author 15\frameworks\dita\styleguide). There's a reference "From The DITA Style Guide - Best Practices for Authors (Tony Self) (http://www.ditastyle.com)" in the contentFilter.xsl file but I've found no further documentation.

Can anyone shed some light on this?

TIA
Frank

[Radu]

Hi Frank,

The DITA Style Guide by Tony Self is available in WebHelp format on the Oxygen XML Web site:

http://www.oxygenxml.com/dita/styleguid ... index.html

When you press ENTER when editing a DITA topic in the Author visual editing mode and Oxygen presents the content completion window, for some DITA elements (for codeblock for example) it presents in the documentation window next to the elements list a link to the DITA Style Guide.
The same is done when the tooltip is shown when hovering over a certain element, the tooltip has a reference to the DITA 1.2 specification and for a few elements references to the DITA Style Guide.

Now going back to the contentFilter.xsl you found, originally we wanted to include the entire style guide set of HTML resources bundled in each Oxygen installation. And that XSLT was meant to be dynamically applied to clean each HTML page and display it inside an internal documentation window inside Oxygen.
This mechanism we built of providing style guide references for each DITA element is generic, for example a company can have its own style guide and for its users provide for each DITA element references to its internal style guide web site.

Regards,
Radu

[Frank Ralf]

Thanks for the quick reply, Radu. This sounds like a great feature. Where can I find instructions on how to provide custom help for my oXygen users?

Kind regards,
Frank

[Radu]

Hi Frank,

Let's say you create a folder somewhere on your hard drive in which you copy the entire contents of this folder:

OXYGEN_INSTALL_DIR\frameworks\dita\styleguide

You can remove the folder rules which is not useful for this.

Then in the Oxygen Preferences->XML / XML Catalog you add a reference to the catalog.xml from that folder. The content completion support Oxygen has for DITA will try to find the contentCompletionElementsMap.xml file by resolving through the XML catalogs support in Oxygen the URI:

http://www.oxygenxml.com/dita/styleguid ... ntsMap.xml

Then if you open the XML contentCompletionElementsMap.xml from your custom folder you will see that it contains mappings between various DITA elements (and attributes) and HTML documents.

Code: Select all

<mappingGroup

    xml:base="http://www.oxygenxml.com/dita/styleguide/webhelp-feedback/">

......................

    <mapping elementName="abstract" path="index.html#Artefact/Syntax_and_Markup/c_Abstracts.html" type="link" linkText="DITA Style Guide"/>

.........

If the @type of the mapping is "link" then, the documentation for that element will contain a link to that HTML file. The @path attribute value is added to the xml:base value specified on the mappingGroup to compose the entire link URL.
If the @type attribute is missing on the <mapping> element then the HTML page itself will be shown in-place in the Oxygen internal content completion documentation window after it was filtered and possibly simplified using the contentFilter.xsl stylesheet located in the same folder. HTML rendering support in the internal browser window Oxygen uses is quite primitive and it cannot handle very well links from the HTML page to CSS or Javascript resources, this is why we prefer by default to show links to the HTML pages and not to embed them directly.

Regards,
Radu

[Frank Ralf]

Thanks for the thorough instruction, Radu. That's quite cool and I hope to try that soon.

Kind regards,
Frank

[Frank Ralf]

Just a clarifying question: Is this the same mechanism that drives the Dynamic Help View?

Frank

[Radu]

Hi Frank,

No, this styleguide mechanism presents annotations (which can be HTML-styled) for each element when the content completion window is shown (ENTER pressed in the Author editing mode). The same annotation for the current element is presented in the Model view.

The dynamic help is a view which shows topics from our user manual depending on the current focused component in the application.

Regards,
Radu

[Frank Ralf]

Thanks for the clarification, Radu. So we have the choice between two context sensitive help mechanisms

[jlmalin]

Is there an offline version of the DITA Style Guide? I can't find it anywhere else, and the book is out of print. There are copies bouncing around the Internet, but they start at $86! I'm more interesting in having a PDF or ePub version, anyway.

[Radu]

Hi,

I googled for this and it seems Scriptorium has a free EPUB for download:

http://www.scriptorium.com/books/#dsg

Regards,
Radu