xdg-user-dir man page missing XDG user dir names

l0b0 commented 7 months ago

Issue description

This is the entire man page as shown on nixos-unstable:

XDG-USER-DIR(1)                                User Commands                                XDG-USER-DIR(1)

NAME
       xdg-user-dir - Find an XDG user dir

SYNOPSIS

       xdg-user-dir [NAME]

DESCRIPTION
       xdg-user-dir looks up the current path for one of the special XDG user dirs.

       This command expects the name of an XDG user dir as argument. The possible names are:

FILES
       The values are looked up in the user-dirs.dirs file. This file is created by the
       xdg-user-dirs-update utility.

ENVIRONMENT
       The XDG_CONFIG_HOME environment variable determines where the user-dirs.dirs file is located.

SEE ALSO
       xdg-user-dirs-update(1)

XDG                                                                                         XDG-USER-DIR(1)

After "The possible names are:" the list of names as shown for example here is missing.

Steps to reproduce

man xdg-user-dir

Technical details

system: "x86_64-linux"
host os: Linux 6.6.22, NixOS, 24.05 (Uakari), 24.05pre601756.44d0940ea560
multi-user?: yes
sandbox: yes
version: nix-env (Nix) 2.18.1
channels(root): "nixos"
channels(username): ""
nixpkgs: /nix/var/nix/profiles/per-user/root/channels/nixos

eclairevoyant commented 7 months ago

It's due to the borked formatting of the manpage itself:

$ gzip -d $(nix-build '<nixpkgs>' -A xdg-user-dirs)/share/man/man1/xdg-user-dir.1.gz -c | bat -r 40:43 -p
This command expects the name of an XDG user dir as argument\&. The possible names are:
.RS 4 DESKTOP .RE .RS 4 DOWNLOAD .RE .RS 4 TEMPLATES .RE .RS 4 PUBLICSHARE .RE .RS 4 DOCUMENTS .RE .RS 4 MUSIC .RE .RS 4 PICTURES .RE .RS 4 VIDEOS .RE
.SH "FILES"
.PP

Each macro should be on its own line, i.e.:

.RS 4
DESKTOP
.RE
.RS 4
DOWNLOAD
.RE

l0b0 commented 7 months ago

It's due to the borked formatting of the manpage itself:

I'd rather suspect that our parser is non-standard, since other places have generated correct man pages: 1, 2, 3.

eclairevoyant commented 7 months ago

It has nothing to do with any "parser". Arch for example correctly puts each macro on its own line.

$ gzip -d /usr/share/man/man1/xdg-user-dir.1.gz -c | bat -r 40:43 -p
This command expects the name of an XDG user dir as argument\&. The possible names are:
.RS 4
DESKTOP

Something's borked on the DocBook XSLT side of things.

Though the stylesheet has the newlines, same as Arch:

$ bat $(nix-build '<nixpkgs>' -A docbook_xsl)/xml/xsl/docbook/manpages/lists.xsl -r 344:356 -p

<xsl:template match="simplelist">
  <xsl:for-each select="member">
    <xsl:text>.RS</xsl:text>
    <xsl:if test="not($list-indent = '')">
      <xsl:text> </xsl:text>
      <xsl:value-of select="$list-indent"/>
    </xsl:if>
    <xsl:text>&#10;</xsl:text>
    <xsl:apply-templates/>
    <xsl:text>&#10;</xsl:text>
    <xsl:text>.RE&#10;</xsl:text>
  </xsl:for-each>
</xsl:template>

so I gave up figuring out what's going on.

KucharczykL commented 2 months ago

The man page for xdg-mime is completely borked:

XDG-MIME(1)                                                 xdg-mime Manual                                                XDG-MIME(1)

  .SH "NAME" xdg-mime - command line tool for querying information about file type handling and adding descriptions for new file types

  .SH "SYNOPSIS"

    .HP 216u

      xdg-mime
       query
       {       | filetype FILE       | default mimetype
      }

    .HP 216u

      xdg-mime
       default
       application
       mimetype(s)

    .HP 216u

      xdg-mime
       install
       [--mode mode]
       [--novendor]
       mimetypes-file

    .HP 216u

      xdg-mime
       uninstall
       [--mode mode]

I compared the version in NixOS with a version on Nobara (Fedora-based distro) and for some reason the NixOS version has some kind of indentation applied which I guess makes the source file not valid (not familiar with source format). It's also curious that the build dates are not set in the NixOS version.

--- (nix-build '<nixpkgs>' -A xdg-utils)/share/man/man1/xdg-mime.1.gz   2024-08-02 21:34:19.537426668 +0200
+++ /mnt/nobara-root/usr/share/man/man1/xdg-mime.1.gz   2024-08-02 21:34:19.540081461 +0200
@@ -1,13 +1,13 @@
 '\" t
 .\"     Title: xdg-mime
 .\"    Author: Kevin Krammer
-.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
-.\"      Date: 01/01/1980
+.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
+.\"      Date: 02/11/2024
 .\"    Manual: xdg-mime Manual
 .\"    Source: xdg-utils 1.0
 .\"  Language: English
 .\"
-.TH "XDG\-MIME" "1" "01/01/1980" "xdg-utils 1.0" "xdg-mime Manual"
+.TH "XDG\-MIME" "1" "02/11/2024" "xdg-utils 1.0" "xdg-mime Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -27,95 +27,35 @@
 .\" -----------------------------------------------------------------
 .\" * MAIN CONTENT STARTS HERE *
 .\" -----------------------------------------------------------------
-
-  
-
-  
-
-  .SH "NAME"
+.SH "NAME"
 xdg-mime \- command line tool for querying information about file type handling and adding descriptions for new file types
-
-
-  .SH "SYNOPSIS"
-
-    .HP \w'\fBxdg\-mime\fR\ 'u
-
-      \fBxdg\-mime\fR
-       query
-       {
-    | filetype\ \fIFILE\fR
-    | default\ \fImimetype\fR
-      }
-    
-
-    .HP \w'\fBxdg\-mime\fR\ 'u
-
-      \fBxdg\-mime\fR
-       default
-       \fIapplication\fR
-       \fImimetype(s)\fR
-    
-
-    .HP \w'\fBxdg\-mime\fR\ 'u
-
-      \fBxdg\-mime\fR
-       install 
-       [\fB\-\-mode\ \fR\fB\fImode\fR\fR]
-       [\fB\-\-novendor\fR]
-       \fImimetypes\-file\fR
-    
-
-    .HP \w'\fBxdg\-mime\fR\ 'u
-
-      \fBxdg\-mime\fR
-       uninstall   
-       [\fB\-\-mode\ \fR\fB\fImode\fR\fR]
-       \fImimetypes\-file\fR
-    
-
-    .HP \w'\fBxdg\-mime\fR\ 'u
-
-      \fBxdg\-mime\fR
-       {
-         | \fB\-\-help\fR
-         | \fB\-\-manual\fR
-         | \fB\-\-version\fR
-      }
-    
-
-  
-
-  .SH "DESCRIPTION"
-
-    
-    .PP
+.SH "SYNOPSIS"
+.HP \w'\fBxdg\-mime\fR\ 'u
+\fBxdg\-mime\fR query {filetype\ \fIFILE\fR | default\ \fImimetype\fR}
+.HP \w'\fBxdg\-mime\fR\ 'u
+\fBxdg\-mime\fR default \fIapplication\fR \fImimetype(s)\fR
+.HP \w'\fBxdg\-mime\fR\ 'u
+\fBxdg\-mime\fR install [\fB\-\-mode\ \fR\fB\fImode\fR\fR] [\fB\-\-novendor\fR] \fImimetypes\-file\fR
+.HP \w'\fBxdg\-mime\fR\ 'u
+\fBxdg\-mime\fR uninstall [\fB\-\-mode\ \fR\fB\fImode\fR\fR] \fImimetypes\-file\fR
+.HP \w'\fBxdg\-mime\fR\ 'u
+\fBxdg\-mime\fR {\fB\-\-help\fR | \fB\-\-manual\fR | \fB\-\-version\fR}
+.SH "DESCRIPTION"
+.PP
 The xdg\-mime program can be used to query information about file types and to add descriptions for new file types\&.
-
-  
-  .SH "COMMANDS"
-
-    
-    
-
-      .PP
+.SH "COMMANDS"
+.PP
 query file
 .RS 4
-
-   
-   
-     Returns the file type of
+Returns the file type of
 \fIFILE\fR
 in the form of a MIME type\&.
 .sp
-
-     Please note that
+Please note that
 \fIFILE\fR
 names starting with a
 \-
 will be rejected, this can be mitigated:
-
-      
-        
 .sp
 .RS 4
 .ie n \{\
@@ -129,7 +69,6 @@
 \fBrealpath\fR
 as a preprocessor\&.
 .RE
-       
 .sp
 .RS 4
 .ie n \{\
@@ -144,81 +83,55 @@
 sed \-E \*(Aqs|^[^/]|\&./\e0|\*(Aq
 as a preprocessor\&.
 .RE
-      .sp
-
-     The
+.sp
+The
 \fIquery file\fR
 option is for use inside a desktop session only\&. It is not recommended to use xdg\-mime query file as root\&.
-
-   
-      .RE
-
-      .PP
+.RE
+.PP
 query default
 .RS 4
<snip>

NixOS / nixpkgs