Date: Thu, 24 Jul 1997 11:56:28 -0400 (EDT)
From: Stanley Gambarin <stanleyg@cs.bu.edu>
To: new-httpd@apache.org
Subject: Re: documentation stuff
In-Reply-To: <Pine.LNX.3.95dg3.970723220301.7392F-100000@twinlark.arctic.org>
Message-ID: <Pine.GSO.3.95q.970724110548.27726B-100000@csa>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Sender: new-httpd-owner@apache.org
Precedence: bulk
Reply-To: new-httpd@apache.org


On Wed, 23 Jul 1997, Dean Gaudet wrote:

> What do we feel about using POD format to integrate this sort of thing
> with the code directly?  (POD and C get along together, don't they?) 
> 

	Thanks for reading the stuff... it must have been painful :)
My opinion on the using POD inside the code is a no-no.  This would 
contribute to code bloat in a huge way, as documentation that i write
usually surpasses the size of documented code.  A possible solution is to
provide a comment header before each function which contains http link to
the corresponding .html file and html file can contain a link to the 
corresponding source file, where the function is defined.

> >     pool *make_sub_pool (pool *pp)
> >         Create and return a subpool of the pp.
> 
> This is pretty much all you should say for make_sub_pool.  Although you
> should note that even though it is a "sub pool", memory allocation within
> it are in distinct chunks of memory.  So there's no/little fragmentation
> potential.

	Not fully agreed. (a) the documentation should provide all error 
conditions that may be generated by the function call (returning NULL?)
(b) "Current" implementation uses distinct chunks of memory... the idea is
to provide a documentation, such as if Mr. Bob Jones would like to
implement his own pool alternative, all he has to do is to conform to the 
provided API.

> >     void register_cleanup (pool *p, void *data, (void *)plain_cleanup (void *), void (*child_cleanup)(void *))
> >         pool, while function pointed to by the child_cleanup is
> >         invoked on the subpools of the pool p.
> 
> Not correct.  The child_cleanup is used after a fork() to clean up
> resources in the child.  Specifically consider a FILE *.  A FILE * should
> be fclose()d exactly once, otherwise it may have part of its buffer
> flushed twice, leading to corrupt output.  So notice that the
> child_cleanup for a FILE * just does a close(fileno(f))... which doesn't
> flush the buffer.

	This is exactly what is needed in the documentation.  I just read 
the code and tried to see where it is used.

> >         Example: run_cleanup (p, NULL, generic_cleanup);
> 
> Interesting that we don't have a child equiv for this one.

	Actually, the code calls run_cleanup() for both plain_cleanup and
child_clean parameters for generic_cleanup.

> >         regex()
> >         This function provides an Apache's interface to the regular
> >         expression engine which is bundled with the web server. A
> >         pool p is used to allocate any additional memory that maybe
> >         required.
> 
> Actually no pool is created ... it just registers cleanups for the compiled
> regex_t in the pool p.

	I did not say created..i said used, as pool p is used to allocate
the memory for the matching expression (using pcalloc()).


	I am currently in the process of the revamping the documentation
system (playfully named A(pache) D(ocumentation) P(roject)) which is going
to take some time to implement.  In the meantime, would appreciate any
suggestions that people may have on the design.  Should have some
preliminary version available hopefully by september (but i target this
for 2.0,so i guess i am in no hurry :()  Current document directory
structure (not complete by any means) include something of the following:

+ search
+ intro
	+ welcome to apache
	+ how to use this documentation
	+ what is apache
	+ history of the apache server
	+ apache group
	+ notes on versioning (i.e this documentation is for 2.0 release)
+ apache user
	+ intro
		+ obtaining apache
		+ compiling apache
		+ starting/restarting/killing server
	+ configuration
		+ enabling multiple logs
		+ enabling virtual hosts
		+ directives
			+ core
			+ modules
		+ a bunch of other stuff 	
	+ apache server support
		+ reporting problems
		+ ciswu
		+ mailing list
		+ external support organization
+ apache developer
	+ coding style
	+ module developer
		+ intro
			+ targeted audience
			+ why do we need extra modules
		+ API exposed to module developer
			+ memory
			+ file/network i/o
			+ logging/debugging
			+ request hooks
		+ implementing module in C
			+ functions
			+ registering module
		+ implementing module in Perl
			+ functions
			+ registering module
		+ testing your module
		+ submitting a module
			+ core/distributed
			+ module registry 
	+ core developer
		+ intro
			+ targeted audience
			+ submitting changes
		+ OS limitations
			+ fds / slack
			+ accept(), etc.
		+ design of the subsystems (detailed design of subsystems)
			+ memory
			+ file/network i/o
			+ protocol implementation
			+ request processing
			+ trace/debugging/logging facility
	+ porting
		+ adding new ported system
		+ compile time options
	+ performance
		+ optimizing code
+ future
	+ requested features	
	+ planned enhancements
	+ timeline

	If i missed anything, please say so.  To start with, .html format
will be used, which will then be transformed to .hlp (for win32 users) and
simple text for some os us at more disadvantaged positions.
						Stanley.