Fix #622 Handle multi-line value for field description #623
Conversation
|
The CI is failing for reasons unrelated to this pull request. See: |
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 |
|
@mpilgrem I'm gonna do a review, but can you please give me feedback on my question first? |
|
@sol, I am away from a machine, but the short answer is: in part. With a With a |
|
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 |
| @@ -1,3 +1,6 @@ | |||
| ## UNRELEASED | |||
| - Handle a multi-line value for the `description` key of a flag (see #623) | |||
There was a problem hiding this comment.
I would tend to release this straightaway as 0.38.3.
| - http-client-tls >= 0.3.6.2 | ||
| - vector | ||
| - infer-license >= 0.2.0 && < 0.3 | ||
| - crypton-x509-store < 1.6.12 || > 1.6.12 |
There was a problem hiding this comment.
What is the issue with that version?
As this is not a direct dependency, I'm not eager to include this in the package description.
Could this be addressed as a Hackage revision instead?
There was a problem hiding this comment.
See: kazu-yamamoto/crypton-certificate#21
This was intended only as a temporary fix, to allow the Hpack CI to run (as it uses Cabal).
There was a problem hiding this comment.
Ah, ok, thanks.
This should be addressed by a Hackage revision.
| where | ||
| description = maybe [] (return . Field "description" . Literal) flagDescription | ||
| description = maybe [] (return . Field "description" . LineSeparatedList) formattedFlagDescription | ||
| formattedFlagDescription = formatDescription' cabalVersion <$> flagDescription |
There was a problem hiding this comment.
From what I understand, formatDescription functionally works here, and I think that is what you should use.
While technically, I guess, I would prefer two spaces of indentation, it does not justify misusing LineSeparatedList (at least not by my book).
There was a problem hiding this comment.
To elaborate on this, from what i understand, using LineSeparatedList produces
description:
This is some textand
description:
This is some text
.
This is more some textwhile using formatDescription would produce
description: This is some textand
description: This is some text
.
This is more some textWhile you could argue the multi-line formatting is indeed nicer with LineSeparatedList, for single-line descriptions I prefer what formatDescription produces. That means, LineSeparatedList is not strictly better than formatDescription, but using formatDescription is strictly cleaner, code wise, than using LineSeparatedList.
If anything, we would want to extend the formatting abilities of formatDescription, but even that is not very high on my priority list.
See:
flagsdescriptionproduces invalid Cabal file #622This uses
LineSeparatedListso that:renders as:
otherwise I could not see how to avoid ugly rendering.