MajaMaja
This page is the documentation for MajaMaja.
What is MajaMaja
MajaMaja is designed to accept as an input a directory structure containing
material (text, images, files, ready-made html pages, links) and to produce as
an output a static website which allows to navigate that material.
The emphasis is on static contents: i.e. the output of MajaMaja is
designed to work independently from any circumstances. It will work when put
on a web server, it will work when stored on a CD, it will work when just left
on your hard disk, and maybe made available via a network share.
Therefore, you can use it to manage your contents for personal use (hard disk),
for a small work group (network share) or for a larger community (web),
which can navigated and used even when stored on a ROM support.
Given these constraints, MajaMaja does not offer features which rely on a web
server or on a database (access counters, guestbooks, comments from users,
wiki), but it is easy to include in pages images or scripts which perform
counter management, and directories which contain a wiki, which MajaMaja
will not touch in any way.
MajaMaja is written in Tcl, therefore it runs equally well under Windows,
Linux, and any other architecture for which a Tcl interpreter is available.
The emphasis is also on structure rather than fexibility. It allows to
create websites which have a common, uniform format, rather than giving you
precise control over the appearance of each single graphical or typographical
element.
If the above constraints make MajaMaja unsuitable for your needs, feel free
to modify it (the source code IS the program itself) or to use something
else. Since I don't get any money from you either using or not using it,
I frankly prefer that you use something else rather than stretching it for
uses which are not appropriate, and then complain because it does not work as
you like.
Also, I have no time to process change or feature requests and version merges
(unless they are accompanied by some juicy check). Therefore, if you want a
feature, please go ahead, examine the code, and implement it yourself.
Conditions of use
MajaMaja can be freely used, adapted and redistributed for non-commercial use.
When redistributed after a modification, it must retain the same conditions of
use as indicated here.
Any other use is not allowed and requires prior written consent from the author.
How to use MajaMaja
To use MajaMaja:
- create a directory, which we will call the document root;
- get the MajaMaja archive at the end of this page, and
unpack it in your document root;
- arrange your material in a structure of directories of arbitrary complexity,
starting from a given directory which will act as the root directory of your website;
- launch
MajaMaja.tcl with your Tcl interpreter in the document
root directory;
- start navigating file
index.html in the document root!
MajaMaja generates a complete website, from the home page to the leaf nodes,
indexing all the above materials, according to the following rules:
Frequently asked questions
- Q: How can I include text material?
A: the best way to include text documents (with or without images and
other embedded contents) is to convert them to HTML and to save them as
body.htt file in a separate subdirectory.
Make sure that this file contains only what you would normally put
between <BODY> and </BODY> tags in a normal HTML file
(the <BODY> and </BODY> tags are excluded).
- Q: How can I include ready-made portions of a website?
A: Just put your ready-made web structure in a subdirectory
of the document root, making sure that it contains a file
named index.html.
Whenever MajaMaja finds a subdirectory containing a
file named index.html which was not generated by
MajaMaja itself, it stops processing the contents of that subdirectory
and its subdirectories. It will just provide a link to this file
from the page in its containing directory.
MajaMaja can distinguish its own index files from the index files
generated by someone/something else. Upon subsequent re-runs, MajaMaja
will rewrite only its own index files, without touching the ones you
provide.
- Q: How can I ignore files or directories?
A: Just put an underscore "_" in front of them.
MajaMaja ignores all the directories and files with a name beginning
with "_".
Another way to prevent MajaMaja from examining a directory is to put
a file named _MajaMaja_ignore_dir_ in it.
The file can be empty or contain arbitrary material; it is not examined.
This way, directory with arbitrary names can be ignored.
- Q: How can I hide a directory?
A: When a directory is hidden, its contents are processed by MajaMaja,
but the index page in its parent directory will not show any link
to the hidden directory.
This way, the hidden directory and its contents will be available
to anyone who knows it is there (i.e. they know its path name or its
URL), but it will not be listed anywhere.
To hide a directory, put a file named _MajaMaja_noindex_dir_
in it.
- Q: How can I include more file types in index pages?
A: The shipped version of MajaMaja provides support for a variety of file
types, identified by their extension (bmp, tiff, gif, png, pdf, ps,
tgz, txt, ...). If you want to add support for more, just prepare
an icon file named icon-ext.gif (where ext is the extension
you want to enable) and put it in directory _MajaMaja_
under the document root.
Upon the next run, MajaMaja will include in index pages also those files
having an extension equal to ext, and it will associate to them the
icon you provided.
- Q: How can I provide an icon for a content directory?
A: Provide a file named _MajaMaja_icon.gif,
_MajaMaja_icon.png, _MajaMaja_icon.jpg or
similar inside this directory.
MajaMaja will use this icon in the index page of the parent
subdirectory.
If you do not provide an icon, MajaMaja will use a stock directory
icon named icon_big_dir.gif and contained in directory
_MajaMaja_ under the document root.
- Q: How can I set the title, the abstract and the group for a content
directory?
A: By default, the title of a content directory as it appears in its parent
index is the name of the directory; its group is Unfiled and its abstact
is empty. To change these properties, create a file named
_MajaMaja_info.tcl in that directory. This file will
contain the following commands (in any order):
set title "Cats and dogs"
set abstract "The results of my research on domestic animals."
set group "Ethology"
Be aware of the fact that these files are executed as Tcl code, and
there is no prior syntax check on them. Therefore, if you do not respect
the prescribed syntax, you can cause MajaMaja to terminate with an
error. On the other hand, you can have any sorts of Tcl scripts inside
them, which can dynamically determine title, abstract and group on the
fly.
- Q: How can I provide a global header for all the pages in my site?
A: Provide a file named _MajaMaja_header.htt in your
document root directory. If this file contains any images,
use a regular IMG SRC tag to include them.
MajaMaja will provide automatic path rewriting to make sure that
the image is correcly linked when the header is included in files
from different directories. If you are providing an absolute URL for
that image, use a IMG SRC tag with two spaces between the
IMG and the SRC words.
- Q: How can I provide a header for the current page in a directory?
A: Provide a file named head.htt in your current
directory.
- Q: How can I provide title, abstract and author information for the indexed
files in my website?
A: For each file filename.ext, you can provide a separate tag
file named filename.ext.MajaMaja, which has the following
syntax:
set title "On Simulation Model Complexity"
set authors "Jones R., Sullivan Q. and Doe J."
set abstract "This paper describes the size and complexity of models ..."
MajaMaja includes the information specified in these tagfiles in
index pages.
- For any other question, read the source code or look for specific MajaMaja
files on this website... :P.
Frequently asked non-technical questions
- Why didn't you write it in Python?
Tcl is a mature and full-featured language, in which it is absolutely fun
to write software, and for a number of tasks it is much more
expressive than Python and shell script (i.e. it does more things in less
lines of code). Nevertheless, Python has also significant advantages,
primarily it comes shipped with a vast library which could allow MajaMaja
to do more, e.g. manipulate images and prepare thumbnails. The main
reason why MajaMaja is written in Tcl is that I did not know Python when
I started writing it. I am considering a rewriting in Python, but now I
don't have time to do it.
- What does the name MajaMaja come from?
MajaMaja is an expression in lombard, one of the local languages spoken
in northern Italy. For english-speaking readers, it is roughly pronounced
as Mah-yah-mah-yah. It literally means eat! eat! (imperative mode,
present tense of the verb to eat, singular 2nd person), and it is a
humourous reference to the ability of the program to eat up and
process any contents.
|
