Re: cvs commit: apache-devsite/apidoc README dict-ap_cpystrn.html dict-ap_destroy_pool.html dict-ap_make_sub_pool.html

[Ben Laurie <be...@algroup.co.uk>]

Rodent of Unusual Size wrote:
> 
> Ben Laurie wrote:
> >
> > If that's true, why do you have...
> >
> > >   1.1                  apache-devsite/apidoc/dict-ap_destroy_pool.html
> > >
> > >   Index: dict-ap_destroy_pool.html
> > >   ===================================================================
> > >     <P>
> > >     This function will recursively destroy the specified
> > >     <A HREF="#pool">pool</A> allocation area and any sub-pools of it,
> > This..^^^^^^^^^^^^^^^^ ?
> 
> I don't think I understand the question..  That's the doc file for the
> routine.  Only the example and definition sections are automatically
> parsed for link targets.  It's perfectly reasonable to add links to
> the doc file; that's why the README explains the target naming.
> 
> What am I missing?

Oh, I see. Why don't the doc files get it done automatically, then?

Cheers,

Ben.

-- 
Ben Laurie            |Phone: +44 (181) 735 0686|  Apache Group member
Freelance Consultant  |Fax:   +44 (181) 735 0689|http://www.apache.org
and Technical Director|Email: ben@algroup.co.uk |
A.L. Digital Ltd,     |Apache-SSL author    http://www.apache-ssl.org/
London, England.      |"Apache: TDG" http://www.ora.com/catalog/apache

Re: cvs commit: apache-devsite/apidoc README dict-ap_cpystrn.html dict-ap_destroy_pool.html dict-ap_make_sub_pool.html

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

Ben Laurie wrote:
> 
> Oh, I see. Why don't the doc files get it done automatically, then?

I didn't do that in the current version for a few reasons:

 . The doc file is included verbatim; someone wrote it to look
   the way it does.
 . Marking up the doc file contents would almost certainly push
   lots of lines past column 80.
 . Some sections would probably end up so liberally sprinkled
   with links as to be annoying.
 . Each link adds 16 bytes to the file.
 . Dealing with word forms gets difficult - should "pool" be a
   link but "pools" not?
 . What if a doc file talks about the server's "pool of children"?
   Or "the module source files"?  Parsing by intent is a little
   problematical..

However, most of these would only apply to common multi-value words
like "pool" or "module" and so it might not be a big deal.  I'm
not opposed to giving it a try.. but I don't think it would be an
improvement.

#ken	P-)}

Ken Coar                    <http://Web.Golux.Com/coar/>
Apache Group member         <http://www.apache.org/>
"Apache Server for Dummies" <http://Web.Golux.Com/coar/ASFD/>