[BlindMath] markdown

[Godfrey, Jonathan]

Hello Rmana and anyone else interested in markdown,



I decided to write some thoughts here in a new thread because I think there are a bunch of people who don't know, but should learn, how easy it is to work with markdown.



First: markdown files are plain text, editable in any text editor, even Notepad in Windows. The raw files are therefore very readable in braille. I choose to use uncontracted 8 dot braille output because I am generally needing to see the range of characters used in coding that are seldom used in literary work, including {} and \ for example.



Second. The text files do not need to be given an extension of *.md but this is strongly advisable. It will make conversion easier. You may need to watch that an extra *.txt doesn't get added to your filename.



Third: conversion to HTML is done using pandoc. Even if people are not going to use markdown, getting hold of pandoc for conversion among other formats is a good idea. We'll worry about that stuff later. Use of the right editor can make conversion faster; we all have our favourites. In general though, people will write a command line that is of the form: "pandoc -s file.md -o file.html" which says take my source file called "file.md" and make the output file "file.html". Even if the editor has a conversion tool linked to it, this command line is what gets done behind the scenes.





So, that's the process. What's hard about that? Well the command line is what throws people the most. I hope other people will share which editors they use and the way they process the markdown in a more automated fashion.



Then, we need to write a few things down. If I gave you a text file and you read the following five lines (count carefully, including blank lines)  <starts>

## Introduction



Let $\mu$ be the **population mean** of a variable.

We calculate this by summing the observations and dividing by the number of observations

$$\mu = \frac{1}{n} \sum_{i=1}^n}{x_i}$$

<ends>





Back to me: I've used plain text characters to do some formatting, and LaTeX users will see the familiar construct for an inline mathematical element as well as an equation that will be on its own line in the document. The use of the number signs (pound or hash to some people) suggests some sort of heading based on the way it appears; in fact this will be put as a <h2> element in HTML which means heading level 2. It looks like I've tried to emphasize the "population mean" using some stars/asterisks; two of them means bold, only one would have been italic, and in a fit of logic, 3 means bold italic!



Some other features that are less easily demonstrated in an email typed in Outlook include how we make bulleted or numbered lists, and how we manage indenting to make lists within lists.



You have almost certainly read HTML content that was created from markdown because it is used in blogging sites and numerous documentation projects for software where there are code demonstrations. For example, if I type `mean()` in a document, I am telling my students that the command "mean" is used. I put the () there to make a point, but the use of the backticks (also known as accent grave) turns that element into typewriter font.



I hope you've had enough of a taste to want to know how to get pandoc and a useful editor to have a go for yourself.



I'll fetch out some instructions for getting the simplest installation going when time allows = not in the next two hours.



Jonathan