You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@crunch.apache.org by Matthias Friedrich <ma...@mafr.de> on 2012/07/11 20:22:37 UTC
Maven site markup language
Hi,
I set up the new Maven site using Markdown because we already had one
document in Markdown syntax. I think before we add more documentation
we should decide for a Doxia module [1] before it's too late :)
With Doxia we have the following alternatives:
XDoc is the old Maven 1 format that is still used by many Apache
projects. It uses XML which makes it a bit unpleasant to use,
especially for code examples.
APT is the main Maven 2 format. We use it extensively at work, but
it's the worst plain-text markup language I've ever used. You can get
used to it though and it works.
Markdown is pretty popular on Github. It has its weird corners and
the Doxia module seems pretty young. The error messages it generates
weren't very helpful to me and breadcrumbs are broken (do we need
them?).
Confluence/Textile has the advantage that you *might* be able to copy
and paste stuff from the wiki to the Maven site. I don't know how
well the module works.
So, which one do you want to use?
Regards,
Matthias
[1] http://maven.apache.org/doxia/modules/index.html
Re: Maven site markup language
Posted by Rahul <rs...@xebia.com>.
I would say Markdown could be the way forward. Apache is currently in
process of phasing out Confluence and adopting a new CMS
(/http://www.apache.org/dev/cms.html/) for wiki documentation which is
based on Markdown. Adopting markdown would have the plus of having the
maven site and the other documentation in the same format.
regards
Rahul
On 12-07-2012 05:07, Patrick Hunt wrote:
> I'd suggest something other than markdown, it's not rich enough, from
> zk discussion (we went with textile in the end on top of CMS):
>
> Ben Reed:
> "after deciding to go with markdown and converting the
> zooKeeperProgramming guide. i realize textile is the way to go. the
> problem is that the table support in markdown is non-existent as is
> the ability to create anchors for links in a document."
>
> https://issues.apache.org/jira/browse/ZOOKEEPER-925
>
> Patrick
>
> On Wed, Jul 11, 2012 at 11:28 AM, Josh Wills <jw...@cloudera.com> wrote:
>> I lean Markdown, primarily out of ignorance at this point. :) Does anyone
>> else have a strong opinion on this?
>>
>> On Wed, Jul 11, 2012 at 11:22 AM, Matthias Friedrich <ma...@mafr.de> wrote:
>>
>>> Hi,
>>>
>>> I set up the new Maven site using Markdown because we already had one
>>> document in Markdown syntax. I think before we add more documentation
>>> we should decide for a Doxia module [1] before it's too late :)
>>>
>>> With Doxia we have the following alternatives:
>>>
>>> XDoc is the old Maven 1 format that is still used by many Apache
>>> projects. It uses XML which makes it a bit unpleasant to use,
>>> especially for code examples.
>>>
>>> APT is the main Maven 2 format. We use it extensively at work, but
>>> it's the worst plain-text markup language I've ever used. You can get
>>> used to it though and it works.
>>>
>>> Markdown is pretty popular on Github. It has its weird corners and
>>> the Doxia module seems pretty young. The error messages it generates
>>> weren't very helpful to me and breadcrumbs are broken (do we need
>>> them?).
>>>
>>> Confluence/Textile has the advantage that you *might* be able to copy
>>> and paste stuff from the wiki to the Maven site. I don't know how
>>> well the module works.
>>>
>>> So, which one do you want to use?
>>>
>>> Regards,
>>> Matthias
>>>
>>> [1] http://maven.apache.org/doxia/modules/index.html
>>>
>>
>>
>> --
>> Director of Data Science
>> Cloudera <http://www.cloudera.com>
>> Twitter: @josh_wills <http://twitter.com/josh_wills>
Re: Maven site markup language
Posted by Patrick Hunt <ph...@apache.org>.
I'd suggest something other than markdown, it's not rich enough, from
zk discussion (we went with textile in the end on top of CMS):
Ben Reed:
"after deciding to go with markdown and converting the
zooKeeperProgramming guide. i realize textile is the way to go. the
problem is that the table support in markdown is non-existent as is
the ability to create anchors for links in a document."
https://issues.apache.org/jira/browse/ZOOKEEPER-925
Patrick
On Wed, Jul 11, 2012 at 11:28 AM, Josh Wills <jw...@cloudera.com> wrote:
> I lean Markdown, primarily out of ignorance at this point. :) Does anyone
> else have a strong opinion on this?
>
> On Wed, Jul 11, 2012 at 11:22 AM, Matthias Friedrich <ma...@mafr.de> wrote:
>
>> Hi,
>>
>> I set up the new Maven site using Markdown because we already had one
>> document in Markdown syntax. I think before we add more documentation
>> we should decide for a Doxia module [1] before it's too late :)
>>
>> With Doxia we have the following alternatives:
>>
>> XDoc is the old Maven 1 format that is still used by many Apache
>> projects. It uses XML which makes it a bit unpleasant to use,
>> especially for code examples.
>>
>> APT is the main Maven 2 format. We use it extensively at work, but
>> it's the worst plain-text markup language I've ever used. You can get
>> used to it though and it works.
>>
>> Markdown is pretty popular on Github. It has its weird corners and
>> the Doxia module seems pretty young. The error messages it generates
>> weren't very helpful to me and breadcrumbs are broken (do we need
>> them?).
>>
>> Confluence/Textile has the advantage that you *might* be able to copy
>> and paste stuff from the wiki to the Maven site. I don't know how
>> well the module works.
>>
>> So, which one do you want to use?
>>
>> Regards,
>> Matthias
>>
>> [1] http://maven.apache.org/doxia/modules/index.html
>>
>
>
>
> --
> Director of Data Science
> Cloudera <http://www.cloudera.com>
> Twitter: @josh_wills <http://twitter.com/josh_wills>
Re: Maven site markup language
Posted by Josh Wills <jw...@cloudera.com>.
I lean Markdown, primarily out of ignorance at this point. :) Does anyone
else have a strong opinion on this?
On Wed, Jul 11, 2012 at 11:22 AM, Matthias Friedrich <ma...@mafr.de> wrote:
> Hi,
>
> I set up the new Maven site using Markdown because we already had one
> document in Markdown syntax. I think before we add more documentation
> we should decide for a Doxia module [1] before it's too late :)
>
> With Doxia we have the following alternatives:
>
> XDoc is the old Maven 1 format that is still used by many Apache
> projects. It uses XML which makes it a bit unpleasant to use,
> especially for code examples.
>
> APT is the main Maven 2 format. We use it extensively at work, but
> it's the worst plain-text markup language I've ever used. You can get
> used to it though and it works.
>
> Markdown is pretty popular on Github. It has its weird corners and
> the Doxia module seems pretty young. The error messages it generates
> weren't very helpful to me and breadcrumbs are broken (do we need
> them?).
>
> Confluence/Textile has the advantage that you *might* be able to copy
> and paste stuff from the wiki to the Maven site. I don't know how
> well the module works.
>
> So, which one do you want to use?
>
> Regards,
> Matthias
>
> [1] http://maven.apache.org/doxia/modules/index.html
>
--
Director of Data Science
Cloudera <http://www.cloudera.com>
Twitter: @josh_wills <http://twitter.com/josh_wills>
Re: Maven site markup language
Posted by Vinod Kumar Vavilapalli <vi...@hortonworks.com>.
We've been using APT for Hadoop. It's very simple. The only limitation is the inability to do custom styling. Don't think that is a big requirement here.
Maven has moved beyond XDoc for various reasons. Not sure if we want to go back.
Don't know about Markdown. Breadcrumbs aren't needed, but build error messages should be good enough I think.
Confluence - the downside is the docs and site versioning which is very painful.
So, in summary, +1 for APT, it is simple and it works.
Thanks,
+Vinod
On Jul 11, 2012, at 11:22 AM, Matthias Friedrich wrote:
> Hi,
>
> I set up the new Maven site using Markdown because we already had one
> document in Markdown syntax. I think before we add more documentation
> we should decide for a Doxia module [1] before it's too late :)
>
> With Doxia we have the following alternatives:
>
> XDoc is the old Maven 1 format that is still used by many Apache
> projects. It uses XML which makes it a bit unpleasant to use,
> especially for code examples.
>
> APT is the main Maven 2 format. We use it extensively at work, but
> it's the worst plain-text markup language I've ever used. You can get
> used to it though and it works.
>
> Markdown is pretty popular on Github. It has its weird corners and
> the Doxia module seems pretty young. The error messages it generates
> weren't very helpful to me and breadcrumbs are broken (do we need
> them?).
>
> Confluence/Textile has the advantage that you *might* be able to copy
> and paste stuff from the wiki to the Maven site. I don't know how
> well the module works.
>
> So, which one do you want to use?
>
> Regards,
> Matthias
>
> [1] http://maven.apache.org/doxia/modules/index.html
Re: Maven site markup language
Posted by Josh Wills <jw...@cloudera.com>.
Yeah, we didn't quite reach consensus there. I wanted to investigate APT,
based on Vinod's positive referral and Pat's anti-Markdown stance, but I
wasn't locked in to it yet.
On Sun, Jul 15, 2012 at 2:23 AM, Matthias Friedrich <ma...@mafr.de> wrote:
> Hi,
>
> I think we successfully ruled out xdoc :)
>
> Other than that I'm not sure how to proceed. Maybe we should postpone
> the decision a bit and put new documentation on the wiki for now. The
> wiki is probably better suited for getting our docs off the ground
> anyway.
>
> Does the wiki require separate accounts/privileges? I can't seem to
> log in with my usual Apache credentials.
>
> Regards,
> Matthias
>
> On Wednesday, 2012-07-11, Matthias Friedrich wrote:
> > Hi,
> >
> > I set up the new Maven site using Markdown because we already had one
> > document in Markdown syntax. I think before we add more documentation
> > we should decide for a Doxia module [1] before it's too late :)
> >
> > With Doxia we have the following alternatives:
> >
> > XDoc is the old Maven 1 format that is still used by many Apache
> > projects. It uses XML which makes it a bit unpleasant to use,
> > especially for code examples.
> >
> > APT is the main Maven 2 format. We use it extensively at work, but
> > it's the worst plain-text markup language I've ever used. You can get
> > used to it though and it works.
> >
> > Markdown is pretty popular on Github. It has its weird corners and
> > the Doxia module seems pretty young. The error messages it generates
> > weren't very helpful to me and breadcrumbs are broken (do we need
> > them?).
> >
> > Confluence/Textile has the advantage that you *might* be able to copy
> > and paste stuff from the wiki to the Maven site. I don't know how
> > well the module works.
> >
> > So, which one do you want to use?
> >
> > Regards,
> > Matthias
> >
> > [1] http://maven.apache.org/doxia/modules/index.html
>
--
Director of Data Science
Cloudera <http://www.cloudera.com>
Twitter: @josh_wills <http://twitter.com/josh_wills>
Re: Maven site markup language
Posted by Matthias Friedrich <ma...@mafr.de>.
Hi,
I think we successfully ruled out xdoc :)
Other than that I'm not sure how to proceed. Maybe we should postpone
the decision a bit and put new documentation on the wiki for now. The
wiki is probably better suited for getting our docs off the ground
anyway.
Does the wiki require separate accounts/privileges? I can't seem to
log in with my usual Apache credentials.
Regards,
Matthias
On Wednesday, 2012-07-11, Matthias Friedrich wrote:
> Hi,
>
> I set up the new Maven site using Markdown because we already had one
> document in Markdown syntax. I think before we add more documentation
> we should decide for a Doxia module [1] before it's too late :)
>
> With Doxia we have the following alternatives:
>
> XDoc is the old Maven 1 format that is still used by many Apache
> projects. It uses XML which makes it a bit unpleasant to use,
> especially for code examples.
>
> APT is the main Maven 2 format. We use it extensively at work, but
> it's the worst plain-text markup language I've ever used. You can get
> used to it though and it works.
>
> Markdown is pretty popular on Github. It has its weird corners and
> the Doxia module seems pretty young. The error messages it generates
> weren't very helpful to me and breadcrumbs are broken (do we need
> them?).
>
> Confluence/Textile has the advantage that you *might* be able to copy
> and paste stuff from the wiki to the Maven site. I don't know how
> well the module works.
>
> So, which one do you want to use?
>
> Regards,
> Matthias
>
> [1] http://maven.apache.org/doxia/modules/index.html