# LnBlog

Homepage: http://www.skepticats.com/lnblog/

LnBlog: A simple file-based weblog focused on design elegance.
Copyright (C) 2005 Peter A. Geer <pageer@skepticats.com>
This program is licensed under the GNU General Public License. See the license information section for details.

## Introduction

LnBlog is a simple weblog package written in PHP which stores data in text files. It is strives to be easy to use, easy to manage, and feature rich while maintaining a clean, elegant, and modular design. It is built to create sites with a clean, directory-based URL structure and valid XHTML and CSS for style and layout. It is intended to run well on inexpensive web hosting accounts, and so is cross-platform and light on requirements.

## Status

Currently, LnBlog is in the active development, which just means that it is functional and tested, but not anywhere close to done yet. There are still lots of features to add, both in the back-end code and in terms of interface elements. You can see the to do list to get an idea of what is currently planned. If you have any comments or suggestions, or if you have any problems or find any bugs, feel free to e-mail me.

## Requirements

LnBlog is fairly light on requirements. It does not require any particular operating system or web server and is known to work on Linux/Apache, Windows/Apache, and Windows/IIS. The only hard and fast requirements are the following:

1. PHP 4.1or greater.
2. Support for Perl Compatible Regular Expression (PCRE), which is enabled by default in most PHP packages.
3. The ability for scripts to read and write files to the server. To do this, you must either have FTP access to the web server and configure LnBLog to use it, or have PHP's safe mode disabled and appropriate directory permissions set on the web server.

## Feature List

LnBlog's built-in features include:

- Works in Safe Mode when using FTP support.
- Anonymous reader comments.
- Send and receive TrackBack pings.
- Create multiple user accounts with basic serucity on entires and blogs.
- Easily create multiple weblogs.
- Create static "articles" in addition to weblog entries.
- Change between multiple themes, each of which can have completely a different look and behavior, i.e. different styles, HTML markup, images, and even client-side scripts.
- Default themes use valid XHTML Strict for markup and CSS-based page layout.
- Flexible theming system that allows HTML templates, scripts, and stylesheets to be tweaked on a per-blog basis.
- Support for posting with simple auto-markup, a simple subset of BBcode, or raw HTML code.

The following features are also supported by the standard set of plugins:

- Automatically generated RSS feeds for blog entries and comments.
- E-mail notification when new comments are posted.
- Automatically created .htaccess file preventing access to raw data files.

## Initial Setup

For step-by-step instructions, please see the install guide. If you're more technically inclined, then it's probably safe to just skip to the summary below.

Here's the quick version. Just extract the installation archive and upload the whole LnBlog directory to a location in the publicly accessible portion of your web hosting account. You can them navigate to that directory with your favorite browser to run the configuration scripts. The first script configures file writing. You have two options for file writing:

1. NativeFS: This uses PHP's standard file writing functions to create data files. The up side of this is that there is no special configuration required. The down side is that, because of how PHP works, any files it creates will be owned by a system account, i.e. the username under which the web server runs, such as 'apache' or 'nobody'. This makes it hard to manage the files if you do not have root (i.e. administrator) access to the machine, because you will not be able to delete or move files. In addition, native file writing requires that PHP's safe_mode be disabled.
2. FTPFS: This filters file writing through FTP. Needless to say, this reuqires FTP access to you web server. It is recommended for shared hosting accounts and other situations where you do not have root (i.e. administrator) access to the web server because it keeps file permissions manageable. Also, FTP file writing will work when safe_mode is turned on.

After file writing support is configured, you must set an administrator login. This account will be used to add new weblogs as well as to log into the ones you create. After that's set, you can log in and start adding new blogs and/or users. There are also administrative functions to:

1. Modify a blog, i.e. change properties like the name, description, and allowed writers.
2. Modify the links in the system-wide menu bar.
3. Update blog data, meaning upgrade existing data files to a new format after an upgrade. This is almost never used.
4. Upgrade a blog, which simply means replacing replacing the PHP wrapper scripts created by LnBlog. This is sometimes required after an upgrade.
5. Fix file permissions on a blog, which is almost never needed.

## Upgrading

Upgrading your LnBlog installation is generally quite easy. First, you must make a backup copy of the files in the "userdata" folder in your LnBlog directory. Then, just rename or delete your old LnBlog folder and copy the one for the new version in it's place. You can then copy the backed-up userdata files into the new LnBlog folder. For major releases, you may also need to upgrade the files for each individual blog. This is done by going to the administration page and using the "upgrade blog" option. Simply put the relative path to your blog (e.g. myblog, as described in the "Adding New Blogs" section) into the "upgrade to current version" box and click the "Upgrade" button. This will upgrade the configuration files for the blog and add any new pages. You will have to do this separately for each blog that youhave.

Note: If you are upgrading from LnBlog 0.3 to 0.4, the locations of the user configuration files have changed. You will need to copy the fsconfig.php, passwd.php, and sitemap.htm files from the root of your old LnBlog folder into the "userdata" subdirectory of your new LnBlog folder. You will also need to run an upgrade on each of your blogs.

Note 2: If you are upgrading to LnBlog 0.4 from version 0.3.1 or earlier, it is recommended that you delete your fsconfig.php file and go to the LnBlog administration page to recreate it, as there was a configuration value added to this file in version 0.3.2. Your site may, however, continue to function normally with the old file.

Note 3: If, for some reason, you want to upgrade from LnBlog 0.2 to a higher version, you will need to delete your passwd.php file and create a new login, because the format of this file has changed and is no longer compatible.

## Adding New Users

In addition to the administrator account, you can create as many new user accounts as you like. (Disclaimer: LnBlog was not buit to handle large numbers of users and has not been tested with such a configuration. While there is no inherent limit on the number of users, don't expect it to scale well beyond a couple dozen accounts.) To create a new account log in to the LnBlog administration page and click the "Add new user" link. Only the administrator account can create new users.

The form to add new users should be fairly self-explanatory. You are required to enter a username, password, and password confirmation. The real name, e-mail, and homepage are all optional. However, please note that the user will (obviously) not receive e-mail confirmation of comments on his posts if you do not give an e-mail address.

## Security

LnBlog uses a very simple security model based on user ownership. The rules for determining what each user can do are as follows

1. The administrator can do everything that can be done.
2. The owner of a blog can modify the blog properties (theme, name, number of posts shown, etc.), can add entries and articles to it,and can modify the entries and articles of other users who post to the blog.
3. The owner of an entry or article can modify that entry or article, including comments and trackbacks.
4. A user can only add articles or entries to a blog he owns or one he is explicitly on the write-list for.
5. Anybody, user or anonymous reader, can add comments.

To put it more succinctly, there's the administrator (can do anything), the blog owner (can do anything with the blog), the other users (can do anything with their own posts - provided they can post), and everybody else (can only post comments). Which role a particular person will take depends on who they are and what blog you're talking about. The owner of one blog may be just a regular reader on another.

## Adding New Blogs

Adding new blogs is done on the LnBlog administration page. Only the administrator account can add new blogs. Note that if you are using native file writing, then the user account under which PHP is running must have write access to the location where the blog will be created. This is normally not the case, so you may have to create the blog folder beforehand.

To add a new blog, just click the "Add new blog" link and fill out the form on the resulting page. The fields define various properties of the blog, and are as follows:

1. Blog path: The path to the blog on the web server machine. You may specify either an absolute path or a relative path, in which case the path is computed relative to your web root directory. So, if you specify the path "myblog", then the web address of the blog will be `http://www.mysite.com/myblog/`
2. Blog owner: The username of whoever owns the blog. This is the user who will be allowed to change these settings later. By default, this is the administrator.
3. Additional allowed writers: A comma-separated list of usernames other than the owner who can post new entries and articles to this blog.
4. Blog name: The name of the blog.
5. Description: A short description of the blog.
6. Theme: The theme visual used for the blog.
7. Blog name: The name of the blog.
8. Maximum number of entries: The maximum number of entries to display on the homepage of the blog. For example, if this is 10, then the main page of the blog will display the last 10 entries.
9. Maximum number of entries in RSS feeds: The maximum number of entries that will be put in the main blog RSS feed.

## Adding Entries

Adding a blog entry is pretty self-explanatory. Just log in and click on the "add entry" link. You will be taken to the entry edit screen, where you can enter the subject for your entry, the entry text itself, and turn comments for this entry on or off. Note that in order to add an entry, you must either be the owner of the blog you're adding it to, or you must be on the allowed writers list for that blog.

There are three possible input modes, which you can change between with the option buttons below the edit area. They are:

1. Auto-markup: Adds HTML paragraphs and line breaks based on the plain-text input and converts all http:// and ftp:// URLs to links.
2. LBCode: Use a dialect of the BBCode markup popular in web forums to markup your page. Paragraphs and line breaks are inserted like with auto-markup, but you can also include other supported tags. See the LBCode Syntax section for details.
3. Raw HTML: The text you type is treated as raw HTML code. No processing is done and there's no guarantee that your page will validate. In other words, this is for people who know what they're doing.

## User Comments

LnBlog allows anonymous user comments by default. You can turn off the ability to add comments with a checkbox on the entry edit screen. Comments have a required body text and optional subject, name, e-mail, and homepage fields. For logged-in users, comments will also store the username, so that the up-to-date name, e-mail, and homepage can be displayed automatically. Currently, comments cannot be edited, but they can be deleted by users with permission to modify the entry.

If the owner of a post has an e-mail address specified for his username, then he can receive e-mail notification of any new comments on his posts. This feature is one of the standard plugins and can be disabled globally or on a per-blog basis. The e-mail is sent using PHP's mail() function, so that must be correctly configured for your server. The messages themselves are in plain-text format and include the URL of the comment, as well as the comment itself and any personal information entered by the reader.

## TrackBacks

LnBlog has some very primitive support for Trackbacks. Each entry has a trackback URL and will store and display any trackback pings it receives.

To send a trackback ping, you must be logged in and have permission to modify the blog. You can then click on the "Send trackback ping" link for your blog entry and start the two-step ping process. The first step is to enter the URL you wish to ping. The second is to confirm the ping data and send it.

Due mostly to laziness on my part, LnBlog does not yet support "real" trackback pings. Instead, it uses a simple HTML form with element names conforming to the TrackBack specification to submit the HTTP POST request. As a result of this, you will notice that after the ping, you are directed to the page you pinged, which will probably show you the XML response dictated by the specification. If this is a 0 (zero), that means the ping succeeded. Otherwise, you should hopefully see an error message. Because of the suckiness of this situation, sending a trackback ping will open a new browser window so that you don't have to manually go back to your blog.

As of version 0.4.0, LnBlog supports TrackBack auto-discovery with embedded RDF code using a plugin. There is not yet a feature for auto-discovering TrackBack URLs in other blogs.

## LBCode Syntax

LnBlog supports marking up your text with LBCode, which is a variant of BBCode, the markup language used in many popular web-board and forum packages, such as phpBB. I call this dialect LBCode because it makes absolutely no attempt to match the official syntax (if there is such a thing) of BBCode. The primary purpose of LBCode is to let the user write rich text that is valid XHTML 1.0 Strict without having to learn any XHTML or worry about making mistakes while writing. Below is a table of the currently supported tags, with descriptions, example, and the mapping to HTML. Please note that LnBlog does not currently handle LBCode errors gracefully - incorrect syntax will simply be displayed as plain text.

Description | Code | Example | HTML equivalent
--- | --- | --- | ---
Bold text | [b]bold[/b] | bold | <strong>bold</strong>
Italic text | [i]italic[/i] | italic | <em>italic</em>
Underlined text | [u]underline[/u] | underline | <span style="text-decoration: underline">underline</span>
Abbreviation | [ab=Full phrase]abbreviation[/ab] | abbreviation | <abbr title="Full phrase">abbreviation</abbr>
Acronym | [ac=Full phrase]acronym[/ac] | acronym | <acronym title="Full phrase">acronym</acronym>
Block quotation | [quote]Quotation[/quote] | Quotation | <blockquote>Quotation</blockquote>
Source code | [code]Source code[/code] | `Source code` | <code>Source code</code>
Teletype | [t]Teletype text[/t] | `Teletype text` | <tt>Teletype text</tt>
Header | [h]Header[/h] | ### Header | <h3>Header</h3>
Short quotation | [q]Quote[/q] | Quote | <q>Quote</q>
Block quote | [quote]Block quotation[/quote] | Block quotation | <blockquote>Block quotation</blockquote>
Block quote with citation | [quote=http://www.somesite.com/]Block quotation[/quote] | Block quotation | <blockquote cite="http://www.somesite.com/">Block quotation</blockquote>
Hyperlink | [url=http://www.google.com]Google[/url] | Google | <a href="http://www.google.com">Google</a>
Image | [img=http://www.google.com/images/logo.gif]Google logo[/img] |  | <img src="http://www.google.com/images/logo.gif" alt="Google logo" title="Google logo" />
Right-aligned image | [img-right=http://www.google.com/images/logo.gif]Google logo[/img-right] |  | <img alt="Google logo" title="Google logo" style="float: right; clear: none;" src="http://www.google.com/images/logo.gif" />
Left-aligned image | [img-left=http://www.google.com/images/logo.gif]Google logo[/img-left] |  | <img alt="Google logo" title="Google logo" style="float: left; clear: none;" src="http://www.google.com/images/logo.gif" />
Number list | [numlist] [*]First item [*]Second item [/numlist] | First item Second item | <ol> <li>First item</li> <li>Second item</li> </ol>
Unordered list | [list] [*]First item [*]Second item [/list] | First item Second item | <ul> <li>First item</li> <li>Second item</li> </ul>

#### Notes on LBCode

1. The line breaks between items in numbered lists and unordered lists are not optional. You must put each item on a single line and you must put the beginning and ending tags on their own line.
2. When you give just a file name (i.e. a path containing no '/' characters) as the target for an [img] or [url] tag, LnBlog will automatically convert it to an absolute URI to a file in the entry directory when it is displayed. This feature is provided for two reasons: because you will not know the absoute URI of a blog entry until after you post it and because the post can be displayed at its permanent location, in which case the relative link is valid, or in another place (the front page of the blog or an RSS feed), where the relative link is not valid.
3. In Mozilla-based browser, [ac] and [ab] both do the same thing. They are both provided because there is a semantic difference, i.e. that an abbreviation is simply a shortening of a phrase using the initial letters, whereas an acronym is such a shortening that actually spells a pronounceable word. However, while the <abbr> tag is often the semantically correct one, Internet Explorer 6 doesn't support it, so you should use this tag with care.
4. In the [img] tag, the text between the opening and closing tags is required. This is because it is used as the text for both the ALT attribute, which is required in XHTML, and the TITLE attribute, which gives you the tooltips in Mozilla-based browsers. Since Internet Explorer incorrectly uses the ALT text for tooltips, you'll actually get the same tooltip in all browsers.
5. In Mozilla-based browsers, the <q> tag renders quotation marks automatically. However, this depends on the CSS2 :before and :after pseudo-elements, which are not supported by Internet Explorer, so use this with care. Note that in the default LnBlog stylsheets, the <q> tag is rendered with italic text, so that even in Internet Explorer, it can be distinguished from normal text.
6. The current LBCode handler does not deal gracefully with multiline tags. So if, e.g., you have a multiline block quotation or code block, the LBCode handler will still put <br /> tags in for the line breaks.
7. In addition to the [img] tag, there are also [img-left] and [img-right] tags. These are exactly the same, except that the resulting HTML includes a CSS style to float the image to the left or right respectively. This is used to flow text around an image.

## LBCode Editor

When posting using LBCode markup, you can use LnBlog's simple Javascript-based LBCode editor to insert the codes for you. The editor is simply a series of buttons and two text boxes, labeled "text" and "attribute." The "text" box is used to enter the contents of an LBCode tag, i.e. the actual text the goes between the opening and closing tags. The "attribute" box is used to enter any attribute for the opening tag. such as the URL for an image or link, or the phrase that an appbreviation or acronym stands for.

To use the editor, just type in the text and attribute you want and click the appropriate button. If you want to add a word in bold, type your word into the box labeled "text" and click the bold button. If you want to add a link, put the link text in the "text" box and the URL for the link in the "attribute" box and click the URL button. The corresponding markup will be added to your post at the current cursor position or at the end, depending on your browser's Javascript support. Inserting at the cursor position works on Opera 8.0, Firefox 1.0.3, and sorta-kinda works in Internet Explorer 6.0. I haven't tried it on other browsers, so your mileage may vary.

An extra feature of the editor is that the abbreviation and acronym buttons will save any attributes you use during your post and add them automatically. So, for example, if you enter the abbreviation with the text "GNU" and the attribute "GNU's Not UNIX," then if you mention GNU later in your post, you can just enter "GNU" for the text and leave the attribute blank. When you hit the abbreviation button, the attribute "GNU's Not UNIX" will be added automatically.

## Plugins

LnBlog supports a simple, event-driven plugin system. In a nutshell, this means that LnBlog supplies hooks that plugins can attach to whenever something interesting happens, e.g. when a comment is submitted, ablog entry is deleted, or the page sidebar is displayed. So when one of those events occurrs, any plugins that are waiting for it will be notifed and run their code. For information on writing plugins, consult the technical documentation.

Installing and using plugins is quite easy. All you need to do is copy the plugin files to your "plugins" directory. You can use either the system-wide plugins directory under your LnBlog installation folder, or a plugins directory in the root folder of a specific blog. Note that if the same filename exists in both locations, the one for the specific blog will take precedence. As a general rule, there is no additional configuration required to make a plugin work, but this will depend on the particular plugin. None of the plugins that ship with LnBlog require additional configuration, but some thrid-party plugins might.Also, note that the standard plugins are all self-contained, so if you want to turn one off, you can just delete the file.

Note that the precedence of plugins in a blog's plugins directory allows you to easily disable plugins on a per-blog basis. All you need to do is create an empty file with the same name as the system-wide plugin file you want to disable and put it in the plugins folder for your blog. One use of this is to turn off certain interface elements you don't want, because the sidebar panels, page banner, and the sitemap are all done with plugins. So, if you are using LnBlog on a local network and want to turn off the Google search in the sidebar, you can justcreate an empty file named sidebar_5_googlesearch.php file in your blog's plugins folder.

## CMS Features

While LnBlog is a technically a weblog package, it also includes several "mini-CMS" features. These exist mostly for the sake of maintaining the design consistency of the site and making it slightly easier to manage. The following sections describe these.

### Adding Articles

An article in LnBlog is just a blog entry with a different URL and different display template. It's basically a cheap and easy way to add static content that meshes with the overall look and feel of the blog, but doesn't require any extra work. You still get BBCode support and revision history, but the URL structure is pneumonic and comments are turned off by default. You can enter the last component of the article URL when you first post it or go with the default, which is to use the subject with all letters converted to lower case, spaces converted to underscores, and all other characters removed. In addition, articles have a "sticky" attribute that you can set. This will cause a link to the article to be displayed in the sidebar (provided you're using one of the default themes).

### Uploading Files

LnBlog provides pages to upload files to the root of the current blog or to the current entry or article. Currently, you can only upload one file at a time. You should also note the file size limit when trying to upload a file. To change this, must change the values of the PHP configuration variables upload_max_size and post_max_size by creating a .htaccess file (if you use Apache) or by modifying the system php.ini file.

### Sitemap Editing

Part of LnBlog's basic page layout includes a sitemap, also refered to as the menubar. In the default theme, this is the bar just under the banner with your blog name. It is intended for global site navigation, e.g. to go from one blog to another or to other sections of your website. Needless to say, you will want to customize it for your own site.

There are two ways to edit the menubar: globally for al LnBlog blogs, or locally to just the current blog. To edit the global sitemap, use the link on the LnBlog administration page where you will see a link to the sitemap editor. To change the sitemap for a particular blog, log in and use the link in the administration section of the blog sidebar. Note that setting a sitemap for the blog will override the global sitemap.

The sitemap editor is a simple Javascript form that creates a list of links. Just enter the text you want for the link, the tooltip (what to display when hovering the mouse over the link), and the target URL for the link, either relative or absolute. When you click the "Add Link" button, a line will be added to the output box with the HTML code for the information you specified. When a page is displayed, LnBlog will read this file and put each line into a list item to be displayed in the menubar. Please note that, currently, if you want to create a more complicated menu layout, you will have to modify the menubar template.

## License Information

LnBlog: A simple file-based weblog focused on design elegance.
Copyright (C) 2005 Peter A. Geer <pageer@skepticats.com>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.