Man page translations are outdated

[Denis Silakov]

As was noted here: https://qa.mandriva.com/show_bug.cgi?id=61716
translations of rpm5 man pages are quite old, most of them come from rpm4.

The Mandriva bug also discusses some possible improvements in man pages.

[Jeff Johnson (n3npq)]

RPM is registered with The Translation Project for translations.

Part of being included in The Translation Project is that *only*
The Translation Project will be used.: a project that participates
is *not* supposed to check-in any i18n changes but rather to
encourage others (including developers and users) to submit
changes through The Translation Project national teams.

So "... quite old .." isn't accurate (wrto the @rpm5.org project) because
the latest available translations are pulled before every monthly
release.

There's no easy answer for ancient i18n because of complex FL/OSS politics.

Nor is there any easy answer for what SHOULD be documented and not in RPM:
RPM has many many many options that simply aren't useful to anyone but me
doing development and remote support/diagnosis. The mere act of documenting
some feature like --nosignatures or --nofsync causes users to try-and-see and
complain mightily when RPM "breaks".

Note that rpm had --rsegfault and --wsegfault options to segfault on demand.
Should these options be documented? Damfino ... I do know why the options
were added and what they were used for ... and I would argue that many options
simply do not need to be documented.

[Denis Silakov (dsilakov)]

Yes, not all possible options should be documented, and having options for development/debugging only is reasonable.

There is definitely no need to document options not mention in the `rpm --help` output. But if some option is present in that output, then it should be probably mentioned in documentation. If the option is reported by `--help` but still not intended to be used by 'usual' users, then there is no need to describe its behavior, but just to say smth like 'for debugging only'.

[Jeff Johnson (n3npq)]

Many RPM "options" are actually POPT aliases: in fact most of
the options that users wish to have documented are POPT aliases.

Since POPT aliases are a configurable extension displayed by --help,
I would claim that the man page is *NOT* the place to document
because configurable options are intended to change in opaque
manners that cannot be documented.

So the rule
    If an option is in --help, then it should be "documented".
isn't adequate because POPT aliases are in --help and not
(by conscious intent) in the man pages.

You can of course patch the man pages in Mandriva/ROSA however you wish.

[Jeff Johnson (n3npq)]

To illustrate the problem, here is an example

    echo "rpm exec --ls /bin/ls" >> ~/.popt
    rpm --ls

If the contents of ~/.popt is edited to look like:
  rpm exec --ls /bin/ls \
 --POPTdesc=$"Use rpm to invoke /bin/ls"
then the text is displayed
  $ rpm --help
  ...
  Options implemented via popt alias/exec:
  ...
        --ls Use rpm to invoke /bin/ls

Note that the $"..." marker will also display popt configuration
properly localized (if the usual extraction procedures for i18n
are used).

Hard questions:

  1) Should the --ls option be documented (because it is in --help)?
  2) Is there sufficient i18n team process sophistication to translate "quite old"
       "option" (aka popt alias/exec) in a timely fashion? Remember, "The Translation Project"
       MUST be used because that is the process, joining voluntary national teams.
  3) If the "option" is documented, is the rpm.8 man page the correct place, or
       is it better to describe popt alias/exec, and perhaps change popt to generate
       docbook or other markup from .popt, /etc/popt, and /usr/lib/rpm/rpmpopt-X.Y

The answers here aren't simple (although there are certain simplifications on
a case-by-case basis).

[Denis Silakov (dsilakov)]

Well, surely, popt alises is a separate case.

[Jeff Johnson (n3npq)]

Good we agree.

Now lets deal with certain other issues.

rpm-3.0 (released in 1998) used a different database format
that needed a --initdb command. This is/was documented in
"Maximum RPM" and carried forward into the "The RPM Guide"
and is easy to find on the WWW with GOOG.

The rpm-4.0.x series had a --verifydb command that wasn't
documented (but was described by me doing "rpm therapy")

Neither --initdb/--verifydb have been needed or very useful
( I forget whether I've removed in rpm-5.3, I have been trying
to remove "legacy cruft" since forever.

---> Should 'legacy compatible' commands be carried and documented?

Please note that --nosignatures --nodigests and a performance speedup
using --nofsync are crucially important to MANDATORY signatures
(coming to an RPM ROADMAP near you soon) and --nofsync (when used)
eliminiates Durability in ACID.

---> Should these options be documented/eliminated or otherwise fiddled
   with to meet user documentation expectations?

I literally do not know the answers: I usually leave "bad enuf" alone, but
that does lead to bug reports like here quite predictably.

[Denis Silakov (dsilakov)]

... That is, I agree there is no need to propagate 'help <-> man' matching requirement on all options implemented using popt, case-by-case approach is required.

Btw, in the old rpm man (dated 2002) there was a statement in the SEE ALSO section:
rpm --help - as rpm supports customizing the options via popt aliases it's impossible to guarantee that what's described in the manual matches what's available.

[Denis Silakov (dsilakov)]

There is no need to described dropped options in help/man; and --initdb/--verifydb doesn't seem to be known for rpm-5.3.

Not sure about options marked as obsolete but still supported; some projects leave such options in docs with explicit deprecation statement, some simply drop them from man and help. Maybe if we don't have them in the man atm, there is no need to add them.

--nosignatures and --nodigests are already mentioned in man. --nofsync should be probably documented.

[Jeff Johnson (n3npq)]

Specifically:
    Both --nosignatures and --nodigests are already useless for all packages
    produced by rpm-5.3 because of non-repudiable signatures included within.
Should the options be removed (like --initdb/--verifydb)?

And --nofsync is a popt alias to set a macro (with rather complex behavior changes) which
is already decided no need to document (in the rpm.8 man page).

[Denis Silakov (dsilakov)]

Oops, indeed, I didn't catch the point.

Yes, I'd vote for removing --nosignatures and --nodigests.

[Jeff Johnson (n3npq)]

Good we agree: I wasn't expecting that answer (and these are hard questions).

In reality --nosignatures/--nodigests is used too many places to
just rip out. However signature checking has to become a
per-system policy, not per-invocation, as part of a rational
(in the sense of a security audit) policy based configuration
scheme for verifying the installed software.

And --nofsync (which changes rpmdb behavior) is also pending
for review revisiting the reliability <-> performance tradeoffs
with "RPM ACID" behavior.

There are blueprints for each somewhere here ...