abuse of .Nm mdoc macro (fast_ipsec and others)

[Jeremy C. Reed]

apropos fast or apropos ipsec shows:

Fast IPsec (4) - hardware-accelerated IP Security Protocols

But "Fast IPsec" is not a manual page.

Should I use the following patch or should I make a MLINKS to create "Fast
IPsec.4" (filename with a space in it)? I think space is wrong for some
systems.

Index: share/man/man4/fast_ipsec.4
===================================================================
RCS file: /cvsroot/src/share/man/man4/fast_ipsec.4,v
retrieving revision 1.7
diff -u -r1.7 fast_ipsec.4
--- share/man/man4/fast_ipsec.4 25 May 2008 20:08:12 -0000 1.7
+++ share/man/man4/fast_ipsec.4 23 Apr 2009 13:34:19 -0000
@@ -32,8 +32,8 @@
 .Dt FAST_IPSEC 4
 .Os
 .Sh NAME
-.Nm "Fast IPsec"
-.Nd hardware-accelerated IP Security Protocols
+.Nm fast_ipsec
+.Nd Fast IPsec hardware-accelerated IP Security Protocols
 .Sh SYNOPSIS
 .Cd "options FAST_IPSEC"
 .Cd "options IPSEC_NAT_T"
@@ -49,7 +49,7 @@
 .Tn IPComp
 (for IP Payload Compression Protocol)
 that provide security services for IP datagrams.
-.Nm
+Fast IPsec
 is an implementation of these protocols that uses the
 .Xr opencrypto 9
 subsystem to carry out cryptographic operations.
@@ -57,7 +57,7 @@
 employed whenever possible to optimize the performance of these protocols.
 .Pp
 In general, the
-.Nm
+Fast IPsec
 implementation is intended to be compatible with the
 .Tn KAME IPsec
 implementation.
@@ -70,7 +70,7 @@
 .Xr opencrypto 9
 subsystem.
 When the
-.Nm
+Fast IPsec
 protocols are configured for use, all protocols are included in the system.
 To selectively enable/disable protocols, use
 .Xr sysctl 8 .
@@ -93,7 +93,7 @@
 .Tn IPsec
 protocols.
 The
-.Nm
+Fast IPsec
 protocols are based on code which appeared in
 .Fx 4.7 .
 The


I notice many man pages use Nm wrong. Many use it as "bold" and maybe .Sy
should be used instead. I don't list all them here.






  Jeremy C. Reed

echo 'EhZ[h ^jjf0%%h[[Zc[Z_W$d[j%Xeeai%ZW[ced#]dk#f[d]k_d%' | \
  tr            '#-~'            '\-.-{'

[Jeremy C. Reed]

Another example is lib/libdes/des_modes.7

.SH "NAME"  
Modes of \s-1DES\s0 \- the variants of \s-1DES\s0 and other crypto algorithms of OpenSSL

I am not sure how to improve that one though.

lib/libcrypto/man/des_modes.7 instead has:

.SH "NAME"
des_modes \- the variants of DES and other crypto algorithms of OpenSSL

Okay if I switch to that line instead?

Why do we have two files?

[Elad Efrat]

Jeremy C. Reed wrote:

> apropos fast or apropos ipsec shows:
>
> Fast IPsec (4) - hardware-accelerated IP Security Protocols
>
> But "Fast IPsec" is not a manual page.
>
> Should I use the following patch or should I make a MLINKS to create "Fast
> IPsec.4" (filename with a space in it)? I think space is wrong for some
> systems.
>
> Index: share/man/man4/fast_ipsec.4
> ===================================================================
> RCS file: /cvsroot/src/share/man/man4/fast_ipsec.4,v
> retrieving revision 1.7
> diff -u -r1.7 fast_ipsec.4
> --- share/man/man4/fast_ipsec.4 25 May 2008 20:08:12 -0000 1.7
> +++ share/man/man4/fast_ipsec.4 23 Apr 2009 13:34:19 -0000
> @@ -32,8 +32,8 @@
>  .Dt FAST_IPSEC 4
>  .Os
>  .Sh NAME
> -.Nm "Fast IPsec"
> -.Nd hardware-accelerated IP Security Protocols
> +.Nm fast_ipsec
> +.Nd Fast IPsec hardware-accelerated IP Security Protocols
>  .Sh SYNOPSIS
>  .Cd "options FAST_IPSEC"
>  .Cd "options IPSEC_NAT_T"
> @@ -49,7 +49,7 @@
>  .Tn IPComp
>  (for IP Payload Compression Protocol)
>  that provide security services for IP datagrams.
> -.Nm
> +Fast IPsec
>  is an implementation of these protocols that uses the
>  .Xr opencrypto 9
>  subsystem to carry out cryptographic operations.
> @@ -57,7 +57,7 @@
>  employed whenever possible to optimize the performance of these protocols.
>  .Pp
>  In general, the
> -.Nm
> +Fast IPsec
>  implementation is intended to be compatible with the
>  .Tn KAME IPsec
>  implementation.
> @@ -70,7 +70,7 @@
>  .Xr opencrypto 9
>  subsystem.
>  When the
> -.Nm
> +Fast IPsec
>  protocols are configured for use, all protocols are included in the system.
>  To selectively enable/disable protocols, use
>  .Xr sysctl 8 .
> @@ -93,7 +93,7 @@
>  .Tn IPsec
>  protocols.
>  The
> -.Nm
> +Fast IPsec
>  protocols are based on code which appeared in
>  .Fx 4.7 .
>  The

You are correct, the man-page is wrong. To me both the first chunk of
the diff, and all of it seem fine, so commit whatever you choose. :)

I think netbsd-docs@ is too quiet btw. Perhaps you should always mail
just tech-userlevel@?

Thanks,

-e.