Scotts Radio :: FAQ
Last updated: 8/20/2002; 9:27:13 AM
 
The FuzzyBlog!

Marketing 101. Consulting 101. PHP Consulting. Random geeky stuff. I Blog Therefore I Am.

Scotts Radio :: FAQ

Scott's Radio UserLand FAQ

version 0.8

J. Scott Johnson, Edited by Gretchen Cahaly, Guy K. Haas
My Second Favorite Photo of All Time, Nahant, MA
 
 

IMPORTANT
This is a draft document.  Its a work in progress, it isn't complete.  I'm still working on it but it keeps getting longer and longer so I thought it was better to publish early and often rather than late.

Please send suggestions, comments and flames to sjohnson@fuzzygroup.com.  The Table of contents lists the intended content.  If an item on the Table of Contents isn't linked then its just not written yet.

 

If You are a Total Radio Beginner
This FAQ may not be quite right for you.  You might want to look at this document or this document instead before reading the FAQ.

YAF or YARUF

Yet another FAQ or Yet Another Radio UserLand Faq.  This document is a Frequently Asked Questions document about Radio UserLand, a weblogging application from UserLand Software.   

DISCLAIMER: This FAQ, while not Macintosh hostile, is written from the perspective of a Windows user and the examples reflect this.  Please direct the obligatory platform flames to sjohnson@fuzzygroup.com.  

Where ever you see this: , its a context sensitive link to that section of Radio's help system.  These links will only work if you have Radio installed on the computer where you are reading the faq.  In every product specific part of this faq, I try and link to that feature's help page.  These are usually at the beginning of the section. 

UPDATE: I didn't get as many of these in as I wanted since I wrote the Categories, Stories and Instant Outlining topics instead.  Soon…

Why?

I'm writing this because while there is a lot of information out there on Radio, I haven't seen what I think is a FAQ – a single comprehensive list of questions and answers in one place, on one page.  To me that's what a FAQ is.  Now, this may be a old fashioned notion of a FAQ, but I've been on the net a long time now.  And that's how we did it "back in the day".  This way you can print it out, read it in one piece and so on.

NOTE: This is a product level faq that tries to answer questions about the product itself.  For information on how to install it, how to buy it, etc., please see here. 

Table of Contents

The following topics are covered in this faq: 

Now, to the questions …

What is It?

Overview

At its core, Radio produces a regularly updated web page, a weblog.  Weblogs can cover any topic imaginable and do.  Take a look at www.weblogs.com for more.  

Who are you?  Why do you care?

I'm (currently) an out of work techie trying new stuff and, for me, writing is the best way to learn.  I like the product and I particularly like the attitude of UserLand – down to earth, practical, no lies.  Its how I used to run a company and it appeals to me.   Feel free to contact me at sjohnson@fuzzygroup.com.  Of course, if you're hiring, I'm available.  See my homepage for more.

The Two Faces of Radio

Its important to understand that Radio has two faces: 

  • Its a "Desktop Website", an application that runs on your desktop and is used through a web browser.
  • Its also a powerful development tool under the hood that runs as a native Windows or Mac application.  Probably 90% of people don't need this but for those that do, it looks like this: 

IMPORTANT: If anything that you see from UserLand references "the File menu" or "the Tools menu", it usually means that you need to use the tool in the picture above.  You might want to look at my first Radio essay for more details on this.  That dichotomy is what brought me into writing these missives. 

Russ Lipton's Two Faces of Radio essay really discusses this very well.  You should read it.

More Info

This is the section where I admit that you might not like my writing style or think that this isn't the right FAQ for you.  That's fine.  There are a bunch of other resources to look at.  Normally this goes at the end and people leave in disgust without ever seeing it.

Where are there more Radio resources?

Why don't you try the following: 

How do I find more information?  Can I search the Radio site?

From what I've seen and from what other Radio users have told me, finding information on Radio is just plain hard.  The web site is interesting in its organization.  To be honest, I haven't found the search engine on the Radio site to be all that helpful (disclaimer: I have high standards and I am a bona fide expert on searching).  For example, the tutorial above that I recommended was written by John Robb and Scoble.  When you enter those three terms (no and) into the search form at http://search.UserLand.com/, you get nothing.  Try it.

Here is what does work: Google.  If you add to your search the phrase Radio UserLand and then what you want to find, this really works quite well.

Try searching for Radio UserLand John Robb Scoble (the " " marks indicate a phrase to google); this basically constrains the search to things really about Radio.  Here is the search and the article I recommended floats to the top.  At least on April 1, 2002.

A better way to do this is to click here and enter your search at the top of my weblog in the Search Google box (top left).

The Very Basics

How do I get started?

After you download and install Radio, you go to your Programs menu (I'm on Windows) and run Radio.  This brings up a window like that below: 

How do I post?

You make a post to your weblog by typing text into the text entry field (shown above) and then clicking the Post to Weblog button.  This will post your entry to your weblog and also list it below the text entry field so that it can be selected for editing or deleting. 

How do I save without posting?

This requires changing Radio's configuration by altering the "Prefs" setting located on Radio's set of command links. The Post to Weblog button below the editing panel both saves your content locally and publishes it to your Radio server. This forces you to always go live in your weblog with things that
might not be ready. The solution is to set your Radio preferences to have both Post and Publish buttons. Follow this sequence:

  1. Choose the Prefs link at the top of the screen in the row of command links, the "menu".
  2. Under the Weblog grouping, click on the Three buttons or one option.
  3. UNCHECK the checkbox for one button.
  4. Click the Submit button.
  5. Click the Home link at the top left of the menu.

Now, you have the three buttons available on your editing page: Post to store only locally, Publish to store only to your Radio server, and the combination button to do both with one click.
 

How do I edit a post?

To edit a weblog post, scroll down on the main Radio home page until you see the post you want to edit and then click the Edit button to the right of it.  This will bring the text of the post up in the editing area so you can change it.

NOTE : If you find that when you click on the Edit button and the text does NOT appear, you probably need to shut down Radio and restart it.  I've seen this a few times although I don't know why.

How do I restart Radio?

Although Radio is mostly used through a web browser, there is a whole program underneath it, the Radio desktop web server.  If you find things are funny then you might need to restart it.    

Right click on the icon above and choose "Exit and Shut Down".  This shuts Radio down.  Now you need to choose the Radio UserLand option from the UserLand group in your Programs menu to start Radio again. 

How do I delete a post?

Once you've made a post to your weblog, it will be listed on the home page of the Radio application.  To delete a post, check off the box next to it and then scroll down to the Delete button and click it.  Please note that if you have a lot of posts, that can be a lot of scrolling but its there.

Where is my weblog stored? Do I have a copy?  What if it crashes?

By default your weblog is stored in 2 places.  Its both locally on your machine and its also on the radio.weblogs.com server.  When you downloaded Radio you were issued a "user number".  For example, mine is 0103807.  If you go to that user number at a special url, this is where your weblog is stored.  To get to my weblog, go to http://radio.weblogs.com/0103807/.  

Your weblog is also stored locally on your computer in the www subdirectory of the Radio UserLand subdirectory below Program Files. 

What's that wacky little orange XML () button for?

The XML button makes absolutely no sense until you understand the News feature in Radio and then its just plain brilliant.  You should probably read the News section below to really understand this.  I've repeated this question there with the full description.

What is the relationship between Radio and Manila?

Manila is an earlier product from UserLand.  Radio incorporates most if not all of its features (AFAIK).  

How can I revise an existing published entry?

Scroll down to the list of Recently Published entries and click the Edit button to its right.  This will bring it up in an editing panel where you can make changes.

You can use the Calendar to navigate back to an old post and then click on the Edit button next to the entry.  When you are editing a lot of posts (such as recategorizing them) then you may want to use the next approach. 

If you want to see all your posts on one page, go to the Prefs page and select the Previous Posts option.  Se the Number of Posts value to something large enough to see all posts on the home page and then go back to the home page.  If they all aren't there then just reload the page.  

How can I republish it as revised?

Copy and paste the revised entry to the clipboard.  Create a new weblog entry and paste it in.

Appearance

Overview

Radio has a very sophisticated "themes" tool that lets you change your look and feel by applying a new "theme" to your entire weblog.  Themes not only include look and feel but also functionality.  For example, the "Add Comment" feature found on many Radio weblogs is added to your weblog by a change to your overall theme.

A Warning About Themes!

Danger Will Robinson.  Danger.  This really isn't a big deal but you want to be aware of it.  The theme you use is a collection of overall templates that collectively define the look and feel of your weblog.  Templates can be individually edited.  For example, you might want your email address to appear at the bottom of your weblog.  Inserting a macro into your template for this can be done easily.  Here's the gotcha: When you apply a new theme, all changes to templates are lost.  Be careful here – I lost all my changes the first time I went from template to template. 

Just so you know, Radio warns you about this.  It tells you before it does it and gives you the chance to back out.  We're all so used to ignoring warnings that you can click right by it. 

Work Around #1: Create your own theme on the Themes page and then all your settings are at least saved somewhere that you can go back to.

Work Around #2: Here's how you avoid it: Whenever you make a change to your template then go to the program filesradio userlandwww directory and put all the files in that directory that begin with # into a zip file.  Get in the habit of doing it after each change and this shouldn't hit you.  It's not a big deal and I got my changes back in about 30 minutes but it can be a bit of a pain.

Work Around #3: Since I generally only change my Home Page and Item templates, I copy them to text files (or just Notepad windows) and then apply the new theme and then insert the modified HTML. 

How do I change my look and feel?

To change the look and feel of your weblog, you want to change its overall theme.  Follow these steps:

Click the Themes link on the command bar at the top of the screen

Select a theme to use by clicking on the radio button to its left.

Click Submit

Check your weblog to make sure that you like the appearance you chose.  If you don't like it then repeat this process to choose a different theme.

Where can I get more themes?

At present there are eight or nine themes built into Radio and more available online here.   A very talented designer, Bryan Bell, http://themes.weblogger.com, has made many, many themes for the earlier UserLand product Manila.  He told me recently that he was working on Radio themes and would have them soon. Check his site for more information.

How do I add a new theme to Radio?

Visit the site http://themes.UserLand.com and select a Radio theme.   This will cause your browser to ask if you want to save a file with the extension of .fftb to your system.  Choose Yes and it will be added to the themes directory of your Radio installation.  If you then go to the Themes link in Radio, it will be available to use.

NOTE: If you have customized your current template by adding commenting, sidebar links or such, you need to repeat those customizations.  I'd recommend saving them first before changing your template just to be safe.

How do I create my own themes?

This is a topic that I don't feel comfortable writing about yet.  I haven't been able to find a good link at UserLand either. 

Most weblogs have a set of links along the site of the screen (top, bottom, right or left) to give access to different resources, other sites and so on.  Radio calls these "Navigators".  There is really an excellent discussion of this located at the link below:

http://radio.UserLand.com/stories/storyReader$6923

The things that aren't discussed in the link above are:

Exactly where the #navigatorLinks.xml file is.  Its usually in C:Program FilesRadio UserLandwww or where ever you installed Radio.

You can edit this file with any text editor such as Notepad.  Just double clicking the file will bring it up in Internet Explorer which as far as I can tell is pretty much useless.  It is pretty though.  Right click it instead and choose Open With and then type in "notepad" to edit it easily and quickly.

Radio includes very powerful collaboration tools such as letting people comment on your postings.  These are standard with the product provided that your weblog is hosted at radio.weblogs.com/yourusernumber/.  They are not, however, turned on by default.  To do this you have modify your Template.  This isn't just changing your template with the look and feel stuff above.  Its actually getting down to how Radio works.  Its not hard but you might not be comfortable doing it.  Here are the steps:

Click on the Prefs link on the command bar at the top of the screen.

Click on Item Template.  Every post to your weblog is considered an item.

Paste the text <%commentLink%> into the edit after the <%editButton%>.  The <% %> indicates a "macro" to Radio, a way for it to programmatically do something – in this case insert a link to the comment function.

This places the link to the Comment tool on the left hand side of the screen below your post. 

Click Submit to save your change.

Check out your weblog to see if you like the change.  If not, revise it by adjusting the HTML or just take out the <%commentLink%> macro.

How are comments deleted?

At this time user added comments cannot be deleted.  More Details.

Common Problems and Support

With every product, now matter how visionary or wonderful, there are always problems.  Now that you have enough information to really start using Radio, this section tries to cover them.

How do I get support?

Support is available in several ways:

Can I send email to support@UserLand.com?

Apparently not.  I've sent a bunch of things to this address and never gotten a response.  I don't know that it disappears but I don't know that doesn't.

Why does my content disappear when I click a link in Radio?

I was typing content into Radio, clicked on the Help link to look up how to do something and then when I backed up to my editing box, the home page, my content was gone!  What gives?  When you come right down to it, working in Radio is pretty much like filling out a web form.  If you happen to click a link in a web form while filling it out, when you back up, its a pretty good bet that your content is going to have disappeared.  Your "work around" is one of the two things:

  • Remember to copy your content with CTRL+A and then CTRL+C before clicking a link.  This way you can paste it back into Radio when it disappears.  You could also paste it into Word as a "buffer" just in case
  • Configure Radio with the 3 Button Post option to give yourself the ability to save without publishing

Note: I say "work around" because its arguable if this is a bug but it can hit you in the head the first time you lost an article or story because of it.

Note: I say paste it into Word, not Write, because if you use Write, your formatting will change. Its a bug in Write, not Radio.

Why does my content disappear when I post?

I've seen this only a few times but I have seen it.  What happened to me was that I wrote a long article (this one), clicked Post and it disappeared.  Something seemed wrong so I immediately clicked on the "Home" link in the "Cloud" and saw that it wasn't there.  Luckily I had done the copy trick so I still had it available to me.  I tried a few times more and had to use Exit and Shutdown Radio before it would work for me once I restarted Radio.

Note: This was probably a fluke but losing data is really bad so I included it for users benefit.

How do I reset my default browser in Radio?

This is covered here:

http://radio.userland.com/discuss/msgReader$7818?mode=topic

But there are some clarifications that we can add.  This really requires resetting a value stored within "Radio.root" – the internal object database that stores all Radio configuration values and settings.  Radio does not use the default Windows settings (AFAIK) for the current browser.  It relies on its own settings.

To change the browser setting, you need to:

Go into Radio the environment, not Radio the browser tool.  Do this by choosing the Open Radio command off Radio's popup menu from the Radio icon in the task bar area (bottom right).

Open the Radio.root window. 

Scroll to the bottom and look for "webBrowser".

Expand this node by double clicking on the right facing triangle icon.

The last node should be "winDefaultBrowserApp".  Click in the middle pane, Value, and set it to the correct path to the browser.  Make sure to use two slashes for one i.e. c:\ not c:

Save Radio.root using the Save command on the File menu.

You will probably need to restart Radio for this to take effect.

This is illustrated below:

Setting the winDefaultBrowserApp Value

Radio running within Opera!

Particular thanks to Guy Haas for pushing the envelope on this and for supplying the screen captures.

NOTE : Depending on the browser that you choose, editing in Radio under Windows may not work correctly if you change your browser.  For example, Opera 5 and 6 do not work with the native Radio editing object.  If you find this affecting you then use the Prefs command to set that the JavaScript editor is used instead.

 

News

Overview

When I was first looking at Radio, I kept running into the "News" feature. It never made any sense to me and I just ignored it. Now that I do understand it, I'm kicking myself. First, you need to understand that there are really two different types of weblogs that people generally create with Radio: Pundit and Personal for a lack of better terms:

A Pundit weblog basically comments on existing news items.

A Personal weblog might do that as well but generally contains mostly original information.

The News feature is designed to make it very, very easy to make a Pundit weblog. It lets you subscribe to the type of news features that you generally like to read and then easily add them to your weblog along with your own commentary. 

What's that wacky little orange XML () button for?

Now that you understand what the News feature is, I can explain the XML button. The XML button lets you treat ANY Radio weblog as a source of "news". For example, lets say that you like Dave Winer's content on Scripting.com. If you wanted to comment on Dave's content, you could right click on the XML button and choose Copy Shortcut.  This will copy the URL for Dave's XML newsfeed.  You could then go to the News feature in Radio and "subscribe" to Dave's weblog by following the Subscribe link and pasting this url into the Subscribe field and clicking Add.

NOTE: You can also do this without the Right Click and Copy Shortcut by just clicking on the XML button and then copying the url from the address bar.  My way is shorter and faster so that's what I wrote about first.

Is News useful even if I'm writing a "Personal" weblog?

Yes it is.  What you can do with the News feature is use it to subscribe to different weblogs or news sources that you find interesting.  New postings to those items are then displayed on Radio's News page to make them easy to read, all in one place.  It essentially amounts to a "custom newspaper" feature.  My own News settings are shown below to illustrate this.

News items are only organized chronologically with the newest items at the top.  Radio regularly updates the News page without your having to tell it to.  As long as your computer has an Internet connection, your News page should always be up to date.

How do I use the News feature?

Once you have subscribed to a News source, you can add items from it right to your home page by just clicking the Post button to its right.  This will copy the text of the News item into your editing window so you can add your own commentary.  It also adds a hyperlink to the news posting but it does let you change it. 

How can my Weblog become a News feed?

Your weblog actually already is a news feed.  That's right.  Just as we talked about above, "What's that wacky…", any weblog built with Radio lets people subscribe to it – if the orange XML button (the wacky one) is there.  As long as you are displaying it on your weblog, and, yes, its on by default, people can have your weblog feed into their news page. 

Is News useful for my Intranet / Knowledge Management application?

Weblogs started as a public thing on the Internet but they are increasingly being used within the organization as well.  An internal weblog lets a "knowledge worker", someone whose output is primarily intellectual in nature, share his or her topical knowledge in an ongoing, chronological way.  Take a software engineer, for example, working on a project.  With a weblog, he or she could document their project regularly and make that knowledge available to anyone who can see the weblog.

Now, take that example and consider that your internal audience never has to bother visiting your weblog page unless they want to.  When your weblog is a news feed as well, people can subscribe to it and just have your updates appear on their news page.  If you are a manager with multiple engineers all weblogging then you have only one page to examine not one page per engineer.

News is one of those things that really is a paradigm shift.  If you couple it with categories (next section), its even more powerful.

NOTE : There is an even better approach than this for internal applications.  Its called Instant Outlining and Jon Udell is far more literate on it than I am.  Read his article.

How do I find more XML news feeds to subscribe to?

That's an excellent question.  There are really three ways:

Weblog Discovery

Directory

Site Discovery

With weblog discovery, you find an interesting weblog just by wandering over it.  You see the XML button, copy the shortcut and then paste it into your copy of Radio in the News page, using the Add button. 

With a directory of news feeds, you go to a central place that lists available news feeds and choose which one or ones you want from a list.  An excellent directory is www.syndic8.com.  This source has over 4,000 different news feeds available on any topic imaginable.  Another is www.newsisfree.com and seems to be of equally high caliber.

With site discovery, you are at a web site, just wandering around, and run into text something like this:

Get a newsfeed from NewsForge! You can now receive NewsForge on your My OSDN, My Netscape pages and through your own site via the RDF/RSS format. The following news streams, are available in Rich Site and modules are available for scripting languages such as Perl.
...
Original reports and linked NewsVacs
NewsVac RSS
NewsForge Reports RSS

If you just copied the two shortcuts above, you could paste those into your Radio News page and subscribe to them.

Can subscribing with the XML button be easier?

While the subscription process isn't hard (copy, go to News, paste, click Add), it can be a little tedious.  And there is a solution.  This is referred to as "The Mystery of the Coffee Cup".  Whenever you see this icon:

It means that you can click right on it and Radio will be smart enough to enter the url into the Url field of the Subscriptions page.  All you have to do is click Add.  No fuss, no muss.

How can my webpage become an XML news feed to syndic8 and other registries?

That's an excellent question.  I presume there is some kind of sign up I haven't figured that out yet myself.  If you do, please let me know.

Can I control the look and feel of my News page in Radio so I can sort it, search it and so on?

Not at present.  It could probably be developed as an application within Radio but it doesn't seem to be available yet.

Categories

Overview

The Categories feature in Radio is turned off by default so you may not even have encountered it yet.  What categories do is let you essentially "segment" your weblog into different types of content.  For example, you might write a weblog that mentions your work but also talks about your personal life.  You could assign each weblog post to one category or the other and then people that wanted to see only material in that category could do so.  Another way to think of categories is that they let you build multiple views of your weblog.

What else categories do?

Categories are really powerful and I don't have a full handle on them yet.  What they can do includes:

Format the content differently i.e. each category can have its own theme

Let people subscribe to different chunks of your weblog, not just the whole thing

Be created in HTML as well as RSS formats.  This means that your category can be a separate little "mini weblog" of its own if you have the disc space.

What categories come with Radio?

Radio has builtin categories for:

Home Page – By default everything is tagged for the home page.  You can turn it off if you want to but normally the home page includes everything.

My Hobbies – Posts about your hobbies.

My Organization – Posts about your work.

My Friends – Personal posts.

My Interests – Posts about your interests.

My Profession – Posts about what you do instead of where you do it.

Can something go in multiple categories?

Yes.  Any item can go in one or more categories.

How do I turn on categories?

Do this to make categories available to you:

Click on Prefs.

Under the Weblog grouping, click on Categories

Turn on the checkbox for categories.

Click Submit

Click on the Home link.

At the bottom of the editing area, above the Post to Weblog button, you will now see six checkboxes which when selected assign something to one or more categories.

How do I create a category?

To create a new category:

Click on Prefs.

Under the Weblog grouping, click on Categories

Click on the New Category page.

Fill out the form.  Other than the name of the category, you probably want to select that the Default theme be applied to the category and, ideally, you'd select the language.

Click Submit to create the category.

Click Home to return to the home page.  You should see a new category at the bottom of the screen.

How do I delete a category?

I haven't done this myself yet so I am going to defer to the experts here for more details on deleting.

How do I assign a page to a category?

Before you post your webpage, check off which category or categories it belongs in and then click Post.

Adding Interactivity, Commenting and Such

Overview

When your weblog is hosted at http://radio.weblogs.com/, Radio has very powerful interactive features such as supporting discussions and comments within the context of your weblog.  You should also note that you can use third party interactivity tools since your weblog is really just a plain old webpage.  Any of the interactivity tools you use on the web can be used with Radio.

This is covered earlier here.

How do I add commenting when my weblog is on my own server?

When your weblog is on your own server, you can't make use of the interactivity features found at radio.weblogs.com.  What you can do is use the Radio Community Server.

What's the Radio Community Server (RCS)?

The Radio Community Server is a piece of groupware software available for UserLand which makes all of the community and interactivity features found at UserLand available behind your firewall.  More information is here.  Expanded documentation is here.

Adding to Your Weblog by Email

Overview

Editor's Note: If this section doesn't make sense to you as it is written (i.e. it requires understanding what POP is, etc) then, perhaps, you shouldn't use this feature.  I'm not being snide but pointing out that this is an advanced, power user feature. 

At work I can't FTP out of our firewall, so I can't put content for Radio on my weblog. I run Radio on my Home PC and I have tried several ways to get access to it, including a virtual desktop using GoToMyPC, which works well, gives you a full interactive look at your PC but costs about $20 a month. If you're the play-with-your-home-firewall type, you might also try VNC (http://www.uk.research.att.com/vnc/).  But if you're looking for a quick and easy solution, the Mail-to-Weblog feature is well thought-out.

A few steps to take BEFORE you configure this option. You need a POP Mail account that you can dedicate to the Mail-to-Weblog feature, since Radio retrieves and deletes any messages in the account it monitors. Many ISPs allow you to have multiple accounts, so make sure to create a new one for Radio. You could call it "blogmail" and the address would be "blogmail@yourserver.com". Some of the free hosting services have this feature. Yahoo used to allow free access, but now gives you to access POP mail for $20 a year. This page shows you how to do it if you are a Yahoo user.

Once your mail account is set up, you're ready to use Mail-to-Weblog.

In the Prefs screen, go to the item under the Weblog heading called "Mail-to-Weblog." On a standard Radio install, this link should work http://127.0.0.1:5335/system/pages/prefs?page=2.9 .

work http://127.0.0.1:5335/system/pages/prefs?page=2.9 .

Check the checkbox to enable the feature.

Pick a secret subject that you will remember. You put this in the subject line of your email so Radio knows to treat the mail as a weblog post. Then type in the address you set up, and fill in your password twice. Don't forget to hit "Submit" to save your changes to the page.

Then, send a test message to yourself.

A Recommendation

Until you are comfortable with this feature, I'd check your blog carefully to make sure that what ends up in it is what you expect and that the formatting is what you want. 

Credits

This FAQ entry was largely written by Howard Greenstein (I wrote the recommendation and Editor's note – he did all the real work).  His weblog is www.howardgreenstein.com/blog and his email is public@howardgreenstein.com.

Instant Outlining

Overview

Instant Outlining or IO is the latest new Radio feature.  Its cool.  Its powerful.  I don't 100% understand it yet.  I can answer questions enough to write this but I'm still trying to understand how it changes things.  I do think that it really represents a fundamental shift, a new paradigm.  Ok.  So what is it?  Instant Outlining lets individuals within or across organizations share outlines.  Its done in real time over the Internet.  Think of Instant Messaging where what you're sharing is real knowledge, not just short conversations.  From one window, you have access to someone else's thinking.  That's powerful.  Its actually profound if you think about it.

Confused?  I was too.  You really should read Jon Udell's article on IO.  He describes it better than I can.

Here are some other references:

A Warning

You should know that this feature is still in beta.  Its been officially released and the UserLand developers have been working with it for a while but it is "flying without a net".  Bear that in mind.  Here are the beta notes.

What's an Outline?

An outline is a hierarchical structure of information.  Think of a book.  The book has chapters.  The chapters have sections.  The structure of that information could be shown as:

  • Book
    • Chapter
      • Section

That's an outline.  Very simple but very powerful.

What's an Instant Outline look like?

An Instant Outline is shown below.  At the top is some information of mine.  Below that appear outlines for any of my "buddies" i.e. outlines to which I subscribe.  From one place, I can see if they are online or offline and what they're working on.

What's OPML?

With Radio you've probably seen the term XML or seen what I call "the wacky XML button".  Just as XML is a way to represent information, so is OPML.  The difference is that OPML is designed to represent outlines.  Think of OPML as HTML for outlines.  You really don't need to worry about it.

What's this wacky OPML coffee mug?

Now that Instant Outlining has been officially released, you are going to see a profusion of this icon: Click on the coffee mug to add Dave Winer's Instant Outline to your Radio UserLand buddy list.

This icon indicates that you can subscribe to this user's outline if you want to.

Why do I want to subscribe to a user's outline?

Well, for the same reason that you might subscribe to that user's weblog.  You want to know what they're thinking, what they're doing.

Why do I care?  What's an example?

The best example right now is from the team that developed it – UserLand. Apparently what they are finding is that the outline cuts down on email – its really a communications tool but of a higher order.  Here's the quote from Jon's article:

"Winer and his team don't email one another any more, and they claim radical productivity gains as a result of the switch to instant outlining:"

We've been using this tool since November, internally at UserLand. We shipped Radio 8 with it. When we switched over our workgroup productivity soared. All of a sudden people could narrate their work. Watch Jake as he reports his progress on the next project he does. We've gotten very formal about how we use it. I can't imagine an engineering project without this tool.

Depending on your type of work environment, this could be extremely useful.  Certainly in a software development context it would and I can easily see it for other applications as well.

How do I get to the outliner?

For most users, they only have seen Radio as the web based tool where they create weblogs.  There is a whole different side to Radio – its also an application that you run on your desktop.  The first step in using Instant Outlining is to launch that application.

  1. Right click on the Radio icon in the control panel area on your Windows taskbar.  This is shown below.

  1. From the Radio menu that pops up, choose the Open Radio command.  Again, this is shown below:

This is going to launch the full blown Radio environment.  What you should see is something like this:

This is the full Radio environment.  To get to the Outliner, you need to select it from the Radio menu.

How do I create an outline?

To make an outline, select the Outliner command from the Radio menu.  Next, select My Outline.  This will create an Outline window where you can enter text and move it around in outline fashion.  Here are the quick keys to use:

  • Enter – create a new level in the outline
  • Tab – move an outline entry in a level
  • Shift Tab – move an outline entry out a level

What's my "buddy list"?

Your buddy list is the list of people whose outlines you subscribe to.

How does Radio know who's online or offline?

Excellent question.  At this point its unclear.  There doesn't seem to be an I'm Away feature as in an Instant Messenger tool.  So I would guess that they monitor keystrokes and when you are inactive for a while, they make you "offline".

Is this tied to my Instant Messenger's buddy list?

At this point, as far as I can determine, its not. 

How do I give someone the url to my Instant Outline?

Your Instant Outline url is going to be something like this:

http://radio.weblogs.com/0103807/instantOutliner/filename.opml

For example, for my Instant Outline that organizes the UserLand website, go to:

http://radio.weblogs.com/0103807/instantOutliner/theFuzzystuff.opml

Can I see all of a user's Instant Outlines?

Yes.  Just go to the instantOutliner subdirectory off their Radio url.  For example:

http://radio.weblogs.com/0103807/instantOutliner/

Shows you all my Instant Outlines.

What's "Subscribe to Outline"?

This is the command for subscribing to someone's outline.  It pops open a dialog box where you can paste the url to that user's outline.  After you do so then you are subscribed to the outline and will have it in your Buddy List.

Is there a place like www.weblogs.com where I can subscribe to outlines?

Yes.  Go to http://www.weblogs.com/io.html. 

What are my outline Preferences?

Outliner Preferences set several options:

  • How often to poll – in other words, how often does Radio update the instant outlines that you've subscribed to
  • Play sounds – make a noise when new outlines arrive
  • Public folder – a folder of your weblog where your outline is saved

NOTE: When you click on Preferences, it opens a Radio window in your web browser to set the preferences.  It is easy to not realize that this is happening and think that Preferences is broken.  Trust me, it isn't.  Look for the blinking window in your task bar (blinking means that it wants your attention).

If you can't get to your Outliner Preferences right from your Instant Buddy window then this may be helpful:
http://127.0.0.1:5335/system/pages/outlinerPrefs?page=1

What can I do with an Outline I created?

Outlines are actually great tools for working with information.  Its a fast way to write and easy to boot.  Once you create an outline in Radio, you can export it as text or HTML.  Look at the Save commands on Radio's File menu.

How Do I Delete an Outline I Subscribed To?

Today this is a manual process by hacking into weblogdata.root.  See Radio Exposed for more.

 

What tools does Radio have for working with outlines?

Um.  Most of them?  The UserLand crew basically invented outlining in its modern form.  Here's the Radio Outline menu:

Where can I learn more?

Read the articles cited above and keep and eye on www.scripting.com.  I'm sure that more will be written about Instant Outlining.

Stories

Overview

The Stories feature is designed to make it easy to create longer works than simple postings to your weblog.  Its designed for, well, stories.  Think of essays and then it makes a bit more sense.  Most of what you know about Radio is applicable to Stories.

   

How do I create a story? 

To create a story, click on the Stories link in the top command bar of links in Radio.  What you see is a screen which lists all stories that you have created.  Click the Create link to start creating a story.  What you'll see is now a larger version of the Radio edit box for you to create your story. 

What's the difference between a story and a weblog post?

Weblog posts are normally short, to the point and pretty informal.  More stream of consciousness to some degree.  A story is a more polished work that's longer and really intended for a permanent archive.  Radio also automatically builds an index page linking to all your stories just as it does for all your weblog posts.  Generally you first create a story and then create a weblog entry linking to it.

How do I create a table of contents to my stories?

You don't have to.  Radio automatically builds this for you.

Macros

Overview

Deep within the Radio product is actually a featured scripting or programming language. Its not needed for most of what you do with Radio, i.e. simple weblogs, but it is there if you need it.  Programs written in the Radio language are referred to as a "Macro".  Macros are generally (and I think always) embedded within your template to give your weblog new features.  A sample macro is shown below: 

<%radio.macros.recentTitledBlogPosts (maxTitleLength:50)%> 

If you notice, you don't see the lines of programming that make up the macro itself.  What you see instead is the name of the macro.  You will also see one or more "parameters" or options for the macro.  In the example above, the "maxTitleLength" is the parameter.

What a macro does for you is insert information into your template that the macro produces.  If you put the macro above into your template, it will provide a list of recent weblog posts.  Think of it as a table of contents for your weblog. 

What's Frontier?  What's DocServer?

Frontier is an earlier product from UserLand.  It was a scripting environment for the Macintosh.  Somewhere along the line, UserLand took that some technology and rolled it into other products including, now, Radio.  Old software never dies, it just matures and gets renamed.

Given that the language is the same, UserLand seems to have decided to document it all in the context of Frontier rather than Radio or something like "USL: UserLand Scripting Language".

DocServer seems to just be the name of the website where stuff is documented i.e. http://docserver.UserLand.com/.

What's all this Mac stuff?

Frontier was originally a Macintosh product and the macro documentation reflects that.  The product seems to be fully cross platform so, except for things that are very Mac specific (BBEdit???), you should be fine with using it on a PC.

What standard macros are there?

TBD.

How do I add new macros to the system?

TBD.

Why don't my new macros show up?

This has happened to me as well.  When you "Update Radio.root", new macros are downloaded into your system.  Unfortunately, these aren't displayed on the Built-in Macros page.  I don't know how to get a list of every macro in Radio but I suspect there is a way.

How do I write my own macros?

TBD.

How do I jump to a specific script within the Radio development environment?

Press CTRL+J and type in the name of the script.

How do I run my own script within the Radio development environment?

Use the Quick Script command which is available with Ctrl-; (or if you're on a Mac, use Cmd-; instead).

A good cross reference is here.

Where is the full documentation for macros?

Take a look at: http://docserver.UserLand.com/.  This documents all the "verbs" in the language.

Where can I learn more?

Take a look at the below links: 

http://radio.UserLand.com/recentTitledBlogPosts 

Going Crazy with Macros

http://docserver.UserLand.com/

Advanced Stuff

Overview

Radio is a sophisticated product but even advanced stuff isn't all that hard.  A lot of it is just taking advantage of the fact that what Radio produces is just a web page and all the standard tricks that you know for web pages are applicable to Radio.

How do I make my weblog automatically update the user's screen every few minutes? 

This is also known as the "I want to be just like Dave feature".  If you have ever read the www.scripting.com weblog, you may have noticed that if you leave it open on your desktop, periodically there will be new content.  This is actually a simple HTML trick, not a sophisticated Radio thing.  What you need to do is take the HTML below and insert it into the Template for your home page.

<meta http-equiv="refresh" content="6000; url=/">

Here are the steps in your copy of Radio:

Click on the Prefs link in the command bar at the top of the screen

Scroll down to Templates

Select Home page template

In the editing box, put your cursor after the first <HEAD> tag

Press ENTER to add a blank line.

Add this line by pasting it in.

Click Submit

Visit your page on radio.weblogs.com (or your own server) and verify that its in the page by Viewing the Source.

How do I make my weblog searchable?

You'd be surprised how quickly content on your weblog adds up.  A post here, a post there and pretty soon you have lots of posts.  Now you need a search engine.  Or so I think.  A lot of webloggers would disagree.  They're wrong. 

Any of the different free web search engines can make your weblog searchable.  I chose www.atomz.com since I think they are really great.  Sign up for Atomz (its free) and they'll end up giving you html like that shown below (don't use this since its for my site, not yours!):

<!– Atomz Search HTML for FuzzyStuff Weblog –>
<CENTER>
<form method="get" action="http://search.atomz.com/search/">
<B>Search:</B> <input size=15 name="sp-q"><input type=submit value=Search>
<input type=hidden name="sp-a" value="sp1001f48f">
<input type=hidden name="sp-f" value="iso-8859-1">
</CENTER></form>

You can add this to your home page in the same way that we added the refresh tag above only we need to put it in a different place.  Here are the steps:

Click on the Prefs link in the command bar at the top of the screen

Scroll down to Templates

Select Home page template

In the editing box, scroll down to where you want it.

NOTE: This does require at least a basic understanding of HTML.  To make it easy, lets assume that you want it at the top of the page.
 

To figure out where the top of the page is, you have to find it among all the HTML tags.  What you are looking for is: <%bodytext%> .  This is a Radio macro which tells Radio where the text of your web log posting should be inserted.  If you are using Internet Explorer then you can press CTRL+F and search for it.  If not, you'll have to scroll down and look for it.

Paste in the search form you got from Atomz in at this spot and click the Submit button.

Check out your weblog on radio.weblogs.com (or your own server) to see if the search box is ok.  You may need to go back and forth playing with the HTML to get it looking just right.  That's normal.

The Radio Community Server

Overview

This product is sophisticated enough to warrant a more detailed description.  Check out the document: Radio Community Server Step by Step.

Where do I download it?

http://rcs.userland.com/download

Where's the FAQ for RCS?

Take a look here: http://rcs.userland.com/frequentlyAskedQuestions

Installation

Download it from the url above.  When you have to save the file, select that you want to save it into the program filesradio userlandtools directory. 

How do I set the port where Radio runs?

In installing RCS, you may well have to modify the port where the Radio application runs.  This is done as follows:

  1. Go into the main Radio environment (Right click on the Radio icon in your lower right task bar area and then choose Open Radio).
  2. Select From the Radio menu "Web Server".
  3. Select from this menu "Set Port".  Enter the port that you want to use.

Common ports that you might want to use are: 80 (the default port for web servers, you can only use this if there ISN'T a web server on the machine already or if its not running on port 80), 5335 (Radio's default port when 80 is used) and 8080 (Radio's second default port).

NOTE – If you need to do this then you may also need to disable a port.  Here's a quote: "In the radioStartupCommands.txt in the Radio UserLand folder, you can add this command to disable port 5335:
user.inetd.config.http2.startup = false;" Read Original.

Understanding the Full Peer Concept

This is interesting.  Take a look here: http://www.userland.com/whatIsAFullPeer

Glossary

Like any rich, powerful application, Radio has its own "language".  Here's my first cut at a translation.  Please send feedback to sjohnson@fuzzygroup.com with problems and missing terms.

Term Definition

Blog

 The same as weblog. See below. The two terms are used interchangeably.

Blogger

 One who blogs of course. Seriously a person who writes a weblog.

Category

 

 Categories segment your weblog into different "chunks" or "views" that people can subscribe to individually (i.e. they just see a part of, not the whole weblog).

Cloud

 

 		 The somewhat abstract area out on the Internet where all your information is stored and where the server that physically stores your information is considered to really exist.  The home page for your weblog is generally considered to exist in the "cloud".

Desktop Website

 A personal website that runs right on your desktop. Radio is an application that is itself a desktop website.

Directive

 

 A higher level of control over your HTML output than a macro. A directive seems to determine which macros are executed within your template. I recommend that you see this: http://drmatt.userland.com/webAdvancedStuff/pageheader.html for details.

Enclosure

Unclear to be honest. It seems to be a term that represents information carried along with a weblog. I believe that if you think "attachment", you're not far wrong.

Item

A single discrete unit of information on your weblog. Think of it as one entry or one post (see below).

Macro

 

 		 A small programming subroutine in Radio. The term "macro" really means two things to Radio. Most typically, it refers to a marker embedded in your template. This marker represents what Radio should do when it finds that marker. For example, the <%title%> is the invocation of the macro.  This tells Radio to insert the title of the page at that location. The second thing that Macro can mean is a subroutine written in Radio's underlying UserTalk scripting language. You don't see this all that often so really think of Macros as markers in your HTML template.

Post

Post has two meanings. If used as "Today's Post mentioned ..." then it generally refers to a single entry on a weblog. If used as "I need to post this today..." then it means the process of publishing an entry to your weblog.

Depending on how Radio is configured (see Preferences), this can mean one of two things.  In the first case, Post means "Save my weblog entry and publish it on the Internet".  This is Radio's default setting.  In the second case, Post means "Save this to Radio's internal database but don't publish it".

RSS

 A software protocol for different applications or websites to accept regular streams of data, originally news headlines, now weblog entries.

Template

 

 		 Each element in your weblog, such as an individual posting, is formatted according to rules defined by a template. You can modify your templates to give you full control over the look and feel of different parts of your weblog. Think of a template as a small part of a theme (below).

Themes

 

 		 A collection of different user interface elements that combine to give your overall weblog a professional, polished appearance. Themes can include background images, tables, the calendar to choose between dates macros and more. Themes control all the presentation aspects of your weblog including every single entry.  With themes, you can revise your weblog's look and feel with just one command.

Upstreaming

 

 		 The process by which Radio takes your content and sends it out to its destination, either on your own server or on the radio.weblogs.com server. This can be done by Radio's native protocols and by FTP which lets your Radio site work with, well, essentially every single hosting service in the world.

Weblog

 A regularly updated webpage that functions almost like a stream of consciousness to the outside world.

XML

 

 		 A way to "tag" data. Think of it as a "meta file-format". When you think of Microsoft Word, you probably know that it creates files with the extension .DOC. DOC is Word's file format. Now think of a file format that let you create file formats for other programs. Confused? Perhaps you should be, but that's what XML lets you do -- create file formats for data. Typically XML is used to interchange information within or between applications. For example, Radio uses XML to tag navigator links for the sidebar. This lets another part of Radio work on those tagged links such as formatting them when they are displayed.

NOTE: I have grossly oversimplified many discrete issues here.  I know this.  Please send flames to /dev/null

XML-RPC

 

 		 (Oversimplified) A software protocol for programs on one computer to call parts of programs on another computer. For more information, see here: http://davenet.userland.com/2002/04/04/fourYearsOfXmlrpc . XML-RPC is notable for many reasons, not the least of which is that it was created by UserLand and Microsoft (and driven mostly by UserLand). Its a simple, concise, easy-to-develop-for mechanism.

Credits

I'd like to thank several people for making this FAQ possible:

Dave Winer for making a product good enough for third parties to write documentation for free

Russ Lipton whose Radio Tutorials taught me a lot

Guy Haas, Software Exegete in Silicon Valley who helped a lot

Howard Greenstein and Bob Stepno who confirmed the need for this and helped with the questions

The makers of WinAmp, Diet Coke, Dunkin Donuts and Krispy Kreme

Special thanks to Guy Haas who edited large parts of this, without request, fixing several egregious errors that I made.  Any errors in this document are, of course, my own and I take full responsibility for them.  Punishment by lashes with a wet noodle or flaming emails happily accepted.

Distribution of this FAQ

Can I distribute this?

Yes.  Please feel free to distribute this or link to it provided that it is complete (including what's just below) and that the copyright notice is intact.  Thanks.

Copyright (c) 2002, J. Scott Johnson. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections being, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled " Appendix 1 - Terms of Use ". Note: I'm new to writing a Free Documentation statement and the above might not be perfect. 

comment []

 
Copyright 2002 © The FuzzyStuff