[qubes-doc] Opinion and decision for code blocks?

[Jeremias E.]

Hello,

I tried 5 combination for code blocks in qubes doc out.

The github flavored markdown (GFM) code block extension is not possible:

```
code comes here
```

because the current qubes-doc configuration [1] uses kramdown and pygments.

The fenced code block can be used with an additional setting in the configuration file:

-> q-doc-kramdown-gfm.png

Standard markdown uses four spaces of indention or eight in an list.

-> q-doc-markdown.png - shows a markdown code block in a list.

Markdown code blocks don't offer syntax highlighting.

Kramdown itself has a fenced code block syntax [2], but it is different from GFM:
~~~
code comes here
~~~

-> kramdown-block.png result of the above code

The kramdown fenced code block syntax allows to specific a programming language for syntax highlighting:

~~~ bash
code comes here
~~~

-> q-doc-kramdown-block-lang.png

this only works with the KramdownPygments plugin [3]:

-> q-doc-KramdownPygments.png

but the plugin has to be installed and configured.

Another option to highlight code blocks is to use pygments:

{% highlight bash %}
code comes here
{% endhighlight %}

this works fine:

q-doc-kramdown-pygments.png

but is not perfect with intended code blocks:

-> q-doc-kramdown-pygments-wrong.png

Here is my not completely objective pro/contra summary:

Markdown:
---------------

Pro:
  + Least common denominator

Con:
  - No, syntax highlighting
  - Based on indention (easy to make a mistake)
  - Hard to find with automatic scripts

Kramdown:
----------------

Pro:
  + easy to write with US and European keyboard layouts
  + visible difference between code and text

Con:
  + No, syntax highlighting

KramdownPygments:
-------------------------------

Pro:
  + see Kramdown
  + synatx highlightning

Con:
  - Extra plugin needed
  - Configuration needs to be changed

Pygments:
----------------

Pro:
  + syntax highlighting

Con:
  + ugly in text

There are many options, but what is the best options?

[1] https://github.com/QubesOS/qubesos.github.io/blob/12dc47618b0bc4e20bf52dc31ff08223a3693486/_config.yml#L23

[2] http://kramdown.gettalong.org/syntax.html#code-blocks

[3] https://github.com/mvdbos/kramdown-with-pygments

Best regards
  J. Eppler

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Thanks for detailed analysis!

We need a solution, which:
1. Does work with github pages. AFAIR there is predefined set of plugins
which can be used.
2. Looks nicely on website.
3. Looks nicely in source (and is easy to edit).

According to this criteria, the best option would be to use
KramdownPygments, if possible on github pages (not sure if this plugin
is supported there). If not, we should probably go with plain Markdown
or Kramdown (without syntax highlighting).

> [1]
> https://github.com/QubesOS/qubesos.github.io/blob/12dc47618b0bc4e20bf52dc31ff08223a3693486/_config.yml#L23
>
> [2] http://kramdown.gettalong.org/syntax.html#code-blocks
>
> [3] https://github.com/mvdbos/kramdown-with-pygments
>
> Best regards
> J. Eppler

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBCAAGBQJWBTmwAAoJENuP0xzK19cst9QH+wSj+M5GjERs+S4jqzrX7Cp3
S8C0zbNcgxB1NbOGVWZUEdKDwfJMMXSMSl7Nzulfb1NLBPpSClJGm9nxW1WXC1KO
7XJWJDoDcJp09NXwR6o4GdyChRGLqu56/TZED1634s+YljPuz75xiFXyFxNci8Nu
qQBUXmPFA4E3lGaQmriWNJebmZx44FD8rSSxG211m3SQ0cdZ3SGFbnDGeaMv4fRZ
9p13yp/IzLYCnzdPhz4vkUpc1cG+IpM0zsfZTJXGRbXBBG79q716hkUO3oCklFHZ
FL7Xcu6tN3RpKldXB4XcsQ/8M/QMAu96kfWjXdNidUN41jdp32FKCU5V6Joo64Y=
=b4pZ
-----END PGP SIGNATURE-----

[Jeremias E.]

Hello,

We need a solution, which:
1. Does work with github pages. AFAIR there is predefined set of plugins
which can be used.
2. Looks nicely on website.
3. Looks nicely in source (and is easy to edit).

According to this criteria, the best option would be to use
KramdownPygments, if possible on github pages (not sure if this plugin
is supported there). If not, we should probably go with plain Markdown
or Kramdown (without syntax highlighting).

KramdownPygments needs a custom plugin, but custom plugins are not allowed with github pages [1]. This is only true if the pages are build by Github. If you build them offline an push the result of jekyll's build process, than it is possible to use every available result.

Github-Pages uses the master branch to build. If there is only a gh-pages branch Github will just serve the static content on the gh-pages branch.

What works on Github-Pages an what not can be tested locally with: jekyll serve --safe
Github-Pages uses the --safe parameter. The big advantage of testing locally is, that Github-Pages does not provide usefull debug messages if something goes wrong.

[1] http://jekyllrb.com/docs/plugins/

[Jeremias E.]

I guess the decision is clear: qubes-doc should use either markdown or kramdown's tilde syntax or?

[Jeremias E.]

Hello,

@Marek I hope kramdown for the qubes-doc repo is okay.
I created a pull request, you can find it here:
https://github.com/QubesOS/qubes-doc/pull/43