prefer lowe-case name for example sub; some minor formatting tweaks

Author: smls

lib/Language/nativecall.pod

@@ -39,16 +39,16 @@ routine in your library that may be different from your Perl subroutine name.
 
     module Foo;
     use NativeCall;
-    our sub Init() is native('libfoo') is symbol('FOO_INIT') { * }
+    our sub init() is native('libfoo') is symbol('FOO_INIT') { * }
 
 Inside of "libfoo" there is a routine called "FOO_INIT" but, since we're
-creating a module called Foo and we'd rather call the routine as Foo::Init,
+creating a module called Foo and we'd rather call the routine as C<Foo::init>,
 we use the "symbol" trait to specify the name of the symbol in "libfoo"
-and call the subroutine whatever we want ("Init" in this case).
+and call the subroutine whatever we want ("init" in this case).
 
 =head1 Passing and Returning Values
 
-Normal Perl 6 signatures and the "returns" trait are used in order to convey
+Normal Perl 6 signatures and the C<returns> trait are used in order to convey
 the type of arguments a native function expects and what it returns. Here is
 an example.
 
@@ -69,8 +69,8 @@ likely grow with time).
     CArray[int32]  (int* in C, an array of integers)
     Pointer[void]  (void* in C, can point to all other types)
 
-Note that the lack of a "returns" trait is used to indicate void return type.
-Do *not* use the 'void' type anywhere except in the Pointer parametrization.
+Note that the lack of a C<returns> trait is used to indicate void return type.
+Do I<not> use the 'void' type anywhere except in the Pointer parametrization.
 
 For strings, there is an additional "encoded" trait to give some extra hints on
 how to do the marshalling.
@@ -145,10 +145,10 @@ Here is an example of passing a C array.
     @values[2]  = 180.7e0;
     RenderBarChart('Weights (kg)', 3, @titles, @values);
 
-Note that binding was used to @titles, *NOT* assignment! If you assign, you
+Note that binding was used to C<@titles>, I<not> assignment! If you assign, you
 are putting the values into a Perl 6 array, and it will not work out. If this
-all freaks you out, forget you ever knew anything about the "@" sigil and just
-use "$" all the way when using NativeCall. :-)
+all freaks you out, forget you ever knew anything about the C<@> sigil and just
+use C<$> all the way when using NativeCall. :-)
 
     my $titles = CArray[Str].new;
     $titles[0] = 'Me';
@@ -199,7 +199,7 @@ the memory is not managed for you.
 
 NativeCall currently doesn't put object members in containers, so assigning new values
 to them (with =) doesn't work. Instead, you have to bind new values to the private
-members: $!struct-member := StructObj.new;
+members: C<$!struct-member := StructObj.new;>
 
 As you may have predicted by now, a null is represented by the type object of the
 struct type.
@@ -230,16 +230,21 @@ to callbacks.
 
 TBD
 
-=head1 Running the Examples
+=head1 Examples
 
-The examples directory contains various examples of how to use NativeCall:
-L<http://github.com/jnthn/zavolaj/tree/master/examples>
+The L<zavolaj|https://github.com/jnthn/zavolaj> git repository (where NativeCall is
+developed) hosts L<various examples|https://github.com/jnthn/zavolaj/tree/master/examples>
+of how to use NativeCall.
 
-More examples can be found in the lib/DBDish/ directory of the DBIsh repository
-at L<http://github.com/perl6/DBIish>.
+More examples can be found L<in the DBIsh repository
+|https://github.com/perl6/DBIish/tree/master/lib/DBDish>.
 
 =head2 MySQL
 
+=comment TODO Do we really need this here? Seems like this info should just go
+              along-side that example in the git repo, rathern than replicated
+              on p6doc.
+
 There is an example of using the MySQL client library. There is a project
 L<http://github.com/mberends/minidbi> that wraps these functions with a DBI
 compatible interface. You'll need that library to hand; on Debian-esque systems