[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Groff] comments
|
From: |
Bruno Haible |
|
Subject: |
[Groff] comments |
|
Date: |
Mon, 23 Jan 2006 16:50:45 +0100 |
|
User-agent: |
KMail/1.5 |
Hi,
For the first step, the support of all Unicode characters without huge data
tables, I intend to submit modifications to the following files:
font.h, font.cpp, nametoindex.cpp, troff/input.cpp, post-html.cpp.
Since most files are without comments and since it takes me about 10 or 50
times more time to understand a method declaration without comments (and
preferrably even with just types and no argument names in the parameter
list!) compared to method declarations with comments, let me start by adding
comments.
If you don't agree that comments are a good thing, I invite you to remove
them after we're done with Unicode support :-) But until then, they will be
useful.
Bruno
2006-01-21 Bruno Haible <address@hidden>
* 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.
*** groff-20060113/src/include/device.h.bak 2005-07-07 13:16:42.000000000
+0200
--- groff-20060113/src/include/device.h 2006-01-17 01:43:55.000000000 +0100
***************
*** 1,5 ****
// -*- C++ -*-
! /* Copyright (C) 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
Written by James Clark (address@hidden)
This file is part of groff.
--- 1,5 ----
// -*- C++ -*-
! /* Copyright (C) 1989, 1990, 1991, 1992, 2006 Free Software Foundation, Inc.
Written by James Clark (address@hidden)
This file is part of groff.
***************
*** 18,21 ****
--- 18,25 ----
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;
*** groff-20060113/src/include/font.h.bak 2005-07-07 13:16:42.000000000
+0200
--- groff-20060113/src/include/font.h 2006-01-21 19:21:15.000000000 +0100
***************
*** 1,5 ****
// -*- C++ -*-
! /* Copyright (C) 1989, 1990, 1991, 1992, 2002, 2004
Free Software Foundation, Inc.
Written by James Clark (address@hidden)
--- 1,5 ----
// -*- C++ -*-
! /* Copyright (C) 1989, 1990, 1991, 1992, 2002, 2004, 2006
Free Software Foundation, Inc.
Written by James Clark (address@hidden)
***************
*** 19,33 ****
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);
struct font_kern_list;
struct font_char_metric;
struct font_widths_cache;
class font {
public:
enum {
LIG_ff = 1,
LIG_fi = 2,
--- 19,43 ----
with groff; see the file COPYING. If not, write to the Free Software
Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
! /* 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 characters represented by
+ the font, and metrics for each character.
+ In the member functions a character is represented by a font-independent
+ 'int' called an "index"; the functions font::name_to_index and
+ font::number_to_index return such an index. */
class font {
public:
+ /* The valid argument values of the has_ligature method. */
enum {
LIG_ff = 1,
LIG_fi = 2,
***************
*** 36,124 ****
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);
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;
static const char *papersize;
static int biggestfont;
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 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;
int nindices;
font_char_metric *ch;
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 };
! 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);
void extend_ch();
void compact();
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);
protected:
! font(const char *);
! int load(int * = 0, int = 0);
};
--- 46,267 ----
LIG_ffl = 16
};
+ /* Destructor. */
virtual ~font();
+ /* Returns 1 if this font contains the character with the given index, 0 if
+ not. */
int contains(int index);
+ /* Returns 1 if this font is special, 0 if not. See the groff documentation
+ node "Special Fonts". Used by make_glyph_node(). */
int is_special();
+ /* A parallelogram represents the shape of the character with the given
index
+ at the given point size. Returns the length of each the top horizontal
+ line and the bottom horizontal line. */
int get_width(int index, int point_size);
+ /* A parallelogram represents the shape part above the baseline of the
+ character with the given index at the given point size. Returns the y
+ coordinate difference between the top horizontal line and the bottom
+ horizontal line (= the baseline) of this parallelogram. */
int get_height(int index, int point_size);
+ /* A parallelogram represents the shape part below the baseline of the
+ character with the given index at the given point size. Returns the y
+ coordinate difference between the bottom horizontal line and the top
+ horizontal line (= the baseline) of this parallelogram. Returns 0 if
+ the character does not extend below the baseline. */
int get_depth(int index, int point_size);
+ /* Returns the normal width of a space at the given point size. */
int get_space_width(int point_size);
+ /* Returns a bit mask describing the shape of the character 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_character_type(int index);
+ /* Returns the kerning between the character index1 and the character
index2,
+ both at the given point size. */
int get_kern(int index1, int index2, int point_size);
+ /* A parallelogram represents the shape of the character with the given
index
+ at the given point size, with the slant of this font plus the given
+ additional slant (given in degrees). Returns the x coordinate difference
+ between the top horizontal and the bottom horizontal lines of this
+ parallelogram. This is 0 if this font's slant and the given additional
+ slant sum up to zero. */
int get_skew(int index, int point_size, int slant);
! /* Returns nonzero if this font has the given ligature type (one of LIG_ff,
! LIG_fi, etc.), 0 if not. */
! int has_ligature(int ligature);
! /* If the character with the given index at the given point size is followed
! by an unslanted roman glyph, some horizontal white space may need to be
! inserted in between. See the groff manual, description of \/. Returns
! the amount (width) of this white space. */
int get_italic_correction(int index, int point_size);
+ /* If the character with the given index at the given point size is preceded
+ by an unslanted roman glyph, some horizontal white space may need to be
+ inserted in between. See the groff manual, description of \,. Returns
+ the amount (width) of this white space. */
int get_left_italic_correction(int index, int point_size);
+ /* If the character with the given index at the given point size is followed
+ by a subscript, the x coordinate might need to be advanced by some
+ (possibly negative) amount. See groff manual, description of \w and
+ the 'ssc' register. Returns this amount. */
int get_subscript_correction(int index, int point_size);
! /* Returns the code point in the physical font of the character with the
! given index. */
! int get_code(int index);
! /* Returns special device dependent information about the character with the
! given index. Returns NULL if there is no special information. */
const char *get_special_device_encoding(int index);
+ /* Returns the name of this font. */
const char *get_name();
+ /* Returns the "internalname" attribute of this font. Returns NULL if it
+ has none. */
const char *get_internal_name();
+ /* Returns the "image_generator" attribute of this font. Returns NULL if it
+ has none. */
const char *get_image_generator();
! /* Parses the "papersize" attribute in a DESC file. Returns the name of the
! size in *size, and the length and width in *length and *width, and
returns
! 1. Returns 0 in case of an error. */
! static int scan_papersize(const char *s,
! const char **size, double *length, double *width);
!
! /* Loads the font with the given name and returns it.
! not_found describes the error handling if the font is not found: If
! not_found is non-NULL, *not_found is set to 1; otherwise an error message
! is printed.
! If head_only is nonzero, only the part of the font before the "charset"
! and "kernpairs" sections is loaded.
! Returns NULL in case of failure. */
! static font *load_font(const char *s, int *not_found = 0, int head_only =
0);
! /* Prepends path to the list of directories in which to look up fonts. */
static void command_line_font_dir(const char *path);
+ /* Opens a font file with the given name. If pathp is non-NULL, sets
+ *pathp to the found pathname (depends also on the device). Returns the
+ opened file. If not found, *pathp is unchanged, and NULL is returned.
*/
static FILE *open_file(const char *name, char **pathp);
+ /* Opens the DESC file (depending on the device) and initializes some static
+ variables with info from there. */
static int load_desc();
! /* Converts the glyph with the given name 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 name_to_index(const char *s);
! /* Converts 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 int number_to_index(int n);
! /* Registers a function which defines the semantics of arbitrary commands
! in the font DESC file. */
static FONT_COMMAND_HANDLER
set_unknown_desc_command_handler(FONT_COMMAND_HANDLER);
+ /* The "res" attribute given in the DESC file. */
static int res;
+ /* The "hor" attribute given in the DESC file. */
static int hor;
+ /* The "vert" attribute given in the DESC file. */
static int vert;
+ /* The "unitwidth" attribute given in the DESC file. */
static int unitwidth;
+ /* The "paperwidth" attribute given in the DESC file, or derived from the
+ "papersize" attribute given in the DESC file. */
static int paperwidth;
+ /* The "paperlength" attribute given in the DESC file, or derived from the
+ "papersize" attribute given in the DESC file. */
static int paperlength;
static const char *papersize;
+ /* The "biggestfont" attribute given in the DESC file. */
static int biggestfont;
static int spare2;
+ /* The "sizescale" attribute given in the DESC file. */
static int sizescale;
+ /* Nonzero if the DESC file has the "tcommand" attribute. */
static int tcommand;
+ /* Nonzero if the DESC file has the "unscaled_charwidths" attribute. */
static int unscaled_charwidths;
+ /* Nonzero if the DESC file has the "pass_filenames" attribute. */
static int pass_filenames;
+ /* Nonzero if the DESC file has the "use_charnames_in_special" attribute.
*/
static int use_charnames_in_special;
+ /* The "image_generator" attribute given in the DESC file. */
static const char *image_generator;
! /* The "fonts" attribute given in the DESC file, as a NULL-terminated
! array of strings. */
static const char **font_name_table;
+ /* The "styles" attribute given in the DESC file, as a NULL-terminated
+ array of strings. */
static const char **style_table;
+ /* The "family" attribute given in the DESC file. */
static const char *family;
+ /* The "sizes" attribute given in the DESC file, as an array of intervals
+ of the form { lower1, upper1, ... lowerN, upperN, 0 }. */
static int *sizes;
private:
+ /* Bit mask of available ligatures. Used by has_ligature(). */
unsigned ligatures;
+ /* Hash table of kerning pairs. Used by get_kern(). */
font_kern_list **kern_hash_table;
+ /* The normal width of a space. Used by get_space_width(). */
int space_width;
+ /* Conversion table from font-independent character indices to indices
+ for this particular font. */
int *ch_index;
int nindices;
+ /* Metrics information for every character in this font. The indices of
+ this array are font-specific, found as values in ch_index[]. */
font_char_metric *ch;
int ch_used;
int ch_size;
+ /* 1 if this font is special, 0 if not. Used by is_special(). */
int special;
+ /* The name of this font. Used by get_name(). */
char *name;
+ /* The "internalname" attribute of this font, or NULL. Used by
+ get_internal_name(). */
char *internalname;
+ /* The slant angle (in degrees) of this font. */
double slant;
+ /* A cache of scaled character widths. Used by the get_width() function.
*/
font_widths_cache *widths_cache;
+ /* A function defining the semantics of arbitrary commands in the DESC
+ file. */
static FONT_COMMAND_HANDLER unknown_desc_command_handler;
+ /* Size of the hash table of kerning pairs. */
enum { KERN_HASH_TABLE_SIZE = 503 };
! /* 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();
+ /* Adds to the kerning table a kerning amount between character index1 and
+ character index2. */
+ void add_kern(int index1, int index2, int amount);
+ /* Returns a hash code for the pair of characters (i1, i2). */
+ static int hash_kern(int i1, int i2);
+
+ /* Returns w * pointsize / unitwidth, rounded to the nearest integer. */
static int scale(int w, int pointsize);
+ /* Convert *value from the given unit ('i', 'c', 'p', 'P', as documented in
+ the groff documentation, node "Measurements") to inches. Stores the
+ result in *value and returns 1. If the unit is invalid, returns 0. */
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);
protected:
! /* Initializes a font with the given name. */
! font(const char *s);
! /* Loads the font with the given name into this object.
! not_found describes the error handling if the font is not found: If
! not_found is non-NULL, *not_found is set to 1; otherwise an error message
! is printed.
! If head_only is nonzero, only the part of the font before the "charset"
! and "kernpairs" sections is loaded.
! Returns nonzero if successful, 0 in case of failure. */
! int load(int *not_found = 0, int head_only = 0);
};
*** groff-20060113/src/include/unicode.h.bak 2005-07-07 13:16:42.000000000
+0200
--- groff-20060113/src/include/unicode.h 2006-01-17 02:55:25.000000000
+0100
***************
*** 1,5 ****
// -*- C++ -*-
! /* Copyright (C) 2002, 2003
Free Software Foundation, Inc.
Written by Werner Lemberg <address@hidden>
--- 1,5 ----
// -*- C++ -*-
! /* Copyright (C) 2002, 2003, 2006
Free Software Foundation, Inc.
Written by Werner Lemberg <address@hidden>
***************
*** 19,26 ****
with groff; see the file COPYING. If not, write to the Free Software
Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
! const char *glyph_name_to_unicode(const char *);
! const char *unicode_to_glyph_name(const char *);
! const char *decompose_unicode(const char *);
!
! const char *check_unicode_name(const char *);
--- 19,52 ----
with groff; see the file COPYING. If not, write to the Free Software
Foundation, 51 Franklin St - Fifth Floor, Boston, MA 02110-1301, USA. */
! /* Converts a groff glyph name to a string containing an underscore-separated
! list of Unicode code points. For example,
! "-" -> "2010"
! ",c" -> "00E7"
! "fl" -> "0066_006C"
! Returns NULL if there is no equivalent. */
! const char *glyph_name_to_unicode(const char *s);
!
! /* Converts a string containing an underscore-separated list of Unicode code
! points to a groff glyph name. For example,
! "2010" -> "hy"
! "0066_006C" -> "fl"
! Returns NULL if there is no equivalent. */
! const char *unicode_to_glyph_name(const char *s);
!
! /* Converts a string containing a precomposed Unicode character to a string
! containing an underscore-separated list of Unicode code points,
representing
! its canonical decomposition. Also performs compatibility equivalent
! replacement. For example,
! "1F3A" -> "30399_0313_0300"
! "FA6A" -> "983B"
! Returns NULL if there is no equivalent. */
! const char *decompose_unicode(const char *s);
!
! /* Tests whether the string u denotes a Unicode character: "uNNNN" where
! - NNNN are at least 4 hexadecimal digits in upper case,
! - if more than 4 hexadecimal digits, not starting with a zero,
! - denoting a valid Unicode code point (U+0000..U+10FFFF, excluding
! surrogate code points).
! Returns u+1 (pointer to "NNNN") if yes, NULL otherwise. */
! const char *check_unicode_name(const char *u);
*** groff-20060113/src/include/ptable.h.bak 2005-07-07 13:16:42.000000000
+0200
--- groff-20060113/src/include/ptable.h 2006-01-17 02:33:55.000000000 +0100
***************
*** 1,5 ****
// -*- C++ -*-
! /* Copyright (C) 1989, 1990, 1991, 1992, 2003, 2004
Free Software Foundation, Inc.
Written by James Clark (address@hidden)
--- 1,5 ----
// -*- C++ -*-
! /* Copyright (C) 1989, 1990, 1991, 1992, 2003, 2004, 2006
Free Software Foundation, Inc.
Written by James Clark (address@hidden)
***************
*** 22,27 ****
--- 22,28 ----
#include <assert.h>
#include <string.h>
+ /* name2(a,b) concatenates two C identifiers. */
#ifdef TRADITIONAL_CPP
#define name2(a,b) a/**/b
#else /* not TRADITIONAL_CPP */
***************
*** 29,41 ****
#define name2x(a,b) a ## b
#endif /* not TRADITIONAL_CPP */
#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 *);
#define declare_ptable(T) \
\
struct PASSOC(T) { \
--- 30,56 ----
#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)
! /* Returns the first suitable hash table size > n. */
! extern unsigned next_ptable_size(unsigned n);
+ /* Returns a hash code of the string s.
+ The hash function is platform dependent. */
+ extern unsigned long hash_string(const char *s);
+
+ /* Declares the types 'class PTABLE(T)', 'struct PASSOC(T)',
+ 'class PTABLE_ITERATOR(T)' for the type T. */
#define declare_ptable(T) \
\
struct PASSOC(T) { \
***************
*** 50,57 ****
PTABLE(T) *p;
\
unsigned i; \
public:
\
PTABLE_ITERATOR(T)(PTABLE(T) *); \
! int next(const char **, T **); \
}; \
\
class PTABLE(T) { \
--- 65,75 ----
PTABLE(T) *p;
\
unsigned i; \
public:
\
+ /* Initializes an iterator running through the given table. */ \
PTABLE_ITERATOR(T)(PTABLE(T) *); \
! /* Fetches the next pair and stores it in *keyp and *valp and returns 1.
\
! If there is no more pair in the table, this method returns 0. */
\
! int next(const char **keyp, T **valp); \
}; \
\
class PTABLE(T) { \
***************
*** 60,69 ****
unsigned used; \
enum { FULL_NUM = 2, FULL_DEN = 3, INITIAL_SIZE = 17 }; \
public:
\
PTABLE(T)();
\
~PTABLE(T)();
\
! void define(const char *, T *); \
! T *lookup(const char *); \
friend class PTABLE_ITERATOR(T); \
};
--- 78,92 ----
unsigned used; \
enum { FULL_NUM = 2, FULL_DEN = 3, INITIAL_SIZE = 17 }; \
public:
\
+ /* Creates an empty table. */ \
PTABLE(T)();
\
+ /* Deletes a table including its values. */
\
~PTABLE(T)();
\
! /* Defines the value of the given key to be val. */
\
! void define(const char *key, T *val);
\
! /* Returns a pointer to the value of the given key, if found in the table,
\
! or NULL otherwise. */ \
! T *lookup(const char *key); \
friend class PTABLE_ITERATOR(T); \
};
***************
*** 72,77 ****
--- 95,102 ----
// Values must be allocated by the caller (always using new[], not new)
// and are freed by PTABLE.
+ /* Defines 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)()
\
*** groff-20060113/src/libs/libgroff/ptable.cpp.bak 2005-07-07
13:16:42.000000000 +0200
--- groff-20060113/src/libs/libgroff/ptable.cpp 2006-01-17 02:21:59.000000000
+0100
***************
*** 1,4 ****
! /* Copyright (C) 1989, 1990, 1991, 1992 Free Software Foundation, Inc.
Written by James Clark (address@hidden)
This file is part of groff.
--- 1,4 ----
! /* Copyright (C) 1989, 1990, 1991, 1992, 2006 Free Software Foundation, Inc.
Written by James Clark (address@hidden)
This file is part of groff.
***************
*** 23,28 ****
--- 23,30 ----
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) {
- [Groff] comments,
Bruno Haible <=