Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

documentation suggestion #209

Open
GeorgeCo opened this issue Oct 28, 2021 · 8 comments
Open

documentation suggestion #209

GeorgeCo opened this issue Oct 28, 2021 · 8 comments

Comments

@GeorgeCo
Copy link

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
Copy link
Collaborator

sjakobi commented Nov 11, 2021

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
Copy link
Author

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
Copy link
Collaborator

sjakobi commented Nov 11, 2021

 "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
Copy link
Collaborator

sjakobi commented Nov 11, 2021

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
Copy link
Author

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
Copy link
Collaborator

sjakobi commented Nov 11, 2021

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
Copy link
Author

GeorgeCo commented Nov 12, 2021 via email

@sjakobi
Copy link
Collaborator

sjakobi commented Nov 13, 2021

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants