Andy Hatton | 22 Sep 16:59 2014
Picon

DocBook XSL 1.78.1 copyright status

Hi,

I have been asked to investigate/verify the copyright status for the 
DocBook 1.78.1 stylesheets.

The distribution includes the COPYING file, which includes various 
copyright statements.

The copyrights run up to 2012, but 1.78.1 was released in 2013 (I 
think). The same statements are included in the current snapshot 
distribution.

Is this just an oversight, or has the copyright situation changed after 
2012?

Thanks

--

-- 
~~~~~~~~~~~~~~~
Andy Hatton
Janice Manwiller | 22 Sep 13:38 2014

Problems customizing WebHelp and HTML output

Still relatively new to DocBook.

In the doc set that I inherited, there are XSL files marked for FO (PDF), HTML, and WebHelp. Our doc build uses the Maven docbkx plugin to generate our documents.

I've been able use information from the DocBook XSL reference to make changes to the FO file and see the results in the PDF output. These changes include:

- Removing table and figure numbers
- Removing the lists of tables and figures
- Updating the cross-reference text to remove "the section called"

However, any changes I make in the HTML or WebHelp XSL files seem to be ignored. I've been able to update the CSS file to make changes to the look and feel of the output, but not any changes to the basic transformation.

For example, I added this chunk to the FO stylesheet to handle removing the table and figure numbers and updating the cross-reference text:

<!-- Eliminates the table and figure numbers. Also gets rid of "the section called" in cross-references -->
  <xsl:param name="local.l10n.xml" select="document('')"/>
    <l:l10n language="en">
      <l:context name="xref"> 
        <l:template name="appendix" text="%t"/> 
        <l:template name="chapter" text="%t"/> 
        <l:template name="section" text="%t"/> 
      </l:context> 
      <l:context name="title">
        <l:template name="table" text="%t"/>
      </l:context>
      <l:context name="xref-number-and-title">
        <l:template name="table" text="&#8220;%t&#8221;"/>
      </l:context>
      <l:context name="title">
        <l:template name="figure" text="%t"/>
      </l:context>
      <l:context name="xref-number-and-title">
        <l:template name="figure" text="&#8220;%t&#8221;"/>
      </l:context>
    </l:l10n>
  </l:i18n>

  <xsl:template match="table" mode="label.markup"/>
  <xsl:template match="figure" mode="label.markup"/> 
  <xsl:template match="appendix" mode="label.markup"/>
  <xsl:template match="chapter" mode="label.markup"/>
  <xsl:template match="section" mode="label.markup"/>


However, adding the same chunk to the WebHelp XSL file has no effect on the WebHelp output.

As another example, our HTML output still has section numbers. I added the following to the HTML stylesheet:

<xsl:param name="section.autolabel" select="0"/>

But that had no effect either - the section numbers were still there.

Am I missing something? Is there a difference in the transformation configuration for online output vs. PDF output?

Thanks,

Janice
Erik Rask | 22 Sep 12:13 2014

Olinking to section does not provide section number

When I use an olink to a chapter, I get the labelnumber element correctly represented. When I olink to a
section, I do not, and I get the message "Request for label of unexpected element: olink". I've tried
setting the xrefstyle with both "template:%n %t" and "select:labelnumber title" to no avail.

Is there a parameter I'm missing here, or is xsltproc not able to deduce labelnumber from section?

BR
Erik Rask
--
Technical Communication Team Lead
Procera Networks
Frank Arensmeier | 18 Sep 09:14 2014
Picon

Simplified DocBook RelaxNG schema not valid?

Hi there!

For a project I am working on, I did a couple of tests with the Simplified DocBook schema. The definition I
downloaded was 5.1CR3. When I open that schema in Oxygen I see a couple of validation errors:

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of start without "combine" attribute
Start location: 290:11

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of start without "combine" attribute
Start location: 2390:11

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of start without "combine" attribute
Start location: 6644:11

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of "db.admonition.blocks" without "combine" attribute
Start location: 6736:40

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of "db.os.inlines" without "combine" attribute
Start location: 6826:33

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of "db.programming.inlines" without "combine" attribute
Start location: 6835:42

System ID: /Users/brillo/Downloads/sdocbook.rng
Description: multiple definitions of "db.markup.inlines" without "combine" attribute
Start location: 6853:37

Most of these errors seem to be caused by the fact that there are some duplicates of element definitions.
Removing those duplicates however does not make Oxygen happy. Instead, it says: found element matching
the prohibited path start//empty in the simplified XML form of the schema[…].

What is going on here? Can this be fixed? Shall I file a bug report somewhere? Do pigs fly?
Thanks!

/frank

Frank Arensmeier
farensmeier <at> gmail.com
Richard Hamilton | 16 Sep 20:31 2014
Picon

Colophon doesn't reset footnote numbering

I just ran into a bug in the fo stylesheets.

If a colophon has a footnote (or a link and you've set ulink.footnotes) and the preceding chapter,
appendix, etc., also has a footnote, then the footnote numbering in the colophon will not start from 1; it
will start from where the preceding section ended.

It looks like the error is in the following two templates:

footnote.xsl: <xsl:template match="d:footnote" mode="footnote.number">
xref.xsl: <xsl:template name="ulink.footnote.number">

In both templates, the variable fnum is calculated using xsl:number.  I believe the error is that the from
attribute for xsl:number should include colophon, but it doesn't.

Given that there's a note stating "list in  <at> from is probably not complete", and given that making this
change fixed the problem, I think that's all that needs to be done to fix this bug.

Does anyone know if there is anything else that might have to be changed?

Best regards,
Dick Hamilton
-------
XML Press
XML for Technical Communicators
http://xmlpress.net
hamilton <at> xmlpress.net
Stefan Seefeld | 14 Sep 03:22 2014

support for xpointer

Hello,

Sorry if the following is slightly off-topic.

I'm trying to refactor a large docbook document (an API specification)
into multiple documents, including relevant chunks of content from a
"meta-model" document into a "language-bindings" document via xinclude /
xpointer.

I played a bit with the sample code from
http://www.sagehill.net/docbookxsl/ModularDoc.html, using xsltproc
(Using libxml 20901, libxslt 10128 and libexslt 817) on Fedora 20, with
mixed results. While I got simple cases working, slightly more advanced
cases led to wrong results, letting me doubt the quality of the
implementation of xpointer support in xsltproc.

Can anyone confirm the state of xpointer support in xsltproc, or any
other Free XSLT processor for that matter ? (For example, what about
saxon ?) Are there any (free) test suites that I could use to get a
sense of what is supported and what not ?

Many thanks,
        Stefan

--

-- 

      ...ich hab' noch einen Koffer in Berlin...
Warren Young | 12 Sep 00:19 2014

Re: Workaround for xinclude path bug, fixed in xsltproc 1.1.27?

Accidentally took this off-list:

On 9/11/2014 14:49, Bob Stayton wrote:
>
> There is nothing the XSL process can do to correct this problem, as the
> resolved file does not have the information necessary to locate qux.txt.

Though I posted this to the DocBook list, I wasn't expecting a fix to 
the stylesheets to work around this xsltproc bug.  I was just hoping 
that there were enough people here using xsltproc that I might find 
someone who had run across this years ago, before it got fixed, and 
worked around it in some clever way.

The question would be more on-topic on the libxslt mailing list, but 
they'd probably just tell me to upgrade.

> If those links are autogenerated,

This is static user documentation for an open source library.  The 
generated files are really just preprocessed, to add or remove a few 
things; they are not fully generated.

If you build the docs in-tree (./configure && make), the generated files 
and static DocBook source files end up in the same directory, so there 
is no problem.

The problem comes when you use the build system's ability to build 
outside the source code tree.  In that case, you end up with about half 
the files -- the ones lightly preprocessed -- in the build tree and the 
rest left behind in the source tree.  You can use xsltproc --path 
feature to point to both directories to cope with this, unless you're 
using an old xsltproc and you have an XInclude in a build tree file that 
refers to a file in the source tree, which in turn XIncludes a file that 
lives in the build tree.  Older xsltprocs can't follow that double 
indirection.

I think I'm just going to say the minimum version is 1.1.27.  That will 
give me the excuse I need to move to DocBook 5.  I couldn't do it before 
because I support some really old systems, and I only want to support 
the DocBook XSL files that come with the OS.
Mary Tabasko | 11 Sep 02:59 2014

Webhelp adventures: the gory details

Hi, all.

In my excessively long "Adventures in Webhelp" note, I offered to provide
some of the customizations I did to interested parties. I have attached
three stylesheets and one Perl script. (This note probably won't make much
sense if you haven't read that prior one, since I refer to issues noted there.)

I have attached the stylesheet I use to generate a single, generic sidebar
TOC into a file as a preprocessing step. This is not dependent on any of
the webhelp stylesheets, though it consists of the TOC-building template
from webhelp. The main stylesheet is the one that contains the customizations
I made for generating the chunked HTML. This is where I refactored some of
the templates, parameterized some of the customization hooks that weren't
parameterized, and otherwise overrode a bunch of webhelp-common.xsl.
The third simply contains my modified "object.id" template, which is imported
into the other two.

The Perl script is run as a preliminary step for doing search indexing.
It has two main jobs: fixing that unclosed meta tag (Content-Type) (which
is what I wrote it for originally), and adding "webhelp-currentid" at the
right place in each file's copy of the sidebar TOC.

Note that these are NOT exactly the version we use, since I have
stripped out some non-webhelp-related customizations, and some "corporate"
branding things. (The only one that's substantially different is the HTML chunking
XSL. The rest were so small and generic that there wasn't really
much to remove. But all the "webhelp"-related stuff is here.)

I've also attached a screen shot that shows what our webhelp looks like.
The content is the README from the DocBook webhelp itself.

Here is the basic build sequence we use. We have a TON of Ant scripts,
and I'm not going to try and provide them, since they are highly specific
to our environment, and not easily "genericized". I'll be happy to answer
any questions about what the steps do, but most of this is straightforward
if you've got webhelp already building.

A couple of things to note:

  * The <book> documents we wrap into <set>s are all stand-alone, so we are
    NOT doing o-linking between them. There are no passes
    to generate target databases.

  * We are also NOT profiling. 

This is what we do for each of our "helpset" documents (XML <set> files
that xinclude one or more <book> documents):

1. Delete any old output tree, and create a new output tree. This will
   be zipped up for installation with the product. (This structure
   is basically the webhelp template, with some additional directories
   for our product images.)

2. Copy our CSS file into the expected location in the output tree.

3. Copy our doc-related graphics into the output tree. This includes our
   content graphics, admonition icons, and HTML-specific icons.

4. Copy the parts we are using from the DocBook Webhelp template
   into the output tree. We skip a lot of the "common" images (because
   we replace them with our own in the next step), and some of the JS library
   images (like callouts), which we just don't use or need.

5. Copy our modifications to the DocBook Webhelp template
   into the output tree. This is mostly images, but we also have a
   modified version of "main.js" (we commented out a block of code
   as a solution to a problem with within-page links, and we changed
   some of the hard-coded colors. No other changes were made).

6. Generate the generic sidebar TOC using XSLTproc and "mt-webhelptoc.xsl".

7. Generate the webhelp HTML files using XSLTproc and "mt-wehbelp.xsl".
   This step splices a copy of the generic sidebar TOC into each file.

8. Generate the search indices. This actually is three steps:

   First, we run the "post-process-html" Perl script on the HTML files.
   This fixes an issue with an unclosed "meta" element and adds the 
   "webhelp-currentid" to the right place in the generic sidebar TOC for
   the file being processed.

   Second, we run the "IndexerMain" class from the DocBook stylesheets.

   Third, we delete the temp files generated during search indexing but
   not used in running searches.

The output tree is then zipped up for installation with the product.

Again, I do not suggest that the customizations I have made are in any
way suitable for general-purpose use, but perhaps they may inform some
discussion for possible refinements. I hope someone finds this at least
interesting. Feel free to contact me directly if you want

Thanks for hanging with me this long!

-- Mary
Attachment (mt-webhelp.xsl): text/xml, 41 KiB
Attachment (mt-webhelp-ids.xsl): text/xml, 4252 bytes
Attachment (mt-webhelp.post-process-html.pl): application/octet-stream, 6935 bytes

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe <at> lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help <at> lists.oasis-open.org
Peter Fleck | 10 Sep 17:21 2014
Picon

Splitting Chapter label and Title in html output

Hi all,

Is it possible to split the Chapter label and Title in the html output. 
I want to have:

Chapter 1.
The title of the chapter

I did it ages ago on the FO output but can't replicate what I did for 
the html. Which template should I be modifying?

Thanks,

Peter
Warren Young | 9 Sep 21:26 2014

Workaround for xinclude path bug, fixed in xsltproc 1.1.27?

Take these three files:

foo.dbx:

     <?xml version="1.0" encoding='UTF-8'?>
     <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

     <article>
       <title>Test</title>

       <xi:include href="bar.dbx"
         xmlns:xi="http://www.w3.org/2001/XInclude"/>
     </article>

bar/bar.dbx:

     <?xml version="1.0" encoding='UTF-8'?>
     <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

     <sect1>
       <title>Article Section 1</title>

       <para>
         <xi:include href="qux.txt" parse="text"
           xmlns:xi="http://www.w3.org/2001/XInclude"/>
       </para>
     </sect1>

and qux.txt:

     Hi, I am the article's real text.

Now write them to disk, so that foo.dbx and qux.txt are in the current 
working directory, and bar.dbx is in a bar subdirectory.  Then try to 
create an HTML version of the combined document:

     $ xsltproc --xinclude --path .:bar /path/to/html.xsl foo.dbx

You can use any stylesheet you like, it doesn't matter.

If you use xsltproc 1.1.27 or newer, it builds successfully.

Any older version will fail on the second xinclude because it apparently 
binds the "bar" path it determined for the first xinclude to the second 
xinclude call, so it erroneously goes looking for bar/qux.txt instead of 
going back to the --path value and searching all of the directories given.

The problem is, 1.1.27 came out about three years after 1.1.26, so a lot 
of systems will have this problem.  I can't just ask the whole world to 
upgrade to 1.1.27 or newer.

So, does anyone have a workaround for this?

Assume that I cannot know the relative locations of all the files being 
xincluded.  All I get to know is that, at build time, I will learn the 
value for xsltproc's --path value, and that all of the files will be 
somewhere in that set of directories.

Just for completeness, this sort of thing happens when you're using a 
system like the autotools or CMake, which lets you have a build tree 
that is separate from the source tree, and some of your xincluded files 
are generated.  The generated files end up in the build directory, so 
you can end up with xinclude jumps back and forth between the two trees.
Mary Tabasko | 9 Sep 02:45 2014

Webhelp: My adventures therein

Hi, all.

Here is the promised write-up of my adventures with Webhelp. It is long,
so if you don't care, don't bother reading any further! But I hope some
of you find it helpful. I apologize for the length, but this way, at least
it's one big message for those who don't care, not a bunch of irrelevant
little ones.

-- Mary

Background:

  For one of our products, we have a doc set that currently consists of
  three PDFs and two Microsoft Help CHM files.

  PDFs:
    Admin guide: 679 pges (13.1 MB)
    User Guide:  792 pages (61.6 MB)
    What's New: 36 pages (2 MB)

  CHMs:
    Admin Helpset: 72.5 MB (includes content of
         Admin and User Guides, and What's New)
    User Helpset: 62.9 MB (includes content of User Guide)

  We have been have had issues with the ancient MSHelp compiler
  over the ages, and have been getting increasingly worried about
  its continued viability. It does some strange things on 64-bit
  systems. So we have been looking to replace it.

  These documents (and many more) are all built using a homegrown
  toolchain. The documents are mostly written in DocBook (v. 4.4) and
  converted into various formats using the DocBook stylesheets and
  customizations. (Some are written in other XML that we convert to
  DocBook 4.4 using some combination of Perl and XSL.)

  We use Ant, XSLTproc, XEP, Perl, and various other tools to build our
  docs on both local "development" systems (desktops) and on our
  build system, with nightly and on-demand builds. We have an entire
  set of XSL stylesheets that customize the DocBook stylesheets for
  our "corporate" and "product" styles, and then each project may have
  a project-specifc stylesheet that tweaks the corporate ones. So a
  project's stylesheet may import a corporate stylesheet, which in turn
  imports the DocBook ones. Or a project sheet may go straight to DocBook XSL.

  Due to corporate restrictions, it is generally not easy to upgrade
  things, so we tend to not bother unless we really have to. As a
  result, we had been using DocBook 4.4 and DocBook XSL 1.74.3 for
  ages.

  While researching options to replace the MSHelp format, we found
  nothing that was both suitable and corporately allowable until we
  noticed that Oxygen (one of the XML editors we have in-house)
  had a "help" format that looked intriguing. After digging into
  it, we discovered that it was based on the webhelp transforms
  in DocBook XSL 1.76.0. Based on some experiments with the stylsheets
  in Oxygen, we bit the bullet to get the latest and greatest
  DocBook XSL release. The format looked like it would do a lot
  of what we wanted, and it was based on the already-established
  toolchain, so we wouldn't have corporate issues. Could
  make it do what we wanted?

  We were eventually able to create webhelp docsets that we could
  use to replace our CHM archives, but it was non-trivial. The
  rest of this describes some of the issues we encountered and how
  we addressed, or didn't address, them. But without the DocBook XSL,
  we would have been SOL. :) So thank you all again for this wonderful
  resource!

  Dramatis Personae
    DocBook 4.4 DTD
    Docbook XSL 1.78.1
    XSLTProc using libxml2 2.7.3; libxslt 1.1.24
    Xalan (for indexing): Xalan-J 2.7.1
    Perl, Ant, homegrown XSL, and other supporting players

Issue with the "Content-Type" meta element.

  A "meta" element for "Content-Type" is written into each
  of our HTML documents; it has the form of an "open tag":
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">,
  but it is stand-alone.

  The search indexer balks at this (and any other unclosed tags), and
  indexing fails. Changing the element to <meta ... /> solves
  the problem. I haven't been able to figure out where
  this comes from in the XSL transforms, so I was not able
  to use XSLT to fix it. (This may be an artifact of some of our
  out-of-date tools.)

  I ended up writing a trivial Perl script that would be
  run on all the generated HTML files before the search-indexing
  step, to change <meta ...> into <meta .../>. Inelegant, but
  effective. This turned out to be really useful later....

Issues with the sidebar TOC.

  The generation of the sidebar TOC for each HTML page bogs down
  the processing on large documents. 

  Generating the HTML for our old HTMLHelp format takes less than
  2 minutes on our largest doc. When I ran that doc through the
  Webhelp transform, it OOMed after 6 hours. I noticed that the
  default chunking level was much higher than what we used for
  HTMLHelp and wondered if that might be part of the problem. When
  I changed it, the processing completed successfully in about 2 hours.
  (That would still be a show-stopper for our nightly builds.)

  But that the time it took to process was so strongly related to
  the number of files it was creating made me suspect the sidebar
  TOC was the culprit. (I have to admit that it never occurred to
  me to look for a bug report. I didn't find that until much later!)

  It took some investigation to determine that the TOC generation
  was indeed the problem, but once I narrowed it down, I split the
  HTML generation into two steps. I lifted the template that
  generates the sidebar TOC into a separate stylesheet, and
  pre-generated a single file containing the sidebar TOC
  (the <ul id="filetree"> list) as a preliminary step.

  When generating the chunked HTML, instead of regenerating the
  TOC for each file, we simply read in the pre-generated file.

  Two issues with this:

  1. I needed to use the "generate.consistent.ids"
     parameter to keep the generated IDs in sync between
     generating the sidebar TOC and the standard HTML. I had
     never encountered that parameter before; I was worried I would
     have to solve this myself, so yay again for the stylesheets!
     (These generated IDs caused another issue, though, described later.)

  2. Since the TOC was pre-generated once, we lost the insertion
     of the "webhelp-currentid" attribute for each file. We were
     willing to take that loss if necessary, especially given
     that the ToC doesn't "stick" (bug 1226, which we did not attempt
     to address). But it wasn't.

     Since I already had a Perl script that would be run on all the
     generated HTML (to fix the "meta" element mentioned above),
     it was trivial to add a step to reinstate the "webhelp-currentid"
     attribute at the right place in each file.

  Handling the sidebar TOC this way kept the processing time to
  under 2 minutes with no loss of functionality. I realize that this
  is NOT a general solution and probably not suitable for everyone, but
  given our build environment and the tools we have available, this was
  expedient and fit into our "ecosystem" just fine.

  This doesn't address the issue of embedding this TOC in every file.
  (I hadn't seen the proposed solution noted in bug 1259 before implementing
  my solution, and I'm not sure I'd be allowed to just download it
  (corporate policy, esp. since it includes more JavaScript).

  We are seeing some issues with the "expand/collapse" indicators on the
  sidebar TOC. The "treeview" JavaScript inserts "class" attributes
  with values like "collapsable" and "expandable" to indicate the
  state of the TOc entry (embedded lists). We often see expanded
  lists given the attribute "expandable" rather than "collapsable",
  which means that the "rollup" indicators are incorrect. This seems to
  happen mostly with pointers to sections inside pages, so I suspect
  that this is an interplay between the chunking level and the
  "treeview" JavaScript. (I suspect that it doesn't happen if each link
  goes to a separate page (or at least that no page contains more than
  one level of expandable sections). I tried to run this down
  to the source (the stylesheets only provide the minified JS library),
  but it looks like this library went out of support in 2010 and is
  no longer being maintained. (Because of corporate policies, I can't
  casually download the original JS library.) Since this affects only
  the visual collapse/expand indicators, not the functionality, we are
  willing to live with it for now.

Issues with links to local (within-page) IDs.

  We noted that within-page links did not work. We found the
  messages on the docbook-apps list about this, and tried
  commenting out the salient block in the "main.js" file. This
  fixed the problem for most links within a page (those within "content".
  (We tried using the fix in the later snapshot, but we didn't see any
  difference.)

  We also noted another problem with generated links from the sidebar TOC.
  If you were on a page like, say, "bk01.html" and tried to navigate
  to "bk02ch01s04#id-4.1.3.4.6" (a totally made-up id value, but
  the format is what we got), the correct page and local link would load
  (that is, the new page would be scrolled to the local link), but the
  sidebar disappeared, and the sidebar toggle would not bring it back.

  (Clicking the Next link followed by the Previous link would restore
  it, but the direct navigation from the sidebar TOC always clobbered the
  sidebar.)

  The problem only occurred with generated IDs. Navigating from the
  sidebar TOC on "bk01.html" to "bk02ch01s04#using-passwords" worked
  fine. Looking at the gross structure of the links in the sidebar
  TOC revealed no differences. The difference had to be in the structure
  of the values of the IDs.

  By default, the "object.id" template with "generate.consistent.ids"
  set makes values like "id-4.2.6.3". I played around with these values
  a bit and determined that changing the "dots" to "dashes" solved the
  problem. That is, links with id values like "id-4-2-6-3" worked just
  fine. (The original ids work fine within the content block; it's only
  using them from the sidebar TOC that causes the problem.

  I could find no way to tell the "generate-id" function to alter this
  structure, so I had to override "object.id" and do it myself. (The
  problem appears to be in some piece of JavaScript, but I have not
  attempted to find it. The browser follows the links fine.)

  For completeness, I put "." characters into a couple of our explicitly
  provided IDs and the links to them. They then exhibit the same problem:
  the sidebar does not appear when you traverse to such an ID. (This
  was not a browser-specific problem, either.) 

  Note: Unless you have "." in your explicit IDs or have set
  "generate.consistent.ids" for some other reason, this issue wouldn't affect
  anyone who didn't generate the sidebar TOC separately like we did.

Issues with styling and layout.

  The webhelp XSL templates provide some customization mechanisms, but
  we found that we often needed to override pieces that provided no
  handy hooks. And having our CSS file as the first one in the doc
  header meant that it was constantly fighting with the "built-in"
  stylesheets ("positioning.css", the Jquery stylesheets, and the
  CSS elements embedded right into the pages). There were some CSS
  items we could not figure out how to override using just our stylesheet.

  We spent a lot of hours simply trying to figure out where some bit of
  styling was coming from, and then more time trying to figure out how
  to override it. I eventually decided that trying to work around that
  huge block of CSS imports, JavaScript, and embedded CSS in every page
  wasn't worth the effort.

  In the end, I ended up taking apart the "user.head.content" template
  in "webhelp-common.xsl" and refactoring it. I tried to use only the
  customization hooks that were provided, but I just couldn't do it. :)

  I broke "user.head.content" into several smaller templates (one to insert
  CSS imports, one to insert JavaScript, etc) and reimplemented the
  original template simply to call the other templates. That way, I could
  selectively override the parts I wanted/needed to. I could then easily
  import our stylesheet last, which let me move all of the CSS elements that
  were being embedded into each page into the our CSS instead (and change
  them). 

  This made styling the documents MUCH easier. It also meant that
  I didn't have a big blob of CSS repeated in every HTML page.

  We wanted to change the layout of the items in the header, like the
  nav bar, to be consistent with other collateral we have. MOre overrides.
  I also found it necessary to parameterize some of the other templates
  (like "user.header.content") called from "chunk-element-content".
  I ended up overriding a LOT of stuff. Again, these changes are probably
  not ideal as general approaches (though I think breaking up some of the
  big templates and refactoring them, and maybe adding more parameterized
  customization hooks, are, but most of my fixes were geared toward solving
  my specific problem in my specific environment.

  I also found that we had to alter some of the colors embedded into
  "main.js" to get the effects we wanted. I really didn't want to have
  to change "main.js", but we couldn't find any other way to
  get the changes we wanted. (This was before we discovered the
  local-link issue that required us to change the file anyway.)

  There was no elegant way to override some of the JQuery styling,
  particularly replacing images. We simply had to replace their image
  files (keeping the names) with our images, since the JavaScript
  is responsible for getting the images in. We created a "customization
  template" (a directory with the same structure as the template, but with
  our project-specific variants (images, main.js) in it, and we simply
  slapped this on top of the template from the stylesheets when building
  the docs.

  The one thing that really drove us crazy was the fact that we could not
  figure out how to change the size of that header. We tried a bunch
  of different things, and in the end, we just dealt with what we had.
  I'm sure it's in that JQuery UI Layout stuff, but none of us was familar
  with that package, and we just didn't have the time to try to sort it out.

I would be more than happy to share the customizations we made to the
stylesheets, my Perl script and so on, if anyone is interested in seeing
them. Like I've said, my solutions are probably NOT general-purpose
solutions, but they worked for us and may be helpful to some of you.
I can also send a screen-shot of what our final output looks like.
I don't want to send this out generally, since I suspect most readers
of this list are not interested.

                                     -- 30 --

Gmane