Editing Markdown documents with uText

People can make sense of text by reading, but a machine needs extra instructions regarding meaning and structure to get the job done. Formatting elements provide this assistance, and they take many forms, including highlighting important content passages via italics or indicating that text consists of headings and code fragments so that the structure becomes apparent.

The term applied to this process is known as markup. When books are printed professionally, this separate step may be performed by specialists. In today's world of self-publishing, many authors do this work, often with the help of a template.

(X)HTML is the best known of these markup languages. However, it offers only a restricted amount of formatting that leads to complicated workarounds. These texts are then difficult for people to read. It became clear that a meta language was needed to make the appearance of the text more straightforward and to make the direct generation of HTML via a converter simpler. An entire series of programs now exist for these purposes, including AsciiDoc [1], Pandoc [2], and the previously mentioned Markdown [3].

The current Markdown version 1.0.1 was designed to be easily readable for humans. It therefore has a simple syntax. The developers achieved this in two ways. First is the support that Markdown provides for just part of the HTML structures. The second is that the developers are strict about having an easy to understand markdown syntax. This is used in many ways for designing an HTML page – with wikis, for example. These do not always consist of pure Markdown, but rather a derivative that often includes additional functions.

One peculiarity of Markdown is that it is possible to write HTML structures directly into the code without having to designate it as such. This is called inline HTML and makes it possible to create complex structures, although it also adds to the burden of the reader. Tables not supported by Markdown are a typical example of this trade-off.

Markdown uses syntax similar to that of AsciiDoc for headings having different levels. Headings are made with underlining or are preceded by equal signs or hash tags. The software supports up to three levels for this. Listing 1 shows an example. Closing characters can also appear in the example shown.

:A Heading
=========
# Heading
# Heading #

Markdown's approach is also barebones for simple lists. An asterisk (* ) at the beginning of a line introduces a list item. You can place plus and minus signs next to the asterisk using the same function. You can highlight sub-items by inserting at least four blank spaces at the beginning of a line followed by a character for a list item. You can also include various characters in one level. The position in the source text, rather than the character used, determines the definition and how the entry appears (Listing 2).

* List entry 1
+ List entry 2 (same list and level)
    - one sub item ...
    + ... and another

You can create numbered lists or enumerations with an arbitrary number directly at the beginning of a line, which is followed by a period (Listing 3). Here again you can generate nested lists by starting a line with at least four blank spaces.

1. first item in the enumeration
1. second item in the enumeration
     1. first sub item for item 2
     1. second sub item for item 2
1. third item in the enumeration

The best approach is to start the enumeration with 1. in case the software you are using supports start values. Note that if you want to combine a digit or a number with a period without beginning a list, you can mask the period with a backslash (\. ).

Hard breaks can be created in lines by adding two blank spaces to the end of the line. Markdown editors such as uText recognize these invisible structures and show them as highlighted. The manner of dealing with characters such as less than (< ) and ampersand (& ) in this context is interesting. It may be necessary to mask them depending on whether they are included in URLs. Markdown permits these characters to be included in the text without any special masking.

Markdown has a particularly noteworthy capability: It permits the insertion of citations in email style. All you need to do is to prefix a line with a greater than sign (> ), to signify that the line is a citation. There's no need to add an empty space after this initial character.

For longer paragraphs, you can also use one greater than sign at the beginning to designate the entire paragraph as a citation. This is likewise true for paragraphs that have hard breaks. Nested citations are made by adding several of these greater than signs (Listing 4).

>It bears mentioning that it is possible to insert
 citations in the style of an email. It is sufficient
 to preface a line with a
 >> greater than sign (>). The line will then be
   recognized as a citation and no blank space needs to follow.

01 [clickable text](URL "Link title")
02 [clickable Text][ID]
03 [ID]: URL "Link Title"
04 [clickable Text][]

Horizontal lines separate particular parts in the document and originate in HTML via the <hr /> element. Three stars, items or minus signs placed in what would otherwise be a blank line are sufficient in Markdown to create this structure. Empty spaces in between are allowed. The examples from Listing 6 all generate the same result.

*
* * *
---
- - - - - -
...

Using uText

The idea behind Markdown, that is, text with frugal markup, actually made it hardly necessary to use special editors for creating such text documents. Nonetheless, the language has some advantages as shown by uText [4].

The editor consists primarily of two windows (Figure 1). To the left, you should enter the source text. Results will appear on the right, even with respect to embedded HTML code. This is where the software stands out. It is suitable for entering and editing Markdown source texts and also as a learning program for the markup language.

Figure 1: uText looks straightforward, tidy, and practical.

The Markdown format is simple and so is working with uText. The text editor has all of the standard functions but not much more, making the program straightforward in use. The tool bar contains nothing that would surprise. Consequently, it pays to take a look at the menu.

A unique feature under File offers the possibility of loading files directly from Dropbox or writing them to Dropbox. However, Dropbox is the only such cloud option.

The Html function is found in the View menu. This function explicitly switches the preview window found to the right into HTML code mode. You should use this function if the preview does not show the expected result. In this way, you can determine whether the corresponding code has errors or the preview simply does not work.

The Preferences can be found in the Edit menu. These are the settings. The Search and Format entries lead to the corresponding functions. The latter permits direct insertion of the most important Markdown structures into the source text. You will find functions for integrating some additional structures in the Insert menu. These include things like horizontal lines, images and URLs.

When attaching images, a dialog will open for entering relevant HTML elements (Figure 2). The image will show up in the preview. When you pass the cursor over the image, the title will show up (Figure 3). It is often faster to manually attach images directly. The syntax for this is simple (Listing 7, line 1). At this point, it is possible to add an image title (line 2).

Figure 2: You should enter the relevant HTML elements in a separate dialog when inserting the images.

Figure 3: The preview shows the image and the title when you pass the cursor over it.

01 ![AlternativeText](/path/to/image.jpg)
02 ![AlternativeText](/path/to/image.jpg) "Optional title"

A spell-check feature can be activated via the menu option Tools . uText automatically chooses the language that you have specified for the system. If you need to change the language, you can do so in the context menu under languages (Figure 4).

Figure 4: The option for changing the language specification for the text is somewhat hidden in the context menu.

You can call many functions directly via the keyboard shortcuts. This usually works faster than searching for them in the menu. Table 1 summarizes the major combinations.

The configuration of the software is fairly easy. Figure 5 shows the three configuration dialogs. Advanced settings, such as the possibility for using customized keyboard shortcuts, however, are not currently supported by the program.

Figure 5: The configuration of the Markdown editor is done with three dialogs.

Conclusion

Implementing Markdown syntax with uText does not yet work perfectly, which becomes clear in testing [5]. Problems occur with implementing the cursive boldface font with three underlines and the horizontal line. However, because most things work very well, uText can be of great benefit to users dealing with Markdown. The side-by-side display of source text and formatted output appears to be useful and well implemented.

$ sudo add-apt-repository ppa:atareao/utext
$ sudo apt-get update
$ sudo apt-get install utext