Re: [Haskell-cafe] Re: Writing great documentation[MESSAGE NOT SCANNED]

I agree with Duncan's comment:

I rather like the idea of using markdown (pandoc) for separate non-reference docs like man pages, tutorials, user guides etc rather than trying to make haddock do everything.

In one of my projects (Hydra and Sigma), I use pandoc for the bulk of the documentation, and integrate this with haddock documentation for the parts of the documentation that haddock can do (which is a small part of it). This is all coordinated by a (rather clunky) Setup.hs. The whole thing isn't very elegant, but it works robustly on both Linux and Windows. That's a big advantage of pandoc: you can install it with cabal and use it in your Setup, so it isn't necessary to do any shell scripting, which can cause portability problems. I'll attach the Setup.hs file. One of the central issues here is *where* the documentation files go. I don't like the existing situation, where haddock documentation goes into a standard place, and presumably other documentation goes somewhere else. It's surely better to have all the documentation for a package in one directory, with all the parts linked together. So my setup makes a directory, builds the haddock and pandoc pieces of the documentation, copies (or build) it all into the directory, and then the contents of this directory is listed under data-files in the cabal file. The result is that building the system produces a complete self-contained directory and the executable application is able to find its own documentation files. This is usful in a GUI program, for example, where it's nice to make the documentation availble under the Help menu. Something along these lines (with a cleaner design) would be generally useful. John O'Donnell On 11/13/2009 10:31 PM, Duncan Coutts wrote:

On Fri, 2009-11-13 at 23:20 +0200, Max Rabkin wrote:

...

On Fri, Nov 13, 2009 at 10:58 PM, Simon Michael wrote:

...

A very common problem with online docs is fragmentation.

Absolutely! Is it possible to include non-haddock documentation in a cabal package. Is it possible to have it readable on Hackage?

Not yet.

Want to volunteer?

http://hackage.haskell.org/trac/hackage/ticket/330

It's partly a matter of tasteful design and partly implementation. The same person/people do not need to do both bits. Thrashing out a detailed and workable design would get us most of the way there.

...

I think this would help with the fragmentation and versioning issues.

Yes, I agree.

...

One option is to have haddock-only modules for non-reference documentation (xmonad-contrib does this), and I think at the moment it is a good option, but it does have disadvantages. It may not be clear from the outline where documentation can be found, and it clutters up the module namespace. Perhaps we could add support for a Documentation-Modules field in cabal files, which would separate these modules in the outline, and not install them but only their documentation.

I rather like the idea of using markdown (pandoc) for separate non-reference docs like man pages, tutorials, user guides etc rather than trying to make haddock do everything.

Duncan

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