[
https://issues.apache.org/jira/browse/LOG4J2-1802?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15980487#comment-15980487
]
Matt Sicker commented on LOG4J2-1802:
-------------------------------------
Remko has pointed out that [Asciidoctor|http://asciidoctor.org/] works pretty
well for this as well, plus it's also supported via Maven through JRuby. I'd be
willing to use asciidoc instead of markdown if we'd prefer that.
> Convert documentation into Markdown
> -----------------------------------
>
> Key: LOG4J2-1802
> URL: https://issues.apache.org/jira/browse/LOG4J2-1802
> Project: Log4j 2
> Issue Type: Documentation
> Components: Documentation
> Reporter: Matt Sicker
> Assignee: Matt Sicker
>
> The xdoc system currently in place is difficult to use correctly (it expects
> proper XHTML, no block level elements inside inline level elements, the usual
> pedantry from an XHTML/XML validator) and is needlessly verbose for writing
> documentation.
> The plugin we already use (maven-site-plugin) supports Markdown as an
> alternative (amongst others). Most text can be formatted as plain Markdown
> which simplifies the format a bit, plus anything complex can still be written
> in regular HTML (e.g., special tables). This will also allow for the
> documentation to be viewable on GitHub (at least for non-templated files) as
> seen in [this example
> page|https://github.com/apache/logging-log4j2/blob/master/src/site/markdown/build.md].
> I suggest using Markdown instead of something like Asciidoc as it's simpler
> to convert from xdoc and because I'm far more experienced with the syntax.
--
This message was sent by Atlassian JIRA
(v6.3.15#6346)
