Re: Bug#793067: Bug#792328: info: can no longer find the Emacs manual

[Rob Browning]

Gavin Smith <address@hidden> writes:

> One observation is that the case with Emacs having many manuals for it
> and associated programs is a rare case. Thus the suggestion of having
> subdirectories for each Emacs version (/usr/share/info/emacs23,
> /usr/share/info/emacs24, etc.) doesn't mean that there would be a huge
> number of subdirectories. Other manuals could have a suffix on the
> filename, like gcc-4.0.info, gcc-4.1.info, etc. The only drawback of
> that would be that you wouldn't be able to access those manuals with
> cross-references to the "gcc" manual. Only one manual at a time could
> be accessed as "gcc", unless they were installed in multiple
> directories all of which were on INFOPATH. I don't think that's a huge
> problem.

I guess in general, perhaps "gcc" could be resolved by symlink(s), and
of course, other pages should only refer to "gcc" when they're sure the
version isn't relevant.

> Debian maintainers, please tell us what you need us to do. I'd be
> looking for indications that somebody would find changes useful that I
> might make, because any changes I would go and implement at the moment
> would only be based on my theorizing, because I haven't had a real
> need to look up documentation of multiple versions of programs, and my
> theorizing might not match the practical reality.

I'm not sure I have strong preferences about the details, but broadly
speaking, perhaps it'd be nice if we could satisfy the following:

  - When people ask for the pages for foo, they get the current "system
    default" foo (or maybe just the newest one?).

  - All of the internal links for a particular "version" point to the
    pages that go with that version.  I'm not sure I care right now
    whether that's via browser behaviors, or via some (speculating
    wildly) "makeinfo --version-ref calc=24.4 --version-ref org=24.4
    emacs.info" build-time mechanism.

  - There's an easy way to ask specifically for the "foo X" pages.  I
    suppose X might be program specific, but all of the values I can
    think of right now are of the form N or N.M. (i.e. GCC 5.0, Python
    2.7, Python 3.4, Emacs 24.4 (or just 24?)), etc.

All else being equal, it might be handy to allow X to be configurable,
so that you don't have to get involved in deciding where the
"multi-version line" should be.  i.e. some people might only want pages
for GCC 4 and GCC 5, and some might want pages for 4.8, 4.9, and 5.0.

I suppose if you were willing to assert that all of the "versions" were
going to be strings separated by periods, then you might be able to
support lookups for say, "5", "5.0", and "5.0.1" at the same time, when
5.0.1 was installed, but I'm somewhat wary.

As mentioned elsewhere, I'd be fine with a top-level dir listing
multiple versions, but I don't know what would be easiest/best.

I suppose in the end, I think of this issue roughly like that of going
to look for the web documentation for say Python.  Sometimes I need the
2.X pages, and sometimes I need 3.X, and on the main page
(https://docs.python.org/3/) there's a sidebar:

  Python » 3.4.3 Documentation » 

  Download these documents |   Welcome! This is the Python 3.4.3 documentation
  Docs for other versions  |   Parts of the documentation:
    Python 2.7 (stable)    |     What's new in Python 3.4?
    Python 3.3 (stable)    |     Tutorial
    Python 3.5 (devel)     |       start here
    Old versions           |       ...

Of course we wouldn't necessarily handle it that way, but I think the
general idea of treating multiple versions as a normal case is sound.

> PS Is there any way of stopping the Debian bug tracker system
> acknowledging my email, other than leaving it off the reply list?

Hmm, not sure offhand, I just ignore it, but I wouldn't mind turning it
off myself.

Thanks
-- 
Rob Browning
rlb @defaultvalue.org and @debian.org
GPG as of 2011-07-10 E6A9 DA3C C9FD 1FF8 C676 D2C4 C0F0 39E9 ED1B 597A
GPG as of 2002-11-03 14DD 432F AE39 534D B592 F9A0 25C8 D377 8C7E 73A4