[Xapian-discuss] debs missing query templates

[Olly Betts]

On Tue, Nov 23, 2004 at 04:03:04PM +0000, James Aylett wrote:
> On Tue, Nov 23, 2004 at 03:52:53PM +0000, Olly Betts wrote:
> 
> > It should probably be xapian-omega rather than omega since the package
> > name is xapian-omega.
> 
> Indeed.
>  
> > And the templates should really be under /var since it's expected
> > they'll be modified.
> 
> Less keen on this, because I don't think web content belongs in
> /var. Perhaps I'm old fashioned, but it makes no sense to me
> whatsoever; when was the last time you edited something in /var that
> wasn't a website?

We ought to adhere to the FHS unless there's a good reason not to.

The Debian package needs to since we want to get it into Debian itself
at some point, and Debian Policy 9.1.1 says:

    The location of all installed files and directories must comply with
    the Filesystem Hierarchy Standard (FHS), version 2.1, except where
    doing so would violate other terms of Debian Policy.

And Debian does enforce this - for example this recent apt-spy bug:

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=277816

It makes sense to follow the FHS in general too - it's a standard which
is generally adhered to, so following it leads to least suprise with
users.  It's also clearer if the paths match between packages and built
from source versions where possible - it's easier for users, and easier
to write instructions, database backup scripts, etc.

Looking at FHS 2.1, /usr certainly isn't right for templates - chapter 4
starts:

    /usr is the second major section of the filesystem.  /usr is
    shareable, read-only data.  That means that /usr should be shareable
    between various hosts running FHS-compliant and should not be
    written to.  Any information that is host-specific or varies with
    time is stored elsewhere.

Users will typically want to customise the omega templates or add their
own - they aren't read-only data.

/var/lib probably isn't right since FHS 2.1 5.5 says:

    Users should never need to modify files in /var/lib to configure a
    package's operation.

Although if you want to nitpick, you could argue that you never *need*
to edit the templates.

/var/share isn't mentioned at all, and doesn't seem to exist!  I'm sure
I've seen it somewhere, but not somewhere FHS compliant it would seem.

/etc is the FHS place for configuration files, though these templates
aren't exactly configuration - they're much more akin to PHP or SSI web
pages than apache's httpd.conf.  

FHS 2.3 suggests "/srv" for "site-specific data which is served by this
system", such as web pages, CVS, etc.  Not sure I really agree with them
inventing practice rather than documenting it, but that's not in FHS 2.1
anyway.

So I don't know, really.  I tend to think they belong in a comparable
place to where web pages live.  That's typically /var/www for Linux
distributions, so /var/lib/xapian-omega is probably the answer for
now.

> Thinking about it, I don't think it's a good idea to have /all/
> templates available straightaway. Perhaps we could put them in
> /usr/share/doc/xapian-omega/ and perhaps put one in wherever they're
> going to be used from. We don't want to install godmode by default,
> for instance.

There's not actually any harm in installing the godmode template - it
doesn't reveal secret information or allow you to write to the database
or anything.  It just allows you to inspect a raw view of a document,
which can be a handy debugging tool (or would be if I finished writing
it!) so it's arguably useful to have it available by default.

> > I don't thing writing and maintaining man pages in addition to --help
> > output and HTML documentation is a sensible use of resources.
> > 
> > I'd suggest using help2man to turn the --help output into a man page.
> > That way there's a man page with some useful information, and a pointer
> > to the HTML documentation.  And it won't suffer from bitrot.
> 
> I'd be happy with that.

OK, I'll try to whip up a makefile rule to do that.

Cheers,
    Olly