QTML Reference

Carl Milsted, Jr on Jun 4 12:59:37

View QTML

Table of Contents

• The Syntax
• Basic Blocks (paragraphs and headings)
• Styles
• Links
• Pictures
• Video
• Lists
• Tables
• Code, Poetry, and Typewriter Mode
• Equations
• Quotes and Wide
• Miscellaneous: Moderation, Social Graph, etc.

QTML Syntax

QTML is a line based language. Tags are created by a period at the very beginning of a line.

.tagname	Beginning tag
..tagname	Ending tag
...	If you need to start a line with a period, type three dots in order to avoid treating your following text as a tag

(Note: in all this reference, italicized text means text to be substituted vs. literal text.)

Basic Blocks

blank  line	A blank line ends a block. If the next line is just text, a default block is created. Usually, this is just a paragraph, but within lists or table rows, the default block is a list item or table row
.p	The p tag is an explicit way to start a paragraph. Usually not needed since paragraphs are the default block.
.p desc	The p tag with the desc attribute means use the paragraph as the description for your post. This is useful for SEO and sharing on other social media. (By default the first paragraph of a post is used for the description.)
.desc	Create an invisible paragraph which is used for the post description.
.h	Top level heading
.hh	Second level heading
.hhh	Third level heading

Note: the beginning of a block automatically closes the current block. No need for closing tags (but you can use them if you want).

Inline Styles

Within paragraphs, headings, table cells, etc. you can apply a wide array of different styles. Styles can nest; that is, you can have text that is both bold and italic. Unlike HTML, QTML inline styles automatically close at the end of a paragraph or other block.

The basic syntax:

.tagname	Begin the style
.tagname  bs	Begin the style without a preceding space. bs stands for "backspace"
..tagname	End the style.
..tagname  bs	End the style without putting a space after the change.

Note: since the usual convention is to treat a return as whitespace, the default is to have space around a styled range. This is both intuitive and a good default. The bs attribute can be added when you don't want space around the styled range. A canonical example: underlining periods looks ugly, but you also don't want space before a period, so ..u bs is common.

Exception: superscripts and subscripts do not get a space before them by default.

Tag	Meaning
i	italic
b	bold
u	underline
del	strikethrough. del stands for delete.
red	Red text
yellow	Text with yellow background -- like a highlighter
icode	Inline code like so
sup	superscript
sub	subscript

Links and Anchors

Unlike most social networks, Conntects does not automatically turn URLs (web addresses) into hyperlinks, nor does Conntects grab headlines, featured images, or descriptions from other sites. You need to use the link tag. link behaves much like a style tag, save that you must have the web address as the first argument. To avoid a space before or after your link text, use the bs argument just as you would for a style tag.

.link  address	Begin hyperlink. Subsequent lines are link text. By default, links open in a new window or tab.
.link  address  this	Begin hyperlink. Opens link in the current window. this means this window
..link	Finish link text. Throw in the bs argument if you don't want a space after the hyperlink.
.a  name	Named anchor. You can then link to a different part of your post using this name preceded by the # sign.

Note on anchors: some anchor text names are reserved by the system, such as top, bottom, and commentStart. Eventually, the system will flag such name collisions.

For an example of anchors in action, just hit the View QTML button for this reference and look at QTML for the Table of Contents and the headings.

Pictures

.pic  picname	Insert a picture. If picname corresponds to an already uploaded picture, that picture is used. Otherwise, you will see an Upload Pic button in your preview window (This is no closing tag for pic)
.pic  picname  f	Insert a picture and make it the featured image. (By default, the first picture in your post is the featured image.) Useful for sharing your post on other social media
.pic  picname s	Insert a picture but make it roughly half the usual size. s stands for small. (Note that pictures in tables and lists are already small (tile size). Use the s flag inside a table or list and you get thumbnail size images.)
.pic  picname s f	Insert a picture and make it both small and featured. Order of flags does not matter

Video

Conntects does not actually host videos, but you can embed video from YouTube and Rumble. (More services to come.) The syntax is:

.video

address

begin time

The begin time field is optional and currently only works for YouTube videos. Its format is the usual colon separated fields such as 1:23 or 2:30:01 or can be just a number of seconds.

For YouTube, the address can be that in the address bar when you are at YouTube video page, or it can be the URL provided by the Share button.

For Rumble, use the Embed IFRAME URL provided when you hit the Embed button. You have to use this for Rumble, since Rumble's page URLs are wildly different from the embed URLs. You also need to use Rumbles Start At feature if you want to begin anywhere other than the beginning.

Lists

QTML currently supports two kinds of lists: bullet lists and numbered lists. Currently, lists cannot be nested.

.list	Start a bullet list.
..list	Finish a bullet list. Lists must be closed!
.numlist	Start a numbered list
..numlist	Finish a numbered list.
blank  line	Within either kind of list, a blank line starts a new list item.
.pic  picname	You can have pictures inside lists. A picture is a list item.
.eqn	You can also have display equations in lists. See the equations section for details on equations.

Tables

.table	Begin a table. The first row of your new table will be headings by default.
.table  nh	Begin a table with no heading.
..table	Finish a table. Tables must be closed.

By default, the text between the table tags is treated as CSV format. Each line is a row and commas separate the cells. If want something different, see the following tags which can be used inside tables:

.sep  separator	Change the separator to be used. If separator is missing, go back to commas.
.row	Start a fancy row. Now each block is a cell. Blank lines separate cells. You have blocks of text, pictures, or display equations as cells. Currently, there is no way to have multiple paragraphs within a table cell or lists within a table cell
..row	Finish a fancy row. You can omit this tag if you are starting a new row with the .row tag. A new row automatically finishes the previous row.

For general readability, the width of text is limited no matter how wide you make the window. If you have a large number of columns in your table, surround the table with opening and closing wide tags. This will stretch your table to window width.

Code, Poetry, and Typewriter Mode

Sometimes you want your line breaks to be preserved. Common examples are computer code and poetry.

.code	Go into code mode. The background becomes dark, and the font becomes fixed width. Your line breaks become line breaks
..code	Exit code mode. Code must be closed.
.poem	Go into poetry mode. The font becomes a roman font. Your line breaks become line breaks
..poem	Exit poetry mode. Poems must end.
.type	Enter typewriter mode with normal font. Line breaks are preserved.
.type c	Enter typewriter mode with Courier font. (Courier is the standard typewriter font.)
.type i	Enter typewriter mode indented halfway across the page. Useful for mimicking the style of a business letter.
.type c i	Enter typewriter mode in Courier font and indented halfway across the page. Order of i and c flags does not matter
..type	Exit typewriter mode. Mandatory.

You cannot use block level and above tags in either code or poem mode. However, you can use inline styles. When in either mode, the bs attribute on opening and closing tags says don't start a new line, vs. don't add whitespace. If you need a space, then you need to add it to end of the previous line or beginning of the subsequent line.

Since wrapping lines in either code or poetry is bad form, if you have really long lines, you should wrap your block of code or poetry with opening and closing wide tags.

Equations

.eqn	Start a display equation. (A display equation is a block, just like a paragraph or list item.
.eqn  equationNumber	Start a display equation with an equation number.
..eqn	Finish a display equation. Closing equations is mandatory. Unlike other blocks, line breaks do not finish equations. This is to make it easy to visually break up equation source code for complicated equations.
.eqni	Begin an inline equation. Useful for short snippets inside a paragraph, list item, table cell etc.
..eqni	Finish an inline equation. Mandatory.

Within the eqn tags, you describe equations using the ancient eqn language that goes back to the early days of the UNIX operating system. For details on the eqn language here is some documentation:

• Equations in QTML A short tutorial to get you started
• Typesetting Mathematics—User's Guide Second Edition, by Brian Kernighan and Lorinda Cherry. The actual manual which came with UNIX a long long time ago. Worth printing out.
• Brian Kernighan's ACM paper on eqn. The link takes you to the abstract. Hit the PDF link on said page to get the actual paper. I recommend you print it out. It's quite readable and a useful reference.

Quotes and Wide

The outermost contexts in QTML are block quotations and spans of wide text. Mixing the two is not officially supported.

.quote	Begin a block quote. Block quotes can be nested! Putting images inside block quotes is not recommended. Picture names are dependent on who owns the image. (A better means of sharing posts is on the todo list.)
..quote	Finish a block quote. You need as many closing quote tags as opening. Mandatory!
.wide	Jump out of the standard margins and go wide. You can engulf paragraphs, tables, spans of code, etc. inside this tag. Use sparingly, as overly wide text can be hard to read.
..wide	Ends the zone of extreme wideness

Miscellaneous

Moderator and Author Notes

When moderating a post (or eventually comment), it is useful for moderator and post author to be able to communicate within the text itself, to flag what has been changed or what needs to be changed.

.auth	Begin a comment by author to moderator. This tag should not be used inside a list or table.
..auth	Finish a comment by author to moderator. Mandatory
.mod	Begin a comment by moderator to author.
..mod	Finish a comment by moderator to author. Mandatory

Author and moderator comments are automatically stripped when a post is published. Such comments can be multiple paragraphs, but putting tables, lists, etc. inside such comments is not recommended. And definitely do not put such comments inside any context other than the default context.

Social Graph Stuff

For public posts, Conntects by default uses the first paragraph as the description to be shown when other social sites do a scrape. The first image in a post is the default featured image.

You have two options for changing the description:

.p  desc	This is the (usually unnecessary) opening tag for paragraphs with the desc attribute added. If you add the desc attribute to multiple paragraphs, the last such paragraph will become your description.
.desc	If you want a description other than any paragraph in your post, use the desc tag followed by a hidden paragraph of text. An empty line or the start of another block type ends your hidden description.

For pictures, use the f attribute after your picture name to denote which picture you want to be the featured image.

Tags: QTML