enhancement: documentation: translations and versioned sections, move to markdown

Status: https://github.com/i3/translation and https://github.com/stapelberg/i3/commits/markdown are where things stand. I’m not currently actively working on this.

I have been thinking about how to support community-contributed translations of i3 documentation. In particular, I see the following constraints:

• Translating a whole document can be a lot of work, so partial translations should be easily possible.
• Documents change, so translations must be marked as out of date, ideally on a per-section level.
• Additional tooling should be preferred over additional hosted services. While there are plenty of services for string translation within a program (e.g. weblate), I wasn’t able to find a service that would help with document translation anyway.

Proposal

I propose we convert our current asciidoc documentation into markdown.

Using markdown will allow us to easily write tools that make translations easier to manage for our release/contribution workflow.

As a side benefit, over the last few years, markdown has strongly overtaken asciidoc in popularity, so contributors will have an easier time, too.

Once the documentation is in markdown, we will annotate headings with the translation status, for example:

### Mouse bindings {#_mouse_bindings introduced="4_16" translated="4_18"}

A mouse binding makes i3 execute a command upon pressing a specific mouse…

We then use a custom markdown renderer (built on the well-established goldmark package) which converts our custom attributes into the desired HTML output.

You can find an initial sketch of tl8-render in the https://github.com/i3/translation repository.

Other markdown tools will still be able to make sense of our documents, but translation status will only be rendered when using our tool of course.

For our tooling to work, all headings must have an id, and that id must be consistent across translations. For switching from asciidoc to markdown, we already must ensure that all headings have the same id as they had before, in order to not break any (external or internal) links.

Translations will live in the https://github.com/i3/i3.github.io website repository, because they are based on released documentation, not in-development documentation.

As a nice bonus, versioned documentation as discussed in issue #2563 will become trivial to implement with this approach.

Example: starting a new translation

git cp _docs/userguide.markdown _docs/fr/userguide.markdown
tl8-new _docs/fr/userguide.markdown  # marks all sections as untranslated

Example: new i3 release / out-of-date sections

When we do a new release, our release.sh automation would call tl8-flag like so:

tl8-flag _docs/userguide.markdown  # flags changed sections as out of date in _docs/*/userguide.markdown 

Here’s a mockup of how an out-of-date section would be rendered with tl8-render:

(Obviously default keybindings were not only introduced in i3 v4.16, but I wanted to illustrate versioned documentation as well.)

TODO list

• implement tooling and submit it into the i3 repository so that it is versioned/released with the rest of i3
• find a markdown-to-HTML converter that Linux distribution packaging can use
  • there are many (python-markdown, pandoc, the original markdown, …), but distributions should most likely not rebuild the docs and just use the HTML versions from our release tarball. Even Debian doesn’t rebuild.
• convert our documentation to markdown
  • docs/debugging
  • docs/hacking-howto
  • docs/userguide.markdown
  • docs/ipc
  • docs/multi-monitor
  • docs/wsbar
  • docs/testsuite
  • docs/i3bar-protocol
  • docs/layout-saving
• update release.sh to deal with translations