On Fri, May 12, 2023 at 1:11 PM Petter Reinholdtsen <p...@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
