Re: [docbook-apps] Indexing.

[Fekete , Róbert]

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:



term1
term2

loremipsum


(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  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  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
> > Admission to Seats in Synod
> > Ven. Archdeacon McMurray
> > Rev. Dr. Sullivan
> > Rev. Dr. Stocking
> > Wm. J. Harris
> > W. B. Curran
> > 
> >
> > 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  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-unsubscr...@lists.oasis-open.org
> >> For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
> >>
> >
>
> -
> To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
>
>

Re: [docbook-apps] Indexing.

[Dave Pawson]

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  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
> Admission to Seats in Synod
> Ven. Archdeacon McMurray
> Rev. Dr. Sullivan
> Rev. Dr. Stocking
> Wm. J. Harris
> W. B. Curran
> 
>
> 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  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-unsubscr...@lists.oasis-open.org
>> For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
>>
>

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[Pc Thoms]

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  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
> Admission to Seats in Synod
> Ven. Archdeacon McMurray
> Rev. Dr. Sullivan
> Rev. Dr. Stocking
> Wm. J. Harris
> W. B. Curran
> 
>
> 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  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-unsubscr...@lists.oasis-open.org
>> For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
>>
>>
>

Re: [docbook-apps] Indexing.

[Pc Thoms]

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
Admission to Seats in Synod
Ven. Archdeacon McMurray
Rev. Dr. Sullivan
Rev. Dr. Stocking
Wm. J. Harris
W. B. Curran


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  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-unsubscr...@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
>
>

[docbook-apps] Indexing markup... emacs

[DaveP]

Reading a very good emacs blog
I found the guy has a book, $5 US
http://ergoemacs.org/emacs/buy_xah_emacs_tutorial.html

The blog is good, I'm finding the tutorial really handy

Quick lesson in macros. Docbook indexing.

Highlight the term, M-x pi
with or without s (for secondary term)

Enjoy.


(defun pi (class start end)
  Markup for docbook index, optional secondary term
  (interactive sEnter s for secondary : \nr)
  (let* (
 (idxterm  (buffer-substring start end))  ; the indexed term
 (termlen (length idxterm))  ; len of above
 (pms (concat indextermprimary idxterm /primary))
 (sms secondary)
 (sme /secondary)
 (pme /indexterm)
 (pml (length pms)) ;; primary length
 (sml (length sms))  ;; secondary length
 ) ;; end of local vars
  (goto-char (- end termlen ))(insert pme )
(goto-char start)(insert pms)
(when (equal s class) ;; if secondary wanted
   (insert (concat sms sme )))
(setq newpoint
  (if (equal s class)
  (+ (length pms) (length sms)) ;; insert point for secondary
(+ (length pms) (length pme))
))
(goto-char (+ (region-beginning) newpoint))
))

regards

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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing software and DocBook

[Xmplar]

Richard,
I have an indexer working on an ebook now. He's using embedded indexing 
(as per Bob's book) with oXygen, but apparently prefers to use SkyIndex 
for the indexing, then transfer the entries into XML chunks.

I'll let you know in a few weeks exactly how he handled the job.
Dave

On 10-08-12 5:11 AM, Richard Hamilton wrote:

Has anyone worked with indexing software (like Cindex) and DocBook? It looks 
like Cindex will operate on XML instances and even export XML, but I don't know 
how practical it might be to use it for an indexing project in DocBook.

If anyone has experience doing that and could spend a few minutes off-line 
talking/emailing about it, please let me know.

Thanks,
Dick Hamilton
---
XML Press
New from XML Press:
The Content Pool
http://xmlpress.net/publications/the-content-pool


-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org





-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing software and DocBook

[Richard Hamilton]

Dave,

Thanks very much. It will be interesting to see how SkyIndex works.

After doing some investigation on Cindex, it's clear that it's a pretty cool 
program, but it doesn't seem to be set up to work with markup that embeds 
codes, so there are extra steps involved in making it work with DocBook 
(Caveat: I did not do an extensive investigation, but I did get the demo 
version of the software and exchanged email with two people who have used the 
product.

Thanks,
Richard
---
XML Press
XML for Technical Communicators
http://xmlpress.net
hamil...@xmlpress.net



On Aug 12, 2012, at 4:01 PM, Xmplar wrote:

 Richard,
 I have an indexer working on an ebook now. He's using embedded indexing (as 
 per Bob's book) with oXygen, but apparently prefers to use SkyIndex for the 
 indexing, then transfer the entries into XML chunks.
 I'll let you know in a few weeks exactly how he handled the job.
 Dave
 
 On 10-08-12 5:11 AM, Richard Hamilton wrote:
 Has anyone worked with indexing software (like Cindex) and DocBook? It looks 
 like Cindex will operate on XML instances and even export XML, but I don't 
 know how practical it might be to use it for an indexing project in DocBook.
 
 If anyone has experience doing that and could spend a few minutes off-line 
 talking/emailing about it, please let me know.
 
 Thanks,
 Dick Hamilton
 ---
 XML Press
 New from XML Press:
 The Content Pool
 http://xmlpress.net/publications/the-content-pool
 
 
 -
 To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
 For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
 
 
 
 
 -
 To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
 For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
 


-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

[docbook-apps] Indexing software and DocBook

[Richard Hamilton]

Has anyone worked with indexing software (like Cindex) and DocBook? It looks 
like Cindex will operate on XML instances and even export XML, but I don't know 
how practical it might be to use it for an indexing project in DocBook.

If anyone has experience doing that and could spend a few minutes off-line 
talking/emailing about it, please let me know.

Thanks,
Dick Hamilton
---
XML Press
New from XML Press:
The Content Pool
http://xmlpress.net/publications/the-content-pool


-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[Bob Stayton]

Regarding the (continued) label for long index entries that break across a column, 
I've implemented that feature for a client in XEP using its extension property 
rx:table-omit-initial-header, in a manner similar to that feature for repeating table 
titles across page breaks.  In this case, each primary indexterm is placed in a 
one-column table.  I think the XSL 1.1 retrieve-table-marker feature could probably do 
the same thing without resorting to an extension, but I've not tried it.


Bob Stayton
Sagehill Enterprises
b...@sagehill.net


- Original Message - 
From: davep da...@dpawson.co.uk

To: docbook-apps@lists.oasis-open.org
Sent: Monday, May 07, 2012 12:10 AM
Subject: Re: [docbook-apps] Indexing.



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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org






-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[davep]

On 11/05/12 21:27, Bob Stayton wrote:

Regarding the (continued) label for long index entries that break across
a column, I've implemented that feature for a client in XEP using its
extension property rx:table-omit-initial-header, in a manner similar to
that feature for repeating table titles across page breaks. In this
case, each primary indexterm is placed in a one-column table. I think
the XSL 1.1 retrieve-table-marker feature could probably do the same
thing without resorting to an extension, but I've not tried it.

Bob Stayton
Sagehill Enterprises
b...@sagehill.net


If this is implemented in axf, do you think it is a worthwhile addition Bob?

http://www.antennahouse.com/xslfo/fo.htm
6.13.7 fo:retrieve-table-marker Extendedyes 

So it seems it is?

regards







- Original Message - From: davep da...@dpawson.co.uk
To: docbook-apps@lists.oasis-open.org
Sent: Monday, May 07, 2012 12:10 AM
Subject: Re: [docbook-apps] Indexing.



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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org






-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org






regards

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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[davep]

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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[davep]

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
  !-- indexterm ok --
 /section
  !-- indexterm not ok --
/section

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,indextermprimaryShakespeare/primary/indexterm
indextermprimaryHamlet/primary/indexterm
indextermprimaryplays, 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,indextermprimaryShakespeare/primary/indextermindexterm
primaryHamlet/primary/indextermindexterm
primaryplays, 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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[John W. Shipman]

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 (j...@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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

[docbook-apps] Indexing.

[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? 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-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[Thomas Schraitle]

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


-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[PC Thoms]

 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.

!-- SIMPLE INDEX ENTRY EXAMPLE  --

SHAKESPEAREindextermprimaryShakespeare/primary/indexterm

!-- STARTOFRANGE TO ENDOFRANGE  --

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 da...@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.orgdocbook-apps-unsubscr...@lists.oasis-open.org
 For additional commands, e-mail: 
 docbook-apps-help@lists.oasis-**open.orgdocbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[davep]

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 usetag  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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[davep]

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 anindexterm  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 theindexterm  but that was
answered at:
http://www.docbook.org/tdg51/en/html/indexterm.singular.html
Whitespace aroundindexterm  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 theindexterm  that have worked for me.

!-- SIMPLE INDEX ENTRY EXAMPLE  --

SHAKESPEAREindextermprimaryShakespeare/primary/indexterm

!-- STARTOFRANGE TO ENDOFRANGE  --

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

-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[PC Thoms]

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 da...@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 anindexterm  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 theindexterm  but that was
 answered at:
 http://www.docbook.org/tdg51/**en/html/indexterm.singular.**htmlhttp://www.docbook.org/tdg51/en/html/indexterm.singular.html
 Whitespace aroundindexterm  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 theindexterm  that have worked for me.

 !-- SIMPLE INDEX ENTRY EXAMPLE  --

 SHAKESPEAREindexterm**primaryShakespeare/primary**/indexterm

 !-- STARTOFRANGE TO ENDOFRANGE  --

 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.htmlhttp://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.orgdocbook-apps-unsubscr...@lists.oasis-open.org
 For additional commands, e-mail: 
 docbook-apps-help@lists.oasis-**open.orgdocbook-apps-h...@lists.oasis-open.org

Re: [docbook-apps] Indexing.

[Richard Hamilton]

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
 !-- indexterm ok --
/section
 !-- indexterm not ok --
/section

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,indextermprimaryShakespeare/primary/indexterm
indextermprimaryHamlet/primary/indexterm
indextermprimaryplays, 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,indextermprimaryShakespeare/primary/indextermindexterm
primaryHamlet/primary/indextermindexterm
primaryplays, 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
hamil...@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-unsubscr...@lists.oasis-open.org
 For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
 


-
To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org
For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org

Re: DOCBOOK-APPS: Indexing and XSL stylesheets

[Bob Stayton]

On Fri, Jan 03, 2003 at 10:30:47AM +0100, Sebastian Bergmann wrote:

   Where can I read on indexing and rendering thereof with the XSL
   stylesheets?

I'm writing some doc now, but it isn't ready yet.
The basic idea is to insert indexterm elements
in your doc to mark index points, and then add an
empty index/ element at the end of your book.
The stylesheets will then automagically generate the
index at that location.  Works for HTML and FO.

The current release (1.58.1) does not fold upper and lower
case words together during sorting, but the next release
will fix that.

You can learn about how to write indexterms in DocBook The
Definitive Guide:

http://docbook.org/tdg/en/html/indexterm.html

-- 

Bob Stayton 400 Encinal Street
Publications Architect  Santa Cruz, CA  95060
Technical Publications  voice: (831) 427-7796
The SCO Group   fax:   (831) 429-1887
email: [EMAIL PROTECTED]

DOCBOOK-APPS: indexing an entire set

[Claus Rasmussen]

Hi all,

I've successfully made indexes for my books. Now I want to combine some books 
in a set - is there no way of making an index for the entire set? The spec 
says that index can't be a child of set.

I know there is setindex, but that doesn't let me benefit from the 
automated indexing provided by Norm's XSL style sheets?

I'm using xml-books (4.1.2) with Saxon and Norms style sheets.

/claus



To subscribe or unsubscribe from this elist use the subscription
manager: http://lists.oasis-open.org/ob/adm.pl

Re: DOCBOOK-APPS: indexing an entire set

[Bob McIlvride]

Hi Claus,

We faced the challenge of indexing a set of books last year,
particularly how to incorporate some kind of functionality with the
local, global, and all scope attributes on indexterms.  

We modified Norm's collateindex.pl to do this, and posted a diff file to
this newsgroup at that time (before the days of sourceforge), but I
don't think our customizations were incorporated into collateindex.pl. 
At any rate, we also wrote a perl script that used our modified
collateindex.pl to let us generate a number of different kinds of
indices for books and sets.  We also had to modify our DSSSL stylesheet
to produce the correct output.  I know you are working with the XML
stylesheets, but you can view these at the links below, and are welcome
to take what you need and use it as you see fit.

http://24.112.178.91/cogent/prepdoc/pd-collateindexpl.html
http://24.112.178.91/cogent/prepdoc/pd-collateall.html
http://24.112.178.91/cogent/prepdoc/pd-customizingthedssslstylesheets.html#PD-COGENTBOTHDSLFILE
 
(towards the bottom)

Claus Rasmussen wrote:

 I've successfully made indexes for my books. Now I want to combine some books
 in a set - is there no way of making an index for the entire set? 

Cheerio!

Bob

---
Robert McIlvride ([EMAIL PROTECTED])
Cogent Real-Time Systems (www.cogent.ca)


To subscribe or unsubscribe from this elist use the subscription
manager: http://lists.oasis-open.org/ob/adm.pl

Re: DOCBOOK-APPS: indexing for print with DSSSL / OpenJade / JadeTex

[Deborah Greenberg Lidl]

On Fri, Apr 13, 2001 at 03:24:02PM -0600, Deborah Greenberg Lidl said:
 DocBook SGML 4.1 / DSSSL 1.62 / OpenJade 1.3 / JadeTex 3.33
 
 I'm trying to get my head around creating indexing a book.  I've
 managed to get things mostly working for the HTML version, both chunked
 and non-chunked.  And, I've got it partially working for a PostScript
 version (via TeX and dvips).
 
[snip]
 
 Marking things up as a range using the class attribute (indexterm
 id=foo class=startofrange.../indexterm...indexterm startref=foo
 class=endofrange) sort of works.  The page number in the index shows
 the page number where the startofrange is; for example, 16.  It doesn't
 show a range; for example, 16-30.  The collateindex.pl script reports
 that it is ignoring one index entry -- I suspect it's the endofrange
 one.

I think the issue is with collateindex.pl.  HTML.index seems to contain
the correct info.  I understand that ranges that span pages are a
difficult issue, so I have not looked any further into this.

 Marking things using the zone attribute (indexterm
 zone=bar.../indexterm...emphasis id=bar.../emphasis) doesn't
 work.  The page number in the index shows as ?.  

Again, I think the issues with collateindex.pl, as HTML.index contains
what appears to be a sufficient amount of info.  

If you don't use the -p option, the generated ulink contains the title
of the nearest section as the role.  Even if there is an ID for the
title of the section, the section, the indexterm, and just about
everything else you can think of.  The title is usually more than one
word, so the stylesheets don't know what to do with it. 

If you use the -p option, the generated ulink still contains the title
of the nearest section as the role.  And, the url is just a reference
to the title, not to a specific target.

Again, I do have simple samples that show these issues.

If anyone can confirm this, I'd be much obliged.  I expect these are
either requests for enhancements or bugs, depending on how the
question was phrased.

Many thanks,
Debbie
-- 
Deborah Greenberg Lidl   Toll free: 1.888.849.BSDi
[EMAIL PROTECTED]BSDi Phone: 1.301.765.7945
http://www.bsdi.comFax: 1.301.765.7946

--
To unsubscribe from this elist send a message with the single word
unsubscribe in the body to: [EMAIL PROTECTED]

Re: DOCBOOK-APPS: indexing for print with DSSSL / OpenJade / JadeTex

[Sebastian Rahtz]

Deborah Greenberg Lidl writes:
  - What do I need to do to make entries that reference zones show a
page number in the printed index?

tell me precisely what it has in the .tex file at the point where the
page number should be printed

sebastian


--
To unsubscribe from this elist send a message with the single word
unsubscribe in the body to: [EMAIL PROTECTED]

DOCBOOK-APPS: indexing for print with DSSSL / OpenJade / JadeTex

[Deborah Greenberg Lidl]

All --

DocBook SGML 4.1 / DSSSL 1.62 / OpenJade 1.3 / JadeTex 3.33

I'm trying to get my head around creating indexing a book.  I've
managed to get things mostly working for the HTML version, both chunked
and non-chunked.  And, I've got it partially working for a PostScript
version (via TeX and dvips).

My command sequence (edited for clarity of path names) is:
  perl collateindex.pl -N -o generated-index.sgml
  openjade -t sgml -V html-index -c catalog -d html/docbook.dsl test.sgml
  perl collateindex.pl -f -p -g -o generated-index.sgml
  openjade -t tex -V tex-backend -c catalog -d print/docbook.dsl test.sgml
  tex -fmt=jadetex -progname=jadetex test
  tex -fmt=jadetex -progname=jadetex test
  tex -fmt=jadetex -progname=jadetex test
  dvips test.ps test.dvi

Marking things up as a single point (indexterm.../indexterm)
works.  The page number displayed in the index reflects the page
number where the text is.  

Marking things up as a range using the class attribute (indexterm
id="foo" class="startofrange".../indexterm...indexterm startref="foo"
class="endofrange") sort of works.  The page number in the index shows
the page number where the startofrange is; for example, 16.  It doesn't
show a range; for example, 16-30.  The collateindex.pl script reports
that it is ignoring one index entry -- I suspect it's the endofrange
one.

Marking things using the zone attribute (indexterm
zone="bar".../indexterm...emphasis id="bar".../emphasis) doesn't
work.  The page number in the index shows as ?.  

A search of the archives reveals that someone else reported this in
February 2000.  But I didn't see any follow up, other than Norm asking
for a sample (non-PostScript) file.  Other reports of index issues seemed
to be explanations of the list of commands and options to use, and how
to mark up things.

I've verified this with the default DTD and stylesheets shipped with
the versions above, so I don't think the problem is with any of my
customizations to the DTD or stylesheets.  I have a Makefile and test
sgml file that I can send.  I have an HTML.index file that I can send.

My questions, then, are two:

- What do I need to do to make range entries show both the start and
  end of the range in the printed index? 
- What do I need to do to make entries that reference zones show a
  page number in the printed index?

If anyone else has run into these issues, I'd love to hear about it.
Suggestions greatly appreciated.

Many thanks,
Debbie
-- 
Deborah Greenberg Lidl   Toll free: 1.888.849.BSDi
[EMAIL PROTECTED]BSDi Phone: 1.301.765.7945
http://www.bsdi.comFax: 1.301.765.7946

--
To unsubscribe from this elist send a message with the single word
"unsubscribe" in the body to: [EMAIL PROTECTED]