[Hackage] #936: Add Haddock-Options field to Cabal package description
#936: Add Haddock-Options field to Cabal package description ----------------------------------+----------------------------------------- Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.16 Component: Cabal specification | Version: 1.10.2.0 Severity: normal | Keywords: Difficulty: unknown | Ghcversion: Platform: | ----------------------------------+----------------------------------------- Currently when running 'runhaskell Setup haddock' I can pass options to Haddock with the --haddock-option and --haddock-options option. I would like to add some options in a Cabal description file analogously to the GHC-Options fields and others. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/936 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#936: Add Haddock-Options field to Cabal package description ----------------------------------+----------------------------------------- Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.16 Component: Cabal specification | Version: 1.10.2.0 Severity: normal | Keywords: Difficulty: unknown | Ghcversion: Platform: | ----------------------------------+----------------------------------------- Comment(by duncan): What would you want to add? In general we think it's inappropriate for the package author to specify haddock options, only the package builder. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/936#comment:1 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#936: Add Haddock-Options field to Cabal package description ----------------------------------+----------------------------------------- Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.16 Component: Cabal specification | Version: 1.10.2.0 Severity: normal | Keywords: Difficulty: unknown | Ghcversion: Platform: | ----------------------------------+----------------------------------------- Comment(by guest): I want to set the qualification style with the '--qual' option. This is new in Haddock-2.10. Since the qualification style depends on the used identifier convention, it is something that the package author should choose. If you think that general Haddock options do not fit into a Cabal file, maybe we can look for a subset of Haddock options and handle them in a special way. This could be similar to Extensions, where using the Extensions field is prefered to writing GHC-Options: -XExtension. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/936#comment:2 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#936: Add Haddock-Options field to Cabal package description ----------------------------------+----------------------------------------- Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.16 Component: Cabal specification | Version: 1.10.2.0 Severity: normal | Keywords: Difficulty: unknown | Ghcversion: Platform: | ----------------------------------+----------------------------------------- Comment(by duncan): Hmm, but this isn't something that authors want to specify on a per- file/module basis like other haddock directives? With haddock, the usual rule of thumb is that author-specified directives go in the source files themselves (e.g. hide, pune etc) while things the builder should specify are command line options (which we partially reflect as cabal haddock features or via --haddock-options). I found the bit in the user guide for `--qual` but I have to admit it's not clear to me the purpose or who should be setting it, and if it's really a package global or module local option. Is there any ticket or other discussion that gives some explanation or motivation for the feature? -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/936#comment:3 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#936: Add Haddock-Options field to Cabal package description ----------------------------------+----------------------------------------- Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.16 Component: Cabal specification | Version: 1.10.2.0 Severity: normal | Keywords: Difficulty: unknown | Ghcversion: Platform: | ----------------------------------+----------------------------------------- Comment(by guest): The feature request for the --qual option is in this ticket: http://trac.haskell.org/haddock/ticket/22 I am currently adding a mode that is close to the proposed 'orig' qualification mode. Currently Haddock only allows to set the qualification style globally. The reason is that you normally choose one style of identifiers for a whole package. E.g. identifiers in the 'stm' package always contain a suffix that reflects the module. You will usually write them unqualified. In contrast to that package 'bytestring' re-uses the same function names in different modules of the package and function names that are already present in Prelude. Thus you will certainly use those identifiers in a qualified way. In principle we could add a Haddock-PRAGMA for a per-module setting, but this seems to be less useful. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/936#comment:4 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#936: Add Haddock-Options field to Cabal package description ----------------------------------+----------------------------------------- Reporter: guest | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Cabal-1.16 Component: Cabal specification | Version: 1.10.2.0 Severity: normal | Keywords: Difficulty: unknown | Ghcversion: Platform: | ----------------------------------+----------------------------------------- Comment(by duncan): I think I see. So yes, it is a little like the current `default- extensions:` field which applies the extensions to all the modules in the package so you don't have to use LANGUAGE pragmas in each module. What I don't want is to have a general haddock-options field because most options are not applicable. Another alternative is to heavily restrict the allowed options, as we do for ghc, but a more explicit approach might be better. It's really a haddock global style thing, e.g. if haddock ever decided to allow markdown and that were enabled by a flag, that would be a similar one where it's the package author who decides. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/936#comment:5 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
participants (1)
-
Hackage