Hobix Tutorial 1

Introduction

Hobix est un système de création et d’édition de blogs, écrit en Ruby par _Why the Lucky Stiff.

A la différence de la plupart des autres système de création de blogs, Hobix ne doit pas forcement tourner sur le système qui abritera votre blog.

Par exemple, mon blog ne peut être mis a jour qu’en envoyant les pages le constituant via FTP sur la machine dédiée par mon ISP.

Hobix peut tourner sur *nix, Mac OS X et Windows.

Il utilise de façon extensive le format YAML, à la fois pour les fichiers de configuration et pour les articles eux même.

Chaque article est contenu dans un fichier (appelé une entry). L’entry contient d’autres informations telles que le nom de l’auteur (un blog pouvant avoir plusieurs auteurs), la date de création, le titre, un sommaire.

La nature extrêmement dynamique de Ruby (et par la même de Hobix) vous permet de définir votre propre format d’entry.

La répartition des articles au sein de sections (par exemple Code, Livres, Misc) se fait a travers une structure de répertoires, dans lesquels se trouvent les articles concernés (par exemple, tous les articles de la sections Livres se trouveront dans le répertoires Livres).

Dans ce tutoriel je ne couvrirai que les bases : installer Hobix, le configurer (de façon minimale), et poster des articles.

J’essaierai de couvrir des sujets un peu plus avancés (comme ceux décrits par _why sur la mailing list) dans les tutoriaux suivants.

Installation et configuration

Hobix peut s’installer de différentes façons : en utilisant une archive tgz, en utilisant le CVS ou même en évaluant le code renvoyé par le site Web de Hobix ;) Je ne parlerai ici que de l’installation par le Web, mais les autres installations ne sont pas plus difficiles.

Prérequis

Vous devez d’abord avoir installé l’interpréteur Ruby. La dernière version de préférence, et je suggèrerai la version 1.8.2. Nous aurons aussi besoin d’une autre des productions de _why, appellée RedCloth (qui permet l’utilisation de Textile lors de la rédaction d’un article).

Vous pourrez trouver RedCloth sur rubyforge.

Installation

Pour installer via le web, il vous faut une connexion internet active et taper la ligne suivant ruby -ropen-uri -e 'eval open("http://go.hobix.com/0.3b/").read'

 

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

Nous sommes d’accord. Notez que nous installons ici la version 0.3b … En consultant le site d’Hobix vous devriez avoir accès a la dernière 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] +

Choisissons le path par défaut (appuyez sur entrée) :

* 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.. L’installeur a bien vu que la version 0.3 était déjà installée sur ma machine et va mettre a jour la version. Choisissons une fois encore le chemin par défaut :

# 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] +

Le choix par défaut …

# 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] ?

Il faut maintenant choisir la façon dont votre installation va être finalisée. En effet la copie des fichiers constituant Hobix nécessite (du moins sur les environnements dignes de ce nom) d’être éventuellement effectuée par l’administrateur (root). Si vous effectuez votre installation en tant qu’utilisateur normal, il vous faut donc choisir la façon dont vous vous identifierez (su ou sudo). Comme j’ai fait l’installation en tant que root (Arrrgggghhh), je choisis NONE (défaut) :

# here's your setup options

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

+ all set + [Yn] ?

Nous sommes d’accord avec ces valeurs (appuyez sur entrée) :

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] ? 

Configuration

Nous pouvons maintenant configurer notre système de blog (et notre blog). Appuyez donc sur entrée :

# 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]: 

Je veux que Hobix me connaisse en tant que sleeper, aussi j’appuie sur entrée :

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]: 

De même je veux qu’il utilise l’éditeur indiqué dans la variable d’environnement EDITOR.. donc … entrée. Notez que si votre variable EDITOR n’est pas séttée (un petit echo $EDITOR vous le diras), et que vous voulez qu’emacs soit votre éditeur par défaut, un petit export EDITOR="emacs", sous bash, sera suffisant .. Pour les autres shells, veuillez consulter votre page de manuel ;)

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

Nous voulons aussi qu’Hobix mette à jour le site à chaque fois que nous postons un nouvel article :

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

Hobix veut quelques informations complémentaires ….

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

On va supposer que nous serons hébergés sur http://bloggie, et que mon adresse email est 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

Notre blog s’appellera bloggie ...mais comme rien n’a encore été créé, nous appuierons sur entrée quand Hobix nous demandera le chemin qui mène au fichier de configuration de bloggie :

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

Nous pouvons laisser Hobix créer le blog. Nous voulons qu’il soit situé dans /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
On n’utilisera pas Apache dans ce tutoriel (ni vraisemblablement dans les tutoriaux futurs), aussi on appuie sur entrée à la prochaine question :
The default blog is available in the following modes:
  apache1-ssi, apache2-ssi

Mode: [Enter for none] 

Maintenant l’éditeur mentionné dans la variable d’environnement EDITOR devrait apparaître, montrant quelque chose comme :

--- !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

C’est la configuration du blog qui vient par défaut avec Hobix. Changeons le nom de l’auteur (name), ainsi que l’ url,l’ email, le lien (link), le sous-titre (tagline) (si nécessaire) et le titre (title). Notez que cela pourrait être fait par Hobix (on demandera a _why de l’inclure pour nous ;) :

--- !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

Sauvegardez et quittez l’éditeur:

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

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

Appuyez juste sur entrée, car nous ne voulons pas créer d’autre blog…

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.

Yiikkss !!! Hobix est installé et notre premier blog est configuré (avec des valeurs par défaut toutefois … ) : Vérifions que tout marche:

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.

Génération du blog

Nous pouvons maintenant demander à Hobix la génération de notre blog :

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 … quelque chose cloche … En fait les articles qui viennent avec le blog par défaut sont signés par you .. et comme ce n’est pas vous ;) On va donc remplacer cet auteur par vous, et on va le faire en suivant le “Ruby way” !

misc> ruby -i -pe 'gsub(/^author:.*$/,"author: sleeper")' weblog/bloggie/entries/*/*.yaml

(n’oubliez pas de changer le nom d’utilisateur par votre nom, ainsi que le path par le path de votre blog ..)

et essayons de générer à nouveau le 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

Bien !!! Par défaut le site est généré dans weblogs/bloggie/htdocs/ (vous pouvez modifier cela en attribuant output_path au chemin désiré, dans le fichier hobix.yaml)

Vous pouvez utiliser un navigateur pour ouvrir le fichier index.html, utiliser Apache, ou écrire votre propre serveur HTTP, en utilisant WEBRick… Copier le programme suivant, dans un fichier appelé par exemple 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

Il vous faut juste le rendre exécutable (par exemple chmod +x http-server.rb), et le lancer avec le chemin que vous voulez qu’il serve :

./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

Vous pouvez maintenant ouvrir la page http://localhost:2000 avec votre navigateur, et vous devriez voir votre blog :

Poster un article

Bon, maintenant postons notre premier article. Nous le nommerons ‘Good Morning’, et nous voulons qu’il appartienne a la section misc.

D’abord créons une section misc dans le répertoire entries :

mkdir weblogs/bloggie/entries/misc

et appelons Hobix :

hobix post bloggie misc/GoodMorning

Votre éditeur devrait apparaître, et afficher quelque chose comme :

--- !hobix.com,2004/entry
title: Good Morning
author: sleeper
content:

Notez que le nom du fichier GoodMorning est devenu le titre,’Good Morning’ (vous pouvez bien évidemment changer le titre sans avoir à changer le nom du fichier ;) Vous devez maintenant remplir la section content du fichier. N’oubliez pas que vous éditez un document YAML (alors attention aux tabulation !) et que vous pouvez utiliser Textile comme balisage :

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

Vous puvez sauver et quitter votre éditeur.

[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

Rechargez la page dans votre navigateur, et votre article devrait apparaître :

C’est tout pour ce premier tutoriel. La prochaine fois nous verrons comment réparer les liens invalides qui apparaissent sur votre blog, et comment le personnaliser en utilisant les “Quick Templates”.
Version: $Id: hobix-tut-1-fr.yaml,v 1.2 2005/02/24 22:17:19 sleeper Exp $
On: $Date: 2005/02/24 22:17:19 $