Draft: Convert coding guidelines to markdown
Experimental migration of the C++ coding guidelines (by @ssnyder) from the original org-format [1] to markdown. Mostly done using pandoc and few extra fixes using sed (see full command below).
Comparison:
- NEW: https://atlas-software.docs.cern.ch/staging-cppguidelines/coding-guidelines/
- OLD: https://atlas-computing.web.cern.ch/atlas-computing/projects/qa/draft_guidelines.html
TODO (in case we decide to make this our primary source for the coding guidelines)
-
Author attribution -
Change a few code blocks to verbatim text -
Cleanup footnotes -
Fix and add a few missing anchors (already missing in org-format) -
Fix spellchecker -
Use a better name/URL so we could distinguish this from some future Python coding guidelines
[1] https://gitlab.cern.ch/ssnyder/coding-rules/-/blob/master/rules.org
To reproduce
cat rules.org |
# Convert example code blocks to proper C++ code blocks
sed 's/BEGIN_EXAMPLE/BEGIN_SRC cpp/' | sed 's/END_EXAMPLE/END_SRC/' |
# Convert to markdown
pandoc --shift-heading-level-by=1 --from=org --to=markdown_strict+backtick_code_blocks+footnotes |
# Fix double quotes
sed 's/\\`\\`/"/g' | sed "s/''/\"/g" |
# Create proper anchors
sed 's/\\\[<span id="\(.*\)"><\/span>\\\]/[[\1]](#\1){: #\1}/' > rules.mdMerge request reports
Activity
added 5 commits
-
44013be6...a06b9073 - 4 commits from branch
main - 99bed835 - Convert coding guidelines to markdown
-
44013be6...a06b9073 - 4 commits from branch
hi Frank -
Thanks. I'd been meaning to play around with this a bit. It'll be a little while before i can look at this in detail, but a few quick comments.
Did you try converting from the md to pdf? One of the reasons that i originally set the document up like this was so as to be able to get a good-quality pdf version.
Comparing the outputs, they both have better points and worse points. If i were looking at it frequently, though, i think i'd prefer the original version. Having the sections numbered makes it easier to navigate, and for long texts, i generally find a serif font easier to read,. But those are presumably functions of the style, not of the input.
I am unsure that "generic" markdown is really appropriate for a "complex" document. I hope, for example, that one doesn't need to number citations by hand, as in the example here. And not having a comment syntax seems mind-boggling. (HTML comments seem to work with some translators but not others...) Maybe pandoc-markdown would be better...
Thanks for the feedback. I agree, one should decide carefully which format we want to use as the primary source for this type of document (admittedly, org-mode is maybe a bit exotic for most people). Just a few comments:
- Style (font, etc.) can certainly be adjusted. Automatic header numbering (in the HTML) would be a matter of adding some CSS.
- The footnotes are automatically numbered. But the pandoc export somehow decided to convert them to hard-coded numbers instead of using your original named footnotes.
- I added a pandoc-generated PDF version to the top of the page for comparison. Although even the browser-builtin "Print..." produced something reasonable.
One of the most problematic features to convert across formats are the local anchors to individual guidelines, which I consider a must-have (very useful for MR reviews). On the current HTML pages, they are defined, but don't appear as actual links either.
In any case, I would really leave it up to you to decide on the source format as you are the one maintaining the coding guidelines and then we'll see how to best integrate them into
atlas-software.docs(the currentiframesolution is really not very ergonomic).-
I made a bit more progress on this draft and fixed the remaining issues. The only remaining problem I found was that Markdown does not automatically number the footnotes according to occurrence in the text. So one has to manually put them in the correct order (I changed them back to the same name as in the original
orgsource).Of course, many of them could just be converted to normal hyperlinks instead of footnotes.
added 100 commits
-
a2ea0fd9...1c7e5288 - 98 commits from branch
main - 6075276a - Convert coding guidelines to markdown
- 4e3fd131 - Add PDF export of coding guidelines
-
a2ea0fd9...1c7e5288 - 98 commits from branch
added 2 commits
added 8 commits
- cecdc61d - Fix footnotes in coding guidelines
- 37316694 - Add section numbering
- fc203f79 - Make changelog a pure list and change some code blocks to text
- 651fa603 - Fix and add some missing anchors
- 59b2387b - Make spellchecker pass on coding guidelines
- 46d7b956 - Ignore footnotes in spellchecker
- 6c184f36 - Fix broken link to CERN-UCO/1999/207
- f714d991 - Add original authors
Toggle commit listadded 14 commits
-
a5d9ba65...da3d1f7a - 4 commits from branch
main - 1fcd8666 - Convert coding guidelines to markdown
- 06fa7ee9 - Add PDF export of coding guidelines
- 0b39e1ad - Fix footnotes in coding guidelines
- 67bca0fb - Add section numbering
- c56f717f - Make changelog a pure list and change some code blocks to text
- d4f03c05 - Fix and add some missing anchors
- 577190cb - Make spellchecker pass on coding guidelines
- 21a69cbe - Ignore footnotes in spellchecker
- aafc1bb9 - Fix broken link to CERN-UCO/1999/207
- bd8e7b12 - Add original authors
Toggle commit list-
a5d9ba65...da3d1f7a - 4 commits from branch