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 <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
