speced / bikeshed

:bike: A preprocessor for anyone writing specifications that converts source files into actual specs.
https://speced.github.io/bikeshed
Creative Commons Zero v1.0 Universal
1.11k stars 200 forks source link

Some inconsistencies in specially recognized paragraphs (notes, examples etc.) #2626

Open woutermont opened 1 year ago

woutermont commented 1 year ago

When using the short hands provided by bikeshed to create (boxed) asides, I stumble upon some weird behaviour.

The generall rule seems to aim to recognize all keywords, in whatever case, followed by a colon, a comma (notes-only), or a single newline, followed by text.

Note: I used the plain bikespec template of v3.14.3.

I end up writing custon CSS like

    /* Reset base counters and additional ones */
    body { counter-reset: example note issue assertion advisement figure !important; }

    /* Configure increments for additional counters */
    .note { counter-increment: note; }
    .assertion { counter-increment: assertion; }
    .advisement { counter-increment: advisement; }

    /* Configure display of additional counters */
    .note:not(.no-marker)::before { content: "Note " counter(note); }
    .assertion:not(.no-marker)::before { content: "Assertion" counter(assertion); }
    .advisement:not(.no-marker)::before { content: "Advisement" counter(advisement); }

    /* Hide generated markers */
    .note,
    .issue,
    .example,
    .assertion,
    .advisement { 
      .marker { 
        display: none; 
      }
    }
tabatkins commented 1 year ago

Yeah, as these were introduced over time to the syntax, they're not completely consistent. There's no good reason for that, tho, and I know I've written Assert: foo lines expecting them to turn into assertions in my own specs. ^_^

Happy to align these.