-
Notifications
You must be signed in to change notification settings - Fork 181
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
Use bolding only for warnings? #324
Comments
IMO it's okay to have bolding used for both. "Warning: the runsvdir needs..." doesn't look too strange. |
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 |
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 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
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. |
@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. (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.) |
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.
This makes me a bit uneasy. It's syntactically ambiguous (does it output 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,
turns out |
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, |
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/
yeah, there's no problem contorting what |
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? |
so vmdfmt chokes on inline html. and also on that stuff I was doing with headings. and also on |
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 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 |
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.)
The text was updated successfully, but these errors were encountered: