On Sunday, 6 October 2013, Mirko Friedenhagen wrote: > Hello there, > > just my 2 cents: > > * I do not understand what is that bad about xdoc which is almost HTML. And > having a XSD/DTD code completion is available.
It's ugly (remember beauty is in the eye of the beholder) > > * *All* freestyle markup languages are ugly and hard to remember (I have to > use TWiki/FosWiki and JIRA inhouse) Markdown and asciidoc are not ugly. Markdown ends up looking almost the same as you'd format in plain text if you didn't have a markup language. Asciidoc is similar, it has the advantage of actually having a specification and a 1:1 bijection with docbook, however the full feature set if docbook can make it more ugly and you can need to look up some of the more obscure features. If I was choosing to write a technical book I would choose asciidoc. For smaller pages like what we have, markdown is perfect as you don't need the full docbook feature set... IMHO Betamax == AsciiDoc VHS == MarkDown AsciiDoc is the technically superior product that may well loose out to the more popular markdown. For our content there will be virtually no difference between the two and right now there are better editors for markdown (eg I like iaWriter on the mac/iPhone/iPad) and GitHub has editor support for markdown (afaik it supports rendering asciidoc but I don't think they have the same editor support for asciidoc) >From my PoV until there is a pure JavaScript implementation of an AsciiDoc parser/renderer it will not be able to win the war. > * So getting rid of APT looks like a good idea but to be consistent with > Wiki/JIRA of Maven I could imagine Confluence to be a better choice. Something like https://marketplace.atlassian.com/plugins/com.atlassian.plugins.confluence.markdown.confluence-markdown-macro Might be a better option :-) (Granted I might be thought biased towards markdown given my recent work on literate builds for Jenkins, but trust me, after writing a parser for extracting literate builds from markdown, asciidoc would be *much* better) > Regards Mirko > -- > Sent from my mobile > On Oct 6, 2013 5:31 AM, "Jason van Zyl" <[email protected]> wrote: > > > I'm not saying we tell people not to use it, but for us I don't think > it's > > an issue. It's been years since anything significant has been added to > our > > FAQ and they are few enough that they can be converted by hand to add a > > TOC. I just want to make working with our documentation a little more > > enjoyable and amenable to pull requests. > > > > On Oct 5, 2013, at 5:52 PM, Robert Scholte <[email protected]> wrote: > > > > > https://jira.codehaus.org/browse/DOXIA-472 ? No, still not fixed. > > > > > > IMHO the fml can only be replaced if there's a macro to generate an > > index of all the questions. > > > > > > Robert > > > > > > Op Sat, 05 Oct 2013 22:59:42 +0200 schreef Stephen Connolly < > > [email protected]>: > > > > > >> Has the page title problem been fixed? > > >> > > >> Last I checked you could not set the page title that Doxia generates > for > > >> HTML pages generated from markdown > > >> > > >> (Crosses fingers that it is fixed) > > >> > > >> On Saturday, 5 October 2013, Jason van Zyl wrote: > > >> > > >>> We current have multiple formats for our site documentation and two > of > > >>> them no one else in the world uses except us. We created xdoc here a > > long > > >>> time ago in the Jakarta project, and APT has lost in the world of > > markup. I > > >>> ported it from another project many years ago but there are many > better > > >>> options like asciidoc, restructured text, and markdown. My preference > > is > > >>> for markdown but I would like to get rid of xdoc, fml, and xdoc and > > convert > > >>> that documentation over to markdown. The tool support is great for > > editing, > > >>> book support is great (the Pro Git book is created from markdown). We > > can > > >>> still use all the Doxia tools for all the post processing. But I see > no > > >>> need to 4 different types of markup for the site, and honestly I find > > >>> working with APT now incredibly annoying. > > >>> > > >>> I'm happy to do the conversion and testing. > > >>> > > >>> Thanks, > > >>> > > >>> Jason > > >>> > > >>> ---------------------------------------------------------- > > >>> Jason van Zyl > > >>> Founder, Apache Maven > > >>> http://twitter.com/jvanzyl > > >>> --------------------------------------------------------- > > >>> > > >>> > > >>> > > >>> > > >>> > > >>> > > >>> > > >>> > > > > > > --------------------------------------------------------------------- > > > To unsubscribe, e-mail: [email protected] > > > For additional commands, e-mail: [email protected] > > > > > > > Thanks, > > > > Jason > > > > ---------------------------------------------------------- > > Jason van Zyl > > Founder, Apache Maven > > http://twitter.com/jvanzyl > > --------------------------------------------------------- > > > > > > > > > > > > > > > > > -- Sent from my phone
