[Web Console] Provide a help command to list the available helper functions

VERIFIED FIXED

Status

()

Firefox
Developer Tools
--
enhancement
VERIFIED FIXED
7 years ago
7 years ago

People

(Reporter: vladmaniac, Assigned: jwalker)

Tracking

({dev-doc-complete})

Trunk
x86
Windows 7
dev-doc-complete
Points:
---

Firefox Tracking Flags

(blocking2.0 -)

Details

(Whiteboard: [Web-Console-Testday])

Attachments

(2 attachments, 2 obsolete attachments)

(Reporter)

Description

7 years ago
Build ID: 

Mozilla/5.0 (Windows NT 6.1; rv:2.0b8pre) Gecko/20101018 Firefox/4.0b8pre

Help command is a must. Web devs use different kinds of debuggers or consoles (like iPhyton for e.g) and we should provide some guidance for the FF4's new web console users. 

Suggestions: could type "help" or "?" to list available line commands.

Comment 1

7 years ago
brilliant! why didn't *I* think of this earlier.

Comment 2

7 years ago
Good idea! Unfortunately, I'm not sure if we can get this in Firefox 4 due to string freeze.
we could probably popup a window with the MDC page as we were going to do with the Style panel.

Comment 4

7 years ago
That's an excellent idea, Rob
Blocks: 594225

Comment 5

7 years ago
Here is the MDC page about the Web Console: https://developer.mozilla.org/en/Using_the_Web_Console

it includes a summary of the helper functions.

Updated

7 years ago
Assignee: nobody → jwalker
Perhaps, rather than open a window when the user types "help" we could respond as follows:

> help
For help see: _Using_the_Web_Console_ (opens in a new window)

Clearly some of the text is a hyperlink, which when clicked opens a new window.

Opening a new window feels like quite a heavyweight option, and it feels like the user expects a textual response from a textual input. A new window is a bit of a surprise, but it's just what you expect when you click a link like the one above.
(In reply to comment #6)
> Perhaps, rather than open a window when the user types "help" we could respond
> as follows:
> 
> > help
> For help see: _Using_the_Web_Console_ (opens in a new window)
> 
> Clearly some of the text is a hyperlink, which when clicked opens a new window.
> 
> Opening a new window feels like quite a heavyweight option, and it feels like
> the user expects a textual response from a textual input. A new window is a bit
> of a surprise, but it's just what you expect when you click a link like the one
> above.

Wait - that would be a new string.

I guess we'll have to go with ugly. Grr.

Comment 8

7 years ago
The ideal case would probably have a bunch of useful help info show up in the command output when you type help, but that's a *lot* of localization and I think that just opening the new window is a nice thing to do for now.
Created attachment 487563 [details] [diff] [review]
Proposed fix
Attachment #487563 - Flags: review?(gavin.sharp)
Keywords: dev-doc-needed

Comment 10

7 years ago
I'd like to nominate this as a blocker, because it will help the discoverability of the console's JS command line functionality (by responding to help, ? and help() and providing the user with the docs from MDC).
blocking2.0: --- → ?
Created attachment 489133 [details] [diff] [review]
Upload 2

Rebase, adding tests
Attachment #487563 - Attachment is obsolete: true
Attachment #489133 - Flags: review?(gavin.sharp)
Attachment #487563 - Flags: review?(gavin.sharp)
I don't think this is a blocker, but we can take the patch.
blocking2.0: ? → -
Comment on attachment 489133 [details] [diff] [review]
Upload 2

I had some concerns about the l10n aspect of this - hardcoding the en-US link isn't a great experience for non-en-US users. Devmo isn't really set up to do proper l10n fallback though, so I think this is probably the best we can do for now (Pike seems to agree).

We should probably add a note to the MDC page (in a wiki-source comment or something?) that mentions that the page is linked to in-product, and give sheppy a heads up about it as well.
Attachment #489133 - Flags: review?(gavin.sharp)
Attachment #489133 - Flags: review+
Attachment #489133 - Flags: approval2.0+
I'll take on the wiki-source comment.

We've been through this issue a bit with linking from the stylesheet inspector to give help on CSS properties. I think we all agree that we need to be able to do better in the future, but that there's not a lot we can do right now.

Thanks.
FWIW, I'm watching this bug. Want me to look into the possibility of a script of some kind that we could set up on MDN to redirect to localized versions of the page if available?
(In reply to comment #15)
> FWIW, I'm watching this bug. Want me to look into the possibility of a script
> of some kind that we could set up on MDN to redirect to localized versions of
> the page if available?

Thanks Sheppy - I think something like that would be a good idea.

This has cropped up before in bug 591584 which lead to bug 591902, which you're aware of.

Personally I very keen that in Developer Tools we move beyond telling the user raw data about web pages, and into helping them be awesome web developers, and it's better to do this by linking into MDN than through copying content into Firefox, so I'd like to do more of this type of thing.
Is there a way for the URL to be built on the fly to include a component indicating the language you need? Something like https://developer.mozilla.org/AppLinks/WebConsoleHelp?lang=<langCode> for example?

If you can do that, I can easily (very easily) set up a script at https://developer.mozilla.org/AppLinks/WebConsoleHelp that would redirect to the appropriate section in the given language if available, otherwise show the English version (possibly with a "this isn't available in your language yet" in the user's language).

That would be different from just building a URL for the language directly in that you'd get at least the English version if no translation is available, instead of a "there's no content here" page.
OK, I've put together this page:

https://developer.mozilla.org/AppLinks/WebConsoleHelp?locale=<foo>

Where <foo> is the language code to display the help in. If <foo> isn't found in our wiki, the English version is displayed, with a link at the top asking the reader to contribute a translation. Try:

https://developer.mozilla.org/AppLinks/WebConsoleHelp?locale=en (exists)

https://developer.mozilla.org/AppLinks/WebConsoleHelp?locale=es (doesn't)

Let me know if this will do the job for you.
Thanks. I'll update the patch and we'll see how it works.
If there are rough edges I can work out on the web side, let me know. This was halfway between proof of concept and fully smoothed out implementation, but should be good enough to be sure the thing will work before we do any cleanup work.

Comment 21

7 years ago
(In reply to comment #18)
> OK, I've put together this page:
> 
> https://developer.mozilla.org/AppLinks/WebConsoleHelp?locale=<foo>

That's very cool. FWIW, we were hoping for that kind of functionality for the Style Inspector (and will want to revisit that when we come back to the Style Inspector).
I'm just testing an update to include this. I'll post as soon as it passes.
Thanks.
(In reply to comment #20)
> If there are rough edges I can work out on the web side, let me know. This was
> halfway between proof of concept and fully smoothed out implementation, but
> should be good enough to be sure the thing will work before we do any cleanup
> work.

I've not managed to test any successful re-direction. Is there an easy way to tell if there are any translations of that page other than en?

We're currently getting the locale from navigator.language, which is specified as {language}-{COUNTRY} (e.g. en-GB) rather than just {language}. What are your internationalization plans? Would we ever distinguish between pt-BR and pt-PT (I believe that's a good example of a single language that's quite different in 2 countries)?

We're using a target of #Helpers to jump to the right place in the page, however this obscures the "This page isn't available" message. Maybe the final version needs an in-page dialog or something? It could also offer to pass through BabelFish etc.

Many thanks for hacking on this.
Created attachment 491487 [details] [diff] [review]
Upload 3

This patch is a rebase and tweaks the URL to the correct one supplied by sheppy.

It uses navigator.language, we might wish to use navigator.language.split("-")[0] to remove the country part though.
We can change the code on the site to direct straight to the helpers section if you want. I had set it up to show all the info about the command line environment, but that's easy to change.

As for the locale code... the site is set up to only use the two-character language code instead of a language-country combination. I can change the script to strip off the country part, but barring a significant redeployment of the site, I don't foresee the country actually being used by the site anytime soon. Up to you.

As for testing, we can put up a temporary page for another language so you can confirm the direction works properly. Hopefully localizers will translate that page soon. In fact, I will encourage them to do that as soon as the UI changes for the console land and the document is finalized.
I suggest we split the WebConsole page in 2. One is the 'home' page, and the other is the 'helpers' page, so we don't need a #target at all.
What do you think?
Done; the helpers page is now a separate page, so no #target is needed.
(In reply to comment #25)
> As for the locale code... the site is set up to only use the two-character
> language code instead of a language-country combination. I can change the
> script to strip off the country part, but barring a significant redeployment of
> the site, I don't foresee the country actually being used by the site anytime
> soon. Up to you.

I suggest that we pass you the information so you can ignore it, rather than us hiding the information so you can't ever have it.

However I'm 49/51 so if anyone has strong opinions ...

Joe.
Created attachment 491809 [details] [diff] [review]
[checked-in] Upload 4

I've just altered the URL to fit in with sheppy's page splitting.
I think we're ready to go on this now.
Thanks!
Attachment #491487 - Attachment is obsolete: true
Whiteboard: [checking-in]
I've tweaked the code on the site to strip off the country code if passed, so you can now safely pass en-US or whatever, and the script will act appropriately. This will let us support the country code later if things change on the wiki in the future.
The list of locale codes that we use for Firefox builds (i.e. the possible values of navigator.language) are here:
http://mxr.mozilla.org/mozilla-central/source/browser/locales/all-locales

Some specify regions while others don't. Do they all map correctly to MDC's locale codes?
blocking2.0: - → ?
blocking2.0: ? → -
Yes, although we obviously don't have localizations for all of them.
was hoping to get this checked in today, but with build bustage this morning and other patch shenanigans later today, I've run out of time. I'll either get to it this weekend or some other kind soul can check it in with their stuff as a ride-along.

This patch is totally working no tests fail and no leaks will happen. Promise!
Status: NEW → ASSIGNED
Keywords: checkin-needed
Whiteboard: [checking-in] → [safe-to-checkin]

Comment 34

7 years ago
navigator.language is not one of all-locales in general, lang-packs can be selected by arbitray codes, and it could even be junk in general.

We should really use the accept-languages http header to determine the best match of locale code, probably even to match the unicode language codes.
Comment on attachment 491809 [details] [diff] [review]
[checked-in] Upload 4

http://hg.mozilla.org/mozilla-central/rev/847fe59d8095
Attachment #491809 - Attachment description: Upload 4 → [checked-in] Upload 4
Status: ASSIGNED → RESOLVED
Last Resolved: 7 years ago
Keywords: checkin-needed
Resolution: --- → FIXED
Whiteboard: [safe-to-checkin]
Keywords: dev-doc-needed → dev-doc-complete

Updated

7 years ago
Status: RESOLVED → VERIFIED
Whiteboard: [Web-Console-Testday]
You need to log in before you can comment on or make changes to this bug.