Re: [docbook-apps] DocBook schema/DocBook XSL customization for teaching purposes

[Michael Smith <smith at xml-doc dot org>]

"Dimitry V. Ketov" <Dimitry.Ketov@avalon.ru> writes:

> Michael Smith wrote:
> <skipped>
> >
> >I personally would recommend adding new elements rather than using
> ...
> >
> >But if you decide to go with adding new elements, what you'll
> >probably want to do is to create an XSL stylesheet to take doc
> >instances with your custom elements and transform them into
> >"standard" DocBook before you generate any output from them. That
> ...
> >
> >The reason to do it that way is that you then don't need to do any
> >hacking of the DocBook XSL stylesheets.
> Yes, I have considered that way before. But I still need to hack DocBook's 
> XSL stylesheets to customize titleing and labeling (then "autoannotated" 
> elements with custom roles) in HTML/PDF output, e.g <section 
> role="exercise"> should give "Exercise 2.1: Title", rather plain section 
> title.

Is it possible that you might be able to the output you want by
doing the following instead?

  - use Sect1, Sect2, etc. instead of recursive Section

  - change gentext settings for Sect1, Sect2, etc.; for example,
    instead of outputting "Section" for Sect2s, output "Exercise":

      <sect2><title>Foo -> Exercise N.N: Foo

BTW, I guess you've probably already thought of this, but I think
you will need to be careful to make sure that your authoring
DTD/schema does not allow non-Exercise sections as siblings of
Exercise. Same thing for the ancestor sectioning elements of
Exercise. Otherwise, if you are doing autonumbering, you might end
up with stuff like:

  Course
    Module 1.1
      Topic 1.1.1
      Topic 1.1.2
        Exercise 1.1.2.1
        Exercise 1.1.2.2
        Section  1.1.2.3
        Exercise 1.1.2.4

> So what reason then not to build customization layer right over DocBook's 
> XSL styleets?

In general, IMHO, if there is an alternative, it's best to avoid
creating a DocBook XSL customization layer that does anything more
than "normal" changes. I mean changes to templates. Rather than
things like setting parameters or values in attribute sets,
titlepages tweaks, gentext changes -- the kinds of things that are
already designed/expected to be to changed by users.

When you make a change to a XSLT template, you have to copy the
whole template into your customization layer. So you do that and
make your customizations and get everything working. Then a new
DocBook XSL version is released that may include changes (bug
fixes or enhancements) to some of the same templates you have
copied into your customization layer.

So copying templates can potentially create maintenance problems
for you if/when you want to use your customization layer with a
later version of the stylesheets and want to make sure that you're
actually getting all the bug fixes and enhancements.

At a mininum, I would recommend that if you create new elements,
that you don't put those elements into your DocBook customization
layer. Set up a separate stylesheet to transform the new elements
into native DocBook ones, then pre-process your doc instances with
that stylesheet before using the DocBook XSL stylesheets.

I think that is the easier way to do it. And especially the more-
easy-to-maintain way to do it.

That said, I guess if you wanted to be able to have both
<section label="Topic"> and <section label="Exercise"> in your doc
instances, then yeah, I guess you'd have to do some template
customization to tell the stylesheets how to deal with them.

But for the structure you've described, you could maybe avoid that
by not using recursive Section at all and instead doing what I
mentioned before -- authoring with Sect1, Sect2, and Sect3 instead -

  Course -> Book
    Module -> Chapter
     Topic -> Sect1
       Exercise -> Sect2
              Lab -> Sect3

Then, you only need to make some gentext changes and can avoid
making template changes.

Yeah, I know that only works if, e.g., all your Sect2s actually
are Exercises. But I think you'd want to do it that way anyway --
otherwise you could end up with autonumbering weirdness.

But if turns out that you really need to use recursive Section
intead of Sect1, etc., I wouldn't recommend using the Role
attribute to indicate that a section is an Exercise. If you use
anything, I think you should use the Label attribute instead.

I'm not sure what (if anything) the stylesheets will do with Label
on Section now, but if you could come up with a way of
implementing <section label="Foo"><title>Bar such that it would
cause the stylesheets to generate "Foo 2.1: Bar" instead of
"Section 2.1: Bar", and could provide a patch, you might be able
to get it added to the DocBook XSL codebase. So you wouldn't need
to maintain a customization layer for it.

That's an enhancement that I guess might be of use to other
people. And it could be made configurable if it conflicts with
whatever the current behavior with respect to the Label attribute
on Section.

Hope that helps,

  --Mike

-- 
Michael Smith
http://logopoeia.com/ | http://www.oreillynet.com/pub/au/890

Attachment: smime.p7s
Description: S/MIME cryptographic signature