Language blocks as table/dl via AsciiDoc, removing problematic flags

[toastal]

Flags are not languages. To remove this problematic issue, I moved the list to a horizontal definition list (which is rendered as a table). I tried using some other formatting options but most were not compatible with GitHub's default styling. I think this provides the best alternative while still maintaining IDs. Unfortunately lang attributes are stripped or I'd wrap the whole block to help with the accessibility. To view a preview of this commit rendered in GitHub: https://github.com/toastal/anim-com/blob/lang-blocks%2Bno-flags/README.adoc.

Additionally, I added proper curly punctuation to English and German.

[pnu-s]

Hi @toastal and thanks for the proposal!

I agree with you about the flags and I like the new rendering.

I am not familiar with this so could you please explain:

• why it is better to rename our file to README.adoc?
• why your new syntax for titles is better than the previous one (## for instance)?
• why your new syntax for web links is better than the previous one?

This overall feels less standard to me, but I'm happy to be proven wrong here.

[toastal]

*.adoc is the file extension for AsciiDoc which is supported by GitHub, GitLab, and others as a "human-readable document format", similar to Markdown, except AsciiDoc has a slightly different but similar in spirit syntax to other formats like Markdown, reStructured Text, Org files, etc. Markdown is notorious for having very few features and not having a good standard syntax with many forks/flavor (like GitHub-flavored Markdown on GitHub, GitLab-flavored on GitLab) to deal with lack of features, but this ties the README's syntax to a specific platform.

What does AsciiDoc bring? In this case, more semantic elements for this markup. The English idiom is "when you have a hammer, everything looks like a nail" and that's how this seemed the ## headings were used. Languages options aren't "headings" and headings come with anchors that didn't make much sense (README#-de means??).. While I believe regular blocks with titles and a lang tag would be more optimal if this were pure HTML, dealing with GitHub's rendering limitations/styling for AsciiDoc (specifically a lack of styling for block titles) lead me to suggest a description list as a better element choice in the GitHub render, the HTML render from a tool like asciidoctor, and syntax highlighting in a text editor.

Alternatively, a <table> via GitHub's specific Markdown flavor could work if the project maintainer does not like or does not want to change from Markdown to AsciiDoc, however, the 'human-readable' part of a GitHub-flavored Markdown table is quite noisy and now the only place this README can be expected to be rendered correctly is on Microsoft's GitHub. Given Exodus as the umbrella is about exposing trackers, tying specifically to GitHub and its data sharing seems out of character.

[jfoucry]

Hello,

I agree with @toastal about the general advantage of asciiDoc. but in our case it will make to type of markup language to maintain. The blog use markdown (with Hugo).

Btw, I read that Hugo can use asciiDoc as source format but changing ALL the website markup will be a huge work and we did not have time for that.

[toastal]

Well then I wouldn't recommend changing everything. Feel free to close this bug however if you have a flag-less solution of your own.

[pnu-s]

Can we reach a compromise and remove the flags without changing the doc format?

[toastal]

Sure. I would suggest a table, but this is specific to GitHub's Markdown dialect and not the larger Markdown spec.

[jfoucry]

Sound a good compromise for me.