Re: Next approach: Documentation Policy
On Wed, 2 Jul 1997, Fernando wrote:
> > > Did you read my alternative proposal? I think it issues important points
> [...]
> >
> > 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.
>
> Oh! That was my old proposal. Maybe you missed the latest version I made then.
> I include it below. I made it as short as I could, so as to not bore you too
> much.
I really think I missed this one. (There were too many mails in this
discussion :-)
> The main differences between your point of view and mine are:
I can't agree with your "language": My proposals do _not_ represent "my
very personal point of view". As Debian Policy Manager, I try to
incorporate the ideas, needs, fears, etc. of _all_ Debian developers and
users (though this is not easy in this discussion).
(I hope that people are not irritated that my proposals change that much.
This is, because they are not my personal opinion. I'll try to get a
consensus here.)
(My systems are fast and have enough memory, for example, but I know a lot
of people with slower systems and they should get most out of Debian as
well.)
Anyways, I think our proposals are getting nearer and nearer. (Perhaps we
are very close to a consensus now!)
> 1) You don't want to include source formats while I want to include them.
> One more point for including source formats:
> -) Local admins may want to modify docs to adjust to local layout
> BEFORE printing the docs. That's impossible within your proposal,
> unless they download the full source code (which may be expensive!)
I'm definitely against distribution the source _only_. (See below.)
> 2) You want uncompressed sources and no webserver by default, while I want
> the opposite.
> This has already been discussed at length.
My last proposal regarding HTML files was to ship these files uncompressed
and have a "doc-base" package which can optionally compress them, if the
local sysadmin either has web servers or web browsers that can handle
these. (Since all files in a .deb are compressed for distribution, this
surely makes no overhead. Of course, compressing at installation time
takes some time, too, but "gzip" is quite fast.)
Since noone objected until yet, I think most people agree with this.
> 3) You want HTML and info. I want HTML and texinfo.
> Your reasons:
> -) HTML because it is the default method.
> -) Info for everyone because some people like it.
> -) For printing, download our pre-compiled PS files.
> My reasons:
> -) HTML because it is the default method.
> -) Texinfo to print (maybe locally modified) copies.
> -) Info as an option for people who want it.
I totally agree with your option here. Just to get it right: We don't ship
*.info files, they are created on demand. (Note, that we'll have to split
makeinfo of the tetex packages, maybe in doc-base, to simply dependencies.
But this can easily be done.)
> 4) You don't make distinction between binary and markup formats. I do.
> Binary formats are untouchable, impossible to index, almost impossible to
> cut and paste into another document and much bigger than markup formats
> with the same info. Use of binary formats as original source should be
> discouraged and they should be kept separately.
> On the other hand, markup formats are easy to index, easy to convert
> locally to PS, easy to cut and paste, easy to modify. There is no real need
> for us to pre-convert them to PS instead of just providing them.
I agree 70% :-) but please don't forget that compiling takes some time on
slow systems.
> 5) There is no safeguard on your proposal that every program contain _some_
> documentation, even if it is just instructions of how to get the rest, what
> the user needs to view it (ghostscript and friends) and a summary of its
> contents. That could be enough to decide whether or not the rest of the docs
> are needed.
I don't get your point. Do you want us to force all developers to write
docs, if these are not available? I will definitely _not_ do this. We
currently for the maintainers to write manual pages (to the extent where
this is possible in a volunteer project) if these are not available. This
should be enough.
> 6) Your idea of a repository of documents in PS format is good, but I see
> it as an added value option, not as the main option.
Right. And I'm currently thinking of dropping this (PS docs on ftp
server) again, since I'm not sure if enough people would use it (instead
of compiling them on their own systems). This would definitely be a lot of
additional work for the maintainers.
> 7) Your idea of the doc-base package is good, but here are some remarks:
> -) The policy the user chooses has to be enforced every time a package
> is installed or de-installed and not only when the doc-base is
> installed. That's trickier, but important!
Sure, but what's the problem with that? We'll just have all maintainers
add a line like
update-docs <insert-your-package-name-here>
(or something very similar) to the postinst and preinst script.
> -) Makeinfo is very fast, even on slow machines. I think there is no
> need to provide pre-compiled info files just to have them deleted
> later. I think you are putting the burden on the wrong side.
This was my last proposal.
> ---------------------------------------------------------------------------
>
> My proposals on documentation:
>
> 1) The preferred format for online documents is compressed HTML.
> The default installation supplies a default web server and a default web
> browser. The user can override that, of course.
Again, we differ here.
> 2) Documents for which on-the-fly conversion is available and fast should be
> included in original format. The list of formats which are OK will change as
> on-the-fly converters improve. Currently it will include plaintext and man
> at the least. (man2html is very fast even in an old system.)
Ok.
> 3) Other documents are classified in two groups:
> 3.a) Human-readable files. They typically are in a markup format.
> Both HTML and original format will be supplied.
>
> 3.b) Machine-readable files. Commonly PS or DVI.
> If no source is available from the upstream author, the files should
> be packaged separately. However, instructions on how to get it and
> a summary of its content should be included with the program.
I'm sorry, but I don't get the idea behind these points.
> 4) Man and info should be optional and not installed by default.
> (makeinfo is very fast even on an old system. Compiling info files when
> installing info is not a problem.)
Are you kidding? "Man" will surely not be dropped in the near future!
After all, I'm very happy that our proposals are getter nearer to each
other. (Perhaps the whole discussion here was just a big
"misunderstanding" :-)
Thanks,
Chris
-- _,, Christian Schwarz
/ o \__ schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
! ___; schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
\ /
\\\______/ ! PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
\ / http://fatman.mathematik.tu-muenchen.de/~schwarz/
-.-.,---,-,-..---,-,-.,----.-.-
"DIE ENTE BLEIBT DRAUSSEN!"
--
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: