On 06.09.2006, at 23:15, Stephen Deasey wrote:
On 9/5/06, Zoran Vasiljevic <[EMAIL PROTECTED]> wrote:
On 05.09.2006, at 19:07, Bernd Eidenschink wrote:
http://wiki2man.sourceforge.net/
Almost (although you are right)! What we need is
wiki->doctools man-pages not nroff man pages.
(what a stupid naming mess !!!)
I wonder if there is a wiki->doctools as I know
there is doctools->wiki converter...
If someone adds some Makefile magic to generate nroff and HTML from
the doctools source, I'll set up sourceforge to auto generate the HTML
straight from CVS and make it available on the website.
This may not be the problem. I will try (honestly!) to make some
directives in the makefile for that. It should be something like
make doc
make mandoc
make htmldoc
where make doc will make both and the others will make
only the corresponding formats.
I will put the putput into the
doc/man
doc/html
and the source files (mainly templates for now) into
doc/src
There's a script in there now which creates symbolic links for all the
commands embedded in a singe file, so if foo, bar, and baz are all
documented in the foo.man file, you can still access bar and baz
directly via 'man bar' etc. Does doctools support anything like this?
I do not thing they can but I'm not 100% sure. I'm afraid it will
be 1:1 (one procedure per file)
We can add some wiki-macros so that whenever you type [proc ns_foo] it
creates a link to /doc/ns_foo.html (or wherever).
If the API doc is always automatically uptodate on the website then
that can be the single canonical location to find everything.
Is there a script which will convert the existing man pages to
doctools format? We can't be the first people to ever have done this.
I do not know. I do not believe there are is such tool ready.
Mostly people either have no content and they start with some
or they already have large existing base in which case they stay
with it. We have few in man, few in wiki, none in doctools.
The reason why I'm for doctools is:
its Tcl
its easy to write
its easy to convert to wiki/html
If we can convert the existing stuff, then strip out the
old/deprecated APIs and stubb out the new ones, I think finding time
to sit down and write something will be much easier.
I believe that converting the existing things is always
going to require manual intervention.
As of today we have:
html pages from old aolserver docs
wiki pages from new aolserver docs
some nroff pages from old aolserver docs
The task to convert all to doctools and then generate
html and man (and wiki) is not small, but once you have
done it, you can automate whatever you want. Plus: the
doctools itself is written in Tcl so it would be easy
for us to tweak it if necessary.
I strongly beleive we should start with doc sources in
doctools and then use converters to auto-generate other
(handful of) formats.
Zoran
