[Cairo] format for api docs

[Carol Spears]

Thomas Hunger wrote:
> 
> Hello,
> if someone wanted to write some api docs, what would be the best way to do it?
> I like Gtkdoc very much, but a friend of mine said that not all people like
> in-source-documentation.
> Is there a plan?

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

I can easily build many very complicated software applications on my
elite linux box.  I claim to run an elite box since I need to use debian
sid to get Netscape3 (my favorite mailer back.  I have to run a
"bleeding edge" linux box to get this simple mailer/browser to work. I
didn't want to be elite; I wanted a simple mailer that was attached to
the browser.  I am lazy.  I run elite software because I am lazy, I
guess.

I managed to build gtk-docs *once*.  I build amazing image renderers and
kernels and other impressive impressive software thingies. It is amazing
how my build tools work to build software on many different operating
systems (past and present) yet cannot build documentation.  
Documentation was the only thing computers could share easily with me in
the early days.  Think back.  What the hell happened?

If I want documentation at home, or I want to contribute, this is not
good.

The last time I tried to build gtk2 from a tarball, I got stopped as I
needed to install a bunch of software that simply did not work for me.

Funny that my issue with this software was that the author information
was buried.  By buried, I mean that xslt is the way to go, yet the
deeper the nesting of the information, the more difficult it is to reach
in and get it.  Which actually makes sense, by design.  But the author
information was really really hidden in the format I was being forced to
have a dependency on.  I love the authors.  Especially when I pay the
publishers for the book, I should get my free software free and easily
scoop author information out as well.  At the free level, the author
should be as easy to get to as the group that supports them, perhaps
easier to contact the author at the free level (authors choice) than the
group I gave the cash to.  How dare them to hide the info like that
about who you all are.  I will buy the book or did.  Photos of my books
available upon request.  The receipts are long gone since I had no issue
with getting them and never wanted to return them.  This is your share
though.  This is what you asked.  At the free level, put the author at
the same level in the nesting as the publisher.

I love the books that this format writes.  I spend my actual money on
them, and I don't have much money.  I want to know who the authors you
support are and display this information as easily as who got my money. 
I even go so far as to respect the authors you choose and you for
choosing them.  Let me know who they are; and trust your advertising
group to tell me who you are; that is what you pay them for.  Maybe you
don't trust them and are fiddling with my free software?  I ask that you
stop this.  

All I ask is that the documentation not be dependent on such a self
serving vehicle as the people who financially supported docbook have
made docbook be.  God bless them, their books used to have *good*
bindings.  So hiding the authors has not really helped them as much as
they thought, maybe.

If the documentation could just be there (not dependent on software I
did not like to use), I think I can make the gizzmo that will read it
and give everyone the credit they deserve.  *Everyone*.  That is my
goal.  I would like to build gtk+ and gtk2 and the documentation using
whatever documentation "scooper and writer" that I choose.

At the free level, allow me to choose or create software to build the
documentation.  Or just leave it there in text form and let me figure
out how to get the documentation out.  Offer the documentation for free
download as html or sgml or dvi  and sell your software at this level as
your authors sell their software.  I got pissy when I was in a corner
with no choices.  The one thing I get from working with freesoftware is
not being dependent on one format or another.  What are you doing to me? 
When there are books online that I use often, I buy them.  If nothing
else, they make great pillows.  I love them.  I brag about them, and
have people look at them and let them touch them even.  Please stop
hiding the authors; you don't have to promote them, I will.  I am
willing to figure out the best way to build the documentation 

I would like whatever documentation that the free software guys are
willing to write to be available for me to handle how I would like to
handle it.  Maybe make me use software to read it online that hides the
author information as well as docbook does? That would be your choice,
but instead, it got attached to my widgets.  

I just want to build the software.  I have very reasonable expectations
right now.  Make it easy for me to get to the author, myself.

Maybe I should start to hide the corporations to the level they have
hidden the authors from me; as they hide the authors of the software
they live on.

I bought it!  Get the corps out of the free part.  The free stuff is
already hard enough.

carol