[Hackage] #330: Support general documentation, not just haddock

Hackage trac at galois.com
Tue Jun 2 09:25:58 EDT 2009


#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


More information about the cabal-devel mailing list