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

Re: Next approach: Documentation Policy

On Tue, 1 Jul 1997, Fernando wrote:

> Christian Schwarz wrote:
> > 
> > No, I talked about the "*.info" files. Someone else said here, some time
> > ago, that the intention of a Linux distribution is to provide the people
> > with "compiled files", not with the source that everyone has to compile.
> > Some people have slow computers, little memory, etc. and they surely don't
> > want to compile these files themselves all the time (whenever a package is
> > installed, upgraded, etc.).
> So why we are still distributing the man sources instead of pre-formatted
> man pages? 

That's a good question! (I don't know why.)

> Please note that makeinfo (the info compiler) is much faster than groff (the
> man compiler).

But the "texi2html" compiler is slow! 

> And you did not answer my other concerns about not distributing documents
> in source format. I summarize them and add a few points:
> 	- The speed of compiling sources is reasonable enough in most cases.

No. Some people have slow computers with little manual and they couldn't
afford recompiling the docs whenever the upgrade/install a package.

> 	- On demand compiling works for man, it should work for info too.

Perhaps we should reconsider shipping compiled manual pages, then.

> 	- On-the-fly conversion to html is good enough in many cases.

No. That's why I started this discussion. The result of "info2www" is not
good enough.

> 	- Makeinfo is fast, groff is slow.

texi2html is slow, too. (And other converters, from other mark up formats,
e.g. SGML, may be much slower!)

> 	- Users may want to print the documents. They need the source for that.

We can easily provide PostScript documents via our ftp server.

> 	- Users may want to automatically process the sources or convert them
> 	  to a non-standard format.

Right, but how often will it happen, that someone needs a format other
than info/html/postscript?

> 	- Texinfo files are nicer when viewed with the texi2html converter.

Sure. That's why on-the-fly compilation is not possible. (texi2html does
not work as CGI script, AFAIK--and it's much to slow anyways)

> Did you read my alternative proposal? I think it issues important points
> not covered in the present one, like treatment of binary documents, fallthrough
> methods for man and info when not installed and (IMHO) a nice and consistent
> solution to the problem of when to include multiple formats in a package.
> Even if you don't agree with everything I still think you should consider
> some parts of it.

I just read it again. You mention a few additional aspects (dpkg support
to unpack doc only, for example) which we should consider _after_ the main
points have been decided.

> One problem I see with the texi2html program is that it depends on Perl, which
> makes it very slow in an old computer. I was trying to modify it to do
> on-the-fly conversion but I have switched to makeinfo, which is very fast
> even in my old 386. I am adapting makeinfo to produce on-the-fly html output
> instead of info output.

Ok, this would change things a bit.



--                 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: