Readme as Description

[yaitskov]

Describe the feature request
I would like to include whole readme or first section into haddock output instead of content
from cabal description section if it is missing.

Markdown syntax is isomorphic to haddock one.

Additional context
I think readme file and cabal description section share a lot of data and
keeping them in-sync is a boring task.

[yaitskov]

https://gitlab.haskell.org/ghc/ghc/-/issues/25788

[ffaf1]

Markdown syntax is isomorphic to haddock one.

I am not sure about this (footnotes? Which specific flavour of Markdown?)

On Hackage READMEs are displayed at the bottom, along description at the top.
I think I understand the need (avoid duplication), but “whole readme or first section” sounds prone to badly butchered descriptions.

[yaitskov]

Description is the most odd section in cabal file.
It is in terms of HMTL requires a text area meanwhile rest fields are inputs or lists of tuples i.e. something small.
Ability to include description from HTML file is a good deal too.
Developer can hammer readme into description with some text preprocessing tool.
Description is similar to license, thought license text is located in a separate file.
Is there text editor capable to highlight haddock section inside a cabal file?
Extracting description section into a separate file by itself would improve developer experience.

Haddock cannot include HTML chunks and in general it is not practical.
Haddock is part of GHC core libraries and dependency on markdown library is less feasible than for cabal.
Majority of open source projects are hosted on github which markdown syntax doesn't support include.

[Bodigrim]

Developer can hammer readme into description with some text preprocessing tool.

pandoc works well to convert Markdown to Haddock. It would be quite straightforward to write a standalone tool, which replaces description: field with converted README.md.

[ulysses4ever]

Markdown syntax is isomorphic to haddock one.

As someone who once tried to enable Markdown frontend in Haddock (see discussion starting this comment: haskell/haddock#794 (comment)) I can assure you that it's far from being true. For instance, the special support for linking 'identifiers' in single quotes has no analog in Markdown.

I don't think this (non-)isomorphism is relevant to the feature you have in mind, though. The interesting idea that you seem to have is to include READMEs instead of descriptions on the Haddock output. Note that this is not a cabal feature but a haddock feature, so the proper place to discuss it is your other ticket on GHC's repository. In my experience, there's little energy for discussing noticeable changes to Haddock these days, sadly (It seems that there's just not enough man-power in Haskell ecosystem to develop Haddock further than what it is today.) But good luck to you in any case!

If we could agree that we're not doing anything with cabal files as a part of this, and this is purely a Haddock feature request, I'd propose we close this issue and move to https://gitlab.haskell.org/ghc/ghc/-/issues/25788.