On Mon, Sep 15, 2014 at 11:28:38AM -0700, Tikhon Jelvis wrote: | Maybe we could have a guerrilla campaign of pull requests adding examples | and a bit of explanation to every package you like that doesn't have | them... That could also be a good way for beginners who want to contribute | to start. I am a beginner, also coming from the Perl world of lovely synopses, and I would love to contribute in this fashion! I haven't started yet, but this is a great idea. Let it be said that Michael's packages are better documented than most, I've noticed. Amiri

I've had cases where some code I wanted to put in an example could not be expressed in haddock due to escaping rules. I would much rather be able to write a synopsis in markdown, or asciidoc, or HTML, rather than haddock markup.

On Monday, September 15, 2014, Tikhon Jelvis mailto:tikhon@jelv.is> wrote:

Genuinely curious: do you think a `Synopsis.md` would be that much easier than the current system with a potentially long description in

Hi all, Using Markdown would be a great idea. And, if Haddock were to support Markdown, and packages were migrated gradually to that, the inconsistency would disappear (eventually). IIRC, adding Markdown to Hadock was suggested on this list before, and the major argument against it was that Markdown didn't have a standard. Now, it has one, called CommonMark[1]. Barring any (further) copyright issues with the name, that looks to be a great step forward for Markdown. [1]: http://commonmark.org Regards, Jonathan Paugh On 09/15/2014 03:11 PM, Michael Snoyman wrote: the .cabal file? I could see a case either way. Or maybe I'm just misunderstanding the distinction.

On the one hand, a separate file makes organization easier and

markdown is a known quantity; on the other, it seems functionally equivalent to what we *can* do now albeit with Haddock syntax and in a file full of other details.

I could see why a file would be easier, and maybe that's enough to

encourage more people to write one. We could even have .cabal just render the existing README file or something! On the other hand, that would take some effort and sometimes using Haddock markup and sometimes using markdown would be confusing.

Maybe we could have a guerrilla campaign of pull requests adding

examples and a bit of explanation to every package you like that doesn't have them... That could also be a good way for beginners who want to contribute to start.

On Mon, Sep 15, 2014 at 10:40 AM, Michael Snoyman

javascript:_e(%7B%7D,'cvml','michael@snoyman.com');> wrote:

On Mon, Sep 15, 2014 at 8:38 PM, Richard Lewis

javascript:_e(%7B%7D,'cvml','richard@rjlewis.me.uk');> wrote:

Hi there,

If any of you have ever used CPAN you may agree with me that the synopsis sections customarily included in each package's POD are generally invaluable for getting a quick overview of how to use the facilities provided by that package.

I wonder if we might be able to encourage the Hackage community to do something similar? Perhaps in the cabal description authors could include a synopsis with a few code examples?

Obviously, I ought to start the ball rolling but I don't actually have any code published on Hackage.

Any thoughts?

Richard -- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Richard Lewis @lewisrichard http://web.rjlewis.me.uk/ -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org

javascript:_e(%7B%7D,'cvml','Haskell-Cafe@haskell.org');

http://www.haskell.org/mailman/listinfo/haskell-cafe

I'd love to see it work similar to the new changelog feature.

Imagine if you could add a `Synopsis.md` file to your cabal sdist, and Hackage rendered it to HTML and displayed it?

Michael

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org

javascript:_e(%7B%7D,'cvml','Haskell-Cafe@haskell.org');

http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

On 09/16/2014 12:22 AM, Brandon Allbery wrote:

On Mon, Sep 15, 2014 at 6:54 PM, Jonathan Paugh wrote:

...

IIRC, adding Markdown to Hadock was suggested on this list before, and the major argument against it was that Markdown didn't have a standard.

The biggest argument against it is that several Markdown conventions conflict with existing Haddock conventions, so you don't get to mix and match and you may have to specify which convention you're using. Note that a flag day to deprecate the old Haddock is not an option, unless you are offering to rewrite the haddocks of every existing package.

This part is actually only an implementation detail, the original idea was to have a {-# OPTIONS_HADDOCK Markdown #-} pragma. It would require we re-order how we deal with pragmas but this is not a good argument against. You would of course have problems if you tried to use older Haddock on a new, Markdown'd module but it could be mostly mitigated by co-ordinating with GHC release + talking with the Hackage folk to use a new version. -- Mateusz K.

On 09/15/2014 06:27 PM, Mateusz Kowalczyk wrote:

On 09/15/2014 11:54 PM, Jonathan Paugh wrote:

...

Hi all,

Using Markdown would be a great idea. And, if Haddock were to support Markdown, and packages were migrated gradually to that, the inconsistency would disappear (eventually).

IIRC, adding Markdown to Hadock was suggested on this list before, and the major argument against it was that Markdown didn't have a standard. Now, it has one, called CommonMark[1]. Barring any (further) copyright issues with the name, that looks to be a great step forward for Markdown.

[1]: http://commonmark.org

Regards, Jonathan Paugh

It was more than proposed, it was the original plan of my GSOC in 2013. In the end it went into a different direction because after actually hacking on Haddock I came to the conclusion that Markdown was actually not a good idea. You can find reasons in café archives I'm sure.

Okay, thanks for the correction & info.

There is also the question of who's going to maintain it. Now, that would be a bigger obstacle than any technical ones.

Also, there's the fact that CommonMark hasn't been vetted by the community at large, yet. In case it changes any, this might be a bad time to base a core Haskell component on it. (Aside from these obstacles, I'm all for it!)

We are severely understaffed. Haddock has only two maintainers, Simon Hengel and myself and Simon tends to be quite busy so it's mostly myself, and I also have about a billion projects I want to spend time on. I don't want to maintain another parser, there are more important things to hack. Honestly, it's sad that such a core project is so understaffed. Thanks for all your hard work!

Alas, complaining is not my main aim here. I simply want to point out that after some work, the Haddock parser and the required types now don't depend on GHC or any other libs that don't ship (bar for internal attoparsec dependency) with the compiler. This means that recent Pandoc now has both reader and writer modules for Haddock which means you can go Haddock <=> Markdown if you wish and get some results. I have not tried it myself however. Incidentally, implementing such reader/writer Pandoc modules was my initial submission in 2013.

In summary, if you really want to write Markdown instead of Haddock, use pandoc to convert between the two. I really wonder if the hassle is worth it though.

Regards, Jonathan Paugh

On Tue, Sep 16, 2014 at 2:36 AM, Mateusz Kowalczyk wrote:

On 09/15/2014 09:11 PM, Michael Snoyman wrote:

...

I've had cases where some code I wanted to put in an example could not be expressed in haddock due to escaping rules.

The parser has been improved and the escaping rules have been made saner. You shouldn't have real problems since 2.14 release which came out along with GHC 7.8.1. If you have problems with escaping then I'd like to hear about it on the issue tracker rather than stumbling upon complaints on café.

I ran into these issues over four years ago, discussed them at the time, and the general consensus I got at the time was that these issues weren't going to be resolved, so I didn't follow up. I've seen nothing in recent release announcements to imply otherwise. To test this out, I put together a simple demonstration of a Hamlet synopsis in Markdown[1], and then converted it via Pandoc to Haddock[2]. I copied that Haddock content into a cabal file's description, then indented it, ran cabal haddock, and got: cabal: hamlet.cabal:30: unexpected span: "!" For some reason, the trailing exclamation point is rejected by cabal. I tried removing the exclamation point, and it *did* generate content. However, all of the content was on the same line, because I needed to add periods between each block to deal with cabal's description parsing. After adding those periods, things *mostly* worked, except that my first code sample came out as: <p>Hi, my name is # Notice how the {name} portion has been stripped away. So I see a number of ways that this current situation for writing synopses is inferior: 1. Far more people are comfortable writing Markdown than writing Haddock, even those of us who write a lot of Haddock. Tooling support for editing Markdown is also superior. 2. Having the synopsis in a separate file means that it's easy to give a link to the file on Github and get readable docs, which is *not* the case with linking to a cabal file. 3. I don't have to go through any preprocess step to convert from Markdown to Haddock if that's the way I want to edit. 4. Putting the synopsis in the cabal file means we have to deal with cabal rules *in addition to* Haddock rules, such as the periods between blocks and not having an exclamation point at the end of the line[3]. 5. On top of all that, Haddock still can't handle the documentation I want to write for Hamlet, to demonstrate #{variable} interpolation. So again, I really like the idea of doing the same thing for synopses as we have already for changelogs. Michael [1] http://lpaste.net/111103 [2] http://lpaste.net/111104 [3] For the record, I was completely unaware of this limitation, and stumbled upon it by accident when putting together this example.

I think just about the only thing nowadays that might surprise people is that tokens stretch over newlines but this is by design, especially considering one can embed code.

...

I would much rather be able to write a synopsis in markdown, or asciidoc, or HTML, rather than haddock markup.

As I mention on the other e-mail, you can now use pandoc to achieve this. If people really care then it should not be difficult to co-ordinate with cabal + Hackage and make it parse your favourite format and splice it into synopsis.

I'd quite like the complaints about the existing Haddock markup, the rules are pretty damn close to what Markdown uses.

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

On Tue, Sep 16, 2014 at 7:24 AM, Ivan Lazar Miljenovic < ivan.miljenovic@gmail.com> wrote:

On 16 September 2014 14:13, Michael Snoyman wrote:

...

On Tue, Sep 16, 2014 at 2:36 AM, Mateusz Kowalczyk <

fuuzetsu@fuuzetsu.co.uk>

...

wrote:

...

On 09/15/2014 09:11 PM, Michael Snoyman wrote:

...

I've had cases where some code I wanted to put in an example could not be expressed in haddock due to escaping rules.

The parser has been improved and the escaping rules have been made saner. You shouldn't have real problems since 2.14 release which came out along with GHC 7.8.1. If you have problems with escaping then I'd like to hear about it on the issue tracker rather than stumbling upon complaints on café.

I ran into these issues over four years ago, discussed them at the time, and the general consensus I got at the time was that these issues weren't going to be resolved, so I didn't follow up. I've seen nothing in recent release announcements to imply otherwise. To test this out, I put together a simple demonstration of a Hamlet synopsis in Markdown[1], and then converted it via Pandoc to Haddock[2]. I copied that Haddock content into a cabal file's description, then indented it, ran cabal haddock, and got:

cabal: hamlet.cabal:30: unexpected span: "!"

For some reason, the trailing exclamation point is rejected by cabal. I tried removing the exclamation point, and it *did* generate content. However, all of the content was on the same line, because I needed to add periods between each block to deal with cabal's description parsing. After adding those periods, things *mostly* worked, except that my first code sample came out as:

<p>Hi, my name is #

Notice how the {name} portion has been stripped away. So I see a number of ways that this current situation for writing synopses is inferior:

1. Far more people are comfortable writing Markdown than writing Haddock, even those of us who write a lot of Haddock. Tooling support for editing Markdown is also superior. 2. Having the synopsis in a separate file means that it's easy to give a link to the file on Github and get readable docs, which is *not* the case with linking to a cabal file. 3. I don't have to go through any preprocess step to convert from Markdown to Haddock if that's the way I want to edit. 4. Putting the synopsis in the cabal file means we have to deal with cabal rules *in addition to* Haddock rules, such as the periods between blocks and not having an exclamation point at the end of the line[3]. 5. On top of all that, Haddock still can't handle the documentation I want to write for Hamlet, to demonstrate #{variable} interpolation.

So again, I really like the idea of doing the same thing for synopses as we have already for changelogs.

I would instead prefer to have a Github-esque README that might be displayed on Hackage pages, and keep the synopsis as a slightly longer version of the description. The description field is used by various Cabal-based package creation tools for various *nix distributions to provide a short blurb about what a package is, whereas the short guide as to how to use a package is better suited to a README.

I'm not implying that we should get rid of any existing functionality: cabal fields should remain exactly as they are now. I was proposing that, in addition, if a Synopsis.md file is present, that it be displayed on the Hackage page. But now that you bring up Github READMEs, that's clearly the right name for this proposal, so consider it amended: if a README or README.md file is present, that's what should be used. Michael

On 09/16/2014 05:13 AM, Michael Snoyman wrote:

On Tue, Sep 16, 2014 at 2:36 AM, Mateusz Kowalczyk wrote:

...

On 09/15/2014 09:11 PM, Michael Snoyman wrote:

...

I've had cases where some code I wanted to put in an example could not be expressed in haddock due to escaping rules.

The parser has been improved and the escaping rules have been made saner. You shouldn't have real problems since 2.14 release which came out along with GHC 7.8.1. If you have problems with escaping then I'd like to hear about it on the issue tracker rather than stumbling upon complaints on café.

I ran into these issues over four years ago, discussed them at the time, and the general consensus I got at the time was that these issues weren't going to be resolved, so I didn't follow up. I've seen nothing in recent release announcements to imply otherwise.

Really? [1] has quite a few things and I even made a visual guide to each change which was quite widely circulated. IIRC it was on main list, cafe, Planet Haskell, reddit, circulated on Twitter, posted in #haskell… My nginx says the post demonstrating the changes had ~3000 hits. I don't know what more I can do to make people aware of the releases.

To test this out, I put together a simple demonstration of a Hamlet synopsis in Markdown[1], and then converted it via Pandoc to Haddock[2]. I copied that Haddock content into a cabal file's description, then indented it, ran cabal haddock, and got:

cabal: hamlet.cabal:30: unexpected span: "!"

Cabal problem, no idea why it happens however, I have not looked into it.

For some reason, the trailing exclamation point is rejected by cabal. I tried removing the exclamation point, and it *did* generate content. However, all of the content was on the same line, because I needed to add periods between each block to deal with cabal's description parsing.

Also Cabal problem but you raise an important issue. Cabal's synopsis parsing sucks so if it could instead read from a separate file without these weird limitations, that'd be a big improvement in itself and a lot easier to automated if one wants to.

After adding those periods, things *mostly* worked, except that my first code sample came out as:

<p>Hi, my name is #

Notice how the {name} portion has been stripped away. So I see a number of ways that this current situation for writing synopses is inferior:

Maybe this is to do with Haddock issue #308 which was fixed in June and made it into 7.8.3 release. In fact, here[2] is the AST the parser (found in ‘haddock-library’ package which you can trivially install and try yourself) produces. This means I have to ask for your Haddock version. If you're on 7.8.2 or 7.8.3 you should be able to upgrade to 2.15.0 (that's right, we had another release since) simply by cabal install haddock which should demonstrate the correct behaviour. I'm surprised that you have a version without this fix unless you're stuck on 7.6.3 or something.

1. Far more people are comfortable writing Markdown than writing Haddock, even those of us who write a lot of Haddock. Tooling support for editing Markdown is also superior.

As usual, I point out that there are tens of different Markdown flavours. Of course today I will be pointed to the recent common Markdown creation but as far as I'm concerned, we had 14 standards and this is the 15th until it gets established. More importantly, Markdown is not suited for documenting code. We'd have to introduce new identifiers if we wanted to link to some functions from our synopsis. 16th standard aside, this is quickly starts looking like Haddock. I'm pretty sure that if you only used Haddock features that Markdown also has, you could tell someone your Haddock is a flavour of Markdown and they'd believe you. In any case, I'm not here to wage war against Markdown people but to find out why your Haddock experience is bad so let's move on. Bah, regarding tooling, with the parser now being in its own small package it's trivial to get out the AST for any snippet of text. If someone is eager then they can write emacs modes or whatever people use pretty easily now.

2. Having the synopsis in a separate file means that it's easy to give a link to the file on Github and get readable docs, which is *not* the case with linking to a cabal file.

I am not against this at all, I would quite like to see a separate file, it would make for much easier editing and you don't have to post-process anything spit out by tools to conform to additional cabal gotchas.

3. I don't have to go through any preprocess step to convert from Markdown to Haddock if that's the way I want to edit.

Seems like something cabal could handle for you if it sees pandoc on your system.

4. Putting the synopsis in the cabal file means we have to deal with cabal rules *in addition to* Haddock rules, such as the periods between blocks and not having an exclamation point at the end of the line[3].

Solved by your point 2.

5. On top of all that, Haddock still can't handle the documentation I want to write for Hamlet, to demonstrate #{variable} interpolation.

As the AST at [2] demonstrates, it can. Bah, just for you I used your pandoc-generated Haddock, stuck it in a module and produced the HTML file at [3]. It looks fine to me. We probably want to teach pandoc that it can put the anchors on the same line as the headers and that it can put content on the very next line from the header which would remove excessive spacing but other than that, it looks fine to me. Notably your #{name} problem is not present. [4] houses the Haskell file used to generate the HTML. Generated with Haddock HEAD but it only is 4 commits ahead of 2.15.0 release with the only changes being some documentation stuff.

So again, I really like the idea of doing the same thing for synopses as we have already for changelogs.

I also do, I am here merely to investigate why Markdown is so strongly preferred when Haddock does the job. Yes, the escaping was really bad in the past. Yes, it had some weird bugs. Yes, it has been fixed. To my knowledge, we have zero bugs open on the issue tracker[5]. There are some that are to do with GHC lexer + parser but those are not relevant at all here. If you know of bugs then please report them.

Michael

[1] http://lpaste.net/111103 [2] http://lpaste.net/111104 [3] For the record, I was completely unaware of this limitation, and stumbled upon it by accident when putting together this example.

...

I think just about the only thing nowadays that might surprise people is that tokens stretch over newlines but this is by design, especially considering one can embed code.

...

I would much rather be able tom write a synopsis in markdown, or asciidoc, or HTML, rather than haddock markup.

As I mention on the other e-mail, you can now use pandoc to achieve this. If people really care then it should not be difficult to co-ordinate with cabal + Hackage and make it parse your favourite format and splice it into synopsis.

I'd quite like the complaints about the existing Haddock markup, the rules are pretty damn close to what Markdown uses.

-- Mateusz K. _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

[1]: https://github.com/haskell/haddock/blob/master/CHANGES#L55 [2]: http://lpaste.net/111124 [3]: http://fuuzetsu.co.uk/misc/md/MarkdownToHaddock.html [4]: http://lpaste.net/111125 [5]: https://github.com/haskell/haddock/issues -- Mateusz K.

On 09/16/2014 06:04 PM, Michael Snoyman wrote:

On Tue, Sep 16, 2014 at 6:58 PM, Mateusz Kowalczyk wrote:

...

On 09/16/2014 05:13 AM, Michael Snoyman wrote:

...

So again, I really like the idea of doing the same thing for synopses as we have already for changelogs.

I also do, I am here merely to investigate why Markdown is so strongly preferred when Haddock does the job. Yes, the escaping was really bad in the past. Yes, it had some weird bugs. Yes, it has been fixed. To my knowledge, we have zero bugs open on the issue tracker[5]. There are some that are to do with GHC lexer + parser but those are not relevant at all here. If you know of bugs then please report them.

I don't think I can make my point any clearer. I demonstrated that the bug I brought up four years ago still exists,

…what? I just showed you that it no longer exists, linked to the source files used to generate it with your own input and linked to output. The bug was fixed, there's nothing more to it.

that a separate file makes more sense

Yes.

, that people are more familiar with markdown, that existing tools (editors and sites like Github) already have very solid Markdown support. You've used the same argument multiple times: Markdown has multiple flavors. I get it, you don't like Markdown. You made that clear. But many others- myself included- *do* like Markdown, and want to be able to use it. Your arguments don't convince me that my desires are invalid.

I don't neither dislike Markdown nor think your desires are invalid. I am only trying to understand what your problem with Haddock is. That's it. You say there's a bug, I show that it's fixed. What else is there? I only mention various Markdown flavours for a simple reason: it is to deter any potential ‘Haddock should just support Markdown’ posts, like seen early in this thread.

I'm not opposed to Hackage supporting multiple flavors of README files (much like Github does). But I really dislike someone saying "you shouldn't be able to edit in the file format that you like, because I have an objection to it." If you don't like Markdown, don't use it. But please don't tell me "Haddock markup is sufficient, you should use that." If you're hearing that "Markdown is so strongly preferred," maybe you should accept that people prefer Markdown.

No, again, I didn't say what you have to use and I even told you about a tool which can make it easy for you to write whatever you want in the existing system.

So my ideal is: Hackage chooses some Markdown implementation- I don't really care which too much- and adds support for README.md files. It can also add support for README.html, README.haddock, README.asciidoc, and README.klingon for all I care. If people run into problems because Github flavored Markdown is different than Hackage flavored Markdown... well, that's a situation that people using Markdown are used to already, and have come to terms with. I won't be put off by that. I already encounter that when I copy-paste something from a Stack Overflow answer into a Reddit comment. I can deal with it. People with objections to Markdown are perfectly free to use whatever syntax they want as well.

Michael

OK, great. I'd still like to hear about this bug you mention as the only thing you pointed out has been fixed in June. Lastly, who is going to implement all this stuff? It's easy to wish but I'm sure you have even less time than I do. -- Mateusz K.

On 09/16/2014 07:38 PM, Michael Snoyman wrote:

On Tue, Sep 16, 2014 at 8:16 PM, Mateusz Kowalczyk wrote:

...

On 09/16/2014 06:04 PM, Michael Snoyman wrote:

...

On Tue, Sep 16, 2014 at 6:58 PM, Mateusz Kowalczyk < fuuzetsu@fuuzetsu.co.uk> wrote:

...

On 09/16/2014 05:13 AM, Michael Snoyman wrote:

...

So again, I really like the idea of doing the same thing for synopses as we have already for changelogs.

I also do, I am here merely to investigate why Markdown is so strongly preferred when Haddock does the job. Yes, the escaping was really bad in the past. Yes, it had some weird bugs. Yes, it has been fixed. To my knowledge, we have zero bugs open on the issue tracker[5]. There are some that are to do with GHC lexer + parser but those are not relevant at all here. If you know of bugs then please report them.

I don't think I can make my point any clearer. I demonstrated that the bug I brought up four years ago still exists,

…what? I just showed you that it no longer exists, linked to the source files used to generate it with your own input and linked to output. The bug was fixed, there's nothing more to it.

I think you're discussing a strawman. The original proposal I made is "let's do Markdown in a separate file, because the current cabal + Haddock situation doesn't work." I demonstrated that. You're now saying that "it's not Haddock, it's cabal." That may be true, but it doesn't negate my point in the least: we could realize use an alternative, and the alternative I'd like is README.md.

OK, if that's what you want then that's fine. I am simply trying to clarify that it's not ‘let's use Markdown because Haddock can't do X, Y and Z’.

...

...

that a separate file makes more sense

Yes.

...

, that people are more familiar with markdown, that existing tools (editors and sites like Github) already have very solid Markdown support. You've used the same argument multiple times: Markdown has multiple flavors. I get it, you don't like Markdown. You made that clear. But many others- myself included- *do* like Markdown, and want to be able to use it. Your arguments don't convince me that my desires are invalid.

I don't neither dislike Markdown nor think your desires are invalid. I am only trying to understand what your problem with Haddock is. That's it. You say there's a bug, I show that it's fixed. What else is there?

I only mention various Markdown flavours for a simple reason: it is to deter any potential ‘Haddock should just support Markdown’ posts, like seen early in this thread.

It comes down to the fact that I like writing Markdown. Honestly, that's enough. As for the *reason* I like Markdown: it's because I'm __always__ writing Markdown. When I'm on Github's wiki or issue tracker, on Reddit, on Stack Overflow, on School of Haskell, or my blog. If you pay attention, even this email is Markdown-formatted. To my knowledge, Github does *not* support Haddock format, so I'd have to maintain both a README.md and README.haddock (part of the tooling issue I brought up).

Fair.

And on top of all that: I believe there are things that can be expressed in Markdown (via HTML blocks) that simply cannot be expressed in Haddock, such as tables. I could be mistaken on that point, however, can you clarify?

It is correct you can't include HTML for the same reason we don't allow embedding LaTeX: we want to be able to target multiple back-ends and it is unclear what to do with HTML when rendering as LaTeX and vice-versa. So you're correct that Haddock is not suited as a formatting tool for web pages, it's a code documentation tool. It does go the other way too by the way, Markdown won't let you link to modules, identifiers and all that, so Markdown is not suited for code documentation. It really depends what you're after I suppose.

...

...

I'm not opposed to Hackage supporting multiple flavors of README files (much like Github does). But I really dislike someone saying "you shouldn't be able to edit in the file format that you like, because I have an objection to it." If you don't like Markdown, don't use it. But please don't tell me "Haddock markup is sufficient, you should use that." If you're hearing that "Markdown is so strongly preferred," maybe you should accept that people prefer Markdown.

No, again, I didn't say what you have to use and I even told you about a tool which can make it easy for you to write whatever you want in the existing system.

That's a non-starter and a cop-out. Saying "Hackage will only support Haddock, but you can use Markdown and manually convert to Haddock and hope that the conversion is lossless" is just another way of saying "you have to use Haddock."

I specifically said ‘existing system’. If you *right now* wanted to be able to write your comments/synopsis in Markdown then you can, it's just not Hackage-native.

...

...

So my ideal is: Hackage chooses some Markdown implementation- I don't really care which too much- and adds support for README.md files. It can also add support for README.html, README.haddock, README.asciidoc, and README.klingon for all I care. If people run into problems because Github flavored Markdown is different than Hackage flavored Markdown... well, that's a situation that people using Markdown are used to already, and have come to terms with. I won't be put off by that. I already encounter that when I copy-paste something from a Stack Overflow answer into a Reddit comment. I can deal with it. People with objections to Markdown are perfectly free to use whatever syntax they want as well.

Michael

OK, great. I'd still like to hear about this bug you mention as the only thing you pointed out has been fixed in June.

Lastly, who is going to implement all this stuff? It's easy to wish but I'm sure you have even less time than I do.

That's a great question, but irrelevant to whether this is a good feature. I'd rather figure out the first than conflate it with the second.

Michael

OK, to summarise: * separate file for synopsis is a good idea * Currently Hackage only supports Haddock descriptions * Ideally Hackage should support more formats * You want to use Markdown as one of the formats because you like it rather than because Haddock has bugs which stop you from doing so. * The workaround to be able to use Markdown before this proposal is implemented is to use pandoc As long as there is no disagreement as to this summary, we are on the same page, I consider the previous exchange more of a miscommunication rather than disagreement. -- Mateusz K.

On Tue, Sep 16, 2014 at 1:04 PM, Michael Snoyman wrote:

I don't think I can make my point any clearer. I demonstrated that the bug I brought up four years ago still exists, that a separate file makes more sense, that people are more familiar with markdown, that existing tools (editors and sites like Github) already have very solid Markdown support. You've used the same argument multiple times: Markdown has multiple flavors. I get it, you don't like Markdown. You made that clear. But many others- myself included- *do* like Markdown, and want to be able to use it. Your arguments don't convince me that my desires are invalid.

I don;t see where you have, ever, even tried to address the concerns of incompatibility, including backward incompatibility. Should I assume that, since you have never had trouble with this (probably because you consider it a "bug" in haddock, the claim to said bug of course actually being that it ever existed in the first place --- if you actually think about the implications...), nobody else should ever have had such problems either? Basically, while you claim that Mateusz's entire argument is "he doesn't like Markdown", *your* entire argument boils down to "everyone but Me is wrong with a side helping of "whoever invented Haddock forgot to get My blessing first". Talking past each other in such way is not constructive. -- brandon s allbery kf8nh sine nomine associates allbery.b@gmail.com ballbery@sinenomine.net unix, openafs, kerberos, infrastructure, xmonad http://sinenomine.net

On 2014-09-16 17:58, Mateusz Kowalczyk wrote:

Also Cabal problem but you raise an important issue. Cabal's synopsis parsing sucks so if it could instead read from a separate file without these weird limitations, that'd be a big improvement in itself and a lot easier to automated if one wants to.

+1 Personally, I don't care whether it's markdown or Haddock(*), but having the ability to have the Description (and/or synopsis) in a separate file would be a definite improvement, IMO. The layering of the .cabal file format rules on top of the Haddock ones is weird and annoying in practice (extra indentation, a single . for empty lines, etc) and it would be good to be rid of those, at least. Regards, (*) Both equally misguided/flawed in my opinion, but whatevs. It's what people are using.

So there's clearly an important technical hurdle to be overcome for this: what markup language is to be used?; and where should the synposis be stored? But I can't help thinking that the real work is in getting the synopses written. Encouraging package authors/maintainers to add them to their own packages is one possible way forward. At Mon, 15 Sep 2014 11:28:38 -0700, Tikhon Jelvis wrote:

Maybe we could have a guerrilla campaign of pull requests adding examples and a bit of explanation to every package you like that doesn't have them... That could also be a good way for beginners who want to contribute to start.

Another, as Tikhon suggests, would be for others to write them and send pull requests (or whatever) to the maintainers. At Mon, 15 Sep 2014 20:10:18 -0400, Dominick Samperi wrote:

I think this is a great idea, but it probably needs a complementary "nudge" if it is going to have a significant impact. This could be incorporated into the package submission process where the submitter runs a final check and is warned when examples are not provided for exported functions (unless an "opt out" flag is turned on for functions that have "obvious" semantics).

And yet another, as Dominick suggests, is effectively to require a synposis when a package is submitted. In CPAN, it's just become part of the culture, but it's also not required and you do find packages without a synposis. If there's interest, I'd like to solicit some discussion on this part of the proposal on this thread... There may also be a potentially significant difference between Hackage/Haskell and CPAN/Perl: most CPAN packages tend to be quite small and specific in their purpose and consequently have just a few, simple common use cases which suit a synposis very well. Hackage packages, on the other hand, are quite often more broad in their scope, often comprising many modules. Also, Perl has only one semantics for organising code at the finest level: sequential, imperative statements. In Haskell, some packages actually define whole coding styles. As a result, it's always pretty obvious how to write a few isolated lines of Perl code, but not necessarily so with Haskell code. Anyway, I'm sure all this can be overcome, and/or argued against. Richard -- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Richard Lewis j: ironchicken@jabber.earth.li @: lewisrichard http://www.richardlewis.me.uk/ -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

For an example of this kind of policy see the R system. Here the final check issues warnings when exported functions are not documented. This strategy is not perfect as a submitter can always provide dummy docs that keep the checker quiet but do not provide much assistance to the end user. On the other hand, R functions tend to be documented well, and almost always include working examples in the help page that can be run from the command prompt via: help(function-name). On Tue, Sep 16, 2014 at 5:10 PM, Richard Lewis wrote:

So there's clearly an important technical hurdle to be overcome for this: what markup language is to be used?; and where should the synposis be stored?

But I can't help thinking that the real work is in getting the synopses written. Encouraging package authors/maintainers to add them to their own packages is one possible way forward.

At Mon, 15 Sep 2014 11:28:38 -0700, Tikhon Jelvis wrote:

...

Maybe we could have a guerrilla campaign of pull requests adding examples and a bit of explanation to every package you like that doesn't have them... That could also be a good way for beginners who want to contribute to start.

Another, as Tikhon suggests, would be for others to write them and send pull requests (or whatever) to the maintainers.

At Mon, 15 Sep 2014 20:10:18 -0400, Dominick Samperi wrote:

...

I think this is a great idea, but it probably needs a complementary "nudge" if it is going to have a significant impact. This could be incorporated into the package submission process where the submitter runs a final check and is warned when examples are not provided for exported functions (unless an "opt out" flag is turned on for functions that have "obvious" semantics).

And yet another, as Dominick suggests, is effectively to require a synposis when a package is submitted. In CPAN, it's just become part of the culture, but it's also not required and you do find packages without a synposis.

If there's interest, I'd like to solicit some discussion on this part of the proposal on this thread...

There may also be a potentially significant difference between Hackage/Haskell and CPAN/Perl: most CPAN packages tend to be quite small and specific in their purpose and consequently have just a few, simple common use cases which suit a synposis very well. Hackage packages, on the other hand, are quite often more broad in their scope, often comprising many modules. Also, Perl has only one semantics for organising code at the finest level: sequential, imperative statements. In Haskell, some packages actually define whole coding styles. As a result, it's always pretty obvious how to write a few isolated lines of Perl code, but not necessarily so with Haskell code. Anyway, I'm sure all this can be overcome, and/or argued against.

Richard -- -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Richard Lewis j: ironchicken@jabber.earth.li @: lewisrichard http://www.richardlewis.me.uk/ -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe