From nobody Sun Jan 12 05:49:42 2025 X-Original-To: doc@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4YW4Gk472Kz5kX8r for ; Sun, 12 Jan 2025 05:49:50 +0000 (UTC) (envelope-from jpb@jimby.name) Received: from jimby.jimby.name (jimby.jimby.name [104.225.1.79]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (2048 bits) client-digest SHA256) (Client CN "www.jimby.name", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4YW4Gj4V1Yz57s2 for ; Sun, 12 Jan 2025 05:49:49 +0000 (UTC) (envelope-from jpb@jimby.name) Authentication-Results: mx1.freebsd.org; dkim=pass header.d=jimby.name header.s=1908dkim header.b=pbvYUVp+; spf=pass (mx1.freebsd.org: domain of jpb@jimby.name designates 104.225.1.79 as permitted sender) smtp.mailfrom=jpb@jimby.name; dmarc=pass (policy=reject) header.from=jimby.name Received: from remote.jimby.name (unknown [IPv6:2600:1700:3901:4940:3e97:eff:fe10:92f2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange ECDHE (prime256v1) server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by jimby.jimby.name (Postfix) with ESMTPSA id 1AFD66B19E for ; Sun, 12 Jan 2025 00:49:43 -0500 (EST) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=jimby.name; s=1908dkim; t=1736660983; bh=j06E9YaFAC0k4glS4a9wv/k2eBmQYJnXHmm47lhCbnM=; h=Date:From:To:Subject; b=pbvYUVp+SUVPLy4j0W6k1Q83HZCqV5Bq1nkuqXSYQHxhDhCnYDHyWq5eArQiGGv68 g07BmUTFpxS0G+BLswOQxcYfAyMYo6ottkEz4iyQeJBnhl7KD4bPz9zNrD1WTKK5zi iLBNp7i+Wulb6iTORAkJ456azYIqIdZ0PB6awi4k= Date: Sun, 12 Jan 2025 00:49:42 -0500 From: jpb To: doc@freebsd.org Subject: [FDP] Generating an Index for PDF Documents Message-ID: <20250112004942.3ba69810.jpb@jimby.name> X-Mailer: Claws Mail 3.21.0 (GTK+ 2.24.33; amd64-portbld-freebsd14.1) List-Id: Documentation project List-Archive: https://lists.freebsd.org/archives/freebsd-doc List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-freebsd-doc@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit X-Rspamd-Queue-Id: 4YW4Gj4V1Yz57s2 X-Spamd-Bar: -- X-Spamd-Result: default: False [-2.86 / 15.00]; NEURAL_HAM_LONG(-1.00)[-1.000]; MID_CONTAINS_FROM(1.00)[]; NEURAL_HAM_MEDIUM(-1.00)[-1.000]; NEURAL_HAM_SHORT(-0.96)[-0.960]; DMARC_POLICY_ALLOW(-0.50)[jimby.name,reject]; R_DKIM_ALLOW(-0.20)[jimby.name:s=1908dkim]; R_SPF_ALLOW(-0.20)[+mx]; MIME_GOOD(-0.10)[text/plain]; ONCE_RECEIVED(0.10)[]; MIME_TRACE(0.00)[0:+]; ASN(0.00)[asn:36236, ipnet:104.225.1.0/24, country:US]; RCVD_VIA_SMTP_AUTH(0.00)[]; RCPT_COUNT_ONE(0.00)[1]; RCVD_COUNT_ONE(0.00)[1]; RCVD_TLS_ALL(0.00)[]; MLMMJ_DEST(0.00)[doc@freebsd.org]; FROM_EQ_ENVFROM(0.00)[]; FROM_HAS_DN(0.00)[]; ARC_NA(0.00)[]; TO_DN_NONE(0.00)[]; PREVIOUSLY_DELIVERED(0.00)[doc@freebsd.org]; TO_MATCH_ENVRCPT_ALL(0.00)[]; DKIM_TRACE(0.00)[jimby.name:+] 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