[svnbook commit] r1904 - in trunk/src/en: . book
maxb
svnbook-dev at red-bean.com
Tue Dec 13 12:43:48 CST 2005
Author: maxb
Date: Tue Dec 13 12:43:43 2005
New Revision: 1904
Modified:
trunk/src/en/TODO
trunk/src/en/book/ch08.xml
Log:
* en/book/ch08.xml: Consistently use parentheses after function names and
function-like macros in <function> markup.
Consistently place foo_t structs in <structname> markup.
Eliminate oblique references to the SWIG-Java bindings.
Be slightly more optimistic about the bindings' maturity.
Do not be implausibly optimistic about the ease of adding new SWIG languages
to the Subversion bindings supported set.
* en/TODO: Suggest that the Python bindings examples need work.
Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO (original)
+++ trunk/src/en/TODO Tue Dec 13 12:43:43 2005
@@ -57,6 +57,11 @@
NEEDED SOMETIME (NOT VERSION-SPECIFIC)
============================================================================
+ * Either of the Python bindings examples are easily able to cause an
+ is_canonical assert. To be fair, this is more the fault of the bindings
+ than of the examples, but I'm noting the issue here since it does affect
+ first impressions of the book.
+
* Example 8.5 (pool usage) is very odd. It uses svn_pool_foo() wrappers,
yet uses apr_status_t, not svn_error_t, error handling. This is weird.
Since it is attempting to demonstrate proper Subversion pool coding style,
Modified: trunk/src/en/book/ch08.xml
==============================================================================
--- trunk/src/en/book/ch08.xml (original)
+++ trunk/src/en/book/ch08.xml Tue Dec 13 12:43:43 2005
@@ -352,7 +352,7 @@
use of both the repository and filesystem interfaces to create
a new revision of the filesystem in which a directory is
added. Note that in this example (and all others throughout
- this book), the <function>SVN_ERR</function> macro simply
+ this book), the <function>SVN_ERR()</function> macro simply
checks for a non-successful error return from the function it
wraps, and returns that error if it exists.</para>
@@ -439,7 +439,7 @@
<para>In the previous code segment, calls were made to both the
repository and filesystem interfaces. We could just as easily
have committed the transaction using
- <function>svn_fs_commit_txn</function>. But the filesystem
+ <function>svn_fs_commit_txn()</function>. But the filesystem
API knows nothing about the repository library's hook
mechanism. If you want your Subversion repository to
automatically perform some set of non-Subversion tasks every
@@ -447,7 +447,7 @@
email that describes all the changes made in that transaction
to your developer mailing list), you need to use the
libsvn_repos-wrapped version of that
- function—<function>svn_repos_fs_commit_txn</function>.
+ function—<function>svn_repos_fs_commit_txn()</function>.
This function will actually first run the
<literal>pre-commit</literal> hook script if one exists, then
commit the transaction, and finally will run a
@@ -756,7 +756,7 @@
Repository Access Layer, and then to provide the highest-level
API to any application that wishes to perform general revision
control actions. For example, the function
- <function>svn_client_checkout</function> takes a URL as an
+ <function>svn_client_checkout()</function> takes a URL as an
argument. It passes this URL to the RA layer and opens an
authenticated session with a particular repository. It then
asks the repository for a certain tree, and sends this tree
@@ -869,7 +869,7 @@
uses these types extensively throughout the codebase. But
perhaps the most pervasive APR datatype, found in nearly every
Subversion API prototype, is the
- <literal>apr_pool_t</literal>—the APR memory pool.
+ <structname>apr_pool_t</structname>—the APR memory pool.
Subversion uses pools internally for all its memory allocation
needs (unless an external library requires a different memory
management schema for data passed through its API),
@@ -917,8 +917,8 @@
class="url">file:///home/username/My%20File.txt</systemitem>.
Again, Subversion supplies helper functions that your
application can
- use—<function>svn_path_uri_encode</function> and
- <function>svn_path_uri_decode</function>, for URI encoding and
+ use—<function>svn_path_uri_encode()</function> and
+ <function>svn_path_uri_decode()</function>, for URI encoding and
decoding, respectively.</para>
</sect2>
@@ -928,15 +928,14 @@
<para>If you are interested in using the Subversion libraries in
conjunction with something other than a C program—say a
- Python script or Java application—Subversion has some
- initial support for this via the Simplified Wrapper and
- Interface Generator (SWIG). The SWIG bindings for Subversion
- are located in <filename>subversion/bindings/swig</filename>
- and are slowly maturing into a usable state. These bindings
- allow you to call Subversion API functions indirectly, using
- wrappers that translate the datatypes native to your
- scripting language into the datatypes needed by Subversion's
- C libraries.</para>
+ Python or Perl script—Subversion has some support for this
+ via the Simplified Wrapper and Interface Generator (SWIG). The
+ SWIG bindings for Subversion are located in
+ <filename>subversion/bindings/swig</filename> and whilst still
+ maturing, they are in a usable state. These bindings allow you
+ to call Subversion API functions indirectly, using wrappers that
+ translate the datatypes native to your scripting language into
+ the datatypes needed by Subversion's C libraries.</para>
<para>There is an obvious benefit to accessing the Subversion
APIs via a language binding—simplicity. Generally
@@ -1156,15 +1155,15 @@
<para>Subversion's language bindings unfortunately tend to lack
the level of attention given to the core Subversion modules.
However, there have been significant efforts towards creating
- functional bindings for Python, Perl, and Java. Once you have
- the SWIG interface files properly configured, generation of
- the specific wrappers for all the supported SWIG languages
- (which currently includes versions of C#, Guile, Java,
- MzScheme, OCaml, Perl, PHP, Python, Ruby, and Tcl) should
- theoretically be trivial. Still, some extra programming is
- required to compensate for complex APIs that SWIG needs some
- help generalizing. For more information on SWIG itself, see
- the project's website at <ulink url="http://www.swig.org/"/>.</para>
+ functional bindings for Python, Perl, and Ruby. To some extent,
+ the work done preparing the SWIG interface files for the these
+ languages is reusable in efforts to generate bindings for other
+ languages supported by SWIG (which includes versions of C#,
+ Guile, Java, MzScheme, OCaml, PHP, Tcl, and others).
+ However, some extra programming is required to compensate for
+ complex APIs that SWIG needs some help interfacing with. For
+ more information on SWIG itself, see the project's website at
+ <ulink url="http://www.swig.org/"/>.</para>
</sect2>
</sect1>
More information about the svnbook-dev
mailing list