No fish, please

Andrew Coppin

12 May 2011 12 May '11

1:45 p.m.

Both Hackage and Cabal seem to assume as a matter of course that I want to use Haddock to generate all my documentation. Suppose I decide to violate this assumption. Then what? 1. Is there some way I can include my own HTML documentation in the package tarball and have Hackage/Cabal use it? 2. Is there a way to tell Hackage/Cabal to use some tool besides Haddock?

Show replies by date

Don Stewart

12 May 12 May

2 p.m.

No, you should be using Haddock. If you wish to generate docs some other way, you are free to host that on your own site, and link to it from the Hackage page. On Thu, May 12, 2011 at 10:45 AM, Andrew Coppin wrote:

...

Both Hackage and Cabal seem to assume as a matter of course that I want to use Haddock to generate all my documentation. Suppose I decide to violate this assumption. Then what?

1. Is there some way I can include my own HTML documentation in the package tarball and have Hackage/Cabal use it?

2. Is there a way to tell Hackage/Cabal to use some tool besides Haddock?

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

Jason Dagit

4:38 p.m.

On Thu, May 12, 2011 at 11:00 AM, Don Stewart wrote:

...

No, you should be using Haddock.

If you wish to generate docs some other way, you are free to host that on your own site, and link to it from the Hackage page.

Or improve haddock if you think it's lacking something. Jason

John Millikin

18 May 18 May

12:25 a.m.

Is there any way to indicate to Hackage that it should not try to generate Haddock documentation? I'm concerned for two use cases for packages using a different docs system: 1) A user might see the commentless auto-generated haddock and believe the package is undocumented. 2) A user might find the haddock through Google, and not realize there's real documentation available elsewhere. Purposfully causing Hackage's haddock step to fail will mark the package as a "build failure", which gives a bad impression to potential users.

Don Stewart

12:28 a.m.

I'm intrigued by the idea of Hackage docs that don't use Haddock. IF you do have better docs, host them somewhere, and put a link prominently in the .cabal file synopsis. On Tue, May 17, 2011 at 9:25 PM, John Millikin wrote:

...

Is there any way to indicate to Hackage that it should not try to generate Haddock documentation? I'm concerned for two use cases for packages using a different docs system:

1) A user might see the commentless auto-generated haddock and believe the package is undocumented. 2) A user might find the haddock through Google, and not realize there's real documentation available elsewhere.

Purposfully causing Hackage's haddock step to fail will mark the package as a "build failure", which gives a bad impression to potential users.

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

Andrew Coppin

5:39 p.m.

On 18/05/2011 05:28 AM, Don Stewart wrote:

...

I'm intrigued by the idea of Hackage docs that don't use Haddock.

This is basically the reason I asked. Currently Cabal assumes that Haddock is the only tool of its kind. If somebody built a better Haddock, you wouldn't be able to use it. (Unless you named the executable "haddock" and made it accept the same command options.) Also, Haddock generates API reference documentation. It does not really support generating tutorials, introductions, HOWTOs, and all the other types of useful documentation that a project ought to have.

...

IF you do have better docs, host them somewhere, and put a link prominently in the .cabal file synopsis.

That works, but it does mean that you can't read the documentation offline. (It also requires you to have somewhere to host, which not everybody has. Hackage provides hosting for the code itself, but you can only host documentation there if it's Haddock.)

Daniel Fischer

6:09 p.m.

On Wednesday 18 May 2011 23:39:47, Andrew Coppin wrote:

...

On 18/05/2011 05:28 AM, Don Stewart wrote:

...
I'm intrigued by the idea of Hackage docs that don't use Haddock.

This is basically the reason I asked. Currently Cabal assumes that Haddock is the only tool of its kind. If somebody built a better Haddock, you wouldn't be able to use it. (Unless you named the executable "haddock" and made it accept the same command options.)

Or maybe support for that tool would be integrated into Cabal and cabal and hackage. But even while such a tool is not yet available, it would be worth thinkng about hackage offering the possibility to display other docs than haddock- generated ones.

...

Also, Haddock generates API reference documentation. It does not really support generating tutorials, introductions, HOWTOs, and all the other types of useful documentation that a project ought to have.

...
IF you do have better docs, host them somewhere, and put a link prominently in the .cabal file synopsis.

That works, but it does mean that you can't read the documentation offline.

Make it downloadable? Include the docs in the package (extra-source-files: thedocs.tar.gz) and mention it in the package descripiton for a (less than optimal) workaround.

...

(It also requires you to have somewhere to host, which not everybody has.

Haskellwiki, bitbucket, github, ...

...

Hackage provides hosting for the code itself, but you can only host documentation there if it's Haddock.)

Yes, hackage is code hosting and not tutorial etc. hosting. Maybe integrating that would be a good thing, but even so, there are feasible ways of making additional documentation available. Sure, a centralised documentation-hosting would have advantages over sprinkling over all the free project-hosting services, but the situation is not unbearably dire as is.

Ivan Lazar Miljenovic

6:25 p.m.

On 19 May 2011 08:09, Daniel Fischer wrote:

...

On Wednesday 18 May 2011 23:39:47, Andrew Coppin wrote:

...
(It also requires you to have somewhere to host, which not everybody has.

Haskellwiki, bitbucket, github, ...

Also if you have a project on code.haskell.org, then you also can have a website for it on projects.haskell.org -- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com IvanMiljenovic.wordpress.com

Andrew Coppin

19 May 19 May

2:27 p.m.

On 18/05/2011 11:25 PM, Ivan Lazar Miljenovic wrote:

...

On 19 May 2011 08:09, Daniel Fischer wrote:

...
On Wednesday 18 May 2011 23:39:47, Andrew Coppin wrote:

...
(It also requires you to have somewhere to host, which not everybody has.

Haskellwiki, bitbucket, github, ...

Also if you have a project on code.haskell.org, then you also can have a website for it on projects.haskell.org

Today is the first time I've seen these domain names mentioned. (They appear to be aliases to the same server that runs the rest of haskell.org...)

Andrew Coppin

2:27 p.m.

...

...
This is basically the reason I asked. Currently Cabal assumes that Haddock is the only tool of its kind. If somebody built a better Haddock, you wouldn't be able to use it. (Unless you named the executable "haddock" and made it accept the same command options.)

Or maybe support for that tool would be integrated into Cabal and cabal and hackage.

I believe the correct approach would be to make it easy to configure Cabal to use any tool that might be produced one day, rather than integrating support for each specific tool that actually exists.

...

But even while such a tool is not yet available, it would be worth thinkng about hackage offering the possibility to display other docs than haddock- generated ones.

Agreed.

...

...
...
IF you do have better docs, host them somewhere, and put a link prominently in the .cabal file synopsis.

That works, but it does mean that you can't read the documentation offline.

Make it downloadable? Include the docs in the package (extra-source-files: thedocs.tar.gz) and mention it in the package descripiton for a (less than optimal) workaround.

I thought extra-source-files: is only for Haskell source code?

...

...
(It also requires you to have somewhere to host, which not everybody has.

Haskellwiki, bitbucket, github, ...

BitBucket only works for Mercurial, GitHub only works for Git. The Haskell wiki might be OK, and has the nice advantage that other people can improve it. (Do we think Hackage will ever get a wiki per package?) The other thing is, you can bet as soon as you put your package's documentation on the wiki and link it from the package description, the URL will change at some point, breaking the link.

...

Sure, a centralised documentation-hosting would have advantages over sprinkling over all the free project-hosting services, but the situation is not unbearably dire as is.

Granted. I'm just saying how it could be better.

Daniel Fischer

3:01 p.m.

On Thursday 19 May 2011 20:27:16, Andrew Coppin wrote:

...

...
...
This is basically the reason I asked. Currently Cabal assumes that Haddock is the only tool of its kind. If somebody built a better Haddock, you wouldn't be able to use it. (Unless you named the executable "haddock" and made it accept the same command options.)

Or maybe support for that tool would be integrated into Cabal and cabal and hackage.

I believe the correct approach would be to make it easy to configure Cabal to use any tool that might be produced one day, rather than integrating support for each specific tool that actually exists.

Well, 'any tool that might be produced one day' is perhaps a bit much to ask for, but making it easier to use other tools would be a good thing. The problem is, how?

...

I thought extra-source-files: is only for Haskell source code?

No, README, CHANGES, such stuff. Putting a doc-tarball there might be abusing it, but while there's no better option ...

...

...
...
(It also requires you to have somewhere to host, which not everybody has.

Haskellwiki, bitbucket, github, ...

BitBucket only works for Mercurial, GitHub only works for Git. The

Sure, I don't spell 'perfect' that way either.

...

Haskell wiki might be OK, and has the nice advantage that other people can improve it. (Do we think Hackage will ever get a wiki per package?) The other thing is, you can bet as soon as you put your package's documentation on the wiki and link it from the package description, the URL will change at some point, breaking the link.

...
Sure, a centralised documentation-hosting would have advantages over sprinkling over all the free project-hosting services, but the situation is not unbearably dire as is.

Granted. I'm just saying how it could be better.

Agreed.

Andrew Coppin

28 May 28 May

9:10 a.m.

On 18/05/2011 10:39 PM, Andrew Coppin wrote:

...

On 18/05/2011 05:28 AM, Don Stewart wrote:

...
I'm intrigued by the idea of Hackage docs that don't use Haddock.

This is basically the reason I asked. Currently Cabal assumes that Haddock is the only tool of its kind. If somebody built a better Haddock, you wouldn't be able to use it. (Unless you named the executable "haddock" and made it accept the same command options.)

Also, Haddock generates API reference documentation. It does not really support generating tutorials, introductions, HOWTOs, and all the other types of useful documentation that a project ought to have.

Apparently there's already a ticket for this: http://hackage.haskell.org/trac/hackage/ticket/330 It seems part of the reason for inaction is that people would like a general way of saying how to generate different types of documentation. Myself, I would be content with a way to say "put *these* files with documentation and tell the user where you've put them" as a first step. We can worry about how to *generate* various types of documentation later...

Heinrich Apfelmus

21 May 21 May

4:56 a.m.

Don Stewart wrote:

...

I'm intrigued by the idea of Hackage docs that don't use Haddock.

IF you do have better docs, host them somewhere, and put a link prominently in the .cabal file synopsis.

My package [operational][1] uses Haddock, but it also includes some [additional documentation][2]. I would love the ability to install it locally and to link to it from the Haddock documentation. [1]: http://hackage.haskell.org/package/operational [2]: http://projects.haskell.org/operational/Documentation.html Best regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com

Antoine Latter

12 May 12 May

7:01 p.m.

On Thu, May 12, 2011 at 12:45 PM, Andrew Coppin wrote:

...

Both Hackage and Cabal seem to assume as a matter of course that I want to use Haddock to generate all my documentation. Suppose I decide to violate this assumption. Then what?

1. Is there some way I can include my own HTML documentation in the package tarball and have Hackage/Cabal use it?

2. Is there a way to tell Hackage/Cabal to use some tool besides Haddock?

Why do you want to do this? Maybe there is some other way to get what you need. Is Haddock doing something wrong? In addition, it would be pretty easy to break the links from the Hackage page for your package into the documentation - it is all done by convention. That said, you can change your Setup.hs to call 'defaultMainWithHooks yourHooks' instead of 'defaultMain'. The 'yourHooks' indetifier would by of type Distribution.Simple.UserHooks (you would want to extend the 'simpleUserHooks' value). The record field you want to change is the 'haddockHook'. I think you would also need to update your package description file to indicate that you've customized the build, but I'm not 100% on that step. I have no idea how this interacts with the scripts currently run on Hackage, so it might not even work for that. Antoine _______________________________________________

...

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

5107

Age (days ago)

5123

Last active (days ago)

List overview

Download

13 comments

8 participants

participants (8)

Andrew Coppin
Antoine Latter
Daniel Fischer
Don Stewart
Heinrich Apfelmus
Ivan Lazar Miljenovic
Jason Dagit
John Millikin

No fish, please

Andrew Coppin

Andrew Coppin

Andrew Coppin

Andrew Coppin

Andrew Coppin

tags

participants (8)