By: Kenneth Stauffer
NONAME@MYSITE.com
August 4th, 2022
This page shows the raw Tagged{Text} source code for some files used to build this website.
This is the actual Tagged{Text} document that was used to generate: taggedtext.html.
include{common.tt}
MySite.top_url{projects}
MySite.window_title{Tagged Text}
MySite.side{
Heading{
Links
Link{Projects URL{projects.html}}
}
}
MySite.body{
Title{TaggedText{}}
P{ By: AuthorName{} }
P{ TT{AuthorEmail{}} }
P{ B{GitDate{}} }
TableOfContents{}
Section{Introduction}
P{
Here is a description of Tagged{Text},
a very simple file format for organizing text documents.
}
P{ B{NOTE:} This website was constructed using Tagged{Text}. To the see the source
file used to generate this page, click LINK{here URL{taggedtext_source.html}}. }
//{ Hello!!!! This is a comment.
// I
// Love
// You
//}
Section{Example}
P{
The following is a snippet of text which would qualify as a Tagged{text} document:
}
BlockQuote{
Code<<_EOFX_
P{
This is a I{simple} example of B{Tagged{Text}}. Here is a program:
Code<<_EOF_
main()
{
printf("Hello, World!\n");
}
_EOF_
}
P{Click LINK{here URL{http://wwww.url.com?abc90} to visit site.}
P{Escape chars: '\{' and '\}' and '\\'}
_EOFX_
}
P{
This example demonstrates every feature of Tagged{Text}.
A Tagged{Text} document is broken down into the following constructs:
}
BulletList{
Item{ LH{Tags:}
These are introduced via the use of curly braces, preceeded by a I{tag name}.
}
Item{ LH{Heredocs:}
There is one Heredoc in this example, with its own tag name TT{Code}. Heredocs
allow blocks of text to be introduced which will not be interpreted.
}
Item{ LH{Words:}
Words are any whitespace seperated text that is not a B{Tag} or a B{Heredoc}.
}
Item{ LH{Escape Character:}
The escape character is the backslash B{TT{\\}}. It may only preceed the characters B{TT{\{}}, B{TT{\}}},
B{TT{\<}} and B{TT{\\}}.
}
Item{ LH{White-space:}
White-space is used to delimit I{words} and the beginning of I{tags} and I{heredocs}. Whitespace conists
of space, tab and newline characters. Except for delimiting constructs whitespace is stripped
from the Tagged{Text} tree. Only in I{heredocs} is whitespace preserved.
}
}
P{
Tagged{Text} is a file format for tagging and organizing text with tags. These tags can be whatever the author
wishes them to be. For example the TT{I\{ I{...} \}} tag used in the example above could mean "italics".
}
IMGC{images/tt_tree10.png}
P{
This diagram shows a tree representing the example document. Tagged{Text} documents are always given a TT{root}
node. Each node can have zero or more children. The order of the children is the order in which they appear in the file. I{Tags} introduce new
nodes which can have children. I{Words} and I{Heredocs} do not have children.
}
P{
A heredoc ( TT{Code} in this example) consists of the entire block of text that was given. The programming
API makes this text available as a list of text lines. Common whitespace (spaces and tabs) are removed
from the I{heredoc}. Trailing whitespace is also trimmed. This allows heredocs to be indented in you document for
ease of reading. A B{heredoc} uses a delimiter which is _EOF_ in this example. Any text can be used, which
will not be part of the text you want to include in the heredoc. All lines of text between TT{Code\<\<_EOF_}
and TT{_EOF_} will be part of the B{heredoc}.
}
Section{Why use Tagged{Text}?}
P{
It is an agnostic markup format, it can be used to form a basis for documents in a static website generator. The
author would custom craft python scripts to translate their markup tags into their website.
Agnostic means the Tagged{Text} does not enforce any rules or define any meaning to markup tags.
}
P{
I always like the syntax of TeX and LaTeX from my college days. So I designed Tagged{Text} to have a
syntax that reminds me of TeX. Tagged{Text} in my opinion is the simplest file format one can have
to structure a text document and not be over burdnoned with gross syntactic elements.
}
P{
The real power of Tagged{Text} is having programs that can process it. Tree's are very easy structures
for computer programs to handle. The recursive solutions that emerge are very clean and simple to reason
about.
}
SubSection{Blog Entry Example}
P{
Here is an example of a Blog entry:
}
BlockQuote{
Code<<_EOF_
Blog{
Title{What grinds my gears}
Date{2016-3-4}
P{
Ipsum delio gro! Thrunk fo violio of my Streout Santo Listria?
asddsjk kasjdf ksjf ks fks fkfksj dks fksj f
sdfjs f ksf ksfd s
}
P{
Thats all for now. Be back in a few months after I return
from the intl. space station. Oh, here is a cool equation
I wrote in C++:
}
Equation<<_EOC_
E = M C ^ 2
_EOC_
}
_EOF_
}
P{
This could form the basis of content for a blog section in a website.
At this stage you don't care about HTML formatting. Instead focusing on content first.
A tool, you must write, would format these entries into HTML or whatever format you want.
}
P{
The appearance can be tweaked later and never have to concenred with the content when playing around
with the appearance. The TT{Blog\{\}} entries never have to be touched, or retouched as you change your mind
about formatting.
}
Section{Summary}
P{
That is essentially all you need to know about TaggedText{}.
You annotated text with tags, which are simple identifiers
that are case sensitive. I.e., TT{ATag\{\} I\{\<...stuff...>\} TT\{\}}.
You simply invent tags for whatever you feel like doing at the time.
My main problem with markdown languages is they are focused on formatting
and not semantical meaning. Notice the example above is focused on
tagging text based on what is required by a tt{Blog} entry. The formatting
is a secondary concern.
}
P{
The first goal of tagged text is to get your document structured according
to whatever organizing tags you care about. Whenever you face a new problem of expressing
your ideas, just invent tags that structure your text into something sane. Need
a slight variation on the bullet list but with each item kinda sorta like
a dictionary entry? Then invent that structure. Worry about formatting later.
I.e.,
}
BlockQuote{
Code<<_EOF_
DictList{
Entry{
Word{Frelopiated}
Def{
Snake gloves louisianans luck a now glanced turn expressed recorder
dui discovered ruffian the pyramidal nunc
This is when the floop of their then situa el doriao.
}
}
Entry{
Word{Doorliplidated}
Def{Blah blah. I like turtles. Glaxon}
}
Entry{
Word{Libertanist}
Def{This like floop but with situa el doriao.}
}
Entry{
Word{Junk-lick}
Def{gross list, URL{http:://www.junk-lick.com} see more there.}
}
}
_EOF_
}
P{
Some interesting constructions:
}
BlockQuote{
Code<<_EOF_
DEFINE{ MainCharacter{Bob H. Smith} }
DEFINE{ BirthYear{1971} }
P{
My main character in this novel is named MainCharacter{}. He was born
in the year BirthYear{}.
}
_EOF_
}
P{
A simple macro definition scheme, as shown above.
}
BlockQuote{
Code<<_EOF_
//{ this is a comment }
_EOF_
}
P{
A scheme for comments. I wrote a python filter
that is run through most of my documents and it removed these
comment tags.
}
BlockQuote{
Code<<_EOFX_
include{filename.tt}
HEREDOC{ Code{pythonexample.py} }
_EOFX_
}
P{
I invented an include file mechanism, which opens other files
and embeds the Tagged{Text} tree from one document inside the
tree of the main document. Also a way to read in a B{heredoc}
from an external file.
}
P{
The tree like structure is easy to craft and mentally visualize.
Plus tools exist to dump the tree in various formats, even a GUI
using tcl exists. The tree is where is all begins.
}
P{
Now You can write tools to convert peices of the tree into the
final output. How does this work? With a special TT{RawText}
tree node. This node is understood to be already converted
into the final format. Once the entire document consist of
nothing but TT{RawRext} nodes, then it can be simply emitted
as the final output. Just perform an I{in order traversal} of
the document tree and emit the pieces of raw text to the
output.
}
P{
The I{Formatting Problem} can be tackled in a variety of ways.
One cool way, it so successively rewrite the original tree until
it only has tags that are available to a generic HTML formatter.
}
P{
Then the final pipeline would include this formatter and now
you have HTML.
}
P{
TaggedText{} is basically a programming language for text.
By using a very simple syntax (2 constructs) text files can be
organized into a rich tree structure. That is it really.
This file format is totally agnostic about formatting. Downstream
tools will be responsible for that.
}
P{
I call these scripts filters. They do not need to perform 100%
conversion from the TaggedText{} tree format to the final output. Instead,
they can carve out a piece of the formatting problem and leave the rest alone.
}
P{
This means an ecosystem of filters can emerge and be combined to achieved
different results.
}
P{
TaggedText{} lets you invent tags on a whim and worry about the formatting later.
For example, say you are documenting your brand new language. So you have tags like this:
}
BlockQuote{ Code<<_EOF_
Code<<_END_
function foo(a,b,c)
{
d = 100 * a + sine(b)^ * 2 * c;
return d;
}
_END_
_EOF_
}
P{
But then you wish you could automatically run this code and generate the
results. You can! Just invent a tag structure like this:
}
BlockQuote{ Code<<_EOF_
RunCode{
CodeTag{Example1Code}
ResultTag{Example1Result}
Title{Example 1: Sine function}
LineNumbers{yes}
Code<<_END_
function foo(a,b,c)
{
d = 100 * a + sine(b)^ * 2 * c;
return d;
}
_END_
}
_EOF_
}
P{
This tt{RunCode\{\}} tag has many features. Basically it will compile
the code, run it and store the code in one tag variable, and store
the results in another tag variable. Title\{\} and LineNumbers\{\} allow you
to enrich this tag.
}
P{
Now you write a python script to pick out these tags and rewrite the
TaggedText{} tree to replace the Example1Code1\{\} tag with the code.
and the Example1Result\{\} with the result.
}
P{
As a user of TaggedText{} you will organically grow your own set of useful
filters that can be combined together to generate cool documents.
}
P{
The filter concept is great, as you can debug each piece of the pipeline
by viewing it using 'more' or a graphical viewer (provided. see tt-vis-tree)
}
Section{Cheat Sheet}
P{
Here I document all the tags I have use for this website. The python code for
these tags is given also.
}
//{ ********************************************************************** }
BlockQuote{
Code<<_EOF_
Simple Tags
This is B{bold}, I{Italics}, And so on...
_EOF_
}
Section{Tagged Text File Format}
P{
The five syntax elements of Tagged{Text} are:
}
NumberedList{
Item{ Tag }
Item{ Word }
Item{ Here Document }
Item{ Escaping }
Item{ White-space }
}
SubSubSection{1. Tag}
P{
The tag is an arbitrary identifier which begins a new node in the tree
with children. The children of this node are enclosed in curly braces.
}
Code<<_EOF_
Foo{this is foo stuff. Now this is Bar stuff: Bar{1 2 3}}
_EOF_
P{
The key parsing requirement for tags is that a word is B{immediately}
followed by a open curly brace B{\{}. This is what signals to the parser
that we are entering a tag.
}
SubSubSection{2. Word}
P{
Any non-whitespace text that lacks a trailing curly brace B{\{} shall
be considered a word. These are all words:
}
Code<<_EOF_
Biteme
@@
Hello,There
done.
(stealth)
f(1,2,3)
_EOF_
SubSubSection{3. Here Document}
P{
You can associate an arbitrary identifier with a bunch of text that
is perfectly preserverd and untainted. All whitespace is preserved.
All special characters are preserved. This is for things like code
and quoting text that you don't want interpreted.
}
SubSubSection{4. Escaping}
P{
Escaping is for preventing a couple special characters from being
mis-interpreted. The backslash character is the escap character.
It is use to escape B{\{} and B{\}} and B{\<} and B{\\}. So anytime
you wish to use these characters they must be preceeded with the slash.
}
P{
Futhermore, it is an error for the back slash to preceed any another character.
}
SubSubSection{5. White-space}
P{
Except in Here Document, white-space is used only to seperate words.
This may seem drastic but I haven't found any cases where it hurts things.
}
P{
It has the nice benefit that you can indent you document to fit your
coding preferences. You can use indenting to give the document the friendly
viewing capabilities you want.
}
P{
Even blank lines have no effect on the TaggedText{} tree that is created. Inside of I{Here Document's}
white space is removed as much as possible too. Whitespace removal is a great normalization of
the document.
}
P{
How to do tables?
I prefer using tags that match your specific needs, not writing to a generic way.
So rather than invent massive table package and assorted tags, just invent
the minimum viable set of tags to accomplish your particular task.
}
P{
You simply need something pretty to present a nice clean two column table
of dates and inflation numbers. Just invent this for now:
}
Code<<_EOF_
KennysSimpleTwoColumnTable{
H{Date} H{Inflation}
D{3/4/68} D{1.2}
D{3/4/78} D{2.2}
D{3/4/88} D{4.2}
D{3/4/98} D{6.2}
}
_EOF_
P{
Another example, one might wish to invent tags like this to keep track
of all your dives in text database, then use python to format it nicely for the web.
}
BlockQuote{
Code<<_EOF_
DiveLog{
Date{2018-03-04}
Time{14:30}
Site{Lake Travis}
Location{Austin, TX}
Duration{45 minutes}
MaxDepth{85 ft}
AirStart{3100 psi}
AirEnd{400 psi}
Temp{65 degrees}
Buddy{Hans Solo}
Equipment{8mm full, hoodie, 90 watt light}
Visibility{20 ft}
Notes{
P{
Dive went well. I saw the plane. I saw a several
giant cat fish around the damn area. My tank slipped out again, had
to take my BCD off and tighten. Saw a group of other divers getting
out when I was getting in.
}
P{
visibility was pretty good, especially at depth.
}
}
}
_EOF_
}
P{
With Tagged{Text} I can create really elabote macros:
}
Code<<_EOFX_
DEFINE{ Bob{
Code<<_EOF_
fhsdjsdf skd
sdfjsdfskdfjk
sdfsdf
sd
f
sdf
sdf
_EOF_
}}
_EOFX_
P{
So now the handy tag TT{Bob\{\}} spits out a Here Document into my code.
}
} //{ MySite.body }
Here is common.tt, one of the files included by the previous file:
//{
//
// These definitions are common to all web pages.
// To use this file do this: include{common.tt}
//
//}
DEFINE{ AuthorName{Kenneth Stauffer} }
DEFINE{ AuthorEmail{NONAME@MYSITE.com} }
DEFINE{ BirthYear{1968} }
MySite.name{ AuthorName{} }
MySite.logo{ Ken Stauffer }
MySite.email{ AuthorEmail{} } //{ my email }
MySite.year{2016 - 2023} //{ my copyright year thing }
MySite.lastmodified{ NowDT{} } //{ gets set to the current date/time whenever static site built }
//{
//
// This defines the top links and their names
// Use MySite.top_url\{....\} to make one of these
// the "active" onve
//
//}
MySite.top{
Item{home URL{index}}
Item{cv URL{cv}}
Item{projects URL{projects}}
Item{blog URL{blog}}
}
And now... to totally mess with your mind, here is this file: taggedtext_source.tt:
This is the Tagged{Text} commands needed to include a file:
BlockQuote{ HEREDOC{ Code{taggedtext_source.tt} } }
include{common.tt}
MySite.top_url{projects}
MySite.window_title{Tagged Text Raw Source}
MySite.side{
Heading{
Links
Link{Tagged Text URL{taggedtext.html}}
}
}
MySite.body{
Title{Tagged Text Raw Source}
P{ By: AuthorName{} }
P{ TT{AuthorEmail{}} }
P{ B{GitDate{}} }
P{
This page shows the raw TaggedText{} source code for some files used to
build this website.
}
TableOfContents{}
Section{ taggedtext.tt }
P{
This is the actual Tagged{Text} document that was used to
generate: LINK{ URL{taggedtext.html} }.
}
BlockQuote{ HEREDOC{ Code{taggedtext.tt} } }
Section{ common.tt }
P{ Here is B{TT{common.tt}}, one of the files included by the previous file: }
BlockQuote{ HEREDOC{ Code{common.tt} } }
Section{ taggedtext_source.tt }
P{
And now... to totally mess with your mind, here is I{this} file: B{TT{taggedtext_source.tt}}:
}
This is the Tagged{Text} commands needed to include a file:
Code<<_EOF_
BlockQuote{ HEREDOC{ Code{taggedtext_source.tt} } }
_EOF_
BlockQuote{ HEREDOC{ Code{taggedtext_source.tt} } }
} //{ MySite.body }