[Cairo] format for api docs
spitzak at d2.com
Fri Oct 17 10:36:30 PDT 2003
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
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
More information about the cairo