docbook: Thread: index generation

hello,

i'm the maintainer of the linux kernel module programming guide (lkmpg),
and noticed awhile back that no index is being generous, despite the
fact that the lkmpg is sprinkled liberally with <indexterm> tags.

can someone tell me what i need to do to generate an index of terms?

thanks!
pete

-- 
Fingerprint: B9F1 6CF3 47C4 7CD8 D33E 70A9 A3B9 1945 67EA 951D

hi greg et al,

ok, first an apology.  i didn't know about the mailing list search, but
i do now.   :) anyway, i'm getting an error.  here's a snippet of the
makefile:

   STYLE='/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/ldp.dsl'
   TARGET=lkmpg

   all:
      collateindex.pl -N -o index.sgml
      jade -t sgml -V html-index -d ${STYLE} ${TARGET}.sgml


at this point (the invocation of jade), i get an error:

   jade:index.sgml:1:6:E: document type does not allow element "INDEX" here
   jade:lkmpg.sgml:96:85:E: end tag for "APPENDIX" which is not finished

index.html contains (in its entirety):

   <index>
   
   <!-- This file was produced by collateindex.pl.         -->
   <!-- Remove this comment if you edit this file by hand! -->
   </index>


lkmpg.sgml (the relevent portion) contains:

  <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
    <!ENTITY TheIndex           SYSTEM  "index.sgml">
  ]>
  <book>

  blah blah blah 

  <appendix><title>Changes: 2.0 To 2.2  </title>&Changes20-22;</appendix>
  <appendix><title>Where To Go From Here</title>&WhereFromHere;</appendix>
  <appendix><title>Index                </title>&TheIndex;</appendix>
  </book>


i *suspect* the problem is related to the fact that this is a <book> and
not an <article>.   i've tried looking at the other guides, and AFAICS,
none of them have an index.

is there anything special that <book>'s need to do for index creation?

pete


begin Greg Ferguson ####@####.#### 
> On Tue, 1 Apr 2003 16:29:37 -0800 Peter Jay Salzman ####@####.#### wrote:
> 
> > hello,
> > 
> > i'm the maintainer of the linux kernel module programming guide (lkmpg),
> > and noticed awhile back that no index is being generous, despite the
> > fact that the lkmpg is sprinkled liberally with <indexterm> tags.
> > 
> > can someone tell me what i need to do to generate an index of terms?
> > 
> > thanks!
> > pete
> > 
> 
> (from earlier ####@####.#### post...)
> 
> To create indexes:
> 
> 1. Add <indexterm> references into your SGML file (I'm not going
>    into detail, that's covered in the LDP Author Guide)
> 
> 2. Add an entity reference in your main SGML file:
> 
>      <!DOCTYPE Article PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
>        <!ENTITY myindex SYSTEM "index.sgml">
>        ..
>      ]>
> 
> 3. Include/reference the entity at the end of the file/document (or
>    wherever you wish to have the index occur):
> 
>        &myindex;
> 
>      </article>
> 
> 3. Now run the the tools to generate the index:
> 
>       collateindex.pl -N -o index.sgml
>       jade -t sgml -V html-index -d <style> My-HOWTO.sgml
>       collateindex.pl -g -t Index -i doc-index -o index.sgml HTML.index
> 
> You will now have a index.sgml file which can be used in conjunction
> with the "normal" run of the tools (which you use to produce your
> HTML files, etc). This should work ok with XML files as well (adjust
> your file extensions in the examples shown above!).
> 
> For an example, see IBM7248-HOWTO - http://tldp.org/HOWTO/IBM7248-HOWTO/
> You can also get the source to examine from our CVS (web) tree.

-- 
Fingerprint: B9F1 6CF3 47C4 7CD8 D33E 70A9 A3B9 1945 67EA 951D

>    jade:index.sgml:1:6:E: document type does not allow element "INDEX" here
>    jade:lkmpg.sgml:96:85:E: end tag for "APPENDIX" which is not finished
...
>   <appendix><title>Index                </title>&TheIndex;</appendix>

An appendix must have content between the title and an index; I
would assume that the index for an appendix is supposed to handle
terms in the appendix only.

You don't need to wrap the index in an appendix.

--
John R. Daily
<email><mailbox>john</mailbox><domain>geekhavoc.com</domain></email>

begin Greg Ferguson ####@####.#### 
> On Wed, 2 Apr 2003 09:45:49 -0800 Peter Jay Salzman ####@####.#### wrote:
> 
> > hi greg et al,
> > 
> > ok, first an apology.  i didn't know about the mailing list search, but
> > i do now.   :) anyway, i'm getting an error.  here's a snippet of the
> > makefile:
> > 
> >    STYLE='/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/ldp.dsl'
> >    TARGET=lkmpg
> > 
> >    all:
> >       collateindex.pl -N -o index.sgml
> >       jade -t sgml -V html-index -d ${STYLE} ${TARGET}.sgml
> > 
> >
> > at this point (the invocation of jade), i get an error:
> > 
> >    jade:index.sgml:1:6:E: document type does not allow element "INDEX"
> > here
> >    jade:lkmpg.sgml:96:85:E: end tag for "APPENDIX" which is not finished
> > 
> > index.html contains (in its entirety):
> > 
> >    <index>
> >    
> >    <!-- This file was produced by collateindex.pl.         -->
> >    <!-- Remove this comment if you edit this file by hand! -->
> >    </index>
> > 
> > 
> > lkmpg.sgml (the relevent portion) contains:
> > 
> >   <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
> >     <!ENTITY TheIndex           SYSTEM  "index.sgml">
> >   ]>
> >   <book>
> > ...
> 
> 
> As someone else suggested, try it outside of a container element:
> 
>   ...
>   <appendix><title>Where To Go From Here</title>&WhereFromHere;</appendix>
>   &TheIndex;
>   </book>
> 
> Also, if referencing the LDP stylesheet (I assume it's the same as what
> is provided on our website), you need to use an identifier when utilizing
> it in a jade command line:
> 
>   STYLE='/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/ldp.dsl#html'
> 

hi john and greg,

thank you!  progress is being made!  lkmpg.html has an index :), but
lkmpg.ps doesn't :(.   makefile is at the bottom.

is there a way to generate an index for the postscript version of the
guide?

the whole build process is kind of a black box to me, but it seems like
ldp_print (or perhaps htmldoc?) may need to be hacked.   is that about
right?

if so, i'm willing to be happy with an index just in the html version.


btw, i really like the search utility for this list.  it's much better
than what my LUG uses (lugod.org).  but is there a way to do searches
with "and"?  something google-like:

   "+index +postscript"

pete 



  TARGET=lkmpg
  STYLE='/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/ldp.dsl'
  JADEOPTIONS=-t sgml -i html -V nochunks  -d $(STYLE)\#html
  
  new:
     # Generate the index
     collateindex.pl -N -o index.sgml
     jade -t sgml -V html-index -d ${STYLE}\#html ${TARGET}.sgml
     collateindex.pl -g -t Index -i doc-index -o index.sgml HTML.index
 
     jade ${JADEOPTIONS} ${TARGET}.sgml > ${TARGET}.html
     -ldp_print ${TARGET}.html
     make tidy

begin Greg Ferguson ####@####.#### 
> On Wed, 2 Apr 2003 12:43:35 -0800 Peter Jay Salzman ####@####.#### wrote:
> 
> >
> > lkmpg.html has an index, but lkmpg.ps doesn't.
> > 
> > is there a way to generate an index for the postscript version of the
> > guide?
> > 
> the whole "ldp_print" process uses the single-file (non-chunked) 
> HTML instance of the document and then produces PDF and PostScript
> from it (using htmldoc). So if the index is part of the non-chunked
> version, it'll be part of the PDF/PostScript version(s).
  
okay, i've been at this for day now.  sorry for being dense, but i can't
figure this out.


TARGET=lkmpg
STYLE='/usr/share/sgml/docbook/stylesheet/dsssl/modular/html/ldp.dsl'
JADEOPTIONS=-t sgml -i html -V nochunks  -d $(STYLE)\#html

1 new:
2    collateindex.pl -N -o index.sgml
3    jade -t sgml -V html-index -d ${STYLE}\#html ${TARGET}.sgml
4    collateindex.pl -g -t Index -i doc-index -o index.sgml HTML.index
5
6    jade ${JADEOPTIONS} ${TARGET}.sgml > ${TARGET}.html
7    -ldp_print ${TARGET}.html


it sounds like you're saying if line 6 produces a non-chunked HTML file
with an index, then line 7 produces a postscript version with an index.

however, line 6 produces a non-chunked html file with an index, yet the
postscript version still doesn't have an index.

docbook hates me.  any ideas what could be going wrong?

sorry.   :(

pete

-- 
Fingerprint: B9F1 6CF3 47C4 7CD8 D33E 70A9 A3B9 1945 67EA 951D