X-Authentication-Warning:	delorie.com: mail set sender to geda-user-bounces using -f
X-Recipient:	geda-user AT delorie DOT com
DKIM-Signature:	v=1; a=rsa-sha256; c=relaxed/relaxed; d=sbcglobal.net; s=s1024; t=1352924461; bh=jNN4/sYmEsVT5vd89rD5I/K8ZRkOUcq3fx8PWuOVtCg=; h=X-Yahoo-Newman-Id:X-Yahoo-Newman-Property:X-YMail-OSG:X-Yahoo-SMTP:Received:Message-ID:Date:From:User-Agent:MIME-Version:To:Subject:References:In-Reply-To:Content-Type:Content-Transfer-Encoding; b=zBEx0jxuJd/uam+x+4q3Lc0mJMUJdvWs+r75axg2drAMvLMlqFkgTMd4k7OC8vUvsBD1wBDHfrj5GSln8mhs/jh0SHeW79lHQGII+/sr9xaeNWBUbHaIvTYmkH92Na0SyuGn/5wxfsyl6CGYepcMfu2nHIvPYoV8UZ/9/nmoRR0=
X-Yahoo-Newman-Id:	726267 DOT 28924 DOT bm AT smtp114 DOT sbc DOT mail DOT ne1 DOT yahoo DOT com
X-Yahoo-Newman-Property:	ymail-3
X-YMail-OSG:	R7_KcIAVM1npwWTZI4u6RVtpvijZyVjw85ZiVvUwUxmYVdQ
	Cve_UYYFe.xrRq48GUlHzOT2KThj70gV3EeXEGx5vQkLO73bsuEX_1GSJNGL
	KvJ7X0wAc3kvD8lHcz8xIKEUVsRHzv7DzmpCWzZUALXKFGFJlgZ6XxEkZRw9
	h77o2BDOvdj3wKkp1MAXjevmxkVvJuPsI1JJDoNSvd2rEha2pQLYIgpjgq4T
	W76KzRTW6r_1pg99_XiW2E5JtCpG4jChCkwmffxmdju6cVVcFUNtLIVKl0G7
	7POcBkoq58lJYg8H9UUFe39h8PUZs.wEtf15WVZN7HNoDPjtFLoxqT6dEmY5
	W3leKpxsDU0s9qpmW_BTmzdP3uGUgPFP6iHGxfkGh_P3dxr9sTB7zZqcyC9S
	jXm_zO7dXyTzsyhNrJnQFBtr8iPyTETGY2SnngVcr5msv2bX7elJy01tO65d
	L96CsczIDeW3VFcq78cBGqrxxl4vM0WG30CnR5Bi0ko1aLnoUJA5nmdxsH6o
	xJsV_4RlF1GEzzzZBdbZ0d8eUjiDM85upavJOcDIMHKJclWsDIXIAvYRLFlI
	mDg1HWmJbfjdcVQ--
X-Yahoo-SMTP:	f_DTt3mswBBgAkQlHvfWr7fedPivEj8lM_i1QPTGLa1z0f7XFiw-
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>
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

- Raw text -