Documentation update.

git-svn-id: https://svn.code.sf.net/p/gphoto/code/trunk/libgphoto2@3302 67ed7778-7388-44ab-90cf-0a291f65f57c

4 files changed, 330 insertions, 25 deletions

diff --git a/doc/api/gphoto2-api.sgml b/doc/api/gphoto2-api.sgml
index 80e8b9f60..70ccf34ae 100644
--- a/doc/api/gphoto2-api.sgml
+++ b/doc/api/gphoto2-api.sgml
@@ -13,6 +13,44 @@
 <book id="index">
   <bookinfo>
     <title>GPhoto2 API Reference Manual</title>
+    <authorgroup>
+      <author>
+        <firstname>Lutz</firstname>
+        <surname>Müller</surname>
+        <affiliation>
+          <address>
+	    <email>urc8@rz.uni-karlsruhe.de</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+
+    <copyright>
+      <year>2000</year>
+      <holder>The Free Software Foundation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this
+        document under the terms of the <citetitle>GNU Free
+        Documentation License</citetitle>, Version 1.1 or any later
+        version published by the Free Software Foundation with no
+        Invariant Sections, no Front-Cover Texts, and no Back-Cover
+        Texts. You may obtain a copy of the <citetitle>GNU Free
+        Documentation License</citetitle> from the Free Software
+        Foundation by visiting <ulink type="http"
+        url="http://www.fsf.org">their Web site</ulink> or by writing
+        to:
+
+        <address>
+          The Free Software Foundation, Inc.,
+          <street>59 Temple Place</street> - Suite 330,
+          <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
+          <country>USA</country>
+        </address>
+      </para>
+    </legalnotice>
   </bookinfo>
 
   <chapter id="gphoto2"
@@ -60,11 +98,13 @@ locking of serial ports. GPhoto2 currently supports
   </chapter>
 
   <chapter id="gphoto2base" role="no-toc">
-    <title>GPhoto2 Core Reference</title>
-      <para>
-        GPhoto2's core provides some utility functions and general 
-	datatypes.
-      </para>
+    <title>GPhoto2 Utilities</title>
+    <para>
+      GPhoto2's core provides some utility functions and general 
+      datatypes. In contrast to the
+      objects presented later, they
+      cannot be classified as objects, and are therefore presented upfront.
+    </para>
 
 &gphoto2-result;
 &gphoto2-library;
@@ -73,24 +113,53 @@ locking of serial ports. GPhoto2 currently supports
 
   <chapter id="gphoto2objects" role="no-toc">
     <title>GPhoto2 Objects</title>
+    <para>
+      In order to simplify programming with GPhoto2, an object oriented
+      approach has been used. The different objects are presented in
+      the following sections.
+    </para>
 
-      <sect1 id="FrontendObjects">
-        <title>Objects used by front-ends</title>
-	&gphoto2-camera;
-      </sect1>
+&gphoto2-camera;
+&gphoto2-filesys;
+&gphoto2-widget;
+&gphoto2-list;
+&gphoto2-abilities-list;
+&gphoto2-file;
 
-      <sect1 id="BackendObjects">
-	<title>Objects used by camera drivers</title>
-	&gphoto2-filesys;
-      </sect1>
+  </chapter>
 
-      <sect1 id="GeneralPurposeObjects">
-	<title>Objects used by both frontends and camera drivers</title>
-	&gphoto2-widget;
-	&gphoto2-list;
-	&gphoto2-abilities-list;
-	&gphoto2-file;
-      </sect1>
+  <appendix id="license">
+    <title>License</title>
+        
+    <para>
+      This library is free software; you can redistribute it and/or
+      modify it under the terms of the <citetitle>GNU Library General
+      Public License</citetitle> as published by the Free Software
+      Foundation; either version 2 of the License, or (at your option)
+      any later version.
+    </para>
+
+    <para>
+      This library is distributed in the hope that it will be useful,
+      but WITHOUT ANY WARRANTY; without even the implied warranty of
+      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+      <citetitle>GNU Library General Public License</citetitle> for
+      more details.
+    </para>
+
+    <para>
+      You may obtain a copy of the <citetitle>GNU Library General
+      Public License</citetitle> from the Free Software Foundation by
+      visiting <ulink type="http" url="http://www.fsf.org">their Web
+      site</ulink> or by writing to:
+
+      <address>
+        Free Software Foundation, Inc.
+        <street>59 Temple Place</street> - Suite 330
+        <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
+        <country>USA</country>
+      </address>
+    </para>
+  </appendix>
 
-  </chapter>
 </book>
diff --git a/doc/api/gphoto2-sections.txt b/doc/api/gphoto2-sections.txt
index 1af9b5353..4c806ebc4 100644
--- a/doc/api/gphoto2-sections.txt
+++ b/doc/api/gphoto2-sections.txt
@@ -192,12 +192,40 @@ gp_list_sort
 CameraFile
 
 gp_file_new
+gp_file_ref
+gp_file_unref
+gp_file_free
+
 gp_file_append
+
+gp_file_open
+gp_file_save
+gp_file_clean
+
 gp_file_get_name
 gp_file_set_name
+
+CameraFileType
 gp_file_get_type
+gp_file_set_type
+
+GP_MIME_AVI
+GP_MIME_CRW
+GP_MIME_JPEG
+GP_MIME_UNKNOWN
+GP_MIME_PPM
+GP_MIME_BMP
+GP_MIME_TIFF
+GP_MIME_QUICKTIME
+GP_MIME_WAV
+GP_MIME_PGM
+GP_MIME_RAW
 gp_file_get_mime_type
+gp_file_set_mime_type
+gp_file_detect_mime_type
 gp_file_adjust_name_for_mime_type
+
+gp_file_get_data_and_size
 gp_file_set_data_and_size
 
 </SECTION>
@@ -255,6 +283,7 @@ gp_filesystem_count
 
 gp_filesystem_reset
 gp_filesystem_append
+gp_filesystem_set_file_noop
 
 gp_filesystem_dump
 
diff --git a/doc/api/tmpl/gphoto2-file.sgml b/doc/api/tmpl/gphoto2-file.sgml
index d5fe9491b..a8f59c2da 100644
--- a/doc/api/tmpl/gphoto2-file.sgml
+++ b/doc/api/tmpl/gphoto2-file.sgml
@@ -2,27 +2,54 @@
 CameraFile
 
 <!-- ##### SECTION Short_Description ##### -->
-
+An abstraction of files
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+  Files on cameras are somewhat different from traditional files. For example,
+  cameras can often provide a thumbnail of a file. Some cameras even 
+  provide audio data that is connected to a file.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+  #CameraFileSystem
+</para>
+
+<!-- ##### STRUCT CameraFile ##### -->
+<para>
 
 </para>
 
 
-<!-- ##### SECTION See_Also ##### -->
+<!-- ##### FUNCTION gp_file_new ##### -->
 <para>
 
 </para>
 
+@file: 
+@Returns: 
 
-<!-- ##### STRUCT CameraFile ##### -->
+
+<!-- ##### FUNCTION gp_file_ref ##### -->
 <para>
 
 </para>
 
+@file: 
+@Returns: 
 
-<!-- ##### FUNCTION gp_file_new ##### -->
+
+<!-- ##### FUNCTION gp_file_unref ##### -->
+<para>
+
+</para>
+
+@file: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gp_file_free ##### -->
 <para>
 
 </para>
@@ -42,6 +69,35 @@ CameraFile
 @Returns: 
 
 
+<!-- ##### FUNCTION gp_file_open ##### -->
+<para>
+
+</para>
+
+@file: 
+@filename: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gp_file_save ##### -->
+<para>
+
+</para>
+
+@file: 
+@filename: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gp_file_clean ##### -->
+<para>
+
+</para>
+
+@file: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gp_file_get_name ##### -->
 <para>
 
@@ -62,6 +118,24 @@ CameraFile
 @Returns: 
 
 
+<!-- ##### ENUM CameraFileType ##### -->
+<para>
+  For gphoto2, there are several facets of a file. A file is something that
+  you can create and delete, but not split apart. However, you can look at
+  it from different directions.
+</para>
+
+@GP_FILE_TYPE_PREVIEW: A file of this type is a preview of another file.
+@GP_FILE_TYPE_NORMAL: A file of this type is a normal file, i.e. one that
+		      can be read with standard applications.
+@GP_FILE_TYPE_RAW: A file of this type contains raw data. No processing
+		   has been done. Those files typically cannot be
+		   interpreted by standard applications. You need to have
+		   detailed knowledge about the camera model and its raw
+		   data format in order to be able to process the data.
+@GP_FILE_TYPE_AUDIO: A file of this type contains audio data that is 
+		     connected to another file.
+
 <!-- ##### FUNCTION gp_file_get_type ##### -->
 <para>
 
@@ -72,6 +146,98 @@ CameraFile
 @Returns: 
 
 
+<!-- ##### FUNCTION gp_file_set_type ##### -->
+<para>
+
+</para>
+
+@file: 
+@type: 
+@Returns: 
+
+
+<!-- ##### MACRO GP_MIME_AVI ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_CRW ##### -->
+<para>
+  Canon cameras store files in a special format, the Canon RaW file format.
+  See  http://www.shore.net/~dcoffin/powershot/ or 
+  http://www2.primushost.com/~dcoffin/powershot/ for details on this
+  format.
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_JPEG ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_UNKNOWN ##### -->
+<para>
+  For files that are not recognized by our driver yet.
+  DO NOT use this when you're just too lazy to use the proper MIME
+  type, or we will feed you to Crud Puppy.
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_PPM ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_BMP ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_TIFF ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_QUICKTIME ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_WAV ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_PGM ##### -->
+<para>
+
+</para>
+
+
+
+<!-- ##### MACRO GP_MIME_RAW ##### -->
+<para>
+
+</para>
+
+
+
 <!-- ##### FUNCTION gp_file_get_mime_type ##### -->
 <para>
 
@@ -82,6 +248,25 @@ CameraFile
 @Returns: 
 
 
+<!-- ##### FUNCTION gp_file_set_mime_type ##### -->
+<para>
+
+</para>
+
+@file: 
+@mime_type: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gp_file_detect_mime_type ##### -->
+<para>
+
+</para>
+
+@file: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gp_file_adjust_name_for_mime_type ##### -->
 <para>
 
@@ -91,6 +276,17 @@ CameraFile
 @Returns: 
 
 
+<!-- ##### FUNCTION gp_file_get_data_and_size ##### -->
+<para>
+
+</para>
+
+@Param1: 
+@data: 
+@size: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gp_file_set_data_and_size ##### -->
 <para>
 
diff --git a/doc/api/tmpl/gphoto2-filesys.sgml b/doc/api/tmpl/gphoto2-filesys.sgml
index fdae2fc43..d3ea156ee 100644
--- a/doc/api/tmpl/gphoto2-filesys.sgml
+++ b/doc/api/tmpl/gphoto2-filesys.sgml
@@ -489,6 +489,17 @@ retreiving information about a file, etc.
 @Returns: 
 
 
+<!-- ##### FUNCTION gp_filesystem_set_file_noop ##### -->
+<para>
+
+</para>
+
+@fs: 
+@folder: 
+@file: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gp_filesystem_dump ##### -->
 <para>