make SUMMARY.md more easy to write

[tshepang]

SUMMARY.md is tedious to write. There is code to avoid that by automatically generating that file, an idea that solves this problem for when the book already exists. What I propose applies to when the book does not even exist.

Following is how it would look:

# Building and debugging `rustc`

- How to Build and Run the Compiler 
    - Prerequisites
    - Suggested Workflows
    - Distribution artifacts
    - Documenting Compiler
- The compiler testing framework
    - Running tests
    - Adding new tests
    - Using `compiletest` commands to control test execution

That would produce the following directory structure:

building-and-debugging-rustc.md
how-to-build-and-run-the-compiler/
  index.md --> this implicit file is added for any chapter that has sub-chapters
  prerequisites.md
  suggested-workflows.md
  distribution-artifacts.md
  documenting-compiler.md
the-compiler-testing-framework/
  index.md
  running-tests.md
  adding-new-tests.md
  using-compiletest-commands-to-control-test-execution.md

Is this sensible (ignoring backward compatibility concerns)?

[ISSOtm]

So, basically, a paragraph of plaintext would be equivalent to itself as the link name, and the link "URL" would be itself, but all lowercase and spaces replaced by dashes? Should formatting be allowed?

[tshepang]

@ISSOtm I don't understand would be equivalent to itself and formatting be allowed

[ISSOtm]

The "parens" were supposed to be "a paragraph of plaintext would be equivalent to (itself as the link name, and [...] would be itself but all lowercase)". I'm trying to clarify how the text in each list item would be turned into a link, i.e. what transformations should be applied to it to get the link text and the URL.

As for "Should formatting be allowed", I'm talking about bold text, links, etc.

[tshepang]

Oh, yeah... you got it right. That is, the actually generated file would be a slug of a line of text (which also means formatting is removed).