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

Fix problems in manual page #186

Merged
merged 1 commit into from
Nov 18, 2024
Merged

Fix problems in manual page #186

merged 1 commit into from
Nov 18, 2024

Conversation

n-peugnet
Copy link
Contributor

While packaging j4-dmenu-desktop r3.1 for Debian, I noticed a few problems in the manul page. Here is the patch that fixes them:

  • Fix two typos.
  • Fix man error message: troff: error: automatically ending diversion 'doc-enclosure-box0' on exit
    caused by the invalid link in the end.
  • Fix the appearance of the brackets around the email link.

- Fix two typos.
- Fix man error message: troff: error: automatically ending diversion 'doc-enclosure-box0' on exit
  caused by the invalid link in the end.
- Fix the appearance of the brackets around the email link.
@meator
Copy link
Collaborator

meator commented Nov 18, 2024

  • Fix the appearance of the brackets around the email link.

What's the problem here? I have tried to test your changes, but the link looks identical with and without your changes. I have tested both terminal output and HTML output. Both manpages pass mandoc -T lint without issues.

Is the erroneous behavior specific to man-db and not mdocml?

Here is a rendered version of j4-dmenu-desktop r3.1: https://man.voidlinux.org/j4-dmenu-desktop

@n-peugnet
Copy link
Contributor Author

I have tested both terminal output and HTML output. Both manpages pass mandoc -T lint without issues.

Is the erroneous behavior specific to man-db and not mdocml?

I will post screenshots when I'll be back on my PC.

The error was initially reported by lintian with the following tag: https://lintian.club1.fr/tags/groff-message.html

I really am not an expert about man pages but it shows a command for how to get the error message.

While reading the manpage with man ./j4-dmenu-desktop.1 I noticed that the last line and footer were not rendered, so I tried to modify the link and bracketing markup to make it work. Then I noticed that on my machine, the right bracket of the email link had a space before it, which looked weird, so I fixed it the same way as the last link.

@n-peugnet
Copy link
Contributor Author

n-peugnet commented Nov 18, 2024

Here are the problems fixed (in addition to the typos):

$ LC_ALL=C.UTF-8 MANROFFSEQ='' MANWIDTH=80 man --warnings -E UTF-8 -l -Tutf8 -Z ./j4-dmenu-desktop.1 >/dev/null
troff: automatically ending diversion 'doc-enclosure-box0' on exit

Then by running man ./j4-dmenu-desktop.1, at the end of the page.

Before:
2024-11-18-140043_677x239_scrot

After:
2024-11-18-140152_682x285_scrot

@meator
Copy link
Collaborator

meator commented Nov 18, 2024

This is strange. I have verified that this issue is specific to man-db, mdocml works as expected.

I still believe that j4-dmenu-desktop's manpge (which I've rewritten in mdoc: #126 several years ago) is written in valid mdoc. The HTML manpage of j4-dmenu-desktop which I've linked shows no space before the final >. But I'll merge this PR anyway to support users of man-db.

Ah, the joys of working with documentation systems from the nineties...

@meator meator merged commit bf34aac into enkore:develop Nov 18, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants