165960 - Implement Mozilla Firebird Help

Status: VERIFIED FIXED

(Firefox :: Menus, enhancement)

Description

[Blake Ross]

Comment 1

[Asa Dotzler [:asa]]

We don't have help content. What's the point of launching the help viewer? This
shouldn't block us on 0.1

Comment 2

[Asa Dotzler [:asa]]

This impacts windows and linux.

Comment 3

[Fabricio Campos Zuardi]

Is there a bug about Phoenix documentation?

Comment 4

[Asa Dotzler [:asa]]

Fabricio, are you interested in making help documentation for Phoenix?

Comment 5

[Fabricio Campos Zuardi]

English is not my primary language, but I have interest in help =)

Comment 6

[Asa Dotzler [:asa]]

Updating summary. We can use the Mozilla help system or the OS's help system but
we'd need Phoenix help docs. This bug can be used to track the implementation of
both. Bugs which block Phoenix having a working and decent help system should
block this bug.

Comment 7

[Neil Parks]

I would be interested in trying to write some help or documentation.

Comment 8

[David Tenser [:djst]]

> We can use the Mozilla help system or the OS's help system but
> we'd need Phoenix help docs.

What kind of documentation do you need? What format, what topics, etc. etc.?

Comment 9

[Matt Pusey]

If you could create some sort of documentation TODO list then I would be happy
to do a few items on it. (Writing things that is, I'm a **** programmer.)

Comment 10

[Sean Kent]

Perhaps just list a redirect to David's site? http://texturizer.net/firebird/

Comment 11

[Bill Creswell]

David Tenser's pages could be reformated to create a fairly complete help menu.

http://texturizer.net/firebird/documentation.html

Comment 12

[Will Levine]

do we want to use the same help viewing system as Mozilla?  i can work on
changing that to make it work with firebird.

Comment 13

[Brant Gurganus]

Hey Will and others interested in this, I've got a partially working XPI of Help
for Firebird.  It has no content (if it is an extension, the default content
should be Help on Help, otherwise, it should be Firebird help).  I commented out
some stuff because I could not find the new entity names and other things I
hardcoded because I couldn't get the locale stuff to work.  If anybody else
wants to hack on this, go ahead.  I am CC'ing Ian since he originally wrote the
Help browser.

Comment 14

[Brant Gurganus]

Attachment: Firebird Help XPI 0.1

Firebird Help XPI 0.1
Known issues:
 * Something is wrong with themes.
 * No content yet.

Changes from Seamonkey version
 * I changed Netscape references to mozilla.org references.
 * I change Mozilla to Mozilla Browser.

This will add a "Help" item as the first item in the Help menu.

Comment 15

[Brant Gurganus]

Attachment: Help XPI 0.2

The sidebars seem to be working.  The toolbar is not though.  Any help with it
would be appreciated.  I'm trying to look at browser.xul as a reference to no
avail.

Comment 16

[Simon Paquet [:sipaq]]

Taking QA Contact as designated owner of Firebird-Menus. Sorry for bugspam.

Comment 17

[Brant Gurganus]

Attachment: Help XPI 0.3

I still can't get the toolbars working, but I think everything else is working.
 If somebody could tackle the toolbars and get them working, then I think we
have a working help viewer for Firebird.  We just need to start creating
content packages for it.

Comment 18

[Eric Hodel]

Hi, drbrain from IRC here...

Those image paths don't exist in Firebird, you'll want
chrome://browser/skin/Toolbar.png and friends instead.

See: http://lxr.mozilla.org/mozilla/source/browser/base/skin/browser.css#148

Comment 19

[R.J. Keller]

I'm willing to contribute some help menu documentation.

Comment 20

[Brant Gurganus]

R.J. I'm adding you to CC since you expressed interest in helping to create some
initial documentation.  The first documentation package that we need made is the
default one that tells how to use help and how to create packages for it.

I will upload my latest XPI (still with broken toolbars) shortly and you can use
the items in the locale folder as a starting point.  Since we don't care about
Internet Explorer or anything with this, I am making all new documentation XHTML
1.1, UTF-8 encoding and CSS.

Some starter information:
 * mozillahelp.rdf is the help package description.  It tells where to find the
contents, index, search database, and glossary.
 * contents.rdf, index.rdf, etc. populate the respective sections of the UI.

Once this Help on Help package is complete, we can start on actual application
packages.

Comment 21

[Brant Gurganus]

Attachment: Latest Help Package

Toolbars look correct, but for some reason they are not functional (except the
Print button).

Comment 22

[Brant Gurganus]

Current development of help can be found at firebirdhelp.mozdev.org for the time
being.

Comment 23

[R.J. Keller]

--> me

Me and Brant are currently working on this bug at http://firebirdhelp.mozdev.org

Comment 24

[R.J. Keller]

Makefiles were added to the Firebird Help trunk at MozDev.org and it compiles
correctly into Firebird. Now here's the issue: how would Firebird Help and
Seamonkey Help work together?

Comment 25

[Oleg Sidletskiy]

*** Bug 220259 has been marked as a duplicate of this bug. ***

Comment 26

[R.J. Keller]

Attachment: Patch

Patch adds the Help directory. This will allow you to build Firebird Help on
the trunk.

This patch should include ALL of the contents of Firebird Help on the MozDev
Server:

export CVSROOT=:pserver:[e-mail]:/cvs
cvs -z3 -q co -P firebirdhelp/firebirdhelp

the firebirdhelp/firebirdhelp dir would be renamed help.

Comment 27

[R.J. Keller]

Comment on attachment 133610 [details] [diff] [review]
Patch

Note comment #26.

Comment 28

[R.J. Keller]

Attachment: Patch

FULL patch, excluding images.

Comment 29

[Pham]

I've tried the one on mozdev and it's horrrible

Comment 30

[Daniel Wang]

Simon, can you also take over the QA at firebirdhelp.mozdev.org?

Comment 31

[R.J. Keller]

If you got a problem with Firebird Help, file a bug
(http://firebirdhelp.mozdev.org/bugs.html).

Comment 32

[Simon Paquet [:sipaq]]

Comment on attachment 133637 [details] [diff] [review]
Patch

Dean, can you take a look at this and land it before 0.8 ships if you like it?
Thanks.

Comment 33

[Simon Paquet [:sipaq]]

Comment on attachment 133637 [details] [diff] [review]
Patch

Dean's review is no longer sufficient.

Comment 34

[Mike Connor [:mconnor]]

I don't know about the blocking flag here.  But just a couple comments: 

1) the Help module needs to be supported as an XPI within the installer.  I
personally don't want or need help, and people trying to do a minimal install
will want the choice to not install this.

2) the XPI on mozdev is 638k, is this expected size?  how big is help in the suite?

Comment 35

[R.J. Keller]

> 1) the Help module needs to be supported as an XPI within the installer.  I
> personally don't want or need help, and people trying to do a minimal install
> will want the choice to not install this.

I would agree with having Firebird Help not default for a minimal install, but
it should be part of the build because an end-user product should have end-user
documentation, and the Firebird Help documentation is very user-friendly (as
opposed to the Seamonkey Help documentation).

> 2) the XPI on mozdev is 638k, is this expected size?  how big is help in the
suite?

It's difficult to track since the Seamonkey files are spread throughout the JAR
files. When they're not jar'red, Seamonkey Help is 1.67 MB while Firebird Help
is 869 KB (including Thunderbird Help stuff, which won't be on trunk). Firebird
Help is a HUGE cleanup in Seamonkey help, and it also includes about 400K less
documentation/images.

Also note that the latest version of Firebird Help fixed most of the major bugs
with Firebird Help, that the patch does not contain. It's complete for the most
part. The only thing left is a couple of minor documentation changes and get
some toolbar button images and it's done.

Comment 36

[Ben Goodger (use ben at mozilla dot org for email)]

Sorry for the delay in looking at this. I will get to it tomorrow, I promise!

Comment 37

[Ben Goodger (use ben at mozilla dot org for email)]

OK, I suck, I got bogged down with other things today. Tomorrow! Or, this week,
at least!

Comment 38

[Ben Goodger (use ben at mozilla dot org for email)]

OK, I have a few comments. 

1. Browser specific matter (documentation files, images, indices, etc) should go
into browser/components/help/. Shared matter (help engine) should go into
toolkit/components/help/. This is purely for code organizational reasons. 
2. I'm not seeing any jar manifests here (maybe you forgot to include them in
your patch), but I'm assuming from your contents.rdf file that this is being
packaged as a separate jar. That's good. The files from browser/components/help
and toolkit/components/help/ should go into the same jar, and same chrome
package. That way my requirement in (1) has no effect on your code at all (i.e.
it won't break anything).

So basically you will have:

toolkit/components/help/ ----+
                             +------>  help.jar (chrome://help/content/) 
browser/components/help/ ----+

This will allow Thunderbird to share your help engine, and provide its own help
resources folder under mail/components/help or wherever scott wants it to go. 

The plan once you've done that is to create a separate distribution XPI for
help, so that the in the Windows installer, things look like this:

* Easy Install - Everything, including Help
* Custom Install - Help is an option in the Component Selection page. 

For self-extracting archive installs, we will distribute the help XPI as part of
the bundle, but in the future I plan on reviving the net stub install, so it'll
be possible for seasoned users to shave a bit off their download size by using
the custom path. At that time I'll also have a scheme in place for the Help menu
items to offer to go off and download the XPI from the site if clicked. So very
little needs to be done by you at this point since your code is already factored
into an extension. Great!

A few review comments on what you do have however...

+        chrome:displayName="Help Viewer" chrome:author="mozilla.org"
+        chrome:name="help" chrome:localeVersion="0.6"
+        chrome:authorURL="http://www.mozilla.org/"
+        chrome:description="A port of the Mozilla Application Suite's Help
+            Viewer as a Browser extension."
+        chrome:extension="true"/>

displayName should be "Mozilla Firebird Help"
description "Online Help Documentation for the Mozilla Firebird browser"

don't set "extension" to "true"... as I've explained above it will be an
optional component but not something that can be configured through the
extension UI. 

Also, I'll get you to replace every use of the word "Mozilla Firebird" with a
reference to &brandShortName; which can be loaded from
chrome://global/locale/brand.dtd ... We're try to keep repetition of string
usage down in case we want to shorten usage to just "Firebird" etc.

I haven't looked at the actual content of the help system but am less concerned
about that right now as I am about just having this great feature checked in. 

Let me know when you've revised your patch, and I'll test it here to make sure
everything is in order. 

Thanks a lot!!

Comment 39

[R.J. Keller]

> 2. I'm not seeing any jar manifests here (maybe you forgot to include them in
> your patch), but I'm assuming from your contents.rdf file that this is being
> packaged as a separate jar. That's good. The files from browser/components/help
> and toolkit/components/help/ should go into the same jar, and same chrome
> package. That way my requirement in (1) has no effect on your code at all (i.e.
> it won't break anything).

Do you mean jar.mn files? Maybe I forgot to put them in the patch. They should
be there. Sorry about that.

> So basically you will have:
> 
> toolkit/components/help/ ----+
>                              +------>  help.jar (chrome://help/content/) 
> browser/components/help/ ----+

Excellent idea! sounds good! Should be very easy. I could have the same Makefile
with different jar.mn files, and it should work out very well.

> displayName should be "Mozilla Firebird Help"
> description "Online Help Documentation for the Mozilla Firebird browser"
> 
> don't set "extension" to "true"... as I've explained above it will be an
> optional component but not something that can be configured through the
> extension UI. 

OK, sure!

> Also, I'll get you to replace every use of the word "Mozilla Firebird" with a
> reference to &brandShortName; which can be loaded from
> chrome://global/locale/brand.dtd ... We're try to keep repetition of string
> usage down in case we want to shorten usage to just "Firebird" etc.

This should be already done. I'm not sure how old of a version of Firebird Help
that I attached in the patch. I'm having a problem with making &brandShortName;
work in the help RDF. Not sure how I'll fix that, but don't think it's a huge
issue right now.

> I haven't looked at the actual content of the help system but am less concerned
> about that right now as I am about just having this great feature checked in. 
> 
> Let me know when you've revised your patch, and I'll test it here to make sure
> everything is in order. 

Great! I'll post the new patch soon.

Comment 40

[Ben Goodger (use ben at mozilla dot org for email)]

Last call for the new patch. 0.8 train is getting ready to leave the station. 

R.J. - by hook or by crook I'm getting 0.8 out the door this year. This lands
this week, or it may not land at all for this release. 

Comment 41

[alanjstr]

-> Extension bundle per Ben in comment 38

Comment 42

[R.J. Keller]

--> Firebird 0.9

I'm not going to have time to apply the changes until at least Saturday of this
week.

Comment 43

[R.J. Keller]

Attachment: Help Viewer with Ben's Comments

This patch contains all of Ben's comments. Also fixes some JavaScript errors I
found and lots of documentation errors fixed. The glossary has been shrunk to
contain only definitions useful to the user, along with other enhancements.

I've done a LOT of debugging on this patch, so there shouldn't be any bugs.

Comment 44

[Ben Goodger (use ben at mozilla dot org for email)]

I'm pulling a tree to test this in now...

Comment 45

[Ben Goodger (use ben at mozilla dot org for email)]

Comment on attachment 137760 [details] [diff] [review]
Help Viewer with Ben's Comments

OK. I think we should get this in the tree now. If there are any problems it'll
be easier to work them out once this is checked in.

Comment 46

[R.J. Keller]

Patch checked in!

phew!

Comment 47

[u60234]

The images seems to be missing though. 

Comment 48

[Jon Henry]

The build appears to be busted with this latest checkin...

+++ making chrome /cygdrive/c/MozillaRoot/firebird/toolkit/components/help  => .
./../../dist/bin/chrome/help.jar
+++ adding chrome ../../../dist/bin/chrome/installed-chrome.txt
+++     content,install,url,jar:resource:/chrome/help.jar!/content/help/
error: file '/cygdrive/c/MozillaRoot/mozilla/toolkit/components/help/skin/conten
ts.rdf' doesn't exist at /cygdrive/c/MozillaRoot/mozilla/config/make-jars.pl lin
e 385, <STDIN> line 10.
make[5]: *** [libs] Error 2
make[5]: Leaving directory `/cygdrive/c/MozillaRoot/firebird/toolkit/components/
help'
make[4]: *** [libs] Error 2
make[4]: Leaving directory `/cygdrive/c/MozillaRoot/firebird/toolkit/components'

Comment 49

[Bob Clary [:bc] (inactive)]

I still get an error building:

+++ making chrome
/cygdrive/c/work/mozilla_source/trunk/mozilla/obj-i586-pc-msvc-firebird-release/toolkit/components/help
 => ../../
../dist/bin/chrome/help.jar
+++ adding chrome ../../../dist/bin/chrome/installed-chrome.txt
+++     content,install,url,jar:resource:/chrome/help.jar!/content/help/
+++ adding chrome ../../../dist/bin/chrome/installed-chrome.txt
+++     skin,install,url,jar:resource:/chrome/help.jar!/skin/help/
error: file
'/cygdrive/c/work/mozilla_source/trunk/mozilla/toolkit/components/help/locale/en-US/contents.rdf'
doesn't exist at
/cygdrive/c/work/mozilla_source/trunk/mozilla/config/make-jars.pl line 385, 

The contents.rdf is really at toolkit/components/help/locale/en-US/help/contents.rdf

Comment 50

[R.J. Keller]

bc: I checked in the fix to this problem early this morning.

Comment 51

[Bob Clary [:bc] (inactive)]

I did a fresh check out and build and get the same error.

Comment 52

[Daniel Wang]

I'm looking at 20040102 build of MF and I don't see any Help

Comment 53

[Hussam Al-Tayeb]

Re: Comment #52

that's because the help is only implemented in the trunk and not the branch

Comment 54

[matsuba]

http://lxr.mozilla.org/mozilla/source/browser/components/help/locale/en-US/firebird-index1.rdf#68

I think there is a typo in this line.

nc:name="Cache" -> nc:name="Cookies"

Comment 55

[Simon Paquet [:sipaq]]

verified fixed on trunk.

Comment 56

[Hussam Al-Tayeb]

when will this be added to the installer builds?

Comment 57

[R.J. Keller]

see bug 240277