141350 - Gecko Embedding Basics tracking bug

Status: RESOLVED INVALID

(Developer Documentation Graveyard :: General, defect)

Description

[Ellen Evans]

Please file any questions, additions, errors, etc re: this document here.

Comment 1

[Ellen Evans]

Moz wrapper .css added unexpected bold to two pages.  Will do workaround.

Comment 2

[Håkan Waara]

Looks great!  Here are some humble suggestions:

* Add the TOC to the start page, as an overview of what the guide is about.
* Is this guide linked from mozilla.org/docs and mozilla.org/catalog? If not,
hook it up for public usage. Perhaps even post a note to the front page of
www.mozilla.org so people will notice this new document.
* From the XUL/XBL page, link to www.xulplanet.com ; their documentation is by
far better (and better up-to-date) than ours.

Comment 3

[Ellen Evans]

The TOC is easily available from the opening page, and this is traditionally how
we've done the docs.  It's certainly changeable, though, if there is a strong
feeling about it.  The only link in for the moment is from the embedding project
page, which is where most folks who might need this will probably be looking. 
The doc stuff is in the process of being reorganized and will probably link to
this as well. The XUL Planet suggestion is a good one.  I'll put it on my update
to do list.  Thanks.

Comment 4

[Aaron Leventhal]

Excellent job Ellen!

"Netscape and Mozilla both use XUL for their interfaces, but not all embedders
chose to use it."  

I think you want to say "choose" not "chose"

On page 12 - What Gecko Provides - most of the page is bold. Is that intentional?

If you want to include any information about our support for accessibility, or
our future plans, let me know. Most of the info is at
http://www.mozilla.org/projects/ui/accessibility

Comment 5

[Aaron Leventhal]

Couple more spelling errors on Page 16:
- View Manger
- things like platform specific event   [ missing an s in events ]

Comment 6

[Ellen Evans]

The bold on "What You Provide" and "What Gecko Provides" are the result of the
.css file on the mozilla.org wrapper.  I'm trying to work it out.

Comment 7

[Ellen Evans]

Bold problem fixed.  

Comment 8

[Mitchell Baker]

Ellen

One other thing I'd like to have is a list of interfaces that are frozen as of
Mozilla 1.0.  Not before, or not after.  In other words, a version of the doc
athttp://www.mozilla.org/projects/embedding/EmbedInterfaceFreeze.html
that is frozen as of the 1.0 release.  

James is willing to create this doc, but we don't want to duplicate effort if
you are working on this.  I apologize if you've had this discussion with James,
but can you let us know if you're working on this, or if there's any reason
James shouldn't plow ahead?

thanks

mitchell

Comment 9

[Ellen Evans]

Mitchell - 

There is the document at
http://mozilla.org/projects/embedding/embedapiref/embeddingapiTOC.html which is
a pretty good first cut at documenting the frozen interfaces as of 1.0.  Some
things haven't yet made it - the network stuff being the biggest chunk - but
they will be there in fairly short order.  It would be fairly simple to add some
sort of "frozen by <milestone>" to each of the interfaces if that would be
useful information.

James and I have exchanged emails about this - I was dismayed to hear he had
already put some time in on the work.  But it does seem as if it would be a
duplication of effort to have him develop his own cut at the APIs.

Thanks.

Ellen

Comment 10

[Mitchell Baker]

I think James will be OK, I'm glad we learned of your work before he got too far.   
Your suggestion of adding a "frozen@milestone" info might be helpful. Or is
there some easier way for a reader to tell if the referenced API has been frozen?

It doesn't sound like this suggestion would actually generate a list of APIs
frozen as of 1.0.  We've talked a great deal about Mozilla 1.0 being important
because of a set of APIs that are frozen and can be relied on.  I'd like to have
a list that says "and here is that set of APIs."  An LXR query won't do it once
additional APIs are frozen after 1.0 (or even frozen on the trunk before 1.0 is
released).  Am I missing some simple technique?


mitchell

Comment 11

[Ellen Evans]

I can just version a copy of the APIs I'm doing at 1.0 - that would be simple
enough.  But there are other APIs I'm not documenting - for example the DOM
stuff, which lives in a document Ian did.  Or any of the XUL/XBL stuff. 
Creating some sort of super-index of all of them would be one way to go to get a
_Frozen at 1.0_ set.  Would James be interested in doing that?

Another thing this whole experience brings up is the woeful state of
communication re: docs between mozilla and Netscape.  We probably need to come
up with a better way of trying to keep potential reduplication (and thus waste
of precious resources) at a minimum.  Ideas?

Comment 12

[Håkan Waara]

Well, we have the newsgroup netscape.public.mozilla.documentation ... that's a
good starting point for communication across boundaries. :-)

Comment 13

[rudman]

Ditto what Hakan said. 

We did have the Mozilla Documentation Project page, which was an attempt to
provide an infrastructure for establishing who was doing what. It didn't get
very far. And though the page still exists, it doesn't appear to be accessible
from any of the new Moz doc pages. 

Comment 14

[James Cox]

so now i know why i wasn't getting mail about this, *no-one* cc'ed me! :)

 -- james

Comment 15

[Andreas Fahrner]

Two humble suggestions:
* Replace graphic buttons with text.
* The logo "Gecko Embedding Basics" takes up much space. You could replace it by
a horizontal logo. This could sometimes prevent scrolling.

Comment 16

[Ellen Evans]

Added ref to XULPlanet

Comment 17

[Neil Becker]

on http://www.mozilla.org/projects/embedding/embedoverview/EmbeddingBasics9.html

old:

Web browsing typically involves a large amount of string manipulation. Mozilla
has developed a hierarchy of C++ classes to facilitate such manipulation and to
render it efficient and quick.

should be:

Web browsing (snip typically) involves...

... render it quickLY and efficientLY.

Comment 18

[Ellen Evans]

Actually, no.  "Quick and efficient" modifies "string manipulation" not
"render". The word render here means "make" not "draw on the screen"

Comment 19

[Aaron Leventhal]

Under common browser tasks, I think you should show people the declaration for
mWebBrowser, so they know what type it is. I haven't checked other areas of the
docs for the same problem.

//Create an instance of the Mozilla embeddable browser 
 
HRESULT CBrowserView::CreateBrowser()  
{ 
// Create a web shell  
nsresult rv; 
mWebBrowser =  
	do_CreateInstance(NS_WEBBROWSER_CONTRACTID, &rv); 
if(NS_FAILED(rv)) 
return rv; 

Comment 20

[Dave Fancella]

Ok, maybe I'm being really really picky, but I'm trying to embed Gecko into a
wxWindows-based application.  (With any luck, it'll result in the class wxGecko
:)  )

My development environment is Mandrake Linux 9.0, with the mandrake supplied
rpm's of mozilla 1.1.

I'm having a real hard time grokking how to embed Gecko.  In concept, it seems
simple enough, right?  Initialize XPCOM, make sure to terminate it.  So you
initialize it when the app starts, and you terminate it when the app terminates.

Problem is, what include files do I use?  How do I include the declarations for
the functions to initialize and terminate XPCOM, and what files do I include for
the nsWebBrowser interface (et al, it looks like that one will satisfy my needs)?

I ask, because as I'm sure you're aware, typically you have the .h files
somewhere in your include path, and you include the one you need.  Then the
linker sorts out where the functions/classes actually are.

Dave

Comment 21

[Ellen Evans]

Embedding Gecko is a somewhat more complex task that just dropping nsWebBrowser
into one's code.  As the document says, the best place to get an idea of what an
embedded browser might look like is 
mozilla.org/projects/embedding/examples/index.html, where an example from each
of the platforms is available.  Sample manifest files can be found in
mozilla/embedding/config.  

Comment 22

[Daniel Wang]

http://www.mozilla.org/projects/embedding/embedoverview/EmbeddingBasics4.html
update MRE link to www.mozilla.org/projects/embedding/GRE.html.

Comment 23

[Ellen Evans]

Updated to GRE link

Comment 24

[Paul Lacourse]

At the end of the page
http://www.mozilla.org/projects/embedding/embedoverview/EmbeddingBasics6.html
there's an '"' (doublequote) missing that make the author's e-mail address look
strange.

Here is a patch generated by doctor.mozilla.org

Index: mozilla-org/html/projects/embedding/embedoverview/EmbeddingBasics6.html
===================================================================
RCS file:
/cvsroot/mozilla-org/html/projects/embedding/embedoverview/EmbeddingBasics6.html,v
retrieving revision 1.8
diff -u -r1.8 EmbeddingBasics6.html
--- mozilla-org/html/projects/embedding/embedoverview/EmbeddingBasics6.html	7
Jul 2003 20:03:36 -0000	1.8
+++ mozilla-org/html/projects/embedding/embedoverview/EmbeddingBasics6.html	29
Jul 2003 18:19:36 -0000
@@ -120,7 +120,7 @@
 <a name="1000474"> </a>For more information<br>
 </div>
 <p class="Body">
-  <a name="1000479"> </a>More information on XPCOM in general can be found at
<a href="http://mozilla.org/projects/xpcom/">mozillla.org/projects/xpcom/</a>.
For an overview of creating XPCOM components, see Chapter 8 of O'Reilly's
<i>Creating Applications with Mozilla</i>, an open source version of which is
available at<a
href="http://books.mozdev.org/chapters/ch08.html">books.mozdev.org/chapters/ch08.html</a>.
There is also a new book completely devoted to this topic, <i>Creating XPCOM
Components</i>, available at <a
href="http://mozilla.org/projects/xpcom/book/cxc/>http://mozilla.org/projects/xpcom/book/cxc/</a>.
 A fuller explanation of some of the underlying logic to COM systems can be
found in the early chapters of <i>Essential COM</i> by Don Box. While it
focusses on MSCOM in particular, the book does provide an excellent background
on some of the core rationales for using such an object model.
+  <a name="1000479"> </a>More information on XPCOM in general can be found at
<a href="http://mozilla.org/projects/xpcom/">mozillla.org/projects/xpcom/</a>.
For an overview of creating XPCOM components, see Chapter 8 of O'Reilly's
<i>Creating Applications with Mozilla</i>, an open source version of which is
available at<a
href="http://books.mozdev.org/chapters/ch08.html">books.mozdev.org/chapters/ch08.html</a>.
There is also a new book completely devoted to this topic, <i>Creating XPCOM
Components</i>, available at <a
href="http://mozilla.org/projects/xpcom/book/cxc/">http://mozilla.org/projects/xpcom/book/cxc/</a>.
 A fuller explanation of some of the underlying logic to COM systems can be
found in the early chapters of <i>Essential COM</i> by Don Box. While it
focusses on MSCOM in particular, the book does provide an excellent background
on some of the core rationales for using such an object model.
 </p>
 </blockquote>

Comment 25

[Ellen Evans]

Fixed.

Thanks.

Comment 26

[Nickolay_Ponomarev]

The doc was moved into MDC wiki, so people can update it directly if needed.