Subject: Re: Documentation formats

From: [email-masked] (Bruce Perens)
Date: Sat, 10 Aug 96 14:47 PDT

Ian,

I am aware of your efforts with linuxdoc.sgml, and I think it's important
to make it clear that HTML is only the end-product. It's fine to encourage
people to use linuxdoc as a source language.

	Thanks

	Bruce

---

From: Ian Jackson <[email-masked]>
Date: Sat, 10 Aug 96 00:25 BST

> people to use linuxdoc as a source language.

Err, yes, errm, I think you've missed my point(s) rather.

The thing is that I think we need to be able to distribute other
end-products.  HTML is bad for printing, for example, and not ideal
if you have a slow machine.   Choice is a good thing.

I think we need some kind of convention for the distribution of
additional end-product documentation formats.  Hence my last message.

BTW, I'm not using linuxdoc-sgml any more.  In the end I wrote my own
DTD (well, hacked up linuxdoc until it was a quarter of the size) and
backends.

Ian.

---

From: [email-masked] (Bruce Perens)
Date: Sun, 11 Aug 96 22:10 PDT

From: Ian Jackson <[email-masked]>
> [documentation] end-products [than HTML].
> HTML is bad for printing, for example, and not ideal

Do you have a proposal? I'm not trying to exclude other formats,
but I'm trying to arrive at a common denominator, even if it
has its detriments.

I'm not sure I agree with the slow machine part. That seems to be
browser-specific.

	Thanks

	Bruce

---

From: Ian Jackson <[email-masked]>
Date: Tue, 13 Aug 96 13:35 BST

> but I'm trying to arrive at a common denominator, even if it

Yes, fine.  I think we're in agreement.  I'll post my proposal in
another message.

> I'm not sure I agree with the slow machine part. That seems to be

Well, even lynx is much slower than less, and has a worse user
interface in some people's eyes.

Ian.

---

From: Ian Jackson <[email-masked]>
Date: Tue, 13 Aug 96 13:47 BST

> > [documentation] end-products [than HTML].
...
> Do you have a proposal?
...

My initial proposal is as follows:

If it's available we distribute HTML documentation with the package
itself (if the documentation is usually distributed with the package)
or in the main documentation package <package>-doc (if it wants to be
distributed separately, for example because it's large).

Other formats are distributed in separate packages <package>-doc*
where * is some string.  We can either put them all together, keeping
the number of packages small, or have one package per format, making
it possible to install formats selectively.  If we do former the *
should probably be `xf' (extra formats) or `fmts' (formats) or some
such; if we do the latter it should represent the format (`dvi', `ps',
`text', whatever).

We can do a mixture of the two, specifying that one or two specific
formats should be supplied in their own packages, or allow the package
maintainer to decide, or set size-based guidelines, or whatever.

Opinions and arguments, anyone ?

Ian.

---

From: Mark Eichin <[email-masked]>
Date: 13 Aug 1996 20:22:30 -0400

if we standardize the names for the alternate formats, can we also
have, for each format foo, a virtual foo-viewer package, and include
it in the dependencies?  (That will, as a side effect, make it easier
to determine which formats are supported in a given package...)

---

From: Lars Wirzenius <[email-masked]>
Date: Thu, 15 Aug 1996 01:23:38 +0300

I'm not certain that distributing HTML with the packages and other formats
separately is a good idea. I think it might be a better idea to continue
as now and use on-line conversions from man and Info to HTML. Pre-converted
HTML should be distributed as separate packages.

Debiandoc (I really need to decide on a new name) can do the conversions.

I think the change is too radical until we've had some more experience
with how well using a web browser for all documentation access works.
I've been using Debiandoc for a while now, and it is decidedly not fast
enough to completely convert me from manual pages (when I know which
manual page I want -- searching for information is nicer with Debiandoc).

-- 
Rural sizes win <[email-masked]> <http://www.iki.fi/liw/>
Please don't Cc: me when replying to my message on a mailing list.

---

From: Ian Jackson <[email-masked]>
Date: Wed, 21 Aug 96 23:04 BST

> to determine which formats are supported in a given package...)

It looks like we don't have a consensus or indeed a technical basis
for a decision on documentation formats, so we'll keep the current
ad-hoc arrangements for the moment.

When we go for a more formalised scheme this sounds like a good idea.

Ian.

---

From: Ian Jackson <[email-masked]>
Date: Sat, 24 Aug 96 18:15 BST

Lars Wirzenius writes ("Re: Documentation formats "):
...
> HTML should be distributed as separate packages.

So you'd rather I put the SGML source for the manuals in the dpkg
binary package, rather than the HTML pre-converted form ?

Conversion of things into HTML is particularly awkward because you end
up with lots of intermediate files.

And, my debiandoc-sgml converters are not exactly fast.  Converting
the dpkg manuals to plain text takes about 5 minutes on my Cx5x86/120
(clock-tripled 40MHz).  This is about 50% of the time it takes to
build a whole new release of dpkg (the HTML converter is much faster).

Ian.

---

From: Lars Wirzenius <[email-masked]>
Date: Sun, 25 Aug 1996 11:17:26 +0300

> binary package, rather than the HTML pre-converted form ?

No, I was talking about man and Info, in my usual unclear fashion, sorry.
The conversions of man and Info to HTML are fairly fast.

-- 
Please read <http://www.iki.fi/liw/mail-to-lasu.html> before mailing me.
Please don't Cc: me when replying to my message on a mailing list.