Last Comment Bug 115310 - Block and Line Layout need to be fully documented
: Block and Line Layout need to be fully documented
Status: RESOLVED INVALID
:
Product: Developer Documentation
Classification: Other
Component: Mozilla Platform (show other bugs)
: unspecified
: All All
: -- normal (vote)
: ---
Assigned To: Nobody's working on this, feel free to take it
:
:
Mentors:
Depends on:
Blocks:
  Show dependency treegraph
 
Reported: 2001-12-14 11:51 PST by Marc Attinasi
Modified: 2015-09-17 10:41 PDT (History)
14 users (show)
See Also:
QA Whiteboard:
Iteration: ---
Points: ---


Attachments
Layout Documentation Overview (9.14 KB, text/html)
2001-12-18 14:03 PST, Marc Attinasi
no flags Details
Dummy Class Diagram.. (5.47 KB, image/jpeg)
2001-12-18 14:05 PST, Marc Attinasi
no flags Details
High Level Design Template (4.44 KB, text/html)
2001-12-18 14:09 PST, Marc Attinasi
no flags Details
Detailed Design Template (4.25 KB, text/html)
2001-12-21 11:33 PST, Marc Attinasi
no flags Details
SpaceManagerClasses.gif (60.12 KB, image/gif)
2002-01-08 14:15 PST, Marc Attinasi
no flags Details
Space Manager Class Diagram UML source file (DOME) (14.33 KB, application/octet-stream)
2002-01-08 14:21 PST, Marc Attinasi
no flags Details
Space Manager High Level Design - for review and sanity check, and as a possible example (10.58 KB, text/html)
2002-01-08 15:16 PST, Marc Attinasi
no flags Details
Detailed Design of Space Manager (27.56 KB, text/html)
2002-01-15 16:01 PST, Marc Attinasi
no flags Details

Description Marc Attinasi 2001-12-14 11:51:18 PST
Block and line layout is a difficult area that is not well documented. We need
to document it to make it more penetrable and to better understand where its
strengths and weaknesses are.
Comment 1 Marc Attinasi 2001-12-18 14:03:58 PST
Created attachment 62129 [details]
Layout Documentation Overview

This is an overview of the documentation strategy I plan to use for documenting
the design of layout (block and line initially). This is a work In Progress -
comments and criticisms are welcome.
Comment 2 Marc Attinasi 2001-12-18 14:05:25 PST
Created attachment 62130 [details]
Dummy Class Diagram..

for reference in the High Level design Template (WIP)
Comment 3 Marc Attinasi 2001-12-18 14:09:53 PST
Created attachment 62131 [details]
High Level Design Template

A template to be used for High Level Design documents (WIP)
Comment 4 Marc Attinasi 2001-12-18 21:07:05 PST
P1 --> 098
Comment 5 Alexandru Savulov 2001-12-19 12:09:41 PST
For those interested, there is a complete spec of UML to find under:

http://www.rational.com/uml/resources/documentation/index.jsp




Comment 6 Marc Attinasi 2001-12-21 11:33:27 PST
Created attachment 62538 [details]
Detailed Design Template

Simple template for Layout Detailed Designs (WIP)
Comment 7 Marc Attinasi 2001-12-21 11:42:53 PST
I'm working on sample designs for the Space Manager now. I will attach them as
they are completed. They should have been in this week, but I got sick and
progress was slowed as I reallocated my internal resources to fight the invading
army of evil, terrorizing microbes.  Stay tuned, I am hoping to do some of this
over the Holiday, family willing.
Comment 8 Marc Attinasi 2002-01-08 14:15:49 PST
Created attachment 64023 [details]
SpaceManagerClasses.gif
Comment 9 Marc Attinasi 2002-01-08 14:21:11 PST
Created attachment 64024 [details]
Space Manager Class Diagram UML source file (DOME)
Comment 10 Chris Waterson 2002-01-08 14:51:18 PST
What's DOME?
Comment 11 Marc Attinasi 2002-01-08 15:14:50 PST
DOME is a free UML editor: http://www.htc.honeywell.com/dome/

How the diagrams are generated is not important, but I wanted to include the
DOME source file in case it needs future edits.
Comment 12 Marc Attinasi 2002-01-08 15:16:21 PST
Created attachment 64038 [details]
Space Manager High Level Design - for review and sanity check, and as a possible example
Comment 13 Chris Waterson 2002-01-08 15:26:03 PST
Wow; looks great. Is a bug the best place to keep this stuff? Why not just check
it all in on gila under html/newlayout/doc? (Or, if you want it in the source
tree, under mozilla/layout/doc?)
Comment 14 Marc Attinasi 2002-01-08 15:31:08 PST
I think the source tree is a good place.  I'm putting up the Space Manger docs
here, along with the templates, to get the format ironed out.  Once all
interested parties are happy with 'em, we should move them to the source tree,
and /mozilla/layout/doc sounds like a good spot.

CC'ing dbaron in hopes he can review the Space Manger HLD.

Also, I'd like to get a short list of bite-sized topics we should start working
on documenting.  I am going finishing up the Detailed Design of the Space
Manager first, but it is short.

A couple candidates for the short-list:

* Frame Constructor (probably several sub-topics rather than one biggie)
* Block Frame (ugh, this is a big one too)
* LineBox / line_iterator
* State Recovery / Margin Collapsing
* Debugging facilities
Comment 15 Marc Attinasi 2002-01-08 15:32:45 PST
Also, once we move the docs to the source tree we need to update Mozilla.org
with a doc that points to some LXR links or something, I think, or maybe even
mirror them to Mozilla.org periodically.
Comment 16 Bernd 2002-01-08 22:35:49 PST
Marc, I understand your preference for the source tree but, I would recommend to
put them on gila, this would at least ease a little bit the pain (shame) of
having only old and outdated layout documentation there.
Comment 17 Chris Waterson 2002-01-09 11:19:18 PST
We shouldn't get too hung up on where these docs go: it's trivial to point from
a page on gila to an LXR page that is the HTML doc.

Marc, the block code might not be too awful if we break it out into the
component objects:

  nsBlockReflowState
  nsBlockReflowContext
  nsLineLayout
    PerSpanData
    PerFrameData
  nsLineBox
    nsLineList
    nsLineList_iterator
  nsFloaterCache
    nsFloaterCacheList
    nsFloaterCacheFreeList

To get coverage, we'll probably need to also do these:

  nsInlineFrame
  nsHTMLReflowState

and to a lesser degree:

  nsAbsoluteContainingBlock
  nsContainerFrame
  nsFrame
  nsHTMLContainerFrame
  nsHTMLReflowCommand
  nsTextFrame


Comment 18 Bernd 2002-01-15 12:53:07 PST
I volunteer for the debugging facilities.
Comment 19 Marc Attinasi 2002-01-15 16:01:10 PST
Created attachment 65128 [details]
Detailed Design of Space Manager
Comment 20 Marc Attinasi 2002-01-15 17:16:56 PST
I have moved the templates and space manager docs to the /mozilla/layout/doc
directory.  The docs that previously lived there are woefully out of date and
have been moved to /mozilla/layout/doc/obsolete

If you start working on a doc, first check the index file in /mozilla/layout/doc
to see if somebody is already working on that, or has already done it.  Put a
link to the doc in the 'Works In Progress' section to signal to others that you
are working on it too.

As new documents are added to the tree, update the index file in
/mozilla/layout/doc to point to the new doc. 

We'll need to get the Mozilla site to link to these docs - I'll look into the
gila systems 'cause I don't know anything about it.
Comment 21 Marc Attinasi 2002-01-16 11:16:24 PST
Bulk push to next milestone
Comment 22 Marc Attinasi 2002-02-04 14:36:59 PST
Removing milestone as this is a recurring task
Comment 23 Håkan Waara 2002-06-16 18:49:32 PDT
Marc, would you obsolete the files you've already checked in / uploaded?  Thanks.
Comment 24 Alexandru Savulov 2002-06-17 19:20:27 PDT
Marc?.... Maaaaarc!... Duuude, where are ya!...

error line 1: dude not found!
Comment 25 Alexandru Savulov 2002-06-19 17:45:40 PDT
hwaara:

you want the files removed from CVS? marc does not work for netscape anymore (he
cannot read the mail since this was an employee account) so i think i will take
over this bug .

taking
Comment 26 Håkan Waara 2002-06-19 19:23:32 PDT
No, no, why would I want that!  I meant obsolete the attachments in bugzilla, as
I didn't know if any of these documents were still pending review or whatever.
Comment 27 Alexandru Savulov 2002-06-19 19:41:05 PDT
ah, ok. i wasn't sure. well, the problem is that this was meant to be a
collection bug for all kind of doc pieces as we thougth to go along and write
them. unfrotunately nobody found enough time to do this so the whole thig got
stuck. there is now a new documentation effort started by jkeiser and me.
jkeiser is working now with alex vincent on a larger issue, though jkeiser will
limit his activity to gecko and alex vincent tries to do the organizational work
in order to get a unified collection of documents covering not only the
developer documentation but also the embedder doc, web-author doc and so on.
check n.p.m.documentation for more information.
Comment 28 Daniel Wang 2003-03-06 19:46:42 PST
-> documentation
Comment 29 David Baron :dbaron: ⌚️UTC-7 (busy September 14-25) 2003-03-30 16:15:54 PST
->block&line
Comment 30 Mike Shaver (:shaver -- probably not reading bugmail closely) 2007-04-02 23:41:55 PDT
Pretty sure dbaron meant what he said when he assigned the bug in comment 29, so I'm putting it back there.  (It can stay in this product/component, I suppose, though I find the "severity: critical" labeling to be somewhat lol-worthy in the context of MDC.)
Comment 31 John Karahalis [:openjck] 2012-12-04 07:35:16 PST
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 32 John Karahalis [:openjck] 2012-12-04 08:09:59 PST
Reopening for review by Sheppy.
Comment 33 Florian Scholz [:fscholz] (MDN) 2015-09-17 10:41:34 PDT
The material here is from 2001. Please reopen if you think this is still relevant or open a new bug that contains a new request/plan for what to document here.

Note You need to log in before you can comment on or make changes to this bug.