[pacman-dev] Errors in pacman man pages

Thu Jul 9 12:31:38 UTC 2020

Hello Eli,
On Wed, Jul 08, 2020 at 10:35:36PM -0400, Eli Schwartz wrote:
> On 7/8/20 2:25 AM, Helge Kreutzmann wrote:
> 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.

Please accept my apologizes that I won't be able to do that as
detailed in my mail.

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

Thank you very much.

> > 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"?

Yes, many issues are like that, giving also readers an indication what
the text in the markup actully is (an option, ..). Following the
systematic is helping all kinds of readers.

> > 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]

I`ll forward this to the translator, thanks for the explanation.

> > --
> > 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>"

Greetings

       Helge

-- 
      Dr. Helge Kreutzmann                     debian at helgefjell.de
           Dipl.-Phys.                   http://www.helgefjell.de/debian.php
        64bit GNU powered                     gpg signed mail preferred
           Help keep free software "libre": http://www.ffii.de/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://lists.archlinux.org/pipermail/pacman-dev/attachments/20200709/847e7f50/attachment.sig>