Created attachment 13405 [details] Unadequate format in programlisting Most XML files for manpages which use programlisting tag are not adequate in the typing manner, so the output would also be not adequate. This is because the characters within the programlisting tags have the unneccessary blanks or tabs in the head position of each lines, as will be output exactly as seen, and this cause unadequate results in the output. Few files, such as pdbedit.8.xml, rpcclient.1.xml, wbinfo.1.xml, are good in the point of this view. But, especially vfs_shell_snap.8.xml is the worst one, please look in the htmlman version, its hyperlinks created for other option pages look bad because of having the unneccessary line breaks in the middle of smbconfoption tags. Here is a sample, manpages/idmap_tdb2.8.xml: diff --git a/docs-xml/manpages/idmap_tdb2.8.xml b/docs-xml/manpages/idmap_tdb2.8.xml index 5b4fe2e..4f93f7b 100644 --- a/docs-xml/manpages/idmap_tdb2.8.xml +++ b/docs-xml/manpages/idmap_tdb2.8.xml @@ -79,10 +79,9 @@ </para> <programlisting> - SIDTOID S-1-xxxx - IDTOSID UID xxxx - IDTOSID GID xxxx - </programlisting> +SIDTOID S-1-xxxx +IDTOSID UID xxxx +IDTOSID GID xxxx</programlisting> <para> And it should return one of the following responses as a single line of Note that there should be no blanks or tags before '</programlisting>' tag. If not, an unnesseary blank line would create at the end of this programlising content. I have found several pages that, I am afraid, should modify, and these are shown in an attachment diff file.
Wrong explanation I had before. Again: Note that there should be no blanks or tags before '</programlisting>' tag. If there exists a blank or tag, an unnesseary blank line would create at the end of this programlising content.
The problem is most easily seen in one-line program listings, like under "THE MAPPING FORMULAS" in https://www.samba.org/samba/docs/current/man-html/idmap_rid.8.html However, I notice that https://www.samba.org/samba/docs/current/man-html/lmhosts.5.html does not have a trailing blank line in its <programlisting>, even though </programlisting> is on a new line. That is, it looks like removing the leading tabs and space is enough, which makes the patch more palatable and easier to review. We don't need to <programlisting> - RID = ID + BASE_RID - LOW_RANGE_ID. - </programlisting> +RID = ID + BASE_RID - LOW_RANGE_ID</programlisting> because we can <programlisting> RID = ID + BASE_RID - LOW_RANGE_ID. - </programlisting> +</programlisting> Unsurprisingly, the patch doesn't entirely apply.
(In reply to Douglas Bagnall from comment #2) > <programlisting> > RID = ID + BASE_RID - LOW_RANGE_ID. > - </programlisting> > +</programlisting> OK, I guess we'd want to <programlisting> - RID = ID + BASE_RID - LOW_RANGE_ID +RID = ID + BASE_RID - LOW_RANGE_ID. </programlisting> as a second patch, and maybe pull the <prgramlisting> opening over too.
Created attachment 18615 [details] patches for the worst problems These patches remove the trailing empty lines, and reformat the multiline smbconf options in docs-xml/manpages/vfs_shell_snap.8.xml At the time of posting, the "CONFIGURATION" section of https://www.samba.org/samba/docs/current/man-html/vfs_shell_snap.8.html shows the problem. removing leading whitespace needs more care.
This bug was referenced in samba master: dc33c630d7028e334fce847713e51aee9f6c8fc0 ddd9f36562f0139ea44a14a0c77dd10a1d0fcd52