On Sun, Jun 13, 2004 at 01:52:36AM +0200, Johan Dahlin wrote: > > >1) Include the reference manual in the pygtk tarball (like in gtk+) > > > > > >2) Likewise for the tutorial > > > > > I would hesitate to include these in the tarball because of their size. > > The reference manual html is 710kB and the tutorial is 2.3MB. The source > > for these is about the same. > > Okay, maybe not the tutorial then since it's quite big. But I can't > really see why it's an issue to include another 600-700 k in the > tarball, the benefits are big.
Are the benefits so big, though? I don't think it's such a big problem to include in the doc/ directory a README that points to the downloadable tarballs and CVS -- whoever wants the file will be happy to download it, and who doesn't isn't bothered by the extra time to pull it. > > >3) Generate .devhelp files on the fly > > > > > What are these? > > Basically a toc tree and a list of functions/methods. > Maybe you should try out devhelp and look at the .devhelp files to get > an idea how it works. These would be generated from the HTML docs themselves? > > I find the GTK/GDK documentation index really confusing and fragmented > > and it's hard to find where a particular reference page is. I much > > prefer an alphabetical listing. We could have both types of indexes, I > > suppose. > > For me it's the opposite, I find the list of classes quite bad, > especially for beginners. But for sure, both of them are needed. I never sifted around the reference documentation without knowing what class I was looking for, but I agree that there's a pattern where somebody goes searching through the docs for topic X without knowing necessarily what class implements what is necessary. > > Does this mean that if you change the PyGTK API or add to it that you > > must also change the documentation or that you can't change the > > documentation unless there is an API change or addition? I'm guessing > > the former but I could interpret the wording as the latter. > > Ideally yes. I'm not sure if I can get everyone to agree on it though. I think this isn't a difficult constraint, given the fact that very little public API is "changed" in general (if anything, we seem to generally end up changing the code to agree with the docs, and not vice-versa). Gustavo is always against everything that would help improve our process, anyway <wink>. I'd be happy to comply with this requirement, though it does push the point that the reference docs should be kept together with the code. The way I see it is that it all depends on how we're going to treat the reference docs; whether we want to continue maintaining them independently, or take it under the pygtk.org code people to maintain it now that it's been "completed". I'd like to defer to John this decision, for the obvious reasons. > > There is a bug filed about trying to generate the reference > > documentation from the source code. It might be worth considering if > > that could be done. The current automatic doc generation uses the GTK > > source which is often wrong. > > I don't think it matters any longer. The bug was filed years before you > wrote the reference manual. We should probably just close that one and > live on. John's intent is perhaps similar to mine here -- if we want to make maintenence of the docs easier and more easily integratable to our code contributions, then this could be the ideal solution. As long as someone has time to dissect the docs, add them to the correct spots, and change the generation scripts. It does sound like a lot of work, now that I think about it. :-) Take care, -- Christian Robottom Reis | http://async.com.br/~kiko/ | [+55 16] 261 2331 _______________________________________________ pygtk mailing list [EMAIL PROTECTED] http://www.daa.com.au/mailman/listinfo/pygtk Read the PyGTK FAQ: http://www.async.com.br/faq/pygtk/
