Re: [lmi] Style guide

[Vadim Zeitlin]

On Sun, 25 Feb 2018 02:51:45 +0000 Greg Chicares <address@hidden> wrote:

GC> But it's not okay to modify MD as though it were plain text:

 It is. Nothing bad will ever happen if you do this.

GC> it has its
GC>   ```
GC>   oddities--like triple-backquote instead of <pre>...</pre>
GC>   which isn't easier, clearer, or cleaner--just different
GC>   ```

 OK, I don't know why did I use triple backticks to be honest. Just remove
them and indent the contents instead. And, as you well know, <pre> is not
enough: you also need <tt> inside it. And don't forget to put it on the
same line if you want to avoid unwanted line breaks.

GC> and `quirks` and

 Quirks, really? For anybody who has ever used shell to ask `who am i`
backticks can really only a single thing: this is some text meant for the
computer.

GC> weird stuff
GC> -----------

 How can underlining a header be weird? It would be more weird to not
underline it.

GC> * and
GC> weirder stuff
GC> =============

 Or double underlining a more important header?

GC> ### and so on

 OK, don't use hashes for the next level sections. It's a common
convention, but, I agree, not a universal one, unlike the underlines.
It's fine not to use them. Just use numbered items instead if you prefer.
Or nothing, it's completely up to you.

GC> I don't want a file in the savannah repository that I can't maintain.
GC> I can't maintain this without learning a new markup language. I have
GC> no wish to learn a new markup language.
GC> 
GC> Markup-free flat text works just fine:
GC>   http://git.savannah.nongnu.org/cgit/lmi.git/tree/gwc/develop3.txt

 Please just rename this file to .txt, remove the triple quotes and let's
pretend it's just a plain text file. Anything is better than writing HTML
by hand (not because it's so complicated (it is, but not inordinately so),
but because it's so unnecessary and needlessly self-punishing).


 Let me make a **bold** statement and paraphrase one of your favourite
quotes:

        > Monsieur Greg, you've been already writing Markdown all your
        > life.

 Every time you do one of the following:

* Use bullet lists.
* Or _emphasize_ something.
* Or indent code for clarity.

 You were writing Markdown without knowing it. In fact, here is your
gwc/develop3.txt file with only very minor changes (use 4 spaces instead of
2 for indentation and add blank lines around the code snippets) as Markdown:
https://github.com/vadz/lmi/wiki/Develop-example

 I could literally use the following command to commit it to the wiki:

        $ git commit -m "Subliminal message: Markdown is great"

 And, to finish, here is the last part of this email without any changes at
all: https://github.com/vadz/lmi/wiki/Email-example


 You don't need to learn Markdown, it's too late, you already know it
(insert sounds of maniac laughter). Please let's just continue using it,
it's the de facto lingua franca of all programmers world-wide and while it
might not be the prettiest thing ever, it's definitely the easiest one to
read and to write -- because you've been already doing it for decades.

 Regards,
VZ