Improve documentation for file_munge_filename()

Me neither, but I'll see what I can find out.

dww describes the reason #693084-73: Regression: file_munge_filename() extension handling broken by move to File Field which I am copying and pasting here for ease of use:

If Apache doesn't recognize the file type it'll skip the extension and keep moving on until it finds one it recognizes. If filename is filename.php.pps and Apache doesn't recognize pps then it'll execute the file as a PHP file resulting in a possible hacked server. My understanding is that file munging is done to protect such a scenario.

This answers #2 in the Description.

And it answers #1 as well. That seems like a good thing to add to the doc.

It also answers #3: anything Apache recognizes should be added to $extensions.

Good thing to add to the doc...

Here's a patch for the doc for file_munge_filename(), which incorporates the information from #2 to answer the questions posed in this issue report. Hopefully.

This information is excellent and answers the questions to the degree they need answering. #3 isn't explicitly answered, but I think that's OK in this context.

The voice is somewhat passive, I suggest changing to active form:

Munging a file name prevents unknown file extensions from masking
exploit files. When web servers such as Apache
decide how to process a URL request, they use the file extension. If
the extension is not recognized, Apache skips that extension and uses
the previous file extension. For example, if the file being requested
is exploit.php.pps, and Apache does not recognize the '.pps' extension, it
treats the file as PHP and executes it. To make this file name safe for
Apache and prevent it from executing as PHP, the .php extension is "munged"
into .php_, making the safe file name exploit.php_.pps.

Specifically, this function adds an underscore to all extensions that are between 2 and 5
characters in length, internal to the file name, and not included in
$extensions. If variable 'allow_insecure_uploads' evaluates to TRUE, no
alterations will be made.

Last line seems like it's just tacked on, and it's important. Maybe:

Specifically, this function adds an underscore to all extensions that are between 2 and 5
characters in length, internal to the file name, and not included in
$extensions.

Function behavior is controlled by the variable 'allow_insecure_uploads'. If 'allow_insecure_uploads' evaluates to TRUE, no
alterations will be made, if it evaluates to FALSE, the filename is 'munged'.

So make a new patch?

Sorry for being wishy-washy. It could go in as-is, but I think would be even better in a more active voice. So I guess that's a yes?

Please make a new patch. Active voice is better.

New patch with active voice per #5/#8

Looks good, thanks!

Committed to CVS HEAD. Thanks.

We should probably port this to D6 as well.

Done!

Looks good to me. Thanks!

Committed, thanks.