Product SiteDocumentation Site

BlazeBlogger 1.2.0

User Guide

Creating and managing websites with BlazeBlogger

Edition 1

Jaromír Hradílek

Legal Notice

Copyright © 2010, 2011 Jaromír Hradílek
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included at the end of this book.
Abstract
This book will help you obtain, install, and use BlazeBlogger 1.2.0 for managing different kinds of websites without the need of database servers or a server side scripting. Furthermore, it contains useful tips on how to set up some additional tools, as well as a complete reference of all available commands.
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Feedback
I. Introduction
1. Installation
1.1. Installing on GNU/Linux
1.1.1. Installing on Debian
1.1.2. Installing on Fedora
1.1.3. Installing on Gentoo
1.1.4. Installing on Ubuntu
1.2. Installing on Windows
1.3. Installing from the Source Code
2. Getting Started
2.1. Creating a New Blog
2.2. Configuring a Blog
2.2.1. General Blog Settings
2.2.2. Configuring an RSS Feed
2.2.3. Changing a Blog Title
2.2.4. Changing a Blog Metadata
2.2.5. Changing a Blog Author
2.2.6. Changing a Blog Language
2.2.7. Changing a Blog Theme
2.3. Adding a Blog Post or a Page
2.4. Editing a Blog Post or a Page
2.5. Removing a Blog Post or a Page
2.6. Displaying Blog Statistics
2.7. Listing Blog Posts or Pages
2.8. Generating a Blog
2.9. Displaying a Log
II. Reference
3. Core Utilities
3.1. blaze-init
3.1.1. Synopsis
3.1.2. Description
3.1.3. Options
3.1.4. Example Usage
3.1.5. See Also
3.2. blaze-config
3.2.1. Synopsis
3.2.2. Description
3.2.3. Options
3.2.4. Environment Variables
3.2.5. Files
3.2.6. Example Usage
3.2.7. See Also
3.3. blaze-add
3.3.1. Synopsis
3.3.2. Description
3.3.3. Options
3.3.4. Environment Variables
3.3.5. Example Usage
3.3.6. See Also
3.4. blaze-edit
3.4.1. Synopsis
3.4.2. Description
3.4.3. Options
3.4.4. Environment Variables
3.4.5. Example Usage
3.4.6. See Also
3.5. blaze-remove
3.5.1. Synopsis
3.5.2. Description
3.5.3. Options
3.5.4. Example Usage
3.5.5. See Also
3.6. blaze-list
3.6.1. Synopsis
3.6.2. Description
3.6.3. Options
3.6.4. Example Usage
3.6.5. See Also
3.7. blaze-make
3.7.1. Synopsis
3.7.2. Description
3.7.3. Options
3.7.4. Files
3.7.5. Example Usage
3.7.6. See Also
3.8. blaze-log
3.8.1. Synopsis
3.8.2. Description
3.8.3. Options
3.8.4. Files
3.8.5. Example Usage
3.8.6. See Also
4. UNIX Utilities
4.1. blaze.sh
4.1.1. Synopsis
4.1.2. Description
4.1.3. Options
4.1.4. Environment Variables
4.1.5. Example Usage
4.1.6. See Also
5. Windows Utilities
5.1. blaze.bat
5.1.1. Synopsis
5.1.2. Description
5.1.3. Options
5.1.4. Example Usage
5.1.5. See Also
A. BlazeBlogger Quick Reference
B. GNU Free Documentation License
C. Revision History

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 to return to your X-Windows session.
The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose System → Preferences → Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose Applications → Accessories → Character Map from the main menu bar. Next, choose Search → Find… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit → Paste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus: 
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows: 
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. Feedback

If you find an error in this book, or if you have a suggestion on how to improve it, please, let me know. To do so, either file a new bug in the official issue tracker, or send an email to the discussion group.

Part I. Introduction

Table of Contents

1. Installation
1.1. Installing on GNU/Linux
1.1.1. Installing on Debian
1.1.2. Installing on Fedora
1.1.3. Installing on Gentoo
1.1.4. Installing on Ubuntu
1.2. Installing on Windows
1.3. Installing from the Source Code
2. Getting Started
2.1. Creating a New Blog
2.2. Configuring a Blog
2.2.1. General Blog Settings
2.2.2. Configuring an RSS Feed
2.2.3. Changing a Blog Title
2.2.4. Changing a Blog Metadata
2.2.5. Changing a Blog Author
2.2.6. Changing a Blog Language
2.2.7. Changing a Blog Theme
2.3. Adding a Blog Post or a Page
2.4. Editing a Blog Post or a Page
2.5. Removing a Blog Post or a Page
2.6. Displaying Blog Statistics
2.7. Listing Blog Posts or Pages
2.8. Generating a Blog
2.9. Displaying a Log

Chapter 1. Installation

1.1. Installing on GNU/Linux
1.1.1. Installing on Debian
1.1.2. Installing on Fedora
1.1.3. Installing on Gentoo
1.1.4. Installing on Ubuntu
1.2. Installing on Windows
1.3. Installing from the Source Code
This chapter covers the installation of BlazeBlogger on various operating systems, including GNU/Linux®, and Microsoft® Windows®.

Important

To run BlazeBlogger on your system, a working installation of Perl is required, version 5.8.8 or higher.

1.1. Installing on GNU/Linux

1.1.1. Installing on Debian

BlazeBlogger is currently available in both testing (“Squeeze”) and unstable (“Sid”) version of Debian. To install it, open a terminal, and run the following command as root: 
~]# apt-get install blazeblogger

1.1.2. Installing on Fedora

BlazeBlogger is currently available in both Fedora 13 (“Goddard”) and Fedora 14 (“Laughlin”). To install it, open a terminal, and run the following command as root: 
~]# yum install blazeblogger

1.1.3. Installing on Gentoo

BlazeBlogger is currently available in Gentoo Portage. To install it, open a terminal, and run the following command as root: 
~]# emerge blazeblogger

1.1.4. Installing on Ubuntu

BlazeBlogger is currently available in both Ubuntu 10.04 LTS (“Lucid Lynx”) and Ubuntu 10.10 (“Maverick Meerkat”). To install it, open a terminal, and run the following command: 
~]$ sudo apt-get install blazeblogger

1.2. Installing on Windows

Currently, there is no installer for Microsoft® Windows®. To use BlazeBlogger there, download the latest version from the official homepage, unpack it, and use the batch files that are located in blazeblogger-1.2.0/windows/. For example: 
C:\blazeblogger-1.2.0\windows> blaze init
Alternatively, you can use BlazeBlogger with Cygwin. In that case, see Section 1.3, “Installing from the Source Code” for detailed installation instructions.

1.3. Installing from the Source Code

To install BlazeBlogger from the source code, download the latest source package from the official homepage, and unpack it: 
~]$ tar xfz blazeblogger-1.2.0.tar.gz
A directory called blazeblogger-1.2.0 will appear in the current working directory. Switch to superuser, get into the newly created directory, and type make install at a shell prompt: 
~]# cd blazeblogger-1.2.0
blazeblogger-1.2.0]# make install
This will install executables, manual pages, documentation, and application data to the /usr/local/ directory, and place Bash completion file to /etc/bash_completion.d/. To use a different installation directory, change the value of prefix on the command line. For example, if you want to install BlazeBlogger to /usr/, type the following command: 
blazeblogger-1.2.0]# make prefix=/usr install
Alternatively, you can choose to install exacutables only. For instance, to install BlazeBlogger into your home directory, type: 
blazeblogger-1.2.0]$ make prefix=$HOME install_bin
Finally, if you prefer to install all available files, but you do not have superuser privileges, change the value of compdir to a directory you have access to. For example: 
blazeblogger-1.2.0]$ make prefix=$HOME compdir='$(prefix)/etc' install

Chapter 2. Getting Started

2.1. Creating a New Blog
2.2. Configuring a Blog
2.2.1. General Blog Settings
2.2.2. Configuring an RSS Feed
2.2.3. Changing a Blog Title
2.2.4. Changing a Blog Metadata
2.2.5. Changing a Blog Author
2.2.6. Changing a Blog Language
2.2.7. Changing a Blog Theme
2.3. Adding a Blog Post or a Page
2.4. Editing a Blog Post or a Page
2.5. Removing a Blog Post or a Page
2.6. Displaying Blog Statistics
2.7. Listing Blog Posts or Pages
2.8. Generating a Blog
2.9. Displaying a Log
This chapter provides a brief introduction to BlazeBlogger and its usage, and covers how to create, configure, manage, and build a full-featured blog.

Note

On GNU/Linux, UNIX, and similar operating systems, you can use blaze-command and more convenient blaze command interchangeably. For a list of available commands, type the following at a shell prompt: 
blaze help

2.1. Creating a New Blog

To create a new blog, move into the directory in which you want to keep its working copy, and type the following at a shell prompt: 
blaze-init
This creates a hidden directory, .blaze/, in which the blog data are stored. The actual content of this directory is not important, and it is recommended that you never touch the files in it directly.
To recover its content should it ever be damaged, use the same command again. You can also revert the existing configuration, theme, and language files to their initial state by supplying the --force (or -f for short) command line option: 
blaze-init -f
For a complete list of available command line options, refer to Section 3.1, “blaze-init”.
Example 2.1. Creating a New Blog in the ~/public_html/ Directory
Many web servers are able to serve content from a certain directory within user's home directory, typically ~/public_html/. You can start a new blog in this directory by typing the following command: 
public_html]$ blaze-init
Created a BlazeBlogger repository in .blaze.

2.2. Configuring a Blog

In an attempt to make complex changes to the configuration as painless as possible, BlazeBlogger is shipped with a utility to help you with this task. To display the current value of a particular configuration option, use the blaze-config command followed by an option name: 
blaze-config option
To change a configuration option, supply the new value: 
blaze-config option value…
BlazeBlogger also allows you to edit all available options at once in an external text editor. To do so, run the blaze-config command with the --edit (or -e) command line option: 
blaze-config -e
Note that unless the core.editor configuration option is already set, you must also specify a text editor to use by adding the --editor (or -E) option: 
blaze-config -e -E editor
The rest of this section tries to cover the most common configuration tasks, and by no means serves as a full reference. For a complete list of available configuration options, refer to Section 3.2, “blaze-config”.
Example 2.2. Configuring the Blog in GVim
To edit the configuration in the GVim text editor, run: 
public_html]$ blaze-config -e -E "gvim -f"
You can set this editor as the default by typing the following command: 
public_html]$ blaze-config core.editor "gvim -f"

2.2.1. General Blog Settings

In order for web browsers to correctly determine the character encoding of a blog, each web page must include an appropriate information in its header. To change this information, update the core.encoding option with a value in the form that is recognized by W3C standards: 
blaze-config core.encoding encoding
Keep in mind that this option must match the character encoding you use to write the content. BlazeBlogger does not change the encoding on its own, nor does it check the value you provided. The default option is UTF-8.
To select the document type of the generated pages, use the following command: 
blaze-config core.doctype type
Allowed options are html for HTML and xhtml for the XHTML standard. For compatibility reasons, the default option is to generate HTML pages.
Finally, to change the file extension of the generated pages, run: 
blaze-config core.extension extension
The changes will take effect the next time you build the blog with the blaze-make command.
Example 2.3. Changing the Blog Encoding
In most cases, the use of UTF-8 is recommended. However, if you write your blog in other encoding such as ISO-8859-2 (that is, Latin-2), type: 
public_html]$ blaze-config core.encoding ISO-8859-2
The option has been successfully saved.

2.2.2. Configuring an RSS Feed

To enable the creation of an RSS feed with the syndication of blog updates, supply a valid URL with the location of the blog, making sure that you include the http:// (or https:// if you use a secure protocol) prefix: 
blaze-config feed.baseurl url
The feed will be created the next time you build the blog with the blaze-make command.
Example 2.4. Enabling the Creation of an RSS Feed
To enable an RSS feed for a blog located at http://blaze.blackened.cz/, type the following at a shell prompt: 
public_html]$ blaze-config feed.baseurl http://blaze.blackened.cz/
The option has been successfully saved.

2.2.3. Changing a Blog Title

To change the title of a blog, use the following command: 
blaze-config blog.title title
Beside this option, BlazeBlogger also allows you to specify the subtitle. This is typically a brief description of the blog, or a motto. To change the blog subtitle, run: 
blaze-config blog.subtitle subtitle
The changes will take effect the next time you run the blaze-make command.
Example 2.5. Changing the Blog Title and Subtitle
To change the blog title to “BlazeBlogger” and the corresponding subtitle to “a CMS without boundaries”, type the following commands at a shell prompt: 
public_html]$ blaze-config blog.title BlazeBlogger
The option has been successfully saved.
public_html]$ blaze-config blog.subtitle a CMS without boundaries
The option has been successfully saved.

2.2.4. Changing a Blog Metadata

To change the descrption of a blog, run the following command: 
blaze-config blog.description description
To specify a comma-separated list of keywords that characterize the blog, type: 
blaze-config blog.keywords keywords
The changes will take effect the next time you run the blaze-make command.
Example 2.6. Changing the Blog Description and Keywords
To change the blog description to “a CMS without boundaries” and keywords to “blazeblogger”, “cms”, and “blog”, type the following at a shell prompt: 
public_html]$ blaze-config blog.description a CMS without boundaries
The option has been successfully saved.
public_html]$ blaze-config blog.keywords blazeblogger, cms, blog
The option has been successfully saved.

2.2.5. Changing a Blog Author

To change the name of the author of a blog, run: 
blaze-config user.name full_name
This name appears in the copyright notice, and is used as the default author for a new blog post or page. However, if you prefer to keep the full name in the copyright notice only, you can specify a nickname by using the following command: 
blaze-config user.nickname nickname
Additionally, you can supply an email address to allow readers to contact the blog author directly: 
blaze-config user.email email_address
The changes will take effect the next time you run the blaze-make command.
Example 2.7. Changing the Author Information
To change the author's name to “Jaromír Hradílek”, author's nickname to “Blackened”, and the email address to “jhradilek@gmail.com”, type: 
public_html]$ blaze-config user.name Jaromír Hradílek
The option has been successfully saved.
public_html]$ blaze-config user.nickname Blackened
The option has been successfully saved.
public_html]$ blaze-config user.email jhradilek@gmail.com
The option has been successfully saved.

2.2.6. Changing a Blog Language

To use a non-English translation of a blog, copy an appropriate language file to the .blaze/lang/ directory, and configure the blog to use this translation: 
blaze-config blog.lang language_code
The changes will take effect the next time you run the blaze-make command.
Example 2.8. Using the Basque Translation
When installing BlazeBlogger on Linux, UNIX, and similar operating systems from the source code, by default, all available language files are copied to the /usr/local/share/blazeblogger/lang/ directory. On such system, you can change the translation of your blog to the Basque language by running the following commands: 
public_html]$ cp /usr/local/share/blazeblogger/lang/eu_ES .blaze/lang/
public_html]$ blaze-config blog.lang eu_ES
The option has been successfully saved.

2.2.7. Changing a Blog Theme

To change the theme of a blog, copy the relevant files to the blog directory, and move the template and style sheet to .blaze/theme/ and .blaze/style/ respectively. Then change the configuration to use this theme by typing the following at a shell prompt: 
blaze-config blog.theme template_file
blaze-config blog.style stylesheet_file
The changes will take effect the next time you run the blaze-make command.
Example 2.9. Installing the VectorLover Theme
To install the VectorLover theme on Linux, UNIX, and similar operating systems, download the archive from the website and extract its content to the directory with .blaze/: 
public_html]$ wget http://blaze.blackened.cz/files/theme/vectorlover-1.0.2.tar.gz
--2011-02-14 00:53:07--  http://blaze.blackened.cz/files/theme/vectorlover-1.0.2.tar.gz
Resolving blaze.blackened.cz... 87.236.199.95
Connecting to blaze.blackened.cz|87.236.199.95|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 59972 (59K) [application/x-gzip]
Saving to: "vectorlover-1.0.2.tar.gz"

100%[======================================>] 59,972      --.-K/s   in 0.1s    

2011-02-14 00:53:08 (397 KB/s) - "vectorlover-1.0.2.tar.gz" saved [59972/59972]

public_html]$ tar xfz vectorlover-1.0.2.tar.gz
Then move the template file and the corresponding style sheet to .blaze/theme/ and .blaze/style/ respectively: 
public_html]$ mv vectorlover.html .blaze/theme/
public_html]$ mv vectorlover.css .blaze/style/
Finally, change the configuration to use this theme: 
public_html]$ blaze-config blog.theme vectorlover.html
The option has been successfully saved.
public_html]$ blaze-config blog.style vectorlover.css
The option has been successfully saved.

2.3. Adding a Blog Post or a Page

To write a new blog post, run the following command: 
blaze-add
To write a new page, add the --page (or -p) command line option: 
blaze-add -p
This opens an external text editor with a pre-formatted header and brief instructions on how to compose a blog entry.
The blog post or page header contains important metadata, such as the title, author, or date of publishing of the entry. For a detailed explanation of all available options, refer to Table 2.1, “A List of Available Header Options”.
Table 2.1. A List of Available Header Options
Option Type Description
title Mandatory Specifies the title of the blog post or page.
author Mandatory Specifies the author of the blog post or page. The value of the user.name (or user.nickname if supplied) configuration option is used by default.
date Mandatory Specifies the date of publishing of the blog post or page, and has to be in the YYYY-MM-DD format. The current date is used by default.
keywords Optional Allows you to specify a comma-separated list of keywords that are specific for the blog post or page.
tags Optional Allows you to specify a comma-separated list of categories the blog post belongs to. This option is not relevant for pages.
url Optional Allows you to specify the string to be used in the URL. It must contain alphanumeric characters, hyphens, and underscores only.

Besides ordinary elements defined by the HTML or XHTML standard, BlazeBlogger recognizes several special forms that can be used in the text itself. This includes various placeholders that ensure the cross-references within a particular blog are valid and always point to the expected target. For a complete list of these special forms, refer to Table 2.2, “A List of Special Forms and Placeholders”.
Table 2.2. A List of Special Forms and Placeholders
Form Description
<!-- break --> Delimits a blog post synopsis.
%root% Is replaced with a relative path to the root directory of the blog.
%home% Is replaced with a relative path to the index page of the blog.
%page[id]% Is replaced with a relative path to a page with the given id.
%post[id]% Is replaced with a relative path to a blog post with the given id.
%tag[name]% Is replaced with a relative path to a tag with the given name.

Refer to Section 3.3, “blaze-add” for a full description of the blaze-add utility and its usage.
Example 2.10. Writing a Blog Post
To open an external editor in order to write a new blog post, type: 
public_html]$ blaze-add
The blog post itself may look like the following: 
# This and the following lines beginning with '#' are the blog post header.
# Please take your time and replace these options with desired values. Just
# remember that the date has to be in the YYYY-MM-DD form, tags are a comma
# separated list of categories the post (pages ignore these) belong to, and
# the url,  if provided, should consist of alphanumeric characters, hyphens
# and underscores only.  Specifying your own url  is especially recommended
# in case you use non-ASCII characters in your blog post title.
#
#   title:    BlazeBlogger 1.1.1
#   author:   Jaromír Hradílek
#   date:     2010-10-30
#   keywords: release, bug fix
#   tags:     release
#   url:
#
# The header ends here. The rest is the content of your blog post.

<p>
  BlazeBlogger 1.1.1 has been released! This release fixes four bugs that may have caused BlazeBlogger to sort entries in a wrong order, produce invalid RSS feed, or not to run properly when using an older version of Perl.
</p>

<!-- break -->

<h3>Bug Fixes</h3>

<ul>
  <li>
    When the <code>feed.fullposts</code> configuration option was disabled, all HTML/XHTML entities were removed. However, this may have led to an invalid output. With this update, such entities are no longer stripped out, and the RSS feed is now created as expected. (<a href="http://code.google.com/p/blazeblogger/issues/detail?id=18">Issue 18</a>, <a href="http://code.google.com/p/blazeblogger/issues/detail?id=29">29</a>)
  </li>
  <li>
    Due to incorrect use of the <code>cmp</code> operator, both <code>blaze-list</code> and <code>blaze-make</code> utilities may have listed blog posts in a wrong order. With this update, the comparison subroutine has been corrected, so that all entries are now sorted in a correct order. (<a href="http://code.google.com/p/blazeblogger/issues/detail?id=26">Issue 26</a>)
  </li>
  <li>
    <p>When using an older version of Perl, attempting to run the <code>blaze-make</code> utility may have failed with the following error message:</p>
    <pre>blaze-make: Creating `': mkdir : No such file or directory</pre>
    <p>This error no longer occurs, and <code>blaze-make</code> now produces the expected output. (<a href="http://code.google.com/p/blazeblogger/issues/detail?id=30">Issue 30</a>)</p>
  </li>
</ul>

2.4. Editing a Blog Post or a Page

To edit an existing blog, run the blaze-edit command followed by an appropriate identification number: 
blaze-edit id
To edit a page, add the --page (or -p) command line option: 
blaze-edit -p id
For a complete list of available command line options, refer to Section 3.4, “blaze-edit”.
Example 2.11. Editing a Blog Post
To edit a blog post with id 10, type the following at a shell prompt: 
public_html]$ blaze-edit 10

2.5. Removing a Blog Post or a Page

To delete a blog post from your blog, run the blaze-remove command followed by an appropriate identification number: 
blaze-remove id
To delete a page, add the --page (or -p) command line option: 
blaze-remove -p id
For a complete list of available command line options, refer to Section 3.5, “blaze-remove”.

Warning

Be careful when using this command, as there is no easy way to take this action back. To prevent an accidental loss of potentially valuable data, run the command in the interactive mode by supplying the --interactive (or -i) option: 
blaze-remove -i id
Example 2.12. Removing a Blog Post Safely
Interactive mode gives you one last chance to ensure you are deleting a correct blog entry. To initiate the removal of a blog post with id 10 and then abort it, type the following at a shell prompt: 
public_html]$ blaze-remove -i 10
Remove the post with ID 10 titled `Debian and Fedora Packages'? n
Aborted.

2.6. Displaying Blog Statistics

To display detailed information about blog statistics, including the total number of blog posts and pages, the date of the very first blog post, and the date of the latest published post, use the blaze-list with the --stats (or -S) command line option: 
blaze-list -S
You can also display the short version of the above output by supplying the --short (or -s) command line option as well: 
blaze-list -Ss
Example 2.13. Displaying Blog Statistics
To display detailed blog statistics, type the following at a shell prompt: 
public_html]$ blaze-list -S
Number of pages: 5
Number of posts: 11
Last post date:  2010-07-25
First post date: 2009-02-10
To display the same information on a single line, type: 
public_html]$ blaze-list -Ss
There is a total number of 11 blog posts and 5 pages in the repository.

2.7. Listing Blog Posts or Pages

To make the management of blog posts and pages easier, BlazeBlogger is shipped with the blaze-list utility that allows you to display the content of a blog. This includes the important information such as the identification number, date of publishing, title, and attached tags.

Note

Since version 0.9.0, BlazeBlogger allows you to enable a colored output for some of its utilities. To enable this feature for blaze-list, use the following command: 
blaze-config color.list true
To display all featured blog posts, type the following at a shell prompt: 
blaze-list
Similarly, to display a complete list of available pages, add the --pages (or -p) command line option: 
blaze-list -p
By default, the latest entries are listed first, and in most cases, this is a reasonable behavior. However, to change the sorting order and display the latest entries last, use the --reverse (or -r) option: 
blaze-list -r
You can also limit the number of listed entries by specifying the --number (or -n) option. 
blaze-list -n number
Additionally, you can limit the output by specifying a blog post author (--author or -a), a tag (--tag or -T), a matching title (--title or -T), a date of publishing, and other criteria.
For a complete list of available command line options, refer to Section 3.6, “blaze-list”.
Example 2.14. Identifying the Very First Blog Post
To display only the information about the first blog post, type the following at a shell prompt: 
public_html]$ blaze-list -n 1 -r
ID: 1 | 2009-02-10 | Jaromír Hradílek

    Title: BlazeBlogger 0.7.0
    Tags:  release

2.8. Generating a Blog

To generate a complete directory tree of static pages with all blog posts, single pages, monthly and yearly archives, tags, and an RSS feed, run the following command: 
blaze-make
Unless told otherwise, BlazeBlogger generates the blog in the current working directory. To use a different location, specify the --destdir (or -d) command line option: 
blaze-make -d directory
To display the list of files as they are created, use --verbose (or -V) command line option: 
blaze-make -V
For a complete list of available command line options, refer to Section 3.7, “blaze-make”.

Note

If you intend your blog to be accessed offline, for example, if you want to review it before you publish it on your website, use the --full-paths (or -F) option: 
blaze-make -F
This option ensures that all generated links point directly to index pages, and not to their parent directories. Additionally, you can turn off the creation of the RSS feed as well. To do so, add the --no-rss (or -r) option: 
blaze-make -Fr
Example 2.15. Generating a Blog Preview
To generate a preview of your blog with a list of created files written to standard output, type the following at a shell prompt: 
public_html]$ blaze-make -VF
Created index.rss
Created index.html
Created index1.html
Created 2010/10/index.html
Created 2010/07/11-join-blazeblogger-on-irc/index.html
Created 2009/12/10-debian-and-fedora-packages/index.html
Created 2009/index.html
Created 2010/07/index.html
etc.
Done.

2.9. Displaying a Log

For the possibility of a future review, BlazeBlogger keeps track of all significant changes to the blog, including its initialization and recovery, addition of new content, changes to existing blog posts and pages, and their removal.

Note

Since version 0.9.0, BlazeBlogger allows you to enable a colored output for some of its utilites. To enable this feature for blaze-log, use the following command: 
blaze-config color.log true
To display the complete history of the blog, type the following at a shell prompt: 
blaze-log
By default, log entries are sorted from the newest to oldest, so that the latest change is listed at the top. If you prefer the reverse order, use the --reverse (or -r) command line option: 
blaze-log -r
Finally, to display only a limited number of log entries, specify the --number (or -n) command line option: 
blaze-log -n number
For a complete list of available command line options, refer to Section 3.8, “blaze-log”.
Example 2.16. Identifying the Last Change to a Blog
To display only the last change to a blog, type the following at a shell prompt: 
public_html]$ blaze-log -n 1
Date: Sun Jul 25 16:48:22 2010

    Edited the page with ID 5.

Part II. Reference

Table of Contents

3. Core Utilities
3.1. blaze-init
3.1.1. Synopsis
3.1.2. Description
3.1.3. Options
3.1.4. Example Usage
3.1.5. See Also
3.2. blaze-config
3.2.1. Synopsis
3.2.2. Description
3.2.3. Options
3.2.4. Environment Variables
3.2.5. Files
3.2.6. Example Usage
3.2.7. See Also
3.3. blaze-add
3.3.1. Synopsis
3.3.2. Description
3.3.3. Options
3.3.4. Environment Variables
3.3.5. Example Usage
3.3.6. See Also
3.4. blaze-edit
3.4.1. Synopsis
3.4.2. Description
3.4.3. Options
3.4.4. Environment Variables
3.4.5. Example Usage
3.4.6. See Also
3.5. blaze-remove
3.5.1. Synopsis
3.5.2. Description
3.5.3. Options
3.5.4. Example Usage
3.5.5. See Also
3.6. blaze-list
3.6.1. Synopsis
3.6.2. Description
3.6.3. Options
3.6.4. Example Usage
3.6.5. See Also
3.7. blaze-make
3.7.1. Synopsis
3.7.2. Description
3.7.3. Options
3.7.4. Files
3.7.5. Example Usage
3.7.6. See Also
3.8. blaze-log
3.8.1. Synopsis
3.8.2. Description
3.8.3. Options
3.8.4. Files
3.8.5. Example Usage
3.8.6. See Also
4. UNIX Utilities
4.1. blaze.sh
4.1.1. Synopsis
4.1.2. Description
4.1.3. Options
4.1.4. Environment Variables
4.1.5. Example Usage
4.1.6. See Also
5. Windows Utilities
5.1. blaze.bat
5.1.1. Synopsis
5.1.2. Description
5.1.3. Options
5.1.4. Example Usage
5.1.5. See Also

Chapter 3. Core Utilities

3.1. blaze-init
3.1.1. Synopsis
3.1.2. Description
3.1.3. Options
3.1.4. Example Usage
3.1.5. See Also
3.2. blaze-config
3.2.1. Synopsis
3.2.2. Description
3.2.3. Options
3.2.4. Environment Variables
3.2.5. Files
3.2.6. Example Usage
3.2.7. See Also
3.3. blaze-add
3.3.1. Synopsis
3.3.2. Description
3.3.3. Options
3.3.4. Environment Variables
3.3.5. Example Usage
3.3.6. See Also
3.4. blaze-edit
3.4.1. Synopsis
3.4.2. Description
3.4.3. Options
3.4.4. Environment Variables
3.4.5. Example Usage
3.4.6. See Also
3.5. blaze-remove
3.5.1. Synopsis
3.5.2. Description
3.5.3. Options
3.5.4. Example Usage
3.5.5. See Also
3.6. blaze-list
3.6.1. Synopsis
3.6.2. Description
3.6.3. Options
3.6.4. Example Usage
3.6.5. See Also
3.7. blaze-make
3.7.1. Synopsis
3.7.2. Description
3.7.3. Options
3.7.4. Files
3.7.5. Example Usage
3.7.6. See Also
3.8. blaze-log
3.8.1. Synopsis
3.8.2. Description
3.8.3. Options
3.8.4. Files
3.8.5. Example Usage
3.8.6. See Also
This chapter provides a thorough description of core BlazeBlogger utilities and their respective command line options.

3.1. blaze-init

blaze-init creates a BlazeBlogger repository, or recovers a previously corrupted one.

3.1.1. Synopsis

blaze-init [-fqV] [-b directory]

blaze-init -h|-v

3.1.2. Description

blaze-init either creates a fresh new BlazeBlogger repository, or recovers an existing one in case it is corrupted. Optionally, it can also revert a configuration and default templates to their original state, leaving all user data (that is, both blog posts and pages) intact.

3.1.3. Options

-b directory, --blogdir directory
Allows you to specify a directory in which the BlazeBlogger repository is to be blaced. The default option is a current working directory.
-f, --force
Reverts existing configuration, theme, and language files to their initial state. By default, these files are kept intact.
-q, --quiet
Disables displaying of unnecessary messages.
-V, --verbose
Enables displaying of all messages, including a list of created files.
-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

3.1.4. Example Usage

  • Create a new blog in a current directory: 
    ~]$ blaze-init
Created a BlazeBlogger repository in .blaze.
  • Create a new blog in ~/public_html: 
    ~]$ blaze-init -b ~/public_html
Created a BlazeBlogger repository in /home/jhradilek/public_html/.blaze.
  • Revert a configuration file and default templates to their initial state: 
    ~]$ blaze-init -f
Recovered a BlazeBlogger repository in .blaze.
    Or if you want to see what files have been reverted: 
    ~]$ blaze-init -fV
Created .blaze/config
Created .blaze/theme/default.html
Created .blaze/style/default.css
Created .blaze/lang/en_US
Recovered a BlazeBlogger repository in .blaze.

3.1.5. See Also

Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.
Section 3.3, “blaze-add”
blaze-add adds a blog post or a page to the BlazeBlogger repository.

3.2. blaze-config

blaze-config displays or sets BlazeBlogger configuration options.

3.2.1. Synopsis

blaze-config [-qV] [-b directory] [-E editor] option [value…]

blaze-config -e [-b directory]

blaze-config -h|-v

3.2.2. Description

blaze-config either sets BlazeBlogger configuration options, or displays their current value. Additionally, it can also open a configuration file in an external text editor.

3.2.3. Options

3.2.3.1. Command Line Options

-b directory, --blogdir directory
Allows you to specify a directory in which the BlazeBlogger repository is placed. The default option is a current working directory.
-E editor, --editor editor
Allows you to specify an external text editor. When supplied, this option overrides the relevant configuration option.
-e, --edit
Allows you to edit the configuration in a text editor.
-q, --quiet
Disables displaying of unnecessary messages.
-V, --verbose
Enables displaying of all messages. This is the default option.
-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

3.2.3.2. Configuration Options

blog.title=string
A title of your blog.
blog.subtitle=string
A subtitle of your blog.
blog.description=string
A brief description of your blog.
blog.keywords=list
A comma-separated list of keywords.
blog.theme=string
A theme for your blog. Note that it must point to an existing file in the .blaze/theme/ directory. The default option is default.html.
blog.style=string
A style sheet for your blog. Note that it must point to an existing file in the .blaze/style/ directory. The default option is default.css.
blog.lang=string
A translation of your blog. Note that it must point to an existing file in the .blaze/lang/ directory. The default option is en_US.
blog.posts=integer
A number of blog posts to be listed on a single page. The default option is 10.
color.list=boolean
A boolean to enable (true) or disable (false) colors in the blaze-list output. The default option is false.
color.log=boolean
A boolean to enable (true) or disable (false) colors in the blaze-log output. The default option is false.
core.doctype=string
A document type. It can be either html for HTML, or xhtml for the XHTML standard. The default option is html.
core.extension=string
A file extension. The default option is html.
core.encoding=string
A character encoding. Note that it has to be in a form that is recognized by W3C standards. The default option is UTF-8.
core.editor=string
An external text editor. When supplied, this option overrides the system-wide settings.
core.processor=string
An external application to be used to process newly added or edited blog posts and pages. Note that you must supply %in% and %out% in place of an input and output file name respectively. This option is disabled by default.
feed.baseurl=string
A URL of your blog, for example http://example.com.
feed.posts=integer
A number of blog posts to be listed in the feed. The default option is 10.
feed.fullposts=boolean
A boolean to enable (true) or disable (false) inclusion of the whole content of a blog post in the feed, even though the <!-- break --> form is used. The default option is false.
post.author=string
A location of a blog post author name. It can be placed above the post (top), below it (bottom), or nowhere on the page (none). The default option is top.
post.date=string
A location of a date of publishing, as it can either be placed above the post (top), below it (bottom), or nowhere on the page (none). The default option is top.
post.tags=string
A location of post tags, as they can either be placed above the post (top), below it (bottom), or nowhere on the page (none). The default option is top.
user.name=string
Your full name to be used in the copyright notice, and as the default post author. The default option is admin.
user.nickname=string
Your nickname to be used as the default post author. When supplied, it overrides the user.name setting. This option is disabled by default.
user.email=string
Your email address. The default option is admin@localhost.

3.2.4. Environment Variables

EDITOR
Unless the core.editor option is set, blaze-config tries to use system-wide settings to decide which editor to use.

3.2.5. Files

.blaze/config
A file containing the configuration.
.blaze/theme/
A directory containing blog themes.
.blaze/style/
A directory containing style sheets.
.blaze/lang/
A directory containing language files.

3.2.6. Example Usage

  • Configure the default text editor: 
    ~]$ blaze-config core.editor nano
The option has been successfully saved.
  • Configure the user information: 
    ~]$ blaze-config user.name Jaromir Hradilek
The option has been successfully saved.
~]$ blaze-config user.email jhradilek@gmail.com
The option has been successfully saved.
  • Configure the blog appearance: 
    ~]$ blaze-config blog.title BlazeBlogger
The option has been successfully saved.
~]$ blaze-config blog.subtitle a CMS without boundaries
The option has been successfully saved.
~]$ blaze-config blog.theme keepitsimple.html
The option has been successfully saved.
~]$ blaze-config blog.style keepitsimple.css
The option has been successfully saved.
  • Configure the RSS feed: 
    ~]$ blaze-config feed.fullposts true
The option has been successfully saved.
~]$ blaze-config feed.posts 10
The option has been successfully saved.
~]$ blaze-config feed.baseurl http://blaze.blackened.cz/
The option has been successfully saved.
  • Open the configuration in a text editor: 
    ~]$ blaze-config -e

3.2.7. See Also

Section 3.1, “blaze-init”
blaze-init creates a BlazeBlogger repository, or recovers a previously corrupted one.

3.3. blaze-add

blaze-add adds a blog post or a page to the BlazeBlogger repository.

3.3.1. Synopsis

blaze-add [-pqCPV] [-b directory] [-E editor] [-a author] [-d date] [-k keywords] [-t title] [-T tags] [-u url] [file…]

blaze-add -h|-v

3.3.2. Description

blaze-add adds a blog post or a page to the BlazeBlogger repository. If a file is supplied, it adds the content of that file, otherwise an external text editor is opened for you. Note that there are several special forms and placeholders that can be used in the text, and that will be replaced with a proper data when the blog is generated.

3.3.2.1. Special Forms

<!-- break -->
A mark to delimit a blog post synopsis.

3.3.2.2. Placeholders

%root%
A relative path to the root directory of the blog.
%home%
A relative path to the index page of the blog.
%page[id]%
A relative path to a page with the supplied id.
%post[id]%
A relative path to a blog post with the supplied id.
%tag[name]%
A relative path to a tag with the supplied name.

3.3.3. Options

-b directory, --blogdir directory
Allows you to specify a directory in which the BlazeBlogger repository is placed. The default option is a current working directory.
-E editor, --editor editor
Allows you to specify an external text editor. When supplied, this option overrides the relevant configuration option.
-t title, --title title
Allows you to specify the title of a blog post or page.
-a author, --author author
Allows you to specify the author of a blog post or page.
-d date, --date date
Allows you to specify the date of publishing of a blog post or page.
-k keywords, --keywords keywords
Allows you to specify a comma-separated list of keywords attached to a blog post or page.
-T tags, --tags tags
Allows you to supply a comma-separated list of tags attached to a blog post.
-u url, --url url
Allows you to specify the url of a blog post or page. Allowed characters are letters, numbers, hyphens, and underscores.
-p, --page, --pages
Tells blaze-add to add a page or pages.
-P, --post, --posts
Tells blaze-add to add a blog post or blog posts. This is the default option.
-C, --no-processor
Disables processing a blog post or page with an external application. For example, if you use Markdown to convert the lightweight markup language to the valid HTML output, this will enable you to write this particular post in plain HTML directly.
-q, --quiet
Disables displaying of unnecessary messages.
-V, --verbose
Enables displaying of all messages. This is the default option.
-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

3.3.4. Environment Variables

EDITOR
Unless the core.editor option is set, blaze-add tries to use system-wide settings to decide which editor to use.

3.3.5. Example Usage

  • Write a new blog post in an external text editor: 
    ~]$ blaze-add
  • Add a new blog post from a file: 
    ~]$ blaze-add new_packages.txt
Successfully added the post with ID 10.
  • Write a new page in an external text editor: 
    ~]$ blaze-add -p
  • Write a new page in nano: 
    ~]$ blaze-add -p -E nano

3.3.6. See Also

Section 3.1, “blaze-init”
blaze-init creates a BlazeBlogger repository, or recovers a previously corrupted one.
Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.
Section 3.4, “blaze-edit”
blaze-edit edits a blog post or a page in the BlazeBlogger repository.
Section 3.5, “blaze-remove”
blaze-remove removes a blog post or a page from the BlazeBlogger repository.
Section 3.7, “blaze-make”
blaze-make generates a blog from the BlazeBlogger repository.

3.4. blaze-edit

blaze-edit edits a blog post or a page in the BlazeBlogger repository.

3.4.1. Synopsis

blaze-edit [-fpqCPV] [-b directory] [-E editor] id

blaze-edit -h|-v

3.4.2. Description

blaze-edit opens an existing blog post or a page with the specified id in an external text editor. Note that there are several special forms and placeholders that can be used in the text, and that will be replaced with a proper data when the blog is generated.

3.4.2.1. Special Forms

<!-- break -->
A mark to delimit a blog post synopsis.

3.4.2.2. Placeholders

%root%
A relative path to the root directory of the blog.
%home%
A relative path to the index page of the blog.
%page[id]%
A relative path to a page with the supplied id.
%post[id]%
A relative path to a blog post with the supplied id.
%tag[name]%
A relative path to a tag with the supplied name.

3.4.3. Options

-b directory, --blogdir directory
Allows you to specify a directory in which the BlazeBlogger repository is placed. The default option is a current working directory.
-E editor, --editor editor
Allows you to specify an external text editor. When supplied, this option overrides the relevant configuration option.
-p, --page
Tells blaze-edit to edit a page or pages.
-P, --post
Tells blaze-edit to edit a blog post or blog posts. This is the default option.
-f, --force
Tells blaze-edit to create an empty source file in case it does not already exist. If the core.processor option is enabled, this file is used as the input to be processed by the selected application.
-C, --no-processor
Disables processing a blog post or page with an external application.
-q, --quiet
Disables displaying of unnecessary messages.
-V, --verbose
Enables displaying of all messages. This is the default option.
-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

3.4.4. Environment Variables

EDITOR
Unless the core.editor option is set, blaze-edit tries to use system-wide settings to decide which editor to use.

3.4.5. Example Usage

  • Edit a blog post in an external text editor: 
    ~]$ blaze-edit 10
  • Edit a page in an external text editor: 
    ~]$ blaze-edit -p 4
  • Edit a page in nano: 
    ~]$ blaze-edit -p 2 -E nano

3.4.6. See Also

Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.
Section 3.3, “blaze-add”
blaze-add adds a blog post or a page to the BlazeBlogger repository.
Section 3.6, “blaze-list”
blaze-list lists blog posts or pages in the BlazeBlogger repository.

3.5. blaze-remove

blaze-remove removes a blog post or a page from the BlazeBlogger repository.

3.5.1. Synopsis

blaze-remove [-fipqPV] [-b directory] id…

blaze-remove -h|-v

3.5.2. Description

blaze-remove removes a blog post or a page with the specified id from the BlazeBlogger repository.

3.5.3. Options

-b directory, --blogdir directory
Allows you to specify a directory in which the BlazeBlogger repository is placed. The default option is a current working directory.
-p, --page, --pages
Tells blaze-remove to remove a page or pages.
-P, --post, --posts
Tells blaze-remove to remove a blog post or blog posts. This is the default option.
-f, --force
Disables requiring manual confirmation of each blog post or page removal. This is the default option.
-i, --interactive
Enables requiring manual confirmation of each blog post or page removal.
-q, --quiet
Disables displaying of unnecessary messages.
-V, --verbose
Enables displaying of all messages. This is the default option.
-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

3.5.4. Example Usage

  • Remove a blog post: 
    ~]$ blaze-remove 10
Successfully removed the post with ID 10.
  • Remove a page: 
    ~]$ blaze-remove -p 4
Successfully removed the page with ID 4.
  • Remove multiple blog posts: 
    ~]$ blaze-remove 10 4 6
Successfully removed the post with ID 10, 4 and 6.
  • Remove multiple blog posts safely: 
    ~]$ blaze-remove -i 10 4 6
Remove the post with ID 10 titled `Debian and Fedora Packages'? y
Remove the post with ID 4 titled `BlazeBlogger 0.8.0 RC2'? y
Remove the post with ID 6 titled `BlazeBlogger 0.8.1'? y
Successfully removed the post with ID 10, 4 and 6.

3.5.5. See Also

Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.
Section 3.3, “blaze-add”
blaze-add adds a blog post or a page to the BlazeBlogger repository.
Section 3.6, “blaze-list”
blaze-list lists blog posts or pages in the BlazeBlogger repository.

3.6. blaze-list

blaze-list lists blog posts or pages in the BlazeBlogger repository.

3.6.1. Synopsis

blaze-list [-cpqrsCPSV] [-b directory] [-I id] [-a author] [-t title] [-T tag] [-d day] [-m month] [-y year] [-n number]

blaze-list -h|-v

3.6.2. Description

blaze-list lists existing blog posts or pages in the BlazeBlogger repository. Additionally, it can also display basic repository statistics.

3.6.3. Options

-b directory, --blogdir directory
Allows you to specify a directory in which the BlazeBlogger repository is placed. The default option is a current working directory.
-I id, --id id
Allows you to display a single blog post or a page with the specified id.
-a author, --author author
Allows you to list blog posts or pages by the selected author.
-t title, --title title
Allows you to list blog posts or pages with matching title.
-T tag, --tag tag
Allows you to list blog posts or pages with matching tag.
-d day, --day day
Allows you to list blog posts or pages from the specified day of a month. The value has to be in the DD form.
-m month, --month month
Allows you to list blog posts or pages from the specified month. The value has to be in the MM form.
-y year, --year year
Allows you to list blog posts or pages from the specified year. The value has to be in the YYYY form.
-n number, --number number
Allows you to specify a number of blog posts or pages to be listed.
-p, --page
Tells blaze-list to list pages.
-P, --post
Tells blaze-list to list blog posts. This is the default option.
-S, --stats
Tells blaze-list to display statistics.
-s, --short
Tells blaze-list to display each blog post or page information on a single line.
-r, --reverse
Tells blaze-list to display blog posts or pages in reverse order.
-c, --color
Enables colored output. When supplied, this option overrides the relevant configuration option.
-C, --no-color
Disables colored output. When supplied, this option overrides the relevant configuration option.
-q, --quiet
Disables displaying of unnecessary messages.
-V, --verbose
Enables displaying of all messages. This is the default option.
-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

3.6.4. Example Usage

  • List all blog post: 
    ~]$ blaze-list
ID: 11 | 2010-07-05 | Jaromir Hradilek

    Title: Join #blazeblogger on IRC
    Tags:  announcement

ID: 10 | 2009-12-16 | Jaromir Hradilek

    Title: Debian and Fedora Packages
    Tags:  announcement, archlinux, debian, fedora, ubuntu

etc.
  • List all blog post in reverse order: 
    ~]$ blaze-list -r
ID: 1 | 2009-02-10 | Jaromir Hradilek

    Title: BlazeBlogger 0.7.0
    Tags:  release

ID: 2 | 2009-02-11 | Jaromir Hradilek

    Title: BlazeBlogger 0.7.1
    Tags:  release

etc.
  • List all pages: 
    ~]$ blaze-list -p
ID: 5 | 2009-02-10 | Jaromir Hradilek

    Title: Downloads

ID: 4 | 2009-02-10 | Jaromir Hradilek

    Title: Themes

etc.
  • List each blog post on a single line: 
    ~]$ blaze-list -s
ID: 11 | 2010-07-05 | Join #blazeblogger on IRC
ID: 10 | 2009-12-16 | Debian and Fedora Packages
etc.
  • Display a short version of blog statistics: 
    ~]$ blaze-list -Ss
There is a total number of 11 blog posts and 5 pages in the repository.

3.6.5. See Also

Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.
Section 3.3, “blaze-add”
blaze-add adds a blog post or a page to the BlazeBlogger repository.

3.7. blaze-make

blaze-make generates a blog from the BlazeBlogger repository.

3.7.1. Synopsis

blaze-make [-cpqrIFPTV] [-b directory] [-d directory]

blaze-make -h|-v

3.7.2. Description

blaze-make reads the BlazeBlogger repository, and generates a complete directory tree of static pages, including blog posts, single pages, monthly and yearly archives, tags, and even an RSS feed.

3.7.3. Options

-b directory, --blogdir directory
Allows you to specify a directory in which the BlazeBlogger repository is placed. The default option is a current working directory.
-d directory, --destdir directory
Allows you to specify a directory in which the generated blog is to be placed. The default option is a current working directory.
-c, --no-css
Disables creating a style sheet.
-I, --no-index
Disables creating the index page.
-p, --no-posts
Disables creating blog posts.
-P, --no-pages
Disables creating pages.
-T, --no-tags
Disables creating tags.
-r, --no-rss
Disables creating the RSS feed.
-F, --full-paths
Enables including page names in generated links.
-q, --quiet
Disables displaying of unnecessary messages.
-V, --verbose
Enables displaying of all messages, including a list of created files.
-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

3.7.4. Files

.blaze/theme/
A directory containing blog themes.
.blaze/style/
A directory containing style sheets.
.blaze/lang/
A directory containing language files.

3.7.5. Example Usage

  • Generate a blog in a current working directory: 
    ~]$ blaze-make
Done.
  • Generate a blog in the ~/public_html/ directory: 
    ~]$ blaze-make -d ~/public_html
Done.
  • Generate a blog with full paths enabled: 
    ~]$ blaze-make -F
Done.

3.7.6. See Also

Section 3.1, “blaze-init”
blaze-init creates a BlazeBlogger repository, or recovers a previously corrupted one.
Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.
Section 3.3, “blaze-add”
blaze-add adds a blog post or a page to the BlazeBlogger repository.

3.8. blaze-log

blaze-log displays the BlazeBlogger repository log.

3.8.1. Synopsis

blaze-log [-cqrsCV] [-b directory] [-n number]

blaze-log -h|-v

3.8.2. Description

blaze-log displays the content of the BlazeBlogger repository log.

3.8.3. Options

-b directory, --blogdir directory
Allows you to specify a directory in which the BlazeBlogger repository is placed. The default option is a current working directory.
-n number, --number number
Allows you to specify a number of log entries to be listed.
-s, --short
Tells blaze-log to display each log entry on a single line.
-r, --reverse
Tells blaze-log to display log entries in reverse order.
-c, --color
Enables colored output. When supplied, this option overrides the relevant configuration option.
-C, --no-color
Disables colored output. When supplied, this option overrides the relevant configuration option.
-q, --quiet
Disables displaying of unnecessary messages.
-V, --verbose
Enables displaying of all messages. This is the default option.
-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

3.8.4. Files

.blaze/log
A file containing the repository log.

3.8.5. Example Usage

  • List the whole repository history: 
    ~]$ blaze-log
Date: Sun Jul 25 16:48:22 2010

    Edited the page with ID 5.

Date: Tue Jul  6 18:54:59 2010

    Edited the page with ID 5.

etc.
  • List the whole repository history in reverse order: 
    ~]$ blaze-log -r
Date: Tue Feb 10 00:40:16 2009

    Created/recovered a BlazeBlogger repository.

Date: Tue Feb 10 01:06:44 2009

    Added the page with ID 1.

etc.
  • Display the very first log entry on a single line: 
    ~]$ blaze-log -rs -n 1
Tue Feb 10 00:40:16 2009 - Created/recovered a BlazeBlogger repository.

3.8.6. See Also

Section 3.1, “blaze-init”
blaze-init creates a BlazeBlogger repository, or recovers a previously corrupted one.
Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.

Chapter 4. UNIX Utilities

4.1. blaze.sh
4.1.1. Synopsis
4.1.2. Description
4.1.3. Options
4.1.4. Environment Variables
4.1.5. Example Usage
4.1.6. See Also
This chapter provides a thorough description of UNIX® utilities that are shipped with BlazeBlogger.

4.1. blaze.sh

blaze allows you to run all BlazeBlogger utilities with a single command.

4.1.1. Synopsis

blaze command [option…]

blaze help|man [command]

blaze -h|-v

4.1.2. Description

blaze provides a common way to run BlazeBlogger utilities with a single command.

4.1.3. Options

4.1.3.1. Command Line Options

-h, --help
Displays usage information and exits.
-v, --version
Displays version information and exits.

4.1.3.2. Available Commands

init, in
Runs blaze-init, a utility that either creates a BlazeBlogger repository, or recovers a previously corrupted one. Refer to Section 3.1, “blaze-init” for a full description of the command usage.
config, cf, cfg
Runs blaze-config, a utility that either displays, or sets BlazeBlogger configuration options. Refer to Section 3.2, “blaze-config” for a full description of the command usage.
add
Runs blaze-add, a utility that adds a blog post or a page to the BlazeBlogger repository. Refer to Section 3.3, “blaze-add” for a full description of the command usage.
edit, ed
Runs blaze-edit, a utility that edits a blog post or a page in the BlazeBlogger repository. Refer to Section 3.4, “blaze-edit” for a full description of the command usage.
remove, rm, del
Runs blaze-remove, a utility that removes a blog post or a page from the BlazeBlogger repository. Refer to Section 3.5, “blaze-remove” for a full description of the command usage.
list, ls
Runs blaze-list, a utility that lists blog posts or pages in the BlazeBlogger repository. Refer to Section 3.6, “blaze-list” for a full description of the command usage.
make, mk
Runs blaze-make, a utility that generates a blog from the BlazeBlogger repository. Refer to Section 3.7, “blaze-make” for a full description of the command usage.
log
Runs blaze-log, a utility that displays the BlazeBlogger repository log. Refer to Section 3.8, “blaze-log” for a full description of the command usage.
help
Displays usage information, either for the utility itself, or for the selected command.
man
Displays a manual page, either for the utility itself, or for the selected command.
version, vs, ver
Displays version information.

4.1.4. Environment Variables

EDITOR
Unless the core.editor option is set, blaze tries to use system-wide settings to decide which editor to use.

4.1.5. Example Usage

  • Run the blaze-remove command: 
    ~]$ blaze remove -p 4
Successfully removed the page with ID 4.
  • Display usage of the blaze-config command: 
    ~]$ blaze help config
Usage: blaze-config [-qV] [-b DIRECTORY] [-E EDITOR] OPTION [VALUE...]
       blaze-config -e [-b DIRECTORY]
       blaze-config -h|-v

  -b, --blogdir DIRECTORY     specify a directory in which the BlazeBlogger
                              repository is placed
  -E, --editor EDITOR         specify an external text editor
  -e, --edit                  edit the configuration in a text editor
  -q, --quiet                 do not display unnecessary messages
  -V, --verbose               display all messages
  -h, --help                  display this help and exit
  -v, --version               display version information and exit
  • Display the manual page for the blaze-init command: 
    ~]$ blaze man init

4.1.6. See Also

Section 3.1, “blaze-init”
blaze-init creates a BlazeBlogger repository, or recovers a previously corrupted one.
Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.
Section 3.3, “blaze-add”
blaze-add adds a blog post or a page to the BlazeBlogger repository.
Section 3.4, “blaze-edit”
blaze-edit edits a blog post or a page in the BlazeBlogger repository.
Section 3.5, “blaze-remove”
blaze-remove removes a blog post or a page from the BlazeBlogger repository.
Section 3.6, “blaze-list”
blaze-list lists blog posts or pages in the BlazeBlogger repository.
Section 3.7, “blaze-make”
blaze-make generates a blog from the BlazeBlogger repository.
Section 3.8, “blaze-log”
blaze-log displays the BlazeBlogger repository log.

Chapter 5. Windows Utilities

5.1. blaze.bat
5.1.1. Synopsis
5.1.2. Description
5.1.3. Options
5.1.4. Example Usage
5.1.5. See Also
This chapter provides a thorough description of Microsoft® Windows® utilities that are shipped with BlazeBlogger.

5.1. blaze.bat

blaze.bat allows you to run all BlazeBlogger utilities with a single command.

5.1.1. Synopsis

blaze command [option…]

blaze help [command]

5.1.2. Description

blaze.bat provides a common way to run BlazeBlogger utilities with a single command.

5.1.3. Options

init
Runs blaze-init, a utility that either creates a BlazeBlogger repository, or recovers a previously corrupted one. Refer to Section 3.1, “blaze-init” for a full description of the command usage.
config
Runs blaze-config, a utility that either displays, or sets BlazeBlogger configuration options. Refer to Section 3.2, “blaze-config” for a full description of the command usage.
add
Runs blaze-add, a utility that adds a blog post or a page to the BlazeBlogger repository. Refer to Section 3.3, “blaze-add” for a full description of the command usage.
edit
Runs blaze-edit, a utility that edits a blog post or a page in the BlazeBlogger repository. Refer to Section 3.4, “blaze-edit” for a full description of the command usage.
remove
Runs blaze-remove, a utility that removes a blog post or a page from the BlazeBlogger repository. Refer to Section 3.5, “blaze-remove” for a full description of the command usage.
list
Runs blaze-list, a utility that lists blog posts or pages in the BlazeBlogger repository. Refer to Section 3.6, “blaze-list” for a full description of the command usage.
make
Runs blaze-make, a utility that generates a blog from the BlazeBlogger repository. Refer to Section 3.7, “blaze-make” for a full description of the command usage.
log
Runs blaze-log, a utility that displays the BlazeBlogger repository log. Refer to Section 3.8, “blaze-log” for a full description of the command usage.
help
Displays usage information, either for the utility itself, or for the selected command.

5.1.4. Example Usage

  • Run the blaze-remove command: 
    C:\> blaze remove -p 4
  • Display usage of the blaze-config command: 
    C:\> blaze help config
Usage: blaze-config [-qV] [-b DIRECTORY] [-E EDITOR] OPTION [VALUE...]
       blaze-config -e [-b DIRECTORY]
       blaze-config -h|-v

  -b, --blogdir DIRECTORY     specify a directory in which the BlazeBlogger
                              repository is placed
  -E, --editor EDITOR         specify an external text editor
  -e, --edit                  edit the configuration in a text editor
  -q, --quiet                 do not display unnecessary messages
  -V, --verbose               display all messages
  -h, --help                  display this help and exit
  -v, --version               display version information and exit

5.1.5. See Also

Section 3.1, “blaze-init”
blaze-init creates a BlazeBlogger repository, or recovers a previously corrupted one.
Section 3.2, “blaze-config”
blaze-config displays or sets BlazeBlogger configuration options.
Section 3.3, “blaze-add”
blaze-add adds a blog post or a page to the BlazeBlogger repository.
Section 3.4, “blaze-edit”
blaze-edit edits a blog post or a page in the BlazeBlogger repository.
Section 3.5, “blaze-remove”
blaze-remove removes a blog post or a page from the BlazeBlogger repository.
Section 3.6, “blaze-list”
blaze-list lists blog posts or pages in the BlazeBlogger repository.
Section 3.7, “blaze-make”
blaze-make generates a blog from the BlazeBlogger repository.
Section 3.8, “blaze-log”
blaze-log displays the BlazeBlogger repository log.

BlazeBlogger Quick Reference

Creating a New Blog

Table A.1. Creating a New Blog Repository
Command Description
blaze-init Creates a new blog repository in a current directory.
blaze-init --blogdir ~/public_html Creates a new blog repository in ~/public_html/.
blaze-init --verbose Creates a new blog repository while displaying a list of created files.

Table A.2. Recovering a Corrupted Blog Repository
Command Description
blaze-init Recovers a corrupted blog repository while keeping existing files intact.
blaze-init --force Recovers a corrupted blog repository while reverting existing files to their initial state.
blaze-init --verbose Recovers a corrupted blog repository while displaying a list of created files.

Configuring a Blog

Table A.3. General Blog Settings
Command Description
blaze-config blog.title BlazeBlogger Changes the blog title to “BlazeBlogger”.
blaze-config blog.subtitle CMS without boundaries Changes the blog subtitle to “CMS without boundaries”.
blaze-config blog.description CMS without boundaries Changes the blog description to “CMS without boundaries”.
blaze-config blog.keywords blazeblogger, cms, blog Changes the blog keywords to “blazeblogger”, “cms”, and “blog”.
blaze-config blog.theme default.html Changes the blog theme to default.html.
blaze-config blog.style default.css Changes the style sheet to default.css.
blaze-config blog.lang en_US Changes the blog translation to en_US.
blaze-config blog.posts 10 Changes the number of blog posts to be listed on a single page to 10.

Table A.4. User Settings
Command Description
blaze-config user.name Jaromír Hradílek Changes the default blog post author to Jaromír Hradílek.
blaze-config user.nickname Blackened Changes the default blog post author's nickname to Blackened.
blaze-config user.email jhradilek@gmail.com Changes the email address to .

Table A.5. RSS Feed Settings
Command Description
blaze-config feed.baseurl http://blaze.blackened.cz Changes the URL of the blog to http://blaze.blackened.cz.
blaze-config feed.posts 10 Changes the number of blog posts to be listed in the feed to 10.
blaze-config feed.fullposts true Enables inclusion of the whole content of a blog post to the feed.

Table A.6. Color Settings
Command Description
blaze-config color.list true Enables colors in the blaze-list utility output.
blaze-config color.log true Enables colors in the blaze-log utility output.

Table A.7. Advanced Blog Post Settings
Command Description
blaze-config post.author top Places the blog post author above the post.
blaze-config post.date top Places the date of publishing above the post.
blaze-config post.tags bottom Places the blog post tags below the post.

Table A.8. Advanced BlazeBlogger Settings
Command Description
blaze-config core.doctype html Changes the document type to HTML.
blaze-config core.extension html Changes the file extension to html.
blaze-config core.encoding UTF-8 Changes the character encoding to UTF-8.
blaze-config core.editor 'gvim -f' Changes the external text editor to GVim.
blaze-config core.processor 'markdown %in% > %out%' Configures Markdown to process each blog post or a page.

Adding a Blog Post or a Page

Table A.9. Adding a Blog Post
Command Description
blaze-add Opens an external text editor for you to write the blog post in.
blaze-add release.txt changelog.txt Creates blog posts from the release.txt and changelog.txt files.
blaze-add --editor nano Opens the nano text editor for you to write the blog post in.
blaze-add --no-processor Opens an external text editor for you to write the blog post in while disabling processing it by an external application afterwards.

Table A.10. Adding a Page
Command Description
blaze-add --page Opens an external text editor for you to write the page in.
blaze-add --page about.txt downloads.txt Creates pages from the about.txt and downloads.txt files.
blaze-add --page --editor nano Opens the nano text editor for you to write the page in.
blaze-add --page --no-processor Opens an external text editor for you to write the page in while disabling processing it by an external application afterwards.

Editing a Blog Post or a Page

Table A.11. Editing a Blog Post
Command Description
blaze-edit 10 Opens an external text editor for you to edit the blog post with ID 10 in.
blaze-edit --editor nano 10 Opens the nano text editor for you to edit the blog post with ID 10 in.
blaze-edit --no-processor 10 Opens an external text editor for you to edit the blog post with ID 10 in while disabling processing it by an external application afterwards.
blaze-edit --force 10 Opens an external text editor for you to edit the blog post with ID 10 in, creating an empty source file in case it does not already exist.

Table A.12. Editing a Page
Command Description
blaze-edit --page 4 Opens an external text editor for you to edit the page with ID 4 in.
blaze-edit --page --editor nano 4 Opens the nano text editor for you to edit the page with ID 4 in.
blaze-edit --page --no-processor 4 Opens an external text editor for you to edit the page with ID 4 in while disabling processing it by an external application afterwards.
blaze-edit --page --force 4 Opens an external text editor for you to edit the page with ID 4 in, creating an empty source file in case it does not already exist.

Removing a Blog Post or a Page

Table A.13. Removing a Blog Post
Command Description
blaze-remove 3 4 11 Removes the blog posts with ID 3, 4, and 11.
blaze-remove --interactive 3 4 11 Removes the blog posts with ID 3, 4, and 11 while requiring manual confirmation of each removal.

Table A.14. Removing a Page
Command Description
blaze-remove --page 2 3 4 Removes the pages with ID 2, 3, and 4.
blaze-remove --page --interactive 2 3 4 Removes the pages with ID 2, 3, and 4 while requiring manual confirmation of each removal.

Listing Blog Posts or Pages

Table A.15. Listing Blog Posts
Command Description
blaze-list Lists all blog posts.
blaze-list --reverse Lists all blog posts in reverse order.
blaze-list --short Lists all blog posts, displaying each entry on a single line.
blaze-list --number 7 Lists the latest seven blog posts.
blaze-list --author "Jaromir Hradilek" Lists blog posts written by Jaromir Hradilek.
blaze-list --year 2009 --month 02 Lists blog posts written in February 2009.
blaze-list --tag release Lists blog posts tagged as release.
blaze-list --id 11 Displays the blog post with ID 11.

Table A.16. Listing Pages
Command Description
blaze-list --pages Lists all pages.
blaze-list --pages --reverse Lists all pages in reverse order.
blaze-list --pages --short Lists all pages, displaying each entry on a single line.
blaze-list --pages --number 3 Lists the latest three pages.
blaze-list --pages --id 4 Displays the page with ID 4.

Displaying Blog Statistics

Table A.17. Displaying Blog Statistics
Command Description
blaze-list --stats Displays blog statistics.
blaze-list --stats --short Displays blog statistics on a single line.

Generating a Blog

Table A.18. Generating a Blog
Command Description
blaze-make Generates a complete directory tree of static pages, including blog posts, single pages, monthly and yearly archives, tags, and an RSS feed.
blaze-make --destdir ~/public_html Generates a complete directory tree of static pages in the ~/public_html/ directory.
blaze-make --verbose Generates a complete directory tree of static pages while displaying a list of created files.
blaze-make --full-paths Generates a complete directory tree of static pages while including page names in generated links.
blaze-make --no-rss Generates a complete directory tree of static pages while omitting the creation of the RSS feed.

Displaying a Log

Table A.19. Displaying a Log
Command Description
blaze-log Lists all log entries.
blaze-log --reverse Lists all log entries in reverse order.
blaze-log --short Lists all log entries, displaying each record on a single line.
blaze-log --number 5 Lists the latest five log entries.

Creating a New Theme

Table A.20. List of Available Theme File Placeholders
Form Description
<!-- START-DOCUMENT --> Is replaced with the document header followed by the opening HTML tag.
<!-- END-DOCUMENT --> Is replaced with the closing HTML tag.
<!-- content-type --> Is replaced with the Content-Type META tag.
<!-- generator --> Is replaced with the Generator META tag.
<!-- copyright --> Is replaced with the Copyright META tag.
<!-- date --> Is replaced with the Date META tag.
<!-- description --> Is replaced with the Description META tag.
<!-- keywords --> Is replaced with the Keywords META tag.
<!-- stylesheet --> Is replaced with the Stylesheet LINK tag.
<!-- feed --> Is replaced with the RSS feed LINK tag.
<!-- page-title --> Is replaced with a page title.
<!-- title --> Is replaced with the blog title.
<!-- subtitle --> Is replaced with the blog subtitle.
<!-- name --> Is replaced with the author's name.
<!-- nickname --> Is replaced with the author's nickname.
<!-- e-mail --> Is replaced with the author's email.
<!-- year --> Is replaced with the current year.
<!-- tags --> Is replaced with the list of tags.
<!-- archive --> Is replaced with the list of months.
<!-- pages --> Is replaced with the list of pages.
<!-- posts --> Is replaced with the list of recent blog posts.
<!-- content --> Is replaced with the actual content.
%root% Is replaced with a relative path to the root directory of the blog.
%home% Is replaced with a relative path to the index page of the blog.
%page[id]% Is replaced with a relative path to a page with the given id.
%post[id]% Is replaced with a relative path to a blog post with the given id.
%tag[name]% Is replaced with a relative path to a tag with the given name.

Table A.21. List of Available Style Sheet Classes
Form Description
post A H2 tag containing the title of a blog post or a page.
section A DIV tag containing a section name.
information A DIV tag containing blog post meta information that are displayed above the post.
post-footer A DIV tag containing blog post meta information that are displayed below the post.
date A SPAN tag containing a date of publishing.
author A SPAN tag containing an author of a blog post.
tags A SPAN tag containing a list of attached tags.
previous A DIV tag containing a link to a page with older blog posts.
next A DIV tag containing a link to a page with newer blog posts.
more An A tag containing a “Read more” link.

GNU Free Documentation License

Version 1.3, 3 November 2008
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Preamble

The purpose of this License is to make a manual, textbook, or other functional and useful document “free” in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1. Applicability and Definitions

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
The “publisher” means any person or entity that distributes copies of the Document to the public.
A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

2. Verbatim Copying

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.

3. Copying in Quantity

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

4. Modifications

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
  4. Preserve all the copyright notices of the Document.
  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
  8. Include an unaltered copy of this License.
  9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
  11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
  13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
  14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
  15. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

5. Combining Documents

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements”.

6. Collections of Documents

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

7. Aggregation with Independent Works

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

8. Translation

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

9. Termination

You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

10. Future Revisions of This License

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

11. Relicensing

“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.
“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.
“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.
An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to Use This License for Your Documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: 
Copyright (C)  YEAR  YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with … Texts.” line with this: 
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Revision History

Revision History
Revision 1-018 February 2011Jaromír Hradílek
The first public release of the book.
Revision 03 July 2010Jaromír Hradílek
Initial creation of the book using Publican