From zedwiki

Magazines

Explanation of Text Elements

(RNIB Magazine version 1.33)

[Main items which are optional are marked in this list with a ?. The question mark is not part of the tag. Specific items such as list which are obviously optional have not been so marked.]

mag

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.

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.

front

This contains all the items before the articles in the magazine: a banner logo for the magazine (bannerlogo), the title, subtitle, date, issue, editor, magazine publication information (pubinfo), price, and contents. One or more paragraphs (p) and lists may also be inserted between these items to allow for other information being present. Note, however, that the paragraph tag should not be used where one of the specific tags is appropriate.

body

This contains all the articles in the magazine. It can also contain paragraphs directly, to cater for magazines without separate articles.

back ?

This optional element can occur after the body, and contains one or more index.

cover ?

This is information which may appear on the cover of the magazine. It is placed as the last item in mag, and is optional. The contents of this element is normally omitted in the braille output, but if the brlincl attribute is set to "yes", it will be included. (This attribute does not affect other outputs.)

bannerlogo ?

This is an optional element which may occur as the first item in front, indicating that a banner logo should be used in the outputs where appropriate. It automatically outputs the RNIB logo. (No attributes are required.)

title

This is the title of the magazine, and is the first item in front.

subtitle ?

This is a subtitle of the magazine, and, if present, follows the title in front. There may be more than one subtitle.

date

This is the publication date of the magazine, and is the second item in front.

issue ?

This is the issue number of the magazine, and if present follows the date. Include the full text required, e.g. V15 No. 8. issue can have a medium attribute with values "braille", "print", "moon", "html", "etext" or "daisy". Such an attribute should be used when it is to appear in a particular medium only.

editor ?

This is the editor of the magazine. It may be absent, depending on the magazine in question. Include the full text required (e.g. include "Editor:"). editor can have a medium attribute with values "braille", "print", "moon", "html", "etext" or "daisy". Such an attribute should be used when it is to appear in a particular medium only.

pubinfo ?

This is the standard paragraph at the beginning of the magazine, stating the magazine publication details and the RNIB contact address, etc. Do not use the paragraph tag p within it. pubinfo can have a medium attribute with values "braille", "print", "moon", "html", "etext" or "daisy". Such an attribute should be used when it is to appear in a particular medium only.

price ?

This is the price of the magazine. Include the full text which is required to appear. Do not use the paragraph tag p within it. price can have a medium attribute with values "braille", "print", "moon", "html", "etext" or "daisy". Such an attribute should be used when it is to appear in a particular medium only.

contents ?

This is the magazine contents, and contains the heading (head) , possibly one or more paragraphs (p), and different levels of entries (entry1 ... entry4, and entryp). contents can have a medium attribute with values "braille", "print", "moon", "html", "etext" or "daisy". Such an attribute should be used when it is to appear in a particular medium only.

head

This element name is used for all the headings in the magazine, e.g. at the start of the contents, at the start of articles, etc.

subhead ?

This is a subheading which may follow a head at the start of articles, topics, etc.

entry1

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

entry2

This is a second-level entry in the contents. It has the same structure as entry1.

entry3

This is a third-level entry in the contents. It has the same structure as entry1.

entry4

This is a fourth-level entry in the contents. It has the same structure as entry1.

entryp

This is an entry in the contents indicating a major part or division of the magazine, but does not correspond to a heading in the text. It is typically centred in print or braille. It contains the name of the part or division (artname), but no page number.

artname

This is the name of an article or subarticle, and appears in its entry (entry1, entry2, entry3 or entry4) in the contents. It is also used for the name of a major part or division of the magazine, where it appears within the entryp element in the contents.

pageno

This is the starting page number of an article or subarticle, and appears after the article name (artname) in its entry in the contents. This number will not be known when preparing the XML file, and so should be left blank.

body

This follows front and contains all the articles in the magazine.

article

This is a main article in the magazine, and contains the initial items: head, subhead, author, subauthor,source, introduction (intro), followed by the text of the article. It may contain subarticles (article2).

author ?

1. This may be used at the beginning of an article or sub-article (article2) after the head or subhead, to give the author of the article. It may be absent. Only include the name, not any accompanying format, as the latter will be inserted automatically for the required medium.

2. It may be used at the end of a poem to state its author.

subauthor ?

This element may be used after the author, either for additional authors or for lines containing related information (e.g. qualifications or employment details). More than one subauthor may be used.

source ?

1. This may be used at the beginning of an article or sub-article (article2) after the head and author to give the source of the article. It should include both the name of the source magazine, as well as the date (if present), separated by a comma. It may be absent. Use italics for the name of the source magazine if required, but not any accompanying format, as the latter will be inserted automatically for the required medium.

2. It may be used within a paragraph (usually at the end) to give the source of the preceding text. It should come before the closing paragraph tag </p>. Do not include any accompanying format, as the latter will be inserted automatically for the required medium.

3. It may be used at the end of a table to state its source.

4. It may be used at the end of a longquote to state its source. Do not include any accompanying format, as the latter will be inserted automatically for the required medium.

intro ?

This is an introductory paragraph to an article or sub-article, which may be absent. Do not use the paragraph tag p within it, nor other formatting devices such as surrounding brackets or italics. The latter will be inserted automatically as required for the required medium.

article2 ?

This is a subarticle within an article, and has the same structure as an article, except that a subarticle within it is tagged as article3. article2 can have a type attribute of "minor", which indicates a lower level of prominence as may be reflected in the outputs. E.g. end-markers may be omitted in braille when this attribute is set.

article3 ?

This is a subarticle within an article2, and has the same structure as an article2, except that there is no provision for a subarticle within it. Article3 is generally only used where an article2 has more than one level of subheading; if there is only one level of subheading, topic is used instead.

p

This is a paragraph. A paragraph can have a medium attribute with values "braille", "print", "moon", "html", "etext" or "daisy". Such an attribute should be used when the paragraph is to appear in a particular medium only. For example it would be used for an explanatory note to be inserted into the braille only.

list

This is a list, and contains one or more list items (litem). A list can appear between paragraphs, etc., or within a paragraph. It may also be used within a longquote or a paragraph within it (lqpara). 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". Although a list can appear within a paragraph, it is best that it does not end a paragraph: close the paragraph tag first, then start the list.

litem

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

textbreak

This is a break in text between paragraphs, etc., typically shown in print as a line of asterisks or just a gap between paragraphs within an article or topic, etc., as in a story. (It is not used between paragraphs which are normally spaced.) It should not be used where a gap indicates the end of a topic: in this case the topic tags should be used instead to enclose the whole topic. The textbreak element should be left empty.

pb

This element (paragraph break) will break a paragraph into minor paragraphs in some media (e.g. it will give a 3-space paragraph in braille instead of the normal new line paragraph). When used, it is placed within a normal paragraph (p), retaining the normal space at that point before the element. The element should be left empty.

poem

This is a poem or part of a poem. It can occur between paragraphs, etc., or within a paragraph. It can contain a heading (head), poetry lines (pline), stanzas, and an author. This tag should be used for poems which may be specially displayed, e.g. on separate lines in print, but not for poetry occurring in the normal run of a sentence. A poem can have the attribute brlform with values "linebyline" or "linesign" which can be used to set the form of the braille output. The default (with no attribute set) is for line sign braille format.

pline

This is a poetry line. It may occur within a stanza, or directly within the poem tags. (The latter situation occurs when a poetry extract does not start at the beginning of a stanza.) Any line breaks at runovers shown in the source text should be ignored; runovers are not tagged as separate poetry lines. This tag should only be used within the poem or stanza tags, not for poetry lines occurring in the normal run of a sentence.

stanza

This a stanza or verse of a poem. It is used within a poem and contains poetry lines (pline).

address

This is a postal address, and contains one or more address lines (addline). It can appear between paragraphs, etc., but not within a paragraph. This tag should be used for addresses which may be specially displayed, e.g. on separate lines in print, but not for addresses occurring in the normal run of a sentence, such as "write to: Mr Smith, 66 Park Road, Pinner".

addline

This is a line of an address. It may contain the addressee's name or title, an element of the postal address, or a phone number, etc.

table

This is a table. It may occur between paragraphs, but not within a paragraph. It may contain a head, initial paragraphs, the main body of the table (tablebody), and a source. A table can have the attribute brlform with values "para" or "table" which can be used to set the form of the braille output. The default (with no attribute set) is for paragraph braille format.

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.

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.

longquote

This a quoted extract of the kind which is usually displayed in print on separate lines as a block. It should not be used for ordinary speech as in a novel, nor for extracts which are included in the normal run of the text. It can occur within a paragraph when the extract is considered to be part of the current paragraph, or between paragraphs. It can itself contain paragraphs, which are tagged as lqpara rather than using the p tag. If the extract is considered to start mid-paragraph, that part-paragraph should be tagged as lqtext, rather than lqpara. A longquote may also contain lists, and may end with a source.

lqpara

This is a paragraph within a longquote, and is used instead of the normal p. It may contain lists.

lqtext

This is a text within a longquote, which does not start as a new paragraph. It may contain lists.

topic

This is one or more paragraphs, possibly introduced by a heading (head, subhead). It is contained within an article or subarticle (article2), and has lower status to these. A topic requires a type attribute, which specifies one of a variety of styles available. The difference between a subarticle and a topic is only one of degree: it can be arguable whether an item in an article is a subarticle or a topic.

chessgame

This is chess notation giving game moves, and can occur between, but not within, paragraphs, etc.

chessdiag

This is chess notation representing a diagram of a chess board, and can occur between, but not within, paragraphs, etc.

chess

This is chess notation occuring within an ordinary text, e.g. within a paragraph, etc.

index

This is an index which occurs in some magazines, and occurs in back. It contains a head, possibly some paragraphs, then up to three levels of index entries, ientry1, ientry2, ientry3; or index sections, isect.

isect

This is an alphabetic section in an index, and contains an optional head, then up to three levels of index entries, ientry1, ientry2 and ientry3.

ientry1

This is a first level index entry, and can occur directly in an index, or within an index section (isect). It contains the text of the entry (including the page number).

ientry2

This is a second level index entry, and is similar to ientry1.

ientry3

This is a third level index entry, and is similar to ientry1.

ppage

This is a print page indicator, used to mark page turns in the original document (if appropriate). It can appear within a stream of text (e.g. within a paragraph or heading), but not between paragraphs, etc. Where the model does not allow ppage between elements, insert it within an adjacent element, between the last text on the old page and the first text on the new page. ppage contains just the relevant page number, not any associated format, which will be added automatically according to the specific output medium.

i

Italics. Use this for italicised words in the normal stream of text, not for headings, etc. For italicised paragraphs, the i tags should be within the paragraph tags.

b

Bold. Use this for bold words in the normal stream of text, not for headings, etc. For bold paragraphs, the b tags should be within the paragraph tags.

computer

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

email

Use this for e-mail addresses.

web

Use this for internet web addresses.

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.

sup

This is a superscript.

sub

This is a subscript.

stext

This is special text which is to appear in a specific medium only, such as an explanatory remark relating to that medium only. stext has a medium attribute with values "braille", "print", "moon", "html", "etext" or "daisy", which indicates the target medium.

[SJP]

30/3/06