Re: [DISCUSS] Converting site documentation to Markdown
Hi Jason Which sites are you talking about? Do you mean maven-site (the project site), the site for maven-core and/or all the other 100+ sites for all of our plugins and components? My view on documentation is that the person who takes the time to write the documentation gets to choose the format. As long as the format is one that can be used our current tooling (Maven Site Plugin). So I have no objections to adding new documentation in, for example, markdown. That being said it is good to have a preferred format, or a couple of them, that should be used. The format should fulfill the needs of the content as well as the author, which is why I think that we might need more than one format depending on the content. I have only looked at markdown briefly, but it looks like it doesn't support tables using textual markup, but rather relies on inserted html markup. Also you cannot mix markdown markup inside html markup. That might pose a problem for some of our pages on the project site that make heavy use of tables, like the index pages for plugins and shared components. Doing any kind of conversion requires good tooling, but it also requires lots of checking to make sure that the tooling has done what you think it should do. We have a lot of pages, which means a lot of before-and-after proof reading. Do we need to convert everything in one go? Or can we do it gradually? On Sat, Oct 5, 2013 at 5:19 PM, Jason van Zyl ja...@tesla.io 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 - -- Dennis Lundberg - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: [DISCUSS] Converting site documentation to Markdown
I'll also offer up a project I've been playing with in my free time: https://github.com/jdcasey/freeki/ Not sure if it's useful for anything per se, but maybe inspires some hacking. On 10/6/13 10:20 AM, Jason van Zyl wrote: Here's a pretty good list of tools. The other two I've tried are Marked (which is another MAC app), but I've also tried dillinger.io which is web-based editor and it's quite good. There are quite a few web-based tools that provide similar capabilities to Mou. http://mashable.com/2013/06/24/markdown-tools/ On Oct 5, 2013, at 11:19 AM, Jason van Zyl ja...@tesla.io 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 - Thanks, Jason -- Jason van Zyl Founder, Apache Maven http://twitter.com/jvanzyl - -- John Casey GitHub - http://github.com/jdcasey - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: [DISCUSS] Converting site documentation to Markdown
If I was choosing to write a technical book I would choose asciidoc. Agreed.. in fact asciidoc is the default markup tool at OReilly. I use it for all the books as Sonatype including Maven: The Complete Reference and Maven by Example.. AsciiDoc is the technically superior product that may well loose out to the more popular markdown. Maybe, maybe not. Asciidoc has gotten a lot of traction recently with the jruby/jvm port asciidoctor written by a mixed team of github and jboss/red hat developers. It includes a very good Maven plugin that can be used for site creation. 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) Correct. Github supports rendering .. actually using asciidoctor. http://asciidoctor.org/ From my PoV until there is a pure JavaScript implementation of an AsciiDoc parser/renderer it will not be able to win the war. There already is including a Chrome and Firefox plugins that can just render an asciidoc page in the browser. So you can basically just write your doc and refresh in the browser to see what it looks like. And you can combine it with livereload too.. I am fine with using markdown as well, but personally and if we want to go further than just providing the HTML rendering for the site.. we should choose asciidoc imho. manfred - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: [DISCUSS] Converting site documentation to Markdown
On Monday, 7 October 2013, Manfred Moser wrote: If I was choosing to write a technical book I would choose asciidoc. Agreed.. in fact asciidoc is the default markup tool at OReilly. I use it for all the books as Sonatype including Maven: The Complete Reference and Maven by Example.. AsciiDoc is the technically superior product that may well loose out to the more popular markdown. Maybe, maybe not. Asciidoc has gotten a lot of traction recently with the jruby/jvm port asciidoctor written by a mixed team of github and jboss/red hat developers. It includes a very good Maven plugin that can be used for site creation. For our content there will be virtually no difference between the two and Or to emphasise the point I was making that may have been lost, we can up-format trivially to asciidoc when the tooling catches up. The downside of asciidoc is there is more syntax to remember, not tones more, but still more than markdown 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) Correct. Github supports rendering .. actually using asciidoctor. http://asciidoctor.org/ I am well familiar with those, I would maintain that until there are *native* JavaScript (and Java but it's a lesser concern... JRuby is too good) as opposed to auto- ported code... It will not get the uptake it deserves. The auto-ported js lib (from ruby) is a good start, but a less platform idiomatic API will see poorer adoption... Similarly for Java from the CLI, starting JRuby is a performance hit... A smallish one, but a hit none the less, and CLI tools need fast like we need oxygen From my PoV until there is a pure JavaScript implementation of an AsciiDoc parser/renderer it will not be able to win the war. There already is including a Chrome and Firefox plugins that can just render an asciidoc page in the browser. So you can basically just write your doc and refresh in the browser to see what it looks like. And you can combine it with livereload too.. I am fine with using markdown as well, but personally and if we want to go further than just providing the HTML rendering for the site.. we should choose asciidoc imho. manfred - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org javascript:; For additional commands, e-mail: dev-h...@maven.apache.org javascript:; -- Sent from my phone
Re: [DISCUSS] Converting site documentation to Markdown
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. * *All* freestyle markup languages are ugly and hard to remember (I have to use TWiki/FosWiki and JIRA inhouse) * 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. 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 -
[DISCUSS] Converting site documentation to Markdown
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 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
Re: [DISCUSS] Converting site documentation to Markdown
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:
Re: [DISCUSS] Converting site documentation to Markdown
On Oct 6, 2013, at 3:13 AM, Mirko Friedenhagen mfriedenha...@gmail.com 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 not bad, per se. It's really about the prevalence of good editors. I don't much find the XSD/DTD of much benefit in contrast to editors like Mou where I have the raw content on the left, rendered content on the right, I can edit diagrams, reload and iterate. * *All* freestyle markup languages are ugly and hard to remember (I have to use TWiki/FosWiki and JIRA inhouse) * 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. 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 - Thanks, Jason -- Jason van Zyl Founder, Apache Maven http://twitter.com/jvanzyl -
Re: [DISCUSS] Converting site documentation to Markdown
2013/10/6 Stephen Connolly stephen.alan.conno...@gmail.com: IMHO Betamax == AsciiDoc VHS == MarkDown Being a bunch of old geezers, we all know which was technically superior. I had to teach my oldest kid how to operate a non-mobile phone the other day (she dialled number before lifting the handset) Kristian - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: [DISCUSS] Converting site documentation to Markdown
ok for the rationale Markdown seems to have been chosen in Apache CMS too [1] DOXIA-472 is a show stopper IMHO for the moment: I hope someone will fix it Stephen wrote about asciidoc, but it is not supported by Doxia at the moment [2], so not an option until someone adds this format to Doxia For conversion, if someone write a Markdown Sink, doxia-converter [3] is already available to convert any Doxia-parser-supported format to Doxia-sink- supported format. then can we share on the tools for editing? From the dicsussion, I understand that Mac users have Mou http://mouapp.com/, with side-by-side edit/render: really nice But I don't have a Mac. There are many online Markdown editors, but we need something local. Any good tool for Linux, ie my OS? Any experience with major IDEs: Eclipse, Netbeans, Idea? Notice I couldn't edit our Maven website Markdown content with CMS and any editor enhancement: does anybody know what is wrong with our content? Regards, Hervé [1] http://www.apache.org/dev/cms.html#markdown [2] http://maven.apache.org/doxia/references/index.html [3] http://maven.apache.org/doxia/doxia-tools/doxia-converter/ Le samedi 5 octobre 2013 11:19:01 Jason van Zyl a écrit : 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
Re: [DISCUSS] Converting site documentation to Markdown
FML is used in a few places, not only main sites [1] but plugins and components too [2] So perhaps FML will remain until we find some macro tooling. I prefer keeping FML than maintaing index by hand If we can replace apt and xdoc, that will already be a good step Regards, Hervé [1] http://maven.apache.org/doxia/faq.html [2] http://maven.apache.org/plugins/maven-site-plugin/faq.html Le samedi 5 octobre 2013 23:31:17 Jason van Zyl a écrit : 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 - - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: [DISCUSS] Converting site documentation to Markdown
Regarding automatic conversion to Markdown: The main ASF site was converted from xdoc to Markdown. Some tools werr written for this, but they were not 100% accurate; we were still finding conversion issues a year or so later. [We've probably not found them all yet] Whether these conversion issues are important is another matter, but there are certainly some area such as the license pages where it is vital that the conversion is accurate -- and problems were found there. AFAIR, Markdown still has some areas where it is weak - for example numeric lists, which was one of the license page issues. The existing HTML documentation is presumably all in SCM, so it should be possible to compare the new with the old if necessary. And if layout etc problems are detected later, the originals should be available. Might be worth creating tags for the source and generated HTML just before and after conversion to make it easier to dig into the history later. On 6 October 2013 10:13, Kristian Rosenvold kristian.rosenv...@gmail.com wrote: 2013/10/6 Stephen Connolly stephen.alan.conno...@gmail.com: IMHO Betamax == AsciiDoc VHS == MarkDown Being a bunch of old geezers, we all know which was technically superior. I had to teach my oldest kid how to operate a non-mobile phone the other day (she dialled number before lifting the handset) Kristian - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
RE: [DISCUSS] Converting site documentation to Markdown
Please remove me from mailing list Tanveer Ahmad Lecturer, School of Technology St Patricks International College 48 Carey Street New Court London WC2A 2JE United Kingdom www.st-patricks.ac.uk From: sebb seb...@gmail.com Sent: 06 October 2013 13:16 To: Maven Developers List Subject: Re: [DISCUSS] Converting site documentation to Markdown Regarding automatic conversion to Markdown: The main ASF site was converted from xdoc to Markdown. Some tools werr written for this, but they were not 100% accurate; we were still finding conversion issues a year or so later. [We've probably not found them all yet] Whether these conversion issues are important is another matter, but there are certainly some area such as the license pages where it is vital that the conversion is accurate -- and problems were found there. AFAIR, Markdown still has some areas where it is weak - for example numeric lists, which was one of the license page issues. The existing HTML documentation is presumably all in SCM, so it should be possible to compare the new with the old if necessary. And if layout etc problems are detected later, the originals should be available. Might be worth creating tags for the source and generated HTML just before and after conversion to make it easier to dig into the history later. On 6 October 2013 10:13, Kristian Rosenvold kristian.rosenv...@gmail.com wrote: 2013/10/6 Stephen Connolly stephen.alan.conno...@gmail.com: IMHO Betamax == AsciiDoc VHS == MarkDown Being a bunch of old geezers, we all know which was technically superior. I had to teach my oldest kid how to operate a non-mobile phone the other day (she dialled number before lifting the handset) Kristian - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: [DISCUSS] Converting site documentation to Markdown
Here's a pretty good list of tools. The other two I've tried are Marked (which is another MAC app), but I've also tried dillinger.io which is web-based editor and it's quite good. There are quite a few web-based tools that provide similar capabilities to Mou. http://mashable.com/2013/06/24/markdown-tools/ On Oct 5, 2013, at 11:19 AM, Jason van Zyl ja...@tesla.io 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 - Thanks, Jason -- Jason van Zyl Founder, Apache Maven http://twitter.com/jvanzyl -
Re: [DISCUSS] Converting site documentation to Markdown
There's a great comprehensive list at http://staticsitegenerators.net (btw, I've wrote the jbake-maven-plugin, for jbake - https://github.com/jonbullock/JBake) -- -- Aldrin Leal, ald...@leal.eng.br Master your EC2-fu! Get the latest ekaterminal public beta http://www.ingenieux.com.br/products/ekaterminal/ On Sun, Oct 6, 2013 at 12:20 PM, Jason van Zyl ja...@tesla.io wrote: Here's a pretty good list of tools. The other two I've tried are Marked (which is another MAC app), but I've also tried dillinger.io which is web-based editor and it's quite good. There are quite a few web-based tools that provide similar capabilities to Mou. http://mashable.com/2013/06/24/markdown-tools/ On Oct 5, 2013, at 11:19 AM, Jason van Zyl ja...@tesla.io 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 - Thanks, Jason -- Jason van Zyl Founder, Apache Maven http://twitter.com/jvanzyl -
[DISCUSS] Converting site documentation to Markdown
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 -
Re: [DISCUSS] Converting site documentation to Markdown
+10 for markdown and getting rid of old formats. Markdown is really easy, and as Jason says, tooling for editing it is really superb. Thanks, ~t~ (mobile) On Oct 5, 2013 5:19 PM, Jason van Zyl ja...@tesla.io 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 -
Re: [DISCUSS] Converting site documentation to Markdown
If we were to deprecate one or more documentation formats, wouldn't it make sense to make a plugin to automate the conversion ? After all, there's a few thousand sites out there that might want such a modernization ? Kristian 2013/10/5 Tamás Cservenák t.cserve...@gmail.com: +10 for markdown and getting rid of old formats. Markdown is really easy, and as Jason says, tooling for editing it is really superb. Thanks, ~t~ (mobile) On Oct 5, 2013 5:19 PM, Jason van Zyl ja...@tesla.io 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
Re: [DISCUSS] Converting site documentation to Markdown
Tools are already there, just read from one format and write to another using Doxia. I'm definitely not going to do it manually. On Oct 5, 2013, at 1:28 PM, Kristian Rosenvold kristian.rosenv...@gmail.com wrote: If we were to deprecate one or more documentation formats, wouldn't it make sense to make a plugin to automate the conversion ? After all, there's a few thousand sites out there that might want such a modernization ? Kristian 2013/10/5 Tamás Cservenák t.cserve...@gmail.com: +10 for markdown and getting rid of old formats. Markdown is really easy, and as Jason says, tooling for editing it is really superb. Thanks, ~t~ (mobile) On Oct 5, 2013 5:19 PM, Jason van Zyl ja...@tesla.io 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 -
Re: [DISCUSS] Converting site documentation to Markdown
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 - -- Sent from my phone
Re: [DISCUSS] Converting site documentation to Markdown
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
Re: [DISCUSS] Converting site documentation to Markdown
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 -
