Kotisivu

Kehittämäni www-sivuston ylläpitojärjestelmän nimi on Kotisivu.

Koko homma lähti siitä, että halusin tehdä itselleni yksinkertaisen ja yhdenmukaisen tavan ylläpitää erilaisia kotisivuja. Vaatimuksina olivat mm. staattisuus (sivujen sisältö on yksinkertaisissa tekstitiedostoissa) ja standardinmukaisuus (XHTML Strict ja CSS). Toteutin homman Perl-ohjelmalla (1500 riviä koodia tuskin on enää skripti).

Koska staattisuus ei sovi ihan kaikille sivuille, niin systeemi on Perl-moduuli, jota voi käyttää CGI- tms. skriptistä, mutta tietenkin myös tai komentoriviltä:

LOOK

The basic style in Kotisivu is a box with a header, footer, borders and main content.

SOURCE FILES

Besides the text content, a Kotisivu-file contains simple directives that are either section declarations (inside square brackets, e.g. [1,2]), parameter aggignments (key = value), or HTML-like markup (e.g. <BOX>). Any line starting with a '\#' -character is skipped (as a comment), unless '#' is escaped with the backslash: '\#'. Other special characters (including \,[,],<,>) may also be escaped with a backslash.

DIRECTIVES

Before the first section one can set some file-specific configuration options. See CONFIGURATION.

All other content before the first section declaration is the title of the page. (Only the non-HTML part or the alt-text of an image goes inside the HTML <TITLE>-tag.)

[N,M]

The content is divided into sections. The notation emulates that of a 2D-matrix: the upper left section is started by '[1,1]', the one to the left of it by '[1,2]' and the one beneath it by '[2,1]' and so on. The sections may be in random order in the source file.

A '[N,M]' -directive begins a new main content section, but if the same section is already specified earlier, the contents are merged. Everything until the next section declaration or the end of the file is the content of this section.

N and M are normally integers, but they may be substituted by one of the characters '+', '-' and '=' to increment, decrement or repeat the value of the previous section directive. E.g. a [+,=] after a [1,1] equals [2,1]. A modifier in the first section equals to '1'. And decrementing a '1' still equals to '1'.

The ',M' -part may be omitted, which is equal to ',1' so you can start a new row with a mere '[+]'. It may also be replaced with a single non-whitespace character to specify a full line of sections. The non-whitespace character is the cell separator. E.g. the line '[2:] foo : bar : foobar' declares three sections.

<BOX>

A <BOX> -tag starts a table. These are similar to the main matrix; only that section definitions are more line-oriented. The notation is otherwise the same, but they must always be at the beginning of a line and without the angle brackets. Columns and rows numered 0 are treated as headers.

<BOX>Header
1,1 row1,col1
1,2 row1,col2
2|  row2,col1 | row2,col2
+|  row3,col1 | row3,col2 | row3,col3
</BOX>

Header

row1,col1	row1,col2
row2,col1	row2,col2
row3,col1	row3,col2	row3,col3

<BOX> may be given the arguments of XHTML tag <table>. Additional arguments are:

"number", which gives you numbered table rows; and

"secv=n,m,...", where the argument value is a list of columns which should be colspan'ed in case of equal content on consecutive rows (secv is an acronym of "span equal column values").

"columns=n" puts the table rows in n columns

"border" creates a table with inner and outer borders

Translation

If you want to write the same web-page in several languages, you have to first mark all language-specific content inside curly braces: {Hello}. After that create a pot-file for the site with 'Kotisivu --create-potfile=file.pot [files]'. Then copy the potfile to the desired language (e.g. messages.fi.po for Finnish) and translate the strings by editing the file (the Emacs po-mode is really good for this). You may define these pofiles in .Kotisivurc, or use the the default, which is messages.XX.po in the site root directory.

The result will be one html-page for each language and links to the others on top of the page.

Every time you make new translatable strings you'll have to run 'Kotisivu --create-potfile=file.pot [files]' again. It will try to update the corresponding po-files also (but you'll still have to do the translation...).

A second method of translation is the tag <LANG xx>, where xx is the language code to be used (e.g. "en" or "fi").

The third method of translation is the configuration option "Languages", which has the desired language codes as its value. The language codes are separated by a non-whitespace-non-word-character. Translations are then done in the file inside double braces with the separator character separating the different languages.

<INCLUDE file>

Include the contents of "file" (which may contain Kotisivu-directives) to the resulting pages.

<TOC>

Create a "table of contents" by searching for <SUBTARGET> -tags from the file.

<FILENAME>

Replaced the source filename.

<SSUBMIT url arg1=val1 arg2=val2 ...>

Create a lone submit button sending to "url" with hidden attributes arg1=val1 etc.

<IMAGE image_filename alt-text>

Insert an image. Alt-text may be language-specific. If alt-text is omitted, the image name is passed as the alt attribute of HTML <img> -tag.

<LINK URL text>

Insert a link. Text may be language-specific. A relative URL is checked so that if it doesn't exist, it doesn't show up as a link on the HTML-page. If text is omitted, the link text is taken from the filename part of the URL. Many don't want non-ASCII characters in filenames, but need them in the link text, so if the filename doesn't exist, some non-alphanumeric characters in text are converted to '_'s and accents are dropped.

<SUBHEAD foo bar>

Creates a <h2> HTML-header with a <A name="foo_bar"> -tag. Intended to be used with '<SUBLINK>'.

<SUBTARGET foo bar>

Creates a <A name="foo_bar"> -tag. Intended to be used with '<SUBLINK>'.

<SUBLINK foo bar>

Creates an internal link <A href="\#foo_bar">foo bar</A>. Intended to be used with '<SUBHEAD>'.

<FEEDBACK prog>

Creates a feedback form inside a <BOX> which sends to the program prog. Related directives are: <FEEDBACKBOX name>, <FEEDBACKINPUT name> and <FEEDBACKSUBMIT text>, where 'name' is the value of the name-attribute of the HTML <INPUT>-tag and text is the text that goes on the button.

<HL>

Begins a region of highlighted text. The color is defined by a configuration option.

<EMPTY number>

Adds specified amount of non-breaking space.

Undocumented tags

COMMAND LINE OPTIONS

-h,--help	Some help on usage.
-V,--version	Print version information and exit.
-v,--verbose	Verbose messages (nothing very useful yet).
-q,--quiet	No output.
-p,--print_config	Print configuration information.

CONFIGURATION

Under configuration fall all the things that are thought to be common for several pages, such as page colours (like CSS, but much simpler). Configuration is placed in a file called '.Kotisivurc'. If a file with that name exists in the same directory with the text-file, then that one is used, the next place to look for it is the next directory up the tree ('..') and so on. .Kotisivurc-files don't need to contain all the options. Below is a sample file with all the options and their default values.

Configuration may also be put in the heading of the source file (before the first section).

Since moving to CSS, the colour-definitions affect only to creating the CSS-file for which there is a script available.

main_lang=xx
author=
base_address=
header=
head=
pofiles=messages.*.po
cssfile=/Kotisivu.css

[main_page]
fi=Takaisin pääsivulle
en=Back to main page
sv=Tillbaka till hemsidan

[this_page]
fi=Suomeksi
en=English
sv=Svenska

# Colours
text = #eeeeee
bg = #000000
border = #ffa500
hltext = #ffa500

link = #eeee00
visited = #b22222
active = #ff0000
hover = #ff7700

# Override above default colours for box and head
[boxcol]
bg = #b22222
border = #283a2e

[headcol]
bg = #b22222
text = #ffffff