Add Markdoen guidelines

README.md

@@ -3,6 +3,12 @@ My Book
 
 Set of my more-or-less proven guidelines, best practices and (coding) styles.
 
+Index
+-----
+
+ *  [Markdown](guidelines/markdown.md)
+
+
 Author
 ------
 

guidelines/markdown.md

@@ -0,0 +1,112 @@
+Markdown guidelines
+===================
+
+Markdown is very flexible.  To ensure this flexibility does not help
+create inconsistencies, I try to adhere to following guidelines. These
+are not meant as strict rules, but rather set of hints, and reminders
+for myself next time I forget how do I do spacing etc.
+
+The guidelines take only original MD into account.
+
+
+Generic
+-------
+
+ *  Wrap at 75 columns at most (*fmt(1)* default).  Wrapping to less can
+    be beneficial (e.g. for re-quoting or in block comments) but less
+    than 61 is not considered sane.
+
+ *  Try to have 2 spaces after sentence.
+
+ *  Avoid huge paragraphs.
+
+ *  Avoid tiny paragraphs (except as a means of emphasis)
+
+ *  Avoid "strong" like the plague (rule of thumb: max. once per page).
+
+
+Headings
+--------
+
+ *  Use `===`, `---`, `###`, `####` for H1, H2, H3...
+
+ *  For #-based headings, append hashes also after the heading text
+    (e.g. `### Foo ###`, not `### Foo`)
+
+ *  Have 2 empty lines before each heading, 1 empty line after
+
+ *  In longer step-by-step howtos, consider using numbered headings
+    instead of lists.
+
+
+Lists
+-----
+
+ *  Make sure to have empty line before and after.
+
+ *  Except for very simple lists where all items are just few words,
+    add one empty line between items.
+
+ *  Align 2nd line and the rest to 4 spaces, (i.e. the previous
+    alignment plus 4 spaces).
+
+ *  For unordered lists, use asterisk, at least for the first level.
+
+ *  Optimal spacing is 1 space, asterisk, 2 spaces, e.g. ` *  foo`.
+
+ *  For ordered lists, optimal spacing is one or zero spaces in front
+    of the number, then one space, e.g. ` 9. Foo`, then `10. Bar`.
+
+
+Jargon names
+------------
+
+ *  For IT-related texts, variable names, underscores, tool names,
+    filenames are considered as "jargon", which falls into the typical
+    case for emphasized text.
+
+ *  However, if the text is (or should be, by author's opinion)
+    represented as code, backticks may be better choice.
+
+
+Links
+-----
+
+ *  Use reference-style, i.e. `[link text][1]` and then, after paragraph
+    (or later if that makes sense), use `  [1]: http://www.foo.../`.
+
+ *  Note that you don't need to use numbers: keyword is OK (even spaced),
+    but *keep it consistent within the document*.
+
+ *  You can also use `[link][]`; here the keyword = link text (i.e.
+    `  [link]: http://whatever` would follow).
+
+ *  Links can be local (although I have only used this in Github).
+
+
+Images
+------
+
+ *  Needless to say, they make no sense in plain text.  Otherwise
+    look at official Markdown specs.
+
+
+Code
+----
+
+ *  Remember that you can have code blocks in lists (step-by-step
+    howtos) and even in quotations:
+
+        John [said][1]:
+
+        > Always call `foo()` before `bar()`:
+        >
+        >     foo();
+        >     bar();
+        >
+        > and *everything* will work.
+
+ *  Try for copy/paste-able code i.e. avoid prompt char (`$`, `%`, `%`)
+    unless you are pasting *output*.  To convey the need of root privilege,
+    mention that in surrounding text or use *sudo*.
+