I could add a "useful resources" section to list all the tutorials/examples/libraries that use glam

Ideally I should add at least a couple more tutorials before doing that, a list with a single bullet point would be sad :(

I'm weak for packages with logos like Nakai and I'd love to add one here as well

Also if I ever do this I should remember to use it for the social preview

I'd like to add some tests for the examples that are shown in the library.
This would be beneficial in two ways:

• act as some sort of "integration testing" to make sure that future changes do not break the pretty printing algorithm
• make sure I do not show buggy code in the tutorials :P

Why is this a good first issue and how can you help?

I feel like this shouldn't be too complicated, especially if one has already walked through the package's tutorials.
Basically, what one would need to do is:

• read the examples' code
• make the x_to_doc functions to test public
• create a new module in the tests folder to add the tests for each pretty printer
• write some tests that test different data structures at different line widths
  • you can use the tutorials' examples as a reference for how the pretty printed documents should look

@bcpeinhardt pointed out that it may be handy to have a doc.nest_docs that can take a list of documents and concat them together adding a given nesting. This would be analogous to doc.append/doc.append_docs

Why is this a good first issue and how can you help?

Closing this issue would require

• implementing a doc.nest_docs function
• adding relevant tests to check that it behaves like a normal nest

I think the function should have the following signature:

pub fn nest_docs(docs: List(Document), by nesting: Int) -> Document { ... }

And the implementation could be as simple as concatenating the docs and wrapping everything with a doc.nest. There should be some tests to check that it works properly, though :)

I should add support for zero width strings, that is strings that are simply appended to the text without increasing the width of the string. This would be really useful to properly handle ansi color codes

Since this package is so similar to Elixir's Inspect.Algebra I could add more tests taking as a reference the ones they use. The API is quite similar so it wouldn't be too hard to port those

Why is this a good first issue and how can you help?

Adding this shouldn't be too hard if you can read a bit of Elixir.
Basically, what one would need to do is:

• look at Inspect.Algebra's tests
• rewrite each test in Gleam
  • the tests can be added to the glam/doc_test module
  • most likely you'll need to have a look at Inspect.Algebra's documentation
  • mapping each of Inspect.Algebra's functions into the corresponding glam one. The API is quite similar but things may have different names

It would be lovely to add a debug function that turns a document into a pretty document showing its structure with a nice format to help debugging complex documents.

Informally:

doc.group(•)         ~> [•]
doc.concat([•,…,•])  ~> • . … . •
doc.nest(•, by: n)   ~> ⟨•⟩ⁿ
doc.break(•, •)      ~> {•, •}
doc.flex_break(•, •) ~> {•, •}
doc.from_string(•)   ~> "•"
doc.force_break(•)   ~> force(•)
doc.lines(n)         ~> lfⁿ

An example with a concrete document:

[
  doc.from_string("foo"),
  doc.space,
  doc.from_string("bar"),
  [ 
    doc.from_string("baz"),
    doc.space,
    doc.from_string("foo again"),
  ]
  |> doc.concat
  |> doc.nest(by: 1)
  |> doc.group
]
|> doc.join(with: doc.line)
|> doc.nest(by: 12)
|> doc.debug
|> doc.to_string(45)

// ->
// ⟨   
//   "foo" . lf . {" ", ""} . lf . "bar" . lf .
//   [ ⟨ "baz" . {" ", ""} . "foo again" ⟩¹ ]
// ⟩¹²

Maybe since doc.space is quite common it could be turned into something shorter like ~:

// ->
// ⟨   
//   "foo" . lf . ~ . lf . "bar" . lf .
//   [ ⟨ "baz" . ~ . "foo again" ⟩¹ ]
// ⟩¹²