Re: [naviserver-devel] Documentation & website question

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

On 06.09.2006, at 23:15, Stephen Deasey wrote:

> On 9/5/06, Zoran Vasiljevic <zv...@ar...> 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