Weblog/Journal Software · Version 1.3 · Manual & Reference
Copyright ©2000-2003 The Greymatter Team · All Rights Reserved

Table of Contents

1. About Greymatter
2. Copyright & Usage
3. A note about the bottom line
4. Security Considerations
5. Configuration Options
6. Entries & Archives
7. The Templates
8. Template Variables
9. Editing & Creating Authors
10. The Banned IP List
11. Rebuilding Your Files
12. Tips & Suggestions
13. Troubleshooting
14. Version History
15. Credits & Thanks

1. About Greymatter

Thanks for trying Greymatter. =) Greymatter is a Web-based tool for the creation of weblogs (regularly-updated news- or journal-type sites) or online journals, allowing complete control over your weblog/journal while supporting such features as: the ability for users to post comments to your entries or cast "karma" votes on them, with no database used or required whatsoever; a template-based system that allows you to fully customise every aspect of your site's look and function, great or small; support for multiple weblog/journal authors, with fully-controllable individual access; a ban system for preventing malicious users from voting or posting on your site; nearly a hundred template variables that allow for extremely flexible styles and setups; easy and complete editing of any entry (including its comments) at any time; runs completely on your own account and is thus under your full control at all times; and, of course, "more"!

To install Greymatter, please carefully follow the instructions in the install.html file. Greymatter is intended as a flexible "power tool" for webloggers & journal-keepers who are moderately comfortable with the HTML language (to customise Greymatter's templates). Greymatter requires a server that fully supports CGI programs with Perl 5 installed, and is optimised for 800x600 or higher.

IMPORTANT NOTE: If you're upgrading from an older version of Greymatter, please read the install.html file for instructions on how to upgrade.

2. Copyright & Usage

Greymatter is Copyright (c)2000-2003 by the Greymatter team. All rights reserved.

By possessing this software, you agree not to hold the author responsible for any problems that may arise from your installation or usage of Greymatter itself, or from any content generated by yourself or others through the use of this program. You may freely modify and redistribute this program, so long as every copyright notice (including in this manual and in the Greymatter code) remains fully intact. Finally, you may not sell or in any way make a financial profit from this program, either in original or modified form.

Your possession of this software signifies that you agree to these terms; please delete your copy of this software if you don't agree to these terms.

3. A note about the bottom line

At present, Greymatter is a completely free program; you don't need to spend a cent to use it, or to download any updates from the Greysoft site whenever they're made available. However, any donations (no requested fee, do what your heart dictates, if anything) or gift purchases made from the Greysoft site would be more than welcome; I've put an immense amount of work into this program, and any donations (though again, of course, *not* required in any way) would definitely be the best incentive to keep me working on and updating it, or simply to let me know that this program's existence is appreciated. =)

In any event, donation or no donation, if you like using Greymatter then feel free to e-mail me at—I'd love to hear from you. (For most tech-support questions or comments and queries relating to its usage, please leave a post about it on Greymatter's discussion forums instead; that way, everyone can benefit from the information.)

4. Security Considerations

Greymatter requires that certain files and directories be writeable by the userid that the web server runs as. Normally, this is accomplished by making those files and directories world-writeable. If you have the flexibility to exec a CGI script under a different userid, then this userid is the only one that requires write privileges. Greymatter has not been tested extensively under a "CGI wrapper" but should work fine if you keep this need to write files in mind.

Every attempt has been made to secure this set of scripts against cross-site scripting (XSS) attacks. However, it is worth noting that if security is a significant concern, disallowing comments entirely is the only way to be completely safe from XSS attacks. Greymatter has configuration options that allow you to filter the set of allowable tags in comments. You need to be aware that allowing HTML in comments with no restrictions can lead to your site being compromised.

In Greymatter 1.3, author usernames and passwords are no longer exposed during a rebuild files operation. Please take note that using the cookie and bookmarklet options both have the potential to reveal your author login information. If you are not the sole user of a machine, you should not use the cookies or bookmarklets features.

5. Configuration Options

The Configuration screen is where you set up Greymatter and tell it how you want it to work. As explained in installation.htm, setting things up here will need to be your first order of business when you use Greymatter for the first time. Whenever you change any of the settings here after your weblog/journal has already started, then it'd be a good idea to rebuild your files (see the "Rebuilding Your Files" section of the manual below) to make the appropriate changes visible on your site. You can also run "Diagnostics & Repair" (indeed, you'll need to do so upon installation) to insure that all your files and paths are accessible and are working correctly.

Since the various configuration options are now described within the program itself, descriptions of them aren't included here.

6. Entries & Archives

Entries are what your weblog/journal is made of, and the "Add A New Entry" screen is where you'll post them. There are three distinct elements to an entry that you can create: the subject, the main text, and the extended (or "more") text.

You must always give your entries a subject, for at least reference purposes, since entries are listed by subject when you select them from the Edit An Entry menu. (However you want to use or display them in your weblog/journal, or whether you want them displayed anywhere on your site at all, is, of course, entirely up to you and how you configure your templates.)

The Main Entry Text is intended to be the main body of your entry, and the extended text is for additional or supplemental information; you must always enter a main text, but the extended text is optional. This is intended to help you make an entry's appearance on your main index, and on its entry page, distinct when you want them to be distinct; typically (as in the default templates included with Greymatter), you would use the main text for when entries appear in the body of your log, and if you have something more you want to say in an entry but don't want to dump it all on the main page, you'd enter it as extended text to appear in full on that entry's individual page. (Also note that you can, if you wish, give normal and extended entries different formatting via your templates, or handle them in any distinct way you choose.)

Finally, upon creating the entry, you're given the option whether or not you want to turn karma voting and comment posting on or off for this entry (the options won't appear if you've disabled karma and/or comments in Configuration, since disabling them overrides individual entry settings). You also have the option to mark that entry to stay at the top of your main log (which you could set apart with custom formatting via the templates, for announcements, special notices, and so forth)—when the main index is generated, then that entry will stay at the top indefinitely, until you edit it removing its stay-at-top status (or set another entry to take its place).

You can edit an entry anytime by selecting it from the "Edit An Entry" screen (entries are listed by subject in order from newest to oldest); this includes being able to edit or delete any comments from any entry, turning karma and/or comments on or off for that entry, and marking or removing it as the stay-at-top entry. When you edit an entry, you also have the option to leave it "open" or make it "closed"—meaning, basically, whether or not you want to leave that entry on your site. Think of open as meaning "visible" and closed meaning "invisible"; all entries are, of course, open by default. To close an entry is to effectively "delete" it—when the relevant files are rebuilt, Greymatter will treat that entry as if it no longer exists, removing all links to it or traces of it—but with the obvious advantage that Greymatter still has the entry data on file, and you could re-open it later if you wish. Be sure to rebuild the appropriate files after saving any changes to an entry, to make those changes take immediate effect on your site. (Greymatter automatically updates all relevant files whenever you add a new entry.)

An entry is considered "archived" when it becomes too old to be listed on your main index. You specify in Configuration how many days' worth of entries you want to keep on your main index. (This counts how many days you've posted entries for, *not* consecutive days; so for example, if you've posted entries only on four different days scattered throughout a month, Greymatter still counts that as four days.)

Indexes of your archived logs are automatically created by Greymatter in your entries/archives directory, in monthly or weekly installments. If you have the "Keep main index and archive log indexes concurrent with each other" option selected, then Greymatter will generate these files in your archives directory right away when you post entries and log your entries in both places simultaneously. Otherwise, entries won't appear here, and these files won't be generated, until entries have "scrolled off" the main index. Your archive master index is a good place to set up links to your archives; check the Template Variables section below for information about the {{log*list}} family of variables, which generate lists of these links automatically. (The "Miscellaneous Templates" allow you to customise these lists.)

7. The Templates

Templates are what Greymatter builds your site out of—they're patterns that tell Greymatter how you want your site to look, how you want your content to be formatted, what information you want to include and exactly where you want to include it. You mainly customise your templates with HTML (though since Greymatter generates *exactly* what the templates tell it to generate—nothing more, nothing less—you can also incorporate SHTML, PHP/SQL, or any other kinds of codes into your templates if you wish; you could even use Greymatter to generate text files or other specially-formatted documents if you wanted to), and you use the template variables (see the "Template Variables" sections below for a complete listing) to control what information you want to incorporate and where you want it to be placed.

Since the various templates are now described within the program itself, descriptions of them aren't included here.

8. Template Variables

Think of variables as placeholders for dynamic information (since that's exactly what they are)—each variable represents some piece of info or code, and their placement in your templates tells Greymatter where you want that info to be included. Variables are usually context-dependent; for example, a date/time variable like {{month}} or {{hour}}, in the context of the Individual Entry Template, will display the numbers for the month and hour respectively in which that entry was posted, or in the context of the Comments Template, the month and hour in which that comment was posted. Some variables (for example, {{header}}, {{footer}} and {{sidebar}}) have their own templates; in those cases, Greymatter inserts the contents of those templates wherever those variables are and then goes on analyzing the rest of the variables. A few variables can only be used in a particular instance, but most are intended to be used as flexibly as you like.

The template variables are as follows:

{{ampm}}, {{ampmlower}}, {{ampmdot}}, {{ampmdotlower}}

The AM or PM status of the relevant time. The "lower" variations list it in lowercase ("am" or "pm"), and the dot variations list it with dots ("a.m." or "p.m.").


Placeholder for use only in the Archive Log Index Template; when the log archives are generated, this tells Greymatter where to place the body of that month's or week's log. You can also use {{logbody}} (see below) to do the same thing.

{{author}}, {{authoremail}}, {{authorhomepage}}, {{authorentrycount}}

The name of that entry's author, their e-mail address (if given), their homepage address (if given), and the total number of entries they've posted so far, respectively. You can also include the name of an author to always give the relevant status for that particular author; for example, {{authoremail Alice}} will give Alice's e-mail address (if there is one), {{authorentrycount Mad Hatter}} will display how many entries Mad Hatter has posted, and so on.


Displays the name of that entry's author as a link either to that author's e-mail or homepage address, whichever has been given (if both are available, the link is to that author's homepage; if neither, the name is left unlinked). This is a self-contained link. As above, you can also names to generate smart dynamic links for specific authors.

{{calendar}}, {{calendar [mm]/[yy]}}, {{calendarweek}}

Creates calendar displays for the current month or week (or, in the case of {{calendar [mm]/[yy]}}, the month you specify) with each day in the calendar display as a link to the most recent entry posted that day, if any; you can specify in configuration whether calendars will link to any entry or only to extended entries. Use {{calendar [mm]/[yy]}} to create a calendar for a specific month; for example, {{calendar 11/00}} would make a calendar for the month of November 2000. (This requires that you've actually posted at least one entry during that month.)


Inserts the web path where your Greymatter CGI files are located, as specified in Configuration.

{{commentauthor}}, {{commentauthoremailabsolute}}, {{commentauthorhomepageabsolute}}

The name of that comment's author, their e-mail address (if given), and their homepage address (if given), respectively.

{{commentauthoremail}}, {{commentauthorhomepage}}

The contents of their respective templates; these will only appear if the author of that comment has given an e-mail or homepage address, respectively.


Displays the IP address of that comment's author. You can always see the IP addresses for comments by editing the entries they appear in, so you may want to think twice about using this variable and thus having the IPs appear out in the open, since many will (with due reason) probably consider this an invasion of privacy.


Displays the name of that comment's author as a link either to that author's e-mail or homepage address, whichever has been given (if both are available, the link is to that author's homepage; if neither, the name is left unlinked). This is a self-contained link.


The text of the current comment.


The contents of the {{commentdivider}} template. This will only appear if the entry contains at least one comment (and, if so, will still appear in that entry whether or not comments are disabled later).


The number of the comment. The first comment posted is always number 1, whether or not the comments are displayed in ascending or descending order.


The contents of the {{commentslink}} template, intended for linking to the comments on individual entry pages. This will not appear on entries for which comments have been disabled (or, of course, if comments are disabled altogether).


The number of comments that entry has received.


Generates a link to the #comments marker in that entry's page (wherever you have the tag in your entry page templates; by default, the tag points to the comments in that particular entry, or the posting form if no comments have been posted yet). If used outside the {{commentslink}} template, this link will always appear whether or not comments are disabled for that entry.

{{commentstatussmart}}, {{commentstatussmartupper}}, {{commentstatussmartlower}}

By default, displays how many comments there are in the "x Comments" format (with upper- and lower-case variations) with a "smart" status of how many comments there are: zero comments are "No Comments" and one is "1 Comment" (note the singular). If used outside the {{commentslink}} template, this will always appear whether or not comments are disabled for that entry. You can customise the output of this variable via the templates.

{{customone}} through {{customten}}

Inserts whatever you have in the respective custom template.

{{day}}, {{dayday}}

Displays the number of the relevant day. {{dayday}} forces it to two digits (if it's not already), padding single-digit numbers with zeroes (for example, 2 becomes 02).


Displays the domain the gm software resides on.

{{email [url]}}, {{email [url] [link text]}}, {{emailmo [url] [link text]|[mouseover]}}

Works the same way as the {{link}} variables; see the description of them below.


Inserts the path to your emoticon images, as specified in the Configuration.


Inserts the web path of your entries/archives directory, as specified in Configuration.


All the comments for that individual entry; like {{logbody}} on the Main Index and Archive Log Index pages, this is a placeholder for the full body of the comment list. Each comment is patterned on the Comment Appearance template.


The contents of the {{entrycommentsform} template—the form whereby your visitors can add their comments to an entry. This won't appear on entries for which comments are disabled, or if comment posting is disabled altogether.


The contents of the {{entrycommentsform} template, intended to be a distinct form by which people can vote on an entry's karma from that entry's individual page. This won't appear on entries for which karma is disabled, or if karma voting is disabled altogether.


The main text of that entry.


The extended (or "more") text of that entry, if there is any.

{{entrymainbodyfirstwords [x]}} and {{entrymorebodyfirstwords [x]}}

Displays only the first X words of that entry's main or extended text, respectively; for example, {{entrymainbodyfirstwords 20}} will display the first twenty words of the main text (or the entire main text if it's less than twenty words, of course). All words displayed this way will be shown without HTML codes.

{{entrymusic}}, {{entrymood}}

Displays the music or mood text for that entry, if there is any.

{{entrynumber}}, {{entrynumberpadded}}

The number of that entry. The "padded" version displays it in Greymatter's 8-digit padded filenaming convention (for example, the number for entry 187 would display as 00000187).


The subject line for that entry. Although you're required to give a subject when adding a new entry for the sake of reference, you're certainly not required to display it anywhere in your log.

{{entrysuffix}}, {{archivesuffix}}

Displays the page extension specified in the config. {{entrysuffix}} for entry pages, {{archivesuffix}} for archive files.


Inserts whatever you have in the Footer template.


Puts the gm-icon.gif graphic on your page, linked to the Greysoft site. Required on the main index template, although donators can request a copy of Greymatter with the requirement removed if desired.


Greymatter's current version number.


Inserts whatever you have in the Header template.

{{hour}}, {{hourhour}}

Displays the number of the relevant hour. {{hourhour}} forces it to two digits (if it's not already), padding single-digit numbers with zeroes (for example, 4 becomes 04).

{{link [url]}}, {{link [url] [link text]}}, {{linkmo [url] [link text]|[mouseover]}}

For use when adding new entries, to facilitate adding links as a kind of shorthand. (You can always do them the old-fashioned way too, of course.) Links added this way are self-contained. The syntax works as follows:

  • Typing "Check this site out: {{{link}}" produces "Check this site out:" with the URL as a plain link.
  • Typing "Say, have you been to {{link Noah's site}} lately?" produces "Say, have you been to Noah's site lately?" with the words "Noah's site" as a link to
  • Typing "Really, you MUST {{linkmo go there|Click here!}} sometime!" produces "Really, you MUST go there sometime!" with the words "go there" as a link to, and the words "Click here!" appearing as mouseover text for that link in the browser's status bar.

You can also use "email" and "emailmo", with the same syntax as above (replacing "link" or "linkmo" accordingly), for linking to e-mail addresses.


Generates a list of links to all your monthly/weekly log archives. The appearance of these links is controlled by the Log Archives Link template (under Miscellaneous Templates) and the Log Archives Link Separator.


Placeholder for use only in the Main Index or Archive Log Index Templates; when the log is generated, this tells Greymatter where to place the body of the log (the current log for the main index, and the monthly/weekly log for the archive log index).

{{logentrylist}}, {{logshortentrylist}}, {{logmoreentrylist}} (plus optional variants: day, month, year, firsthalf, secondhalf, number, comments, commentsminimum, commentsnumber, and author name)

Generates a list of links to your individual entry pages (unless you have those disabled). The appearance of these links is controlled by the Entry List Link templates (under Miscellaneous Templates) and the Entry List Link Separator. {{logentrylist}} generates a list of links to all your entries; {{logshortentrylist}} generates a list for non-extended entries only, and {{logmoreentrylist}} for extended entries only. With each of those you can optionally specify that only a particular range of entries be listed:

  • day—lists the entries only for the most recent day that entries were posted
  • month—lists the entries only for the most recent month
  • year—lists the entries only for the most recent year
  • firsthalf—lists the first (most recent) half of all entries
  • secondhalf—lists the second (older) half of all entries
  • number—lists the most recent number of however many entries you specify in Configuration
  • comments—lists entries sorted by the number of comments they've received
  • commentsminimum—same as above, but lists entries only if they've received at least one comment
  • commentsnumber—lists the top X most-posted-to entries (X being whatever you specified in Configuration)
  • (name of any author)—lists all entries by that particular author

So, for example, {{logshortentrylist month}} would list all the non-extended entries for the current month; {{logentrylist firsthalf}} and {{logentrylist secondhalf}} would list all the entries in separate halves (useful if you want to list them in two columns); {{logmoreentrylist number}} would list the twenty most recent extended entries, if you have "Log entry list variable number" in Configuration set to 20; {{logentrylist commentsminimum}} lists all entries, sorted by number of comments, that have received at least one comment (you can specify in Configuration whether or not this only lists entries for which comments can still be posted to); {{logmoreentrylist commentsnumber}} would list the top five most-posted-to entries if you have "Log entry list variable number" in Configuration set to 5; {{logentrylist WhiteRabbit}} would list all entries written by WhiteRabbit; and so on.


Inserts the web directory where your main index is, as specified in Configuration.


The contents of the {{karmalink}} template, for use in voting on an entry's karma. This won't appear with entries for which karma is disabled, or if karma voting is disabled altogether.


Displays the number of the relevant hour, in military time (always double-digit). The custom in military time is to add twelve to any hour after noon; so for example, 2 PM would be 14 in military time.

{{minute}}, {{minuteminute}}

Displays the number of the relevant minute. {{minuteminute}} forces it to two digits (if it's not already), padding single-digit numbers with zeroes (for example, 5 becomes 05).

{{month}}, {{monthmonth}}

Displays the number of the relevant month. {{monthmonth}} forces it to two digits (if it's not already), padding single-digit numbers with zeroes (for example, 3 becomes 03).

{{monthword}}, {{monthwordupper}}, {{monthwordlower}}, {{monthwordshort}}, {{monthworduppershort}}, {{monthwordlowershort}}

Displays the name of the month; {{monthwordshort}} displays it abbreviated to three letters. The "upper" and "lower" variations for both are for displaying it in upper- or lowercase respectively. So for example, the month of December would be displayed by the variables like so, in the order they're listed above: December, DECEMBER, december, Dec, DEC, dec.

{{morelink}}, {{morepreface}} (not recommended)

The contents of their respective templates; will only appear with entries that have an extended ("more") text. These are no longer recommended for use; it's simpler and more flexible now to distinguish standard and extended entries with their separate templates, so these are no longer necessary (but are kept for compatibility purposes).

{{next}} and {{nextmore}} as a prefix

When "next" or "nextmore" is used as a prefix to most variables, it will give the relevant variable output as it pertains to the next standard or extended entry; for example, {{nexthour}} gives the next entry's hour, {{nextmoreentrysubject}} the next extended entry's subject, and so on.


Generates a link to the individual page for that entry. This is always generated, so you won't want to use this variable if you have individual entry page generation turned off, unless you want it to create links to pages that don't exist. =)

{{pageindexlink}}, {{pagearchiveindexlink}}, {{pagearchivelogindexlink}}

Generates links to the main index, the archive master index (if you have one), and the log archives for the current month or week, respectively.


Generates a "smart" link either to the main index page or, if the entry is an archived entry, to the log archives for that entry's month or week.

{{popup [filename] [title] [width]x[height]}}

Generates a popup window for images, as well as an HTML file for that popup window in the entries/archives directory (both according to the popup templates you specify). "Filename" is the name of the image file (the HTML file Greymatter creates for the window will be named based on this file as well), "title" is its title, and "width" and "height" are the image's width and height respectively. {{popup}} creates its link and HTML file according to your customisation of them in the templates. So, for example, {{popup me.jpg This is me 300x200}} would create a popup window for the me.jpg image in the entries/archives directory (creating a me.htm file there for the window as well) that is 300 pixels wide and 200 pixels high. Note that when you upload an image through Greymatter, you can have it automatically create a new entry with the correct {{popup}} variable already in place.

{{popupfile}}, {{popuphtmlfile}}, {{popuptitle}}, {{popupwidth}}, {{popupheight}}

Gives the image filename, HTML filename, title, width, and height respectively, from the popup variable above. These variables will, of course, only work in the popup templates.

{{positivekarma}}, {{negativekarma}}, {{totalkarma}}

The positive, negative and total karma ratings of that entry, respectively. If used outside the {{karmalink}} and {{entrykarmaform}} templates, these will just show up as permanent zeroes for entries on which karma is disabled or if karma voting is disabled altogether. Total karma is the positive minus the negative karma votes; 10 positive votes with 3 negative would give a 7 total karma rating, 4 positive with 7 negative would give -3 total.

{{positivekarmalink}}, {{negativekarmalink}}

Generates links for voting upon that entry's karma for the positive or the negative respectively. If used outside the {{entrykarmaform}} or {{karmalink}} templates, these links will always appear whether or not karma voting is enabled for that entry or if karma is disabled altogether (if karma's disabled, though, clicking the links will not alter that entry's karma).

{{previewcommentauthor}}, {{previewcommentemail}}, {{previewcommenthomepage}}, {{previewcommentbody}}

The name, e-mail, homepage of the author previewing the comment, and the text of the comment being previewed, respectively. These will only work in the Comment Previewing Confirmation Form.

{{previous}} and {{previousmore}} as a prefix

When "previous" or "previousmore" is used as a prefix to most variables, it will give the relevant variable output as it pertains to the previous standard or extended entry; for example, {{previoushour}} gives the previous entry's hour, {{previousmoreentrysubject}} the previous extended entry's subject, and so on.

{{previouslink}}, {{nextlink}}, {{previousmorelink}}, {{nextmorelink}}

Inserts the contents of their respective templates, intended for use in linking to previous or next entries (or, with the "more" variations, previous/next extended entries). These will only appear if there's a non-closed previous/next entry (or extended entry, respectively) to be linked to.

{{randomnumber [x]-[y]}}

Displays a random number within the range you specify; for example, {{randomnumber 1-10}} generates a random number from 1 to 10 (inclusive). These numbers will be different each time the page in question is rebuilt, of course.


Inserts the form for searching through your entries.

{{searchterm}}, {{searchmatches}}, {{searchresults}}

The term used in a search, the number of matches for that search, and the total formatted results of the search, respectively. These variables only apply to the Search Results Page template.

{{second}}, {{secondsecond}}

Displays the number of the relevant second. {{secondsecond}} forces it to two digits (if it's not already), padding single-digit numbers with zeroes (for example, 7 becomes 07).

{{smartentrymusic}}, {{smartentrymood}}

Displays contents of the respective templates if text is included in the respective inputs when adding a new entry.


Inserts whatever you have in the Sidebar template.


Your time zone, as entered in Configuration.

{{weekbeginning[?]}}, {{weekending[?]}}

Pertains to the date at the beginning or ending of the current week, respectively; [?] can be any of the variables pertaining to days, months, years, or weekdays. For example, {{weekbeginningday}} would give the day at the beginning of the current week, and {{weekendingmonthword}} would give the name of the month for the day at the end of the week.

{{weekday}}, {{weekdayupper}}, {{weekdaylower}}, {{weekdayshort}}, {{weekdayuppershort}}, {{weekdaylowershort}}

Displays the name of the weekday; {{weekdayshort}} displays it abbreviated to three letters. The "upper" and "lower" variations for both are for displaying it in upper- or lowercase respectively. So for example, Thursday would be displayed by the variables like so, in the order they're listed above: Thursday, THURSDAY, thursday, Thu, THU, thu.

{{year}}, {{yearyear}}

Displays the number of the relevant year. {{year}} displays only the last two digits of the year, and {{yearyear}} the full year; so for example, 2001 would be displayed as "01" and "2001" respectively.

9. Editing & Creating Authors

To post an entry to your weblog/journal—to access Greymatter or do anything with it at all, for that matter—you have to be a registered author. (The default author is "Alice", password "wonderland".) You can control the specific access of any author registered with Greymatter—for example, if you want to create an account for someone that can post entries to your weblog/journal, but you don't want them having the ability to muck up your site's configuration or to do anything else. (Needless to say, be careful about turning off your own access to anything!) Likewise, of course, you can also delete an author's account altogether at any time.

To create a new author account, simply enter the desired name and password in the "Register A New Author" box, as well as that person's e-mail and/or homepage (this is optional). If you leave the "All access on for this author by default?" checkbox on, then that author will be created having access to everything; if you leave it unchecked, then they'll be created having access to nothing. After creating the author, edit them if you want to specifically turn their access on or off for different functions. There is no theoretical limit to how many authors you can register.

10. The Banned IP List

If someone's being a pain and you want to ban them from posting comments to your site or casting karma votes on any of the entries, you can add their IP address to the Banned IP list. You can also optionally specify a name to go along with the banned IPs, to help you remember who's who, and, of course, you can remove a banned IP from the list at any time. (In a nutshell, IP addresses are four-digit numbers—in the format x.x.x.x—which usually specify an individual account accessing the Internet; a full explanation of IPs is beyond the scope of this manual.) You can see the IP address of someone posting a comment or voting on karma whenever an e-mail notification is sent to you (if you have that enabled), or by reviewing that entry in the "Edit An Entry" screen.

Since some internet service providers use "rolling" (non-static) IPs, you can enter a partial IP if you want to ban all IP numbers that contain the given partial IP string; for example, banning "12.34.56" would ban the IP "" as well as "".

11. Rebuilding Your Files

From time to time, you may want to rebuild your files—to rebuild files basically means to tell Greymatter to regenerate them. You'll usually only want to do this after you've made changes to your configuration settings, after you've edited your templates, or after you've edited an entry (including closing or reopening it). For example, if you've changed the entry page templates for current entries, you'll probably just want to rebuild the main entry pages—and if you've made changes affecting the entire look or operation of your site, you'll want to rebuild everything. Most of the time, though, rebuilding should be quite unnecessary.

Remember that, obviously, some of these operations may take some time, depending on how much is involved in the rebuilding—most rebuilding operations should be fairly quick, but major rebuilding over a large number of entries could take a little while. DO NOT attempt to abort Greymatter in any way once you've started rebuilding, or you may mess up your files!

The rebuilding options are as follows:

  • "Rebuild Last Entry Page Only"—Rebuilds only the individual entry page for the most recent entry.
  • "Rebuild Main Index File"—Rebuilds the main index of your weblog/journal.
  • "Rebuild Main Entry Pages"—Rebuilds the individual entry pages of every entry that's still considered current (non-archived).
  • "Rebuild Archive Master Index"—Rebuilds the archive master index (if enabled).
  • "Rebuild Archive Log Indexes"—Rebuilds the archive log indexes for every month or week.
  • "Rebuild Archive Entry Pages"—Rebuilds the individual entry pages of every entry that's considered an archive.
  • "Rebuild All Entry Pages"—Rebuilds the individual entry pages of every entry, both current and archived.
  • "Rebuild Connected Pages"—Rebuilds any page you might have connected to Greymatter in Configuration; this option will only appear if you have other pages connected to Greymatter.
  • "Rebuild Everything"—Rebuilds all of the above at once.

12. Tips & Suggestions

The following are some things you might like to consider after you've become comfortable with using and customising Greymatter.

1. Using Greymatter to do an online journal

Although Greymatter's default inclination is towards weblogs, it can also be used as a flexible tool for maintaining an online journal with, to which you could have visitors post comments to your journal entries. For starters, try editing your templates to leave the date grouping template blank, and in the individual entry template, list only the date and entry subject—for example, a one-line template like so:

{{month}}/{{day}}/{{year}}: {{pagelink}}{{entrysubject}}

would make for a quick-and-easy "table of contents" type of format, and you could use the main index as your table of contents for current journal entries. (You might also want to try bumping up the "Days to keep on main index" variable to a much higher number - even a number like 99999, which would in effect make the main index a table-of-contents list of all entries.)

2. Tying variables to graphics (suggested by Jay Barrow)

Greymatter's template variables don't have to only be used for outputting plain text—try using them to automatically insert particular graphics as well. For instance, say that you have a series of twelve GIFs, one for every month, displaying that month's name in a special visual way—january.gif, february.gif, etc. In this case, use a tag like "<IMG SRC="{{monthwordlower}}.gif">", and Greymatter will automatically insert the appropriate month word (in this instance, in lowercase) in the image tag. You could also use it to, say, associate particular graphics/icons to particular people if you have multiple authors in your weblog/journal and wanted to set them apart.

3. Using Greymatter for database-type sites like movie/music review sites, etc.

Remember that you're not constrained to think of "main text", "more text" or anything else with their default meanings, or to use Greymatter's templates only in the same way all the time. Let's say that you want to run a site for music reviews. Set up your main index page in a table-of-contents type of format (as suggested under "Using Greymatter to do an online journal" above). When you add reviews, your "subject" can be the title of the CD you're reviewing, your "main text" could be some miscellaneous info (the release date, the label, a summary of your review, etc) that you want to set apart somehow, and the "more text" could be the review itself—format your templates accordingly. And you could use karma ratings, but instead call it: "Do you like this album? Yes/No", for example.

Despite the way Greymatter names things, it's not intended to be a program where you must always think "this is what I have to do here" and "that's what I have to do there" - take the time to learn how Greymatter works, and feel free to make it all into whatever *you* want to be.

13. Troubleshooting

First, assuming you can run Greymatter at all, be sure to run "Diagnostics & Repair" on the Configuration screen if you're having problems; that should be able to tell you what most of the holdups are, if Greymatter hasn't done so already along the way—whenever Greymatter has trouble accessing a file, it should stop and tell you what the problem is. You might also want to contact your server operator or webhost to find out if your server has any special limitations when running Perl software. Also, don't forget to check the discussion board at the Greymatter Forums; someone (including me) may be able to answer your problem there, if it hasn't been answered already.

PROBLEM: I keep getting a 500 Internal Service Error when I attempt to run Greymatter, or at a particular spot while attempting to do something in Greymatter.

DIAGNOSIS: First, check to make sure that you've uploaded everything in ASCII mode via your FTP program; if you're unsure, reupload all the files making sure that each upload is in ASCII mode. Next, check to make sure that your Perl pointers are correctly set, as specified in the installation instructions; then, double-check that everything is CHMODed correctly, also as specified in the installation instructions. If it still won't run after all that, then your server might not have Perl 5 or its standard modules installed.

PROBLEM: I can't seem to configure my paths correctly.

DIAGNOSIS: If you're absolutely certain that your paths are as they should be, and "Diagnostics & Repair" still gives you error notices, then try using virtual instead of relative paths instead. For example, your local CGI path would simply be a "." period (that just means "this directory is right where I'm running from"), and if your entries directory is a subdirectory of that named "archives", then your local entries path would be "./archives". Use "../" for going back one directory relative to the current one (where gm.cgi is); for example, if you have gm.cgi in /cgi-bin/gmfiles/ and you want your log path to be in /www/weblog/, you'd use "../../www/weblog"—the "../../" going back two directories and into "/www/weblog" from there. (Without the quotes, in all instances.)

PROBLEM: I get "Forbidden" errors whenever I try to view my main index and/or any of my entries.

DIAGNOSIS: If you've got your main index in your account's cgi-bin directory, and/or your entries directory as a subdirectory of that, then your server is probably set to automatically disallow viewing of any files in your cgi-bin directory (or subdirectories thereof) as a security measure. You'll have to have your log directory and your entries/archives directory to be somewhere other than in the cgi-bin directory.

PROBLEM: My entries or other files are messed up, and/or Greymatter just stalls out and stops running whenever I attempt to do something.

DIAGNOSIS: You may have interrupted Greymatter in the middle of an operation, such as adding a new entry or rebuilding files. Never do this, since this is the surest way to corrupt your Greymatter files. Keep in mind that actions like rebuilding files will always take some time, depending on how much Greymatter has to rebuild; if you have large templates, and/or you're trying to rebuild a significant amount of entries (and/or if entries contain a significant amount of comments), then rebuilding will probably require an ample amount of time. If your files have indeed been definitely corrupted, there will probably be no choice but to reinstall from scratch. If you believe you've encountered a genuine bug that corrupted your files through no fault of your own, then please don't hesitate to report it to me.

PROBLEM: I try to run Greymatter and get a bunch of text, but can't get the program to run properly; or, whenever I try to access Greymatter I'm simply prompted to download gm.cgi instead.

DIAGNOSIS: Your server may not have Perl 5 installed, or it may not be properly configured to run CGI scripts (*or* it may not allow for running CGI at all).

14. Version History

1.3: minor release

  • numerous security-related improvements
  • added music input to entries
  • added mood input to entries
  • integrated smilies hack to core gm code
  • improved php hack check
  • changed entry rebuild increment to 10 (instead of 20)
  • improved the default template set
  • fixed bug where "00000000.cgi can not be read" errors occur
  • fixed bug where sqare brackets in entry subjects broke the scripts
  • fixed bug where image buttons would not work in entrycommentsform template
  • added automatic configuration save when D&R is clicked
  • improved upgrade handling over 1.21d

1.21d: bug-fix release

  • fixed php exploit

1.21c: bug-fix release

  • fixed bug with crypt in gm-authors.cgi

06.19.2001: license change

  • updated the "Copyright & Usage" information in this manual

1.21b [02.22.2001]: bug-fix release

  • fixed bug with every 20th entry not being rebuilt
  • fixed bug with {{calendar mm/yy}} not aligning dates to the correct weekdays
  • fixed bug with {{logentrylist comments}} not sorting properly with entries having 10 or more comments

1.21a [01.17.2001]: bug-fix release

  • fixed security issue involving clicking "Visit Your Site" after certain rebuilding operations
  • fixed bug converting pluses to spaces in selected text/URLs when using bookmarklets
  • fixed bug padding {{militaryhour}} to too many zeroes when used in {{logentrylist}}s
  • fixed bug with not properly handling some {{previousmorepagelink}}s and {{nextmorepagelink}}s

1.21 [01.15.2001]: minor release

  • added incremental rebuilding—entry pages & connected files are now rebuilt 20 files at a time rather than all at once, to be somewhat more browser/server-friendly
  • fixed a minor bug involving {{commentauthoremail}} and {{commentauthorhomepage}}
  • fixed problem not recognizing pre-1.2 passwords that contained nonalphanumeric characters

1.2 [01.12.2001]: major upgrade release

1.1b [12.27.2000]: bug-fix release

1.1a [12.07.2000]: bug-fix release

1.1 [12.06.2000]: major upgrade release

1.0a [11.20.2000]: bug-fix release

1.0 [11.04.2000]: first official public release of Greymatter

beta 2 [10.28.2000]: fixed a small bug with IP addresses (thanks, Jay)

beta 1 [10.26.2000]: first private beta release

alpha 0.x [began 09.10.2000]: spawning, creating, testing, tweaking

15. Credits & Thanks

Greymatter is written and created entirely by Noah Grey and The Greymatter Team. All rights reserved.

Thanks to: Jay Barrow, without whose encouragement Greymatter wouldn't be in your hands right now (and who made the included "Powered By Greymatter" button); to Neal Coffey for help with Linux and URL auto-linking; to Bill, Daniel, Eric, James, Jay, Jimmy, Lee, Sara, and Tom for being great beta-testers (and friends); to my family and friends for their love and support; to everyone who has donated and helped make Greymatter to feel like a worthwhile effort thus far; and to Thomas for being himself.

—Noah Grey
—The Greymatter Team