Skip to content

amulecmd.1: don't translate command names in section headers - #547

Merged
mrjimenez merged 1 commit into
amule-project:masterfrom
got3nks:fix/manpage-untranslate-commands
May 11, 2026
Merged

amulecmd.1: don't translate command names in section headers#547
mrjimenez merged 1 commit into
amule-project:masterfrom
got3nks:fix/manpage-untranslate-commands

Conversation

@got3nks

@got3nks got3nks commented May 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Fixes #397amulecmd(1) localised manpages were rendering command names in the user's locale (e.g. Spanish Mostrar <what> instead of Show <what>), which no one can actually type at the amulecmd prompt because the runtime command is the English form.

Root cause

docs/man/amulecmd.1 used the standard .SS macro for command section headers like Add, Show, Get, etc. po4a treats every .SS line as a translatable string and dutifully ran the command names through translation. The source already had the right pattern for argument-less commands — Disconnect, Exit, Progress, Quit, Reset, Results, Shutdown, Status use the project-defined .SS_untranslated alias (declared at the top of amulecmd.1 and listed in po4a.config's untranslated= set). The 14 commands that take arguments missed this treatment.

Fix

Switch the 14 remaining command headers to .SS_untranslated. Section headers under NOTES (.SS Paths, .SS Languages) are intentionally left as .SS — those are descriptive section titles in the document outline, not commands users have to type, so localising them is correct.

Verification

Regenerated with po4a 0.73. Spanish manpage before / after:

- .SS "Mostrar \fI<what>\fP"
- Mostrar cola de descarga.
- Mostrar registro.
+ .SS_untranslated Show \fI<what>\fR
+ Mostrar cola de descarga.
+ Mostrar registro.

Command name now English (so amulecmd> show DL matches), explanations remain Spanish.

Scope of the diff

  • docs/man/amulecmd.1 — the actual fix (14 lines, .SS.SS_untranslated).
  • docs/man/amulecmd.$lang.1 × 9 — regenerated translated manpages.
  • docs/man/po/manpages-$lang.po × 9 + manpages.pot — regenerated catalogs.

The .po regeneration also picks up some incidental drift unrelated to this fix — removal of xas.1 references (xas was deleted in 5ebf3da7b), charset header utf-8UTF-8 normalisation, and po4a 0.73's preferred line wrapping. These come along because regenerating only the .1 files would leave the .po catalogs out of sync, and the next po4a-update run would revert our changes. The unrelated amule.*.1, amuled.*.1, amulegui.*.1, amuleweb.*.1, ed2k.*.1 files were also touched by po4a (line-wrap differences only) — those have been deliberately reverted from this PR to keep the scope focused; a maintainer can pick them up in a separate cosmetic regeneration commit when convenient.

Closes #397

@mrjimenez

Copy link
Copy Markdown
Contributor

@got3nks , this one got conflicts.

@got3nks
got3nks force-pushed the fix/manpage-untranslate-commands branch 2 times, most recently from a587e53 to 0a887da Compare May 11, 2026 11:27
@got3nks

got3nks commented May 11, 2026

Copy link
Copy Markdown
Contributor Author

@mrjimenez rebased onto current master and regenerated all translation artefacts via po4a 0.73 again.

Two things to flag in this update beyond a plain rebase:

  1. Scope expanded to all other tools' translated manpages (amule.$lang.1, amuled.$lang.1, amulegui.$lang.1, amuleweb.$lang.1, ed2k.$lang.1, alc/alcc/cas/wxcas.$lang.1), not just amulecmd.$lang.1. Reason: since this PR was opened, master has had untranslated content added to several .1 source files (e.g. the new --disable-fatal text in amule.1, the search-filters block in amulecmd.1, and similar drift in other manpages). Running po4a regenerates those translated outputs from the current .po catalogs; the diff is otherwise unchanged. Keeping the scope narrow to amulecmd alone would have left the .po catalogs inconsistent with the on-disk translated manpages, and the next po4a-update would have reverted parts of this PR. Same reasoning as the original commit body, just covering more files now.

  2. amulecmd.es.1 dropped. The new search-filters block in amulecmd.1 introduced ~28 untranslated strings; Spanish coverage on the resulting po4a output fell to 76.85% (93/121 strings), below po4a's default 80% threshold. po4a discards the file at that threshold. The Spanish strings already present in manpages-es.po are preserved — when someone translates the new search-filters strings, the next regeneration will restore amulecmd.es.1 automatically. Worth filing a follow-up for Spanish translators but not blocking for this PR.

Tip of fix/manpage-untranslate-commands is now 0a887da6d on top of d4e6d86b3.

amulecmd.1 used .SS for command headers like 'Add', 'Show', 'Get',
which po4a treated as translatable. Localised manpages then ended up
with translated command names -- e.g., the Spanish manpage rendered
'.SS "Mostrar <what>"', which no user can actually type at the
amulecmd prompt because the command is 'show', not 'mostrar'.

The source already used the .SS_untranslated alias for argument-less
commands (Disconnect, Exit, Progress, Quit, Reset, Results, Shutdown,
Status); switch the remaining 14 command headers to the same alias so
their command names stay English while the body explanations remain
translatable. Section headers under NOTES (.SS Paths, .SS Languages)
are left as .SS -- those are descriptive section titles, not
commands.

Regenerated all amulecmd.$lang.1 files plus the manpages-$lang.po
catalogs and manpages.pot via po4a 0.73 so the source and the
generated artefacts stay in sync. The .po regeneration also picks up
some unrelated drift -- removal of the deleted-in-5ebf3da7b xas
references, charset 'utf-8' -> 'UTF-8' normalisation, and po4a's
preferred line wrapping -- which is necessary because regenerating
only the .1 files would leave the .po catalogs stale and the next
po4a-update would revert our changes.

Closes amule-project#397
@got3nks
got3nks force-pushed the fix/manpage-untranslate-commands branch from 0a887da to 958fbb0 Compare May 11, 2026 11:46
@got3nks

got3nks commented May 11, 2026

Copy link
Copy Markdown
Contributor Author

Update: folded Spanish translations for amulecmd.1 into this PR so amulecmd.es.1 is regenerated (no longer dropped). Now at 958fbb097.

What changed since the previous push:

  • 7 new translations in manpages-es.po covering the search-filters block (--type, --extension, --avail, --min-size, --max-size, the leading "Optional filters can be placed…" paragraph, and the trailing example) — the strings that pushed Spanish below the 80% threshold in my previous push.
  • 1 fuzzy translation corrected at amulecmd.1:212 — the previous translation was for the old msgid "Reload shared files list."; updated to match the current "Show shared files list." (English msgid changed in master at some point, leaving a stale translation that po4a flagged fuzzy).
  • docs/man/amulecmd.es.1 regenerated (file restored, no longer in the deletion set).

Spanish coverage is now back above po4a's 80% threshold (~83.4%, well clear).

All 8 new/changed translations are marked with a translator comment # AI-GENERATED — please review. above the entry, so a Spanish-speaking reviewer can spot them with grep "AI-GENERATED" docs/man/po/manpages-es.po. Translations are conservative — they preserve roff macros (I<...>, B<...>, \\(mu, \\(lq/\\(rq) and aMule-specific terminology (B<--min-size>, B<--type> left untranslated as command-line flags).

Happy to back this out if you prefer keeping the PR focused on the original .SS_untranslated change and dealing with translation gaps separately — just say the word.

@mrjimenez

Copy link
Copy Markdown
Contributor

No need to back it out. As soon as the CI finishes, we commit.

@mrjimenez
mrjimenez merged commit 4296bbc into amule-project:master May 11, 2026
12 checks passed
mrjimenez pushed a commit that referenced this pull request May 11, 2026
The Spanish manpage catalog was already brought up above po4a's 80%
threshold for amulecmd.1 in #547; this commit completes the parity
with the it/fr/de translation passes in this PR by adding the two
remaining strings the other languages got:

  - amule.1:45 / amuled.1:53 -- the new --disable-fatal description
    added upstream around the same time the search-filters block
    landed in amulecmd.1.

  - amulecmd.1:140 -- the previously-fuzzy "A synonym of..." entry.
    The Spanish translation was already correct ('Un sinónimo del
    comando B<exit>.'); only the typo 'synonim' -> 'synonym' changed
    in the English msgid, so just removing the #, fuzzy flag is
    sufficient (no AI marker since no translation change).

The deeper backlog of pre-existing Spanish translation gaps (~46
amulecmd/amulegui/amuleweb/ed2k/alc/alcc/cas/wxcas strings that have
been untranslated since long before this PR) is intentionally left
for a separate "fill backlog Spanish gaps" follow-up to keep this PR
focused and per-language commits comparable in scope.

The --disable-fatal translation is marked `# AI-GENERATED -- please
review.` for a native Spanish reviewer.

Regenerated amule.es.1, amulecmd.es.1, amuled.es.1 via po4a 0.74.
@got3nks
got3nks deleted the fix/manpage-untranslate-commands branch May 11, 2026 13:46
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
The amuleGUI "aMule Log" tab appended the daemon log one line at a time.
Each AppendText auto-scrolls the bottom-anchored wxTE_RICH2 control, so a
first-sync backlog of thousands of lines paid an O(n) RichEdit reflow per
line and visibly churned the scrollbar (what reads as forced "smooth
scrolling"), taking ~20 s for a ~16k-line log. Coalesce each poll's lines
into one AppendText per bold/normal run (FlushLogBatch) instead of one per
line.

On Windows the log view (which lives on the Networks page) also renders
wrong when the backlog arrives while that page is hidden -- the default tab
on launch is Transfer, so a hidden wxTE_RICH2 never lays out and comes back
showing only the last few lines until a manual scroll. Defer the scroll +
repaint to the next page-show, armed only when lines actually arrived while
hidden, so a user who scrolled up and switched tabs keeps their position.
When the page is visible, force a Refresh()/Update() after the scroll.

Addresses points 1, 2 and 5 of amule-project#547.
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
The amuleGUI log panes used a wxTE_RICH2 (RichEdit) control, which holds the
whole document and reflows O(n) on scroll. A remote-GUI first sync can dump
tens of thousands of daemon-log lines at once, so scrolling crawled and the
view mispainted -- only the tail visible until a manual one-line scroll
(issues amule-project#445, amule-project#547).

Replace the three log/info panes (aMule Log, aMuleGUI Log, server info) with a
new CMuleLogCtrl backed by wxStyledTextCtrl. Scintilla renders only the
visible lines, so scrolling and full-history retention stay O(visible) at any
size, and unlike a virtual list it keeps character-level selection and find.
Critical lines are bold via per-line Scintilla styles; the view tail-scrolls
only when already at the bottom, so scrolling up to read history sticks.

This removes the whole RichEdit workaround stack -- the per-poll append
batching, the deferred hidden-page scroll, and the Freeze/Thaw lineage from
amule-project#451/amule-project#471/amule-project#477 -- none of which Scintilla needs.

wxStyledTextCtrl (the stc component) ships with the wxWidgets packages every
platform already builds against, so it adds no new dependency; it is requested
only for the GUI library that owns the log views.
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
The amuleGUI log panes used a wxTE_RICH2 (RichEdit) control, which holds the
whole document and reflows O(n) on scroll. A remote-GUI first sync can dump
tens of thousands of daemon-log lines at once, so scrolling crawled and the
view mispainted -- only the tail visible until a manual one-line scroll
(issues amule-project#445, amule-project#547).

Replace the three log/info panes (aMule Log, aMuleGUI Log, server info) with a
new CMuleLogCtrl backed by wxStyledTextCtrl. Scintilla renders only the
visible lines, so scrolling and full-history retention stay O(visible) at any
size, and unlike a virtual list it keeps character-level selection and find.
Critical lines are bold via per-line Scintilla styles; the view tail-scrolls
only when already at the bottom, so scrolling up to read history sticks.

This removes the whole RichEdit workaround stack -- the per-poll append
batching, the deferred hidden-page scroll, and the Freeze/Thaw lineage from
amule-project#451/amule-project#471/amule-project#477 -- none of which Scintilla needs.

wxStyledTextCtrl (the stc component) ships with the wxWidgets packages every
platform already builds against, so it adds no new dependency; it is requested
only for the GUI library that owns the log views.
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
The amuleGUI log panes used a wxTE_RICH2 (RichEdit) control, which holds the
whole document and reflows O(n) on scroll. A remote-GUI first sync can dump
tens of thousands of daemon-log lines at once, so scrolling crawled and the
view mispainted -- only the tail visible until a manual one-line scroll
(issues amule-project#445, amule-project#547).

Replace the three log/info panes (aMule Log, aMuleGUI Log, server info) with a
new CMuleLogCtrl backed by wxStyledTextCtrl. Scintilla renders only the
visible lines, so scrolling and full-history retention stay O(visible) at any
size, and unlike a virtual list it keeps character-level selection and find.
Critical lines are bold via per-line Scintilla styles; the view tail-scrolls
only when already at the bottom, so scrolling up to read history sticks.

This removes the whole RichEdit workaround stack -- the per-poll append
batching, the deferred hidden-page scroll, and the Freeze/Thaw lineage from
amule-project#451/amule-project#471/amule-project#477 -- none of which Scintilla needs.

wxStyledTextCtrl (the stc component) ships with the wxWidgets packages every
platform already builds against, so it adds no new dependency; it is requested
only for the GUI library that owns the log views.
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
The amuleGUI log panes used a wxTE_RICH2 (RichEdit) control, which holds the
whole document and reflows O(n) on scroll. A remote-GUI first sync can dump
tens of thousands of daemon-log lines at once, so scrolling crawled and the
view mispainted -- only the tail visible until a manual one-line scroll
(issues amule-project#445, amule-project#547).

Replace the three log/info panes (aMule Log, aMuleGUI Log, server info) with a
new CMuleLogCtrl backed by wxStyledTextCtrl. Scintilla renders only the
visible lines, so scrolling and full-history retention stay O(visible) at any
size, and unlike a virtual list it keeps character-level selection and find.
Lines word-wrap as the old pane did; critical lines are bold via per-line
Scintilla styles.

The view tail-scrolls after new content only when it was already at the
bottom, so scrolling up to read history sticks. When the backlog arrives while
the Networks page is hidden (the default tab on launch is Transfer) the log
control has no laid-out geometry and cannot be scrolled reliably, so the
tail-scroll is deferred and performed when the page is next shown.

This removes the whole RichEdit workaround stack -- the per-poll append
batching and the Freeze/Thaw lineage from amule-project#451/amule-project#471/amule-project#477 -- none of which
Scintilla needs.

wxStyledTextCtrl (the stc component) ships with the wxWidgets packages every
platform already builds against, so it adds no new dependency; it is requested
only for the GUI library that owns the log views.
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
The amuleGUI log panes used a wxTE_RICH2 (RichEdit) control, which holds the
whole document and reflows O(n) on scroll. A remote-GUI first sync can dump
tens of thousands of daemon-log lines at once, so scrolling crawled and the
view mispainted -- only the tail visible until a manual one-line scroll
(issues amule-project#445, amule-project#547).

Replace the three log/info panes (aMule Log, aMuleGUI Log, server info) with a
new CMuleLogCtrl backed by wxStyledTextCtrl. Scintilla renders only the
visible lines, so scrolling and full-history retention stay O(visible) at any
size, and unlike a virtual list it keeps character-level selection and find.
Lines word-wrap as the old pane did; critical lines are bold via per-line
Scintilla styles.

The view tail-scrolls after new content only when it was already at the
bottom, so scrolling up to read history sticks. When lines arrive while a pane
is hidden (its notebook page or sub-tab is not selected -- e.g. the first-sync
backlog before the Networks tab is opened) the control has no laid-out geometry
and cannot be scrolled reliably, so the tail-scroll is deferred and applied on
the first idle once the pane is on screen. This lives in CMuleLogCtrl, so all
three panes share it.

This removes the whole RichEdit workaround stack -- the per-poll append
batching and the Freeze/Thaw lineage from amule-project#451/amule-project#471/amule-project#477 -- none of which
Scintilla needs.

wxStyledTextCtrl (the stc component) ships with the wxWidgets packages every
platform already builds against, so it adds no new dependency; it is requested
only for the GUI library that owns the log views.
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
The deferred/tail scroll called ScrollToEnd() directly. With word-wrap on --
where Scintilla lays out wrapped lines incrementally over several idles -- two
problems fell out:

- switching to a hidden log pane after the backlog loaded landed a few lines
  short (the single scroll ran before the tail was wrapped); and
- switching to it mid-load landed at ~90%, because the batch tail-scroll and
  the idle re-scroll loop both moved the view and the loop misread its own
  batch scroll as a manual scroll and gave up.

Make OnInternalIdle() the sole scroller: ScrollToBottom() only sets a pending
flag, and the idle loop re-applies ScrollToEnd() until the first-visible line
stops moving (wrap settled at the true bottom), bailing only when the view
moves on its own (a real manual scroll). Appends never move the first-visible
line, so the loop follows the growing log through the whole replay. Lives in
the base CMuleLogCtrl, so all three panes (aMule Log, aMuleGUI Log, server
info) share it. Follow-up to amule-project#548 (issue amule-project#547).
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
The deferred/tail scroll called ScrollToEnd() directly. With word-wrap on --
where Scintilla lays out wrapped lines incrementally over several idles -- two
problems fell out:

- switching to a hidden log pane after the backlog loaded landed a few lines
  short (the single scroll ran before the tail was wrapped); and
- switching to it mid-load landed at ~90%, because the batch tail-scroll and
  the idle re-scroll loop both moved the view and the loop misread its own
  batch scroll as a manual scroll and gave up.

Make OnInternalIdle() the sole scroller: ScrollToBottom() only sets a pending
flag, and the idle loop re-applies ScrollToEnd() until the first-visible line
stops moving (wrap settled at the true bottom), bailing only when the view
moves on its own (a real manual scroll). Appends never move the first-visible
line, so the loop follows the growing log through the whole replay. Lives in
the base CMuleLogCtrl, so all three panes (aMule Log, aMuleGUI Log, server
info) share it. Follow-up to amule-project#548 (issue amule-project#547).
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
…le-project#548)

The amuleGUI log panes used a wxTE_RICH2 (RichEdit) control, which holds the
whole document and reflows O(n) on scroll, so a remote-GUI first-sync backlog
of tens of thousands of daemon-log lines made scrolling crawl and mispaint
(only the tail visible until a manual scroll).

Replace the three log/info panes (aMule Log, aMuleGUI Log, server info) with a
new CMuleLogCtrl backed by wxStyledTextCtrl (Scintilla), which renders only the
visible lines: full history is kept and scrolling stays O(visible) at any size,
with character-level selection/find preserved. Lines word-wrap; critical lines
are bold via per-line styles. Tail-scroll only fires when already at the bottom;
a scroll requested while the pane is hidden is deferred to the first idle once
it is on screen (in the base control, so all three panes share it). Removes the
RichEdit workaround stack (per-poll batching, the Freeze/Thaw lineage of
amule-project#451/amule-project#471/amule-project#477). The stc component ships with every platform's wxWidgets and is
requested only for the GUI library; the Windows portable bundles its DLL via the
existing GET_RUNTIME_DEPENDENCIES install step. Reported in amule-project#547.
got3nks added a commit to got3nks/amule that referenced this pull request Jul 22, 2026
…mule-project#549)

Follow-up to amule-project#548 (Scintilla log panes). The tail-scroll landed short when log
lines wrap, because Scintilla lays out wrapped lines incrementally over several
idles, so a one-shot ScrollToEnd() ran against a display-line count that did
not yet include the still-unwrapped tail. Switching in mid-load made it worse:
each poll's batch also scrolled directly and the idle re-scroll loop misread
its own batch scroll as a manual scroll and gave up (~90%).

Make OnInternalIdle() the sole scroller: ScrollToBottom() only flags a pending
scroll, and the idle loop re-applies ScrollToEnd() until the first-visible line
stops moving (wrap settled at the true bottom), bailing only on a genuine
manual scroll. Appends never move the first-visible line, so it follows the
whole replay. In the base CMuleLogCtrl, so all three panes share it. Also
corrects a few amule-project#548 comments the rework left inaccurate. Reported in amule-project#547.
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.

The manual page should not translate commands

2 participants