[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: End of Documentation Discussion

On Fri, Jun 27 1997 16:10 CDT John Goerzen writes:
John, I agree with the overall contents of your remarks. Just some
>  * HTML cannot do very much with formatting.
>  * HTML cannot be easily printed.
>  * HTML cannot be easily grepped.

I fully agree.

> I think that other formats have the following problems:
>  * PostScript makes very nice printed output, but it difficult to
>    search and requires a fairly expensive graphical monitor to be
>    able to read on-screen reasonably.
And it is generally too large for its contents.

>  * LaTeX also makes nice printed output and can be converted to
>    HTML as well as other formats, but such conversion on-the-fly is
>    not practical due to the huge size of the LaTeX system.
And the conversion is generally poor.

>  * GNU Info has an awkward interface and is difficult to search.
>    It is also nearly impossible to print an entire manual from the
>    files in the info directory.
This is not meant to be. If you want to print something, convert the
.texi files to dvi!

>  * Manpages are portable, searchable, and produce nice printed ouput
>    with man -t.  However, for very long manuals, they are not
>    approprriate.
I agree.

> I would suggest either of the following:
>  * DVI format.  It can be converted to HTML (I think...) and plain
Nope, not possible. In DVI you have lost the structure information.

>    text on-the-fly.  It can also be converted to PostScript and
>    have very nice printed documentation.

>    searchable.  Downside: conversion to PostScript requires
>    significant disk resources (fonts!) and can be a lengthy process.
>    On second thought, maybe DVI isn't the best choice... :-)
No. DVI is not font-independent (unfortunately).

> All packages should ideally provide manpages (although there are a few
> exceptions).  
Rewrite this to: `All packages provide manpages'.

> Packages providing additional documentation should use
> GNU info format or LinuxDoc/SGML format.  There should be a script or
GNU texinfo (in the source package)

> program available to convert SGML to HTML on-the-fly (shouldn't be
> hard since we already have the tools to do that).  Various other
> documentation provided by the upstream author should be converted to
> SGML if possible; if not, it should be included untouched.
Probably yes, although I don't exactly love SGML.

> Just to summarize: I believe that HTML is a VERY BAD choice for
> unification of documentation for the reasons outlined above. 


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: