Documentation

[janosvitok]

Hi all,

I've made a quick attempt to convert documentation to AsciiDoctor.

Sources: https://github.com/janosvitok/qlcplus-manual
Result: https://github.com/janosvitok/qlcplus-m ... manual.pdf

I've taken English HTML user guide, converted to Asciidoctor using pandoc, sorted to directories,
and hand edited so that the header levels are right.

I've not created HTML from it yet.

Next the whole text must be reordered, fixed to proper AsciiDoc, and nicer template applied.

Jano

[mcallegari]

Hi Jano, thanks but the idea is to convert everything to Markdown and create a new collaborative project on GitHub integrated in a service like Transifex or Weblate and then exposed on a dedicated website.

Example: https://demo.hibbittsdesign.org/grav-learn2-git-sync/

[janosvitok]

Hi,

my idea was to

- convert the docs to asciidoc,
- setup github action to produce html and pdf and publish it to github pages

if it works then we can move the repo to github/mcallegari/ or whatever is best,
and people can post pull requests with corrections.

I prefer asciidoc/asciidoctor over markdown (mainly for built-in PDF support, nicer tables and I don't remember what else).
There's also readthedocs/sphinx, that looks promising, I just don't like the RST syntax.

There is plugin for firefox to render asciidoc live in browser, and plugin for IntelliJ Idea to edit the files.

It's possible to render the files to QT help. It would require to write special processor and I don't think it's worth it.

Github does natively display asciidoc quite ok. I don't know if the github web editor previews asciidoc.
Gitlab has much better asciidoc support, but I think it's not worth it to move.

I don't know of a better way to handle translations than to have separate dirs for each language.

Jano