Re: Documentation stuff
>>>>> Jim Pick writes:
Jim> dwww is meant to integrate the existing documentation
Jim> formats for convenience, but not replace all of them.
Jim> 2) All the documentation should be viewable via HTML if dwww
Jim> is installed - but it shouldn't be necessary to have HTML
Jim> versions of something that is already in info or man format.
Jim> If there is an HTML version that looks better, by all means
Jim> include it (if it's small, put it in the same package,
Jim> otherwise use a separate package).
I agree. I prefer to use Info in XEmacs to html, whenever
possible... I think that the Info browser and TeXinfo could be
improved. Someday I'll look at HyperTeX, and learn about that. It
might be neat to have pop-up glossary balloons, and active URL's in
info. If you don't use Emacs or XEmacs, you're not serious anyhow.
I really want the glimpse searching that TkMan has, but within the
XEmacs interface. `dwww' has it, but for some reason it does not find
as many manual entries as Tkman does for the same search. I wonder
why? Perhaps a generalized perl script (or pull the tcl out of tkman
that does it?) could do the search, and spit out the links for XEmacs
or dwww to parse and display?
I'm using W3 now, so html isn't that bad an option. I can still have
almost everything inside the editor interface that way. I really love
having `webster-www' bound to {f2}, so I can look up a word in a
really nifty fashion.
Jim> 3) I'd recommend using something like Debiandoc-SGML for
Jim> documentation written directly for Debian. But this should
Jim> be optional. I like it because it will work nicely with dwww
Jim> (and without), plus it is fairly consistent, and can be
Jim> converted to multiple formats. We discussed some nice
Jim> enhancements for it on the debian-doc mailing list which
Jim> should work quite nicely.
It occured to me today that it would be good to have an rfc index,
too. Maybe it would have the <a href...>'s link through a cgi script
that would check for a local copy, then go get a remote one if the
local one's not around? Perhaps it could cache them?
I've got the doc-rfc package installed. `dwww' might call on a
module for searching that someday, perhaps.
Gee, maybe HTML should support alternative URL's? The first try to
the local copy, if that's not there, then call out to a server on the
net. There could be <META-html> style variables in the markup to set
up the base directories/servers.
Jim> HTML shouldn't be used to replace info files shipped with
Jim> GNU software either.
Right. The two ideal documantation formats should coalesce and
become something better.
Jim> 4) HTML documentation, if it exists, should be gzipped. Lynx
Jim> and Netscape can handle the compressed files, provided that
Jim> the links are straightened out using a tool like fixhrefgz.
Can't apache do that? I think there's a mod-rewrite that will do
what we need. Though I suppose not everyone runs apache... You tell
me and we'll both know. I think it's a good idea to have a
light-weight server that can launch from xinetd.
Q: How do I get netscape to gunzip again??? It used to let me view
gzipped html, but now it won't do it. I just tried W3, and it does
the same thing. What's the MIME types recipe?
Jim> 5) It would be nice if Diety could install just
Jim> documentation, or just the binaries, and no documentation.
Yes!
Jim> 6) dwww will let us serve documentation directly off of an
Jim> external site, so it would be nice to have a way of
Jim> installing the packages with no documentation at all.
Sound's good... what about the ability to install a documentation
server on a LAN too?
Jim> 7) Cacheing - I'm going to split the cacheing in dwww into a
Jim> separate package. That way, it should be easy to improve it,
Jim> not use it, or use something like squid instead.
Ok here. :-) (back to the bat book.)
--
Karl M. Hegbloom <karlheg@inetarena.com>
http://www.inetarena.com/~karlheg
Portland, OR USA
Debian GNU 1.3 Linux 2.1.36 AMD K5 PR-133
--
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: