Sent from my iPhone
> On 6 Oct 2013, at 08:44, Stephen Connolly <stephen.alan.conno...@gmail.com> > wrote: > > > >> 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. https://github.com/asciidoctor/asciidoctor.js But I suspect that cross compiling ruby to JavaScript will not lead something that JavaScript developers will take up... I could be wrong, but I think a pure JavaScript impl using JavaScript API "conventions" would be needed. FWIW I think the same could be said for Java... But life is too short and personally I don't mind sucking in JRuby ;-) > >> >> * 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" <ja...@tesla.io> 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 <rfscho...@apache.org> 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 < >> > stephen.alan.conno...@gmail.com>: >> > > >> > >> 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: dev-unsubscr...@maven.apache.org >> > > For additional commands, e-mail: dev-h...@maven.apache.org >> > > >> > >> > Thanks, >> > >> > Jason >> > >> > ---------------------------------------------------------- >> > Jason van Zyl >> > Founder, Apache Maven >> > http://twitter.com/jvanzyl >> > --------------------------------------------------------- >> > >> > >> > >> > >> > >> > >> > >> > > > > -- > Sent from my phone
