--------------------------------------------------------------------------------
------------------------------Introduction to Tent------------------------------
-----------------------------"Email needs a change"-----------------------------
-------------------------------Ted (doseofted.me)-------------------------------
-----------------------------------2015-03-14-----------------------------------
--------------------------------------------------------------------------------
Email as we know it has been around for a long time yet we don't really have a
standard for how message content is formatted. Yes, we use HTML and CSS but
these languages are intended for creating and formatting web pages - not
messages. Because of this, we receive emails that look like basic web pages -
not messages. We need a format that is designed specifically for our email, a
format that maximizes readability and makes email enjoyable and efficient. In
order to do this, we first have to decide what parts of an email are essential.
The most important parts of an email are the text, the media and the
organization of the text and media. That is specifically what the Tent language
and design is made for.
Tent is meant to replace HTML in emails. That can't happen unless email clients
are on board and Tent becomes an official standard. Because of this, Tent cannot
be used in reality. Instead, it is a suggestion for a distinct message content
markup.
--------------------------------------------------------------------------------
--------------------------------Tent Language (v1)------------------------------
--------------------------------------------------------------------------------
Structure
--------------------------------------------------------------------------------
So, how do we write a "Tent" document? Let's open our favorite text editor and
get started. There are two important structures that we need to know. These are
called the "tent" and the "poles."
/!\ This is a tent.
|| These are the poles.
The "tent" is used to declare our document and to insert media (image, video and
audio). The poles are used to format the text of our document. These two
structures will be explained in a minute.
Declaration
--------------------------------------------------------------------------------
To declare our document we insert a "tent" structure followed by a space and
then by a number. This number will be the version of Tent being used. This
version is 1. The markup is shown below.
/!\ 1
We now press the Enter/Return key. We have just declared our document!
Inserting Text
--------------------------------------------------------------------------------
Text is inserted into the document simply by entering the text. Each line of
text is considered a paragraph. Pressing Enter/Return will create a new line and
therefore a new paragraph. An example is shown below.
This is a paragraph.
This is a new paragraph on a new line.
Multiple new lines will be ignored since you cannot have an empty paragraph.
Therefore you cannot have empty new lines. Tabs are also ignored.
Formatting Text
--------------------------------------------------------------------------------
Text can be formatted by using the "poles" structure. The poles are prefixed by
a letter representing its function. The text to be formatted goes in-between the
poles. Three examples are shown below. The "t" stands for title. The "i" prefix
stands for italics. The "b" prefix stands for bold. A list of formatting
prefixes are available in the Reference section.
t|This is a Title|
What's i|my| name?
My name is b|Ted.|
Formatting should not span multiple lines. Using the vertical bar to format text
can lead to issues when typing code snippets. To escape the vertical bar, simply
use another vertical bar as an escape character. For example, the logical OR
operator would be typed by prefixing each vertical bar with another vertical
bar. Therefore four vertical bars would be seen by the reader as two vertical
bars. However, code is meant to be attached to the email and not to be typed in
the message body.
Tent only supports basic functional formatting. Formatting that does not clarify
the message is not used when writing in Tent. Nonfunctional formatting (like the
typeface) will be handled by the email client and then adjusted by the user
through "theming" (explained later in "Tent Design") to improve readability.
Inserting Media
--------------------------------------------------------------------------------
Media is inserted into the Tent document by typing the "tent" structure followed
by a space and then by the path of the media. Optionally, the path can be
followed by a space and then by text which will be the media's caption. Media
must be on a line by itself. An example is shown below.
/!\ /path/to/file.format This is a caption.
Tent is made to only support image, video and audio files. Popular media formats
should be used to ensure access across different clients.
Reference
--------------------------------------------------------------------------------
Media and Declaration
Declaration
/!\ 1
Media
/!\ /path/to/file.format Caption text goes here.
Text
This is text. No tags, braces, or other structures needed!
Text Formatting
i|italic text here|
b|bold text here|
t|Title Text Here|
-t|Subtitle Here|
--t|Subtitle of Subtitle Here|
l|descriptive link text here|domain.tld/page|
--------------------------------------------------------------------------------
---------------------------------Tent Design (v1)-------------------------------
--------------------------------------------------------------------------------
Format Basics
--------------------------------------------------------------------------------
Tent as a language does not specify the message's layout - it's not supposed to.
This is handled by the email client with suggestions from this documentation.
By not allowing messages to specify a layout, the client can organize the
message in a way that can easily be read and adjusted by the user. It also
prevents the user from receiving an email that looks like a web page. Tent puts
the focus back on the message, where it should be. Tent's design describes how
messages written in Tent should be formatted. It also describes behaviors that
should be utilized by the client using Tent.
Titles
--------------------------------------------------------------------------------
Tent defines a title through the title poles structure, shown below.
t|This is a Title|
Clients should not specify a "Subject" field when writing messages in Tent since
the subject is already handled through "title poles" above. If a message
written in Tent has more than one title, the first that appears in the message
should be used.
Replies
--------------------------------------------------------------------------------
Email today is often redundant when it comes to replies. By default, many
clients will quote the entirety of the message the user is replying to.
Considering many clients also use conversation threading, this is pointless and
sends more data than what is needed. Messages written with Tent should not quote
the message a user is replying to. This being said, Tent depends on conversation
threading.
Forwarding
--------------------------------------------------------------------------------
Tent does not support block quotations in an effort to make messages simpler and
to thwart email forwarding. Forwarded emails make the reader assume that the
forwarder made no changes to the original message which can damage the original
sender's reputation. Messages written in Tent should not be forwarded. If a
received message needs to be sent to more recipients, the original sender should
be the one to send said message to more recipients.
Image Formatting
--------------------------------------------------------------------------------
Images are the most likely media to be used in a message. It is important that
the images are cleanly placed in the message on all screen sizes.
Images should be aligned to the text based on its aspect ratio. An image with a
larger width than height should take up an entire line to ensure it is
easy to view. An image with a 1:1 aspect ratio or a height larger than width
should be left or right aligned to large paragraphs. If a Tent document has very
little text then the image should be placed on its own line. If many images are
placed one after another without text separating them, a "gallery" view should
be displayed to the user for easy navigation.
On devices with little screen real estate, all images should take up an entire
line unless in a gallery.
Video and Audio Formatting
--------------------------------------------------------------------------------
Video and audio should be placed on its own line so the user can easily scrub
the media. Video with 1:1 aspect ratio or with a height larger than its width
should follow the same rules as images.
Nonfunctional Formatting and "Theming"
--------------------------------------------------------------------------------
It is suggested that the email client lets the user specify what typeface,
margins and other formatting to use when reading messages; this formatting
should be applied to all messages to create a consistent reading experience.
This makes reading a lot of emails much easier.
Technical Notes
--------------------------------------------------------------------------------
There are some technicalities that should be addressed, such as the problem of
newline characters. In some text editors, the program will insert a carriage
return and then a newline character when the user presses Enter/Return; newlines
and carriage returns followed by newlines should be interpreted the same.
Another issue is the use of too many newlines and the general use of tabs.
Paragraphs should be separated by only one newline character. Multiple newlines
and carriage return/newline combos should be ignored. Tabs should also be
ignored.
Another issue is the use of spaces. Some users may try to use four spaces to
represent a tab. However, only one space is allowed between characters. Code
should be inserted into an email as an attachment, not in the message's body.
--------------------------------------------------------------------------------
------------------------------Questions and Answers-----------------------------
--------------------------------------------------------------------------------
Why not write "Tent" in XML?
--------------------------------------------------------------------------------
I didn't want to. Tent's markup is much smaller, doesn't require tags for text
(which Tent is focused around) and doesn't require ending tags.
Is Tent an acronym?
--------------------------------------------------------------------------------
No. The "tent" structure just looks like a tent. /!\
What is/isn't Tent?
--------------------------------------------------------------------------------
Tent is used to format the message body. It is a markup language. It is not XML.
It is not a protocol.