So, it's /finally/ time for the first release of this module. :-)

If you have just installed the module and set it up to point to this
directory, using the template file provided and with all other options
in their default state, you'll find that this page is found when you
look at http://your.server.address/diary/ or
http://your.server.address/diary/1999-04-24.html -- more on this in a
moment. Accessing the module by its mount point alone will render a
redirect to the most recent date present in the directory, in this
case the 24:th of April, 1999. Note that what is considered "most
recent" is not the file most recently modified, but rather the file
whose filename indicates the most recent date.

As you may have noticed, the filename is on the format YYYY-MM-DD.
This is not a coincidence, but rather a necessity. The filename is how
the module knows what date to assign the text to. The only files the
module will serve are those named in this fashion, all other files
will be ignored. This could be useful if your directory of text files
is somewhere below the mountpoint of your virtual server's file
system. Let's say that / is mounted on /home/roxen/www/. Then, with
your module mounted at /diary/ and textfiles fetched from
/home/roxen/www/diary/, you could put other files in this same
directory, which would be served transparently by the filesystem
module; perhaps an about.html, some images used by the template or
similar.

Oh, that reminds me: there is a feature in the Text2HTML magic
settings called "Separator breaking". It relies on a hardcoded image
file name, which points to a 147 by 17 pixel images/snirkel.gif file
used to separate different chunks of the text file from each other,
this way:


-- whenever you add two empty, blank lines, this separator would be
inserted. If you plan on using this feature, you probably want to use
the filesystem setup discussed above, having the images directory in
the diary/ directory. All relative paths given in the template file,
by the way, will be relative to the mountpoint of the module, and not
the path where the template resides. If you always use absolute paths
in your templates, you won't notice this, but, like the rest of us,
you probably don't. :-)


On to some of the features of the module! You probably already noticed
my using /emphasized text/ in the first sentence. How is it done? What
more does the module do? Well, I suggest you check the source file and
compare it with the parsed result seen in your browser.

This section should use all the features available, all options turned
on:

/emphasized text/, as already stated.

_bold text_ -- useful at times.

Paragraph break -- a blank line is used to separate the text before
and after it with a <P> element. This also showed the HTML
substitution, by the way; <, >, ", ' and & are shown using their
respective HTML entities.

Explicit <BR>
line breaks,
using carriage
return characters.

Automatic links to dates present in the module: 1999-04-24 (any date
formatted in this fashion will be turned into a URL to that date, if
there is such a date in this diary module instance.

Other automatic links; The preferred formats are:
"http://a205.ryd.student.liu.se/(Diary)/docs/" (enclosing the link in
double quotes), or the named link: "the diary module homepage"
("http://a205.ryd.student.liu.se/(Diary)/docs/"). Other ways of
stating links that work are outlined in the ChangeLog file and in the
configuration interface help strings for the magic options. Absolute
URL:s referring to documents on your server can be used in a
"shorthand form" ("/diary/1999-04-24.html") such as this.


---8<------8<------8<------8<------8<------8<------8<------8<------8<---
Preformatted text sections

Note that there is an ugly limitation here:
only one such section will work per file.
---8<------8<------8<------8<------8<------8<------8<------8<------8<---

Finally, there are the <tm>, (C) and (R) translators. :) Not much to
say, really. These are case insensitive, giving other legal
permutaions such as <TM>, (c) and (r). Have fun!


Combinations of the above, in general, do not work. You can't have
text being _bold_ and /emphasized/ at the same time, nor can you have
emphasis on only parts of a word et cetera. This mock "meta" markup
language used in my diary files its definete limits, and if they bug
you a lot, you probably prefer tweaking the HTML by hand. By all
means, do. I won't be insulted, I promise! :-)

Well, what have I forgotten? Oh, there's one thing I added after
having released beta versions to a few friends of mine to ease
debugging a bit. I still left it in, out of sheer laziness, but
somebody else is bound to find it fun, at least to play about with.
:-) If you want to find out the exact look of the unparsed textfile,
just add the prestate "raw" to the path, like this
("/(raw)/diary/1999-04-24.html"). This could be an alternative
approach to reading the diary, if you only have access to tools such
as wget. :-)

There is one other prestate available for module info; the "expert
prestate" ("/(expert)/diary/1999-04-24.html"). This will print out
some tab-separated info about the module nversion, configuration and
the files being served by it.

Well, that's about it, I guess.