Re: [Haskell-cafe] GSoC Project Proposal: Markdown support for Haddock
2013/4/8 Evan Laforge qdun...@gmail.com Can't we just add some features to haddock? There are a lot of ways to improve haddock a lot, and no one is doing them, so my impression is that haddock doesn't really have active maintainers. Adding a whole new backend seems risky, unless it results in new maintainers joining. As one of the official maintainers (the other one is Simon Hengel), I agree that Haddock can barely be called actively maintained and it has been like that for a long time now. It's sad, but we lack of time, which is the usual excuse of course. A more resourceful maintainer would be great, so if someone reading this is motivated and wants to help out, we'd love to be contacted by you. I don't think a SoC project for Markdown support would be risky at all (with a sufficiently good student), however. And it wouldn't require a new backend, the backend would still be the existing HTML backend in Haddock. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: Simplification of instances
2012/9/28 Simon Peyton-Jones simo...@microsoft.com: Ahem. DFuns (what you get from is_dfun of a ClsInst) now have some silent arguments, that are added by GHC and are not part of the original instance declaration. See Note [Silent superclass arguments] in TcInstDcls. But you don't want to print them. Just do what InstEnv.pprInstanceHdr does (in InstEnv) to drop the silent arguments. I've added some more comments (commit to come). Thanks! I've written a Haddock patch that drops the arguments. David ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Re: [Haskell-cafe] haddock changes between 2.10 and 2.12?
2012/9/24 Edward Kmett ekm...@gmail.com: Was there some significant change/bug introduced to haddock made between 2.10 and 2.12? When I look at the haddocks for kan-extensions 3.1: Data.Functor.Yoneda which purports to have been built by haddock 2.12 it shows all sorts of spurious superclass constraints on almost every instance that should have simplified out, but going back to kan-extensions-2.7: Data.Functor.Yoneda none of this extra noise is present -- and the code in question hasn't been changed in the interim, so I'm pretty sure its not on my end. I think this is probably due to some change in the GHC internals. We'll investigate. Thanks for the report. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] ANNOUCE: Haddock 2.10.0 and 2.11.0
2012/9/8 Ivan Lazar Miljenovic ivan.miljeno...@gmail.com: On 7 September 2012 23:19, David Waern david.wa...@gmail.com wrote: -- Haddock 2.10.0 and 2.11.0 Two new versions of Haddock have been uploaded to Hackage: version 2.10.0 which comes with GHC 7.4.2 and 2.11.0 which comes with the new GHC 7.6.1! -- Changes in version 2.12.0 So either your changelog has the wrong versions, or else you listed the wrong versions above? ;-) Oops, sorry. I listed the wrong versions above! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] ANNOUCE: Haddock 2.10.0 and 2.11.0
-- Haddock 2.10.0 and 2.11.0 Two new versions of Haddock have been uploaded to Hackage: version 2.10.0 which comes with GHC 7.4.2 and 2.11.0 which comes with the new GHC 7.6.1! -- Changes in version 2.12.0 * Labeled URLs (e.g http://example.net/ some label) * Improved memory usage (new dependency: deepseq) -- Changes in version 2.11.0 * Show deprecation messages for identifiers * List identifiers declared on the same line (with a common type) separately * Don't crash on unicode strings in doc comments * Fix reporting of modules safe haskell mode * Fix a case where we were generating invalid xhtml * Improved --qual option (no crashes, proper error messages) * A new --qual option aliased which qualifies identifers by the module alias used in the source code * The Haddock API restores GHC's static flags after invocation * Access to unexported identifiers through the Haddock API again -- Links Homepage: http://www.haskell.org/haddock Hackage page: http://hackage.haskell.org/package/haddock-2.12.0 Bugtracker and wiki: http://trac.haskell.org/haddock Mailing list: hadd...@projects.haskell.org Code repository: http://darcs.haskell.org/haddock.git -- Contributors The following people contributed patches to this release: Paolo Capriotti Simon Hengel Ian Lynagh Simon Peyton Jones Iavor S. Diatchki David Terei Henning Thielemann David Waern -- Get Involved We would be very happy to get more contributors. To get involved, start by grabbing the code: http://darcs.haskell.org/haddock.git Then take a look at the bug and feature tracker for things to work on: http://trac.haskell.org/haddock ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] ANNOUNCE: Haddock 2.10.0
2012/3/4 Sergei Trofimovich sly...@gmail.com: Thanks! Fixed upstream. Let me bother you with another example (looks like a regression this time). Example comes from probability-0.2.3.1 package (selfcontained example attached). Haddock seems to have stopped liking utf-8 special chars in comments like: n² × n² n·(n+1)/2 Thanks for the report. I think unicode worked mostly by accident before and a recent change to support Alex 3 might unfortunately have turned that off. We're working on full support for unicode and I think we'll be able to get that into the next release. Sorry for the regression! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] ANNOUNCE: Haddock 2.10.0
-- Haddock 2.10.0 Version 2.10.0, which was released with GHC 7.4.1, is now uploaded on Hackage. Here are the release notes: -- Changes in 2.10.0 * Require GHC = 7.4 * Safe Haskell indications on module pages * Type declarations on identifiers no longer necessary * Add flag --interface-version * Warn when comment refers to in-scope identifier without documentation * Bug fix: links to out-of-scope things (#78) * Bug fix: module references to other packages work again -- Links Hackage page: http://hackage.haskell.org/package/haddock-2.10.0 Bugtracker and wiki: http://trac.haskell.org/haddock Mailing list: hadd...@projects.haskell.org Code repository: http://darcs.haskell.org/haddock.git -- Contributors The following people contributed patches to this release: Ian Lynagh Jose Pedro Magalhaes Simon Peyton-Jones Ryan Newton David Terei David Waern Also thanks to Simon Hengel for spotting a serious bug before the release. -- Get Involved We would be very happy to get more contributors. To get involved, start by grabbing the code: http://darcs.haskell.org/haddock.git Then take a look at the bug and feature tracker for things to work on: http://trac.haskell.org/haddock ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] ANNOUNCE: Haddock 2.10.0
2012/3/3 Sergei Trofimovich sly...@gmail.com:
It seems to fail to generate buildwrapper documentation.
The minimal example:
-- Base.hs:
module Base where
-- | component in cabal file
data CabalComponent
= CCLibrary -- ^ library
{ cc_buildable :: Bool -- ^ is the library buildable
}
You can't stick a doc comment between a constructor and its arguments.
Try putting the comment after the record closing bracket instead (or
tell the author of the code).
David
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] [haskell-cafe] Some reflections on Haskell
2012/2/15 Aristid Breitkreuz arist...@googlemail.com: In the source file, the Haddock documentation is there, no idea why it doesn't show up. Thanks, this could be a bug in the new Haddock version. We'll look into it. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: Records in Haskell
2012/1/14 Johan Tibell johan.tib...@gmail.com:
On Fri, Jan 13, 2012 at 3:52 PM, Simon Peyton-Jones
simo...@microsoft.com wrote:
I know of no proposal that advocates only (A). It seems that we are agreed
that we must make use of types to disambiguate common cases.
I will try to make the case for (A), just so it has been put on the table.
Proposal
=
The proposal is to implement
http://hackage.haskell.org/trac/ghc/wiki/Records/NameSpacing without
any of the type resolution parts. I think this approach is dismissed a
bit to easily on the wiki page above:
We have name-spaces, but it is hard to see how this is better
than the current practice of adding prefixes to record fields: data
Record = Record { recordA :: String }
There are (at least) three benefits of using namespaces (e.g.
'Record.a') rather than ad-hoc prefixes (e.g. 'recordA'):
* You can use a type synonym to abbreviate the namespace part (as
shown on the wiki page.)
* If there's no ambiguity you don't need to use a namespace (e.g. you
can use 'a' instead of 'Record.a').
* The namespace name is predictable (e.g. Typename.fieldname)
while ad-hoc prefixes tend to use different conventions e.g. the whole
record name (e.g. 'recordA') or some abbreviation thereof (e.g.
'rcrdA'.)
The main argument for this approach is its simplicity; it's simple to
understand for users and (hopefully) simple to implement.
At work we have extended the OCaml compiler with the same mechanism,
to solve the same problem. I find it quite annoying to use, as you
tend to try without a namespace name first, and if you get a compile
error you add one. I'd prefer a system which just infers the right
selector - less time spent fighting with the compiler!
David
___
Glasgow-haskell-users mailing list
Glasgow-haskell-users@haskell.org
http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Re: [Haskell-cafe] Disjunctive patterns
2011/12/8 Asger Feldthaus asger.feldth...@gmail.com: Haskell doesn't seem to support disjunctive patterns, and I'm having a difficult time writing good Haskell code in situations that would otherwise call for that type of pattern. I've also missed this after having done a bit of OCaml coding. Perhaps if a good syntax can be found (since | is already taken) it could be added as an extension to GHC. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
2011/12/6 Yves Parès limestr...@gmail.com: Hi, I noticed some time ago the fact that qualified imports doesn't affect the generated documentation. It's kind of clumsy in case of libraries that define a lot of synonyms (vector and bytestring come in my mind first). For instance, in the package utf8-string: http://hackage.haskell.org/packages/archive/utf8-string/0.3.7/doc/html/Data-ByteString-UTF8.html Here, the documentation doesn't say that the utf8-string/Data.ByteString.UTF8.ByteString datatype used all along comes in fact from Data.ByteString. If it were instead a new implementation of ByteString (as for bytestring/Data.ByteString.Char8.ByteString) the documentation would look exactly the same, so to disambiguate to reader has to crawl through the code to get to the initial definition. (clicking on a 'ByteString' doesn't even redirect you to the original bytestring/Data.ByteString page) It should be written that this 'ByteString' is not a newly defined type but instead a re-exportation. It should be simple to add some kind of Re-export of link to original thing tag to the Haddock documentation. Feel free to add a ticket for this feature to the issue tracker (trac.haskell.org/haddock) with a description of how it should work. It's even worse when you see the doc of a module that uses in the meantime lazy and strict ByteStrings, or normal and unboxed/storable/insert flavour here vector: you have to hover the type name to see which haddock page it points to. In that case, a solution might be to indicate on top of the doc page that it uses another module as a qualified import, and to keep the prefixes in the function signatures. Maybe. But have you tried experimenting with Haddock's --qual flag? David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
2011/12/6 David Waern david.wa...@gmail.com: 2011/12/6 Yves Parès limestr...@gmail.com: It should be written that this 'ByteString' is not a newly defined type but instead a re-exportation. It should be simple to add some kind of Re-export of link to original thing tag to the Haddock documentation. Feel free to add a ticket for this feature to the issue tracker (trac.haskell.org/haddock) with a description of how it should work. I should really add as well that if you contribute patches that will increase the likelyhood of this being added in the near future from ~0% to 100% :-) In general I'd like to encourage anyone interesting in hacking on small useful projects for the benefit of the Haskell community to take a look at the Haddock trac. It's got a lot of nice little feature requests that no one is working on. In general we're not seeing that much new development in Haddock at the moment. I am (as the maintainer) mostly spending my time fixing bugs, making releases and so on. If anyone feels like helping out, please talk to me. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock and the qualified imports
2011/12/6 Evan Laforge qdun...@gmail.com: I've also often wished that unimported but fully qualified modules like 'Data.List.partition' would link even if Data.List is not imported. I suppose similarly to the way that s blind link without having to know about the module in question. That's just been fixed - it's just been a long standing bug. And speaking of s, I've always wondered why double quotes were needed for module names, and why single quotes around capitalized words isn't sufficient. That would refer to a type or data constructor! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: gitweb on darcs.haskell.org?
Hi Iavor, Could we get darcs.haskell.org/haddock.git in there as well? It's now the haddock upstream repository, and darcs.haskell.org/haddock2 should not be used. 2011/6/24 Iavor Diatchki iavor.diatc...@gmail.com: Hello, We now have a git-web instance running on darcs.haskell.org. You can access it at the following URL: http://darcs.haskell.org/cgi-bin/gitweb.cgi -Iavor On Tue, Jun 21, 2011 at 10:26 AM, austin seipp a...@hacks.yi.org wrote: I am also a fan of cgit: http://hjemli.net/git/cgit/about/ As it's very very fast and has a pleasant UI, but I'm not partial either way (gitweb is probably more than robust enough to handle a repo of GHC's size I'm sure.) On Tue, Jun 21, 2011 at 12:09 PM, Iavor Diatchki iavor.diatc...@gmail.com wrote: Hello, Do we have an instance of gitweb for the various ghc related repos running somewhere? If not, I'd be happy to setup an instance, would anyone object? gitweb is a web-interface which makes it easy to get a quick overview of what's going on with a collection of repositories. It shows commits, branches, tags, etc. Also, it provides RSS/Atom feeds, which makes it easy to subscribe to changes for repos of interest. -Iavor PS: you can try it out locally by typing git instaweb in a git repository. ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users -- Regards, Austin ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Re: Exported modules in the GHC API
2011/5/27 Simon Marlow marlo...@gmail.com: On 23/05/2011 13:52, David Waern wrote: 2011/5/23 Simon Marlowmarlo...@gmail.com: This is the way it's defined in Haskell - a 'module' export expands to all those names in scope qualified with that module name. There might be several different modules imported with that name, and the 'module' export would export the contents of all of them. So I'm afraid you have to traverse the whole of the scope. Aha. I suspected I didn't know the full story. Thanks for claring it up. I suspect we don't do this properly in Haddock, since the documentation always contains just a link to the exported module, right? Yes, it contains a link if the exported module is not hidden, otherwise we inline all the export items of the module. There are several things related to module exports that we do wrong currently. So I propose we should do this: There are two different behaviours: 1) We emit a link (under the original module name), if: * The module name is used to fully import exactly one non-hidden module. Fully *export*, you mean? Yes, sorry. 2) We inline all imported export items from the module(s), if: (2) applies in all the cases that (1) doesn't, right? We can list those cases, but the code doesn't need to check for them explicitly, checking the condition for (1) is enough. Yep, exactly. I realized that after sending the mail. :-) David ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Re: Exported modules in the GHC API
2011/5/23 Simon Marlow marlo...@gmail.com: This is the way it's defined in Haskell - a 'module' export expands to all those names in scope qualified with that module name. There might be several different modules imported with that name, and the 'module' export would export the contents of all of them. So I'm afraid you have to traverse the whole of the scope. Aha. I suspected I didn't know the full story. Thanks for claring it up. I suspect we don't do this properly in Haddock, since the documentation always contains just a link to the exported module, right? Yes, it contains a link if the exported module is not hidden, otherwise we inline all the export items of the module. There are several things related to module exports that we do wrong currently. So I propose we should do this: There are two different behaviours: 1) We emit a link (under the original module name), if: * The module name is used to fully import exactly one non-hidden module. 2) We inline all imported export items from the module(s), if: * The module name is used by imports from more than one module or (one module): * The module name points to a hidden module * The module name points to a partially-imported module Sounds OK? That would fix #174 as well as handle multiple modules imported under the same name. David ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Exported modules in the GHC API
Hi, When encountering an IEModuleContents ModuleName export item, I'd like a simple way to get its original Module (with the original module name and package ID). It seems a bit complicated to have to go through the import items to figure this out. My question is: is there a simpler way, and if not, do you agree that the API should provide a simpler way? Thanks, David ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Re: [Haskell-cafe] ANN: Leksah 0.10.0
2011/4/28 jutaro j...@arcor.de: So its a bit like running Haddock on a package, which usually may fail, but it is uncommon to have this kind of problems. (It happened one time before with a type level library, which defined all integers between 1 and several thousands...). If a package uses template haskell, haddock can slow down substantially, as it will compile all the modules of the package rather than just typecheck them. See this ticket: http://trac.haskell.org/haddock/ticket/101 If anyone would like to work on fixing that, that'd be great of course. I don't have much time for Haddock development at the moment. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Haskell internship in the south of France
To all undergrads on this list: Are you a student looking for an internship? Do you want to work with Haskell in the south of France? My company, Amadeus, is able to offer an internship on the subject of property-based testing of XML schema based web service APIs. The project goal is to write an XML test case generation tool in Haskell. The exact length of the intership can be discussed. It may be six months or a full year. XML based web services may not be the most fashionable technology, but this is a chance to apply Haskell to real world problems! Also, you get to work in Sophia-Antipolis, a beautiful technology park close to Nice on the French riviera. Contact me if you're interested! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock fails on parsing Hamlet
2011/3/12 Mathew de Detrich dete...@gmail.com: Don't need to worry about this, its being fixed in the next release of hamlet So was it a bug in Haddock that you've worked around or something else? Thanks, David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GRIN and Urban Boquist's thesis
2011/2/24 Lemmih lem...@gmail.com: They will also be in the lhc repository once I restore it on code.haskell.org. Lemmih, while you're here, what's the status of LHC? It's an interesting project but we haven't heard much from you lately. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock: generate documentation for all functions?
2011/1/3 Antoine Latter aslat...@gmail.com: For this I use: 'cabal haddock --internal' Or if you're using haddock directly it's: --ignore-exports. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] How can i insert graphic into a haddock document?
2010/12/11 Poprádi Árpád popradi_ar...@freemail.hu Hi, I have found nothing about this topic in the haddock documentation. Is there a light way to do that? Yes: -- | picture-url-here The documentation should be updated. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] ANNOUNCE: Haddock 2.9.0
-- Haddock 2.9.0 A new version of Haddock, the Haskell documentation tool, is out! This version is compatible with .haddock files produced by the version of Haddock that comes with GHC 7.0.1. -- Changes in version 2.9.0 Changes in version 2.9.0 * Drop support for ghc 7 * New flag --qual for qualification of names * Print doc coverage information to stdout when generating docs * Include an 'All' option in the A-Z subdivided index * Make TOC group header identifiers validate * Minor changes to the API -- Links Homepage: http://www.haskell.org/haddock Hackage page: http://hackage.haskell.org/package/haddock-2.9.0 Bugtracker and wiki: http://trac.haskell.org/haddock Mailing list: hadd...@projects.haskell.org Code repository: http://code.haskell.org/haddock -- Contributors The following people contributed patches to this release: Tobias Brandt Mark Lentczner Ian Lynagh Simon Marlow Simon Michael Ryan Newton David Waern -- Get Involved We would be very happy to get more contributors. To get involved, start by grabbing the code: http://code.haskell.org/haddock Then take a look at the bug and feature tracker for things to work on: http://trac.haskell.org/haddock ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock API and .haddock interface files questions
2010/10/26 Claus Reinke claus.rei...@talk21.com: Some questions about Haddock usage: 1. Haddock executable and library are a single hackage package, but GHC seems to include only the former (haddock does not even appear as a hidden package anymore). Is that intended? Yes, I think that's so that GHC maintainers don't need to worry about API changes in Haddock when making new releases. The Haddock API is not very stable. 2. Naively, I'd expect Haddock processing to involve three stages: 1. extract information for each file/package 2. mix and match information batches for crosslinking 3. generate output for each file/package I would then expect .haddock interface files to repesent the complete per-package information extracted in step 1, so that packages with source can be used interchangeably with packages with .haddock files. However, I can't seem to use 'haddock --hoogle', say, with only .haddock interface files as input (No input file(s).). Haddock currently mostly works on GHC's front-end AST, called HsSyn, which is not stored in the .haddock files, so that's why you need sources. I say mostly, because the one-year old feature that we call cross-package documentation (allowing the user to re-export documentation from other packages), is implemented by taking information from GHC's .hi files, converting that to HsSyn. The syntax used in the .hi files is slightly less detailed than HsSyn so we loose some information about the exact declaration syntax used by the programmer (brackets in type expressions, infix/prefix declaration styles, etc - nothing that is semantically relevant). In theory we could continue along that road and let you build output from a combination of .haddock and .hi files. Or we could do as you say and just put everything in the .haddock files (in which case we could use the HsSyn type). 3. It would be nice if the Haddock executable was just a thin wrapper over the Haddock API, if only to test that the API exposes sufficient functionality for implementing everything Haddock can do. Yes, good idea. We haven't done that yet since the API started out as something quite experimental, and it's still in that stage although it has gained a lot more functionality recently. Instead, there is an awful lot of useful code in Haddock's Main.hs, which is not available via the API. So when coding against the API, for instance, to extract information from .haddock files, one has to copy much of that code. Also, some inportant functionality isn't exported (e.g., the standard form of constructing URLs), so it has to be copied and kept in synch with the in-Haddock version of the code. Right. We should export that. It might also be useful to think about the representation of the output of stage 2 above: currently, Haddock directly generates indices in XHtml form, even though much of the index computation should be shareable accross backends. That is, current backends seem to do both stage 2 and stage 3, with little reuse of code for stage 2. True. The index could be factored out of the Xhtml backend and added to the output of stage 2. It seems that exposing sufficient information in the API, and allowing .haddock interface files as first-class inputs, there should be less need for hardcoding external tools into Haddock (such as --hoogle, or haddock-leksah). Instead, clients should be able to code alternative backends separately, using Haddock to extract information from sources into .haddock files, and the API for processing those .haddock files. Are these expectations reasonable, or am I misreading the intent behind API and .haddock files? Is there any documentation about the role and usage of these two Haddock features, as well as the plans for their development? No documentation yet, but yes, the long term plan is to be able to split Haddock in parts: one program that creates data from sources, probably resulting in a .haddock file or maybe something text based, and backends that use those files. The API should provide a convenient way to read the files. It's not been fleshed out in detail yet, and the API is quite ad-hoc at the moment so we need think more about this and write documentation on the Haddock trac. Thanks for the input! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock: patch to generate single-index page in addition to perl-letter indexes indices.
2010/10/24 Ryan Newton new...@mit.edu: When I encounter a split-index (A-Z) page it can be quite frustrating if I don't know the first letter of what I'm searching for. I want to use my browser find! For example, tonight I wanted to look at all the functions that END in Window in the Chart package -- no luck: http://hackage.haskell.org/packages/archive/Chart/0.13.1/doc/html/doc-index.html Therefore I propose that even when generating the A-Z individual pages that there also be an All option for the single-page version. Attached is a patch against haddock's HEAD (darcs get http://code.haskell.org/haddock/ right?) that implements this behavior. As an example, here is FGL's documentation built with the patched haddock: http://people.csail.mit.edu/newton/fgl_example_doc/doc-index.html The great thing about hackage being centralized is that if people are happy with this fix it can be widely deployed where it counts, and quickly! Patch applied. Thanks! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: haddock and associated data families
2010/9/9 Antoine Latter aslat...@gmail.com: CC'ing the maintainer listed on Hackage for haddock On Wed, Sep 8, 2010 at 5:14 PM, Christian Höner zu Siederdissen choe...@tbi.univie.ac.at wrote: Hi, haddock seems to produce an error on associated data family decls.: http://hackage.haskell.org/packages/archive/PrimitiveArray/0.0.2.1/logs/failure/ghc-6.12 line 22, where the errors occurs is exactly this one: class PrimArrayOps a b where data PrimArray a b :: * -- ^ PrimArray data type I'll fix it by trying other methods to put comments there. Could someone enter this as a bug, if it is not done yet? (Assuming it is a bug ;-) Hi, Sorry for the late reply. Haddock doesn't support comments on associated types yet. I created a ticket: http://trac.haskell.org/haddock/ticket/154 David ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Re: [Haskell-cafe] HackageDB: Haddock parse failure
Den 27 september 2010 18:22 skrev Jonas Almström Duregård jonas.dureg...@chalmers.se: HackageDB reports a build failure for happy-meta-0.1.1 (http://hackage.haskell.org/package/happy-meta-0.1.1), but from the log it seems that the failure occurs when building the documentation. The error is src/LALR.lhs:230:2: parse error on input `numberSets' I'm guessing there is no syntax error in this file (it is taken from Happy), but rather an error in Haddock? I suspect this has something to do with the comment before that line. I might be wrong but I think Cabal turns the text in literal haskell files into haddock comments. If that's the case then you have to be careful to not use haddock comment markup in the wrong way. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock comments for GADT constructors?
2010/9/10 Conal Elliott co...@conal.net: I'm updating a library (TV) and getting haddock parse errors for the doc strings attached to GADT constructors. Is there a way to haddock-document GADT constructors? I've tried both -- | ... before and -- ^ ... after. Both give parse errors. Thanks, - Conal Nope. It's not yet supported. We should really get this one done. http://trac.haskell.org/haddock/ticket/43 David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] ANNOUNCE: Haddock version 2.8.0
-- Haddock 2.8.0 A new version of Haddock, the Haskell documentation tool, is out! The biggest news this time is that we have a shiny new XHTML backend, created by Mark Lentczner, which outputs semantically correct XHTML, making it much easier to create new themes for Haddock. Mark has made an extraordinary effort by going through and rewriting the old table based HTML backend, fixing non-standards-compliant quirks, and adding a bunch of new useful features on top of that. See the changelog for more details. Included is a new default CSS theme created by Thomas Schilling, Mark and Johan Tibell, as well as the classic theme converted to work with the new backend. Another great new feature is markup support for examples, contributed by Simon Hengel. The idea is to be able to write examples that function both as documentation and unit tests. Last but not least, we now also have a LaTeX backend. It was written by Simon Marlow and it was used to generate the libraries section of the Haskell 2010 report. This version is compatible with .haddock files produced by Haddock 2.6.1 and above, provided that the version of GHC used to build Haddock stays the same. -- Changes in version 2.8.0 * HTML backend completely rewritten to generate semantically rich XHTML using the xhtml package. * New default CSS based on the color scheme chosen for the new Haskell wiki, with a pull-out tab for the synopsis. * Theme engine based on CSS files. Themes can be switched from the header menu. (New flags --built-in-themes and --theme. The latter is an alias for --css which now has extended semantics). * Markup support for executable examples/unit-tests. To be used with an upcoming version of the DocTest program. * Addition of a LaTeX backend. * Frames-mode can be enabled from the header menu. * Path to source entities can be specified per package, so that source links work for cross-package documentation. * Support for a second form of enumerated lists (1. 2. etc). * Additions and changes to the Haddock API. * New flag --no-tmp-comp-dir to tell Haddock to read/write compilation files (.o, .hi, etc) to/from GHC's output directory instead of to/from a temporary directory. * Various bug fixes. -- Links Homepage: http://www.haskell.org/haddock Hackage page: http://hackage.haskell.org/package/haddock-2.8.0 Bugtracker and wiki: http://trac.haskell.org/haddock Mailing list: hadd...@projects.haskell.org Code repository: http://code.haskell.org/haddock -- Contributors The following people contributed patches to this release: Simon Hengel Mark Lentczner Ian Lynagh Simon Marlow Simon Peyton-Jones Thomas Schilling David Waern -- Get Involved We would be very happy to get more contributors. To get involved, start by grabbing the code: http://code.haskell.org/haddock Then take a look at the bug and feature tracker for things to work on: http://trac.haskell.org/haddock ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] ANNOUNCE: Haddock version 2.8.0
2010/9/2 Henk-Jan van Tuyl hjgt...@chello.nl:
On Thu, 02 Sep 2010 14:00:56 +0200, David Waern david.wa...@gmail.com
wrote:
-- Haddock 2.8.0
A new version of Haddock, the Haskell documentation tool, is out!
It doesn't install on Windows + MinGW:
cabal install --global haddock
Resolving dependencies...
Downloading haddock-2.8.0...
:
:
[ 9 of 33] Compiling Haddock.Utils ( src\Haddock\Utils.hs,
dist\build\Haddock\Utils.o )
src\Haddock\Utils.hs:435:8: parse error on input `import'
cabal: Error: some packages failed to install:
haddock-2.8.0 failed during the building phase. The exception was:
ExitFailure 1
This concerns a line with a foreign import:
#ifdef mingw32_HOST_OS
foreign import ccall unsafe _getpid getProcessID :: IO Int -- relies on
Int == Int32 on Windows
#else
getProcessID :: IO Int
getProcessID = fmap fromIntegral System.Posix.Internals.c_getpid
#endif
Adding the line:
{-# LANGUAGE ForeignFunctionInterface #-}
to the top of file src\Haddock\Utils.hs helped.
Thanks for catching this!
I'll wait a little while in case other issues are reported before I
upload 2.8.1.
David
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] ANNOUNCE: Haddock version 2.8.0
2010/9/2 Daniel Peebles pumpkin...@gmail.com: Mmm, delicious! Thanks to all involved! Any idea how long it'll take for this to make it to hackage and regenerate all the documentation up there? It'd be wonderful to do the same to the GHC documentation too. I don't actually know yet if it's possible to regenerate the documentation on hackage. We're looking into the matter. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock: Documentation of instances with un-documentable type arguments
2010/8/25 Alexander McPhail haskell.vivian.mcph...@gmail.com: Perhaps Haddock could exclude class instance reporting when it cannot find a documentable link to a parameter? Yes, it should. BTW, we have a trac ticket for it: http://trac.haskell.org/haddock/ticket/37 You can add yourself to the CC list to show that you want this feature. Currently we don't have many people working on these types of tickets in Haddock (I'm mostly fixing bugs, others are working on bigger improvements), so if more people would volunteer to help out, that'd be great. The mailing list hadd...@projects.haskell.org can be used to ask for directions and help. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Academic Haskell Course
2010/8/19 Eyal Lotem eyal.lo...@gmail.com: Can anyone point me towards existing work I could use? Open course material and syllabuses I could use, with the necessary references? At Chalmers University of Technology: http://www.cse.chalmers.se/edu/course/afp/ David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
2010/7/23 Ivan Miljenovic ivan.miljeno...@gmail.com: On 22 July 2010 18:33, David Waern david.wa...@gmail.com wrote: [snip] We currently only support concrete examples (i.e. unit tests), but the plan is to add support for QuickCheck properties. Would you have some kind of inbuilt time limit (similar to what mueval has) for very long/complex QC tests? I have some that take quite a while to run... The testing is carried out by a separate program: DocTest. There is no support for QC properties yet. Some kind of time limit would probably be useful to have, yes. Thanks for the suggestion. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] On documentation
2010/7/21 Richard O'Keefe o...@cs.otago.ac.nz: One of the really nice ideas in the R statistics system is that documentation pages can contain executable examples, and when you wrap up a package for distribution, the system checks that the examples run as advertised. The next version of Haddock will support something like this, implemented by SImon Hengel. Here's an example of how to use the new markup: -- | An example: -- -- ghci fib 10 -- 55 -- Haskell has a *perfect* fit for this idea in QuickCheck. We currently only support concrete examples (i.e. unit tests), but the plan is to add support for QuickCheck properties. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Type classes
2010/7/4 Ivan Lazar Miljenovic ivan.miljeno...@gmail.com: Andrew Coppin andrewcop...@btinternet.com writes: In summary, I think we need to devise a way of better-documenting class instances. Haddock 2.7 supports documenting instance implementations; I don't know how this works, but according to the Changelog it's available. It's simple: -- | Documentation for the instance instance Monoid Foo David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Type classes
2010/7/4 Daniel Fischer daniel.is.fisc...@web.de: Hmm, it seems only partial: documentation attached to an instance is shown in the list of instances under a type, but not the list under a class. I'm guessing that's to reduce noise... I'm guessing it might have something to do with the fact that often the module containing the class definition isn't processed together with the module containing the instance declaration. Actually Haddock attaches instance information to the modules in a separate step after having processed all of them. The fact that no documentation shows up for instances under the class documentation is a bug, embarrasingly enough, which I hadn't noticed. Looking at the code, it's not that I've forgotten to add code to the Html backend, it's something deeper that is wrong, so I will have to investigate. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Type classes
2010/7/4 Ivan Lazar Miljenovic ivan.miljeno...@gmail.com: David Waern david.wa...@gmail.com writes: 2010/7/4 Ivan Lazar Miljenovic ivan.miljeno...@gmail.com: Andrew Coppin andrewcop...@btinternet.com writes: In summary, I think we need to devise a way of better-documenting class instances. Haddock 2.7 supports documenting instance implementations; I don't know how this works, but according to the Changelog it's available. It's simple: -- | Documentation for the instance instance Monoid Foo It's not for each method, just for the overall instance? I was kinda hoping to use it to be able to put runtime bounds on instances of some classes :( It's just for the overall instance at the moment. Haddock doesn't document instance declarations separately. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Type classes
2010/7/4 Ross Paterson r...@soi.city.ac.uk: It could be either way: sometimes you define a new class with instances for existing types, and with the current implementation that produces no documentation. (I tested with type, class and instance in the same package.) Hi Ross, thanks for testing this. Could you send me the file(s) you used? I wasn't able to reproduce the issue here with a few simple tests. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Type classes
2010/7/4 David Waern david.wa...@gmail.com: 2010/7/4 Daniel Fischer daniel.is.fisc...@web.de: Hmm, it seems only partial: documentation attached to an instance is shown in the list of instances under a type, but not the list under a class. I'm guessing that's to reduce noise... I'm guessing it might have something to do with the fact that often the module containing the class definition isn't processed together with the module containing the instance declaration. Actually Haddock attaches instance information to the modules in a separate step after having processed all of them. The fact that no documentation shows up for instances under the class documentation is a bug, embarrasingly enough, which I hadn't noticed. Looking at the code, it's not that I've forgotten to add code to the Html backend, it's something deeper that is wrong, so I will have to investigate. I found the bug and fixed it, it's in the latest darcs version at http://code.haskell.org/haddock. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/15 Dominic Steinitz domi...@steinitz.org: David Waern david.waern at gmail.com writes: I think using --optghc=-package-conf is the correct way to point to another package DB, so I'll look into why it doesn't work. Perhaps another line of attack would be to see why haddock thinks I have an E: drive? Right. However I suspect it's not a problem with Haddock but rather something to do with the platform. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/15 David Waern david.wa...@gmail.com: 2010/6/15 Dominic Steinitz domi...@steinitz.org: David Waern david.waern at gmail.com writes: I think using --optghc=-package-conf is the correct way to point to another package DB, so I'll look into why it doesn't work. Perhaps another line of attack would be to see why haddock thinks I have an E: drive? Right. However I suspect it's not a problem with Haddock but rather something to do with the platform. Here's something similar: http://trac.haskell.org/haskell-platform/ticket/119 I tried myself on windows, and haddock --print-ghc-libdir yields: E:\ghc\ghc-6.12.1\lib and I don't have an E: either. So Haddock seems to be more or less broken on windows in the current platform. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock Problem
2010/6/14 Dominic Steinitz domi...@steinitz.org: ..\ThirdParty\Haskell_Platform\2010.1.0.0\bin\haddock.exe BackendC\Core.hs haddock.exe: can't find a package database at E:\ghc\ghc-6.12.1lib\package.conf.d But if I do haddock --help there is no option to set the package database and I don't even have an E: drive. I'm on windows in case that wasn't obvious and we have a custom package database which we point e.g. ghc and cabal at. Try --optghc=-package-conf --optghc=file, to point Haddock at the custom DB. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/14 Dominic Steinitz domi...@steinitz.org: Try --optghc=-package-conf --optghc=file, to point Haddock at the custom DB. Hi David, Thanks for the quick response. No dice I am afraid. Dominic. BTW this (using optghc) used to work on previous versions of haddock (iirc 2.4 and 2.5). ..\ThirdParty\Haskell_Platform\2010.1.0.0\bin\haddock.exe --optghc=-package-conf --optghc=c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell _packages\fpf.package.conf backendc\PAD2C.hs haddock.exe: can't find a package database at E:\ghc\ghc-6.12.1 \lib\package.conf.d OK, it seems like the path from the ghc-paths package overrided what you specified. I'm not sure this will work, but you could try: haddock -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\fpf.package.conf David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/14 David Waern david.wa...@gmail.com: OK, it seems like the path from the ghc-paths package overrided what you specified. I'm not sure this will work, but you could try: haddock -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\fpf.package.conf Sorry, that should be haddock -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock Problem
2010/6/14 Dominic Steinitz domi...@steinitz.org: So I created one and copied our custom package databse into it but still no luck: ..\ThirdParty\Haskell_Platform\2010.1.0.0\bin\haddock.exe -B c:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages backendc\PAD2C.hs haddock: internal Haddock or GHC error: C:\p4wksp\steinitd_fpf_exdate_ws\FPF_Dev.br\ThirdParty\haskell_packages\package. conf.d\package.cache: openBinaryFile: does not exist (No such file or directory) I'm not what this file is. Is it the same as the index file that cabal uses? I don't know exactly what that file is, but -B is actually for pointing Haddock at the GHC lib dir, so it's not surprising that it doesn't work. I thought that perhaps the package.conf.d file is the only thing it needs from that directory, but that doesn't seem to be the case. I think using --optghc=-package-conf is the correct way to point to another package DB, so I'll look into why it doesn't work. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Is anyone using Haddock's support for frames?
2010/5/4 Evan Laforge qdun...@gmail.com: On Tue, May 4, 2010 at 1:23 PM, David Waern david.wa...@gmail.com wrote: 2010/5/4 Sean Leather leat...@cs.uu.nl: Somewhat OT, but is there a place where we can request/review features in the new HTML presentation of Haddock. Are there any mockups of what the pages might look like? I've had some ideas pop around my head every time I look at documentation. ;) http://trac.haskell.org/haddock/ticket/108 Or feel free to open a discussion on hadd...@projects.haskell.org. I haven't been able to find information on this list anywhere. http://www.haskell.org/haddock/ doesn't mention it, and neither does the haddock wiki nor http://haskell.org/haskellwiki/Mailing_lists. Am I missing something obvious? Here's the list of mailing lists on the community server: http://projects.haskell.org/cgi-bin/mailman/listinfo The wikis and the homepage should be updated. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Is anyone using Haddock's support for frames?
Hi Since version 2.4.0 Haddock has generated HTML output that uses frames (index-frames.html) in addition to the normal output. We'd like to deprecate this feature unless there is a significant amount of users. The reason is two-fold: * We probably want to replace the frames with something more modern (like a sidebar on the same page) in the future * We are rewriting the HTML backend and it would be nice to avoid unnecessary work So if you're using this feature and want to keep it, please speak up! cc:ing cvs-ghc@ in case they have any users of the frames due to the size of the GHC code base. (This might have been the the original motivation for the feature). Thanks, David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Is anyone using Haddock's support for frames?
2010/5/4 Sean Leather leat...@cs.uu.nl: Somewhat OT, but is there a place where we can request/review features in the new HTML presentation of Haddock. Are there any mockups of what the pages might look like? I've had some ideas pop around my head every time I look at documentation. ;) http://trac.haskell.org/haddock/ticket/108 Or feel free to open a discussion on hadd...@projects.haskell.org. Ideas very welcomed! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock infix constructors in markup
2010/4/26 Daniel Fischer daniel.is.fisc...@web.de: Am Montag 26 April 2010 22:18:53 schrieb Daniel Fischer: Am Montag 26 April 2010 22:05:48 schrieb Ozgur Akgun: So, how can we make use of this fix? My guess: $ cabal install haddock-2.7.2 No, it's not yet in there :( Yes, I should make a new release. In the meantime, you could try darcs get http://code.haskell.org/haddock David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock infix constructors in markup
2010/4/26 Daniel Fischer daniel.is.fisc...@web.de: Am Montag 26 April 2010 18:15:02 schrieb Ozgur Akgun: Hi all, If I have the following data type: data Expr = Num Int | Expr :+: Expr | Expr :-: Expr Haddock handles the infix constructors, and generates a very nice output (html in this case) However when I try to reference to one of the infix constructors in the markup of other functions it fails to hyperlink. -- | If the input is 'Num' does magic, if it is ':+:' does even more magic! someFunc :: Expr - Expr In the output of this markup, the 'Num' is hyperlinked but the ':+:' is not. Is there a different syntax for infix constructors (and for infix functions presumably) or does haddock simple lack this feature? Infix functions work fine (try referring to e.g. '' in the haddock comment), but infix constructors apparently not. Yes, I actually fixed this a few weeks ago in Haddock's lexer. Colon was just not included in the character set for identifiers. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project: A Haddock + Pandoc documentation tool
2010/4/9 Johan Tibell johan.tib...@gmail.com: On Fri, Apr 9, 2010 at 4:35 AM, Mark Lentczner ma...@glyphic.com wrote: On Apr 8, 2010, at 6:55 PM, ViaToR (Alvaro V.) wrote: I just finished writing my GSoC proposal ... The project is about creating a new documentation tool for Haskell projects,... I've taken a brief look and this looks lovely. I'm currently deep at work on re-coding the Haddock backend to produce semantic XHTML rather than table-nested HTML. I'm pretty familiar now with the internals of the backends of Haddock and would be happy to help you. General GSoC question: Would this be good time to offer to be a mentor? Do we have too many mentors or would it be useful for me to help out here? If so, do I need to register on the GSoC site today or tomorrow? Yes. Since you know Haddock well and care about the project you should definitely sign up. The student application deadline is today at 19:00 UTC. I think mentors can still join after that deadline (if I read the SoC timeline correctly) but I suggest signing up as a mentor today. During the next few weeks the mentors will decide which projects will get accepted and who will mentor them. I second this. We don't have too many mentors, and we need someone like you with good knowledge of HTML, CSS and the new Haddock backend to mentor a project like this. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project: A Haddock + Pandoc documentation tool
2010/4/9 ViaToR (Alvaro V.) alv...@gmail.com: Hello, I just finished writing my GSoC proposal and I want to have some feedback from the community. I'll try to be brief (this is not the proposal). The project is about creating a new documentation tool for Haskell projects, like Sphinx[1] for Python or Scribble[2] for Scheme. We have Haddock, which is a great tool. It can take the sources of a project and generate a useful API reference. But the reference is just a fragment of the whole project documentation. So, Haddock can only do a part of what Sphinx can do. But we have another tool, Pandoc, that takes files of whatever markup language and transform it to another format. And this is the more general-purposed part of Sphinx that is missing in Haddock. So we have the tools for creating documentation as useful as other systems, we just need the glue and several improvements. To achieve this project, first I'll have to use Haddock as an API. Currently, the Haddock API is rudimentary and highly experimental, so I would have to extend and test it. Then I would have to write a Haddock backend which would generate the reference in an internal independent pandoc format [3]. Finally I would have to write a new command-line program that would manage the projects or I would have to add Pandoc support in Haddock command-line program or Haddock support in Pandoc. IMHO, I think that will be better a new command-line program, everyone with its own purpose. I created an example of what would be a library documented with this system [4]. The file contains a configuration file a la cabal, a reST file (It could be markdown) and the html output. I tried to represent that the html output for the reference have to be almost the same that generates Haddock (css may differ). Note that all the entries of the Haddock reference are first-citizens entities in the documentation, so you can refer to the entries, render one entry, all or by groups (there are examples in the reST file). I am looking forward your impressions and suggestions. My main concerns are: 1) Two places containing the API reference. In your example documentation the API reference is included in one of the chapters. Wouldn't it be better to just have it in one place - the Haddock docs? 2) Integration with Haddock docs. I think it would be best if the pages generated by this system and the pages generated by Haddock would be integrated as much as possible - both style wise (sharing CSS, structure, headers, footers, sidebars etc) and also in terms of hyper linking. Identifiers in your documentation should go to the Haddock docs. It should feel as if the Haddock pages are just a part of the whole documentation structure. 3) Configuration I haven't looked at this yet but I suspect people will not want another configuration file in their projects. Perhaps you could propose some kind of Cabal integration instead. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project: A Haddock + Pandoc documentation tool
2010/4/9 Alvaro Vilanova Vidal (viator) alv...@gmail.com: 2) Integration with Haddock docs. I think it would be best if the pages generated by this system and the pages generated by Haddock would be integrated as much as possible - both style wise (sharing CSS, structure, headers, footers, sidebars etc) and also in terms of hyper linking. Identifiers in your documentation should go to the Haddock docs. It should feel as if the Haddock pages are just a part of the whole documentation structure. I agree, and I tried to represent that in the example (but I created a new css). All the documentation will be rendered by Pandoc so there is no difference between the format of each side. [...] If we want /one/ API reference (and not one generated by Pandoc and one generated by Haddock), then I think we need to generate it in XHTML format directly. There is no sensible way to transmit all the semantic information we need to be able to style and layout the different Haskell declaration through the markup languages supported by Pandoc. One can embed HTML but I suspect it's not the right solution. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GSoC Project: A Haddock + Pandoc documentation tool
2010/4/9 Alvaro Vilanova Vidal (viator) alv...@gmail.com: 3) Configuration I haven't looked at this yet but I suspect people will not want another configuration file in their projects. Perhaps you could propose some kind of Cabal integration instead. That would be awesome. I have to see how Cabal handles these files. Here's the relevant Cabal ticket: http://hackage.haskell.org/trac/hackage/ticket/330 David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] ANNOUNCE: Haddock 2.7.0
-- Haddock 2.7.0 A new version of Haddock, the Haskell documentation tool, is out! -- Changes in version 2.7.0 * Instances can be commented * The Haddock API now exposes more of the internals of Haddock * Bug fixes (most importantly #128) -- Links Homepage: http://www.haskell.org/haddock Hackage page: http://hackage.haskell.org/package/haddock-2.7.0 Bugtracker and wiki: http://trac.haskell.org/haddock Mailing list: hadd...@projects.haskell.org Code repository: http://code.haskell.org/haddock -- Contributors The following people contributed patches to this release: Isaac Dupree Yitzchak Gale David Waern -- Get Involved We would be very happy to get more contributors. To get involved, start by grabbing the code: http://code.haskell.org/haddock Then take a look at the bug and feature tracker for things to work on: http://trac.haskell.org/haddock ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] haddock forgets parens in type sigs?
2010/2/12 Johannes Waldmann waldm...@imn.htwk-leipzig.de: The annotated type of update is missing parentheses: http://hackage.haskell.org/packages/archive/haskelldb/0.12/doc/html/Database-HaskellDB.html#v%3Aupdate (compare with the signature given in the source) - Best, J.W. Already fixed in the darcs version. Stay tuned for the next release. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Strange Haddock output
2010/2/9 Sean Leather leat...@cs.uu.nl: I was browsing Hackage pointlessly and came across what appears to be strange Haddock formatting here: http://hackage.haskell.org/packages/archive/pointless-haskell/0.0.3/doc/html/Generics-Pointless-Functors.html#v%3Afmap The following source -- | Polytypic 'Prelude.Functor' class for functor representations class Functor (f :: * - *) where fmap :: Fix f -- ^ For desambiguation purposes, the type of the functor must be passed as an explicit paramaeter to 'fmap' - (x - y) - Rep f x - Rep f y -- ^ The mapping over representations produces the following view from the browser class Functor f where Polytypic Prelude.Functor class for functor representations Methods fmap :: = Fix f - x - y - Rep f xThe mapping over representations - Rep f y with the Haddock 2.6.0 on Hackage. There seems to be an extraneous = in the signature of fmap, and the comment on Fix f does not show up. I think this is an instance of a bug introduced when implementing cross-package documentation. It has been fixed already and will be in the next minor release. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Strange Haddock output
I think this is an instance of a bug introduced when implementing cross-package documentation. It has been fixed already and will be in the next minor release. Sorry, I should have said that the /fix/ will be in the next minor release, and not the bug, of course :-) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GHC/base API documentation has been generated incorrectly
2010/2/3 John Millikin jmilli...@gmail.com: Looking at (for example) the docs for 'bracket'[1], the parameter documentation has been shifted up by one. The source code[2] looks correct, so perhaps Haddock is parsing it incorrectly? Docs for other functions, such as 'showSigned'[3], exhibit the same error. Hi John, This has already been fixed and the fix will be in the next release. Thanks, David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Include creation date in Haddock documentation
2010/1/29 Dennis Walter dennis.wal...@gmail.com: Hi all, I wonder if it is possible to have Haddock include the date and time at which the documentation was generated. Ideally this should only occur on index.html, but to have it in any file (e.g. in the footer) would be OK, too. I couldn't find any information about dates in the documentation. Documentation is created via Cabal: cabal haddock --executables --hyperlink-source Right now I include a token in the Cabal description field of the package, and sed-replace it afterwards, which is of course ugly. It's not possible at the moment AFAIK, but we could add it. I've created a ticket: http://trac.haskell.org/haddock/ticket/131 David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] GHC bug? Cabal bug? Haddock bug?
2010/1/17 Mark Lentczner ma...@glyphic.com: AHA! Note that after running cabal haddock we re-build all of our .hi and .o files EXCEPT ./dist/build/HSsyb-with-class-0.6.1.o And now, since TH generates random symbols, we have symbols in the new .hi files that aren't in the old (and only) HSsyb-with-class-0.6.1.o. So, this leaves us with two questions: 1) Why does cabal haddock rebuild the .hi and .o files? On the face of it, this seems odd: Build documentation and your library gets rebuilt? Maybe this has already been answered elsewhere: when TH is involved Haddock may rebuild your library. In this case Cabal is directing Haddock's output to the same place that is used for normal builds. This bug has been fixed in Cabal. 2) Why doesn't Instances.o get rebuilt? Surely this has something to do with the fact that Instances.hs contains only orphan instances. But any answer here just leads to a raft of other questions: Surely this problem would plague other modules have have similar source files? What is Haddock doing? If Haddock needs the .hi files, why not just use them? If it just builds them to be sure, why in the dist tree and not some place temporary? If is going to build .o files, why not all? Not sure why Instances.o isn't rebuilt. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock question: hiding internal instances
2010/1/15 Niklas Broberg niklas.brob...@gmail.com: Hi all, The question I have is this: How can I get Haddock to omit listing instances of package-internal data types for exported classes? You currently can't, unfortunately. See: http://trac.haskell.org/haddock/ticket/37 David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] ANNOUNCE: Haddock 2.6.0
-- Haddock 2.6.0 A new version of Haddock, the Haskell documentation tool, is out! This is the version that comes with GHC 6.12.1. It contains the main results of Isaac Dupree's Summer of Code project, which are: * Cross-package documentation (exporting something that comes from another package is handled correctly. The full documentation of that thing shows up in your documentation) * Lexing and parsing of Haddock comment markup is moved from GHC back into Haddock. This will make it easier to make changes to the markup format We have decided to drop compatibility with older GHC versions in order to speed up development. -- Full list of changes in version 2.6.0 * Drop support for GHC 6.10.* * Add support for GHC 6.12.1 * Cross-package documentation * Move lexing and parsing of the Haddock comment markup back to Haddock * Slightly prettier printing of instance heads * Support platforms for which GHC has no native code generator * Add a flag --print-ghc-libdir * Minor bug fixes -- Links Homepage: http://www.haskell.org/haddock Hackage page: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/haddock-2.6.0 Bugtracker and wiki: http://trac.haskell.org/haddock Mailing list: hadd...@projects.haskell.org Code repository: http://code.haskell.org/haddock -- Contributors The following people contributed patches to this release: Isaac Dupree Ian Lynagh Simon Peyton-Jones David Waern -- Get Involved We would be very happy to get more contributors. To get involved, start by grabbing the code: http://code.haskell.org/haddock Then take a look at the bug and feature tracker for things to work on: http://trac.haskell.org/haddock ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] haddock: parse error in doc string
2009/8/26 Peter Verswyvelen bugf...@gmail.com: Ouch, with all the great Haskell parsers like Parsec around I think I was expecting a line/column number :-) But I see a ticket is already open for this http://trac.haskell.org/haddock/ticket/83 Yes, and the line-number part of that ticket has been fixed in 2.4.2 and higher versions. So the best idea is to upgrade Haddock. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] haddock: parse error in doc string
2009/8/26 Peter Verswyvelen bugf...@gmail.com: Oh, I just installed the Haskell platform. I have Haddock version 2.4.2, (c) Simon Marlow 2006 Ported to use the GHC API by David Waern 2006-2008 But I noticed that my bad comments were in the description of the cabal file, not the source file. So that might be a new ticket? My guess is that Cabal passes the description via the --prologue flag and Haddock doesn't print which file it was passed. I'll fix this for the next release, you don't have to file a ticket. Thanks, David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] ANN: Haddock version 2.5.0
2009/8/16 por...@porg.es: George Porges s/Porges/Pollard/; Porges is just an alias :) Oh, sorry about that! I tried to google on your email address but didn't find anything, so I assumed Porges was your surname. I should start sending out my release notes for revivew ;-) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Blank definition list in haddock
2009/8/16 Maurício CA mauricio.antu...@gmail.com:
I read in haddock documentation that we write
definition lists like this:
-- �...@something@] Definition of something.
However, using that structure to document many
itens, I get a blank list of definitions, like
you can see in this section ('Macros') of the
documentation for a package of mine:
http://hackage.haskell.org/packages/archive/bindings-common/0.2.2/doc/html/Bindings.html#3
However, as can be seen in the source code, there
are many definitions inside 'Macros' section.
http://hackage.haskell.org/packages/archive/bindings-common/0.2.2/doc/html/src/Bindings.html
Did I used those definitons the wrong way?
I think the problem is that you have written normal comments instead
of Haddock comments. Try adding a | in front of the paragraphs, or
just merge them all into one Haddock comment by inserting -- in
front of the blank lines in between your paragraphs.
David
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] ANN: Haddock version 2.5.0
-- Haddock 2.5.0 A new version of Haddock, the Haskell documentation tool, is out! If you're using GHC 6.10.2 and Haddock 2.4.2, you should be able to upgrade to this version without any problem. If you're using something else, you should re-install any documentation that you want to link to after upgrading. Please use the bug tracker to submit bug reports or feature requests. -- Changes in version 2.5.0 * Drop support for GHC 6.8.* * Add support for GHC 6.10.3 and 6.10.4 * Revert to the old multi-page index for large packages (#106) * Show GADT records in the generated documentation * Create the output directory if it doesn't exist (#104) * Use the native codegen instead of compiling via C for TH modules * Add --use-unicode flag for displaying prettier versions of common symbols * Mutiple verbosity levels: remove --verbose and add --verbosity=n * Simpler versioning of .haddock files To avoid slow search, Haddock switches from the searchable index to the old multi-page index for large packages (containing over 150 items). This, and support for GADT records in the generated documentation was implemented by Isaac Dupree as part of his Summer of Code project. The --use-unicode flag was contributed by George Porges. -- Links Homepage: http://www.haskell.org/haddock Hackage page: http://hackage.haskell.org/package/haddock-2.5.0 Bugtracker and wiki: http://trac.haskell.org/haddock Mailing list: hadd...@projects.haskell.org Code repository: http://code.haskell.org/haddock -- Contributors The following people contributed patches to this release: Isaac Dupree Ian Lynagh Simon Marlow Simon Peyton-Jones George Porges David Waern -- Future Plans Here are the top priority tickets right now: * Cross-package documentation (#24) * Good warning messages when encountering unexpected Haddock comments (#94) * Comments on instance declarations (#29) Isaac Dupree has been working on the first item as part of his SoC project and it is near completion. If you have any input on what we should prioritize, add yourself to the CC list of the ticket(s) that you are interested in. -- Get Involved We would be very happy to get more contributors. To get involved, start by grabbing the code: http://code.haskell.org/haddock Then take a look at the bug and feature tracker for things to work on: http://trac.haskell.org/haddock ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] ANN: Haddock version 2.5.0
2009/8/15 Magnus Therning mag...@therning.org: David Waern wrote: -- Haddock 2.5.0 A new version of Haddock, the Haskell documentation tool, is out! If you're using GHC 6.10.2 and Haddock 2.4.2, you should be able to upgrade to this version without any problem. If you're using something else, you should re-install any documentation that you want to link to after upgrading. Please use the bug tracker to submit bug reports or feature requests. -- Changes in version 2.5.0 * Drop support for GHC 6.8.* * Add support for GHC 6.10.3 and 6.10.4 Hmm, does this mean that GHC 6.10.4 ships with a version of Haddock that doesn't handle the compiler it ships with? Doh. You are right, both 2.4.2 and 2.5.0 work with GHC 6.10.*. Should not have been added to CHANGES. Thanks, David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: Strangeness in the syntax of types
2009/6/18 Niklas Broberg niklas.brob...@gmail.com:
GHC:
ctypedoc :: { LHsType RdrName }
: 'forall' tv_bndrs '.' ctypedoc
| context '=' ctypedoc
| gentypedoc
Notice GHC's recursive call to ctypedoc after the =. I have no idea
what the doc suffix on the production is intended to indicate though -
and I was curious to find a separate set of rules that don't have that
suffix:
The doc suffix says can contain Haddock comments.
ctype :: { LHsType RdrName }
: 'forall' tv_bndrs '.' ctype
| context '=' type
| type
This one looks just like the one that haskell-src-exts uses - type
instead of ctype after the =.
You're not looking at the latest version of the code. I'm guessing
you're looking at the stable version instead of the HEAD. In HEAD we
have:
ctypedoc :: { LHsType RdrName }
: 'forall' tv_bndrs '.' ctypedoc{ LL $ mkExplicitHsForAllTy $2
(noLoc []) $4 }
| context '=' ctypedoc { LL $ mkImplicitHsForAllTy $1 $3 }
-- A type of form (context = type) is an *implicit* HsForAllTy
| ipvar '::' type { LL (HsPredTy (HsIParam (unLoc $1)
$3)) }
| typedoc { $1 }
This should accept both
multipleCtx :: (Eq a = Show a = a)
multipleCtx = undefined
and
multipleCtx :: Eq a = Show a = a
multipleCtx = undefined
The reason why ctypedoc and ctype were so different before, is because
they drifted apart after ctypedoc was added. ctype was changed (I
think during implementation of the TypeFamilies extension) without any
changes to ctypedoc. This was fixed in HEAD not so long ago.
If you need more information I can dig up the trac ticket :-)
David
___
Glasgow-haskell-users mailing list
Glasgow-haskell-users@haskell.org
http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Re: [Haskell-cafe] Re: Haddock : parse error on input `{-# UNPACK'
2009/6/7 Dominic Steinitz domi...@steinitz.org:
Ha! It's yet another of haddock's quirks. If I replace -- ^ by -- then haddock
accepts {-#. I'll update the ticket you created.
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- ^ input
{-# UNPACK #-} !Int -- ^ bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- ^ the failure depth
-- | The parse state
data S = S {-# UNPACK #-} !BL.ByteString -- input
{-# UNPACK #-} !Int -- bytes read
{-# UNPACK #-} ![B.ByteString]
{-# UNPACK #-} !Int -- the failure depth
Haddock doesn't actually support comments on individual constructor
arguments. People often get confused by this, and the error message
isn't especially useful. We have a ticket for giving better error
messages:
http://trac.haskell.org/haddock/ticket/94
We also have a ticket about the feature itself:
http://trac.haskell.org/haddock/ticket/95
David
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] hackage version scheme survey
2009/5/24 br...@lorf.org: Maybe most of the a.b people are thinking major.minor, and most of the a.b.c people are thinking breaking.feature.implementation like the rational RubyGems scheme described in http://rubygems.org/read/chapter/7#page24 , but I don't know. It makes it hard to describe dependencies. Will there be a standard versioning scheme sometime? We have one already: http://www.haskell.org/haskellwiki/Package_versioning_policy David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: haddock could be a pretty-printer?
2009/5/22 Maurício briqueabra...@yahoo.com: The new version of haddock makes use of GHC parser. How much of effort would take to make haddock generate pretty-print of the source code itself, (...) (...) Is this what you want or is there some reason why you want the code to be pretty-printed? I usually have to resort to braces or bad indenting to get code to parse, but I like to give it good presentation before publishing. I used to pretty-print my code using haskell-src-exts with great result, but that kills documentation. I think the plan is to extend haskell-src-exts to retain comments. But if you want something that works now, you could use the GHC API. It has support for getting the token stream of a module, which contains the comments as tokens. Using Haddock to do this is not a good idea, better use the GHC API directly. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] haddock could be a pretty-printer?
2009/5/22 Maurício briqueabra...@yahoo.com: Hi, The new version of haddock makes use of GHC parser. How much of effort would take to make haddock generate pretty-print of the source code itself, including haddock documentation (although probably loosing other comments)? Maybe even an html version that documentation could point to? You can use hscolour to output source code in HTML form and Haddock can generate links to it if you use the --source-* flags. Most documentation on Hackage seems to make use of this. Is this what you want or is there some reason why you want the code to be pretty-printed? David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Problem with haddock importing definition
2009/5/15 Maurício briqueabra...@yahoo.com: Hi, I have a situation like this: module A imports R (a newtype declaration) from module B, and lists it in its (module A) export list. Documentation for R is included by haddock in documentation for module A, as I want. However, if my package exposes only module A, documentation for R desapears. Hi Mauricio, sorry for the late reply. When you say documentation disappears, do you mean that R is still listed, but its comments are not shown, or is R completely absent from the documentation? Thanks, David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Problem with haddock importing definition
2009/5/20 Ross Paterson r...@soi.city.ac.uk: On Wed, May 20, 2009 at 09:42:19AM +0200, David Waern wrote: 2009/5/15 Maurício briqueabra...@yahoo.com: I have a situation like this: module A imports R (a newtype declaration) from module B, and lists it in its (module A) export list. Documentation for R is included by haddock in documentation for module A, as I want. However, if my package exposes only module A, documentation for R desapears. When you say documentation disappears, do you mean that R is still listed, but its comments are not shown, or is R completely absent from the documentation? See http://trac.haskell.org/haddock/ticket/107 He just needs to include B in the other-modules list, so that cabal will pass it to haddock (and setup sdist). Yes, that is a solution that he can use. I would still like to know the answer to my question though, since I think we can improve Haddock here. Haddock is given a list of modules on the command line, for which it should create documentation pages. Before Haddock used GHC, it could not do dependency analysis, so you had to give it both the modules you wanted pages for, and their dependencies. Nowadays we do dependency analysis, since we have to typecheck all modules. But we still only do documentation-processing for the given modules (I think). This could explain why F appears in the documentation, but without comments, when only module A is specified on the command line (assuming this is indeed the problem). In that case we should enhance Haddock so that it processes all modules but only creates documentation pages for the specified modules. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Problem with haddock importing definition
2009/5/20 Maurício briqueabra...@yahoo.com: I would still like to know the answer to my question though, since I think we can improve Haddock here. R is completely absent from documentation. OK. That's strange. I thought that Haddock would at least show R but without a link. I did include a working example with .cabal file in that ticket, maybe that can help. (Just to note, my problem was solved by 'other-modules'.) I saw that - thanks. Couldn't investigate it yet since I'm at work :-) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: Inter-module links with Haddock broken?
2009/4/28 Sven Panne sven.pa...@aedion.de: Am Samstag, 25. April 2009 14:48:03 schrieb Sven Panne: Currently I am unable to make inter-module links (of the form 'Foo.Bar.baz') work with the Haddock shipped with GHC 6.10.2. [...] Until a few moments ago, I wasn't aware of the fact that Haddock has a trac for itself nowadays, so I guess my problem is a symptom of: http://trac.haskell.org/haddock/ticket/78 What is the schedule for the Haddock milestone 2.5.0 mentioned in that ticket? When can we expect that fix in a shipped GHC? We have no schedule yet. I will just release it when I have had time to fix enough bugs that it's worth making a release. Help wanted :-) I'm not sure if we can do Haddock fixes for 6.10.3. Can we? Otherwise an updated Haddock will not ship with GHC until 6.12.1. Not sure if Haddock will be installed by GHC installations in the future though, since I think the Haskell Platform is supposed to manage that. Is this correct? David ___ Glasgow-haskell-bugs mailing list Glasgow-haskell-bugs@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-bugs
Re: ghc-pkg check problem in 6.10.2
2009/4/2 Simon Marlow marlo...@gmail.com: I just noticed that the new 'ghc-pkg check' feature exposes a silly mistake in the definition of the rts package that we ship with GHC 6.10.2: $ ghc-pkg check There are problems in package rts-1.0: include-dirs: PAPI_INCLUDE_DIR doesn't exist or isn't a directory ... To fix it, issue this command: $ ghc-pkg describe rts | sed 's/PAPI_INCLUDE_DIR//' | ghc-pkg update - and now ghc-pkg check should give no errors: $ ghc-pkg check $ (Except on Windows, where there also seems to be a problem with the Haddock package. Haddock itself is ok, but the Haddock library has some problems with its registration.) Oh, which problems? David ___ Glasgow-haskell-users mailing list Glasgow-haskell-users@haskell.org http://www.haskell.org/mailman/listinfo/glasgow-haskell-users
Re: [Haskell-cafe] Announcement: Beta of Leksah IDE available
2009/4/2 Duncan Coutts duncan.cou...@worc.ox.ac.uk: On Wed, 2009-04-01 at 22:13 +0200, David Waern wrote: 2009/4/1 jutaro j...@arcor.de: I guess you mean the dialog which should help leksah to find sources for installed packages. It needs this so you can go to all the definitions in the base packages ... This is very handy if it works. Look to the manual for details. Maybe could add support to Cabal for installing sources? Should be very useful to have in general. http://hackage.haskell.org/trac/hackage/ticket/364 Jutaru, perhaps a nice Hackathon project? :-) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Announcement: Beta of Leksah IDE available
2009/4/1 jutaro j...@arcor.de: I guess you mean the dialog which should help leksah to find sources for installed packages. It needs this so you can go to all the definitions in the base packages ... This is very handy if it works. Look to the manual for details. Maybe could add support to Cabal for installing sources? Should be very useful to have in general. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] ANNOUNCE: Haddock 2.4.2
-- Haddock 2.4.2 A new version of Haddock, the Haskell documentation tool, is out. This is a bug fix release only, and it's the same version that will ship with GHC 6.10.2, unless any important problems are discovered before the GHC release. Because the .haddock file format has changed, links to previously installed documentation will not work when generating documentation using this version. Please use the bug tracker to submit bug reports or feature requests. -- Changes in version 2.4.2 * Support for GHC 6.10.2 * Haddock no longer crashes on Template Haskell modules (#68) (only with GHC 6.10.2 or above) * Fix problem with Template Haskell-generated declarations disappearing (#59) * Generate two anchors for each link for compatibility between IE and Opera (#45) * Improved error messages * Show re-exports from external packages again (GHC ticket #2746) * Store hidden modules in .haddock files again (needed by the haddock library) * Avoid processing boot modules * Pragmas may exist between document comments and declarations * Do not indicate that a constructor argument is unboxed * Fix problem with non-working links to ghc-prim * Allow referring to a specific section within a module in a module link (#65) * Fixes to the Hoogle backend * Improvements to the haddock library * Many other fixes (including #67, #69, #58, #57) -- Links Homepage: http://www.haskell.org/haddock Hackage page: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/haddock-2.4.2 Bugtracker and wiki: http://trac.haskell.org/haddock Mailing list: hadd...@projects.haskell.org Code repository: http://code.haskell.org/haddock -- Contributors The following people contributed patches to this release: Joachim Breitner Roman Cheplyaka Ian Lynagh Neil Mitchell Simon Peyton-Jones Thomas Schilling David Waern -- Get Involved We welcome new contributors. To get involved, start by grabbing the code: http://code.haskell.org/haddock Then take a look at the bug and feature tracker for things to work on: http://trac.haskell.org/haddock ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Problem with haddock - it dislikes my comments
2009/2/28 Colin Paul Adams co...@colina.demon.co.uk: Colin == Colin Paul Adams co...@colina.demon.co.uk writes: Gwern == Gwern Branwen gwe...@gmail.com writes: Gwern On Sat, Feb 28, 2009 at 2:59 PM, Colin Paul Adams Gwern co...@colina.demon.co.uk wrote: Having just read the Haddock manual , I am haddocking (may I copyleft that verb?) my code. But half-way through this data type, I discover that haddock rejects my non-haddock comments, although GHC is fine: How can I document the components of each constructor? Gwern http://trac.haskell.org/haddock/ticket/60 ? Colin That seems to be a different bug - my haddock comments are Colin accepted fine - it's the plain Haskell ones (no ^) that it Colin complains about as a parse error. No, I'm wrong - it does seem to be the same problem. In fact, it's not. I've added two new tickets for your problem: http://trac.haskell.org/haddock/ticket/95 http://trac.haskell.org/haddock/ticket/94 Since the ticket has been downgraded to a minor problem, it seems the Haddock team doesn't want to allow documentation of components, except when they are named fields. Again, not the same problem. The ticket is about documenting empty data declarations on the same line, e.g: data Empty -- ^ A comment Since you can just put the comment above or below the declaration, I consider it a minor problem. We have more serious bugs to focus on :) The new tickets for your problem have been assigned major priority, though. Thanks, David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Missing documentation for Haddock
2009/2/27 Colin Paul Adams co...@colina.demon.co.uk: On http://haskell.org/haddock/doc/html/module-attributes.html the not-home attribute is missing (it's documentation is present, but the attribute itself is not named). Thanks for the report. By the way, the Haddock trac page is at: http://trac.haskell.org/haddock We also have a mailing list: hadd...@projects.haskell.org I will fix this bug directly, so we don't need a bug ticket of course. But it may be nice for you to know where to report bugs in the future. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: [Haskell] Google Summer of Code 2009
2009/2/11 Gwern Branwen gwe...@gmail.com: [^complaints]: I can hear the wankers in the peanut gallery - Yeah, and it's been buggy ever since! Hush you. Those (aforementioned) people should keep in mind we tried to keep the scope of the project down to just making the new Haddock support the features of the old Haddock (no type inference, docs for GHC extensions, etc). Most of the bugs concerning the pre-GHC subset of Haddock have now been fixed (although there are a few left). Most other problems we're currently seeing is with GHC extensions, like for instance Template Haskell.You should not blame the SoC project so much for this (although it could have handled extensions more gracefully). The project was also run in a time when the GHC API was not so evolved and had a bug or two. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] 1,000 packages, so let's build a few!
2009/1/31 Andrew Coppin andrewcop...@btinternet.com: In celebration of Hackage reachin over 1,000 unique packages, I decided that I would re-visit the problem of attempting to build them on Windows. I began by removing all existing Haskellness from my PC. I now have a vanilla Windows XP (32-bit) system with Service Pack 3. So, let's see what we can do here... - Install GHC 6.10.1. As you'd expect, no issues here. - Now, let's install stream-fusion. First let me ch... woah! What the hell? OK, it seems that Google is temporarily broken. (All websites show up as this site may damange your computer.) Obviously this has nothing to do with Haskell, but it makes navigating Hackage moderately more tedious. Oh well, anyway, where was I? Ah yes, I already have the tarball for stream-fusion-0.1.1, but I see that the latest release is 0.1.2.1. (Unfortunately, there doesn't appear to be any way to determine what the difference is between the two versions...) - Right, I've got the tarball for stream-fusion. Now let's see if it will install... J:\Haskell\unpack runhaskell Setup configure J:\Haskell\unpack runhaskell Setup build J:\Haskell\unpack runhaskell Setup install J:\Haskell\unpack ghc-pkg list ...stream-fusion-0.1.2.1... OK, nothing much wrong with that then. :-D - Hmm, doesn't GHC 6.10.1 now come with Haddock included? I wonder if there's a way to ask Cabal to build the docs for me... [Grr! Google is still busted.] Ah, yes there is. OK, let's try this: J:\Haskell\unpack runhaskell Setup haddock ... Data\Stream.hs:292:33: parse error on input `!' haddock: Failed to check module: Data.Stream Uh... OK. So I guess I *won't* build the docs for that one then. :-/ Oh well, maybe it's a one-off failure? Let's try some more packages... The problem there is that stream-fusion is trying to put documentation on individual data constructor arguments which is not supported by Haddock. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: Haddock
2009/2/6 Max Rabkin max.rab...@gmail.com: On Thu, Feb 5, 2009 at 4:25 PM, David Waern david.wa...@gmail.com wrote: As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. I personally find it useful to have Haddock comments readable in the source. And aren't there security issues, too? So we'd have to have an option to disable them, which would have to be on by default, and basically they would be disabled by everybody but the writers of the comments themselves. I think you can invoke any command using Setup.hs and Cabal already. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
2009/2/6 Alistair Bayley alist...@abayley.org: [1 of 1] Compiling Test.Fail( Test\Fail.hs, Test\Fail.o ) Test\Fail.hs:11:26: Can't make a derived instance of `Typeable Fail' (You need -XDeriveDataTypeable to derive an instance for this class) In the data type declaration for `Fail' Are you processing the above module but it is called Test.Fail in reality? Have you stripped out a deriving statement from the example above? I'm very confused by this message :) Sorry, my mistake. I pasted the error message from a different problem. This is the error I get from haddock: C:\bayleya\eclipse\workspace\takusen\srchaddock -h --odir=doc Test/Haddock.lhs Cannot find documentation for: $named_block Okay, then I understand. My guess is (without looking at ghc code) that ghc just throws the literate comments away before lexing the file. This means that the Haddock comments won't be recognized. As you say, there is also an unlitter in Cabal. I don't remember if it is invoked when using Haddock 2, but if it is, it would solve this problem. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: haddock-2.3.0 literate comments discarded from .lhs input
2009/2/6 Alistair Bayley alist...@abayley.org: I have this test case for Haddock (2.3.0): -- | Module : Test.Haddock Copyright : (c) 2009 Alistair Bayley License : BSD-style Maintainer : alist...@abayley.org Stability : stable Portability : portable Test case for Haddock. module Test.Haddock ( -- $named_block Fail(..) ) where data Fail = Fail | Succeed $named_block This is some hadock documentation. -- This fails with: [1 of 1] Compiling Test.Fail( Test\Fail.hs, Test\Fail.o ) Test\Fail.hs:11:26: Can't make a derived instance of `Typeable Fail' (You need -XDeriveDataTypeable to derive an instance for this class) In the data type declaration for `Fail' Are you processing the above module but it is called Test.Fail in reality? Have you stripped out a deriving statement from the example above? I'm very confused by this message :) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: build problems on Hackage
2009/2/5 Ross Paterson r...@soi.city.ac.uk: On Thu, Feb 05, 2009 at 10:41:20AM +0100, Wolfgang Jeltsch wrote: type-level built fine with GHC 6.8 but failed to build with GHC 6.10. The last line of the build log is this: haddock: internal Haddock or GHC error: Maybe.fromJust: Nothing Yes, haddock 2.4.1 (the most recent release) bombs on Data.TypeLevel.Num.Aliases. In Haddock 2.4.0 we switched from using the compilation mode of the GHC API to a mode which does only typchecking. This broke Template Haskell support: http://trac.haskell.org/haddock/ticket/68 The problem is fixed in Haddock 2.4.2 which will be released with GHC 6.10.2. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: build problems on Hackage
2009/2/5 Ross Paterson r...@soi.city.ac.uk: On Thu, Feb 05, 2009 at 03:05:44PM +0100, David Waern wrote: In Haddock 2.4.0 we switched from using the compilation mode of the GHC API to a mode which does only typchecking. This broke Template Haskell support: http://trac.haskell.org/haddock/ticket/68 The problem is fixed in Haddock 2.4.2 which will be released with GHC 6.10.2. Haddock 2.4.2 uses a different interface file format, right? (Not an insuperable problem -- just asking.) Yep, that's right. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Re: build problems on Hackage
2009/2/5 Ross Paterson r...@soi.city.ac.uk: On Thu, Feb 05, 2009 at 03:03:35PM +0100, Wolfgang Jeltsch wrote: Am Donnerstag, 5. Februar 2009 13:16 schrieb Ross Paterson: On Thu, Feb 05, 2009 at 10:41:20AM +0100, Wolfgang Jeltsch wrote: type-level built fine with GHC 6.8 but failed to build with GHC 6.10. The last line of the build log is this: haddock: internal Haddock or GHC error: Maybe.fromJust: Nothing Yes, haddock 2.4.1 (the most recent release) bombs on Data.TypeLevel.Num.Aliases. Hackage uses Haddock 2.3.0, doesn't it? The build client uses 2.4.1. I just tried with 2.3.0, and saw the same problem. Oh, I'm sorry, seem like the problem was introduced in 2.3.0 (I should have checked the Trac ticket which clearly states that). I think 2.2.2 is fine, if that's of any help. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Re: Haddock
Hi everyone, I received this question from Lennart Augustsson (via Simon M) and thought I'd send out an inquiry to the Haskell community in general (Lennart, I hope you don't mind): Lennart writes: We have some local patches for haddock that extends the blah syntax so you can put TeX formulae in the documentation. It looks like, ! LaTeX stuff here !, but I'd like to extend it so you can process the string with any command. Are you interested in folding this into the main branch? So the question is about extending the Haddock markup language. When modifying the language we should think about the tension between familiarity, presentation features (pictures, math, whatever) and visual portability across different mediums (HTML, ghci, IDE tooltips, etc). And here I should say that Haddock already supports pictures using the url syntax. IMHO, adding ! LaTeX ! for TeX math is fine, because: - math in documentation is often useful - if you're going to write math, you need a format, even when the medium is plain text as in ghci. - TeX formulae seem to be relatively widely used and understood. As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. There was also a thread about Haddock markup on haskell-cafe@ about a year ago, which originated with the interesting idea of using Markdown (or a Pandoc-extended version of it) instead of the current language: http://www.mail-archive.com/haskell-cafe@haskell.org/msg38054.html I think the original idea there is pretty nice, but let's first focus on the current markup language in order to answer Lennart's question. That thread contains some useful opinions on this matter, also. So, any comments? :) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
[Haskell-cafe] Haddock Markup
I got the subject line wrong, so I'm reposting this: Hi everyone, I received this question from Lennart Augustsson (via Simon M) and thought I'd send out an inquiry to the Haskell community in general (Lennart, I hope you don't mind): Lennart writes: We have some local patches for haddock that extends the blah syntax so you can put TeX formulae in the documentation. It looks like, ! LaTeX stuff here !, but I'd like to extend it so you can process the string with any command. Are you interested in folding this into the main branch? So the question is about extending the Haddock markup language. When modifying the language we should think about the tension between familiarity, presentation features (pictures, math, whatever) and visual portability across different mediums (HTML, ghci, IDE tooltips, etc). And here I should say that Haddock already supports pictures using the url syntax. IMHO, adding ! LaTeX ! for TeX math is fine, because: - math in documentation is often useful - if you're going to write math, you need a format, even when the medium is plain text as in ghci. - TeX formulae seem to be relatively widely used and understood. As for running arbitrary commands, I think we are opening up to a lot of unfamiliar syntax. I'd like to hear what everyone thinks about that. There was also a thread about Haddock markup on haskell-cafe@ about a year ago, which originated with the interesting idea of using Markdown (or a Pandoc-extended version of it) instead of the current language: http://www.mail-archive.com/haskell-cafe@haskell.org/msg38054.html I think the original idea there is pretty nice, but let's first focus on the current markup language in order to answer Lennart's question. That thread contains some useful opinions on this matter, also. So, any comments? :) David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] haddock-2.3.0 error: file name does not match module name
2009/1/29 Alistair Bayley alist...@abayley.org: 2009/1/29 Matthijs Kooijman matth...@stdin.nl: I assume that it's procesing file Database.Enumerator.lhs when it emits this, but I'm puzzled because the module name in Database.Enumerator.lhs is certainly Database.Enumerator, and not Main. Any chance the module statement in the file is wrong? I think I remember seeing this error once when I accidentally typed Module instead of module. Apparently ghc assumes Main when there is no valid module statement. It's not this, but it certainly looks like something similar is confusing haddock. This has been reported before: http://trac.haskell.org/haddock/ticket/73#comment:4 Not sure what's going on yet. If anyone's got a minimal test-case, that'd be great. David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Haddock bug for strict unpacked fields?
2009/1/21 Stephan Friedrichs deduktionstheo...@web.de:
Hi,
using haddock-2.4.1 and this file:
module Test where
data Test
= NonStrict Int
| Strict !Int
| UnpackedStrict {-# UNPACK #-} !Int
The generated documentation looks like this:
data Test
Constructors
NonStrict Int
Strict !Int
UnpackedStrict !!Int
Note the double '!' in the last constructor. This is not intended
behaviour, is it?
This is the way GHC pretty prints unboxed types, so I thought Haddock
should follow the same convention. Hmm, perhaps Haddock should have a
chapter about language extensions in its documentation, with a
reference to the GHC documentation. That way the language used is at
least documented. Not sure if it helps in this case though, since !!
is probably not documented there.
Perhaps we should not display unbox annotations at all since they are
an implementation detail, right? We could display one ! instead,
indicating that the argument is strict.
David
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
Re: [Haskell-cafe] Comments from OCaml Hacker Brian Hurt
2009/1/18 Don Stewart d...@galois.com: ross: On Sat, Jan 17, 2009 at 09:12:32PM -0500, a...@spamcop.net wrote: And FWIW, I agree with everyone who has commented that the documentation is inadequate. It'd be nice if there was some way to contribute better documentation without needing checkin access to the libraries. There is. The current state of the docs may be viewed at http://www.haskell.org/ghc/dist/current/docs/libraries/ Anyone can check out the darcs repos for the libraries, and post suggested improvements to the documentation to librar...@haskell.org (though you have to subscribe). It doesn't even have to be a patch. Sure, it could be smoother, but there's hardly a flood of contributions. I imagine if we set up a wiki-like system where the entire hackage docs could be edited, as well as viewed, we would end up with a flood. A modification to haddock perhaps, that sends edits to generated docs to libraries@ ? This has come up many times lately. I've created a ticket for it: http://trac.haskell.org/haddock/ticket/72 If anyone has suggestions for design or implementation of a system like this, don't hesitate to post to this ticket! David ___ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
