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

[Rogan Creswick]

On Fri, Apr 5, 2013 at 10:12 AM, Petr Pudlák <petr.mvd at gmail.com> wrote:

>
> While I like the idea of allowing any markup language (let's say supported
> by Pandoc) and freedom it gives to developers, it also has also drawbacks:
> It makes contributing more difficult, if a project uses some wierd,
> non-standard markup language.
>
>
I feel pretty strongly about this; I don't think we gain much by allowing
arbitrary formats.  I think the same argument for coding conventions
applies here -- consistency is much more important for readability than
flexibility.

--Rogan


> Concerning math expressions, what about using Markdown with MathJAX, like
> math.stackexchange.com does?
>
>   Best regards,
>   Petr Pudlak
>
>
> 2013/4/5 Andrew Butterfield <Andrew.Butterfield at scss.tcd.ie>
>
>> I'm not proposing the LaTeX is used for hyperlinking the
>> reference  -  hence my comment about nicely integrating
>>
>> Perhaps a \begin{haddock} ... \end{haddock} environment* ?
>>
>> * This would only affect those using LaTeX/lhs - everyone else could
>> haddock** as usual
>>
>> ** haddock = whatever markdow/up/sideways scheme you guys come up with...
>>
>>
>> On 5 Apr 2013, at 16:22, Aleksey Khudyakov wrote:
>>
>> > On 5 April 2013 12:20, Andrew Butterfield
>> > <Andrew.Butterfield at scss.tcd.ie> wrote:
>> >>
>> >> On 4 Apr 2013, at 22:53, Aleksey Khudyakov wrote:
>> >>
>> >>> If we are going to change haddock syntax we should add ability to add
>> >>> math formulae to documentation. It's not currently possible and it
>> makes
>> >>> documenting numeric code properly difficult.
>> >>
>> >> How about support for .lhs files?
>> >> - both those with bird-tracks (which I don't use anymore)
>> >>   and \begin{code}...\end{code} (which I do use).
>> >>
>> >> My .lhs files are also LaTeX sources - I guess some way to nicely
>> integrate
>> >> haddock markup/down/whatever with LaTeX stuff would be needed
>> >>
>> > I'm not sure that it would help. If we to use haddock markup it need to
>> > support math typesetting. And LaTeX IMHO isn't right tool for creating
>> > hyperlinked API reference
>> >
>> > _______________________________________________
>> > Haskell-Cafe mailing list
>> > Haskell-Cafe at haskell.org
>> > http://www.haskell.org/mailman/listinfo/haskell-cafe
>>
>> --------------------------------------------------------------------
>> Andrew Butterfield     Tel: +353-1-896-2517     Fax: +353-1-677-2204
>> Lero at TCD, Head of Foundations & Methods Research Group
>> Director of Teaching and Learning - Undergraduate,
>> School of Computer Science and Statistics,
>> Room G.39, O'Reilly Institute, Trinity College, University of Dublin
>>                           http://www.scss.tcd.ie/Andrew.Butterfield/
>> --------------------------------------------------------------------
>>
>>
>> _______________________________________________
>> Haskell-Cafe mailing list
>> Haskell-Cafe at haskell.org
>> http://www.haskell.org/mailman/listinfo/haskell-cafe
>>
>
>
> _______________________________________________
> 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/68d87ecd/attachment.htm>