Newsbruiser User Documentation

Leonard Richardson <leonardr@segfault.org>
Version: 1.4.0

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.

Installation

  1. Untar the NewsBruiser .tar.gz into a Web-accessible directory, eg. ~/public_html/nb.
  2. Run the tool/setup.py script. The script will ask you for four pieces of information:
    1. Where your NewsBruiser installation is located. Unless you moved things around after unzipping the tarball, it will guess this correctly, so you can just confirm its guess.
    2. Where the script should put the NewsBruiser configuration file. Choose something like /home/[user]/.nb/.nbrc. The directory you specify (in the example case, /home/[user]/.nb/ will be used as NewsBruiser's base directory, and a notebook's information and entries will be stored in a subdirectory of that directory (the name of the subdirectory corresponding to the name of the notebook). setup.py will create the base directory if it doesn't exist.
    3. A notebook name. This is a short name used in URLs; something like "weblog" or "notebook" is fine, or you can use the abbreviated name of your weblog.
    4. A password to use when adding entries to the notebook or otherwise modifying it.
  3. setup.py will use the information you gave it to write a simple configuration file to the path you specify. If you want more than one notebook on your site, you can edit that configuration file now (see the configuration document). Otherwise, make sure that NewsBruiser's base directory is writable by the webserver, and proceed.
  4. To verify that you set everything up correctly, hit the NewsBruiser directory with your Web browser. Depending on whether or not you have SSI enabled on your webserver, you should see either a directory listing (in which case you should hit index.cgi instead) or a list of notebooks.

    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.

  5. Once you can view index.cgi, it's time to configure your notebooks. For every notebook in the notebook list, follow its "Configure" link from index.cgi and fill out its configuration information. You will want to change all the text fields under the 'Notebook' heading, and possibly tell NewsBruiser not to use an authentication cookie. At this point 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.

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

Every file with a .cgi extension in the top-level NewsBruiser distribution directory is part of NewsBruiser's Web interface.

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

Other documents