Message-ID: <50A3FD26.5000305@sbcglobal.net>
Date: Wed, 14 Nov 2012 12:20:54 -0800
From: "Girvin R. Herr" <girvin DOT herr AT sbcglobal DOT net>
User-Agent: Thunderbird 2.0.0.24 (X11/20100228)
MIME-Version: 1.0
To: geda-user AT delorie DOT com
Subject: Re: [geda-user] libgeda documentation
References: <20121113195022 DOT 2B2CF813A49B AT turkos DOT aspodata DOT se> <50A2E0FC DOT 5050108 AT sbcglobal DOT net> <20121114090659 DOT BF2CF813A49D AT turkos DOT aspodata DOT se>
In-Reply-To: <20121114090659.BF2CF813A49D@turkos.aspodata.se>
Content-Type: text/plain; charset=windows-1252; format=flowed
Content-Transfer-Encoding: 8bit
Reply-To: geda-user AT delorie DOT com


Karl Hammar wrote:
> Girvin Herr:
> ...
>   
>> A while back on this forum, I asked if there was an API document that
>> explains the libgeda functions and their inputs (arguments) and
>> output(s).
>>     
>
> If you downloaded the source and built the suite, you can look into
>
>  <geda-gaf source dir>/libgeda/docs/html/index.html
>
> you'll find what you are asking for. It is incomplete but it is there.
>
> If you click on "File list" in the left frame and then on "a_basic.c",
> and then on "o_save", you'll find:
>
> ====
> int o_save 	( 	TOPLEVEL *  	toplevel,
> 		GList *  	object_list,
> 		char *  	filename	 
> 	) 			
>
> Function Description
>     This function saves the data in a libgeda format to a file 
>
> Parameters:
>     [in] 	toplevel 	The current TOPLEVEL.
>     [in] 	object_list 	The head of a GList of OBJECTs to save.
>     [in] 	filename 	The filename to save the data to.
>
> Returns:
>     1 on success, 0 on failure.
> ====
>
> Yes, it would be nice if one could click on "object_list" to find
> out what that is.
>
> ///
>
> Is it anybody using this?
> Should we try to include documentation for scheme routines also?
> Is this the kind of documentation one wants ?
>
> Comments
>
> Regards,
> /Karl Hammar
>
> -----------------------------------------------------------------------
> Aspö Data
> Lilla Aspö 148
> S-742 94 Östhammar
> Sweden
> +46 173 140 57
>
>
>
>   
Karl,
Yes, that looks like what I need.
I checked my source path as you described and I do not have an html 
subdirectory. I am running geda/gaf 1.6.2. Here is what I have in source 
dir>/libgeda/docs/:
total 108
drwxr-xr-x 3 gherr users 304 2012-11-14 11:56 .
drwxr-x--- 10 gherr users 248 2012-11-01 14:51 ..
-rw-r--r-- 1 gherr users 756 2011-01-13 21:07 Makefile.am
-rw-r--r-- 1 gherr users 22120 2011-01-14 19:41 Makefile.in
drwxr-xr-x 2 gherr users 392 2011-01-14 20:30 images
-rw-r--r-- 1 gherr users 254 2009-10-04 13:38 libgeda-main.txt
-rw-r--r-- 1 gherr users 51199 2009-10-04 13:38 libgeda.dox
-rw-r--r-- 1 gherr users 15870 2009-10-04 13:38 logo.png
-rw-r--r-- 1 gherr users 876 2009-10-04 13:38 what-is-geda.html
-rw-r--r-- 1 gherr users 128 2009-10-04 13:38 what-is-libgeda.html

The two html files listed are no help in my case. Maybe the html files 
you suggested were added in newer releases. I will try downloading the 
latest version and see if the html files are in it.

As for whether this should be available to regular users in the 
documentation, maybe not. I need it to understand the interfaces that 
gsymcheck uses to libgeda, but regular users should not need this level 
of information. However, maybe it should be (continue to be) included 
with the source. If Schema routines are geda-specific and not available 
elsewhere, then they should probably be included also. I don't think it 
is in the scope of geda to teach schema, but that is only my opinion. If 
geda is truly open source, then I think everything unique that is needed 
to understand and work with the code should be included. This is all 
valuable information. There was a thread lately about someone who left 
the project and didn't leave much information for someone else to take 
over. That is not nice. As a retired engineer and C programmer, I 
preferred to include all my notes and documentation with my code. I also 
commented my code profusely, especially when I did something out of the 
ordinary or not intuitive. That not only helped me when I came back to 
the code years later to make a modification or fix a bug, but it helped 
my successor take over, letting me go on to other new challenges.
Thanks for your help. I may need to contact you again, if I can't find 
these html files.
Girvin Herr