Date: Sun, 12 Jan 2025 00:49:42 -0500 From: jpb <jpb@jimby.name> To: doc@freebsd.org Subject: [FDP] Generating an Index for PDF Documents Message-ID: <20250112004942.3ba69810.jpb@jimby.name>
next in thread | raw e-mail | index | archive | help
Here's a quick summary on how to generate an index for FreeBSD FDP books, articles, and multi-part documents. Happily, the indexing tooling is already built into Asciidoctor. 1. Decide where you want the index. In my case I added another "chapter" document directory - foo-index/_index.adoc. Edit the _index.adoc and change the title, and any next/prev. You will also need to change the weight. The weight value should be higher than the highest chapter in the book. This will place the index at the end of the document or book. 2. Add this section info to the bottom of the _index.adoc file after all the front matter and hugo stuff. This tells Asciidoctor where you want the index. This is all you need to add. [index] = Index 3. You'll now have to go through all the chapters and tag each line that has a term you want in the index. Add the following to the end of the line: indexterm:[foo] for term 'foo' or indexterm:[buzzword,foo] which will add an entry for foo under the 'buzzword' index. 4. Make the document as you usually do (make DOC_LANG=whatever). When the book is completed, open the PDF version and check out the index at the end (or wherever you put it). NOTES: You can tag any kind of text - regular text, text inside [NOTEs], [TIPs], etc. or text inside listings such as [.programlisting], [.source], [subs=+quotes] etc. I've found that tagging a singular stem version of a word relieves you from having to text all other variations. You don't have to tag every instance of a term. If there are several sentences together, each having the same term, or even nearby paragraphs all having the same term, just tag the term once. The index entry will be the same for all of them. Check these examples: https://www.jimby.name/fbsd/_index.adoc.txt https://www.jimby.name/fbsd/fdp_index_example.png Best Regards, Jim B. jpb@jimby.name
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20250112004942.3ba69810.jpb>