Pages: 1
Print
Author Topic: How do you use <prereq> in web help?  (Read 4802 times)
kwag_myers
Member

Posts: 69


« on: January 06, 2011, 03:24:15 PM »

XMetaL Help talks about how the pre-requisite links are placed, etc., but I've yet to figure out how this works or found an example of a completed section.

In my published web help the Pre-requisite section displays as a paragraph with no title, i.e., nothing distinguishing it from any other paragraph. What I'm hoping for is something like:

Pre-requisites:

1. Read <link>Concepts</link>. This is good stuff to know.
2. Do <link>This</link>. Otherwise, it won't work.
Logged

XMetaL 6 Author in Windows 7 Home Premium
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2606



WWW
« Reply #1 on: January 06, 2011, 04:43:16 PM »

WebHelp relies on files included with the standard DITA OT XHTML transtype to transform to XHTML. This transtype does nothing special to identify the <prereq> element markup-wise in the XHTML; it inserts a <div> with a class attribute value of "p". If you want something else to appear in the output you will need to modify the XSLT.

The file that handles this part of the transformation is here:
....\DITA_OT\xsl\xslhtml\taskdisplay.xsl

Around line 65 there's a section that begins like so:
<xsl:template match="*[contains(@class,' task/prereq ')]" name="topic.task.prereq">
  <xsl:variable name="flagrules">
    <xsl:call-template name="getrules"/>
  </xsl:variable>
  <xsl:variable name="conflictexist">
    <xsl:call-template name="conflict-check">
      <xsl:with-param name="flagrules" select="$flagrules"/>
    </xsl:call-template>
  </xsl:variable>
<div class="p">
  <xsl:call-template name="commonattributes"/>...etc...


The second to last line above is probably where you will want to start mucking around.

The simplest thing to do would be to change the value for the class to be unique so you can more easily address it in your CSS. You might also stick in a heading, perhaps like so:

<xsl:template match="*[contains(@class,' task/prereq ')]" name="topic.task.prereq">
  <xsl:variable name="flagrules">
    <xsl:call-template name="getrules"/>
  </xsl:variable>
  <xsl:variable name="conflictexist">
    <xsl:call-template name="conflict-check">
      <xsl:with-param name="flagrules" select="$flagrules"/>
    </xsl:call-template>
  </xsl:variable>
<div class="prereq"><h2>Prerequisites:</h2>
  <xsl:call-template name="commonattributes"/>...etc...


Then in your CSS you can address that section and each portion it contains with specific styling if you want:

div.prereq {border:1px solid red}
div.prereq h2 {font-family: "Comic Sans"; font-size: 1.2em; color: red}


This change is not changing the Webhelp output directly, it is changing files in the XHTML transtype that are used by other parts of the DITA OT. This means it will affect WebHelp, but also CHM, Multiple HTML, Single HTML, Eclipse Help, Java Help, etc. I assume this is what you would want because then all your various HTML-like outputs will be similar.
Logged
kwag_myers
Member

Posts: 69


« Reply #2 on: January 07, 2011, 07:03:19 AM »

That works, thanks!

However, I'm still a bit perplexed by this statement in Help:

"Prerequisite links will be placed in a list after the related-links section; on output the <prereq> links from the related-links section are added to the <prereq> section."

I get the impression that, when <prereq> is used, an element in, or after <related-links> is made available in order to make a list. But I've played around with <related-links> elements and see nothing to indicate a "prerequisite link" or anything other than the usual elements.
Logged

XMetaL 6 Author in Windows 7 Home Premium
Derek Read
Program Manager (XMetaL)
Administrator
Member

Posts: 2606



WWW
« Reply #3 on: January 07, 2011, 12:09:45 PM »

This quote comes from the DITA Language Specification 1.1, which we include verbatim as part of our documentation so that you can access it easily for reference when working on DITA documents in XMetaL.

See: http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/prereq.html

This documentation (maintained by the DITA TC at OASIS) contains guidance on proper or suggested usage for elements. In some cases it also makes statements about how particular elements and attributes should affect output, but it was not written to describe the proper functioning of the DITA Open Toolkit (ie: it is an input into how the DITA OT is created, not written to describe what the DITA OT actually does).

The DITA OT is developed separately from this documentation as an open source project (hosted currently at SourceForge). I think that is where the disconnect is in this particular case. In most cases the DITA OT has implemented features following these recommendations but in some cases it may not have (either the implementation is incomplete or might be buggy). There are other solutions for generating output from DITA content and they will probably follow this documentation to a similar degree but implement things in different ways as well (see: ditac).

If you feel that the output is not correct (for any element or a particular set of documents) you can check on the status of existing feature requests and bugs (and file new ones) here: http://sourceforge.net/tracker/?group_id=132728
« Last Edit: January 07, 2011, 12:18:53 PM by Derek Read » Logged
kwag_myers
Member

Posts: 69


« Reply #4 on: January 11, 2011, 07:40:19 AM »

If you feel that the output is not correct...
Actually, it's more curiosity than necessity. I'll just use the <ul>. Thanks for the info.

edit: Which .xsl do I edit for my PDF output?
« Last Edit: January 11, 2011, 09:33:01 AM by kwag_myers » Logged

XMetaL 6 Author in Windows 7 Home Premium
Pages: 1
Print
Jump to:  

email us