[Haskell-cafe] Markdown extension for Haddock as a GSoC project

[Joe Nash]

On 28 Apr 2013 11:33, "Mateusz Kowalczyk" <fuuzetsu at fuuzetsu.co.uk> wrote:
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 28/04/13 00:08, Joe Nash wrote:
> > Managed not to send to all:
> >
> > I think the reason markdown was the original suggestion was due to
> > the fact it is a very widespread and popular syntax, and as Johan
> > commented in the original thread, has to an extent "won". Having a
> > consistent, standard documentation syntax for Haskell is of course
> > important, but this project also seeks to standardise the syntax
> > beyond Haskell.
> I don't think standardising it beyond Haskell is the goal at all. I
> think that coming up with Markdown that doesn't repeat the mistakes of
> all the flavours out there is quite difficult in itself, but coming up
> with such Markdown AND making it making it flexible enough to be of
> any use with Haddock as is? I think it might be a little out of scope.

I think my statement was a bit misleading there; I don't mean we should try
to come up with a markdown flavour that is suitable for the whole internet
to adopt as a standard, that is well beyond scope, as you sat. However,
using markdown, even if it has differences and additional peculiarities to
make it useful for haddock, is still to an extent bringing haddock in line
with the other markdown users and strengthening that standard. Even with
the differences there will be more similarities and it will be easier for
users to move between other markdown flavours and our flavour than others
and haddock syntax.

> Extending Haddock itself and providing a writer (and a new reader) for
> Pandoc will let you write Markdown if you please and then convert it
> to (and from) many of the formats supported by Pandoc.

I do really like this idea, and expressed interest in it to John, but it
adds additional complexity and dependencies for the documentation writer.
Encouraging the writing of more and better documentation means removing as
many barriers to doing so as possible, and having to run an additional
conversion step to write in a nice syntax may impede that. Having said
that, having to write in syntax you don't like also impedes that, so it may
in fact encourage the writing of more/better documentation.

>
> > It may be hedging our bets, as a lot could change and markdown
> > could suddenly fall from fame, but I believe the large variety of
> > opposing markup languages are failing to gain traction in
> > comparison and it is indeed a safe bet.
> While I don't think it will fall from fame overnight, it would be a
> shame to restrict people to just using Markdown because that's how all
> the extensions were implemented.
> >
> > If the flexibility of having it pandoc compatible is a desired
> > feature, can this not be achieved through implementing markdown for
> > haddock as well? Depending on what haddock specific features were
> > required to be added to the superset, it may require only minimal
> > changes to an existing markdown reader/writer in pandoc already.
> It can, but the restriction comment applies here as well.

Does it? If it is suitable to write in another markup and convert to
haddock with pandoc, why is it more restrictive to write in another markup
and convert to pandoc-markdown? Have I missed a point here?

I think these are starting to form two projects with tangential, but
slightly differing goals. It would be interesting to see the results if we
diverged here and a proposal was submitted for both ideas.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20130428/7ff8f0cb/attachment.htm>