You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@guacamole.apache.org by Mike Jumper <mj...@apache.org> on 2021/04/20 22:20:19 UTC
[DISCUSS] Migrate guacamole-manual away from DocBook?
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
Re: [DISCUSS] Migrate guacamole-manual away from DocBook?
Posted by Nick Couchman <vn...@apache.org>.
On Wed, Apr 21, 2021 at 8:19 PM carl harris <ce...@gmail.com> wrote:
> One thing to note about RST tables — there are two ways to do table
> markup, and pandoc has selected the one that is most painful to maintain,
> but looks most attractive in plaintext form. The “simple table” markup is
> less attractive in plaintext form, but is definitely much less of a
> nuisance to maintain, and has fewer options for exotic nesting/merging of
> cells within columns/rows.
>
> +1 on the observation that RST relies on indentation, but (at least in my
> experience) that reliance feels pretty natural and intuitive, and the
> alternatives aren’t all that appealing. Quoting the RST specification,
> "Indentation is used to indicate -- and is only significant in indicating
> -- block quotes, definitions (in definition lists), and local[ly] nested
> content”. To me, it feels acceptable (and sort of obligatory) to ident
> consistently in the plaintext source in all of these situations anyway. But
> I move pretty freely and easily between “bracey” languages like
> Java/Javascript/XML and Python, so maybe I’m not too representative of
> “typical” Guacamole contributors in that regard.
>
>
I do this to some degree, too - I dabble in Python, and use Ansible (YAML)
on a routine basis for automation, so I'm used to working between languages
like those that rely on indentation and then back to Java, JavaScript, C,
etc., that couldn't care less is you had whitespace anywhere in the code or
not. So, while it may take some getting used to, I don't think that's a
show-stopper for RST.
-Nick
Re: [DISCUSS] Migrate guacamole-manual away from DocBook?
Posted by carl harris <ce...@gmail.com>.
One thing to note about RST tables — there are two ways to do table markup, and pandoc has selected the one that is most painful to maintain, but looks most attractive in plaintext form. The “simple table” markup is less attractive in plaintext form, but is definitely much less of a nuisance to maintain, and has fewer options for exotic nesting/merging of cells within columns/rows.
+1 on the observation that RST relies on indentation, but (at least in my experience) that reliance feels pretty natural and intuitive, and the alternatives aren’t all that appealing. Quoting the RST specification, "Indentation is used to indicate -- and is only significant in indicating -- block quotes, definitions (in definition lists), and local[ly] nested content”. To me, it feels acceptable (and sort of obligatory) to ident consistently in the plaintext source in all of these situations anyway. But I move pretty freely and easily between “bracey” languages like Java/Javascript/XML and Python, so maybe I’m not too representative of “typical” Guacamole contributors in that regard.
carl
Re: [DISCUSS] Migrate guacamole-manual away from DocBook?
Posted by Mike Jumper <mj...@apache.org>.
I've created a quick test using pandoc to translate the entire manual into
reStructuredText and Asciidoc for comparison.
reStructuredText:
https://gist.githubusercontent.com/mike-jumper/b93ef997e83d8565cf46b5bff71845b7/raw/7910262cf97247fcbb4053ed8ab33bcb40710e8d/gug.rst
Asciidoc:
https://gist.githubusercontent.com/mike-jumper/b93ef997e83d8565cf46b5bff71845b7/raw/7910262cf97247fcbb4053ed8ab33bcb40710e8d/gug.adoc
reStructuredText definitely seems much more readable in text form (compare
the tables and lists within the "Optional dependencies" sections). Changing
their contents, resizing columns, etc. looks like it would be painful,
though, and the document format appears to rely heavily on indentation
(like Python).
Asciidoc seems to require a good deal of technical markup even to create a
table, and the syntax seems more obscure.
- Mike
On Wed, Apr 21, 2021 at 1:43 PM Ivanmarcus <iv...@yahoo.com> wrote:
> Good morning all,
>
> Not sure I can contribute anything much on the two systems Mike's
> mentioned, but I've some related comments, for what they're worth:
>
> In general I've found the present documentation to be clearly written
> and formatted well, albeit (as with all documentation) it takes a little
> time to get used to the writer's intentions.
>
> I think the presentation is much better than many other project docs
> I've seen. Unless there was a compelling need or evidence to change the
> presentation per se I suggest it'd be a positive if something similar to
> the current output format could be retained.
>
> From an input perspective, this may be at complete odds with what I've
> just said, but almost everyone will know how to fundamentally edit text
> documents, whereas understanding and hand-editing XML etc is simply an
> arse (well, to me it is!). So, not knowing anything about the
> possibilities, a system that is as similar as possible to the way people
> would do it using something like LibreOffice or similar should be the
> most universally usable. Pretty much simple WYSIWYG.
>
> From the extremely brief look I've just taken at Asciidoc it's clearly
> not WYSIWYG? This may be ok for those who're used to cli/cryptic
> methodologies, but that certainly isn't everyone, and it doesn't make it
> easy (setting aside the 'purety' argument :-). People who may be good at
> writing clear documentation may not be coders, and could be well put off
> by the need to do so simply in order to present their writing. So, if
> there's an intent to encourage input from others I don't see this sort
> of thing to be the way forward.
>
> Of course I could have got a hold of completely the wrong end of the
> stick in which case feel free to ignore me, but if I search for 'online
> WYSIWYG editor' and 'wiki WYSIWYG editor' I get quite a few results.
> I've no experience with any of them, so can't provide any further
> insight at this point, but perhaps someone on this list will have, and
> could comment?
>
> As for offline docs - where it's significant my personal preference is
> usually for PDF because it retains the formatting that (usually) makes
> documents easier to read. Long plain text docs can be difficult given
> the absence of various visual cues to certain sections, and emphasis
> where useful etc. For shorter things text is fine, but that's not
> applicable to Guacamole IMV.
>
> Cheers, Luke.
>
> On 21/04/21 10:20 am, Mike Jumper 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
> >
>
Re: [DISCUSS] Migrate guacamole-manual away from DocBook?
Posted by Ivanmarcus <iv...@yahoo.com.INVALID>.
Good morning all,
Not sure I can contribute anything much on the two systems Mike's
mentioned, but I've some related comments, for what they're worth:
In general I've found the present documentation to be clearly written
and formatted well, albeit (as with all documentation) it takes a little
time to get used to the writer's intentions.
I think the presentation is much better than many other project docs
I've seen. Unless there was a compelling need or evidence to change the
presentation per se I suggest it'd be a positive if something similar to
the current output format could be retained.
From an input perspective, this may be at complete odds with what I've
just said, but almost everyone will know how to fundamentally edit text
documents, whereas understanding and hand-editing XML etc is simply an
arse (well, to me it is!). So, not knowing anything about the
possibilities, a system that is as similar as possible to the way people
would do it using something like LibreOffice or similar should be the
most universally usable. Pretty much simple WYSIWYG.
From the extremely brief look I've just taken at Asciidoc it's clearly
not WYSIWYG? This may be ok for those who're used to cli/cryptic
methodologies, but that certainly isn't everyone, and it doesn't make it
easy (setting aside the 'purety' argument :-). People who may be good at
writing clear documentation may not be coders, and could be well put off
by the need to do so simply in order to present their writing. So, if
there's an intent to encourage input from others I don't see this sort
of thing to be the way forward.
Of course I could have got a hold of completely the wrong end of the
stick in which case feel free to ignore me, but if I search for 'online
WYSIWYG editor' and 'wiki WYSIWYG editor' I get quite a few results.
I've no experience with any of them, so can't provide any further
insight at this point, but perhaps someone on this list will have, and
could comment?
As for offline docs - where it's significant my personal preference is
usually for PDF because it retains the formatting that (usually) makes
documents easier to read. Long plain text docs can be difficult given
the absence of various visual cues to certain sections, and emphasis
where useful etc. For shorter things text is fine, but that's not
applicable to Guacamole IMV.
Cheers, Luke.
On 21/04/21 10:20 am, Mike Jumper 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
>
Re: [DISCUSS] Migrate guacamole-manual away from DocBook?
Posted by Nick Couchman <vn...@apache.org>.
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 <ce...@gmail.com> 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 <vn...@apache.org> 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 <ce...@gmail.com>
> 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 <mj...@apache.org> 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
> >>
>
>
Re: [DISCUSS] Migrate guacamole-manual away from DocBook?
Posted by carl harris <ce...@gmail.com>.
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 <vn...@apache.org> 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 <ce...@gmail.com> 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 <mj...@apache.org> 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
>>
Re: [DISCUSS] Migrate guacamole-manual away from DocBook?
Posted by Nick Couchman <vn...@apache.org>.
+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 <ce...@gmail.com> 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 <mj...@apache.org> 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
>
Re: [DISCUSS] Migrate guacamole-manual away from DocBook?
Posted by carl harris <ce...@gmail.com>.
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 <mj...@apache.org> 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