87663 - Update and organize Gecko style system documentation

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: Mozilla Platform, enhancement, P3)

Description

[Bernd]

To my knowledge there is only one outdated document about the stylesystem from
'98. It hit me now the third time in a row that I cannot fix a table bug because
there is no documentation how the style system works. A good manual would
include: for instance I have property 'foo' that my tag 'bar' should inherit
from 'xxx': what is necessary to do?. Where can one set efficiently a break
point to see all the magics work e.g rule creation, walk rule, caching. 
In order to overcome the problem that real programmers dont write documentation
you also could make a brown bag video about style :-).

Comment 1

[John Morrison]

Yeah, hyatt! Why didn't you right any documentation in 1999/2000. And don't 
give me that XUL/XBL/XPToolkit excuse again!

Comment 2

[Hixie (not reading bugmail)]

If Netscape is to resolve this bug then Netscape should hire some tech 
writers...

Comment 3

[Bernd]

Hixie: unclear specs + unclear code basis = planned failure + less external
contribution

Comment 4

[Daniel Glazman (:glazou) (not active in Mozilla any more)]

I have to agree 100% with Bernd

Comment 5

[Hixie (not reading bugmail)]

Let me just be clear that I did not mean anything to be read in between the 
lines of what I wrote. I was being totally literal. If Netscape is going to
resolve this bug, then Netscape needs to hire some technical writers. Just like
every other company in the industry does.

I'm not at all saying that this bug should be marked WONTFIX or P5 or whatever.

Comment 6

[Bernd]

I disagree with you: I think star developers at the mozilla project should have
in mind stupid maintance programmers like me. It seems to me unefficient instead
of fixing the bugs to look where I can throw the hot potato.
I do not need several thousand of pages, just a cheat sheet like the one at
http://www.mozilla.org/newlayout/doc/block-and-line.html written by Chris
Waterson. This will probably take several hours from Marc for instance but I
think it is a good investment of his time, because with his assistance a lot of
small and hardworking ant's will kill the bugs. Whether this will be good for
netscape, I can not judge, but I do not see to many checkins fixing Hixie Px
bugs, so attracting some external help may be a good idea.

Your requirement postpones the solution of this issue, because you and I know
that probably mozilla 1.0 will be out before that tech writer is hired (netscape
 has proven over half a year that it is not able to find a replacement for
buster) Even if netscape is able to hire that woman/guy very soon, she/he will
face the same problem, because there is not even a starting point to write some
documentation. I asked both the assignee of the bug and Daniel about some help,
and they agreed that they have also have a problem with the doc. Writing this
kind of documentation is to my knowledge from other projects one of the most
efficient methods to discover subtle coding problems (see also bug 88735) and
this should do developers, who know the code. This cheat sheet should have been
written during the review process of the big style checkin, but it was not. Why
we need a different approach for style documenation than for string or XPCOM,
which has been done by developers in order to serve other developers.

I even do not expect to get the quality of scc's docs, but I see the structural
problem we have: we would like to build a CSS compatible browser and a core
component is style. Layout depends on style and this requires docu. 
I think the current situation is not tolerable and your solution is not the best
one for mozilla.


Hixie: as you might have seen, I am a veteran flamer, so may be we should stop
here and wait for Marc's solution of the bug.

Comment 7

[Hixie (not reading bugmail)]

I'm not trying to argue here. I'm stating facts. Netscape engineers are already
overburdened, they have bugs coming out the wazoo and managers breathing down
their necks to get their bug counts down. It's quite possible that at some point
Marc, Hyatt, Daniel, David or Waterson will write some documentation -- e.g., 
the cheat sheet that Chris has written or the cook books that Daniel has 
written. However, that isn't real documentation. It's useful, sure, and it would
get written independent of this bug existing. But it's not a substitute for 
what we need to get lots of contributors.

Comment 8

[rubydoo123]

Moving this to future for the time being.

Reporter: are you looking for documentation against the following?
http://lxr.mozilla.org/mozilla/source/content/base/src/nsStyleContext.cpp
http://lxr.mozilla.org/mozilla/source/content/base/src/nsStyleContextDebug.cpp
http://lxr.mozilla.org/mozilla/source/content/base/src/nsStyleContextDebug.h
http://lxr.mozilla.org/mozilla/source/content/base/src/nsStyleLinkElement.cpp
http://lxr.mozilla.org/mozilla/source/content/base/src/nsStyleLinkElement.h
http://lxr.mozilla.org/mozilla/source/content/base/src/nsStyleSet.cpp

Are there other portions of the code that would fall into this category?

I suspect the documentation you were refering to is this:
http://www.mozilla.org/newlayout/doc/style.html

Comment 9

[Daniel Glazman (:glazou) (not active in Mozilla any more)]

Beth, this doc on www.mozilla.org is in large parts outdated. Bernd is looking
for the verbatim of the Layout Technical Meeting we had some weeks ago.
I think that all contributors to the Style Engine (existing, future, nscpers,
external - yes we DO have external contributors to the style engine) would benefit 
from a  written summary of that meeting.

Comment 10

[rubydoo123]

This should actually be assigned to the style system folks and not Marc, so 
Daniel I am giving this one to you (lucky man), please hand over to David or 
Pierre if that is correct. Marc's queue is full with layout issues.

Comment 11

[Daniel Glazman (:glazou) (not active in Mozilla any more)]

Well, that's really the author of the new code who should wite it; ==> david

Comment 12

[Pierre Saslawsky]

Taking...

Comment 13

[rubydoo123]

removing myself from the cc list

Comment 14

[James Cox]

accepting QA for mozilla developer docs.

some of these bugs have been around for a _long_ time. Reporters, would you
please review the bugs, see if the issues have been resolved, and close bugs
appropriately.

I will do a full review of all bugs not touched in one week (8th April). 

Thanks.

</spam>

Comment 15

[Bernd]

this bug is still valid in all its beauty

Comment 16

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

I just started writing http://www.people.fas.harvard.edu/~dbaron/mozilla/ssdoc/
.  More later.  I haven't even proofread what I wrote yet.

Comment 17

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

Assigning pierre's remaining Style System-related bugs to myself.

Comment 18

[Jonathan Nieder]

For no real reason, note that the docs in question have moved to
<http://dbaron.org/mozilla/ssdoc/>.

I have no business here - just browsing bugs to familiarize
myself with the logic of parts of Mozilla.

Comment 19

[Jonathan Nieder]

erm, (extremely sorry for the spam)
<http://www.mozilla.org/newlayout/doc/style-system.html>.

Comment 20

[Eric Shepherd [:sheppy]]

Do we have anyone around who would like to tackle this work?  This bug has been here since the dawn of time. :)

Comment 21

[Mike Shaver (:shaver -- probably not reading bugmail closely)]

It's still assigned to dbaron, likely just waiting on cycles.  Lay low. :)

Comment 22

[John Karahalis [:openjck]]

Automatically closing all bugs that have not been updated in a while. Please reopen if this is still important to you and has not yet been corrected.

Comment 23

[John Karahalis [:openjck]]

Reopening for review by Sheppy.

Comment 24

[Eric Shepherd [:sheppy]]

While we have bits and pieces of documentation for the style system, we need to organize and update it. A new style system doc set should be built with a landing page here:

https://developer.mozilla.org/en-US/docs/Mozilla/Style_system

Here are the pages I've been able to locate on a quick search. They should be updated, cleaned up, and migrated to be under that page:

https://developer.mozilla.org/en-US/docs/Mozilla_Style_System
https://developer.mozilla.org/en-US/docs/Style_System_Overview
https://developer.mozilla.org/en-US/docs/Mozilla_Style_System_Documentation

Do we know anyone who knows their way around the style system that could work on this material?

Comment 25

[David Baron :dbaron: (⌚️UTC-4, no longer working on Mozilla)]

Also https://wiki.mozilla.org/Gecko:Overview#Style_System and substantial amounts of in-code documentation in the various *.h files in layout/style.

Comment 26

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.