XUL reference migration plan
Deb Richardson
migrated into the MDC wiki, so I spent some time today digging through the
existing reference to figure out a good way of going about this. Here are
my initial notes, your feedback/thoughts/corrections would be very
appreciated:
Root page: "XUL reference"
Alternate root page: "XUL quick reference"
* XUL elements (page name prefix - XUL:Element:*)
Page structure
* Summary
* Implemented interfaces
* Attributes
* Properties
* Methods
* Examples
* XUL tutorial links
* Further information and resources
* XUL attributes (page name prefix - XUL:Attribute:*)
* One attribute per page, to be included in other pages as templates.
* XUL properties (page name prefix - XUL:Property:*)
* One property per page, to be included in other pages as templates.
* XUL methods (page name prefix - XUL:Method:*)
* One method per page, to be included in other pages as templates.
* Other XUL reference templates (titles and template names can be changed)
* "Attributes inherited from XUL element"
(Template:XULElementAttributes)
* "Properties and methods inherited from XUL element"
(Template:XULElementPropertiesAndMethods)
* "Properties and methods inherited from Element"
(Template:ElementPropertiesAndMethods)
* XBL elements (page name prefix - XBL:Element:*)
Page structure
* Summary
* Implemented interfaces
* Attributes
* Properties
* Methods
* Examples
* Further information and resources
* XBL attributes (page name prefix - XBL:Attribute:*)
* One attribute per page, to be included in other pages as templates.
* Built-in datasources (page name prefix - RDF:*)
* One RDF per page, as in the current XUL Ref.
I didn't go through every single page and element for these so I may have
missed some things. Please post if you have a better idea of how things
might be done. Thanks :)
~ deb
Nickolay Ponomarev
> * XUL elements (page name prefix - XUL:Element:*)
> Page structure
> * Summary
> * Implemented interfaces
> * Attributes
> * Properties
> * Methods
> * Examples
> * XUL tutorial links
> * Further information and resources
attributes/methods/properties docs on that page.
How are we going to separate common XUL and element-specific
attributes/properties/methods?
Otherwise the overall structure of the page looks sane, but we need to
create one such page and agree on its layout before migrating the
reference.
> * XUL attributes (page name prefix - XUL:Attribute:*)
> * One attribute per page, to be included in other pages as templates.
>
> * XUL properties (page name prefix - XUL:Property:*)
> * One property per page, to be included in other pages as templates.
>
> * XUL methods (page name prefix - XUL:Method:*)
> * One method per page, to be included in other pages as templates.
>
I'm not sure what is the point of creating a page for each property
and method. In most cases we'll end up with pages like this one:
http://developer.mozilla.org/en/docs/XPath:Axes:ancestor
Another issue I have with this naming scheme is that in XUL many
attributes/properties/methods are element-specific.
I'm in favor of copying XUL Planet's structure in this regard.
> * Other XUL reference templates (titles and template names can be changed)
> * "Attributes inherited from XUL element"
> (Template:XULElementAttributes)
> * "Properties and methods inherited from XUL element"
> (Template:XULElementPropertiesAndMethods)
> * "Properties and methods inherited from Element"
> (Template:ElementPropertiesAndMethods)
>
I think it's pointless to discuss the templates we'll use without the
example pages demonstrating the layout and format for all types of
pages in the reference.
> * XBL elements (page name prefix - XBL:Element:*)
That's not a part of XUL reference, so I suggest we discuss it
separately. Note that we already have an XBL reference which has
recently received much attention from Martijn and V K. I'd rather we
not create a second veresion of the XBL reference.
> * Built-in datasources (page name prefix - RDF:*)
> * One RDF per page, as in the current XUL Ref.
>
That's not a part of XUL reference either, and I think some
datasources, such as rdf:bookmarks are not even a part of the
platform.
Also, I'm not sure, but the datasource names might be case-sensitive.
In that case we want them named all lowercase, e.g.
[[rdf:window-mediator]].
Nickolay
Pete Morgan
> There's quite a lot of interest in getting the XULPlanet XUL reference
> migrated into the MDC wiki, so I spent some time today digging through the
> existing reference to figure out a good way of going about this. Here are
> my initial notes, your feedback/thoughts/corrections would be very
> appreciated:
Does this mean that this http://www.mozilla.org/xpfe/xulref/ is
redundant. The bit I like about it is the summary of elements on the
left frame .. eg tabs and trees list all the elements on the one page
>
> Root page: "XUL reference"
> Alternate root page: "XUL quick reference"
http://xulplanet.com/references/elemref/quickref.html but without the
attributes and properties
IMHO.. I would stick to short eg XUL.align, XUL.tabbox.
If there is a clash, then the disambiguation will kick in and as u
pointed out in your research there will be very few clashes imho.. eg
XUL:popup !
Also .attributes and .properties are almost one and the same !!
Indeed aren't some of the methods already in DOM:* space .. eg here are
links
http://developer.mozilla.org/en/docs/XUL_Tutorial:Modifying_a_XUL_Interface
I would also like to see quite a few javascript examples that go along
with each element.. eg addChild() and since these are shared amongst a
lot of elements it could be in a template eg Template:XUL:addChild()
Within the XUL Tutorial I've linked to some DOM bits eg on this page
appendItem()
http://developer.mozilla.org/en/docs/XUL_Tutorial:Modifying_a_XUL_Interface
However I'm not sure where some of the elements here
http://developer.mozilla.org/en/docs/XUL_Tutorial:Manipulating_Lists
would point to.. XUL:* or DOM:*
Would we also want to put links to the XUL tutorial ? maybe at the
bottom with ==see also== (I love wiki)
And this is cool .. like it a lot
http://www.mozilla.org/docs/xul/xulnotes/xulnote_cheatsheet.html real
cut and paste stuff. maybe this should be integrated..
On a tangent slightly .. it would be nice to have the XUL reference in
XUL. Here's wip on the smarty manual .. note the tree on the left is xul
http://smarty.daffodil.uk.com/xul_dev/xul_index.php
my happeny's worth .
pete :-)
Axel Hecht
They are case-sensitive.
Axel
Nickolay Ponomarev
> Does this mean that this http://www.mozilla.org/xpfe/xulref/ is
> redundant. The bit I like about it is the summary of elements on the
> left frame .. eg tabs and trees list all the elements on the one page
It's outdated and is redundant because of XUL Planet's well-maintained
reference already.
> As to creating XUL:foo.bar for each element/attribute.. its too long
> IMHO.. I would stick to short eg XUL.align, XUL.tabbox.
> If there is a clash, then the disambiguation will kick in and as u
> pointed out in your research there will be very few clashes imho.. eg
> XUL:popup !
>
You might as well call it just [[align]] and [[tabbox]] then. The
reason we don't do it is that we try to use predicatble names for
pages and your suggestion makes it hard to guess where a particular
page might be located.
Anyways as I said earlier, I believe the correct solution here is to
create one page per element (and not for attributes and properties).
> Also .attributes and .properties are almost one and the same !!
They aren't, and we want people to understand the difference.
http://www.xulplanet.com/ndeakin/article/290/
> Indeed aren't some of the methods already in DOM:* space .. eg here are
> links
> http://developer.mozilla.org/en/docs/XUL_Tutorial:Modifying_a_XUL_Interface
The methods discussed there are part of DOM core. All XUL elements are
DOM elements and support all methods/properties on the DOM Element
(and Node) interfaces. There are also XUL-specific methods and
attributes, which we probably will document in the XUL reference, even
though it is part of (non-W3C) DOM strictly speaking.
> I would also like to see quite a few javascript examples that go along
> with each element.. eg addChild() and since these are shared amongst a
> lot of elements it could be in a template eg Template:XUL:addChild()
>
There's no addChild method in XUL. appendChild is part of DOM Core,
appendItem is XUL-specific method available on <listbox> and some
other elements.
Also, it's hard to write a short JS example dealing with DOM that
makes sense. You can look at the DOM reference pages to see what I
mean. Because of this I'm not sure if adding script examples to the
reference is a good idea in general.
> On a tangent slightly .. it would be nice to have the XUL reference in
> XUL. Here's wip on the smarty manual .. note the tree on the left is xul
> http://smarty.daffodil.uk.com/xul_dev/xul_index.php
>
XUL is nice, but it's not appropriate for public sites. You wouldn't
be able to use an alternative browser to view such sites, which is
pretty bad.
Nickolay
Mike Shaver
> > As to creating XUL:foo.bar for each element/attribute.. its too long
> > IMHO.. I would stick to short eg XUL.align, XUL.tabbox.
> > If there is a clash, then the disambiguation will kick in and as u
> > pointed out in your research there will be very few clashes imho.. eg
> > XUL:popup !
> >
> reason we don't do it is that we try to use predicatble names for
> pages and your suggestion makes it hard to guess where a particular
> page might be located.
With disambiguation pages in place for the cases in which XUL itself
has naming clashes between attribute and element names, for example, I
don't think it's hard to guess where the vast majority of cases will
be located. Having people who are guessing page names bounce off of a
disambig page for a single (?) XUL case seems quite bearable, and a
very different situation from that which we'd have by using naked
[[align]] -- and thereby clashing with HTML and who knows what else.
This is similar to the way we will use [[Components object]] but not
[[Components.classes object]] for the JS Components.* documentation.
There's a good rule that gives a natural disambiguation for virtually
all cases, and we deal with the remaining ones individually, rather
than making every page bear ugly additional hierarchy in its name.
Nobody who types in [[XUL:popup]] will be frustrated or upset that
they have to say which popup they mean, I'm quite confident. On the
other hand, having to know which element (or "abstract" element, as
with the Element "base class") an attribute is on to find
documentation seems to work against the common use case of someone not
knowing exactly where in the hierarchy such an attribute is.
(I haven't yet thought in any great detail about the specific layout
proposed by Deb, but I wanted to comment on this philosophical point
anyway.)
Mike
Nickolay Ponomarev
> This is similar to the way we will use [[Components object]] but not
> [[Components.classes object]] for the JS Components.* documentation.
> There's a good rule that gives a natural disambiguation for virtually
> all cases, and we deal with the remaining ones individually, rather
> than making every page bear ugly additional hierarchy in its name.
>
> Nobody who types in [[XUL:popup]] will be frustrated or upset that
> they have to say which popup they mean, I'm quite confident. On the
> other hand, having to know which element (or "abstract" element, as
> with the Element "base class") an attribute is on to find
> documentation seems to work against the common use case of someone not
> knowing exactly where in the hierarchy such an attribute is.
>
I can agree if you're only talking about common XUL attributes/etc.
(Though I don't quite understand your point here, as those who have to
type in the page names - editors - can be assumed to know a little bit
about the structure of the wiki.)
If you think element-specific stuff should be at
[[XUL:<element-specific property>]] too, then why don't we make all
our references follow this naming scheme, e.g. [[DOM:getElementById]],
[[DOM:firstChild]], [[JS:replace]]? Or maybe simply [[getElementById]]
like what JesseW has been doing. I believe this is the wrong way to go
and thought we all felt the same about this.
Anyways, I think we should first decide if we want documentation for
each attribute be on a separate page. It appears that everyone
silently assumes this decision has already been made.
Nickolay
Deb Richardson
> Anyways, I think we should first decide if we want documentation for
> each attribute be on a separate page. It appears that everyone
> silently assumes this decision has already been made.
>
The reason I suggested that each attribute, property, and method to have its
own page is because it appears that some (many) of them are common to
multiple elements (some are common to all elements, I believe). I figured
that having each on its own page would allow us to include them in the
element pages via the {{:Foo}} syntax so we would only have to maintain one
instance of each instead of having to change each element page its used on,
should it need changing.
Now, if there are a small number of possible namespace collisions between
elements, attributes, properties, and methods, I concede that the second
prefix (ie: Element/Attribute/etc) for the page naming is unnecessary and we
can simply disambiguate the few that do exist.
~ deb
Pete Morgan
page as a tempate
http://xulplanet.com/references/elemref/ref_XULElement.html
Common to all elements
Whilst we might end up with one pages.. we can also expand on each
property..
If we get thsi right we should have a set of templates intact
and btw I seen a tempate recoently
{{cssxref|foo}}
are we gonna do the same ?
pete
Deb Richardson
> and btw I seen a tempate recoently
> {{cssxref|foo}}
> are we gonna do the same ?
>
We certainly could. It's a very simple template to create.
~ deb
Nickolay Ponomarev
>
> > Anyways, I think we should first decide if we want documentation for
> > each attribute be on a separate page. It appears that everyone
> > silently assumes this decision has already been made.
> >
>
> The reason I suggested that each attribute, property, and method to have its
> own page is because it appears that some (many) of them are common to
> multiple elements
description (other than these:
http://xulplanet.com/references/elemref/ref_XULElement.html )
> (some are common to all elements, I believe).
Those can just be listed on a separate page, which can then be
included in all other element pages.
> I figured
> that having each on its own page would allow us to include them in the
> element pages via the {{:Foo}} syntax so we would only have to maintain one
> instance of each instead of having to change each element page its used on,
> should it need changing.
>
That's true, but note that this makes it harder for random people to
edit the page's text. You can see [edit this template] links on
wikipedia for this reason. On the other hand if we add an edit link
for each included attribute, it would look ugly and make later mass
page moves ;-) harder.
> Now, if there are a small number of possible namespace collisions between
> elements, attributes, properties, and methods, I concede that the second
> prefix (ie: Element/Attribute/etc) for the page naming is unnecessary and we
> can simply disambiguate the few that do exist.
>
How does it work with attributes vs properties? You'll have a lot
"collisions" in that area, and I argue we need to make the distinction
between them clear.
Nickolay
Mike Shaver
> > The reason I suggested that each attribute, property, and method to have its
> > own page is because it appears that some (many) of them are common to
> > multiple elements
>
> I don't think there are *many* such attributes with nontrivial
> description (other than these:
> http://xulplanet.com/references/elemref/ref_XULElement.html )
Can someone do a census? That would be better than having us each
guess differently. (Pete?)
> > (some are common to all elements, I believe).
>
> Those can just be listed on a separate page, which can then be
> included in all other element pages.
We could do that if we always wanted to include them in the same
order, which I think that we don't. Specifically, I think that we'll
want to sort all the entries for a given element in a unified order,
not as two lists (inherited vs. not -- or worse, one list for each of
the superclasses!).
When someone is looking at the page for a given element, they don't
really care *why* it has a given method (as in, where in the
inheritance hierarchy it comes from), they just want to be able to
find out about it.
I think we want to have two sorted lists, one for methods and the
other for attributes+properties.
> > I figured
> > that having each on its own page would allow us to include them in the
> > element pages via the {{:Foo}}
>
> That's true, but note that this makes it harder for random people to
> edit the page's text. You can see [edit this template] links on
> wikipedia for this reason. On the other hand if we add an edit link
> for each included attribute, it would look ugly and make later mass
> page moves ;-) harder.
(Editing "composite" pages needs help, it's true. That seems to be
something that would help a *lot* of use cases, and so I think we
should probably start a separate thread to discuss how we might make
that work better.
Templates have much virtue for us, especially in reducing the effort
required to maintain content or structure that can be usefully
presented in multiple places. The upcoming <includeonly> and
<noinclude> support will make them even more useful, so we should
figure this case out.
Wanna start a thread? Thanks! :) )
> How does it work with attributes vs properties? You'll have a lot
> "collisions" in that area, and I argue we need to make the distinction
> between them clear.
Attribute and property collisions are inherent, because they're named
in many cases _to_ collide. They're not coincidental collisions,
other than a few exceptions, but instead are different aspects of the
same XUL "thing".
You know, because you linked to Neil's article, that people are often
confused about whether they want to use the property or the attribute.
I think we do them a greater service by making sure that they see
"this is a property _and_ an attribute, click here for more
information on the difference" when they go looking for information on
"align".
As I discovered while trying Neil's patience in IRC, there are some
things here that may complicate this, such as differences in case
between attribute and property name, or the handful of cases in which
the attributes specify initial or default state, and the property
reflects the dynamic state. We should figure out what distinctions we
want to make clear here, and what the user is likely to expect and to
already know, and how we can help them better understand the
attribute-vs-property gotchas.
That might mean that we coalesce attribute and property descriptions
where they reflect each other fully, or where there are small
differences ("true" vs true) that can be summarized concisely. It
might mean that we keep the descriptions separate and heavily
cross-link between attributes and associated properties.
I have some ideas in my head for a mockup, but I won't have a chance
to get to them for a bit. They involve little icons for property or
attribute (or both) in the list of fields, but the aforementioned
census would help a lot in figuring out what the collision cases are
and whether we should just one-off the hard ones.
Mike
Nickolay Ponomarev
> On 4/26/06, Nickolay Ponomarev <asqu...@gmail.com> wrote:
> > > (some are common to all elements, I believe).
> >
> > Those can just be listed on a separate page, which can then be
> > included in all other element pages.
>
> We could do that if we always wanted to include them in the same
> order, which I think that we don't. Specifically, I think that we'll
> want to sort all the entries for a given element in a unified order,
> not as two lists (inherited vs. not -- or worse, one list for each of
> the superclasses!).
>
> When someone is looking at the page for a given element, they don't
> really care *why* it has a given method (as in, where in the
> inheritance hierarchy it comes from), they just want to be able to
> find out about it.
>
certainly not true for me personally.
While it is useful in some situations to have the complete sorted
listing of attributes for a particular XUL element, I often need to
find something I know is specific to some element. In that case it's
easier to scan the short list of element-specific attributes.
> I think we want to have two sorted lists, one for methods and the
> other for attributes+properties.
>
Combining the lists of attributes and properties seems a bad idea to
me for two reasons:
1) Properties and attributes are not the same (and there's no
one-to-one mapping between them);
2) You need the attributes reference when you write XUL code, and the
properties+methods reference when writing scripts.
> > > I figured
> > > that having each on its own page would allow us to include them in the
> > > element pages via the {{:Foo}}
> >
> > That's true, but note that this makes it harder for random people to
> > edit the page's text. You can see [edit this template] links on
> > wikipedia for this reason. On the other hand if we add an edit link
> > for each included attribute, it would look ugly and make later mass
> > page moves ;-) harder.
>
> (Editing "composite" pages needs help, it's true. That seems to be
> something that would help a *lot* of use cases, and so I think we
> should probably start a separate thread to discuss how we might make
> that work better.
>
> Templates have much virtue for us, especially in reducing the effort
> required to maintain content or structure that can be usefully
> presented in multiple places. The upcoming <includeonly> and
> <noinclude> support will make them even more useful, so we should
> figure this case out.
>
> Wanna start a thread? Thanks! :) )
>
I'm afraid I don't have any good suggestions yet.
This is my only (I think!) problem with making heavy use of page
includes, but I would not like to see them used much until this issue
is resolved or at least until we have an idea how it's going to be
fixed.
> > How does it work with attributes vs properties? You'll have a lot
> > "collisions" in that area, and I argue we need to make the distinction
> > between them clear.
>
> Attribute and property collisions are inherent, because they're named
> in many cases _to_ collide. They're not coincidental collisions,
> other than a few exceptions, but instead are different aspects of the
> same XUL "thing".
>
> You know, because you linked to Neil's article, that people are often
> confused about whether they want to use the property or the attribute.
> I think we do them a greater service by making sure that they see
> "this is a property _and_ an attribute, click here for more
> information on the difference" when they go looking for information on
> "align".
>
> That might mean that we coalesce attribute and property descriptions
> where they reflect each other fully, or where there are small
> differences ("true" vs true) that can be summarized concisely. It
> might mean that we keep the descriptions separate and heavily
> cross-link between attributes and associated properties.
>
> I have some ideas in my head for a mockup, but I won't have a chance
> to get to them for a bit. They involve little icons for property or
> attribute (or both) in the list of fields, but the aforementioned
> census would help a lot in figuring out what the collision cases are
> and whether we should just one-off the hard ones.
>
This information would make sense on the separate
per-attribute/property page, yes.
I'm not yet convinced we should have a "real" page (i.e. categorized
and linked to, not just included into other pages) for each attribute.
It is because I'm afraid they will be too short to be useful. Check
out http://developer.mozilla.org/en/docs/XPath:Axes:descendant-or-self
to see what I mean.
Nickolay
P.S. I would appreciate it if you answered my questions about the
naming for per-page attributes as well. I don't understand why the
naming shouldn't be consistent with the DOM reference.
Mike Shaver
> On 4/27/06, Mike Shaver <mike....@gmail.com> wrote:
> > When someone is looking at the page for a given element, they don't
> > really care *why* it has a given method (as in, where in the
> > inheritance hierarchy it comes from), they just want to be able to
> > find out about it.
>
> find something I know is specific to some element. In that case it's
> easier to scan the short list of element-specific attributes.
Yes, I think we should have a way to JS/CSS hide inherited stuff (here
and in XPCOM interfaces and such). I think that search results and
such will be better with them unified, but narrowing to a given
most-derived object/class/etc. is indeed a useful thing to permit.
> 2) You need the attributes reference when you write XUL code, and the
> properties+methods reference when writing scripts.
Indeed, this was something that I mentioned in a conversation with Deb
and Eric the other day. The XUL Reference covers both "HTML-like
markup" and "DOM-like objects and methods", as we use the term.
So it might be that we want to talk about the markup and the
manipulations separately, to split along the questions "how do I
construct this interface model?" and "how do I do this thing to my
interface model?".
I've been convinced that merging attrs+props isn't likely to be
helpful, as I had originally thought. Thanks to you and Neil for
helping me work through that understand that!
> This is my only (I think!) problem with making heavy use of page
> includes, but I would not like to see them used much until this issue
> is resolved or at least until we have an idea how it's going to be
> fixed.
It seems to me that if we have a big problem with template editing, we
can use a bot to flatten the pages. For now, it seems like having
"micropages" for inherited/reused attr/prop/meth descriptions.
> I'm not yet convinced we should have a "real" page (i.e. categorized
> and linked to, not just included into other pages) for each attribute.
> It is because I'm afraid they will be too short to be useful. Check
> out http://developer.mozilla.org/en/docs/XPath:Axes:descendant-or-self
> to see what I mean.
If it's not useful to have the sub-articles linked and categorized,
then we just won't do that. Not sure what that has to do with the
structural issue at hand. Given that there seem to be a number of
organizational approaches here that could be usefully attempted, it
seems like building a micropage for each attr/prop/meth will let us
unleash the migrating power of p_mash without committing ourselves to
a final structure. Should we want to put all the "common bits" into a
single page and then include that, we can easily-enough build that
XULElementBase page from these micropages, f.e.
(I could see even see a similarly short page for a XUL attribute or
property being useful if decorated with <noinclude> bits about which
elements it can be found on, etc.)
> P.S. I would appreciate it if you answered my questions about the
> naming for per-page attributes as well. I don't understand why the
> naming shouldn't be consistent with the DOM reference.
I don't have a strong opinion here, so I don't really have any answer
to give. Superficially, I tend to prefer consistency (if only because
it's a form of "design reuse"), but I haven't thought about the naming
proposals enough to develop a useful position.
Mike
Pete Morgan
>> properties+methods reference when writing scripts.
>
> Indeed, this was something that I mentioned in a conversation with Deb
> and Eric the other day. The XUL Reference covers both "HTML-like
> markup" and "DOM-like objects and methods", as we use the term.
>
> So it might be that we want to talk about the markup and the
> manipulations separately, to split along the questions "how do I
> construct this interface model?" and "how do I do this thing to my
> interface model?".
>
> I've been convinced that merging attrs+props isn't likely to be
> helpful, as I had originally thought. Thanks to you and Neil for
> helping me work through that understand that!
Am a bit confused where the line is between DOM:* pages and XUL
eg there's http://developer.mozilla.org/en/docs/DOM:document.getElementById
and lots of other properties/methods used by XUL.
So will addChild be in the DOM: or XUL: section
>
>> This is my only (I think!) problem with making heavy use of page
>> includes, but I would not like to see them used much until this issue
>> is resolved or at least until we have an idea how it's going to be
>> fixed.
>
> It seems to me that if we have a big problem with template editing, we
> can use a bot to flatten the pages. For now, it seems like having
> "micropages" for inherited/reused attr/prop/meth descriptions.
>
I think that templates are a good idea.. however it will be repeating
the same shared/common stuff on each page .. as in this mockup page
which shows all the common elements and has 4 included templates
http://developer.mozilla.org/en/docs/Sandbox:XUL:XUL_Element
>> I'm not yet convinced we should have a "real" page (i.e. categorized
>> and linked to, not just included into other pages) for each attribute.
>> It is because I'm afraid they will be too short to be useful. Check
>> out http://developer.mozilla.org/en/docs/XPath:Axes:descendant-or-self
>> to see what I mean.
>
> If it's not useful to have the sub-articles linked and categorized,
> then we just won't do that. Not sure what that has to do with the
> structural issue at hand. Given that there seem to be a number of
> organizational approaches here that could be usefully attempted, it
> seems like building a micropage for each attr/prop/meth will let us
> unleash the migrating power of p_mash without committing ourselves to
> a final structure. Should we want to put all the "common bits" into a
> single page and then include that, we can easily-enough build that
> XULElementBase page from these micropages, f.e.
I would favour keeping each on a separate page as it will make it
easier to link. Most will want some examples etc
>
> (I could see even see a similarly short page for a XUL attribute or
> property being useful if decorated with <noinclude> bits about which
> elements it can be found on, etc.)
>
>> P.S. I would appreciate it if you answered my questions about the
>> naming for per-page attributes as well. I don't understand why the
>> naming shouldn't be consistent with the DOM reference.
>
Indeed whether some of the stuff is on DOM
Pete mash
Deb Richardson
discussion and what's still in question?
~ deb
Nickolay Ponomarev
> On 4/29/06, Nickolay Ponomarev <asqu...@gmail.com> wrote:
> > On 4/27/06, Mike Shaver <mike....@gmail.com> wrote:
> > > When someone is looking at the page for a given element, they don't
> > > really care *why* it has a given method (as in, where in the
> > > inheritance hierarchy it comes from), they just want to be able to
> > > find out about it.
> >
> > listing of attributes for a particular XUL element, I often need to
> > find something I know is specific to some element. In that case it's
> > easier to scan the short list of element-specific attributes.
>
> Yes, I think we should have a way to JS/CSS hide inherited stuff (here
> and in XPCOM interfaces and such). I think that search results and
> such will be better with them unified, but narrowing to a given
> most-derived object/class/etc. is indeed a useful thing to permit.
>
also useful, at least in case of the DOM reference (if we ever get to
cleaning it up).
> > 2) You need the attributes reference when you write XUL code, and the
> > properties+methods reference when writing scripts.
>
> Indeed, this was something that I mentioned in a conversation with Deb
> and Eric the other day. The XUL Reference covers both "HTML-like
> markup" and "DOM-like objects and methods", as we use the term.
>
> So it might be that we want to talk about the markup and the
> manipulations separately, to split along the questions "how do I
> construct this interface model?" and "how do I do this thing to my
> interface model?".
>
Unfortunately it's not that easy. Sometimes you have to manipulate the
attributes from the script.
> I've been convinced that merging attrs+props isn't likely to be
> helpful, as I had originally thought. Thanks to you and Neil for
> helping me work through that understand that!
>
Are you talking about the listings on the element pages only or also
about merging the attribute/property pages themselves?
> > This is my only (I think!) problem with making heavy use of page
> > includes, but I would not like to see them used much until this issue
> > is resolved or at least until we have an idea how it's going to be
> > fixed.
>
> It seems to me that if we have a big problem with template editing, we
> can use a bot to flatten the pages.
I don't see how running a bot will help without sacrificing the
initial idea of avoiding text duplication.
> > I'm not yet convinced we should have a "real" page (i.e. categorized
> > and linked to, not just included into other pages) for each attribute.
> > It is because I'm afraid they will be too short to be useful. Check
> > out http://developer.mozilla.org/en/docs/XPath:Axes:descendant-or-self
> > to see what I mean.
>
> If it's not useful to have the sub-articles linked and categorized,
> then we just won't do that. Not sure what that has to do with the
> structural issue at hand.
Nevermind. I was thinking that if making use of page-includes is just
an implementation detail, then it's not important how those auxiliary
pages are named.
There's the problem of linking to a particular attribute. Imagine an
element page with two attributes with descriptions included from
micropages. Imagine that the description of the first attribute needs
to link to the other attribute. If we decide to create "real"
sub-articles, then the link should point to the sub-article. Otherwise
it should point to an anchor on the element page. That's not a major
problem and it can be solved via ugly hacks involving includeonly and
noinclude, but it's something to keep in mind.
> Given that there seem to be a number of
> organizational approaches here that could be usefully attempted, it
> seems like building a micropage for each attr/prop/meth will let us
> unleash the migrating power of p_mash without committing ourselves to
> a final structure. Should we want to put all the "common bits" into a
> single page and then include that, we can easily-enough build that
> XULElementBase page from these micropages, f.e.
>
I'm ok with that, but this will mean more energy will have to be spent
on the reference later when we figure out what we want from it.
> (I could see even see a similarly short page for a XUL attribute or
> property being useful if decorated with <noinclude> bits about which
> elements it can be found on, etc.)
>
Right, noinclude is useful.
> > P.S. I would appreciate it if you answered my questions about the
> > naming for per-page attributes as well. I don't understand why the
> > naming shouldn't be consistent with the DOM reference.
>
> I don't have a strong opinion here, so I don't really have any answer
> to give. Superficially, I tend to prefer consistency (if only because
> it's a form of "design reuse"), but I haven't thought about the naming
> proposals enough to develop a useful position.
>
I remembered why I am in favor of including the interface/class/object
name in the page name for a property doc. The primary reason (for me)
is that the name of the page should be the same as the name of the
entity the page documents. I feel that the correct name for methods on
interfaces has to include the name of the interface. This is why I
favor [[DOM:document.getElementById]] over [[DOM:getElementById]].
Fewer name clashes should be a consequence of this. It is also why I
was for dropping the "DOM:" prefix from the page names.
This might make no sense to you, but anyway..
Nickolay
Eric Shepherd
perhaps as an image map or a similar construct that people can browse
through and click on the various nodes to route to the documentation
for that particular interface?
This is often a popular way to learn the hierarchy of a system like
XUL, and can certainly offer a visually easy way to figure things out
fast.
Eric Shepherd
Technical Writer
she...@mozilla.com
Mike Shaver
> Why not create a graphical inheritance chart of all the interfaces,
> perhaps as an image map or a similar construct that people can browse
> through and click on the various nodes to route to the documentation
> for that particular interface?
>
> This is often a popular way to learn the hierarchy of a system like
> XUL, and can certainly offer a visually easy way to figure things out
> fast.
That sounds like a great enhancement, especially once we get the first
doxygen stuff working. So I have no answer to "why not?", but to
"why not now?" I think my answer would be "stick to basics until we
have a better sense of how we want to present the reference".
Mike
Deb Richardson
similar) table styling that's requested in bug 334225, or is this more
complex than that could handle?
https://bugzilla.mozilla.org/show_bug.cgi?id=334225
~ deb
> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
>
>
--
Deb Richardson