Re: 327-gary-clarify-libltdl-api-docs

[Ralf Wildenhues]

Hi Gary,

* Gary V. Vaughan wrote on Wed, Mar 28, 2007 at 01:55:02PM CEST:
> 
> Whilst becoming reacquainted with the guts of libltdl in order to work
> on release blockers, I found myself rewriting this part of the HACKING
> file.
> 
> Okay to commit to HEAD?

Sure, with nits below addressed.

Thanks, and cheers,
Ralf

>   --- HACKING 25 Mar 2007 21:09:42 -0000 1.37
>   +++ HACKING 28 Mar 2007 11:53:23 -0000
>   @@ -287,84 +287,99 @@
>    * The libltdl API uses a layered approach to differentiate internal and
>      external interfaces, among other things.  To keep the abstraction
>      consistent, files in a given layer may only use APIs from files in the
>   -  lower layers.  The exception to this is lt__glibc.h which serves a
>   -  dual purpose, as explained later.
>   +  lower layers.  The ASCII art boxes below represent this stack, from
>   +  top to bottom...
>    
>   -* At the bottom of the stack we have the system abstraction layer,
>   -  which tries to smooth over the cracks where there are differences
>   -  between host systems and compilers.  config.h is generated at
>   -  configure time and is not installed; lt_system.h is an installed
>   -  file and cannot use macros from config.h:
>   +* But first, outside of the stack, there is a convenience header that
>   +  defines the internal interfaces (as evidenced by the `lt__' prefix to
>   +  the filename!) shared between implementation files in the stack, that
>   +  are however not exported to libltdl clients:

'are not' is technically not correct: should not be used by clients
(there is no effort made to hide these symbols on non-w32 systems;
neither do all systems provide means to hide symbols).

>   +* The next file is used both by the headers that implement it (in which
>   +  case its function is to avoid namespace clashes when linking with the
>   +  GNU C library proper) and is included by code that wants to program
>   +  against a glibc like interface, in which case it serves to pull in all

typo `glibc-like', to be consistent with the following line:

>   +  the glibc-like functionality used by libltdl with a simple:
[...]

>   +  api to various system libc interfaces that differ between hosts

Use of both `API' and `api'.

[...]
>   -   lt__private.h
>   +        ,-----------.
>   +   |../config.h|
>   +   `-----------'

Using both tabs and spaces for ASCII art indentation; dunno if being
consistent would be preferable (multiple instances).