documentation suggestion
GeorgeCo opened this issue · comments
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
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.
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
"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.
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
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
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.
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.