kellyfelkins.org: textpattern

problems with textile

A key component of textpattern for me is the textile system of generating pages with simple text. As I described in simplifiedmarkup, systems like textile can really simplify the maintenance of a web site, and by doing so facilitate the expansion of content on the site. Textile was one of the reasons I initially chose textpattern for my content management system / blog software.

Textile is cool, but it is not perfect. My hunch is that textile is suffering from a greatly expanded charter, flawed design, and flawed implementation.

Before I go further, let me say that my goal is not to dis textile. I like it, though I’m a bit frustrated with it. I hope these problems get resolved, and I’m contemplating fixing them myself.

What’s wrong with textile? This is what I’ve noticed: I’m spending way too much time wrestling with textile. By “wrestling” I mean trying different things to get textile to render the way I want. This is important because the reason for textile is to save time. If I can do the same thing with hand coded html in less time, then I don’t need textile.

I’m going to list the problems as I encounter them. I’ll update this periodically with both new problems and, hopefully, fixes.

Textile problems:

Textile parsing and transforms are not well documented. There is a page where you can try it. There are examples. And there are small descriptions for various pieces. Normally I would consider this pretty good documentation, but when I am trying to resolve a problem I find myself looking all over the place for a hint.
I encounter various apparent parsing problems. Often things start working if I put a new line in at a strategic position.
As far as I can tell, there is no simple character escape. Sometimes you want to tell textile to simply display this exact character—don’t interpret it, don’t reformat it, don’t do anything with it.
At least one documented bug: alignment of images is broken.
On one page I can’t get a bulleted list to work correctly. The bulleted list has 2 levels. At various times the primary level (single *) gets displayed shifted right. This page displays this problem.
I have a table. Each column has a title. If the first column is empty, textile ignores it, messing up the alignment of the other columns.

Share this article on

Comment

* * *

permalink

simplified markup

I’m interested in systems that convert simple text with optionally simple markup to html. I’ve used 2 such systems now:

textile, used by textpattern (this site’s publishing system)
the text formatting used in twiki.

but why?

Two main reasons:

coding html/xhtml/sgml is tedious
html/xhtml/sgml code is complex and hard to comprehend

I guess #1 is important to me as the primary author of my documents—simply put, I want to create these documents quickly and easily and have the output be valid html.

#2 becomes important when others must maintain the document. This is a key motivation for the twiki markup language—the system is a group collaboration system, and targeted to people that may not be skilled in html.

Textile extends #1 above to include translation of simple quotes and other punctuation to, um, the “more proper characters”. Matching double quotes become the paired, directional quotes, as in the previous sentence.

"before textile" —“after textile”

historical context

Here are some other systems (in no particular order):

No-Tags Markup
txt2html
setext is described on the meatball wiki. It has been apparently abandoned, but superceeded by other tools.
zope’s StructuredText
wikiwiki TextFormattingRules
reStructuredText from python’s docutils.
markdown
smart ASCII
probably many more…

challenges

These are great for creating documents with simple markup, but you soon want to do something that goes beyond the scope of the tool. As an example, I often want lists in tables. In twiki, tables and lists rely on lines for information about layout. A new line indicates a new list item (or the end of the list). A new line indicates a new row in the table, or the end of the table. Fortunately, twiki allows you to drop in regular html markup as needed, so if you really want a list in a table, you can just put the list tags right in, or code the whole table and list in html.

other strategies

Another technique is to use a wysiwyg editor in a web form. There are a few of these available, too:

FCKeditor. It didn’t seem to work in mozilla, but looked nice in IE.
htmlArea

Share this article on

Comment

* * *

permalink

textpattern sections, pages, forms

I’m trying to understand the details of textpattern.

pages – think templates

Textpattern “pages” are poorly named—they are templates. I’m going to call them templates—when you see “template”, think textpattern page.

OFTB, textpattern has the following templates:

template	description
default	this appears to be the page displayed when you go to the home page. The home page can list pages from multiple sections.
archive	this is the default article type. There is a section called article, and the associated template is archive.

One of the key differences between the templates is the stuff that displays the content:

default	<txp:article limit="5" />
archive	<txp:article />

forms – think includes

Forms are chunks of html that can be included into templates, and probably other forms. I guess I would have called these includes.
Template default appears to include form default as its repeating element, as does template archive.

Form comment and form comment_form are used for comments, the latter being the actual comment input form, and the former display of the comment.

sections

Each piece of textual content—let’s call them articles—has a single section associated with it. The section defines:

site organization	in that the section name is a folder / directory in your urls. Note, though, that the hiearchy is pretty flat right now, as you cannot nest sections natively. However, I’ve been nesting sections by creating new instances of textpattern in the hierarchy. Clearly I’m going to hell for this.
indirectly presentation	since you can associate templates with sections.

Share this article on

Comment

* * *