[pacman-dev] Errors in pacman man pages

[Eli Schwartz]

On 7/8/20 2:25 AM, Helge Kreutzmann wrote:
> Dear pacman maintainer,
> the manpage-l10n project maintains a large number of translations of
> man pages both from a large variety of sources (including packman) as
> well for a large variety of target languages.
> 
> During their work translators notice different possible issues in the
> original (english) man pages. Sometimes this is a straightforward
> typo, sometimes a hard to read sentence, sometimes this is a
> convention not held up and sometimes we simply do not understand the
> original.
> 
> We use several distributions as sources and update regularly (at
> least every 2 month). This means we are fairly recent (some
> distributions like archlinux also update frequently) but might miss
> the latest upstream version once in a while, so the error might be
> already fixed. We apologize and ask you to close the issue immediately
> if this should be the case, but given the huge volume of projects and
> the very limited number of volunteers we are not able to double check
> each and every issue.

Our manpages are fairly low churn, and I'm pretty sure the status of
what you've noticed has not changed. So no worries on that count.

> Secondly we translators see the manpages in the neutral po format,
> i.e. converted and harmonized, but not the original source (be it man,
> groff, xml or other). So we cannot provide a true patch (where
> possible), but only an approximation which you need to convert into
> your source format.

Our manpages are in the doc/ directory of the source code in asciidoc
format, in case there is interest in providing a patch.

Otherwise, one of us can try looking at it when we have a chance.

> Finally the issues I'm reporting have accumulated over time and are
> not always discovered by me, so sometimes my description of the
> problem my be a bit limited - do not hesitate to ask so we can clarify
> them.

If I understand correctly, these are mostly formatting/markup issues
that help to semantically parse some words e.g. as "do not translate"?

> I'm now reporting the errors for your project. If future reports
> should use another channel, please let me know.
>
> Man page: makepkg-template.1
> Issue: "name" and "version" should be I<> as they are options of the program
> 
> "Currently used keys are: name (mandatory) and version\\&. Template names are "
> "limited to alphanumerics, \"@\", \"+\", \"\\&.\", \"-\", and \"_\"\\&. "
> "Versions are limited to numbers and \"\\&.\"\\&."
> --
> Man page: pacman.8
> Issue: This and other options' parameters could be wrapped in 'I<' and '>'
> 
> "I<pacman> E<lt>operationE<gt> [options] [targets]"
> --
> Man page: pacman.8
> Issue: Curly double quotes in some strings, others regular quotes. Uniformize.
> 
> "Since version 3\\&.0\\&.0, pacman has been the front-end to B<libalpm>(3), "
> "the \\(lqArch Linux Package Management\\(rq library\\&. This library allows "
> "alternative front-ends to be written (for instance, a GUI front-end)\\&."
> --
> Man page: pacman.8
> Issue:  'Search' 'owns' 'group' 'list' 'check' = option-related words, wrap around with "I<--" and ">" (or "B<--" and ">"?)
> 
> "Show less information for certain query operations\\&. This is useful when "
> "pacman\\(cqs output is processed in a script\\&. Search will only show "
> "package names and not version, group, and description information; owns will "
> "only show package names instead of \"file is owned by pkg\" messages; group "
> "will only show package names and omit group names; list will only show files "
> "and omit package names; check will only show pairs of package names and "
> "missing files; a bare query will only show package names rather than names "
> --
> Man page: pacman.8
> Issue: 'Search' 'group' 'list' = option-related words, wrap around with "I<--" and ">"
> 
> "Show less information for certain sync operations\\&. This is useful when "
> "pacman\\(cqs output is processed in a script\\&. Search will only show "
> "package names and not repository, version, group, and description "
> "information; list will only show package names and omit databases and "
> "versions; group will only show package names and omit group names\\&."
> --
> Man page: pacman.conf.5
> Issue: wget → B<wget>(1)
> 
> "If set, an external program will be used to download all remote files\\&. "
> "All instances of %u will be replaced with the download URL\\&. If present, "
> "instances of %o will be replaced with the local filename, plus a \\(lq\\&."
> "part\\(rq extension, which allows programs like wget to do file resumes "
> "properly\\&."
> 
> "This option is useful for users who experience problems with built-in HTTP/"
> "FTP support, or need the more advanced proxy support that comes with "
> "utilities like wget\\&."
> --
> Man page: pacman.conf.5
> Issue: Incorrect markup of -U: "" → B<>
> 
> "Set the signature verification level for installing packages using the \"-U"
> "\" operation on a local file\\&. Uses the value from SigLevel as the default"
> "\\&."
> --
> Man page: pacman.conf.5
> Issue: Missing markup of syslog(): syslog() → B<syslog>()
> 
> "Log action messages through syslog()\\&. This will insert log entries into /"
> "var/log/messages or equivalent\\&."
> --
> Man page: pacman.conf.5
> Issue: Where did "%o" come from? The XferCommand command usage does not have an %o
> 
> "If set, an external program will be used to download all remote files\\&. "
> "All instances of %u will be replaced with the download URL\\&. If present, "
> "instances of %o will be replaced with the local filename, plus a \\(lq\\&."
> "part\\(rq extension, which allows programs like wget to do file resumes "
> "properly\\&."

The rationale here seems to have been that %o is optional.

Currently:

XferCommand = /path/to/command %u

Could be, perhaps:

XferCommand = /path/to/command %u [--out %o]

> --
> Man page: pacman.conf.5
> Issue: [options] should not be translated, wrap it with B<>
> 
> "The I<SigLevel> directive is valid in both the [options] and repository "
> "sections\\&. If used in [options], it sets a default value for any "
> "repository that does not provide the setting\\&."
> --
> Man page: pacman-conf.8
> Issue: remote → repository
> 
> "B<-r, --repo> E<lt>remoteE<gt>"
> 


-- 
Eli Schwartz
Bug Wrangler and Trusted User

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 1601 bytes
Desc: OpenPGP digital signature
URL: <https://lists.archlinux.org/pipermail/pacman-dev/attachments/20200708/d00d9ce4/attachment.sig>