Subject: Re: Documentation formats

From: [email-masked] (Bruce Perens)
Date: Fri, 9 Aug 96 17:41 PDT

Someone:
> IMHO info is a great format.
From: [email-masked] (Kai Henningsen)
> Actually, I have just about the same problems with info that you
> have with  lynx - it's ugly, it has a *really* arcane user interface.

*** Project Leader Fiat Power On ***

The unification of Debian documentation will be carried out via
HTML. You should not consider the merits of a particular HTML viewer,
or even the weight of the best of our existing HTTP servers. These things
will change with time, and without effort on our part. Instead, you
should concentrate in providing automatic means to present man files,
info files, and other various forms of documentation to the user. This
can be done at run-time via CGI scripts, or when the documentation packages
are installed. Use existing software where possible. Try to consider disk
space, but having a full documentation system takes priority over that.
A keyword search facility and a unifying set of indices are a high
priority.

Look at what Ray Dassen has done on our web site. That is a really good
start. Now think of the top-level index to Debian documentation coming up
in a web browser when the new user starts the system.

*** Project Leader Fiat Power Off ***

	Thanks

	Bruce

---

From: Rob Browning <[email-masked]>
Date: 09 Aug 1996 11:42:39 -0500

Lars Wirzenius <[email-masked]> writes:

> I don't think we have free software packaged to do full text searches.
> We have glimpse and ferret, neither of which is free. There's something
> that is part of freeWais, but I haven't looked at it yet. Someone with
> the time should find and package one. It should be usable from the
> command line so that it can easily be integrated into Debiandoc.

It'd be nice to have something like altavista, that could generate a
page containing a (heirarchical) list of the references found.

--
Rob

---

From: Lars Wirzenius <[email-masked]>
Date: Fri, 09 Aug 1996 17:26:26 +0300

Bruce Perens:
> The unification of Debian documentation will be carried out via HTML. 

I assume the unification won't mean that the native formats aren't 
supported -- they _do_ have benefits.

That said, I fully agree with choosing HTML. Debiandoc, supports on-line
conversions to HTML from man and text, and info2www supports Info (it
isn't really integrated, but it's not really visible). The converters
are configurable.

In addition, I think we should provide texi2html'd documentation in 
addition to Info files. texi2html seems to do a better job than info2www.

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

---

From: "Susan G. Kleinmann" <[email-masked]>
Date: Sat, 10 Aug 1996 17:05:16 -0400

> page containing a (heirarchical) list of the references found.

The search program ht://Dig (which has an admittedly odd name) comes with the
GNU general public license.  Its home page is:
         http://htdig.sdsu.edu/

Also, there's been a Javascript on comp.infosystems.www.authoring.cgi 
that uses the Altavista search engine to search only your own site.  
(Seems like exploiting rather than excluding robots.)

Regards,
Susan Kleinmann

---

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

Bruce Perens writes ("Re: Documentation formats"):
...
> A keyword search facility and a unifying set of indices are a high

Texinfo-generated info files are very common for obvious reasons.

Do we start distributing Texinfo-generated HTML instead ?  (Is
texi2html any good ?)  Or do we do some kind of display-time
conversion from info to HTML ?  Or leave the question for the moment ?

Ian.

---

From: [email-masked] (Bruce Perens)
Date: Tue, 13 Aug 96 15:41 PDT

> Or do we do some kind of display-time conversion from info to HTML ?

This is probably best.

	Thanks

	Bruce
--
       Clinton isn't perfect, but I like him a lot more than Dole.
            Please register to vote, and vote for Democrats.
Bruce Perens AB6YM          [email-masked]            http://www.hams.com/

---

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

> (Is texi2html any good?)

http://www.cygnus.com/ (and I'm sure other places) has texi2html'ed
versions of gnu compiler-related tools, if you want a quick look at
them.

---

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

Ian Jackson:
> Do we start distributing Texinfo-generated HTML instead ? [...]

I'd suggest both. texi2html seems to do a nicer job than info2www,
but we shouldn't require people to install both HTML and Info versions
on sites where some people want HTML and others Info.

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

Mark Eichin writes ("Re: Documentation formats"):
> [Ian asked:]

Thanks.  They do look reasonable.

Ian.