Runestone Documentation Issue: Instructions for BOOK_PATH unclear in 6.1

[habibasorour]

What Page were you on?
https://docs.runestone.academy/en/latest/running.html

Describe the bug
In 6.1, it mentions having book_path ready and adding it to Docker. It is explained further down in section 6.7, but there is no mention of going to 6.7 for clarification.

Suggested Fix:

• A mention of 6.7 in 6.1 would be very helpful.
• Adding a subsection in 6.1 or at the start of 6.2 explaining how to set up the books directory, and not have it at the end of 6.7
• Its wording can be: (Set Up Books Directory (all platforms):
  You need to create a directory for your books before running the setup script. This directory will become your books path (referenced in section 6.7).
  On Linux/macOS/WSL (Windows): Open your terminal and run:
  mkdir -p ~/runestone/books
  This creates the directory at /home/youruser/runestone/books. Use this full Linux path when Docker asks for your books path and when adding the directory to Docker’s file sharing settings.
  Windows users: Run the mkdir command above inside your WSL terminal (Ubuntu), not in File Explorer or PowerShell. Everything must stay in the Linux filesystem.)

A Screenshot is worth a thousand words

What is your username
habibasorour

[harrisonj2-v]

working on this

[bnmnetp]

Also the init_runestone.sh script prompts the user for book_path and creates it for the user.

[harrisonj2-v]

Understood. I was only trying to clarify what the book_path should look like for newer users, but since init_runestone.sh already prompts for it and creates it, is there a need to add a pointer to it?

[bnmnetp]

I think adding a pointer to those sections that tell the user about the config file and the book path is reasonable. On the mac this isn't a step I've had to worry about as by default it makes all the usual places available without any additional work. So maybe this is only important for WSL. Which I really know nothing about. I'd be curious to know though because if docker desktop for WSL already makes your home directory available then you don't have to make an explicit addition, and maybe that comment about file sharing causes more confusion than it helps.

[harrisonj2-v]

I am also on Mac, and I will ask my peers how the book path worked for them when they set it up, and I will come back with more information.

[harrisonj2-v]

From what I've heard from WSL users, when Docker prompts you to create a path, it keeps the original Windows path rather than automatically converting it to the WSL path.

[harrisonj2-v]

@pearcej, can you please just suggest wording that would help this issue?

[pearcej]

@bnmnetp Despite me telling my students they must never, never use Windows in their open-source work, several used a tool to choose a C: book path, which is clearly on Windows. So, my approach was ineffective.

@harrisonj2-v I recommend using a hint to say "If you are on WSL, be sure to use a folder in the Linux portion of your hard drive; the path must certainly not begin with C:".

[pearcej]

@harrisonj2-v This comment should not have been made without a user of WSL.

Who approved this?

[harrisonj2-v]

@pearcej I asked my teammates, but then asked all my Berea peers, and all that answered, but one had the same answer,