Permalink
Browse files

Changed documentation to use POD5 instead of POD6 since `perl6 --doc`…

… just doesn't cut it right now.
  • Loading branch information...
1 parent edef6aa commit 12e617a60edb11b7ec890345e77acf9ffa54b252 @soh-cah-toa soh-cah-toa committed Oct 19, 2011
@@ -1,5 +1,3 @@
-=begin pod
-
=head1 Adding a New Project Action
This document describes how to add a new action that can be performed on a
@@ -12,15 +10,13 @@ L<Adding a New Command|add-command.pod> instead.
You will need to update F<src/lib/Plumage/Project.nqp> to implement the
action, as follows:
-=over 4
-
-=item New Subsection
+=head3 New Subsection
Add a new subsection for the new action within the C<ACTIONS> section of
the code. Try to place the new subsection roughly in the sequence the
action is likely to be used.
-=item Base Action Method
+=head3 Base Action Method
Add the base action method at the top of the new subsection. It should
be named for the action itself and take no arguments. For instance, the
@@ -36,7 +32,7 @@ If the instructions do exist, the base method should let the user know
the action is about to be executed and then redispatch to a method
specific to the action type specified in the metadata instructions.
-=item Specific Action Methods
+=head3 Specific Action Methods
Add specific action methods for each type supported by the new action.
Each specific method name should have the base method name and the action
@@ -45,8 +41,6 @@ type separated by an underscore, e.g. C<fetch_git()> and C<fetch_svn()>.
These should actually perform the task at hand and return 1 on success and 0
on failure.
-=back
-
=head2 Known Actions List
Before the new action is considered valid, it must be added to the known
@@ -70,5 +64,3 @@ C<Plumage::Project> does not have a test suite yet.
Once the new action is implemented, documented, and tested, continue with
L<Adding a New Command|add-command.pod> to add a command for this action to
the C<plumage> command-line tool.
-
-=end pod
@@ -1,5 +1,3 @@
-=begin pod
-
=head1 Adding a New Build Tool
There are a great many build tools in the wild, from C<make> to C<Build>,
@@ -63,5 +61,3 @@ along with any special features or limitations.
=head2 Tests
C<Plumage::Project> does not have a test suite yet.
-
-=end pod
@@ -1,5 +1,3 @@
-=begin pod
-
=head1 Adding a New Command
This document describes how to add a new command to Plumage, so that users can
@@ -79,5 +77,3 @@ command should actually do what it claims to do.
Lastly, make sure you properly document the purpose and features of the new
command in the manpage (F<man/man1/plumage.1>). Documentation is very
important!
-
-=end pod
View
@@ -1,5 +1,3 @@
-=begin pod
-
=head1 Adding Tests
This document lists a few general conventions that will make it easier for
@@ -9,14 +7,10 @@ developers to work together on the test suite.
Test files should be named as follows:
-=begin code
-
(01-09)-foo.t Basic tests of low-level infrastructure
(10-49)-lib-plumage-foo.t Tests for Plumage::Foo libraries in layer order
(50-99)-plumage-type.t Various types of tests for the Plumage CLI tool
-=end code
-
=head2 Test File Layout
Each new test file should follow the same basic layout as seen in the
@@ -44,14 +38,20 @@ PIR-based design shows through and NQP provides better native tools.
In particular:
-=item Instead of C<like()>, please use C<ok()> with a native NQP-rx
+=over 4
+
+=item *
+
+Instead of C<like()>, please use C<ok()> with a native NQP-rx
C<$string ~~ /regex/> match.
-=item Instead of C<lives_ok()>, C<dies_ok()>, or C<throws_like()>, please use
+=item *
+
+Instead of C<lives_ok()>, C<dies_ok()>, or C<throws_like()>, please use
the native NQP-rx C<try {}> and/or C<CATCH {}>.
+=back
+
If you do end up using a C<Test::More> subroutine not already sanity-checked
in F<t/01-sanity.t>, please add a quick test there as well just to verify that
we know what happened if a future change in Parrot breaks the test suite.
-
-=end pod
@@ -1,5 +1,3 @@
-=begin pod
-
=head1 Contributing
=head2 Getting Started
@@ -20,9 +18,17 @@ Don't worry, there aren't many.
Fundamentally, our committer rules boil down to the same ones Parrot uses:
-=item 1 Don't break the build.
+=over 4
+
+=item *
+
+Don't break the build.
-=item 2 Increase the awesome.
+=item *
+
+Increase the awesome.
+
+=back
Many thanks to I<chromatic> for suggesting these.
@@ -42,5 +48,3 @@ review them and commit or reply with comments.
With your first patch or commit, please add yourself to the F<CREDITS> file.
Welcome to the Plumage team. We're happy to have you!
-
-=end pod
@@ -1,5 +1,3 @@
-=begin pod
-
=head1 Internal Design
Plumage is designed as a set of layered libraries providing the bulk of
@@ -9,8 +7,6 @@ command-line tool.
The Plumage stack currently looks like this:
-=begin code
-
,---------------------------------------------------.
| User Interface |
| ,------------------. ,-----------------------. |
@@ -28,8 +24,6 @@ The Plumage stack currently looks like this:
| * Config::JSON | |
`---------------------------------------------------'
-=end code
-
It is intended that as Plumage's functionality grows, more libraries (and
probably more layers) will be added in the C<Plumage::*> namespace. There
has also been some discussion of merging C<Plumage::NQPUtil> or its
@@ -86,5 +80,3 @@ user's input, showing feedback, displaying query results, and giving help.
Adding a new command to the F<plumage> command-line tool is described in the
L<Adding a New Command|add-command.pod> document.
-
-=end pod
View
@@ -1,5 +1,3 @@
-=begin pod
-
=head1 Using the Plumage Interactive Command-Line Interface
In addition to the basic single command interface from the shell, Plumage
@@ -22,22 +20,16 @@ temporarily or permanently.
After you've started Plumage, you will be greeted by the welcome message.
-=begin code
-
Plumage: Package Manager for Parrot
Copyright (C) 2009-2011, Parrot Foundation.
Enter 'help' for help or see docs/interactive.pod for further information.
plumage>
-=end code
-
As the above message suggests, if you aren't sure of something, use the C<help>
command.
-=begin code
-
plumage> help
List of commands:
@@ -66,13 +58,9 @@ command.
clean <project> Performs basic cleanup of source tree for <project>.
realclean <project> Removes all generated files during the build process for <project>.
-=end code
-
Suppose you want to try a new programming language but aren't sure which. Let's
see what's available.
-=begin code
-
plumage> projects
Known projects:
Close Systems programming language (C-like) for the Parrot VM
@@ -96,14 +84,10 @@ see what's available.
# Output truncated for brevity
-=end code
-
As you can see, the C<projects> command lists all the projects in the
ecosystem. Maybe you're feeling a little silly and want to write some
LOLCODE. Let's find out a little bit more about LOLCODE.
-=begin code
-
plumage> info lolcode
Name : lolcode
Version : HEAD
@@ -113,13 +97,9 @@ LOLCODE. Let's find out a little bit more about LOLCODE.
License : Artistic License 2.0
Description : Lolcode
-=end code
-
Looks like someone was lazy and didn't fully fill out the LOLCODE metadata
file. That's alright, it'll be a surprise!
-=begin code
-
plumage> install lolcode
/usr/bin/git clone git://github.com/parrot/lolcode.git /home/foo/.parrot/plumage/build/lolcode
Cloning into /home/foo/.parrot/plumage/build/lolcode...
@@ -131,19 +111,12 @@ file. That's alright, it'll be a surprise!
# Output truncated for brevity
-=end code
-
This builds, tests, and installs a particular project/module; in this case,
C<lolcode>. It could be that you're not really in a lolcatz mood right now.
Uninstalling a project is done with the aptly named C<uninstall> command.
-=begin code
-
plumage> uninstall lolcode
Uninstalling lolcode ...
/home/foo/bin/bin/parrot setup.pir uninstall
Successful.
-=end code
-
-=end pod

0 comments on commit 12e617a

Please sign in to comment.