From 703427a48612bf98fba599dfcd6e91485efd5b77 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Fri, 9 Jun 2017 17:28:55 +0100 Subject: Update documentation removing junk and moving to markdown for most text files --- Docs/ideas/css-engine.txt | 381 ---------------------------------------------- 1 file changed, 381 deletions(-) delete mode 100644 Docs/ideas/css-engine.txt (limited to 'Docs/ideas/css-engine.txt') diff --git a/Docs/ideas/css-engine.txt b/Docs/ideas/css-engine.txt deleted file mode 100644 index 1ea8778d5..000000000 --- a/Docs/ideas/css-engine.txt +++ /dev/null @@ -1,381 +0,0 @@ -CSS engine -========== - -Requirements ------------- - - + Parse stylesheets conforming to the forward compatible CSS grammar - (Note that in the short term, the semantic analysis stage only need - support CSS2.1) - + Stylesheet management/merging (i.e. multiple stylesheets may be added - to a single engine context and thus affect style selection) - + Be able to select a style for a DOM node based upon the current stylesheets - in the engine context. - + Implemented as a standalone, reusable, library -- ideally MIT licensed. - -Suggested API -------------- - -struct css_context; -struct css_style; -struct css_stylesheet; - -typedef struct css_context css_context; -typedef struct css_style css_style; -typedef struct css_stylesheet css_stylesheet; - -typedef enum css_error { - CSS_OK, - CSS_NOMEM, - /* etc */ -} css_error; - -typedef enum css_origin { - CSS_ORIGIN_UA, - CSS_ORIGIN_USER, - CSS_ORIGIN_AUTHOR -} css_origin; - -#define CSS_MEDIA_SCREEN (1<<0) -#define CSS_MEDIA_PRINT (1<<1) -/* etc */ -#define CSS_MEDIA_ALL (0xffffffff) - -#define CSS_PSEUDO_CLASS_NONE (0) -#define CSS_PSEUDO_CLASS_LINK (1<<0) -#define CSS_PSEUDO_CLASS_VISITED (1<<1) -#define CSS_PSEUDO_CLASS_HOVER (1<<2) -#define CSS_PSEUDO_CLASS_ACTIVE (1<<3) -#define CSS_PSEUDO_CLASS_FOCUS (1<<4) - -typedef enum css_property { - CSS_BACKGROUND_ATTACHMENT, - /* etc */ -} css_property; - -typedef struct css_value { - css_property property; - - union { - css_background_attachment background_attachment; - /* etc */ - } value; -} css_value; - -typedef css_error (*css_import_handler)(void *pw, const char *url, - css_stylesheet *sheet); - -/* Initialise library */ -css_error css_init(void); -/* Finalise library */ -css_error css_fini(void); - -/* Create a stylesheet associated with the given URL, - * specifying the sheet's origin, the media type(s) it applies to and - * a callback routine for fetching imported sheets */ -css_stylesheet *css_stylesheet_create(const char *url, - css_origin origin, uint32_t media, - css_import_handler import_callback, void *pw); -/* Destroy a stylesheet */ -void css_stylesheet_destroy(css_stylesheet *sheet); - -/* Append data to a stylesheet, parsing progressively */ -css_error css_stylesheet_append_data(css_stylesheet *sheet, - const uint8_t *data, size_t len); -/* Tell stylesheet parser that there's no more data (will complete parsing) */ -css_error css_stylesheet_data_done(css_stylesheet *sheet); - -/* Retrieve the URL associated with a stylesheet */ -const char *css_stylesheet_get_url(css_stylesheet *sheet); -/* Retrieve the origin of a stylesheet */ -css_origin css_stylesheet_get_origin(css_stylesheet *sheet); -/* Retrieve the media type(s) applicable to a stylesheet */ -uint32_t css_stylesheet_get_media(css_stylesheet *sheet); - -/* Create a selection context */ -css_context *css_context_create(void); -/* Destroy a selection context */ -void css_context_destroy(css_context *context); - -/* Append a top-level stylesheet to a selection context */ -css_error css_context_append_sheet(css_context *context, - css_stylesheet *sheet); -/* Insert a top-level stylesheet into a selection context, at the given index */ -css_error css_context_insert_sheet(css_context *context, - css_stylesheet *sheet, uint32_t index); -/* Remove a top-level stylesheet from a selection context */ -css_error css_context_remove_sheet(css_context *context, - css_stylesheet *sheet); - -/* Retrieve the total number of top-level sheets in a selection context */ -uint32_t css_context_count_sheets(css_context *context); -/* Get a stylesheet from a selection context given an index [0, count) */ -const css_stylesheet *css_context_get_sheet(css_context *context, - uint32_t index); - -/* Select a style for a given DOM node with the given pseudo classes active - * and media type. - * - * If the document language contains non-CSS presentational hints (e.g. HTML - * presentational attributes etc), then these are passed in through - * property_list and treated as if they were encountered at the start of the - * author stylesheet with a specificity of 0. */ -css_style *css_style_select(css_context *context, - *node, uint32_t pseudo_classes, uint32_t media, - css_value **property_list, uint32_t property_list_length); -/* Destroy a selected style */ -void css_style_destroy(css_style *style); - -/* Retrieve a property value from a style */ -css_value *css_value_get(css_style *style, css_property property); -/* Destroy a property value */ -void css_value_destroy(css_value *value); - -Memory management ------------------ - - + Stylesheets are owned by their creator. Selection contexts reference them. - + Selection contexts are owned by the client. - + Selected styles are owned by the client. - + Property values are owned by the client. - - Therefore, the only difficulty lies within the handling of stylesheets - inserted into a selection context. The client code must ensure that a - stylesheet is destroyed after it has been removed from any selection - contexts which are using it. - -DOM node types & tree traversal -------------------------------- - - This is currently undecided. Either the CSS engine is tied to a DOM - implementation (and makes API calls directly), or it's more generic and - performs API calls through a vtable provided by the client. - -Imported stylesheets --------------------- - - Imported stylesheets are handled by the CSS engine creating an appropriate - css_stylesheet object for the imported sheet and then asking the client - to fetch the data and append it to the sheet. The imported sheet is then - stored in the sheet that imported it. This effectively creates a tree of - stylesheets beneath the initial top-level sheet created by the client. - -Style selection algorithm -------------------------- - - css_style_select(context, node, pseudo_classes, media, - property_list, property_list_length): - result = blank_style; - done_props = false; - foreach sheet in context: - # Assumes that sheets are in the order UA, USER, AUTHOR - if !done_props && css_stylesheet_get_origin(sheet) == CSS_ORIGIN_AUTHOR: - fake_rule = fake_rule(node, property_list, property_list_length); - cascade(result, fake_rule, CSS_ORIGIN_AUTHOR); - done_props = true; - process_sheet(sheet, node, pseudo_classes, media, result); - return result; - - fake_rule(node, property_list, property_list_length): - rule = (node.name, 0); # Specificity is 0 - foreach (property, value, importance) in property_list: - rule[property] = (value, importance); - return rule; - - process_sheet(sheet, node, pseudo_classes, media, result): - if (css_stylesheet_get_media(sheet) & media) == 0: - return; - foreach import in sheet: - process_sheet(import, node, pseudo_classes, media, result); - origin = css_stylesheet_get_origin(sheet); - foreach rule in sheet: - if matches_rule(rule, node, pseudo_classes): - cascade(result, rule, origin); - - cascade(result, rule, origin): - foreach (property, value, importance) in rule: - insert = false; - if result[property]: - rOrigin = result[property].origin; - rImportance = result[property].importance; - rSpecificity = result[property].specificity; - if rOrigin < origin: - if rImportance == "important": - if rOrigin != CSS_ORIGIN_USER: - insert = true; - else: - insert = true; - else if rOrigin == origin: - if rImportance == "" && importance == "important": - if rOrigin == CSS_ORIGIN_UA: - if rSpecificity <= rule.specificity: - insert = true; - else: - insert = true; - else if rImportance == "important" && importance == "": - if rOrigin == CSS_ORIGIN_UA: - if rSpecificity <= rule.specificity: - insert = true; - else: - if rSpecificity <= rule.specificity: - insert = true; - else: - if origin == CSS_ORIGIN_USER && importance == "important": - insert = true; - else: - insert = true; - if insert: - result[property] = (value, origin, importance, rule.specificity); - -Outstanding issues ------------------- - - + Parsing/selection quirks. - - Probably as an argument to css_stylesheet_create() and possibly - css_style_select(). This could either take the form of a blanket - full/almost/not quirks mode flag or be more granular and permit the - toggling of individual quirks. - - References: - - + http://developer.mozilla.org/en/docs/Mozilla_Quirks_Mode_Behavior - + http://www.opera.com/docs/specs/doctype/ - + http://www.quirksmode.org/css/quirksmode.html - + http://www.cs.tut.fi/~jkorpela/quirks-mode.html - + Grep WebKit sources for inCompatMode() - - + The :lang pseudo-class - - Need to pass the current language string into css_style_select() - - + Pseudo-elements - - Probably as an argument to css_style_select(). Most likely a bitfield - like the way in which pseudo-classes are handled. - - The inheritance model of :first-line and :first-letter is such that: - - + css_style_select() must begin with a blank style and not the - parent node's style - + an API for cascading one style onto another is needed - - This is because pseudo-elements may be nested inside children of the - node to which they are logically connected. e.g.: - -
-

- first paragraph -

-
- - is logically equivalent to - -
-

- - - first paragraph - - -

-
- - so the actual cascade order is only known at the time the render tree is - built. Note that, courtesy of scripting, the location of pseudo-elements - can move around (e.g. if some text was inserted just before the

within - the div, above, then would move). Additionally, the actual - content that pseudo-elements apply to can change due to reflow. - - Pseudo-elements may also affect the processing of inline boxes. e.g.: - -

- foo bar baz bat -

- - becomes (logically): - -

- - foo bar baz - - bat -

- - In terms of interaction between pseudo-elements, :first-letter inherits - from :first-line e.g.: - -

- first line - second line -

- - becomes (logically): - -

- - - f - - irst line - - second line -

- - :first-line and :first-letter apply to the relevant content _including_ any - text inserted using :before and :after. - - List of CSS 3 pseudo-elements: - - + :(:)?first-line - + :(:)?first-letter - + :(:)?before - + :(:)?after - + ::selection - + ::footnote-call - + ::footnote-marker - + ::before-page-break - + ::after-page-break - + ::line-number-left - + ::line-number-right - + ::line-number-inside - + ::line-number-outside - + ::slot() - + ::value - + ::choices - + ::repeat-item - + ::repeat-index - + ::marker - + ::outside - + ::alternate - + ::line-marker - - References: - - + CSS 2.1 $$5.12 and $$12.1 - - + Stylesheet charset handling - - An embedded stylesheet shares the charset of the containing document. - - The charset of a stand-alone stylesheet can be specified by (in order of - priority, highest -> lowest): - - + the transport layer - + a BOM and/or @charset at the immediate start of the sheet - + or other metadata from the linking mechanism - + charset of referring stylesheet or document - + assuming UTF-8 - - The API currently has no way of conveying the first, third, or fourth of - these to the engine. This can be realised through the addition of a - parameter to css_stylesheet_create() - - CSS 2.1 $4.4 specifies that a stylesheet's transport encoding must be a - superset of US-ASCII. - - The internal encoding will be UTF-8. - - All strings passed in by the client are assumed to be UTF-8 encoded. - Strings retrieved from DOM nodes are assumed to be UTF-8 encoded. - -- cgit v1.2.3