requiring '.' for blank lines is annoying

[Jake Wheat]

The cabal documentation on this page:

 http://www.haskell.org/cabal/release/cabal-latest/doc/users-guide/authors.html#pkg-descr

contains this under the documentation for the description property: 'For library packages, this field is used as prologue text by setup haddock (see the section called “setup haddock”), and thus may contain the same markup as haddock documentation comments.'

But when I try to use e.g. paragraphs in this field, it appears as though the whitespace gets stripped out and so the paragraphs don't appear and all the text gets shoved together.

Example from my cabal file:

Description: Sql parser, pretty printer and type checker, targets PostGreSQL SQL and PL/pgSQL, uses Parsec and UUAGC.

Overview:

see the module 'Database.HsSqlPpp?.TypeChecking?.Ast' for the ast types;

'Parser' for converting text to asts;

'PrettyPrinter?' for converting asts to text;

<snip>

this results in:

Sql parser, pretty printer and type checker, targets PostGreSQL SQL and PL/pgSQL, uses Parsec and UUAGC. Overview: see the module Database.HsSqlPpp?.TypeChecking?.Ast for the ast types; Parser for converting text to asts; PrettyPrinter? for converting asts to text;<snip>

coming out in the haddock docs and on hackagedb - all the newlines are missing. When I copy this text to a separate file an invoke haddock -p, the documentation comes out with the paragraphs correctly, so I'm guessing this is something cabal is doing to the description property before passing it to haddock.

full cabal file here:  http://hackage.haskell.org/packages/archive/hssqlppp/0.0.6/hssqlppp.cabal scrunched text viewable here:  http://hackage.haskell.org/package/hssqlppp

[duncan]

In that same section of the user guide it state:

• To get a blank line in a field value, use an indented “.”

This is an annoying historical artifact in the Cabal specification from the time when blank lines were used to separate sections. There's no need to keep this "feature". See ticket #478.

[guest]

Yes I missed that text, my mistake.

I did check a few packages on hackage db before reporting and somehow managed to only find ones where the package author had made the same mistake as me, looking again I can see most uploaders got this right.

Since a few others have also made this mistake, could I suggest adding a sentence to description property, something like:

For library packages, this field is used as prologue text by setup haddock (see the section called “setup haddock”), and thus may contain the same markup as haddock documentation comments (you need to use an indented '.' to get a blank line in the markup passed to haddock, as noted above).

[elga]

*  simyo