Page MenuHomeFreeBSD

fdp-primer: reduce confusion around section levels
Needs ReviewPublic

Authored by grahamperrin on Nov 30 2022, 5:04 PM.
Referenced Files
Unknown Object (File)
Wed, Mar 22, 6:42 PM
Unknown Object (File)
Mon, Mar 6, 3:36 AM
Unknown Object (File)
Thu, Mar 2, 2:09 PM
Unknown Object (File)
Feb 10 2023, 8:55 PM
Unknown Object (File)
Jan 8 2023, 3:31 PM
Unknown Object (File)
Jan 8 2023, 2:39 AM
Unknown Object (File)
Jan 5 2023, 5:19 AM
Unknown Object (File)
Dec 14 2022, 4:10 AM

Diff Detail

R9 FreeBSD doc repository
Lint Not Applicable
Tests Not Applicable

Event Timeline

grahamperrin created this revision.
carlavilla added a subscriber: carlavilla.

Perfect, thanks!

This revision is now accepted and ready to land.Nov 30 2022, 5:11 PM
grahamperrin added inline comments.

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


AsciiDoc Language Documentation at Asciidoctor Docs – – 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.


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.

= Overview

– and so on.