[jira] [Commented] (GUACAMOLE-1347) Migrate guacamole-manual away from DocBook

["Mike Jumper (Jira)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/GUACAMOLE-1347?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17344229#comment-17344229 ] 

Mike Jumper commented on GUACAMOLE-1347:
----------------------------------------

After giving this a shot with AsciiDoc and finding the markup too opaque, I retried things with Sphinx and reStructuredText. That approach seems better, but I then ran into limitations of the reStructuredText format, such as the inability to nest inline formatting or to include formatting in the text of a link.

An alternative parser for Sphinx, called "MyST", offers a flavor of Markdown with additional syntax for the parts of reStructuredText not otherwise represented. After converting around a third of the documentation to this format, things seem clean and are working well.

https://myst-parser.readthedocs.io/en/latest/

> Migrate guacamole-manual away from DocBook
> ------------------------------------------
>
>                 Key: GUACAMOLE-1347
>                 URL: https://issues.apache.org/jira/browse/GUACAMOLE-1347
>             Project: Guacamole
>          Issue Type: Task
>          Components: Documentation
>            Reporter: Mike Jumper
>            Assignee: Mike Jumper
>            Priority: Major
>
> In the interest of making the Guacamole documentation more approachable for contributors, the format of guacamole-manual should be migrated away from DocBook XML to a mainstream markup format that is closer to simply editing text (such as AsciiDoc, reStructuredText, or Markdown).
> See discussion on dev@: https://lists.apache.org/thread.html/r4be1d606d2d2209d08f4a0b89c978cff18b75a33685c5f4e126cc8bf%40%3Cdev.guacamole.apache.org%3E



--
This message was sent by Atlassian Jira
(v8.3.4#803005)