Thanks for the additional insight, Carl. Your points about Markdown and extensions seem valid, and I'm perfectly fine with asciidoc and/or RST.
I don't know about producing a "book" for the Guacamole Manual - it seems like it may be valuable to have some sort of "offline" representation of it, whether that's a PDF or a Text-based document. I lean more toward just doing text-based and web, and maybe avoiding the PDF option, but, again, no strong preferences and I'll go with the consensus. -Nick On Wed, Apr 21, 2021 at 6:09 AM carl harris <[email protected]> wrote: > 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 > >> > >
