At least in my experience, Markdown is great for making web pages, but it's difficult to do a book/manual in pure Markdown without resorting to using some HTML or adopting one of the Markdown extended variants and perhaps adopting a delivery mechanism too. For example, you can do really attractive technical documentation using Hugo which is based on Markdown, but to really make it work, you’re also adopting Hugo and it's really focused on producing an (attractive) HTML presentation of Markdown as a website.
Almost everything that can be represented using the semantic markup of Docbook has an equivalent representation in Asciidoc or RestructuredText. In fact, pandoc[1] does a darn good job of automating translation from Docbook to Asciidoc or RST as a starting point. Is producing the Guacamole manual as a “book” with a PDF representation that could reasonably be printed or viewed on an e-reader still an important consideration? Asciidoc and RST both include “book” as a structure semantic and include tooling to produce PDF, EPub, Mobi, for an e-book or printable representation. All of that said, if the desire is for something that is more approachable than Docbook, either of Asciidoc and RST will definitely come with a whole new set of approachability issues. One really has to work in one of these formats pretty often to be effective in using it. And if you work in Markdown often, the hardest part about using Asciidoc or RST might just be remembering that it *isn’t* Markdown — similar syntax can lead to different results. You might find some Guacamole contributors who have experience with RST (largely because of its extensive use in the Python community), and maybe even a few with Asciidoc experience, but I suspect that more often than not a contributor will find herself/himself reading an Asciidoc or RST primer while trying to write a contribution to the Guacamole manual. Maybe that primer is more approachable than a Docbook primer? :-) carl [1] https://pandoc.org <https://pandoc.org/> > On Apr 20, 2021, at 8:15 PM, Nick Couchman <[email protected]> wrote: > > +1 for moving to...something. I have very limited familiarity with > documentation frameworks, but I'm wondering if something in the line of > Mark Down would be possible, and if there's a good parser for turning that > into web pages? My thought here is that Mark Down seems to provide both > parseable functionality for building into rich text experiences (like > HTML), but also maintains good readability from a command line or text > editor, making it possible to distribute the manual in multiple formats. > > Having said that, and looking at documentation for both asciidoc and RST, > it looks like those languages have the same rough goals and features as > Mark Down, so I've no strong preference one way or the other. > > -Nick > > On Tue, Apr 20, 2021 at 7:08 PM carl harris <[email protected]> wrote: > >> I've used asciidoc and RestructedText (RST) on two different large >> document projects. I kinda prefer the RST toolchain, and I find the >> plaintext presentation of RST a little more agreeable, but really either of >> them would be good choices to move away from docbook. >> >> — >> carl >> >>> On Apr 20, 2021, at 6:20 PM, Mike Jumper <[email protected]> wrote: >>> >>> I've been thinking recently that the current guacamole-manual is not >> very >>> approachable with respect to contributions, and that members of the >>> community that might want to contribute to the manual may be turned off >> by >>> the complexity/unfamiliarity of DocBook and XML. It'd be nice if >> improving >>> the manual were as simple as editing a text document. >>> >>> Thoughts? Asciidoc seems a common alternative that is compatible with >>> DocBook. >>> >>> - Mike >>
