Re: [naviserver-devel] Documentation & website question

[Zoran V. <zv...@ar...>]

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