Paypal module passes STORE_NAME instead of item

The PayPal payment module (paypal.php,v 1.39 2003/01/29) for OSCommerce does not pass a meaningful item description to Paypal as a transaction is processed. Instead, the developer of this module programmed it to send the name of your store instead:

tep_draw_hidden_field('item_name', STORE_NAME) .

The result is that when the transaction completes, Paypal sends the store owner an email notification, unhelpfully describing the item purchased as "[name of your store]".

We will fix this by changing the code in the payment module to send a better description for that field. While we're at it, we'll change the code to better support stores selling multiple items in one transaction because this Paypal module comes "out of the box" designed more for single item purchase. When multiple items are purchased, this module just gives an aggregate description of the whole transaction, without any detail of what exatly was purchased.

To fix both of these problems, use the patch file below, or edit (path to your store)/includes/modules/payment/paypal.php and jump down to this function:

function process_button() {

find the line that looks like:

$process_button_string = tep_draw_hidden_field

and insert a comment marker right before it:

/*
$process_button_string = tep_draw_hidden_field

and then go down a few more lines from there until you get to the one that has a semicolon at the end, instead of a period. After that line, insert an ending comment marker:

*/

Now, after your ending comment marker (commenting out the original code makes it not operate anymore, while preserving it for reference), insert the following:

 # Multiple item payment, P. 86 of 
 # https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf

$process_button_string = tep_draw_hidden_field('cmd', '_cart') .
      tep_draw_hidden_field('upload', '1') .
      tep_draw_hidden_field('business', MODULE_PAYMENT_PAYPAL_ID) .
      tep_draw_hidden_field('handling_cart', number_format($order->info['shipping_cost'] * $currencies->get_value($my_currency), $currencies->get_decimal_places($my_currency))) .
      tep_draw_hidden_field('currency_code', $my_currency) .
      tep_draw_hidden_field('custom', $order->info['comments']) .
      tep_draw_hidden_field('return', tep_href_link(FILENAME_CHECKOUT_PROCESS, '', 'SSL')) .
      tep_draw_hidden_field('cancel_return', tep_href_link(FILENAME_CHECKOUT_PAYMENT, '', 'SSL'));

 # add individual items and amounts to keep in PP transaction history and notices

 $i=0;
 foreach($order->products as $key => $arr)
 {
     $i++;
     $process_button_string .= tep_draw_hidden_field("item_name_$i",  $arr["qty"] ." ". $arr["name"]) .
                               tep_draw_hidden_field("amount_$i", $arr["qty"] * $arr["final_price"]);

 } 

Save the file, and now every payment transaction from your OS-Commerce store that is processed with this payment module will send Paypal the item name and price of each item your customer is purchasing. The "handling_cart" field adds a single shipping fee to the entire order. If you want to charge shipping amount per item, see the manual mentioned in the code comment above and use multiple "shipping_X" fields inside the foreach loop instead.

Once you make this change, the email notices that Paypal sends to the shop owner after each purchase will contain a detailed list of what was bought. Both the customer and the merchant will also have detailed records of the itemized list stored in the Paypal transaction history. This is much better than just one aggregate item with a total price and no Paypal record of what the order consisted of.

Using my patch file to make the above change.
You can skip a whole lot of manual editting if you download the patchfile included below, save it as paypal.patch in the same directory as the original paypal.php file, and then run the following shell command:

patch -b paypal.php < paypal.patch

The -b option will make a backup copy of the original file, just in case.

Click to show patch

Hide Patch

--- orig.php    Wed Sep 20 22:49:53 2006
+++ paypal.php  Wed Sep 20 23:05:07 2006
@@ -83,6 +83,8 @@
       if (!in_array($my_currency, array('CAD', 'EUR', 'GBP', 'JPY', 'USD'))) {
         $my_currency = 'USD';
       }
+
+/*
       $process_button_string = tep_draw_hidden_field('cmd', '_xclick') .
                                tep_draw_hidden_field('business', MODULE_PAYMENT_PAYPAL_ID) .
                                tep_draw_hidden_field('item_name', STORE_NAME) .
@@ -91,6 +93,30 @@
                                tep_draw_hidden_field('currency_code', $my_currency) .
                                tep_draw_hidden_field('return', tep_href_link(FILENAME_CHECKOUT_PROCESS, '', 'SSL')) .
                                tep_draw_hidden_field('cancel_return', tep_href_link(FILENAME_CHECKOUT_PAYMENT, '', 'SSL'));
+*/
+
+# Multiple item payment, P. 86 of
+# https://www.paypal.com/en_US/pdf/PP_WebsitePaymentsStandard_IntegrationGuide.pdf
+
+$process_button_string = tep_draw_hidden_field('cmd', '_cart') .
+                         tep_draw_hidden_field('upload', '1') .
+                         tep_draw_hidden_field('business', MODULE_PAYMENT_PAYPAL_ID) .
+                         tep_draw_hidden_field('handling_cart', number_format($order->info['shipping_cost'] * $currencies->get_value($my_currency),
+                                               $currencies->get_decimal_places($my_currency))) .
+                         tep_draw_hidden_field('currency_code', $my_currency) .
+                         tep_draw_hidden_field('custom', $order->info['comments']) .
+                         tep_draw_hidden_field('return', tep_href_link(FILENAME_CHECKOUT_PROCESS, '', 'SSL')) .
+                         tep_draw_hidden_field('cancel_return', tep_href_link(FILENAME_CHECKOUT_PAYMENT, '', 'SSL'));
+
+# add individual items and amounts to keep in PP transaction history and notices
+
+$i=0;
+foreach($order->products as $key => $arr)
+{
+    $i++;
+    $process_button_string .= tep_draw_hidden_field("item_name_$i", $arr["qty"] ." ". $arr["name"]) .
+                              tep_draw_hidden_field("amount_$i", $arr["qty"] * $arr["final_price"]);
+}

       return $process_button_string;
     } 

Getting your rental deposit back

My friend gets jammed up a lot. In July it was over his deposit on a residential rental that he shared with some roommates. The landlord stopped by two days before their lease expired to express some very demanding expectations about how her crummy little shack should be returned, otherwise it was coming out of their deposit.

Landlord's list of intended charges included:

• the brown, unwatered sections of lawn
• replacing dead landscaping bushes
• edging and weeding
• professional carpet cleaning in a damp sub-basement!
• scrubbing stains out of 60 year old grout with particular cleaning products
• replacing a stolen freezer

My friend knew this list was going to mean a large chunk of their $1,000 security deposit would be missing when they got it back. The landlord even hired a lawn psychiatrist to come over and pad the bill with exotic plant examinations. So I was asked to be there as a mouthpiece when the landlord returned to check on cleaning progress.

I did, and let her know (in the most helpful and innocent manner) that she really couldn't deduct a thing from the deposit because 1) the property is in the same condition now as it was when she rented it to them, and 2) she never did a written "check-in" sheet documenting the original condition, and without it, the law is not on her side for making deductions from the deposit.

We went back and forth, her pointing out some alleged damage, my saying it was like that when they moved in, her saying it wasn't, and my asking then for the move-in condition of that item on the non-existent "check-in" sheet.

After some tense moments, she left. Then I went to the library to write a pre-emptive letter for my friend to get the landlord to see why I was right and she would have to give back the whole deposit. It's included below, and you may copy it freely for personal use in saving your own security deposit from greedy slumlords.

Click to show 1st letter

Close 1st letter

July 31, 2006

Dear Landlord,

We are surrendering the premises to you at the expiration of our 1 year lease on July 31, 2006. Our forwarding addresses, for the purpose of returning all of our $1000.00 security deposit, and for any other notices are:

[Tenant #1 name, address]
[Tenant #2 name, address]

We would also like to put you on notice that you are not entitled to withhold any amount from our security deposit because as a lessor of residential rental property, and as a lawyer yourself, you have failed to comply with the following law of the State of Montana:

70-25-206. Landlord to furnish statement of condition of premises at beginning of lease. (1) Any person engaged in the rental of property for residential purposes who requires a security deposit shall furnish to each tenant, in conjunction with execution of a lease or creation of a tenancy, a separate written statement as to the present condition of the premises intended to be let. At the written request of the tenant, a copy of the written list of damage and cleaning charges, if any, provided to the tenant of the immediately preceding leasehold agreement for the premises in question must be provided to the tenant.
      (2) Each written statement of the present condition of a premises intended to be let shall contain at least the following:
      (a) a clear and concise statement of the present condition of the premises known to the landlord or the landlord's agent or which should have been known upon reasonable inspection;
      (b) if the premises have never previously been let, a statement indicating the fact; and
      (c) the signature of the landlord or the landlord's agent.

(emphasis added).

In Montana, when a landlord fails to provide the written statement of condition as required by law, as you have, then that landlord is barred from retaining any portion of the security deposit for cleaning or damages.

70-25-206. (3) A person engaged in the rental of property for residential purposes who fails to furnish a tenant, in conjunction with the execution of the lease or creation of the tenancy, with a separate written statement of the present condition of the premises intended to be let and, upon the written request of the tenant, a written list of damage and cleaning charges provided to the tenant of the immediately preceding leasehold agreement is barred from recovering any sum for damage to or cleaning of the leasehold premises unless the person can establish by clear and convincing evidence that the damage occurred during the tenancy in question and was caused by the tenant occupying the leasehold premises or the tenant's family, licensees, or invitees.

(emphasis added).

With regard to cleaning as we return the premises, we have restored the property to the exact condition that it was in when it was rented to us. If you still think it is not sufficiently clean, we will clean it further, even though we are not required to, and even though, by law, you cannot deduct any amount from our deposit for additional cleaning.

With regard to the grounds, we did maintain the curtilage in a reasonable manner. Because you did not provide us with the required statement of condition of the premises at the beginning of the lease, you cannot deduct any amount from our deposit for any shrubs, grass, or weeds. The yard is in the exact condition now that it was when you rented it to us, excepting only some backyard grass which has dried out from the 100 degree temperatures that occurred last week, which were not caused by us and also affected most of the neighbors in the area without tree cover. The grass will become green again soon with normal routine watering.

Any shrubs which you allege are in worse condition now than at the beginning of the lease were damaged by the cold weather during winter, which was also not our fault. As for any oral instructions or arrangements that you contend were made, our only obligations as tenants arise solely from the written lease and from applicable statutes, neither of which can be modified by any earlier or later oral agreements. Furthermore, the lease does not specify that tenants are responsible for caring for “special needs” plants or shrubs, nor does it spell out any particular methods for taking care of the grounds. Without such a special obligation in the lease, the reasonable care that we have taken of the grounds, keeping it in the same condition as that of the surrounding neighbors, is legally sufficient.

In our last conversation, you also mentioned an intent to charge against our security deposit for carpet cleaning in the basement when there was no specific damage, spots or stains to the carpet. Carpet cleaning under such conditions is merely normal maintenance and is specifically prohibited by statute.

70-25-201. (3) Cleaning charges may not be imposed for normal maintenance performed on a cyclical basis by the landlord as noted by the landlord at the time that the tenant occupies the space unless the landlord is forced to perform this maintenance because of negligence of the tenant.

(emphasis added).

Because you are not legally entitled to retain any portion of our deposit, and because we have been good, cooperative tenants for the entire lease period, you should consider this a learning experience and make sure that when renting to future tenants, you protect your and your tenants’ rights by complying with all laws applicable to landlords of residential property. Things really can go very smoothly when everyone is obeying the law.

In the case that you do withhold any of our security deposit, in violation of Montana law, we will immediately file a lawsuit claiming all wrongfully withheld amounts, plus court costs and attorneys fees, which are permitted by the Montana Residential Landlord Tenant Act.

70-24-442. Attorney fees -- costs. (1) In an action on a rental agreement or arising under this chapter, reasonable attorney fees, together with costs and necessary disbursements, may be awarded to the prevailing party notwithstanding an agreement to the contrary.

(emphasis added). Our attorney charges $140.00 per hour.

We hope that it will not come to that and that we will be treated fairly and in compliance with Montana law.

Sincerely,

Close 1st letter

[Tenant #1]

[Tenant #2]

A couple of weeks later, my friend received a refund from the landlord minus just one deduction, $149 for the landlord's freezer that was stolen from the garage earlier in the year. I'm certain that without my first letter laying out the legal analysis, there would have been many more deductions.

That last $149 still bothered him because he believes the thief was the landlord's son, or someone to whom the landlord gave keys, and because they also stole gear from his truck the same night. So it was up to me to secure return of that last amount, and I had reserved some of my ammo for just such an occasion.

Here is my second letter to the landlord, wherein I prove that white is black, and black is white, according as I am paid. You may freely copy it for personal use in recovering your own security deposit.

Click to show 2nd letter

Close 2nd letter

August 23, 2006

RE: Benton St. security deposit withheld for freezer
Dear Landlord,

This letter is in regard to your itemized statement of withholding $149 from my security deposit for the Benton street rental under a lease which terminated on July 31, 2006.

Your stated reason for the deduction was a damage charge for the freezer that had been stolen from the garage. However, you are not legally entitled to withhold that amount for that reason, and must now return the remainder of the deposit, for several reasons.

A freezer stolen by uninvited trespassers from a locked garage does not constitute "damage" for which a tenant is liable and for which a landlord may withhold any portion of the security deposit. Montana law states this explicitly in the definition of "damage" as it relates to security deposits:

70-25-101. Definitions.
... (2) "Damage" means any and all tangible loss, injury, or deterioration of a leasehold premises caused by the willful or accidental acts of the tenant occupying same or by the tenant's family, licensees, or invitees, as well as any and all tangible loss, injury, or deterioration resulting from the tenant's omissions or failure to perform any duty imposed upon the tenant by law with respect to the leasehold.

Because the loss of the freezer from a locked garage was not damage caused by any of us, our families, invitees, or licensees, but instead by uninvited criminal trespassers, this is not the type of loss for which tenants are responsible and for which a landlord may deduct as "damage" from a rental security deposit.

Deductions from security deposits can only be made for reasons explicitly enumerated in the statutes (cleaning and statutorily defined damage) concerning security deposits and for no other reasons. Because this freezer line item qualifies as neither cleaning, nor damage, the $149.00 that you have withheld from our deposit is wrongfully withheld according to Montana law:

70-25-204. Wrongful withholding of security deposit -- action. (1) A person who wrongfully withholds a residential property security deposit or any portion of the deposit is liable in damages to the tenant in a civil action for an amount equal to the sum determined to have been wrongfully withheld or deducted. The attorney fees may be awarded the prevailing party at the discretion of the court. The burden of proof of damages caused by the tenant to the leasehold premises is on the landlord.

The above statute permits our filing an action for the wrongfully withheld amount of $149, plus attorney fees for filing the action.

Technically, the theft of the freezer by trespassers is a casualty. In case of serious casualty, the law provides that the tenant does not pay for casualty damage, but that the landlord reduces the rent in proportion to the diminution in value after the casualty:

70-24-409. Fire or casualty damage -- rights of tenant. (1) If the dwelling unit or premises are damaged or destroyed by fire or casualty to an extent that enjoyment of the dwelling unit is substantially impaired, the tenant may:
...
(b) if continued occupancy is lawful, vacate any part of the dwelling unit rendered unusable by the fire or casualty, in which case the tenant's liability for rent is reduced in proportion to the diminution in the fair rental value of the dwelling unit.

Although we did not need to vacate any portion of the premises after the theft of our freezer, this law shows that tenants are not charged for casualty damages not caused by the tenant, and that the landlord or the landlord's insurance company is instead responsible for this type of casualty damage.

An additional reason why you are not entitled to withhold this amount, even without application of the legal definition of "damage," as it is used in the context of residential rental security deposits is because of another Montana statute:

70-24-401. The aggrieved party has a duty to mitigate damages.

In this case, you have not mitigated your damages before making deductions from our security deposit. Before we surrendered the premises, we provided you with a replacement freezer in good working order, with similar capacity to the one that was stolen. During the last two days of our tenancy, you entered the property and told me in person that you wanted that new freezer removed from the premises. Not wanting you to charge us for handling abandoned property, we complied with your request to remove the replacement freezer from the premises.

Because it was your own request that the replacement freezer, provided at no cost to you, be removed from the premises, you are now estopped from charging our deposit for another freezer. By ordering us to remove the replacement freezer, you created the extra expense of securing yet another freezer, violating your legal duty to mitigate damages. Because you failed to mitigate damages by accepting the working freezer that we provided, you are not entitled to deduct any amount from our deposit for replacing it again later.

By law, I may not file an action to recover the wrongfully withheld security deposit until after September 1st.

70-25-204(2) An action may not be maintained by a tenant for any amount wrongfully withheld or deducted prior to: ...
(b) the expiration of a 30-day period after the termination of a tenancy;

However, if you return the wrongfully withheld amount of $149.00 prior to September 9th, I will not file my planned lawsuit against you. Otherwise, if I have not received our $149.00 by September 9th, then I will file an action against you in Missoula County on Monday, September 11th to recover that amount, plus attorney fees and court costs as permitted by MCA 70-24-442.

In the case that I must file suit, I will add another count to the complaint that will entitle us to additional damages in the amount of up to 3 times the monthly rental amount. This last count will allege your inclusion of provisions in our rental agreement which are prohibited by law.

The prohibited items that you included in our rental agreement dated July 29, 2005 were paragraph 11, which states:

"I will not remove any furniture, fixtures or personal property until all rent and charges are fully paid and grant the owner a lien on the same."

The other provision that you require your tenants to agree to, despite being legally prohibited, is paragraph 2, which is explicitly contrary to Montana law on the subject of security deposits, breach, and mitigation of damages:

"I agree to place a security deposit of $1,000.00, to be forfeited as liquidated damages in the event of any default or breach of any part of this agreement."

The above provisions are patently illegal and unenforceable. Landlords are not entitled to file liens against tenants' personal property as a function of tenancy, and the law of security deposits in Montana forbids landlords from keeping arbitrary amounts of a security deposit.

70-24-202. Prohibited provisions in rental agreements. A rental agreement may not provide that a party:
      (1) agrees to waive or forego rights or remedies under this chapter;

Since you are also an attorney, it should be clear to you that both of those illegal lease lease provisions require tenants to forego rights guaranteed to them under the Montana Residential Landlord Tenant Act. For this, Montana law also provides tenants a statutory remedy, even without a showing of actual damage arising from those illegal provisions:

70-24-403. Prohibited provision in rental agreement -- unenforceability -- damages. (1) A provision prohibited by 70-24-202 included in a rental agreement is unenforceable.
      (2) If a party purposefully uses a rental agreement containing provisions known by him to be prohibited, the other party may recover, in addition to his actual damages, an amount up to 3 months' periodic rent.

So, in the case that I must file a suit to recover our actual damages of $149, I will also claim the above statutory damages totaling $2,850 ($950/month rent * 3 months), plus recoverable court costs and attorneys fees as permitted by statute.

It would be to your advantage, however, to resolve this prior to September 11th, by remitting the wrongfully withheld $149.00.

Sincerely,

Close 2nd letter

[Tenant]

(I should also metion that between these two letters, I laid a small trap for the landlord should she have made any deductions for cleaning. Montana law states that before any cleaning charges can be deducted from a deposit, the landlord must give the tenant 24 hours to perform that cleaning himself, in order to avoid charges. I knew that she had already promised the house to another tenant on the same day my friend's lease was to expire, and that even if she knew about that statute, she would not have wanted to go through the inconvenience of following it. If she didn't follow it, then any charges for cleaning would have been easy to recover in court, plus additional damages for intentionaly disobeying the law. In any case, this landlord never made a deduction for cleaning charges.)

The day before my deadline given in the second letter, my friend received this from the landlord, along with a check for $149.00.

I am in receipt of your letter dated August 23, 2006 stating that the freezer was taken from a locked garage, yet you stated to me last fall that the garage door was not locked and that you did not report the freezer theft to the police. Therefore, the freezer theft was due to your failure to lock the garage, and amounts to damage. The refrigerator you offered to leave behind did not include a freezer with similar capacity to the lost freezer. A judge with common sense would agree that you are responsible for the replacement freezer cost. Be that as it may, it is not worth my time to further address this matter, and am enclosing a check for $149.00, the cost of the freezer which was withheld from the deposit.

It's clear from her letter that the landlord still thinks she's right about the freezer, but probably sees that she is wrong about everything else and therefore won't take her chances in court.

Granted, my friend should not have told the landlord that he left the garage wide open, and I wish my friends would consult me by cellphone before making damaging public statements. However, even allowing that he might have left the door open, we would need to debate whether that consituted any comparative negligence in a quiet Missoula neighborhood, and even if it did, my friend's omission was not the proximate cause of the freezer being stolen. The superceding and intervening cause of it's loss was solely the intentional act of an uninvited trespasser. Such a criminal act would break any chain of causation caused by acts or omissions of my client, and render my client not legally responsible for the loss.

An uninvited trespasser could have just as easily set the whole garage on fire, and by the same reasoning, the landlord would not be able to charge the smoking pile of debris against my friend's deposit.

Though there's a small chance she's right about the freezer (very small, don't bet on it), she's almost certainly wrong on the other items mentioned in my second letter which could cause her losses upwards of $3,000.00. That's why it's good to have many arguments, as long as each is strong.

Since this landlord also happened to be a (non-practicing) lawyer, she could recognize her risk, and also her disadvantage in being held to a higher standard regarding knowledge of landlord-tenant law.

If your landlord is just some old codger who doesn't consult lawyers and goes on just as he did in feudal times before tenant protection laws existed, then you might really have to sue him. And you should. It will help improve the quality of landlords and their business practices in your area.

Actually, I am sad that Landlord did not take us on. I was looking forward to splitting the take with my friend, 90% for me and 10% for him.

Windows Key to access Ubuntu Start Menu

I was so used to using the Windows Key on the keyboard to open the Windows Start menu, I just expect it to work on Gnome panels too.

If you don't already have an Ubuntu "Main Menu" item on your panel, you can add one by right clicking on the panel, choose "Add to Panel," then scroll down to "Utilities" and click the "Menu Bar" item and then the "Add" button. If you want to move that item around on your panel, you can figure out how to do that by right clicking it.

Now to bind the Windows Key to that item. Click your panel's "Main Menu" item, then "System," "Preferences," and "Keyboard Shortcuts." Under the "Desktop" group, click "Show the Panel Menu," then press your Windows Key and you will see the associated binding change to "Super_L". Click the "Close" button on this dialogue and you are done.

Now when you hit your Windows Key, it opens the Main Menu, equivalent to the Windows Start button.

Stop gnome-terminal screen clear

Gnome-terminal (and Mac OSX Terminal.app) clears your screen when you quit a pager or editor and I don't like it. You won't like it either if you need to refer to the thing you were just looking at after you exit back to shell. This happens with man, less, more, pico, vi and others.

Here's an example of gnome-terminal automatically clearing the screen when exiting a pager. This is what needs fixing:



Here's what it does after we fix it. No more automatic clearing:



I used to fix this problem easily in the MUD by setting an environment variable: setenv NO_CLEAR 1

But Ubuntu Dapper is no LPMUD. I searched Google for the fix. Other people had the same complaint. The best source of synthesized info I found was here.

That writer, Akkana, understood the problem and offers some solutions for everything except gnome-terminal:

"...there's no way to tell gnome-terminal to disable the alt screen behavior."

I eventually found my own solution to fix gnome-terminal that I'll share at the end of this post, but first I want to review Akkana's, since her site doesn't accept comments.

First, she correctly identifies that gnome-terminal is the source of my problem. I confirmed that by dropping out of X to a real console (CNTRL+ALT+F2), logging into my shell, and checking my TERM environmental variable:

echo $TERM

On a console, that returns "linux," and quitting any pager on a console leaves the paged info on my screen the way I want it. While in X (CNTRL+ALT+F7 to get back to X), using gnome-terminal, the $TERM variable is "xterm."

This means that I can't solve this problem under X in a way that will break my console. How limiting.

Akkana offered 3 ideas and I tried them all. The first was to create a file in my home directory called .Xdefaults (symlinked to .Xresources, just in case) that contains these lines:

XTerm*titeInhibit: true
xterm*titeInhibit: true
gnometerminal*titeInhibit: true
gnome-terminal*titeInhibit: true

and then launch new terminals both in the real xterm program and in gnome-terminal. Through trial and error, I determined that only the 2nd line above had any effect, and it only stopped screen clearing in the xterm program. That problem persisted in gnome-terminal.

If I would just use xterm, my work would be done. But I do not like xterm.

Akkana's next suggestion is to create a ~/terminfo/xtermnoalt.terminfo file and export a TERM for it into the bash environment. She provides the file, doctored xterm-color terminfo data, but with the ti/te and rmcup screen clearing bits removed. Without those, gnome-terminal is supposed to be tricked into never trying to use those features.

It sort of works, but causes an extra prompt warning that my terminal is broken:

~$ man man
Reformatting man(1), please wait...
WARNING: terminal is not fully functional
- (press RETURN)

I can hit RETURN and get the pager normally after that, and when I quit, my screen does not get cleared, but that broken warning is more irritating than the original problem.

The 'man' utility ultimately uses 'less' to do its paging, and 'less' is actually the program emitting that warning. Even though I always use 'more' instead of 'less,' and 'more' still works fine, I look at man files a lot, and I am not satisfied with these results.

Technically, I could go a bit further and just hack a fix for man. The man file on man (in the --pager option) says that man uses /usr/bin/pager for paging, and that's just a symlink to /etc/alternatives/pager, which is itself another symlink to /usr/bin/less. So I could change that last symlink to /bin/more and then 'man' and 'more' would work fine. But that is a crummy hack that still leaves pico (actually /bin/nano) totally broken:

~$ pico -w sdsd
Error opening terminal: xterm-noalt.

And I use pico a lot, so I'm still unsatisfied.

Akkana's last idea is to use a command option to 'less' to ignore terminal initializations, and yes, I could make an alias for that in ~/.bashrc so that I don't have to remember to type it (alias less='less -X') but pico would still be broken, and you know I need pico.

So I searched around the web trying to learn about termcap and terminfo. And that was hard. So instead, I downloaded all the other terminal emulators I could find, hoping to just dump gnome-terminal (apt-get install pterm aterm eterm multi-gnome-terminal konsole). I tried and hated them all.

In the end, I just got out my sledge hammer and did this:

mv /lib/terminfo/x/xterm /lib/terminfo/x/xterm.orig
ln -s /lib/terminfo/v/vt220 /lib/terminfo/x/xterm

That moves the original xterm definition out of the way, and symlinks the vt220 definition in its place. Vt220's do not do the "alternate screen" feature that makes your page disappear.

This fixes Gnome-terminal which is now being fed a vt220 definition that it thinks is xterm. Really, gnome-terminal should give users a way to turn off the annoying screen clearing feature. You and I are not the only ones that find it a nuisance.

[A reader later posted a much better solution in the Comments that uses infocmp and tic to "fix" the terminfo definition file used by the terminal program. URLs at the end of the Conclusion section.]

If you want to know how I came up with this elegant solution, I just did a 'man terminfo' (lots of websites said this was caused by "terminfo") and at the top of the page it said, "Synopsis: /etc/terminfo/*/*," so I looked in there (ls -l /etc/terminfo) and found a single README file which said that if this directory is empty, ncurses (the library in charge of cursors and terminal-like things) would look in /lib/terminfo/*/*. Looking there, I found all the term definitions and figured one of them would be without silly rmcup. Symlinking by trial and error, I found one that worked.

Conclusion

You can fix your broken gnome-terminal emulator by tampering with the terminfo definition files, and get gnome-terminal to swallow vt220 terminfo that is intentionally mislabelled xterm.

Nay-sayers may point out that vt220 is not the same as xterm and that this could cause other problems, but I haven't noticed any. If there are, they should be less annoying than xterm's rmcups screen clearing. I'm not worried. Vt220's don't have any "dangerous modes" such as those from a vt100 that can lock up a vt220's output to "line printer."

The worst result I've seen from this switch, after using it for 10 minutes, is that the X-mouse won't work in console programs like sysv-rc-conf anymore, because it's designed for an xterm, not a vt220. No big deal.

If you really hate my idea, there may be, after all, some X resources in gnome-terminal for which ti/te can be inhibited that would fix the original problem, but I don't know what else they might be called. I suppose one could read the gnome-terminal source, or email the developer, if one were (subjunctive, condition contrary to fact) very determined.

I do wish gnome-terminal had a few more user-configurable items in its menus. But at least it has a menu. Really, I'm sad that since I said goodbye to Windows, I don't have VanDyke's SecureCRT anymore.

My psychiatrist says that I should just run it under wine.

Benjamin's Reader Comments provided a real solution that fixes the whole problem correctly, rebuilding a custom terminfo definition file:

toward the end or reprinted on his own site.

This solution also works great on Apple OSX in Terminal.app. In my case, on the Mac, I am using the "Homebrew" Terminal profile, which uses xterm-color, so that is the terminal definition that I customized:

infocmp > ~/xterm-color-noclear.src
pico xterm-color-noclear.src
mkdir .terminfo
tic xterm-color-noclear.src
export TERM=xterm-color-noclear
pico .bashrc