Updated the style guide a bit, and a proposal

[EzequielBruni]

I updated the style guide a little based on some current practice/ideas, and finished up the unfinished bits. Finally.

I'd like to make one more proposal, though, that I have not included. I'd like to officially propose, going forward, that every command that sits in its own "line" uses a code block, rather than inline code backticks. code in paragraphs can stay as-is of course, but I think everything that's not inline should officially go into a triple-backticked code block. If only so we can define the syntax.

To be clear, it should look like:

Run this command:

```bash
the-command
```

And not:

Run this command:

`the-command`

Thoughts?

[NezSez]

I like the idea of the syntax highlighting of the code blocks. So plus one thumbs!

[sspencerwire]

@EzequielBruni I think this would be fine. My question is whether bash needs to be included every time. To me, with code it does not, whereas if you are showing results of a command or something it does. That said, using the ```bash identifier for everything would make it less confusing for beginners and, for that matter, make it easy for editors to just add it if it wasn't there. I'm on board! I talked myself out of my own argument!! :-)

[NezSez]

I assumed the "bash" was just an example and not to be a default always to be included, as GH MD allows for many different language specs via "Linquist" and Grammer List (Note: one grammer includes many languages usually, it's like a style family), and languages.yml .
This system includes almost any programming language I've heard of, and many I haven't.

Reference: GH Syntax Highlighting

[alemorvan]

For information and unfortunately, crowdin does not keep the bash after the 3 anti-quotes in the translations. We will open an issue occasionally.

[alemorvan]

@EzequielBruni could you add a note on admonitions? It might be interesting to add something like:

Add a note when you want to give a tip or information that you want to highlight. There are several types of admonitions (Note, Warning, Tip, etc.)

[sspencerwire]

After further thought @EzequielBruni I think single-line commands can be entered with the as:

this command is here

but the output of the command could include the ```bash if needed. As @antoine has said, Crowdin is not keeping the bash section of that code, so perhaps we should just ditch it altogether and go with what I just put above for the command for the output of the command as well.

Ooops forgot that it will not display those back-ticks, so triple-back-ticks and then either code or output from the code followed by triple back-ticks.

[sspencerwire]

Also... I've not merged your changes (even though they can be merged), would you prefer to open an issue instead of keeping this conversation in the PR??

[EzequielBruni]

@sspencerwire Good point. Might be a better place to discuss it so we can merge the current changes.

I'd like to say that I don't think we need to be strict about keeping the language identifiers in translations and so on, my main concern was simple formatting.

[sspencerwire]

Ok all, I'm merging these changes after reading through them. If there are errors, I'll fix them up or @EzequielBruni will. Please continue the discussion on the suggestions in Issue 555 (see issues at the top of the GitHub interface). Thanks for all of the suggestions!