and soup. This year I decided to sit down and write HTML by hand following the conventions of the early Internet, and ultimately discovered my new notes/memo format. Now I am going back on that decision. While I love HTML and think its actually one of the best markup languages, it unfortunately has a few fatal flaws which make it wholly unsuitable for my needs. Some of these are solvable problems, but others are fundamental problems with the format and how it evolved over time. In this post, I am going to walk through the problems that I quickly discovered while authoring notes in HTML and the benefits of plain text over it. TAG SUPPORT =========== The beginning of the end for HTML as my notes format came with one simple tag,

.  This tag allows your document to embed MathML, a markup language for
writing math equations in a similar vein to LaTeX.  MathML is one of those
things I was surprised I hadn't heard about before, especially since it has
been around for quite a while.  But simply checking the MDN compatibility
matrix[1] showed exactly why.  While MathML is old, it was only recently
supported by major browsers.  This makes it basically unusable for my
circumstances.  If a browser from even as recently as 5 years ago can't display
my note properly, then I can't use that feature.  Unfortunately the only
alternatives are large JavaScript frameworks which introduce compatibility
restrictions of their own.

MathML is an example of a tag which was never properly supported until
recently, but there are examples of tags which _were_ well supported and were
deprecated somewhere along the line, making them unsuitable for use in a modern
browser, but not an old one.  The classic example for me is the

tag, which was removed from HTML following the introduction of CSS[2]. The rationale was that served a purpose (styling) which should be handled by a separate and independent part of the page. While I don't know of any modern browser that doesn't support , you will get big scary warnings whenever you use it. With plain text, what goes in the document is only limited by your character set (which is practically unlimited now thanks to UTF-8). While math equations may not be perfect, they're at least as good as HTML without MathML or some external JavaScript library (since you'd have to fall back to just writing in plain text), and formatting like the tag can easily be done just by adding a certain amount of spaces before your text. These can then be rendered by *ANY* text editor regardless of what standard it supports. Plain text is plain text, there is no "feature set" to support. In effect, every single plain text editor is a "WYSIWYG" (what you see is what you get) editor. ESCAPING SPECIAL CHARACTERS =========================== Another issue with HTML is the difficulty of including source code listings within a document. Most if not all of my notes contained at least some source code embedded within them. Most of this was in languages like Scheme which caused few problems, but sometimes I would embed a bit of C or Java and everything would fall apart. The reason comes down to the < and > characters. In HTML, these characters are only valid to appear in tags, and must be escaped everywhere else. This means replacing "<" with "<" and ">" with ">". This turns one character into four, which messes with spacing and alignment. Take for example my latest blog post about the Remote Proxy Pattern[3]. In it I feature a plain text diagram of the flow of information through a system. It is intended to be displayed as follows: Method call [Client] -----------> [Server] Return value [Client] <----------- [Server] Unfortunately, the ends of my arrows caused issues with HTML, so in the actual source of the page, I had to write it as follows: Method call [Client] -----------> [Server] Return value [Client] <----------- [Server] While this example still roughly lines up, you can see the text above the arrow is no longer centered, and on an example that uses more "<" and ">", the added four characters can accumulate into tens of characters of displacement. While this isn't a problem for most websites on the internet, it made writing notes in HTML that much more annoying. Now there _was_ a solution to this back in the day. The "example" or tag. This tag functioned much like the modern <pre> tag, however it did not permit tags to be embedded within it. In effect, it automatically escaped special characters like "<" and ">" so long as your listing didn't contain the text . This tag seems like the perfect solution to my problem, however it was deprecated pretty early on, as far back as HTML 2[4]. The reason is a very good one, with cross site scripting attacks, it may be possible to inject a stray opening tag and reveal the source code of the web page (as embedded PHP would be included in the "we should escape this" body)[5]. While this tag is still supported in most modern browsers, the implementation of it tends to vary slightly. While it is still probably safe to use, there is no guarantee that it won't be going away tomorrow night, or that it will continue to work as it does right now. So effectively we're all stuck with escaping our source code. Plain text allows embedding whatever you want directly into it. While it may take a little work to properly delineate what is code and what is a paragraph (I tend to indent code blocks by 4 spaces on the left), it can still be displayed without having to modify the source at all. Just this alone has sped up my creation of notes, as I now don't need to paste my code in and run an Emacs macro to escape all the special characters within it. YOU WILL NEVER WRITE A STANDARDS COMPLIANT HTML PARSER ====================================================== Another very large factor that pushed me away from HTML was the very strange state of the standards. For modern HTML 5, there are two competing standards: the "living standard", and the proper HTML 5 standard. These two standards agree on most things, but differ in slight ways. This isn't even to consider the multitude of other HTML standards like HTML 2 to HTML 4, XHTML, and the various "transitional" or "strict" variants of them[6]. So to produce a proper, standards compliant HTML parser involves implementing parsers for *ALL* of those standards since they can be used interchangeably. This isn't even to mention the hell that is writing the parser in the first place. HTML is a notoriously hard language to parse[7]. While it may seem simple at first given that most tags are explicitly opened and closed with named start and end points, it gets complicated when you read that some tags (notably <p> and <li>) don't need closing tags. The closing tags are _recommended_ but not required, so both are expected to close when encountering a new "block" tag, but not a new "inline" tag. This also applies to when the closing tag is provided as well. So the following HTML source should parse into the exact same tree: <p> Hello world <i>Testing 123</i> <p> New Paragraph </p> </p>  <p> Hello world <i>Testing 123</i> </p> <p> New Paragraph </p> This makes writing a parser much harder than it needs to be because now you need to add special handling for a corner case on tags that are frequently used. This isn't even to mention the hell of writing a parser which properly handles the embedded languages of HTML. While it is super nice to embed CSS and JavaScript directly into your document, to parse it correctly now requires that you parse these two (very different) languages. While you can just skip the inner text of the <script> or <style> tags until you reach their respective closing tag, this adds yet another parser state and more complexity to the overall parser. Not to mention skipping these embedded languages is technically against the standard since the standards specify that these languages must be supported... Overall, I've come to the conclusion that it is nearly impossible to write a fully standards compliant HTML parser... or at least its probably nearly impossible for me. Plain text of course doesn't have this problem. To parse plain text, you simply read the bytes in. There is no special handling apart from standard text handling (newlines, spaces, tabs). This is comparatively simple when you look at the mess that is HTML's parser and something that even a first year computer science student could write code for. Writing a plain text formatter (which is a considerable harder task than just a plain text render/parser) was actually an assignment in my second year undergrad computer science class. HTML BOILERPLATE ================ Finally, the problem most people who've written HTML probably expected to see first. Simply writing a simple note in HTML involves writing annoying boilerplate which serves very little purpose on a simple document. While it is technically possible to omit this and just start writing tags, it is not standards compliant and therefore might not render in certain browsers. To write a proper standards compliant page requires at minimum the following boilerplate (at least for my uses): <!DOCTYPE html> <html lang="en"> <head> <title>...</title> </head> <body> ... </body> </html> While this isn't bad by any means, its also not the freedom and flexibility of just opening a text editor and jotting down what you are thinking. This boilerplate only gets worse when you start to include things like external stylesheets or scripts into your document. HTML has no syntax for "include some part of an external HTML file", so you have to simply copy and paste the tags which load stylesheets and scripts into every file you are working on. THE PROBLEMS WITH PLAIN TEXT ============================ Now, all of this isn't to say plain text is some perfect format with no flaws whatsoever. If it was, I wouldn't have switched to HTML for any length of time. The biggest issue with plain text comes from its lack of any standard formatting options. As I slightly touched on in the source code listing example, its hard to differentiate what is supposed to be part of a paragraph, and what is supposed to be some other element of the text. Take for example a heading. Without the formatting of an <h1> tag, its hard to tell if some text should be interpreted as a heading, or just a short paragraph. Most of the time this requires some indication (usually underlining the text with some character or centering it), but this is unique to every document and author. There is no standard convention on how we should represent different textual elements within a plain text document. However, in practice most documents, even if using non-standard ways, are able to differentiate between textual elements fairly well. CONCLUSION ========== While I still like writing web pages in HTML, I will not be writing notes in it anymore. Plain text is a simple but powerful format that is widely compatible and easy to implement. While it may not have the power of HTML, it also doesn't have the annoyances of HTML. Its simplicity lends itself perfectly well to writing quick notes, memos, and write-ups. A task which I will continue using it for. [1] https://developer.mozilla.org/en-US/docs/Web/MathML/Reference/Element/math [2] https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/center [3] https://mckinley.net/dev/stdscr/remote-proxy-pattern.html [4] https://www.w3.org/MarkUp/html-spec/html-spec_5.html#SEC5.5.2.1 [5] https://www.reddit.com/r/PHPhelp/comments/152kglq/can_anyone_explain_to_me_the_reason_for_why_xmp/ [6] https://www.w3resource.com/html/HTML-versions.php [7] https://html.spec.whatwg.org/multipage/parsing.html