[svn:parrot-pdd] r14308 - in trunk: . cage docs docs/art docs/dev docs/imcc docs/pdds docs/pdds/clip docs/stm languages languages/tcl/docs lib/Pod/Simple t/distro
am...@cvs.perl.org
Date: Tue Aug 22 10:14:31 2006
New Revision: 14308
Modified:
trunk/docs/pdds/clip/pdd06_pasm.pod
trunk/docs/pdds/clip/pdd09_gc.pod
trunk/docs/pdds/clip/pdd10_embedding.pod
trunk/docs/pdds/clip/pdd11_extending.pod
trunk/docs/pdds/pdd21_namespaces.pod
Changes in other areas also in this revision:
Modified:
trunk/README.win32.pod
trunk/cage/todo.pod
trunk/docs/BROKEN.pod
trunk/docs/art/pp002-pmc.pod
trunk/docs/compiler_faq.pod
trunk/docs/configuration.pod
trunk/docs/debug.pod
trunk/docs/dev/optimizer.pod
trunk/docs/embed.pod
trunk/docs/faq.pod
trunk/docs/imcc/syntax.pod
trunk/docs/intro.pod
trunk/docs/optable.pod
trunk/docs/stm/atomic.pod
trunk/docs/stm/stm_frontend.pod
trunk/docs/stm/thread-issues.pod
trunk/docs/strings.pod
trunk/docs/tests.pod
trunk/docs/vtables.pod
trunk/languages/LANGUAGES.STATUS.pod
trunk/languages/tcl/docs/howto.pod
trunk/lib/Pod/Simple/Subclassing.pod
trunk/t/distro/linelength.t
Log:
While discussion continues on p2, pod files should be at most
80 columns, special on verbatim sections, so we the man formatter
show it properly.
Modified: trunk/docs/pdds/clip/pdd06_pasm.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd06_pasm.pod (original)
+++ trunk/docs/pdds/clip/pdd06_pasm.pod Tue Aug 22 10:14:31 2006
@@ -58,12 +58,14 @@
in a label a dollar sign can appear) are private to the subroutine they appear
in.
-Namespaces are noted with the C<.namespace> directive. It takes a single parameter,
-the name of the namespace, in the form of a multi-dimensional key.
-
-Subroutine names are noted with the C<.sub> directive. It takes a single parameter,
-the name of the subroutine, which is added to the namespace's symbol table. Sub
-names may be any valid Unicode alphanumeric character and the underscore.
+Namespaces are noted with the C<.namespace> directive. It takes a
+single parameter, the name of the namespace, in the form of a
+multi-dimensional key.
+
+Subroutine names are noted with the C<.sub> directive. It takes a
+single parameter, the name of the subroutine, which is added to the
+namespace's symbol table. Sub names may be any valid Unicode
+alphanumeric character and the underscore.
Constants don't need to be named and put in a separate section of the assembly
source. The assembler will take care of putting them in the appropriate part of
@@ -1010,7 +1012,10 @@
So the signature for, for example, this SDL routine:
- int SDL_BlitSurface(SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect);
+ int SDL_BlitSurface(SDL_Surface *src,
+ SDL_Rect *srcrect,
+ SDL_Surface *dst,
+ SDL_Rect *dstrect);
would be C<ipppp>, since it returns an integer and takes four pointers.
Presumably previous calls would have set those pointers up properly.
Modified: trunk/docs/pdds/clip/pdd09_gc.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd09_gc.pod (original)
+++ trunk/docs/pdds/clip/pdd09_gc.pod Tue Aug 22 10:14:31 2006
@@ -227,7 +227,8 @@
This macro is invoked when in aggregate C<agg> the element C<old> is getting
overritten by C<new>. Both C<old> and C<new> may be NULL.
-=item C<DOD_WRITE_BARRIER_KEY(Interp*, PMC *agg, PMC *old, PObj *old_key, PMC *new, PObj *new_key)>
+=item C<DOD_WRITE_BARRIER_KEY(Interp*, PMC *agg, PMC *old, PObj
+*old_key, PMC *new, PObj *new_key)>
Like above. Invoked when a hash key is inserted, possibly replacing an old
key.
Modified: trunk/docs/pdds/clip/pdd10_embedding.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd10_embedding.pod (original)
+++ trunk/docs/pdds/clip/pdd10_embedding.pod Tue Aug 22 10:14:31 2006
@@ -7,7 +7,8 @@
=head1 ABSTRACT
-What we believe people will do when embedding and extending Parrot, why they do it, and how.
+What we believe people will do when embedding and extending Parrot, why they
+do it, and how.
{{ NOTE: some of this will later move into pdds 11 & 12, but for now
just want to get the stub checked in. }}
@@ -19,45 +20,103 @@
=head1 DESCRIPTION
Why embed:
- - access to special features/libraries/languages Parrot provides
- - need an interpreter for a DSL or existing language
- - want to run Parrot on another platform or environment (dedicated
- hardware, in a web server, et cetera)
+
+=over 4
+
+=item - access to special features/libraries/languages Parrot provides
+
+=item - need an interpreter for a DSL or existing language
+
+=item - want to run Parrot on another platform or environment (dedicated
+hardware, in a web server, et cetera)
+
+=back
Why extend:
- - need something NCI doesn't provide
- - writing a custom PMC
+
+=over 4
+
+=item - need something NCI doesn't provide
+
+=item - writing a custom PMC
+
+=back
Philosophical rules:
- - only ever use opaque pointers
- - should be able to communicate through PMCs
- - minimize conversions to and from C data
- - perhaps macros; Ruby does this fairly well and Perl 5 does this
- poorly
- - minimize the number of necessary functions
- - probably can follow core Parrot code to some extent, but beware the
- Perl 5 problem
- - do not expose Parrot internals that may change
- - probably includes vtable methods on PMCs
+
+=over 4
+
+=item - only ever use opaque pointers
+
+=item - should be able to communicate through PMCs
+
+=item - minimize conversions to and from C data
+
+=over 4
+
+=item - perhaps macros; Ruby does this fairly well and Perl 5 does this
+poorly
+
+=item - minimize the number of necessary functions
+
+=item - probably can follow core Parrot code to some extent, but beware the
+Perl 5 problem
+
+=over 4
+
+=item - do not expose Parrot internals that may change
+
+=item - probably includes vtable methods on PMCs
+
+=back
+
+=back
+
+=back
Gotchas:
- - who handles signals?
- - who owns file descriptors and other Unix resources?
- - is there an exception boundary?
- - namespace issues -- especially key related
- - probably a continuation/control flow boundary
- - packfiles and compilation units probably too much information for either
- - do not let MMD and other implementation details escape
- - okay to require some PBC/PIR/PASM for handling round-trip data
- - Parrot should not spew errors to STDERR when embedded
- - const_string() is a real pain, especially with necessary deallocation
- - should be access to Parrot's event loop when embedded
- - passing var args to Parrot subs likely painful
- - perhaps macros/functions to add parameters to call
- - build up a call signature somehow?
- - some abstraction for a call frame?
- - compiling code from a string should return the PMC Sub entry point (:main)
+=over 4
+
+=item - who handles signals?
+
+=item - who owns file descriptors and other Unix resources?
+
+=item - is there an exception boundary?
+
+=item - namespace issues -- especially key related
+
+=item - probably a continuation/control flow boundary
+
+=item - packfiles and compilation units probably too much information for
+either
+
+=item - do not let MMD and other implementation details escape
+
+=item - okay to require some PBC/PIR/PASM for handling round-trip data
+
+=item - Parrot should not spew errors to STDERR when embedded
+
+=item - const_string() is a real pain, especially with necessary deallocation
+
+=item - should be access to Parrot's event loop when embedded
+
+=item - passing var args to Parrot subs likely painful
+
+=over 4
+
+=item - perhaps macros/functions to add parameters to call
+
+=item - build up a call signature somehow?
+
+=item - some abstraction for a call frame?
+
+=back
+
+=item - compiling code from a string should return the PMC Sub entry point
+(:main)
+
+=back
=head1 DEFINITIONS
Modified: trunk/docs/pdds/clip/pdd11_extending.pod
==============================================================================
--- trunk/docs/pdds/clip/pdd11_extending.pod (original)
+++ trunk/docs/pdds/clip/pdd11_extending.pod Tue Aug 22 10:14:31 2006
@@ -144,7 +144,8 @@
Keyed version of C<Parrot_PMC_set_pointer>. Assigns C<value> to the PMC stored
at element <key> of the passed-in PMC.
-=item C<Parrot_PMC_set_pmc_intkey(interp, pmc, Parrot_PMC value, Parrot_Int key)>
+=item C<Parrot_PMC_set_pmc_intkey(interp, pmc, Parrot_PMC value,
+Parrot_Int key)>
Assigns C<value> to the PMC stored at element <key> of the passed-in PMC.
Modified: trunk/docs/pdds/pdd21_namespaces.pod
==============================================================================
--- trunk/docs/pdds/pdd21_namespaces.pod (original)
+++ trunk/docs/pdds/pdd21_namespaces.pod Tue Aug 22 10:14:31 2006
@@ -275,8 +275,8 @@
This method allows other HLLs to know one name (the HLL) and then work with
that HLL's modules without having to know the name it chose for its namespace
-tree. (If you really want to know the name, the get_name() method should work on
-the returned namespace PMC.)
+tree. (If you really want to know the name, the get_name() method should work
+on the returned namespace PMC.)
Note that this method is basically a convenience and/or performance hack, as
it does the equivalent of C<get_root_namespace> followed by
Joshua Hoblitt
specifically for formatting Parrot's Pod.
http://search.cpan.org/~jhoblitt/Pod-Tidy-0.09/
-J
--