docbook-apps

I'm about to start indexing a db5 book.
Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
been there and done that, got the tee-shirt and found the pitfalls in
docbook? Any advice from those with lots of experience of using
db indexes please?



regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Hi Dave,

Am Samstag, 5. Mai 2012, 08:10:05 schrieb davep:
> I'm about to start indexing a db5 book.
> Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
> been there and done that, got the tee-shirt and found the pitfalls in
> docbook?

I don't know this author, so I can only speak about the experiences of
indexing my book.


> Any advice from those with lots of experience of using
> db indexes please?

Are you asking more about the indexing task itself or about the technical
aspect?

Speaking about the indexing task itself, IHMO this is something that some
books don't take it seriously enough. An index is a service to make the book
more accessible to readers. I've seen lots of bad index which came just as an
alibi, but with no value.
So it isn't a surprise that a good index takes time and energy. When I've
created the index of my book, it took lots of iterations and I guess it still
isn't perfect. :)

What I've learned is this: don't write and create the index simultaneously. It
doesn't work (well, at least for me). Try to finish your book and when it's in
a decent state, then and only then, focus on the index. If you don't have an
idea what to index, look at other books. I've found O'Reilly books has mostly
good indices.

A good index should contain different "access paths". For example, if you want
to know something about namespaces in DocBook you can look it up as
"Namespaces > DocBook" or "DocBook > Namespaces". IMHO both are valid and
needed. Apart from this, try to be consistent. Either plural or singular, but
noth both. I preferred the plural form.


If you are more interested in the technical aspect, that depends (heavily) on
your document. I assume, you write more technical documents, right? In that
case, you can automate (some) things to make the indexing more easy.

For example, if you write about HTML5 you will probably use <tag> or
<sgmltag>. If you use this tag consistently, you can add some of them
(semi-)automatically to your index page through profiling. I've described this
topic in my book:

http://doccookbook.sf.net/html/en/dbc.structure.adding-indexterms.html

With the help of profiling, this eases the pain of indexing and you can
concentrate on the more difficult parts that can't be automated.

Hope that helps and good luck with your index. :-)

--
Gruß/Regards
Thomas Schraitle

On 05/05/12 11:00, Thomas Schraitle wrote:
>> Any advice from those with lots of experience of using
>> db indexes please?
>
> Are you asking more about the indexing task itself or about the technical
> aspect?

The docbook aspects please Thomas

>
> Speaking about the indexing task itself, IHMO this is something that some
> books don't take it seriously enough. An index is a service to make the book
> more accessible to readers. I've seen lots of bad index which came just as an
> alibi, but with no value.
> So it isn't a surprise that a good index takes time and energy. When I've
> created the index of my book, it took lots of iterations and I guess it still
> isn't perfect. :)

I'm hoping I can learn about the task from this book (at least a little)



>
> If you are more interested in the technical aspect, that depends (heavily) on
> your document. I assume, you write more technical documents, right? In that
> case, you can automate (some) things to make the indexing more easy.

Yes, this is what I'm interested in. And yes, it is a tech document.

>
> For example, if you write about HTML5 you will probably use<tag> or
> <sgmltag>. If you use this tag consistently, you can add some of them
> (semi-)automatically to your index page through profiling. I've described this
> topic in my book:
>
> http://doccookbook.sf.net/html/en/dbc.structure.adding-indexterms.html

Thanks... I was thinking of a manual 'edit' (addition of indexterm)
but I'll have a look at this.

>
> With the help of profiling, this eases the pain of indexing and you can
> concentrate on the more difficult parts that can't be automated.
>
> Hope that helps and good luck with your index. :-)

Thanks Thomas




regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

I've indexed three 500-page books, but never in DocBook.
However, I'd like to reinforce Thomas Schraitle's point that it
is both important and nontrivial.

The first thing I'd recommend is to read up on indexing. The
Wikipedia page is a good starting point.

http://en.wikipedia.org/wiki/Index_%28publishing%29

In earlier eras I used the "Chicago Manual of Style" to learn
about good practices.

There are certain very specific fetishes I have about indexing
that I see violated quite often.

The index to the "Guide to LaTeX" by Helmut Kopka has an example
of a horrible flaw that severely compromises its usefulness:
if a major topic is continued over a page break, the major
topic is NOT repeated on the continuation column.

Think about how you use an index: you depend on the top words
of each column to be in alphabetical order. But on page
584 of Kopka's book, the entire column is a continuation of
major topic "package", but the first entry is "amsmath".
So you think you're in the "a" section of the index, but you're
actually in the "p" section!

It should look like this, but in many books I don't see a
line like the first one:

package (continued)
amsmath, 191, 269-270
amsopn, ...

An obvious application for marks.

My next suggestion may slightly increase the page count, so I
never mentioned it back in the day when dead trees were the
only route to publication. However, the increase is small,
and inexcusable if you expect most people will e-read your
book.

As an example, the discussion of the amsmath package should
have two entries:

amsmath package, 372
packages, 366
amsmath, 372

In general, if an indexable phrase has more than one important
word, it should appear in the index under each of those words.

I can't give you any useful suggestions on current tools. Back
in the day I just invented a file format for entering all the
indexable references and then wrote my own software in C to
generate the index in TeX. This approach assumes that the
page numbers are all cast in stone, which was fine because
in my cases the rest of the book had all been put to bed.

Best regards,
John Shipman (john@nmt.edu), Applications Specialist, NM Tech Computer Center,
Speare 146, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john
``Let's go outside and commiserate with nature.'' --Dave Farber

On 06/05/12 22:45, John W. Shipman wrote:
>
> There are certain very specific fetishes I have about indexing
> that I see violated quite often.

!Not sure you should be talking about your fetishes in public John!!


>
> The index to the "Guide to LaTeX" by Helmut Kopka has an example
> of a horrible flaw that severely compromises its usefulness:
> if a major topic is continued over a page break, the major
> topic is NOT repeated on the continuation column.

?? Continuation column?

topic page 4 - 5
Is the '5' the continuation column?

>
> Think about how you use an index: you depend on the top words
> of each column to be in alphabetical order. But on page
> 584 of Kopka's book, the entire column is a continuation of
> major topic "package", but the first entry is "amsmath".
> So you think you're in the "a" section of the index, but you're
> actually in the "p" section!

I think I interpret your 'continuation column' as meaning
the part of the back of the book index which happens to have
a page break in the middle of a main entry? Is that right?

>
> It should look like this, but in many books I don't see a
> line like the first one:
>
> package (continued)
> amsmath, 191, 269-270
> amsopn, ...


a) I don't think (someone correct me if I'm wrong) that we'd
see the first line in a db output? Happens with table headers
but indexes? I.e. we'd only see
amsmath, 191, 269-270
amsopn, ...
Where the reader has to infer the sub-topic from the indent?

>
> An obvious application for marks.

Yes.

>
> My next suggestion may slightly increase the page count, so I
> never mentioned it back in the day when dead trees were the
> only route to publication. However, the increase is small,
> and inexcusable if you expect most people will e-read your
> book.
>
> As an example, the discussion of the amsmath package should
> have two entries:
>
> amsmath package, 372
> packages, 366
> amsmath, 372
>
> In general, if an indexable phrase has more than one important
> word, it should appear in the index under each of those words.

+1 with your example. Covered in the book I'm reading, though
the author cations on making it an iron rule. Again the reader
comes first.


>
> I can't give you any useful suggestions on current tools. Back
> in the day I just invented a file format for entering all the
> indexable references and then wrote my own software in C to
> generate the index in TeX. This approach assumes that the
> page numbers are all cast in stone, which was fine because
> in my cases the rest of the book had all been put to bed.

Which is the case the author talks about (quite endlessly in fact)
but not so in my case. I'm thinking I may be able to have a two
swipe go at it, but that's for the future.

Thanks John.




regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Hi Dave

Mulvany's text is an excellent indexing manual.
The Chicago Manual of Style (http://www.chicagomanualofstyle.org/home.html)
has a concise chapter on indexing. A free trail is available, and this
manual is usually available at a library in the reference section.

I have indexed books using docbook and TEI.
And my preference is docbook.

I did made a note to for myself some time back that an <indexterm> inside a
footnote caused an error. I was using oXygenXML v12 at the time. Not sure
if this is still the case.

I did have a problem with the placement of the <indexterm> but that was
answered at:
http://www.docbook.org/tdg51/en/html/indexterm.singular.html
Whitespace around <indexterm> may affect placement of the IDs in PDFs
generated.

Here are two examples of the <indexterm> that have worked for me.



SHAKESPEARE<indexterm><primary>Shakespeare</primary></indexterm>



<indexterm class="startofrange" xml:id="aaa1">
<primary sortas=" Shakespeare ">The Shakespeare</primary>
</indexterm>
. . . .
. . . .
<indexterm class="endofrange" startref="aaa1" />

Overall I have been pretty satisfied indexing with docbook.

And Dave, I know you are familiar with Bob Sagehill's book which has the
following:
http://www.sagehill.net/docbookxsl/GenerateIndex.html

Indexing an e-text it is very easy to over index. Generally an indexer is
allotted a limited number of pages for an index, but in an e-text what's a
few more bits. A bigger index does not mean a better index.

Happy Indexing

On Sat, May 5, 2012 at 4:40 AM, davep <davep@dpawson.co.uk> wrote:

> I'm about to start indexing a db5 book.
> Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
> been there and done that, got the tee-shirt and found the pitfalls in
> docbook? Any advice from those with lots of experience of using
> db indexes please?
>
>
>
> regards
>
> --
> Dave Pawson
> XSLT XSL-FO FAQ.
> http://www.dpawson.co.uk
>
> ------------------------------**------------------------------**---------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@**lists.oasis-open.org<docbook-apps-unsubscribe@lists.oasis-open.org>
> For additional commands, e-mail: docbook-apps-help@lists.oasis-**open.org<docbook-apps-help@lists.oasis-open.org>
>
>

On 05/05/12 12:52, PC Thoms wrote:
> Hi Dave
>
> Mulvany's text is an excellent indexing manual.
> The Chicago Manual of Style (http://www.chicagomanualofstyle.org/home.html)
> has a concise chapter on indexing. A free trail is available, and this
> manual is usually available at a library in the reference section.

I have the 14th edition. Ch 17 is apposite.

>
> I have indexed books using docbook and TEI.
> And my preference is docbook.

<grin/> Me too.

>
> I did made a note to for myself some time back that an<indexterm> inside a
> footnote caused an error. I was using oXygenXML v12 at the time. Not sure
> if this is still the case.

"Footnotes aren't normally indexed" is one piece of advice. So perhaps
docbook is right.


>
> I did have a problem with the placement of the<indexterm> but that was
> answered at:
> http://www.docbook.org/tdg51/en/html/indexterm.singular.html
> Whitespace around<indexterm> may affect placement of the IDs in PDFs
> generated.

This is the sort of issue to which I referred (nothing like experience?)


>
> Here are two examples of the<indexterm> that have worked for me.
>
>
>
> SHAKESPEARE<indexterm><primary>Shakespeare</primary></indexterm>
>
>
>
> <indexterm class="startofrange" xml:id="aaa1">
> <primary sortas=" Shakespeare ">The Shakespeare</primary>
> </indexterm>
> . . . .
> . . . .
> <indexterm class="endofrange" startref="aaa1" />


I knew it existed, though I haven't used it.

>
> Overall I have been pretty satisfied indexing with docbook.
>
> And Dave, I know you are familiar with Bob Sagehill's book which has the
> following:
> http://www.sagehill.net/docbookxsl/GenerateIndex.html
>
> Indexing an e-text it is very easy to over index. Generally an indexer is
> allotted a limited number of pages for an index, but in an e-text what's a
> few more bits. A bigger index does not mean a better index.

Common sense and balance? Paper (modulo 32 is not an issue in my case).


>
> Happy Indexing

I'll report back!

Thanks.




regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Hi Dave

Here is another example with quotations. This from a legacy project, which
is most of my work.

<indexterm>
<primary sortas="banks">“Banks,” The</primary>
</indexterm>

On Sat, May 5, 2012 at 1:05 PM, davep <davep@dpawson.co.uk> wrote:

> On 05/05/12 12:52, PC Thoms wrote:
>
>> Hi Dave
>>
>> Mulvany's text is an excellent indexing manual.
>> The Chicago Manual of Style (http://www.**chicagomanualofstyle.org/home.*
>> *html <http://www.chicagomanualofstyle.org/home.html>)
>> has a concise chapter on indexing. A free trail is available, and this
>> manual is usually available at a library in the reference section.
>>
>
> I have the 14th edition. Ch 17 is apposite.
>
>
>
>> I have indexed books using docbook and TEI.
>> And my preference is docbook.
>>
>
> <grin/> Me too.
>
>
>
>> I did made a note to for myself some time back that an<indexterm> inside
>> a
>> footnote caused an error. I was using oXygenXML v12 at the time. Not sure
>> if this is still the case.
>>
>
> "Footnotes aren't normally indexed" is one piece of advice. So perhaps
> docbook is right.
>
>
>
>
>> I did have a problem with the placement of the<indexterm> but that was
>> answered at:
>> http://www.docbook.org/tdg51/**en/html/indexterm.singular.**html<http://www.docbook.org/tdg51/en/html/indexterm.singular.html>
>> Whitespace around<indexterm> may affect placement of the IDs in PDFs
>> generated.
>>
>
> This is the sort of issue to which I referred (nothing like experience?)
>
>
>
>
>> Here are two examples of the<indexterm> that have worked for me.
>>
>>
>>
>> SHAKESPEARE<indexterm><**primary>Shakespeare</primary><**/indexterm>
>>
>>
>>
>> <indexterm class="startofrange" xml:id="aaa1">
>> <primary sortas=" Shakespeare ">The Shakespeare</primary>
>> </indexterm>
>> . . . .
>> . . . .
>> <indexterm class="endofrange" startref="aaa1" />
>>
>
>
> I knew it existed, though I haven't used it.
>
>
>
>> Overall I have been pretty satisfied indexing with docbook.
>>
>> And Dave, I know you are familiar with Bob Sagehill's book which has the
>> following:
>> http://www.sagehill.net/**docbookxsl/GenerateIndex.html<http://www.sagehill.net/docbookxsl/GenerateIndex.html>
>>
>> Indexing an e-text it is very easy to over index. Generally an indexer is
>> allotted a limited number of pages for an index, but in an e-text what's a
>> few more bits. A bigger index does not mean a better index.
>>
>
> Common sense and balance? Paper (modulo 32 is not an issue in my case).
>
>
>
>> Happy Indexing
>>
>
> I'll report back!
>
> Thanks.
>
>
>
>
>
> regards
>
> --
> Dave Pawson
> XSLT XSL-FO FAQ.
> http://www.dpawson.co.uk
>
> ------------------------------**------------------------------**---------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@**lists.oasis-open.org<docbook-apps-unsubscribe@lists.oasis-open.org>
> For additional commands, e-mail: docbook-apps-help@lists.oasis-**open.org<docbook-apps-help@lists.oasis-open.org>
>
>

Dave,

Regarding the markup mechanics, here are two possibly unexpected things to look out for:

1) When you are doing a range, the closing index term in the range cannot follow a section close. I.e., If you have the following

<para> some text.</para>





Generally this is not a problem, since you can move the index term up in a case like this without changing its position in the resulting text. It happens because the grammar doesn't allow much after a section closes except another section and a couple of other elements.

2) If you have space (including newlines) between index terms, you will get extra space in the output. E.g.,

In Shakespeare's Hamlet,<indexterm><primary>Shakespeare</primary></indexterm>
<indexterm><primary>Hamlet</primary></indexterm>
<indexterm><primary>plays, Shakespeare</primary></indexterm>
everyone (nearly) dies in the end.

In PDF output, you will get "In Shakespeare's Hamlet,^^^^ everyone (nearly) dies in the end." The "^" characters are space characters that come through in the output. You can avoid this by not leaving any space/newlines between successive index terms. In the Definitive guide, you will find things like the following, where an indexterm is opened on one line and then continued (space inside are ok):

In Shakespeare's Hamlet,<indexterm><primary>Shakespeare</primary></indexterm><indexterm>
<primary>Hamlet</primary></indexterm><indexterm>
<primary>plays, Shakespeare</primary>
</indexterm> everyone (nearly) dies in the end.

I think this happens because the parser sees the white space between the index terms (and in front or after) as distinct instances of white space that need to be preserved.

Neither is hard to avoid, but they can be frustrating (esp. the second one) if you're not expecting them.

Dick Hamilton
-------
XML Press
XML for Technical Communicators
http://xmlpress.net
hamilton@xmlpress.net



On May 5, 2012, at 12:10 AM, davep wrote:

> I'm about to start indexing a db5 book.
> Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
> been there and done that, got the tee-shirt and found the pitfalls in docbook? Any advice from those with lots of experience of using
> db indexes please?
>
>
>
> regards
>
> --
> Dave Pawson
> XSLT XSL-FO FAQ.
> http://www.dpawson.co.uk
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>

On 05/05/12 18:57, Richard Hamilton wrote:
> Dave,
>
> Regarding the markup mechanics, here are two possibly unexpected things to look out for:
>
> 1) When you are doing a range, the closing index term in the range cannot follow a section close. I.e., If you have the following
>
> <para> some text.</para>
>
>
>
>
>
> Generally this is not a problem, since you can move the index term up in a case
>like this without changing its position in the resulting text.
^^^^^^^^^^^^^^^^^^
>It happens because the grammar doesn't allow much after a section closes except
>another section and a couple of other elements.

I guess this is the key bit. 'Guess' where the page number will be and
align the element in a valid position.
Being a singleton it can 'cross' section boundaries though...




>
> 2) If you have space (including newlines) between index terms, you will get extra space
> in the output. E.g.,
>
> In Shakespeare's Hamlet,<indexterm><primary>Shakespeare</primary></indexterm>
> <indexterm><primary>Hamlet</primary></indexterm>
> <indexterm><primary>plays, Shakespeare</primary></indexterm>
> everyone (nearly) dies in the end.
>
> In PDF output, you will get "In Shakespeare's Hamlet,^^^^ everyone (nearly) dies in the end."
> The "^" characters are space characters that come through in the output.
> You can avoid this by not leaving any space/newlines between
successive index terms.
> In the Definitive guide, you will find things like the following,
where an indexterm is
> opened on one line and then continued (space inside are ok):
>
> In Shakespeare's Hamlet,<indexterm><primary>Shakespeare</primary></indexterm><indexterm>
> <primary>Hamlet</primary></indexterm><indexterm>
> <primary>plays, Shakespeare</primary>
> </indexterm> everyone (nearly) dies in the end.
>
> I think this happens because the parser sees the white space between the index terms
> (and in front or after) as distinct instances of white space that need to be preserved.


Rather more subtle Richard, thanks. I can see the logic.
... Just to check, it is the space *inbetween* <indexterm/>'s that is
causing the problem? Despite the fact that it shows (visually) at the
end of the indexterm. Space between <indexterm>
<primary> is insignificant ws.




>
> Neither is hard to avoid, but they can be frustrating (esp. the second one)
> if you're not expecting them.

Certainly I wouldn't be expecting the second one.
Thanks Richard.



regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Hi Dave and Docbook-apps Company:

In working with a legacy text, 1875, and it's index I entered five
secondary entries, expecting an error, using the following:

<index>
<indexentry><primaryie>Admission to Seats in Synod</primaryie>
<secondaryie>Ven. Archdeacon McMurray</secondaryie>
<secondaryie>Rev. Dr. Sullivan</secondaryie>
<secondaryie>Rev. Dr. Stocking</secondaryie>
<secondaryie>Wm. J. Harris</secondaryie>
<secondaryie>W. B. Curran</secondaryie></indexentry>
</index>

And to my surprise and delight this validated and produced the desired
entry.
All I have to say is that the xslt stylesheets for DocBook are awesome!
If this should not work - don't change anything.

Grateful - Paul


On Sat, May 5, 2012 at 4:40 AM, davep <davep@dpawson.co.uk> wrote:

> I'm about to start indexing a db5 book.
> Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
> been there and done that, got the tee-shirt and found the pitfalls in
> docbook? Any advice from those with lots of experience of using
> db indexes please?
>
>
>
> regards
>
> --
> Dave Pawson
> XSLT XSL-FO FAQ.
> http://www.dpawson.co.uk
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>

Should have waited to observe what else might happen.

It appears that the way I entered as in the previous e-mail is the expected
manner in which to code secondary enteries in a static index. Repeating the
primary entry generates the following:

Algoma

Appeal for Diocese of

Algoma

Contributions to Diocese of

Algoma

Report of Committee on duty of Synod

This is easily corrected, by using the method discovered in the first
e-mail I sent.
Cheers - Paul

On Tue, Jun 21, 2016 at 7:36 PM, Pc Thoms <pcthoms@gmail.com> wrote:

> Hi Dave and Docbook-apps Company:
>
> In working with a legacy text, 1875, and it's index I entered five
> secondary entries, expecting an error, using the following:
>
> <index>
> <indexentry><primaryie>Admission to Seats in Synod</primaryie>
> <secondaryie>Ven. Archdeacon McMurray</secondaryie>
> <secondaryie>Rev. Dr. Sullivan</secondaryie>
> <secondaryie>Rev. Dr. Stocking</secondaryie>
> <secondaryie>Wm. J. Harris</secondaryie>
> <secondaryie>W. B. Curran</secondaryie></indexentry>
> </index>
>
> And to my surprise and delight this validated and produced the desired
> entry.
> All I have to say is that the xslt stylesheets for DocBook are awesome!
> If this should not work - don't change anything.
>
> Grateful - Paul
>
>
> On Sat, May 5, 2012 at 4:40 AM, davep <davep@dpawson.co.uk> wrote:
>
>> I'm about to start indexing a db5 book.
>> Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
>> been there and done that, got the tee-shirt and found the pitfalls in
>> docbook? Any advice from those with lots of experience of using
>> db indexes please?
>>
>>
>>
>> regards
>>
>> --
>> Dave Pawson
>> XSLT XSL-FO FAQ.
>> http://www.dpawson.co.uk
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>>
>>
>

I agree, the more I've used it the more I'm impressed with the coding,
for which many thanks to the docbook team.

regards

On 21 June 2016 at 23:06, Pc Thoms <pcthoms@gmail.com> wrote:
> Hi Dave and Docbook-apps Company:
>
> In working with a legacy text, 1875, and it's index I entered five secondary
> entries, expecting an error, using the following:
>
> <index>
> <indexentry><primaryie>Admission to Seats in Synod</primaryie>
> <secondaryie>Ven. Archdeacon McMurray</secondaryie>
> <secondaryie>Rev. Dr. Sullivan</secondaryie>
> <secondaryie>Rev. Dr. Stocking</secondaryie>
> <secondaryie>Wm. J. Harris</secondaryie>
> <secondaryie>W. B. Curran</secondaryie></indexentry>
> </index>
>
> And to my surprise and delight this validated and produced the desired
> entry.
> All I have to say is that the xslt stylesheets for DocBook are awesome!
> If this should not work - don't change anything.
>
> Grateful - Paul
>
>
> On Sat, May 5, 2012 at 4:40 AM, davep <davep@dpawson.co.uk> wrote:
>>
>> I'm about to start indexing a db5 book.
>> Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
>> been there and done that, got the tee-shirt and found the pitfalls in
>> docbook? Any advice from those with lots of experience of using
>> db indexes please?
>>
>>
>>
>> regards
>>
>> --
>> Dave Pawson
>> XSLT XSL-FO FAQ.
>> http://www.dpawson.co.uk
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>>
>

Hi,

some technical/formatting things we ran into while using indexes:

1. Indexterms within listitems add a line break in the generated HTML (if
they come first). Review the entire documentation, and either reposition
them to come after a para (workaround), or use zones:

<listitem>
<indexterm zone="para1">
<primary>term1</primary>
<secondary>term2</secondary>
</indexterm>
<para xml:id="para1">loremipsum</para>
</listitem>

(Zones documented at: http://docbook.org/tdg/en/html/indexterm.html)

2. When adding indexterms directly after a

or similar tag, we
got validation errors, so now we place them after the title tag. However,
this causes the browsers scroll through the title, which is a bit
confusing, because the title of the section/procedure/whatever is not
always visible

HTH,

Robert



On Wed, Jun 22, 2016 at 8:27 AM, Dave Pawson <davep@dpawson.co.uk> wrote:

> I agree, the more I've used it the more I'm impressed with the coding,
> for which many thanks to the docbook team.
>
> regards
>
> On 21 June 2016 at 23:06, Pc Thoms <pcthoms@gmail.com> wrote:
> > Hi Dave and Docbook-apps Company:
> >
> > In working with a legacy text, 1875, and it's index I entered five
> secondary
> > entries, expecting an error, using the following:
> >
> > <index>
> > <indexentry><primaryie>Admission to Seats in Synod</primaryie>
> > <secondaryie>Ven. Archdeacon McMurray</secondaryie>
> > <secondaryie>Rev. Dr. Sullivan</secondaryie>
> > <secondaryie>Rev. Dr. Stocking</secondaryie>
> > <secondaryie>Wm. J. Harris</secondaryie>
> > <secondaryie>W. B. Curran</secondaryie></indexentry>
> > </index>
> >
> > And to my surprise and delight this validated and produced the desired
> > entry.
> > All I have to say is that the xslt stylesheets for DocBook are awesome!
> > If this should not work - don't change anything.
> >
> > Grateful - Paul
> >
> >
> > On Sat, May 5, 2012 at 4:40 AM, davep <davep@dpawson.co.uk> wrote:
> >>
> >> I'm about to start indexing a db5 book.
> >> Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has
> >> been there and done that, got the tee-shirt and found the pitfalls in
> >> docbook? Any advice from those with lots of experience of using
> >> db indexes please?
> >>
> >>
> >>
> >> regards
> >>
> >> --
> >> Dave Pawson
> >> XSLT XSL-FO FAQ.
> >> http://www.dpawson.co.uk
> >>
> >> ---------------------------------------------------------------------
> >> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> >> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
> >>
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>
>