[Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock

[Krzysztof Skrzętnicki]

I think this thread has went to became a quest for One True Markup
Language...

I would like to propose a different approach: while we are at extending
Haddock why not make it possible to choose from a set of different
documentation plugins? Something that works akin to the type: Text ->
Environment -> Documentation, where Documentation is Haddock AST (possibly
extended)?

That would make most people happy and put the source code writer in power:
they could choose the syntax they would like to write their docs. Whether
it is Haddock markup, Github Markdown, RST or OneTrueMarkup (c) (r)
(patented).

The task of defining such an API could be actually harder than writing
support for any particular syntax but I think it is more beneficiary in the
long run.

*Bonus points:* provide the integration with .cabal files so that each
package can inform which plugins it expects.
*Extra bonus points:* let the plugin be simply the name of a function (or
datatype that implements a typeclass) which in turn would be taken from a
well-defined scope. (think: library that can provide its own plugin for
documenting itself).

Best regards,
Krzysztof Skrzętnicki


On Fri, Apr 5, 2013 at 4:24 AM, Richard A. O'Keefe <ok at cs.otago.ac.nz>wrote:

>
> On 5/04/2013, at 2:00 PM, Johan Tibell wrote:
>
> >> Would it be too much to ask that a notation be used which has
> >> a formal syntax and a formal semantics?
> >
> > We will document our superset, sure. That's what others did as well.
> > The point is using Markdown as the shared base.
>
> Nononono.
> Sure, the others "documented" their supersets.
> But they did *NOT* provide what I am asking for:
>  - a FORMAL SYNTAX and
>  - a FORMAL SEMANTICS.
> I tried to use one of these systems, and found myself
> unable to determine which combinations of features were
> legal and what legal combinations of features *meant*.
> I corresponded with some people who had built markdown
> parsers, and the answer was the same each time: they had
> reversed engineered some other parser (typically a Perl
> one) and bashed on it until they were bug-compatible.
>
> If I want to get a particular effect in LaTeX or even in
> HTML+CSS, I can usually figure it out *without* having to
> run any program.  If I want to get a particular effect in
> Markdown, I flounder around and end up doing without.
>
> I am sick of "documentation" that vaguely hints at things,
> and I am especially sick of Markdown so-called documentation.
>
> To say it one more time:  I was unable to use the official
> Markdown documentation,
> http://daringfireball.net/projects/markdown/syntax,
> to guide the construction of a parser.
>
> For example, <br> is a valid URL enclosed in <. . .>, so
> is it a link, as the "Automatic Links" section would suggest,
> or is it embedded HTML, as the "Inline HTML" section would
> suggest?  Can you tell *from the documentation*?
>
> For another example, is *foo**bar**ugh* supposed to map to
> <em>foo<strong>bar</strong>ugh</em> or to
> <em>foo</em><em>bar</em><em>ugh</em>?
> Again, I'm not asking "what does this or that *program* do",
> I'm asking "can you tell from the documentation what they
> *ought* to do?"
>
> If there is an unambiguous specification of Markdown somewhere
> (specification; not program), I would be glad to see it.
>
>
>
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.haskell.org/pipermail/haskell-cafe/attachments/20130405/bbafec2e/attachment.htm>