Issue in man page nfsservctl.2

Issue in man page nfsservctl.2

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    mountd(8) → B<mountd>(8)
"/*\n"
" * These are the commands understood by nfsctl().\n"
" */\n"
"#define NFSCTL_SVC        0  /* This is a server process. */\n"
"#define NFSCTL_ADDCLIENT  1  /* Add an NFS client. */\n"
"#define NFSCTL_DELCLIENT  2  /* Remove an NFS client. */\n"
"#define NFSCTL_EXPORT     3  /* Export a filesystem. */\n"
"#define NFSCTL_UNEXPORT   4  /* Unexport a filesystem. */\n"
"#define NFSCTL_UGIDUPDATE 5  /* Update a client\\[aq]s UID/GID map\n"
"                                (only in Linux 2.4.x and earlier). */\n"
"#define NFSCTL_GETFH      6  /* Get a file handle (used by mountd(8))\n"
"                                (only in Linux 2.4.x and earlier). */\n"
"\\&\n"
"struct nfsctl_arg {\n"
"    int                       ca_version;     /* safeguard */\n"
"    union {\n"
"        struct nfsctl_svc     u_svc;\n"
"        struct nfsctl_client  u_client;\n"
"        struct nfsctl_export  u_export;\n"
"        struct nfsctl_uidmap  u_umap;\n"
"        struct nfsctl_fhparm  u_getfh;\n"
"        unsigned int          u_debug;\n"
"    } u;\n"
"}\n"
"\\&\n"
"union nfsctl_res {\n"
"        struct knfs_fh          cr_getfh;\n"
"        unsigned int            cr_debug;\n"
"};\n"

Re: Issue in man page nfsservctl.2

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 1650 bytes --]

Hi Helge, Branden,

On Wed, Nov 01, 2023 at 02:02:11PM +0000, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    mountd(8) → B<mountd>(8)
> "/*\n"
> " * These are the commands understood by nfsctl().\n"
> " */\n"
> "#define NFSCTL_SVC        0  /* This is a server process. */\n"
> "#define NFSCTL_ADDCLIENT  1  /* Add an NFS client. */\n"
> "#define NFSCTL_DELCLIENT  2  /* Remove an NFS client. */\n"
> "#define NFSCTL_EXPORT     3  /* Export a filesystem. */\n"
> "#define NFSCTL_UNEXPORT   4  /* Unexport a filesystem. */\n"
> "#define NFSCTL_UGIDUPDATE 5  /* Update a client\\[aq]s UID/GID map\n"
> "                                (only in Linux 2.4.x and earlier). */\n"
> "#define NFSCTL_GETFH      6  /* Get a file handle (used by mountd(8))\n"

Since Branden is going to patch these things soon, and it will likely
affect his script, I'll let him decide what to do here.

Cheers,
Alex

> "                                (only in Linux 2.4.x and earlier). */\n"
> "\\&\n"
> "struct nfsctl_arg {\n"
> "    int                       ca_version;     /* safeguard */\n"
> "    union {\n"
> "        struct nfsctl_svc     u_svc;\n"
> "        struct nfsctl_client  u_client;\n"
> "        struct nfsctl_export  u_export;\n"
> "        struct nfsctl_uidmap  u_umap;\n"
> "        struct nfsctl_fhparm  u_getfh;\n"
> "        unsigned int          u_debug;\n"
> "    } u;\n"
> "}\n"
> "\\&\n"
> "union nfsctl_res {\n"
> "        struct knfs_fh          cr_getfh;\n"
> "        unsigned int            cr_debug;\n"
> "};\n"

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Issue in man page nfsservctl.2

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    mountd(8) → B<mountd>(8)

"/*\n"
" * These are the commands understood by nfsctl().\n"
" */\n"
"#define NFSCTL_SVC        0  /* This is a server process. */\n"
"#define NFSCTL_ADDCLIENT  1  /* Add an NFS client. */\n"
"#define NFSCTL_DELCLIENT  2  /* Remove an NFS client. */\n"
"#define NFSCTL_EXPORT     3  /* Export a filesystem. */\n"
"#define NFSCTL_UNEXPORT   4  /* Unexport a filesystem. */\n"
"#define NFSCTL_UGIDUPDATE 5  /* Update a client\\[aq]s UID/GID map\n"
"                                (only in Linux 2.4.x and earlier). */\n"
"#define NFSCTL_GETFH      6  /* Get a file handle (used by mountd(8))\n"
"                                (only in Linux 2.4.x and earlier). */\n"

Re: Issue in man page nfsservctl.2

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1033 bytes --]

Hi Helge,

On 3/11/23 18:13, Helge Kreutzmann wrote:
> Without further ado, the following was found:
> 
> Issue:    mountd(8) → B<mountd>(8)

We don't use that formatting in example code.

Cheers,

Alex

> 
> "/*\n"
> " * These are the commands understood by nfsctl().\n"
> " */\n"
> "#define NFSCTL_SVC        0  /* This is a server process. */\n"
> "#define NFSCTL_ADDCLIENT  1  /* Add an NFS client. */\n"
> "#define NFSCTL_DELCLIENT  2  /* Remove an NFS client. */\n"
> "#define NFSCTL_EXPORT     3  /* Export a filesystem. */\n"
> "#define NFSCTL_UNEXPORT   4  /* Unexport a filesystem. */\n"
> "#define NFSCTL_UGIDUPDATE 5  /* Update a client\\[aq]s UID/GID map\n"
> "                                (only in Linux 2.4.x and earlier). */\n"
> "#define NFSCTL_GETFH      6  /* Get a file handle (used by mountd(8))\n"
> "                                (only in Linux 2.4.x and earlier). */\n"

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page nfsservctl.2

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 856 bytes --]

Hello Alex,
On Sun, Mar 12, 2023 at 12:31:05AM +0100, Alejandro Colomar wrote:
> On 3/11/23 18:13, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    mountd(8) → B<mountd>(8)
> 
> We don't use that formatting in example code.

I think I saw it elsewhere, but then probably from one of our ~ 100
other projects.

(And again, for hyperlinking etc. I think it can be helpful; I just
checked, even with formatting I can simply copy that code out - so
there is not disadvantage?)

Greetings

        Helge

-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page nfsservctl.2

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 2125 bytes --]

At 2023-03-12T06:23:33+0100, Helge Kreutzmann wrote:
> Hello Alex,
> On Sun, Mar 12, 2023 at 12:31:05AM +0100, Alejandro Colomar wrote:
> > On 3/11/23 18:13, Helge Kreutzmann wrote:
> > > Without further ado, the following was found:
> > > 
> > > Issue:    mountd(8) → B<mountd>(8)
> > 
> > We don't use that formatting in example code.
> 
> I think I saw it elsewhere, but then probably from one of our ~ 100
> other projects.
> 
> (And again, for hyperlinking etc. I think it can be helpful; I just
> checked, even with formatting I can simply copy that code out - so
> there is not disadvantage?)

I don't have anything quantitative for you, but my impression from my
own readings in software is that generally, in typeset material, code
comments don't indulge in much style variation.  They might be set
uniformly in a slanted face, or in proportional typeface where the code
proper is monospaced, but not much beyond that.

Also, I think having URLs in code comments in documentary examples is
typographically dangerous.  In examples, filling is (usually) off, and
URLs can get long, so the risk of oversetting the output line is
greater.  You also don't know how wide the user's terminal is going to
be.  On top of that, groff man(7) permits the user to configure the
"standard indentation amount".

    -rIN=standard-indentation
        Set the amount of indentation used for ordinary paragraphs (.P
        and its synonyms) and the default indentation amount used by
        .IP, .RS, .TP, and the deprecated .HP.  See subsection
        "Horizontal and vertical spacing" above for the default.  For
        terminal devices, standard-indentation should always be an
        integer multiple of unit "n" to get consistent indentation.

These factors combine to make it hard to judge how much room you're
going to have for your code examples.

So I would avoid putting URLs in example comments.

In fact, I could counsel against any code comments in examples at all,
unless they're so short that they don't increase the total width of the
example.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: Issue in man page nfsservctl.2

[Helge Kreutzmann]

[-- Attachment #1: Type: text/plain, Size: 1675 bytes --]

Hello Branden,
On Sun, Mar 12, 2023 at 12:11:15PM -0500, G. Branden Robinson wrote:
> At 2023-03-12T06:23:33+0100, Helge Kreutzmann wrote:
> > Hello Alex,
> > On Sun, Mar 12, 2023 at 12:31:05AM +0100, Alejandro Colomar wrote:
> > > On 3/11/23 18:13, Helge Kreutzmann wrote:
> > > > Without further ado, the following was found:
> > > > 
> > > > Issue:    mountd(8) → B<mountd>(8)
> > > 
> > > We don't use that formatting in example code.
> > 
> > I think I saw it elsewhere, but then probably from one of our ~ 100
> > other projects.
> > 
> > (And again, for hyperlinking etc. I think it can be helpful; I just
> > checked, even with formatting I can simply copy that code out - so
> > there is not disadvantage?)
> 
> I don't have anything quantitative for you, but my impression from my
> own readings in software is that generally, in typeset material, code
> comments don't indulge in much style variation.  They might be set
> uniformly in a slanted face, or in proportional typeface where the code
> proper is monospaced, but not much beyond that.

No, the code does not show any URL.

When HTML output is generated, the tools detect the man page reference
and turn it into a hyperlink.

I think Mario (in CC) knows more about it.

So the only idea is to have those tools detect the man page reference.

Greetings

           Helge



-- 
      Dr. Helge Kreutzmann                     debian@helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Issue in man page nfsservctl.2

[Helge Kreutzmann]

Without further ado, the following was found:

Issue:    mountd → B<mountd>(8)

"/*\n"
" * These are the commands understood by nfsctl().\n"
" */\n"
"#define NFSCTL_SVC        0  /* This is a server process. */\n"
"#define NFSCTL_ADDCLIENT  1  /* Add an NFS client. */\n"
"#define NFSCTL_DELCLIENT  2  /* Remove an NFS client. */\n"
"#define NFSCTL_EXPORT     3  /* Export a filesystem. */\n"
"#define NFSCTL_UNEXPORT   4  /* Unexport a filesystem. */\n"
"#define NFSCTL_UGIDUPDATE 5  /* Update a client\\(aqs UID/GID map\n"
"                                (only in Linux 2.4.x and earlier). */\n"
"#define NFSCTL_GETFH      6  /* Get a file handle (used by mountd)\n"
"                                (only in Linux 2.4.x and earlier). */\n"