Nanocomment is a standalone comment tracking system intended to be used with nanoblogger. Comments are stored in a relational database, and the now-dynamic aspects of the nanoblogger pages are provided through PHP scripts. Nanocomment is intended to be a replacement to NBCom, offering similar functionality and improvements in appearance and flexibility. ------------------------------------------------------------------------------- REQUIREMENTS Nanoblogger (http://nanoblogger.sourceforge.net/) I have tested these instructions with versions 3.3rc5. It is likely possible to use Nanocomment with earlier versions, but it will require different template modifications and possibly plugin modifications, and you're on your own for that. PHP >= 5.0 (http://www.php.net/) The comment body validation makes use of the PHP DOM functions which did not appear until PHP 5. The dom extension is required. The iconv and gd (required for the spam-prevention image test) extensions are also needed. If you use typekey authentication, either bcmath or gmp must be available. libxml2 >= 2.6.23 (http://www.xmlsoft.org/) (Schema validation only) The schema validation for comment bodies requires the use of xsd:redefine, which was not enabled in libxml2 until 2.6.23. PHP must be compiled with this version of libxml2 or newer. As an alternative, a RELAX-NG schema is also provided that works with older versions of libxml2. MDB2 (http://pear.php.net/package/MDB2) MDB2 can be installed through PEAR. In addition, the driver for your particular database (e.g., MDB2_Driver_mysql, MDB2_Driver_pgsql) is required. A database Either mysql or postgresql are supported. A Typekey account (optional): Nanocomment can optionally use Typekey to identify the names of commenters. Typekey is a service provided by Movable Type that handles user identification and authentication in a centralized manner, removing the need for individual blogs to worry about the hassle and security implications of storing accounts. To use Typekey with nanocomment, you will need a Typekey token, you will need to add your blog's URL to the list of allowed sites in your Typekey account preferences, and you will need to set NC_USE_TYPEKEY to "1" in your blog.conf. ------------------------------------------------------------------------------- INSTALLATION Instructions for installing on a clean Nanoblogger blog as well as instructions for converting from NBCom are available in the INSTALL file. Instructions for upgrading from Nanocomment 1.0 along with a summary of changes are provided in the UPGRADE file. ------------------------------------------------------------------------------- CONFIGURATION Several blog.conf variables affect the operation of Nanocomment. Variables specific to Nanocomment are described in nanocomment.conf. All variables therein must be included in blog.conf before using Nanocomment, and sensible defaults are provided. The use of $DATE_FORMAT deserves some special attention. Comment timestamps are formatted using the PHP strftime function. The format characters accepted by PHP are a superset of the basic format characters defined by POSIX, but certain extensions of the date program, such as those provided by GNU, may not be supported. See http://www.php.net/manual/en/function.strftime.php if you are unsure. In the case of an empty $DATE_FORMAT, the %c format will be used which may not necessarily be identical to the output of date with no formatting options. I would recommend setting an explicit $DATE_FORMAT in order to avoid inconsistencies. For example, the output of date with no arguments may look something like Sat Dec 16 17:37:39 EST 2006 which could be represented by "%a %b %e %H:%M:%S %Z %Y" for both GNU date and PHP. ------------------------------------------------------------------------------- COMPATIBILITY WITH NBCOM Nanocomment uses the same URL structure as NBCom, so, if cmt.php is installed in the same location and the entry IDs provided as the article argument are not changed, existing NBCom URLs will continue to work under Nanocomment. Considerations for the article argument are described in the INSTALL file under the TEMPLATES section. The RSS output by nbcom's 'act=showrss' mode does not include guid elements, whereas Nanocomment does. This means that your RSS reader will view all items as new after switching from NBCom to Nanocomment. ------------------------------------------------------------------------------- TRACKBACKS Nanocomment 2.0 adds the ability to receive trackback pings as specified in . Trackbacks are similar to comments except that they point to an entire blog entry instead of a short, standalone comment. Like anything on the Internet, trackbacks are vulnerable to spam. Trackback pings are especially troublesome since trackback pings only contain a small, standardized set of data, so there is no way to include bot-prevention tests like with comments. One common method of spam prevention is to fetch the content of the trackback link and search for the blog URL being pinged. This is what nanocomment does. Although this will catch the majority of spam trackback pings, trackbacks are usually sent automatically by a blog engine, so there's a chance that the ping may be sent before the page doing the pinging is published, meaning that the fetch-and-check method may deny some valid pings. Also, the URLs being searched for by nanocomment may not exactly match the format being used by the pinging blog. Nanocomment has no ability to send trackback pings automatically. Parsing HTML in bash is super-hard, so this feature probably won't be added in the future. A script, tb-ping, is provided to simplify sending trackback pings to other blogs. ------------------------------------------------------------------------------- A NOTE ON MAGIC QUOTES AND SQL SYNTACES Most SQL implementations add their own deviations and interpretations of the standard SQL syntax, and database abstraction layers such as MDB2 are unable to handle every case. Two aspects of the SQL syntax used in Nanocomment unlikely to work everywhere are the date formatting and the "LIMIT" keyword. Date formatting differs wildly among databases, so Nanocomment punts on the issue and does the actual formatting in PHP. The dbdate() function in scripts/funcs.php is used to create an expression to select the UNIX epoch-- seconds from January 1, 1970, UTC--from a date column, and this function must be modified to support new database syntaces. The LIMIT keyword is used by the feeds to restrict the dataset to the most recent entries. It is supported by both mysql and postgresql, but Oracle, for example, does not use this keyword. If you wish to use Nanocomment with Oracle, you would need to replace "LIMIT $NC_LIMIT_ITEMS" with an addition to the WHERE clause of "ROWNUM <= $NC_LIMIT_ITEMS". String quoting is another point of drastic difference, but MDB2 is, fortunately, able to quote strings in a manner appropriate to the driver being used. The problem with quoting comes instead from PHP itself. By default, PHP ships with the magic_quotes_gpc configuration variable set, the intent of which is to allow programmers to append data from a form into a SQL query without checking or modifying its contents. This can create a nightmare of escaping for those interested in portability or accuracy, as it means that the values for GET and POST data differ depending on the environment, and the means of escaping performed is not likely to exactly match the escaping necessary for the particular SQL syntax. Also, as is PHP's wont, the stated means and occurrence of escaping does not exactly match the actual behavior, and the documentation contradicts itself by recommending both to leave magic_quotes_gpc on but to code as if it is off. Nanocomment does not use arrays indexed by array in the GET or POST data, and so is hopefully safe in checking only the value of get_magic_quotes_gpc to determine what processing is necessary to obtain the original strings. There are two other variables as of PHP5 that can affect string behavior, magic_quotes_sybase, which escapes strings in the Sybase (and Oracle) method of adding another apostrophe to literal apostrophes, and magic_quotes_runtime, which escapes the data from "most functions that return data from an external source," though the exact set of these functions is not specified. magic_quotes_sybase, unlike magic_quotes_gpc, does not have a corresponding function to test its value, and thus it is only accessible through ini_get. Though I could test its value this way, I have no guarantee that PHP won't add another automatic escaping variable tomorrow, so testing for one particular value seems ultimately futile. magic_quotes_runtime defines an entire shadowy world of potential escaping, and I will not test each of the functions I use to determine whether it does or does not add backslashes to everything it returns. If you are using either of these configuration variables, please stop. ------------------------------------------------------------------------------- LICENSING AND CONTACT Nanocomment is written and maintained by David Shea and licensed under version 2 of the GPL, provided in the file COPYING. Send any comments or bug reports to david@gophernet.org. img.php is taken from NBCom-1.1 (http://nhw.pl/blg/articles/nbcom/) by Witold Rugowski based on code from http://www.phpclasses.org/browse/package/2349.html written by Rochak Chauhan. Licensing information for nbcom is provided in NBCOM-COPYRIGHT. Auth_TypeKey.php (http://pear.php.net/pepr/pepr-proposal-show.php?id=164) is written by Daiji Hirata and licensed under the PHP license, a copy of which is provided in PHP-LICENSE. The XHTML schemata distributed here for comment body validation are Copyright 1998-2005 World Wide Web Consortium. The full copyright and licensing information is provided in schema/xhtml-copyright-1.xsd.