>Number:         10078
>Category:       misc
>Synopsis:       Format errors in mdoc.samples(7) man page
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    misc-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon May 08 15:26:00 PDT 2000
>Closed-Date:
>Last-Modified:
>Originator:     John Franklin
>Release:        NetBSD-current (08 May 00)
>Organization:
John Franklin
franklin@elfie.org
ICBM: N37 12'54", W80 27'14" Z+2100'
>Environment:
	
System: NetBSD elfie.org 1.3.3 NetBSD 1.3.3 (CALCIFER) #0: Wed Feb 24 18:21:08 EST 1999 franklin@elfie.perspex.com:/usr/src/sys/arch/alpha/compile/CALCIFER alpha


>Description:
	
	There are a number of format errors in the mdoc.samples(7) man
	page.  Most, if not all, of them are only noticeable if they're
	printed to a PostScript printer.

	Note that the change is to NetBSD-current as of 8-May-00, but
	the pr was sent from an older 1.3.3 machine.
>How-To-Repeat:
	
	groff -Tps -mdoc mdoc.samples.7 | lpr
	notice inconsistencies with printout.

>Fix:
	
	Apply the attached patch to fix those I noticed.


Index: mdoc.samples.7
===================================================================
RCS file: /cvsroot/sharesrc/share/man/man7/mdoc.samples.7,v
retrieving revision 1.26
diff -c -r1.26 mdoc.samples.7
*** mdoc.samples.7	2000/01/19 05:54:42	1.26
--- mdoc.samples.7	2000/05/08 22:13:29
***************
*** 611,617 ****
  .Xr troff 1
  macros are themselves a type of command;
  the general syntax for a troff command is:
! .Bd -filled -offset indent
  \&.Va argument1 argument2 ... argument9
  .Ed
  .Pp
--- 611,617 ----
  .Xr troff 1
  macros are themselves a type of command;
  the general syntax for a troff command is:
! .Bd -literal -offset indent
  \&.Va argument1 argument2 ... argument9
  .Ed
  .Pp
***************
*** 751,757 ****
  All content macros
  are capable of recognizing and properly handling punctuation,
  provided each punctuation character is separated by a leading space.
! If an request is given:
  .Pp
  .Dl \&.Li sptr, ptr),
  .Pp
--- 751,757 ----
  All content macros
  are capable of recognizing and properly handling punctuation,
  provided each punctuation character is separated by a leading space.
! If a request is given:
  .Pp
  .Dl \&.Li sptr, ptr),
  .Pp
***************
*** 1039,1045 ****
  .Ql \&.Fl
  macro is parsed and is callable.
  .Ss Functions (library routines)
! The .Fn macro is modeled on ANSI C conventions.
  .Bd -literal
  Usage: .Fn [type] function [[type] parameters ... \*(Pu]
  .Ed
--- 1039,1047 ----
  .Ql \&.Fl
  macro is parsed and is callable.
  .Ss Functions (library routines)
! The 
! .Ql \&.Fn
! macro is modeled on ANSI C conventions.
  .Bd -literal
  Usage: .Fn [type] function [[type] parameters ... \*(Pu]
  .Ed
***************
*** 1503,1516 ****
  .Bd -filled -offset indent
  .Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX
  .Em " Quote	 Close	 Open	Function	Result"
! \&.Aq	.Ac	.Ao	Angle Bracket Enclosure	<string>
! \&.Bq	.Bc	.Bo	Bracket Enclosure	[string]
! \&.Dq	.Dc	.Do	Double Quote	``string''
! 	.Ec	.Eo	Enclose String (in XX)	XXstringXX
! \&.Pq	.Pc	.Po	Parenthesis Enclosure	(string)
! \&.Ql			Quoted Literal	`st' or string
! \&.Qq	.Qc	.Qo	Straight Double Quote	"string"
! \&.Sq	.Sc	.So	Single Quote	`string'
  .El
  .Ed
  .Pp
--- 1505,1518 ----
  .Bd -filled -offset indent
  .Bl -column "quote " "close " "open " "Enclose Stringx(in XX) " XXstringXX
  .Em " Quote	 Close	 Open	Function	Result"
! .It Li ".Aq	.Ac	.Ao" Ta Angle Bracket Enclosure	<string>
! .It Li ".Bq	.Bc	.Bo" Ta Bracket Enclosure	[string]
! .It Li ".Dq	.Dc	.Do" Ta Double Quote	``string''
! .It Li "	.Ec	.Eo" Ta Enclose String (in XX)	XXstringXX
! .It Li ".Pq	.Pc	.Po" Ta Parenthesis Enclosure	(string)
! .It Li ".Ql		" Ta Quoted Literal	`st' or string
! .It Li ".Qq	.Qc	.Qo" Ta Straight Double Quote	"string"
! .It Li ".Sq	.Sc	.So" Ta Single Quote	`string'
  .El
  .Ed
  .Pp
***************
*** 1552,1558 ****
  callable,
  performs the analogous suffix function.
  .It Li ".Ap
! The \&.Ap macro inserts an apostrophe and exits any special text modes,
  continuing in
  .Li \&.No
  mode.
--- 1554,1562 ----
  callable,
  performs the analogous suffix function.
  .It Li ".Ap
! The 
! Ql \&.Ap 
! macro inserts an apostrophe and exits any special text modes,
  continuing in
  .Li \&.No
  mode.
***************
*** 1855,1861 ****
  macro can take up to nine arguments.
  It is parsed and but is not callable.
  .Bl -tag -width ".Sh SYNOPSIS"
! .It \&.Sh NAME
  The
  .Ql \&.Sh NAME
  macro is mandatory.
--- 1859,1865 ----
  macro can take up to nine arguments.
  It is parsed and but is not callable.
  .Bl -tag -width ".Sh SYNOPSIS"
! .It Li \&.Sh NAME
  The
  .Ql \&.Sh NAME
  macro is mandatory.
***************
*** 1875,1881 ****
  The
  description should be the most terse and lucid possible,
  as the space available is small.
! .It \&.Sh SYNOPSIS
  The
  .Sx SYNOPSIS
  section describes the typical usage of the
--- 1879,1885 ----
  The
  description should be the most terse and lucid possible,
  as the space available is small.
! .It Li \&.Sh SYNOPSIS
  The
  .Sx SYNOPSIS
  section describes the typical usage of the
***************
*** 1940,1946 ****
  .Sx PREDEFINED STRINGS
  for a usable \*(Ba
  character in other situations.
! .It \&.Sh DESCRIPTION
  In most cases the first text in the
  .Sx DESCRIPTION
  section
--- 1944,1950 ----
  .Sx PREDEFINED STRINGS
  for a usable \*(Ba
  character in other situations.
! .It Li \&.Sh DESCRIPTION
  In most cases the first text in the
  .Sx DESCRIPTION
  section
***************
*** 1967,1993 ****
  They are listed in the order
  in which they would be used.
  .Bl -tag -width SYNOPSIS
! .It \&.Sh ENVIRONMENT
  The
  .Sx ENVIRONMENT
  section should reveal any related
  environment
  variables and clues to their behavior and/or usage.
! .It \&.Sh EXAMPLES
  There are several ways to create examples.
  See
  the
  .Sx EXAMPLES
  section below
  for details.
! .It \&.Sh FILES
  Files which are used or created by the man page subject
  should be listed via the
  .Ql \&.Pa
  macro in the
  .Sx FILES
  section.
! .It \&.Sh SEE ALSO
  References to other material on the man page topic and
  cross references to other relevant man pages should
  be placed in the
--- 1971,1997 ----
  They are listed in the order
  in which they would be used.
  .Bl -tag -width SYNOPSIS
! .It Li \&.Sh ENVIRONMENT
  The
  .Sx ENVIRONMENT
  section should reveal any related
  environment
  variables and clues to their behavior and/or usage.
! .It Li \&.Sh EXAMPLES
  There are several ways to create examples.
  See
  the
  .Sx EXAMPLES
  section below
  for details.
! .It Li \&.Sh FILES
  Files which are used or created by the man page subject
  should be listed via the
  .Ql \&.Pa
  macro in the
  .Sx FILES
  section.
! .It Li \&.Sh SEE ALSO
  References to other material on the man page topic and
  cross references to other relevant man pages should
  be placed in the
***************
*** 2003,2009 ****
  .Pp
  It is recommended that the cross references are sorted on the section
  number, and then alphabetically on the names within a section.
! .It \&.Sh STANDARDS
  If the command, library function or file adheres to a
  specific implementation such as
  .St -p1003.2
--- 2007,2013 ----
  .Pp
  It is recommended that the cross references are sorted on the section
  number, and then alphabetically on the names within a section.
! .It Li \&.Sh STANDARDS
  If the command, library function or file adheres to a
  specific implementation such as
  .St -p1003.2
***************
*** 2015,2034 ****
  should be noted in the
  .Sx HISTORY
  section.
! .It \&.Sh HISTORY
  Any command which does not adhere to any specific standards
  should be outlined historically in this section.
! .It \&.Sh AUTHORS
  Credits, if need be, should be placed here.
! .It \&.Sh DIAGNOSTICS
  Diagnostics from a command should be placed in this section.
! .It \&.Sh ERRORS
  Specific error handling, especially from library functions
  (man page sections 2 and 3) should go here.
  The
  .Ql \&.Er
  macro is used to specify an errno.
! .It \&.Sh BUGS
  Blatant problems with the topic go here...
  .El
  .Pp
--- 2019,2038 ----
  should be noted in the
  .Sx HISTORY
  section.
! .It Li \&.Sh HISTORY
  Any command which does not adhere to any specific standards
  should be outlined historically in this section.
! .It Li \&.Sh AUTHORS
  Credits, if need be, should be placed here.
! .It Li \&.Sh DIAGNOSTICS
  Diagnostics from a command should be placed in this section.
! .It Li \&.Sh ERRORS
  Specific error handling, especially from library functions
  (man page sections 2 and 3) should go here.
  The
  .Ql \&.Er
  macro is used to specify an errno.
! .It Li \&.Sh BUGS
  Blatant problems with the topic go here...
  .El
  .Pp
***************
*** 2037,2047 ****
  sections may be added,
  for example, this section was set with:
  .Bd -literal -offset 14n
! \&.Sh PAGE LAYOUT MACROS
  .Ed
  .Ss Paragraphs and Line Spacing.
  .Bl -tag -width 6n
! .It \&.Pp
  The
  .Ql \&.Pp
  paragraph command may
--- 2041,2051 ----
  sections may be added,
  for example, this section was set with:
  .Bd -literal -offset 14n
! \&.Sh PAGE STRUCTURE DOMAIN
  .Ed
  .Ss Paragraphs and Line Spacing.
  .Bl -tag -width 6n
! .It Li \&.Pp
  The
  .Ql \&.Pp
  paragraph command may
***************
*** 2257,2263 ****
  Displays may be nested within lists, but may
  .Em not
  contain other displays; this also prohibits nesting
! of .D1 and .Dl one-line displays.
  .Ql \&.Bd
  has the following syntax:
  .Pp
--- 2261,2271 ----
  Displays may be nested within lists, but may
  .Em not
  contain other displays; this also prohibits nesting
! of 
! .Ql \&.D1
! and 
! .Ql \&.Dl
! one-line displays.
  .Ql \&.Bd
  has the following syntax:
  .Pp
***************
*** 2328,2334 ****
  .Xr troff .
  .El
  .El
! .It ".Ed"
  End-display.
  .El
  .Ss Tagged Lists and Columns
--- 2336,2342 ----
  .Xr troff .
  .El
  .El
! .It Li ".Ed"
  End-display.
  .El
  .Ss Tagged Lists and Columns
***************
*** 2468,2474 ****
  \&.Bl -inset -offset indent
  \&.It Em Tag
  \&The tagged list (also called a tagged paragraph) is the
! \&most common type of list used in the Berkeley manuals.
  \&.It Em Diag
  \&Diag lists create section four diagnostic lists
  \&and are similar to inset lists except callable
--- 2476,2484 ----
  \&.Bl -inset -offset indent
  \&.It Em Tag
  \&The tagged list (also called a tagged paragraph) is the
! \&most common type of list used in the Berkeley manuals. Use a
! \&.Fl width
! \&attribute as described below.
  \&.It Em Diag
  \&Diag lists create section four diagnostic lists
  \&and are similar to inset lists except callable
***************
*** 2770,2784 ****
  may be bogus.
  If there is only one file, it should be accurate.
  The second line gives the argument count, the argument
! .Pq Ql \&Fl
  and its length.
  If the length of an argument is two characters, the
  argument is tested to see if it is executable (unfortunately, any
  register which contains a non-zero value appears executable).
  The third line gives the space allotted for a class, and the
  class type.
! The problem here is the argument aC should not be
! executable.
  The four types of classes are string, executable, closing
  punctuation and opening punctuation.
  The last line shows the entire
--- 2780,2795 ----
  may be bogus.
  If there is only one file, it should be accurate.
  The second line gives the argument count, the argument
! .Pq Li \&Fl
  and its length.
  If the length of an argument is two characters, the
  argument is tested to see if it is executable (unfortunately, any
  register which contains a non-zero value appears executable).
  The third line gives the space allotted for a class, and the
  class type.
! The problem here is the argument 
! .Ql \&aC 
! should not be executable.
  The four types of classes are string, executable, closing
  punctuation and opening punctuation.
  The last line shows the entire
>Release-Note:
>Audit-Trail:
>Unformatted: