#809754 docbook-xsl: manpages: Misuse of "no-break space" causes overlong lines

Package:
docbook-xsl
Source:
docbook-xsl
Submitter:
Bjarni Ingi Gislason
Date:
2023-10-24 08:45:05 UTC
Severity:
normal
Tags:
#809754#5
Date:
2016-01-03 18:16:49 UTC
From:
To:
  This is related to Debian bug #569828, which is number 1120 upstream.

Dear Maintainer,

   * What exactly did you do (or not do) that was effective (or
     ineffective)?

  For example "man usb_copy_descriptors".  Manual is from the
"linux-manual" package.

  Environment was:

MANWIDTH=80
MANOPT=--no-hyphenation --warnings=w
MAN_KEEP_STDERR=yes

   * What was the outcome of this action?

  For example

<standard input>:34: warning [p 1, 1.5i]: can't break line

###

  There are many error detected by "lintian" in the package
"linux-manual" caused by the use of a "no-break space".  I don't know
the markup language used, but I experimented and did the following
changes in the directory
/usr/share/xml/docbook/stylesheet/docbook-xsl/manpages:

  What is missing in the patch is the idea in Debian bug #569828.


  Patch: (also in the attachment, if it should get mangled here)
--- param.xsl.jessie	2012-01-09 14:09:15.000000000 +0000
+++ param.xsl	2016-01-02 21:43:50.000000000 +0000
@@ -90,10 +90,15 @@ or
 <xsl:param name="man.segtitle.suppress" select="0"/>
 <xsl:param name="man.string.subst.map">

-  <!-- * remove no-break marker at beginning of line (stylesheet artifact) -->
+  <!-- * remove no-break marker at the beginning of a line (stylesheet artifact) -->
   <substitution oldstring="▒▀" newstring="▒"/>
-  <!-- * replace U+2580 no-break marker (stylesheet-added) w/ no-break space -->
-  <substitution oldstring="▀" newstring="\ "/>
+  <!-- no-break space causes formatting errors, like overlong lines,
+  that get truncated if printed (on paper) or get automatically folded
+  by a pager (on a screen)
+  -->
+  <!-- * replace U+2580 no-break marker (stylesheet-added) with space -->
+  <substitution oldstring="▀" newstring=" "/>
+

   <!-- ==================================================================== -->

@@ -101,9 +106,9 @@ or
   <substitution oldstring="

." newstring="
."/>
   <!-- * remove any .sp instances that directly precede a .PP  -->
   <substitution oldstring=".sp
.PP" newstring=".PP"/>
-  <!-- * remove any .sp instances that directly follow a .PP  -->
-  <substitution oldstring=".sp
.sp" newstring=".sp"/>
   <!-- * squeeze multiple .sp instances into a single .sp-->
+  <substitution oldstring=".sp
.sp" newstring=".sp"/>
+  <!-- * remove any .sp instances that directly follow a .PP  -->
   <substitution oldstring=".PP
.sp" newstring=".PP"/>
   <!-- * squeeze multiple newlines after start of no-fill (verbatim) env. -->
   <substitution oldstring=".nf

" newstring=".nf
"/>
--- synop.xsl.jessie 2012-01-09 14:08:12.000000000 +0000 +++ synop.xsl 2016-01-02 18:08:55.000000000 +0000 @@ -163,19 +163,24 @@ <xsl:text>.hy 0 </xsl:text> </xsl:if> <xsl:call-template name="synopsis-block-start"/> - <xsl:text>.HP </xsl:text> + <!-- * Calculate the argument to .HP separatly to avoid problems from --> + <!-- * paddable spaces in the argument --> + <xsl:text>.nr hP </xsl:text> <xsl:text>\w'</xsl:text> <xsl:variable name="command"> <xsl:apply-templates select="command"/> </xsl:variable> + <!-- * Comment this out as the space is moved to the ".nr hP" line <xsl:call-template name="string.subst"> <xsl:with-param name="string" select="normalize-space($command)"/> <xsl:with-param name="target" select="' '"/> <xsl:with-param name="replacement" select="'\ '"/> </xsl:call-template> + --> <xsl:text>\ 'u</xsl:text> <xsl:text> </xsl:text> - <xsl:apply-templates/> + <!-- * <xsl:apply-templates/> --> + <xsl:text>.HP \n(hPu</xsl:text> <xsl:text> </xsl:text> <xsl:call-template name="synopsis-block-end"/> <!-- * if justification is enabled by default, turn it back on --> @@ -271,7 +276,8 @@ <xsl:apply-templates select="funcdef"/> </xsl:variable> <xsl:call-template name="synopsis-block-start"/> - <xsl:text>.HP </xsl:text> + <!-- * Calculate the argument to .HP separately to avoid problems with space --> + <xsl:text>.nr hP </xsl:text> <xsl:text>\w'</xsl:text> <xsl:variable name="funcdef"> <xsl:apply-templates select="funcdef"/> @@ -283,6 +289,8 @@ </xsl:call-template> <xsl:text>('u</xsl:text> <xsl:text> </xsl:text> + <xsl:text>.HP \n(hPu</xsl:text> + <xsl:text> </xsl:text> <xsl:text>.</xsl:text> <xsl:value-of select="$man.font.funcprototype"/> <xsl:text> </xsl:text> I have not yet seen the reason for this excessive use of the "no-break space", but it is not acceptable. These patches should be applied as soon as possible by the maintainers of the package "linux-manual" to their version of the package "docbook-xsl", as there can be a longer wait for an official update of it. After applying the patches I get 14 errors caused by long lines (MANWIDTH=80). "Lintian" reports about 300 "manpage-has-errors-from-man".
#809754#10
Date:
2023-10-24 08:19:06 UTC
From:
To:
[Bjarni Ingi Gislason 2016-01-03]

Do you know if the patch  is applied upstream?  I tried applying it in
docbook-xsl/manpages/ in the Debian source package, but some of the parts
failed.

#809754#15
Date:
2023-10-24 08:41:20 UTC
From:
To:
For the record, the email to the original submitter bounced with "550
5.0.0 <bjarniig@rhi.hi.is>... User unknown".