<html dir="ltr"><head></head><body style="text-align:left; direction:ltr;"><div>Can we move this discussion to an upstream bug, and even better propose a patch per </div><div><a href="https://wiki.samba.org/index.php/Contribute">https://wiki.samba.org/index.php/Contribute</a> on GitLab for Samba master?</div><div><br></div><div>There is nothing debian-specific here and it is all going to have to be solved upstream anyway. </div><div><br></div><div>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.</div><div><br></div><div>Andrew Bartlett</div><div><br></div><div>On Thu, 2022-11-03 at 20:04 +0100, Patrice Duroux wrote:</div><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre>Thanks Michael!</pre><pre><br></pre><pre>I have also dig a bit into the samba source.</pre><pre>There are similar duplicates in the smbcacls(1) manpage.</pre><pre><br></pre><pre>$ rgrep -n "max-protocol" *</pre><pre>docs-xml/build/DTD/samba.entities:559:<!ENTITY cmdline.common.connection.max-protocol '</pre><pre>docs-xml/build/DTD/samba.entities:561: <term>-m|--max-protocol=MAXPROTOCOL</term></pre><pre>docs-xml/build/DTD/samba.entities:580:&cmdline.common.connection.max-protocol;</pre><pre>docs-xml/manpages/rpcclient.1.xml:37: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>docs-xml/manpages/smbcquotas.1.xml:41: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>docs-xml/manpages/winexe.1.xml:37: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>docs-xml/manpages/smbcacls.1.xml:51: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>docs-xml/manpages/smbcacls.1.xml:182: <term>-m|--max-protocol PROTOCOL_NAME</term></pre><pre>docs-xml/manpages/smbcacls.1.xml:190: a max-protocol of SMB3 is required.</pre><pre>docs-xml/manpages/mdsearch.1.xml:37: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>docs-xml/manpages/nmblookup.1.xml:43: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>docs-xml/manpages/smbclient.1.xml:46: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>docs-xml/manpages/smbclient.1.xml:193: <term>-m|--max-protocol protocol</term></pre><pre>docs-xml/manpages/smbclient.1.xml:201: a max-protocol of SMB3 is required.</pre><pre>docs-xml/manpages/samba-regedit.8.xml:33: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>docs-xml/manpages/net.8.xml:35: <arg choice="opt">-m|--max-protocol=MAXPROTOCOL</arg></pre><pre>lib/cmdline/cmdline.c:705: .longName = "max-protocol",</pre><pre>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"]:</pre><pre>source3/utils/smbcquotas.c:627: .longName = "max-protocol",</pre><pre>source3/utils/net_help_common.c:67: d_printf(_("\t-m|--max-protocol=MAXPROTOCOL\t\tSet max protocol level\n"));</pre><pre><br></pre><pre>I think that samba.dtd contents some common shared entries and both</pre><pre>smbclient.1.xml and smbcacls.1.xml should not have their own</pre><pre><varlistentry><term>...</term></varlistentry>.</pre><pre><br></pre><pre>I did not try to check by removing them.</pre><pre><br></pre><pre>More annoying is small discrepancy regarding the '-U|--user' option.</pre><pre><br></pre><pre>$ rgrep -n "\-U|--user" *</pre><pre>docs-xml/build/DTD/samba.entities:591: <term>-U|--user=[DOMAIN\]USERNAME[&pct;PASSWORD]</term></pre><pre>docs-xml/manpages/rpcclient.1.xml:42: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg></pre><pre>docs-xml/manpages/smbcquotas.1.xml:46: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg></pre><pre>docs-xml/manpages/winexe.1.xml:42: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME%[PASSWORD]</arg></pre><pre>docs-xml/manpages/smbcacls.1.xml:56: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg></pre><pre>docs-xml/manpages/mdsearch.1.xml:42: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg></pre><pre>docs-xml/manpages/smbclient.1.xml:51: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME%[PASSWORD]</arg></pre><pre>docs-xml/manpages/samba-regedit.8.xml:38: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg></pre><pre>docs-xml/manpages/smbtree.1.xml:34: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg></pre><pre>docs-xml/manpages/net.8.xml:40: <arg choice="opt">-U|--user=[DOMAIN/]USERNAME[%PASSWORD]</arg></pre><pre>docs-xml/manpages/pdbedit.8.xml:33: <arg choice="opt">-U|--user SID=STRING</arg></pre><pre>source3/utils/net_help_common.c:75: d_printf(_("\t-U|--user=[DOMAIN/]USERNAME[%%PASSWORD]\tSet the "</pre><pre><br></pre><pre>The separator to the DOMAIN value (ie. [DOMAIN\] or [DOMAIN/]) and the position</pre><pre>of the pourcent % should be inside the brackets (ie. [%PASSWORD] and not</pre><pre>%[PASSWORD]).</pre><pre><br></pre><pre>Finally, I found more to say about the documentation versus the output of help</pre><pre>option on the different samba commands.</pre><pre>Let see with what upstream have to say.</pre><pre><br></pre><pre>To conclude, be free to close this wish.</pre><pre><br></pre><pre>Regards,</pre><pre>Patrice</pre><pre><br></pre><pre>On Wed, 2 Nov 2022 19:53:02 +0300 Michael Tokarev <</pre><a href="mailto:mjt@tls.msk.ru"><pre>mjt@tls.msk.ru</pre></a><pre>> wrote:</pre><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre><br></pre><pre>28.10.2022 10:28, Patrice DUROUX wrote:</pre><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre>Package: smbclient</pre><pre>Version: 2:4.16.6+dfsg-5</pre><pre>Severity: wishlist</pre><pre><br></pre><pre>Dear Maintainer,</pre><pre><br></pre><pre>The smbclient(1) manpage contains some multiple entries in the OPTIONS</pre><pre>section regarding the SYNOPSIS list.</pre><pre><br></pre><pre>Here are the two detected cases:</pre><pre><br></pre><pre>71: -m|--max-protocol protocol</pre><pre>72- This allows the user to select the highest SMB protocol level</pre></blockquote></blockquote><pre>that smbclient will use to connect to the server. By default this is set to</pre><pre>highest available SMB3</pre><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre>and</pre><pre>259: -m|--max-protocol=MAXPROTOCOL</pre><pre>260- The value of the parameter (a string) is the highest protocol</pre></blockquote></blockquote><pre>level that will be supported by the client.</pre><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre><br></pre><pre>samba manpages are generated. And this is interesting.</pre><pre><br></pre><pre>The first text above comes from docs-xml/manpages/smbclient.1.xml:</pre><pre><br></pre><pre> <term>-m|--max-protocol protocol</term></pre><pre> <listitem><para>This allows the user to select the</pre><pre> highest SMB protocol level that smbclient will use to</pre><pre> connect to the server. By default this is set to..</pre><pre><br></pre><pre>And the second text comes from docs-</pre></blockquote><pre>xml/smbdotconf/protocol/clientmaxprotocol.xml:</pre><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre><br></pre><pre> <samba:parameter name="client max protocol"</pre><pre> context="G"</pre><pre> type="enum"</pre><pre> function="_client_max_protocol"</pre><pre> enumlist="enum_protocol"</pre><pre> xmlns:samba="</pre><a href="http://www.samba.org/samba/DTD/samba-doc"><pre>http://www.samba.org/samba/DTD/samba-doc</pre></a><pre>"></pre><pre> <description></pre><pre> <para>The value of the parameter (a string) is the highest</pre><pre> protocol level that will be supported by the client.</para></pre><pre> ...</pre><pre><br></pre><pre>So it looks like smbclient.1.xml manpage lists *all* options available,</pre><pre>and also includes other files which lists some options which are referenced</pre><pre>by smbclient.1.xml. And it looks like the same applies to other manpages too.</pre><pre><br></pre><pre>I'm Cc'ing samba-technical@ with this.</pre><pre><br></pre><pre>Thanks,</pre><pre><br></pre><pre>/mjt</pre><pre><br></pre><pre><br></pre><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre>76: -P|--machine-pass</pre><pre>77- Make queries to the external server using the machine account</pre></blockquote></blockquote><pre>of the local server.</pre><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre>and</pre><pre>335: -P|--machine-pass</pre><pre>336- Use stored machine account password.</pre><pre><br></pre><pre>Moreover the entries in the OPTIONS section should be more consistent to the</pre></blockquote></blockquote><pre>SYNOPSIS</pre><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><blockquote type="cite" style="margin:0 0 0 .8ex; border-left:2px #729fcf solid;padding-left:1ex"><pre>syntax. For instance, SYNOPSIS is:</pre></blockquote></blockquote><pre><br></pre></blockquote><div><span><pre>-- <br></pre><div style="width: 71ch;">Andrew Bartlett (he/him) <a href="https://samba.org/~abartlet/">https://samba.org/~abartlet/</a></div><div style="width: 71ch;">Samba Team Member (since 2001) <a href="https://samba.org">https://samba.org</a></div><div style="width: 71ch;">Samba Team Lead, Catalyst IT <a href="https://catalyst.net.nz/services/samba">https://catalyst.net.nz/services/samba</a></div><div style="width: 71ch;"><br></div><div style="width: 71ch;">Samba Development and Support, Catalyst IT - Expert Open Source</div><div style="width: 71ch;">Solutions</div><div style="width: 71ch;"></div></span></div></body></html>