[Discussion] Structure

[azerupi]

Hi Steve,

A couple of thoughts about the structure:

1. As of now, all source files reside in the root src folder. Do you plan on adding a bit more hierarchy? For example, every chapter / section could be moved into it's own directory, so that files about similar subjects reside closer to each other and are more easily found.

   src
   ├── 1-introduction
   │   ├── hello_worl.md
   │   ├── introduction.md
   │   └── ...
   ├── 2-tutorial
   │   ├── ...
   └── 3-primitive_rust
   │   ├── functions.md
   │   ├── variable_bindings.md
   │   └── ...
   ├── ...
   

2. The current version (old book) is pretty "flat", there is only one sub-level to the chapters. I would personally subdivide the longer chapters, were you have multiple sub-parts, into actual sub-chapters.

   Shorter chapters, focussing on one specific subject, are more comprehensive. You clearly see where the current subject stops and were the next begins. Reading a chapter feels lighter and less involved, which is good when you read on-the-go, in situations were your time is limited or when there is a lot of distraction.

   Because sub-chapters would be shown in the sidebar, it would also enhance the structure and navigation.

What is your view about this?

[steveklabnik]

I'm not totally sure yet. One major issue here is that each chapter has to go to No Starch in one chunk, and I don't want to be going back and forth and back and forth splitting and re-assembling.

But beyond that, until I actually come up with new drafts of each chapter, I don't know how many sub-headings they have, which is why I haven't done a whole lot.

[aturon]

@azerupi Just for reference, the intended TOC is here: https://public.etherpad-mozilla.org/p/trpltoc

[azerupi]

One major issue here is that each chapter has to go to No Starch in one chunk, and I don't want to be going back and forth and back and forth splitting and re-assembling.

Interesting! What format do you have to deliver in?

Just for reference, the intended TOC is here: https://public.etherpad-mozilla.org/p/trpltoc

Ok thanks!

The reason I asked is because I read the primitive types chapter (and your comment about it) and as I imagine more info will be added in the future about some types, that chapter will become quite long with well defined sub-sections.

Splitting into sub-sections would allow to go more in depth and give more examples without having abnormally long pages.

For example:

- Primitive types (int, float, bool, char, ...)
    - Compound types (arrays, tuples, slices, ...)
    - Strings
    - Functions (fn, closures, ...)

---

Lastly, two neat tricks (at least I find it neat) you can do with mdBook, just mentioning in case you didn't know :)

1. If you fill in the SUMMARY.md with chapters and paths to files that don't exist and then render, it will automatically create all the missing files. So you almost copy paste the TOC draft and have mdBook create all the necessary files.

   # Summary
   
   - [A](a.md)
   - [AB](a/b.md)
   

   will create two files a.md and a/b.md with respectively "A" and "AB" as heading.

2. You can add non-existing chapters to SUMMARY.md just leave the path empty: [Chapter 1]()
   The chapter will show up in the sidebar but will be greyed out. This is handy if you want to lay out the structure but haven't yet made all the files.

[steveklabnik]

Interesting! What format do you have to deliver in?

In Markdown, they just want to read whole chapters at once and so they can do it or I can, and I feel bad making them do it.

If you fill in the SUMMARY.md with chapters and paths to files that don't exist and then render, it will automatically create all the missing files.

This is like, my favorite feature 👍

You can add non-existing chapters to SUMMARY.md just leave the path empty: Chapter 1
The chapter will show up in the sidebar but will be greyed out.

Ohhh cool. I will probably do this too.

[azerupi]

I can understand it's not easy to target both media at the same time. Even though they are both "books", a paper and an online version still differ a lot in their format and philosophy.

This is like, my favorite feature 👍

Thanks 😊

[steveklabnik]

I think this issue can be closed now, yeah?