From zedwiki

Simpdoca

Explanation of Text Elements

Version 1.49

simpdoca

This contains the whole document. The opening tag is required at the start of the document, and the closing tag at the end of the document. simpdoca consists of the following elements: ver, comment, bannerlogo, title, and possibly subtitles, followed by contents, paragraphs (p, p2, p3), lists, points, tables, boxes, figures, graphics, sections, ending with end matter. All of these items (apart from ver) are optional.

ver

This element states the version of the system used to create and process the document. Such information is required for archiving purposes, but is not part of the original document, and is not usually output.

comment ?

This is an optional comment which may be placed at the beginning of a document, for example it could be a note the author may make to him or herself. It is not usually output.

bannerlogo ?

This is an optional element which may occur before titleinf, indicating the presence of a banner logo to be used in the outputs where appropriate. (E.g. it may be the RNIB print logo and/or the RNIB audio logo.) It has a required attribute, type, which may have the values "RNIB" or "other". There are also optional attributes: imgsrc, for the filename of the graphic file, and sndsrc, for the filename of the audio file. If "RNIB" is chosen as the value of type, imgsrc and sndsrc can be omitted, as default values are then inserted if empty.

title

This is the title of the document, and is optional.

subtitle

This is a subtitle of the document, and is optional.

contents ?

This is a document contents, and contains the heading (head), followed by the various levels of entries (entry1-entry4).

entry1

This is a main entry in the contents. It consists of the section name (secname) and the page number (pageno).

entry2-entry4

These are lower level entries in the contents. They have the same structure as entry1.

secname

This is the name of an section or subsection, and appears in its entry (entry1-entry6) in the contents.

pageno

This is the starting page number of a section or subsection, and appears after the section name (secname) in its entry in the contents.

p

This is a paragraph.

p2

This is a subparagraph, i.e. a paragraph which is subordinate to a main paragraph tagged p. This tag should be used when the subordination is explicitly indicated, e.g. by indentation. A p2 paragraph is not inserted within a main paragraph, but follows it.

p3

This is a sub-subparagraph, i.e. a paragraph which is subordinate to a subparagraph tagged p2. This tag should be used when the subordination is explicitly indicated, e.g. by indentation. A p3 paragraph is not inserted within a main paragraph or a subparagraph, but follows it.

list

This is a list, and contains one or more list items (litem), or subordinate lists. A list can appear between paragraphs, or within paragraphs. This tag should be used for lists which are normally specially displayed, e.g. on separate lines in print, but not for listed items occurring in the normal run of a sentence, such as "he saw: dogs, cats, geese".

litem

This is an item within a list, and contains text (but not paragraphs).

points

This is a series of points and contains one or more point elements. Point elements are of a similar nature to items in a list (litem), but have a higher status in relation to the surrounding text. They may be regarded as alternative format paragraphs, typically represented in print as hanging paragraphs.

point

This is an item within points, and contains text (but not paragraphs).

box

This is a boxed section of text, and can occur between paragraphs, etc. It can begin with a heading (head), followed by paragraphs.

table

This is a table. It may occur between paragraphs, but not within a paragraph. It may contain a head, paragraphs, and the main body of the table (tablebody).

tablebody

This is the main body of a table, and occurs within a table. It may contain the element colheads which contains any column headings, and one or more rows.

colheads ?

This is the first item in the main body of a table (tablebody) and contains the column headings (chead). It will be absent if there are no column headings.

chead

This is a column heading to a table, and occurs within the colheads element.

row

This is a row in the main body of a table (tablebody). Note that a row containing column headings is tagged as colheads, not row. A row may contain a row heading (rowhead) as the first item, followed by one or more data items (di) which contain the data in the table.

rowhead ?

This is a heading to a row in a table, and may be absent.

di

This is a data item (e.g. a number) in the main body of a table. It occurs within a row.

figure

This is an illustration, and can occur between paragraphs, etc. It can contain a head, a caption, then either a graphic or a visual description (vdes).

caption

This is a caption to an illustration, and can occur in a figure element, after the head.

graphic

This element is used for an actual picture, and can occur within a figure, between paragraphs, or within a paragraph. It contains an image box (imgbox) which holds the picture, followed by a visual description (vdes).

imgbox

This element, "image box", contains a picture image (image). It occurs in a graphic element. imgbox has a position attribute which can be set to "centre" when it is required that the image is centred on a separate line, rather than appearing within a line of text.

image

This is a picture image, and occurs in a image box (imgbox). It has a source attribute which states the filename of the picture (e.g. source="c:\docs\house.bmp"), and a width attribute which sets the size of the picture.

vdes

This is a visual object description, i.e. usually a description of an image. It is used to give a description which will appear as a substitute for the image itself in media other than print. It can occur after an image box (imgbox) in a graphic (where it is used to describe that image); or directly in a figure where no actual graphic is present but a description only is required; or within a paragraph, again to add such a description without a graphic.

vdesp

This is similar to vdes as used without an actual image, except that it constitutes a whole paragraph. It can occur between normal paragraphs

section

This is a section within the document. It may contain a heading (head), followed by paragraphs, lists, points, tables and boxes. It may also contain subsections (subsect1).

subsect1

This is a subsection within a section, and has the same structure as a section, except that a subsection within it is tagged as subsect2.

subsect2

This is a subsection within subsect1, and has the same structure as a section, except that a subsection within it is tagged as subsect3.

subsect3

This is a subsection within subsect2, and has the same structure as a section, except that there is no provision for a subsection within it.

head

This is a heading, and may appear within a section or subsection (subsect1 or subsect2), a table, or a box. A head may only be included in the document inside one of these items. Note that the heading for the document as a whole has a separate tag: title.

i

This is italics.

b

This is bold.

u

This is underlined.

sup

This is a superscript.

sub

This is a subscript.

acronym

Acronym. Use this for acronyms like BBC and RNIB, am and pm, but not abbreviations which are parts of words, such as Mr, Rd, St. Do not use for unit abbreviations. A plural "s" should be left outside the closing tag.

braille

This is braille to be displayed, e.g. black dot braille in a print document.

computer

Computer text. Use this for computer filenames and the like.

email

E-mail address.

web

Internet web address.

linkto

This gives a link to another location (e.g. as used for the HTML output). It can contain text (which typcally becomes highlighted in a browser indicating that there is a link on those words). It has an attribute "location", which should state the target of the link. The target can be the "name" of a bookmark in the same file (precede the bookmark name with #, e.g. #contents); a different file (the path is taken from the path of the current file - use / for subdirectories rather then \, e.g. docs/file2.htm); or locations on the web (the web name should start with http://). linkto also has an attribute "medium" which can be set to "html", in which case the text within it only appears in the HTML output. This is useful for links such as "Return to contents" which are only relevant for HTML.

bookmark

This is a bookmark, and can contain bookmarked text. It can be used to mark the target of a linkto element, and may also serve as a linking point from other sources (typically in the HTML output). The name of the bookmark is carried in its "name" attribute.

end

This is information at the end of the document. It can contain name, date and filename all of which are optional.

name

This is the author's name, and may appear as the first item within end.

date

This is the date, and may appear within end.

filename

This is the filename of the current document, which may be included as a reference. It is the last element within end.

[SJP]

21/1/05