On Mon, 2005-02-07 at 16:13, Stefan Kost wrote: > Hi all, > > the original xml docs are written by Chris Lyttle and Dan Mueth. The basically > have streted the docbook help file and written some introductions. > The documents is under GFDL 1.1. > I don't know what others think about this licence. Which licence would be more > appropriate? > Should I mail to the oringinal aithor to ask for permission to change the > licence. If so where do we archive their answers (this list)?
Actually most of the existing text was written by me. I'll attach an email I sent to Dan Mueth years ago. The requirements section came from the README (also by me). The only part I didn't do was the part about the stylesheets, which looks out-of-date anyway. So you could start it again from scratch and we'd be the only 2 authors, which might help if the license needs changing in future. Damon
>From - Tue Nov 7 11:20:07 2000 X-Mozilla-Status: 0001 X-Mozilla-Status2: 00000000 Message-ID: <[EMAIL PROTECTED]> Date: Mon, 06 Nov 2000 17:16:31 +0000 From: Damon Chaplin <[EMAIL PROTECTED]> X-Mailer: Mozilla 4.72 [en] (X11; U; Linux 2.2.14-5.0 i586) X-Accept-Language: en MIME-Version: 1.0 To: Dan Mueth <[EMAIL PROTECTED]> Subject: Re: Gtk-doc doc References: <[EMAIL PROTECTED]> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Dan Mueth wrote: > > Hi Damon, > > I thought I'd send you a gentle reminder about the gtk-doc doc. Have you > had any time to work on it? We have two other people interested in it > now. I'm hoping you can work on the hard part (overall picture of how it > works and the harder parts of setting it up with autoconf) and then they > can work on the other stuff like DocBook, writing the actual comments, > etc. I did a new release of gtk-doc, since I hadn't done a release in ages. I also spent a few hours thinking about how to make the entire process simpler. I have a few ideas but I haven't quite figured it out yet. There is quite a bit of documentation on it already, in the README and in doc/ - setting-up.txt, style-guide.txt, authors.txt, sections.txt. I'll attempt a new overview: gtk-doc is used to document C code. It is typically used to document the public API of libraries, such as the GTK+ and Gnome libraries. But it can also be used to document application code. Documentation on functions can be placed inside the source files in specially-formatted comment blocks, or it can be added to the template files which gtk-doc uses (though note that gtk-doc will only document functions that are declared in header files; it won't produce output for static functions). Currently gtk-doc does not support placing documentation of other types of declarations, such as enums, macros, and structs, inside the source code. gtk-doc consists of a number of perl scripts, each performing a different step in the process. There are 5 main steps in the process: 1) Gathering information about the code. gtkdoc-scan scans the header files of the code looking for declarations of functions, macros, enums, structs, and unions. It creates a list of the declarations, placing them into sections according to which header file they are in. The author can rearrange the sections, and the order of the declarations within them, to produce the final desired order. gtkdoc-scanobj can also be used to dynamically query a library about any GtkObject subclasses it exports. It saves information about each object's position in the class hierarchy and about any GTK Args and Signals it provides. 2) Generating the "template" files. gtkdoc-mktmpl creates a number of files in the tmpl/ subdirectory, using the information gathered in the first step. (Note that this can be run repeatedly. It will try to ensure that no documentation is ever lost.) 3) Writing the documentation. The author fills in the template files with the documentation for each function, macro, union etc. 4) Generating the SGML and HTML. gtkdoc-mkdb turns the template files into SGML files in the sgml/ subdirectory. (If the source code contains documentation on functions, using the special comment blocks, it gets merged in here.) gtkdoc-mkhtml turns the SGML files into HTML files in the html/ subdirectory. 5) Fixing up cross-references between documents. After installing the HTML files, gtkdoc-fixxref can be run to fix up any cross-references between separate documents. For example, the GTK+ documentation contains many cross-references to types documented in the GLib manual. Was that the sort of thing you wanted? Not enough detail/too much? Damon
_______________________________________________ gtk-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gtk-doc-list
