1427737 - Request for clarification of document on Display property

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: CSS, defect, P1)

Description

[mh]

:: Developer Documentation Request

      Request Type: Correction
     Gecko Version: unspecified
 Technical Contact: 

:: Details

I imagine that the article is comprehensive but it is almost impenetrable.  For instance, one of the 170+ lines reads:

"IF its outer display type is inline or run-in, AND it is participating in a block OR inline formatting context, THEN it generates an inline box. Otherwise it generates a block container box."

Although maybe self-explanatory to anyone who already knows this, there seem to be five cases being described in it, at least four of which comprise a group of individually complex concepts.  I find these concepts very challenging to understand.  Although I doubt I have got any of this right, basically speaking, it seems to me the five cases are these:
IF
	1. outer display type is inline AND it is participating in a block formatting context 
	generates an inline box
ELSE 
	IF
		2. outer display type is inline AND it is participating in an inline formatting context 
		generates an inline box
	ELSE 
		IF
			3. outer display type is run-in AND it is participating in a block formatting context 
			generates an inline box
		ELSE 
			IF
				4. outer display type is run-in AND it is participating in an inline formatting context 
				generates an inline box
			ELSE
				5. generates a block container box
			ENDIF
		ENDIF
	ENDIF
ENDIF

Both `run-in` and `inline formatting context` could do with some examples to clarify imo.
	
Specific problems I find are:

a. the article self-refences e.g the linked text `<display-outside>` goes nowhere else than the article
b. there is only one example given (but it seems a huge property to me) and that example is of a "legacy form" of the property which anyone (with any hope of understanding the article, even me) is more than familiar with)
c. the syntax given does not correspond to the CSS I know e.g. wouldn't the syntax for  `<display-outside> = block` be `display-outside: block` ?

As anyone reading this will realise, I am confused.

Comment 1

[Rachel Andrew]

I have updated this page and broken out the various values into subpages.

https://developer.mozilla.org/en-US/docs/Web/CSS/display - each of the values under syntax now has a page with examples.

I would be very happy to add additional examples or explanations if the original reporter (or anyone else) has suggestions.

Comment 2

[Chris Mills [:cmills]]

I think this is fixed now.

Comment 3

[mh]

The point I made has been obviated yet while the page seems clearer I remain a bit confused.  Following are some points where I got confused and after that a cut n' paste reformat (not a pro so all fwiw).

1.  
if <display: flex run-in;> can also be specified as <display: run-in flex;> that would make the logic of the list of values read more clearly.  (<display-outside> ref followed by <display-inside> ref in the spec)

2.  
<display-listitem>
"The element generates a block box for the content and a separate list-item inline box"
Does this mean: the element is displayed as block level element with inline content displayed as a list?
The break-out page example doesn't clarify, and under its Formal Syntax, shows "Syntax not found in DB!".

3.
<display-box>
"These values define whether an element generates display boxes at all."
Is display-box property synonymous with display and the values select whether or not the element is displayed?
Is <display-box: contents; required for other value categories to apply? 
Is <display-listitem> a <display-inside> category?

I found it confusing that the page outlines two types: outer display and inner display, the value list sets out eight categories, and the Syntax section lists six value categories.

THIS THEN IS MY UNDERSTANDING THAT RESULTS:

The display CSS property defines the display type to be applied to an element.
Values for <display-box> define whether the element is to be displayed; for <display-outside> define its role in the flow; and for <display-inside>  how the children of the box are to be laid out. 
 
The full list of values is as below.
nb.See the individual specification provided for some values of display.  See the table at the end of this document for links to all relevant specifications. 

/* Global values */
display: inherit;
display: initial;
display: unset;

/* <display-box> values */
display: contents;
display: none;

/* <display-outside> values */
display: block;
display: inline;
display: run-in;

/* <display-inside> values */
display: flow;
display: flow-root;
display: table;
display: flex;
display: grid;
display: ruby;

/* <display-outside> plus <display-inside> values */
display: block flow;
display: inline table;
display: run-in flex;


<display-legacy>
    CSS 2 used a single-keyword syntax for the display property, requiring separate keywords for block-level and inline-level variants of the same layout mode. e.g inline-block > inline flow-root 
    
/* <display-legacy> values */
display: inline-block;
display: inline-table;
display: inline-flex;
display: inline-grid;

    
<display-listitem>
    the element is displayed as block level element with inline content displayed as a list

/* <display-listitem> values */
display: list-item;
display: list-item block;
display: list-item inline;
display: list-item flow;
display: list-item flow-root;
display: list-item block flow;
display: list-item block flow-root;
display: flow list-item block;

<display-internal>
    Some layout models such as table and ruby have a complex internal structure, with several different roles that their children and descendants can fill. This section defines those "internal" display values, which only have meaning within that particular layout mode.
    
/* <display-internal> values */
display: table-row-group;
display: table-header-group;
display: table-footer-group;
display: table-row;
display: table-cell;
display: table-column-group;
display: table-column;
display: table-caption;
display: ruby-base;
display: ruby-text;
display: ruby-base-container;
display: ruby-text-container;
		

I cleared the "needinfo" request, but all I could see was that there was one.
This Bubzilla page isn't fully functional on my system.