{"id":26,"date":"2016-09-23T09:05:00","date_gmt":"2016-09-23T09:05:00","guid":{"rendered":"https:\/\/sandrock.co.za\/carl\/2016\/09\/23\/appearance-vs-semantics\/"},"modified":"2016-09-23T09:05:00","modified_gmt":"2016-09-23T09:05:00","slug":"appearance-vs-semantics","status":"publish","type":"post","link":"https:\/\/sandrock.co.za\/carl\/2016\/09\/appearance-vs-semantics\/","title":{"rendered":"Appearance vs semantics"},"content":{"rendered":"

As our department’s go-to guy for computer-related queries, I have been involved in ushering many people from Word to LaTeX and more recently Markdown (via Jupyter Notebooks<\/a>). I find myself repeating some thoughts over and over again, so I thought I would take the time to write them down this time rather than have another discussion about it.<\/p>\n

\nFormatting and meaning<\/h2>\n

Many modern computer users use direct manipulation tools like Word in a way which achieves the layout and look of the document they are working on in the shortest amount of time possible. This often involves direct formatting. Many Word users do not use styles or really think about the semantics<\/a> of their document layout at all. Semantics in this context means that there are two layers to the appearance of documents. I can emphasize<\/i> a word by writing it in italics. In Word, I simply apply the formatting. But the action of formatting is the same whether I am applying italics because I want to add emphasis or because I want to format a species name like Saccharomyces cerevisiae<\/i>. The formatting is handled by the tool, and the semantics are not encoded in the document at all. A human writer or reader would reconstruct the semantics from context, distinguishing between the italics used for emphasis and the italics used for a species name.<\/p>\n

When I started learning how to use LaTeX I was converted to this philosophy of adding semantic content to the document and allowing the document generator to make decisions about how it would look. The LaTeX way of handling the formatting in the previous paragraph would be to use emph{ephasize}<\/span> for the emphasis and species{Saccharomyces cerevisiae}<\/span> for the species. So if you’re doing LaTeX the way its creators intended it to be used, you end up looking at a document layer with the words you are writing and the meaning you intend it to have, but not seeing what it looks like until you compile the document. This allows for a great amount of flexibility. I may decide later that emphasis<\/b> works better when bold rather than italic, for instance.<\/p>\n

The most common issue new users of LaTeX have with the system is that it is often hard to apply the formatting they want. I think this is a direct cause of them not having considered the semantics of their formatting. They just want to know how to get the text to be bold, or a different font or colour or alignment, which are all very simple operations in Word, but often quite hard in LaTeX, for the very reason that LaTeX was designed to separate these small formatting concerns from the meaning layer.<\/p>\n

Now, if you are a certain type of Word user, you may be saying that these concerns look very much like using styles. You would be right. My experience with Word users, however, shows that very few of them aim for purity in their application of styles, and the whole interface of Word is asking you to simply click the formatting buttons you need to get the document to look like you want it to look.<\/p>\n

\nThe web dimension<\/h2>\n
\nAlthough LaTeX and Word are different regarding the encoding of meaning, their default use is still focused on producing a document within a relatively fixed layout. For the vast majority of users, the target is to produce an A4 page which will either be printed and read or be shown in a simulation of a sequence of A4 pages in an environment like Adobe Acrobat or even just Word itself. Choosing a paper size makes some other choices relatively easy. It is easy to know what size fonts should be displayed as, or what size a picture will be and where it is on the page, as all these things have simple unambiguous answers when working with print.<\/div>\n
\n<\/div>\n
\nThe web changes these assumptions greatly. Every viewer is likely to have, if not a different size screen on their device, then a different size for their window. They may have different fonts installed on their system and they may even have overridden their preferences so that their fonts display differently. HTML was designed with a similar philosophy to LaTeX in that the tags encode semantics more than appearance. There is even a kind of similarity to the code. For instance, to emphasise text, you could do emphasis<\/em><\/span>, allowing the same flexibility of formatting I mentioned earlier. Of course, there are also direct formatting tags, but many people advocate removing as much of the formatting details from your HTML as you can, relying on CSS to style the output document. The amazing results of this can be seen at sites such as the CSS Zen Garden<\/a>, where the same document can look very different depending on the styling supplied. <\/div>\n
\n<\/div>\n
\nEven if we’re not going over the top like the Zen Garden, we may see the benefit of allowing flexible layout when rescaling a window or viewing a web page on a phone with a smaller screen. I think everyone can agree it is more convenient to view a web page which nicely reflows and uses sensible font sizes, than trying to read a PDF on your phone.<\/div>\n
\n<\/div>\n

\nMarkdown (and the Jupyter Notebook)<\/h2>\n
\nThis brings me to Markdown<\/a>, which aims to be a more easily writable format for producing HTML. It is being used as the default text entry method in Slack and the Jupyter Notebook. Since it is aimed primarily at the Web, it inherits many of the semantics\/formatting distinctions from the other tools. When you look at the syntax of Markdown, you will notice that there are very few commands or formatting options which allow the user to determine what text will end up looking like. This is disconcerting for users who are used to applying formatting for the sole purpose of obtaining a particular visual result, and they often end up hunting through the various options to get the effect that they are looking for without thinking about the semantics. I recently found a document where the author had used #### in front of a paragraph in order to obtain a bold text effect when in fact #### is used to produce a level 4 heading.<\/div>\n
\n<\/div>\n

\nFormatting advice<\/h2>\n
\nNow that I have talked about what I see as one of the major conceptual hurdles encountered by people migrating from Word, let me give my advice. When producing a document using one of the markup systems, resist the temptation of applying any direct formatting in the first draft. Focus on the content of the document and apply semantic markup only. Distinguish between heading levels using the tools provided (section<\/span>, <\/p>\n

\n<\/h1>\n

<\/span> or #<\/span>). Restrict your check of the rendering to check that there are no errors in the processing (so don’t check if the document “looks” right, just check that all the text you have written ended up in the final output and has the appropriate semantics). Once you have done that, figure out how to handle formatting in a way which doesn’t require direct formatting. Style files for LaTeX, CSS for HTML and Markdown which results in HTML output. Also, before you start fiddling with the formatting, try hard to live with the default formatting, as this will allow the maximal freedom for downstream users. When you make a decision about how wide the text should be because it looks good on your screen, you may be negatively affecting the experience of a user with a wider or narrower screen. Similarly, try to be considerate of scaling in inserting things like pictures. Avoid direct sizes like 300px and rather use relative sizes (like 60% if you want the picture relative to the screen size, or 100em if you want it relative to the font size), this will make your output scale correctly on output devices.<\/div>\n

\n<\/div>\n
\nIf you are viewing your output on a web browser, try to change the size of the window and see if the formatting is still the way you like it. In almost all cases, it will be better to avoid formatting and allow the browser to figure out how to display things rather than micro-managing it.<\/div>\n

\nSpecial characters and math<\/h2>\n
\nMy final note is about special characters and math. Many word users still use the Symbol font to include special characters in their text. The Unicode standard has solved this problem in a far better way. The drawback of using Symbol in Word is that it doesn’t allow for easy reformatting of your document later. For instance, if I had used a capital D and symbol font instead of \u2206 in this sentence, you wouldn’t be able to select it and reformat it in Arial, as the symbol would turn back to a D! Using proper Unicode symbols allows you to copy and paste into text-only fields on Facebook, WhatsApp Web, Slack and the Jupyter Notebook. Learn how to do entry for the platform you are using<\/a>.<\/div>\n
\n<\/div>\n
\nFor mathematical formulae, it is worth your while to learn a little bit of LaTeX math syntax. It is memorable and easy to type and is used in the latest version of the Word equation editor:<\/div>\n
\n<\/div>\n
\n<\/div>\n
\n<\/div>\n
\nThese shortcuts will save you time in all these environments and are the same in the Jupyter Notebook.<\/div>\n","protected":false},"excerpt":{"rendered":"

As our department’s go-to guy for computer-related queries, I have been involved in ushering many people from Word to LaTeX and more recently Markdown (via Jupyter Notebooks). I find myself repeating some thoughts over and over again, so I thought I would take the time to write them down this time rather than have another […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_feature_clip_id":0,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_post_was_ever_published":false},"categories":[1],"tags":[],"class_list":["post-26","post","type-post","status-publish","format-standard","hentry","category-uncategorized"],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/posts\/26","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/comments?post=26"}],"version-history":[{"count":0,"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/posts\/26\/revisions"}],"wp:attachment":[{"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/media?parent=26"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/categories?post=26"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sandrock.co.za\/carl\/wp-json\/wp\/v2\/tags?post=26"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}