Hi Anthony, Anthony J. Bentley wrote on Sun, Feb 15, 2015 at 06:16:11AM -0700: > "Anthony J. Bentley" writes: >> "Ted Unangst" writes:
>>> spamd(8) quotes the <spamd> pf table name. That's in normal text, so it doesn't really matter, nobody is going to copy and paste a single word out of the middle of the text. But i don't to just writing "the <spamd-white> table" either. >>> compress(3) quotes the <zconf.h> path. >> IMO, these are bugs in the manuals. spamd(8) should be using <> directly. >> compress(3) should drop the angle quotes and just use Pa. Or wrap Pa in >> <> if people really think it's needed. > Replying to myself, there's already a simpler and more semantic macro > for include files: "In". mdoc(7) only seems to document its usage in > SYNOPSIS, but that could just be unclear wording. I just committed a patch to mdoc.7 to avoid that misconception. > It is already widely used in non-SYNOPSIS situations. Indeed, .In is fine everywhere. > ok? OK schwarze@ on the patch below. Yours, Ingo > Index: lib/libarch/i386/i386_get_ldt.2 > =================================================================== > RCS file: /cvs/src/lib/libarch/i386/i386_get_ldt.2,v > retrieving revision 1.16 > diff -u -p -u -p -r1.16 i386_get_ldt.2 > --- lib/libarch/i386/i386_get_ldt.2 31 May 2007 19:19:27 -0000 1.16 > +++ lib/libarch/i386/i386_get_ldt.2 15 Feb 2015 12:52:50 -0000 > @@ -64,7 +64,7 @@ Each entry in the > .Fa descs > array can be either a segment_descriptor or a gate_descriptor, > as defined in > -.Aq Pa i386/segments.h . > +.In i386/segments.h . > These structures are defined by the architecture > as disjoint bit-fields, so care must be taken in constructing them. > .Pp > Index: lib/libz/compress.3 > =================================================================== > RCS file: /cvs/src/lib/libz/compress.3,v > retrieving revision 1.14 > diff -u -p -u -p -r1.14 compress.3 > --- lib/libz/compress.3 16 Jul 2013 15:21:11 -0000 1.14 > +++ lib/libz/compress.3 15 Feb 2015 12:52:50 -0000 > @@ -229,7 +229,7 @@ and > for consistency. > If the first character differs, the library code actually used is > not compatible with the > -.Aq Pa zlib.h > +.In zlib.h > header file used by the application. > This check is automatically made by > .Fn deflateInit > @@ -889,7 +889,7 @@ memLevel=1 uses minimum memory but is sl > memLevel=9 uses maximum memory for optimal speed. > The default value is 8. > See > -.Aq Pa zconf.h > +.In zconf.h > for total memory usage as a function of > .Fa windowBits > and > @@ -2588,7 +2588,7 @@ and > must be able to allocate exactly 65536 bytes, > but will not be required to allocate more than this if the symbol MAXSEG_64K > is defined (see > -.Aq Pa zconf.h ) . > +.In zconf.h ) . > .Pp > WARNING: On MSDOS, pointers returned by > .Fa zalloc > @@ -2598,7 +2598,7 @@ The default allocation function provided > To reduce memory requirements and avoid any allocation of 64K objects, > at the expense of compression ratio, > compile the library with -DMAX_WBITS=14 (see > -.Aq Pa zconf.h ) . > +.In zconf.h ) . > .Pp > The fields > .Fa total_in > @@ -2739,7 +2739,7 @@ version and the compiler's view of > .Re > .Sh HISTORY > This manual page is based on an HTML version of > -.Aq Pa zlib.h > +.In zlib.h > converted by > .An piaip Aq Mt [email protected] > and was converted to mdoc format by the > Index: sbin/pflogd/pflogd.8 > =================================================================== > RCS file: /cvs/src/sbin/pflogd/pflogd.8,v > retrieving revision 1.46 > diff -u -p -u -p -r1.46 pflogd.8 > --- sbin/pflogd/pflogd.8 21 Jan 2014 03:15:45 -0000 1.46 > +++ sbin/pflogd/pflogd.8 15 Feb 2015 12:52:50 -0000 > @@ -137,7 +137,7 @@ Selects which packets will be dumped, us > .Xr tcpdump 8 . > Tcpdump has been extended to be able to filter on the pfloghdr > structure defined in > -.Aq Ar net/if_pflog.h . > +.In net/if_pflog.h . > It can restrict the output > to packets logged on a specified interface, a rule number, a reason, > a direction, an IP family or an action. > Index: share/man/man4/speaker.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/speaker.4,v > retrieving revision 1.7 > diff -u -p -u -p -r1.7 speaker.4 > --- share/man/man4/speaker.4 16 Jul 2013 16:05:49 -0000 1.7 > +++ share/man/man4/speaker.4 15 Feb 2015 12:52:50 -0000 > @@ -72,7 +72,7 @@ on a speaker file descriptor to control > definitions for the > .Fn ioctl > interface are in > -.Aq Pa dev/isa/spkrio.h . > +.In dev/isa/spkrio.h . > The > .Li tone_t > structure used in these calls has two fields, > Index: share/man/man4/usb.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/usb.4,v > retrieving revision 1.162 > diff -u -p -u -p -r1.162 usb.4 > --- share/man/man4/usb.4 6 Feb 2015 23:46:30 -0000 1.162 > +++ share/man/man4/usb.4 15 Feb 2015 12:52:50 -0000 > @@ -651,7 +651,7 @@ field contains the actual length transfe > .El > .Pp > The include file > -.Aq Pa dev/usb/usb.h > +.In dev/usb/usb.h > contains definitions for the types used by the various > .Xr ioctl 2 > calls. > @@ -672,7 +672,7 @@ and > macros to handle byte order and alignment properly. > .Pp > The include file > -.Aq Pa dev/usb/usbhid.h > +.In dev/usb/usbhid.h > similarly contains the definitions for > Human Interface Devices > .Pq Tn HID . > Index: share/man/man4/wsdisplay.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/wsdisplay.4,v > retrieving revision 1.46 > diff -u -p -u -p -r1.46 wsdisplay.4 > --- share/man/man4/wsdisplay.4 28 Aug 2010 22:09:49 -0000 1.46 > +++ share/man/man4/wsdisplay.4 15 Feb 2015 12:52:50 -0000 > @@ -142,12 +142,12 @@ calls are provided by the > .Nm > driver or by devices which use it. > Their definitions are found in > -.Aq Pa dev/wscons/wsconsio.h . > +.In dev/wscons/wsconsio.h . > .Bl -tag -width 4n > .It Dv WSDISPLAYIO_GTYPE Pq Li u_int > Retrieve the type of the display. > The list of types is in > -.Aq Pa dev/wscons/wsconsio.h . > +.In dev/wscons/wsconsio.h . > .It Dv WSDISPLAYIO_GINFO Pq Li "struct wsdisplay_fbinfo" > Retrieve basic information about a framebuffer display. > The returned structure is as follows: > Index: share/man/man4/man4.luna88k/lcd.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/man4.luna88k/lcd.4,v > retrieving revision 1.3 > diff -u -p -u -p -r1.3 lcd.4 > --- share/man/man4/man4.luna88k/lcd.4 22 Apr 2014 22:58:02 -0000 1.3 > +++ share/man/man4/man4.luna88k/lcd.4 15 Feb 2015 12:52:50 -0000 > @@ -67,7 +67,7 @@ Restore boot-time LCD message. > .El > .Pp > These ioctl parameters are defined in > -.Aq Ar machine/lcd.h . > +.In machine/lcd.h . > .Sh FILES > .Bl -tag -width /dev/lcd > .It Pa /dev/lcd > Index: share/man/man4/man4.sparc/fga.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/man4.sparc/fga.4,v > retrieving revision 1.13 > diff -u -p -u -p -r1.13 fga.4 > --- share/man/man4/man4.sparc/fga.4 16 Jul 2013 16:05:49 -0000 1.13 > +++ share/man/man4/man4.sparc/fga.4 15 Feb 2015 12:52:50 -0000 > @@ -79,7 +79,7 @@ The > device responds to the following > .Xr ioctl 2 > calls defined in > -.Aq Pa machine/fgaio.h : > +.In machine/fgaio.h : > .Bl -tag -width FGAIOCSEM > .It Dv FGAIOCSEM > .Pq Li "struct fga_sem" > Index: share/man/man4/man4.sparc64/uperf.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/man4.sparc64/uperf.4,v > retrieving revision 1.16 > diff -u -p -u -p -r1.16 uperf.4 > --- share/man/man4/man4.sparc64/uperf.4 16 Jul 2013 16:05:50 -0000 > 1.16 > +++ share/man/man4/man4.sparc64/uperf.4 15 Feb 2015 12:52:50 -0000 > @@ -190,7 +190,7 @@ The > device responds to the following > .Xr ioctl 2 > calls, which are defined in > -.Aq Pa dev/sun/uperfio.h . > +.In dev/sun/uperfio.h . > .Bl -tag -width UPIO_GCNTSRC > .It Dv UPIO_GCNTSRC > .Pq Li "struct uperf_io" > Index: share/man/man4/man4.vax/mtc.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/man4.vax/mtc.4,v > retrieving revision 1.7 > diff -u -p -u -p -r1.7 mtc.4 > --- share/man/man4/man4.vax/mtc.4 31 May 2007 19:19:57 -0000 1.7 > +++ share/man/man4/man4.vax/mtc.4 15 Feb 2015 12:52:50 -0000 > @@ -59,7 +59,7 @@ communicates with the host through > a packet protocol known as the Mass Storage Control Protocol > .Pq Tn MSCP . > Consult the file > -.Aq Pa mscp/mscp.h > +.In mscp/mscp.h > for a detailed description of this protocol. > .Sh SEE ALSO > .Xr intro 4 , > Index: share/man/man4/man4.vax/ra.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/man4.vax/ra.4,v > retrieving revision 1.10 > diff -u -p -u -p -r1.10 ra.4 > --- share/man/man4/man4.vax/ra.4 2 Jun 2013 20:42:27 -0000 1.10 > +++ share/man/man4/man4.vax/ra.4 15 Feb 2015 12:52:50 -0000 > @@ -84,7 +84,7 @@ A drive somehow changed from one kind to > to an > .Tn RA60 . > The numbers printed are the encoded media identifiers (see > -.Aq Pa vax/mscp.h > +.In vax/mscp.h > for the encoding). > The driver believes the new type. > .It "ra0: uda0, unit N, size = N sectors" > Index: share/man/man4/man4.vax/uda.4 > =================================================================== > RCS file: /cvs/src/share/man/man4/man4.vax/uda.4,v > retrieving revision 1.22 > diff -u -p -u -p -r1.22 uda.4 > --- share/man/man4/man4.vax/uda.4 15 Nov 2014 14:41:02 -0000 1.22 > +++ share/man/man4/man4.vax/uda.4 15 Feb 2015 12:52:50 -0000 > @@ -53,7 +53,7 @@ communicates with the host through > a packet protocol known as the Mass Storage Control Protocol > .Pq Tn MSCP . > Consult the file > -.Aq Pa vax/mscp.h > +.In vax/mscp.h > for a detailed description of this protocol. > .Pp > The > Index: share/man/man5/fs.5 > =================================================================== > RCS file: /cvs/src/share/man/man5/fs.5,v > retrieving revision 1.17 > diff -u -p -u -p -r1.17 fs.5 > --- share/man/man5/fs.5 29 May 2014 12:02:50 -0000 1.17 > +++ share/man/man5/fs.5 15 Feb 2015 12:52:50 -0000 > @@ -43,9 +43,9 @@ > .Fd #include <ufs/ufs/inode.h> > .Sh DESCRIPTION > The files > -.Aq Pa ufs/ffs/fs.h > +.In ufs/ffs/fs.h > and > -.Aq Pa ufs/ufs/inode.h > +.In ufs/ufs/inode.h > declare several structures and define variables and macros > which are used to create and manage the underlying format of > file system objects on random access devices (disks). > @@ -68,7 +68,7 @@ that is of size > .Dv SBSIZE . > The following structure describes the super-block and is > from the file > -.Aq Pa ufs/ffs/fs.h : > +.In ufs/ffs/fs.h : > .Bd -literal > #define FS_MAGIC 0x011954 > struct fs { > @@ -374,7 +374,7 @@ An inode is > .Dq named > by its device/i-number pair. > For further information, see the include file > -.Aq Pa ufs/ufs/inode.h . > +.In ufs/ufs/inode.h . > .Sh HISTORY > A super-block structure named > .Em filsys > Index: share/man/man9/ktrace.9 > =================================================================== > RCS file: /cvs/src/share/man/man9/ktrace.9,v > retrieving revision 1.8 > diff -u -p -u -p -r1.8 ktrace.9 > --- share/man/man9/ktrace.9 14 Aug 2013 06:32:32 -0000 1.8 > +++ share/man/man9/ktrace.9 15 Feb 2015 12:52:50 -0000 > @@ -138,7 +138,7 @@ is the current traced process' signal ma > Signal-specific code and > .Em siginfo_t > structure as described in > -.Aq Pa sys/siginfo.h > +.In sys/siginfo.h > are given in the > .Fa code > and > Index: share/man/man9/pci_conf_read.9 > =================================================================== > RCS file: /cvs/src/share/man/man9/pci_conf_read.9,v > retrieving revision 1.11 > diff -u -p -u -p -r1.11 pci_conf_read.9 > --- share/man/man9/pci_conf_read.9 4 Jun 2013 19:27:10 -0000 1.11 > +++ share/man/man9/pci_conf_read.9 15 Feb 2015 12:52:50 -0000 > @@ -44,7 +44,7 @@ > These functions provide a way to access PCI configuration space. > .Pp > The following types are defined in the machine dependent include file > -.Aq Pa pci_machdep.h . > +.In pci_machdep.h . > .Pp > .Bl -tag -width pci_chipset_tag_t -offset indent -compact > .It pci_chipset_tag_t > Index: usr.bin/file/file.1 > =================================================================== > RCS file: /cvs/src/usr.bin/file/file.1,v > retrieving revision 1.34 > diff -u -p -u -p -r1.34 file.1 > --- usr.bin/file/file.1 17 Jan 2013 21:29:14 -0000 1.34 > +++ usr.bin/file/file.1 15 Feb 2015 12:52:50 -0000 > @@ -91,16 +91,16 @@ Any known file types, > such as sockets, symbolic links, and named pipes (FIFOs), > are intuited if they are defined in > the system header file > -.Aq Pa sys/stat.h . > +.In sys/stat.h . > .Pp > The magic tests are used to check for files with data in > particular fixed formats. > The canonical example of this is a binary executable (compiled program) > a.out file, whose format is defined in > -.Aq Pa elf.h , > -.Aq Pa a.out.h , > +.In elf.h , > +.In a.out.h , > and possibly > -.Aq Pa exec.h > +.In exec.h > in the standard include directory. > These files have a > .Dq magic number > @@ -154,7 +154,7 @@ has determined the character set used in > it will > attempt to determine in what language the file is written. > The language tests look for particular strings (cf.\& > -.Aq Pa names.h ) > +.In names.h ) > that can appear anywhere in the first few blocks of a file. > For example, the keyword > .Em .br > Index: usr.bin/lex/flex.1 > =================================================================== > RCS file: /cvs/src/usr.bin/lex/flex.1,v > retrieving revision 1.37 > diff -u -p -u -p -r1.37 flex.1 > --- usr.bin/lex/flex.1 23 Mar 2014 16:28:29 -0000 1.37 > +++ usr.bin/lex/flex.1 15 Feb 2015 12:52:50 -0000 > @@ -3460,7 +3460,7 @@ defaults to generating the scanner to th > instead of > .Pa lex.yy.c . > The generated scanner includes the header file > -.Aq Pa g++/FlexLexer.h , > +.In g++/FlexLexer.h , > which defines the interface to two C++ classes. > .Pp > The first class, > @@ -3510,7 +3510,7 @@ and > object pointer). > .Pp > The second class defined in > -.Aq Pa g++/FlexLexer.h > +.In g++/FlexLexer.h > is > .Fa yyFlexLexer , > which is derived from > @@ -3707,7 +3707,7 @@ to rename each > .Fa yyFlexLexer > to some other > .Fa xxFlexLexer . > -.Aq Pa g++/FlexLexer.h > +.In g++/FlexLexer.h > can then be included in other sources once per lexer class, first renaming > .Fa yyFlexLexer > as follows: > @@ -4109,7 +4109,7 @@ on some systems). > .It lex.yy.cc > Generated C++ scanner class, when using > .Fl + . > -.It Aq g++/FlexLexer.h > +.It In g++/FlexLexer.h > Header file defining the C++ scanner base class, > .Fa FlexLexer , > and its derived class, > @@ -4394,7 +4394,7 @@ token. > .Pp > Due to both buffering of input and read-ahead, > it is not possible to intermix calls to > -.Aq Pa stdio.h > +.In stdio.h > routines, such as, for example, > .Fn getchar , > with > Index: usr.bin/openssl/openssl.1 > =================================================================== > RCS file: /cvs/src/usr.bin/openssl/openssl.1,v > retrieving revision 1.11 > diff -u -p -u -p -r1.11 openssl.1 > --- usr.bin/openssl/openssl.1 13 Jan 2015 14:09:54 -0000 1.11 > +++ usr.bin/openssl/openssl.1 15 Feb 2015 12:52:51 -0000 > @@ -9008,7 +9008,7 @@ Finally a text version of the error numb > .Pp > An exhaustive list of the error codes and messages is shown below; this also > includes the name of the error code as defined in the header file > -.Aq Pa openssl/x509_vfy.h . > +.In openssl/x509_vfy.h . > Some of the error codes are defined but never returned: these are described > as > .Qq unused . >
