Styled Text Pages Suck
(Note: I still believe this page to be useful for others, however, I have stopped using this method as my reStructuredText plugins give me a "better" alternative.)
Ok, there's no other way to say it... Styled Text pages suck. You wanna know why? There are three major reasons:
First Problem
Styled Text lacks some serious features in order to make the claim, "You don't have to know HTML".
- It can't do bulleted lists or numbered lists.
- It can't do tables.
- There's no way to add your own styles (without reverting to HTML and "Ignore Formatting").
- It can't do horizontal rules.
- It can't do proper headings (i.e. <h1>, <h2>, ...)
Now I know you're saying, "Proper headings?? Sure it can!". Well, that's true, but Styled Text is supposed to be WYSIWYG and if you want to get proper headings, it's no longer WYSIWYG. And, let's face it - that's a small list. There should be more there, but I wanted to hit my personal highlights.
Second Problem
Styled Text's default formatting is wrong; just plain wrong.
By this, I mean the following:
Back in the "old" days (say mid-90's) we used to mark things up like this:
This is my first
paragraph.<br/>
<br/>
This is my second
paragraph<br/>
<br/>
If you thought you understood proper HTML, then you might do this (but, of course, you'd be insane):
<p>This is my first paragraph.</p>
<br/>
<p>This is my second paragraph.</p>
<br/>
But then we got smarter and realized that embedding format into the HTML was really a bad idea and along came CSS. As a result, this became the de-facto standard:
<p>This is my first paragraph.</p>
<p>This is my second paragraph.</p>
Which one do you think RapidWeaver uses? Yup, you guessed it; the first one. When you make a paragraph with an editor, you hit Return when the paragraph ends. If it doesn't incorporate proper paragraph spacing (as Styled Text fails to do) then you hit Return again to get the proper "look". That results in number 1 above.
You can, however mark a section of text and then use the
menu option Format -> HTML -> Paragraph
which will get rid of the first <br/>. However, the
second one is still there. The first thing you try to do
here is to delete the extra "Return" and then mark the
second paragraph. Well, the problem now is that the two
marked sections join up into a single paragraph. You
must have unformatted space between formats of the same
type. And the first thing you think of to give you
that is, a "Return".
Third Problem
It destroys all "natural" formatting. The entire page goes on one bloody line, which makes doing proper <pre> tags impossible because it turns this:
<pre>
function myfunction
{
if [[ $this == $that ]];
then
echo
"hithere"
fi
}
</pre>
into this
<pre>
function myfunction { if [[ $this ==
$that ]]; then echo "hithere" fi } </pre>
Getting Around the Problems
Solution to Problem One
Use plugins! Essentially what you're going to do is turn the Styled Text page into nothing but a container for plugins. Of course, if it works for you, feel free to use some of the Styled Text features from time to time (the only thing I can think of at the moment is placing images), but you're probably going to find things much better if you leave Styled Text alone for the most part.
I generally use Markdown, and there are very good reasons why it is so popular. There are a couple of plugins available for RapidWeaver regarding Markdown, but I happen to use Andre Pang's Markup plugin. The Markup plugin includes, not only Markdown, but also TextTile and a BASH filter. The bash filter allows us to take the output of any UNIX or Shell command and insert it into the page at compile time.
The BASH filter lets me do things like saying that this page was last updated on Thu Sep 6 2007 at 18:56:50 EDT.The above was done by writing "date '+The BASH
filter lets me do things like saying that this page was
last updated on %a %b %e %Y at %H:%M:%S %Z.'" and
then marking that section in BASH markup.
I have to give it all to BASH instead of just giving it
'%a %b %e %Y' and '%H:%M:%S %Z'
in separate calls because I'm inter-mixing it with
Markdown, and Markdown is going to put <p> and
</p> in the transitions which will make it look
stupid. If the plugins knew about each other they may not
need to do this, but that might not be the ideal solution.
If the entire page wasn't all shoved on one line then we
could easily post-process it by removing the </p>
part of </p>{Return} and the <p> part of
{Return}<p>, but we can't do that.
Solution to Problem Two
I have to give credit to Giuseppe Caruso for a post of mine that he responded to in the Feature Requests area of the RapidWeaver website.
If you read the post, you'll know that he's telling us to do things in "rows". That equates to the following:
Where blue represents Markdown, pink is "Ignore Formatting" and the yellow is the High-Light plugin. This basically allows us to use Styled Text as a "plugin container" that stays out of our way and doesn't format anything. Strictly speaking, we don't need the pink sections when the markup on either side of them are different from each other, but it makes for a nice "base case" (i.e. do this all the time and it will always work).
Solution to Problem Three
Roger Nilsson has jumped in to save my ass here with his High-Light plugin. It is a front end to GNU Source-Highlight, and if you have a need to do <pre> tags in a styled text page and to make them look nice as well, you've gotta grab this plugin.
Summary
RapidWeaver is a really great app, don't get me wrong. This page discusses one aspect of the product. Unfortunately, it's a big aspect of it and it sucks, but that doesn't mean that the entire product sucks.
Plugins are the best way to get around the many deficiencies of the Styled Text plugin. The guys at RealMacSoftware promote RapidWeaver by saying "You don't have to know HTML". Well, sorry guys, but that just ain't so. Sure, you don't have to know HTML, but if you want to do anything but write the odd paragraph here and there and not really care how it's styled, then you had better know a fair bit. And once you know that, you had better be ready to be constantly marking stuff as "Ignore Formatting" (which is a real pain in the butt) and working around the oddness of the extra <br /> bits that get put in.
Using the "row markup" in solution two allows us to truly shut off the styling effects of the Styled Text page and use it as a convenient container for all the plugins we like.
And, with a great plugin for marking up source code we can fix the "one lined-ness" problem inherent to Styled Text pages.
Until I found this formula for working with Styled Text, I would always revert to HTML pages to make things look right. And why would anyone want to do that after buying something that promises you don't have to?
This page was last updated on Thu Sep 6 2007 at 18:56:50 EDT.