From 6a59b323cf8f6cc829985edcdef44e69ec176e29 Mon Sep 17 00:00:00 2001 From: Shaun McCance Date: Wed, 13 May 2009 19:03:45 -0500 Subject: [mallard] Adding info to mal_block, marking review --- doc/mallard/C/mal_block.xml | 81 +++++++++++++++++++++++++++++++++------- doc/mallard/C/mal_block_tree.xml | 24 ++++++++++++ doc/mallard/C/mal_list_tree.xml | 24 ------------ 3 files changed, 91 insertions(+), 38 deletions(-) create mode 100644 doc/mallard/C/mal_block_tree.xml delete mode 100644 doc/mallard/C/mal_list_tree.xml diff --git a/doc/mallard/C/mal_block.xml b/doc/mallard/C/mal_block.xml index 7e49cd6..9078302 100644 --- a/doc/mallard/C/mal_block.xml +++ b/doc/mallard/C/mal_block.xml @@ -5,16 +5,21 @@ + + Shaun McCance shaunm@gnome.org - 2008 + 2008-2009 Shaun McCance - + + + Paragraphs, lists, tables, and various semantic elements for + building simple yet stunning pages. Block Elements @@ -28,10 +33,18 @@ mal_block = ( ) - - Shaun McCance -

Add some intro text

- +

Block elements are the building blocks of pages. Mallard provides block +elements for most common needs in software documentation, from simple paragraphs +to example blocks to powerful tables. Pages and sections in Mallard are built +up of block elements, which in turn contain either further block elements or +inline content.

+ +

Authors, editors, or other content producers sometimes need to supply +richer information in their documents. While this information may not +be conveyed by display tools, it may be used for various internal tracking +purposes. Mallard allows elements to be extended with attributes from +external namespaces. See for more +information.

@@ -53,13 +66,17 @@ mal_block_basic = ( mal_block_p | mal_block_screen ) + +

Basic block elements are elements that do not contain a title and which + have either general block content or inline + content. Using basic block elements, you can build up simple pages + which convey information clearly.

- Formal Elements Formal Block Elements @@ -69,6 +86,7 @@ mal_block_basic = ( + Formal Elements mal_block_formal = ( mal_block_comment | @@ -78,24 +96,34 @@ mal_block_formal = ( mal_block_quote | mal_block_synopsis ) + +

Formal block elements contain a title + and general block content. Formal block elements allow you to provide + richer information in your pages.

- List Elements + List Elements mal_block_list = ( mal_block_dlist | mal_block_olist | - mal_block_ulist + mal_block_ulist | + mal_block_tree ) + +

Mallard provides list elements for most common needs, including the common + defintion, ordered, and unordered lists. Mallard also provides simple trees, + which are useful for representing heirarchies such as class inheritance or + directory layouts.

@@ -106,17 +134,17 @@ mal_block_list = ( Tables - - Shaun McCance -

Add a blurb that just links to mal_table

- + +

Mallard provides a simple table model based on HTML tables. While not + allowing the level of styling flexibility as HTML and CSS, Mallard tables + provides simple solutions to common styling needs, such as alternate-row + shading.

- Other Elements Other Block Elements @@ -124,7 +152,32 @@ mal_block_list = ( + Other Block-like Elements + +

Mallard contains various block-like elements which are only used in + specific contexts, and are not allowed in general block content. These + elements allow for richer content models for the elements they appear + in.

+ + +
+ Processing Expectations + +

Block elements all begin on a new line in rendered output. Pages can + be visualized as a sequence of vertically-stacked block elements. Some + block elements contain other block elements. In these cases, the + containing element may introduce certain styling effects, and each of + the child elements is rendered as normal.

+ +

Each block element should be clearly distinguishable from its surrounding + block elements. Typically, vertical padding is placed between block elements + to set them apart. Certain block elements, especially those that have block + content, may use a border, background color, or other styling effects. See + each block element's specification for more details.

+
+ + diff --git a/doc/mallard/C/mal_block_tree.xml b/doc/mallard/C/mal_block_tree.xml new file mode 100644 index 0000000..a12774a --- /dev/null +++ b/doc/mallard/C/mal_block_tree.xml @@ -0,0 +1,24 @@ + + + + + + + +Tree Lists + + +mal_list_tree = element list { + attribute type { "tree" }, + attribute style { text } ?, + mal_item_tree + +} +mal_item_tree = element item { + mal_inline, + mal_item_tree * +} + + + diff --git a/doc/mallard/C/mal_list_tree.xml b/doc/mallard/C/mal_list_tree.xml deleted file mode 100644 index fc1d011..0000000 --- a/doc/mallard/C/mal_list_tree.xml +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - - -Tree Lists - - -mal_list_tree = element list { - attribute type { "tree" }, - attribute style { text } ?, - mal_item_tree + -} -mal_item_tree = element item { - mal_inline, - mal_item_tree * -} - - - -- cgit v1.2.1