Page MenuHomeFreeBSD
Files F108264736

D48468.diff
No OneTemporary
Actions

D48468.diff
View Options

diff --git a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
--- a/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
+++ b/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc
@@ -66,7 +66,7 @@
Filenames could be shown in a “typewriter” style font for viewing on screen, but as “italics” when printed, or any of a myriad of other options for presentation.
It was once hoped that Artificial Intelligence (AI) would make this easy.
-The computer would read the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more.
+The computer would read the document and automatically identify key phrases, filenames, text that the reader should type in, examples, and more.
Unfortunately, real life has not happened quite like that, and computers still require assistance before they can meaningfully process text.
More precisely, they need help identifying what is what.
@@ -137,7 +137,7 @@
[[asciidoctor-paragraphs]]
== Paragraphs
-Paragraphs don't require special markup in AsciiDoc.
+Paragraphs do not require special markup in AsciiDoc.
A paragraph is defined by one or more consecutive lines of text.
To create a new paragraph leave one blank line.
@@ -222,7 +222,7 @@
=== Links to another book or article
To point to another book or article the Asciidoctor variables should be used.
-For example, if we are in the `cups` article and we want to point to `ipsec-must` these steps should be used.
+For example, in the `cups` article, to point to `ipsec-must` these steps should be used.
. Include the [.filename]#urls.adoc# file from [.filename]#~/doc/shared# folder.
+
@@ -297,7 +297,7 @@
The next step will be to configure the Asciidoctor attributes `images-path` and `imagesdir`.
-We are going to use as an example the header of the extref:{freebsd-releng}[FreeBSD Release Engineering] article.
+Here is the example header of the extref:{freebsd-releng}[FreeBSD Release Engineering] article.
[source,asciidoc]
....
@@ -333,7 +333,7 @@
[TIP]
====
-To improve accessibility, it is mandatory to add descriptive text to each image.
+To improve accessibility, it is mandatory to add descriptive text to each image as shown in the example above.
====
[[asciidoctor-icons]]
@@ -360,6 +360,199 @@
To improve the accessibility of the website, the `title` attribute is mandatory.
====
+== Creating an Index in FDP Articles and Books
+
+Creating an index in FreeBSD Documentation Project documents is easy, because the index tooling is already built into Asciidoctor.
+An index is simply a new section in a document or a new chapter in a book.
+Here's a quick summary on how to generate an index for FreeBSD FDP books, articles, and multi-part documents.
+
+[NOTE]
+====
+The FDP toolkit does not generate an index for HTML output, only PDF output.
+====
+
+=== Creating an Index for Article Documents
+
+Articles are single-part documents as opposed to muli-part documents like books.
+If the article is short - one or two pages - an index is hardly worth the trouble.
+But for larger articles, it can help the reader to easily locate specific terms.
+
+[TIP]
+====
+Asciidoctor only allows level 1 headings (== MyHeading) and higher levels for articles.
+It does not allow level 0 headings (= MyHeading) for articles, only books.
+====
+
+Here is a procedure for creating an index for an article.
+
+[.procedure]
+====
+. Decide where to place the index.
+The best location is usually at the end of the article.
++
+. Add a new section to the bottom of the _index.adoc file.
+This tells Asciidoctor where the index is to be placed.
+Use the following construction:
++
+ [[index]]
+ == Index
++
+. Continue below with "Tagging Terms for an Index"
+====
+
+=== Creating an Index for Book Documents
+
+There are several additional steps necessary for building a book index.
+An index is a new chapter, and the steps below show how to integrate the new chapter into an existing book.
+
+[.procedure]
+====
+. Create a new chapter by copying an existing chapter.
+Usually, copying the last existing chapter works well.
+Here, `chapter10` is used as the name of the last chapter.
++
+ cd <bookdir>
+ cp -av chapter10 index
++
+Change the front matter in the [.filename]#index/_index.adoc# as described below.
+Change the title, "prev:" field, and the "weight:" value.
++
+[subs=+quotes]
+----
+ ---
+ title: #Index#
+ #prev: books/mybook/chapter10#
+ description: #Index#
+ tags: ["firewall", "IPFW", "Virtual Machine", "VM", "QEMU"]
+ showBookMenu: true
+ weight: #140#
+ path: "/books/mybook/index/"
+ ---
+----
+Make the weight value the highest value of any chapter in the book.
+This puts the index at the end of the book.
++
+Also, add or change the #next:# field in the front matter of the *previous* chapter (chapter10/_index.adoc).
++
+. Put the index header and title at the end as shown below.
+Use a level 0 section header for the title "Index".
+This puts the index on a separate page.
++
+[subs=+quotes]
+----
+ . . .
+
+ ifndef::env-beastie[]
+ toc::[]
+ include::../../../../../shared/asciidoctor.adoc[]
+ endif::[]
+
+ [[index]]
+ = Index
+----
+====
+=== Tagging Terms for the Index
+Follow this procedure to tag items for the index.
+[.procedure]
+====
+. Now go through all the text in all the chapters and tag each term to be indexed.
+Add the *indexterm:[]* tags on their own line near the term.
+The tag placement can be on the line before or after the term - just be consistent.
+Note how subindex terms are specified.
++
+ The quick brown fox jumps over the lazy dog.
+ indexterm:[fox] indexterm:[dog] indexterm:[animal, fox] indexterm:[animal, dog]
++
+This example creates four index entries as follows (all shown on page 1):
++
+[subs=+quotes]
+----
+ *A*
+ animal
+ dog 1
+ fox 1
+ *D*
+ dog 1
+ *F*
+ fox 1
+----
++
+*Additional notes*
++
+Multiple tags on the same line are permitted.
+However, *do not* use tags on the same line as the term like this:
++
+ Do not do this:
+ The quick brown fox jumps over the lazy dog. indexterm:[fox] indexterm[dog] indexterm[animal, fox] indexterm:[animal, dog]
++
+This tagging style (added to the end) conflicts with the FDP "One Sentence Per Line" directive and man:vale[1] will complain.
++
+. Avoid tagging terms inside any block listings.
+The tags show up in the output.
+Instead, put the tags on a separate line either before the listing header or after the listing body.
+Leave one extra line before the listing header.
++
+ indexterm:[fox] indexterm[dog] indexterm[animal, fox] indexterm:[animal, dog]
+ (Leave a blank line here.)
+ [.programlisting]
+ ....
+ The quick brown fox jumps over the lazy dog.
+ ....
++
+. Avoid tagging terms inside [NOTE], [TIP], [WARNING], [IMPORTANT], and similar structures.
+The tags show up in the output in some cases.
+. Be consistent in tag usage.
+Keep a running list of decisions on indexing.
+If a term in a tag is singular or capitalized or contains multiple words, always use the same stye of the term in other tags.
++
+Avoid mixing term styles like this:
++
+ indexterm:[jump] indexterm:[jumps over] indexterm[Jump]
++
+. Not every instance of a term needs its own tag.
+If there are several sentences together, each having the same term, or even nearby paragraphs having the same term, just tag the term once.
+The index entry will be the same for all of them.
+Asciidoctor does not filter out multiple index entries on the same page.
++
+. If tagging terms in a numbered procedure, place the tags on separate lines with '+' for continuation.
++
+Example:
++
+ [.procedure]
+ ====
+ . On the FreeBSD host, install the necessary packages - man:qemu[1], man:sudo[8] (or man:doas[1]).
+ The examples in this book use sudo.
+ +
+ indexterm:[QEMU, pkg install] indexterm:[sudo] indexterm:[sudo, pkg install]
+ +
+ [subs=+quotes]
+ ----
+ # *pkg install qemu sudo*
+ ----
+ +
+ . Create a directory layout for the files to be used.
+ +
+ indexterm:[SCRIPTS] indexterm:[ISO] indexterm:[fetch]
+ +
+ [subs=+quotes]
+ ----
+ % *mkdir -p ~/ipfw/VM ~/ipfw/SCRIPTS ~/ipfw/ISO*
+ % *cd ~/ipfw/ISO*
+ % *fetch https://download.freebsd.org/releases/amd64/amd64/ISO-IMAGES/#<latest version>#/FreeBSD-#<latest-version>#-RELEASE-amd
+ 64-dvd1.iso*
+ ----
+ +
+ indexterm:[tap] indexterm:[bridge]
+ +
+ . Create the bridge and tap devices for the virtual machines (VMs) to use.
+ +
+ . Finish everything and go home.
+ ====
+
+. Make the document normally (make DOC_LANG=whatever).
+When the book is completed, open the PDF version and review the index for errors and consistency.
+====
+
[[asciidoctor-conclusion]]
== Conclusion

File Metadata

Mime Type
text/plain
Expires
Fri, Jan 24, 6:08 AM (16 h, 55 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
15828710
Default Alt Text
D48468.diff (8 KB)

Event Timeline