[Pkg-samba-maint] Bug#1022945: smbclient: ambiguous duplications in the smbclient(1) manpage

Thu Nov 3 19:04:52 GMT 2022

Thanks Michael!

I have also dig a bit into the samba source.
There are similar duplicates in the smbcacls(1) manpage.

$ rgrep -n "max-protocol" *
docs-xml/build/DTD/samba.entities:559:<!ENTITY cmdline.common.connection.max-protocol '
docs-xml/build/DTD/samba.entities:561:	<term>-m|--max-protocol=MAXPROTOCOL</term>
docs-xml/build/DTD/samba.entities:580:&cmdline.common.connection.max-protocol;
docs-xml/manpages/rpcclient.1.xml:37:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbcquotas.1.xml:41:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/winexe.1.xml:37:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbcacls.1.xml:51:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbcacls.1.xml:182:		<term>-m|--max-protocol PROTOCOL_NAME</term>
docs-xml/manpages/smbcacls.1.xml:190:		a max-protocol of SMB3 is required.
docs-xml/manpages/mdsearch.1.xml:37:      <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/nmblookup.1.xml:43:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbclient.1.xml:46:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/smbclient.1.xml:193:		<term>-m|--max-protocol protocol</term>
docs-xml/manpages/smbclient.1.xml:201:		a max-protocol of SMB3 is required.
docs-xml/manpages/samba-regedit.8.xml:33:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
docs-xml/manpages/net.8.xml:35:		<arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg>
lib/cmdline/cmdline.c:705:		.longName   = "max-protocol",
source3/selftest/tests.py:508:for options in ["", "--option=clientntlmv2auth=no", "--option=clientusespnego=no", "--option=clientusespnego=no --option=clientntlmv2auth=no", "--option=clientntlmv2auth=no --option=clientlanmanauth=yes --max-protocol=LANMAN2", "--option=clientntlmv2auth=no --option=clientlanmanauth=yes --option=clientmaxprotocol=NT1"]:
source3/utils/smbcquotas.c:627:			.longName   = "max-protocol",
source3/utils/net_help_common.c:67:	d_printf(_("\t-m|--max-protocol=MAXPROTOCOL\t\tSet max protocol level\n"));

I think that samba.dtd contents some common shared entries and both
smbclient.1.xml and smbcacls.1.xml should not have their own
<varlistentry><term>...</term></varlistentry>.

I did not try to check by removing them.

More annoying is small discrepancy regarding the '-U|--user' option.

$ rgrep -n "\-U|--user" *
docs-xml/build/DTD/samba.entities:591:	<term>-U|--user=[DOMAIN\]USERNAME[&pct;PASSWORD]</term>
docs-xml/manpages/rpcclient.1.xml:42:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/smbcquotas.1.xml:46:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/winexe.1.xml:42:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME%[PASSWORD]</arg>
docs-xml/manpages/smbcacls.1.xml:56:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/mdsearch.1.xml:42:      <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/smbclient.1.xml:51:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME%[PASSWORD]</arg>
docs-xml/manpages/samba-regedit.8.xml:38:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/smbtree.1.xml:34:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/net.8.xml:40:		<arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg>
docs-xml/manpages/pdbedit.8.xml:33:		<arg choice="opt">-U|--user SID=STRING</arg>
source3/utils/net_help_common.c:75:	d_printf(_("\t-U|--user=[DOMAIN/]USERNAME[%%PASSWORD]\tSet the "

The separator to the DOMAIN value (ie. [DOMAIN\] or [DOMAIN/]) and the position
of the pourcent % should be inside the brackets (ie. [%PASSWORD] and not
%[PASSWORD]).

Finally, I found more to say about the documentation versus the output of help
option on the different samba commands.
Let see with what upstream have to say.

To conclude, be free to close this wish.

Regards,
Patrice

On Wed, 2 Nov 2022 19:53:02 +0300 Michael Tokarev <mjt at tls.msk.ru> wrote:
> 
> 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: