qb is a blog system by Tim 'Scytale' Weber for people who:
Warning: Since October 12, 2008, qb has no maintainer and is not actively developed or supported. However, the current codebase works fine and there are no known security issues. You are encouraged to become qb's new maintainer if you think it is worth it.
There was once a mailing list which is now discontinued. The list is archived at Gmane, Google and mail-archive.com. If you need to contact the former developer, for example because you found a security bug or want to take over maintainership, please use one of the ways described on contacting Scytale. Please don't ask for support, my spare time (or the lack of it) doesn't allow for this.
"Not tested" doesn't mean it's not going to work, just give it a try. If you managed to run qb on something "not tested", drop us a note.
qb's official web site is at http://scytale.name/proj/qb/. There are several possibilities available to get the code:
You can have a look at the developer's changelog or the version control changelog.
Warning: This documentation is updated while qb's development goes on. If you are reading this file online, keep in mind that the information herein describes qb's current "bleeding edge" Git version. If you downloaded a release tarball, please refer to the README.html that's included there instead.
Copy all files into a directory somewhere inside the Document Root of your webserver. You can use a subdirectory or the Document Root itself. If you're running Apache, you may want to move the htaccess file to .htaccess or create a symlink to it. Lighttpd users may instead want to delete it, although you might as well simply ignore the file.
Inside the lib directory, copy qb-0.2.conf.dist.php to qb-0.2.conf.php and edit it according to your needs. (Don't be afraid of its name, even if you downloaded a 0.3 release. See qb versioning below.)
You may wish to create your own templates (find them in tpl/) and CSS. The templates to use are specified in qb.cfg.php, the CSS in the template. You can find a list of template tags below.
Make sure your web server can write to the QB_META directory.
Start putting files with your configured suffix (default: .qb) into the src directory.
Each content file consists of a header (the first line) and a body (everything else).
The header consists of several tags formatted like <NAME:VALUE>, where NAME will be the name of a template variable and VALUE its value.
There are some special things:
If you don't supply a NAME, it's the same as setting it to "title", therefore you can supply the entry's title like <:My cool entry> or <title:My cool entry>, it's equivalent.
Then there's the <tags:> tag where you can supply some tags for the entry.
Those are available in the template via spantags and ultags, depending on whether you like <span class="tag"> or <ul class="tags"><li>... more.
Soon one will be able to search for certain tags as well.
Specify the tags as in Flickr, i.e. seperate them with spaces and put double quotes around multi-word tags:
<tags:example documentation boring "all your tags are belong to us" omg>
Last but not least there's the <via:> tag where you can place a link to another blog to cite as source:
<via:<<http://example.com/blog/23-foo.html ExBlog>>>(See below for the default "link" syntax.) You can also put unlinked text in it:
<via:Fefe's Blog>There'll probably be a trackback function soon.
You can add other tags if you want to, their values will be available in the templates like any other ones.
The body contains HTML code plus some regex shortcuts. With the default config you can write things like
<<http://example.com/link Description>>which will then translate to
<a href="http://example.com/link">Description</a>
There's other stuff like <wXX:Lemma Description> which will link to http://XX.wikipedia.org/Lemma.
Please note that for those Wikipedia links spaces in the article name (that is, the link target) will have to be replaced by underscores like this:
<wen:Linus_Torvalds Inventor of Linux>, which will look like Inventor of Linux.
Suppose you've installed qb in a subdirectory called qb on your web server scytale.name and you've activated the supplied .htaccess file. Now every request that starts with http://scytale.name/qb/ will be handled by qb.
qb will map the path on the web server to its "source" directory (by default src). That means, if someone sends a request to http://scytale.name/qb/foo, qb will search first for a directory src/foo. If it exists, it will display all .qb files in that directory and its subdirectories, ordered by their creation date, newest first. This allows you to organize your files in a flexible way. For example, you can throw all your blog entries directly in the source directory (creative chaos), put them under different directories depending on the content (like coding, politics etc.) or in date-based directories (like 2007/05/30). In the last example, someone requesting http://scytale.name/qb/2007 will see all your entries in the 2007 directory and its subdirectories.
If there's no directory with that name, qb will look for a .qb file matching. For example, the request http://scytale.name/qb/foo will look for src/foo.qb. If that doesn't exist also, an "not found" error message will be sent.
If you are not using the .htaccess file to alias the whole directory to qb, you can also use the qb.php file as the request handler. Your URLs will then look like this: http://scytale.name/qb/qb.php/2008/some-article. No matter if you call qb via qb.php or using the .htaccess, this should be recognized and configured automatically. Contact me if it doesn't, it's a pretty new feature.
There are two other special things that may be passed as "query" part of the URL, i.e. after a question mark. First, you can pass a template name. This is how the Atom feed works: You pass http://scytale.name/qb/?atom10 in the URL, and qb will use the qb.article.atom10 and qb.template.atom10 template files in its source directory, which will output a valid Atom feed instead of HTML data.
Second, if the query part is a positive integer, it will be interpreted as page number. http://scytale.name/qb/?3 will therefore refer to page three of the articles. Page numbers are used if the number of articles that would match a certain request is larger than the maximum number of articles per page set in the config file.
Note that I consider this URL format quite crappy, and it will change in later versions. But rest assured that I will do everything to keep old links from breaking. And I'm quite good at that: My blog exists for several years now and went through two different authoring softwares as well as three different directories and a domain change. And yet even links to the very first article still work.
Since most current Unix systems do not store file creation times (only the modification time), qb uses a dirty workaround that can be seen in the meta directory of a qb installation. In this directory there are .cre files stored for each .qb file in the source directory. Their modification time is used as creation time of the source files. That means that for each .qb file displayed, qb will check whether its .cre file exists. If it doesn't, it is created and its modification time set to that of the .qb file. This timestamp is never changed, in contrast to that of the .qb file when you change it.
The meta directory needs to be writable by the web server for obvious reasons (on a side note, the source directory needs not). It will contain the same subdirectories as the source directory. If you delete or move around files in the source directory, orphaned files will not be automatically deleted or moved to the new location.
qb does nothing to your articles but run some regular expressions over them and aggregate the results.
In order to include things like the current page number etc. in the output, there are special strings called "template tags", that look like XML tags.
For example, the current page number can be included in a template like this:
<qb:thispage/>
Here's a list of available template tags and what they do. All start with the prefix qb:, and I won't explicitly repeat that prefix in the following list.
<span class='tag'> tag.
Unset in page templates or if there are no tags.
<li> tag, wrapped inside an <ul class='tag'>.
Unset in page templates or if there are no tags.
There are four special tags you can use that contain not only a value, but perform additional logic:
<qb:ifset:tagname>...</qb:ifset:tagname>.
For example, to only show a "modified date" line if the file really has been modified, use something like <qb:ifset:wasmodified>Modified at <qb:wasmodified/></qb:ifset:wasmodified>.
date() function supports.
The text content of this tag is split into two parts, the first one being all the digits from the start of the string up to the first non-digit, the second one being all the rest (but excluding any leading spaces).
These two things are then simply passed to date() as timestamp and format string parameter, respectively.
An example would be something like <qb:date><qb:created/> j. n. Y, H:i:s (T)</qb:date>.
<qb:basepath/>/qb.css.
In its current version, cleanpath will simply remove double slashes, which is necessary in the above example if the base path is "/".
Soon, cleanpath should do things like protect you a bit from path traversal attacks etc. as well.
Additionally, you can create your own article template tags by simply including a new tag name in the article's header line.
A sample header line could look like <:Five Years><tags:music Björk song><mood:destructively sad>, and a template construct like <qb:ifset:mood><qb:mood/><qb:ifset:mood> would then display the mood you're in.
The values of created and modified can be specified (as an Epoch integer) in the first line of a content file as well.
If they are, they override the actual file metadata.
This is useful if you can't, for whatever reason, change the file metadata, but the contents.
When overriding, you may choose to specify only one or both of them.
Also, you can set modified to the special value ! (just a single exclamation mark), which will instruct qb to set the modified value to that of created, effectively making the entry appear as though it has never been modified at all.
Since qb is only using plain text files, it's easy to create a backup. You don't have to create database dumps and all that. The only thing you'll have to take care for is to keep the correct time stamps.
If you would like to move a qb installation to a different directory or web server, here are some common pitfalls:
qb is still far from complete (although it does everything that's currently implemented quite well), therefore its version number is still below 1.0. For those interested, here's an overview of the versions that already existed, why they were called that way and what's going to come up next. Details about the changes between various versions are available in the changelog.
The versioning scheme is quite simple: major.minor.revision. There are no "stable" and "unstable" versions like for example in Linux, all releases are (hoped to be) stable.
The current major version is 0, meaning that qb is not feature-complete enough and the internal architecture is not fixed enough yet to be considered a "complete" product. It will change to 1 once I consider qb to be serious competition to Wordpress; feature-wise, not with regards to security bugs. A major number change is expected every few years.
Minor numbers advance every time a major step in development has been finished. This can be one or more new features, internal restructuring of the code, or both. New minor versions are expected to come up every few months.
If something goes wrong in a x.y.0 release (usually some kind of bug), a new release will be published, having the revision number increased by one. They do not contain new features, but rather fix existing ones.
The 0.2 version, for example, saw two revisions right at the same day the original version was released, because not enough testing went into a new feature and it behaved wrong in exceptional cases. I've learned from these mistakes, and for 0.3 there will be beta "releases" and release candidates.
Beta releases (or beta tags, as they should be called more correctly), are not released at all, at least not via the usual "tarball" method. When working on a new release, at some points I consider the current code base quite stable, and to encourage testing I tag those as "0.3.0b1" (meaning "beta 1") or something in Git. People who are running the Git version and looking forward to the new release can then try out this beta version to have an early preview on what the next big things are going to be. If you're a Git user, but too afraid to update to arbitrary commits, you are encouraged to try out the beta versions.
Release candidates are just what the name implies: Something that might end up being a release. That means I have tested it and consider code and documentation to be stable. However, I cannot test all the rare scenarios other people use qb in, and therefore ask kindly for testing of the candidate by every current user, regardless of whether they use Git or just tarball releases. To support this, I build a complete tarball just like for an ordinary release. Depending on the feedback I receive, the final release will appear sooner or later, but not sooner than two weeks after the last release candidate.
Finally, a short story of qb versions:
