Skip to content

Commit

Permalink
Changed documentation to use POD5 instead of POD6 since perl6 --doc…
Browse files Browse the repository at this point in the history 
… just doesn't cut it right now.
  • Loading branch information
@soh-cah-toa
soh-cah-toa committed Oct 19, 2011
1 parent edef6aa commit 12e617a
Show file tree
Hide file tree
Showing 7 changed files with 23 additions and 70 deletions.
14 changes: 3 additions & 11 deletions docs/hacking/add-action.pod
View file
@@ -1,5 +1,3 @@
=begin pod
=head1 Adding a New Project Action =head1 Adding a New Project Action


This document describes how to add a new action that can be performed on a This document describes how to add a new action that can be performed on a
Expand All @@ -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 You will need to update F<src/lib/Plumage/Project.nqp> to implement the
action, as follows: action, as follows:


=over 4 =head3 New Subsection
=item New Subsection


Add a new subsection for the new action within the C<ACTIONS> section of 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 the code. Try to place the new subsection roughly in the sequence the
action is likely to be used. 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 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 be named for the action itself and take no arguments. For instance, the
Expand All @@ -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 the action is about to be executed and then redispatch to a method
specific to the action type specified in the metadata instructions. 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. 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 Each specific method name should have the base method name and the action
Expand All @@ -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 These should actually perform the task at hand and return 1 on success and 0
on failure. on failure.


=back
=head2 Known Actions List =head2 Known Actions List


Before the new action is considered valid, it must be added to the known Before the new action is considered valid, it must be added to the known
Expand All @@ -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 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 L<Adding a New Command|add-command.pod> to add a command for this action to
the C<plumage> command-line tool. the C<plumage> command-line tool.
=end pod
4 changes: 0 additions & 4 deletions docs/hacking/add-build-tool.pod
View file
@@ -1,5 +1,3 @@
=begin pod
=head1 Adding a New Build Tool =head1 Adding a New Build Tool


There are a great many build tools in the wild, from C<make> to C<Build>, There are a great many build tools in the wild, from C<make> to C<Build>,
Expand Down Expand Up @@ -63,5 +61,3 @@ along with any special features or limitations.
=head2 Tests =head2 Tests


C<Plumage::Project> does not have a test suite yet. C<Plumage::Project> does not have a test suite yet.
=end pod
4 changes: 0 additions & 4 deletions docs/hacking/add-command.pod
View file
@@ -1,5 +1,3 @@
=begin pod
=head1 Adding a New Command =head1 Adding a New Command


This document describes how to add a new command to Plumage, so that users can This document describes how to add a new command to Plumage, so that users can
Expand Down Expand Up @@ -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 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 command in the manpage (F<man/man1/plumage.1>). Documentation is very
important! important!
=end pod
20 changes: 10 additions & 10 deletions docs/hacking/add-tests.pod
View file
@@ -1,5 +1,3 @@
=begin pod
=head1 Adding Tests =head1 Adding Tests


This document lists a few general conventions that will make it easier for This document lists a few general conventions that will make it easier for
Expand All @@ -9,14 +7,10 @@ developers to work together on the test suite.


Test files should be named as follows: Test files should be named as follows:


=begin code
(01-09)-foo.t Basic tests of low-level infrastructure (01-09)-foo.t Basic tests of low-level infrastructure
(10-49)-lib-plumage-foo.t Tests for Plumage::Foo libraries in layer order (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 (50-99)-plumage-type.t Various types of tests for the Plumage CLI tool


=end code
=head2 Test File Layout =head2 Test File Layout


Each new test file should follow the same basic layout as seen in the Each new test file should follow the same basic layout as seen in the
Expand Down Expand Up @@ -44,14 +38,20 @@ PIR-based design shows through and NQP provides better native tools.


In particular: 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. 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 {}>. 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 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 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. we know what happened if a future change in Parrot breaks the test suite.
=end pod
16 changes: 10 additions & 6 deletions docs/hacking/contributing.pod
View file
@@ -1,5 +1,3 @@
=begin pod
=head1 Contributing =head1 Contributing


=head2 Getting Started =head2 Getting Started
Expand All @@ -20,9 +18,17 @@ Don't worry, there aren't many.


Fundamentally, our committer rules boil down to the same ones Parrot uses: 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. Many thanks to I<chromatic> for suggesting these.


Expand All @@ -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. 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! Welcome to the Plumage team. We're happy to have you!
=end pod
8 changes: 0 additions & 8 deletions docs/hacking/design-internals.pod
View file
@@ -1,5 +1,3 @@
=begin pod
=head1 Internal Design =head1 Internal Design


Plumage is designed as a set of layered libraries providing the bulk of Plumage is designed as a set of layered libraries providing the bulk of
Expand All @@ -9,8 +7,6 @@ command-line tool.


The Plumage stack currently looks like this: The Plumage stack currently looks like this:


=begin code
,---------------------------------------------------. ,---------------------------------------------------.
| User Interface | | User Interface |
| ,------------------. ,-----------------------. | | ,------------------. ,-----------------------. |
Expand All @@ -28,8 +24,6 @@ The Plumage stack currently looks like this:
| * Config::JSON | | | * Config::JSON | |
`---------------------------------------------------' `---------------------------------------------------'


=end code
It is intended that as Plumage's functionality grows, more libraries (and It is intended that as Plumage's functionality grows, more libraries (and
probably more layers) will be added in the C<Plumage::*> namespace. There probably more layers) will be added in the C<Plumage::*> namespace. There
has also been some discussion of merging C<Plumage::NQPUtil> or its has also been some discussion of merging C<Plumage::NQPUtil> or its
Expand Down Expand Up @@ -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 Adding a new command to the F<plumage> command-line tool is described in the
L<Adding a New Command|add-command.pod> document. L<Adding a New Command|add-command.pod> document.
=end pod
27 changes: 0 additions & 27 deletions docs/interactive.pod
View file
@@ -1,5 +1,3 @@
=begin pod
=head1 Using the Plumage Interactive Command-Line Interface =head1 Using the Plumage Interactive Command-Line Interface


In addition to the basic single command interface from the shell, Plumage In addition to the basic single command interface from the shell, Plumage
Expand All @@ -22,22 +20,16 @@ temporarily or permanently.


After you've started Plumage, you will be greeted by the welcome message. After you've started Plumage, you will be greeted by the welcome message.


=begin code
Plumage: Package Manager for Parrot Plumage: Package Manager for Parrot
Copyright (C) 2009-2011, Parrot Foundation. Copyright (C) 2009-2011, Parrot Foundation.


Enter 'help' for help or see docs/interactive.pod for further information. Enter 'help' for help or see docs/interactive.pod for further information.


plumage> plumage>


=end code
As the above message suggests, if you aren't sure of something, use the C<help> As the above message suggests, if you aren't sure of something, use the C<help>
command. command.


=begin code
plumage> help plumage> help
List of commands: List of commands:


Expand Down Expand Up @@ -66,13 +58,9 @@ command.
clean <project> Performs basic cleanup of source tree for <project>. clean <project> Performs basic cleanup of source tree for <project>.
realclean <project> Removes all generated files during the build process 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 Suppose you want to try a new programming language but aren't sure which. Let's
see what's available. see what's available.


=begin code
plumage> projects plumage> projects
Known projects: Known projects:
Close Systems programming language (C-like) for the Parrot VM Close Systems programming language (C-like) for the Parrot VM
Expand All @@ -96,14 +84,10 @@ see what's available.


# Output truncated for brevity # Output truncated for brevity


=end code
As you can see, the C<projects> command lists all the projects in the 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 ecosystem. Maybe you're feeling a little silly and want to write some
LOLCODE. Let's find out a little bit more about LOLCODE. LOLCODE. Let's find out a little bit more about LOLCODE.


=begin code
plumage> info lolcode plumage> info lolcode
Name : lolcode Name : lolcode
Version : HEAD Version : HEAD
Expand All @@ -113,13 +97,9 @@ LOLCODE. Let's find out a little bit more about LOLCODE.
License : Artistic License 2.0 License : Artistic License 2.0
Description : Lolcode Description : Lolcode


=end code
Looks like someone was lazy and didn't fully fill out the LOLCODE metadata Looks like someone was lazy and didn't fully fill out the LOLCODE metadata
file. That's alright, it'll be a surprise! file. That's alright, it'll be a surprise!


=begin code
plumage> install lolcode plumage> install lolcode
/usr/bin/git clone git://github.com/parrot/lolcode.git /home/foo/.parrot/plumage/build/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... Cloning into /home/foo/.parrot/plumage/build/lolcode...
Expand All @@ -131,19 +111,12 @@ file. That's alright, it'll be a surprise!


# Output truncated for brevity # Output truncated for brevity


=end code
This builds, tests, and installs a particular project/module; in this case, 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. 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. Uninstalling a project is done with the aptly named C<uninstall> command.


=begin code
plumage> uninstall lolcode plumage> uninstall lolcode
Uninstalling lolcode ... Uninstalling lolcode ...
/home/foo/bin/bin/parrot setup.pir uninstall /home/foo/bin/bin/parrot setup.pir uninstall
Successful. Successful.


=end code
=end pod

0 comments on commit 12e617a

Please sign in to comment.