Fix #622 Handle multi-line value for field description

[mpilgrem]

See:

• Multi-line flags description produces invalid Cabal file #622

This uses LineSeparatedList so that:

flags:
  my-flag:
    description: |
      This is some text

      This is more some text
    manual: true
    default: true

renders as:

flag my-flag
  description:
      This is some text
      .
      This is more some text
  manual: True
  default: True

otherwise I could not see how to avoid ugly rendering.

[mpilgrem]

The CI is failing for reasons unrelated to this pull request. See:

• crypton-x509-store-1.6.12 build failure with unix-2.7.3 (GHC 9.4.8) kazu-yamamoto/crypton-certificate#21

[sellout]

This looks good as far as I can tell. Shares code with the existing description formatting, looks like it correctly handles Cabal versioning 👍

[sol]

See:

• Multi-line flags description produces invalid Cabal file #622

This uses LineSeparatedList so that:

flags:
  my-flag:
    description: |
      This is some text

      This is more some text
    manual: true
    default: true

renders as:

flag my-flag
  description:
      This is some text
      .
      This is more some text
  manual: True
  default: True

otherwise I could not see how to avoid ugly rendering.

What does ugly rendering mean?

Something like this?

flag my-flag
  description: This is some text
               .
               This is more some text
  manual: True
  default: True

[sol]

@mpilgrem I'm gonna do a review, but can you please give me feedback on my question first?

[mpilgrem]

@sol, I am away from a machine, but the short answer is: in part. With a Literal the indentation is 'coded' in the value, so you have to 'hard code' that the start of description: for a flag stanza will be two spaces in from the left.

With a LineSeparatedList, I did not need to encode indentation in the value. A different type of hack, I suppose...

[mpilgrem]

One thing I have not checked, but needs to be understood, is how Hackage renders a multi-paragraph description for a flag.

(I know how Hackage renders a long description, because the stack package provides examples of those.)

EDIT: Now checked with a package candidate: Hackage does respect and render a multi-paragraph description for a Cabal flag.

[mpilgrem]

@sol, the current solution uses Literal and 'hard codes' in the value an indentation of two spaces, so that:

flags:
  my-flag:
    description: |
      This is some text

      This is more some text

renders as:

flag my-flag
  description: This is some text
               .
               This is more some text

However, the limitation is that if Hpack 'sniffs' from the library or executable stanzas of an existing Cabal file an indentation of, say, six spaces, it will render as:

flag my-flag
      description: This is some text
               .
               This is more some text

I consider that to be 'ugly'.

[sol]

However, the limitation is that if Hpack 'sniffs' from the library or executable stanzas of an existing Cabal file an indentation of, say, six spaces, it will render as:

flag my-flag
      description: This is some text
               .
               This is more some text

I consider that to be 'ugly'.

OK, understand, thanks for pointing this out.

I think the issue here is that formatDescription was only meant to be used for top-level fields and does not properly support nested fields, like flag descriptions.

A clean way to address this could be to add support for multi-line strings to Hpack.Render.Dsl.

I'd be happy to help with the code. But before doing so, I think it would help if we can answer the following questions:

1. Are there any more .cabal-fields that support multi-line strings?
2. Is handling of empty lines consistent for all of these fields across Cabal versions? (. vs empty line)

[mpilgrem]

@sol, given Cabal's current online documentation:

I would expect all Cabal file fields that accept freeform values (an arbitrary, uninterpreted string) to support . before Cabal 3.0 and to preserve empty lines and indentation from Cabal 3.0.

See:
https://cabal.readthedocs.io/en/stable/file-format-changelog.html#cabal-version-3-0 and

Free text fields (e.g. description) preserve empty lines and indentation. In other words, you
don’t need to add dots for blank lines.

Such fields are (1) top level: copyright, author, stability, synopsis, description, category (2) flag stanza: description.

Also:

• https://hackage-content.haskell.org/package/Cabal-syntax-3.16.0.0/docs/src/Distribution.PackageDescription.FieldGrammar.html (search freeTextField); and
• https://hackage-content.haskell.org/package/Cabal-syntax-3.16.0.0/docs/src/Distribution.FieldGrammar.Parsec.html (see instance FieldGrammar Parsec ParsecFieldGrammar)

together suggest that such fields also include (1) top level: maintainer (documented as an 'address' value), homepage (as 'URL'), package-url (as 'URL'), bug-reports (as 'URL') (2) source-repository stanza: location (as 'VCS location').

Empirically, the following (extract) is a valid Cabal file:

cabal-version: 2.2

name:           testDotStyle
version:        0.1.0.0
description:    Paragraph one.
                .
                Paragraph two.
homepage:       Paragraph one.
                .
                Paragraph two.
bug-reports:    Paragraph one.
                .
                Paragraph two.
author:         Paragraph one.
                .
                Paragraph two.
maintainer:     Paragraph one.
                .
                Paragraph two.
copyright:      Paragraph one.
                .
                Paragraph two.
stability:      Paragraph one.
                .
                Paragraph two.
synopsis:       Paragraph one.
                .
                Paragraph two.
category:       Paragraph one.
                .
                Paragraph two.
build-type:     Simple

source-repository head
  type: git
  location: Paragraph one.
            .
            Paragraph two.

flag my-flag
    description: Paragraph one.
                 .
                 Paragraph two.

EDIT: Although what Hackage expects or requires of a Cabal file can be a further consideration, for example:

• Accept a list for category #624

[mpilgrem]

Rebased against main branch on the release of hpack-0.38.3.