Move toolchain architecture to markdown

[jonmeow]

Note I'm mostly trying to capture the docs as they exist today, not fixing issues with the docs. I think the doc itself hasn't changed much lately (i.e., for months). Trying to organize it a little better though, particularly so that it shows up reasonably when looking in github or the website.

[eyelash]

The following code block is missing the indentation from the original Google Doc.

[jonmeow]

Fixed. Looks like this was getting auto-formatted away. Other examples are fine because they're not fully valid yaml.

[eyelash]

The backticks are missing here.

[jonmeow]

Thanks, fixed.

[jonmeow]

@zygoloid Maybe you can give your thoughts on the parse charts, at #4242 (comment)? Geoffrey is asking to go back to svg, I think the mermaid charts are good enough to understand what's going on, maybe you can weigh in.

[jonmeow]

@zygoloid Maybe you can give your thoughts on the parse charts, at #4242 (comment)? Geoffrey is asking to go back to svg, I think the mermaid charts are good enough to understand what's going on, maybe you can weigh in.

Just to note, we ended up discussing this in open discussion on Thursday. @chandlerc's suggested the ascii graphs.

[eyelash]

Not sure what exactly was discussed in open discussion (can't find it in the minutes) but using box-drawing characters would probably make these ASCII diagrams easier to read.

For example:

        ┌───┐ ┌─────┐             ┌───┐ ┌───┐
        │ x │ │ i32 │             │ y │ │ 1 │
        └─┬─┘ └──┬──┘             └─┬─┘ └─┬─┘
          │      │                  │     │
          └──────┴──────┐           └─────┴─────┐
                        │                       │
┌─────┐               ┌─┴─┐ ┌───┐             ┌─┴─┐
│ var │               │ : │ │ = │             │ + │
└──┬──┘               └─┬─┘ └─┬─┘             └─┬─┘
   │                    │     │                 │
   └────────────────────┴─────┴─────────────────┴─────┐
                                                      │
                                                    ┌─┴─┐
                                                    │ ; │
                                                    └───┘

[jonmeow]

Not sure what exactly was discussed in open discussion (can't find it in the minutes) but using box-drawing characters would probably make these ASCII diagrams easier to read.

For example:

    ┌───┐ ┌─────┐             ┌───┐ ┌───┐
    │ x │ │ i32 │             │ y │ │ 1 │
    └─┬─┘ └──┬──┘             └─┬─┘ └─┬─┘
      │      │                  │     │
      └──────┴──────┐           └─────┴─────┐
                    │                       │

┌─────┐ ┌─┴─┐ ┌───┐ ┌─┴─┐
│ var │ │ : │ │ = │ │ + │
└──┬──┘ └─┬─┘ └─┬─┘ └─┬─┘
│ │ │ │
└────────────────────┴─────┴─────────────────┴─────┐
│
┌─┴─┐
│ ; │
└───┘

This kind of character set change would require a chunk of time to just rewrite the graphs, and would be harder to update versus the basic ascii currently in use. It might make sense to consider separately, but given this review is jammed on specific style of these graphs, I want to be careful about investing lots of time into aesthetics that might be undone.