[
https://issues.apache.org/jira/browse/DISPATCH-399?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15346614#comment-15346614
]
ASF subversion and git services commented on DISPATCH-399:
----------------------------------------------------------
Commit 3f7aa499633e4b4e8e34eaa63f54672060113ea8 in qpid-dispatch's branch
refs/heads/master from [~aconway]
[ https://git-wip-us.apache.org/repos/asf?p=qpid-dispatch.git;h=3f7aa49 ]
DISPATCH-399: Converted documentation to asciidoc format.
Converted .rst documentation files to asciidoc .adoc format.
asciidoc format is becoming more popular for documentation and has several
advantages over RST + sphinx.
- Mature, widely-used DocBook model without painful XML syntax
- Popular with doc writers (coming from docbook) and developers (e.g. github
support)
- Fully-featured for serious documentation without needing extensions, unlike
markdown.
- Standard support for multi-file documents and entity substitution
- Sphinx has non-standard extensions for this, but they are not part of RST.
- Tools are simpler to use, need less configuration than sphinx.
Conversion from RST to asciidoc was straightforward (used pandoc). Most of the
work was tweaking the doc generators and CMake.
> Convert documentation to asciidoc format
> ----------------------------------------
>
> Key: DISPATCH-399
> URL: https://issues.apache.org/jira/browse/DISPATCH-399
> Project: Qpid Dispatch
> Issue Type: Improvement
> Components: Documentation
> Affects Versions: 0.6.0
> Reporter: Alan Conway
> Assignee: Alan Conway
> Priority: Minor
>
> asciidoc format is becoming more popular for documentation and has several
> advantages over RST + sphinx.
> - Mature, widely-used DocBook model without painful XML syntax
> - Multi-file documents and entity substitution are standard in asciidoc
> (Sphinx has non-standard extensions, but not defined by RST)
> - simpler, more flexible tools, fewer generation steps.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@qpid.apache.org
For additional commands, e-mail: dev-h...@qpid.apache.org
