Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

nixos manual (man configuration.nix) duplicates option names into descriptions #166304

Closed
dtzWill opened this issue Mar 29, 2022 · 1 comment · Fixed by #166509
Closed

nixos manual (man configuration.nix) duplicates option names into descriptions #166304

dtzWill opened this issue Mar 29, 2022 · 1 comment · Fixed by #166509
Assignees

Comments

@dtzWill
Copy link
Member

dtzWill commented Mar 29, 2022

Describe the bug

In recent nixos-unstable versions, my manual now has a strange formatting error. The option name, in bold, is repeated within the text describing the option. For example, first entry (bold formatting lost):

       appstream.enable
           appstream.enableWhether to install files to support the AppStream metadata specification.

           Type: boolean

           Default: true

           Declared by:
               <nixpkgs/nixos/modules/config/appstream.nix>

Steps To Reproduce

Steps to reproduce the behavior:

  1. Checkout Nixpkgs and go to 'nixos' subdirectory:
$ cd /path/to/nixpkgs/nixos
  1. Build the manpages:
$ nix-build release.nix -A manpages.x86_64-linux
  1. Look at manpage:
$ man ./result/share/man/man5/configuration.nix.5

Expected behavior

The expected text is that the line "appstream.enableWhether" instead start "Whether".

Additional context

Originally noticed it with home-manager, with report here: nix-community/home-manager#2820 .

Notify maintainers

@nbp , maybe?

Metadata

Please run nix-shell -p nix-info --run "nix-info -m" and paste the result.

$ nix-shell -p nix-info --run "nix-info -m"
 - system: `"x86_64-linux"`
 - host os: `Linux 5.17.0, NixOS, 22.05 (Quokka), 22.05pre364050.a34c788e30f`
 - multi-user?: `yes`
 - sandbox: `yes`
 - version: `nix-env (Nix) 2.8.0pre20220328_2d572a2`
 - channels(will): `""`
 - channels(root): `"home-manager, nixos"`
 - nixpkgs: `/nix/var/nix/profiles/per-user/root/channels/nixos`
@dtzWill
Copy link
Member Author

dtzWill commented Mar 30, 2022

Bisect says 2982bcb is where the duplication started occurring. cc @jtojnar .

So it looks like this broke with upgrade to libxslt 1.1.35.


In case it helps anyone looking into this, the bisect script was essentially:

#!/bin/sh
nix build -f nixos/release.nix manpages.x86_64-linux
! grep -F 'enable\fR\fR\m[]Whether' -q ./result/share/man/man5/configuration.nix.5

(I used a slightly different formulation, but this works 👍).


libxslt 1.1.35 release notes, FWIW.
Not sure if this is our issue, but they do start off mentioning a breaking change: (?)

Note that conflict resolution for templates was fixed to match the spec. When there are multiple matching templates with the same priority, libxslt now uses the template that occurs last in the stylesheet. This can potentially break stylesheets that rely on the old, badly predictable and non-conformant behavior. The solution is to reorder affected templates.

@jtojnar jtojnar self-assigned this Mar 30, 2022
jtojnar added a commit to jtojnar/nixpkgs that referenced this issue Apr 3, 2022
libxslt 1.1.35 fixed conflict resolution for templates to match the specification.
This uncovered a bug in docbook-xsl (docbook/xslt10-stylesheets#240),
which causes option names to be duplicated into the option descriptions.

Let’s resolve the conflict by patching the stylesheets.

Fixes: NixOS#166304
arcnmx pushed a commit to arcnmx/nmd that referenced this issue Jul 21, 2022
Should fix duplicate option names into the manpages generated with nmd.
See:
- NixOS/nixpkgs#166304
- NixOS/nixpkgs#166509
- nix-community/home-manager#2820
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants