Subject: Documentation formats

From: Ian Jackson <[email-masked]>
Date: Mon, 5 Aug 96 12:36 BST

Increasingly, documentation is in a generic markup format that can be
processed into various output formats either by standard tools or ones
that come with the package.

For example:
 * GNU Texinfo can be converted to Info, DVI (and hence rather large
   PostScript) and HTML.
 * The Linux FAQ comes in plain ASCII, HTML, Info, and PostScript via
   Lout.
 * The Linux HOWTOs are done in linuxdoc-sgml, which produces ASCII,
   HTML, Info and LaTeX (hence DVI and large PostScript).
 * My new dpkg manuals will be available in plain ASCII, overstruck
   ASCII, HTML and Postscript (via Lout).
 * The Perl documentation can be converted to HTML, plain text,
   manpage source (hence overstruck text and PostScript) and LaTeX
   (hence DVI and large PostScript).

We need to decide which documentation formats we wish to distribute,
and how to manage their display.  Obviously we can't distribute all of
the output formats as that will either make packages too large or
produce too many packages.

For some of the formats you can process the data `on the fly' as it is
viewed; for others (at least TeX, Lout and HTML) this is trickier as
the processing or viewing involves dumping the formatted document to a
file, or storing some kind of auxiliary data in files while it's being
processed.

Options for our policy include:
 1. Specify one or two particular preferred target formats and
    distribute those.  Leave the source in the source package.  So far
    we have done this with documentation in Texinfo - we leave the
    .texi files in the source package and distribute only the info
    files.
 2. Distribute the source only and a converter.  This has been done
    with manpages, and with the Perl `pod' documentation.
 3. Distribute the source and one target format for people who don't
    have or want converters.
 4. Do something fancy with Lars's documentation viewing stuff.  I'm
    sure Lars will tell us about this.

My inclination is to go for 4 with 2 or 3, if that makes sense.

Ian.

---

From: Lars Wirzenius <[email-masked]>
Date: Mon, 05 Aug 1996 18:06:01 +0300

Ian Jackson (after my deletions):
>  * GNU Texinfo ... HTML.
>  * The Linux FAQ ... HTML ...
>  * The Linux HOWTOs ... HTML ...
>  * My new dpkg manuals ... HTML ...
>  * The Perl documentation ... HTML

I think I see a trend here. While HTML is not the perfect format (e.g.,
it lacks the navigation hints in Info), it is still the only common
denominator, and I guess most people will have a web browser installed
anyway.

We must still support the native versions. Not everyone will want or
prefer a web browser over Info or manual pages.

Debiandoc can handle on-line conversions.  Some of the conversions aren't
too good. For example, texi2html seems to do a better job than info2www,
and I'm told this is inherent. Thus, it would be a good idea to provide
texi2html'd versions of the Info files as optional packages.

The FAQ's, HOWTO's, and other such stuff should also be made available
as optional HTML versions, if one is currently not part of the main
package.

Summary: status quo, but provide optional HTML packages.

This leaves us with the problem of having the same documentation in
several formats installed at the same time, which is usually a waste
of disk space. This is solvable with some programming: provide tools
to identify and remove duplicate documents. It's a SMOP, as long as I
don't have to do it. :-)

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

---

From: [email-masked] (Erick Branderhorst)
Date: Mon, 5 Aug 1996 15:59:42 +0100

> My inclination is to go for 4 with 2 or 3, if that makes sense.

And get rid of the .info files, using w3-el on texi2html .texi files. Sorry
but this isn't very fast on an 8mb machine.  It might be that I don't
understand the above, but for me w3-el via texi2html on the fly is a very
fast and therefore unwanted alternative for the info-reader in emacs.  I
presume quite some others agree with me.

Erick

---

From: [email-masked] (Emilio Lopes)
Date: Tue, 6 Aug 96 20:33 EST

>>>>> "LW" == Lars Wirzenius <[email-masked]> wrote:

>> * The Perl documentation ... HTML

LW> I think I see a trend here. While HTML is not the perfect format (e.g.,
LW> it lacks the navigation hints in Info), it is still the only
LW> common

There is a great advantage of info over html: you can search an entire
document with it. I think this is fundamental.

LW> denominator, and I guess most people will have a web browser
LW> installed anyway.

People who have standalone machines might not want to install a www
browser.

Lynx is ugly (JMHO). Can't really use it. Nevertheless, I must be able
to read docs in text mode.

IMHO info is a great format. After reading some discussion on
gnu.misc.disc I'm pretty convinced that it's currently the best format
for online docs (and don't forget texinfo files can also generate
printed manuals) and that we should try it a bit more. The real
problem are the info browsers. The last version I checked of the
standalone "info" program simply sucks. Maybe someone with a good
knowledge of termlib should take a look at it. Maybe add some mouse
support via gpm?

What about xinfo? Is this any good? Yes, I know there is tkinfo, but
it needs tcl/tk...

Ciao, Emilio.

-- 
                 Emilio C. Lopes <mailto:[email-masked]>
               Instituto de Fisica da Universidade de Sao Paulo
             Caixa Postal 66318, 05389-970 Sao Paulo - SP, BRAZIL
              Phone: (+55) (11) 818-6724 (Voice) / 818-6715 (Fax)

---

From: [email-masked] (Kai Henningsen)
Date: 08 Aug 1996 12:55:00 +0200

> IMHO info is a great format. After reading some discussion on

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. Hell, it  
doesn't even have working cursor key support!

(And *don't* tell me to use Emacs. I don't want that monster.)

On the other hand, the search problem with HTML can certainly be solved.

Personally, I think what's needed is a sort of extremely light-weight http  
server for this stuff. Shouldn't be too hard; maybe I'll look into that  
when I come back from my vacation. Could probably even be written in Perl  
:-)

> standalone "info" program simply sucks. Maybe someone with a good

Oh, I see we don't disagree that much :-)

MfG Kai