Stop referring to "Examples" in the docs; "Example:" is not supported

[Quuxplusone]

This patch is not ready for prime time, as indicated by the [TODO FIXME WHAT GOES HERE]. But I hope it's somewhat useful.

I wanted to add an "Example:" block to a C++ paper — basically a "Note:" but with the implication that readers might as well just skip over it if they don't care. The documentation for Bikeshed has a section on "... Examples, ..." — but the section title seems to be a lie: Bikeshed doesn't support Example: markup in anything like the way it does for Note: or Issue:.

I do wonder if Assert: is intended to be kind of like an "Example." But of course I don't want my paper to actually say the word "Assert:" inside the gray box. So I'll use some custom div styling, probably.

I have not checked whether the .example class actually exists (the doc says it does), but I have definitely checked that the .bs syntax Example: doesn't trigger it.

[ferdnyc]

-1 from me. It's true "Example:" is not supported as an automatic callout type, and the docs never claim it is.

The Markdown processor specially recognizes paragraphs starting with "Issue: ", "Advisement: ", "Assertion: ", "Note: ", or "Note, ", and will add a matching class to the paragraph automatically.

But of course examples are supported, even Bikeshed's own documentation is lousy with them. And the documentation explains how to insert them:

Elements with the .example class will also be given a generated-content "header" in the format EXAMPLE n with an auto-incrementing number, and have self-links created to allow linking directly to the example.

All MarkDown formats (including .bs) accept raw HTML in addition to MarkDown, and the example support is coded to make use of that rather than using "Example:" paragraphs, which are far too limited for presenting examples. Example content may contain code blocks and other markup much more complex than a simple paragraph of text. So, examples have to be coded as HTML.

The examples in the Bikeshed docs themselves use a pretty standard HTML container:

<div class="example">
    ...
</div>

Everything represented by "..." will be enclosed in an "EXAMPLE #" callout box.

Notes, issues, etc. can also be created the same way, optionally — as the documentation also explains. For example, these two paragraphs are equivalent, and both create a "NOTE:" callout box:

Note: Lorem ipsum dolor sit amet...

<p class="note">
Lorem ipsum dolor sit amet...
</p>

Perhaps this could be explained in more detail in the documentation, but the place to explain it would be in exactly the section titled "Notes, Issues, Examples, Advisements", which absolutely does cover the (supported!) example formatting requirements.