markup

Via yesterday's Vimcasts episode, "Converting markdown to structured HTML with a macro", check out this most-excellent Vim plugin:

Surround.vim: Delete/change/add parentheses/quotes/XML-tags/much more with ease

Surround.vim is all about "surroundings": parentheses, brackets, quotes, XML tags, and more. The plugin provides mappings to easily delete, change and add such surroundings in pairs. While it works under Vim 6, much of the functionality requires Vim 7.

Anybody editing HTML or other markup can definitely use this.

From Fletcher Penny: "Using MultiMarkdown with Scrivener"

This document assumes a basic familiarity with Scrivener, and with MultiMarkdown. It is designed to help you combine the two programs into a system to help you with the writing process, as well as the printing and publishing process.

It will guide you through the process of setting up a document that will be compatible with exporting to MultiMarkdown.

I've been taking a look at Scrivener again of late -- I waver back and forth about using it for my next book, but I'm leaning toward it at the moment.

(In case you don't know, Fletcher is the one who expanded on John Gruber's Markdown by creating the spiffy MultiMarkdown. Thanks Fletcher!)

"Anyone who slaps a 'this page is best viewed with Browser X' label on a Web page appears to be yearning for the bad old days, before the Web, when you had very little chance of reading a document written on another computer, another word processor, or another network."

-- Tim Berners-Lee

There's a known issue with the atom.module for Drupal, which creates an Atom syndication feed to accompanying the built-in RSS feed -- the issue is that if you're also using the Markdown or Textile modules, atom.module doesn't convert the markup to proper HTML, instead showing the Markdown or Textile as is. Like I said, this is a known issue.

After a bit of investigation, I've come up with a temporary solution to the problem, at least for Markdown format. (I don't have Textile installed, so someone else will have to confirm; given the nature of the fix, I imagine it would work.)

If you check out the raw XML atom.module makes, it is creating a proper Atom file with "summary" and "content" fields. The module fills these in with the contents of the Drupal "teaser" and "body" fields respectively for each node. So far so good.

Strangely, the "teaser" field is getting formatted correctly -- in other words, the Markdown markup is being converted to regular HTML, as it should be (and as it is on the regular webpage). But the "body" atom.module is using for the Atom "content" content in is the raw Markdown, sans conversion.

Spending a bit of time familiarizing myself with the system, I've not tracked down the exact problem (though I suspect it might be an issue with the node_invoke_nodeapi usage here), but my temporary fix is to simply replace the line (line 179 in my copy of atom.module) that reads

$output .= check_markup($item->body);

with this:

$output .= check_markup($item->teaser);

All this does is use the same command as on line 173 just above, which calls the properly formatted teaser.

This is not a permanent solution by any means, and is also at the whims of whether or not you use teasers and/or excerpts, but it takes care of things for me until the real fix is in.

UPDATE

After some more experimentation, I've discovered the following:

1. atom.module apparently uses the default Input Format to display the body version of the story.
2. If that Input Format is not Markdown-capable, the story will not display properly.
3. If it is Markdown-capable, but certain HTML tags are forbidden, it will not display those.

Another temporary solution

Although this temporary solution isn't for everybody, if you allow Markdown in your default Input Format, and include appropriate HTML formatting+filtering, you will take care of the problem for now.

I have been leaning toward using Textile in the new version of the site and in general writing. As you can read in the Markup article, the initial lean was inspired by Textile's method of indicating emphasis: _emphasis_ and *strong emphasis* versus Markdown's *emphasis* and **strong emphasis**. The former seemed more natural at the time.

While casting about for Textile tools, it seems as if -- at least on the Python side of things -- development hasn't been particularly rampant lately. That combined with Merlin's recent endorsing of Markdown prompted me to revisit John Gruber's markup effort.

I first read up on some of John's methodology and liked his email "foundation":

In fact, I love writing email. Email is my favorite writing medium. I've sent over 16,000 emails in the last five years. The conventions of plain text email allow me to express myself clearly and precisely, without ever getting in my way.

Then I re-read this post of his, answering a query about the underscore/asterisk issue: asterisks as bold or italic?. This bit struck a chord with me:

...if you stop thinking about "italics" and "bold", and think instead of "emphasis" and "strong emphasis", I think it"s very fair to say that this and this both imply normal emphasis.

Fair enough. The rest of the syntax seems good, as well (though I do think I prefer Textile's header handling).

There's a bundled Perl-based conversion engine that I could use on the CLI, something I've not been able to track down for Textile. And there's the 3rd-party PHP Markdown.

Markdown is also supported in various blogging platforms, not to mention Drupal, VoodooPad, TextMate, etc.

Note: while I'm no longer using special icons to indicate external links on the site, this is still a useful tip.

Another "text instead of image" trick like RSS in CSS is the small arrow icon you see next to external links. Some sites do that with small images. While checking out Wikki Wakka, I noticed theirs were actually text, rendering an HTML entity code of an infinity symbol -- ∞ -- which in the raw HTML is ∞

Splendid idea, I thought, but I didn't want to do the same exact thing they had.

Enter the Web Design Group's (WDG) HTML entities reference page, where you can find all sorts of neat letters and symbols, including the ⇒ "rightwards double arrow" or ⇒

And then Notanda, during its processing of my saved plaintext file entries, automatically adds that code at the end of external links.

On the previous version of this site, I had a couple of badges of the ubiquitous RSS/XML variety:

What's different about them versus the run of the mill versions were that they were just text, not images like most versions. It's all done in CSS. Here's how.

For a given badge, enclose the text you want to appear in a paragraph block and make it a link. Give the paragraph a suitable class name. I used "feeds" for mine. Viz:

<p class="feeds"><a href="http://www.celsius1414.com/index.xml">RSS 2.0</a></p>

Then in your CSS file, use something along these lines:

.feeds a {
     background: orange;
     color: white;
     padding: 2px;
     border: outset thin;
     font-style: normal;
     font-weight: bolder;
     text-decoration: none;
}

Which will produce something like what you see in the picture. A simple trick, but useful for all sorts of things.

Check out External Link Icon for a related tip.