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
remarks:
> * 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.
Yes.
> 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.
Agreed.
David
--
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: