Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

Quuxplusone
Copy link

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
Copy link

ferdnyc commented Jan 21, 2024

-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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants