Bug#1022945: smbclient: ambiguous duplications in the smbclient(1) manpage

[Michael Tokarev]

28.10.2022 10:28, Patrice DUROUX wrote:
> Package: smbclient
> Version: 2:4.16.6+dfsg-5
> Severity: wishlist
> 
> Dear Maintainer,
> 
> The smbclient(1) manpage contains some multiple entries in the OPTIONS
> section regarding the SYNOPSIS list.
> 
> Here are the two detected cases:
> 
> 71:       -m|--max-protocol protocol
> 72-           This allows the user to select the highest SMB protocol level that smbclient will use to connect to the server. By default this is set to highest available SMB3
> and
> 259:       -m|--max-protocol=MAXPROTOCOL
> 260-           The value of the parameter (a string) is the highest protocol level that will be supported by the client.

samba manpages are generated. And this is interesting.

The first text above comes from docs-xml/manpages/smbclient.1.xml:

                 <term>-m|--max-protocol protocol</term>
                 <listitem><para>This allows the user to select the
                 highest SMB protocol level that smbclient will use to
                 connect to the server. By default this is set to..

And the second text comes from docs-xml/smbdotconf/protocol/clientmaxprotocol.xml:

   <samba:parameter name="client max protocol"
                  context="G"
                  type="enum"
                  function="_client_max_protocol"
                  enumlist="enum_protocol"
                  xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
   <description>
     <para>The value of the parameter (a string) is the highest
     protocol level that will be supported by the client.</para>
     ...

So it looks like smbclient.1.xml manpage lists *all* options available,
and also includes other files which lists some options which are referenced
by smbclient.1.xml. And it looks like the same applies to other manpages too.

I'm Cc'ing samba-technical@ with this.

Thanks,

/mjt


> 76:       -P|--machine-pass
> 77-           Make queries to the external server using the machine account of the local server.
> and
> 335:       -P|--machine-pass
> 336-           Use stored machine account password.
> 
> Moreover the entries in the OPTIONS section should be more consistent to the SYNOPSIS
> syntax. For instance, SYNOPSIS is:
> 
>         smbclient [-M|--message=HOST] [-I|--ip-address=IP] [-E|--stderr] [-L|--list=HOST] [-T|--tar=<c|x>IXFvgbNan] [-D|--directory=DIR] [-b|--send-buffer=BYTES]
>          [-t|--timeout=SECONDS] [-p|--port=PORT] [-g|--grepable] [-q|--quiet] [-B|--browse] [-?|--help] [--usage] [-d|--debuglevel=DEBUGLEVEL] [--debug-stdout]
>          [-s|--configfile=CONFIGFILE] [--option=name=value] [-l|--log-basename=LOGFILEBASE] [--leak-report] [--leak-report-full] [-R|--name-resolve=NAME-RESOLVE-ORDER]
>          [-O|--socket-options=SOCKETOPTIONS] [-m|--max-protocol=MAXPROTOCOL] [-n|--netbiosname=NETBIOSNAME] [--netbios-scope=SCOPE] [-W|--workgroup=WORKGROUP]
>          [--realm=REALM] [-U|--user=[DOMAIN/]USERNAME%[PASSWORD]] [-N|--no-pass] [--password=STRING] [--pw-nt-hash] [-A|--authentication-file=FILE] [-P|--machine-pass]
>          [--simple-bind-dn=DN] [--use-kerberos=desired|required|off] [--use-krb5-ccache=CCACHE] [--use-winbind-ccache] [--client-protection=sign|encrypt|off] [-V|--version]
>          [-c|--command=STRING]
> 
> and the entries in OPTIONS are (with the duplicates):
>         -M|--message NetBIOS name      <- =HOST
>         -p|--port port                 <- =PORT
>         -g|--grepable
>         -m|--max-protocol protocol     <- duplicated
>         -P|--machine-pass              <- duplicated
>         -I|--ip-address IP-address     <- =IP
>         -E|--stderr
>         -L|--list                      <- =HOST
>         -b|--send-buffer buffersize    <- =BYTES
>         -B|--browse
>         -t|--timeout <timeout-seconds> <- =SECONDS
>         -T|--tar tar options           <- =<c|x>IXFvgbNan
>         -D|--directory initial directory <- =DIR
>         -c|--command command string    <- =STRING
>         -?|--help
>         -d|--debuglevel=DEBUGLEVEL
>         -l|--log-basename=logdirectory <- =LOGFILEBASE
>         -V|--version
>         -R|--name-resolve=NAME-RESOLVE-ORDER
>         -O|--socket-options=SOCKETOPTIONS
>         -m|--max-protocol=MAXPROTOCOL
>         -n|--netbiosname=NETBIOSNAME
>         -W|--workgroup=WORKGROUP
>         -r|--realm=REALM
>         -U|--user=[DOMAIN\]USERNAME[%PASSWORD] <- / or \ ?
>         -N|--no-pass
>         -A|--authentication-file=filename
>         -P|--machine-pass
> 
> And as we can see, the SYNOPSIS set is much larger than that of OPTIONS.
> 
> Regards,
> Patrice
> 
> ps: I just used the following command to check: man smbclient | grep -n -A 1 '\-.|'
> https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-samba-maint