QTML Tutorial

If all you want are simple paragraphs, just add a blank line in the simple text to break up your posts and comments into paragraphs and you are good to go.

But what if you want italics, bold, underlined text or highlighted text? What about lists and/or tables? How about being able to choose where in your text to place pictures? Or how about the ability to display blocks of computer code in a fixed width font for proper indentation? How about equations?

For that we present QTML, the reactionary new markup language which uses half century old ideas to let you style your posts and comments with a minimum of extra typing. If you are willing to learn a few simple rules and about 20 tag names, you will be able to do everything promised above except equations. (For equations you will also need to learn the old UNIX eqn language — which is surprisingly simple and easy to type. More on that later.)

Lesson 1: The Basics

Web pages are usually styled using Hypertext Markup Language (HTML), a markup language which is easy for browsers and evil robots to parse, but horribly tedious for humans to type. Use your browser's "View Page Source" command (it is a right mouse item in Mozilla) to see what this page is under the hood. Notice all those <s and >s. Those are how HTML separates tags from content. A beginning tag is <tagname>, the corresponding ending tag is </tagname>. Typing all those special characters is tedious enough on a real keyboard. On a phone you are living in Nightmare Mode.

QTML uses a period at the beginning of a line immediately followed by the tag name to indicate a beginning tag, and two periods at the beginning of a line followed by the tag name to indicate the closing tag. In either case you might have one or two arguments after the tag name in certain circumstances, which we'll see later.

To see tags in action, let's look at a trivial example using paragraphs, headings, and italics.

The .p tag marks the beginning of a paragraph, but you rarely need to use this tag. Paragraphs are the default. And to end a paragraph, all you need is a blank line.

The .h tag marks major headings, .hh for subheadings, and .hhh for sub sub headings. (Typing multiple h's is way easier than reaching for the appropriate number key!) Like paragraphs, headings are block tags. You can close block tags with a blank line.

The .i tag marks the beginning of a span of italics. The ..i tag marks the end. Italics are a kind of style tag. You do generally need to close style tags. The exception is when the end of a block is being styled. There, QTML automatically closes the style.

Some example QTML code using these tags is in the text box below. Below that is an Apply button. Press that and the QTML text is turned into nicely formatted HTML in the box further down the page.

This is an interactive tutorial, by the way. Notice that one of the movies in the example below is not in italics. Fix the problem and press the Apply button again.

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).


A few things to pay attention to in the example above:

  • We did not need to use any tag to start or end paragraphs. Blank lines did the trick. (You could use the .p to start paragraphs and the ..p tag to end paragraphs if you the sort of person who prefers XHTML to HTML. But for the rest of us, paragraphs are implicit at the top level. There is one special situation where you do need to use the .p tag. We'll get to that when we get to social graphs.)
  • We did not need a closing tag for the heading. Headings and paragraphs are both block tags, so both are automatically closed by a blank line.
  • We did need to have end tags for italics. Using a blank line to close italics would start a new paragraph, which is usually not the intent. This situation holds for all inline style tags as well as for hyperlinks.
  • (With that being said, if you do start a new paragraph while in italics mode, the italics do not spill over to the next paragraph.)


Lesson 2: Hyperlinks

So you want to link to an article you found on another site, or you want to link to a different post on this site. What do you do?

You use the link tag. Duh!

The link tag is an inline tag, just like the .i tag we used in Lesson 1. However, the link tag takes an argument: the web address of the page you are linking to.

Conntects does not scrape web sites to find the clickbait headline or excerpt. It is up to you to provide the link text. You put that text in the lines between .link and ..link. (Or you can omit the closing tag if the link is at the end of a paragraph.)

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).

A final note. Notice that the second example link has bs on the same line as the closing ..link tag. The bs stands for backspace. By adding this attribute it was possible to avoid a space between the link and the comma. Notice how the comma got underlined in the first example link. As an exercise, see if you can get the comma out from inside the link without having a space.

Lesson 3: Pictures

Unlike certain other social networks, Conntects allows you to put pictures where you want in your posts (and comments). To that end, we have the .pic tag. This is a block tag, so you don't need a closing tag. In the default context a picture acts much like a paragraph, but as we'll see later, pictures can also be used as list items or table cells.

The .pic tag requires one argument: the name of your picture. This name does not need to be related to the filename on your computer. It does need to look like a single word to the parser: no spaces or special characters; use camel case or underscores if you want multi-word picture names.

You can add the optional s flag after your picture name if you want the picture to be displayed smaller.

The name can be the name you gave your image when you uploaded it in the past. Or you can also use the pic tag before you upload your image. If an image hasn't been uploaded yet with the name you give in the QTML code, the result screen will have Upload buttons for you. Press one of said buttons and a drag-and-drop photo uploader/editor will appear.

Get yourself a couple of images ready and try it in the example below. Note that since this tutorial is available for people who are not logged in, your images will not be uploaded onto our servers for this example. Instead, they will be temporarily stored as canvases in your browser using JavaScript secrets Man was not meant to know.


QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).


P.S. You can change the name of the pictures in the QTML above to try uploading different pictures. Or, you can re-upload the same pictures and play with the picture editor. Check out how you can crop by dragging the boxes on the edge of your picture. Or you can adjust the color balance using the four sliders. For forest scenes you can get some really neat effects by turning down the gray slider and turning up the brightness.

Or, try adding the s flag after a picture name and hitting Apply again. Notice how the picture is now smaller.

Lesson 4: Lists

QTML allows you to easily create lists. For bullet lists just use the list tag. For numbered lists use the numlist tag. You could theoretically use the li tag for the list items, but why bother? When in the list context, the default block type is list item. So just separate the list items with blank lines.

Do note that QTML lists have limited capabilities. You cannot have paragraphs within a list item. And you cannot nest lists to make a deep outline. If you need that level of control make a PDF or start a blog.

On the other hand, you can have pictures as list items. (Pictures as list items show up smaller than display pictures.)

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).

Lesson 5: Simple Tables

Tables are tedious to type in HTML. You have to surround every cell with <td> and </td> tags. And you need to do the same with <tr> for each row. QTML makes it trivial to format simple tables: just use an opening .table tag, and then type in the rows with each cell separated with a comma. Spreadsheet programs can dump tables in this format when you ask for CSV format.

The first line of the table consists of table headings, unless you add the nh argument to the .table tag.

But sometimes we need more. For example, if your cells have commas within them, you need to use a different separater. For these cases you can use the .sep tag within a table. Just use your delimiter as the first field after the .sep tag. If you want to go back to commas, have another .sep tag with comma.

If you want to paste a selection from a spreadsheet, use the .sep tag with no attribute at all. This will make tabs the separator, which is what you get when you paste from a spreadsheet.


QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).

In the example above, add the nh argument to one of the .table tags. Apply and see the change in the top line of the table.

Lesson 6: Styles

Once upon a more civilized time, we had font changes to signify emphasis, as well as to properly format book and movie titles. Then, the advent of the Internet gave us emoticons (such as :-) ). And then social media gave us emojis. Without action, we may yet revert to grunts and pictograms.

Conntects encourages the more dignified tradition of font changes, and thus QTML supports italics, bold, and underline. The tags are i, b, and u respectively.

And since we are all humans, we have the del tag for indicating deleted text which we want to replace. (Also useful for snark...)

And if you want to do footnotes or write chemical formulae, we have the sup tag for superscripts and the sub for subscripts. Unlike the other style tags, these do not automatically generate surrounding whitespace.

And since there's no kill like overkill, Conntects also has the red tag to make text turn red, and the yellow tag to turn the background behind text yellow as if you are using a highlighter.

Manually closing style and link tags is highly recommended! With that being stated, all styles and hyperlinks are automatically closed when you start a new block. (This is not the case for HTML, where styles inside one paragraph can spill over into subsequent paragraphs.)

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).

Notice that sometimes the underlining goes too far in the styled text above. Or sometimes we got a space between a word and the period at the end of the sentence. We have run up against an inherent weakness in using return+period to denote our tags. Fortunately, there are fixes, which is the subject of the next lesson.

Lesson 7: Styles, Spaces, and Related Nitnoids

Return-period-tagname is very easy to type. The creators of UNIX used this fact back in the 1970s when they created the troff typesetting system.

But there are inherent problems with using RETURN plus a period as a delimiter:

  1. What do you do when you don't want a space when making a style change?
  2. What do you do when you want to begin a string of text with a period when that string comes after a tag?

QTML allows the bs argument for both opening and closing tags for inline styles. bs stands for backspace. Used with the opening tag, it means don't interpret the return that starts the tag as a whitespace. Use with the closing tag, it means to don't interpret the return that ends the closing tag as whitespace.

The bs argument was introduced in earlier lessons, but since it is such a special case, it gets its own lesson. But there is more.

The bs argument can also be used for links, but when starting the link it needs to be the second argument. The first needs to be the web address.

Finally, we have the case where we want to put a non styled period right after a link or styled range. If it is a period followed by a space or number, the QTML interpreter will just treat the line as a text line. For the weird case where you want to start a line with a period immediately followed by a lower case letter, start the next line with three periods. The three periods become one with no leading space.

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).

Lesson 8: Code, Poetry, and Typewriter Mode

With all our marketing aimed at people who don't want to fry their brains, we'll probably end up having some nerds as members, and that means people who want to talk computer code. To make part of your post look like an old school computer monitor, surround the text with the code tag. The code tag is a special kind of block in that it allows blank lines inside. The code tag can only be used in the outermost context: no code windows inside of tables or lists.

Like an old school computer terminal, code blocks use a fixed width font. Unlike an old school computer terminal, code blocks allow styling the text with bold, italic, yellow highlighting, and even red, just like for regular paragraphs.

Still, sometimes you want to reference code within regular paragraphs, so QTML includes the icode tag as yet another inline style you can use within paragraphs, lists, and tables.

Finally, since computer code does not wrap, code boxes can have a horizontal scrollbar when the lines are long. This can be annoying. For this reason we also offer the wide tag. Anything inside the .wide and ..wide tags goes the full width of your browser window. (This can be handy for tables as well.)

But we might also appeal to other introspective types, such as poets. For poets, we have the poem tag. Like the code tag, the poem tag makes returns significant. But instead of a black background and a fixed width font, the poem tag provides a bit of indentation and a Roman font.

Finally, there are those who like to use a computer like a typewriter. For such people/situations, we have the type tag. By itself this tag makes returns significant but otherwise makes no changes in the font. If you add the c argument, you get a Courier font, just like and old typewriter. And if you want to type out an old school business letter, you can use the i argument to indent halfway across the page.

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).

Lesson 9: Equations

Not all nerds think in computer code. Some use equations. To that end the QTML markup language includes an equation feature. To include a display equation, use the eqn tag. This tag takes an optional label attribute which you can use to give the equation an equation number. The .eqn tag starts a block, which would be a paragraph in the default context, a list item within a list context, or a table cell in a table rows context (See next lesson).

To insert an equation into an existing block use the eqni tag; the i at the end is for inline. Like style tags, you really want to close this tag manually.

Within either set of tags, you describe your equation using the eqn language, which was part of the troff typesetting language which was part of the UNIX operating system a half century ago. This was the language I used to describe coupled vector partial differential equations for my doctoral dissertation. The elegance of the eqn language is delightful. It reads like you would describe an equation, albeit with some words abbreviated.

Alas, the TeX typesetting system has become the gold standard for typesetting equations. TeX has more features, but it is WAY harder to type! (But it is not nearly as hard to type as MathML, the hideous Internet standard!!!) If you want to publish a scientific paper in a refereed journal, you might still need to use TeX (I haven't checked lately). But to get your ideas out to the world super quick, take the 0.5-2 hours it takes to learn eqn and get your ideas out with Conntects! Here is some documentation:

QTML uses the GNU version of eqn to convert your equations into MathML. The conversion is not perfect, and GNU eqn does not have all the power of TeX for equations. But if Conntects becomes popular, perhaps the free software community will update GNU eqn to be powerful enough to make real mathematicians happy. Or if Conntects becomes big and profitable, we will pay someone to upgrade the GNU eqn program based on the complaints of our math geek members. Stay tuned...

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).

Lesson 10: Fancy Tables

Comma separated cells are easy to type, but what if you want to use some tags to style up individual cells?

For those situations, use the .row tag. Use this tag for each row in your table. Each block of text signifies a cell on that row. That is, in row mode, blocks of text and tags which would be paragraphs in default mode become table cells. Also, display equations and pictures are legitimate table cells in this mode.

If you want a few styled rows but then want to go back to simple comma delimitted rows, just use the .sep tag instead of a .row tag

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).

Lesson 11: Quotes

Posts and comments often include quoting other people. For this purpose we have the quote tag. The quote is the outermost tag: quotes can include lists, tables, code and equations within.

Exactly how pictures will be handled inside quotes is still TBD. There are security issues around linking to other people's pictures that still need to be worked out.

QTML


Resultant HTML

In the box below is the result of the QTML above (assuming you hit the Apply button above).


Drag the picture you want to upload into the large box below. You can use the controls to edit the picture to be uploaded. This will not affect the picture on your hard disk.

Or, if you are on a tablet or phone, or don't like Drag and Drop, you can select a picture using this

Get a modern browser to make picture uploads

Rotation:
Up Right Down Left

Brightness:
1.0

Color Balance:
Red: 1.0
Green: 1.0
Blue: 1.0
Gray: 1.0

Contrast:
0.0

Cropping:
Slide the boxes with triangles along the edges of the picture to crop.