52222 - Help button on askSendFormat dialog

Status: ASSIGNED

(SeaMonkey :: MailNews: Composition, defect, P3)

Description

[Ben Bucksch (:BenB)]

4.x had an "Help"-button in the askSendFormat dialog. We have it, too, but it is
not enabled. I think, it would really help a lot, because this whole format
topic is non-trival, especially for end-users.

I didn't bring this up earlier, becuase it has been said, context-sensitive help
were cutted for this version. However, I see context-sensitive help ("More Info"
etc.) in several places in the product, usually technically opening a browser
window. See e.g. this code:
<http://bonsai.mozilla.org/cvsview2.cgi?diff_mode=context&whitespace_mode=show&subdir=mozilla/xpfe/components/prefwindow/resources/content&command=DIFF_FRAMESET&file=pref-smart_browsing.xul&rev1=1.29&rev2=1.30&root=/cvsroot>.

I think, we should do the same. I can still write the doc itself (shortly) after
nsbeta3.

Comment 1

[Ben Bucksch (:BenB)]

Status report:
It works, but
- For dumb technical reasons (limitations of the current implementation of the
common dialog), the Help button appears in the middle, i.e. OK - Help - Cancel,
on Win and Unix. Neither J-F nor me know a good workaround.
- I open a browser window, because there is no help window xul, to my knowledge
(if you know some, please say where).
- The document is not yet written. Matthew and I will work on it.

Does the UI freeze apply to help files, too?

Comment 2

[Ben Bucksch (:BenB)]

Attachment: Fix, version 1

Comment 3

[Ben Bucksch (:BenB)]

Attachment: Placeholder doc, version 1

Comment 4

[Ben Bucksch (:BenB)]

ducarroz, please review.

Comment 5

[Jean-Francois Ducarroz]

Ben, good catch for the prefs service progID stuff. The rest of the code is good 
too. However, you cannot add the help button until the help file that goes with 
is complete! Sorry, I cannot give you my OK.

The purpose of th UI freeze is to let internationalization (I10n) people start 
doing the translation, therefore the Help file must be ready too.

Comment 6

[verah (gone)]

Adding myself and rudman to cc list

Comment 7

[rudman]

Adding Robin Foster to cc list.

Comment 8

[verah (gone)]

The *content* of the Help files doesn't have to be final until 10/13, per 
localization. In other words, you can use a placeholder.

However, there's other really big problem -- localization doesn't know about 
this Help file, since it's not part of the end user online help suite. Mozilla 
doesn't have a help suite defined yet, and the commercial version doesn't call 
for this file. Since it's small, it might be okay.

But here's another problem -- how does this get into the installer? Where is it 
going to live? What is it's format -- if it's going to use the Help chrome, then 
we'll have to get an exception to check it in. If it will be displayed in the 
regular browser window, it will blow away the page the user's currently viewing 
(if any). Is that okay?

And finally, the content needs to go through a review and an editorial pass.

Comment 9

[Ben Bucksch (:BenB)]

> The *content* of the Help files doesn't have to be final until 10/13, per 
> localization. In other words, you can use a placeholder.

So, can I have an r=ducarroz?

> However, there's other really big problem -- localization doesn't know about 
> this Help file, since it's not part of the end user online help suite. Mozilla 
> doesn't have a help suite defined yet, and the commercial version doesn't call 
> for this file.

I have no idea what a help suite is, or why this is a problem.

> Where is it going to live?

In the locale, right next to the askSendFromat.dtd file (unless you have a
better suggestion).

> What is it's format -- if it's going to use the Help chrome,

Where does the Help chrome live?

> then we'll have to get an exception to check it in.

Why does it matter where (browser or help chrome) it is displayed?

> If it will be displayed in the regular browser window, it will blow away the
> page the user's currently viewing (if any).

No, I open a new window. (Unfortunately, this browser window is modal then.)

Comment 10

[Jean-Francois Ducarroz]

Sorry Ben but I cannot let you activate a button that will display an incomplete 
document at this stage of the development. I would like first to see the 
document be finalized.

Another question: Does help files are suppose to be local?

Comment 11

[scottputterman]

Hey Ben,

We aren't going to take this code at this point. As Vera said there are a lot of 
complications that make this not worth exploring right now.

The reasons for this include:

1.The Help button in the center of the OK, Cancel buttons really doesn't look 
good 

2.The modal browser window for reading about it.

3.All of the localization issues associated with translating a file that they 
were not expecting to translate.

This might be something we can look into in the future, perhaps when there's 
more context sensitive help in the product and when there's more resources in 
documentation and localization to make sure everything gets done properly. 

Comment 12

[Ben Bucksch (:BenB)]

putterman,
1. and 2. are not my fault, I cannot do much against it, and we don't know, when
it will be fixed. It doesn't seem like a good reason to me not to include this
much-needed help at all.
3. is invalid for the trunk.
So, can get this into the trunk now, please?

Comment 13

[scottputterman]

I'm still not a big fan of this because I think it doesn't look good, but I 
wouldn't mind having a solution for this.  Vera and Steve, do you have any 
preferred solutions for this besides not doing it at all?  Do we have plans to 
start adding context sensitive help to other dialogs?

Comment 14

[rudman]

Ben, there is Help window XUL, which we are going to check in. So I wouldn't
want this button to be at cross-purposes of what we are trying to accomplish
with the XUL.

There is no context-sensitivity to the help system we're going to check in, but
we would welcome work on that for future releases.

I would say that the help xul won't be checked in until at least 10/16, as we
are trying to fix things for the Netscape release.

I encourage you to wait a brief while until you can see the work that's been
done with regard to help.

Comment 15

[Ben Bucksch (:BenB)]

rudman, a help chrome would surely be nice, but I don't see, how this would help
us with problems 1./2..

Comment 16

[Ben Bucksch (:BenB)]

Targetting mozilla0.9. What should I do now?

Comment 17

[Ben Bucksch (:BenB)]

What should I do now? putterman?

Comment 18

[scottputterman]

I still don't like the idea of a help button in between ok and cancel. Steve and
Vera, do you know of any plans to add context sensitive help in the near future?
 What do you think is the best way to provide extra help?  I just read the
documentation and it seems to me that this is aimed at a higher level of user
than I would think help would be aimed at.  For example I don't think most mail
users are going to understand how html tags affect the email they are sending.

Comment 19

[Ben Bucksch (:BenB)]

> I still don't like the idea of a help button in between ok and cancel.

Me neither, but last time I checked, it seemed like a lot of work to add this.
We'd have to change the "interface" for XPTollkit's CommonDialogs, IIRC. Nothing
I'd want to do personally.

> I just read the documentation

It is just a placeholder. I am not too qualified to write user docs, I can just
correct them.

Comment 20

[timeless]

for dialogs, we should use os specific approaches. windows has the what's this 
widget (top right title region), macos has the help widget (bottom right 
corner).  Linux would probably follow the macos approach.

Help should not be between ok and cancel, and unless mpt has a strong objection 
to it being a non command button at the bottom right edge this solution will 
work.

<a href="javascript:chelp();" class="desc"><img 
src="chrome://global/images/chelp" alt="?" tooltip="show _what's this_ context 
sensitive help">Help</a>

Comment 21

[Ben Bucksch (:BenB)]

> windows has the what's this widget (top right title region)

this is inappropriate in this case - the help is about the whole dialog, not a
specific widget.

> Help should not be between ok and cance

Feel free to implement something better. Until we have this, I suggest to take
my patch. Better a misplaced help button than no help at all IMO.

Comment 22

[rudman]

Just last week, we came up with an alternative Help system solution (different
than the 6.0 viewer), based on ActiveState's Komodo viewer. It probably allows
for context-sensitivity. It'll be checked in most likely during the week of
1/15. I'd suggest waiting for the new viewer rather than doing the one-offs for
particular dialogs.

Comment 23

[timeless]

*cheers*, komodo's system rocks.

Comment 24

[Ben Bucksch (:BenB)]

We should know have generic Help buttons in dialogs, so fixing thus bug is much
easier and gives better results.

If anybody wants to write a draft for a document (possibly based on my
placeholder), feel free.

Comment 25

[Asa Dotzler [:asa]]

Bugs targeted at mozilla1.0 without the mozilla1.0 keyword moved to mozilla1.0.1 
(you can query for this string to delete spam or retrieve the list of bugs I've 
moved)

Comment 26

[Daniel Wang]

Attachment: patch (Help text)

Comment 27

[Daniel Wang]

Attachment: patch (XUL & JS)

Comment 28

[R.J. Keller]

Comment on attachment 139975 [details] [diff] [review]
patch (Help text)

r=rlk, with one small request.

> +<li>
> +  <span class="ui">Send the message in HTML anyway</span>:
> +  If you select
 this option, keep in mind that some mail programs may have trouble
 displaying the message.</li>

Let's try and keep everything aligned correctly.

Comment 29

[Ben Bucksch (:BenB)]

>  whether your recipient can display HTML messages. If you are in
>  doubt, send the message in both HTML and plain-text formats.</p>

I believe this text is legacy from the Netscape help. Please change that to
"If you are in doubt, send the message as Plain Text only." We decided that to
be the default in Mozilla long ago, after a long discussion.

>   Choose this option to send message in both HTML and its
>   plain-text equivelent.

equiv*a*lent

I'd write
"Choose this option to send both a formatted HTML version and its
Plain Text equivalent inside the message."
to make clear that it's sending only one emails, not two.

> Your recipient's mail program will
> display the appropriate format depending on the program
> settings/capabilities.

Please add
"This wastes Internet traffic and disk space by storing the same text twice."
here, too.

> +    If you select this option, keep in mind that some mail
> +    programs may have trouble displaying the message.

s/may/will/.

All of that applies to both the askSend dialog and the prefs dialog.


Combining these changes and a few other ones, I'd write:


+If you are in doubt, send the message as Plain Text only.
+
+<ul>
+  <li>
+    <span class="ui">Send in Plain Text and HTML</span>:
+    Choose this option to send both a formatted HTML version and its
+    Plain Text equivalent inside the message.
+    The recipient's mail program should
+    display the appropriate version depending on the program
+    capabilities and settings.
+    This wastes Internet traffic and disk space by storing
+    the same text twice.
+  </li>
+  <li>
+    <span class="ui">Send in Plain Text only</span>:
+    Choose this option to convert the message to plain text. &brandShortName;
+    will convert formatted text to its text equivelent (e.g. *bold* for
+    <b>bold</b>). Some formattings such as color may be lost.
+  </li>
+  <li>
+    <span class="ui">Send in HTML only</span>:
+    If you select this option, keep in mind that some recipients
+    will have trouble reading the message.
+  </li>
+</ul>

Identical text then for the prefs dialog help.

Comment 30

[Ben Bucksch (:BenB)]

> Some formattings such as color may be lost.

ops, this should be "will", not "may".

Comment 31

[Daniel Wang]

>>   Choose this option to send message in both HTML and its
>>   plain-text equivelent.
> equiv*a*lent

grrr... MSWord autocorrect fooled me

>> +    If you select this option, keep in mind that some mail
>> +    programs may have trouble displaying the message.
>s/may/will/.

I prefer "may"

>> Some formattings such as color may be lost.
> ops, this should be "will", not "may".

This doesn't sound right. Should be either "<a specific thing> will be lost" or
"<some uncertain thing> may be lost"

Cleaned up version:

<span class="ui">Send in Plain Text and HTML</span>:
Choose this option to send both HTML
and its plain-text equivalent in the message.
<!--
The recipient's mail program should display the appropriate
version depending on the program capabilities and settings.
-->
This option increases disk space usage and connection
bandwidth.

I don't like "connection bandwidth" or "Internet traffic". fantasai, help?

Comment 32

[Ben Bucksch (:BenB)]

Attachment: Patch (Help text)

Comment 33

[Ben Bucksch (:BenB)]

I used references innstead of copying the text 3 times, but feel free to copy
it, if you add comments to keep them in sync.

Comment 34

[Ben Bucksch (:BenB)]

> > some mail programs may have trouble displaying the message.

> I prefer "may"

It's not a matter of preference, but correctness. It's a matter of fact that
*some* mail programs *cannot* display HTML, either displaying garbage (HTML
source) or basically treating it as attachment. Not maybe, but sure. Either
"some will" or "it may".

Comment 35

[R.J. Keller]

Comment on attachment 139999 [details] [diff] [review]
Patch (Help text)

BTW, Daniel I think that Ben is right. We should have will instead of may.

Ben, my review is below:

> +tables — just like a web page. However, some recipients will not
> +be able to read HTML messages. &brandShortName;

Generally the style is to not have a space before and after a mdash (meaning
"tables—just"). It looks more correct when displayed then when looking at
the HTML.

> +<a name="OPTIONS_FORMAT"></a> 
> +

Change the name of this to "options_format" to keep consistency with the rest
of the file. All caps is something I've been trying to avoid when it comes to
anchors.

> +&brandShortName; will convert formatted text to its text equivelent

<picky>I think we're breaking the consistency a bit when changing Mail &
Newsgroups to &brandShortName; all around Mail help.</picky>

> +Choose this option to send both a formatted HTML version and its
> +Plain Text equivalent inside the message.
> +The recipient's mail program should display the appropriate version
> +depending on the program capabilities and settings.
> +This uses more disk space, but may be the best choice if
> +you need to send richly formatted email and you are not sure whether

At the end of each line you don't have a consistent amount of characters per
line, making it hard to read.

> +<li>
> +  <span class="ui">Ask me what to do</span>,
> +  <span class="ui">Convert the message to plain text</span>,
> +  <span class="ui">Send the message in HTML anyway</span>,
> +  <span class="ui">Send the message in both plain text and HTML</span>:

Let's have a line break at the end of each <span> tag. This looks difficult to
read from inside the Help viewer.

Comment 36

[Ben Bucksch (:BenB)]

> Generally the style is to not have a space before and after a mdash (meaning
> "tables—just"). It looks more correct when displayed then when looking at
> the HTML.

I never understood why people omit these spaces. To me, it looks confusingly
wrong, it looks like it's one word with an overly long hyphen, like
"tables-just". BTW, at the very top, there's "window — the", i.e. with spaces -
that looks correct to me.

> Change the name of this to "options_format" to keep consistency with the rest
> of the file. All caps is something I've been trying to avoid when it comes to
> anchors.

I used upper case, because I saw other anchors with upper case. Anything is fine
with me.

> <picky>I think we're breaking the consistency a bit when changing Mail &
> Newsgroups to &brandShortName; all around Mail help.</picky>

"Mail & Newsgroups" is a bug, if you ask me. You hardcode a product name. Not
all vendors use that name. (Besides, I think that's a quite bad product name and
makes the text sound strange: "Mail & Newsgroups formats the message"?)

> At the end of each line you don't have a consistent amount of characters per
> line, making it hard to read.
...
> Let's have a line break at the end of each <span> tag. This looks difficult to
> read from inside the Help viewer.

OK

Comment 37

[fantasai]

> I don't like "connection bandwidth" or "Internet traffic". fantasai, help?

Just say it increases the size of the message. That covers both the "disk space"
issue and the "bandwidth" issue.

Comment 38

[R.J. Keller]

> I used upper case, because I saw other anchors with upper case. Anything is fine
> with me.

really? If this is the case, a bug should be filed. Although some help docs
haven't been updated, all help docs ending in *.XHTML should not have any
anchors in all caps.

> "Mail & Newsgroups" is a bug, if you ask me. You hardcode a product name. Not
> all vendors use that name. (Besides, I think that's a quite bad product name and
> makes the text sound strange: "Mail & Newsgroups formats the message"?)

true. This issue will probably be issued in bug 206840.

> I never understood why people omit these spaces. To me, it looks confusingly
> wrong, it looks like it's one word with an overly long hyphen, like
> "tables-just". BTW, at the very top, there's "window — the", i.e. with spaces -
> that looks correct to me.

I'm just trying to think of what is most commonly used. I know that it is
strange but I'm sure there's a logical reason (that I probably don't know :)).
There is a lack of consistency in the help docs with things like mdashes, but
for future patches I'd like it to follow what looks to me the most commonly used
style in documentation.

Comment 39

[Ben Bucksch (:BenB)]

(In reply to comment #38)
> > I used upper case, because I saw other anchors with upper case.
> 
> really? If this is the case, a bug should be filed.

Filed bug 232396.

[dash]
> I'm just trying to think of what is most commonly used.

Replied by mail.

Comment 40

[Daniel Wang]

>-tables—just like a web page. However, some recipients may not
>-be able to receive HTML messages. Mozilla Mail & Newsgroups
>+tables — just like a web page. However, some recipients will not
>+be able to read HTML messages. &brandShortName;

This is too assertive. Let's keep the orginal wording.

>+Even if you use the HTML editor, the message can still be converted to
>+plain text during the sending process. You can choose whether
> your addressees should receive HTML or plain-text messages by

"sending process" should link to #using_the_html_mail_question_dialog_box and
"choose" should link to #send_format

>+<a name="OPTIONS_FORMAT"></a> 
>+
> <ul>

<ul id="format_menu_options">

>+you need to send richly formatted email and you are not sure whether
nit, "formatted messages"

>+See <a href="#OPTIONS_FORMAT">above</a> for a description of the options.

See <a href="#format_menu_options">format options</a> ...

>+Some mail programs will have trouble displaying an HTML-formatted message.

Some mail programs cannot display HTML messages.

can we use either "HTML message" or "formatted message", and drop
"HTML-formattted message"?

>+If you are in doubt, send the message as Plain Text only.</p>

The dialog already has "(recommended)" after the plain-text option. Other
vendors may have a different default, so we should take this out to avoid conflict.

>-<li><strong>Ask me what to do</strong>: This option requires Mail
> :
>+  <a href="#OPTIONS_FORMAT">Format options menu</a> for a description.
>+</li>

The Options | Format Help text says nothing about Ask Me what to do, or what
"Send the message in HTML anyway" mean. Also, for Perferences dialog Help, we
should just describe the options, not redirect the user to somewhere else.

Don't forget in my previous patch:

+You can set a default option in the
+<a href="#send_format">Send Format Preferences</a>.

Comment 41

[Ben Bucksch (:BenB)]

> This is too assertive.

No, it's not, it's a fact.

> Let's keep the orginal wording.

Remember that the original text was written by Netsacape, which had a proclaimed
goal of promoting HTML mail, creating serious communication problems with the
resulting anger on the side of netizens.

> "choose" should link to #send_format

"choose" referred to the address book here.

> > you need to send richly formatted email and you are not sure whether

> nit, "formatted messages"

No, I intentionally wrote "email". Sending HTML to Usenet or public mailing
lists is generally frowned upon. The text implies why.

> can we use either "HTML message" or "formatted message", and drop
> "HTML-formattted message"?

"HTML message" is fine with me. ("formatted message" would be too ambiguous.)

Comment 42

[R.J. Keller]

> This is too assertive. Let's keep the orginal wording.

no Daniel, Ben is right. This should be changed. It is obsolete.

Comment 43

[Alec Flett]

assertive or fact or whatever, it is misleading.

"Some recipients may not be able to recieve.." is obviously not quite correct,
but it is because of "recieve". To say "Some recipients will not be able..." is
in fact incorrect, because we don't know what kind of mail client they will use.
If we say that "SOME" recipients "WILL NOT" then there is at least one recipient
in the user's list that absolutely cannot read the message. There is no way that
we can know this at send time.

"Some recipients may not be able to read.." (or "display" could also work) would
be the most correct message AND would not mislead users.

There is no conspiracy theory about netscape trying to promote HTML mail.
Mozilla is a mail client that allows you to write HTML mail, and it needs to
properly inform users without misleading them. 

Comment 44

[Ben Bucksch (:BenB)]

> If we say that "SOME" recipients "WILL NOT" then there is at least one
> recipient in the user's list that absolutely cannot read the message

This is a help text and talks in general, not about a specific message. In
general, there *are* people not able to read HTML mail.

If you think that users may assume that the help is so context-sensitive that it
asserts that some of the current, *actual* recipients are not able to read HTML
mail, I'd be OK with "may".

> netscape trying to promote HTML mail.

(FYI, that's what a Netscape guy (phil peterson?) told me.)

Comment 46

[Mark Banner (:standard8)]

Thunderbird doesn't have help buttons on its dialogs now - only SeaMonkey does. Therefore moving this to the SM product.

Comment 47

[Robert Kaiser]

Ben, this is still ASSIGNED to you, are you still planning to work on this in the SeaMonkey world?

Comment 48

[Ben Bucksch (:BenB)]

Not for Seamonkey specifically. I do still think it is needed (also for Thunderbird!), I just didn't have motivation to do it yet.