Re: cleaning up FT2

[David Turner]

Hi Werner,

> David,
> 
> while cleaning up FT2 (well, just starting in the src/base dir :-),
> I've found some inconsistencies.
> 
> .) Why are header files in `freetype2/src/shared'?  Wouldn't be
>    `freetype2/include' a better place?  If not, I suggest to move the
>    files to `freetype2/src/shared/include' for orthogonality.
>

'freetype2/include' is reserved for those header files that will be
available to users of the library. These should probably be installed
in a directory like "/usr/lib/freetype/include" for a "freetype-devel"
package on a typical Unix box.

'freetype2/src/shared' contains header files that are used by several
font drivers, but are not part of the public API. We may move some of
these later into include but for now, I prefer to keep them here.

And of course, each driver has its own header files, which are used
exclusively for intra-communication of declarations betweens several
.c files for a given driver..

> .) Am I correct that `ttnamedid.h' is a) a typo and b) no longer used?
>
a) certainly, the "d" is a typo as this should be "ttnameid.h"
b) actually, I believe that I wanted to move "freetype2/src/truetype/ttnameid.h"
   to "freetype2/include" but forgot to erase the original file.. grumpp..

   I'll check that now..

> .) I strongly suggest that we avoid duplicated documentation.
>    Functions, function types etc. should be documented in the *.c
>    files, and only stuff not in the *.c files should be described in
>    the *.h files (example: ftbbox.c vs. ftbbox.h).  It's a nightmare
>    otherwise IMHO.
>
All right, I suggest removing documentation comments from the *.c files.
However, we don't need to hurry. Let's simply consider that the "reference"
documentation is always placed in the headers.. that will let us time to
make the removal by hand when we see fit (i.e. modifying source code..)

>    BTW, can you send me your tool for extracting the documentation?
>
I have commited it to "freetype2/docs/docmaker.py". It's tiny python program.
For now, it only parses the documentation, builds a tree of objects for the
documentation, then dump its contents in an unfriendly way (for debugging).

I don't think it'd be hard to change it to spit HTML or readable text but
I didn't take the time to do that for now..

syntax:    ./docmaker.py [file1 ...]


> .) The files in the CVS still have incorrect access permissions, i.e.,
>    the executable flag is still there.
>
Ooops, seems I only fixed the bits in the "freetype" module, not the other
ones... Fixed that. Please check..

Cheers,

- David