[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: new approach: Documentation Policy

On Thu, 3 Jul 1997, Federico Di Gregorio wrote:

> > > Just a question:
> > > 
> > > 	Where do we put texinfo sources? (FSSTD experts?)
> > 
> > Hmm. What about /usr/doc/foo/texinfo/ ?
> Seems right for me.
> > And there is more to define now: We'll have to find a unique way to
> > compile the texinfo manuals into ".info" and ".ps". I think there may be
> > some manuals out there, that do not come in a single ".texi" file. Since
> > /usr may be mounted read-only, we'll have to move the files somewhere else
> > to compile them. 
> > 
> > Any ideas?
> What about making /usr/info a softlink to something like /var/info?
> Usually the PS file are temporary, they stay only as long as the 
> docs are printed so I think something in /var/tmp should be right.
> Mmm... another idea, what about /var/doc/info, /var/doc/ps, etc...
> (with the link /usr/info -> /var/doc/info)?

Well, /usr is can only be modified at installation time since it might be
mounted read-only afterwards, and /var is used for files that need to be
modified at run-time. Some people have different partitions for this, so
we should try to keep stuff out of /var, if it's "static" data.

Since the "*.info" are only generated when you install either "doc-base"
and select info output, or when you install a package containing a texinfo
manual (and you selected info output before), these files can go into
/usr/info as usually.

The "*.ps" files are generated on request only (maybe after installation),
so these can not be placed below /usr as default.

What would be the best way to get the PostScript files? I see two
different options that should be supported either case: generation on
demand, as you run `man -t', and generation via a CGI script, for example,
"dwww" will contain a menu of all available docs. It would be nice to have
a hyperlink "printable version" next to the hyperlink that links to the
HTML document, which will link to a CGI script that generates the
postscript version on-the-fly. (Sure this takes some time. But if you set
up your web browser to display .ps files with ghostview/gv, you can read
nice manuals this way, or simply select "print" to send this to your
printer. This is IMHO much user friendlier than having to search for the
filename, create a new directory in /tmp, etc.)

What about HTML files? Brian suggested /usr/html . I'm not sure if this is
compliant with the FSSTND. We could either use /usr/doc/html/<pkg>, but I
think the change from /usr/doc/examples/<pkg> to /usr/doc/<pkg>/example
(and the same with "copyright") tried to "decentralize" all doc files.

So I would suggest using


for arbitrary HTML files, and


for GNU info converted HTML files. (Some packages may provide both types
and we should try not to mix them.) Of course, 


or other options to consider.

Any comments?



--                 Christian Schwarz
Do you know         schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
Debian GNU/Linux?    schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
Visit                  PGP-fp: 8F 61 EB 6D CF 23 CA D7  34 05 14 5C C8 DC 22 BA
http://www.debian.org   http://fatman.mathematik.tu-muenchen.de/~schwarz/

TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-request@lists.debian.org . 
Trouble?  e-mail to templin@bucknell.edu .

Reply to: