HOWTO: TOC and headings formatting

MIKE MAJOR ossfm at yahoo.com
Wed Aug 15 02:41:16 UTC 2018


Hello everyone,
As mentioned previously, I would like to start making some edits and submissions to the project. I am going to start small because that is a good way to start for the first edit and because Paul appears to be a prolific editor. I can see in his fork that he is already addressing some of the issues I noted. If our changes/commits collide, I will learn some more about how to stay in sync with upstream while making changes at the same time. 

The first edits I propose are to massage the TOC indentations and add section numbers. 

First, the TOC indentations. The major sections should not be indented. By major section I mean mainly the phases called out like Early Configuration, Smoke-test the SBC/HAT combination, Live-test the GPS and so on. The supporting sections should be indented to show they are part of a larger section. 

The second change I propose is to add section numbers. The idea is to let the reader know where they are in the process. It can also help to have a number to refer to when discussing a section. A user contacting the project might type "In reference to section 4d. Clockmaker...". Here is a sample TOC. It is a snippet from my cloned repo with asciidoc modifications applied, built and rendered in a browser.
1. Introduction
2. Parts list
3. Hardware assembly
    3a. Understanding the GPIO connector
4. Configuration overview
    4a. Make a bootable SD
    4b. First boot
    4c. First ssh access
    4d. Clockmaker

I also added a heading just for the Hardware Assembly section. I thought it deserved its own major section. 

These are quite a few lines of changes but I think it is "all one thought, which is easier for (code) review". 

I look forward to your thoughts on the proposal. 

Thanks, 
Mike 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ntpsec.org/pipermail/devel/attachments/20180815/8ab6b579/attachment-0001.html>


More information about the devel mailing list