[sane-devel] bad markup in sane-artec.5, sane-agfafocus.5

Eric S. Raymond esr@snark.thyrsus.com
Fri, 10 Dec 2004 14:11:45 -0500


I found these while adding a parsing feature to my conversion script.
They are ndw patches, not previously sent to this list.

Problems with sane-artec.5 and sane-agfafocus.5:

1. Unknown or invalid macro .DS.  It's not available in the Linux or 
   basic Unix man macro set.

2. Unclosed .DS; it needs a closing .DE in manual markup extensions
   where it is valid (such as the Ultrix macros).

3. List structure should be expressed rather than simulated with .br.

4. Program listings should be wrapped so a semantic translator can
   recognize them, not simulated with .br.

--- xmlman/sane-artec.5-orig	2004-12-10 13:54:55.898615816 -0500
+++ xmlman/sane-artec.5	2004-12-10 13:59:16.370018144 -0500
@@ -12,22 +12,22 @@
 the following scanners are known to work at least partially with this backend:
 .PP
 .RS
+.IP *
 Artec A6000C
-.br
+.IP *
 Artec A6000C PLUS
-.br
+.IP *
 Artec ViewStation AT3
-.br
+.IP *
 BlackWidow BW4800SP (rebadged Artec AT3)
-.br
+.IP *
 Artec ViewStation AT6
-.br
+.IP *
 Artec ViewStation AT12
-.br
+.IP *
 Artec AM12S
-.br
+.IP *
 Plustek 19200S (rebadged Artec AM12S)
-.br
 .RE
 .PP
 Although this manual page is generally updated with each release,
@@ -51,65 +51,39 @@
 hash mark (#) are ignored.  See
 .I sane-scsi(5)
 on details of what constitutes a valid device name.
-.br
+
 Sample file:
 .br
 .br
+.nf
 # artec.conf
-.br
 #
-.br
 # this is a comment.
-.br
 #
-.br
 # this line says search for any SCSI devices which are scanners and have
-.br
 #     a vendor string of 'ULTIMA'
-.br
 scsi ULTIMA
-.br
 #
-.br
 # the next line forces the backend to assume the next scanner found has
-.br
 #     the specified vendor string (useful for testing rebadged models).
-.br
 vendor ULTIMA
-.br
 #
-.br
 # the next line forces the backend to assume the next scanner found has
-.br
 #     the specified model string (useful for testing rebadged models).
-.br
 model AT3
-.br
 #
-.br
 # now a line that actually specifies a device.  The backend is going to
-.br
 #     assume this is an Artec/Ultima AT3 because we forced the vendor and
-.br
 #     model above.
-.br
 /dev/scanner
-.br
 #
-.br
 # once we hit a scanner device line, the forced vendor and model
-.br
 # string are
-.br
 #     'forgotten', so the vendor and model for this next device will be
-.br
 #     determined from the result of a SCSI inquiry.
-.br
 /dev/sge
-.br
 #
-.br
-.br
+.fi
 
 .SH SCSI ADAPTER TIPS
 
@@ -155,8 +129,7 @@
 variable controls the debug level for this backend. E.g., a value of 128
 requests all debug output to be printed. Smaller levels reduce verbosity:
 SANE_DEBUG_ARTEC values
-.DS
-.sp
+
 .ft CR
 .nf
  Number  Remark
@@ -181,7 +154,9 @@
  == 101  print raw data from scanner to artec.data.raw file
 
  == 128  print out all messages
-
+.fi
+.ft R
+.PP
 Example:
 export SANE_DEBUG_ARTEC=13
 
-----------------------------
--- xmlman/sane-artec.5-orig	2004-12-10 13:54:55.898615816 -0500
+++ xmlman/sane-artec.5	2004-12-10 13:59:16.370018144 -0500
@@ -12,22 +12,22 @@
 the following scanners are known to work at least partially with this backend:
 .PP
 .RS
+.IP *
 Artec A6000C
-.br
+.IP *
 Artec A6000C PLUS
-.br
+.IP *
 Artec ViewStation AT3
-.br
+.IP *
 BlackWidow BW4800SP (rebadged Artec AT3)
-.br
+.IP *
 Artec ViewStation AT6
-.br
+.IP *
 Artec ViewStation AT12
-.br
+.IP *
 Artec AM12S
-.br
+.IP *
 Plustek 19200S (rebadged Artec AM12S)
-.br
 .RE
 .PP
 Although this manual page is generally updated with each release,
@@ -51,65 +51,39 @@
 hash mark (#) are ignored.  See
 .I sane-scsi(5)
 on details of what constitutes a valid device name.
-.br
+
 Sample file:
 .br
 .br
+.nf
 # artec.conf
-.br
 #
-.br
 # this is a comment.
-.br
 #
-.br
 # this line says search for any SCSI devices which are scanners and have
-.br
 #     a vendor string of 'ULTIMA'
-.br
 scsi ULTIMA
-.br
 #
-.br
 # the next line forces the backend to assume the next scanner found has
-.br
 #     the specified vendor string (useful for testing rebadged models).
-.br
 vendor ULTIMA
-.br
 #
-.br
 # the next line forces the backend to assume the next scanner found has
-.br
 #     the specified model string (useful for testing rebadged models).
-.br
 model AT3
-.br
 #
-.br
 # now a line that actually specifies a device.  The backend is going to
-.br
 #     assume this is an Artec/Ultima AT3 because we forced the vendor and
-.br
 #     model above.
-.br
 /dev/scanner
-.br
 #
-.br
 # once we hit a scanner device line, the forced vendor and model
-.br
 # string are
-.br
 #     'forgotten', so the vendor and model for this next device will be
-.br
 #     determined from the result of a SCSI inquiry.
-.br
 /dev/sge
-.br
 #
-.br
-.br
+.fi
 
 .SH SCSI ADAPTER TIPS
 
@@ -155,8 +129,7 @@
 variable controls the debug level for this backend. E.g., a value of 128
 requests all debug output to be printed. Smaller levels reduce verbosity:
 SANE_DEBUG_ARTEC values
-.DS
-.sp
+
 .ft CR
 .nf
  Number  Remark
@@ -181,7 +154,9 @@
  == 101  print raw data from scanner to artec.data.raw file
 
  == 128  print out all messages
-
+.fi
+.ft R
+.PP
 Example:
 export SANE_DEBUG_ARTEC=13
 
-----------------------------
--- xmlman/sane-agfafocus.5-orig	2004-12-10 14:02:02.578750576 -0500
+++ xmlman/sane-agfafocus.5	2004-12-10 14:02:42.483684104 -0500
@@ -107,7 +107,6 @@
 requests all debug output to be printed. Smaller levels reduce verbosity.
 SANE_DEBUG_AGFAFOCUS values:
 
-.DS
 .sp 
 .ft CR
 .nf
@@ -126,6 +125,8 @@
  11      print called sane-procedures
  12      print sane infos
  13      print sane option-control messages
+.fi
+.ft R
 
 .SH MISSING FUNCTIONALITY
 
-----------------------------

-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

The only purpose for which power can be rightfully exercised over any
member of a civilized community, against his will, is to prevent harm
to others. His own good, either physical or moral, is not a sufficient
warrant.	-- John Stuart Mill, "On Liberty", 1859