fdp-primer: reduce confusion around section levels

[grahamperrin]

Summary

https://github.com/freebsd/freebsd-doc/pull/97

Origin of this diff:

• https://github.com/freebsd/freebsd-doc/compare/main...grahamperrin:freebsd-doc:patch-2.diff

Test Plan

Preview in GitHub:

• https://github.com/grahamperrin/freebsd-doc/blob/patch-2/documentation/content/en/books/fdp-primer/structure/_index.adoc#4-the-books-books

[carlavilla]

Perfect, thanks!

[grahamperrin]

My usual mistake: whitespace errors. Corrected prior to a9f81805c39b8a6e0ec6e87ce6d7151764ea850c at:

• https://github.com/grahamperrin/freebsd-doc/commit/8d2eef705d3e92072c0ad02c0c0fcddeae4da078.

Pull request closed by my deletion of the patch-2 branch:

• https://github.com/freebsd/freebsd-doc/pull/97#event-7925082725.

End result (currently chapter 4, section 4.4):

• https://docs.freebsd.org/en/books/fdp-primer/book/#structure-document-books.

[grahamperrin]

documentation/content/en/books/fdp-primer/structure/_index.adoc

155–157

Some wrongness, maybe due to me working with split (not my usual preference) during part of this review.

When a book is viewed as a book, in its entirety:

• <h2> is used for a chapter (not a section thereof)
• <h3> is used for the first logical section of a chapter

{F52387089}

[grahamperrin]

AsciiDoc Language Documentation at Asciidoctor Docs – https://docs.asciidoctor.org/asciidoc/latest/ – is definitive, and clear.

Gut feeling: if it's not easy to paraphrase, accurately, what's definitive, then we should remove what's wrong from this book and allow readers to learn from the definitive point of reference.

documentation/content/en/books/fdp-primer/structure/_index.adoc

151

The implication: all books have multiple parts.

Maybe truer to say that a book can have more than one part.

Book Parts | Asciidoctor Docs

• each chapter is == (AsciiDoc section level 1), not =.

If I understand correctly, FreeBSD Documentation Project Primer for New Contributors is:

• doctype book and not a not a multi-part book

– it has only one part, with AsciiDoc section level 0 used for its first chapter.

https://cgit.freebsd.org/doc/tree/documentation/content/en/books/fdp-primer/overview/_index.adoc#n13:

= Overview

– and so on.