GSoC/GCI Archive
GSoC/GCI Archive
Google Code-in 2011 Parrot Foundation

Add POD/manpage docs for parrotbug

completed by: Aleksandar

mentors: Andrew Whitworth

Task Description

To be a good member of the Unix ecosystem, installed binary programs should have an associated man page for documentation. This is the first thing most users look for when they need help or have a problem, so Parrot should be providing these files for all installed binaries.

Parrot uses the pod2man utility to create manpages from POD formatted documentation files. Every installed binary program should include a related POD file in the /docs/binaries/ directory (create this directory yourself, if needed).

For this task create a documentation file /docs/binaries/parrotbug.pod for the installed binary parrotbug. Follow existing examples in that directory, if any, or if there is a example_format file follow that instead. If neither are available, do your best to follow POD formatting examples from other files in the docs/ directory.

Documentation should include information about what the binary program is (it's a part of Parrot, etc) what it does, what are the command-line arguments, what are the expected results, and where to turn to if you need more help (http://parrot.org, http://github.com/parrot/parrot, parrot-dev@parrot.org, etc)

Steps To Complete This Task

  1. Create a fork of parrot.git on github.com
  2. Examine the utility in question. You may need to build Parrot first before all utilities are created.
  3. Add in the new documentation, following existing formatting examples as best as possible, and including as much information as you can add. Ask for help or clarification if necessary.
  4. Create a Github pull request (button on the upper right of your fork) to have your changes incorporated into the master repository

Benefits

  1. The availability of manpages for all installed binary programs is a requirement for some distribution packaging systems, and a basic courtesy for others. Having even basic documentation available for these utilities will help Parrot be used and accepted on these platforms.

Requirements

  1. Ability to read and understand code to figure out what is going on.
  2. Familiarity with POD formatting (or similar formatting and the ability to learn POD)

Additional Links