Outline Processor Markup Language

Home

Spec

Directory

Validator

Editor

Members Join Now Login

Notes on feedback and changes for August 2007

Changes 

Changes to the OPML 2.0 draft spec.

1. Changed the date at the head to 8/28/07.

2. Removed the note from the author.

3. Added two examples of the category attribute, one with a single category, another with two.

4. Added Note #9 to the Notes section, explaining how to use OPML 2.0 elements in XML documents that are not OPML. Please read this carefully and let me know if it makes sense to you.

5. Created an example file that illustrates OPML elements embedded in an RSS 2.0 document.

6. In Note #1, added the following: "with the exception that the year may be expressed with two characters or four characters (four preferred)." I took the text straight from the RSS 2.0 spec.

Don Hopkins' comments 

Don Hopkins asks: "What does flatdown mean?" and asks for clarification of the expansionState element.

flatdown

First, flatdown, in UserLand's outliner terminology, is a direction. The complete list of directions is: up, down, left, right, flatup, flatdown and nodirection. They are used as parameters to the op.xxx verbs which take a direction as a parameter.

The first four are structured directions. Going up from an outline element takes you to its previous sibling, down takes you to the next sibling. Left takes you to the parent, right takes you to the first child.

The flat directions, flatup and flatdown view the outline as a linear sequence, not structured. Imagine the outline displayed on a screen. To go flatup you'd go to the outline element displayed immediately before, to go flatdown you'd go to the outline element displayed immediately after.

If you want a rigorous definition, you could look at the source code for the OPML Editor. The relevant routine is opgetnextexpanded, it's defined in opops.c. To save you the trouble of searching for it, I took a screen shot of the routine.

nodirection is the "nil" of directions, always useful to have one of these around.

expansionState

OPML was designed as the file format for an outliner, and the outliner, as a nice optional feature, remembers how the outline was expanded when it was saved.

expansionState should not be maintained while the outline is open, we don't do it in the OPML Editor, nor would I expect any other outliner to do it. What's efficient in a file format isn't always appropriate for the in-memory representation of the data. This is certainly one of those cases. In memory, we maintain a boolean in every outline element which indicates if its expanded or not. However, it's much more efficient to remember the expanded state in the file format in one concise if machine-oriented, optional element.

You can find the source code for generating and processing the expansionState element in opxml.c in the source code for the OPML editor. I've placed snapshots of both the Mac and Windows versions in scripting.com. Build instructions, supplied by Andre Radke, are here.

Randy Morin's comments 

Randy Morin has a number of comments and questions about the OPML 2.0 spec.

First, the scope of work I'm considering at this time are small fixes to the spec with very minor impact on the format. I'm not going to comment on or explain changes that fall outside this scope, or would even cause breakage with 1.x, or unnecessarily complicate the format.

1. Making the text attribute required in 2.0 means that all OPML files will be usable in an outliner, which I think is a good thing, esp as outliners are becoming more widely used.

2. You say the category attribute needs an example, and I agree. I will provide one or more.

3. You say the spec should say that htmlUrl must be a URL. It says it's the top level link element from the feed, along with the title and description, also from the feed. So we rely on the RSS 2.0 spec to tell us what htmlUrl must be, we're just passing it through.

4. You ask what are the valid values of the language attribute, again, this is just being passed through from the feed. Whatever the RSS 2.0 spec says about this applies.

5. I don't know what the valid values are for the Atom version attribute. If someone who is an expert on Atom would provide them, and show me that there's some agreement about this from Atom experts, I would be happy to say something about this in the OPML 2.0 spec. For me to say something incorrect here would be much worse than saying nothing.

6. About the extension being important in inclusions, that's only true for link elements, which are from OPML 1.x. In 2.0 we introduced a specific include type, that does not depend on the extension. I document the functionality of link so that people reading OPML know they need to watch for this and know how to interpret the extensions.

7. About existing implementations of OPML autodiscovery, I'm unaware of any. Please elaborate.

Anonymous poster 

Feedback from an anonymous poster.

1. Agreed that four-digit years should be preferred.

2. I don't think your second comment is correct. Please read the spec carefully to verify.

3. I imagine that type-based extension may be difficult to support in some circumstances, but I don't see how namespace-based extension mechanisms can be used to do what new node types can do. Regardless, at UserLand we provided easy mechanisms for user scripts to add new nodetypes to outlines, so it's really not practical to pull this one back. If you want to criticize OPML as being designed for the OPML Editor and its predecessors, I suppose you can do that, but I can't pull back from this.