Website Questions

DaveP

Ok, with 99 per cent of the work done by Bob Stayton:-)

Bob kept mailing me entries which had cross references between questions, presuming it was a single file build. Using the latest website, there are seperate files for each section (or that's the way I use it anyway). Its fairly natural to want to refer to other question and answers so olink seemed about right. For those who (like me until last week) had never come across olink, tdg describes it as “ Unlike Link and ULink, the semantics of OLink are application-specific. OLink provides a mechanism for establishing links across documents, where ID/IDREF linking is not possible and ULink is inappropriate.” which isn't much help, is it. The application specific processing is the clue. Bob wrote a stylesheet to do the hard bit, so once I got my head round it, it wasn't too bad.

The mechanics of it all are explained in a document entitled OlinkHOWTO.html, which presently is found at Sourceforge, in the contrib section of the docbook part of sourceforge.

Put simply, its a one off activity to generate an extra file which tells the processor which files have links in them and an extra step prior to running the main stylesheets. Then you can use the olink markup between any two documents which make up the website.

Markup is fairly straightforward. The file holding the target must have an id on the webpage element, and the target wrapper is marked up with an id value. The source looks something like

The type is constant at 'stylesheet'. The targetdoc attribute is set to the id value of the webpage holding the

Bob Stayton

Well, there is a secret parameter named 'l10n.gentext.default.language' that is declared in the common/l10n.xsl stylesheet module. When processing DocBook documents, if you set that parameter to "de" then you get 'Kapitel 1' instead of 'Chapter 1', etc.. I haven't tried it in website, but I assume it would work since website imports the docbook stylesheet.

I say 'secret' because it hasn't been documented, but it probably should be.

Bob Stayton

Callouts placed with an areaspec require an XSL extension function. You turn that on by setting these two parameters:

and processing your file with Saxon or Xalan with the the appropriate DocBook extensions jar file in your CLASSPATH.

Bob Stayton

Actually, a feature like this is already a part of the website stylesheet. If you specify your css stylesheet using a <style> element in layout.xml instead of with an 'html.stylesheet' parameter, then you each generated HTML file references the same stylesheet file using relative paths. See the example layout.xml file included with the distribution.

Bob Stayton

The items you want to change are l:gentext elements as your original mail mentioned. So something like this in your customization layer:

<xsl:param name="local.l10n.xml" select="document('')" />
 <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
  <l:l10n language="en">
   <l:gentext key="nav-home" text="Table of Contents"/>
  </l:l10n>
 </l:i18n>
</xsl:param>

When the stylesheets are looking up gentext items, they consult $local.l10n.xml first, and then the language gentext file en.xml.

Bob Stayton

If you are using the stock stylesheets, I've found it easiest to put each qandaset into an actual section element.sagehill That way they get into the table of contents and can be easily chunked with chunk.xsl.

To get chunk.xsl to chunk at qandadiv boundaries would require customization of the chunking templates, which is challenging at least.

The problem I have with this solution is that I thought that I could move from my previous use of sections to the QandA tags. But I see that if I want chunking I have to keep my sections. So then it is not very clear to me what advantage QandA tags will give me ?

Well, you lose the higher level hierarchy containers if you use sections, but you keep the lower level question and answer elements, as well as some attributes for controlling numbering or labelling.

The reason chunking is not supported for qandaset is because such elements are not part of the document hierarchy, and so don't always form distinct chunking boundaries. That is, a qandaset is a block element, even though it can be large and complex. It can be preceded and followed by other kinds of block elements:

<para>Blah blah</para>
<qandaset>
 ...
</quandaset>
<para>More and more</para>

So how would such content be chunked? Print the preceding blocks, branch off to chunk the qandaset, and then return to print the following blocks? You would have to insert a reference in the middle to indicate there is a qandaset chunk, otherwise it wouldn't be obvious. That's why the chunking is always done at section boundaries.

There are a few exceptions. A legalnotice will be chunked out (and indicated by a generated "Legal Notice" link) if the "generate.legalnotice.link" stylesheet parameter is nonzero. So chunking on blocks isn't impossible to do, it is just that it has the potential to create a confusing navigational scheme.