Allow customization of help info via introducing semantic Doc #482
Conversation
|
Hi. Yes that's pretty much what I was suggesting. Please don't reformat everything in a PR though. It's too hard to tell what the point is. |
Ah sorry I didn't realize I was doing reformatting! That was ormolu doing it on its own. I will have to turn it off and then re-do the changes. |
src/Options/Applicative/Help/Core.hs
Outdated
| [ ( annotateHelp CmdName $ pretty cmdName, | ||
| align (annotateHelp Description $ ansiDocToHelpDoc $ extractChunk (infoProgDesc cmdInfo)) |
|
|
||
| with_title :: String -> Chunk HelpDoc -> Chunk HelpDoc | ||
| with_title title = fmap (annotateHelp Title . (pretty title .$.)) |
There was a problem hiding this comment.
I did a bit of annotating here.
| annotateHelp Metavar <$> stringChunk (optMetaVar opt) | ||
| descs = | ||
| map (pretty . showOption) names | ||
| map (annotateHelp OptionName . pretty . showOption) names |
| [ (annotateHelp CmdName $ pretty cmdName, | ||
| align (annotateHelp Description $ ansiDocToHelpDoc $ extractChunk (infoProgDesc cmdInfo)) | ||
| ) | ||
| | (cmdName, cmdInfo) <- reverse cmds |
| , infoProgDesc :: Chunk AnsiDoc -- ^ brief parser description | ||
| , infoHeader :: Chunk AnsiDoc -- ^ header of the full parser description | ||
| , infoFooter :: Chunk AnsiDoc -- ^ footer of the full parser description |
There was a problem hiding this comment.
This is still AnsiDoc, so that existing interface or these definitions doesn't change and so that users can continue using ansi styles while defining these.
Does that make sense?
src/Options/Applicative/Types.hs
Outdated
| , propHelp :: Chunk HelpDoc -- ^ help text for this option | ||
| , propMetaVar :: String -- ^ metavariable for this option | ||
| , propShowDefault :: Maybe String -- ^ what to show in the help text as the default | ||
| , propShowGlobal :: Bool -- ^ whether the option is presented in global options text | ||
| , propDescMod :: Maybe ( Doc -> Doc ) -- ^ a function to run over the brief description | ||
| , propDescMod :: Maybe ( HelpDoc -> HelpDoc ) -- ^ a function to run over the brief description |
There was a problem hiding this comment.
I am not quite sure if these should operate on HelpDoc or AnsiDoc?
|
@HuwCampbell I reverted the formatting changes, so now it should be ready for a closer look! |
| -- really a "doc chunk"? But isn't Doc already a "chunk of doc"?. | ||
|
|
||
| -- TODO: We have two types of functions here: general (Chunk a) operations, and Chunk (Doc a) operations. We should probably split those into separate modules. | ||
|
|
There was a problem hiding this comment.
It's so we can get a different monoid instance and not add spaces or breaks when things are hidden.
You'll find if its removed that internal and hidden options will affect the way the parser is rendered.
|
I spent 10 minutes on the train and got it to this: |
|
All up your approach it good. Do you mind if I push some commits to your branch? |
|
That's looking great! @HuwCampbell sure pls go for it -> I am currently slammed with other work, but might be able to dedicate some more time in a couple of weeks. But if you can make progress / get it done in the meantime, none happier than me! Btw this is what we currently have in our CLI, and what we would like to also achieve with optparse applicative:
So I am really hoping to achieve level of customizability that can bring us close to that. This is what we achieved with optparse so far:
|
|
Will do. We're still a way to go though. The issue isn't actually providing colours per se, that's relatively easy. I also want to respect if it's a TTY; environment variables like I general, if it's not a TTY, one shouldn't print colours; same for the other two ways of suppressing them. This gets a bit tricky for us because at the moment we don't have an environment parser to lean on internally. |
Ah interesting, I completely forgot about that. So we are really talking about the support for the ansi escape codes? And you are saying we don't have any logic for checking that at the moment + for propagating it to the right places? |
Should fix #478 once it is done.
@HuwCampbell this is still more of a playground then a solution, and it doesn't even compile completely, but I think it is starting to take some initial shape, so I thought I would rather share while still in this early stage, so you can course-correct me if I am going in a very wrong direction.
I mostly asked questions in the code, in comments, about things that are not clear to me.
The approach is that I introduced a new type of Doc annotation,
HelpAnn, which still allows for "old"AnsiStyleannotations (to support future feature of users specifying style via modifiers, and also the current feature of custom AnsiStyle docs they can already provide for some parts of docs like header, footer and similar), but also allows forHelpTypeannotations, which we use internally to annotate parts.The idea is then to later, probably at SimpleDocStream stage (in prettyprinter docs they recommend doing it at this stage), reannotate
HelpAnnannotations intoAnsiStyleannotations and continue from there same as before.I haven't yet started at all working on modifiers that would allow users to specify custom style. For now, I just focused on replacing one kind of annotation with another kind of annotation. I mostly got stuck on figuring out where to exactly annotate what with our new semantic annotation (
HelpAnn, specificallyHelpAnnType), because I am having hard time figuring out whichChunk Docis presenting what from the code -> is it option name, description, metavar, ... .Once we have internal semantic annotation working, and a default way defined of converting those annotations (
HelpAnn) into ansi annotations (AnsiStyle) (probably we will just do nothing for most of them), we can start looking into allowing users to define their own function that transformsHelpAnnintoAnsiStyleas one way of (global) customization, and style modifiers as another way of (local) customization.Interested to hear what you think, does this direction make sense? Thanks!