bug#52909: Some man pages are not built correctly

bug#52909: Some man pages are not built correctly

[Leo Famulari]

On Guix Git commit c7d74a9bccfc1b1274fc8754a6e78bb6887c7fea, at least
some manpages are not being built correctly for packages such as elogind
and gnome-keyring-daemon. Are we seeing raw groff input? I'm not sure of
the technology used here.

bug#52909: Some man pages are not built correctly

[Maxim Cournoyer]

Hi Leo,

Leo Famulari <leo@famulari.name> writes:

> On Guix Git commit c7d74a9bccfc1b1274fc8754a6e78bb6887c7fea, at least
> some manpages are not being built correctly for packages such as elogind
> and gnome-keyring-daemon. Are we seeing raw groff input? I'm not sure of
> the technology used here.

Thank you for reporting this.  I've noticed them too, and somehow
thought the technology was broken.

The technology is docbook xml and xlstproc to transform the source into
man pages (which are in the nroff format, I think).

I've read the same kind of issue reported to the bind9
project and its resolution, which was very helpful:
https://gitlab.isc.org/isc-projects/bind9/-/issues/2310.  It seems it's
a DocBook XSL stylesheet problem resolved in
https://github.com/docbook/xslt10-stylesheets/pull/111 but not yet
released...

My first idea was to apply this patch, so I went ahead and made:

--8<---------------cut here---------------start------------->8---
modified   gnu/packages/docbook.scm
@@ -229,6 +229,14 @@ (define name-version
      "This package provides XSL style sheets for DocBook.")
     (license (license:x11-style "" "See 'COPYING' file."))))
 
+(define-public docbook-xsl/fixed
+  (package/inherit docbook-xsl
+    (name "docbook-xsl-fixed")
+    (source (origin
+              (inherit (package-source docbook-xsl))
+              (patches (search-patches
+                        "docbook-xsl-allow-non-namespace-fix.patch"))))))
+
 (define-public docbook-xsl-ns
   (package
     (name "docbook-xsl-ns")
new file   gnu/packages/patches/docbook-xsl-allow-non-namespace-fix.patch
@@ -0,0 +1,60 @@
+Retrieved from https://github.com/docbook/xslt10-stylesheets/pull/111.
+
+diff --git a/common/common.xsl b/common/common.xsl
+index 59f51dfd0..80742b6ce 100644
+--- a/common/common.xsl
++++ b/common/common.xsl
+@@ -68,7 +68,6 @@ d:subjectset d:substeps d:synopfragment d:table d:tbody d:textobject d:tfoot d:t
+ d:thead d:tip d:toc d:tocchap d:toclevel1 d:toclevel2 d:toclevel3 d:toclevel4
+ d:toclevel5 d:tocpart d:topic d:varargs d:variablelist d:varlistentry d:videodata
+ d:videoobject d:void d:warning d:subjectset
+-
+ d:classsynopsis
+ d:constructorsynopsis
+ d:destructorsynopsis
+@@ -81,6 +80,45 @@ d:oointerface
+ d:simplemsgentry
+ d:manvolnum
+ "/>
++<xsl:strip-space elements="
++abstract affiliation anchor answer appendix area areaset areaspec
++artheader article audiodata audioobject author authorblurb authorgroup
++beginpage bibliodiv biblioentry bibliography biblioset blockquote book
++bookinfo callout calloutlist caption caution chapter
++citerefentry cmdsynopsis co collab colophon colspec confgroup
++copyright dedication docinfo editor entrytbl epigraph equation
++example figure footnote footnoteref formalpara funcprototype
++funcsynopsis glossary glossdef glossdiv glossentry glosslist graphicco
++group highlights imagedata imageobject imageobjectco important index
++indexdiv indexentry indexterm info informalequation informalexample
++informalfigure informaltable inlineequation inlinemediaobject
++itemizedlist itermset keycombo keywordset legalnotice listitem lot
++mediaobject mediaobjectco menuchoice msg msgentry msgexplan msginfo
++msgmain msgrel msgset msgsub msgtext note objectinfo
++orderedlist othercredit part partintro preface printhistory procedure
++programlistingco publisher qandadiv qandaentry qandaset question
++refentry reference refmeta refnamediv refsection refsect1 refsect1info refsect2
++refsect2info refsect3 refsect3info refsynopsisdiv refsynopsisdivinfo
++revhistory revision row sbr screenco screenshot sect1 sect1info sect2
++sect2info sect3 sect3info sect4 sect4info sect5 sect5info section
++sectioninfo seglistitem segmentedlist seriesinfo set setindex setinfo
++shortcut sidebar simplelist simplesect spanspec step subject
++subjectset substeps synopfragment table tbody textobject tfoot tgroup
++thead tip toc tocchap toclevel1 toclevel2 toclevel3 toclevel4
++toclevel5 tocpart topic varargs variablelist varlistentry videodata
++videoobject void warning subjectset
++classsynopsis
++constructorsynopsis
++destructorsynopsis
++fieldsynopsis
++methodparam
++methodsynopsis
++ooclass
++ooexception
++oointerface
++simplemsgentry
++manvolnum
++"/>
+ <!-- ====================================================================== -->
+ 
+ <doc:template name="is.component" xmlns="">
--8<---------------cut here---------------end--------------->8---

Unfortunately the resulting docbook-xsl/fixed package doesn't seem to
work.

Based on this knowledge (from the same issue linked above):

> When using version 1.79.1 or 1.79.2 of the XSL stylesheets, care must
> be taken to ensure the namespaced stylesheets are used for generating
> BIND documentation.

--8<---------------cut here---------------start------------->8---
modified   gnu/packages/samba.scm
@@ -269,7 +269,7 @@ (define-public samba
        ("rpcsvc-proto" ,rpcsvc-proto)   ; for 'rpcgen'
        ;; For generating man pages.
        ("docbook-xml" ,docbook-xml-4.2)
-       ("docbook-xsl" ,docbook-xsl)
+       ("docbook-xsl" ,docbook-xsl-ns)
        ("xsltproc" ,libxslt)
        ("libxml2" ,libxml2)))           ;for XML_CATALOG_FILES
     (home-page "https://www.samba.org/")
--8<---------------cut here---------------end--------------->8---

But that also doesn't work...

Ahem...

I guess we'll need to wait for Docbook to fix their things and issue a
new release, else use one of their snapshots.

On an unrelated (to the problem at hand note) I've also realized my
confusion in adding a docbook-xsl-ns package.  The legacy suffix (1.79.1
and older) )was inverted for 1.79.2 (-ns was removed, so the docbook-xsl
*is* namespaced while -nons was added to denote the non-namespaced
version).

I should probably get rid of this docbook-xsl-ns package unless 1.79.1
is truly needed and replace it by docbook-xsl-nons.  I tried to use this
with samba but it also didn't work.

That's frustrating!

Good night,

Maxim

bug#52909: Some man pages are not built correctly

[Maxim Cournoyer]

Hi,

Maxim Cournoyer <maxim.cournoyer@gmail.com> writes:

> Hi Leo,
>
> Leo Famulari <leo@famulari.name> writes:
>
>> On Guix Git commit c7d74a9bccfc1b1274fc8754a6e78bb6887c7fea, at least
>> some manpages are not being built correctly for packages such as elogind
>> and gnome-keyring-daemon. Are we seeing raw groff input? I'm not sure of
>> the technology used here.

[...]

> I've read the same kind of issue reported to the bind9
> project and its resolution, which was very helpful:
> https://gitlab.isc.org/isc-projects/bind9/-/issues/2310.  It seems it's
> a DocBook XSL stylesheet problem resolved in
> https://github.com/docbook/xslt10-stylesheets/pull/111 but not yet
> released...

This is now fixable in an ad-hoc fashion on master by replacing the
problematic docbook-xsl with docbook-xsl-next, and fixed for good on
core-updates.

Closing.

Thanks,

Maxim