info-dir translator

[Ben Asselstine]

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.