Matt Sicker updated LOG4J2-1802:
    Summary: Convert documentation into AsciiDoc  (was: Convert documentation 
into Markdown)

> Convert documentation into AsciiDoc
> -----------------------------------
>                 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
>            Priority: Major
> 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

Reply via email to