Mailing-List: contact crunch-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: crunch-dev@incubator.apache.org
Received-SPF: neutral (nike.apache.org: local policy)
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Apple Message framework v1278)
Subject: Re: Maven site markup language
From: Vinod Kumar Vavilapalli <vinodkv@hortonworks.com>
In-Reply-To: <20120711182237.GA13918@mafr.de>
Date: Wed, 11 Jul 2012 11:45:16 -0700
Content-Transfer-Encoding: quoted-printable
Message-Id: <7EBDFAF6-6BCB-4401-B618-249A4E81A1AC@apache.com>
References: <20120711182237.GA13918@mafr.de>
To: crunch-dev@incubator.apache.org


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,
>=20
> 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 :)
>=20
> With Doxia we have the following alternatives:
>=20
> 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.
>=20
> 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.
>=20
> 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?).
>=20
> 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.
>=20
> So, which one do you want to use?
>=20
> Regards,
> Matthias
>=20
> [1] http://maven.apache.org/doxia/modules/index.html