documentation suggestion

[GeorgeCo]

Would it be possible to add an example in the documentation of how to write a function pPrintList for nested lists? i.e.
pPrintList [[1..5],[6..10]] would output something like
[
[1,2,3,4,5]
[6,7,8,9,10]
]

i.e. something similar to the output of (putStrLn . unlines . map show) [[1,2,3,4,5],[6,7,8,9,10]]
[1,2,3,4,5]
[6,7,8,9,10]
except with the enclosing brackets and indentation. It would be interesting to have one where the output has commas and another has spaces instead of commas.

This would be analogous to Wadler's example of how to prettyPrint a tree in his paper "A prettier printer". It would also be good to add an example of how to prettyPrint a tree using this package.

Thanks

[sjakobi]

You might want to look at the source for the list function.

For your specific example, something like list . map (list . map pretty) should work.

I'm open towards enhancing the documentation. Eventually we should probably have a proper tutorial module, so the main Prettyprinter module doesn't get too bloated.

[GeorgeCo]

Thanks Simon, you motivated me to dig a little deeper and come up with what I wanted

λ>   pp2dList l2d = print $ pretty "[" <+>   align (vsep (fmap pretty l2d)) <+> pretty "]"
pp2dList :: Pretty a => [a] -> IO ()
λ>  pp2dList  [[1,2,3,4,5], [6,7,8,9,10]]
[ [1, 2, 3, 4, 5]
  [6, 7, 8, 9, 10] ]

I totally agree that the most needed documentation enhancement would be a tutorial.

wrt the current doc, I modeled my solution after the example in the doc:

 "prefix" <+> align (vsep ["text", "to", "lay", "out"])

I expected to be able to cut and paste that into ghci along with "import Prettyprinter" but that doesn't work. It needs to be this:

 (pretty "prefix") <+> align (vsep (map pretty ["text", "to", "lay", "out"]))

Not surprisingly I prefer my example to the one in the doc! :)

Thanks again

[sjakobi]

 "prefix" <+> align (vsep ["text", "to", "lay", "out"])

I expected to be able to cut and paste that into ghci along with "import Prettyprinter" but that doesn't work. It needs to be this:

 (pretty "prefix") <+> align (vsep (map pretty ["text", "to", "lay", "out"]))

Oh, you could have simply enabled -XOverloadedStrings. The documentation should be explicit about this, of course.

[sjakobi]

Oh, you could have simply enabled -XOverloadedStrings.

GHC could be more helpful with the error message too: https://gitlab.haskell.org/ghc/ghc/-/issues/16496

[GeorgeCo]

Thanks again Simon, that allows me to remove the calls to pretty in my example! It would be great if the doc mentioned that all examples need

{-# LANGUAGE OverloadedStrings #-} 
import Prettyprinter
import Prettyprinter.Util

Most beginners will do the first import but the second isn't so obvious. Small things like this are a great help for beginners. Unfortuntately the docs are normally written by experts for which all this seems obvious.

Cheers
George

[sjakobi]

Would you be interested in addressing the issue yourself with a PR?!

Most beginners will do the first import but the second isn't so obvious. Small things like this are a great help for beginners. Unfortuntately the docs are normally written by experts for which all this seems obvious.

Indeed. It's much easier to find problems with documentation as long as one isn't familiar with the matter.

[GeorgeCo]

Hi Simon I'm interested but not sure I'm capable. I found lots on the web about hacking GHC but nothing specific about packages. Are there are any pages you could recommend or should I just plunge ahead and get back to you with questions? On https://github.com/quchen/prettyprinter/pulls there is a green button "New pull request". Should I just click that and start from there? Cheers George

…

On Thu, Nov 11, 2021 at 3:51 PM Simon Jakobi ***@***.***> wrote: Would you be interested in addressing the issue yourself with a PR?! Most beginners will do the first import but the second isn't so obvious. Small things like this are a great help for beginners. Unfortuntately the docs are normally written by experts for which all this seems obvious. Indeed. It's much easier to find problems with documentation as long as one isn't familiar with the matter. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#209 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABQIJ626F43DXH4VU4A2TYDULQNFBANCNFSM5G3UEVQA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[sjakobi]

Are there are any pages you could recommend or should I just plunge ahead and get back to you with questions?

Hmm. Not much comes to mind. Have you used stack or cabal so far? For stack there's some kind of beginner's guide at https://docs.haskellstack.org/en/stable/README/#quick-start-guide.

To generate the module documentation ("haddocks"), you'd run cabal haddock prettyprinter which will eventually print a path to some HTML that you can view in your browser. stack can even open the browser for you: stack haddock --open prettyprinter.

For haddock syntax, see https://haskell-haddock.readthedocs.io/en/latest/markup.html.

If you have questions, you can ask me, or try the haskell-beginners channel on Slack, or the "Hask anything" thread on reddit.

For your first PR, I'd recommend doing something smallish.

On https://github.com/quchen/prettyprinter/pulls there is a green button "New pull request". Should I just click that and start from there?

That should work. You don't need to have a finished patch when you open the PR, in case you want early feedback on a draft.