Merge branch 'ayardley/pod_DESCRIPTIONS'

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

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
 

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

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

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

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>

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' :
  */
-

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

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

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
 

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
 

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
 

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
-

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' ]

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' ]

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
 

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
 

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'.

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'.

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'.