Whether learning a programming language, working through a problem, or trying to understand a new library, it may be tempting to flail around crafting just the right search engine query or cry for help on a forum like Stack Overflow. But look at any guide to asking good questions and you’ll find this commandment at the top: do your research. And one of the primary sources of that research is the official documentation for the language or library in question.
Fortunately, Perl and its modules come installed with extensive documentation, also available on the Web. Locally, you can use the perldoc command-line program, or if you have the documentation installed as Linux/Unix man pages (short for manual pages) you can use the standard man command. Because that isn’t always the case and because it has more Perl-specific options, I recommend perldoc.
Note that if you’re using the Perl provided by your operating system distribution you may not have any documentation installed at all without a separate package. For example, Ubuntu Linux calls this package perl-doc; you can install it with this command:
(Splitting Perl across several packages is a common operating system distribution tactic; it’s one of the reasons I recommend installing your own Perl.)
Once you’re sure you have the command available, run the following command to get an introduction to the Perl programming language:
All of the built-in documentation begins with “perl” as above, so you can say perldoc perlrun to find out how to execute Perl, perldoc perlfaq to get a directory of frequently asked questions, or perldoc perltoc for a table of contents listing everything available.
As I mentioned above, the perldoc command has several useful options. You can run perldoc perldoc for a full description, but here are some highlights:
perldoc -ffunction: describe a specific function from perlfunc
perldoc -qregular-expression: search the questions in the various perlfaq documents
perldoc -vvariable-name: describe a specific predefined variable from perlvar
The last argument to perldoc can be a documentation page as described earlier, an installed module, a Perl program name in your path, or the URL to a Perl module or Plain Old Documentation (POD) file.
You may have noticed a number of links above to the perldoc.perl.org website. This is a great friendly resource if you prefer reading in a web browser, and you can use features like bookmarks/favorites and sending hyperlinks to others. It has a search engine and you can even switch between different Perl versions (including development).
In addition to using the perldoc command described earlier to understand locally-installed modules, you can use the MetaCPAN web site’s search engine (in both regular and regular expression flavors) to discover and learn how to save time piecing together programs instead of reinventing the wheel. I always check MetaCPAN first when I need to write some Perl.
Writing your own
Perl has its own markup language called Plain Old Documentation (POD), and you can either interleave it with your own program source code or save it in separate files. The perlpod documentation page has all the details and the perlpodstyle page will guide you in writing in a style consistent with other documentation. And if you need to publish elsewhere, there are translators for HTML, LaTeX, PDF, and other formats on CPAN. You can also provide your documentation to others via a dedicated web application; this is an excellent tool for teams with internal-only (“DarkPAN”) code.
Documentation is like a present you give to both your later self and anybody else that needs to use your work. I highly recommend you spend time writing it in addition to the usual developer-level source code comments. This is especially important if you plan to release open source on CPAN; otherwise, no one will understand what it does or why they should care. I’m incredibly grateful to every developer who has put in the effort.
7 thoughts on “Read The Fantastic Manual: How to get the most out of Perl documentation”
[…] Read The Fantastic Manual: How to get the most out of Perl documentation […]
Step 1: rm ‑rf perl
Step 2: move on with your life.
I was kind of expecting a meme gif of someone throwing the manual in the fire
I still make jokes that “we should write it in Perl” but I thought they were jokes… are folks seriously doing new dev in Perl in 2021?
Even if there are few green-field projects nowadays written in Perl, it remains in wide use to maintain existing codebases. Not everything can be presto-rewritten in $popular_language_du_jour.
Well, use Perl for most of my coding, scientific data analysis — perl code with nextflow, ldap and database manipulations, webstuff — Perl Dancer + js, server orchestration — switched from Ansible to Rex — rexify.org.
Yup
Comments are closed.
{"id":"11","mode":"button","open_style":"in_modal","currency_code":"USD","currency_symbol":"$","currency_type":"decimal","blank_flag_url":"https:\/\/phoenixtrap.com\/wp-content\/plugins\/tip-jar-wp\/\/assets\/images\/flags\/blank.gif","flag_sprite_url":"https:\/\/phoenixtrap.com\/wp-content\/plugins\/tip-jar-wp\/\/assets\/images\/flags\/flags.png","default_amount":500,"top_media_type":"featured_image","featured_image_url":"https:\/\/phoenixtrap.com\/wp-content\/uploads\/2021\/02\/image-200x200.jpg","featured_embed":"","header_media":null,"file_download_attachment_data":null,"recurring_options_enabled":true,"recurring_options":{"never":{"selected":true,"after_output":"One time only"},"weekly":{"selected":false,"after_output":"Every week"},"monthly":{"selected":false,"after_output":"Every month"},"yearly":{"selected":false,"after_output":"Every year"}},"strings":{"current_user_email":"","current_user_name":"","link_text":"Leave a tip!","complete_payment_button_error_text":"Check info and try again","payment_verb":"Pay","payment_request_label":"The Phoenix Trap","form_has_an_error":"Please check and fix the errors above","general_server_error":"Something isn't working right at the moment. Please try again.","form_title":"The Phoenix Trap","form_subtitle":"Do you like what you see? Leave a one-time or recurring tip!","currency_search_text":"Country or Currency here","other_payment_option":"Other payment option","manage_payments_button_text":"Manage your payments","thank_you_message":"Thank you for being a supporter!","payment_confirmation_title":"The Phoenix Trap","receipt_title":"Your Receipt","print_receipt":"Print Receipt","email_receipt":"Email Receipt","email_receipt_sending":"Sending receipt...","email_receipt_success":"Email receipt successfully sent","email_receipt_failed":"Email receipt failed to send. Please try again.","receipt_payee":"Paid to","receipt_statement_descriptor":"This will show up on your statement as","receipt_date":"Date","receipt_transaction_id":"Transaction ID","receipt_transaction_amount":"Amount","refund_payer":"Refund from","login":"Log in to manage your payments","manage_payments":"Manage Payments","transactions_title":"Your Transactions","transaction_title":"Transaction Receipt","transaction_period":"Plan Period","arrangements_title":"Your Plans","arrangement_title":"Manage Plan","arrangement_details":"Plan Details","arrangement_id_title":"Plan ID","arrangement_payment_method_title":"Payment Method","arrangement_amount_title":"Plan Amount","arrangement_renewal_title":"Next renewal date","arrangement_action_cancel":"Cancel Plan","arrangement_action_cant_cancel":"Cancelling is currently not available.","arrangement_action_cancel_double":"Are you sure you'd like to cancel?","arrangement_cancelling":"Cancelling Plan...","arrangement_cancelled":"Plan Cancelled","arrangement_failed_to_cancel":"Failed to cancel plan","back_to_plans":"\u2190 Back to Plans","update_payment_method_verb":"Update","sca_auth_description":"Your have a pending renewal payment which requires authorization.","sca_auth_verb":"Authorize renewal payment","sca_authing_verb":"Authorizing payment","sca_authed_verb":"Payment successfully authorized!","sca_auth_failed":"Unable to authorize! Please try again.","login_button_text":"Log in","login_form_has_an_error":"Please check and fix the errors above","uppercase_search":"Search","lowercase_search":"search","uppercase_page":"Page","lowercase_page":"page","uppercase_items":"Items","lowercase_items":"items","uppercase_per":"Per","lowercase_per":"per","uppercase_of":"Of","lowercase_of":"of","back":"Back to plans","zip_code_placeholder":"Zip\/Postal Code","download_file_button_text":"Download File","input_field_instructions":{"tip_amount":{"placeholder_text":"How much would you like to tip?","initial":{"instruction_type":"normal","instruction_message":"How much would you like to tip? Choose any currency."},"empty":{"instruction_type":"error","instruction_message":"How much would you like to tip? Choose any currency."},"invalid_curency":{"instruction_type":"error","instruction_message":"Please choose a valid currency."}},"recurring":{"placeholder_text":"Recurring","initial":{"instruction_type":"normal","instruction_message":"How often would you like to give this?"},"success":{"instruction_type":"success","instruction_message":"How often would you like to give this?"},"empty":{"instruction_type":"error","instruction_message":"How often would you like to give this?"}},"name":{"placeholder_text":"Name on Credit Card","initial":{"instruction_type":"normal","instruction_message":"What is the name on your credit card?"},"success":{"instruction_type":"success","instruction_message":"Enter the name on your card."},"empty":{"instruction_type":"error","instruction_message":"Please enter the name on your card."}},"privacy_policy":{"terms_title":"Terms and conditions","terms_body":null,"terms_show_text":"View Terms","terms_hide_text":"Hide Terms","initial":{"instruction_type":"normal","instruction_message":"I agree to the terms."},"unchecked":{"instruction_type":"error","instruction_message":"Please agree to the terms."},"checked":{"instruction_type":"success","instruction_message":"I agree to the terms."}},"email":{"placeholder_text":"Your email address","initial":{"instruction_type":"normal","instruction_message":"What is your email address?"},"success":{"instruction_type":"success","instruction_message":"Enter your email address"},"blank":{"instruction_type":"error","instruction_message":"Enter your email address"},"not_an_email_address":{"instruction_type":"error","instruction_message":"Make sure you have entered a valid email address"}},"note_with_tip":{"placeholder_text":"Your note here...","initial":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"empty":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"not_empty_initial":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"saving":{"instruction_type":"normal","instruction_message":"Saving note..."},"success":{"instruction_type":"success","instruction_message":"Note successfully saved!"},"error":{"instruction_type":"error","instruction_message":"Unable to save note note at this time. Please try again."}},"email_for_login_code":{"placeholder_text":"Your email address","initial":{"instruction_type":"normal","instruction_message":"Enter your email to log in."},"success":{"instruction_type":"success","instruction_message":"Enter your email to log in."},"blank":{"instruction_type":"error","instruction_message":"Enter your email to log in."},"empty":{"instruction_type":"error","instruction_message":"Enter your email to log in."}},"login_code":{"initial":{"instruction_type":"normal","instruction_message":"Check your email and enter the login code."},"success":{"instruction_type":"success","instruction_message":"Check your email and enter the login code."},"blank":{"instruction_type":"error","instruction_message":"Check your email and enter the login code."},"empty":{"instruction_type":"error","instruction_message":"Check your email and enter the login code."}},"stripe_all_in_one":{"initial":{"instruction_type":"normal","instruction_message":"Enter your credit card details here."},"empty":{"instruction_type":"error","instruction_message":"Enter your credit card details here."},"success":{"instruction_type":"normal","instruction_message":"Enter your credit card details here."},"invalid_number":{"instruction_type":"error","instruction_message":"The card number is not a valid credit card number."},"invalid_expiry_month":{"instruction_type":"error","instruction_message":"The card's expiration month is invalid."},"invalid_expiry_year":{"instruction_type":"error","instruction_message":"The card's expiration year is invalid."},"invalid_cvc":{"instruction_type":"error","instruction_message":"The card's security code is invalid."},"incorrect_number":{"instruction_type":"error","instruction_message":"The card number is incorrect."},"incomplete_number":{"instruction_type":"error","instruction_message":"The card number is incomplete."},"incomplete_cvc":{"instruction_type":"error","instruction_message":"The card's security code is incomplete."},"incomplete_expiry":{"instruction_type":"error","instruction_message":"The card's expiration date is incomplete."},"incomplete_zip":{"instruction_type":"error","instruction_message":"The card's zip code is incomplete."},"expired_card":{"instruction_type":"error","instruction_message":"The card has expired."},"incorrect_cvc":{"instruction_type":"error","instruction_message":"The card's security code is incorrect."},"incorrect_zip":{"instruction_type":"error","instruction_message":"The card's zip code failed validation."},"invalid_expiry_year_past":{"instruction_type":"error","instruction_message":"The card's expiration year is in the past"},"card_declined":{"instruction_type":"error","instruction_message":"The card was declined."},"missing":{"instruction_type":"error","instruction_message":"There is no card on a customer that is being charged."},"processing_error":{"instruction_type":"error","instruction_message":"An error occurred while processing the card."},"invalid_request_error":{"instruction_type":"error","instruction_message":"Unable to process this payment, please try again or use alternative method."},"invalid_sofort_country":{"instruction_type":"error","instruction_message":"The billing country is not accepted by SOFORT. Please try another country."}}}},"fetched_oembed_html":false}
[…] Read The Fantastic Manual: How to get the most out of Perl documentation […]
Step 1: rm ‑rf perl
Step 2: move on with your life.
I was kind of expecting a meme gif of someone throwing the manual in the fire
I still make jokes that “we should write it in Perl” but I thought they were jokes… are folks seriously doing new dev in Perl in 2021?
Even if there are few green-field projects nowadays written in Perl, it remains in wide use to maintain existing codebases. Not everything can be presto-rewritten in $popular_language_du_jour.
Well, use Perl for most of my coding, scientific data analysis — perl code with nextflow, ldap and database manipulations, webstuff — Perl Dancer + js, server orchestration — switched from Ansible to Rex — rexify.org.
Yup