path: root/documentation/layout.mdwn
diff options
authorDaniel Silverstone <>2017-02-04 09:41:13 +0000
committerDaniel Silverstone <>2017-02-04 09:41:13 +0000
commite7366bf41f68cfe07e9ea03fc4a398baecbae651 (patch)
tree5bb9c3cbe7eab7e70ff1ebd65d9de59a694762df /documentation/layout.mdwn
Initial conversion from MediaWiki, 20170204
Diffstat (limited to 'documentation/layout.mdwn')
1 files changed, 70 insertions, 0 deletions
diff --git a/documentation/layout.mdwn b/documentation/layout.mdwn
new file mode 100644
index 0000000..414253f
--- /dev/null
+++ b/documentation/layout.mdwn
@@ -0,0 +1,70 @@
+[[!meta title="Documentation/Layout"]]
+[[!meta author="James Bursa"]]
+[[!meta date="2011-11-26T22:20:06Z"]]
+[[!toc]] The modules in the render
+directory process and layout HTML pages.
+This is the process to render an HTML document:
+First the HTML is parsed to a tree of xmlNodes using the HTML parser in
+libxml. This happens simultaneously with the fetch
+Any stylesheets which the document depends on are fetched and parsed.
+The tree is converted to a 'box tree' by xml\_to\_box(). The box tree
+contains a node for each block, inline element, table, etc. The aim of
+this stage is to determine the 'display' or 'float' CSS property of each
+element, and create the corresponding node in the box tree. At this
+stage the style for each element is also calculated (from CSS rules and
+element attributes). The tree is normalised so that each node only has
+children of permitted types (eg. TABLE\_CELLs must be within
+TABLE\_ROWs) by adding missing boxes.
+The box tree is passed to the layout engine [layout\_document()], which
+finds the space required by each element and assigns coordinates to the
+boxes, based on the style of each element and the available width. This
+includes formatting inline elements into lines, laying out tables, and
+positioning floats. The layout engine can be invoked again on a already
+laid out box tree to reformat it to a new width. Coordinates in the box
+tree are relative to the position of the parent node.
+The box tree can then be rendered using each node's coordinates.
+Lists are one or more elements with 'display: list-item' (which is set
+for 'li' by the default CSS). A list-item is constructed as a BLOCK box
+and a box for the marker attached at block-\>list\_marker. The marker
+contains the bullet, number, or similar, depending on the
+Layout of the block is as normal. A pass of layout after main layout
+places list marker boxes to the left of their block (see
+Absolute positioning
+Absolutely positioned boxes are constructed in the box tree in the same
+place as if they were not absolutely positioned. Inline boxes are
+created as INLINE\_BLOCK, tables as TABLE, and other boxes as BLOCK (see
+During layout, absolutely positioned boxes in block context (BLOCK or
+TABLE) are given a position in layout\_block\_context(), but treated as
+having no height. In inline context (INLINE\_BLOCK), they are given a
+position in layout\_line(), but treated as having no width or height.
+This is done to determine the static position.
+An additional pass after main layout positions and layouts all
+absolutely positioned boxes (see layout\_position\_absolute()).
+[[!inline raw=yes pages="Documentation"]]