[Haskell-cafe] Hackage package "synopsis" sections

[Britt Mathis]

I meant to post this about 30 minutes ago, but I accidentally sent it
only to Michael Snoyman.

It seems to me that there are two use cases here - documentation
inside code and documentation that stands alone. I agree with you,
Michael, that there is no reason why you shouldn't be able to use
whichever documentation method you prefer in your readme file. Since
it stands alone, it should be trivial to include support for a
multitude of formats and display the resulting documentation on
Hackage. I think where Mateusz' opinion differs is on the inclusion of
markdown in source files (correct me if I am wrong):

> More importantly, Markdown
> is not suited for documenting code. We'd have to introduce new
> identifiers if we wanted to link to some functions from our synopsis.
> 16th standard aside, this is quickly starts looking like Haddock.

As he says, there are problems with using markdown this way. I think
it would be beneficial to have a defacto standard for documentation
that lives inside source files - this would prevent it from changing
from file to file and provide consistency across the community's
code-base. Because the haskell community controls haddock it is in a
better position to evolve to our needs. Some flavor of markdown that
has a user-base outside the haskell community may not be willing to
incorporate changes that make it a better fit for living inside
haskell source files, so we would have to maintain our own fork of it
anyway. Why duplicate the work that has already been done? I think if
the community has a problem with haddock syntax that can be discussed
and, if need be, changed. But I do believe that there should be
consistency in source file documentation.

The last problem I see is the cabal problem. It seems that cabal has
trouble handling edge cases, and I think that is again something we
can work on (I may even look into it myself - I have been looking for
a project). It seems like it would be a good idea to only include
small blurbs about the project in the .cabal file, and to separate the
larger documentation into a README file, like is done on github. The
reasoning behind this is two-fold:
1) Cabal files are human readable. They give us insight into the
dependencies a project requires, and including full documentation here
would make it harder to get a quick overview of the project (I know
most people use hackage for this, but cabal was chosen over formats
like XML specifically because it was meant to be read and understood
by humans).
2) Separating the README file allows users to choose their favorite
format, and be certain that it will be formatted as it was intended
(cabal can't be expected to handle every edge case of every format -
there are far too many, and Pandoc already does a great job
translating between formats).