Rob Reed

Tuesday Feb 19, 2008

• Ode is written in Perl.
• The content of an Ode site is a collection of plain text files.
• The look and layout of a site is entirely determined by 'themes', which are no more than standard (X)HTML and CSS.
• Ode uses the filesystem as its content database.
  • This more than any other design decision impacts how Ode is written, how it operates, and how it's used.
• Is that all? No.
  • Ode is extensible.
    • Only essential behaviors are implemented in the script itself.
    • It's possible to extend what Ode can do by taking advantage of an 'addin' scheme which allows for new features or even redefining built-in routines.

Ultimately, Ode should support all of the key features found in other personal publishing packages for the web, including:

• Permalinks
• Date-based browsing and archiving
• Commenting
• Syndication (feeds)
• Local search
• In browser editing (with live preview)
• Presentations (conforming to the S5 format)
• and many others

In fact the majority of these features are already implemented.

Because content are plain text files and Ode uses the filesystem for its content database, negotiating an Ode site amounts to:

1. Editing
2. File management
3. File transfer

When taken together with the wealth of software available for these tasks, Ode is a powerful and flexible little tool.

Editing

• You're free to use any editor you like!
• There are many fantastic editors available, some of the best are open source apps and of course there are also some great commercial applications.
• These editors are as varied as the people who use them and the jobs they're asked to do.
• As a class, editors are some of the most mature, subtlety brilliant software applications available.
  • Why then, when it comes to writing online, are we asked to abandon these finely honed tools in favor of the blunt instrument that is the HTML form?
• Ahh, but being able to write in a browser is so much more convenient. I agree.
  • We can do that too. :)

File Management

• Posts are files.
• Directories are categories.
• Assuming you've used a computer in the last approx 40 years, those two statements are enough for you to understand how to manage content for an Ode site.
• But just like managing and organizing other types of files, this scheme proves to be robust.

Create any number of categories and subcategories in any arrangement that works for you.

Examples:

/Review/
/Review/Movies/
/Review/Software/
/Review/Software/Open_Source/

/Tufts/Courses/Comp250SA/

Here's one you'll never need to do:

/2008/
/2008/02/
/2008/02/06/

Ode handle dates like this automatically.

File Management continued

Static websites work like this too, but because Ode is not static we can take better advantage of this arrangement.

For example:

• Themes can be defined and redefined at any level of the hierarchy.
• Any category or subcategory can be syndicated and subscribed to independently.
• Posts can be reorganized without affecting their date-based permalinks.

File Transfer

Interacting with a remote server is no more complicated than file transfer, which allows for a great degree of flexibility.

You're free to use:

• SFTP
• SSH
• WebDAV
• HTTP

...or any other file transfer/data exchange protocol that works for your environment.

Other

There are other advantages to keeping content as discrete plain text files related to:

• Scripting and automation
• Synchronization among multiple installations, etc.
• Migrating data into and out of Ode
• etc.

'Ode is simple'

• With the stipulation that
  • 'Simple means you know how it works.'

That assertion requires that the documentation be done well.

Ode should be lightweight.

Resource requirements should be minimal.

• By taking advantage of services already provided by the OS, other freely available software, and well-established protocols, we can minimize the overhead involved in running this application while improving its outlook in terms of reliability, security, interoperability, etc.

There should be a minimum of internal and external dependencies.

External Dependencies

• Prerequisites should be eliminated to the extent that it is reasonable to do so.

Internal Dependencies

• Projects that encourage group participation and present a modular architecture can quickly run into problems with conflicting competition and dependency among components.
  • For example, as an end user I want to install an extension but can't because it requires an extension I don't want or can't install.
  • Ode should be designed to avoid these these types of problems.

The code should be accessible for people new to programming.

• The source should be well-documented so that it is accessible to the widest possible audience.
• The code should be clear not clever.
  • Anyone trying to demonstrate their programming prowess would be better off starting with a different project. :)
  • The code should be written so that it is:
    • Intuitive and obvious to experienced programmers (so as to encourage their participation).
    • Accessible even to very new programmers (so as to encourage their participation too).

The code should be accessible for people new to Perl.

Perl's strengths are also some of its weaknesses:

• It is a permissive language, and so has a tendency to result in unstructured programs
• It is overly idiomatic.

For these reasons Perl's critics often deride it as a 'write-only' language.

There's nothing about the language that prevents code from being well-written:

• Perl's weaknesses can be overcome by adhering to good coding practices.
• The style of the source code should be as explicit and language-neutral as possible as opposed to being terse and overly idiomatic, except where the idioms are more efficient.
  • Wherever idioms are preferred, liberal commenting should be used so that people who are unfamiliar with the eccentricities of the language are not lost.

The project should not use a separate package manager which:

• Adds an external dependency.
• Potentially fractures support and maintenance issues between multiple projects.
• Complicates initial setup and configuration.
  • Especially for users new to the package manager who must, at the outset, contend with multiple new projects.

Finally, it's unnecessary because managing Ode's packages (addins) is straightforward.

Work locally or remotely

• Manage content
  • Create
  • Post
  • Edit
  • Share
• Design themes
• Write and test addins

It should not be necessary to introduce mulitple 'modes' of interaction.

It should be possible to synchronize local and remote instances of the same site.

The entire platform should be portable.

• Ode should run, essentially unmodified, on all of the mainstream desktop and server operating systems, including:
  • Linux
  • Mac OSX
  • Windows
• It should be flexible enough to take advantage of best in class or user preferred apps and services available for each platform.

• Presentation or Post?
• Edit Presentation Content Just Like Posts
• Design Presentations Using Themes
• Create, Share and Present
• Collaborative Presentations
• How It Works

• Presentations are posts (and vice versa)

• Create or modify presentations using a web browser
  • Fix mistakes quickly
• or with a text editor
  • Use a comfortable, familiar application
  • Without the bloat and quirks of presentation apps
• Write in either html or markdown

• Treat the design of your presentations like any other theme
• A theme in ode is a bundle (folder) containing a page "template", CSS file(s), an image directory maybe, and whatever else you want to include
• All we need to do is add the S5 javascript files
• Presentation design involves XHTML and CSS

• Create a post about a particular topic or idea
• Then switch themes to present information from that post to a group
• Create a presentation and ask for comments
• Or even invite others to edit the presentation directly
• Share presentations as plain text (email, IM or the web)

• Controls are:
  • Next slide: Space bar, return, right arrow, down arrow, page down, click anywhere in slide that isn't in the control area (lower right corner), or use the control area
  • Previous slide: Up arrow, left arrow, page up, or use the control area
• To invoke the navigation menu: mouse into the lower right corner of the slide