Ben Rudiak-Gould writes:

...

Doing a reasonable job on System.FilePath, even if it isn't perfect, will help prevent lots of applications from falling into common traps, and help make more code portable.

But the library code itself falls into the same traps! It's a great example of the kind of code we should be trying to replace!

If problems are in the implementation but the interface is right, then the module should be provided. It can be fixed later. It's a bigger problem if the design is bad.

2. It will never be possible to change the current weird behavior, because it might break legacy code.

It will be possible if the old behavior is considered a bug. I doubt that programs will make use of these bugs.

With respect to the old message you linked to: having an ADT for paths would not break any code,

I don't see an advantage of using an ADT here.

Right now each function has its own integrated parser, with slight differences in e.g. drive letter handling, and there are probably more bugs I didn't notice.

Well, they should be easy to fix as long as we precisely determine the intended semantics. -- __("< Marcin Kowalczyk \__/ qrczak@knm.org.pl ^^ http://qrnik.knm.org.pl/~qrczak/

Mark Carroll writes:

On Tue, 25 Jan 2005, Marcin 'Qrczak' Kowalczyk wrote: (snip)

...

If problems are in the implementation but the interface is right, then the module should be provided. It can be fixed later. (snip)

A lot of the Haskell libraries are sufficiently poorly documented that I work out what they do by experiment, or by resorting to reading the source.

There should be a wiki page or some other list for libraries that need documentation to be added to them. I would be happy to add documentation here & there. Anyone want to volunteer to create the page and list some libraries there? peace, isaac

"Georg Martius" writes:

Hi,

I think Isaac's idea is pretty nice, to have an easy way to add documentation in a collaborative manner. I have the following in mind:

Well, I've added a much less glorious page than yours on the wiki: http://www.haskell.org/hawiki/LibraryDocsNeedingHelp Click "edit text" and add as much information as possible about the shortcommings of the library documentation you run across. Extra points for patches posted to libraries@haskell.org. It would be nice if there were an easy way to link all the documentation together or allow people to add collaborative documentation hooks to CVS or something, but for now, a low-tech solution will have to do. peace, isaac

Peter Simons writes:

Isaac Jones writes:

...

http://www.haskell.org/hawiki/LibraryDocsNeedingHelp

This is a great idea.

I have been thinking .... you know what would make contribution to the library efforts even simpler? If they were available in a Darcs repository.

I can certainly understand Simon's wish to stay away from a split repository, one for GHC, one for libraries. What I'm doing for the cabal is keeping the _darcs directory in the same place as the CVS directory, and keeping them in sync by hand. This isn't too painful, if it were, I think there are some tools out there for this. Someone else suggested that someone maintain a darcs repository for the libraries and pull in documentatin changes, and then sync it all at once. I think that's a bad idea, because merging is never very easy, and is error prone. What might be good is if someone with CVS access would keep a darcs mirror of all of fptools (or just the libraries), and keep the darcs side automatically in sync w/ the CVS side (there are some tools for this). Then people could send darcs patches to this poor soul who would be sure to review them before committing them to CVS. I doubt that there would be too much traffic to handle, and if there were, then we could possibly put different people in charge of different components. Eventually, of course, everyone will realize that life would be simpler if we got rid of CVS altogether, and darcs will be mature enough to handle GHC, and we'll switch :)

Saying "darcs push" after you've spontaneously added a ^---- Probably "darcs send" if we're talking about letting the masses add documentation.

peace, isaac

Georg Martius wrote:

Hi,

I think Isaac's idea is pretty nice, to have an easy way to add documentation in a collaborative manner. I have the following in mind: A separate wiki which supports generating haddock documentation. Ideally one would see the haddock documentation as it is and would click to a function or type and change the comment for it. However, it would also be enough to see the complete source-code and change the comments there. The question is what happens if there is a parse error. Furthermore there must be someone who maintains it in the sense that changes are committed to cvs at some point and so on. Additionally, it seams to be complicated to keep it synchronised with "real" changes of the source code in the cvs. Probably the most simple, but less "wiki" solution is the do it the traditional way. Just use cvs and a normal text editor and ask for a cvs account :-).

Or, you could set the website to check out the code from CVS and use tex2html (assuming the comments are put in literate programming style) to generate the page. Keean.

On Tue, 2005-01-25 at 19:12 +0000, Ben Rudiak-Gould wrote:

My concern here is that someone will actually use the library once it ships, with the following consequences:

1. Programs using the library will have predictable (exploitable) bugs in pathname handling.

2. It will never be possible to change the current weird behavior, because it might break legacy code. The System.FilePath library will have to remain in GHC forever in its current form, enticing programmers with its promise of easy pathname handling and then cruelly breaking its contract.

If no one uses it in production code then we can fix it at our leisure, and having it out there with "experimental" status isn't necessarily a bad thing in that case. It just feels like we're playing a dangerous game.

That's a sufficiently persuasive argument for me! Could we just punt this library for this release. After all we can add libraries in a later point release (eg 6.4.1) you just can't change existing APIs. Hopefully if we leave it, the current discussion about designing some sane and portable file path functions will result in a reasonable replacement library. Duncan