Hobix Tutorial 1

Introduction

Hobix is a blogging system, written in Ruby, by _Why the Lucky Stiff.

Unlike many other system, Hobix does not need to be running on the system that will host your blog.

For example, my blog can only be FTP’ed to my ISP host (unless I want to use some PHP blogs, which I d not want ;) It can run on Unix/Linux, Mac OS X, and Windows machines. It uses extensively YAML, both as a configuration file format that as the article format.

Each article is contained in one file (called an entry), together with the author name (as several authors may write for a given blog), the creation date, a summary, a title, and eventually a content.

Due to the dynamic nature of Ruby, you can even define your own entry file format to best suits your needs.

Repartition of the articles (for example amongst different sections like Code, Books and Misc) is done through the directory layout that hold articles.

In this tutorial I will cover only the basics: installing hobix, configuring it (in a minimalistic way), and posting articles. I will try to cover more advanced settings (like the one described by _why on the hobix ML)) in subsequent tutorials.

Installation et settings

Hobix can be installed using several ways: by using tarball, using CVS or using Web content evaluation. I will only cover Web installation in this tutorial, as it’s the more convenient.

Prerequesites

You first need to have Ruby interpreter installed. The latest version is preferably the better, and I would suggest using Ruby version 1.8.2 We also need another _why product called RedCloth (which allow the use of Textile formatting when writing article). You can find RedCloth on rubyforge.

Installing

To install from Web sourcing, you just need to have Ruby installed, an Internet connection up and type ruby -ropen-uri -e 'eval open("http://go.hobix.com/0.3b/").read' at the prompt:

 

misc# ruby -ropen-uri -e 'eval open("http://go.hobix.com/0.3b/").read'
# Readying install...
# Beginning gzip transmission.
#

                               () ()
                                () ()
               o --- (--=   _--_ /    \
             o( -- (---=  ~/     / ^ ^/
          o. (___ (_(__-=  //  ///\/\/

              you speedy little goat!!
                you got.. you got..
                  ahee!! hobix!!

# halloo!! ready to install the very latest hobix??
# DON'T BE 'FRAIDY!! nothing scary AT ALL!! (hobix is
# whizzzy cool and /everyone/ is holding your hand.)

+ ready to go + [Y/n] ?Y

Yes, we’re OK … Note that we’re installing version 0.3b… By looking at Hobix site you can have the last current version.

# where would you like to install the libraries??
# the default is your ruby site libs dir, which is
# /usr/lib/ruby/site_ruby/1.8

+ lib path [ENTER for default] +

Let’s choose default path (press ENTER):

* upgrading from hobix v0.3 to the latest v0.3b

# where would you like to install the hobix
# command-line tool?? the default is
# /usr/bin

+ cmd path [ENTER for default] +

OK.. it sees that version 0.3 was already installed on my box, and upgrades it. Let’s choose default location again:

# where would you like to install the hobix
# accessory data?? (this includes the default
# blogging templates.)  the default is
# /usr/share/hobix

+ share path [ENTER for default] +

Again default:

# will you be using su or sudo??  this way you can
# install hobix without being logged in as root.
# (windows users: skip this step!!)

+ su or sudo + [su/sudo/NONE] ?

Choose the way you will identify yoursel if you did the installation as a normal user. I choose NONE (default) as I’m already root (really bad habit):

# here's your setup options

--- 
sharedir: /usr/share/hobix
sitelibdir: /usr/lib/ruby/site_ruby/1.8
bindir: /usr/bin

+ all set + [Yn] ?

We’re OK with this (press ENTER):

creating lib/hobix/bixwik.rb (6k)...
creating lib/hobix/out/okaynews.rb (1k)...
creating lib/hobix/webapp/urigen.rb (5k)...
creating share/default-blog/skel/index.xml.rss (0k)...
creating share/default-blog/skel/section.html.quick-archive (0k)...
creating share/default-blog/entries/blog/theFiftyThirdCalypso.yaml (0k)...
creating lib/hobix.rb (11k)...
creating share/default-blog/skel/index.html.quick-summary (0k)...
creating lib/hobix/weblog.rb (39k)...
creating share/default-blog/skel/monthly.html.quick-archive (0k)...
creating lib/hobix/out/redrum.rb (0k)...
creating share/default-blog.apache2-ssi.patch (0k)...
creating share/default-blog/entries/blog/theSixthBook.yaml (0k)...
creating lib/redcloth.rb (45k)...
creating share/default-blog/skel/yearly.html.quick-archive (0k)...
creating share/default-blog/entries/about/me.yaml (0k)...
creating lib/hobix/entry.rb (7k)...
creating lib/hobix/article.rb (0k)...
creating lib/hobix/linklist.rb (3k)...
creating lib/hobix/out/quick.rb (10k)...
creating lib/hobix/storage/filesys.rb (9k)...
creating lib/hobix/config.rb (1k)...
creating lib/hobix/webapp.rb (29k)...
creating lib/hobix/out/rss.rb (4k)...
creating lib/hobix/webapp/htmlform.rb (4k)...
creating lib/hobix/webapp/webrick-servlet.rb (4k)...
creating bin/hobix (3k)...
creating share/default-blog/hobix.yaml (0k)...
creating lib/hobix/commandline.rb (18k)...
creating lib/hobix/out/erb.rb (2k)...
creating lib/hobix/out/atom.rb (4k)...
creating lib/hobix/util/patcher.rb (6k)...
creating lib/hobix/publish/ping.rb (1k)...
creating lib/hobix/base.rb (6k)...
creating lib/hobix/out/rdf.rb (4k)...
creating share/default-blog/htdocs/site.css (3k)...
creating share/default-blog/skel/index.atom.atom (0k)...
creating share/default-blog/skel/index.yaml.okaynews (0k)...
creating lib/hobix/util/objedit.rb (7k)...
creating share/default-blog.apache-ssi.patch (1k)...
creating share/default-blog-modes.yaml (0k)...
creating share/default-blog/skel/entry.html.quick (0k)...
creating share/default-blog/entries/blog/theBokoMaruCalypso.yaml (0k)...
creating lib/hobix/webapp/cli.rb (8k)...
creating lib/hobix/webapp/message.rb (6k)...
** Unable to install Ri documentation for Hobix **

# brilliant, it's all installed.  would you like to setup your hobix
# configuration now??  (if not, you can use `hobix setup_blogs' at your
# convenience.

+ setup your blogs + [Yn] ? 

Setting

OK. Let’s now setup our new blog (press ENTER)

# Configuration stored in /home/sleeper/.hobixrc
Welcome to hobix (a simple weblog tool).  Looks like your
first time running hobix, eh?  Time to get a bit of information
from you before you start using hobix.  (All of this will be stored
in the file /users/fros/.hobixrc if you need to edit.)

Your hobix username [<Enter> for sleeper]: 

I want Hobix know me as sleeper, so I press ENTER:

Your EDITOR environment variable is set to 'vim'.
You can edit entries with your EDITOR or you can just use hobix.
** NOTE: If you don't use your own editor, then you will be using
   the Hobix built-in object editor, which is highly experimental
   and may not work on your platform.)
Use your EDITOR to edit entries? [Y/n]: 

Once again, I want to use default choice. Note that if your EDITOR variable is not set (use echo $EDITOR to see it), and you’d like to use emacs as your editor, you can do it under bash by typing export EDITOR="emacs". For other shell, please consult the associated man page ;)

After posting a new entry, would you like Hobix to automatically
update the site? [Y/n]: 

We want Hobix to update site each time we post a new article, so let’s press ENTER:

Your personal information has not been setup yet.
Your real name: Frederick Ros

Wow … Big brother ? ;)

URL to your home page: http://bloggie
Your e-mail address: jdoe@nowhere.org

Let’s suppose we will be hosted at http://bloggie, and that my email address is jdoe@nowhere.org


            === Joining an existing weblog? ===
If you want to join an existing hobix weblog, we can do that now.
Each weblog needs a name and a path.  Use <ENTER> at any prompt
to simply move on.

Short name for weblog, used on the command line (i.e. hobix upgen blogName).
: bloggie

We’ll name our blog bloggie ...but there’s nothing created for it yet, so when Hobix asks for a path just press ENTER:

Short name for weblog, used on the command line (i.e. hobix upgen blogName).
: bloggie
Path to weblog's hobix.yaml `bloggie': 
To setup more weblogs later, use: hobix add weblog-name /path/to/hobix.yaml

            === Create a new weblog? ===
If you want to create a new hobix weblog, we can do that now.
Each weblog needs a name and a path.  Use <ENTER> at any prompt
to simply move on.

Short name for weblog, used on the command line (i.e. hobix upgen blogName).
: bloggie

OK. So let’s create structure for our blog. We want it to be in /home/sleeper/misc/weblogs/bloggie:

Path to create weblog `bloggie': /home/sleeper/misc/weblogs/bloggie
*** Creation of weblog `bloggie' will add the following directory" 
    structure to directory /home/sleeper/misc/weblogs/bloggie" 

    /home/sleeper/misc/weblogs/bloggie
       hobix.yaml <- configuration

       entries/   <- edit and organize
                     your news items,
                     articles and so on.

       skel/      <- contains your
                     templates

       htdocs/    <- html is created here,
                     store all your images here,
                     this is your viewable
                     websyht

       lib/       <- extra hobix libraries
                     (plugins) go here

Create this structure? [y/N]: y
We do not want to look at Apache config for now, so let’s press ENTER to the next question:
The default blog is available in the following modes:
  apache1-ssi, apache2-ssi

Mode: [Enter for none] 

OK .. So the editor mentionned in your EDITOR environment variable should pops up, showing you something like:

--- !hobix.com,2004/weblog
title: a bokononist asks
link: http://bokononist.hobix.com/
tagline: "nice, nice, very nice" 
period: 00:60:00
authors:
  you:
    name: the ghost of another hobix user-to-be
    url: http://hobix.com/
    email: ghosty@hobixghostfriends.com
linklist: !hobix.com,2004/linklist
  links: !omap
    - 
      hobix: http://hobix.com/
    - 
      del.icio.us: http://del.icio.us/
sections:
  about:
    ignore: true
    sort_by: id
requires:
  - hobix/storage/filesys
  - hobix/out/quick
  - hobix/out/erb
  - hobix/out/rss
  - hobix/out/okaynews
  - hobix/out/atom

This is the weblog default configuration. Let’s edit it to change the author name, url and email, as well the link, tagline (if used ) and title. Note that this perhaps should be handled by hobix (we’ll ask _why to add it for us ;))

--- !hobix.com,2004/weblog
title: A test weblog
link: http://bloggie
tagline: "To test .. for ever" 
period: 00:60:00
authors:
  sleeper:
    name: Frederick Ros
    url: http://bloggie
    email: jdoe@nowhere.org
linklist: !hobix.com,2004/linklist
  links: !omap
    - 
      hobix: http://hobix.com/
    - 
      del.icio.us: http://del.icio.us/
sections:
  about:
    ignore: true
    sort_by: id
requires:
  - hobix/storage/filesys
  - hobix/out/quick
  - hobix/out/erb
  - hobix/out/rss
  - hobix/out/okaynews
  - hobix/out/atom

Save and exit your editor:

*** Joining blog `A test weblog', adding you as author.

Short name for weblog, used on the command line (i.e. hobix upgen blogName).
: 

Just press ENTER as we do not want to create a new weblog.

To create more weblogs later, use: hobix create weblog-name /path/to/

# your hobix installation is complete!! to get
# started, type `hobix'.  if the command-line
# tool is in your path, you should see a list of
# hobix actions!!  (here are you configs again:)

--- 
sharedir: /usr/share/hobix
sitelibdir: /usr/lib/ruby/site_ruby/1.8
bindir: /usr/bin

# See hobix.com for a tutorial on using your new Hobix blogs!!  And
# when you have your blog up, let everybody know at let.us.all.hobix.com,
# okay?? great, thanks.

Yeah !!! Hobix is now installed, and our first blog is setup (with default values though .. ;):

Let’s check everything works:

misc> hobix
hobix 0.3b on ruby 1.8.2 (2004-12-25) [sparc-solaris2.8]
Usage: hobix command weblog-name [command-options]
Commands are
  upgrade                               Check for updates to Hobix.             

  add weblog-name /path/to/hobix.yaml   Adds a pre-existing hobix weblog to your list.
  blogs                                 List your weblogs.                      
  create weblog-name /path/to/          Create a brand new weblog.              
  del weblog-name                       Remove weblog from your list.           

  edit weblog-name                      Edit weblog's configuration             
  list weblog-name search/path          List all posts within a given path.     
  post weblog-name shortName            Add or edit a post with identifier 'shortName'.
                                        (You can use full paths. 'blog/weddings/anotherPatheticWedding')
  regen weblog-name                     Regenerate the all the pages throughout the site.
  upgen weblog-name                     Update site with only the latest changes.

Generating the default blog

We can now generate the default blog (i.e. the blog that come with your version of hobix):

misc> hobix regen bloggie
[Building monthly pages]
## Page: /2004/05/index.html, updated Thu Jan 20 00:21:48 CET 2005
/usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:668:in `load_and_validate_entry': Invalid
 author 'you' found in entry blog/theSixthBook (Hobix::Weblog::AuthorNotFound)
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:496:in `retouch'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:495:in `collect!'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:495:in `retouch'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:490:in `each'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:490:in `retouch'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:476:in `each'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:476:in `retouch'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:474:in `each'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:474:in `retouch'
        from /usr/lib/ruby/site_ruby/1.8/hobix/weblog.rb:470:in `regenerate'
        from /usr/lib/ruby/site_ruby/1.8/hobix/commandline.rb:238:in `regen_action'
        from /usr/bin/hobix:64:in `call'
        from /usr/bin/hobix:64
misc>

Wow .. things are going bad, because the default articles are signed by the author named you, and it is not known … So let’s replace this author by us, and let’s do it the Ruby way !

misc> ruby -i -pe 'gsub(/^author:.*$/,"author: sleeper")' weblog/bloggie/entries/*/*.yaml
(do not forget to change the username as well as the path to your blog)

and let’s try to regen the whole blog:

misc> hobix regen bloggie
[Building monthly pages]
## Page: /2004/05/index.html, updated Thu Jan 20 00:30:42 CET 2005
[Building entry pages]
## Page: /blog/theSixthBook.html, updated Thu Jan 20 00:30:42 CET 2005
## Page: /blog/theFiftyThirdCalypso.html, updated Thu Jan 20 00:30:42 CET 2005
## Page: /blog/theBokoMaruCalypso.html, updated Thu Jan 20 00:30:42 CET 2005
## Page: /about/me.html, updated Thu Jan 20 00:30:42 CET 2005
[Building index pages]
## Page: /index.html, updated Thu Jan 20 00:30:42 CET 2005
## Page: /index.xml, updated Thu Jan 20 00:30:42 CET 2005
## Page: /index.yaml, updated Thu Jan 20 00:30:42 CET 2005
## Page: /index.atom, updated Thu Jan 20 00:30:42 CET 2005
[Building section pages]
## Page: /about/index.html, updated Thu Jan 20 00:30:42 CET 2005
## Page: /blog/index.html, updated Thu Jan 20 00:30:42 CET 2005
[Building yearly pages]
## Page: /2004/index.html, updated Thu Jan 20 00:30:42 CET 2005

Fine !!! By default the site is generated in weblogs/bloggie/htdocs/ (you can override this by setting the attribute output_path to the path you want in the hobix.yaml file)

You can use a browser to open the index.html, use Apache, or we can write our own, simple HTTP server using WEBRick. Copy the following ruby program, in a file named for example http-server.rb:
#!/usr/bin/env ruby
require 'webrick'
include WEBrick

# Use user supplied directory or default one

root = if ARGV.size != 0 
         ARGV[0]
       else
         File.join(Dir::pwd,"htdocs")
       end

puts "Serving #{ root } directory..." 

s = HTTPServer.new(
  :Port            => 2000,
  :DocumentRoot    => root
)

trap("INT"){ s.shutdown }

s.start

You then just have to make it executable (for example chmod +x http-server.rb), and launch it with the path you want to render as argument:

./http-server.rb /home/sleeper/weblogs/bloggie/htdocs/
Serving /home/sleeper/weblogs/bloggie/htdocs/ directory...
[2005-01-20 00:39:35] INFO  WEBrick 1.3.1
[2005-01-20 00:39:35] INFO  ruby 1.8.2 (2004-12-25) [i686-linux]
[2005-01-20 00:39:36] WARN  TCPServer Error: Address family not supported by protocol - socket(2)
[2005-01-20 00:39:36] INFO  WEBrick::HTTPServer#start: pid=18813 port=2000

You can now direct your browser to http://localhost:2000 and you should see the default blog:

Posting

OK .. Now let’s post our first article. We will entitle it ‘Good Morning’, and want it to be in the misc section…

First let’s create a misc section under the entries :

mkdir weblogs/bloggie/entries/misc

and then call Hobix:

hobix post bloggie misc/GoodMorning
The editor you mentionned in the EDITOR env variable will be pop up, and will display the following:
--- !hobix.com,2004/entry
title: Good Morning
author: sleeper
content:

Note that the GoodMorning file name became ‘Good Morning’ title (you can change it if you need without having to change the file name). You now have to file in the content field. Do not forget that you’re editing a YAML document (so no TAB), and that you can embed Textile markup in your post… So you’ll have something like:

--- !hobix.com,2004/entry
title: Good Morning
author: sleeper
content: |
  This is my *first* post ... There will (hopefully) be several other following  

You can save and exit your editor …

[Building yearly pages]
## Page: /2005/index.html, updated Wed Jan 12 14:37:09 MET 2005
[Building section pages]
## Page: /misc/index.html, updated Wed Jan 12 14:37:09 MET 2005
[Building monthly pages]
## Page: /2005/01/index.html, updated Wed Jan 12 14:37:09 MET 2005
[Building index pages]
## Page: /index.yaml, updated Wed Jan 12 14:37:09 MET 2005
[Building index pages]
## Page: /index.xml, updated Wed Jan 12 14:37:09 MET 2005
[Building index pages]
## Page: /index.html, updated Wed Jan 12 14:37:09 MET 2005
[Building index pages]
## Page: /index.atom, updated Wed Jan 12 14:37:09 MET 2005
[Building entry pages]
## Page: /misc/GoodMorning.html, updated Wed Jan 12 14:37:09 MET 2005

You can now reload index.html in your browser… Your article should now appear.

That’s all for this first tutorial.. Next time we will see how to fix broken links that still appears on your blog, and to personnalize it more through the user of the powerfull so-called “Quick Templates”.
Version: $Id: hobix-tut-1-en.yaml,v 1.2 2005/02/24 22:17:19 sleeper Exp $
On: $Date: 2005/02/24 22:17:19 $