[
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)
