graph
graph copied to clipboard
krlawrence
Replace AsciiDoc headings with new recommended style
In issue #16, we want to replace "Janus Graph" with "JanusGraph", which shortens the headings by a single character. However, the AsciiDoc headings currently in use have the same # of characters are the headings, e.g.,
Heading
~~~~~~~
That said, this is a deprecated heading, and was fixed in JanusGraph in this commit which also says:
As described in the Asciidoc best practices document: http://asciidoctor.org/docs/asciidoc-recommended-practices/#section-titles using heading markers using underlines of various characters is not recommended for several reasons:
- hard to remember which character means which level header
- hard to maintain the correct number of characters (must match heading line)
That commit also includes a complete Python script for making this update for AsciiDoc files, which will be used to convert the headings to the new recommended format, and make it easier to cleanup the name format.
I would like to hold off just a little while on doing this one as I really like how the old style headings look in Vim when I am editing the manuscript. I plan to do a lot of editing over the next few days. After that would be a good time for me to also change the heading style. I also note that the Asciidoctor guide that you referenced is listed as a draft and subject to change but I agree the point about keeping the line length the same does become a big pain. I'll get to this one after I get some more edits done. I just did a fairly big edit on Section 3 this morning.
Makes sense, I'm happy to rerun the script whenever you're ready — just ping either this issue or PR #18 to let me know.
Let's revisit this for the Second Edition on which work is just getting started