mod_perl2 User's Guide
By Stas Bekman, Jim Brandt
By Stas Bekman, Eric Cholet
Ninety percent of the questions asked on the List have already been asked before, and answers will be found at one of the links below. Before you post to the mod_perl List, please read the following. Hopefully it will save you (and everyone else) some time.
Except where noted the language of all documents is English.
You need to know about Apache, CGI and of course about Perl itself. This document explains where to find more information about these and related topics.
If you already have Perl on your machine then it's likely that you already have all the Perl documentation. Try typing `perldoc perldoc' and `man perl'.
Read the documents which came with mod_perl, particularly the ones named INSTALL, README and SUPPORT. Also read the documents to which they refer. Read all the relevant documentation about your operating system, any tools you use such as compilers and databases, and about the Apache Web server.
You will get a much better response from the mod_perl List if you can show that you have made the effort of reading the documentation.
There are dozens of references to many authoritative resources in the Offsite Resources section.
There are two stages to getting on the list. Firstly you have to send a mail message to: email@example.com and wait for receiving a response from the mail server with instructions to proceed.
Secondly you have to do what it says in the instructions. After you are subscribed you will receive a messsage with lots of useful information about the List. Read it. Print it, even. Save a copy of it. You can get another copy of it, but then you'll feel silly.
Traffic on the mod_perl list can be high at times, several hundred posts per week, so you might want to consider subscribing to the mod_perl digest list as an alternative to the mod_perl list. To do so, send an email to firstname.lastname@example.org instead.
Instructions on how to unsubscribe are posted in the headers of every message which you receive from the List. All you have to do is send a message to: email@example.com (or firstname.lastname@example.org if you are on the digest list)
To prevent malicious individuals from unsubscribing other people, the mailing list software insists that the message requesting that an email address be unsubscribed comes from that same address. If your email address has changed you can still unsubscribe, but you will need to read the help document, which can be recieved by sending an empty email to: email@example.com
Posting to the list is just sending a message to the address which you will be given after you subscribe.
To keep the list safe from spam, any message posted from an unsubscribed email address is sent to a moderator for manual approval.
Do not post to firstname.lastname@example.org, except to subscribe to the list! Please do not post to the list itself to attempt to unsubscribe from it.
Please do not send private mail to list members unless it is invited. Even if they have answered your question on the list, you should continue the discussion on the list.
On the other hand, if someone replies to you personally, you shouldn't forward the reply to the list unless you have received permission from this person.
Don't forget that the people reading the list have no idea even what operating system your computer runs unless you tell them. When reporting problems include at least the information requested in the document entitled SUPPORT which you will find in the mod_perl source distribution.
You can find many excellent examples of posts with good supporting information by looking at the mod_perl mailing list archives. There are URLs for several archives (with several different search engines) on the mod_perl home page. Followup posts will show you how easy the writer made it for the person who replied to deduce the problem and to suggest a way of solving it, or to find some further item information.
If after reading the SUPPORT document you think that more information is needed for your particular problem, but you still don't know what information to give, ask on the list rather than sending long scripts and configuration files which few people will have the time to read.
If you include error messages in your post, make sure that they are EXACTLY the messages which you saw. Use a text editor to transfer them directly into your message if you can. Try not to say things like "the computer said something about not recognizing a command" but instead to say something like this:
"When logged in as root I typed the command:
at the console and on the console I saw the message
Syntax error on line 393 of /etc/httpd/conf/httpd.conf: Invalid command 'PerlHandler', perhaps mis-spelled or defined by a module not included in the server configuration [FAILED]"
The Subject: line is very important. Choose an informative Subject line for the mail header. Busy list members will skip messages with unclear Subject lines.
Messages which all have the same Subject line text (possibly preceded by the word "Re:" which is automatically added by your mailer) are together known as a "thread". List members and mail archive use mail unique-ids and/or the Subject line to sort mail. Do not change the text without a very good reason, because this may break the thread. Breaking the thread makes it difficult to follow the discussion and can be very confusing. It may be better to start a new thread than to continue an old one if you change the theme.
Do not post in HTML. Microsoft users in particular should take careful note of this. Use either the US-ASCII or ISO-8859-1 (Latin-1) character set, do not use other character sets which may be designed for those who do not speak English and which may not be displayable on many terminals. If you ignore this advice then the chances are greater that your message will not be read.
Remember that thousands of people may read your messages. To save time and to keep badwidth usage to a minimum, please keep posts reasonably short, but please make it clear precisely what you are asking. If you can, send a small example of a script or configuration which reproduces your problem. Please do not send long scripts which cannot easily be understood. Please do not send large attachments of many kilobytes, if they are needed then put them on the Web somewhere or say in your message that you can send them separately if they are requested.
It can be helpful if you use a
[tag] in square brackets in the
Subject: line, as well as the brief description of your post.
Some suggested tags are:
ADMIN Stuff about running the List. ADVOCACY Promoting the use of mod_perl, printing T-shirts, stuff like that. Please don't start another discussion about whether we should put this on a different list, we've been there before. ANNOUNCE Announcements of new software tools, packages and updates. BENCHMARK Apache/mod_perl performance issues. BUG Report of possible fault in mod_perl or associated software - it's better if you can send a patch instead! DBI Stuff generally concerning Apache/mod_perl interaction with databases. FYI For information only. JOB Any post about mod_perl jobs is welcome as long as it is brief and to the point. Note: Not "JOBS". MASON Jonathan Swartz' implementation of Perl embedded in HTML. NEWS Items of news likely to be interesting to mod_perlers. OT Off-topic items, please try to keep traffic low. PATCH Suggested fix for fault in mod_perl or associated software. QUESTION Questions about mod_perl which is not covered by one of the more specific headings. RareModules Occasional reminders about little-used modules on CPAN. RFC Requests for comment from the mod_perl community. SITE Things about running the Apache/mod_perl servers. SUMMARY After investigation and perhaps fixing a fault, and after an extended discussion of a specific topic, it is helpful if someone summarizes the thread. Don't be shy, everyone will appreciate the effort. mod_perl2 As currently both versions of mod_perl are beeing supported or on the same list, adding a tag to specifiy which version you mp2 are talking about might be a good idea.
If you can't find a tag which fits your subject, don't worry. If you
have a very specific subject to discuss, feel free to choose your own
tag, for example
[Perl Sections] but remember
that the main reasons for the Subject line are to save people time
and to improve the response to your posts. It does not matter whether
[UPPER CASE] or
[lower case] or even a
Both] in the tag. Try to keep the tag short. The tag should be the
first thing in the Subject line.
Sometimes you will not get a reply. Try to be patient, but it is OK to try again after a few days. Sometimes the replies you get will be very short. Please do not worry about that. People are very busy, that's all.
Of course if your post is
[OT] for the list then you may not get a
reply, or you may get one telling you to try a different forum.
Just say so.
The mod_perl list is NOT for general questions about Apache and the Perl language. The majority view is tolerant of off-topic posts, but it is considered impolite to post general Perl and Apache questions on the mod_perl list. The best you can hope for is a private reply and a polite reminder that the question is off-topic for this list. If you catch someone on a bad day, you might not get the best. There are often bad days in software development departments...
If the Perl and Apache documentation has not answered your question then you could try looking at http://lists.perl.org/ or one of the comp.lang.* newsgroups. From time to time there are efforts to start a dedicated Perl mailing list and these usually result in a message or two on the mod_perl list, so it might be worth your while to search the archives.
Please note that there are now separate mailing lists for ASP, EmbPerl and Mason, but although we keep trying to get a separate list off the ground for Advocacy it always seems to end up back on the mod_perl list.
Make sure that you include the exact Subject: from the original post, unmodified. This makes it much easier for people (and for the mail software) to deal with the mail. If you must change the subject line then please append the words "was originally" plus the original subject line to your new subject line so that folks can see what is going on.
When replying to a post, please include short excerpts from the post to which you are replying so that others can follow the conversation without having to wade through reams of superfluous text. If you are lazy about this then messages can get very long indeed and can become a burden to the other people who might be trying to help. Make sure that there is a clear distinction between the text(s) of the message(s) to which you are replying and your reply itself.
Please do not quote the original message you reply to at the bottom of the email, as we already have the original message in the mail list archives. Either quote only the relevant parts you reply to, if you reply under those quotes, or don't quote at all if you can't be bothered to maintain context.
If you know that the intended recipients are subscribed to the List, there is no need to send messages both to them and to the list. They will get more than one copy of the message which is wasteful.
It is helpful to keep most of your replies on the list, so that others see that help is being given and so they do not waste time on problems which have already been solved. Where it is appropriate to take a discussion off the list (for example where it veers off-topic, as often happens), say so in a message so that everyone is aware of it.
The readers of the mod_perl List aren't interested in that kind of thing. Don't get involved.
You absolutely must read the mod_perl documentation.
There are many documents, but they are worth reading, as they might
solve your problems and teach you better coding. Each document also
[PDF] link so that you can print it. If you want to download
the documentation locally, see the Documentation download section. You can then build the whole site
Contributions are very welcome, see the same page for details on how to submit patches.
"How To Ask Questions The Smart Way" by Eric Steven Raymond and Rick Moen: http://www.catb.org/~esr/faqs/smart-questions.html