HOWTO: TOC and headings formatting
ossfm at yahoo.com
Wed Aug 15 02:41:16 UTC 2018
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.
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
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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the devel