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.md
Edited by Frank Winklmeier