Cumbersome documentation

[tox2ik]

Hi I think the documentation is difficult to read because;

• the things I'm looking for each time are tucked away
• the page is too long
  • chatty
  • has useless recommendations
  • not written with word count in mind.
  • does not provide enough examples
  • combines the scripting / formatting with everyday use
  • mixes options for the various invocations (eix-update, eix-installed)

Please comment on whether you would accept a patch where it is

• split into several pages
  • one for everyday use
  • one for scripting / formatting
  • one for tips and tricks
  • one for less-frequently used sub-tools
• trimmed to use fewer words where possible
• avoids awkward german-english expressions
• where recommendations and semi-relevant references are put somewhere else than the main page

to the authors:

Martin Väth, Emil Beinroth, Wolfgang Frisch, Roland Wittmann,

No offence guys, I just love this tool and every time I want to do something special I spend too much time with the man page.

[vaeth]

I am currently the only active maintainer/author, so do not expect any other feedback :(

Essentially, I agree with all of your points: The manpage should be completely rewritten and possibly split. However, be aware that this is a tremendous work, and experience shows that after some new eix releases with major changes, the documentation is as clumsy as before the rewrite.

For the case that you really dare to start the rewrite, note that I will probably not have the time to adapt the German manpage correspondingly. Moreover, the Russian manpage is currently essentially unmaintained, but only half translated anyway - for updates, I just copied corresponding parts from the English manpage, since I do not speak Russian.

Only for some of the points you made, I have some comments:

• • chatty
  • has useless recommendations

Not sure what you mean by these two points: Many recommendations and remarks have been added as a reaction to (invalid) bug reports or frequent requests to make certain things clearer (especially the FAQ section). It would be dangerous if a rewrite of the manpage would contain strictly less information.

• • mixes options for the various invocations (eix-update, eix-installed)

Be aware that a huge bulk of options of eix, eix-update, and eix-diff is identical. I do not think that a separate manpage for each of these tools which repeats all the identical options would be a good idea. Also the variables (cf. eix --dump, eix-diff --dump, eix-update --dump) are essentially identical.

[tox2ik]

I'm glad to hear you are positive to the proposal. I realize that this is an ambitious task. I do not want to do it in one go, but rather with incremental improvements. The Russian page is of no interest to me even though Russian is my native tongue.

I have the impression that eix is fairly stable, but I can study the release history more closely. I'm sure that I will need to understand some parts of the code anyway, so seeing how the tool evolved since ~2008 will be a good place to start.

[vaeth]

I have the impression that eix is fairly stable

It is true that currently I do not have too much time to do bigger changes to eix (and BTW it is not clear how long I will continue to maintain it at all; for personal reasons and also because the code has become very clumsy - see below).

Unfortunately, eix can only be as stable as portage is, and the latter changes still rather frequently, though currently less often than it used to. For instance, currently the whole handling of overlays (including the terminology on the manpage) is still based on overlay paths (PORTDIR, PORTDIR_OVERLAY) and not on the "modern" respository names (repos.conf) (historically clear since eix supported identification of the overlay from which a package was installed some years before portage by interpreting /var/db/CAT/NAME/environment.bz2: before /var/db/CAT/NAME/repository started to be generated by portage). There are still hacks of how to deal with missing repository data, and there is only a hackish translation of repos.conf into PORTDIR_OVERLAY, but it might very quickly happen that this hack is no longer sufficient (e.g. once repos.conf contains data which for the purpose of eix cannot be mapped into PORTDIR_OVERLAY, only, e.g. if more than 1 main repository might have to be considered; already now the main repository is always listed first which differs from portage's handling).

With such changes a fundamental restructuring of eix has to happen - new options and variables might need to be necessary, and people might have to be instructed how to convert their config.

Maybe also that one day it might be better to do a ground-up rewrite in a new project than trying to include further hacks: The code itself (similar as the documentation) has become clumsy due to many historical changes and also since historical C++ is used (partially necessarily in a hackish way) instead of modern C++-11 (or newer) w/ boost (although meanwhile C++-17 codepaths are used for speedup if available).
Also, it might be better to support a more standard output language instead of a confusing "environment variable based" language which due to its deficiencies was extended heavily (e.g. with runtime variables) and equipped with hacks like delayed substitution.

A rather intensive restructuring had happened with these latter extensions, but also with support for further/new portage features like /var/db/CAT/NAME/BUILD_TIME, or when it became clear that eix should support at least some output for DEPEND and USE (both are still supported only rudimentary to avoid too frequent changes). Or when these new data made the 16-color output rather unreadable and some color scheme support had to be introduced which still is rather unsatisfactory. Recently, I was thinking about supporting the relatively new /var/db/CAT/NAME/SIZE entry (although in the moment I dropped this idea, since the data apparently does not refer to the actual installed files).

If your native tongue is Russian, you might have a look at po/ru.po and look for "# fuzzy": For all translations marked this way, there were some changes in the original eix text since eix-0.29.0, quite often combined with a simultaneous extension/change of the manpage. (A few are just punctations, but these I documented explicitly). BTW, I would appreciate if you remove "# fuzzy" if you can confirm that my translation attempts are correct (however, many contain simply English text which I used whenever I found no similar phrase in previous translations; I hope that mixing English into Russian is not considered an offense.)

[tox2ik]

Ok, so it is stable-ish, but could use some changes. But the whole project is ~83800 lines of which ~27900 are .cc files. Doesn't seem all that bad :) I'm not going to volunteer for anything beyond the man page for now, but it would be a real shame if the only active dev left with no one to take over.

I see a whole lot of redundant MSGIDS in the .po file, for example the "this is used only in delayed substitution. To be honest I'd prefer to pay someone instead of doing it myself.

Why do you care about the Russian man page? Are there many Russian users with a lot of questions? But yes, some of the fuzzy ones are definetly incorrect.

[vaeth]

I see a whole lot of redundant MSGIDS in the .po file, for example the "this is used only in delayed substitution.

Most stuff from defaults.cc is only used for the output of comments in eix --dump. I think it is completely fine to leave all that stuff untranslated. The redundancy here is intentional, since only the comments distinguish whether a variable is used directly by eix's internal C code or only implicitly for replacement in other variables (by the "delayed substitution" mechanism). The latter I have always documented by the phrase you mentioned, for easier "grep"ing always spelt in the same manner.

To be honest I'd prefer to pay someone

Since I am not paid, I would certainly never spend any money.

I mentioned the po files mainly so that you can estimate the rate in which eix and its documentation changes: The relase 29.0 (when the translations were all up-to-date) is about 3 years old, and I would say that eix development was relatively slow in that period. I cannot predict the future, though...

Why do you care about the Russian man page?

Some Russian volunteers spent quite some time with the translations. Removing their translations would somehow destroy their work which would not be a nice move. Of course, I understand if no-one is volunteering to spend any more time.