Use bolding only for warnings?

[flexibeast]

As discussed at #297 (e.g. this comment by @ericonr), i think it would be good to draw readers' attention to warnings via bolding. However, to ensure a consistent meaning for bolding, i think it should perhaps only be used in such cases, rather than to e.g. introduce terms, as in #177, where emphasis via *term* could be used instead.

(However, i don't think this issue should be considered a blocker for #177.)

[ericonr]

IMO it's okay to have bolding used for both.

"Warning: the runsvdir needs..." doesn't look too strange.

[flexibeast]

Well, my concern is not about how it looks, per se; it's about the semantics implied by particular styling. i think different semantics ("important information!!1!" vs. "introducing a new term") should have different styling, and making such a distinction could make it easier to automate changes in the future. (For example, if we later decided to use a different presentation for warnings, a search-and-replace can just look for **warning**, rather than having to worry that the bolding might indicate something else.)

[jeffayle]

I agree that the semantics suck here. Markdown fell behind html on semantics a decade ago. html has a tag that means semantically "this is a new term being introduced" (dfn). There's dozens of new html tags that have no counterpart in markdown that are really useful if you want good semantics.

As an aside though, I want to defend the bolding I used in #177. html-wise, strong is a poor tag to use, but in terms of style I think that the styling there should be bold rather than italic (or something similarly noticeable). I didn't use it to introduce a new term, I used it to mark a point where the guide branches. There are sections in the guide where a decision you make at one point affects what you have to do at a later point. When you're reading the guide and get to a bolded phrase you know does not apply to you, it is safe to ignore all the text until the next bolded phrase. If I had written the document in html, I would probably have used something like <section><h1>Term</h1> <p> ... </p> and styled it to look like it was actually <p><b>Term</b> ...</p>. It's semantically a sub section, but it's a very minor sub section that's not worth the visual space of making it look like one.

The only real solution I can see is to write the docs in something other than markdown. I think that's something to consider, but it's not a short-term solution.

Right now, there are certain things we can do within markdown

• Use a markdown renderer that supports better semantics. I don't see this being possible within mdbook and vmdfmt would have to be updated to cooperate, so this is really on the same scale of ditching markdown all together. This would get us a few more tags---I know for example that mdbook's renderer doesn't support definition lists, which is kind of a big deal semantically.
• Use inline html. This is completely straight forward so I'll skip over why it's useful and go right to why it's not as great as it sounds--- inline html starts as soon as you try to use an html tag and doesn't end until a matching closing tag is found. Nothing between the start and end tags is rendered or parsed as markdown. This would be okay for something like <dfn>, but for something like that bit of html I referenced earlier as what I would have done, would mean that entire paragraphs would need to be written in html.
• Contort markdown into producing some kind of html that can be contorted, visually, into something useful. We could use this to create semantics that are (1) syntactic shit (2) useful to us internally (3) completely useless for anyone else without making the semantics any worse. For example,

<!-- markdown -->
()[#technically-semantic-warning]

**Warning** something bad might happen, and **this is still bold**

/* css */
a[href=#technically-semantic-warning] + p > strong:first-of-type {
    font-weight: normal;
    text-style: italic;
}

It's a hack that's more at home somewhere like reddit than official documentation, but it's something to consider as a last resort if nothing else works.

[flexibeast]

@jeffayle: Thanks for explaining the semantics you were intending with the bolding in that case; that makes sense.

My primary concern at this point is some straightforward way to visually mark off warnings from other types of content. Given that simple bolding is being used for other things, how about bold italic, i.e. ***warning***? We can return to more sophisticated approaches re. semantics in general at a later point.

(i personally want to focus on #327, ensuring wiki content is adequately covered by the Handbook, and don't want to spend too much time on infrastructural(-ish) issues whilst that issue is still open.)

[jeffayle]

Actually, now that I think about it more, warnings and notes are basically the same semantics as what I was explaining before. The word "warning" or "note" is really a heading, it just needs another block level element to hold the whole thing together. markdown has basically one block-level element that would work at all here and it's the one that we decided not to use because of the semantics.

Given that simple bolding is being used for other things, how about bold italic, i.e. ***warning***?

This makes me a bit uneasy. It's syntactically ambiguous (does it output <em><strong> or <strong><em>?) and semantically iffy (what even is a strongly emphasized emphasis, or an emphasized strong emphasis). I think it's worth reconsidering blockquotes here, one doesn't really seem worse than the other.

So here's something I came up with: https://jsfiddle.net/ekf28wmp/2/

It's definitely a hack, but other than using a blockquote, the semantics aren't technically wrong. I have to include the warning though that some accessibility software is still based on the html4 outlining algorithm, which will generate an incorrect outline, so while it's technically not an accessibility issue it actually might be.

btw I said earlier,

and styled it to look like it was actually <p><b>Term</b> ...</p>.

turns out display: run-in still doesn't work? so I guess I'll skip this step.

[flexibeast]

Well, what i want is to be able to, in the Markdown, syntactically distinguish "warnings" from "notes", because i believe they're not always synonymous. i want this to facilitate possible conversion to a different source format in the future if necessary. In that sense, i don't necessarily mind what actual MD we use to indicate this, as long as we're assigning consistent MD syntax to the same semantics.

Obviously, as you said, we're hugely limited by (V)MD and how it mixes semantics and presentation; but within that constraint, we could (say) specify that in our MD, > should only ever be used for warnings, and we specify some other MD for simply quoting text. If the proposal you linked to means we can have distinct MD for warnings, notes, and text quotes, i'm certainly open to it.

[jeffayle]

If the proposal you linked to means we can have distinct MD for warnings, notes, and text quotes, i'm certainly open to it.

yes, that's exactly what it does. it uses the first child of the blockquote to decide whether it's a warning, a note or a normal blockquote (or you could add any other class).

here's a slight variation that doesn't have the outlining issues: https://jsfiddle.net/g5o3sqfp/

we could (say) specify that in our MD, > should only ever be used for warnings,

yeah, there's no problem contorting what > means in markdown, but it's still outputting <blockquote>. we could get rid of all these semantics problems by running the regular expressions s/<blockquote>/<section>/g and s/<\/blockquote>/<\/section>/g on the outputted html.

[flexibeast]

Okay, thanks. i like the variation you linked to, and adding those regexes to the build works for me. Thanks for coming up with this solution!

@ericonr: Ok? Any concerns, particularly in terms of building the non-HTML-based formats?

[jeffayle]

so vmdfmt chokes on inline html. and also on that stuff I was doing with headings. and also on ***.

[flexibeast]

@jeffayle: Oh. @ericonr: i'm wondering if maybe vmdfmt needs changing? Not sure when @bobertlo will be around again to comment on this, and to possibly make such changes. (Although of course, we could perhaps temporarily use a fork of vmdfmt ....)

[ericonr]

I'm not entirely sure how I feel about this. This whole thing is a bit over my head, tbh.

Ideally, I would like to completely remove Note: headings, using only constructs like It should be noted that ..., which frees up **Warning**: as the only type of paragraph that starts with a semi colon. This allows for simpler markdown that's still very easy to read as a "raw" file, and simpler HTML gen.

However, I see that we don't have any places with actual quotes besides the style guide, which is being moved out of the handbook anyway in #444, so repurposing quotes for warnings doesn't sound too horrible. I dislike that this breaks mdbook serving, however. You can mdbook build and then run the sed, but you can't locally mdbook serve the changed version.