Re: User Docs for DebianEdu

On Fri, May 12, 2023 at 1:11 PM Petter Reinholdtsen <pere@hungry.com> wrote:

While it is unclear to me if it is a good idea to leave the Debian wiki
when writing documentation, I leave that to others to figure out.

I leave that to others too.

I just wanted to point out that when selecting source format for the
documentation, I strongly recommend using a format that can be converted
to docobok using pandoc, to be able to create good looking documentation
in both HTML, PDF and ePub format.

It is also a very good idea to ensure the format selected is well
handled by po4a to allow the documents to be translated into non-English

Personally I would recommend Restructured text (rst) over markdown, as
it has a richer vocabulary than markdown. I recommend Restructured text
over Asciidoc as the latter is less well supported by po4a.

My first choice would be AsciiDoc+Antora because I have some experience with them.

I think that the AsciiDoc syntax provides the best mapping to the DocBook features.

Pandoc cannot handle it well precisely because its structure is richer than what pandoc can support.

But we can use Asciidoctor instead to generate DocBook from AsciiDoc: https://docs.asciidoctor.org/asciidoctor/latest/docbook-backend/

I have not really explored po4a (and if you ask me it is a bad approach to translation), but it seems like it is supported: https://gitlab.com/antora-ui-custom/antora-i18n#user-content-po4a

Cannot say whether this support is better or worse compared to Restructured text.

Kind regards,

Dashamir