Markup bugs on certain gnuchess manual pages

[Eric S. Raymond]

I'm working on a program that automatically translates manual page sources
to DocBook markup.  You can find out more about this program at 

        http://www.tuxedo.org/~esr/doclifter/

If you are not already considering it, please think about moving your
documentation masters to DocBook (or some format from which you can
generate DocBook).  Tools to generate man pages (docbook2man) HTML
(docbook2html) and PostScript (docbook2ps) from DocBook files are
open source and generally available.  My program, doclifter, should
make moving your masters to DocBook a pretty painless process.

Many major open source projects (including the Linux Documentation
Project, GNOME, KDE, and FreeBSD) have moved to DocBook or are in the
process of doing so.  The format has many advantages over man, info,
texinfo, or HTML; by moving everybody to it, we should be able to
support unified browsing of all system documentation with Web-like 
hypertext capabilities, automatic indexing, and rich search facilities.

In the process of debugging doclifter, I have discovered many bugs in 
man page layout.  These are significant because they make automated
translation to DocBook more difficult, and often confuse other document-
mining tools (such as indexers).

I have found some markup bugs on a manual page you maintain.
Please fix these in your next release.

--- postprint.6 2002/07/19 13:40:53     1.1
+++ postprint.6 2002/07/19 13:43:13
@@ -1,6 +1,6 @@
 .TH POSTPRINT GNUCHESS
 .SH NAME
-postprint
+postprint \- render Postscript from a gnuchess persistent hashfile
 .SH SYNOPSIS
 .B postprint
 filename
@@ -23,22 +23,18 @@
 .B ChessFont
 is courtesy of Andy Walker, Maths Dept., Nott'm Univ., UK. <address@hidden> 
 and is copyrighted by him. 
-
+.PP
 To use:
+.sp
+.nf
+.ft B
+       postprint >tmp
 
-.B     postprint >tmp
-
-.B     cat ChessFont tmp | lpr
-
-.SH "FUNCTION LETTERS"
-.TP
-.SH BUGS
-.PP
+       cat ChessFont tmp | lpr
+.ft R
 .fi
 .SH SEE ALSO
-.nf
-gnuchess(6)
-chesstool(6)
-xboard(6)
-.fi
+.IR gnuchess(6),
+.IR chesstool(6),
+.IR xboard(6).
 
--- game.6      2002/07/19 13:45:07     1.1
+++ game.6      2002/07/19 13:47:25
@@ -1,14 +1,12 @@
 .TH GAME GNUCHESS
 .SH NAME
-game
+game \- make Postscript from gnuchess chess.lst file
 .SH SYNOPSIS
 .B game
-[start [end]]
-filename
-]
+[[start [end]] filename]
 .SH DESCRIPTION
 .I game
-creates a board by board postscript output file on stdout for all or part of a 
chess game.
+creates a board by board Postscript output file on stdout for all or part of a 
chess game.
 Input is a 'chess.lst' file output by
 .I gnuchess.
 When combined with the 
@@ -16,30 +14,27 @@
 file and sent to a postscript printer it will show all boards in the range 
specified.
 For each board the move and the current score are also printed.
 .B ChessFont
-is courtesy of Andy Walker, Maths Dept., Nott'm Univ., UK. (address@hidden) 
+is courtesy of Andy Walker, Maths Dept., Nott'm Univ., UK. <address@hidden> 
 and is copyrighted by him. 
-
+.PP
 Moves starting at 
 .I start
 and ending with 
 .I end
 are printed. If no start or end is given all moves are shown. If only 1 number 
is given it is assumed to be the start.
-
+.PP
 To use:
+.sp
+.nf
+.ft B
+       game gamefile >tmp
 
-.B     game gamefile >tmp
-
-.B     cat ChessFont tmp | lpr
-
-.SH "FUNCTION LETTERS"
-.TP
-.SH BUGS
-.PP
+       cat ChessFont tmp | lpr
+.ft R
 .fi
 .SH SEE ALSO
-.nf
-gnuchess(6)
-chesstool(6)
-xboard(6)
-.fi
+.IR gnuchess(6),
+.IR chesstool(6),
+.IR xboard(6).
+

--- gnuchess.6  2002/07/19 13:53:47     1.1
+++ gnuchess.6  2002/07/19 13:54:06
@@ -483,12 +483,8 @@
 .B xwndw
 -- change X window. The window around alpha/beta used to determine whether the 
position
 should be scored or just estimated.
-.SH BUGS
-.PP
-.fi
 .SH SEE ALSO
-.nf
-chesstool(6)
-xboard(6)
-.fi
+.IR chesstool(6),
+.IR xboard(6).
+
  
--- gnuan.6     2002/07/19 13:49:00     1.1
+++ gnuan.6     2002/07/19 13:50:32
@@ -1,15 +1,15 @@
 .TH GNUAN GNUCHESS
 .SH NAME
-gnuan
+gnuan \- analyze a chess game
 .SH SYNOPSIS
 .B gnuan
 .SH DESCRIPTION
 .I gnuan
 produces an analysis of a chess game.
-For each move it shows the move, the score and the principle variation selected
+For each move it shows the move, the score and the principal variation selected
 by
 .I gnuchess
-
+.PP
 .I gnuan
 prompts for input parameters when it is invoked.
 Input file is a
@@ -19,9 +19,9 @@
 game file or a
 .I PGN
 file.
-
+.PP
 .I gnuan is a modification of the gnuan program from
-Truman Collins (address@hidden).
+Truman Collins <address@hidden>.
 .SH "FUNCTION LETTERS"
 The following commands are recognized:
 .PP
@@ -52,17 +52,11 @@
 .PP
 .B go
 -- advance 1 ply.
-
+.PP
 To emulate the old gnuan just type a number > number of moves at the command 
prompt. The moves
 will be examined til the end of the game.
-
-.SH BUGS
-.PP
-.fi
 .SH SEE ALSO
-.nf
-gnuchess(6)
-chesstool(6)
-xboard(6)
-.fi
+.IR gnuchess (6),
+.IR chesstool (6),
+.IR xboard (6).
 
-- 
                <a href="http://www.tuxedo.org/~esr/";>Eric S. Raymond</a>

The biggest hypocrites on gun control are those who live in upscale
developments with armed security guards -- and who want to keep other
people from having guns to defend themselves.  But what about
lower-income people living in high-crime, inner city neighborhoods?
Should such people be kept unarmed and helpless, so that limousine
liberals can 'make a statement' by adding to the thousands of gun laws
already on the books?"
        --Thomas Sowell