Superset of Haddock and Markdown

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

Superset of Haddock and Markdown

Johan Tibell-2
Hi all,

I spent some time today documenting a library and the experience left me wanting a better markup language. In particular, Haddock lacks:

 * markup for bold text: bold text works better than italics for emphasis on computer monitors.
 * hyperlinks with anchor texts: having the actual URL rendered inline with text hurts readability.

Could Haddock markup be extended to also include some Markdown features? The new features could be hidden behind a flag so old documentation doesn't get unwanted markup (e.g. if it uses *...* to not mean bold).

P.S. This good make a good weekend hack that shouldn't be too difficult.

-- Johan


_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Ivan Lazar Miljenovic
On 18 November 2011 16:09, Johan Tibell <[hidden email]> wrote:
> Hi all,
> I spent some time today documenting a library and the experience left me
> wanting a better markup language. In particular, Haddock lacks:
>  * markup for bold text: bold text works better than italics for emphasis on
> computer monitors.

Even for the italics offered by /.../ would ideally be replaced, as
too often people (including myself) forget to escape paths or when
listing alternatives (e.g. foo/bar), leading to borked documentation.

>  * hyperlinks with anchor texts: having the actual URL rendered inline with
> text hurts readability.
> Could Haddock markup be extended to also include some Markdown features? The
> new features could be hidden behind a flag so old documentation doesn't get
> unwanted markup (e.g. if it uses *...* to not mean bold).

Wasn't there talk at one stage of integrating pandoc into haddock?

--
Ivan Lazar Miljenovic
[hidden email]
IvanMiljenovic.wordpress.com

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Roman Cheplyaka-2
In reply to this post by Johan Tibell-2
* Johan Tibell <[hidden email]> [2011-11-17 21:09:15-0800]

> Hi all,
>
> I spent some time today documenting a library and the experience left me
> wanting a better markup language. In particular, Haddock lacks:
>
>  * markup for bold text: bold text works better than italics for emphasis
> on computer monitors.
>  * hyperlinks with anchor texts: having the actual URL rendered inline with
> text hurts readability.
>
> Could Haddock markup be extended to also include some Markdown features?
> The new features could be hidden behind a flag so old documentation doesn't
> get unwanted markup (e.g. if it uses *...* to not mean bold).
>
> P.S. This good make a good weekend hack that shouldn't be too difficult.

Sounds awesome!

Maybe have a switch that enables markdown and disables markup-related
features of haddock (everything except linking to identifiers/modules, I
believe), so that we don't affect existing docs. Then make it possible
to pass this flag through cabal.

--
Roman I. Cheplyaka :: http://ro-che.info/

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Ivan Lazar Miljenovic
On 18 November 2011 19:06, Roman Cheplyaka <[hidden email]> wrote:
>
> Maybe have a switch that enables markdown and disables markup-related
> features of haddock (everything except linking to identifiers/modules, I
> believe), so that we don't affect existing docs. Then make it possible
> to pass this flag through cabal.

As in have an opt-in Cabal field?

--
Ivan Lazar Miljenovic
[hidden email]
IvanMiljenovic.wordpress.com

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Ertugrul Söylemez
In reply to this post by Ivan Lazar Miljenovic
Ivan Lazar Miljenovic <[hidden email]> wrote:

> Wasn't there talk at one stage of integrating pandoc into haddock?

I wouldn't mind Haddock depending on Pandoc, at least optionally
(-fmarkdown-comments).  Taking this to its conclusion you could easily
have syntax-highlighted code examples in Haddock documentations and
allow alternative output formats.


Greets,
Ertugrul


--
nightmare = unsafePerformIO (getWrongWife >>= sex)
http://ertes.de/



_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Twan van Laarhoven
In reply to this post by Ivan Lazar Miljenovic
On 18/11/11 09:18, Ivan Lazar Miljenovic wrote:
> On 18 November 2011 19:06, Roman Cheplyaka<[hidden email]>  wrote:
>>
>> Maybe have a switch that enables markdown and disables markup-related
>> features of haddock (everything except linking to identifiers/modules, I
>> believe), so that we don't affect existing docs. Then make it possible
>> to pass this flag through cabal.
>
> As in have an opt-in Cabal field?

For a cabal field, we could just have haddock be the default markup
language. Something like:

    DocMarkupLanguage: Haddock | Markdown | Plain | Html | ...
    -- default is Haddock

But before worrying about that, such a possibility should exist in haddock.


Twan

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

David Fox-7
In reply to this post by Ertugrul Söylemez
On Fri, Nov 18, 2011 at 1:10 AM, Ertugrul Soeylemez <[hidden email]> wrote:
> Ivan Lazar Miljenovic <[hidden email]> wrote:
>
>> Wasn't there talk at one stage of integrating pandoc into haddock?
>
> I wouldn't mind Haddock depending on Pandoc, at least optionally
> (-fmarkdown-comments).  Taking this to its conclusion you could easily
> have syntax-highlighted code examples in Haddock documentations and
> allow alternative output formats.

I'm not sure the pandoc license (GPL) is compatible with the GHC license.

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Ivan Lazar Miljenovic
On 21 November 2011 03:19, David Fox <[hidden email]> wrote:

> On Fri, Nov 18, 2011 at 1:10 AM, Ertugrul Soeylemez <[hidden email]> wrote:
>> Ivan Lazar Miljenovic <[hidden email]> wrote:
>>
>>> Wasn't there talk at one stage of integrating pandoc into haddock?
>>
>> I wouldn't mind Haddock depending on Pandoc, at least optionally
>> (-fmarkdown-comments).  Taking this to its conclusion you could easily
>> have syntax-highlighted code examples in Haddock documentations and
>> allow alternative output formats.
>
> I'm not sure the pandoc license (GPL) is compatible with the GHC license.

Do you mean because GHC ships with a Haddock binary?

--
Ivan Lazar Miljenovic
[hidden email]
IvanMiljenovic.wordpress.com

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Malcolm Wallace-2

On 20 Nov 2011, at 22:20, Ivan Lazar Miljenovic wrote:

> On 21 November 2011 03:19, David Fox <[hidden email]> wrote:
>> On Fri, Nov 18, 2011 at 1:10 AM, Ertugrul Soeylemez <[hidden email]> wrote:
>>> Ivan Lazar Miljenovic <[hidden email]> wrote:
>>>
>>>> Wasn't there talk at one stage of integrating pandoc into haddock?
>>>
>>> I wouldn't mind Haddock depending on Pandoc, at least optionally
>>> (-fmarkdown-comments).  Taking this to its conclusion you could easily
>>> have syntax-highlighted code examples in Haddock documentations and
>>> allow alternative output formats.
>>
>> I'm not sure the pandoc license (GPL) is compatible with the GHC license.
>
> Do you mean because GHC ships with a Haddock binary?

GHC also ships with a GPL'd gcc binary, on at least some platforms.

Regards,
    Malcolm

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

David Fox-7
In reply to this post by Ivan Lazar Miljenovic
On Sun, Nov 20, 2011 at 2:20 PM, Ivan Lazar Miljenovic
<[hidden email]> wrote:

> On 21 November 2011 03:19, David Fox <[hidden email]> wrote:
>> On Fri, Nov 18, 2011 at 1:10 AM, Ertugrul Soeylemez <[hidden email]> wrote:
>>> Ivan Lazar Miljenovic <[hidden email]> wrote:
>>>
>>>> Wasn't there talk at one stage of integrating pandoc into haddock?
>>>
>>> I wouldn't mind Haddock depending on Pandoc, at least optionally
>>> (-fmarkdown-comments).  Taking this to its conclusion you could easily
>>> have syntax-highlighted code examples in Haddock documentations and
>>> allow alternative output formats.
>>
>> I'm not sure the pandoc license (GPL) is compatible with the GHC license.
>
> Do you mean because GHC ships with a Haddock binary?
>

Haddock carries the same license as GHC.

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Brandon Allbery
On Mon, Nov 21, 2011 at 12:28, David Fox <[hidden email]> wrote:
On Sun, Nov 20, 2011 at 2:20 PM, Ivan Lazar Miljenovic
<[hidden email]> wrote:
> On 21 November 2011 03:19, David Fox <[hidden email]> wrote:
>> I'm not sure the pandoc license (GPL) is compatible with the GHC license.
> Do you mean because GHC ships with a Haddock binary?

Haddock carries the same license as GHC.

More to the point, Haddock uses ghc internals these days; it's not just a matter of bundling, and the licenses *must* be compatible.

--
brandon s allbery                                      [hidden email]
wandering unix systems administrator (available)     (412) 475-9364 vm/sms


_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Superset of Haddock and Markdown

Thomas Schilling-2
On 21 November 2011 17:34, Brandon Allbery <[hidden email]> wrote:
>> Haddock carries the same license as GHC.
>
> More to the point, Haddock uses ghc internals these days; it's not just a
> matter of bundling, and the licenses *must* be compatible.

No.  If the haddock library any program that links against that
library (e.g., the haddock program) effectively becomes GPL licensed
(roughly speaking).  However, ghc and none of the core libraries link
against haddock, so that's not a problem.  You could run into issues
if you wanted to write a closed-source program that links against the
haddock library.

I generally don't like GPL-licensed libraries for that reason, but in
this case I think it would be fine.

 (Of course, the issue is that many tools start out as programs and
then turn into libraries -- pandoc is a good example.  At that point
GPL becomes an issue again.)

--
Push the envelope. Watch it bend.

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe