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

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

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}}

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

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]: important bug fix

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

1.1a [12.07.2000]: minor bug fix

• 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]: minor bug fix

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