Bug 12918 - Unadequate format in programlisting
Summary: Unadequate format in programlisting
Status: NEW
Alias: None
Product: Samba 4.1 and newer
Classification: Unclassified
Component: Documentation (show other bugs)
Version: unspecified
Hardware: All All
: P5 normal (vote)
Target Milestone: ---
Assignee: Douglas Bagnall
QA Contact: Samba Documentation QA Contact~
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2017-07-20 06:54 UTC by Michio MATSUYAMA
Modified: 2025-03-26 01:52 UTC (History)
0 users

See Also:


Attachments
Unadequate format in programlisting (56.11 KB, patch)
2017-07-20 06:54 UTC, Michio MATSUYAMA
no flags Details
patches for the worst problems (27.64 KB, patch)
2025-03-19 03:36 UTC, Douglas Bagnall
no flags Details

Note You need to log in before you can comment on or make changes to this bug.
Description Michio MATSUYAMA 2017-07-20 06:54:09 UTC
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.
Comment 1 Michio MATSUYAMA 2017-07-20 11:57:58 UTC
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.
Comment 2 Douglas Bagnall 2025-03-19 03:02:33 UTC
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.
Comment 3 Douglas Bagnall 2025-03-19 03:07:58 UTC
(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.
Comment 4 Douglas Bagnall 2025-03-19 03:36:45 UTC
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.
Comment 5 Samba QA Contact 2025-03-26 01:52:30 UTC
This bug was referenced in samba master:

dc33c630d7028e334fce847713e51aee9f6c8fc0
ddd9f36562f0139ea44a14a0c77dd10a1d0fcd52