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

add anchors for chapter 6 #378

Merged
merged 2 commits into from
Nov 21, 2021

Conversation

ntwilson
Copy link

I struggled a lot with this one. Mdbook is very picky about indentation, and there seems to be some edge cases that weren't well thought out when it comes to indented code blocks with anchors. In particular, it seems Mdbook just pastes in the code directly, including whitespace, and doesn't indent further when the code block was indented. So if I had an anchor like

instance Eq (NonEmpty a) where
  eq (NonEmpty x xs) (NonEmpty y ys) = x == y && xs == ys

and I used that in a code block like

## Exercises
1. In the the code below:
    ```haskell
    {{#include ../exercises/chapter6/test/no-peeking/Solutions.purs:eqNonEmpty}}
    ```
    we ...

that would get translated into

## Exercises
1. In the code below:
    ```haskell
    instance Eq (NonEmpty a) where
  eq (NonEmpty x xs) (NonEmpty y ys) = x == y && xs == ys
    ```
    we ...

which really throws off the document flow. The only three solutions I could come up with were

  1. standardize the text indentation on size 4, and indent the source code far enough to get around this problem (6). So the original code block becomes
    instance Eq (NonEmpty a) where
          eq (NonEmpty x xs) (NonEmpty y ys) = x == y && xs == ys
  2. make an anchor for each individual line of code, so we can indent each line as much as we need to in the .md text
  3. don't use anchors at all

I opted for approach 1, but it feels really hacky, and I would welcome feedback on if any other approach should be taken.

@@ -8,6 +8,8 @@ This motivating example for this chapter will be a library for hashing data stru

We will also see a collection of standard type classes from PureScript's Prelude and standard libraries. PureScript code leans heavily on the power of type classes to express ideas concisely, so it will be beneficial to familiarize yourself with these classes.

If you come from an Object Oriented background, please note that the word "class" means something _very_ different in this context than what you're used to. A type class serves a purpose more similar to an OO interface.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feel free to nix my extra commentary. It seemed to me that immediately dispelling any preconceived notions about the word "class" might be helpful

text/chapter6.md Outdated
@@ -123,16 +125,14 @@ No type class instance was found for
Data.Show.Show (Int -> Int)
```

Type class instances can be defined in one of two places: in the same module that the type class is defined, or in the same module that the type "belonging to" the type class is defined. An instance defined in any other spot is called an "orphan instance" and is not allowed by the PureScript compiler. Some of the exercises in this chapter will require you to copy the definition of a type into your MySolutions module so that you can define type class instances for that type.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, feel free to nix my extra commentary. I thought it might confuse some readers why in every chapter up to this point, they've been given all the code they need already and can just start coding up the exercises, but in this chapter they suddenly have to copy+paste a bunch of types into their code.

@ntwilson ntwilson marked this pull request as ready for review August 16, 2021 04:00
text/chapter6.md Outdated Show resolved Hide resolved
text/chapter6.md Outdated Show resolved Hide resolved
@milesfrain
Copy link
Member

Wow. That's some pretty annoying mdbook behavior. Opened rust-lang/mdBook#1626 to see if we can find a resolution. This might require making a PR to that project.

Co-authored-by: milesfrain <milesfrain@users.noreply.github.com>
@milesfrain milesfrain merged commit c8bb7d3 into purescript-contrib:master Nov 21, 2021
@ntwilson ntwilson deleted the chapter6-anchors branch November 21, 2021 17:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants