Skip to content

doc: fix errors and style warnings to unblock CI - #5213

Merged
zyv merged 9 commits into
masterfrom
doc_man_fixes
Nov 4, 2026
Merged

zyv merged 9 commits into
masterfrom
doc_man_fixes

Conversation

@zyv

@zyv zyv commented Nov 4, 2026

Copy link
Copy Markdown
Member

Proposed changes

After the latest Fedora release (44 → 45) came out, our CI went red for master due to stricter style checks in the new version of groff. I took this opportunity to drive mandoc and man2help warnings to zero and extend the doc linter so that they don't come back.

@lucianpopovici, could you please have a look? It would make sense to merge this ASAP to unblock the CI, and in any case before any work on #5208. Thanks!

Checklist

  • I have referenced the issue(s) resolved by this PR (if any)
  • I have signed-off my contribution with git commit --amend -s
  • Lint and unit tests pass locally with my changes (make indent && make check)
  • I have added tests that prove my fix is effective or that my feature works
  • I have added the necessary documentation (if appropriate)

zyv added 9 commits November 4, 2026 16:44
Commit 5fecc8d (ticket #4865) added the %v/%V entry with its .TP in
front instead of after it, so %u/%U got merged into the %v/%V
description.

groff 1.24 (Fedora 45) warns about the resulting empty .TP, which
makes maint/doctest.py fail in CI:

  warning: cannot nest .TP or .TQ inside .TP; supply a tag

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
These .TP requests have no tag line after them:

* es: the three translator's notes start with .TP followed by .PP.
  groff renders the note title as an indented hanging tag and narrows
  the following entries up to the next section; man2hlp indents the
  notes.  mandoc shows a plain paragraph as intended.

* sr: a .TP before the "Overview" node, added in a37e415, turns the
  section heading into an indented list item in groff and man2hlp.

Found with `mandoc -T lint` ("line scope broken").

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
.PP takes no arguments, so groff, mandoc and man2hlp silently drop
any text on the same line:

* hu: the sentence about Emacs-like input lost "A Midnight Commander".
* it: the "Usa le unità SI" option lost its name; mark it up like the
  other options in that list.

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
.RE without a matching .RS was only used to put the two system-wide
mc.ini paths on separate lines.  .br does that without the "unbalanced
.RE" warning; groff and man2hlp output is unchanged.

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
Help links must use the English node name, so the "Opzioni del
pannello" link was dead; man2hlp reported it as stale.

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
Commit 25da880 removed the "Undelete File System" section, but the
VFS overview in every man page still listed undelfs, and the Russian
one kept a help link to the removed node, which man2hlp reported as
stale.

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
.BR alternates bold and roman between its arguments, so with a single
argument it is just .B, and groff's style check (-rCHECKSTYLE=1) warns
about it.  The output is unchanged.

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
Drop .PP, .LP, .P, .br and blank lines that directly follow a section
heading or sit next to another paragraph break.  groff and mandoc
already ignore them (mandoc warns "skipping paragraph macro"), so the
man page output is unchanged.  In the built-in help, a few doubled
blank lines become single, and some pages no longer end with an empty
line, as most English ones already do.

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
Only groff warnings were checked, so markup bugs that groff silently
tolerates kept creeping in.  Add:

* -rCHECKSTYLE=1 for groff/nroff (e.g. one-argument .BR, unbalanced .RE)
* mandoc -T lint -W warning (e.g. tag-less .TP, text after .PP,
  redundant paragraph macros), ignoring the placeholder date
* man2hlp on every mc.1.in to catch stale help links

All of these tools are already installed in the Fedora CI job.

Assisted-By: Claude Opus 5.5
Signed-off-by: Yury V. Zaytsev <yury@shurup.com>
@zyv
zyv requested a review from mc-worker November 4, 2026 17:13
@github-actions github-actions Bot added needs triage Needs triage by maintainers prio: medium Has the potential to affect progress labels Nov 4, 2026
@github-actions github-actions Bot added this to the Future Releases milestone Nov 4, 2026
@zyv zyv added area: docs Improvements or additions to documentation and removed needs triage Needs triage by maintainers labels Nov 4, 2026
@zyv zyv modified the milestones: Future Releases, 4.9.0 Nov 4, 2026
@zyv zyv mentioned this pull request Nov 4, 2026
3 tasks done
@zyv
zyv merged commit d53bd82 into master Nov 4, 2026
25 of 26 checks passed
@zyv
zyv deleted the doc_man_fixes branch November 4, 2026 19:45
lucianpopovici added a commit to lucianpopovici/mc that referenced this pull request Nov 5, 2026
Regenerate doc/man/ro from the updated translations with the current
English pages, which brings in the fixes of the English pages from
MidnightCommander#5213, the working links of the built-in help, and the translation of
the strings changed since. Use "structura arborescentă" for the
directory tree.

Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
lucianpopovici added a commit to lucianpopovici/mc that referenced this pull request Nov 8, 2026
Regenerate doc/man/ro from the updated translations with the current
English pages, which brings in the fixes of the English pages from
MidnightCommander#5213, the working links of the built-in help, and the translation of
the strings changed since. Use "structura arborescentă" for the
directory tree.

Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
lucianpopovici added a commit to lucianpopovici/mc that referenced this pull request Nov 8, 2026
Regenerate doc/man/ro from the updated translations with the current
English pages, which brings in the fixes of the English pages from
MidnightCommander#5213, the working links of the built-in help, and the translation of
the strings changed since. Use "structura arborescentă" for the
directory tree.

Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
lucianpopovici added a commit to lucianpopovici/mc that referenced this pull request Nov 9, 2026
Regenerate doc/man/ro from the updated translations with the current
English pages, which brings in the fixes of the English pages from
MidnightCommander#5213, the working links of the built-in help, and the translation of
the strings changed since. Use "structura arborescentă" for the
directory tree.

Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
lucianpopovici added a commit to lucianpopovici/mc that referenced this pull request Nov 9, 2026
Regenerate doc/man/ro from the updated translations with the current
English pages, which brings in the fixes of the English pages from
MidnightCommander#5213, the working links of the built-in help, and the translation of
the strings changed since. Use "structura arborescentă" for the
directory tree.

Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
lucianpopovici added a commit to lucianpopovici/mc that referenced this pull request Nov 9, 2026
Regenerate doc/man/ro from the updated translations with the current
English pages, which brings in the fixes of the English pages from
MidnightCommander#5213, the working links of the built-in help, and the translation of
the strings changed since. Use "structura arborescentă" for the
directory tree.

Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
lucianpopovici added a commit to lucianpopovici/mc that referenced this pull request Nov 9, 2026
Add the Romanian translation of the mc, mcedit, mcview and mcdiff man
pages, generated with maint/sync-transifex/man-from-transifex.py, and
wire the new doc/man/ro directory into the build: ALL_DOC_LINGUAS and
AC_CONFIG_FILES in configure.ac, and DIST_SUBDIRS in doc/man/Makefile.am.

Unlike the other languages, doc/man/ro/Makefile.am builds all four man
pages; mcedit.1 and mcdiff.1 only if the editor and the diff viewer are
enabled.

The translation is based on the existing Romanian translation of the
man pages on Transifex by Arthur Țițeică, merged with the current
English pages (including the fixes from MidnightCommander#5213) and reviewed string by
string. The terms follow the Romanian interface, e.g. "ghid" for the
help viewer and the dialog and option names as the program shows them.

Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
lucianpopovici added a commit to lucianpopovici/mc that referenced this pull request Nov 16, 2026
Add the Romanian translation of the mc, mcedit, mcview and mcdiff man
pages, generated with maint/sync-transifex/man-from-transifex.py, and
wire the new doc/man/ro directory into the build: ALL_DOC_LINGUAS and
AC_CONFIG_FILES in configure.ac, and DIST_SUBDIRS in doc/man/Makefile.am.

Unlike the other languages, doc/man/ro/Makefile.am builds all four man
pages; mcedit.1 and mcdiff.1 only if the editor and the diff viewer are
enabled.

The translation is based on the existing Romanian translation of the
man pages on Transifex by Arthur Țițeică, merged with the current
English pages (including the fixes from MidnightCommander#5213) and reviewed string by
string. The terms follow the Romanian interface, e.g. "ghid" for the
help viewer and the dialog and option names as the program shows them.

Assisted-By: Claude Opus 5.5
Signed-off-by: Lucian Popovici <lucian.popovici@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs Improvements or additions to documentation prio: medium Has the potential to affect progress

Development

Successfully merging this pull request may close these issues.

2 participants