My personal feedback is just don’t set the font and everyone can use their preferred default font. If you really feel the need for some “personality” set a font for headers but leave the body text alone.
But I’m probably in the minority and most users have terrible default fonts.
On my system, the browser is configured to ignore all website font requests. It is kinda funny using bad websites that insist on icon fonts and such (looking at most anything Google makes), but since they’re bad websites, I can only gain by not using them.
My bliss is real never having to see these things.
Yeah, I did this for a while and it was quite nice. Unfortunately icon fonts haven’t completely died out yet.
I don’t know if I would go as far as calling those sites “bad”, it was the best option available for quite a while. Thankfully technology has improved such that inline SVG or separate images can fill the role and perform better.
Oh! I thought you meant the site design was in progress. I thought it was quite cook for the headings but find my default font more readable for the main copy.
came up with semantic styles way before the semantic web was established. It’s just a very good invention. Bolding a word to highlight it is fine, but way too often people
It might be the interaction with Windows’ antialisaing, but I had to switch to reader mode to read the article. The font is so narrow that vertical lines almost disappear in places.
I’ve never known anyone who uses hotkeys for styling in Word. I’ve tried to learn them and they’re too inconsistent. None of these programs are designed with hotkeys in mind.
Cmd-I for italics or Cmd-B for bold should work in every program dealing with text. Please don’t tell me they don’t work in Word (which I’ve rarely used).
You would think that, but that is solved in a very elegant manner! I can’t speak for Portuguese, but in Norwegian ctrl + F is not search, it is bold because of the Norwegian word for bold is “fet”. So how do you search? Ctrl + B of course. That key isn’t used for anything.
It wouldn’t surprise me that Ctrl + F is new file in Portuguese Office…
That’s not an iff with two f’s — I have never used Office in English.
You are correct that Ctrl+N makes bold text in Microsoft Office on Windows in Portuguese, but that is obviously something you managed to learn, with a simple mnemonic. Compared to learning vim, it seems fairly manageable.
That is true if, and only if, your Office is in English.
Yes. I need to use Word at work. In German Word, it’s CTLR+F for making text bold (as the German word for “bold“ is “fett”). Since for office documents sent to me I use LibreOffice at home (which does use the familiar CTRL+B regardless of locale) I am eternally suffering by Word’s special way to handle this.
You’re not supposed to just bold text, so that’s a pittance. They’ve put so much work in the semantic styles but only the first 3 styles have their own hotkeys, and my European keyboard breaks one of them.
If your output is HTML+CSS, you can manually add styling information to Markdown.
To me, the ability to seamlessly “escape” into HTML is a big draw of Markdown. I despise its table syntax so I generally just use HTML tables in the rare cases I need them.
The HTML “escape” makes Markdown internally inconsistent (as if it wasn’t already due to lack of standardisation) and one of the most complex formats invented, right next to MS Word.
Very well. But in case anyone’s curious, here’s the text-markup-no-one-uses that I’ve got my eyes on: DocBook.
(Content warning: good stuff, but also written by Eric Raymond, whom you may find disagreeable. Shoot the proverbial messenger, though, not the message.)
DocBook looks like XML to me. If I were to accept XML, I’d rather use a tool to generate conformant XHTML and use CSS to get different outputs.
The point of MD (and similar, like reStructured Text, Textile, Asciidoc etc) is to avoid the tagsoup of {SG,H,X}ML when actually writing content.
I actually think (La)TeX is the sweetspot here. It has markup, sure, but it’s much less intrusive when writing than tag-based markup. I.e. you write \emph{text} instead of <em>text</em>.
According to Wikipedia, DocBook is still being supported by the OASIS group.
The point of MD (and similar, like reStructured Text, Textile, Asciidoc
etc) is to avoid the tagsoup of {SG,H,X}ML when actually writing
content.
Asciidoc is semantically equivalent to DocBook. It is a plaintext
representation of DocBook without the tag soup. With Asciidoc driving a
DocBook toolchain, you can have all of the output formats supported by
DocBook for free. As someone who prefers reading documentation in info
mode under emacs, I really appreciate that.
I’ve advocated for it in a situation where markdown wasn’t capable
enough, and I’d do so again.
LaTeX is a nice nesting markup syntax, for sure. However, at its core, it’s still an imperative language—with pervasive use of global variables, to boot.
True, but I’ve always had an issue with the fact that Markdown embeds HTML in a way that doesn’t nest. Once you’re inside a single HTML element, no more nice link and emphasis syntax for you. On top of that, this can also date an individual document to the trends in play when it was written, making it a poor document format in the long term.
This connection also limits Markdown to a format that must be converted to HTML before anything else. But I guess that matches its most common use case, even if it also makes it significantly less than ideal for a document authoring format.
I could select a word, navigate to the “subtle emphasis” section, and apply it, all using the keyboard. When you hit ‘Alt’, a bunch of letter appear in the ribbon that allows you to access the different parts of the ribbon and select them.
Is it as easy as “Cmd-I”? No, but it’s more discoverable than Emacs…
Word came up with semantic styles way before the semantic web was established. It’s just a very good invention. Bolding a word to highlight it is fine, but way too often people use it for titles, and then it’s not just bolding but bigger size and different font too. This is not uncommon in offices. Decades of human labor have been lost to “oh I want all h2 headers one size smaller”, and mistakes are easy so it ends up ugly.
Semantic headings are also important for accessibility. Using screen reader commands to jump to elements matching particular criteria, such as headings or even headings at a specific level, is the closest that a blind person can get to skimming.
This is defeatist thinking about screen reader technology.
A sighted person does not have semantic headings to help them skim. They just have text size and weight.
Today, we have to provide screen readers with semantic hinting in order to enable skimming (and this helps the content creator, as well, through styling etc, so I’m not really arguing against it). But there’s no reason a BETTER screenreader can’t deduce these semantics from rendered font sizes.
You can’t hope to fix a problem by expecting a billion content creators to do the right thing. We have to fix it by enabling tools to do the right thing with the wrong input.
I get your point. In fact, my company provides a tool that tries to automatically make documents more accessible, using the best available heuristics for things like headings and tables, as well as OCR. For the many existing documents out there, especially PDF documents, this is the best we can do. And of course, there will continue to be new inaccessible documents as well. But heuristics are fundamentally unreliable, so we should encourage document authors to directly convey document structure, and make it as easy as possible for them to do so. We should take both approaches at once.
I like your main thesis, but some of your examples don’t help you make your case:
Markdown is easy to read and write for humans, but simple certainly it is not. Parsing Markdown correctly is harder than parsing some non-textual formats.
git is neither simple nor easy to use, even compared to other version control systems. It’s just so popular that using something else limits your ability to collaborate with other people. (Of course, version control is an intrinsically complex problem, not well served by overly simplistic tools, blah blah blah…)
PDFs generated from Markdown files using Pandoc look noticeably worse than PDFs generated from handwritten LaTeX. If you want to beautifully typeset formulas or diagrams past a certain complexity threshold, then you sometimes have to use godforsaken ugly incomprehensible LaTeX hacks.
You say that you wouldn’t use Blogspot or WordPress again, because of the possibility that “the platform deletes your account without notice”. Why couldn’t this happen with GitHub Pages as well?
At the end of the day, tool choices are driven by a combination of convenience, laziness and culture (“I don’t want to change my existing habits”). Any “universal principles” you come up with will almost certainly fail to take into account someone’s needs.
For the books that I’ve written, I tried very hard to write in semantic markup. Markdown just isn’t expressive enough for the things that I wanted to be concise. For example, I can make things code but I can’t differentiate between code that should be syntax highlighted as C and code that should be syntax highlighted as shell script. I can’t annotate key words, which should be both italicised and added to the index. I can’t mark the expansion of an initialism, which should be added to the glossary. I wrote using TeX syntax, but an intentional subset with all of the macros defined in a header when producing PDF and then I could parse the same code and generate semantic HTML for the ePub editions and style it with CSS. It would look something like this in the raw form:
The \ccode{open} function opens a file on the \keyabbrv{filesystem}{FS}. \lstref{exopen} shows how this is used.
\listing{open.c}{ex1}{exopen}{Example of the \ccode{open} system call.}
When rendered, open would be rendered as C code, the keyabbrv expands to filesystem (FS) and is added to the index, the lstref becomes something like Listing 1 on the next page (depending on where it ends up) and the listing has the caption from the text and will insert the code from open.c between the ex1-begin and ex1-end markers in comments, with line numbers. I know that the code examples compile because they’re pulled in from real source files that I can build and test.
Markdown is fine for simple things but I really miss the ability to define a concise dialect of semantic markup when using it.
Aside from using different tools, what you do is exactly what I am advocating for (which is probably the only solution that would work above a certain level of complexity) starting from a simpler format that is based on plaintext (in this case one that you invented) and then converting to other markup formats.
I’m not disagreeing with your overall thesis, I’m just lamenting the fact that we don’t have a good easy-to-parse human-writeable extensible semantic-markup language. XML is easy(ish, if you ignore the difficult bits) to parse and is extensible but is definitely not human writable. TeX is not a markup language, it’s a program format. Markdown is not extensible and the extension mechanisms built on top of Markdown are overly verbose and difficult to write.
I used an ad-hoc LaTeX-like dialect, but there were a bunch of corner cases for a parser because TeX treats several characters as special and magic. I’d love to have a standard, something that does to XML as a markup language what JSON did to XML for representing structured data. Something easy to write, easy to parse, and easy to then write translators that exported HTML, LaTeX, SILE, or whatever.
Indeed there are some hairy edge cases, but in general 99% of what you write can probably be parsed by some Perl regex.
For git, I would get some good front-end that mitigates most of it’s issues.
That’s the point, you can write in markdown and then go through LaTeX for title-pages, headers, footers etc. You can go from simple to complex, but not the other way around.
It can, but the difference will be that my websites will be up again in a few minutes on another platform. I will also manage if Jekyll is dead. Or if git stops working. Overall, my point wasn’t that those are perfect technologies, they are just the ones I use to publish plaintext.
Pandoc can’t handle every use case where you would use LaTeX. For example, generating a bibliography and keeping it sync with the citations in your document (with compilation errors when you cite a book not in your bibliography, and warnings when a book in your bibliography is not cited anywhere) requires compiling your document three times.
I fully agree with your other three points, though.
This and 100 times this. In fact I’ve just consolidated various blogs into a single blog, by moving over all the separate posts into a single directory structure. All in Markdown. I’ve been through the gamut of Blogspot, Blosxom*, Wordpress, Moveable Type, Ghost, and then to Jekyll with static files and hosting (via GitHub Pages), so have experienced a similar epiphany.
I just this weekend I moved from Jekyll to Eleventy, partly because I was tired of the complexity of Jekyll (subjective, I know) and felt I’d be closer to the JS of Eleventy if I needed to hack it, but mostly because I could as all of that blogging content is in Markdown.
*Blosxom for me was the purest solution in this vein, and as Boris describes.
It is a well-known engineering principle, that you should always use the weakest technology capable of solving your problem - the weakest technology is likely the cheapest, easiest to maintain, extend or replace and there are no sane arguments for using anything else.
For text files, we have git which is the same thing, except a thousand times more powerful e.g. you can go back as far as you like, you can create different branches, where different people make different changes, you can merge several different versions of a file into one automatically.
you would find that writing markdown is faster than applying styling by using the mouse
What about folks who have trouble using keyboards?
The one I use is called vim, but since it takes time to getting used to I won’t be preaching it to you (you can click the link to read all about why I use it.)
What about folks who have trouble using keyboards?
Presumably they’d write using a different tool. There are lots and lots of voice-dictation solutions out there, most of which can output to plain text.
Which voice-dictation solution would I use? The only ones I’m familiar with are MacOS and Windows’ included dictation software. How would I use vim? Oh, and what if I am vision impaired, how does plain text work there? Screen reader? How does Markdown work with a screen reader?
Why would you use vim? Use notepad, or whatever you’d like to use. Nobody is forcing (or even suggesting) that you use vim.
If you are vision impaired, plain text works great. It just reads the text to you, same as this comment. If you’re concerned about Markdown formatting, well, a) that’s a trivial task for screenreader software to fix, if it hasn’t already, and b) Nobody’s suggesting you read complex plain-text markdown anyway. They’re suggesting that the markdown be converted to simple HTML for viewing.
I don’t recommend any specific screenreader, as I am not visually impaired. As a developer, I have fairly significant experience working with TalkBack on Android, which handled text blocks and HTML perfectly well to my preferences.
I’m sure most visually impaired users have screen readers that they prefer to use, I’ll leave it to them to comment on recommendations.
TalkBack is one of the best flows I know also but it’s only available on Android. Without a serious recommendation on how to make a plain-text flow work through a screen reader and dictation software on a PC, I am comfortable with saying that the author did not really consider accessibility in this rant.
There’s no need to prove accessibility from first principles for every post. Plaintext reading and writing had great accessibility, as does simple HTML rendering. There’s nothing else to this post.
There’s no need to prove accessibility from first principles for every post.
There isn’t for every post, but there is a need to keep posting about plain text flows and to advocate in comments for plain text flows? There’s dozens of posts/threads on Lobsters about the power of plain text, and that’s fine?
I think I’d say yes? Do you want to see a post about plain text workflows with screen readers? Dyslexic fonts? Braille devices? Eye tracking keyboards?
Workflows don’t have to be accessible to everyone. Rather, we need accessible workflows for every outcome. There’s tons of ways to create static HTML websites. Many of those ways are accessible to various subsets of people. This is one such way, which I would argue is accessible to a huge swath of people, but for anyone who feels that it isn’t for them, there’s tons of other perfectly great ways to accomplish the same outcome of producing your own HTML in a fairly low-effort way.
This sounds like a double standard to me. Multiple, overlapping, posts here about plain text are fine. Asking for accessibility in the comments and there’s opprobrium. Either allow both types of content or neither.
Do you want to see a post about plain text workflows with screen readers? Dyslexic fonts? Braille devices? Eye tracking keyboards?
Yes to all of the above. If we spent even a fraction of the time we keep ranting about plain text tools on accessibility, I think it would be a boon to impaired users. On the other hand, IMO the marginal value of Yet Another Plain Text Evangelism Post is minimal.
I think standalone stories about accessibility would be welcomed, even if they overlapped to the extent that plain text posts do. Raising concerns about accessibility in the comments of a story about plain text gets pushback because some people think plain text already has good accessibility, and in these comments, concerns about accessibility in general seem off topic. You seem to be implying that plain text is likely to be less accessible than alternatives – why do you think that?
As plain text is the lowest common denominator and can be converted using tools like Pandoc, there’s at least a limit of how much worse than the most accessible experience plain text can be. If, for example, writing rich text Microsoft Word is easier than writing any markup language in any plain text editor, then storing your files in plain text wouldn’t be much worse because you could automatically convert them to Word format just for the editing process.
You seem to be implying that plain text is likely to be less accessible than alternatives – why do you think that?
Accessibility generally requires metadata to be available. Which language is a given post in? How does the screen reader know which parts of a post to say aloud and which parts not to? Think about Markdown, you can surround “code” in backticks, but does that mean content in backticks need to be skipped? Markdown isn’t equipped to separate “code” from “math” from quoting passages. If you render Markdown into HTML that’s fine, but what about writing the Markdown itself? And which screen-reader software would I use to write plain-text? Screen readers need to support deleting words, navigating through a document, editing words, etc. Software like Word usually offers OS level hints for accessibility, which helps in interaction with dictation software.
I’m coming from the perspective of someone with bad RSI. Using the terminal, writing plain text documents, all of these things are quite cumbersome using dictation software. Most dictation software I’ve used has only really been okay typing sentences into a chat program. When I see people suggest “just use a screenreader”, it feels dismissive. It’s like someone saying “well your language is Turing complete, so it’s definitely doable”. It’s a largely theoretical epithet offered to check a box; unfortunately I’m the one that needs the box to be checked, so an epithet doesn’t fix my problems.
concerns about accessibility in general seem off topic
What is on-topic in these threads? Plain text evangelism gets posted here all the time. In my mind, it feels these feel like posts are about an ethos not an actual technological thing. As such, there’s nothing particularly meaty to talk about unless we’re talking about lifestyles here, in which case commentary about accessibility seems purely on-topic.
So, these are useful criticisms of “plain text is accessible”. Let me address them as best as I can:
“Which language is a post in?” is a basic feature of a screenreader, and indeed, of the human experience. A post is assumed to be in the language of the device, as configured by the user. In much the same way that a sighted user can view a post and say “This is in English”, a screen reader user can hear a post read via an english-language screenreader and say “this is in english.” If it starts to sound like badly accented german instead, well, it probably is, but this is a human skill, as well as a screenreader skill. A plain text post is not annotated with language for a sighted user, either, and that’s ok, because the post is either in a language that the sighted user understands, or it isn’t. Same thing with a vision-impaired user. There’s no mystery about what language a post is in to a person who speaks that language, and there’s an equal amount of mystery for an unsighted or sighted person who is viewing the same post. This is an unfortunate reality of language.
That said, a screenreader (the screenreader industry) has a huge advantage over the non-screenreader industry in that it is fairly trivial to build language detection into the screenreader, and it can automatically switch pronounciation to the correct language. A sighted user can either annotate all text with expected language, or they can figure it out themselves. Either is more effort than having the reader automatically switch. In reality, I don’t believe this is a hugely desired feature of screenreaders, but it’s not a huge accomplishment to run language detection on each paragraph.
I don’t see any reason that a markdown screenreader should skip code passages? Instead, it should read the passage, and allow the user to skip it if it is incomprehensible to them. Presumably, the reader will have written the markdown themselves, and will understand what it says, but that’s up to the user. It could just as easily be an uninteresting paragraph about anything, that they’d like to skip.
Re: producing markdown: You can probably just write word docs, and convert them to markdown using various software packages, or websites. This is a fairly well-trodden path that works pretty well, particularly if you’re using simple Word docs intended for conversion to markdown. This requires an extra step in your conversion workflow, of course, but it’s pretty trivial to automate that step in your static website generator if you choose to go that route. On the other hand, I just tried editing markdown in TextEdit on Mac, using voice control, and it wasn’t terrible? Considering I’ve put no effort into learning voice control (or markdown, honestly), I don’t see the barrier, here. The only problem I had was entering URLs, and I imagine I was just doing something wrong.
Guys, I am sure we all mean well here, so no need to argue. Accessibility might be off-topic in the sense that it is not being tackled in my post, but still it is interesting nuance to the topic of publishing.
Now, I didn’t include anything about accessibility simply because I don’t know anything about it. I use a screenreaders sometimes to check how my texts “sound” (mainly when writing fiction), but that is about it. In terms of screenreader, I would recommend the Mac platform, as it has a marvelous reading software at OS-level, AFAIK they have some other good accessibility features too (if you count screenreaders as accessibility.)
Otherwise I am sorry to hear that the command-line is not accessible for the visually impaired, as I think that it can be made accessible, due to it’s simplicity (you basically type a message in the console and get a message as a response.)
Also weird and unfortunate is the fact that there isn’t a good plain text editor with accessibility features. One time I wrote a little one-liner in my vimrc that integrated it with the command-line dictation command for Mac and it works quite well (see my post on vim for more info.) I had a keyboard shortcut that reads the selected text. I imagine that something like a plugin that reads the word under your cursor would be doable too.
Otherwise I am sorry to hear that the command-line is not accessible for
the visually impaired,
Speaking as a blind person, I wish people would stop spreading this
particular line of FUD. The command line is perfectly accessible to
people who are visually impaired. It always has been and always will
be. So is plain text. Please no what-abouts; I am tired of this fight.
I’m not talking about accessibility in theory. Much like you recommended tooling (vim or sublime) for writing and (Pandoc) processing, what tools would we use to interact with to drive the Markdown<->HTML edit loop? Which dictation software, what screen reader? How would that flow look like?
Unreadable font
Just a bit wonky, helps with dyslexia. Very readable actually, but maybe too off-putting for most.
Haha, it’s my design. Work in progress. Seems to have some issues with rendering on some screens. Feedback welcome ;)
My personal feedback is just don’t set the font and everyone can use their preferred default font. If you really feel the need for some “personality” set a font for headers but leave the body text alone.
But I’m probably in the minority and most users have terrible default fonts.
On my system, the browser is configured to ignore all website font requests. It is kinda funny using bad websites that insist on icon fonts and such (looking at most anything Google makes), but since they’re bad websites, I can only gain by not using them.
My bliss is real never having to see these things.
Yeah, I did this for a while and it was quite nice. Unfortunately icon fonts haven’t completely died out yet.
I don’t know if I would go as far as calling those sites “bad”, it was the best option available for quite a while. Thankfully technology has improved such that inline SVG or separate images can fill the role and perform better.
Hm, I actually didn’t know you can set a default font for browsers.
In this case, this is a font that I am designing, so I meant to ask about feedback for the font itself.
Oh! I thought you meant the site design was in progress. I thought it was quite cook for the headings but find my default font more readable for the main copy.
It might be the interaction with Windows’ antialisaing, but I had to switch to reader mode to read the article. The font is so narrow that vertical lines almost disappear in places.
Strawman detected.
I’ve never known anyone who uses hotkeys for styling in Word. I’ve tried to learn them and they’re too inconsistent. None of these programs are designed with hotkeys in mind.
Cmd-I for italics or Cmd-B for bold should work in every program dealing with text. Please don’t tell me they don’t work in Word (which I’ve rarely used).
That is true if, and only if, your Office is in English.
In Portuguese, I am sure Ctrl+N is the keystroke for making it bold (negrito in Portuguese).
Therefore, @theblacklounge has a point: the keystrokes aren’t consistent in Word, and not consistent among same version in different idioms.
I would be surprised as it would surely conflict with the new document shortcut.
You would think that, but that is solved in a very elegant manner! I can’t speak for Portuguese, but in Norwegian ctrl + F is not search, it is bold because of the Norwegian word for bold is “fet”. So how do you search? Ctrl + B of course. That key isn’t used for anything.
It wouldn’t surprise me that Ctrl + F is new file in Portuguese Office…
I think you’re abusing the phrase “if and only if”. Pretty sure last time I used Office in Hebrew, the keyboard shortcuts were all the same.
That’s not an iff with two f’s — I have never used Office in English.
You are correct that Ctrl+N makes bold text in Microsoft Office on Windows in Portuguese, but that is obviously something you managed to learn, with a simple mnemonic. Compared to learning vim, it seems fairly manageable.
Yes. I need to use Word at work. In German Word, it’s CTLR+F for making text bold (as the German word for “bold“ is “fett”). Since for office documents sent to me I use LibreOffice at home (which does use the familiar CTRL+B regardless of locale) I am eternally suffering by Word’s special way to handle this.
You’re not supposed to just bold text, so that’s a pittance. They’ve put so much work in the semantic styles but only the first 3 styles have their own hotkeys, and my European keyboard breaks one of them.
I mean… Isn’t there a similar gap in semantic styling in Markdown itself?
If your output is HTML+CSS, you can manually add styling information to Markdown.
To me, the ability to seamlessly “escape” into HTML is a big draw of Markdown. I despise its table syntax so I generally just use HTML tables in the rare cases I need them.
The HTML “escape” makes Markdown internally inconsistent (as if it wasn’t already due to lack of standardisation) and one of the most complex formats invented, right next to MS Word.
There are 2 kinds of
programming languagestext markups: the ones everyone complains about, and the ones no-one uses.Very well. But in case anyone’s curious, here’s the text-markup-no-one-uses that I’ve got my eyes on: DocBook.
(Content warning: good stuff, but also written by Eric Raymond, whom you may find disagreeable. Shoot the proverbial messenger, though, not the message.)
DocBook looks like XML to me. If I were to accept XML, I’d rather use a tool to generate conformant XHTML and use CSS to get different outputs.
The point of MD (and similar, like reStructured Text, Textile, Asciidoc etc) is to avoid the tagsoup of {SG,H,X}ML when actually writing content.
I actually think (La)TeX is the sweetspot here. It has markup, sure, but it’s much less intrusive when writing than tag-based markup. I.e. you write
\emph{text}instead of<em>text</em>.According to Wikipedia, DocBook is still being supported by the OASIS group.
Asciidoc is semantically equivalent to DocBook. It is a plaintext representation of DocBook without the tag soup. With Asciidoc driving a DocBook toolchain, you can have all of the output formats supported by DocBook for free. As someone who prefers reading documentation in info mode under emacs, I really appreciate that.
I’ve advocated for it in a situation where markdown wasn’t capable enough, and I’d do so again.
LaTeX is a nice nesting markup syntax, for sure. However, at its core, it’s still an imperative language—with pervasive use of global variables, to boot.
True, but I’ve always had an issue with the fact that Markdown embeds HTML in a way that doesn’t nest. Once you’re inside a single HTML element, no more nice link and emphasis syntax for you. On top of that, this can also date an individual document to the trends in play when it was written, making it a poor document format in the long term.
This connection also limits Markdown to a format that must be converted to HTML before anything else. But I guess that matches its most common use case, even if it also makes it significantly less than ideal for a document authoring format.
Making a title is easier than bolding in md. You can’t fake a title with just style cause you can’t set font size etc.
I just fired up Word (365, Windows 10).
I could select a word, navigate to the “subtle emphasis” section, and apply it, all using the keyboard. When you hit ‘Alt’, a bunch of letter appear in the ribbon that allows you to access the different parts of the ribbon and select them.
Is it as easy as “Cmd-I”? No, but it’s more discoverable than Emacs…
That’s not a hotkey, it’ll never be faster than using the mouse.
Why are you not supposed to bold text? Not everyone writes for the semantic web.
Word came up with semantic styles way before the semantic web was established. It’s just a very good invention. Bolding a word to highlight it is fine, but way too often people use it for titles, and then it’s not just bolding but bigger size and different font too. This is not uncommon in offices. Decades of human labor have been lost to “oh I want all h2 headers one size smaller”, and mistakes are easy so it ends up ugly.
Semantic headings are also important for accessibility. Using screen reader commands to jump to elements matching particular criteria, such as headings or even headings at a specific level, is the closest that a blind person can get to skimming.
This is defeatist thinking about screen reader technology.
A sighted person does not have semantic headings to help them skim. They just have text size and weight.
Today, we have to provide screen readers with semantic hinting in order to enable skimming (and this helps the content creator, as well, through styling etc, so I’m not really arguing against it). But there’s no reason a BETTER screenreader can’t deduce these semantics from rendered font sizes.
You can’t hope to fix a problem by expecting a billion content creators to do the right thing. We have to fix it by enabling tools to do the right thing with the wrong input.
I get your point. In fact, my company provides a tool that tries to automatically make documents more accessible, using the best available heuristics for things like headings and tables, as well as OCR. For the many existing documents out there, especially PDF documents, this is the best we can do. And of course, there will continue to be new inaccessible documents as well. But heuristics are fundamentally unreliable, so we should encourage document authors to directly convey document structure, and make it as easy as possible for them to do so. We should take both approaches at once.
Agreed.
Reading this comment on a site where people regularly debate vi vs emacs made my day.
I haven’t seen this for ages, and it’s the biggest tragedy of the impending vscode monoculture.
It’s common for word processors and transcriptionists to use keyboard shortcuts.
What is there was a way to make good-looking books using plaintext markup language? Wait… ;)
I like your main thesis, but some of your examples don’t help you make your case:
Markdown is easy to read and write for humans, but simple certainly it is not. Parsing Markdown correctly is harder than parsing some non-textual formats.
git is neither simple nor easy to use, even compared to other version control systems. It’s just so popular that using something else limits your ability to collaborate with other people. (Of course, version control is an intrinsically complex problem, not well served by overly simplistic tools, blah blah blah…)
PDFs generated from Markdown files using Pandoc look noticeably worse than PDFs generated from handwritten LaTeX. If you want to beautifully typeset formulas or diagrams past a certain complexity threshold, then you sometimes have to use godforsaken ugly incomprehensible LaTeX hacks.
You say that you wouldn’t use Blogspot or WordPress again, because of the possibility that “the platform deletes your account without notice”. Why couldn’t this happen with GitHub Pages as well?
At the end of the day, tool choices are driven by a combination of convenience, laziness and culture (“I don’t want to change my existing habits”). Any “universal principles” you come up with will almost certainly fail to take into account someone’s needs.
For the books that I’ve written, I tried very hard to write in semantic markup. Markdown just isn’t expressive enough for the things that I wanted to be concise. For example, I can
make things codebut I can’t differentiate between code that should be syntax highlighted as C and code that should be syntax highlighted as shell script. I can’t annotate key words, which should be both italicised and added to the index. I can’t mark the expansion of an initialism, which should be added to the glossary. I wrote using TeX syntax, but an intentional subset with all of the macros defined in a header when producing PDF and then I could parse the same code and generate semantic HTML for the ePub editions and style it with CSS. It would look something like this in the raw form:When rendered, open would be rendered as C code, the
keyabbrvexpands to filesystem (FS) and is added to the index, thelstrefbecomes something likeListing 1 on the next page(depending on where it ends up) and the listing has the caption from the text and will insert the code fromopen.cbetween theex1-beginandex1-endmarkers in comments, with line numbers. I know that the code examples compile because they’re pulled in from real source files that I can build and test.Markdown is fine for simple things but I really miss the ability to define a concise dialect of semantic markup when using it.
Aside from using different tools, what you do is exactly what I am advocating for (which is probably the only solution that would work above a certain level of complexity) starting from a simpler format that is based on plaintext (in this case one that you invented) and then converting to other markup formats.
I’m not disagreeing with your overall thesis, I’m just lamenting the fact that we don’t have a good easy-to-parse human-writeable extensible semantic-markup language. XML is easy(ish, if you ignore the difficult bits) to parse and is extensible but is definitely not human writable. TeX is not a markup language, it’s a program format. Markdown is not extensible and the extension mechanisms built on top of Markdown are overly verbose and difficult to write.
I used an ad-hoc LaTeX-like dialect, but there were a bunch of corner cases for a parser because TeX treats several characters as special and magic. I’d love to have a standard, something that does to XML as a markup language what JSON did to XML for representing structured data. Something easy to write, easy to parse, and easy to then write translators that exported HTML, LaTeX, SILE, or whatever.
Pandoc can’t handle every use case where you would use LaTeX. For example, generating a bibliography and keeping it sync with the citations in your document (with compilation errors when you cite a book not in your bibliography, and warnings when a book in your bibliography is not cited anywhere) requires compiling your document three times.
I fully agree with your other three points, though.
This and 100 times this. In fact I’ve just consolidated various blogs into a single blog, by moving over all the separate posts into a single directory structure. All in Markdown. I’ve been through the gamut of Blogspot, Blosxom*, Wordpress, Moveable Type, Ghost, and then to Jekyll with static files and hosting (via GitHub Pages), so have experienced a similar epiphany.
I just this weekend I moved from Jekyll to Eleventy, partly because I was tired of the complexity of Jekyll (subjective, I know) and felt I’d be closer to the JS of Eleventy if I needed to hack it, but mostly because I could as all of that blogging content is in Markdown.
*Blosxom for me was the purest solution in this vein, and as Boris describes.
While the CSS isn’t up to much yet, I’m super happy to have everything in one place (well, nearly everything).
Fact: “weak” and “powerful” are antonyms.
Surely one day somebody will care about accessibility.
How so?
What about folks who have trouble using keyboards?
What about folks who have trouble using keyboards?
Presumably they’d write using a different tool. There are lots and lots of voice-dictation solutions out there, most of which can output to plain text.
Which voice-dictation solution would I use? The only ones I’m familiar with are MacOS and Windows’ included dictation software. How would I use vim? Oh, and what if I am vision impaired, how does plain text work there? Screen reader? How does Markdown work with a screen reader?
Why would you use vim? Use notepad, or whatever you’d like to use. Nobody is forcing (or even suggesting) that you use vim.
If you are vision impaired, plain text works great. It just reads the text to you, same as this comment. If you’re concerned about Markdown formatting, well, a) that’s a trivial task for screenreader software to fix, if it hasn’t already, and b) Nobody’s suggesting you read complex plain-text markdown anyway. They’re suggesting that the markdown be converted to simple HTML for viewing.
Which screen reader software do you recommend?
I don’t recommend any specific screenreader, as I am not visually impaired. As a developer, I have fairly significant experience working with TalkBack on Android, which handled text blocks and HTML perfectly well to my preferences.
I’m sure most visually impaired users have screen readers that they prefer to use, I’ll leave it to them to comment on recommendations.
TalkBack is one of the best flows I know also but it’s only available on Android. Without a serious recommendation on how to make a plain-text flow work through a screen reader and dictation software on a PC, I am comfortable with saying that the author did not really consider accessibility in this rant.
There’s no need to prove accessibility from first principles for every post. Plaintext reading and writing had great accessibility, as does simple HTML rendering. There’s nothing else to this post.
There isn’t for every post, but there is a need to keep posting about plain text flows and to advocate in comments for plain text flows? There’s dozens of posts/threads on Lobsters about the power of plain text, and that’s fine?
I think I’d say yes? Do you want to see a post about plain text workflows with screen readers? Dyslexic fonts? Braille devices? Eye tracking keyboards?
Workflows don’t have to be accessible to everyone. Rather, we need accessible workflows for every outcome. There’s tons of ways to create static HTML websites. Many of those ways are accessible to various subsets of people. This is one such way, which I would argue is accessible to a huge swath of people, but for anyone who feels that it isn’t for them, there’s tons of other perfectly great ways to accomplish the same outcome of producing your own HTML in a fairly low-effort way.
This sounds like a double standard to me. Multiple, overlapping, posts here about plain text are fine. Asking for accessibility in the comments and there’s opprobrium. Either allow both types of content or neither.
Yes to all of the above. If we spent even a fraction of the time we keep ranting about plain text tools on accessibility, I think it would be a boon to impaired users. On the other hand, IMO the marginal value of Yet Another Plain Text Evangelism Post is minimal.
I think standalone stories about accessibility would be welcomed, even if they overlapped to the extent that plain text posts do. Raising concerns about accessibility in the comments of a story about plain text gets pushback because some people think plain text already has good accessibility, and in these comments, concerns about accessibility in general seem off topic. You seem to be implying that plain text is likely to be less accessible than alternatives – why do you think that?
As plain text is the lowest common denominator and can be converted using tools like Pandoc, there’s at least a limit of how much worse than the most accessible experience plain text can be. If, for example, writing rich text Microsoft Word is easier than writing any markup language in any plain text editor, then storing your files in plain text wouldn’t be much worse because you could automatically convert them to Word format just for the editing process.
Accessibility generally requires metadata to be available. Which language is a given post in? How does the screen reader know which parts of a post to say aloud and which parts not to? Think about Markdown, you can surround “code” in backticks, but does that mean content in backticks need to be skipped? Markdown isn’t equipped to separate “code” from “math” from quoting passages. If you render Markdown into HTML that’s fine, but what about writing the Markdown itself? And which screen-reader software would I use to write plain-text? Screen readers need to support deleting words, navigating through a document, editing words, etc. Software like Word usually offers OS level hints for accessibility, which helps in interaction with dictation software.
I’m coming from the perspective of someone with bad RSI. Using the terminal, writing plain text documents, all of these things are quite cumbersome using dictation software. Most dictation software I’ve used has only really been okay typing sentences into a chat program. When I see people suggest “just use a screenreader”, it feels dismissive. It’s like someone saying “well your language is Turing complete, so it’s definitely doable”. It’s a largely theoretical epithet offered to check a box; unfortunately I’m the one that needs the box to be checked, so an epithet doesn’t fix my problems.
What is on-topic in these threads? Plain text evangelism gets posted here all the time. In my mind, it feels these feel like posts are about an ethos not an actual technological thing. As such, there’s nothing particularly meaty to talk about unless we’re talking about lifestyles here, in which case commentary about accessibility seems purely on-topic.
So, these are useful criticisms of “plain text is accessible”. Let me address them as best as I can:
“Which language is a post in?” is a basic feature of a screenreader, and indeed, of the human experience. A post is assumed to be in the language of the device, as configured by the user. In much the same way that a sighted user can view a post and say “This is in English”, a screen reader user can hear a post read via an english-language screenreader and say “this is in english.” If it starts to sound like badly accented german instead, well, it probably is, but this is a human skill, as well as a screenreader skill. A plain text post is not annotated with language for a sighted user, either, and that’s ok, because the post is either in a language that the sighted user understands, or it isn’t. Same thing with a vision-impaired user. There’s no mystery about what language a post is in to a person who speaks that language, and there’s an equal amount of mystery for an unsighted or sighted person who is viewing the same post. This is an unfortunate reality of language.
That said, a screenreader (the screenreader industry) has a huge advantage over the non-screenreader industry in that it is fairly trivial to build language detection into the screenreader, and it can automatically switch pronounciation to the correct language. A sighted user can either annotate all text with expected language, or they can figure it out themselves. Either is more effort than having the reader automatically switch. In reality, I don’t believe this is a hugely desired feature of screenreaders, but it’s not a huge accomplishment to run language detection on each paragraph.
I don’t see any reason that a markdown screenreader should skip code passages? Instead, it should read the passage, and allow the user to skip it if it is incomprehensible to them. Presumably, the reader will have written the markdown themselves, and will understand what it says, but that’s up to the user. It could just as easily be an uninteresting paragraph about anything, that they’d like to skip.
Re: producing markdown: You can probably just write word docs, and convert them to markdown using various software packages, or websites. This is a fairly well-trodden path that works pretty well, particularly if you’re using simple Word docs intended for conversion to markdown. This requires an extra step in your conversion workflow, of course, but it’s pretty trivial to automate that step in your static website generator if you choose to go that route. On the other hand, I just tried editing markdown in TextEdit on Mac, using voice control, and it wasn’t terrible? Considering I’ve put no effort into learning voice control (or markdown, honestly), I don’t see the barrier, here. The only problem I had was entering URLs, and I imagine I was just doing something wrong.
Guys, I am sure we all mean well here, so no need to argue. Accessibility might be off-topic in the sense that it is not being tackled in my post, but still it is interesting nuance to the topic of publishing.
Now, I didn’t include anything about accessibility simply because I don’t know anything about it. I use a screenreaders sometimes to check how my texts “sound” (mainly when writing fiction), but that is about it. In terms of screenreader, I would recommend the Mac platform, as it has a marvelous reading software at OS-level, AFAIK they have some other good accessibility features too (if you count screenreaders as accessibility.)
Otherwise I am sorry to hear that the command-line is not accessible for the visually impaired, as I think that it can be made accessible, due to it’s simplicity (you basically type a message in the console and get a message as a response.)
Also weird and unfortunate is the fact that there isn’t a good plain text editor with accessibility features. One time I wrote a little one-liner in my vimrc that integrated it with the command-line dictation command for Mac and it works quite well (see my post on vim for more info.) I had a keyboard shortcut that reads the selected text. I imagine that something like a plugin that reads the word under your cursor would be doable too.
Speaking as a blind person, I wish people would stop spreading this particular line of FUD. The command line is perfectly accessible to people who are visually impaired. It always has been and always will be. So is plain text. Please no what-abouts; I am tired of this fight.
Also see this lovely post, which spells things out far more coherently than I can right now: https://eklhad.net/philosophy.html
What’s more accessible than plain text?
I’m not talking about accessibility in theory. Much like you recommended tooling (vim or sublime) for writing and (Pandoc) processing, what tools would we use to interact with to drive the Markdown<->HTML edit loop? Which dictation software, what screen reader? How would that flow look like?