[Cairo] format for api docs

[Bill Spitzak]

On Friday 17 October 2003 04:07 am, Carol Spears wrote:

> As a complete user, here is my take on linux documentation...

No matter how the documentation is produced, there had better be final html 
output available for download and for perusal from the Cairo web site. Maybe 
pdf as well but only because people may want to print it. It is ok if there 
are complicated instructions to *produce* this documentation, but the result 
should be available already.

Man pages are not needed, "man" should be changed so it can read (limited) 
html and print it on the terminal (use lynx if necessary). Then all the troff 
input can be scrapped and replaced with html so people can look at it in a 
browser.

docbook, info, rtf, etc: NOBODY wants or uses this stuff. All should be 
mechanically converted to html NOW and that program should be scrapped.

I agree with Carol, it seems a lot of stuff RMS touches is designed 
perversely to make sure GNU/Linux is a playground only for the "elite", 
despite claims to the contrary. There is no reason for hundreds of shared 
libraries or insanely complex layers and layers of programs and scripts, 
other than to make sure that you cannot do anything without extensive 
learning of intricate complexities. And there is no reason to make 
documentation require an user-hostile Emacs-style fixed-pitch interface and 
be unprintable, except to make sure only the smartest can read it. And it is 
insulting to run "man" and see a message that "this is out of date and you 
should read the info" without even a hint as to how you run info, because 
obviously you are too stupid to join the wizardly society.

For similar reasons I really want to see Cairo be ONE library, with no 
dependencies on *anything* that is not considered a standard part of Unix. 
Ideally all of freetype and Xlib would disappear into it eventually, but at 
least for now please don't make *new* libraries other than Cairo. The excuse 
that a few thousand bytes could be saved by putting libpixregion or whatever 
in a shared library so another package can use it is insane. The header files 
should be self-contained, not including any files from other packages, and it 
should be fast and obvious to locate the definition of any structure, and any 
varaible that is an int or double or pointer must be declared as such, not 
hidden with a typedef. To the average "non-elite" programmer of Linux, 
"drawing" is ONE thing, not hundreds of things, and I don't care how much 
logical sense dividing it up makes at a low level, it is not obvious. And the 
think I loved about Unix originally was that it *was* obvious, and simple, 
and you could figure things out by looking at files and guessing.

-- 
                   ,~,~,~,~ ~ ~ ~ ~
     /\_       _|_========___         Bill Spitzak
 ~~~/\/\\~~~~~~\____________/~~~~~~~~ spitzak at d2.com