Re: What about the texi/html policy-project ?
On Fri, 12 Dec 1997, Yann Dirson wrote:
> Santiago Vila Doncel writes:
> > Yann Dirson wrote:
> > > I remember there once was some discussion about whether/where to
> > > install HTML docs created from .texi files. If I remember well, we
> > > mostly agreed that we should install them in a subdirectory of the
> > > package's doc dir, but nobody took a decision about how it should be
> > > named. And nothing was made policy.
> > >
> > > What's the current status of this ?
> >
> > We agreed that all packages should support a new `doc-base' package
> > which would generate .info, .html, .dvi or .ps on demand.
>
> Yes and no: I also remember that there were objections for this
> on-demand generation, for machines with low resources (eg. 386). I
> don't remember seing a consensus about that, at least.
The consensus was to ship the doc-source files (.texi or .sgml) _and_
.html files in each package. With that, we can generate other formats on
demand (i.e., .info, .ps) while we don't need to compile any docs at
installation time (important for slow machines).
(The main reason for this was that texi2html is pretty slow while makeinfo
is fast enough, even on slow machines.)
> What I remember is that someone proposed to come with a doc-base, so
> that we'll be able to judge from a sample implementation.
>
> > [ Of course, I would propose to postpone this for Debian 2.1 ]
>
> Yes, doc-base should probably wait for 2.1 now.
(I proposed the doc-base package.) As I see the current situation, we have
a "rough" consensus about how to implement things. However, some people
are still unsure about how that new policy will affect their packages.
That's why I don't want to raise the discussion again before I had time to
develop a _draft_ version of the documentation policy and a draft of
doc-base. After these two things have been finished, we could start the
discussion again--this time about the details.
Anyways, as I'm currently pretty busy with the other policy changes that
should be implemented before 2.0 and as the new doc-policy will take some
time to implement I also suggest to postpone this for 2.1.
However, I'm still looking for volunteers that could me with some design
issues of doc-base. (I already have one volunteer.) So if someone is
intrested, please drop me a note.
> But we could still make policy right now on the location of HTML'd
> texi files. Even if deity is not ready right now, I think it would be
> a good thing to have already a consistent doc layout when
> part-of-package-exclusions will be available.
>
> We already have a policy on where to put manpages and info files. I
> think having right now a policy for placing HTML and texi-HTML files
> should be a good thing.
The main problem of the new doc-policy is that it includes so many
different aspects: different documentation formats (HTML is default, but
users might want TeX, Info, PostScript, Text, etc.), different languages
(we still don't have a consensus what to do with /usr/doc/LANG), some
design issues of debiandoc-sgml (discussion from debian-doc some time ago:
we want to have "dynamically" cross references), file system structure on
ftp.debian.org and www.debian.org, etc.
Therefore, it's a hard job to solve only one aspect at a time.
Perhaps I can dig into the whole subject within the next days again. I'll
come up with a proposal of how to treat HTML files, then.
Stay tuned,
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!"
Reply to: