Re: Standard path for documentation installation

[John Fleck <jfleck inkstain net>]

On Wed, Feb 13, 2002 at 08:46:46PM -0600, Federico Mena Quintero wrote:
> Maybe this is something that is defined somewhere and I'm too lazy to
> look, but...
> 
[snip]
> 
> Note the following:
> 
> - we have things in $(prefix)/share/gtk-doc/html/*
> 
> - we have things in $(prefix)/share/modulename-without-version/html/*
> 
> - we have things in $(prefix)/share/gnome/help/appname/<lang>/*
> 
> - we have things in $(prefix)/doc/modulename-with-version/html/*
> 
> Also:
> 
> - We have index.html, book1.html, modulename.html, ...
> 
> So, this is a plea for consistency.  Where should things go?  What
> should the main file be called?
> 

For the end-user (as opposed to developer) documentation you've
listed, we are consistent:

$(prefix)/share/gnome/help/<docid>/<lang>/*

For most applications with a single doc, docid and appname are the
same. "docid" has been used implicitly for a while for things like
Nautilus that have more than one user doc. It was codified by Jonathan
in the help API he wrote late last year:

gnome-docu/gdp/gnome2_help_api

Though in reading it, I realize it's a little vague on this point, in
practice we've been consistent in applying the above for user docs, as
your list shows.

I can't speak for developer docs - I agree they're rather all over the map.

> Also, for things like nautilus-user-manual, nautilus-quick-reference,
> etc.:  why not just have
> 
> 	nautilus/
> 		index.html
> 		quick-reference.html
> 		screenshot-guidelines.html
> 		release-notes.html
> 
> etc., where all the subsections are of course linked from index.html?
> 
> My proposal, to be ignored if this is already standarized/defined
> somewhere and it's just that modules are not following the standard:
> 
> - Things should go in $(prefix)/share/doc.
> 
> - So you have $(prefix)/share/doc/modulename/<lang>/index.html.
> 
> That's all.  index.html links to everything else for that module.
> 
> It could be argued that this is a moot point because with OMF files we
> can find everything easily.  But then again not every module installs
> OMF files and we should be consistent anyways and blah blah.
> 

I don't think it's moot - OMF files are not yet universally used.

Cheers,

John