[Hackage] #330: Take non-haddock documentation in account
#330: Take non-haddock documentation in account ----------------------------+----------------------------------------------- Reporter: fons | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: Cabal library | Version: 1.2.3.0 Severity: normal | Keywords: Difficulty: normal | Ghcversion: 6.8.2 Platform: | ----------------------------+----------------------------------------------- The generation and installation of Non-Haddock documentation (README and INSTALL files, LaTeX and Docbook tutorials/guides, Haskell examples using the package in question) is not currently taken in account by Cabal. Making Cabal understand how to generate documentation for all those formats would probably be too ambitious, but it could be eased (e.g. letting the user provide Makefiles instead of creating custom hooks). More importantly, the installation of documentation would be much easier with a new package property such as "doc-files" ("data-files" nor "extra- source-files" are semantically suitable). -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/330 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#330: Support general documentation, not just haddock ----------------------------+----------------------------------------------- Reporter: fons | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: Cabal library | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ----------------------------+----------------------------------------------- Changes (by duncan): * summary: Take non-haddock documentation in account => Support general documentation, not just haddock Comment: See also #283. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/330#comment:1 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#330: Support general documentation, not just haddock ----------------------------+----------------------------------------------- Reporter: fons | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: Cabal library | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ----------------------------+----------------------------------------------- Comment (by duncan): We should look at what conventions we can standardise or establish. If we make it easy, perhaps that'll encourage more new documentation. We should at least support literal docs like README, that need no generation/translation. I'd also like us to look at supporting markdown+pandoc for man pages and user guides. As an example, see the happy user guide http://haskell.org/happy/doc/happy.pdf which currently uses docbook and dblatex. That kind of level of markup should be easily doable with markdown+pandoc. The question is how easy are the tools to get good output in html and pdf for user guides, or man pages. We want to support a doc toolchain that requires zero configuration, like we do for haddock. I think we can expect package authors to specify what kind of documentation each thing is, eg notes vs user guide vs reference pages. Ideally we should not need package authors to specify the format of the documentation, we should be able to guess from the extension. {{{ documentation: notes: README, AUTHORS, Changelog, releasenotes user-guide: userguide.markdown man-pages: blah.markdown }}} -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/330#comment:2 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#330: Support general documentation, not just haddock ----------------------------+----------------------------------------------- Reporter: fons | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: Cabal library | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ----------------------------+----------------------------------------------- Comment (by simonmic): I like this. How about: documentation: general: README, AUTHORS, releasenotes user: userguide.md, tool.1 admin: toolconfig.5 developer: Changelog, DEVGUIDE.rst using target audience as major category. .1 and .5 are man pages in the traditional nroff format. To generate man pages from some other format, augment this basic scheme (add a tool.1: tool.md or some such..), but that seems like a nice-to-have. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/330#comment:3 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#330: Support general documentation, not just haddock ----------------------------+----------------------------------------------- Reporter: fons | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: Cabal library | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ----------------------------+----------------------------------------------- Comment (by simonmic): {{{ general: README, AUTHORS, releasenotes user: userguide.md, tool.1 admin: toolconfig.5 developer: Changelog, DEVGUIDE.rst }}} -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/330#comment:4 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
#330: Support general documentation, not just haddock ----------------------------+----------------------------------------------- Reporter: fons | Owner: Type: enhancement | Status: new Priority: normal | Milestone: Component: Cabal library | Version: 1.2.3.0 Severity: normal | Resolution: Keywords: | Difficulty: normal Ghcversion: 6.8.2 | Platform: ----------------------------+----------------------------------------------- Comment (by igloo): I would prefer that there were multiple "doc" sections, just as there are multiple "executable" sections. {{{ doc type: markdown doc-directory: docs/user_guide root: index.md }}} It could be that in the common case you just need to give the path to the root doc file, and Cabal infers everything else, but I think it would be wise to leave space for other options to be given. -- Ticket URL: http://hackage.haskell.org/trac/hackage/ticket/330#comment:5 Hackage http://haskell.org/cabal/ Hackage: Cabal and related projects
participants (1)
-
Hackage