Support general documentation, not just haddock

[fons]

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).

[duncan]

See also #283.

[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

[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.

[simonmic]

general: README, AUTHORS, releasenotes 
user: userguide.md, tool.1 
admin: toolconfig.5 
developer: Changelog, DEVGUIDE.rst

[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.

[duncan]

See additional suggestions in ticket #674.