RE: Idea to allow people to comment on Haskell docs
| I've had a go at patching Haddock to put a link on the page for each | module. It's controlled by an optional --wiki=URL flag. | | As an example, I used this with the (devel version of the) Gtk2Hs docs: | | http://haskell.org/gtk2hs/docs/devel/ | | For example this page: | | http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html It looks great! But I'd never have found the link if you hadn't pointed me at it. Rather than "Wiki" say "User comments". And I think the per-entry [User comment] link is essential. Typically people are going to be looking at a particular thing. For example, here http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html#v %3AsvgRenderFromString is where I'd look for the link for svgRenderFromString. Does MediaWiki support anchors in the middle of a page? That's essential here -- we want one Wiki page for one Haddock page. On a closely related matter, Benjamin Pierce told me how often he wished that there was a link from the Haddock documentation to the source code for a function. Especially for Prelude functions, he's dead right. So another really useful Haddock enhancement would be the ability to add links to the source code from the Haddock docs --- again on a per-function basis. Do you feel like adding that too? Where should the code live? I'd suggest snap-shoting it at the moment that the Haddock docs are generated, and putting the files with the Haddock docs. Simon
On Wednesday 18 January 2006 10:01, Simon Peyton-Jones wrote:
Does MediaWiki support anchors in the middle of a page? That's essential here -- we want one Wiki page for one Haddock page.
Yes. See, for example, the EPICS wiki at http://www.aps.anl.gov/epics/wiki/index.php/Main_Page. BTW, one of the most useful features of MediaWiki are the per-section edit command links at the right margin. If you select the edit link corresponding to a certain section, you'll get only the text of this section in the text-edit widget and when previewing your changes you'll see only the section you edited. (Of course you can also edit the whole page at once, using the top-most edit link.) Ben
I'm developing some libraries and want to set up the haddock docs with
comment wiki pages, as in this discussion thread. I see that the haddock
flags are there. Is anyone using them?
Any ideas on how to get the per-entity sectioning into a wiki page (==
myFnName ==). Or would we be better off having a page per entity?
I wonder how a library author or other interested person could track the
comments when there can be at least one wiki page per module (if not one per
entity). Any ideas? Can one "watch" a whole tree of wiki pages (including
ones that don't yet exist)?
- Conal
On 1/18/06, Benjamin Franksen
On Wednesday 18 January 2006 10:01, Simon Peyton-Jones wrote:
Does MediaWiki support anchors in the middle of a page? That's essential here -- we want one Wiki page for one Haddock page.
Yes. See, for example, the EPICS wiki at http://www.aps.anl.gov/epics/wiki/index.php/Main_Page.
BTW, one of the most useful features of MediaWiki are the per-section edit command links at the right margin. If you select the edit link corresponding to a certain section, you'll get only the text of this section in the text-edit widget and when previewing your changes you'll see only the section you edited. (Of course you can also edit the whole page at once, using the top-most edit link.)
Ben _______________________________________________ Libraries mailing list Libraries@haskell.org http://www.haskell.org/mailman/listinfo/libraries
On Wed, 2006-01-18 at 09:01 +0000, Simon Peyton-Jones wrote:
| I've had a go at patching Haddock to put a link on the page for each | module. It's controlled by an optional --wiki=URL flag. | | As an example, I used this with the (devel version of the) Gtk2Hs docs: | | http://haskell.org/gtk2hs/docs/devel/ | | For example this page: | | http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html
It looks great! But I'd never have found the link if you hadn't pointed me at it.
Rather than "Wiki" say "User comments".
Yes, that is better.
And I think the per-entry [User comment] link is essential. Typically people are going to be looking at a particular thing. For example, here
http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html#v %3AsvgRenderFromString is where I'd look for the link for svgRenderFromString.
Ok, I'll try that next. Where do you think that link should go within each entry?
Does MediaWiki support anchors in the middle of a page? That's essential here -- we want one Wiki page for one Haddock page.
Yes. Each header automatically adds an anchor of the same name. For example look at the definition page: http://haskell.org/haskellwiki/Definition There's a section with this markup: == Historic development of Haskell == Which produces this anchor: http://haskell.org/haskellwiki/Definition#Historic_development_of_Haskell
On a closely related matter, Benjamin Pierce told me how often he wished that there was a link from the Haddock documentation to the source code for a function. Especially for Prelude functions, he's dead right. So another really useful Haddock enhancement would be the ability to add links to the source code from the Haddock docs --- again on a per-function basis. Do you feel like adding that too? Where should the code live? I'd suggest snap-shoting it at the moment that the Haddock docs are generated, and putting the files with the Haddock docs.
I was thinking about that. It'd probably be a less difficult change to haddock to get it to link to the source code, rather than picking it up as it parses it. Haddock does know the file name of each .hs file since it's invoked with then on the command line. We can assume that the --source=URL points to the location where haddock was invoked from. This gives us the full url of each .hs file (I think). Then to deal with the use of pre-processors etc, haddock should pickup the {-# LINE ... #-} pragmas just like ghc does, so that it can discover the original file name. Duncan
On a closely related matter, Benjamin Pierce told me how often he wished that there was a link from the Haddock documentation to the source code for a function. Especially for Prelude functions, he's dead right. So another really useful Haddock enhancement would be the ability to add links to the source code from the Haddock docs --- again on a per-function basis. Do you feel like adding that too? Where should the code live? I'd suggest snap-shoting it at the moment that the Haddock docs are generated, and putting the files with the Haddock docs.
I was thinking about that. It'd probably be a less difficult change to haddock to get it to link to the source code, rather than picking it up as it parses it.
Haddock does know the file name of each .hs file since it's invoked with then on the command line. We can assume that the --source=URL points to the location where haddock was invoked from. This gives us the full url of each .hs file (I think). Then to deal with the use of pre-processors etc, haddock should pickup the {-# LINE ... #-} pragmas just like ghc does, so that it can discover the original file name.
I'd rather have the source code put into the html than linking to it. Say, by default it would be hidden, and shown by a click (javascript). This has the additional benefit that, in the future, one can add annotations to the source. For example, linking every function call to its definition. Cheers, JP.
On a closely related matter, Benjamin Pierce told me how often he wished that there was a link from the Haddock documentation to the source code for a function.
Yes, I think that would be a great feature-enhancement for Haddock.
Haddock does know the file name of each .hs file since it's invoked with them on the command line.
As a further enhancement, can I suggest converting the original .hs file to .html, using some kind of syntax colouring? The tool hscolour (see http://www.cs.york.ac.uk/fp/darcs/) can generate either font tags or CSS colouring. The main difficulty for Haddock would be to embed anchors into the generated html source. Regards, Malcolm
Duncan Coutts wrote:
On Wed, 2006-01-18 at 09:01 +0000, Simon Peyton-Jones wrote:
On a closely related matter, Benjamin Pierce told me how often he wished that there was a link from the Haddock documentation to the source code for a function. Especially for Prelude functions, he's dead right. So another really useful Haddock enhancement would be the ability to add links to the source code from the Haddock docs --- again on a per-function basis. Do you feel like adding that too? Where should the code live? I'd suggest snap-shoting it at the moment that the Haddock docs are generated, and putting the files with the Haddock docs.
I was thinking about that. It'd probably be a less difficult change to haddock to get it to link to the source code, rather than picking it up as it parses it.
Haddock does know the file name of each .hs file since it's invoked with then on the command line. We can assume that the --source=URL points to the location where haddock was invoked from. This gives us the full url of each .hs file (I think). Then to deal with the use of pre-processors etc, haddock should pickup the {-# LINE ... #-} pragmas just like ghc does, so that it can discover the original file name.
Picking up the LINE pragmas is the way to go, yes. The reason we don't get source links currently is because Haddock doesn't understand the LINE pragmas, so it can't find its way to the original source file for preprocessed files. Most of our library code is preprocessed one way or another, even if it's just literate. To get a per-function source code link, we'd need to turn the original source files into HTML in order to add anchors (using Malcolm's hscolour would be good too, and didn't the programmatica folks have a nice source code markup tool?). I don't think that inserting the source code directly in the Haddock-generated HTML would work too well, even if it is hidden by default, because many definitions will refer to auxiliary functions that aren't part of the visible interface. So there are now two per-entity links we need in Haddock: user comments and source code, and there might be more in the future (version history?). So I suggest we have a little row of icons at the far right of each entity's definition, with pop-up descriptions when you hover over them. Cheers, Simon
Hello Simon, Wednesday, January 18, 2006, 12:01:41 PM, you wrote: SPJ> On a closely related matter, Benjamin Pierce told me how often he wished SPJ> that there was a link from the Haddock documentation to the source code SPJ> for a function. Especially for Prelude functions, he's dead right. So SPJ> another really useful Haddock enhancement would be the ability to add SPJ> links to the source code from the Haddock docs --- again on a SPJ> per-function basis. Do you feel like adding that too? Where should SPJ> the code live? I'd suggest snap-shoting it at the moment that the SPJ> Haddock docs are generated, and putting the files with the Haddock docs. as i seen in Ruby documentation tool, the code is just html-ized with syntax colourimng and labels (#concat, #map and so on) added before each function definition. if path to this html-ized sources will be standard, then it can be used not only in this haddock, but for example in links from wiki, in some irc-related tools, in online Hugs/ghci help systems and so on -- Best regards, Bulat mailto:bulatz@HotPOP.com
On Wed, 2006-01-18 at 09:01 +0000, Simon Peyton-Jones wrote:
It looks great! But I'd never have found the link if you hadn't pointed me at it.
Rather than "Wiki" say "User comments".
Done.
And I think the per-entry [User comment] link is essential. Typically people are going to be looking at a particular thing. For example, here
http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html#v:svg... is where I'd look for the link for svgRenderFromString.
Done! So take another look at these example pages: http://haskell.org/gtk2hs/docs/devel/ http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html For the per-entry links, to conserve space I've just said [Comments] rather than [User Comments] and used a smaller font. These cosmetic things are easy to change if anyone complains. I've sent the haddock patches that implement this stuff to Simon Marlow, so if people are generally favourable of this iteration of the patch perhaps he'd like to apply it. :-) I hope I've done the changes in such a way that it should be straightforward to add source code links too if/when haddock is taught how to find the original source file for each module. So, opinions? Duncan
On Thu, 2006-01-19 at 21:55 +0000, Duncan Coutts wrote:
On Wed, 2006-01-18 at 09:01 +0000, Simon Peyton-Jones wrote:
It looks great! But I'd never have found the link if you hadn't pointed me at it.
Rather than "Wiki" say "User comments".
Done.
And I think the per-entry [User comment] link is essential. Typically people are going to be looking at a particular thing. For example, here
http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html#v:svg... is where I'd look for the link for svgRenderFromString.
Done!
So take another look at these example pages: http://haskell.org/gtk2hs/docs/devel/ http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html
For the per-entry links, to conserve space I've just said [Comments] rather than [User Comments] and used a smaller font. These cosmetic things are easy to change if anyone complains.
I've sent the haddock patches that implement this stuff to Simon Marlow, so if people are generally favourable of this iteration of the patch perhaps he'd like to apply it. :-) I hope I've done the changes in such a way that it should be straightforward to add source code links too if/when haddock is taught how to find the original source file for each module.
So, opinions?
I guess the question is if people will actually start commenting on functions. So I would vote for the addition to haddock and see what is happening. Maybe we need then need to gather statistics about what links are clicked most and check which ones of these are empty (and left the user frustrated). Axel.
On Fri, 2006-01-20 at 09:30 +0000, Axel Simon wrote:
On Thu, 2006-01-19 at 21:55 +0000, Duncan Coutts wrote:
So take another look at these example pages: http://haskell.org/gtk2hs/docs/devel/ http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html
For the per-entry links, to conserve space I've just said [Comments] rather than [User Comments] and used a smaller font. These cosmetic things are easy to change if anyone complains.
So, opinions?
I guess the question is if people will actually start commenting on functions. So I would vote for the addition to haddock and see what is happening. Maybe we need then need to gather statistics about what links are clicked most and check which ones of these are empty (and left the user frustrated).
Or we could change the text to "Contribute notes" rather than "User Comments" so that people are not disappointed when there are no existing notes! :-) (I think I'm joking, though I'm not entirely sure.) Duncan
Duncan Coutts
On Wed, 2006-01-18 at 09:01 +0000, Simon Peyton-Jones wrote:
It looks great! But I'd never have found the link if you hadn't pointed me at it.
Rather than "Wiki" say "User comments".
Done.
And I think the per-entry [User comment] link is essential. Typically people are going to be looking at a particular thing. For example, here
http://haskell.org/gtk2hs/docs/devel/Graphics-Rendering-Cairo-SVG.html#v:svg... is where I'd look for the link for svgRenderFromString.
Done!
I think this is quite cool, but there's one thing that concerns me. I fear that users will have the sense that these links are being monitored by the module authors and that if they make a comment like, "there's an error here" or "here's an enhancement" that someone is actually going to see it and modify the haddock. In reality, there's no real way to know whether anyone will ever read a comment. There will be far too many pages for anyone to monitor (unless someone is going to watch an RSS feed or something). This might actually deter people from modifying the haddock code directly and submitting patches, since they did their part by commenting on the function. I'd encourage you to consider how it might interact with the new trac ticket system also. Maybe there should be a "spot a bug" or "make a suggestion" link that creates a trac bug. peace, isaac
On 20/01/06, Isaac Jones
I fear that users will have the sense that these links are being monitored by the module authors and that if they make a comment like, "there's an error here" or "here's an enhancement" that someone is actually going to see it and modify the haddock. In reality, there's no real way to know whether anyone will ever read a comment. There will be far too many pages for anyone to monitor (unless someone is going to watch an RSS feed or something).
That may not be a bad idea.
On Fri, 2006-01-20 at 16:55 -0800, Isaac Jones wrote:
I think this is quite cool, but there's one thing that concerns me.
I fear that users will have the sense that these links are being monitored by the module authors and that if they make a comment like, "there's an error here" or "here's an enhancement" that someone is actually going to see it and modify the haddock. In reality, there's no real way to know whether anyone will ever read a comment. There will be far too many pages for anyone to monitor (unless someone is going to watch an RSS feed or something).
This might actually deter people from modifying the haddock code directly and submitting patches, since they did their part by commenting on the function.
I'd encourage you to consider how it might interact with the new trac ticket system also. Maybe there should be a "spot a bug" or "make a suggestion" link that creates a trac bug.
This is a good point. Let me suggest some possible technical solutions: It is possible to monitor a number of related wiki pages. Since all the module pages would be sub-pages of some existing page then by monitoring the root page for changes in its related pages one could see all changes in the sub pages. MediaWiki does also have some support for RSS. I've not looked into that in detail however. In addition a feature that we might be able to implement for the wiki is to have all the newly created sub pages of a library's root page contain some default text rather than starting off blank. That default text should mention the purpose of the page and where to go instead for reporting bugs. If that's too tricky to implement then perhaps one should just go and pre-create all the wiki pages for each module with the appropriate initial text. This would not be too much of a chore for most libraries which only expose a handful of modules. It'd take me a bit longer since Gtk2Hs has 100+ modules, but it's not intolerable. It can be made simpler by the use of a MediaWiki template that contains th text. Then the info can be written once and appear on each page (and if the template changes the other pages update automatically). Duncan
Isaac Jones
I'd encourage you to consider how it might interact with the new trac ticket system also. Maybe there should be a "spot a bug" or "make a suggestion" link that creates a trac bug.
Isaac, This seems to imply that the trac ticket system is available for all libraries. Is this true and if so how do I make use of it for the Crypto library? Thanks, Dominic.
Dominic Steinitz
Isaac Jones
writes: I'd encourage you to consider how it might interact with the new trac ticket system also. Maybe there should be a "spot a bug" or "make a suggestion" link that creates a trac bug.
Isaac,
This seems to imply that the trac ticket system is available for all libraries. Is this true and if so how do I make use of it for the Crypto library?
It's not available for everything yet, but we'd like to make it available for more projects somehow... If you have any ideas let us know. I'm only suggesting that we try to think of ways that these systems can work together so that users aren't frustrated by leaving messages that no one ends up reading. peace, isaac
participants (12)
-
Axel Simon -
Benjamin Franksen -
Bulat Ziganshin -
Conal Elliott -
Dominic Steinitz -
Duncan Coutts -
Isaac Jones -
Jean-Philippe Bernardy -
Malcolm Wallace -
Samuel Bronson -
Simon Marlow -
Simon Peyton-Jones