Re: [docbook] Bridgehead alternatives

[Kate.Wringe@sybase.com]

Hi again!

What we'd like to do is go through and
tag our docs with DITA-like tags. We don't want to necessarily move to
DITA but we'd like
to mimic some of the DITA content analysis.
Our plan, at the moment, is to use the remap attribute to tag the content
as concept, task, and reference.
Within any sectn we can have content,
usually divided by bridgeheads, that needs to be tagged as concept, task,
or reference. That is, we can't simply
tag our information at the sectn level.
The  problem that we are running into is how to tag the content that
is within our bridgeheads. We need a tag that will
 contain the bridgehead and the
content underneath it.

Simplesect appeals to me because it
is different from sect1, sect2, sect3, sect4. Our writers would only have
to switch from using bridgeheads to using the simplesect tag.
We could use a sect2 with a role and
change the css in our XML editor (which is currently XMetaL but we are
also looking at Oxygen) so that the sect2 with the role looked like the
old
bridgeheads but it doesn't seem ideal
to me.

I think that there is a difference between
docbook versions 4.2 and 5.0 in how simplesects and sect1s are allowed
to exist.
In 4.2, from my understanding (and please
correct me!),  in a sect1 you can have

((refentry)*|
 zero or more refeintry
OR 
    sect2*|simplesect*))|
 zero or more sect2 OR
zero or more simplesect OR
  (refentry)+|
one or more refentry OR 
  sect2+|simplesect+)one
or more sect2 OR one or more simplesect AND
..
 (toc|lot|index|glossary|bibliography)*)

That is, in version 4.2 you can't have
a simplesect followed by a sect2; you can either have 
sect1
   sect2
   sect2...
OR 
sect1
    simplesect
    simplesect
....

However, in version 5, it appears that
within a sect1 you can have simplesects followed by sect2s.

• Optionally one of:
  • Sequence of:
    • One or more of:
      • sect2
      • Zero or more of:
        • simplesect
        • One or more of:
          • simplesect
          • Sequence of:
            • One or more of:
              • sect2
              • Zero or more of:
                • simplesect
                • One or more of:
                  • simplesect
                  
                  
                  
                  Kate
                  
                  
                  
                  
                  
                  
                  
                  Thomas Schraitle <tom_schr@web.de>
                  Sent by: tom_schr@web.de

                  02/04/2009 12:52 PM

                  To	docbook@lists.oasis-open.org
                  cc	Kate.Wringe@sybase.com, "Rowland, Larry" <larry.rowland@hp.com>
                  Subject	Re: [docbook] Bridgehead alternatives

                  
                  
                  
                  
                  
                  
                  Hi,
                  
                  > Right now we use sect1, sect2, sect3, and sect4. When we produce our
                  > output in HTML Help each sect starts a new page.
                  
                  You can configure that. See
                  http://www.sagehill.net/docbookxsl/ChunkingCustomization.html
                  
                  
                  > For example our table of contents can look like the following:
                  > sect1
                  >    sect2
                  >    sect2
                  >        sect3
                  >        sect3
                  >             sect4
                  >        sect3
                  >    sect2
                  >    sect2
                  >         sect3
                  > .........
                  >
                  > Currently, within each sect1, sect2, sect3, and sect4 we have bridgeheads.
                  > I like the idea of replacing the bridgeheads with a tag like section or
                  > simplesect and using renderas to make them appear like bridgeheads.
                  
                  I consider the bridgehead element as a kind of fallback mechanism when the
                  usual sect* elements are inappropriate. The bridgeheads circumvent a good
                  structure. In almost all cases, sectN or section are better elements.
                  
                  For example, you can customize the chunking mechanism very easily (see above).
                  But when you use bridgehead and need the same functionality, this would be
                  more difficult.
                  
                  
                  > Can I add <section> to the element definitions for sect1, sect2, sect3,
                  > and sect4? Is this a good idea?
                  
                  The standard DocBook schema (be it DTD or RELAX NG) does not allow this. Of
                  course, you could customize it, but I think this is not a good idea. Either
                  use sect1, sect2, ... or use nested section elements, but don't mix it. For
                  consistency  reasons stick to one method.
                  
                  
                  > My other thought was to change the element defintions for sect1 so that
                  > within a sect1 you could have simplesects followed by sect2s.
                  > For example:
                  > sect1
                  >        simplesect
                  >        sect2
                  >        sect2
                  
                  You don't have to, it is already there. See the content model of sect1:
                  http://www.docbook.org/tdg/en/html/sect1.html
                  
                  Do you really need simplesect? What would be the difference for you between a
                  normal sect2? For consistency reasons why not use a simple sect2 element?
                  
                  
                  Tom
                  
                  
                  
                  
                  
                  ---------------------------------------------------------------------
                  To unsubscribe, e-mail: docbook-unsubscribe@lists.oasis-open.org
                  For additional commands, e-mail: docbook-help@lists.oasis-open.org