Release 0.5 Changes

Version 0.5 represents a complete rewrite of Pie's code library, extending its features and extendability to even higher levels. Not only have the low-level I/O-routines been detached from the high-level procedures, but the former have also been abstracted by introducing object orientated programming techniques into the library code, enabling developers to replace them by customized variants that suit their needs.

Directory Structure

The number of working directories has been reduced to three:

  1. ${library_path} contains the code library, including low-level classes and high-level scripts, as well as locale files for all supported actions.
  2. ${custom_path} contains site-related customizations.
  3. ${run_path} contains all variable data of the site, that is, pages, files, user data, temporary files, etc.

You specify the location of these directories in the configuration file, which, in turn, is parsed in the master multiplexer script, pie.php.

Run-time Configuration

Pie's run-time configuration has been removed from pie.php and been put into a dedicated configuration file that is being parsed every time the multiplexer script is executed. All configuration options are specified in PHP's ini-file format.

Action Scripts

Each command now comes with its own script file, all of which reside below ${library_path}/action. To modify the behaviour of an action, refer to the homonymous script file. To create a new one, just create the respective file in the action directory.

Locale Files

Locale files have been changed, in number as well as in format. Unlike former releases that used but a single locale file to hold all strings as one-line key/value-pairs, the current version provides a specific locale file for each callable action. Locale values can now comprehend several lines of arbitrary content, including literal text, HTML-code, automatically expanded variable references, as well as recursive references to other keys. It is inside these very files where multiple languages and language-specific changes are being kept and maintained.

Installer/Setup-Script

Version 0.5 comes with an installer script, setup.php, that handles most of the work that is to be done for setting up a new site, or to upgrade an existing site to the current version. After extracting the contents of the distribution archive, make the necessary changes to the configuration file(s) and call setup.php. Once the setup process is finished, you are ready to use your new site.

Aliases

Pages and files may now have aliases associated with them. An aliases is a dummy entry of the respective category, page or file, that possesses no content and property but its name, as well as the name of the page or file it acts as an alias for. Once an alias is called for, it redirects the user to this original resource. That way, multiple notations of a resource are easily created without having to maintain the contents of several independent copies.

File History

Like pages, files too have now a revision history. Thus, a new version of an uploaded file does not replace an existing version any longer, but instead creates a distinctive new version, keeping the former for later reference. You may still overwrite the previous version of a file you upload, if you are author of both consecutive versions.

Browsing & Editing Context

Additional to the common Browsing context that is used to browse through pages and view content, a new context, the Editing context, has been introduced. The reason for separating Browsing and Editing is that the former's appearance and behaviour is usually customized to meet site-specific demands, while the latter is supposed to provide a practical, low-fidelity (yet feature-rich) editing environment to edit pages and make changes to the contents of the site. The Editing context is only available for authenticated users and can be customized by the editors in regard of its appearance.

Look & Feel

In addition to the strict separation of Browsing and Editing, some effort has been spent to make Pie easier and more comfortable to use. One aspect of improving usability is the use of icons and symbols to emphasize the meaning of status, action and context, respectively, catching the editor's eye more elegantly than by the means of mere words. To keep icons from violating a customized site's allover appearance, most symbols only come into play while editing and changing contents, that is, while users operate in the Editing context.

The editing panel's capabilities to serve users to include special markup and formatting options into a document have been extended. On most browsers, the panel now supports marked words and chunks of text to apply formatting to. For instance, you can mark the word MyPage in your text and then click the Page Link button to enclose the marked text in double brackets, making it a page link.

What's more, a number of shortcuts are now available to trigger specific actions that would otherwise require the pointing and clicking of your mouse. Using these shortcuts, you simply press Alt-E (Windows) or Ctrl-E (Mac OS) to edit the current page, <Cmd>-H to list its editing history, <Cmd>-V to verify its links, as well as some more keys to trigger frequently used actions. You can, however, still call these commands via a menu in the Editing mode.

The result of editing a page can now be previewed. This is particularly useful for new users who would like to verify what they have been typing before finally confirming an update. It is also useful for editors who perform lengthy changes to a page and want their update to be published en bloc instead of repeatedly re-editing the text.

Markup Code

Definition Lists

The components of a definition list item may now be separated by a single colon delimiter (:) as well as the conventional double colon delimiter (::). Both methods can be mixed arbitrarily. However, it is still just a single colon selector at the beginning of a line that actually triggers a definition list.

: Topic : Explaination
: Another topic :: Another explaination

Escaping Special Characters in Environments

The use of some characters conflicts with the delimiters of certains environments. To employ the example of the definition lists once more, you can (could, that is) not use a colon as literal content of an item without breaking apart the line at the respective position, separating the list title from the description. The same applies to the pipe character (|) used to specify alternate text in links that could not be used inside tables, the latter of which split the cells of a row when meeting a pipe.

The solution for including such characters literally is to place them in brackets (or double brackets). The content of brackets is never split apart, but treated atomical in regard of parsing for special characters.

; Colon in definition list:
: [[http://pie.ekkaia.org/]] : Project home page.

; Pipe inside table:
|Some text | [[http://foo.bar/|Alternate|text]]|

Detached Commands

A command in single brackets found in a line standing for itself without any other content is treated independently of its environment. Neither is a new environment introduced, nor closed when meeting such a command. If the command generates output, that output is simply appended to the output rendered so far. More specificly, detached commands do not create new paragraphs around themselves.

In the former software releases, the code

Prologue..

[image:MyPortrait.jpg|My portrait]

Epilogue..

created a dedicated paragraph for the embedded image following the first line because the [image:] command is surrounded by empty lines. Starting with version 0.5, detached commands do not create environments anymore, and thus will render the image without a surrounding paragraph, while the preceeding and succeeding line would still reside in their paragraphs, respectively.

To explicitely put the output of a command into a paragraph of its own, you can either enforce a new paragraph by specifying its alignment at the beginning of the line, using the <, > and >< selectors, respectively, or by placing additional (maybe invisible) content into the line to accompany the command and therefore prevent it from standing alone.

Prologue..

< [image:MyPortrait.jpg|My portrait]
; Alternative:
; Put something like a non-breaking space ([_]) after the image:
; [image:MyPortrait.jpg|My portrait][_]

Epilogue after an image that is placed in a left-aligned paragraph.

Customization of Text Blocks

Additional to the [begin:block ...] and [end:block] directives to apply a specific CSS class or id-customization to a text block, you can now use the [class:<className>] command and its twin, [style:<className>], to apply a CSS class to the very next text block. The term next text block is context sensitive. If put right before a new paragraph, the content of this paragraph as treated as the text block and is customized in the way specified via [class:] and [style:], respectively. If a superior environment, such as a list, exists, the customization applies to the next item within that environment.

Because of its more convenient readability, [class:] and [style:] should usually be preferred instead of the opening/closing derivative. However, in certain cases, where the non-standardized appearance is supposed to stretch over several blocks, opening and closing a customized environment is inevitable. Note also that [style:] supports CSS classes only. Named references (IDs) must still be envoked via [begin:].

;The following customization applies to the table as a whole:
[class:priceList]
|=Item|=Price|
|Apple|0.30|
|Pear|0.35|

;The following customization applies to the table row it preceeds:
|=Stock|=Value|
|Apple|43.21|
[class:remarkable]
|IBM|12.34|
|Sun Microsystems|23.45|

Image Preview

The [preview:] command evokes a small version of an image to be embedded on a page. When clicked, the full-sized version of that image is opened in a new browser window. The format of how to use this command is the same as with [image:]. The actual appearance of preview images is defined via the preview CSS class on a system-wide basis.

[preview:NewModel.jpg|Click to open in full size]

Localized Commands

Pie now supports localized commands to make editing more convenient for authors of non-English sites. Given you have installed a foreign language package for the page compiler and configured your site to use that particular locale (default_locale in pie.ini), your users can henceforth use localized versions for commands like [image:], [file:], [class:], etc.

Import of Pages and Files

Pages and files can be imported comfortably by the means of the administrator's maintenance area. The import parser supports common plain text files and standard files as common pages and files, respectively, as well as Pie's native XPF files for pages and files. The former allows you to import arbitrary files as pages and files. The support of XPF files allows you to re-import data of an other Pie-managed site, like it would be the case with leftovers of an older installation.

Name Space

The name space for pages and files has been considerably extended and comprehends now (almost) any character, letter or symbol available, including spaces. This allows links like [[William Henry Gates III]] or [[Phoenix (bird)]] to create pages with names consisting of multiple, space-separated words.

Consequently, blanks can not be used to provide alternate text any longer. The default delimiter character to separate link names from alternate text is now the vertical bar (|). The delimiter can be configured in the run-time configuration file. For imported pages, the administrator has to decide whether to convert pages written in the old syntax to adapt the new notation.

For the sake of readability, group paths of links are removed when such links are embedded into continuous text. As a result, the link [[Software/OS/BSD]] reads just "BSD", though the full link name is used to refer to the designated page. The same applies to name suffices made of parenthesized text, like (bird) in [[Phoenix (bird)]], much like it is done by MediaWiki.

Character Encoding

UTF-8 is now the standard character encoding for pages as well as for resource names. As a matter of fact, you can now include (almost) any Unicode character into your texts, or make it part of the name of a page or file.

Pie powered