On 04.09.2006, at 22:43, Stephen Deasey wrote:
I was looking at the docs too. I installed fedoras tcllib and there's
a doctools lib, but no standalone tool to convert things. Should
there be? Or where does this live?
zvpb:~/meta/usr/local/aw/log zoran$ dtplite
/usr/local/bin/dtplite wrong#args, expected: -o outputpath ?-merge? ?-
ext ext? ?-style file? ?-header file? ?-footer file? ?-nav label
url?... format inputpath
This gets done if you "make install" the tcllib.
Also, how are folks converting the templates to man and html pages? I
can't see any Makefile rules, in the Tcl thread package for example.
Are people just converting by hand and putting the result in CVS?
The "folks" in the Tcl threading extension (i.e. myself) are not
doing it from the makefile. I have a Tcl script doing the conversion
and I hit that script once per hand before doing the distribution.
A million$ question: why not over makefile?
Answer: perhaps I'm lazy to write a makefile rule for that?
I dunno about the below -- docs live in
/usr/shar/doc/naviserver-x.x... I'd like to make things more
standard, not less.
I see the docs in two parts, the man pages, which are a technical
reference, and the HOWTO stuff. Seems to me like the technical ref
should be kept uptodate with the code, and the HOWTO stuff on the
wiki, where people can, hopefully, update it.
Agree 100%. The technical reference should be preferably
in form of man pages (I never look ANY Tcl docs except man-pages)
and optionally in HTML for those bright young people arround
(not including me).
The HOWTO should be definitely a Wiki.
But, it is the former where problems start. As it may be in
several usable formats (nroff, perhaps man, perhaps pdf).
Pointing people in the right direction is a good idea though. How
about a default start page for the installed server which focusses
more on what to do next, rather than advertising? Could point to the
installed html version of the docs with a file:/// reference, and the
online wiki for HOWTO stuff, talk about the reference config file, and
the the stats module can be enabled for introspection stuff.
Nothing to object to.
The current index.adp in contrib doesn't mention any docs at all...
Or how t osign up to the mailing list, or how to report a bug, or how
to find modules to install...
Ditto...
I believe the best way to do that is get somebody new use the code
and tell him to document all that he/she finds odd or missing :-)
We are (I am) far too much into it over the years and it looks all
so "known" to me that I really have to motivate myself to write that
"obvious" things.
Zoran
