Login | Register
My pages Projects Community openCollabNet

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

  1. Untar the NewsBruiser .tar.gz into a Web-accessible directory, eg. ~/public_html/nb.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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