Accueil Installer Configurer Astuces Communauté Wiki Manuel

Manuel

Manuel utilisateur de NanoBlogger

by n1xt3r (Kevin Wood)

Traduit de l'anglais par Denis Bernard

Le guide officiel du moteur de blog NanoBlogger
version du 26 juillet 2008

1. Introduction

NanoBlogger est un petit moteur de blog écrit en Bash pour la commande en ligne. Il utilise les outils UNIX courants comme cat, grep et sed pour créer des contenus statiques HTML. Son utilisation ou sa modification est libre, selon les conditions de la GNU General Public License.

Synopsis

nb [-b blog_rep] [options] <actions> [<keyword> (variable)]

2. Fonctionnalités

  • interface en ligne de commande souple
  • hautement configurable et scriptable :)
  • brouillon, publication et gestion facile des entrées
  • archivage par catégorie, année, mois, jour et entrée
  • pagination
  • permaliens et liens de navigation
  • templates et feuilles de style pour la maîtrise totale de la présentation
  • dossiers pour faciliter l'emploi des templates
  • support des blogs multiples
  • support des catégories (tags) multiples
  • support des liens en adressage relatif ou absolu
  • support de la datation des entrées
  • syndication Atom (version 1.0)
  • syndication RSS (versions RSS 2.0 et 1.0)
  • plugins pour calendrier, entrées récentes, statut du blog, etc.
  • plugins pour l'édition du texte (par ex. retours à la ligne traduits en HTML)
  • configuration globale (nb.conf) et blog par blog (blog.conf);
  • mise à jour intelligente - seulement les fichiers concernés
  • dispositif simple de cache pour une meilleure efficacité
  • n'utilise pas de java-script ou de scripting côté serveur (par ex. PHP)
  • n'utilise pas de base de données externe (données enregistrées en fichiers plats)
  • support multilingue
  • portabilité multiplateforme (seulement Bash et les commandes requises)

3. Dépendances

Programmes :

Bash (au moins v2.05), cat, cp, cut, dirname, date*, grep, mkdir, mv, rm, sed, sort

* = version GNU recommandée, mais non indispensable.

4. Pour commencer

Créer un nouveau blog

Pour créer un nouveau blog (au prompt):

nb --blog-dir [monblog_rep] add weblog

monblog_rep est un répertoire inexistant. Ça créera un nouveau répertoire, copiera les fichiers par défaut dedans et finalement vous laissera éditer le fichier de configuration. Plusieurs blogs peuvent être créés de cette manière.

Pour assigner au blog un répertoire par défaut

1. éditer soit nb.conf ou $HOME/.nb.conf.
2. mettre à BLOG_DIR le répertoire du blog:
        BLOG_DIR="$HOME/public_html/[monblog_rep]"
        

Vous pouvez aussi aller sur le répertoire du blog et NanoBlogger ajustera automatiquement $BLOG_DIR pour vous : ainsi vous n'aurez pas à le spécifier en ligne de commande.

5. Installation et configuration

Pour éditer le fichier de configuration du blog, entrez :
nb --blog-dir [monblog_rep] configure update all

        
ce qui ouvre blog.conf depuis le répertoire du blog pour l'éditer, puis fait la mise à jour intégrale du blog.

Définir le navigateur

NB_BROWSER spécifie le navigateur à utiliser au lieu de celui de la variable BROWSER standard. Vous pouvez spécifier un autre navigateur en le mentionnant à NB_BROWSER dans blog.conf. Sous MacOS X, vous pourriez mettre "open". Si aucun navigateur n'est mentionné, "lynx" sera appelé.

Définir l'éditeur

NB_EDITOR spécifie l'éditeur au lieu de celui de la variable EDITOR standard. Vous pouvez spécifier un autre éditeur en le mentionnant à NB_EDITOR dans blog.conf. Si aucun éditeur n'est spécifié, "vi" sera appelé.

Définir le format des dates des nouvelles entrées

DATE_FORMAT spécifie le format de datation d'une nouvelle entrée. Par défaut, c'est celui de la commande date. Vous pouvez spécifier la localisation pour la commande "date" (voir la variable DATE_LOCALE). Vous pouvez aussi spécifier des arguments supplémentaires à la ligne de commande avec DATE_ARGS, pratique pour exprimer le temps en UTC. Veuillez noter que ces paramètres n'ont pas d'effet sur les précédentes entrées et si vous employez UTC, attention aux conditions de concurrence qui pourraient advenir, car les noms de fichier des entrées pourraient être hors synchronisation. La solution est aussi de changer DB_DATEARGS à l'identique de DATE_ARGS, ainsi ces deux là renverront la même date et heure. Lire les pages "man" de la command "date" pour voir comment personnaliser le format de sortie de la commande "date".

Exemples:

DATE_FORMAT="%m.%d.%Y %H:%M"
DATE_LOCALE="$LANG"
DATE_ARGS="-u"   

Définir le fuseau horaire

BLOG_TZD détermine le fuseau horaire des entrées de votre blog. Par défaut, c'est fait automatiquement en utilisant "%z", une extension hors standard de la commande date. Si la commande "date" de votre système ne la supporte pas, vous aurez à le spécifier.

Exemple :

BLOG_TZD="-0:500"
   

Définir l'encodage

BLOG_CHARSET mentionne le type d'encodage des caractères à employer pour votre blog.

Exemple :

BLOG_CHARSET="iso-8859-1"

AVERTISSEMENT: Si vous avez le plugin Tidy actif, cette disposition peut être changée par Tidy. Prière de vous rapporter à la documentation de Tidy pour le choix de l'encodage des caractères.

Définir le type mime

BLOG_MIMETYPE donne le type mime à être employé pour votre blog.

Exemple :

BLOG_MIMETYPE="text/html"
   

Définir l'adresse Web

BLOG_URL devrait être mis comme étant l'URL complète du blog, en excluant le fichier index et "/" le précédent.

Exemple :

BLOG_URL="http://mon-site.com/blog"
   

Définir la feuille de style

BLOG_CSS indique la feuille de style à être appelée pour votre blog. Les feuilles de style sont placées dans le répertoire styles.

Exemple :

 BLOG_CSS="styles/nb_clean.css"

Définir le favicon

BLOG_ICON indique le favicon à être appelé par votre blog. Les favicons sont placés dans le répertoire images.

Exemple :

BLOG_ICON="images/favicon.ico"

Activer l'affichage dans les liens du fichier index du répertoire

SHOW_INDEXFILE active l'affichage dans les liens du fichier index du répertoire. Par défaut mis à "1", activé.
NdT : en fait c'est l'affichage ou non de l'URL complète, avec ou sans "index.html" par ex.

Définir le nom de l'auteur

BLOG_AUTHOR peut être rempli pour mettre le nom de l'auteur; par défaut c'est le nom pris dans la variable d'environnement USER. Ainsi BLOG_AUTHOR se subsistera à cette dernière.

Définir le nombre par défaut pour "max" de Query

MAX_ENTRIES met le nombre maximal d'entrées qui seront retournées par "max" de Query. Par défaut : 10.

Définir le nombre maximal d'entrées à afficher pour toutes les pages délimitées.

MAX_PAGE_ENTRIES met le nombre maximal d'entrées affichées pour toutes les pages délimitée. Par défaut : "$MAX_ENTRIES".

MAX_CATPAGE_ENTRIES met le nombre maximal d'entrées affichées pour chaque page d'archive "catégorie". Par défaut : "$MAX_PAGE_ENTRIES". Une page archive "catégorie" sera scindée en plusieurs si le nombre d'entrées est plus grand que $MAX_CATPAGE_ENTRIES.

MAX_MONTHPAGE_ENTRIES met le nombre maximal d'entrées affichées par page d'archive "mois". Par défaut :"$MAX_PAGE_ENTRIES". Une page d'archive "mois" sera scindée en plusieurs si le nombre d'entrées est plus grand que $MAX_MONTHPAGE_ENTRIES.

MAX_MAINPAGE_ENTRIES met le nombre maximal d'entrées à afficher pour chaque page principale. Par défaut : "$MAX_PAGE_ENTRIES". La page principale sera scindée si $MAX_MAINPAGE_ENTRIES est moindre que le résultat MAINPAGE_QUERY.

Définir le nombre par défaut de Query pour la page principale

MAINPAGE_QUERY Met le nombre par défaut de Query pour la page principale. Par défaut : "max". Quand combiné avec MAX_MAINPAGE_ENTRIES, cela peut être utilisé pour la mise en pages multiples de la page principale.

Définir le format du texte par défaut

ENTRY_FORMAT spécifie le format de texte par défaut pour une nouvelle entrée. Par défaut : "raw".

Activer la création des archives des entrées

Mettre ENTRY_ARCHIVES égal à "1", active la création des archives des entrées et reconfigure les liens des entrées pointant vers leurs propre page d'archive.

Activer la création des archives mensuelles

Mettre MONTH_ARCHIVES égal à "1", active la création des archives mensuelles.

Activer la création d'archives quotidiennes

Mettre DAY_ARCHIVES égal à "1", activer la création d'archives quotidiennes et reconfigure les leins des entrées pointant vers leur propre page d'archive quand $ENTRY_ARCHIVES n'est pas activé.

Préférences d'archivage spéciales

CATARCH_DATATYPE détermine le jeu de métadonnées à charger pour la catégorie des archives.

MONTHARCH_DATATYPE détermine le jeu de métadonnées à charger pour les archives mensuelles.

DAYARCH_DATATYPE détermine le jeu de métadonnées à charger pour les archives quotidiennes.

Il y a deux types de données qui peuvent être spécifiées, "ALL" ou "NOBODY":

ALL = Totalité des métadonnées (lent et plus gros cache).
NOBODY = Tout, sauf les métadonnées dans le BODY des entrées (plus rapide et plus petit cache).

IMPORTANT : Veuillez éditer (ou créer) category_entry.htm, month_entry.htm, and day_entry.htm selon les besoins.

Définir l'ordre chronologique

CHRON_ORDER spécifie l'ordre chronologique des archives du blog. - 0/1 = normal/inverse. Par défaut mis à "1", ordre inverse.

WARNING : Si vous n'utilisez pas l'action "configure" pour changer ceci, les bases de données ne pourront pas refléter le nouvel ordre chronologique.

Définir des paramètres de prévisualisation et de publication

BLOG_PREVIEW_CMD et BLOG_PUBLISH_CMD permet d'inclure une commande personnalisée quand elles sont invoquées par leurs actions respectives preview et publish.

Définir les préférences pour le cache

MAX_CACHE_ENTRIES met le maximum d'entrées à stocker dans le cache. Par défaut : "$MAX_ENTRIES".

Mettre BLOG_CACHEMNG à "0" désactive la gestion automatique du cache. Le cache peut être géré manuellement en invoquant en ligne de commande l'action : update-cache.

Activer le mode interactif

BLOG_INTERACTIVE active le mode interactif pour votre blog et a le même effet que la commande en ligne : --interactive. Par défaut c'est "0" pour désactivé, le mettre à "1" l'activera à nouveau.

Activer l'affichage des statistiques des temps

SHOW_TIMES active les temps cumulés de l'utilisateur et du système pour le processus de construction. Ça s'avèrera probablement utile si vous n'avez pas déjà la commande "time" sur votre système. Par défaut c'est "0" pour désactivé, le mettre à "1" l'activera à nouveau.

Changer le type de fichier

NB_FILETYPE spécifie le type de fichier. En bref, le suffixe des fichiers générés. Par défaut : "html".

Changer le répertoire "Temp"

NB_TEMP_DIR spécifie l'emplacement du stockage temporaire des fichiers. Par défaut c'est "/tmp", mais il peut en être affecté un à chaque blog, pour une meilleure confidentialité et une sécurité accrue dans un environnement multi-utilisateur.

Changer le critère du mode de requête

QUERY_MODEspécifie le mode de requête par défaut pour toutes les opérations du blog. Par défaut à "all", mais peut être celui de toute requête valide. voir l'action "query" pour toutes les requêtes possibles.

Configuration des liens

ABSOLUTE_LINKS bascule entre les liens en chemin absolu ou relatif. Par défaut mis à "0", chemin relatif.

FRIENDLY_LINKS bascule entre les liens amicaux ou inamicaux. Les liens amicaux sont plus basés sur du texte, alors que les autres ont majoritairement des chiffres. Par défaut mis à "1", liens amicaux.

MAX_TITLEWIDTH fixe la largeur maximale du titre (en nombre de caractères) générés pour les liens amicaux.

SHOW_CATLINKS active l'affichage du lien de la catégorie (tag) de l'entrée; affichage par défaut.

PERMALINKS active l'affichage du permalien d'une entrée. Les permaliens sont mis par défaut.

Configuration des plugins

PLUGINS_DIR spécifie le répertoire des plugins globaux. Les plugins globaux affectent tous les blogs. Par défaut c'est : $NB_BASE_DIR/plugins.

USR_PLUGINSDIR spécifie le répertoire des plugins de l'utilisateur. Les plugins de l'utilisateur affectent le blog spécifié. Les plugins globaux peuvent être surpassés ponctuellement par les plugins utilisateur. Par exemple si vous copiez "raw.sh" dans "$BLOG_DIR/plugins/entry/format/", votre copie sera utilisée à la place du global "raw.sh". Par défaut : $BLOG_DIR/plugins.

Configuration globale

NanoBlogger possède son propre fichier de configuration, $NB_BASE_DIR/nb.conf, qui contient tous les réglages qui agissent sur tous les blogs. Le fichier de configuration globale est lu en premier ce qui signifie que les réglages propres à un blog peuvent se substituer à ceux de $NB_BASE_DIR/nb.conf. La configuration est aussi examinée dans le fichier $HOME/.nb.conf.

Changer la langue par défaut de NanoBlogger

NB_LANG est un paramètre global pour la langue à utiliser. Par défaut c'est "en" pour l'anglais. Tous les paramètres linguistiques devraient être formatés suivant la norme ISO 639-2.

Exemple pour l'espagnol :

NB_LANG="es"
    

Paramétrage linguistique

Créer des variables dans une autre langue est chose simple :

  1. démarrer avec le "en" mis par défaut;
  2. redéfinir toutes les variables dans leur traduction équivalente dans la langue cible;
  3. copier la traduction dans un sous répertoire nommé d'après son code ISO 639-2 alpha-3 ou alpha-2 code sous le répertoire "lang".

6. Gestion des entrées et des tags (catégories)

Commandes pour la gestion des entrées et des tags.

Gestion des entrées

Numérotation des entrées

La dernière entrée aura toujours le numéro "1", les entrées antérieures auront des numéros supérieurs. Une entrée peut avoir un numéro différent pour chaque catégorie à laquelle elle appartient. Quand on modifie des entrées sur la base de sa catégorie (tag), les numéros d'à la fois la catégorie et l'entrée doivent être spécifiés.

Écriture des entrées

Créer un nouveau brouillon:

nb [-b blog_rep] draft un_fichier.txt
    

Importer un brouillon comme nouvelle entrée :

nb [-b blog_rep] import entry un_fichier.txt
    

Création des entrées

Ajouter une nouvelle entrée :

nb [-b blog_rep] add entry
        
Affecter une catégorie à une nouvelle entrée :
nb [-b blog_rep] --tag <ID> add entry
        
Mettre un titre et le nom de l'auteur à la nouvelle entrée :
nb [-b blog_rep] --title "Nouvelle entrée" --author [auteur_entrée] add entry
        
Mettre un titre, le nom de l'auteur et le corps du texte pour une nouvelle entrée :
nb [-b blog_rep] --title "Nouvelle entrée" --author [auteur_entrée] --text "Ceci est ma prose." add entry
        
Importer une nouvelle entrée à partir d'un fichier :
nb [-b blog_rep] import entry un_fichier.txt

Lister les entrées

Lister les entrées :

 nb [-b blog_rep] list [<query>]
        
Lister tous les entrées par tag donné :
nb [-b blog_rep] list tag <ID>
        

Éditer les entrées

Éditer l'entrée :

nb [-b blog_rep] edit entry <ID>
        
Édition d'entrée selon un tag :
nb [-b blog_rep]--tag <ID> edit entry <ID>
        
Éditer de multiples entrées :
nb [-b blog_rep] edit entry 1,2,3
        

Affectation des entrées à des tags

Affecter un tag à une entrée donnée :

nb [-b blog_rep] --tag <ID> tag-entry <ID>
        
Affecter de multiples tags à une entrée donnée :
nb [-b blog_rep] --tag 1,2,3 tag-entry <ID>
        
Affecter un tag donné à de multiples entrées :
nb [-b blog_rep] --tag <ID> tag-entry 1,2,3
        

Supprimer des entrées

Suppression définitive d'une entrée donnée :

nb [-b blog_rep] delete entry <ID>
        
Suppression définitive de plusieurs entrées :
nb [-b blog_rep] delete entry 1,2,3
        
Suppression du tag d'une entrée donné :

1.) trouver le numéro de l'entrée depuis la liste :

nb [-b blog_rep]--tag <ID> list

2.) ôter l'entrée utilisant le numéro d'entrée trouvée dans la première étape :

nb [-b blog_rep] --tag <ID> delete entry <ID>

Changer la date des entrées

Spécifier la date d'une nouvelle entrée en utilisant le méta-tag TIMESTAMP :

nb [-b blog_dir] --var TIMESTAMP --set-var "CCYY-MM-DD HH:MM:SS" add entry
    
Changer la date d'entrée ancienne :
nb [-b blog_dir] --var TIMESTAMP --set-var "CCYY-MM-DD HH:MM:SS" edit entry <ID>
     
Changer manuellement la date d'entrée :
1. nb [-b blog_dir] edit entry <ID>
2. TIMESTAMP: YYYY-MM-DD HH:MM:SS
     
La commande "date" doit supporter l'option "-d" pour suivre le format donné par "$DATE_FORMAT".

Gestion des tags

Également connus comme catégories.

Le numéro de tag

Un numéro de tag démarre à "1". Un numéro de tag reste inchangé jusqu'à ce qu'il soit supprimé. Supprimer un tag rendra ce numéro libre pour une nouvelle création.

Commandes "tag"

Créer un nouveau tag :

nb [-b blog_rep] add tag 
        
Mettre un intitulé pour une nouveau tag :
nb [-b blog_rep] --title exemples add tag 
        
Lister les tags en cours :
nb [-b blog_rep] list tags 
        
Taguer les entrées existantes :
nb [-b blog_rep] --tag <ID> tag-entry <ID>
        
Éditer l'intitulé d'un tag :
nb [-b blog_rep] --title exemple edit tag <ID>
        
Supression d'un tag :
nb [-b blog_rep] delete tag <ID>

Gestion avancée

Employer l'action "--query" pour manipuler la liste des entrées avec lesquelles on doit agir. Premièrement, vérifier votre requête par la combinaison des actions "--query" avec "list" pour voir quel(s) numéro(s) y correspond(ent). Ensuite, le faire depuis cette requête en combinant l'action "--query" avec l'une des actions "edit", "delete", "tag-entry" ou "update"; en employant le(s) numéro(s) d'entrée en accord d'avec la précédente requête.

Éditer les entrées avec "query" :

nb [-b blog_rep] --query <all,CCYY-MM-DD,max> list
nb [-b blog_rep]--query <all,CCYY-MM-DD,max> edit entry <ID>
Supprimer des entrées avec "query" :
nb [-b blog_rep]--query <all,CCYY-MM-DD,max> list
nb [-b blog_rep]--query <all,CCYY-MM-DD,max> delete entry <ID>
Éditer des entrées avec "tag" et "query" :
nb [-b blog_rep]--tag <ID> --query <all,CCYY-MM-DD,max> list
nb [-b blog_rep]--tag <ID> --query <all,CCYY-MM-DD,max> edit entry <ID>

7. Templates

Les templates sont placés dans le sous-répertoire "templates".

Caractères spéciaux des templates

IMPORTANT: protéger ces caractères par le caractère d'échappement pour éviter qu'ils ne soient interprétés par le Shell.

Caractères spéciaux qui, placés dans des templates, sont interprétés par le Shell s'ils ne sont pas échappés :
caractères description notes
$ signe dollar protéger en le précédant d'une barre de fraction inversée, par ex. "\$"
` apostrophe inversée protéger en la précédant d'une barre de fraction inversée, par ex. "\`"
$( signe dollar et parenthèse gauche protéger en les précédant d'une barre de fraction inversée, par ex. "\$("

Templates par défaut

La présentation du blog est contrôlée par les templates suivants :
templates description
category_archive.htm contrôle la structure des pages d'archive par catégorie
day_archive.htm contrôle la structure des pages d'archive journalière
main_index.htm contrôle la structure de la page principale du blog
main_links.htm* contient les liens définis par l'utilisateur
makepage.htm template utilisé par défaut par l'action "make-page"
month_archive.htm contrôle la structure des pages d'archive mensuelles
permalink.htm contrôle la structure des pages d'archives des entrées
entry.htm contrôle la structure du contenu des entrées pour beaucoup d'archives
permalink_entry.htm contrôle la structure du contenu des entrées en archivage individuel
weblog_status.htm contrôle la structure du statut du blog
year_archive.htm contrôle la structure des pages d'archive annuelles
entry.metadata contrôle le format du méta-fichier des entrées
file.metadata contrôle le format d'un méta-fichier

Templates spéciaux

L'apparence du blog peut en outre être contrôlée par les templates suivants :
templates description
category_entry.htm contrôle la structure et le contenu de la catégorie des entrées
month_entry.htm contrôle la structure et le contenu des entrées mensuelles
day_entry.htm contrôle la structure et le contenu des entrées journalières

8. Articles et le plugin des articles

Les articles sont indépendants des archives principales du blog et procurent une façon facile et rapide d'organiser et de créer un contenu supplémentaire pour le blog. La gestion est presque entièrement faite au travers d'un gestionnaire de fichier (ou la ligne de commande). Les articles sont créés simplement depuis des métafichiers trouvés dans le répertoire des articles. La réactualisation des articles se fait à la prochaine mise à jour du blog ou par une mise à jour provoquée, selon ce qui arrive en premier. La génération de l'index et du contenu dépend du plugin 'articles'. Pour plus d'information au sujet du plugin 'articles', veuillez vous référer "*articles_meta.sh" dans À propos des plugins.

Configuration des articles

Établissement du répertoire "articles"

ARTICLES_DIR assigne le nom du répertoire "articles" pour votre blog. Par défaut : "articles". plusieurs répertoires d'articles peuvent être spécifiés.

Exemple :

  	 ARTICLES_DIR="articles articles/divers"
 
	 

Assigner le formatage du texte par défaut pour articles

ARTICLES_FORMAT assigne le formatage par défaut du texte pour les nouveaux articles. Par défaut : "raw".

Définition du suffixe par défaut pour les articles

ARTICLES_SUFFIX met le suffixe à inclure comme article dans le répertoire des articles. Par défaut : ".txt".

Assigner le template par défaut pour les articles

ARTICLES_TEMPLATE assigne le template par défaut à utiliser pour les nouveaux articles. Par défaut : "[blog_dir/]templates/makepage.htm".

Ajouter de nouveaux articles

La création de nouveaux articles est facilement faite à l'aide de la commande 'add article' :

	 nb [--title 'Exemple d'article'] add article

         

Importation d'un nouvel article (dans un sous-répertoire d'articles existant) :

 	 nb import article [blog_rep/]articles/divers/exemple.txt

  	 

Réactualisation manuelle d'articles

Réactualisation manuelle des index et contenus des articles :

 	 nb update articles

  	 

9. À propos des plugins

Cadre de fonctionnement des plugins

Plugins ordinaires : plugins

Les plugins ordinaires sont initialisés inconditionnellement après une requête de mise à jour.

Plugins d'archivage : plugins/archive

Les plugins d'archivage sont inititialisés quand les archives sont à mettre à jour.

Plugins d'archives "catégorie" : plugins/archive/category

Les plugins d'archivage "catégorie" sont inititialisés pour chaque catégorie d'archive qui soit à mettre àjour.

Plugins d'archives "jour" : plugins/archive/day

Les plugins d'archives "jour" sont inititialisés pour chaque archive journalière qui soit à mettre à jour.

Plugins d'archives "mois" : plugins/archive/month

Les plugins d'archive "mois" sont initialisés pour chaque archive mensuelle qui soit à mettre à jour.

Plugins d'archive "année" : plugins/archive/year

Les plugins d'archive "année" sont initialisés pour chaque archive annuelle qui soit à mettre à jour.

Plugins "entrée" : plugins/entry

Les plugins "entrée" sont initialisés inconditionnellement pour chaque entrée qui soit à mettre à jour.

Plugins de modification d'entrée : plugins/entry/mod

Les plugins "modification d'entrée" sont initialisés pour chaque entrée qui soit à mettre à jour.

Plugins de formatage des entrées : plugins/entry/format

Les plugins de formatage des entrées sont initialisés pour chaque entrée modifiée sur la base du champ du méta-tag FORMAT. Plus d'un format peut être spécifié avec un espace ou une virgule comme séparateur; mais en étant prudent quant à leur ordre.

Plugins "page" : plugins/page

Les plugins "page" sont initialisés inconditionnellement avant la mise à jour de chaque page.

Plugins de formatage des pages : plugins/page/format

Les plugins de formatage des pages sont initialisés à la mise à jour de chaque page sur la base du champ de la méta-donnée FORMAT. Plus d'un format peut être spécifié avec un espace ou une virgule comme séparateur, mais en étant prudent quant à leur ordre.

Plugins de fabrication des pages : plugins/makepage

Les plugins de fabrication des pages sont initialisés pour chaque page qui soit à mettre à jour.

Plugins de publication : plugins/post

Les plugins "post" sont initialisés inconditionnellement par les tâches relatives aux publications du blog.

Beaucoup de ces plugins fonctionneront suivant leurs propres règles une fois qu'ils auront été initialisés, autrement dit, plus inconditionnellement.

Plugins fournis

Plugins fournis (beaucoup sont actifs par défaut) :
plugins description variables cibles notes
archive/day/cal2daytitle.sh crée un titre personnalisé pour les archives "jour". CAL_CMD, CAL_ARGS, DATE_LOCALE $NB_ArchiveTitle requiert la commande "cal"
archive/month/month_calendar.sh génère un calendrier avec des liens sur le jour de chaque ajout CAL_CMD, CAL_ARGS, DATE_LOCALE $NB_MonthlyCalendar requiert la commande "cal"
archives/year/year_index.sh génère les archives "année" néant $ARCHIVES_DIR/$yearn/index.$NB_FILETYPE requiert le template "makepage.htm"
articles_meta.sh* génère les articles à partir des méta-fichiers dans le répertoire "articles" ARTICLES_DIR, ARTICLES_FORMAT $NB_ArticleLinks requiert le template "makepage.htm", ce plugin doit être programmé pour être le dernier à être chargé
atom.sh ajoute le flux "atom" BLOG_FEED_ITEMS, ATOM_ITEMS, ATOM_CATFEEDS, ATOM_FEED_LANG $NB_AtomVer, $NB_AtomFile, index-atom.$NB_SYND_FILETYPE néant
calendar.sh génère un calendrier avec des liens sur le jour de chaque ajout CAL_CMD, CAL_ARGS, DATE_LOCALE $NB_Calendar requiert "cal"
entry/category_links.sh génère les liens "catégorie" néant $NB_EntryCategories néant
entry/excerpt.sh* crée l'extrait du texte de l'entrée néant $NB_EntryExcerpt finit après la première détection d'un double retour à la ligne (ligne vide)
entry/format/autobr.sh converti les lignes vides en balises HTML pour former un paragraphe néant $NB_MetaBody, $NB_EntryBody FORMAT : autobr
entry/format/markdown.sh utilise "Markdown" pour le formatage MARKDOWN_CMD, MARKDOWN_OPTS $NB_MetaBody, $NB_EntryBody FORMAT : markdown
entry/mod/base_url.sh aide à la mise en chemin relatif des liens http://oceamer.com/~nanoblogger/ $NB_EntryBody exemple : <img src="http://oceamer.com/~nanoblogger/images/pic.png" />
entry/mod/moods.sh converti les variables "mood" en icônes "smiley" MOODS_URL $NB_EntryBody copie le répertoire des "moods" dans le répertoire du blog
fortune.sh génère aléatoirement des citations FORTUNE_CMD, FORTUNE_FILE $NB_Fortune requiert "fortune"
makepage/tidy.sh valide le code HTML/XML TIDY_CMD, TIDY_HTML_ARGS, TIDY_XML_ARGS $NB_Tidy, $BLOG_DIR/tidy.log requiert "HTML Tidy", surpasse $BLOG_CHARSET
mymood.sh* ajoute la possibilité d'afficher votre "mood" MOODS_URL $NB_MyMood copie le répertoire "moods" dans le répertoire du blog
page/feed_links.sh génère les "alt" des liens des flux de syndication néant $NB_AtomAltLink, $NB_RSS2AltLink, $NB_RSSAltLink requiert un des plugins "atom.sh", "rss.sh" ou "rss2.sh"
page/page_links.sh régénère les liens pour les inclure sur d'autres pages néant $NB_MainLinks, $NB_RecentEntries, $NB_CategoryLinks, $NB_MonthLinks, etc. requiert un des plugins "weblog_links.sh" ou "recent_entries.sh"
page/format/autobr.sh convertit les lignes vides en balises HTML pour former un paragraphe néant $NB_MetaBody, $NB_EntryBody FORMAT : autobr
page/format/markdown.sh utilise "Markdown" pour le formatage MARKDOWN_CMD, MARKDOWN_OPTS $NB_MetaBody, $NB_EntryBody FORMAT : markdown
page/format/moods.sh convertit les variables "mood" en icônes "smiley" MOODS_URL $NB_MetaBody, $NB_EntryBody peut se combiner avec d'autres, par ex. "FORMAT : moods, markdown"
recent_entries.sh génère les listes des entrées récentes et anciennes RECENTLIST_ENTRIES, RECENTLIST_OFFSET, RECENTLIST_MODE $NB_RecentEntries, $NB_OlderEntries néant
rss2.sh ajoute les flux rss 2.0 BLOG_FEED_ITEMS, RSS2_ITEMS, RSS2_CATFEEDS, BLOG_FEED_LANG $NB_RSS2File, index-rss.$NB_SYND_FILETYPE néant
rss.sh ajoute les flux rss 1.0 BLOG_FEED_ITEMS, RSS_ITEMS, RSS_CATFEEDS, BLOG_FEED_LANG $NB_RSSFile, index.$NB_SYND_FILETYPE none
weblog_links.sh génère quelques liens utiles ALL_YEARLINKS, MAX_YEARLINKS, ALL_MONTHLINKS, MAX_MONTHLINKS $NB_MainLinks, $NB_MonthLinks, $NB_CategoryLinks requiert le template "main_links.htm"
weblog_status.sh génères quelques statistiques néant $NB_BlogStatus requiert le template "weblog_status.htm"

* = le nom actuel peut changer

Pour désactiver un plugin individuel, renommer l'extension du plugin de ".sh" en ".off".

10. Configuration des plugins

Les configurations des plugins sont contenues et faites dans le "blog.conf" de votre blog.

Configuration des plugins de syndication

La syndication de votre blog est effectuée par les plugins de NanoBlogger. Veuillez noter qu'une adresse Internet complète et accessible est requise pour avoir une syndication correcte. Ce qui est fait en renseignant BLOG_FEED_URL. C'est mieux aussi de mettre le bon fuseau horaire pour vos flux de syndication. Pour ça, veuillez vous référer à BLOG_TZD dans Installation et configuration.

Mettre l'adresse Web

BLOG_FEED_URL Met l'URL des flux de syndication. Par défaut "$BLOG_URL", seulement s'il a déjà été mis.

Exemple :

      BLOG_FEED_URL="http://www.example.com/johndoe/weblog"

      

Mettre le fuseau horaire

BLOG_FEED_TZDmet le fuseau horaire utilisé pour les flux de syndication. Par défaut "$BLOG_TZD".

Mettre la langue

BLOG_FEED_LANG met la langue utilisée par les flux de syndication.

Exemple :

         BLOG_FEED_LANG="en-us"
     

ATOM_FEED_LANG met la langue utilisée par le flux de syndication Atom.

Exemple :

         ATOM_FEED_LANG="en"

     

NOTE: Le code langage pour les flux de syndication Atom est différent de celui du standard RSS.

Mettre le nombre maximum d'entrées à syndiquer

BLOG_FEED_ITEMS met le nombre maximum d'entrées à inclure dans vos flux de syndication, indépendemment de $MAX_ENTRIES. Par défaut mis à "10". Pour des possibilités d'exportation, vous pourriez vouloir le mettre à "-1" pour inclure toutes les entrées existantes de votre blog.

Exemple :

      BLOG_FEED_ITEMS="10"
     

Support des feuilles de style

BLOG_FEED_CSS met la feuille de style employée pour vos flux de syndication (le chemin devrait être relatif).

Exemple :

     BLOG_FEED_CSS="styles/feed.css"

     

Support des icônes & logos

BLOG_FEED_ICON met une icône pour vos flux de syndication (le chemin devrait être relatif).

Exemple :

      BLOG_FEED_ICON="images/feedicon.png"

     

BLOG_FEED_LOGO met un logo à vos flux de syndication (le chemin devrait être relatif).

Exemple :

     BLOG_FEED_LOGO="images/feedlogo.png"

     

NOTE: Dans le plugin de syndication RSS 2.0, le logo sera employé quand l'icône ne sera pas définie.

Support de la syndication des catégories

Il y a trois manières d'activer la syndication par catégorie :

  1. CATEGORY_FEEDS activer toutes les méthodes supportées de syndication de catégorie. Par défaut "0" - désactivé.
  2. ATOM_CATFEEDS activer les flux Atom par catégorie. Par défaut "0" - désactivé.
  3. RSS2_CATFEEDS activer les flux RSS 2.0 par catégorie. Par défaut "0" - désactivé.

Support pour la création des podcasts

Il y a un méta-tag appelé ENCLOSURE qui est employé pour mettre une donnée d'entrée "enclosure" pour chaque entrée. Le méta-tag ENCLOSURE devrait contenir deux jeux différents de données séparés par un simple espace. Le fichier média et le type de média (par ex. audio/mpeg).

Exemple :

     ENCLOSURE: mp3s/mypodcast.mp3 audio/mpeg

     

Le fichier média devrait être en un chemin relatif qui peut être trouvé dans $BLOG_DIR. La commande système "du -b" est requise pour obtenir la longueur du fichier média nécessaire à la donnée "enclosure". La commande "du" devrait être présente sur bien des systèmes où Bash est supporté, mais il n'y pas de garantie que la syntaxe soit la même et cela doit être vérifié manuellement. Les "enclosures" sont supportés tant pour les plugins des flux de syndication Atom que RSS2.

Vérification & correction syntaxique

Le plugin Tidy apporte la vérification et la correction syntaxique. Cette sorte d'outil peut être tout autant votre meilleur ami ou votre pire ennemi, au sens qu'il peut trop bien dissimuler (corriger) vos erreurs. Un fichier log est tenu dans le répertoire de votre blog; ainsi vous pouvez vérifier toute erreur ou changement enregistré par Tidy.

Il y a deux variables de configuration de Tidy. Une pour le HTML et l'autre pour le XML (plugins de syndication). Comme indiqué dans Installation et configuration, Tidy a tendance à ré-écrire quoique vous ayez mis à $BLOG_CHARSET. Alors, attention.

TIDY_HTML_ARGS met les arguments de la commande pour Tidy.

TIDY_XML_ARGS met les arguments de la commande pour Tidy lors de la vérification le XML des flux de syndication.

Exemples :

     TIDY_HTML_ARGS="-asxhtml -n -utf8"
     TIDY_XML_ARGS="-xml -n -utf8 -wrap 0"

     

Plus de configurations avancées incluant des personnalisations peuvent être faites à travers les plugins utilisateur.

11. Écriture des plugins

Outils pour le développement des plugins

Typiquement, les plugins sont faits pour créer des dossiers pour les templates, mais ne sont en aucun cas limités à ça. Les dossiers permettent un grand contrôle de la manière où sont placées les sorties des plugins dans le template. Quelques plugins requièrent que vous identifiez son unique dossier/destination et que vous l'ajoutiez manuellement à vos templates.

Pour écrire un plugin, vous devriez commencer par créer un fichier texte avec le suffixe ".sh". Les plugins sont ordinairement des scripts shell qui sont chargés (sourcés en terminologie du shell) selon d'où ils sont situés dans le répertoire des plugins ou l'un de ses sous répertoires. Ça peut être une bonne idée de jeter un coup d'oeil à un plugin simple comme "fortune.sh", pour avoir une idée de son fonctionnement. Quand un nouveau plugin est copié, il est nécessaire qu'il ait les droits adéquats en lecture, pour qu'il puisse être chargé par NanoBlogger. Les droits à l'exécution ne sont pas nécessaires pour les plugins.

Ce qui suit est un ensemble d'outils qui peuvent être utiles au développement de vos propres plugins.

API de plugin

API pour l'écriture de plugins.
commande description variables and commutateurs cibles notes
die sort avec un message d'erreur $@ stdout renvoie le statut de sortie "1"
nb_browser utiltaire pour le lancement d'un navigateur adapté $NB_BROWSER, $BROWSER, $1 stdout parse $BROWSER avec le séparateur ":"
nb_edit wrapper simple pour l'éditeur $NB_EDITOR, $EDITOR, $1, $2, -p = force l'invite de commande, prompt (pause) stdout si $2 est nul, alors $1 est supposé être le fichier
nb_print imprime un fichier ligne par ligne nomfichier=$1, nombre de lignes=$2 (en blanc pour tout) stdout employé à la place de "sed 1q"
nb_msg préférence du mode de verbalisation $@ stdout employé au lieu de "echo" quand c'est possible
confirm_action demande à l'utilisateur de confirmer l'action néant stdout peut être employé avec $BLOG_INTERACTIVE
chg_suffix change le suffixe d'un fichier nom du fichichier=$1, suffixe=$2 fichier peut spécifier $NB_FILETYPE, $NB_SYND_FILETYPE comme suffixe
query_db interroge les bases de données db_query=$1, db_catquery=$2, db_setlimit=$3 db_limit=$4, db_offset=$5 $DB_RESULTS exemple (extrait les entrées de 1 à 10) : "query_db all nocat limit 10 1"
lookup_id extrait le numéro d'une entrée correspondante de la base de donnée principale $1, $2 stdout exemple : lookup_id 2005-12-14T00_00_00.$NB_DATATYPE "$MASTER_DB_RESULTS"
translit_text translittération d'un texte sous une forme acceptable pour les liens web $1 stdout néant
set_baseurl aide à la mise des liens en chemin relatif node_var=$1, base_dir=$2 $BASE_URL, $ARCHIVES_PATH on ne devrait en spécifier seulement qu'un à la fois, à node_var ou à base_dir.
set_catlink met le lien et le fichier pour une catégorie donnée $1 $category_file, $category_link la catégorie devrait être au format : cat_N.$NB_DBTYPE
set_daylink met le lien et le fichier pour un jour donné $1 $day_file, $day_link le jour devrait être au format CCYY-MM-DD
set_monthlink met le lien et le fichier pour un mois donné $1 $month_file, $month_link le mois devrait être au format CCYY-MM
set_entryid met une ancre/n° pour une entrée donnée $1 stdout l'entrée devrait être au format CCYY-MM-DDTHH_MM_SS.$NB_DATATYPE
set_entrylink met le lien et le fichier pour une entrée donnée $1 $entry_dir, $permalink_file, $NB_EntryPermalink l'entrée devrait être au format CCYY-MM-DDTHH_MM_SS.$NB_DATATYPE
update_cache compile, liste ou vide le cache des entrées cache_update=$1, cache_def=$2, CACHEUPDATE_LIST=$3 $CACHE_LIST communément utilisé pour renouveler les données en cache
load_template charge le template d'un fichier TEMPLATE_FILE=$1 $TEMPLATE_DATA ne jamais charger les données template plus d'une à la fois, make_page appelle load_template
write_template écrit le template vers la sortie standard $TEMPLATE_DATA stdout "left">example: write_template > "$OUTFILE"
load_metadata charge la métadonnée d'un fichier (entrée) METADATA_TYPE=$1, $METADATA_FILE=$2 dépends de $METADATA_TYPE le type de métadonnée peut être ALL, NOBODY, BODY, TITLE, AUTHOR, DATE, DESC, FORMAT
write_metadata écrit la métadonnée sur le fichier MVAR=$1, METADATA=$2, META_FILE=$3 $META_FILE exemple : "write_metadata UPDATED "`date`" $meta-file"
read_metadata extrait la métadonnée du fichier (entrée) MVAR=$1, META_FILE=$2 $METADATA voir comme bon exemple recent_entries.sh
write_var crée/modifie le champs de la métadonnée utilisateur WRITE_MVAR=$1, WRITE_MVARVALUE=$2, WRITEMETAVAR_FILE=$3 $WRITEMETAVAR_FILE exemple : write_var MODTIME "$(date)" $meta-file
loop_archive boucle et exécute les instructions par années ou mois looparch_list=$1, looparch_type=$2, looparch_exec=$3 déterminé par $looparch_exec exemple : "query_db max; loop_archive "$DB_RESULTS" months make_monthlink"
load_entry charge les données pour les templates ENTRY_FILE=$1, ENTRY_DATATYPE=$2, ENTRY_CACHETYPE=$3 $NB_EntryTitle, $NB_EntryBody, ... voir comme bon exemple le plugin atom.sh
make_page crée les pages du blog à partir des fichiers texte MKPAGE_SRCFILE=$1, MKPAGE_TMPLFILE=$2, MKPAGE_OUTFILE=$3 $MKPAGE_CONTENT, $NB_MetaBody voir comme bon exemple le plugin articles_text.sh
weblog_page crée la page du blog à partir du méta-fichier BLOGPAGE_SRCFILE=$1, BLOGPAGE_TEMPLATE=$2, $BLOGPAGE_OUTFILE=$3 $MKPAGE_CONTENT, $NB_MetaBody voir comme bon exemple le plugin articles_meta.sh

12. Publication

Configurer la commande de publication

la variable BLOG_PUBLISH_CMD permet d'affecter une commande pour la publication sur votre blog. Ça peut être aussi simple qu'une commande FTP pour transférer des fichiers ou que des tâches plus complexe par script.

Publication à distance

FTP, SSH (scp, sftp, etc.), RSYNC ou WebDAV, sont toutes les méthodes qui peuvent être utilisées pour la publication du blog.

exemple : publier automatiquement avec ftp et .netrc.

blog.conf:
BLOG_PUBLISH_CMD="ftp exemple.weblog.com"
 
.netrc:
machine exemple.weblog.com login foo password
RIGHT!
macdef init
passive on
prompt off
lcd ~/public_html/blog
mput *.*
cd archives
lcd archives
mput *
 

Publication locale

Si vous choisissez de publier localement, vous voudrez probablement désactiver la commande de publication. Pour ce faire vous pouvez nullifier BLOG_PUBLISH_CMD par ex. BLOG_PUBLISH_CMD=""

13. Ajout du support des commentaires

Services de commentaire et add-on's :NanoBlogger Comments, CGIComment, blogkomm[1], JS-Kit[2], and Haloscan.com[3].

Choisissez l'un d'eux et suivez leurs instructions d'installation.

14. Importation des entrées

En premier lieu pour importer des entrées, les données doivent d'abord être converties au format de NanoBlogger.

Format d'une entrée

Un nom de fichier d'une entrée a pour format :

CCYY-MM-DDTHH_MM_SS.txt
        
Ainsi le fichier d'une entrée sera typiquement nommé comme suit :
2004-06-25T22_24_37.txt
        

Le format d'une entrée est fait de méta-tags. Beaucoup de ces méta-tags sont du format "VAR: VALUE" suivi d'un retour chariot qui le sépare du suivant. L'ordre des méta-tags n'est pas significatif. La variable BODY est particulière et doit être fermée par la marque END-----. Par défaut, le contenu de la variable BODY doit contenir du code HTML valide avec toutes les entités correctement protégées.

Exemple de format d'une entrée :
\TITLE: Une nouvelle entrée
\AUTHOR: toto
\DATE: Janvier 30 2004, 12:00 PM
\DESC: mots clé ou une courte ligne d'introduction
\FORMAT: raw
\-----
\BODY:
<p>Ceci est ma nouvelle entrée...</p>
\END-----
        

Conversion des entrées

Avant l'importation des entrées, elles doivent d'abord être converties dans un format précis.

Étapes de conversion des entrées :

1. Convertir chaque entrée pour qu'elle contienne les méta-tags suivants : TITLE, AUTHOR, DATE, DESC, FORMAT, BODY
2. Le méta-tag BODY doit se terminer par "END-----".
3. Renommer chaque fichier des entrées avec la date et l'heure correspondantes.
        

S'il y a de beaucoup d'entrées, ce pourrait être une bonne idée que d'automatiser tout ça par un script.

Mise à jour du répertoire "Data" du blog

Les entrées importées devraient être copiées dans le répertoire data de votre blog.
Mettre à jour le blog avec les nouvelles entrées :

nb [-b blog_rep] --force update all
        

15. Trucs et astuces

Commandes d'édition pratiques

Créer un nouveau méta-fichier :
nb [-b blog_rep] make-file un_fichier.txt
Importer le méta-fichier comme nouvelle entrée de blog :
nb [-b blog_rep] import entry un_fichier.txt
ou exporter le méta-fichier comme nouvelle page de blog :
nb [-b blog_rep] --makepage un_fichier.txt un_fichier.html
À noter que ces tâches sont plus faciles quand l'éditeur supporte un sub-shell ou quand vous pouvez suspendre votre éditeur du shell actif (en supposant qu'il y en ait un).

Écriture des méta-tags au vol

Les méta-tags sont simplement des tags qui englobent des méta-fichiers. Ainsi le formatage du texte peut être fait à partir de la ligne de commande :

nb [-b blogdir] --var FORMAT --set-var "markdown" make-page un_texte.txt un_texte.html
    

Actuellement, un seul méta-tag ne peut être spécifié qu'à la fois.

Définir un répertoire de blog par défaut

Normalement vous devez spécifier le répertoire du blog, mais en définissant BLOG_DIR, vous n'avez plus à le faire. Éditez nb.conf ou bien $HOME/.nb.conf:

BLOG_DIR="/chemin/vers/blog"
    

Désactiver les plugins

Vous pouvez souhaiter désactiver les plugins globaux ou bien tous.

Pour désactiver les plugins globaux, éditer blog.conf et changer PLUGINS_DIR d'un répertoire pré-existant :

PLUGINS_DIR="$BLOG_DIR/plugins"

Pour désactiver tous les plugins, y compris ceux de l'utilisateur, éditer blog.conf et changer PLUGINS_DIR et USR_PLUGINSDIR pour un répertoire (vide) préexistant:

 PLUGINS_DIR="$BLOG_DIR/no-plugins"
 USR_PLUGINSDIR="$BLOG_DIR/no-plugins"

Comme noté plus haut, les plugins peuvent être désactivés individuellement en changeant leur suffixe en autre chose que ".sh".

Ajout d'un script shell à vos templates

IL est possible d'employer une commande de substitution dans vos templates suivant une des formes suivantes :

        $(commande)
ou
        `commande`
                

Ajouter une introduction à votre blog

Créer un fichier texte dans le répertoire de votre blog, appelé "intro.txt". Éditer le fichier texte à votre guise, puis ajouter ce qui suit dans le template principal :

$(< "$BLOG_DIR/intro.txt")
        

Intégration de parties de votre blog dans un site Web existant

Beaucoup de parties du blog sont stockées et construites dans le répertoire parts. Disons que vous avez déjà un site Web avec vos scripts "côté serveur" maison, mais que vous aimeriez y ajouter une nouvelle section de news. C'est là que le fichier "parts/index.html" convient. Il contient les plus récentes entrées; ainsi ajouter une section news/diary/blog consiste à ajouter du code pour inclure "parts/index.html" dans la page.

Des personnes astucieuses combinent la sortie de page statique de NanoBlogger avec du PHP ou du Perl. Par exemple, supposons que vous aimiez avoir quelques liens dans la barre latérale, comme les entrées récentes : utilisant PHP, mettez votre NB_FILETYPE à "php" et modifiez le template concerné pour y inclure le code PHP qui extrait les données du répertoire "parts". Un des principaux avantages à ça est qu'il n'y a pas à reconstruire l'intégralité des archives du blog, seulement à y conserver les liens courants.

Encapsuler d'autres variables dans les templates

Tout caractère similaire à l'une des variables du shell ou d'une commande de substitution de caractère, aura à être protégé avant son inclusion dans les templates.

Exemple d'utilisation de variables dans le code PHP :

<?php
\$VAR = array ();
echo "\\\$VAR=\$VAR";
php?>
     

16. Crédits

Remerciements à Adrien "ze" Urban, Paul Drain, Pavel Janik, and O.R.Senthil Kumaran pour toutes les contributions et suggestions. Remerciements à Bowie J. Poag, l'auteur de MicroBlogger, pour l'inspiration de ce projet. Reconnaissance particulière au "Ted Walther's Diary"[4], qui inspira à Bowie la création de MicroBlogger. Enfin, merci à ceux ayant contribué à un patch ou une demande de fonctionnalité. Voir le ChangeLog.

1. http://blogkomm.com
2. http://js-kit.com
3. http://www.haloscan.com
4. http://reactor-core.org/~djw/diary/

Crédits pour la traduction française

Relecture (mise en français ) :
Hubert Lombard (versions 554 et 602)