Radio UserLand Kick Start: Writing a Story

This is part of Chapter 2 of the book Radio UserLand Kick Start by Rogers Cadenhead, published by Sams Publishing

Writing a Story

Radio does not limit the length of a weblog entry, but there may be a limit to the patience of your readers.

Most webloggers compose short one- to five-paragraph entries and publish longer text elsewhere. This can be done in Radio by using the Stories section of your weblog, which is reached by clicking the Stories link atop any page of the desktop Web site.

Stories are saved as text files on your computer in a subfolder of the Radio UserLand/www/stories folder that corresponds to the story's creation date. For example, a story written on August 5, 2003, is saved in the stories/2003/08/05 folder.

Click the Create link to write a new story (Figure 2.5).

Figure 2.5.
Creating a new story.

A larger version of the entry editing box is used to draft stories. Internet Explorer users get the choice of WYSIWYG and source modes; others use a simpler, source-only box.

Every story must be given a title, which serves as its headline and the basis for its filename -- a story titled "Goto Considered Harmful" would be saved on your computer as gotoConsideredHarmful.txt.

A story is published by clicking the Create New Story button below the editing box. Radio publishes the story as a Web page with a design matching the rest of your weblog.

This Web page is upstreamed to the weblog, which you can check by viewing Radio's events log.

To make changes to a story, return to the Stories section of the desktop Web site, click the story's title to load the text, then click the Edit This Page button at the bottom of the story (Figure 2.6). The text is loaded into the story editing box. The Post Changes button at the bottom of the page republishes it.

Figure 2.6.
Making changes to a story.
(Enlarge)

To see all of the stories on a Radio weblog, add /stories to the end of its home page URL. The location of a story on the weblog corresponds to its location on the desktop site, with the exception that it's an .html file instead of a .txt file.

Tip: Radio will use the entire text of a title, sans spaces, in the filename. This can create some extremely cumbersome URLs for stories. To get around this problem, give the story a short name when creating it, then edit the story later to make the title longer.

Radio's browser-based text editor is much better suited to succinct weblog entries than it is to longer articles. Fortunately, any word processor or text editor can be used to write stories if it can save them as unformatted text.

To use an external text editor to create a story, you must know how to give a story a title and where to save the file.

Radio stories are simple text files that contain the full text of the story with HTML formatting. At the top of the file, before the beginning of the story, a #title directive should be inserted of the following form:

#title "title of the story"

Replace the text between the quotes with the actual title. For example:

#title "Harbottle Dorr"

Directives are commands that tell Radio what to do when rendering a file from one format to another. In this case, the text file will be rendered as an HTML document that's upstreamed to the Web.

Another useful directive for stories is #postTime, which has a timestamp for the last time it was updated:

#postTime "2/7/2003; 4:15:54 PM"

Listing 1.1 contains the text of a story.

Listing 1.1: The full text of harbottleDorr.txt.

1: #title "Harbottle Dorr"

2: #postTime "2/7/2003; 4:15:54 PM"

3:

4: HARBOTTLE DORR COLLECTION OF ANNOTATED MASSACHUSETTS NEWSPAPERS, 1765-1776

5:

6: On January 7, 1765, in the middle of the Stamp Act controversy, Boston

7: shopkeeper Harbottle Dorr took the current issue of the Boston Evening-Post and

8: commented on its contents in the margins. Every week thereafter, he collected

9: one or both of the Evening-Post or the Boston Gazette, (sometimes adding a

10: Boston Post-Boy & Advertiser) and continued expressing himself in the margins on

11: the events, referring backward and forward in a maze of cross-references to

12: other documents and stories relevant to the events reported in the news. 

13:

14: The final result 12 years later was an astonishing archive--3,280 pages of

15: annotated newspapers, plus the appended documents and Dorr's own indexes to the

16: four volumes he compiled. This entire unbroken run of annotated Boston

17: newspapers will not only allow students of American history a unique look at the

18: pre-Revolutionary era in New England, but will also provide insight into the

19: thinking of citizen Dorr on the controversies and topics of the times.

20:

21: FORMAT: 4 reels of 35mm microfilm

Directives must be placed at the top of a story with no blank lines above or between them. If an empty line were inserted between Lines 1-2 of Listing 1.1, Radio would include the literal text #postTime "2/7/2003; 4:15:54 PM" as the first line of the story.

A story will be published on your weblog if it is saved anywhere in the www/stories folder or one of its subfolders. However, it only shows up in the desktop Web site's stories section if you save the file in a subfolder of www/stories that corresponds to a year, month, or date.

Note: This example Web page describes the collection of Harbottle Dorr, an American from the Revolutionary War era who marked up newspapers with his own commentary and context-providing notes. He would've been a natural weblogger.

Figure 2.7 shows how the Harbottle Dorr page has been rendered on the Web. The graphics, formatting, and overall look of the page are not handled within the story's file -- all of that is accomplished through a collection of Web templates called a theme.

Figure 2.7.

Reading a story on the Web. (Enlarge)

Chapter 2:

Radio UserLand Kick Start home page