On Friday, May 18, the normal maintenance window (17:00 Pacific time) will be extended for data center maintenance until 23:00 Pacific. No extended down-time is planned, but brief delays and interruptions are possible throughout the period.
Newsbruiser User Documentation
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.
Installation
- Untar the NewsBruiser .tar.gz into a Web-accessible directory,
eg. ~/public_html/nb.
- In a web browser, visit the root of the directory you just
untarred. If you see a directory index instead of a welcome message,
you don't have SSI enabled: visit nb.cgi in that directory.
- Follow the directions in the setup script. This may involve
briefly changing permissions or file ownership on the web
server. You'll also be asked to choose a master password and a name
for an initial notebook.
- Once NewsBruiser is set up, you'll be redirected to the main page
for the notebook you created during setup. You're now ready to start
using NewsBruiser.
- The best thing to do initially is to configure the notebook you
just created. Follow the "Configure" link "Configure" link from and
change the configuration information to your liking. You will want to
change all the text fields under the 'Notebook' heading, and possibly
take a trip to the 'Security' heading to tell NewsBruiser not to use
an authentication cookie. You may also wish to make a brief trip to
'Syndication/Notification' to turn on weblogs.com notification. The
rest you can leave alone now and experiment with later.
- You're now ready to import old entries (if you are moving to
NewsBruiser from another blogging tool), or just start posting
new ones.
If you have problems, or you're confused about the format of the
NewsBruiser configuration file, look at the the configuration document.
The CGI Interface
Obsolete: There is now only one .cgi file: nb.cgi. All the
other .cgi files are now activated by passing a PATH argument to
nb.cgi. For instance, edit.cgi becomes nb.cgi/edit.
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 index.cgi CGI. This CGI is the 'home page' for
NewsBruiser. It presents information about a notebook and links to
most of its other functionality in a 'control panel' format. If you do
not specify a notebook, it will display control panels for all
notebooks.
- Several CGIs for viewing and manipulating
notebook entries.
- Several CGIs for viewing and manipulating categories
- The login.cgi CGI. This CGI challenges you for the
notebook password, and then sets your authentication cookie. You will
only see links to this CGI if you are using authentication
cookies. Certain other CGIs may redirect you to this one if you're not
already logged in.
- The logout.cgi CGI. This CGI clears your authentication
cookie and then redirects you back to the CGI you came from; after
logging out, you will have to enter your notebook password again to
make any changes. You will only see links to this CGI if you are using
authentication cookies.
The gory details
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].
The SSIs
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.
Other documents
