Leonard Richardson <firstname.lastname@example.org>
Congratulations on your purchase of one (1) NewsBruiser brand NewsBruiser. If used correctly, NewsBruiser will satisfy your news-bruising needs for years to come. NewsBruiser.
To use the NewsBruiser software, you must first install the package onto a Web server with an installation of Python 1.5.2 or higher. Though you can access all the functionality of NewsBruiser through the CGIs, I recommended you enable SSI so that you can include NewsBruiser entries on your homepage using this_month.ssi or last_n_entries.ssi.
If instead of a list of notebooks, you see an error about "Couldn't create working directory", you need to make sure that your base directory exists and is writable by the webserver. If you have no way of making the base directory writable by the webserver, you can make it world-writable for just long enough to get started, like so:
chmod o+w [base directory]
[Now hit index.cgi]
chmod o-w [base directory]
Be careful! Making anything world-writable is risky! During the time that directory is world-writable, someone else on your machine could write arbitrary files to the NewsBruiser base directory. If you have no other option but to temporarily make your base directory world-writable, check the base directory for strange files after removing world-writability. The base directory should contain only the installation configuration file and NewsBruiser subdirectories for your notebooks.
If you have problems, or you're confused about the format of the NewsBruiser configuration file, look at the the configuration document.
Every file with a .cgi extension in the top-level NewsBruiser distribution directory is part of NewsBruiser's Web interface.
The following should be intuitive if you start at index.cgi and follow links, but here it is anyway.
Except for index.cgi, all of NewsBruiser's CGIs require a notebook name. Some CGIs also take either a category path, or a full or partial entry ID. A category path is a slash-separated set of strings designating one of the current notebook's categories (eg. "books/sci-fi/Robert Heinlein").
An entry ID is a slash-separated set of numbers designating the year, day, and month of a notebook entry, and the number, starting from zero, of that entry for that day (since you can post arbitrarily many entries on any given day). You can specify a partial entry ID (for instance, just the year and month) to operate on all entries in that chronological range.
CGIs look in the CGI variable PATH_INFO to get the notebook name, entry ID, and notebook. That means you need to specify them as part of the URL, as though the CGI were not really a CGI but a directory containing a file you wanted to access, called [notebook]/[entry ID] or [notebook]/category. Examples: foo.cgi/mynotebook/2001/7/9 to operate on the mynotebook entries of July 9, 2001, foo.cgi/mynotebook/books/sci-fi/Robert+Heinlein to operate on the "Robert Heinlein" subcategory of the "sci-fi" category of the "books" category of the mynotebook notebook.
You can also specify "notebook", "year", "month", "day", and "ordinal" as CGI variables, but I don't recommend it.
If you do not specify a notebook name, a CGI which needs one will assume you want the one you gave ordinal 0 in your .nbrc. If you do not specify an entry ID, a CGI which needs one will assume you want [current year]/[current month].
There are four SSI scripts which come packaged with NewsBruiser. To use them, run them with SSI #exec directives in a .shtml file. A sample invocation is given at the beginning of each script file.
this_month.ssi takes a notebook and displays the current month's entries, using the same format as view.cgi.
this_month_calendar.ssi takes a notebook and displays a calendar for the current month, in the same way as calender.cgi would.
last_n_entries.ssi takes a number and a notebook, and displays that number of the most recent entries in the notebook, using the same format as view.cgi. An alternate version of this_month.ssi for those who write a whole lot or very little every month.
today_in_history.ssi takes a notebook and is not very interesting until that notebook has had regular postings for a few months. Prints out the first few words of the first entry of the day for this day in previous months or (if the notebook has old enough entries) previous years.