Re: Aq macro replacements
Hi Christian, Christian Heckendorf wrote on Sun, Mar 27, 2016 at 11:03:02PM -0400: > - spamd-setup(8) is referring to pf tables. syslogd(8) and tcpdump(8) >use Aq to format program I/O examples. None of these instances use >mathematical unicode symbols in practice. Fixed differently. I committed your other four patches unchanged. Thanks, Ingo > [1] http://marc.info/?l=openbsd-tech=142399113828201=2
Re: Aq macro
Anthony J. Bentley wrote: Ted Unangst writes: The mandoc chars.in though says that for unicode, it should output these fanc y mathematical left angle bracket and mathematical right angle bracket characters. Two problems. First, they look like kind of silly because most fonts use a different glyph. Well, if it's a matter of aesthetics, I happen to like it. So we're at an impasse! More importantly, though, it matches groff. I don't think it can (or should) change. When this behavior was added to mandoc, several pages using Aq to represent HTML tags were fixed. These pages were just overlooked. Here is a patch that corrects spamd(8). I can look at pages that use it for headers later... a quick grep reveals less than 20. Ah, well, fixed is fixed. :) pf.conf also appears to be a big offender.
Re: Aq macro
Anthony J. Bentley writes: Ted Unangst writes: spamd(8) quotes the spamd pf table name. 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. It is already widely used in non-SYNOPSIS situations. ok? 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 - 1.16 +++ lib/libarch/i386/i386_get_ldt.2 15 Feb 2015 12:52:50 - @@ -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 - 1.14 +++ lib/libz/compress.3 15 Feb 2015 12:52:50 - @@ -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 pi...@csie.ntu.edu.tw 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.821 Jan 2014 03:15:45 - 1.46 +++ sbin/pflogd/pflogd.815 Feb 2015 12:52:50 - @@ -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.416 Jul 2013 16:05:49 - 1.7 +++ share/man/man4/speaker.415 Feb 2015 12:52:50 - @@ -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.46 Feb 2015 23:46:30 - 1.162 +++ share/man/man4/usb.415 Feb 2015 12:52:50 - @@ -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
Re: Aq macro
Hi Christian, Christian Weisgerber wrote on Sun, Feb 15, 2015 at 04:04:57PM +: On 2015-02-15, Ted Unangst t...@tedunangst.com wrote: mandoc already special cases Aq in Mt macros to output plain brackets. Existing usage suggests that's what people want elsewhere as well. I'm not sure i can absolutely exclude that, but i don't remember having seen convincing use of .Aq without .Mt that needs ASCII either. So for now, let's just fix the bad .Aq usage that was found. If good usage needing ASCII is found, we can reconsider. pf tables and include.h headers are not math equations either. I think these manuals should use actual instead of the Aq macro. pf.conf(5) should use plain for tables. include.h should always use .In. There are related problems in some man pages like pf.conf(5) where = is turned into a fancy mathematical sign etc. I wanted to clean up some of those, but wasn't sure what the correct fix was, failed to get a straight answer out of schwarze@ and jmc@, and then sort of forgot... Oops, sorry, that mail fell through the cracks, you just got a late answer. It boils down to never use \*(Lt \*(Le \*(Gt \*(Ge. Usually, you don't need any \* whatsoever. Yours, Ingo
Re: Aq macro
Hi Anthony, Anthony J. Bentley wrote on Sun, Feb 15, 2015 at 03:19:48AM -0700: More importantly, though, it matches groff. Yes. We shouldn't change mandoc(1) without changing groff(1) in parallel. Here is a patch that corrects spamd(8). I can look at pages that use it for headers later... a quick grep reveals less than 20. OK schwarze@ for the patch below. Ingo Index: libexec/spamd/spamd.8 === RCS file: /cvs/src/libexec/spamd/spamd.8,v retrieving revision 1.125 diff -u -p -u -p -r1.125 spamd.8 --- libexec/spamd/spamd.8 7 Feb 2015 18:05:57 - 1.125 +++ libexec/spamd/spamd.8 15 Feb 2015 10:17:38 - @@ -268,11 +268,11 @@ regularly scans the .Pa /var/db/spamd database and configures all whitelist addresses as the .Xr pf 4 -.Aq spamd-white +spamd-white table, allowing connections to pass to the real MTA. Any addresses not found in -.Aq spamd-white +spamd-white are redirected to .Nm . .Pp @@ -385,7 +385,7 @@ spamtrap address, it is blacklisted for 24 hours by adding the host to the .Nm blacklist -.Aq spamd-greytrap . +spamd-greytrap. Spamtrap addresses are added to the .Pa /var/db/spamd database with the following @@ -468,7 +468,7 @@ a slightly modified .Xr pf.conf 5 ruleset is required, redirecting any addresses found in the -.Aq spamd +spamd table to .Nm . Any other addresses @@ -488,7 +488,7 @@ like: .Pp .Xr spamd-setup 8 can also be used to load addresses into the -.Aq spamd +spamd table. It has the added benefit of being able to remove addresses from blacklists, and will connect to
Re: Aq macro
On 2015-02-15, Ted Unangst t...@tedunangst.com wrote: mandoc already special cases Aq in Mt macros to output plain brackets. Existing usage suggests that's what people want elsewhere as well. pf tables and include.h headers are not math equations either. I think these manuals should use actual instead of the Aq macro. There are related problems in some man pages like pf.conf(5) where = is turned into a fancy mathematical sign etc. I wanted to clean up some of those, but wasn't sure what the correct fix was, failed to get a straight answer out of schwarze@ and jmc@, and then sort of forgot... -- Christian naddy Weisgerber na...@mips.inka.de
Re: Aq macro
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 - 1.16 +++ lib/libarch/i386/i386_get_ldt.2 15 Feb 2015 12:52:50 - @@ -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 - 1.14 +++ lib/libz/compress.3 15 Feb 2015 12:52:50 - @@ -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 pi...@csie.ntu.edu.tw 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 - 1.46 +++ sbin/pflogd/pflogd.8 15 Feb 2015 12:52:50 - @@ -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 - 1.7 +++ share/man/man4/speaker.4 15 Feb 2015 12:52:50 - @@ -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 - 1.162 +++ share/man/man4/usb.4 15 Feb 2015 12:52:50 - @@ -651,7 +651,7 @@ field contains the actual length transfe .El .Pp The include file -.Aq
Re: Aq macro
Ted Unangst writes: spamd(8) quotes the spamd pf table name. 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. The mandoc chars.in though says that for unicode, it should output these fanc y mathematical left angle bracket and mathematical right angle bracket characters. Two problems. First, they look like kind of silly because most fonts use a different glyph. Well, if it's a matter of aesthetics, I happen to like it. So we're at an impasse! More importantly, though, it matches groff. I don't think it can (or should) change. When this behavior was added to mandoc, several pages using Aq to represent HTML tags were fixed. These pages were just overlooked. Two, a decent number of fonts don't include them, and then things look really silly. But to get to that point you have to: - use a UTF-8 locale (not the default); - change the xterm fonts (all the default fonts display these characters) - ...to something that doesn't support that character (lots of fonts do, what makes yours so special?) mandoc already special cases Aq in Mt macros to output plain brackets. This also matches groff. Here is a patch that corrects spamd(8). I can look at pages that use it for headers later... a quick grep reveals less than 20. Index: libexec/spamd/spamd.8 === RCS file: /cvs/src/libexec/spamd/spamd.8,v retrieving revision 1.125 diff -u -p -u -p -r1.125 spamd.8 --- libexec/spamd/spamd.8 7 Feb 2015 18:05:57 - 1.125 +++ libexec/spamd/spamd.8 15 Feb 2015 10:17:38 - @@ -268,11 +268,11 @@ regularly scans the .Pa /var/db/spamd database and configures all whitelist addresses as the .Xr pf 4 -.Aq spamd-white +spamd-white table, allowing connections to pass to the real MTA. Any addresses not found in -.Aq spamd-white +spamd-white are redirected to .Nm . .Pp @@ -385,7 +385,7 @@ spamtrap address, it is blacklisted for 24 hours by adding the host to the .Nm blacklist -.Aq spamd-greytrap . +spamd-greytrap. Spamtrap addresses are added to the .Pa /var/db/spamd database with the following @@ -468,7 +468,7 @@ a slightly modified .Xr pf.conf 5 ruleset is required, redirecting any addresses found in the -.Aq spamd +spamd table to .Nm . Any other addresses @@ -488,7 +488,7 @@ like: .Pp .Xr spamd-setup 8 can also be used to load addresses into the -.Aq spamd +spamd table. It has the added benefit of being able to remove addresses from blacklists, and will connect to
