[xml/sgml-pkgs] Bug#809754: docbook-xsl: manpages: Misuse of "no-break space" causes overlong lines
Bjarni Ingi Gislason
bjarniig at rhi.hi.is
Sun Jan 3 18:16:49 UTC 2016
Package: docbook-xsl
Version: 1.78.1+dfsg-1
Severity: normal
Tags: patch
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".
-- System Information:
Debian Release: 8.2
APT prefers stable
APT policy: (990, 'stable'), (500, 'stable-updates'), (500, 'proposed-updates')
Architecture: amd64 (x86_64)
Kernel: Linux 3.16.7-ckt20-u1 (SMP w/2 CPU cores)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1)
Shell: /bin/sh linked to /bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages docbook-xsl depends on:
ii xml-core 0.13+nmu2
Versions of packages docbook-xsl recommends:
pn docbook-xml <none>
Versions of packages docbook-xsl suggests:
pn dbtoepub <none>
pn docbook-xsl-doc-html | docbook-xsl-doc-pdf | docbook-xsl-doc-text | <none>
pn docbook-xsl-saxon <none>
pn fop <none>
pn libsaxon-java <none>
pn libxalan2-java <none>
pn libxslthl-java <none>
pn xalan <none>
-- no debconf information
--
Bjarni I. Gislason
-------------- next part --------------
--- 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 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>
More information about the debian-xml-sgml-pkgs
mailing list