Almost Free Text

I have Patterns in MS Word RTF, LaTex, and HTML. So how do I maintain so many formats? I decided that I needed to adopt a standard documentation system to keep my various Patterns in a manageable format.

MS Word was unacceptable. That would mean that I would have to install the product everywhere I work (I spend quite a bit of time in UNIX).

LaTex is my standard documentation format, but my fingers cramp from all the curly braces and verbose inline commands.

HTML has the same problem (and I can't rely on keeping a WYSIWYG HTML editor handy everywhere I go).

So, I was inspired by Wiki TextFormattingRules. Most of the markup is done unobtrusively. About a year ago, I began working on a standard markup syntax and came up with AFT (Almost Free Text).

AFT modifies and extends Wiki markup conventions:

Section names are preceded by 1 to 4 asterisks (for different levels).
Bolding can span lines and uses _ to denote beginning and end.
Emphasis works just like Wiki (but can also span lines).
Bullet, named, and numbered lists are supported and work like Wiki.
A Verbatim (pre-formatted) and Quote mode is supported.

All of this is done in a way that requires few commands (like Wiki) and looks very readable in its own right.

Right now, AFT outputs LaTex and HTML. I am producing some shaky RTF (it works but needs improvement).

-- {JeanJordaan} Hey, Todd, this was in 1996! Not only has your web page moved (to http://www.maplefish.com/todd), it also now has:

Here are some of the new features of AFT 5:

: RTF and LaTex support has been dropped. (Soon to be added XML support should expand your output format options!)

My next improvement is to add a style for doing Patterns in an Alexandrian form.

So far, it works great.

-- ToddCoram

LarryWall uses something very similar for Perl 5 documentation. He calls it ``perlpod'' (Perl Plain Old Documentation). Here's the perlpod man page in HTML - http://www.perldoc.com/perl5.6.1/pod/perlpod.html and pod - http://search.cpan.org/src/SBURKE/Pod-Simple-2.05/lib/perlpod.pod formats. There's also a scheme implementation for POD: SPOD. You can find it here: http://elementals.sf.net/spod.html.

(Should you format AlmostFreeText, or leave it in a form that's easy to edit? Todd and I disagree, as you can tell if you look at the Wiki source for this page.)

-- PaulChisholm

I now do all my pattern writing using AFT. My PLoP96 paper was written by me and my co-author using AFT because I don't have access to MS Word. It was an interesting collaborative experience. I used emacs; he used Word. We exchanged pattern edits via mail. Our patterns were hyperlinked when online and referential when printed. The final conference paper was produced directly from AFT sources.

If you want to take a look at AFT, check out http://www.maplefish.com/todd. Hey Ward, thanks for the inspiration. If imitation is the sincerest form of flattery...

-- ToddCoram

It is a good idea - ZopeApplicationServer's StructuredText http://www.zope.org/Members/millejoh/structuredText is similar.

See also setext (StructureEnhancedText) which I've used for years in an email newsletter for good results. If you're not familiar with the tags you won't even notice them.

If this is a pattern, I HaveThisPattern. When I was revising for my final exams, I wanted to write revision notes on my computer. I didn't have (or want) word, HTML is too verbose to write by hand, and plain text wasn't expressive enough. So, i cooked up a 'revision notes' format; this is a hierarchical format, where curly-brace-delimited sections contain other sections, and each section has a title and some content paragraphs. There are simple conventions for _italics_ and *bold*, as well as for embedding an [+image.png], a [:http://hyperlink.com/like/this.html], a [*"Literature reference" Anderson T. (2002) Wiki Wiki Web 12(3):456], and internal [=anchors] and [>links]. I wrote programs to convert these files to HTML representations, either of the whole thing, or just the section titles (as nested ordered lists), or just section titles plus references, etc. N.B. the bold tag in this example was not closed.

I still use this format for making notes - it's so much more simple and compact than any real format.

-- TomAnderson

Actually, I now use something simpler and more wiki-like. -- ta

Shouldn't that have been /italics/ and _underlined_?

RealMenDoNotUnderline in printed text, nor in text intended for display in a web page, because underlining is assocated with links.

It seems that AlmostFreeText may mean "personally agreeable and customized text", and has little to do with the cost of the tool, whether acquired or programmed by the user.

Free as in style.

I cannot resist to mention my stx2any (http://sange.fi/~atehwa/Stx/) here, too. I hope some day the world will use One Great Unified Structured Text Format, but waiting for that, these software packages can be considered research in the area...

I deem it unfortunate that Wiki's TextFormattingRules originally chose to use apostrophes to mark emphasis. It doesn't look right when read in source form, and it's not very intuitive. -- PanuKalliokoski

Check out Txt2Tags also, at sourceforge...converts to html, xhtml, LaTex, plain-text, moin-moin, magicpoint, and others. Written in Python. Actively developed. -- pond

There is also Halibut http://www.chiark.greenend.org.uk/~sgtatham/halibut/

CategorySoftwareTool