Leonard Richardson <leonardr@segfault.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.
Note: For your convenience, this documentation is Ahoy-enabled. If you're using a Mozilla-derived browser, you can Alt-select any text in the documentation and get a link to that selection. Unfortunately, this only works properly if you're reading this documentation on your local install as opposed to on tigris.org.
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 CGIs are as follows:
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 several 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.
last_n_days.ssi takes a number and a notebook, and finds that number of days of recent entries for the notebook. For those who want the time-based aspects of this_month.ssi but want to deal with shorter units of time.
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.