[ 
https://issues.apache.org/jira/browse/LOG4J2-1802?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
 ]

Matt Sicker updated LOG4J2-1802:
--------------------------------
    Description: 
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.

After experimenting with Markdown as an alternative to xdoc, it has not been 
powerful enough for our uses. AsciiDoc, however, does offer more features 
useful here without extending the markdown processor itself. This will also 
help unify documentation formats used in other Log4j projects.

  was:
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.


> 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.
> After experimenting with Markdown as an alternative to xdoc, it has not been 
> powerful enough for our uses. AsciiDoc, however, does offer more features 
> useful here without extending the markdown processor itself. This will also 
> help unify documentation formats used in other Log4j projects.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

Reply via email to