Abstract

Rassmalog is a static blog engine based on YAML, eRuby, and Rake. It transforms blog entries written in Textile or other formatting systems into valid XHTML files that you can view on your computer or upload to your website.. [Continue reading…]

Resources

To get help or provide feedback, simply contact the author.




Contents

Examples

  1. Adding entries from multiple tags to an RSS feed



Chapter 1
Introduction

Rassmalog is a static blog engine based on YAML, eRuby, and Rake. It transforms blog entries written in Textile or other formatting systems into valid XHTML files that you can view on your computer or upload to your website.

Rassmalog is open-source software (see Section 1.2. License) inspired by the Rog, hobix, and nanoblogger blog engines. Its name is derived from the word Rasmalai and somewhat resembles the words “RSS”, “YAML”, and “blog”.

1.1  Features

Noteworthy:

Standard:

  • Categorization by tags (also known as folksonomy).
  • Automatic archives by date, month, year, etc.
  • Automatic RSS feeds for blog entires, tags, etc.
  • Automated blog import from any RSS feed.

1.2  License

Copyright 2006 Suraj N. Kurapati <SNK at GNA dot ORG>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

  • All copies and substantial portions of the Software (the "Derivatives") and their corresponding machine-readable source code (the "Code") must include the above copyright notice and this permission notice.
  • Upon distribution, the Derivatives must be accompanied by either the Code or—provided that the Code is obtainable for no more than the cost of distribution plus a nominal fee—information on how to obtain the Code.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


1.3  Motivation

Although dynamic blog engines are popular nowadays, static blog engines like Rassmalog are still relevant. The following sections attempt to explain why.

1.3.1  Server requirements

Dynamic blog engine Rassmalog
Requires a web server that supports CGI or a server-side scripting language.

Another typical requirement is access to a relational database.
Requires nothing because all web servers are, by definition, capable of serving files over HTTP.

In fact, even a web server is not necessary if you just want to view your blog locally, on your own computer.

1.3.2  Content ownership

Dynamic blog engine Rassmalog
Your content is locked away within a relational database, to which you might not have access. Thus, it is difficult to backup your content. Your content is stored locally, on your computer. Thus, it is easy to backup and share with a good friend.
You are vulnerable to data loss when your web hosting service accidentally crashes or erases your blog. You are safe from data loss when your web hosting service accidentally crashes or erases your blog.

1.3.3  Content portability

  Dynamic blog engine Rassmalog
How is your content kept? Scattered across a relational database on the web server. In plain text files on your computer.
How do you migrate to another blog engine? Assuming that you have SQL access to your blog’s relational database, you must first understand the database schema before you can extract your content.

Afterwards, you still need to convert the extracted content into the new blog’s format.
Your content is readily converted into the new blog’s format using standard text processing tools or languages such as Perl and Ruby.

1.3.4  Speed and scalability

Dynamic blog engine Rassmalog
Responsiveness depends on speed of web server and speed of the server-side scripting language in which the blog software is written. Responsiveness depends only on speed of web server.
Scales poorly because it generates web pages on demand. Scales perfectly because all content is generated only once and only before it is ever uploaded to your web server!

1.3.5  Comments and spam control

Dynamic blog engine Rassmalog
Provides web-based comments that typically burden users with CAPTCHA tests and/or become vulnerable to comment spam.

You will have to clean up the spam eventually, using a clunky web-based comment management interface.
Provides e-mail based comments by default, while taking special care to avoid e-mail spam by obfuscating your e-mail address in such a way that address harvesters won’t bother trying to figure it out.

If you prefer web-based comments instead, see Section 3.4. Using dynamic Javascript-based comments for solutions.


1.4  Background

The basic unit of content in Rassmalog is the blog entry. Entries are collected into sections. Pages are collected into chapters.

As you can see, there is a hierarchical relationship here:

  • Chapter
    • Section
      • Entry

For example,

  • a chapter shows all available tags
  • a section shows all entries that have a particular tag
  • an entry just shows its content

Furthermore, a listing is just a list of blog entries.

Chapter 2
Setup

2.1  Requirements

Your system needs the following software to run Rassmalog.

Software Notes
Ruby Version 1.8.x or 1.9.x is required
Rake Version 0.7 or newer is required
RedCloth Not required if you want to use a different formatting system. Otherwise version 4.x.x is required.
CodeRay Not required if you want to use a different formatting system. Otherwise version 0.7 or newer is required.
ruby-locale Required if you want to use the locale parameter. This library is also available in Debian and Ubuntu under the name “liblocale-ruby”.

If your system has RubyGems, then you can install Rake, RedCloth, and CodeRay by running the following command:

gem install rake RedCloth coderay

2.2  Installation

  1. Download the newest release package from the download area.
  2. Extract the release package anywhere you want on your system.
  3. Go inside the extracted directory and run the following command:
    rake regen

If the installation was successful, then you will see output like this:

(in /home/sun/src/rassmalog)
        copy  output/styles/print.css
        copy  output/styles/common.css
        copy  output/styles/screen.css
        copy  output/icons/tango-32x32-actions-go-next.png
        copy  output/icons/tango-32x32-actions-go-up.png
        copy  output/icons/tango-32x32-actions-system-search.png
        copy  output/icons/tango-32x32-apps-internet-group-chat.png
        copy  output/icons/tango-32x32-actions-go-last.png
        copy  output/icons/tango-32x32-apps-help-browser.png
        copy  output/icons/tango-32x32-actions-go-first.png
        copy  output/icons/tango-32x32-categories-applications-games.png
        copy  output/icons/tango-32x32-apps-system-users.png
        copy  output/icons/tango-32x32-apps-office-calendar.png
        copy  output/icons/tango-32x32-categories-applications-graphics.png
        copy  output/icons/tango-32x32-actions-go-previous.png
        copy  output/icons/tango-32x32-actions-go-home.png
        copy  output/icons/tango-LICENSE
        copy  output/icons/feed-icon-14x14.png
        copy  output/icons/feed-icon-28x28.png
        copy  output/icons/tango-32x32-actions-edit-redo.png
        copy  output/icons/tango-README
        copy  output/icons/tango-32x32-actions-mail-mark-junk.png
        copy  output/icons/tango-32x32-devices-printer.png
        copy  output/icons/tango-32x32-actions-edit-copy.png
        copy  output/icons/feed-icon-README
       Entry  output/example-paths.html
       Entry  output/about.html
       Entry  output/2006-12-14-formatting-with-textile.html
       Entry  output/blog-entry-file-format.html
       Entry  output/2007-09-25-an-entry-from-the-entries-directory.html
     Listing  output/entries.html
    Entrance  output/example-paths.html
     Section  output/tags-examples.html
     Section  output/tags-reference.html
     Chapter  output/tags.html
     Section  output/archives-december-2006.html
     Section  output/archives-september-2007.html
     Chapter  output/archives.html
       Entry  output/search.html
        feed  output/feed.xml
        feed  output/examples.xml


2.3  Manifest

Now that Rassmalog is installed on your system, let us examine its installation directory. Inside, you will see (among other things) the following items:

  • rassmalog.rb – the core of Rassmalog.

2.3.1  doc/

Documentation for Rassmalog users

  • doc/guide.erb – source code of this user guide

2.3.2  config/

Directory that contains all configuration files.

  • config/blog.yaml – the primary configuration file for your blog.
  • config/feed.erb – template for generating RSS feeds for the blog.
  • config/html.erb – template for generating a complete HTML web page.
  • config/chapter.erb – template for generating HTML for lists of tags and archives.
  • config/section.erb – template for generating HTML for individual tags and archives.
  • config/listing.erb – template for generating the recent/all lists of blog entries.
  • config/entry.erb – template for generating HTML for a blog entry.
  • config/format.rb – defines how text is transformed into HTML.

2.3.2.1  config/lang/

Directory that contains translations of English text used in the core of Rassmalog. These translations do not include English text used in the templates (config/*.erb) because those are already separate from the core of Rassmalog.

  • config/lang/de.yaml German
  • config/lang/el.yaml Greek
  • config/lang/es.yaml Spanish
  • config/lang/fr.yaml French
  • config/lang/it.yaml Italian
  • config/lang/ja.yaml Japanese
  • config/lang/ko.yaml Korean
  • config/lang/nl.yaml Dutch
  • config/lang/pt.yaml Portuguese
  • config/lang/ru.yaml Russian
  • config/lang/te.yaml Telugu
  • config/lang/zh.yaml Chinese-simp
  • config/lang/zt.yaml Chinese-trad


2.3.3  output/

Directory that contains your generated blog.


2.3.4  input/

Directory that contains (1) source files for blog entries and (2) additional resources, such as images and stylesheets, that are used by your blog. Everything inside this directory, except source files for blog entries, is automatically copied into the output/ directory (relative paths are preserved) when your blog is generated.

A blog entry source file’s name must end with a .yaml extension. By default, a source file’s corresponding output file has (1) the same name and relative path as the source file but (2) ends with a .html extension.

For example, the input/foo/bar/moz.yaml source file’s corresponding output file is output/foo/bar/moz.html. You can override this default behavior by adding the output_file parameter to your blog entry.

  • input/styles/screen.css – the default CSS stylesheet provided with Rassmalog.
  • input/styles/print.css – the default CSS stylesheet provided with Rassmalog.
  • input/rassmalog/entry.yaml – reference of the blog entry file format.

2.3.5  entries/

Directory that contains blog entry source files whose output files are automatically calculated by Rassmalog.

A blog entry source file’s name must end with a .yaml extension. By default, all source files in this directory will have a corresponding output file with a name in the form: “date-name.html”.

For example, the entries/foo/bar/moz.yaml source file, which was written on 19 July 2006 and has a name of “hello world”, will have a corresponding output file at output/2006-07-19-hello-world.html. You can override this default behavior by adding the output_file parameter to your blog entry.

As you can see, unlike the blog entries in the input/ directory, blog entries in the entries/ directory do not have to worry about their original file name influencing the output file name. As a result, you can organize your blog entry files however you want.

For example, I like to put all blog entry files related to Ruby programming within the entries/code/ruby/ subdirectory. The names of these subdirectories do not have any special meaning to Rassmalog, so you can name them however you like.


2.3.6  plugins/

This directory contains Ruby source files which define additional Rake tasks for Rassmalog.

2.3.6.1  plugins/import.rb

Command Description
rake import_rss Import blog entries from RSS feed on STDIN.

Rake tasks for importing blog entries from feeds.

2.3.6.2  plugins/new.rb

Command Description
rake new Create a new blog entry file for editing.

Provides a Rake task to facilitate “Lazy Blogging” 1 where you
can easily create a new blog entry source file without having to:

  • think of and manage unique file names every time
  • supply the current date and time
  • remember the entire syntax of a blog entry file
  • remember the names of all tags you have used thus far

The name of the created file follows this format:

"entries/{today's date}+{serial number}.yaml"

To create a new blog entry file that is ready for editing:

rake new

To override the default values of blog entry fields:

rake new name='hello world' date='2008 march 17' tags='foo,bar' body='hey!'

To override the tags field (values must be separated by commas):

rake new tags='foo,bar,hello world'

To override the default location of the created file:

rake new file='hello_world.yaml'

1 Josef ‘Jupp’ Schugt, “Lazy Blogging”, 2008 March 16, available at
pre. http://cip.physik.uni-bonn.de/~jupp/2008-03-16-lazy-blogging.html

2.3.6.3  plugins/validate.rb

Command Description
rake tidy show tidy html validation errors and warnings
rake tidy:warn show tidy diagnostic warnings
rake validate show w3c validation errors and warnings (must be online)

Provides Rake tasks to validate and correct HTML files.

This code was adapted by Greg Weber, and is originally by Scott Raymond.
See http://redgreenblu.com/svn/projects/assert_valid_markup/


2.4  Version numbering system

Rassmalog uses the RubyGems rational versioning policy to number its releases. This major.minor.patch numbering policy is summarized as follows:

What happened? What are the consequences?
Backwards compatible? New features? Bug fixes?
The major number increased No Yes Yes
The minor number increased Yes Yes Yes
The patch number increased Yes No Yes

Chapter 3
Configuration

Start by editing the config/blog.yaml file. It has plentiful comments and documentation to help guide you through you the configuration process. Next, proceed to editing the other files in the config/ directory to suit your taste.

You are encouraged to generate your blog at each step of the configuration process to see how your choices affect the generated output. This gives you a good sense of how Rassmalog works and how your blog can be shaped to suit your specific needs.

3.1  Parameters

The following subsections describe the configuration parameters available for use in the config/blog.yaml file.

3.1.1  name (eRuby) (HTML)

The name of your blog.

3.1.2  info (eRuby) (HTML)

Description of your blog.

3.1.3  author (eRuby) (HTML)

The name of the blog author.

3.1.4  email (eRuby)

The e-mail address that will receive comments about your blog entries.

This address will be obfuscated into HTML entities so that
e-mail address harvesters won’t bother to figure out what it
is. For example, the address “xxx@yyy.zzz” will be converted
into the following before it is written to a HTML file:

xxx@yyy.zzz

If you do not wish to receive comments about your
blog entries, or if you absolutely do not want
your e-mail address to be included in the output
(even in the obfuscated form), then you can
simply leave this parameter blank, as follows:

email:   # nothing here!

Examples:

email: your@email.here
email: your+blog@email.here
email: your+comments@email.here

3.1.5  url (eRuby)

The URL of your published blog.

Examples:

url: http://your_host.com/~you/path/to/your/blog/
url: http://you.your_host.com/path/to/your/blog/

3.1.6  uploader (eRuby)

An eRuby template for the command that uploads your blog to your website.

The following predefined variables are available:

<%= whole %> is a path to the output/ directory which must be uploaded.
<%= parts %> is a sequence of quoted paths to files that must be uploaded.
             For example, the result of this directive is something like:
             "output/foo" "output/bar" "output/baz qux moz"

SSH examples:

These examples assume that your website is located in a
directory named “public_html” on a server named “host”
that is accessible by a user named “user” via SSH or SFTP.

uploader: scp -prC <%= parts %> user@host:public_html
uploader: rsync -e ssh -auvz <%= whole %>/ user@host:public_html
uploader: lftp sftp://user@host -e 'mirror -Ra --ignore-time <%= whole %>/ public_html; exit'

FTP examples:

These examples assume that your website is located in a directory
named “public_html” on a server named “host” that is accessible
by a user named “user” with a password of “password” via FTP.

uploader: lftp host -u 'user,password' -e 'mirror -Ra --ignore-time <%= whole %>/ public_html; exit'

3.1.7  encoding (eRuby)

The character set used in your entries.

Examples:

encoding: utf-8       # Unicode (for all languages)
encoding: x-sjis      # Shift JIS (for Japanese only)
encoding: x-iscii-te  # Telugu ISCII (for Telugu only)

3.1.8  language (eRuby)

The ISO-639 code and (optionally) the ISO-3166 country
code for the primary language used in your entries.

For a list of ISO-639 language codes, see:

http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes

For a list of ISO-3166 country codes, see:

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Current_codes

Examples:

language: en    # English
language: en-us # English (United States)
language: en-gb # English (Great Britain)

3.1.9  locale (eRuby)

This parameter specifies the locale corresponding to the language
in which dates, times, and currency will be formatted by Ruby.
See http://en.wikipedia.org/wiki/Locale for more information.

Here are some examples of how the choice of
locale affects the formatting of dates and times:

$ irb -r locale
>> Time.now
=> Tue Oct 23 13:12:20 -0700 2007

# in German:
>> Locale.setlocale(Locale::LC_TIME, "de_DE"); Time.now
=> Di Okt 23 13:12:32 -0700 2007

# in Spanish:
>> Locale.setlocale(Locale::LC_TIME, "es_ES"); Time.now
=> mar oct 23 13:15:19 -0700 2007

# in Italian:
>> Locale.setlocale(Locale::LC_TIME, "it_IT"); Time.now
=> mar ott 23 13:15:27 -0700 2007

To use the default POSIX (U.S. English) locale, leave this parameter blank:

locale:   # nothing here!

To see a list of available locales on your system, run the following command:

locale -a

3.1.10  entrance (eRuby)

Path to a file in the output/ directory that should be displayed when
somebody visits your blog. This is called the “entrance” of your blog.

To use the newest blog entry as the
entrance, simply leave this parameter blank:

entrance:   # nothing here!

3.1.11  generate_toc

Controls whether a table of contents is
generated, by default, for all blog entries.

A blog entry can override this parameter by specifying
its own “generate_toc” parameter in its source file.

3.1.12  date_format

Controls how dates are formatted for display in blog entries.

To use preferred format for the current system locale, specify:

date_format: %c

To display some other information, specify your own value:

date_format: put your own value here

For more information, see the documentation of the Time.strftime method:

http://www.ruby-doc.org/docs/ProgrammingRuby/html/ref_c_time.html#Time.strftime

3.1.13  archive_frequency

Controls how frequently archives are created.

To have one archive per unique year, specify:

archive_frequency: %Y

To have one archive per unique month, specify:

archive_frequency: %Y-%m

To have one archive per unique day, specify:

archive_frequency: %Y-%m-%d

To have one archive per some other criteria, specify your own value:

archive_frequency: put your own value here

For more information, see the documentation of the Time.strftime method:

http://www.ruby-doc.org/docs/ProgrammingRuby/html/ref_c_time.html#Time.strftime


3.2  Localization for foreign languages

The core of Rassmalog is easily localized (L10N / I18N / M17N) through translation files, which consist of simple key-value pairs. For instance, the translation file for Spanish appears like this:

# es - Spanish
About: Sobre
About %s: Sobre %s
Archives: Archivos
Author: Autor
Comments: Comentarios
Contents: Contenido
Date: Fecha
Entries: Entradas
First: Primero
Generator: Generador
Home: Hogar
Icons: Iconos
Last: Último
Name: Nombre
Next: Después
Permanent hyperlink to this section: Enlace hipertexto permanente a esta sección
Previous: Anterior
RSS feed: Alimentación de RSS
Read more...: Lea más...
Return to %s: Vuelva a %s
Search: Búsqueda
Size: Tamaño
Sorted by %s: Clasificado por %s
Subscribe: Suscriba
Tags: Etiquetas
Up: Encima de
You are now being redirected to %s.: Le ahora están volviendo a dirigir a %s.
You may {send comments by e-mail}.: Usted puede {envíe los comentarios por el email}.

  • English phrases are written on the left and their corresponding Spanish phrases are written on the right.
  • The %s things are placeholders for arbitrary text. Think of them as “blanks” on an exam paper that students will “fill in” later on; i.e. to “fill in the blanks”.

3.2.1  Enabling a translation file

The config/lang/ directory contains translation files (there are 13 of them, at present) for English text used in the core of Rassmalog. To enable one of these files, set the value of the language parameter in the config/blog.yaml file to the name of the translation file.

For example, if you wish to enable the config/lang/foobar.yaml translation file, then you would set the language parameter as follows:

language: foobar

In this manner, you can add or edit translation files for your own languages and use them in your blog. However, please consider contributing your translation files so that other users can also enjoy your translations! :-)


3.3  Using another text formatting system

To use another text formatting system, simply replace the String.to_html and String.to_inline_html methods, which are defined in the config/format.rb file, to make use of your desired text formatting scheme.

For example, if you replace the entire config/format.rb file with the following code, then all blog entries will appear within red boxes in the output.

class String
  # Transforms this string into HTML while ensuring that the
  # result contains one or more block-level elements at the root.
  def to_html
    '<p style="border: thin solid red">' + self + '</p>'
  end

  # Transforms this string into an *inline* HTML string (one that
  # does not contain any block-level HTML elements at the root).
  def to_inline_html
    self
  end
end

In this manner, you can make Rassmalog use any formatting system you wish!


3.4  Using dynamic Javascript-based comments

There are several JavaScript-based commenting services available:

To use these services with Rassmalog, simply replace the default “comments” section of the config/entry.erb template (which appears like this:

    <%# BEGIN COMMENTS SECTION %>
      <% if BLOG.email %>
        <br/>
        <%= icon 'tango-32x32-apps-internet-group-chat.png', LANG['Comments'] %>
        <%=
          LANG['You may {send comments by e-mail}.'].
          sub(/\{(.*?)\}/) { link @entry.comment_url, $1 }
        %>
      <% end %>
    <%# END COMMENTS SECTION %>
) with the activation logic provided by the commenting service.

For example, to make use of the js-kit commenting service in Rassmalog, replace the default “comments” section (shown above) with the following activation logic:

<div class="js-kit-comments" path="<%= @entry.url %>"></div>
<script type="text/javascript" src="http://js-kit.com/comments.js"></script>

Notice that we pass the blog entry’s relative URL (obtained by invoking the url method on the @entry object: <%= @entry.url %>) as a unique identifier to the js-kit commenting service. Other commenting services may require you to do something similar as well.


3.5  Disabling parts of a blog

Suppose you wanted to disable the generation of the RSS feed for your blog. In order to do this,

  1. Open the Rakefile in your text editor.
  2. You should now see a line of code similar to this:
    task :gen => [:copy, :entry, :entry_meta, :entry_list, :feed]
  3. Remove the :feed element from the line of code.

In this manner, you can disable other parts of the blog generation process. Furthermore, you can edit the source code in the “output generation stage” section to suit your needs.


3.6  Disabling the search page

The search page is just a blog entry; there is nothing special about it.

  1. Delete the input/search.yaml file.
  2. Regenerate your blog.

3.7  Disabling the about page

The about page is just a blog entry; there is nothing special about it.

  1. Delete the input/about.yaml file.
  2. Regenerate your blog.

Chapter 4
Usage

In the location where you installed Rassmalog, run the following command to see a list of available tasks:

rake -T

For example, here is the output you would see when you run the above command:

(in /home/sun/src/rassmalog)
rake clean       # Remove any temporary products.
rake clobber     # Remove any generated file.
rake copy        # Copy files from input/ into output/
rake entry       # Generate HTML for blog entries.
rake entry_list  # Generate HTML for recent/all entry lists.
rake entry_meta  # Generate HTML for tags and archives.
rake feed        # Generate RSS feeds for the blog.
rake gen         # Generate the blog.
rake import_rss  # Import blog entries from RSS feed on STDIN.
rake new         # Create a new blog entry file for editing.
rake preview     # Preview your blog while writing.
rake regen       # Regenerate the blog from scratch.
rake search      # Generate the blog search page.
rake upload      # Upload the blog to your website.

4.1  Creating a blog entry file

The new plugin allows you to easily create a new blog entry source file without having to:

  • think of and manage unique file names every time
  • supply the current date and time
  • remember the entire syntax of a blog entry file
  • remember the names of all tags you have used thus far

To use this plugin, run the following command:

rake new

After it executes, the command will report the name of the file it created. You can then edit the created file using your favorite text editor and fill in all the juicy details.


4.2  Generating your blog

To generate your blog, run the following command:

rake

Or alternatively, you can run:

rake gen

To regenerate your blog from scratch (delete all existing output and generate everything again), run the following command:

rake regen

4.3  Removing generated files

To remove all output files that were generated by Rassmalog, run the following command:

rake clean

To remove everything inside the output/ directory, run the following command:

rake clobber

4.4  Publishing your blog

To upload your blog to your website, run the following command:

rake upload

4.5  Preview while you write

To continuously preview a blog entry as you write it, run the following command:

rake preview

Now, whenever you save your blog entry file, its HTML page will be generated for preview in your web browser.


4.6  Importing blog entries from RSS feed

The import task allows you to import blog entries from an RSS feed, which must be provided on the standard input stream.

For example, if you have an RSS feed file named feed.xml then you would import it into Rassmalog like this:

rake import < feed.xml

4.7  Creating RSS feeds

  1. Open the Rakefile in your text editor.
  2. You should now see a some code similar to this:
    feed 'feed.xml', ENTRIES.first(5), BLOG.name, BLOG.info
    

    This code invokes the feed method to create an RSS feed.
  3. Add your own invocation of the feed method to the bottom of the file (see the API documentation in Section 6.1. API documentation for help).

Example 1.  Adding entries from multiple tags to an RSS feed

The second parameter of the feed method is an arry of Entry objects. You can take advantage of this fact with some Ruby magic:

# gather the desired entries
entries = TAGS['foo'] + TAGS['bar'] + TAGS['moz']

# remove duplicate entries
entries.uniq!

# create the feed
feed 'example.xml', entries

Here we gather all blog entries that have the ‘foo’, ‘bar’, or ‘moz’ tag into an array, and keep track of it in the entries variable.

Next, we call the uniq method on the entries variable to ensure that all entries occur only once in the array (since the same entry could have both ‘foo’ and ‘bar’ tags, and would thus appear twice in the array).

Finally, we create the news feed by calling the feed method.

Chapter 5
Writing blog entries

This chapter deals with things related to the writing, formatting, and scripting of blog entries.

5.1  Parameters

The following subsections describe the parameters you can use in a blog entry file. For an example of usage, see the input/rassmalog/entry.yaml file.

5.1.1  name (Required) (eRuby) (HTML)

The title of this blog entry.

5.1.2  date (Optional) (eRuby)

The date when this blog entry written.

Here are some examples:

date: Thu, 01 Jan 1970 08:00:00 GMT
date: 1970-01-01 8:00am
date: 1/1/1970 8:00am
date: jan 1st 1970 16:00 -08:00
date: 1 january 1970
date: Wed Dec 13 21:31:04 PST 2006

You can also specify dates in other languages. For
example, the following date

date: Thursday, 01 January 1970 03:15:00 PM

can be written in German as:

date: Donnerstag, 01 Januar 1970 15:15:00

For more information about the format of this parameter, see the documentation
for the Time.parse method by typing the following command at your terminal:

ri Time.parse

or by visiting the following URL:

http://www.ruby-doc.org/core/classes/Time.html#M000297

If you do not specify this parameter, then Rassmalog will
use the modification time of this source file instead.

5.1.3  tags (Optional)

The categories/labels which classify this blog entry.

5.1.4  output_file (Optional) (eRuby)

A relative path (with respect to the output/
directory) to the output HTML file for this blog entry.

5.1.5  hide (Optional)

Controls whether this entry is displayed in the
lists of tags, archives, and recent/all entries.

5.1.6  generate_toc (Optional)

Overrides the generate_toc parameter that is defined in the main
blog configuration file (config/blog.yaml). This parameter
controls whether a table of contents is generated for this blog entry.

5.1.7  summary (Optional) (eRuby) (HTML)

Overrides the automatic summarization mechanism, which is
defined in the config/entry.erb template, by allowing
you to specify a predefined summary for this blog entry.

5.1.8  your_own_parameter1 (Example)

This is an example of how you can specify your own custom
parameters and use them in the content of this blog entry.

5.1.9  body (Required) (eRuby) (HTML)

The content of this blog entry.

In this parameter, you can use the following
predefined variables inside eRuby directives:

  • BLOG – data from the blog configuration file
  • LANG – data from the translation file
  • ABOUT_PAGE – the blog entry corresponding to the about page
  • SEARCH_PAGE – the blog entry corresponding to the search page
  • ENTRIES – array of all blog entries (Entry objects)
  • TAGS – array of all tags (Section objects)
  • ARCHIVES – array of all archives (Section objects)
  • FEEDS – array of all feeds (Feed objects)
  • @entry – the Entry object for which we are generating HTML
  • @summarize – should this entry be summarized?
  • @solo – is this entry being rendered alone, on its own page?


5.2  eRuby directives

The body of a blog entry is treated as an eRuby template. Thus, you can use eRuby directives (which appear within <% and %> tags) in the body of your blog entries.

For example, putting the following content in a blog entry:

<% 3.times do %>

* Hello World!
<% end %>

Produces the following result:

  • Hello World!
  • Hello World!
  • Hello World!

5.2.1  Including the content of another file

To include the content of another file inside the body of a blog entry, you can use the following eRuby directive:

<%= File.read('path-to-your-file') %>

If the included file contains characters that might be interpreted as HTML, then we should properly escape those characters using the ERB::Util#h method:

<%= h File.read('path-to-your-file') %>


5.3  Relative URLs to output files

Rassmalog adjusts all relative URLs in the final HTML output to be relative to the output/ directory. This is done to give all blog entries (regardless of how deep they are inside the input/ directory) a common way to access files. As a result, some extra work is necessary to access files that are relative to a blog entry itself.

For example, suppose that (1) we have the following directory structure and that (2) the input/food/fruit/banana.yaml blog entry contains the ../nuts/walnut.html relative URL.

  • input/
    • food/
      • fruit/
        • banana.yaml
      • nuts/
        • walnut.yaml
  • output/
    • food/
      • fruit/
        • banana.html
      • nuts/
        • walnut.html

Rassmalog will change ../nuts/walnut.html into ../../../nuts/walnut.html by adding a ../../ prefix. As a result, the changed URL is now referring to a nonexistent nuts/walnut.html file that resides one level above the output/ directory!

One solution is to manually rewrite to rewrite the original URL to be relative to the output/ directory: ../nuts/walnut.html becomes food/nuts/walnut.html.

Another solution is to use an eRuby directive to add the blog entry source file’s parent directory’s path to the relative URL: ../nuts/walnut.html becomes

<%= File.dirname(@entry.output_url) %>/../nuts/walnut.html


5.4  Table of contents generation

A table of contents is automatically generated from headings (<h1> through <h6> for HTML and h1. through h6. for Textile) found in the body of a blog entry.

Headings are numbered in the style of LaTeX; these numbers contain a hyperlink back to the table of contents for easier navigation.

If you want to disable the table of contents for a particular blog entry, then see the generate_toc parameter in the list of parameters above.

If you want to disable the table of contents globally, for all blog entries, then see the generate_toc parameter in your config/blog.yaml configuration file.


5.5  Syntax coloring for source code

Syntax coloring is automatically added to source code found inside the <code> and </code> HTML tags. Note that in Textile, any text enclosed within a pair of at-signs (@ and @) is also considered to be source code.

The following programming languages are currently supported by CodeRay, the default syntax coloring software used in Rassmalog:

  • Ruby
  • C
  • Delphi
  • HTML
  • RHTML (Rails)
  • Nitro-XHTML

This feature can be disabled or changed by editing the config/format.rb file accordingly.

5.5.1  Specifying the programming language

Because different programming languages have different syntax coloring schemes, you can specify the language of your source code using the lang attribute to ensure that only the appropriate coloring scheme is used. Note that unless the lang attribute is specified, Ruby is assumed to be the programming language of all source code by default.

For example, here is some source code without the lang attribute:

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>

And here is the same source code with a lang="c" attribute:

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>

And here is the same source code with a lang="html" attribute:

# Ruby ###########################
def hello
  puts "Hello world!"
end


/* C ****************************/
#include <stdio.h>
int main(int argc, char **argv) {
  printf("Hello world!\n");
  return 0;
}


<!-- HTML ----------------------->
<html>
  <body>
    Hello world!
  <body>
</html>


5.5.2  Smart sizing of source code

Source code is automatically sized to be displayed as either a line or paragraph of text, depending on whether it contains line breaks.

For example, here is a single line of code:

life = true or false

And here is a paragraph of code:

life =
true or false

This feature can be disabled or changed by editing the config/format.rb file accordingly.


5.6  Protecting verbatim text

Sometimes you just need to protect some text from being mangled by the text-to-HTML conversion process (which is governed by config/format.rb). In such cases, you can wrap the text you want to proctect within <noformat> and </noformat> tags.

Note that this is a feature of the default config/format.rb file provided with Rassmalog. If you defined your own text-to-HTML conversion scheme, then this feature might not work.

Chapter 6
Hacking

You can obtain the latest source code from the Darcs repository:

darcs get http://rassmalog.rubyforge.org/src/ rassmalog

6.1  API documentation

Method declaration Description
Entry#parent()
Entry::new(aData = {})
aData:the content of this Entry
Entry#hide?()

Returns true if this entry is hidden (the ‘hide’ parameter is enabled).

Entry#summary()

Returns the summarized HTML content of this blog entry. If there is no summary or summarization is not possible, then returns nil.

Entry#absolute_url()

Returns the absolute URL to this entry.

Entry#<=>(aOther)

Sort chronologically.

Entry#html()

Transforms the content of this entry into HTML and returns it.

Entry#comment_url()

Returns a URL for submiting comments about this entry.

Chapter::new(aName)
Chapter#[](aName, *args)

Allows you to access a section using its name or through the usual Ruby array access idioms.

Language::new(aData = {})
Language#[](aPhrase, *aArgs)

Translates the given string and then formats (see String#format) the translation with the given placeholder arguments. If the translation is not available, then the given string will be used instead.

Template::new(aName, *args)
aName:String that replaces the ambiguous ’(erb)’ identifier in stack traces, so that the user can better determine the source of an error.
args:Arguments for ERB::new
Template#render_with(aInstVars = {})

Renders this template within a fresh object that is populated with the given instance variables.

Section#url()

Path (relative to the output/ directory) to the HTML output file of this object.

Section::new(aName, aChapter)
Section#<=>(aOther)

Sort alphabetically.

String#to_file_name()

Transforms this string into a vaild file name that can be safely used in a URL. See en.wikipedia.org/wiki/URI_scheme#Generic_syntax

String#to_html_entities()

Transforms this UTF-8 string into HTML entities.

String#to_uri_fragment()

Transforms this string into a valid URI fragment. See www.nmt.edu/tcc/help/pubs/xhtml/id-type.html

String#thru_erb(aBinding = Kernel.binding)

Passes this string through ERB and returns the result.

String#shell_escape()

Transforms this string into an escaped POSIX shell argument whilst preserving Unicode characters.

String#table_of_contents()

Builds a table of contents from XHTML headings (<h1>, <h2>, etc.) found in this string and returns an array containing [toc, html] where:

toc:the generated table of contents
html:a modified version of this string which contains anchors for the hyperlinks in the table of contents (so that the TOC can link to the content in this string)
String#to_inline_html()

Transforms this string into an inline HTML string (one that does not contain any block-level HTML elements at the root).

String#to_html(aInline = false)

Transforms this string into HTML while ensuring that the result contains one or more block-level elements at the root.

If aInline is true, then the resulting HTML will be an inline string.

String#thru_redcloth(aInline = false)

Returns the result of running this string through RedCloth.

If aInline is true, then the resulting HTML will be an inline string.

String#thru_coderay()

Adds syntax coloring to <code> elements in the given text. If the <code> tag has an attribute lang="…", then that is considered the programming language for which appropriate syntax coloring should be applied. Otherwise, the programming language is assumed to be ruby.

String#digest()

Returns a digest of this string‘s content.

String#protect(aInput, aTags, aVerbatim) {|aInput| ... }

Protects the given tags in the given input, passes that protected input to the given block, restores the given tags in the result of the block and returns it.

If aVerbatim is true, the content of the elments having the given tags will not be temporarily altered so that process nested elements can be processed.

File::write(aPath, aContent)

Writes the given content to the given file.

TemplateMixin#template_name()

Basename of the template file, which resides in the config/ directory, used to render objects of this class.

TemplateMixin#template()

Returns the template used to render objects of this class.

TemplateMixin#template_ivar()

Returns the name of the instance variable for objects of this class. This variable is used in the template of this class.

TemplateMixin#url()

Path (relative to the output/ directory) to the HTML output file of this object.

TemplateMixin#uri_fragment()

Returns a URI fragment for this object.

TemplateMixin#parent_url()

Returns a URL to the parent page which takes you directly to this item inside the parent page.

TemplateMixin#to_html(aOpts = {})

Transforms this object into HTML.

TemplateMixin#render(aOpts = {})

Renders a complete HTML page for this object.

TemplateMixin#to_link(aOpts = {})

Returns a relative link to this object, customized by the following options:

frag:a URI fragment that is appended to the URL, if given.
body:sets the body of the link (the <a> tag), if given.
nbsp:makes spaces in the link body non-breaking, if true.