The HowTo Tool is used to write HowTos -- documents that show people how to use things.
Getting started
You can download howTo.root from the Tool Catalog page in the OPML Editor (it's in the Misc menu). If you haven't updated recently you might not see it. To update, choose Update opml.root in the File menu.
Before doing anything else, you must have an Identi.ca account (they're free) and you must set up the Identi.ca prefs (click here with the OPML Editor launched on your system). We use Identi.ca for authentication.
Creating a new document
To create a new document, choose Open document command from the HowTo sub-menu of the Tools menu. A dialog appears asking for the path to your document. Enter a path, something like: helloWorld.opml. Its name must end with .opml. The tool sends a message to the server asking for the contents of this file, but since it doesn't exist (it's new) it returns an empty document, which then opens in a window.
Enter a title in the first headline, indent and write the body of the HowTo in an outline.
You may indent as many levels as you like, but the text will scrunch up if you get too deep, so don't.
You can also start a new top-level headline, which will appear bold with a blue arrow next to it that's a permalink.
Save periodically, either by clicking on the Save button in the window, or choosing the Save command in the File menu. When you Save two things happen:
1. The document is rendered in HTML and
2. Both the HTML and the OPML are sent to the server, where they are stored.
You can see what the HTML looks like by clicking on View. That also shows you the URL that your HowTo is stored at.
More facts
Paths can contain slashes, like this: /cars/domestic/buick.opml.
There's an Upload image command in the HowTo sub-menu of the Tools menu. You can upload images up to 256K in size, GIFs, JPEGs, PNGs.
The rendering happens on your machine, and you have full control over the appearance of your docs. A Google search reveals a lot of docs written over the years describing the website framework in the OPML Editor.
The HTML menu in the OPML Editor provides a lot of useful commands for editing HTML in the editor. Of course your can use markup in your HowTos. The last command in the menu Format Text is very important, it allows you to see the raw HTML markup for links and style. I'd go mad without it.
I published this tool cause I needed to write HowTos for the OPML Editor. If you want to write some howtos as well, esp for OPML Editor users, please do.
I used the Identi.ca system for identity because I was tired of writing and maintaining identity systems, and they did such a nice job and I like what they're doing, so I wanted to support it. I asked if it was okay first, and Evan said it was. Thanks!
There's a place to add comments at the bottom of each HowTo. We use the excellent Disqus web service for this. It's so easy and elegant.
The Tool is updated every night at 3AM along with opml.root. You can turn these updates off if you would rather not get them.
I'd like to add more features, including a directory of HowTos, and a way to find the paths to all the HowTos you've written and a reverse-chronologic list of updates to HowTos.
Update 8/12/08 -- Implemented a command that lists all your HowTos.
Yes, you guessed it, this was written with the HowTo Tool! :-)
OPML subscription list editing
New section: 11/22/08.
A friend needs an easy way to edit and maintain an OPML subscription list that's accessible over the net. You can use the HowTo Tool for that purpose. Here's how.
1. Install HowTo.root per the instructions above.
2. Open a document named mySubscriptions.opml, following the instructions above.
3. Enter each subscription as a top-level headline as follows. Press Return to create a new empty headline. Right-click. Choose Add Feed from the pop-up menu. Enter the URL of the feed and click OK. If it was able to read the feed, its title will appear in the headline. Repeat for each subscription. Screen shot:
4. When you're done, click the Save button in the window's toolbar and then click the View button to open the HTML rendering in the browser.
5. Edit the URL in the browser, replacing the html at the end with opml and press Return. You should see the OPML source of the subscription list. Example. Copy the URL and send it to whoever you need to send it to.
6. When you need to make a change, re-open mySubscriptions.opml, make the change and Save.
