support program documentation

[Joshua Slive <jo...@slive.ca>]

At the moment, almost none of the support programs included with Apache
are documented in the manual.  However, most of them do have man pages. I
think that we should add a section or link on the front page of the manual
for "Support Programs" which will include

-apachectl
-apxs
-dbmmanage
-htdigest
-htpasswd
-log_server_status
-log_resolve
-rotatelogs
-split-logfile
-suexec

(Perhaps a few of the small perl scripts like log_server_status,
log_resolve, and split-logfile, should be grouped under an "other" page.)

The question is how to do this without creating a bunch of duplicate,
difficult to maintain docs.  We could just use "man2html" to convert the
man pages, but this program creates horrible HTML, and would require
hand-tweaking of the output in any case. I don't think there is any way of
avoiding the fact that future changes will need to be made both to the man
page and the html docs.

Any ideas?

Joshua.

Re: support program documentation

[Rodent of Unusual Size <Ke...@Golux.Com>]

Joshua Slive wrote:
> 
> Awh, just screw it.  These scripts don't really do anything but
> sprinkle a few "<b>"s around.

Yar, I had to go through and make lots of fixes on the output
of man2html when I put my autoresponder.1 page online.

Now, if someone wanted to muck with a troff HTML device driver.. :-)
-- 
#ken    P-)}

Ken Coar                    <http://Golux.Com/coar/>
Apache Software Foundation  <http://www.apache.org/>
"Apache Server for Dummies" <http://Apache-Server.Com/>
"Apache Server Unleashed"   <http://ApacheUnleashed.Com/>

Re: support program documentation

[Joshua Slive <jo...@slive.ca>]

On Mon, 8 Jan 2001, Tony Finch wrote:

> Joshua Slive <jo...@slive.ca> wrote:
> >
> >The question is how to do this without creating a bunch of duplicate,
> >difficult to maintain docs.  We could just use "man2html" to convert the
> >man pages, but this program creates horrible HTML, and would require
> >hand-tweaking of the output in any case.
>
> http://www.freebsd.org/cgi/man.cgi does a good job -- perhaps we could
> adapt it.
>
> >I don't think there is any way of avoiding the fact that future
> >changes will need to be made both to the man page and the html docs.
>
> I don't see why we can't just re-run the autogeneration of the html
> after changing the man page.

Awh, just screw it.  These scripts don't really do anything but
sprinkle a few "<b>"s around.  I don't think it is worth the
hassel of customizing one for Apache.  Here is an alternate
proposal:

1. nroff -man man-page.8 > man-page.txt
2. Remove the page breaks and other assorted crap from man-page.txt.
3. Wrap the darn thing in our basic HTML headers and footers
and a great big <pre></pre> block.

This will require some manual work when things change, but
not a great deal.

Any better ideas?

Joshua.

Re: support program documentation

[Tony Finch <do...@dotat.at>]

Joshua Slive <jo...@slive.ca> wrote:
>
>The question is how to do this without creating a bunch of duplicate,
>difficult to maintain docs.  We could just use "man2html" to convert the
>man pages, but this program creates horrible HTML, and would require
>hand-tweaking of the output in any case.

http://www.freebsd.org/cgi/man.cgi does a good job -- perhaps we could
adapt it.

>I don't think there is any way of avoiding the fact that future
>changes will need to be made both to the man page and the html docs.

I don't see why we can't just re-run the autogeneration of the html
after changing the man page.

Tony.
-- 
f.a.n.finch    fanf@covalent.net    dot@dotat.at
"Well, as long as they can think we'll have our problems.
But those whom we're using cannot think."