Re: info-dir translator

[Ben Asselstine]

Hi again,

All of this presumes that an info-dir translator is in fact a good idea.
Why put install-info functionality into a translator so that a package
installer doesn't have to run it explicitly?

When we run install-info implicitly through a translator, we have to
wait for filesystem notifications and then do the computation of
updating `dir'.
When executed explicity, it just does the install-info computation and exits.

Is the switch from explicit to implicit worth the extra cpu cycles? 
Does it reduce the complexity of a package installer?  What's the
benefit and how much do we gain?

Ben

On 7/22/05, Ben Asselstine <address@hidden> wrote:
> Hey folks,
> 
> Here's the start of a document that explains what an info-dir
> translator is, and how (in general terms) it might be implemented.
> 
> Ben
> 
> --
> 
> The info-dir translator
> 
>   Currently we need to run install-info on new info files so that they get
>   included into the `info' program's top-level table of contents.  This
>   document describes a translator for the Hurd that will automatically keep
>   the top-level table of contents up to date by reflecting which info files 
> are
>   installed in /share/info.
> 
>   The translator almost always sits on /share/info/dir.
>   It watches a directory and any other dirs below it for file notifications.
>   The directory it watches is a translator parameter.  This value is almost
>   always /share/info.
> 
>   The translator changes the underlying file to contain the info dir file, so
>   that when `info' runs, it shows the table of contents.
> 
>   The translator makes heavy use of install-info (from the texinfo source),
>   to know how to install and uninstall info pages.
> 
> 
> How the translator would install an info file:
> 
>   Whenever a new file arrives, it runs the equivalent of:
>     install-info --quiet --info-file=/share/info/yorick.info.gz
> --info-dir=/share/info
> 
>   Now the info file must contain something like:
>     (install-info already expects this)
> 
>   INFO-DIR-SECTION Miscellaneous
>   START-INFO-DIR-ENTRY
>   * Yorick: (yorick).       Yorick interpreted language.
>   END-INFO-DIR-ENTRY
> 
>   The info-file IS the newly arrived file.
>   The info-dir is the parent dir of where our translating `dir' file sits.
> 
>   Watch out, a newly arrived file could be our own `dir' file.
> 
>   It's important to safely fall-through (eg. not crash on) non-info files.
> 
> 
> How the translator would uninstall an info file:
> 
>   When a file leaves /share/info/*, it runs the equivalent of:
>     install-info --quiet --remove
> --info-file=/share/info/yorick.info.gz --info-dir=/share/info
> 
> How the translator would monitor many dirs:
> 
>   Whenever a new dir shows up, we monitor that one too.
> 
> Implementation details:
> 
>   There's a locking issue here.
>   We have to P() on changing the underlying the /share/info/dir file.
> 
>   It's not a good idea for a translator to have to know where it's sitting, 
> and
>   that exactly what the --info-dir option in install-info implies.
>   Change it to pass down an open port for the info-dir file.
> 
> Usage examples:
> 
>   to run info-dir we run the following comamand:
> 
>     $ settrans -a /share/info/dir /hurd/info-dir /share/info
> 
>     /share/info/dir is the table of contents you see when you start up
>     `info' without any options.
>     /share/info is the name of the directory that we're monitoring.
>     again, we're monitoring that directory, and all dirs underneath it.
>     we do not assume that our dir file is /share/info/dir.
> 
>   installing an info page:
> 
>     $ cp /tmp/yorick.info.gz /share/info/
>     now when we copy yorick.info.gz into /share/info, the
>     /share/info/dir file gets updated automatically by the translator.  If
>     we were to copy a bunch of files into /share/info at the same time, it
>     would update `dir' in sequence with locking.
> 
>   uninstalling an info page:
> 
>     $ rm /share/info/yorick.info.gz
>     The translator notices that yorick.info.gz has gone away and then updates
>     `dir' to reflect this.
> 
>   to stop the info-dir translator we run the following command:
> 
>     settrans -fgap /share/info/dir
> 
>     the translator stops, but the /share/info/dir file is still all there.
>