Re: [TCLCORE] Documentation roundup

[Chris W. <xt...@de...>]

On Thu, Apr 17, 2003 at 08:29:33PM -0700, Peter MacDonald wrote:
> Well, on the topic of documentation, it would be nice if the Tcl/Tk docs
> were a little more accessable on Unix.

What could be more accessible than actual man pages?  That's the
standard format for documentation on Unix systems.  I've worked with
plenty of unix systems that *only* supported man pages for
documentation, but I've never seen a unix or unix-like system that
didn't support man pages.

I can't imagine what more you would want or why.  TeXinfo?  Docbook?
Some sort of html-ized kludge?  None of those are standard or
universal, although TeXinfo is pretty common these days, and Docbook
is powerful and flexible, and can be used to generate a wide variety
of formats including man pages.

> As a start, maybe adding the following
> optional target to the unix/Makefile.

> html:

Ack, twang.  *sigh*

>         mkdir -p $(prefix)/share/tk$(VERSION)/html

This is not a standard location; at the very least, please use a
variable for the "/share/" part, so that those of us who have to deal
with standards can make this do something sensible without too much
pain.  (Assuming the Debian users don't allow me to just ignore this
whole ill-conceived notion.)

>         cd $(SRC_DIR)/doc; for j in *.n; do man2html ./$$j > 

man2html is not a standard unix command.  It's not even a standard
Linux command, although it's probably most common on Linux systems.

> $(prefix)/share/tk$(VERSION)/html/$$j.html 2> /dev/null; done

Again, the hard-coded wrong location.  

And why is sticking some random html files in some obscure directory
better than standard unix man pages again?  And why would you stick
html files somewhere where the httpd (if there is one) can't find
them?  And what about all the unix systems that don't have a browser
installed?  (The vast majority of the ones I work with, for example.)

Oh well, I'm not actually in the core team, so I'll leave it up to
them, but if I were, I would vote a resounding no on this.

cheers
-- 
Chris Waters           |  Pneumonoultra-        osis is too long
xt...@de...       |  microscopicsilico-    to fit into a single
or xt...@sp... |  volcaniconi-          standalone haiku