| Here's a result [1] from a system I've put together, primarily using AsciiDoc(tor) and PO4A[3], to allow us to write a source document then translate it into multiple languages. It produces HTML and PDF, but ePUB is an option too. Using AsciiDoc rather than Markdown has several benefits. The language supports many common book features, especially for technical books, like those "! Warning here" callouts, cited quotes, captioned figures/tables/codeblocks, internal links, I think even an index. It's also a lot more stable; I'm not concerned that there will be significant syntax changes in 5 years time. The user manual [2] is the quickest way to see what AsciiDoc can do. PO4A is an adaptation of GNU GetText to use on prose. PO4A's output can input into a typical translation workflow -- distributing the files, or using online translation services. It mostly supports AsciiDoc, though there are some bugs, and outputting a PO file directly from AsciiDoctor (with a plugin) might be better -- PO4A parses AsciiDoc itself. The code is at [4]. It's in slow development when necessary for new documents; I don't particularly intend to polish it for release or wider use. KiCAD's documentation was the best example of something similar (AsciiDoc + PO4A) to what I've put together. The missing pieces, which are closely related, are translatable and flexible diagrams. AsciiDoctor supports plenty of diagram tools, but none of them can do this. For example, the diagram at [6] is an SVG, which (since it's XML) can be translated using PO4A. However, in French the longer text spills out of the boxes. The previous diagram is an image, for this reason. Is there an open-format (preferably open source) diagramming tool, which supports wrapping text, and even resizing "too long" text? I would be very interested! [1] https://docs.gbif.org/collections-idea-paper/ or (in progress) https://docs.gbif.org/effective-nodes-guidance/1.0/ [2] https://asciidoctor.org/docs/user-manual/ [3] https://po4a.org/ [4] https://github.com/gbif/gbif-asciidoctor-toolkit/ [5] https://gitlab.com/kicad/services/kicad-doc [6] https://docs.gbif.org/effective-nodes-guidance/1.0/en/#box-e... |