This change is based on a patch by Bruno Haible <bruno@clisp.org>.

* src/include/device.h: Add comments.
* src/include/font.h: Add comments.
* src/include/unicode.h: Likewise.
* src/include/ptable.h, src/libs/libgroff/ptable.cpp: Likewise.

Fix quotation in comments to be of the form `xxx'.

10 files changed, 361 insertions, 102 deletions

diff --git a/ChangeLog b/ChangeLog
index 73dd3d41..da9fa163 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2006-01-26  Werner LEMBERG  <wl@gnu.org>
+
+	This change is based on a patch by Bruno Haible <bruno@clisp.org>.
+
+	* src/include/device.h: Add comments.
+	* src/include/font.h: Add comments.
+	* src/include/unicode.h: Likewise.
+	* src/include/ptable.h, src/libs/libgroff/ptable.cpp: Likewise.
+
 2006-01-26  Keith Marshall  <keith.d.marshall@ntlworld.com>
 
 	Suppress `.st' request emission by `grn'.
diff --git a/src/devices/xditview/DviP.h b/src/devices/xditview/DviP.h
index 00f32c81..545661c5 100644
--- a/src/devices/xditview/DviP.h
+++ b/src/devices/xditview/DviP.h
@@ -132,7 +132,7 @@ typedef struct {
 	XFontStruct	*default_font;
 	FILE		*file;
 	Boolean		noPolyText;
-	Boolean		seek;		/* file is "seekable" */
+	Boolean		seek;		/* file is `seekable' */
 	int		default_resolution;
 	/*
  	 * private state
diff --git a/src/include/device.h b/src/include/device.h
index ecafc26c..4bd4378b 100644
--- a/src/include/device.h
+++ b/src/include/device.h
@@ -1,5 +1,5 @@
 // -*- C++ -*-
-/* Copyright (C) 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
+/* Copyright (C) 1989, 1990, 1991, 1992, 2006 Free Software Foundation, Inc.
      Written by James Clark (jjc@jclark.com)
 
 This file is part of groff.
@@ -18,4 +18,9 @@ You should have received a copy of the GNU General Public License along
 with groff; see the file COPYING.  If not, write to the Free Software
 Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
 
+// The target device.  Once initialized, the device doesn't change during
+// the entire program run.  Sample devices are `ps' (for Postscript), `html'
+// (for HTML), and `ascii', `latin1', `utf8' for TTY output.
 extern const char *device;
+
+// end of device.h
diff --git a/src/include/font.h b/src/include/font.h
index 3ef4fed4..49cc6ef6 100644
--- a/src/include/font.h
+++ b/src/include/font.h
@@ -1,5 +1,5 @@
 // -*- C++ -*-
-/* Copyright (C) 1989, 1990, 1991, 1992, 2002, 2004
+/* Copyright (C) 1989, 1990, 1991, 1992, 2002, 2004, 2006
    Free Software Foundation, Inc.
      Written by James Clark (jjc@jclark.com)
 
@@ -19,106 +19,274 @@ You should have received a copy of the GNU General Public License along
 with groff; see the file COPYING.  If not, write to the Free Software
 Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
 
-typedef void (*FONT_COMMAND_HANDLER)(const char *, const char *,
-				     const char *, int);
+// A function of this type can be registered to define the semantics of
+// arbitrary commands in a font DESC file.
+typedef void (*FONT_COMMAND_HANDLER)(const char *,	// command
+				     const char *,	// arg
+				     const char *,	// file
+				     int);		// lineno
 
+// Types used in non-public members of `class font'.
 struct font_kern_list;
 struct font_char_metric;
 struct font_widths_cache;
 
+// A `class font' instance represents the relevant information of a font of
+// the given device.  This includes the set of glyphs represented by the
+// font, and metrics for each glyph.
+//
+// In the member functions a glyph is represented by a font-independent
+// integer value called an `index'; the functions font::name_to_index and
+// font::number_to_index return such an index.
 class font {
 public:
-  enum {
+  enum {		// The valid argument values of `has_ligature'.
     LIG_ff = 1,
     LIG_fi = 2,
     LIG_fl = 4,
     LIG_ffi = 8,
     LIG_ffl = 16
-    };
+  };
 
-  virtual ~font();
-  int contains(int index);
-  int is_special();
-  int get_width(int index, int point_size);
-  int get_height(int index, int point_size);
-  int get_depth(int index, int point_size);
-  int get_space_width(int point_size);
-  int get_character_type(int index);
-  int get_kern(int index1, int index2, int point_size);
-  int get_skew(int index, int point_size, int slant);
-  int has_ligature(int);
-  int get_italic_correction(int index, int point_size);
-  int get_left_italic_correction(int index, int point_size);
-  int get_subscript_correction(int index, int point_size);
-  int get_code(int i);
-  const char *get_special_device_encoding(int index);
-  const char *get_name();
-  const char *get_internal_name();
-  const char *get_image_generator();
-
-  static int scan_papersize(const char *, const char **, double *, double *);
-
-  static font *load_font(const char *, int * = 0, int = 0);
-  static void command_line_font_dir(const char *path);
-  static FILE *open_file(const char *name, char **pathp);
-  static int load_desc();
-  static int name_to_index(const char *);
-  static int number_to_index(int);
+  virtual ~font();	// Destructor.
+  int contains(int);	// Return 1 if this font contains the glyph with the
+			// given index, 0 otherwise.
+  int is_special();	// Return 1 if this font is special, 0 otherwise. 
+			// See section `Special Fonts' in the info file of
+			// groff.  Used by make_glyph_node().
+  int get_width(int, int);	// A rectangle represents the shape of the
+			// glyph with the given index (arg1) at the given
+			// point size (arg2).  Return the horizontal
+			// dimension of this rectangle.
+  int get_height(int, int);	// A rectangle represents the shape of the
+			// glyph with the given index (arg1) at the given
+			// point size (arg2).  Return the distance between
+			// the base line and the top of this rectangle.  If
+			// the top is above the base line, this value is
+			// positive.
+  int get_depth(int, int);	// A rectangle represents the shape of the
+			// glyph with the given index (arg1) at the given
+			// point size (arg2).  Return the distance between
+			// the base line and the bottom of this rectangle. 
+			// If the bottom is below the base line, this value
+			// is positive.
+  int get_space_width(int);	// Return the normal width of a space at the
+  			// given point size.
+  int get_character_type(int);	// Return a bit mask describing the shape of
+			// the glyph with the given index.  Bit 0 is set if
+			// the character has a descender.  Bit 1 is set if
+			// the character has a tall glyph.  See groff
+			// manual, description of \w and the `ct' register.
+  int get_kern(int, int, int);	// Return the kerning between the glyphs
+			// with given indices (arg1 and the arg2), both at
+			// the given point size (arg3).
+  int get_skew(int, int, int);	// A rectangle represents the shape of the
+			// glyph with the given index (arg1) at the given
+			// point size (arg2).  For slanted fonts like
+			// Times-Italic, the optical vertical axis is
+			// naturally slanted.  The natural slant value
+			// (measured in degrees; positive values mean a
+			// slant to the right) is specified in the font's
+			// description file (see member variable SLANT
+			// below).  In addition to this, any font can be
+			// artificially slanted.  This artificial slant
+			// value (arg3, measured in degrees; positive values
+			// mean a slant to the right) is specified with the
+			// \S escape.
+			//
+			// Return the skew value which is the horizontal
+			// distance between the upper left corner of the
+			// glyph box and the upper left corner of the glyph
+			// box thought to be slanted by the sum of the
+			// natural and artificial slant.  It basically means
+			// how much an accent must be shifted horizontally
+			// to put it on the optical axis of the glyph.
+  int has_ligature(int);	// Return a non-zero value if this font has
+			// the given ligature type (one of LIG_ff, LIG_fi,
+			// etc.), 0 otherwise.
+  int get_italic_correction(int, int);	// If the glyph with the given index
+			// (arg1) at the given point size (arg2) is followed
+			// by an unslanted glyph, some horizontal white
+			// space may need to be inserted in between.  See
+			// the groff manual, description of \/.  Return the
+			// amount (width) of this white space.
+  int get_left_italic_correction(int, int);	// If the glyph with the
+			// given index (arg1) at the given point size (arg2)
+			// is preceded by an unslanted roman glyph, some
+			// horizontal white space may need to be inserted in
+			// between.  See the groff manual, description of
+			// \,.  Return the amount (width) of this white
+			// space.
+  int get_subscript_correction(int, int);	// If the glyph with the
+			// given index (arg1) at the given point size (arg2)
+			// is followed by a subscript glyph, the horizontal
+			// position may need to be advanced by some
+			// (possibly negative) amount.  See groff manual,
+			// description of \w and the `ssc' register.  Return
+			// this amount.
+  int get_code(int);	// Return the code point in the physical font of the
+			// glyph with the given index.
+  const char *get_special_device_encoding(int);	// Return special device
+			// dependent information about the glyph with the
+			// given index.  Return NULL if there is no special
+			// information.
+  const char *get_name();	// Return the name of this font.
+  const char *get_internal_name();	// Return the `internalname'
+			// attribute of this font.  Return NULL if it has
+			// none.
+  const char *get_image_generator();	// Return the `image_generator'
+			// attribute of this font.  Return NULL if it has
+			// none.
+  static int scan_papersize(const char *, const char **,
+			    double *, double *);	// Parse the
+			// `papersize' attribute in a DESC file (given in
+			// arg1).  Return the name of the size (in arg2),
+			// and the length and width (in arg3 and arg4). 
+			// Return 1 in case of success, 0 otherwise.
+  static font *load_font(const char *, int * = 0, int = 0);	// Load the
+			// font description file with the given name (arg1)
+			// and return it as a `font' class.  If arg2 points
+			// to an integer variable, set it to 1 if the file
+			// is not found, without emitting an error message. 
+			// If arg2 is NULL, print an error message if the
+			// file is not found.  If arg3 is nonzero, only the
+			// part of the font description file before the
+			// `charset' and `kernpairs' sections is loaded. 
+			// Return NULL in case of failure.
+  static void command_line_font_dir(const char *);	// Prepend given
+			// path (arg1) to the list of directories in which
+			// to look up fonts.
+  static FILE *open_file(const char *, char **);	// Open a font file
+			// with the given name (arg1), searching along the
+			// current font path.  If arg2 points to a string
+			// pointer, set it to the found file name (this
+			// depends on the device also).  Return the opened
+			// file.  If not found, arg2 is unchanged, and NULL
+			// is returned.
+  static int load_desc();	// Open the DESC file (depending on the
+			// device) and initialize some static variables with
+			// info from there.
+  static int name_to_index(const char *);	// Convert the glyph with
+			// the given name (arg1) to a glyph index.  This has
+			// the same semantics as the groff escape sequence
+			// \C'name'.  If such an index does not yet exist, a
+			// new one is allocated.
+  static int number_to_index(int);	// Convert the font-dependent glyph
+			// with the given number (in the font) to a glyph
+			// index.  This has the same semantics as the groff
+			// escape sequence \N'number'.  If such an index
+			// does not yet exist, a new one is allocated.
   static FONT_COMMAND_HANDLER
-    set_unknown_desc_command_handler(FONT_COMMAND_HANDLER);
-
-  static int res;
-  static int hor;
-  static int vert;
-  static int unitwidth;
-  static int paperwidth;
-  static int paperlength;
+    set_unknown_desc_command_handler(FONT_COMMAND_HANDLER);	// Register
+			// a function which defines the semantics of
+			// arbitrary commands in the font DESC file.
+  static int res;	// The `res' attribute given in the DESC file.
+  static int hor;	// The `hor' attribute given in the DESC file.
+  static int vert;	// The `vert' attribute given in the DESC file.
+  static int unitwidth;	// The `unitwidth' attribute given in the DESC file.
+  static int paperwidth;	// The `paperwidth' attribute given in the
+			// DESC file, or derived from the `papersize'
+			// attribute given in the DESC file.
+  static int paperlength;	// The `paperlength' attribute given in the
+			// DESC file, or derived from the `papersize'
+			// attribute given in the DESC file.
   static const char *papersize;
-  static int biggestfont;
+  static int biggestfont;	// The `biggestfont' attribute given in the
+			// DESC file.
   static int spare2;
-  static int sizescale;
-  static int tcommand;
-  static int unscaled_charwidths;
-  static int pass_filenames;
-  static int use_charnames_in_special;
-  static const char *image_generator;
+  static int sizescale;	// The `sizescale' attribute given in the DESC file.
+  static int tcommand;  // Nonzero if the DESC file has the `tcommand'
+			// attribute.
+  static int unscaled_charwidths;	// Nonzero if the DESC file has the
+			// `unscaled_charwidths' attribute.
+  static int pass_filenames;	// Nonzero if the DESC file has the
+			// `pass_filenames' attribute.
+  static int use_charnames_in_special;	// Nonzero if the DESC file has the
+			// `use_charnames_in_special' attribute.
+  static const char *image_generator;	// The `image_generator' attribute
+			// given in the DESC file.
+  static const char **font_name_table;	// The `fonts' attribute given in
+			// the DESC file, as a NULL-terminated array of
+			// strings.
+  static const char **style_table;	// The `styles' attribute given in
+			// the DESC file, as a NULL-terminated array of
+			// strings.
+  static const char *family;	// The `family' attribute given in the DESC
+			// file.
+  static int *sizes;	// The `sizes' attribute given in the DESC file, as
+			// an array of intervals of the form { lower1,
+			// upper1, ... lowerN, upperN, 0 }.
 
-  static const char **font_name_table;
-  static const char **style_table;
-  static const char *family;
-  static int *sizes;
 private:
-  unsigned ligatures;
-  font_kern_list **kern_hash_table;
-  int space_width;
-  int *ch_index;
+  unsigned ligatures;	// Bit mask of available ligatures.  Used by
+			// has_ligature().
+  font_kern_list **kern_hash_table;	// Hash table of kerning pairs. 
+			// Used by get_kern().
+  int space_width;	// The normal width of a space.  Used by
+			// get_space_width().
+  int *ch_index;	// Conversion table from font-independent character
+			// indices to indices for this particular font.
   int nindices;
-  font_char_metric *ch;
+  font_char_metric *ch;	// Metrics information for every character in this
+			// font.  The indices of this array are
+			// font-specific, found as values in ch_index[].
   int ch_used;
   int ch_size;
-  int special;
-  char *name;
-  char *internalname;
-  double slant;
-  font_widths_cache *widths_cache;
-  static FONT_COMMAND_HANDLER unknown_desc_command_handler;
-
-  enum { KERN_HASH_TABLE_SIZE = 503 };
+  int special;		// 1 if this font is special, 0 otherwise.  Used by
+			// is_special().
+  char *name;		// The name of this font.  Used by get_name().
+  char *internalname;	// The `internalname' attribute of this font, or
+			// NULL.  Used by get_internal_name().
+  double slant;		// The natural slant angle (in degrees) of this font.
+  font_widths_cache *widths_cache;	// A cache of scaled character
+			// widths.  Used by the get_width() function.
+  static FONT_COMMAND_HANDLER unknown_desc_command_handler;	// A
+			// function defining the semantics of arbitrary
+			// commands in the DESC file.
+  enum { KERN_HASH_TABLE_SIZE = 503 };	// Size of the hash table of kerning
+			// pairs.
 
-  void add_entry(int index, const font_char_metric &);
-  void copy_entry(int new_index, int old_index);
-  void add_kern(int index1, int index2, int amount);
-  static int hash_kern(int i1, int i2);
-  void alloc_ch_index(int);
+  // These methods add new characters to the ch_index[] and ch[] arrays.
+  void add_entry(int,				// index
+		 const font_char_metric &);	// metric
+  void copy_entry(int,				// new_index
+		  int);				// old_index
+  void alloc_ch_index(int);			// index
   void extend_ch();
   void compact();
 
+  void add_kern(int, int, int);	// Add to the kerning table a kerning amount
+			// (arg3) between two glyphs with given indices
+			// (arg1 and arg2).
+  static int hash_kern(int, int);	// Return a hash code for the pair
+			// of glyph indices (arg1 and arg2).
+
+  /* Returns w * pointsize / unitwidth, rounded to the nearest integer.  */
   static int scale(int w, int pointsize);
-  static int unit_scale(double *value, char unit);
-  virtual void handle_unknown_font_command(const char *command,
-					   const char *arg,
-					   const char *file, int lineno);
+  static int unit_scale(double *, char); // Convert value in arg1 from the
+			// given unit (arg2; possible values are `i', `c',
+			// `p', and `P' as documented in the info file of
+			// groff, section `Measurements') to inches.  Store
+			// the result in arg1 and return 1.  If the unit is
+			// invalid, return 0.
+  virtual void handle_unknown_font_command(const char *,	// command
+					   const char *,	// arg
+					   const char *,	// file
+					   int);		// lineno
+
 protected:
-  font(const char *);
-  int load(int * = 0, int = 0);
+  font(const char *);	// Initialize a font with the given name.
+
+  int load(int * = 0, int = 0);	// Load the font description file with the
+			// given name (in member variable NAME) into this
+			// object.  If arg1 points to an integer variable,
+			// set it to 1 if the file is not found, without
+			// emitting an error message.  If arg1 is NULL,
+			// print an error message if the file is not found. 
+			// If arg2 is nonzero, only the part of the font
+			// description file before the `charset' and
+			// `kernpairs' sections is loaded.  Return NULL in
+			// case of failure.
 };
+
+// end of font.h
diff --git a/src/include/ptable.h b/src/include/ptable.h
index b2881872..fadb158d 100644
--- a/src/include/ptable.h
+++ b/src/include/ptable.h
@@ -1,5 +1,5 @@
 // -*- C++ -*-
-/* Copyright (C) 1989, 1990, 1991, 1992, 2003, 2004
+/* Copyright (C) 1989, 1990, 1991, 1992, 2003, 2004, 2006
    Free Software Foundation, Inc.
      Written by James Clark (jjc@jclark.com)
 
@@ -22,20 +22,36 @@ Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
 #include <assert.h>
 #include <string.h>
 
+// name2(a,b) concatenates two C identifiers.
 #ifdef TRADITIONAL_CPP
-#define name2(a,b) a/**/b
+# define name2(a,b) a/**/b
 #else /* not TRADITIONAL_CPP */
-#define name2(a,b) name2x(a,b)
-#define name2x(a,b) a ## b
+# define name2(a,b) name2x(a,b)
+# define name2x(a,b) a ## b
 #endif /* not TRADITIONAL_CPP */
 
+// `class PTABLE(T)' is the type of a hash table mapping a string
+// (const char *) to an object of type T.
+// `struct PASSOC(T)' is the type of a association (pair) between a
+// string (const char *) and an object of type T.
+// `class PTABLE_ITERATOR(T)' is the type of an iterator iterating through a
+// `class PTABLE(T)'.
+//
+// Nowadays one would use templates for this; this code predates the addition
+// of templates to C++.
 #define PTABLE(T) name2(T,_ptable)
 #define PASSOC(T) name2(T,_passoc)
 #define PTABLE_ITERATOR(T) name2(T,_ptable_iterator)
 
-extern unsigned next_ptable_size(unsigned);
-extern unsigned long hash_string(const char *);
+extern unsigned next_ptable_size(unsigned);	// Return the first suitable
+				// hash table size greater than the given
+				// value.
+extern unsigned long hash_string(const char *);	// Return a hash code of the
+				// given string.  The hash function is
+				// platform dependent.  */
 
+// Declare the types `class PTABLE(T)', `struct PASSOC(T)', and `class
+// PTABLE_ITERATOR(T)' for the type `T'.
 #define declare_ptable(T)						      \
 									      \
 struct PASSOC(T) {							      \
@@ -50,20 +66,33 @@ class PTABLE_ITERATOR(T) {						      \
   PTABLE(T) *p;								      \
   unsigned i;								      \
 public:									      \
-  PTABLE_ITERATOR(T)(PTABLE(T) *);					      \
-  int next(const char **, T **);					      \
+  PTABLE_ITERATOR(T)(PTABLE(T) *);	/* Initialize an iterator running     \
+					   through the given table.  */	      \
+  int next(const char **, T **);	/* Fetch the next pair, store the key \
+					   and value in arg1 and arg2,	      \
+					   respectively, and return 1.  If    \
+					   there is no more pair in the	      \
+					   table, return 0.  */		      \
 };									      \
 									      \
 class PTABLE(T) {							      \
   PASSOC(T) *v;								      \
   unsigned size;							      \
   unsigned used;							      \
-  enum { FULL_NUM = 2, FULL_DEN = 3, INITIAL_SIZE = 17 };		      \
+  enum {								      \
+    FULL_NUM = 2,							      \
+    FULL_DEN = 3,							      \
+    INITIAL_SIZE = 17							      \
+  };									      \
 public:									      \
-  PTABLE(T)();								      \
-  ~PTABLE(T)();								      \
-  void define(const char *, T *);					      \
-  T *lookup(const char *);						      \
+  PTABLE(T)();				/* Create an empty table.  */	      \
+  ~PTABLE(T)();				/* Delete a table, including its      \
+					   values.  */			      \
+  void define(const char *, T *);	/* Define the value (arg2) for a key  \
+					   (arg1).  */			      \
+  T *lookup(const char *);		/* Return a pointer to the value of   \
+					   the given key, if found in the     \
+					   table, or NULL otherwise.  */      \
   friend class PTABLE_ITERATOR(T);					      \
 };
 
@@ -72,6 +101,8 @@ public:									      \
 // Values must be allocated by the caller (always using new[], not new)
 // and are freed by PTABLE.
 
+// Define the implementations of the members of the types `class PTABLE(T)',
+// `struct PASSOC(T)', `class PTABLE_ITERATOR(T)' for the type `T'.
 #define implement_ptable(T)						      \
 									      \
 PASSOC(T)::PASSOC(T)()							      \
@@ -170,3 +201,5 @@ int PTABLE_ITERATOR(T)::next(const char **keyp, T **valp)		      \
     }									      \
   return 0;								      \
 }
+
+// end of ptable.h
diff --git a/src/include/unicode.h b/src/include/unicode.h
index 90dab113..d5351c35 100644
--- a/src/include/unicode.h
+++ b/src/include/unicode.h
@@ -1,5 +1,5 @@
 // -*- C++ -*-
-/* Copyright (C) 2002, 2003
+/* Copyright (C) 2002, 2003, 2006
    Free Software Foundation, Inc.
      Written by Werner Lemberg <wl@gnu.org>
 
@@ -19,8 +19,47 @@ You should have received a copy of the GNU General Public License along
 with groff; see the file COPYING.  If not, write to the Free Software
 Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
 
+// Convert a groff glyph name to a string containing an underscore-separated
+// list of Unicode code points.  For example,
+//
+//   `-'   ->  `2010'
+//   `,c'  ->  `00E7'
+//   `fl'  ->  `0066_006C'
+//
+// Return NULL if there is no equivalent.
 const char *glyph_name_to_unicode(const char *);
+
+// Convert a string containing an underscore-separated list of Unicode code
+// points to a groff glyph name.  For example,
+//
+//   `2010'       ->  `hy'
+//   `0066_006C'  ->  `fl'
+//
+// Return NULL if there is no equivalent.
 const char *unicode_to_glyph_name(const char *);
+
+// Convert a string containing a precomposed Unicode character to a string
+// containing an underscore-separated list of Unicode code points,
+// representing its canonical decomposition.  Also perform compatibility
+// equivalent replacement.  For example,
+//
+//   `1F3A' -> `0399_0313_0300'
+//   `FA6A' -> `983B'
+//
+// Return NULL if there is no equivalent.
 const char *decompose_unicode(const char *);
 
+// Test whether the given string denotes a Unicode character.  It must
+// be of the form `uNNNN', obeying the following rules.
+//
+//   - `NNNN' must consist of at least 4 hexadecimal digits in upper case.
+//   - If there are more than 4 hexadecimal digits, the leading one must not
+//     be zero,
+//   - `NNNN' must denote a valid Unicode code point (U+0000..U+10FFFF,
+//     excluding surrogate code points.
+//
+// Return a pointer to `NNNN' (skipping the leading `u' character) in case
+// of success, NULL otherwise.
 const char *check_unicode_name(const char *);
+
+// end of unicode.h
diff --git a/src/libs/libgroff/ptable.cpp b/src/libs/libgroff/ptable.cpp
index bde2c3ca..9c3f0c05 100644
--- a/src/libs/libgroff/ptable.cpp
+++ b/src/libs/libgroff/ptable.cpp
@@ -1,4 +1,4 @@
-/* Copyright (C) 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
+/* Copyright (C) 1989, 1990, 1991, 1992, 2006 Free Software Foundation, Inc.
      Written by James Clark (jjc@jclark.com)
 
 This file is part of groff.
@@ -23,6 +23,8 @@ Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
 
 unsigned long hash_string(const char *s)
 {
+  // This is the mythical Aho-Hopcroft-Ullman hash function.
+  // TODO: Improve.  See http://www.haible.de/bruno/hashfunc.html
   assert(s != 0);
   unsigned long h = 0, g;
   while (*s != 0) {
@@ -37,9 +39,9 @@ unsigned long hash_string(const char *s)
 }
 
 static const unsigned table_sizes[] = { 
-101, 503, 1009, 2003, 3001, 4001, 5003, 10007, 20011, 40009,
-80021, 160001, 500009, 1000003, 2000003, 4000037, 8000009,
-16000057, 32000011, 64000031, 128000003, 0 
+  101, 503, 1009, 2003, 3001, 4001, 5003, 10007, 20011, 40009,
+  80021, 160001, 500009, 1000003, 2000003, 4000037, 8000009,
+  16000057, 32000011, 64000031, 128000003, 0 
 };
 
 unsigned next_ptable_size(unsigned n)
@@ -50,3 +52,5 @@ unsigned next_ptable_size(unsigned n)
       fatal("cannot expand table");
   return *p;
 }
+
+// end of ptable.cpp
diff --git a/src/libs/libgroff/putenv.c b/src/libs/libgroff/putenv.c
index 2091f3b9..8e7868e8 100644
--- a/src/libs/libgroff/putenv.c
+++ b/src/libs/libgroff/putenv.c
@@ -1,4 +1,4 @@
-/* Copyright (C) 1991, 2001 Free Software Foundation, Inc.
+/* Copyright (C) 1991, 2001, 2006 Free Software Foundation, Inc.
 This file is part of the GNU C Library.
 
 The GNU C Library is free software; you can redistribute it and/or
@@ -45,7 +45,7 @@ PTR malloc();
 
 extern char **environ;
 
-/* Put STRING, which is of the form "NAME=VALUE", in the environment.  */
+/* Put STRING, which is of the form `NAME=VALUE', in the environment.  */
 
 int putenv(const char *string)
 {
diff --git a/src/preproc/grn/main.cpp b/src/preproc/grn/main.cpp
index 22bf7245..401109ad 100644
--- a/src/preproc/grn/main.cpp
+++ b/src/preproc/grn/main.cpp
@@ -219,9 +219,9 @@ int linenum = 0;		/* line number of input file */
 char inputline[MAXINLINE];	/* spot to filter through the file */
 char *c1 = inputline;		/* c1, c2, and c3 will be used to */
 char *c2 = inputline + 1;	/* hunt for lines that begin with */
-char *c3 = inputline + 2;	/* ".GS" by looking individually */
+char *c3 = inputline + 2;	/* `.GS' by looking individually */
 char *c4 = inputline + 3;	/* needed for compatibility mode */
-char GScommand[MAXINLINE];	/* put user's ".GS" command line here */
+char GScommand[MAXINLINE];	/* put user's `.GS' command line here */
 char gremlinfile[MAXINLINE];	/* filename to use for a picture */
 int SUNFILE = FALSE;		/* TRUE if SUN gremlin file */
 int compatibility_flag = FALSE;	/* TRUE if in compatibility mode */
diff --git a/src/roff/groff/pipeline.c b/src/roff/groff/pipeline.c
index d067ae93..5167a783 100644
--- a/src/roff/groff/pipeline.c
+++ b/src/roff/groff/pipeline.c
@@ -1,4 +1,5 @@
-/* Copyright (C) 1989, 1990, 1991, 1992, 2000, 2001, 2002, 2003, 2004, 2005
+/* Copyright (C) 1989, 1990, 1991, 1992, 2000, 2001, 2002, 2003, 2004, 2005,
+                 2006
    Free Software Foundation, Inc.
      Written by James Clark (jjc@jclark.com)
 
@@ -168,7 +169,7 @@ const char *system_shell_dash_c(void)
 
   shell_name = system_shell_name();
 
-  /* Assume that if the shell name ends in "sh", it's Unixy */
+  /* Assume that if the shell name ends in `sh', it's Unixy */
   if (strcasecmp(shell_name + strlen(shell_name) - strlen("sh"), "sh") == 0)
     dash_c = "-c";
   else