Section or page on commonly encountered issues

[smheidrich]

I think it might be useful to have an extra section or page on commonly encountered issues with links to the most useful patterns to solve them, plus maybe a short example here and there. Because while the Patterns section is immensely useful, it's difficult to know a priori if any of them will help with an issue at hand. Also, for each pattern, there are N common problems that can be circumvented with it, but they can't all be listed on the pattern's page without cluttering it. Whereas that would be possible on a page that consists mostly of short paragraphs with links to patterns.

For example, one issue I've had which I haven't seen mentioned in TLBoRM is nesting independent repetitions within each other, e.g. trying to do something like:

macro_rules! cartesian_product {
    ($($a:expr),+ ; $($b:expr),+) => {
        vec![ $( $( ($a, $b) ),+ )+ ]
    };
}

I guess a particularly common special case of this is trying to put an optional variable $($opt:tt)? inside a repetition. In any case, this won't work as written above, but can be done fairly easily using TT munching (or recursion more generally). But as it's just an application of that, it doesn't warrant its own Pattern page. Whereas its Common Issues entry could briefly describe the problem including typical error messages from the compiler and link to TT munching.

Some of the Patterns pages already contain descriptions of what limitations they're trying to get around (e.g. pushdown accumulation and callbacks) so those could be added to the Common Issues page as well.

Thoughts?

Maybe we can collect a few more common issues here before deciding on whether it'd be worth it. I could open a draft PR to collect them as well.