Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge branch 'ayardley/pod_DESCRIPTIONS'

  • Loading branch information...
commit f852446839f3cb03c4c81d91d59ffe55cce84061 2 parents bb128c7 + 0e451e6
@ayardley ayardley authored
Showing with 1,361 additions and 626 deletions.
  1. +0 −5 CREDITS
  2. +3 −3 DONORS.pod
  3. +24 −3 README_cygwin.pod
  4. +3 −5 compilers/data_json/JSON_README.pod
  5. +1 −1  compilers/data_json/data_json.pir
  6. +16 −0 compilers/imcc/imcc.y
  7. +16 −1 compilers/imcc/imcparser.c
  8. +10 −3 compilers/pct/README.pod
  9. +1 −1  compilers/pge/PGE.pir
  10. +1 −1  compilers/pge/PGE/Exp.pir
  11. +1 −1  compilers/pge/PGE/OPTable.pir
  12. +1 −1  compilers/pge/PGE/Perl6Regex.pir
  13. +8 −2 compilers/pge/README.pod
  14. +2 −0  compilers/tge/TGE/Compiler.pir
  15. +3 −4 compilers/tge/TGE/Grammar.pir
  16. +2 −2 compilers/tge/tgc.pir
  17. +3 −3 config/auto/llvm/hello.c
  18. +6 −6 docs/binaries/ops2c.pod
  19. +7 −7 docs/binaries/parrot-nqp.pod
  20. +7 −7 docs/binaries/parrot-prove.pod
  21. +6 −6 docs/binaries/parrot_nci_thunk_gen.pod
  22. +8 −8 docs/binaries/parrotbug.pod
  23. +20 −20 docs/binaries/pbc_to_exe.pod
  24. +9 −9 docs/binaries/plumage.pod
  25. +7 −7 docs/binaries/winxed.pod
  26. +13 −8 docs/compiler_faq.pod
  27. +4 −2 docs/debug.pod
  28. +2 −2 docs/deprecations/deprecations.pod
  29. +4 −2 docs/deprecations/deprecations_2_6.pod
  30. +5 −3 docs/deprecations/deprecations_2_9.pod
  31. +4 −2 docs/deprecations/deprecations_3_0.pod
  32. +4 −2 docs/deprecations/deprecations_3_3.pod
  33. +4 −2 docs/deprecations/deprecations_3_6.pod
  34. +6 −4 docs/deprecations/how_to_deprecate.pod
  35. +14 −9 docs/dev/byteorder.pod
  36. +11 −5 docs/dev/c_functions.pod
  37. +5 −5 docs/dev/coverage.pod
  38. +2 −4 docs/dev/debugging_with_msvc.pod
  39. +8 −6 docs/dev/headerizer.pod
  40. +12 −7 docs/dev/infant.pod
  41. +2 −2 docs/dev/longopt.pod
  42. +9 −1 docs/dev/parrot_api.pod
  43. +6 −1 docs/dev/pcc_methods.pod
  44. +14 −3 docs/dev/pcc_state.pod
  45. +7 −7 docs/dev/pmc_freeze.pod
  46. +16 −4 docs/dev/pmc_obj_design_meeting_notes.pod
  47. +5 −1 docs/extend.pod
  48. +5 −1 docs/faq.pod
  49. +7 −1 docs/gettingstarted.pod
  50. +3 −3 docs/glossary.pod
  51. +12 −4 docs/imcc/imcfaq.pod
  52. +5 −5 docs/intro.pod
  53. +9 −7 docs/memory_internals.pod
  54. +8 −7 docs/overview.pod
  55. +5 −4 docs/parrot.pod
  56. +8 −3 docs/parrotbyte.pod
  57. +24 −15 docs/pmc.pod
  58. +9 −10 docs/pmc/array.pod
  59. +7 −3 docs/pmc/documentation.pod
  60. +11 −2 docs/pmc2c.pod
  61. +7 −5 docs/porting_intro.pod
  62. +16 −10 docs/project/cage_cleaners_guide.pod
  63. +14 −8 docs/project/committer_guide.pod
  64. +7 −5 docs/project/core_inclusion.pod
  65. +16 −7 docs/project/debian_packaging_guide.pod
  66. +13 −4 docs/project/metacommitter_guide.pod
  67. +14 −4 docs/project/release_manager_guide.pod
  68. +16 −6 docs/project/roles_responsibilities.pod
  69. +3 −3 docs/project/support_policy.pod
  70. +14 −5 docs/project/ubuntu_packaging_guide.pod
  71. +12 −5 docs/req/model_users.pod
  72. +11 −9 docs/running.pod
  73. +12 −11 docs/submissions.pod
  74. +9 −7 docs/tests.pod
  75. +14 −3 docs/user/pir/exceptions.pod
  76. +21 −8 docs/user/pir/intro.pod
  77. +12 −1 docs/user/pir/objects.pod
  78. +13 −1 docs/user/pir/pmcs.pod
  79. +4 −2 docs/vtables.pod
  80. +4 −1 editor/README.pod
  81. +2 −2 examples/languages/abc/abc.pir
  82. +1 −1  examples/languages/abc/src/builtins/all.pir
  83. +15 −9 examples/languages/squaak/doc/tutorial_episode_1.pod
  84. +8 −1 examples/languages/squaak/doc/tutorial_episode_2.pod
  85. +8 −2 examples/languages/squaak/doc/tutorial_episode_3.pod
  86. +7 −0 examples/languages/squaak/doc/tutorial_episode_4.pod
  87. +8 −1 examples/languages/squaak/doc/tutorial_episode_5.pod
  88. +8 −1 examples/languages/squaak/doc/tutorial_episode_6.pod
  89. +8 −1 examples/languages/squaak/doc/tutorial_episode_7.pod
  90. +8 −1 examples/languages/squaak/doc/tutorial_episode_8.pod
  91. +8 −1 examples/languages/squaak/doc/tutorial_episode_9.pod
  92. +1 −1  examples/languages/squaak/squaak.pir
  93. +1 −1  examples/languages/squaak/src/squaak.pir
  94. +3 −4 examples/mops/mops.p6
  95. +2 −6 examples/mops/mops.rb
  96. +3 −1 examples/nci/Xlib.pir
  97. +2 −2 examples/nci/Xlibconstants.pir
  98. +6 −4 examples/nci/xlibtest.nqp
  99. +7 −3 examples/nci/xlibtest.p6
  100. +5 −3 examples/nci/xlibtest.pir
  101. +17 −1 examples/past/01-sub.pir
  102. +10 −1 examples/past/four_plus_one.pir
  103. +5 −7 examples/pir/coop_threads.pir
  104. +6 −1 examples/sdl/anim_image.pir
  105. +7 −1 examples/sdl/anim_image_dblbuf.pir
  106. +6 −1 examples/sdl/blue_font.pir
  107. +7 −3 examples/sdl/blue_rect.pir
  108. +7 −1 examples/sdl/blue_rect.pl
  109. +7 −1 examples/sdl/bounce_parrot_logo.pir
  110. +6 −2 examples/sdl/mandel.pir
  111. +3 −2 examples/sdl/minesweeper/eventhandler.pir
  112. +6 −1 examples/sdl/minesweeper/mines.pir
  113. +1 −1  examples/sdl/move_parrot_logo.pir
  114. +1 −1  examples/sdl/raw_pixels.pir
  115. +1 −1  examples/sdl/tetris/app.pir
  116. +1 −1  examples/sdl/tetris/block.pir
  117. +1 −1  examples/sdl/tetris/blockdata.pir
  118. +1 −1  examples/sdl/tetris/blocks.pir
  119. +1 −1  examples/sdl/tetris/board.pir
  120. +1 −1  examples/sdl/tetris/boarddata.pir
  121. +1 −1  examples/sdl/tetris/eventhandler.pir
  122. +1 −1  examples/sdl/tetris/tetris.pir
  123. +1 −1  examples/streams/Bytes.pir
  124. +1 −1  examples/streams/Combiner.pir
  125. +1 −1  examples/streams/Coroutine.pir
  126. +1 −1  examples/streams/FileLines.pir
  127. +1 −1  examples/streams/Filter.pir
  128. +1 −1  examples/streams/Include.pir
  129. +1 −1  examples/streams/Lines.pir
  130. +1 −1  examples/streams/ParrotIO.pir
  131. +1 −1  examples/streams/SubCounter.pir
  132. +1 −1  examples/streams/SubHello.pir
  133. +1 −1  examples/streams/Writer.pir
  134. +3 −1 examples/tge/branch/lib/Branch.pir
  135. +3 −1 examples/tge/branch/lib/Leaf.pir
  136. +9 −1 examples/tutorial/00_README.pod
  137. +8 −2 examples/tutorial/01_temp_var.pir
  138. +8 −2 examples/tutorial/02_local_var.pir
  139. +8 −2 examples/tutorial/03_temp_var_basic_pmcs.pir
  140. +8 −2 examples/tutorial/04_pod_comments.pir
  141. +8 −2 examples/tutorial/10_math_ops.pir
  142. +8 −2 examples/tutorial/11_math_ops_self_mod.pir
  143. +8 −2 examples/tutorial/12_math_ops_pasm.pir
  144. +8 −2 examples/tutorial/13_logical_ops.pir
  145. +8 −2 examples/tutorial/20_string_ops.pir
  146. +8 −2 examples/tutorial/21_string_ops_repeat.pir
  147. +8 −2 examples/tutorial/22_string_ops_length.pir
  148. +8 −2 examples/tutorial/23_string_ops_substr.pir
  149. +8 −2 examples/tutorial/24_string_ops_clone.pir
  150. +8 −2 examples/tutorial/30_arrays_basic.pir
  151. +8 −2 examples/tutorial/31_array_ops_split.pir
  152. +9 −3 examples/tutorial/32_array_ops_sprintf.pir
  153. +8 −2 examples/tutorial/33_hashes.pir
  154. +8 −2 examples/tutorial/34_multikey.pir
  155. +8 −2 examples/tutorial/40_file_ops.pir
  156. +8 −2 examples/tutorial/50_goto.pir
  157. +8 −2 examples/tutorial/51_if_unless.pir
  158. +8 −2 examples/tutorial/52_if_compare.pir
  159. +8 −2 examples/tutorial/53_loop.pir
  160. +8 −2 examples/tutorial/55_iterator.pir
  161. +8 −2 examples/tutorial/56_defined.pir
  162. +8 −2 examples/tutorial/57_exists.pir
  163. +8 −2 examples/tutorial/60_subroutines.pir
  164. +8 −2 examples/tutorial/61_namespaces.pir
  165. +8 −2 examples/tutorial/62_namespaces.pir
  166. +8 −2 examples/tutorial/70_class_object.pir
  167. +8 −2 examples/tutorial/81_continuation.pir
  168. +8 −2 examples/tutorial/82_coroutine.pir
  169. +8 −2 examples/tutorial/83_external_libraries.pir
  170. +8 −2 examples/tutorial/90_writing_tests.pir
  171. +19 −4 lib/Parrot/Test/Pod.pm
  172. +2 −2 runtime/parrot/include/green_threads.pir
  173. +7 −7 runtime/parrot/include/hllmacros.pir
  174. +10 −6 runtime/parrot/include/test_more.pir
  175. +5 −0 runtime/parrot/languages/parrot/parrot.pir
  176. +6 −3 runtime/parrot/library/CGI/QueryHash.pir
  177. +2 −2 runtime/parrot/library/Config/JSON.pir
  178. +3 −3 runtime/parrot/library/HTTP/Daemon.pir
  179. +2 −2 runtime/parrot/library/HTTP/Message.pir
  180. +2 −2 runtime/parrot/library/JSON.pir
  181. +2 −2 runtime/parrot/library/LWP/Protocol.pir
  182. +2 −2 runtime/parrot/library/LWP/UserAgent.pir
  183. +2 −2 runtime/parrot/library/PGE/Dumper.pir
  184. +2 −2 runtime/parrot/library/Range.pir
  185. +1 −3 runtime/parrot/library/Stream/Writer.pir
  186. +6 −2 runtime/parrot/library/String/Utils.pir
  187. +2 −2 runtime/parrot/library/TAP/Formatter.pir
  188. +2 −2 runtime/parrot/library/TAP/Harness.pir
  189. +2 −2 runtime/parrot/library/TAP/Parser.pir
  190. +4 −0 runtime/parrot/library/Test/Builder/Test.pir
  191. +2 −2 runtime/parrot/library/URI.pir
  192. +2 −2 runtime/parrot/library/distutils.pir
  193. +3 −3 runtime/parrot/library/dumper.pir
  194. +1 −1  runtime/parrot/library/parrotlib.pir
  195. +4 −0 src/alarm.c
  196. +1 −1  src/dynpmc/README.pod
  197. +2 −0  src/gc/gc_ms2.c
  198. +2 −0  src/platform/generic/socket.c
  199. +2 −2 src/pmc/callback.pmc
  200. +2 −0  src/pointer_array.c
  201. +5 −1 src/runcore/subprof.c
  202. +8 −5 t/TESTS_STATUS.pod
  203. +5 −1 t/codingstd/pccmethod_deps.t
  204. +4 −1 t/codingstd/pod_description.t
  205. +4 −0 t/dynoplibs/time.t
  206. +27 −27 t/examples/streams.t
  207. +2 −0  t/harness
  208. +4 −0 t/op/time.t
  209. +4 −0 t/pmc/opcode.t
  210. +5 −1 t/pmc/oplib.t
  211. +3 −4 t/pmc/task_primes.t
  212. +1 −1  t/tools/dump_pbc.t
  213. +8 −3 tools/dev/merge_pull_request.pl
  214. +3 −3 tools/release/cut.pl
View
5 CREDITS
@@ -1,5 +1,3 @@
-=pod
-
Following in the steps of other open source projects that
eventually take over the world, here is the partial list
@@ -1218,6 +1216,3 @@ E: svn@perl.org
N: Bart Wiegmans
E: bartwiegmans@gmail.com
D: mod_parrot
-
-
-=cut
View
6 DONORS.pod
@@ -4,10 +4,10 @@
DONORS
-=head1 DONORS
+=head1 DESCRIPTION
-We would like to thank the following people and institutions,
-whose financial contributions help support the development of Parrot.
+We want to thank the following people and institutions, whose financial
+contributions help to support the development of Parrot.
=over 4
View
27 README_cygwin.pod
@@ -4,10 +4,10 @@ This file is best viewed with "perldoc README.cygwin".
README.cygwin - Parrot under Cygwin
-=head1 SYNOPSIS
+=head1 DESCRIPTION
-Parrot builds out of the box under Cygwin,
-when no other parrot is installed. See below at PROBLEMS.
+Parrot builds out of the box under Cygwin, when no other parrot is installed.
+I<See> PROBLEMS below.
There are official cygwin parrot packages available via
L<http://cygwin.com/setup.exe>.
@@ -127,6 +127,11 @@ This is a known cygwin problem with dll's, esp. perl on non-XP 32bit platforms.
You need to install the C<rebase> package and run C<rebaseall> from an C<ash>
shell.
+For more information regarding this problem, I<see>
+http://www.cygwin.com/ml/cygwin/2009-05/msg00413.html;
+http://www.heikkitoivonen.net/blog/2008/11/26/cygwin-upgrades-and-rebaseall/;
+I<and see> http://code.google.com/p/chromium/wiki/CygwinDllRemappingFailure.
+
=item Crash at miniparrot.exe config_lib.pasm
Invoking Parrot to generate runtime/parrot/include/config.fpmc --cross your
@@ -152,6 +157,22 @@ F</usr/lib/libparrot.dll.a>, F</usr/local/lib/libparrot.dll.a>
This is a known Windows limitation with NTFS junctions on files.
+=item Exception: STATUS_ACCESS_VIOLATION ....
+
+If this exception results, ensure there is only one version of the
+C<cygwin1.dll> present on your system or, alternatively, ensure no other
+application interferes with Cygwin. For more information on this problem,
+I<see> the Cygwin/X FAQ at
+http://x.cygwin.com/docs/faq/cygwin-x-faq.html#q-status-access-violation
+I<and see> the main Cygwin FAQ at
+http://cygwin.com/faq-nochunks.html#faq.using.bloda
+
+=item build aborts
+
+If the build aborts, it may be necessary to include already built DLLs in the
+rebase. For instructions on how to accomplish this, I<see> the "PROBLEMS"
+section at http://cpansearch.perl.org/src/BFREE/OpenGL-0.57/README.cygwin
+
=back
=head1 TODO
View
8 compilers/data_json/JSON_README.pod
@@ -3,16 +3,14 @@
# This is the start to rewrite JSON. It starts with rewriting data_json only.
# data_json depends on the PGE. The rewrite use parrot-nqp.
-
=head1 NAME
JSON, a lightweight data-interchange format.
-=head1 SYNOPSIS
+=head1 DESCRIPTION
-The C<from_json> method return a PMC that containing the data structure
-for a given valid JSON (JavaScript Object Notation) string.
-For example:
+The C<from_json> method return a PMC that contains the data structure for
+a given valid JSON (JavaScript Object Notation) string. For example:
.sub 'main' :main
.local pmc result
View
2  compilers/data_json/data_json.pir
@@ -4,7 +4,7 @@
data_json - parse JSON, a lightweight data-interchange format.
-=head1 SYNOPSIS
+=head1 DESCRIPTION
Given a valid JSON (JavaScript Object Notation) string, the compiler will
return a sub that when called will produce the appropriate values. For
View
16 compilers/imcc/imcc.y
@@ -12,6 +12,22 @@
*
*/
+/*
+
+=pod
+
+=head1 NAME
+
+compilers/imcc/imcc.y - Intermediate Code Compiler for Parrot.
+
+=head1 DESCRIPTION
+
+This file contains the grammar of the PIR language parser.
+
+=cut
+
+*/
+
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
View
17 compilers/imcc/imcparser.c
@@ -92,6 +92,22 @@
*
*/
+/*
+
+=pod
+
+=head1 NAME
+
+compilers/imcc/imcc.y - Intermediate Code Compiler for Parrot.
+
+=head1 DESCRIPTION
+
+This file contains the grammar of the PIR language parser.
+
+=cut
+
+*/
+
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
@@ -6031,4 +6047,3 @@ int yyerror(void *yyscanner, ARGMOD(imc_info_t *imcc), const char *s)
* End:
* vim: expandtab shiftwidth=4 cinoptions='\:2=2' :
*/
-
View
13 compilers/pct/README.pod
@@ -1,7 +1,14 @@
+# Copyright (C) 2001-2012, Parrot Foundation.
-=head1 Parrot Compiler Toolkit (PCT)
+=pod
-This is an implementation of an abstract tree representation
-and compiler for Parrot.
+=head1 NAME
+
+compiler/pct/README.pod - Readme file for the 'compiler/pct/' directory.
+
+=head1 DESCRIPTION
+
+This is an implementation of an abstract tree representation and compiler for
+Parrot.
=cut
View
2  compilers/pge/PGE.pir
@@ -4,7 +4,7 @@
PGE - the Parrot/Perl Grammar Engine
-=head2 Description
+=head1 DESCRIPTION
This is the base file for the grammar engine. It basically combines
(via .include) each of the separate PGE modules into a single compilation
View
2  compilers/pge/PGE/Exp.pir
@@ -1,6 +1,6 @@
# Copyright (C) 2005-2009, Parrot Foundation.
-=head1 TITLE
+=head1 DESCRIPTION
PGE::Exp - base class for expressions
View
2  compilers/pge/PGE/OPTable.pir
@@ -1,6 +1,6 @@
# Copyright (C) 2005-2009, Parrot Foundation.
-=head1 Title
+=head1 DESCRIPTION
PGE::OPTable - PGE operator precedence table and parser
View
2  compilers/pge/PGE/Perl6Regex.pir
@@ -1,6 +1,6 @@
# Copyright (C) 2006-2009, Parrot Foundation.
-=head1 TITLE
+=head1 DESCRIPTION
Perl6Regex - compiler and parser for Perl 6 regex
View
10 compilers/pge/README.pod
@@ -1,5 +1,12 @@
+# Copyright (C) 2001-2012, Parrot Foundation.
-=head1 Parrot Grammar Engine (PGE)
+=pod
+
+=head1 NAME
+
+compiler/pge/README.pod - Readme to the 'compilers/pge' directory.
+
+=head1 DESCRIPTION
This is a regular expression/rules/grammar engine/parser designed to
run in Parrot. It's still a work in progress, but has a lot of
@@ -141,4 +148,3 @@ Patches and suggestions should be sent to the Perl 6 compiler list
(perl6-compiler@perl.org).
=cut
-
View
2  compilers/tge/TGE/Compiler.pir
@@ -6,6 +6,8 @@ TGE::Compiler - A compiler for the grammar syntax of TGE.
=head1 DESCRIPTION
+TGE::Compiler is a compiler for the grammar syntax of Tree Grammar Engine.
+
=cut
.namespace [ 'TGE'; 'Compiler' ]
View
7 compilers/tge/TGE/Grammar.pir
@@ -4,12 +4,11 @@
TGE::Grammar - The base class for all tree grammars.
-=head1 SYNOPSIS
-
-(To come.)
-
=head1 DESCRIPTION
+TGE::Grammar is the base class for all of the tree grammars for the Tree
+Grammar Engine
+
=cut
.namespace [ 'TGE'; 'Grammar' ]
View
4 compilers/tge/tgc.pir
@@ -8,13 +8,13 @@ tgc.pir - The TGE rules compiler
> ./parrot compilers/tge/tgc.pir [OPTIONS] FILE
-=head2 DESCRIPTION
+=head1 DESCRIPTION
This program takes a tree grammar, specified in B<FILE>, and compiles it
into the PIR code needed to execute that grammar. This PIR code is then
suitable for inclusion or compilation into other larger programs.
-=head2 OPTIONS
+=head1 OPTIONS
=over 4
View
6 config/auto/llvm/hello.c
@@ -2,15 +2,15 @@
*
Copyright (C) 2009, Parrot Foundation.
-=head1
+=head1 DESCRIPTION
-Test file only.
+A test file only.
=over 4
=item C<int main()>
-Test file only.
+A test file only.
=cut
View
12 docs/binaries/ops2c.pod
@@ -1,16 +1,16 @@
# Copyright (C) 2011, Parrot Foundation.
-=head1 Name
+=head1 NAME
ops2c - Convert Parrot opcodes to C
-=head1 Description
+=head1 SYNOPSIS
-Translate Parrot opcode files (.ops) to C files.
+ops2c [option]
-=head1 Usage
+=head1 DESCRIPTION
-ops2c [option]
+Translate Parrot opcode files (.ops) to C files.
=head2 Command line Options
@@ -45,7 +45,7 @@ To perform all processing without writing to any files, use :
-g
--debug
-=head1 Help
+=head1 HELP
For more help or any other question you go to L<http://parrot.org> or
L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
View
14 docs/binaries/parrot-nqp.pod
@@ -1,10 +1,14 @@
# Copyright (C) 2001-2011, Parrot Foundation.
-=head1 Name
+=head1 NAME
parrot-nqp - Not Quite Perl (6)
-=head1 Description
+=head1 SYNOPSIS
+
+parrot-nqp <file>
+
+=head1 DESCRIPTION
This is "Not Quite Perl (6)" -- a High Level Language (HLL) which allows one to
write Perl6-like code. The key feature of NQP is that it's designed to be an
@@ -17,10 +21,6 @@ outside of the main Parrot git repository. It is occasionally snapshotted into
the main Parrot codebase so it can be bundled with Parrot releases and be used
by core Parrot developers as well as HLL developers.
-=head1 Usage
-
-parrot-nqp <file>
-
=head2 Command Line Usage
For help use :
@@ -71,7 +71,7 @@ For output use :
-o=s
--output=s
-=head1 Help
+=head1 HELP
For more help or any other question you go to L<http://parrot.org> or
L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
View
14 docs/binaries/parrot-prove.pod
@@ -1,19 +1,19 @@
# Copyright (C) 2001-2011, Parrot Foundation.
-=head1 Name
+=head1 NAME
parrot-prove - Prove is a PIR-based TAP (Test Anything Protocol) Harness
-=head1 Description
+=head1 SYNOPSIS
+
+parrot-prove [option] [files]
+
+=head1 DESCRIPTION
It eats test output (i.e. is a TAP consumer) and tells humans if the
test suite passed, and if not, which kind of pretty colors of smoke
came out. It is mostly equivalent to 'prove' from Perl 5.
-=head1 Usage
-
-parrot-prove [option] [files]
-
=head2 Command line boolean options
To print all test lines use :
@@ -89,7 +89,7 @@ To store the resulting TAP in an archive file use :
-a
--archive
-=head1 Help
+=head1 HELP
For more help or any other question you go to L<http://parrot.org> or
L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
View
12 docs/binaries/parrot_nci_thunk_gen.pod
@@ -1,16 +1,16 @@
# Copyright (C) 2001-2011, Parrot Foundation.
-=head1 Name
+=head1 NAME
parrot_nci_thunk_gen - Create Parrot NCI thunks
-=head1 Description
+=head1 SYNOPSIS
-This utility creates C file of routines suitable for use as Parrot Native Call Interface thunks.
+ parrot_nci_thunk_gen [option] -o output_c_file.c < input_signature_list.nci
-=head1 Usage
+=head1 DESCRIPTION
- parrot_nci_thunk_gen [option] -o output_c_file.c < input_signature_list.nci
+This utility creates C file of routines suitable for use as Parrot Native Call Interface thunks.
=head2 Command line Options
@@ -64,7 +64,7 @@ To set the name used for the leader function (default value is 'Parrot_load_nci_
--loader-name
-=head1 Help
+=head1 HELP
For more help or any other question you go to L<http://parrot.org> or
L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
View
16 docs/binaries/parrotbug.pod
@@ -1,20 +1,20 @@
# Copyright (C) 2001-2011, Parrot Foundation.
-=head1 Name
+=head1 NAME
parrotbug.pod - Parrot bug report
-=head1 Description
+=head1 SYNOPSIS
+
+parrotbug [option] [action]
+
+=head1 DESCRIPTION
A program to help generate bug reports about parrot, and mail them.
It is designed to be used interactively. Normally no arguments will
be needed.
-=head1 Usage
-
-parrotbug [option] [action]
-
-=head2 Comman line Options
+=head2 Command line Options
To report successful build on this system to parrot developers use :
@@ -81,7 +81,7 @@ To print version information and exit after that use :
--version
-=head1 Help
+=head1 HELP
For more help or any other question you go to L<http://parrot.org> or
L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
View
40 docs/binaries/pbc_to_exe.pod
@@ -1,16 +1,32 @@
# Copyright (C) 2011, Parrot Foundation.
-=head1 Name
+=head1 NAME
pbc_to_exe - Generate executables from Parrot bytecode
-=head1 Description
+=head1 SYNOPSIS
+
+ pbc_to_exe my.pbc
+
+Will generate:
+
+ my.exe
+
+And
+
+ pbc_to_exe my.pbc --install
+
+Will generate:
+
+ installable_my.exe
+
+=head1 DESCRIPTION
This utility compiles bytecode to native executables. These are called
"fakecutables", because they are actually just the bytecode packaged up as raw
data inside a C skeleton.
-=head1 Usage
+=head1 USAGE
pbc_to_exe [option] <file>
@@ -42,23 +58,7 @@ To change garbage collector algorithm use :
C<gms> is default. C<ms2> is older and slower
-=head2 Synopsis
-
- pbc_to_exe my.pbc
-
-Will generate :
-
- my.exe
-
-And
-
- pbc_to_exe my.pbc --install
-
-Will generate :
-
- installable_my.exe
-
-=head1 Help
+=head1 HELP
For more help or any other question you go to L<http://parrot.org> or
L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
View
18 docs/binaries/plumage.pod
@@ -1,19 +1,19 @@
# Copyright (C) 2001-2011, Parrot Foundation.
-=head1 Name
+=head1 NAME
plumage.pod - Parrot Plumage
-=head1 Description
+=head1 SYNOPSIS
-Parrot Plumage is the Parrot Virtual Machine module ecosystem. It includes
-tools to search metadata, handle dependencies, install modules, and so forth.
+plumage [<options>] <command> [<arguments>]
-=head1 Usage
+=head1 DESCRIPTION
-plumage [<options>] <command> [<arguments>]
+Parrot Plumage is the Parrot Virtual Machine module ecosystem. It includes
+tools to search metadata, handle dependencies, install modules, and so forth.
-=head1 Command line options
+=head2 Command line options
For help about options and commands you can type:
@@ -46,7 +46,7 @@ Not to ignore fail in specific stage use :
--ignore-fail=<stage>=0
-=head1 Command line commands
+=head2 Command line commands
=head2 General commands
@@ -130,7 +130,7 @@ To remove all generated files during the build process for specific project use
reaclean <project>
-=head1 Help
+=head1 HELP
For more help or any other question you go to L<http://parrot.org> or
L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
View
14 docs/binaries/winxed.pod
@@ -1,10 +1,14 @@
# Copyright (C) 2001-2011, Parrot Foundation.
-=head1 Name
+=head1 NAME
winxed.pod - The Winxed Language
-=head1 Description
+=head1 SYNOPSIS
+
+winxed [option] [program] [args]
+
+=head1 DESCRIPTION
This is Winxed, a High Level Language (HLL) that is packaged with Parrot
for tool, library and language development.
@@ -12,10 +16,6 @@ for tool, library and language development.
Winxed is Javascript-ish. If you are looking for something more Perl-ish,
you want NQP.
-=head1 Usage
-
-winxed [option] [program] [args]
-
=head2 Command line otions
'-c' : is used to compile to pir.
@@ -31,7 +31,7 @@ winxed [option] [program] [args]
'--help' : is used to show help for options.
'--version' : is used to show the version of winxed and exit.
-=head1 Help
+=head1 HELP
For more help or any other question you go to L<http://parrot.org> or
L<http://github.com/parrot/parrot>.Or you can send email to 'parrot-dev@parrot.org'.
View
21 docs/compiler_faq.pod
@@ -1,10 +1,15 @@
-# Copyright (C) 2001-2007, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/compiler_faq.pod - Parrot FAQ for compiler writers in PIR
-=head1 General Questions
+=head1 DESCRIPTION
+
+This is the FAQ for anyone interested in writing compilers in PIR, targeting
+the Parrot Virtual Machine.
+
+=head1 GENERAL QUESTIONS
=head2 Which C compilers can I use with Parrot?
@@ -24,7 +29,7 @@ See L<http://parrot.github.com/html/examples/languages/squaak/doc/tutorial_episo
Use C<.line 42 "file.pir"> for this.
-=head1 Subroutines
+=head1 SUBROUTINES
=head2 How do I generate a sub call in PIR?
@@ -256,7 +261,7 @@ Please refer to
L<docs/pdds/pdd20_lexical_vars.pod/Nested Subroutines Have Outies; the ":outer" attribute>
for details.
-=head1 Variables
+=head1 VARIABLES
=head2 How do I fetch a variable from the global namespace?
@@ -359,7 +364,7 @@ doesn't know the variable. You can always just use the register that was
defined in the C<.lex> directive as an alias to that lexical, if you are in
the same scope.
-=head1 Modules, Classes, and Objects
+=head1 MODULES, CLASSES, and OBJECTS
=head2 How do I create a module?
@@ -571,7 +576,7 @@ XXX
XXX
-=head1 Exceptions
+=head1 EXCEPTIONS
=head2 How do I throw an exception in PIR?
@@ -664,7 +669,7 @@ Exception example:
=end PIR_FRAGMENT
-=head1 C Extensions
+=head1 C EXTENSIONS
=head2 How do I create PMCs for my compiler?
@@ -740,7 +745,7 @@ in that same C file, you should pass a null string to loadlib. Do that as follow
Under Linux, the .c file must then be linked with the -export-dynamic option.
-=head1 Misc
+=head1 MISC.
=head2 How can I access a program's environment?
View
6 docs/debug.pod
@@ -1,10 +1,10 @@
-# Copyright (C) 2001-2009, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/debug.pod - Debugging Parrot
-=head1 ABSTRACT
+=head1 DESCRIPTION
This document describes how to debug various parts of Parrot.
@@ -240,3 +240,5 @@ with gdb and a version of parrot compiled with C<gcc> and the C<-g> flag.
executable_name_pmc = (PMC *) 0x8204d70
status = 1267896320
(gdb)
+
+=cut
View
4 docs/deprecations/deprecations.pod
@@ -1,10 +1,10 @@
-# Copyright (C) 2011, Parrot Foundation.
+# Copyright (C) 2011-2012, Parrot Foundation.
=head1 NAME
docs/deprecations/deprecations.pod - Parrot Deprecations
-=head1 Parrot Deprecations
+=head1 DESCRIPTION
This page exists to systematically document all deprecations that apply to core
Parrot code.
View
6 docs/deprecations/deprecations_2_6.pod
@@ -1,10 +1,12 @@
-# Copyright (C) 2011, Parrot Foundation.
+# Copyright (C) 2011-2012, Parrot Foundation.
=head1 NAME
docs/deprecations/deprecations_2_6.pod - Parrot Deprecations for 2.6
-=head1 Parrot Deprecations for 2.6
+=head1 DESCRIPTION
+
+Parrot Deprecations for 2.6.
=head2 Remove sizeof op
View
8 docs/deprecations/deprecations_2_9.pod
@@ -1,10 +1,12 @@
-# Copyright (C) 2011, Parrot Foundation.
+# Copyright (C) 2011-2012, Parrot Foundation.
=head1 NAME
docs/deprecations/deprecations_2_9.pod - Parrot Deprecations for 2.9
-=head1 Parrot Deprecations for 2.9
+=head1 DESCRIPTION
+
+Parrot Deprecations for 2.9.
=head2 Remove charset opcodes and fixed_8 encoding
@@ -197,4 +199,4 @@ There was a inconsistency, some PMCs used is_tty and others isatty. The decision
Use isatty.
-=cut
+=cut
View
6 docs/deprecations/deprecations_3_0.pod
@@ -1,10 +1,12 @@
-# Copyright (C) 2011, Parrot Foundation.
+# Copyright (C) 2011-2012, Parrot Foundation.
=head1 NAME
docs/deprecations/deprecations_3_0.pod - Parrot Deprecations for 3.0
-=head1 Parrot Deprecations for 3.0
+=head1 DESCRIPTION
+
+Parrot Deprecations for 3.0.
=head2 PARROT_ERRORS_GLOBALS_FLAG
View
6 docs/deprecations/deprecations_3_3.pod
@@ -1,10 +1,12 @@
-# Copyright (C) 2011, Parrot Foundation.
+# Copyright (C) 2011-2012, Parrot Foundation.
=head1 NAME
docs/deprecations/deprecations_3_3.pod - Parrot Deprecations for 3.3
-=head1 Parrot Deprecations for 3.3
+=head1 DESCRIPTION
+
+Parrot Deprecations for 3.3.
=head2 pkg-config Support
View
6 docs/deprecations/deprecations_3_6.pod
@@ -1,10 +1,12 @@
-# Copyright (C) 2011, Parrot Foundation.
+# Copyright (C) 2011-2012, Parrot Foundation.
=head1 NAME
docs/deprecations/deprecations_3_6.pod - Parrot Deprecations for 3.6
-=head1 Parrot Deprecations for 3.6
+=head1 DESCRIPTION
+
+Parrot Deprecations for 3.6.
=head2 Special Purpose NCI Parameter Types
View
10 docs/deprecations/how_to_deprecate.pod
@@ -1,13 +1,15 @@
-# Copyright (C) 2011, Parrot Foundation.
+# Copyright (C) 2011-2012, Parrot Foundation.
=head1 NAME
docs/deprecations/how_to_deprecate.pod - How to Deprecate Parrot Code
-=head1 How to Deprecate Parrot Code
+=head1 DESCRIPTION
-So you've found a crufty bit of code in Parrot that's just screaming to be
-removed. Welcome to the club. There's a lot of them. This page documents
+How to Deprecate Parrot Code.
+
+You've found a crufty bit of code in Parrot that's just screaming to be
+removed. Welcome to the club. There's a lot of them. This page documents
the proper procedure to go through to get that junk code out of Parrot while
causing minimal pain to Parrot's users (i.e. people who develop HLLs or
libraries on top of Parrot).
View
23 docs/dev/byteorder.pod
@@ -1,10 +1,15 @@
-# Copyright (C) 2001-2006, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/dev/byteorder.pod - Byteorder Conversion Functions
-=head1 Overview
+=head1 DESCRIPTION
+
+This document addresses the byteorder conversion functions for the Parrot
+Virtual Machine.
+
+=head1 OVERVIEW
The platform byteorder is stored for C code in F<include/parrot/config.h>
@@ -43,7 +48,7 @@ endian. The functions are be placed in the PackFile vtable and are be called
when necessary. The Parrot interpreter is be smart enough to avoid calling
these functions when converting from and to the same byteorder.
-=head1 Data Structures and Algorithms
+=head1 DATA STRUCTURES AND ALGORITHMS
The algorithm to change from one endianness to another is identical and simple
to understand. Basically, the size of an C<INTVAL> or C<opcode_t> is used to
@@ -52,7 +57,7 @@ correct bits are shifted by the correct amounts (please look at source code for
exact amounts). The buffer change functions are implemented by a straight
forward algorithm that assigns swaps all of the bytes.
-=head1 Important Functions
+=head1 IMPORTANT FUNCTIONS
=over 4
@@ -90,7 +95,7 @@ endian.
=back
-=head1 Low level FLOATVAL fetch and convert functions
+=head1 LOW LEVEL FLOATVAL FETCH AND CONVERT FUNCTIONS
We support two different floattypes, stored in the pbc header as 0 or 1.
@@ -115,7 +120,7 @@ Converts a 12-byte i386 long double into a little-endian IEEE 754
=back
-=head1 Unimplemented Functions
+=head1 UNIMPLEMENTED FUNCTIONS
=over 4
@@ -129,18 +134,18 @@ Put an C<INTVAL> directly on a bytestream
=back
-=head1 History
+=head1 HISTORY
Initial version by Melvin on 2002-01-05,
more byteorder explanations by Reini Urban 2009-02-02
-=head1 Notes
+=head1 NOTES
This assumes big or little endianness...other, more esoteric forms (such as
middle endian) are not supported. Also, an assumption of 4 or 8 byte
C<INTVAL>'s and C<opcode_t>'s is made.
-=head1 References
+=head1 REFERENCES
The fetch and transformer functions are implemented in F<src/packfile/pf_items.c>
View
16 docs/dev/c_functions.pod
@@ -1,10 +1,15 @@
-# Copyright (C) 2001-2006, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/dev/c_functions.pod - C function decoration guidelines
-=head1 Overview
+=head1 DESCRIPTION
+
+This document addresses Parrot's macro and configuration system, which help
+to ensure various, important compile-time checks.
+
+=head1 OVERVIEW
Compilers have the ability to detect a wide class of potential errors in
code during the compilation phase, especially if certain metadata is
@@ -31,7 +36,7 @@ compilers. In some cases, the various macros might be empty placeholders.
Also, where it says "compiler", it could also mean "lint or any
other static analysis tool like splint."
-=head1 Function Parameter Decorators
+=head1 FUNCTION PARAMETER DECORATORS
=head2 What's a shim?
@@ -126,7 +131,7 @@ and C<ARGMOD_NULLOK>. These have the same semantics as their
non-NULLOK counterparts, except the compiler will not throw errors if
a null value is passed.
-=head1 Function Decorators
+=head1 FUNCTION DECORATORS
In addition to the C<SHIM>, C<ARGIN>, C<ARGOUT> and C<ARGMOD> parameters
and variants for parameters, there are a number of helpful modifiers that
@@ -194,7 +199,7 @@ For functions that are important API functions.
{{TODO: More detail is needed on this}}
-=head1 Examples
+=head1 EXAMPLES
PARROT_EXPORT
PARROT_WARN_UNUSED_RESULT
@@ -226,3 +231,4 @@ We could put C<PARROT_WARN_UNUSED_RESULT> on this function, but since
all C<PARROT_PURE_FUNCTION>s and C<PARROT_CONST_FUNCTION>s get flagged
that way anyway, there's no need.
+=cut
View
10 docs/dev/coverage.pod
@@ -1,10 +1,10 @@
-# Copyright (C) 2001-2010, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 Make Cover
docs/dev/coverage.pod - Make Cover Documentation.
-=head1 Overview
+=head1 DESCRIPTION
"make cover" is a very useful tool which generates reports on how well tested
parrot code is. The coverage reports are outputted in various formats in
@@ -12,7 +12,7 @@ cover_db/ after C<make cover> has run. The final result of make cover is a
listing of parrot's source files and a matching percentage of how well covered
that file is by the tests.
-=head1 Dependencies
+=head1 DEPENDENCIES
Obviously, the first step would be to get parrot and build it. See
F<docs/intro.pod> for more information. To run "make cover" you must first
@@ -30,7 +30,7 @@ and that will install the required module. Other OSes may have this packaged
as well, so try to find it. If you do not have a packaged version of this
module, head over to http://search.cpan.org/dist/Devel-Cover/ and install it.
-=head1 Process
+=head1 PROCESS
Next, make sure your working parrot directory is as clean as can be. Any left
over files can cause problems when generating the coverage reports.
@@ -46,7 +46,7 @@ type in C<make cover> and leave to make a sandwich and something to drink
because it's probably going to take a I<long> time to run. If you run into
trouble, C<make fulltest> may be of some assistance.
-=head1 Cover
+=head1 COVER
If you have run C<make fullcover> before, you know how long it takes to execute
that command. Recently a new tool C<make cover> has been added that is
View
6 docs/dev/debugging_with_msvc.pod
@@ -1,17 +1,15 @@
-# Copyright (C) 2007, Parrot Foundation.
+# Copyright (C) 2007-2012, Parrot Foundation.
=head1 NAME
docs/dev/debugging_with_msvc.pod - Debugging Parrot with Microsoft
Visual C++
-=head1 ABSTRACT
+=head1 DESCRIPTION
This document describes how to get started with debugging on Microsoft
Windows using Visual C++ 7 and later.
-=head1 DESCRIPTION
-
=head2 Compiler Options
Probably the easiest way to get going with debugging is to add some
View
14 docs/dev/headerizer.pod
@@ -1,4 +1,4 @@
-# Copyright (C) 2007, Parrot Foundation.
+# Copyright (C) 2007-2012, Parrot Foundation.
=pod
@@ -6,11 +6,7 @@
The Headerizer
-=head1 AUTHOR
-
-Andy Lester C<< andy@petdance.com >>
-
-=head1 INTRODUCTION
+=head1 DESCRIPTION
The Headerizer (F<tools/build/headerizer.pl>) is a tool that generates
chunks of F<.h> header files based on C source code.
@@ -38,3 +34,9 @@ here's what you do:
=back
The .h file should now have PARROT_EXPORT for the function in question.
+
+=head1 AUTHOR
+
+Andy Lester C<< andy@petdance.com >>
+
+=cut
View
19 docs/dev/infant.pod
@@ -1,10 +1,15 @@
-# Copyright (C) 2001-2006, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/dev/infant.pod - Infant Mortality
-=head1 Overview
+=head1 DESCRIPTION
+
+This document compares and contrasts several proposals for Parrot's Garbage
+Collection system.
+
+=head1 OVERVIEW
We have a garbage collector that needs to detect all dead objects (the process
is called the mark phase of GC). Any Parrot operation that might allocate
@@ -33,10 +38,9 @@ referred to as the "infant mortality" problem.
Peter Gibbs, Mike Lambert, Dan Sugalski and others have considered various
solutions to this problem. Most of those solutions have been implemented in
-some form or other. This document is an attempt to compare and contrast all
-such proposals.
+some form or other.
-=head1 Solution 1: Stack Walking
+=head1 SOLUTION 1: STACK WALKING
One possible solution is to add the C stack into the root set. This way,
temporary PMCs that have not yet been anchored to the root set will be found on
@@ -71,7 +75,7 @@ calls. This is especially a problem for objects which need early destruction.
pointer lying around on the stack or in a register, and all such
pointers will be dereferenced.
-=head1 Solution 2: Neonate flag
+=head1 SOLUTION 2: NEONATE FLAG
There are several possible variants of the neonate flag, but the basic idea is
to set a flag on newly created objects that prevents them from being collected.
@@ -187,7 +191,7 @@ through longjmps and recursive run_cores.
- Nested temporaries can survive if there is no mark run between two
function calls with increased generation count
-=head1 Solution 3: Explicit root set augmentation
+=head1 SOLUTION 3: EXPLICIT ROOT SET AUGMENTATION
=head2 Variant 1: Temporarily anchor objects
@@ -314,3 +318,4 @@ This thread also includes Juergen Boemmels Variant 3 of Solution 3
2002-Dec-30: Initial Version by Steve Fink 2003-Aug-04: Some extra variants
added by Juergen Boemmels
+=cut
View
4 docs/dev/longopt.pod
@@ -1,10 +1,10 @@
-# Copyright (C) 2001-2006, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/dev/longopt.pod - Long option parsing
-=head1 SUMMARY
+=head1 DESCRIPTION
The files F<longopt.c> and F<longopt.h> implement rudimentary long option
parsing. They have little to do with Parrot itself, other than that the parrot
View
10 docs/dev/parrot_api.pod
@@ -4,6 +4,10 @@
docs/dev/parrot_api.pod - Notes on the PARROT_EXPORT macro
+=head1 DESCRIPTION
+
+This document addresses the correct use of the C<PARROT_EXPORT> macro.
+
=head1 OVERVIEW
Some compilers and platforms export all symbols either by default or through
@@ -17,13 +21,17 @@ anything that will be used by a shared library or by the main Parrot executable
when Parrot is built as a shared library.
-=head1 USAGE NOTES
+=head1 USAGE
Incorrect usage of C<PARROT_EXPORT> can break the build on some platforms,
especially Win32. The rules for how to use it are as follows.
=over 4
+=item If you decorate a function with multiple modifiers, I<e.g.,>
+C<PARROT_EXPORT>, C<PARROT_COLD>, C<PARROT_CANNOT_RETURN_NULL>,
+C<PARROT_EXPORT> I<must> appear first in the list.
+
=item If you decorate a function with C<PARROT_EXPORT> in a .c file, you must
also decorate the symbol with C<PARROT_EXPORT> in all .h files that mention it.
View
7 docs/dev/pcc_methods.pod
@@ -1,9 +1,14 @@
-# Copyright (C) 2007-2011, Parrot Foundation.
+# Copyright (C) 2007-2012, Parrot Foundation.
=head1 NAME
docs/dev/pcc_methods.pod - Parrot Calling Conventions in C
+=head1 DESCRIPTION
+
+This document address issues relating to C<PCCMETHOD> and the Parrot
+Calling Conventions.
+
=head1 OVERVIEW
A C<PCCMETHOD> is a PMC method that follows the Parrot Calling Conventions
View
17 docs/dev/pcc_state.pod
@@ -1,9 +1,20 @@
-=head1 parrot calling conventions state table
+# Copyright (C) 2001-2012, Parrot Foundation.
-this document expresses the calling conventions as outlined in PDD03 in table
-format. this is a work in progress, which, when finished, should assist in
+=pod
+
+=head1 NAME
+
+docs/dev/pcc_state.pod - Readme file for the Parrot Calling Conventions State
+Table.
+
+=head1 DESCRIPTION
+
+This document expresses the calling conventions as outlined in PDD03 in table
+format. This is a work in progress, which, when finished, should assist in
creating an exhaustive test suite for calling conventions.
+=head1 PARROT CALLING CONVENTIONS STATE TABLE
+
1 2 3 4 5 6 7 8 9
| DEST | |
View
14 docs/dev/pmc_freeze.pod
@@ -1,15 +1,15 @@
-# Copyright (C) 2001-2006, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/dev/pmc_freeze.pod - Freeze/Thaw Design Notes
-=head1 VERSION
+=head1 DESCRIPTION
-This document describes freeze/thaw internals version 0.1. This is not the
-final implementation.
+This document describes freeze/thaw internals version 0.1. Please note: This
+is not the final implementation.
-=head1 Overview
+=head1 OVERVIEW
Freezing or serializing arbitrary PMCs is an interesting problem. Aggregates
can hold other aggregates and can be deeply nested, so so a recursive approach
@@ -17,7 +17,7 @@ could easily blow the stack, especially on embedded systems. Also, aggregates
can be self-referential -- they can hold pointers to themselves -- so that
working on such structures could create infinite loops.
-=head1 Coverage
+=head1 COVERAGE
Although the file is named F<pmc_freeze.c> it ultimately will deal with every
kind of operation that deeply traverses an arbitrary data structures. For
@@ -227,7 +227,7 @@ B<EXTRA_IS_PROP_HASH>.
F<src/pmc_freeze.c>, F<pf/pf_items.c>
-=head1 Author
+=head1 AUTHOR
Leopold Toetsch C<lt@toetsch.at>
View
20 docs/dev/pmc_obj_design_meeting_notes.pod
@@ -1,4 +1,17 @@
-=head1 Parrot PMC/Object Design Meeting Notes
+# Copyright (C) 2001-2012, Parrot Foundation.
+
+=pod
+
+=head1 NAME
+
+docs/dev/pmc_obj_design_meeting_notes.pod
+
+=head1 DESCRIPTION
+
+This document sets out PMC/Object Design Meeting Notes which took place in
+Chicago in 2006.
+
+=head1 PARROT PMC/OBJECT DESIGN MEETING NOTES
During the Chicago Hackathon 2006, Jerry Gay, Matt Diephouse, chromatic,
Leo Toetch, Jonathan Worthington and Chip Salzenberg (arriving late) met to
@@ -9,9 +22,8 @@ L<http://rakudo.org/hackathon-chicago/index.cgi?pmc>. A log of the discussion
that took place can be found at
L<http://www.parrotcode.org/misc/parrotsketch-logs/irclog.parrotsketch-200611/irclog.parrotsketch.20061112>.
-This summary has been compiled from these sources,
-and from other conversations that were not recorded.
-
+This summary has been compiled from these sources and from other
+conversations which were not recorded.
=head2 List of problems and proposed solutions for PMCs:
View
6 docs/extend.pod
@@ -1,4 +1,4 @@
-# Copyright (C) 2005-2007, Parrot Foundation.
+# Copyright (C) 2005-2012, Parrot Foundation.
=head1 NAME
@@ -11,6 +11,10 @@ extend.pod - Parrot extension system
int main(int argc, char *argv[]) {
}
+=head1 DESCRIPTION
+
+This document, briefly, describes Parrot's extension system.
+
=head1 FILES
=over 4
View
6 docs/faq.pod
@@ -1,9 +1,13 @@
-# Copyright (C) 2001-2007, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/faq.pod - Parrot FAQ
+=head1 DESCRIPTION
+
+This document is the main Parrot FAQ.
+
=head1 GENERAL QUESTIONS
=head2 What is Parrot?
View
8 docs/gettingstarted.pod
@@ -1,9 +1,13 @@
-# Copyright (C) 2001-2010, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/gettingstarted.pod - Parrot Developer FAQ
+=head1 DESCRIPTION
+
+This document is the Developer FAQ for Parrot.
+
=head1 DEVELOPER FAQ
=head2 I'm interested in helping out. What should I do?
@@ -195,3 +199,5 @@ See F<docs/submissions.pod> for details.
A number of other useful resources that can be found via on the Parrot
wiki, located at L<https://github.com/parrot/parrot/wiki>
+
+=cut
View
6 docs/glossary.pod
@@ -1,16 +1,16 @@
-# Copyright (C) 2001-2011, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/glossary.pod - Parrot Glossary
-=head1 SUMMARY
+=head1 DESCRIPTION
Short descriptions of words and acronyms found in Parrot development.
=head1 VERSION
-LAST UPDATED: 14 FEB 2011
+LAST UPDATED: 24 MAY 2012
glossary.pod is updated and maintained from Parrot's GitHub repository.
You may get the most up-to-date version at:
View
16 docs/imcc/imcfaq.pod
@@ -1,6 +1,13 @@
-# Copyright (C) 2001-2008, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
-=head1 TITLE
+=pod
+
+=head1 NAME
+
+docs/imcc/imcfaq.pod - The FAQ for PIR and Parrot Programming Compiler
+Developers.
+
+=head1 DESCRIPTION
PIR and Parrot Programming for Compiler Developers - Frequently Asked Questions
@@ -17,8 +24,9 @@ The Parrot FAQ : http://www.parrotcode.org/faq/
=head2 What is IMC, PIR and IMCC?
IMC stands for Intermediate Code. IMCC stands for Intermediate Code Compiler.
-Most of the time you will encounter the term PIR which is for Parrot Intermediate Representation
-and means the same thing as IMC. PIR files use the extension C<.pir>.
+Most of the time you will encounter the term PIR which is for Parrot
+Intermediate Representation and means the same thing as IMC. PIR files use the
+extension C<.pir>.
PIR is an intermediate language that compiles either directly to Parrot Byte
code. It is a possible target language for compilers targeting
View
10 docs/intro.pod
@@ -1,17 +1,17 @@
-# Copyright (C) 2001-2009, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/intro.pod - The Parrot Primer
-=head1 Welcome to Parrot
+=head1 DESCRIPTION
This document provides a gentle introduction to the Parrot virtual machine for
anyone considering writing code for Parrot by hand, writing a compiler that
targets Parrot, getting involved with Parrot development or simply wondering
what on earth Parrot is.
-=head1 What is Parrot?
+=head1 WHAT IS PARROT?
=head2 Virtual Machines
@@ -160,7 +160,7 @@ from reporting test failures, using the same method as described for reporting
build problems.
-=head1 Some simple Parrot programs
+=head1 SOME SIMPLE PARROT PROGRAMS
=head2 Hello world!
@@ -418,7 +418,7 @@ the extension F<.pbc>.
parrot -o factorial.pbc factorial.pir
-=head1 Where next?
+=head1 WHERE NEXT?
=head2 Documentation
View
16 docs/memory_internals.pod
@@ -1,10 +1,10 @@
-# Copyright (C) 2001-2009, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/memory_internals.pod - Memory Internals
-=head1 ABSTRACT
+=head1 DESCRIPTION
This document tries to explain the internals of the Parrot memory subsystem,
and the data structures related to memory management and garbage collection.
@@ -44,7 +44,7 @@ considered dead and are collected.
See F<docs/pdds/pdd09_gc.pod> for details about the garbage collector system.
-=head1 Top down: the interpreter
+=head1 TOP DOWN: THE INTERPRETER
A overall layout of the interpreter's memory management looks like so:
@@ -58,7 +58,7 @@ All object-like things that get allocated during the execution of parrot
bytecode are managed from the C<mem_pools> member of the interpreter
structure.
-=head1 Memory Pools
+=head1 MEMORY POOLS
C<struct Memory_Pools> holds pointers to a variety of different kinds of managed
memory. A simplification looks similar to this:
@@ -77,7 +77,7 @@ C<struct Var_Size_Pool> are for variable-size objects, such as constant string
buffers. Pools of type C<struct Fixed_Size_Pool> are for fixed-size objects
such as headers or PMCs.
-=head1 Fixed sized items
+=head1 FIXED SIZED ITEMS
Fixed-size items are either objects by themselves, like a C<PMC>, or are
header structures of variable-sized objects like C<STRING>. The general
@@ -138,7 +138,7 @@ F<pobj.h> provides macros to facilitate referencing individual object flags:
C<gc_flag_SET>, C<gc_flag_CLEAR> and C<gc_flag_TEST>. They make up a portable
way of manipulating the GC-relevant object flags.
-=head1 Variable sized items
+=head1 VARIABLE SIZE ITEMS
Variable-sized items do not exist by themselves, they are always wrapped by
a buffer structure that contains a pointer to the data information about them.
@@ -215,7 +215,7 @@ mark phase all dead users increment the refcount, living users set it to an
huge value. When freeing the buffer, the string is only freed if the refcount
reaches zero.
-=head1 Simplified Figure
+=head1 SIMPLIFIED FIGURE
+--------------+
+--------------<---| Memory Pools |<---------+
@@ -261,3 +261,5 @@ Leopold Tötsch C<lt@toetsch.at>
=head1 VERSION
0.1.1 June 2008
+
+=cut
View
15 docs/overview.pod
@@ -1,17 +1,17 @@
-# Copyright (C) 2001-2006, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/overview.pod - A Parrot Overview
-=head1 The Parrot Interpreter
+=head1 DESCRIPTION
This document is an introduction to the structure of and the concepts used by
the Parrot shared bytecode compiler/interpreter system. We will primarily
concern ourselves with the interpreter, since this is the target platform for
which all compiler frontends should compile their code.
-=head1 The Software CPU
+=head1 THE SOFTWARE CPU
Like all interpreter systems of its kind, the Parrot interpreter is a virtual
machine; this is another way of saying that it is a software CPU. However,
@@ -42,7 +42,7 @@ Registers will be stored in register frames, which can be pushed and popped
onto the register stack. For instance, a subroutine or a block might need its
own register frame.
-=head1 The Operations
+=head1 THE OPERATIONS
The Parrot interpreter has a large number of very low level instructions, and
it is expected that high-level languages will compile down to a medium-level
@@ -92,7 +92,7 @@ Pythonic activities.
For documentation on the specific PMCs that ship with Parrot, see the
F<docs/pmc> directory.
-=head1 Vtables
+=head1 VTABLES
The way we achieve this abstraction is to assign to each PMC a set of function
pointers that determine how it ought to behave when asked to do various things.
@@ -134,7 +134,7 @@ runtimes for bytecompiled languages.
One interesting thing about vtables is that you can construct them dynamically.
You can find out more about vtables in F<docs/vtables.pod>.
-=head1 String Handling
+=head1 STRING HANDLING
Parrot provides a programmer-friendly view of strings. The Parrot string
handling subsection handles all the work of memory allocation, expansion, and
@@ -149,7 +149,7 @@ function either to the other encodings or just to Unicode for use as a pivot.
The string handling API is explained in F<docs/strings.pod>.
-=head1 Bytecode format
+=head1 BYTECODE FORMAT
We have already explained the format of the main stream of bytecode; operations
will be followed by arguments packed in such a format as the individual
@@ -174,3 +174,4 @@ program file.
The bytecode format is fully documented in F<docs/parrotbyte.pod>.
+=cut
View
9 docs/parrot.pod
@@ -1,13 +1,13 @@
-# Copyright (C) 2001-2010, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/parrot.pod - Parrot
-=head1 The Parrot Virtual Machine
+=head1 DESCRIPTION
-Parrot is a language-agnostic common bytecode format and an interpreter for
-dynamic languages.
+The Parrot Virtual Machine is a language-agnostic common bytecode format and
+an interpreter for dynamic languages.
=head2 Documentation
@@ -127,3 +127,4 @@ See:
for more information.
+=cut
View
11 docs/parrotbyte.pod
@@ -1,12 +1,16 @@
-# Copyright (C) 2001-2007, Parrot Foundation.
+# Copyright (C) 2001-2012, Parrot Foundation.
=head1 NAME
docs/parrotbyte.pod - The Parrot Bytecode (PBC) Format
-=head1 Format of the Parrot bytecode
+=head1 DESCRIPTION
-The 18-byte header consists of:
+This document describes the Parrot bytecode format.
+
+=head1 THE HEADER
+
+The 18-byte header consists of,
0 7
+----------+----------+----------+----------+
@@ -331,3 +335,4 @@ mentioned in some of the early Parrot documents.
F<packfile.c>, F<packfile.h>, F<packdump.c>, F<pf/*.c>, and the
B<pbc_dump> utility F<pbc_dump.c>.
+=cut
View
39 docs/pmc.pod
@@ -1,8 +1,16 @@
-=head1 Title
+# Copyright (C) 2001-2012, Parrot Foundation.
+
+=pod
+
+=head1 NAME
docs/pmc.pod - PMC (PMC Makers Compendium)
-=head1 PMC Structure Items Access
+=head1 DESCRIPTION
+
+This document covers some of the important internals of Parrot's PMCs.
+
+=head1 PMC STRUCTURE ITEMS ACCESS
Ideally, there should be minimal direct access to a PMC's internals. In order
to enforce encapsulation, most interaction with a PMC should be performed
@@ -16,7 +24,7 @@ can be accessed either directly: C<< PARROT_FOO(pmc)->bar >> or via a
SETATTR/GETATTR accessor macro: C<GETATTR_Foo_bar(INTERP, x)>. Note that
inside a PMC's source file, these can be shortened to C<GET_ATTR_bar(INTERP, x)>.
-=head1 PMC Storage
+=head1 PMC STORAGE
PMCs can store data in two places. 8 bits can be stored in the PMC's flags.
These are accessed via PObj_private0_FLAG, PObj_private1_FLAG, etc, although
@@ -52,22 +60,23 @@ and it must be destroyed in the C<destroy()> VTABLE function, the PMC must
also indicate that they need active destruction by calling
C<PObj_custom_destroy_SET()> or C<PObj_custom_mark_destroy_SETALL()>.
-If your PMC only needs to store a single pointer, it can use C<PMC_data> directly.