[Pkg-samba-maint] Bug#1022945: smbclient: ambiguous duplications in the smbclient(1) manpage
Andrew Bartlett
abartlet at samba.org
Thu Nov 3 19:37:39 GMT 2022
Can we move this discussion to an upstream bug, and even better propose
a patch per https://wiki.samba.org/index.php/Contribute on GitLab for
Samba master?
There is nothing debian-specific here and it is all going to have to be
solved upstream anyway.
Hard work has been started to have our manpages and even more
importantly code use common elements so that we have consistent
behaviour and consistent documentation, the rough edges just need a
clean up and this would be an awesome contributed patch, as it just
takes time.
Andrew Bartlett
On Thu, 2022-11-03 at 20:04 +0100, Patrice Duroux wrote:
> 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: .longNa
> me = "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
> bothsmbclient.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_print
> f(_("\t-U|--user=[DOMAIN/]USERNAME[%%PASSWORD]\tSet the "
> The separator to the DOMAIN value (ie. [DOMAIN\] or [DOMAIN/]) and
> the positionof 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 helpoption 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: smbclientVersion: 2:4.16.6+dfsg-5Severity: wishlist
> > > Dear Maintainer,
> > > The smbclient(1) manpage contains some multiple entries in the
> > > OPTIONSsection regarding the SYNOPSIS list.
> > > Here are the two detected cases:
> > > 71: -m|--max-protocol protocol72- 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 tohighest available SMB3
> > > and259: -m|--max-protocol=MAXPROTOCOL260- 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 referencedby 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-pass77- Make queries to the
> > > external server using the machine account
> of the local server.
> > > and335: -P|--machine-pass336- Use stored machine
> > > account password.
> > > Moreover the entries in the OPTIONS section should be more
> > > consistent to the
> SYNOPSIS
> > > syntax. For instance, SYNOPSIS is:
--
Andrew Bartlett (he/him) https://samba.org/~abartlet/Samba Team Member (since 2001) https://samba.orgSamba Team Lead, Catalyst IT https://catalyst.net.nz/services/samba
Samba Development and Support, Catalyst IT - Expert Open SourceSolutions
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://alioth-lists.debian.net/pipermail/pkg-samba-maint/attachments/20221104/7332278f/attachment-0001.htm>
More information about the Pkg-samba-maint
mailing list