Kiriwrite Documentation - - User Documentation

+ User Documentation
+ +The User Documentation contains information on how to install Kiriwrite, operate Kiriwrite, solutions to common problems that occur while using Kiriwrite and tips on using Kiriwrite. + +

+Preface

+Kiriwrite originally came into existence in 2003 when I was designing a new layout for my personal website (Kirinji's Pad) and found that I had so many pages to edit, I had to find an easier way of editing the website layout as I needed to and apply those changes to all of the pages on the website very quickly.

+As I was designing my website using an advanced free ware text-editor (at it's time) which allowed me to create a template and create pages as I needed which was great, until I wanted to redesign the website. At that point I had around 50 pages which had to be changed and became somewhat time consuming.

+That was when I wrote the original Kiriwrite script which was coded pretty much to my own needs and wasn't really well organised and was coded in Perl (although not that brilliantly as strict and warnings weren't used since I was learning Perl at the time) and by the time I finished coding it, I was able to do what I needed to do with Kiriwrite.

+Around the end of 2005 (and after a two-year spell at St. Austell College which is now Cornwall College St. Austell) I decided to rewrite the Kiriwrite code because the original Kiriwrite did not do any input validation and so little of the code was commented which meant I forgot what everything did and I wanted to add some new features which would become useful in the future.

+The rewritten Kiriwrite version was pretty much done in October 2006, following a suggestion from a good friend I decided to replace the flat-file based system which I used since the original Kiriwrite with a file-based database system called SQLite. Once that was done pretty much around the end of January 2007, I then separated the database code, presentation code and language strings into separate modules and files which meant that a MySQL 5.x server-based database could be used instead of file-based SQLite. The presentation code used to render internal output from Kiriwrite was separated and placed in the HTML4S (HTML 4.01 Strict) presentation module. The language strings that was hard-coded were separated and placed in the English (British) language file.

+After some minor tweaks, the rewritten Kiriwrite code was pretty much ready and once the documentation was written Kiriwrite was ready for release. What I would like to see in the future for Kiriwrite is to make it work with mod_perl and add some extra customisable features as some settings are currently hard-coded when they could very well not be hard-coded.

+I leave you with some advice, if you are going to design a website which uses a white background don't assume everyone will use a white background by default if no colour is specified and actually declare it as white background in the Cascading Style Sheet markup. You'd be amazed at how many commercial websites and some personal websites (that expect you to have) assume you have a white background when really you have a teal coloured background.

+Introduction

+Kiriwrite is a web-based (browser-based) interface for creating pages for websites, intended for those who know how to create pages by hand and want to accelerate the process of (re)designing a static-only website.

+The documentation is split into three parts, the user documentation (which is this part), the developer documentation (for writing new modules or language files) and the tutorial documentation (the basics and how to use Kiriwrite).

+Although Kiriwrite isn't limited for creating pages for websites (as in you can create other types of text-based formats), Kiriwrite is primarily intended for creating pages for websites.

+Chapter 1: Installation

+Before Kiriwrite can be used, Kiriwrite needs to be installed properly and this involves obtaining the code from a source package or from a Subversion¹ repository, copying the needed files into the correct place, setting the correct permissions on the files and running the installation script.

+ +

+ + Warning
+ Please be aware (for this version), that Kiriwrite is intended to be used on a private web server and not on a public web server unless it is properly secured down because by default anyone can run Kiriwrite and manipulate the data already there. Suggested methods of securing down your Kiriwrite installation are available in Chapter 4: Usage Tips. + +

+ +
+ +This chapter is split into two parts with the first part explaining on how to obtain Kiriwrite and the second part explaining on how to install Kiriwrite.

+ +

+¹ Subversion is a version control system which tracks changes to data stored in the repositories and allows easy updating of source code after the source code is checked out.

+1.1 Obtaining Kiriwrite

+Kiriwrite can be obtained either through the Subversion repository or extracted from a source archive that is available on Kiriwrite homepage.

+1.1.1: Archive Extraction

+The contents of the Kiriwrite archive can be extracted using gzip if it's a Gzip archive, bzip2 if it's a Bzip2'ed archive, 7za if it's a 7-Zip archive and unzip if it's a ZIP archive.

+Bear in mind the following is done from a command console. GUI interfaces can also do the same as preformed here and mainly involves opening the archive and clicking on the Extract/Extract All button or simply dragging the folder containing from out of the archive (usually making a copy of the contents in the archive).

+ +

+ Note
+ The naming convention of the Kiriwrite archives go as the following:

+

+ kiriwrite-x.y.z(-e).arc +

+
+ Where x is the major version, y is the minor version and z is the revision with (-e) meaning a very tiny modification that had to be done that did not merit an increment to the revision number. +

+ +
+ +When downloading an archive, the archive can be checked (by downloading the file with the same name but with .sha256 or .md5 added to the end of it) using shasum¹ or md5sum by doing the following to ensure it is downloaded correctly:

+ +

+ shasum -a 256 kiriwrite-x.y.z(-e).arc
+ md5sum kiriwrite-x.y.z(-e).arc +

+ +
+ +shasum or md5sum should then generate the SHA-256 or MD5 checksum that should match the one that appears in the file with .sha256 or .md5 appended to it. If it does not match (and the file containing the sha256 or md5sum hash is the correct version) then the archive should be downloaded again and repeat the same process.

+To extract the gzip archive, the following command should be preformed when switched to the correct directory to extract from.

+ +

+ gzip -d -c (path)/kiriwrite-0.1.0.tar.gz | tar -xv +

+ +
+ +A list of files that have been extracted will then appear with the contents of the archive appearing in the directory that the archive was extracted to.

+To extract the bzip2 archive, the following command should be preformed when switched to the correct directory to extract from.

+ +

+ bzip2 -d -c (path)/kiriwrite-0.1.0.tar.bz2 | tar -xv +

+ +
+ +A list of files that have been extracted will then appear with the contents of the archive appearing in the directory that the archive was extracted to.

+To extract the ZIP archive, the following command should be preformed when switched to the correct directory to extract from.

+ +

+ unzip (path)/kiriwrite-0.1.0.zip +

+ +
+ +A list of files that have been extracted will then appear with the contents of the archive appearing in the directory that the archive was extracted to.

+To extract the 7Zip archive, the following command should be preformed when switched to the correct directory to extract from.

+ +

+ 7za e (path)/kiriwrite-0.1.0.7z +

+ +
+ +A list of files that have been extracted will then appear with the contents of the archive appearing in the directory that the archive was extracted to.

+ +1.1.2: Subversion Access

+Kiriwrite can also be obtained through checking out the code from the Subversion repository.

+ +

+ Note
+ Bear in mind that the code that is in the Kiriwrite Subversion repository is normally unstable and could very well cause unexpected problems (such as warnings that appear in the web server error log that can be easily fixed and alterations to the database structure which requires an upgrade script which hasn't been written yet for that particular version yet). +

+ +
+ +Kiriwrite can be obtained from the Subversion repository by doing the following in a command console after selecting the correct directory to put it in:

+ +

+ svn checkout svn://svn.berlios.de/kiriwrite/trunk +

+ +
+ +A list of files then appear as they are received from the Subversion repository and placed in the directory the command console is currently in. To update the code stored locally with code that is in the Kiriwrite Subversion repository this command should be done after changing to the directory where the local copy of the Kiriwrite Subversion code is:

+ +

+ svn update +

+ +
+ +A list of files will then appear showing which files has been updated. + +

+¹ The version of shasum talked about here is the shasum script that is used by the Digest::SHA::PurePerl Perl module which can produce checksums in SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512 which can be installed via CPAN.

+1.2.1 Copying files

+Before Kiriwrite can be used, the files need to be copied to the correct place. After extracting the archive, the structure of the extracted archive should be like this:

+Documentation â Documentation that is available in several languages.
+cgi-files â The main Kiriwrite script, associated modules, installer script and language files.
+ Modules â Modules for Kiriwrite are stored here.
+ Database â Database modules are stored here.
+ Presentation â Presentation modules are stored here.
+ db â Default database directory (for file based Database modules).
+ lang â The directory for language files in Kiriwrite.
+ lib - Library files that are used by Kiriwrite.
+ output â The output directory when pages are compiled.
+misc â Miscellaneous files (mainly for developers).
+non-cgi-files â Non CGI files that need to be placed outside of the cgi-bin folder.

+The files in the cgi-files folder should be copied to the cgi-bin¹ folder² and the files in the non-cgi-files folder should be copied to a folder which can be accessed from the web server.

+1.2.2 Setting Permissions

+The following permissions should be set for the files that have been copied to the cgi-files directory (the following file list should apply to those running *nix/BSD systems):

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Filename	Owner	Group	Others
(Top Directory)	RWX	RX	None
Modules	RX	RX	None
Modules/Database	RX	RX	None
Modules/Database/MySQL.pm	R	R	None
Modules/Database/SQLite.pm	R	R	None
Modules/Presentation	RX	RX	None
Modules/Presentation/HTML4S.pm	R	R	None
db	RWX	RX	None
output	RWX	RX	None
lang	RX	RX	None
lang/*.lang	R	R	None
lib	R	R	None
lib\*.lib	R	R	None
kiriwrite.cgi	RWX	R	None
install.cgi	RWX	R	None
page.html	R	R	None

+ +

+ +R = Read, W = Write, X = Execute/Allow directory listing

+For the non-cgi files folder, read only permissions should be set on all files (and read and allow directory listings for directories) as no writing should be needed.

+Once this is done, the installer script can be run by browsing to URI location of where the files in the cgi-files directory were in place and adding install.cgi to the end of it.

+

+¹The cgi-bin folder is used for storing scripts that use the Common Gateway Interface (CGI). CGI scripts are typically associated with Perl scripts but can also be C++, C, Python, shell script and many others.
+²Some servers are configured so that CGI scripts can run from any directory so in this case Kiriwrite doesn't have to be placed in the cgi-bin directory.

+1.3 Kiriwrite Installer Script

+After pointing your browser to the installer script, a page appears which guides you through configuring the settings for Kiriwrite.

+At the top of the page a drop down box is available to change the language of the installer script to another language which is more easier to understand, simply select the language from the drop down box and click on the Switch button, the script will then switch to the selected language.

+The installer script will preform three tests, the first being to check if all the needed modules are there, the second test is to check if the modules needed for the database modules are there and finally a test to check if the directories have their correct permissions set.

+Before the settings can be configured, checks are made to make sure that all of the needed modules are installed properly. If any of the needed modules are missing an error message will appear saying that one or more of the required Perl modules is missing and will need to be installed which can be done from the CPAN interface.

+The installer script then checks to see if at least of the Perl modules for the database modules are installed. If none of the Perl modules needed for the database modules are found then an error message will appear saying that none of the Perl modules needed for the database modules are installed and will need to be installed which can be done from the CPAN interface.

+Finally, the installer script then checks to see if the directories have the minimum correct permissions set. If one or more of the directories has an error, then a message appears saying to make sure that the correct permissions are set.

+ +

+ Hint
+ More information on solving problems that occur while installing Kiriwrite can be found in Chapter 5: Troubleshooting. +

+ +
+ +When the installer finds that everything is fine in regards to Perl modules and file permissions, a form appears allowing to configure the Kiriwrite installation to specific needs. Some default values are given which will work with the file-based database modules.

+The configuration settings in detail:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Database Directory	Specifies the database directory to use for storing databases that are created by the file-based database modules. This option is ignored by the server-based modules.
Output Directory	Specifies the output directory to use to store the compiled pages.
Images (URI path)	Specifies the Images (URI path) to use for displaying images when using the page template with Kiriwrite.
Text Area Columns	Specifies the width of the text area when editing notes, pages and templates.
Text Area Rows	Specifies the height of the text area when editing notes, pages and templates.
Date Format	Specifies the date format to use when list the pages from the database. A selection of date formats are available from the drop down box or a custom one can be entered into the text box next to the drop down box.
Language	Specifies the system language to use in Kiriwrite. If the language used in the installer script is available as language to use in Kiriwrite then that language will be selected by default.
Presentation Module	Specifies the presentation module to use in Kiriwrite.
Database Module	Specifies the database module to use in Kiriwrite. SQLite is a file-based database module which uses the database directory and the SQLite Perl module while MySQL5 is a server-based database module which uses a MySQL 5.x server from the MySQL Perl module.

+ +
+ +The following options are used only by the server-based database modules:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Database Server	Specifies the database server to use.
Database Port	Specifies the database port to use.
Database Protocol	Specifies the database protocol to use.
Database Name	Specifies the database name to use.
Database Username	Specifies the database username to use.
Database Password	Specifies the database password to use.
Database Table Prefix	Specifies the table prefix to use. Multiple Kiriwrite installations can use the same server database so long as the table prefix is different.

+ +
+ +There is an option that is enabled by default to attempt to delete the installation script after the configuration file has been written since the installation script would no longer be needed after that. Unchecking the box for this option disables this.

+Click on the Save Settings button to write the configuration file or the Reset Settings button to restore the settings to their default values.

+After clicking on the Save Settings button, some checks are made to make sure that data passed is correct, the configuration file is written (and the installer script deleted if requested) and a message appears saying that Kiriwrite can now be used by clicking on the link at the bottom of the page. +

+Chapter 2: Operation

+Now that Kiriwrite is installed and working, this chapter is about operating Kiriwrite. This chapter is split into five parts:
+ +

Databases, how to add a database, edit a database and delete a database.
Pages, Selecting a database, creating, editing and deleting pages, deleting, moving, copying and editing multiple pages.
Filters, adding a filter, editing a filter and deleting a filter.
Templates, adding a template, editing a template and deleting a template.
Compiling, compiling one, selected or all databases and cleaning the output directory.

+2.1 Databases

+Databases are used for storing the pages that are created in Kiriwrite. Before pages can be stored in a database, a database has to be created.

+The default view when you run the Kiriwrite script is to show the list of databases. If there are no databases available, then a message appears saying that there are no databases than can be used.

+2.1.1 Add a database

+To add a database, from the View Databases sub-menu click on the 'Add Database' link, a form then appears allowing to enter the information about the new database.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Settings	Description
Database Name	Specifies the database name of the new Kiriwrite database.
Database Description	Specifies the description of the new Kiriwrite database.
Database Categories	Specifies the categories the database should belong to.
Database Notes	The notes that gives information about the database.
Database Filename	Specifies the database filename to use. If nothing is entered for the filename than an attempt to automatically generate a filename will be done.

+ +
+ +To add the database with the settings given, click on the 'Add Database' button and a confirmation message should then appear saying that the database has been added and offering a link back to the list of databases. To clear the settings, click on the 'Clear values' button.

+ +2.2 Edit a database

+To edit a database, click on the 'Edit' link opposite the name and description of the database you want to edit. A form then appears similar to the form for adding a database.

+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Settings	Description
Database Name	Specifies the new database name of the Kiriwrite database.
Database Description	Specifies the new description of the Kiriwrite database.
Database Categories	Specifies the new categories the database should belong to.
Database Notes	The notes that gives information about the database.
Database Filename	Specifies the database filename to use.

+ +
+ +To edit a database with the new settings given click on the 'Edit Database' button and a confirmation message should appear saying that the database has been edited and offering a link back to the database list. Clicking on the 'Restore current settings' button will undo any changes and revert to the currently used settings.

+ +2.3 Delete a database

+To delete a database, click on the 'Delete' link opposite. A message then appears asking if the selected database should be deleted. Clicking on the 'Yes, delete the database' button will delete the database and display a confirmation message saying that the selected database has been deleted offering a link to return to the database list. Clicking on 'No, return to the database list.' link will make it return to the database list.

+ +

+ + Warning
+ When a database is deleted, the pages in the database are deleted as well. + +

+2.2 Pages

+ +Pages are used for storing information that is relevant to that page.

+ +Pages can be access from the 'View Pages' menu link. As no database is selected, a drop down box will appear listing the databases that are available, select a database and then click on the View button. A list of pages for that database will then appear and if there are no pages in the database a message will appear saying that no pages exist in this database.

+ +To view the next (or previous list) of pages, click on the relevant link at the top of the page and to view a specific list of pages, select the list page number in the drop down menu box at the top of the page and click on the Show button.

+ +2.2.1: Creating a page

+A page can be created in the selected database by clicking on the 'Add Page' link in the View Pages sub-menu, a form then appears allowing to enter the information about the new page.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Database	Specifies the database that the page is being added to.
Page Name	Specifies the name of the new page.
Page Description	Specifies the description of the new page.
Page Section	Specifies the section name of the new page.
Page Template	Specifies the page template to use.
Page Filename	Specifies the page filename to use.
Page Content	Specifies the content of the page.
Page Settings	Specifies if the page name and section should be used for the title.

+ +
+ +The following Kiriwrite tags can be used with the page content to automatically place information such as page name, description and section:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Tag	Description
<kiriwrite:pagetitle>	Places the page title here. The format of the page title can be changed using the Page Settings value.
<kiriwrite:pagename>	Places the page name here.
<kiriwrite:pagedescription>	Places the page description here.
<kiriwrite:pagesection>	Places the page section here.
<kiriwrite:autosection>	Places the automatic page section here. + + + Note + If there is a page section then the page section will appear bracketed. If Information was the page section then the automatic page section name would be '(Information)' and if the page section name is blank then no brackets will appear and will be blank. + + +
<kiriwrite:autotitle>	Places the automatic page title here. This combines the section name and page name with brackets around them and a dash separating them with '(Section Name â Page Name)' being the example. The format can be changed by changing the Page Settings value.

+ +
+ +After entering the needed page information, the page can be added to the selected database by clicking on the 'Add Page' button and then a confirmation message would appear saying that the selected page has been added and offering a link to return to the page list for the selected database. The new page settings can be cleared by clicking on the 'Reset Settings' button.

+ +2.2.2: Editing a page

+ +To edit a page, click on the 'Edit' link opposite the page filename you want to edit. A form then appears that is similar for adding a page.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Database	Specifies the database that the page is being edited from.
Page Name	Specifies the new name of the page.
Page Description	Specifies the new description of the page.
Page Section	Specifies the new section name of the page.
Page Template	Specifies the new page template to use.
Page Filename	Specifies the new page filename.
Page Content	Specifies the new content of the page.
Page Settings	Specifies if there should be a new page name and section setting.

+ +
+ +The following Kiriwrite tags are used for when adding a page can also be used when editing a page:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Tag	Description
<kiriwrite:pagetitle>	Places the page title here. The format of the page title can be changed using the Page Settings value.
<kiriwrite:pagename>	Places the page name here.
<kiriwrite:pagedescription>	Places the page description here.
<kiriwrite:pagesection>	Places the page section here.
<kiriwrite:autosection>	Places the automatic page section here. + + + Note + If there is a page section then the page section will appear bracketed. If Information was the page section then the automatic page section name would be '(Information)' and if the page section name is blank then no brackets will appear and will be blank. + + + +
<kiriwrite:autotitle>	Places the automatic page title here. This combines the section name and page name with brackets around them and a dash separating them with '(Section Name â Page Name)' being the example. The format can be changed by changing the Page Settings value.

+ +
+ +After entering the new information, the page can be edited by clicking on the 'Edit Page' button and a confirmation message appears saying that the page has been edited and offering a link back to the list of pages for the currently selected database. Clicking on the 'Restore current settings' button will undo any changes and revert to the current page settings.

+ +2.2.3: Deleting a page

+ +To delete a page, click on the 'Delete' link opposite the page filename you want to delete, a message then appears asking to confirm that page will be deleted. Clicking on the 'Yes, delete the page' button will delete the page and offer a link back to the list of pages for the selected database. Clicking on the 'No, return to the page list for the (database name) database.' link will return to the list of pages for the selected database.

+ +2.2.4: Delete multiple pages

+ +To delete multiple pages from the selected database click on the check-box that is to the left of the page filenames you want to delete and then click on the 'Delete Selected' button at the top of the page, a form will then appear asking to confirm if the selected pages listed should be deleted.

+ +Clicking on the 'Yes, delete the selected pages' button will display a confirmation message saying that the selected pages were deleted offering a link back to the list of pages for the selected database. Clicking on the 'No, return to the page list for the (database name) database.' will return to the list of pages for the selected database.

+ +2.2.5: Move multiple pages

+ +To move multiple pages from the selected database click on the check-box that is to the left of the page filenames you want to delete and then click on the 'Move Selected' button at the top of the page, a form will then appear asking to select which database the selected pages should go to and confirm that those pages are being moved to the new database.

+ +Clicking on the 'Move selected pages' button will display a confirmation message saying that the selected pages were moved to the new database selected offering a link back to the selected database that the pages were moved from and a link to the selected database where the pages have moved to. Clicking on the 'Return to the page list for the (database name) database' will return to the list of pages in the selected database.

+ +2.2.6: Copy multiple pages

+ +To copy multiple pages from the selected database click on the check-box that is to the left of the page filenames you want to copy and then click on the 'Copy Selected' button at the top of the page, a form will then appear asking to select which database the selected pages should be copied to and confirm that those pages are being copied to the new database.

+ +Clicking on the 'Copy selected pages' button will display a confirmation message saying that the selected pages were copied to the new database selected offering a link back to the selected pages that the pages were copied from and a link to the selected database where the pages have been copied to. Clicking on the 'Return to the page list for the (database name) database.' will return to the list of pages in the selected database.

+ +2.2.7: Edit multiple pages

+ +To edit multiple pages from the selected database click on the check-box that is to the left of the page filenames you want to edit and then click on the 'Edit Selected' button at the top of the page, a form will then appear that allows certain settings of each page to be edited as shown in the table below:

+ + + + + + + + + + + + + + + + + + +

Setting	Description
Page Section	Specifies the new page section to be used on the selected pages.
Page Template	Specifies the new page template to be used on the selected pages.
Page Settings	Specifies the new page settings to be used on the selected pages.

+ +
+ +Each setting that needs to be changed needs to have the check-box on the left of the name needs to be checked otherwise the change will not take effect. This is done to make sure that only the selected page settings are changed.

+Clicking on the 'Edit selected pages' button will display a confirmation message saying that the selected pages were edited offering a link back to the list of pages in the selected database, clicking on the 'Clear values' button will clear the currently selected values and clicking on the 'Return to the page list for the '(database name)' database.' link will return to the page list for selected database.

+2.3 Filters

+ +Filters allows text to be easily replaced by looking for certain words, tag or phrase and then replacing it with another set of words, tag or phrase.

+ +The list of filters can be viewed by clicking on the 'View Filters' link. If the filter database doesn't exist than a message will appear saying that the filter database doesn't exist and will be created when a filter is added or if the filter database does exist but there are no filters then a message appears saying that there is no filters in the filter database.

+ +When compiling the pages, the order of the filters list is determined by the filter priority number with the lower numbers being processed first and the filters with the higher filter priority numbers being processed last.

+ +To view the next (or previous list) of filters, click on the relevant link at the top of the page and to view a specific list of filters, select the list page number in the drop down menu box at the top of the page and click on the Show button.

+ +2.3.1 Add a filter

+ +To add a filter click on the 'Add Filter' link on the View Filters sub-menu, a form then appears allowing to enter the information about the new filter.

+ + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Find...	Specifies the find setting to search text for.
Replace With...	Specifies the replace setting to replace the text with if the search text is found.
Priority	Specifies the priority of the filter.
Notes	Specifies the notes for this filter.

+ +
+ +After entering the needed filter information, the filter can be added by clicking on the 'Add Filter' button which displays a confirmation message saying that the filter has been added to the filter database and offering a link back to the list of filters in the filter database. Clicking on the 'Clear values' button will clear any of the filter settings that have been entered and clicking on the 'Return to the filter list.' link will return to the list of filters in the filter database.

+ +2.3.2 Edit a filter

+To edit a filter click on the 'Edit' link opposite the filter you want to edit. A form then appears that is similar to adding a filter.

+ + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Find...	Specifies the new find setting to search text for.
Replace With...	Specifies the new replace setting to replace the text with if the search text is found.
Priority	Specifies the new priority of the filter.
Notes	Specifies the new notes for this filter.

+ +
+ +To update the information about the filter, click on the 'Edit Filter' button and a confirmation message should appear saying that the selected filter was edited offering a link back to the list of filters in the filter database. Clicking on the 'Restore current settings' will undo any changes made and will revert the currently used filter settings and clicking on the 'Return to the filter list.' link will return to the list of filters in the filter database.

+ +2.3.3 Delete a filter

+ +To delete a filter click on the 'Delete' link opposite the filter you want to delete. A form then appears asking to confirm the deletion of the selected filter. Clicking on the 'Yes, delete the selected filter' button will display a confirmation message saying that the selected filter was deleted. Clicking on the 'No, return to the filter list.' link will return to the list of filters in the filter database.

+2.4 Templates

+ +Templates allows pages to use a common layout which is used to keep a consistent layout on a website or keep the format of documentation pages the same. Templates also allow small tweaks to the page layout to be made without needing to edit each page so the change is reflected in all of the pages by simply changing the template layout and then recompile the pages.

+ +The list of templates can be accessed by clicking on the 'View Templates' link. A list of templates from the template database should then appear. If the template database does not exist then a message will appear saying that the template database does not exist and will be created when a template is added. If no templates exist in the template database then a message appears saying that there are no templates in the template database.

+ +To view the next (or previous list) of templates, click on the relevant link at the top of the page and to view a specific list of templates, select the list page number in the drop down menu box at the top of the page and click on the Show button.

+ +2.4.1 Add a template

+ +To add a template to the template database click on the 'Add Template' link from the View Templates sub-menu, a form then appears allowing to enter the new information about the template.

+ + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Template Name	Specifies the template name to be used.
Template Description	Specifies the template description to be used.
Template Filename	Specifies the template filename to use.
Template Layout	Specifies the content of the template layout.

+ +
+ +The following Kiriwrite tags can be used with the template layout to automatically place information such as page content, name, description and section: + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Tag	Description
<kiriwrite:pagecontent>	Places the page content here.
<kiriwrite:pagetitle>	Places the page title here. The format of the page title can be changed using the Page Settings value.
<kiriwrite:pagename>	Places the page name here.
<kiriwrite:pagedescription>	Places the page description here.
<kiriwrite:pagesection>	Places the page section here.
<kiriwrite:autosection>	Places the automatic page section here. + + + Note + If there is a page section then the page section will appear bracketed. If Information was the page section then the automatic page section name would be '(Information)' and if the page section name is blank then no brackets will appear and will be blank. + + +
<kiriwrite:autotitle>	Places the automatic page title here. This combines the section name and page name with brackets around them and a dash separating them with '(Section Name â Page Name)' being the example. The format can be changed by changing the Page Settings value.

+ +
+ +After entering the needed template information, click on the 'Add Template' button to display a confirmation message saying that add the template to the list of templates in the template database and offering a link back to the list of templates in the template database. Clicking on the 'Clear values' button will clear all of the template settings entered. Clicking on the 'Return to the template list.' link will return to the list of templates in the template database.

+ +2.4.2 Edit a template

+To edit a template click on the 'Edit' link opposite the template name you want to edit, a form then appears that is similar to adding a template.

+ + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Template Name	Specifies the new template name to be used.
Template Description	Specifies the new template description to be used.
Template Filename	Specifies the new template filename to use.
Template Layout	Specifies the new content of the template layout.

+ +
+ +The Kiriwrite tags used when adding a template can also be used when editing a template. + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Tag	Description
<kiriwrite:pagecontent>	Places the page content here.
<kiriwrite:pagetitle>	Places the page title here. The format of the page title can be changed using the Page Settings value.
<kiriwrite:pagename>	Places the page name here.
<kiriwrite:pagedescription>	Places the page description here.
<kiriwrite:pagesection>	Places the page section here.
<kiriwrite:autosection>	Places the automatic page section here. + + + Note + If there is a page section then the page section will appear bracketed. If Information was the page section then the automatic page section name would be '(Information)' and if the page section name is blank then no brackets will appear and will be blank. + + +
<kiriwrite:autotitle>	Places the automatic page title here. This combines the section name and page name with brackets around them and a dash separating them with '(Section Name â Page Name)' being the example. The format can be changed by changing the Page Settings value.

+ +
+ +After editing the information about the template, the template can be edited by clicking on the 'Edit Template' button which will display a confirmation message saying that the template information was edited offering a link back to the list of templates in the template database. Clicking on the 'Restore current settings' button will undo any changes and revert to the currently used settings. Clicking on the 'Return to the template list.' will return to the list of templates in the template database.

+ +2.4.3 Delete a template

+ +To delete a template click on the 'Delete' link opposite the template name you want to delete, a message then appears asking to confirm the deletion of the selected template. Clicking on the 'Yes, delete the template' button will display a confirmation message saying that the selected template has been deleted offering a link back to the list of templates in the template database. Clicking on the 'No, return to the template list.' link will return to the list of templates in the template database.

+2.5 Compiling

+ +Compiling combines the page data with the template layout and the filters that are in the filter database to create pages as if they were created manually.

+ +To compile the pages from their databases, click on the 'Compile Pages' menu link. A list of databases will then appear which can be compiled. If no databases are available then a message will appear saying that no databases are available.

+ +2.5.1 Compiling a database

+ +To compile a database, click on the 'Compile' link opposite the database name you want to compile, a message then appears asking if the database should really be compiled. Clicking on the 'Compile Database' button will display a log of pages that have been compiled and any error messages that might appear with the link to return to the list of databases to compile at the end of the log.

+ +When compiling a database, the template being used on the pages in the database selected can be overridden. To override the templates being used, click on the 'Override the template being used' box and select the template to override with.

+ +Clicking on the 'Return to the compile database list.' will return to the list of databases to compile.

+ +2.5.2 Compiling multiple databases

+ +To compile multiple databases click on the check-box to the left of the database name for each database that should have its pages compiled and click on the 'Compile Selected' button which will display a message asking to confirm if the selected databases shown should be compiled. Clicking on the 'Compile Selected Databases' button will display a log of pages that have been compiled and any error messages that might appear with the link to return to the list of databases to compile at the end of the log.

+ +When compiling a database, the templates being used on the pages in the databases selected can be overridden. To override the templates being used, click on the 'Override the template being used' box and select the template to override with.

+ +Clicking on the 'Return to the compile database list.' will return to the list of databases to compile.

+ +2.5.3 Compiling all databases

+ +To compile all of the available databases click on the 'Compile All' link in the Compile Pages sub-menu which will display a message asking to confirm if all of the databases should have its pages compiled. Clicking on the 'Compile All Databases' button will display a log of pages that have been compiled and any error messages that might appear with the link to return to the list of databases to compile at the end of the log.

+ +When compiling a database, the templates being used on the pages in all of the databases can be overridden. To override the templates being used, click on the 'Override the template being used' box and select the template to override with.

+ +Clicking on the 'Return to the compile database list.' link will return to the list of databases to compile.

+ +2.5.4 Cleaning the output directory

+ +Cleaning the output directory removes all of the contents that is in the output directory. To clean the output directory click on the 'Clean Output Directory' link which will display a message asking to confirm that the output directory should be cleaned. Clicking on the 'Yes, clean output directory' will display a confirmation message saying that the output directory was cleaned. Clicking on the 'Return to the compile database list.' link will return to the list of databases to compile.

+Chapter 3: Kiriwrite Settings

+ +The settings that are used in Kiriwrite can be viewed by clicking on the 'View Settings' link in the menu which will display a list of settings that are currently in use.

+ +3.1 Editing the settings

+ +To edit the settings, click on the 'Edit Settings' link in the View Settings sub-menu, a form then appears allowing the settings in Kiriwrite to be edited.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Database Directory	Specifies the database directory to use for storing databases that are created by the file-based database modules. This option is ignored by the server-based modules.
Output Directory	Specifies the output directory to use to store the compiled pages.
Images (URI path)	Specifies the Images (URI path) to use for displaying images when using the page template with Kiriwrite.
Text Area Columns	Specifies the width of the text area when editing notes, pages and templates.
Text Area Rows	Specifies the height of the text area when editing notes, pages and templates.
Date Format	Specifies the date format to use when list the pages from the database. A selection of date formats are available from the drop down box or a custom one can be entered into the text box next to the drop down box.
Language	Specifies the system language to use in Kiriwrite. If the language used in the installer script is available as language to use in Kiriwrite then that language will be selected by default.
Presentation Module	Specifies the presentation module to use in Kiriwrite.
Database Module	Specifies the database module to use in Kiriwrite. SQLite is a file-based database module which uses the database directory and the SQLite Perl module while MySQL5 is a server-based database module which uses a MySQL 5.x server from the MySQL Perl module.

+ +
+ +The following options are used only by the server-based database modules:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Setting	Description
Database Server	Specifies the database server to use.
Database Port	Specifies the database port to use.
Database Protocol	Specifies the database protocol to use.
Database Name	Specifies the database name to use.
Database Username	Specifies the database username to use.
Database Password	Specifies the database password to use.
Database Table Prefix	Specifies the table prefix to use. Multiple Kiriwrite installations can use the same server database so long as the table prefix is different.

+ +
+ +To save the new settings, click on the 'Change Settings' button which will display a confirmation message saying that the settings were changed and will take effect on the next page load of Kiriwrite offering a link back to the updated list of settings. Clicking on the 'Restore current settings' button will undo any changes made and will restore the current settings. Clicking on the 'Return to the list of settings.' link will return to the list of currently used settings.

+Chapter 4: Usage Tips

+This chapter mainly contains usage tips in securing your Kiriwrite installation and small features which may be useful for some users.

+ +

+ In this chapter, directory specific settings used in Apache is .htaccess. Typically, if the web server software is configured to check a file other than .htaccess then a different filename would be used (and would be blocked from being accessed from the web server). +

+4.1 Securing your Kiriwrite installation

+ +This section is about securing your Kiriwrite installation.

+ +4.1.1 HTTP Authentication

+ +HTTP Authentication allows users who only know the correct username and password to access pages that are not available to the public. HTTP Authentication is done by the following if you're using Apache 1.3.x/2.x from a command console:

+ +

+ htpasswd -c .htpasswd username +

+ +
+ +The -c switch specifies that a password file should be created called .htpasswd (although can be called something else), while username is the username of the login (which can be something else other than username), after pressing enter a password prompt then appears asking for a password to be entered the same twice.

+ +After the .htpasswd file is created, the file should be copied to a location that cannot be accessed from a URI resource (such as outside the htdocs/web documents directory) and then create a .htaccess file (if it doesn't exist) pointing to the password file with the following directives as an example.

+ +

+ AuthUserFile /home/www/website/private/.htpasswd
+ AuthType Digest
+ AuthName âPrivate Areaâ +

+ +
+ +The AuthUserFile directive should point to the htpasswd file that was created earlier on. The AuthType directive specifies the authentication type to use and AuthName specifies the name of the area to appear when entering the username and password.

+ +4.1.2 IP Address Filtering

+ +IP Address filtering allows certain IP addresses or hosts to be blocked from access and allowing everyone else access or blocking everyone from access and allowing certain IP addresses or hosts in. Typically when using Kiriwrite, the best method would be the white list method where everyone is blocked from access and only certain IP addresses or hosts can be allowed access.

+ +To setup a white list, open the .htaccess file and insert the following (if it already exists) if you're using Apache 1.3/2.x:

+ +

+ Order Deny, Allow
+ Deny from all
+ Allow from 127.0.0.1 +

+ +
+ +This example denies everyone and then only allows 127.0.0.1 (which is the computer the web server is running from which tends to be the machine you're using on a personal installation). Multiple Allow commands can be entered which allows multiple hosts.

+ +More information on using Allow and Deny can be found in the Apache 1.3/2.x Documentation.

+4.2 Renaming the main Kiriwrite script (kiriwrite.cgi)

+ +While the Kiriwrite script can be used as kiriwrite.cgi, the script has been designed so that it can work if it's renamed to something else such as docmake.cgi, private.cgi or even flyingrhinos.cgi. This can simply be done by renaming the script to whatever name is needed.

+ +

+ + Warning
+ Bear in mind that no matter what the script filename is called, it will always look for configuration file as kiriwrite.xml, the modules in the Modules directory and the language files in the lang directory. + +

+4.3 Removing unneeded modules and language files

+ +As Kiriwrite uses a modular system for manipulating the databases, outputting the pages internally by Kiriwrite and language files for each language used, space can be recovered by removing unneeded modules from the Modules directory and language files from the lang directory.

+ +To make sure that the currently used database module, presentation module and language file are not deleted from their directories. Check which ones should be kept by clicking on the 'View Settings' menu link.

+Chapter 5: Troubleshooting

+5.1 Common Problems

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Problem	Symptom	Solution
When installing, some of the needed Perl modules have the word 'Error' next to them.	The needed Perl modules are more than likely not installed.	Install the needed Perl modules from the CPAN archive using the CPAN command interface.¹
When installing, an error message appears saying that none of the needed Perl modules for the database modules are installed.	The needed Perl module(s) (or the Perl module needed specifically for that certain database module) are more than likely not installed.	Install the needed Perl modules from the CPAN archive using the CPAN command interface.
When installing, an error message appears saying that some of the directories and files have invalid permissions set.	The directories and/or files have invalid permissions set.	Change the permissions on the directories and/or files so that are the correct permissions needed.
When installing, no database or presentation modules appear in the list of available database or presentation modules.	The modules weren't copied or were copied to the wrong directories.	Copy or move the database modules to the correct directory.
When installing, no languages appears in the languages selection list.	The language files weren't copied or were copied to the wrong location.	Copy or move the language files to the correct directory.
When starting Kiriwrite, a critical error message appears saying that the configuration file does not exist.	The configuration file has been deleted or the installation script wasn't run.	Run the installer script (again).
When starting Kiriwrite, a critical error message appears saying that the configuration file has invalid permissions set.	The configuration file has invalid permissions set.	Change the permissions on the configuration file so that it can be read.
When starting Kiriwrite, a critical error message appears saying that the database module does not exist.	The database module has been deleted or renamed.	Run the installer script (again). + Check if the Modules and Modules/Database directory have the correct permissions set so that they can be read. +
When starting Kiriwrite, a critical error message appears saying that the database module has invalid permissions set.	The database module has invalid permissions set.	Change the permissions on the database module so that they can be read (execute permissions not usually needed).
When starting Kiriwrite, a critical error message appears saying that the presentation module does not exist.	The presentation module has been deleted or renamed.	Run the installer script (again). + Check if the Modules and Modules/Presentation directory have the correct permissions set so that they can be read. +
When starting Kiriwrite, a critical error message appears saying that the presentation module has invalid permissions set.	The presentation module has invalid permissions set.	Change the permissions on the presentation module so that they can be read (execute permissions not usually needed).
When starting Kiriwrite, a critical error message appears saying that the language file does not exist.	The language file does not exist.	Run the installer script (again). + Check if the lang directory has the correct permissions set so that they can be read. +
When starting Kiriwrite, a critical error message appears saying that the language file has invalid permissions set.	The language file has invalid permissions set.	Change the permissions on the language file so that they can be read.
When viewing the list of databases, an error message appears saying that the permissions of the database directory is invalid.	The database directory has incorrect permissions set.	Set the correct permissions (read and write) on the database directory.
When viewing the template database, an error message appears saying the permissions of the template database is invalid.	The template database has invalid permissions set.	Set the correct permissions (read and write) on the template database.
When viewing the filter database, an error message appears saying that the permissions of the filter database is invalid.	The filter database has invalid permissions set.	Set the correct permissions (read and write) on the filter database.
When compiling the pages, an error message appears saying that the output directory has invalid permissions set.	The output directory has invalid permissions set.	Set the correct permissions (read and write) on the output directory.
When compiling the pages, certain pages do not change when the pages are edited.	The pages have invalid permissions set.	Set the correct permissions (read and write) on those pages which have invalid permissions set.
When compiling the pages, the template database has invalid permissions set.	The template database has invalid permissions set.	Set the correct permissions (read) on the template database.
When compiling the pages, the filter database has invalid permissions set.	The filter database has invalid permissions set.	Set the correct permissions (read) on the template database.
When saving the new settings, an error message appears saying that the configuration file has invalid permissions set.	The configuration file has invalid permissions set.	Set the correct permissions (read and write) on the configuration file and then change the permissions back to read-only after saving the new settings.

+ +
+ +

+ +¹The CPAN (Comprehensive Perl Archive Network) command interface is normally included with Perl installations and will normally require superuser (root) permissions.

+Chapter 6: Contributing to Kiriwrite

+ +6.1: Contributing

+ +You can contribute to Kiriwrite in many different ways like the following examples: +

Translate Kiriwrite (program or documentation) so that it can be used your own local language.
Add functionality to Kiriwrite.
Write a presentation or database module.
Report a bug or fault (either with Kiriwrite itself or the documentation).

+ When reporting a bug, you should give the version number of Kiriwrite, what operating system you are using, what web server you are using and the version of it, the version of Perl you are using (and if possible the version of the Perl module that is causing the bug), what the error message of the bug is and how to recreate the bug (if possible). +

+ +For more information on how to contribute to Kiriwrite visit http://xestia.co.uk/kiriwrite or visit the BerliOS project site at http://developer.berlios.de/projects/kiriwrite . A list of stuff that needs doing can be found in the TODO file in the Kiriwrite package (remember to check the latest Kiriwrite package's TODO file for the latest on what needs doing). +