Greymatter
Weblog/Journal Software · Version 1.21b · Manual & Reference
Copyright ©2000 Noah Grey · All Rights Reserved



Table of Contents

1. About Greymatter
2. Copyright & Usage
3. A note about the bottom line
4. Configuration Options
5. Entries & Archives
6. The Templates
7. Template Variables
8. Editing & Creating Authors
9. The Banned IP List
10. Rebuilding Your Files
11. Tips & Suggestions
12. Troubleshooting
13. Version History
14. 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 installation.htm 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 installation.htm file for instructions on how to upgrade.


2. Copyright & Usage

Greymatter is Copyright (c)2000-2001 by Noah Grey. 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 noah@noahgrey.com—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 forum instead; that way, everyone can benefit from the information.)


4. 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.


5. 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.)


6. 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.


7. 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.").

{{archivebody}}

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.

{{authorsmartlink}}

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.)

{{cgiwebpath}}

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.

{{commentauthorip}}

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.

{{commentauthorsmartlink}}

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.

{{commentbody}}

The text of the current comment.

{{commentdivider}}

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).

{{commentordernumber}}

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.

{{commentslink}}

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).

{{commentsnumber}}

The number of comments that entry has received.

{{commentspostlink}}

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).

{{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.

{{entrieswebpath}}

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

{{entrycomments}}

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.

{{entrycommentsform}}

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.

{{entrykarmaform}}

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.

{{entrymainbody}}

The main text of that entry.

{{entrymorebody}}

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.

{{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).

{{entrysubject}}

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.

{{footer}}

Inserts whatever you have in the Footer template.

{{gmicon}}

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.

{{gmversion}}

Greymatter's current version number.

{{header}}

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 http://noahgrey.com/}}" produces "Check this site out: http://noahgrey.com/" with the URL as a plain link.
  • Typing "Say, have you been to {{link http://noahgrey.com/ Noah's site}} lately?" produces "Say, have you been to Noah's site lately?" with the words "Noah's site" as a link to noahgrey.com.
  • Typing "Really, you MUST {{linkmo http://noahgrey.com/ go there|Click here!}} sometime!" produces "Really, you MUST go there sometime!" with the words "go there" as a link to noahgrey.com, 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.

{{logarchivelist}}

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.

{{logbody}}

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.

{{logwebpath}}

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

{{karmalink}}

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.

{{militaryhour}}

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.

{{pagelink}}

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.

{{pagesmartindexlink}}

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.

{{searchform}}

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).

{{sidebar}}

Inserts whatever you have in the Sidebar template.

{{timezone}}

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.


8. 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.


9. 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 "12.34.56.78" as well as "90.12.34.56".


10. 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.


11. 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.


12. 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 on the Greysoft site; 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).


13. Version History

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

  • added bookmarklets for convenient "blogging" of sites from anywhere on the web (Internet Explorer 5+ only)
  • added ability to upload files from within Greymatter to your entries/archives directory (you must upload the new gm-upload.cgi file and chmod it to 755); can also allow only certain types of files to be uploaded, and/or specify a maximum filesize limit on uploads; can also send a link to the file or display the image directly in a new entry
  • can now choose whether log archives are kept on a monthly or weekly basis; they can also now be disabled altogether
  • added cookies to remember your name and password upon login; can be disabled or cleared in configuration
  • added new {{calendar}} & {{calendarweek}} options & templates, to create calendar tables showing links to your entries for the current month or week; can also create monthly calendars for individual months
  • added quick-and-easy {{popup}} variable for making popup windows for images (fully customisable, of course); when you upload an image through Greymatter, you can also have the popup window & code automatically made in a new entry
  • added ability for visitors to search your entries (to enable this, add {{searchform}} to any template to insert the search form), with fully-customisable form and results display
  • added ability to search through entries or perform search-and-replace operations across all entries from within Greymatter
  • retooled the way link variables are done for greater flexibility (link variables are no longer self-contained; templates automatically converted upon upgrading)
  • added ten new custom templates to the Header, Footer & Sidebar group
  • added shortcut keys and "easy formatting" (see configuration) for adding link, bold, italic & underline tags to text when adding or editing entries (Internet Explorer 5+ only)
  • added ability for authors to preview the contents of entries within Greymatter before posting them
  • added ability for visitors to preview comments before submitting them (to enable this, add a <INPUT TYPE=SUBMIT NAME="gmpostpreview" VALUE="Preview Your Comment"> button [the "value" text can be changed to whatever you wish, as long as you keep the NAME="gmpostpreview" part] to your entry comments form)
  • can now "connect" other files to Greymatter, allowing Greymatter to use and update any other file on your account as if it were one of its regular index files—recommended for advanced users only
  • added censor list ability; undesired words or phrases (in entries, comments, or both) can now be *****ed out
  • added "Automatically rebuild..." option upon saving changes to templates or entries
  • added "Rebuild All Entry Pages" option to the Rebuild Files menu
  • added more options for customising authors' access, including allowing authors to edit only their own entries and/or the header, footer & sidebar templates
  • can now specify whether only the HTML code for linking, bold and italics, or just linking, can be included in comments
  • can now specify dividers—by day, month, and/or year—to add to lists of entry links (the {{logentrylist}} variables)
  • can now list all entries by any individual author with the {{logentrylist}} variables
  • can also do {{logentrylist}}s sorted by number of comments
  • can now refer to the body of the entry text in {{logentrylist}}ings
  • much more flexible handling of {{previous}} and {{next}}-related variables
  • added new {{weekbeginning}} and {{weekending}} variables, pertaining to the date at the beginning or end of the given week
  • added new {{entrymainbodyfirstwords [x]}} and {{entrymorebodyfirstwords [x]}} variables, to display only the first X words of the current entry
  • added ability to sort by date, subject, or author, as well as an "All entries by you" viewing option, to the Edit An Entry selection menu
  • can now specify a default view for the Edit An Entry selection menu in configuration
  • can now customise the output of {{commentstatussmart}}
  • can now have separate suffix for the monthly log archive files
  • added "Visit Your Site" button to main menu
  • giving subjects to entries is no longer required
  • slightly improved autolinking to e-mail addresses
  • various minor speed optimisations
  • added {{randomnumber [x]-[y]}} variable
  • added a template for line breaks
  • added better checking for incorrect author names when creating a new author
  • fixed a small bug with not using the extended entry page template whenever comments were added to extended entries
  • fixed a small bug involving {{militaryhour}}: midnight was showing up as "12" instead of "00"
  • removed requirement that the Socket module be installed
  • added display of internal errors to browser

1.1b [12.27.2000]: bug-fix release

  • fixed important bug that could cause Greymatter to stop working after New Year's

1.1a [12.07.2000]: bug-fix release

  • fixed a small bug involving mouseovers with the {{logentrylist}} variables

1.1 [12.06.2000]: major upgrade release

  • polished up the interface and editing environment
  • new archive master index template & options
  • new variables ({{logarchivelist}}, {{logentrylist}} and several variations thereof), templates and options for generating automatic, fully-customisable lists of links to log archives and individual entry pages
  • added new Diagnostics & Repair function in the Configuration screen—a means for Greymatter to check that all files and paths are working correctly
  • added new header, footer and sidebar templates/variables
  • added filecheck error trapping (which basically means that if Greymatter ever has a problem reading or writing to a file, it'll stop and tell you what the problem is, instead of stalling out indefinitely)
  • new templates allowing you to set up all standard and extended entries in completely distinct ways
  • can now universally disable karma and/or comments in configuration, overriding individual entry settings
  • new entry separator templates—can now add special separators/dividers between entries if you wish
  • new link customisation template, for any special code to be inserted in links to individual entry pages
  • can now close or reopen entries right from the entry selection menu
  • added {{previouslink}}, {{nextlink}}, {{previousmorelink}} and {{nextmorelink}} variables
  • added {{pagenextmorelink}} and {{pagepreviousmorelink}} for linking to the next and previous extended entries
  • added various variables for referring to the subject, author, and number of next and previous entries
  • added {{pageindexlink}}, {{pagearchiveindexlink}}, and {{pagearchivelogindexlink}} variables for linking to the main index, the archive master index, and the current log archive, respectively
  • can now modify the {{author}} group of variables to insert the links/information for specific authors
  • all variables involving the next & previous entries will now work in any of the mini-templates, not just the entry page templates
  • can now use entry-specific variables in the main index & archive log indexes if you wish; on the main index, they will refer to the most recent entry, and on the archive log index, to the entry at the top
  • new template for the date grouping header in archives
  • much improved handling of auto-linking to URL's in comments (thanks Neal)
  • e-mail addresses in comments will now be automatically linked to, if auto linking is enabled
  • implemented workaround for textareas choking on certain codes when editing templates or entries
  • fixed problem deleting banned IP addresses if the banned person's name contained quotes
  • can now activate both "HTML allowed in comments" and "Auto-link URLs in comments" without the links getting messed up
  • new {{entrieswebpath}} and {{logwebpath}} variables
  • got rid of the "Delete All Generated Pages" button
  • should work better on servers running Windows NT
  • can now fit in 800x600 instead of requiring a minimum display of 1024x768
  • looks much better on Netscape 4.x and 6.x
  • redid the installation file and the manual you're now reading

1.0a [11.20.2000]: bug-fix release

  • fixed tiny bug involving use of negative numbers on "Server Offset Time" (thanks Bill @ mermaniac.com)

1.0 [11.04.2000]: first official public release of Greymatter

  • added automatic path detection for installing (or upgrading, if necessary); Greymatter will attempt to figure out your local & web paths automatically if they haven't been configured or verified yet
  • added a version check to login so that all necessary files can be easily updated whenever an upgrade to Greymatter is installed in a previous Greymatter setup
  • added "Keep main index and archive log indexes concurrent with each other" option, allowing you to have new entries appear simultaneously in the main index and that month's archive log index if you wish
  • added file checks to login; will not allow login if critical files are missing
  • new "Local CGI Path" and "Website CGI Path" fields in configuration
  • added new {{pageindexlink}} and {{cgiwebpath}} variables
  • fixed bug with karma voting (wouldn't work if the main index file was not in the same place as the cgi files, since it assumed the same path)—karma voting links now refer to the cgi web path
  • {{pagenextlink}} and {{pagepreviouslink}} are now "smarter"; will now skip over closed entries (rather than just linking to the main index if the next/previous entry is closed) and will always link to the next/previous non-closed entry
  • single line breaks will now show up in entry text and in comments (unless you've enabled "Strip new lines from comments", of course)
  • minor tweaks to look slightly better on Netscape (still looks much better in IE, though)
  • rewrote the installation.txt file, and finished the manual you're now reading

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


14. Credits & Thanks

Greymatter is written and created entirely by Noah Grey. 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
http://noahgrey.com/
noah@noahgrey.com