Skip to content

docs/man: bring English masters back in sync with the source (#893) - #900

Merged
mrjimenez merged 2 commits into
amule-project:masterfrom
got3nks:docs/man-page-audit-fixes
Jun 7, 2026
Merged

docs/man: bring English masters back in sync with the source (#893)#900
mrjimenez merged 2 commits into
amule-project:masterfrom
got3nks:docs/man-page-audit-fixes

Conversation

@got3nks

@got3nks got3nks commented Jun 7, 2026

Copy link
Copy Markdown
Contributor

Refs #893.

Addresses the @ngosang audit of the English man-page masters against the current source. One commit, one file per logical change, all verified against the cited source lines.

What's in

File Fix
amule.1.in / amuled.1.in / amulegui.1.in Add --configure-autostart <on|off>. The option lives outside the AMULE_DAEMON ifdef in amuleAppCommon.cpp:281-282; the handler at :341-360 calls AutostartManager::Enable(), which registers whichever binary was invoked — so it works for all three.
amulegui.1.in Add -d/--disable-fatal and -i/--enable-stdin (defined for non-Windows builds at amuleAppCommon.cpp:312-316).
amuled.1.in Add the missing <num> argument on the -t/--category short form so it matches -c <path> / -p <path> / -w <path> formatting.
amulecmd.1.in Stop attaching -v to --version and -h to --help. -v is --verbose (ExternalConnector.cpp:503) and -h is --host (:488); --version and --help have no short form (:485, :515). The SYNOPSIS was already correct. Add --force-zlib (:518-520).
amuleweb.1.in Add --force-zlib. Fix -U/--upnp-port formatting to use = before <port> instead of a space (matches every other value-taking option on the page).
ed2k.1.in The parser at ED2KLinkParser.cpp:482-486 reads --category's value as the next argv token; there is no --category= substr-match branch (unlike --config-dir= at :461). Fix the page to show the space-separated syntax. Also fix grammar: "all link found" → "all links found".
cas.1.in Rewrite FILES section to reflect the actual runtime outputs (aMule-online-sign.{png,jpg,html} per graphics.c:79-81 + html.c:113; the old stat.png / tmp.html entries are repo template files, not runtime outputs). Note the -o/--picture requires GD compiled in (handlers behind #ifdef __GD__ at cas.c:194-202; silently no-op otherwise). Clarify "optional <PATH>": only the long forms are optional_argument; the short -P/-H require a separate argument and -o/-p are no-arg switches per optstring "c:P:H:hpo" at :177.

What's deliberately out

  • -h/--help wording on amuled / alcc that ngosang flagged ("Prints a short usage description." vs source "Displays this information." / "show this help message"). Man-page wording is the clearer English; source side is what should sync if anyone wants the two aligned. Same divergence exists on amule.1.in which the audit didn't flag.
  • "eD2k" vs "ED2K" capitalization. Man pages have the canonical eDonkey2000 abbrev right; the source-side help strings at amuleAppCommon.cpp:320-321 are the inconsistent ones.
  • Low-priority observations on alc.1.in and wxcas.1.in — left for a future pass.

Translations / .pot regen

Intentionally not in this PR. A single po4a --no-translations --force pass right before the 3.0.0 tag will pick up these changes AND the stale #: source refs flagged in #894 in one step, per the plan in amule-org/amule-org.github.io#4.

got3nks added 2 commits June 7, 2026 12:57
Addresses the audit in amule-project#893 against the current
src/amuleAppCommon.cpp, src/ExternalConnector.cpp,
src/ED2KLinkParser.cpp, src/utils/cas/cas.c +
src/utils/aLinkCreator/src/alcc.cpp.

amule.1.in / amuled.1.in / amulegui.1.in:
  add --configure-autostart <on|off>. The option lives outside the
  AMULE_DAEMON ifdef in amuleAppCommon.cpp:281-282, and the handler
  at :341-360 calls AutostartManager::Enable() which registers
  whichever binary is invoked -- so it works for all three.

amulegui.1.in:
  add -d/--disable-fatal and -i/--enable-stdin (defined for
  non-Windows builds at amuleAppCommon.cpp:312-316; already
  documented in amule.1.in / amuled.1.in).

amuled.1.in:
  add the missing <num> argument to the -t/--category entry to
  match the formatting of -c/-p/-w.

amulecmd.1.in:
  - fix the DESCRIPTION block to stop attaching -v to --version and
    -h to --help. -v is --verbose (ExternalConnector.cpp:503) and -h
    is --host (:488); --version and --help have no short form. The
    SYNOPSIS was already correct; the page contradicted itself.
  - add --force-zlib (ExternalConnector.cpp:518-520), inherited
    from CaMuleExternalConnector::OnInitCmdLine and missing from
    every page that consumes it.

amuleweb.1.in:
  - add --force-zlib (same source).
  - fix the -U/--upnp-port formatting to use '=' before <port>
    instead of a space, matching every other value-taking option on
    the page.

ed2k.1.in:
  - fix the description of -t/--category to use the space-separated
    "--category <num>" syntax the parser actually accepts; the page
    showed "--category=<num>" but ED2KLinkParser.cpp:482-486 reads
    the value as the next argv token. (--config-dir=<path> is
    handled separately at :461.)
  - fix grammar: "all link found" -> "all links found".

cas.1.in:
  - rewrite FILES section to reflect what cas actually writes:
    aMule-online-sign.png/.jpg via graphics.c:79-81, and
    aMule-online-sign.html via html.c:113. The previous stat.png /
    tmp.html entries were repo template files, not runtime outputs.
  - note that -o/--picture requires GD support (-P/-o handlers are
    behind #ifdef __GD__ at cas.c:194-202).
  - clarify the "optional <PATH>" claim: only the long forms
    (--picture, --html) are optional_argument; the short forms -P/-H
    require an argument and -o/-p are no-argument switches per the
    optstring "c:P:H:hpo" at cas.c:177.

The audit also flagged amuled.1.in and alcc.1.in's -h/--help
descriptions ("Prints a short usage description.") as divergent
from the source --help text ("Displays this information." /
"show this help message"). Deliberately not changing those -- the
man-page wording is clearer English and the source side is the one
that should sync if anyone wants the two aligned; the same
divergence exists on amule.1.in which the audit didn't flag.

The "eD2k" vs "ED2K" capitalization audit items are deliberately
NOT addressed: the man pages have the canonical eDonkey2000 abbrev
("eD2k") correct; the source-side help strings at amuleAppCommon.cpp:
320-321 are the inconsistent ones. Fixing the source is a separate
concern. Likewise the low-priority observations on alc.1.in /
wxcas.1.in are left for a future pass.

The matching docs/man/po/manpages.pot regeneration is intentionally
not in this PR -- a single \`po4a --no-translations --force\` pass
right before the 3.0.0 tag will pick up both these changes and the
stale #: source refs flagged in amule-project#894 in one step.

Refs amule-project#893.
<on|off> are the literal token values the parser checks for at
amuleAppCommon.cpp:344-347, not descriptive placeholders. Localizing
them (e.g. <acceso|spento>) would produce man pages that lie about
what aMule accepts. Switch the SYNOPSIS and description signature
lines to the .RB_untranslated / .B_untranslated form so po4a excludes
them from manpages.pot extraction. Same render — the aliases at the
top of each file map *_untranslated to the standard B/RB macros.

Consistent with the prior-art at amulecmd.1.in:91 where the literal
Connect subcommand list (kad / ed2k / <ip|name>) already uses
.SS_untranslated.
@mrjimenez
mrjimenez merged commit 018e095 into amule-project:master Jun 7, 2026
7 checks passed
@got3nks got3nks mentioned this pull request Jun 7, 2026
got3nks added a commit to got3nks/amule that referenced this pull request Jun 7, 2026
Picks up the entries left untranslated or marked fuzzy after the
preceding pot/po regen pass:

* po/it.po -- 14 untranslated installer-string entries (extracted
  from packaging/windows/installer_strings.c via amule-project#899) and 4 fuzzy
  entries:
  - 'Uninstall' had been msgmerge-mapped to the existing 'Installa'
    translation (wrong direction); fixed to 'Disinstalla'.
  - 'aMule application files (required).' had been msgmerge-mapped to
    the existing 'Integrazione di aMule non riuscita' translation
    (unrelated); fixed to the literal 'File dell'applicazione aMule
    (obbligatori).'.
  - 'Start aMule when I log in' kept the substantively correct
    existing translation, just unfuzzied.
  - The web-server-startup message updated to reference the
    -DBUILD_WEBSERVER=YES CMake flag we use today.

* docs/man/po/manpages-it.po -- 9 untranslated entries (the new
  --configure-autostart / --force-zlib / -t/--category / -o-and-p
  optional-arg / GD-support / aMule-online-sign FILES entries from
  the amule-project#900 audit fixes) and 5 fuzzy entries on synopsis lines and
  the 'all link found' grammar fix.

Refs amule-org/amule-org.github.io#4.
mrjimenez pushed a commit that referenced this pull request Jun 7, 2026
Pre-release pot/po refresh ahead of 3.0.0. Driven by
scripts/update-po.sh which runs xgettext over POTFILES.in to
regenerate po/amule.pot and then msgmerge into every po/*.po.

The substantive change picked up by this sweep is the 16 Windows-
installer translatable strings extracted into amule.pot via the
packaging/windows/installer_strings.c stub added in #899 (the
LangString MYSTR_* set used by packaging/windows/installer.nsi via
the po-to-nsh.py bridge). Each catalog gains those 16 entries with
empty msgstr; translators see them in the next .po edit session and
the installer build's bridge script flips them from English
fallback to the translated text as soon as a non-empty msgstr is
present.

The bulk of the diff outside that is cosmetic: gettext-tools 0.27
rewraps some long strings differently than whatever version last
ran an update on the committed catalogs, and the #: source-location
refs shift by a few lines as source files have moved on since the
last sweep. No msgid content was lost; no existing translation was
discarded -- fuzzy markers grow only on entries whose source string
genuinely changed (e.g. man-page strings touched by the audit
fixes in #900).

Refs amule-org/amule-org.github.io#4 (pre-3.0.0 housekeeping).
mrjimenez pushed a commit that referenced this pull request Jun 7, 2026
Pre-release pot/po refresh ahead of 3.0.0. Runs

  cd docs/man && po4a --no-translations --force po4a.config

which re-walks the .1.in masters listed in po4a.config and rebuilds
docs/man/po/manpages.pot + each docs/man/po/manpages-<lang>.po from
scratch.

Two things land in this sweep:

  1. The stale #: source refs flagged in #894 now point at the
     templated masters they actually come from. All 297 #: lines
     read "*.1.in" (none of the old "*.1" form remain) -- in sync
     with po4a.config since the 5c9781e + a89d1e3 rename.

  2. The new msgids introduced by the man-page audit fixes in #900
     (--configure-autostart, --force-zlib on amulecmd/amuleweb,
     --disable-fatal/--enable-stdin on amulegui, the -t/--category
     formatting + grammar / FILES section / GD-support / optional-arg
     clarifications) get extracted into manpages.pot and turn up as
     untranslated entries in each manpages-<lang>.po.

The rest of the diff is line-wrap reflow -- po4a 0.74 wraps long
strings differently than the version that last touched the
catalogs, so msgid/msgstr bodies move across columns. No msgid
content was lost and no existing translation was discarded; fuzzy
markers grow only on entries whose source string genuinely changed
because of the #900 audit fixes.

Refs amule-org/amule-org.github.io#4 (pre-3.0.0 housekeeping)
Closes #894.
mrjimenez pushed a commit that referenced this pull request Jun 7, 2026
Picks up the entries left untranslated or marked fuzzy after the
preceding pot/po regen pass:

* po/it.po -- 14 untranslated installer-string entries (extracted
  from packaging/windows/installer_strings.c via #899) and 4 fuzzy
  entries:
  - 'Uninstall' had been msgmerge-mapped to the existing 'Installa'
    translation (wrong direction); fixed to 'Disinstalla'.
  - 'aMule application files (required).' had been msgmerge-mapped to
    the existing 'Integrazione di aMule non riuscita' translation
    (unrelated); fixed to the literal 'File dell'applicazione aMule
    (obbligatori).'.
  - 'Start aMule when I log in' kept the substantively correct
    existing translation, just unfuzzied.
  - The web-server-startup message updated to reference the
    -DBUILD_WEBSERVER=YES CMake flag we use today.

* docs/man/po/manpages-it.po -- 9 untranslated entries (the new
  --configure-autostart / --force-zlib / -t/--category / -o-and-p
  optional-arg / GD-support / aMule-online-sign FILES entries from
  the #900 audit fixes) and 5 fuzzy entries on synopsis lines and
  the 'all link found' grammar fix.

Refs amule-org/amule-org.github.io#4.
got3nks added a commit to got3nks/amule that referenced this pull request Jun 7, 2026
…ule-project#912)

Extends existing categories (preferring extensions over new lines):
- Performance/Upload: amule-project#898 SlotAllocation default raised.
- Networking & Discovery: wire-parser hardening list extended with
  amule-project#879/amule-project#882/amule-project#890/amule-project#886; new amuleweb security hardening bullet
  consolidating ngosang's amule-project#869-amule-project#874 triage (all landed in amule-project#875);
  amulegui list extended with amule-project#857; shared-folder watcher extended
  with amule-project#858.
- Packaging: Windows installer i18n line extended with amule-project#899.
- Internals & Refactoring: new docs-polish + code-quality bullets
  covering amule-project#851/amule-project#855/amule-project#862/amule-project#888/amule-project#900/amule-project#866/amule-project#867/amule-project#895 and amule-project#909/amule-project#910/amule-project#912.
- Translations: new pre-release final-wave bullet covering amule-project#847/amule-project#856/
  amule-project#891/amule-project#908/amule-project#860/amule-project#904/amule-project#859/amule-project#863/amule-project#861/amule-project#880/amule-project#911/amule-project#901/amule-project#902/amule-project#889/amule-project#868/amule-project#853.
- Bug Fixes & Stability: amule-project#850/amule-project#854/amule-project#878/amule-project#906.
- CI: ccache wiring (amule-project#892, amule-project#903) + CodeQL binutils-dev (amule-project#907).

Contributors footer gains mifritscher and nguyenhoangminhhieu2004-gif
(both first-time contributors).

PR index extended through amule-project#912.
mrjimenez pushed a commit that referenced this pull request Jun 8, 2026
Extends existing categories (preferring extensions over new lines):
- Performance/Upload: #898 SlotAllocation default raised.
- Networking & Discovery: wire-parser hardening list extended with
  #879/#882/#890/#886; new amuleweb security hardening bullet
  consolidating ngosang's #869-#874 triage (all landed in #875);
  amulegui list extended with #857; shared-folder watcher extended
  with #858.
- Packaging: Windows installer i18n line extended with #899.
- Internals & Refactoring: new docs-polish + code-quality bullets
  covering #851/#855/#862/#888/#900/#866/#867/#895 and #909/#910/#912.
- Translations: new pre-release final-wave bullet covering #847/#856/
  #891/#908/#860/#904/#859/#863/#861/#880/#911/#901/#902/#889/#868/#853.
- Bug Fixes & Stability: #850/#854/#878/#906.
- CI: ccache wiring (#892, #903) + CodeQL binutils-dev (#907).

Contributors footer gains mifritscher and nguyenhoangminhhieu2004-gif
(both first-time contributors).

PR index extended through #912.
@got3nks
got3nks deleted the docs/man-page-audit-fixes branch June 8, 2026 10:33
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