docs(examples/multi-spec): how to set secrets, avoid push conflicts

[tidoust]

This adjusts the documentation for a multi-documents repository to clarify how to pass Echidna tokens per document (see #55), and to highlight the possible need to serialize jobs (at least until #58 gets addressed).

[tidoust]

Build fails because ReSpec wants to process the bits of code I put in the prose. How can I prevent that?

More precisely, I can prevent ReSpec processing with a backslash ${{\ foo }}, but the backslash would then appear in the markdown version of the doc...

[sidvishnoi]

More precisely, I can prevent ReSpec processing with a backslash ${{\ foo }}, but the backslash would then appear in the markdown version of the doc...

Lets go with that for now. I'll figure out a fix later.

[sidvishnoi]

@marcoscaceres We should probably add a check in ReSpec to not do the ${{ term }} expansion if it's wrapped in a <code>. WDYT?
I faced this problem in https://respec.org/docs/src.html also (ended up using a zero-width space hack there - added on include, removed in postProcess).

[sidvishnoi]

Thanks @tidoust!

[marcoscaceres]

@marcoscaceres We should probably add a check in ReSpec to not do the ${{ term }} expansion if it's wrapped in a <code>. WDYT?

That probably wouldn't work, e.g.,:

Someone could do <code>{{ whatver/thing }} = "ffs"</code>, then blah blah.. 

We should use {{\ as the escape hatch, as we do with other things.

[tidoust]

We should use {{\ as the escape hatch, as we do with other things.

Which works well for the ReSpec version of the documentation. Problem is this documentation also exists as a pure Markdown file on GitHub, linked from the README, where {{\ is not an escape hatch, see first Note in:
https://github.com/w3c/spec-prod/blob/main/docs/examples.md#multiple-specs-in-same-repository

[marcoscaceres]

Ah, I read it backwards :)

Yeah, this is why I think we should just fold everything into index.html. We are pointing everyone to that document anyway.