Re: docbook: about paragraphs, cross-references, indexes

[Norman Walsh <ndw at nwalsh dot com>]

/ Roy.Gardiner@natwest.com was heard to say:
| I am still quite ready to believe that I'm nitpicking. I am also prepared to
| offer suggestions for changes to the standard; I have not yet found the
| mechanism to do this. Does one simply email Mr Walsh? We need to anyway; Mr
| Maier has found a spelling error in TDG (line 27139)   :-)

Depends which standard you mean. If you have suggestions for DocBook,
please make them here. I believe that everyone on the Technical
Committee reads this list. If you mean TDG, or the stylesheets, or something
else, well...

Historically, emailing Norm has been the standard way. :-)

However, Michael Smith and I have recently setup a DocBook project at
SourceForge so you can use the Tracker features there to make requests
and report bugs.

Emailing Norm is still OK, but he's forgetful and the Trackers aren't.

| > Steffen.Maier@studserv.uni-stuttgart.de[SMTP:Steffen.Maier@studserv.uni-st
| > uttgart.de]
| > 
| > "Zone
| > 
| > The use of Zone implies a spanning index entry. Zone holds the IDs of the
| > elements to which it applies. Then IndexTerm applies to the contents of
| > the entire element(s) to which it points. If Zone is used, the phyiscal
| > placement of the IndexTerm in the flow of the document is
| > irrelavant." [TDG]
| > 
| Yes; but only for entries marking a range of text. TDG also says "A single
| point is marked with an Indexterm placed in the text at the point of
| reference". This markup: 
| 
| <INDEXTERM>
| <PRIMARY>DocBook</PRIMARY>
| <SECONDARY>Changes for <ACRONYM>V4.0</ACRONYM></SECONDARY>
| </INDEXTERM>
| 
| occurs in full over 40 times in TDG. Surely there must be a simpler way?

Entities are your friends.

| > Jirka Kosek[SMTP:jirka@kosek.cz]
| > 
| says:
| 
| > You can add role attribute to para and modify stylesheet.
| > 
| > Rendering of xref text is left upon stylesheets. You can very easily
| > modify both DSSSL and XSL stylesheets to include page numbers.
| > 
| Yes (and thanks for showing me how) but a design objective of DocBook is (I
| guess) to allow authors to create works using DocBook itself without
| modification.  I would like to have different styles of PARA in the
| standard.

The role attribute is the standard mechanism for this sort of thing.
(If you want to start a detailed discussion about how to support them
in your stylesheets, please post the relevant query to the docbook-apps
list.)

The important question is why do you want to have different styles? What
semantic information are you attempting to convey?

| TDG has many cross-references, none of which have page numbers. This means I

The O'Reilly style does not use page numbers in cross-references. That's
the only reason they aren't there. There's no technical reason why the
stylesheets couldn't have produced them.

| have 2 steps to find anything.  Does an attribute PAGE=YES/NO on XREF break
| the 'no formatting' rule of markup too badly? Non-print renderings would
| just ignore it anyway.

Yes, it does. Although there are exceptions where DocBook provides
formatting hints, for the most part these are pushed off to the
formatter.

If you want page numbers on your cross references, change the way your
stylesheet supports <xref/> to provide them. If you only want some of them
to have page numbers, use <xref role="some-hint"/>

                                        Be seeing you,
                                          norm

-- 
Norman Walsh <ndw@nwalsh.com>      | Simplicity is always a
http://www.oasis-open.org/docbook/ | virtue.--Edward Abbey
Chair, DocBook Technical Committee |

------------------------------------------------------------------
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: docbook-request@lists.oasis-open.org