4 ms·

asciidoc via asciidoctor (https://asciidoctor.org https://asciidoctor.org) covers a lot of this, though not bundled into a system. Comments/edits via something

asciidoc via asciidoctor (https://asciidoctor.org https://asciidoctor.org) covers a lot of this, though not bundled into a system. Comments/edits via something like GitHub, tables (https://asciidoctor.org/docs/user-manual/#tables https://asciidoctor.org/docs/user-manual/#tables), tables of contents (https://asciidoctor.org/docs/user-manual/#user-toc https://asciidoctor.org/docs/user-manual/#user-toc), and with some docbook work (admittedly annoying), you can get header/footer and page number (https://asciidoctor.org/docs/user-manual/#docinfo-file https://asciidoctor.org/docs/user-manual/#docinfo-file). It's not perfect, but it's very similar in concept to Markdown, has several adaptations to make the md->adoc transition easier, and is much more feature-rich, thanks to being based on Docbook (which is used for creating much more complicated documents than Markdown historically has been).

castillar76 9y ago
Agreed. As someone that manages multiple documents under heavy revision control in a public repository (yay, public certificate authority documentation), Asciidoc has been a life-saver. We used Word for a long time, but found it was way too difficult to track revisions and approvals using it. Inevitably, you'd pass the document to eight people that need to approve and get back eight sets of changes, which you then have to integrate in and hope no one has introduced a regression from "DOCUMENT_JONREVIEW_VERSION1_COMMENTS_FINAL_FINAL_DRAFT_FINAL_DRAFT_FINAL_COMMENTS_V6". Moreover, the people doing the reviews are a mix of technical and non-technical, and doing the review/approval process in Word docs meant constructing an Alfresco instance or similar to track the approvals and validate for auditors that we'd completed reviews before pushing updates. Also, you have to create something to keep track of the Word document originals /and/ the PDFs they produce—it always seemed like the Word originals would disappear at some point, leaving everyone to back-create them from the PDFs. Now we do the documents in AsciiDoc, and track everything in an internal Github repository using pull requests. The diffs are clean and are actually easier to read: you can comment, you can immediately see where the changes are, and everyone is focused on changes in content rather than getting distracted by font and spacing choices. Once N people out of M have approved the pull request, I can merge it into the master and then publish it into a clean, readable PDF with an auto-generated table of contents, page numbers, footers, and the like. Now, if someone were to invent a WYSIWYG app for Asciidoc, that would be awesome, but this seems to be working a whole heck of a lot better than the previous Word-based method.

castillar76 9y ago

Agreed. As someone that manages multiple documents under heavy revision control in a public repository (yay, public certificate authority documentation), Asciidoc has been a life-saver. We used Word for a long time, but found it was way too difficult to track revisions and approvals using it. Inevitably, you'd pass the document to eight people that need to approve and get back eight sets of changes, which you then have to integrate in and hope no one has introduced a regression from "DOCUMENT_JONREVIEW_VERSION1_COMMENTS_FINAL_FINAL_DRAFT_FINAL_DRAFT_FINAL_COMMENTS_V6". Moreover, the people doing the reviews are a mix of technical and non-technical, and doing the review/approval process in Word docs meant constructing an Alfresco instance or similar to track the approvals and validate for auditors that we'd completed reviews before pushing updates. Also, you have to create something to keep track of the Word document originals /and/ the PDFs they produce—it always seemed like the Word originals would disappear at some point, leaving everyone to back-create them from the PDFs. Now we do the documents in AsciiDoc, and track everything in an internal Github repository using pull requests. The diffs are clean and are actually easier to read: you can comment, you can immediately see where the changes are, and everyone is focused on changes in content rather than getting distracted by font and spacing choices. Once N people out of M have approved the pull request, I can merge it into the master and then publish it into a clean, readable PDF with an auto-generated table of contents, page numbers, footers, and the like. Now, if someone were to invent a WYSIWYG app for Asciidoc, that would be awesome, but this seems to be working a whole heck of a lot better than the previous Word-based method.