GAPDoc-1.5.1/ 0000755 0001750 0001750 00000000000 12174444024 011203 5 ustar bill bill GAPDoc-1.5.1/doc/ 0000755 0001750 0001750 00000000000 12174444011 011744 5 ustar bill bill GAPDoc-1.5.1/doc/chap3.html 0000644 0001750 0001750 00000276501 12026346063 013647 0 ustar bill bill
GAP (GAPDoc) - Chapter 3: The Document Type Definition
In this chapter we first explain what a "document type definition" is and then describe gapdoc.dtd in detail. That file together with the current chapter define how a GAPDoc document has to look like. It can be found in the main directory of the GAPDoc package and it is reproduced in Appendix B.
We do not give many examples in this chapter which is more intended as a formal reference for all GAPDoc elements. Instead we provide an extra document with book name GAPDocExample (also accessible from the GAP online help). This uses all the constructs introduced in this chapter and you can easily compare the source code and how it looks like in the different output formats. Furthermore recall that many basic things about XML markup were already explained by example in the introductory chapter 1.
3.1 What is a DTD?
A document type definition (DTD) is a formal declaration of how an XML document has to be structured. It is itself structured such that programs that handle documents can read it and treat the documents accordingly. There are for example parsers and validity checkers that use the DTD to validate an XML document, see 2.1-14.
The main thing a DTD does is to specify which elements may occur in documents of a certain document type, how they can be nested, and what attributes they can or must have. So, for each element there is a rule.
Note that a DTD can not ensure that a document which is "valid" also makes sense to the converters! It only says something about the formal structure of the document.
For the remaining part of this chapter we have divided the elements of GAPDoc documents into several subsets, each of which will be discussed in one of the next sections.
See the following three subsections to learn by example, how a DTD works. We do not want to be too formal here, but just enable the reader to understand the declarations in gapdoc.dtd. For precise descriptions of the syntax of DTD's see again the official standard in:
A GAPDoc document contains on its top level exactly one element with name Book. This element is declared in the DTD as follows:
3.2-1 <Book>
<!ELEMENT Book (TitlePage,
TableOfContents?,
Body,
Appendix*,
Bibliography?,
TheIndex?)>
<!ATTLIST Book Name CDATA #REQUIRED>
After the keyword ELEMENT and the name Book there is a list in parentheses. This is a comma separated list of names of elements which can occur (in the given order) in the content of a Book element. Each name in such a list can be followed by one of the characters "?", "*" or "+", meaning that the corresponding element can occur zero or one time, an arbitrary number of times, or at least once, respectively. Without such an extra character the corresponding element must occur exactly once. Instead of one name in this list there can also be a list of elements names separated by "|" characters, this denotes any element with one of the names (i.e., "|" means "or").
So, the Book element must contain first a TitlePage element, then an optional TableOfContents element, then a Body element, then zero or more elements of type Appendix, then an optional Bibliography element, and finally an optional element of type TheIndex.
Note that only these elements are allowed in the content of the Book element. No other elements or text is allowed in between. An exception of this is that there may be whitespace between the end tag of one and the start tag of the next element - this should be ignored when the document is processed to some output format. An element like this is called an element with "element content".
The second declaration starts with the keyword ATTLIST and the element name Book. After that there is a triple of whitespace separated parameters (in general an arbitrary number of such triples, one for each allowed attribute name). The first (Name) is the name of an attribute for a Book element. The second (CDATA) is always the same for all of our declarations, it means that the value of the attribute consists of "character data". The third parameter #REQUIRED means that this attribute must be specified with any Book element. Later we will also see optional attributes which are declared as #IMPLIED.
Within this element information for the title page is collected. Note that more than one author can be specified. The elements must appear in this order because there is no sensible way to specify in a DTD something like "the following elements may occur in any order but each exactly once".
Before going on with the other elements inside the Book element we explain the elements for the title page.
3.2-3 <Title>
<!ELEMENT Title (%Text;)*>
Here is the last construct you need to understand for reading gapdoc.dtd. The expression "%Text;" is a so-called "parameter entity". It is something like a macro within the DTD. It is defined as follows:
<!ENTITY % Text "%InnerText; | List | Enum | Table">
This means, that every occurrence of "%Text;" in the DTD is replaced by the expression
%InnerText; | List | Enum | Table
which is then expanded further because of the following definition:
<!ENTITY % InnerText "#PCDATA |
Alt |
Emph | E |
Par | P | Br |
Keyword | K | Arg | A | Quoted | Q | Code | C |
File | F | Button | B | Package |
M | Math | Display |
Example | Listing | Log | Verb |
URL | Email | Homepage | Address | Cite | Label |
Ref | Index" >
These are the only two parameter entities we are using. They expand to lists of element names which are explained in the sequel and the keyword #PCDATA (concatenated with the "or" character "|").
So, the element (Title) is of so-called "mixed content": It can contain parsed character data which does not contain further markup (#PCDATA) or any of the other above mentioned elements. Mixed content must always have the asterisk qualifier (like in Title) such that any sequence of elements (of the above list) and character data can be contained in a Title element.
The %Text; parameter entity is used in all places in the DTD, where "normal text" should be allowed, including lists, enumerations, and tables, but no sectioning elements.
The %InnerText; parameter entity is used in all places in the DTD, where "inner text" should be allowed. This means, that no structures like lists, enumerations, and tables are allowed. This is used for example in headings.
3.2-4 <Subtitle>
<!ELEMENT Subtitle (%Text;)*>
Contains the subtitle of the document.
3.2-5 <Version>
<!ELEMENT Version (#PCDATA|Alt)*>
Note that the version can only contain character data and no further markup elements (except for Alt, which is necessary to resolve the entities described in 2.2-3). The converters will not put the word "Version" in front of the text in this element.
3.2-6 <TitleComment>
<!ELEMENT TitleComment (%Text;)*>
Sometimes a title and subtitle are not sufficient to give a rough idea about the content of a package. In this case use this optional element to specify an additional text for the front page of the book. This text should be short, use the Abstract element (see 3.2-10) for longer explanations.
3.2-7 <Author>
<!ELEMENT Author (%Text;)*> <!-- There may be more than one Author! -->
As noted in the comment there may be more than one element of this type. This element should contain the name of an author and probably an Email-address and/or WWW-Homepage element for this author, see 3.5-6 and 3.5-7. You can also specify an individual postal address here, instead of using the Address element described below, see 3.2-9.
3.2-8 <Date>
<!ELEMENT Date (#PCDATA)>
Only character data is allowed in this element which gives a date for the document. No automatic formatting is done.
3.2-9 <Address>
<!ELEMENT Address (#PCDATA|Alt|Br)*>
This optional element can be used to specify a postal address of the author or the authors. If there are several authors with different addresses then put the Address elements inside the Author elements.
Use the Br element (see 3.9-3) to mark the line breaks in the usual formatting of the address on a letter.
Note that often it is not necessary to use this element because a postal address is easy to find via a link to a personal web page.
3.2-10 <Abstract>
<!ELEMENT Abstract (%Text;)*>
This element contains an abstract of the whole book.
The "colophon" page is used to say something about the history of a document.
3.2-14 <TableOfContents>
<!ELEMENT TableOfContents EMPTY>
This element may occur in the Book element after the TitlePage element. If it is present, a table of contents is generated and inserted into the document. Note that because this element is declared to be EMPTY one can use the abbreviation
This element may occur in the Book element after the last Appendix element. If it is present, a bibliography section is generated and inserted into the document. The attribute Databases must be specified, the names of several data files can be specified, separated by commas.
Two kinds of files can be specified in Databases: The first are BibTeX files as defined in [Lam85, Appendix B]. Such files must have a name with extension .bib, and in Databases the name must be given without this extension. The second are files in BibXMLext format as defined in Section 7.2. These files must have an extension .xml and in Databases the full name must be specified.
We suggest to use the BibXMLext format because it allows to produce potentially nicer bibliography entries in text and HTML documents.
A bibliography style may be specified with the Style attribute. The optional Style attribute (for LaTeX output of the document) must also be specified without the .bst extension (the default is alpha). See also section 3.5-3 for a description of the Cite element which is used to include bibliography references into the text.
3.2-16 <TheIndex>
<!ELEMENT TheIndex EMPTY>
This element may occur in the Book element after the Bibliography element. If it is present, an index is generated and inserted into the document. There are elements in GAPDoc which implicitly generate index entries (e.g., Func (3.4-2)) and there is an element Index (3.5-4) for explicitly adding index entries.
3.3 Sectioning Elements
A GAPDoc book is divided into chapters, sections, and subsections. The idea is of course, that a chapter consists of sections, which in turn consist of subsections. However for the sake of flexibility, the rules are not too restrictive. Firstly, text is allowed everywhere in the body of the document (and not only within sections). Secondly, the chapter level may be omitted. The exact rules are described below.
Appendices are a flavor of chapters, occurring after all regular chapters. There is a special type of subsection called "ManSection". This is a subsection devoted to the description of a function, operation or variable. It is analogous to a manpage in the UNIX environment. Usually each function, operation, method, and so on should have its own ManSection.
Cross referencing is done on the level of Subsections, respectively ManSections. The topics in GAP's online help are also pointing to subsections. So, they should not be too long.
We start our description of the sectioning elements "top-down":
3.3-1 <Body>
The Body element marks the main part of the document. It must occur after the TableOfContents element. There is a big difference between inside and outside of this element: Whereas regular text is allowed nearly everywhere in the Body element and its subelements, this is not true for the outside. This has also implications on the handling of whitespace. Outside superfluous whitespace is usually ignored when it occurs between elements. Inside of the Body element whitespace matters because character data is allowed nearly everywhere. Here is the definition in the DTD:
<!ELEMENT Body ( %Text;| Chapter | Section )*>
The fact that Chapter and Section elements are allowed here leads to the possibility to omit the chapter level entirely in the document. For a description of %Text; see here.
(Remark: The purpose of this element is to make sure that a validGAPDoc document has a correct overall structure, which is only possible when the top element Book has element content.)
A Chapter element can have a Label attribute, such that this chapter can be referenced later on with a Ref element (see section 3.5-1). Note that you have to specify a label to reference the chapter as there is no automatic labelling!
Chapter elements can contain text (for a description of %Text; see here), Section elements, and Heading elements.
The following additional rule cannot be stated in the DTD because we want a Chapter element to have mixed content. There must be exactly oneHeading element in the Chapter element, containing the heading of the chapter. Here is its definition:
3.3-3 <Heading>
<!ELEMENT Heading (%InnerText;)*>
This element is used for headings in Chapter, Section, Subsection, and Appendix elements. It may only contain %InnerText; (for a description see here).
Each of the mentioned sectioning elements must contain exactly one direct Heading element (i.e., one which is not contained in another sectioning element).
The Appendix element behaves exactly like a Chapter element (see 3.3-2) except for the position within the document and the numbering. While chapters are counted with numbers (1., 2., 3., ...) the appendices are counted with capital letters (A., B., ...).
Again there is an optional Label attribute used for references.
A Section element can have a Label attribute, such that this section can be referenced later on with a Ref element (see section 3.5-1). Note that you have to specify a label to reference the section as there is no automatic labelling!
Section elements can contain text (for a description of %Text; see here), Heading elements, and subsections.
There must be exactly one direct Heading element in a Section element, containing the heading of the section.
Note that a subsection is either a Subsection element or a ManSection element.
The Subsection element can have a Label attribute, such that this subsection can be referenced later on with a Ref element (see section 3.5-1). Note that you have to specify a label to reference the subsection as there is no automatic labelling!
Subsection elements can contain text (for a description of %Text; see here), and Heading elements.
There must be exactly one Heading element in a Subsection element, containing the heading of the subsection.
Another type of subsection is a ManSection, explained now:
3.4 ManSection–a special kind of subsection
ManSections are intended to describe a function, operation, method, variable, or some other technical instance. It is analogous to a manpage in the UNIX environment.
The ManSection element can have a Label attribute, such that this subsection can be referenced later on with a Ref element (see section 3.5-1). But this is probably rarely necessary because the elements Func and so on (explained below) generate automatically labels for cross referencing.
The content of a ManSection element is one or more elements describing certain items in GAP, each of them optionally followed by a Returns element, followed by a Description element, which contains %Text; (see here) describing it. (Remember to include examples in the description as often as possible, see 3.7-10). The classes of items GAPDoc knows of are: functions (Func), operations (Oper), methods (Meth), filters (Filt), properties (Prop), attributes (Attr), variables (Var), families (Fam), and info classes (InfoClass). One ManSection should only describe several of such items when these are very closely related.
Each element for an item corresponding to a GAP function can be followed by a Returns element. In output versions of the document the string "Returns: " will be put in front of the content text. The text in the Returns element should usually be a short hint about the type of object returned by the function. This is intended to give a good mnemonic for the use of a function (together with a good choice of names for the formal arguments).
ManSections are also sectioning elements which count as subsections. Usually there should be no Heading-element in a ManSection, in that case a heading is generated automatically from the first Func-like element. Sometimes this default behaviour does not look appropriate, for example when there are several Func-like elements. For such cases an optional Heading is allowed.
3.4-2 <Func>
<!ELEMENT Func EMPTY>
<!ATTLIST Func Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
This element is used within a ManSection element to specify the usage of a function. The Name attribute is required and its value is the name of the function. The value of the Arg attribute (also required) contains the full list of arguments including optional parts, which are denoted by square brackets. The argument names can be separated by whitespace, commas or the square brackets for the optional arguments, like "grp[, elm]" or "xx[y[z] ]". If GAP options are used, this can be followed by a colon : and one or more assignments, like "n[, r]: tries := 100".
The name of the function is also used as label for cross referencing. When the name of the function appears in the text of the document it should always be written with the Ref element, see 3.5-1. This allows to use a unique typesetting style for function names and automatic cross referencing.
If the optional Label attribute is given, it is appended (with a colon : in between) to the name of the function for cross referencing purposes. The text of the label can also appear in the document text. So, it should be a kind of short explanation.
<Func Arg="x[, y]" Name="LibFunc" Label="for my objects"/>
The optional Comm attribute should be a short description of the function, usually at most one line long (this is currently nowhere used).
This element automatically produces an index entry with the name of the function and, if present, the text of the Label attribute as subentry (see also 3.2-16 and 3.5-4).
3.4-3 <Oper>
<!ELEMENT Oper EMPTY>
<!ATTLIST Oper Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
This element is used within a ManSection element to specify the usage of an operation. The attributes are used exactly in the same way as in the Func element (see 3.4-2).
Note that multiple descriptions of the same operation may occur in a document because there may be several declarations in GAP. Furthermore there may be several ManSections for methods of this operation (see 3.4-4) which also use the same name. For reference purposes these must be distinguished by different Label attributes.
3.4-4 <Meth>
<!ELEMENT Meth EMPTY>
<!ATTLIST Meth Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
This element is used within a ManSection element to specify the usage of a method. The attributes are used exactly in the same way as in the Func element (see 3.4-2).
Frequently, an operation is implemented by several different methods. Therefore it seems to be interesting to document them independently. This is possible by using the same method name in different ManSections. It is however required that these subsections and those describing the corresponding operation are distinguished by different Label attributes.
3.4-5 <Filt>
<!ELEMENT Filt EMPTY>
<!ATTLIST Filt Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #IMPLIED
Comm CDATA #IMPLIED
Type CDATA #IMPLIED>
This element is used within a ManSection element to specify the usage of a filter. The first four attributes are used in the same way as in the Func element (see 3.4-2), except that the Arg attribute is optional.
The Type attribute can be any string, but it is thought to be something like "Category" or "Representation".
3.4-6 <Prop>
<!ELEMENT Prop EMPTY>
<!ATTLIST Prop Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
This element is used within a ManSection element to specify the usage of a property. The attributes are used exactly in the same way as in the Func element (see 3.4-2).
3.4-7 <Attr>
<!ELEMENT Attr EMPTY>
<!ATTLIST Attr Name CDATA #REQUIRED
Label CDATA #IMPLIED
Arg CDATA #REQUIRED
Comm CDATA #IMPLIED>
This element is used within a ManSection element to specify the usage of an attribute (in GAP). The attributes are used exactly in the same way as in the Func element (see 3.4-2).
3.4-8 <Var>
<!ELEMENT Var EMPTY>
<!ATTLIST Var Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
This element is used within a ManSection element to document a global variable. The attributes are used exactly in the same way as in the Func element (see 3.4-2) except that there is no Arg attribute.
3.4-9 <Fam>
<!ELEMENT Fam EMPTY>
<!ATTLIST Fam Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
This element is used within a ManSection element to document a family. The attributes are used exactly in the same way as in the Func element (see 3.4-2) except that there is no Arg attribute.
3.4-10 <InfoClass>
<!ELEMENT InfoClass EMPTY>
<!ATTLIST InfoClass Name CDATA #REQUIRED
Label CDATA #IMPLIED
Comm CDATA #IMPLIED>
This element is used within a ManSection element to document an info class. The attributes are used exactly in the same way as in the Func element (see 3.4-2) except that there is no Arg attribute.
3.5 Cross Referencing and Citations
Cross referencing in the GAPDoc system is somewhat different to the usual LaTeX cross referencing in so far, that a reference knows "which type of object" it is referencing. For example a "reference to a function" is distinguished from a "reference to a chapter". The idea of this is, that the markup must contain this information such that the converters can produce better output. The HTML converter can for example typeset a function reference just as the name of the function with a link to the description of the function, or a chapter reference as a number with a link in the other case.
The Ref element is defined to be EMPTY. If one of the attributes Func, Oper, Meth, Prop, Attr, Var, Fam, InfoClass, Chap, Sect, Subsect, Appendix is given then there must be exactly one of these, making the reference one to the corresponding object. The Label attribute can be specified in addition to make the reference unique, for example if more than one method with a given name is present. (Note that there is no way to specify in the DTD that exactly one of the first listed attributes must be given, this is an additional rule.)
A reference to a Label element defined below (see 3.5-2) is done by giving the Label attribute and optionally the Text attribute. If the Text attribute is present its value is typeset in place of the Ref element, if linking is possible (for example in HTML). If this is not possible, the section number is typeset. This type of reference is also used for references to tables (see 3.6-5).
An external reference into another book can be specified by using the BookName attribute. In this case the Label attribute or, if this is not given, the function or section like attribute, is used to resolve the reference. The generated reference points to the first hit when asking "?book name: label" inside GAP.
The optional attribute Style can take only the values Text and Number. It can be used with references to sectioning units and it gives a hint to the converter programs, whether an explicit section number is generated or text. Normally all references to sections generate numbers and references to a GAP object generate the name of the corresponding object with some additional link or sectioning information, which is the behavior of Style="Text". In case Style="Number" in all cases an explicit section number is generated. So
<Ref Subsect="Func" Style="Text"/> described in section
<Ref Subsect="Func" Style="Number"/>
<!ELEMENT Label EMPTY>
<!ATTLIST Label Name CDATA #REQUIRED>
This element is used to define a label for referencing a certain position in the document, if this is possible. If an exact reference is not possible (like in a printed version of the document) a reference to the corresponding subsection is generated. The value of the Name attribute must be unique under all Label elements.
This element is for bibliography citations. It is EMPTY by definition. The attribute Key is the key for a lookup in a BibTeX database that has to be specified in the Bibliography element (see 3.2-15). The value of the Where attribute specifies the position in the document as in the corresponding LaTeX syntax \cite[Where value]{Key value}.
3.5-4 <Index>
<!ELEMENT Index (%InnerText;|Subkey)*>
<!ATTLIST Index Key CDATA #IMPLIED
Subkey CDATA #IMPLIED>
<!ELEMENT Subkey (%InnerText;)*>
This element generates an index entry. The text within the element is typeset in the index entry, which is sorted under the value, that is specified in the Key and Subkey attributes. If they are not specified, the typeset text itself is used as the key.
A subkey can be specified in the simpler version as an attribute, but then no further markup can be used for the subkey. Optionally, the subkey text can be given in a Subkey element, in this case the attribute value is used for sorting but the typeset text is taken from the content of Subkey.
Note that all Func and similar elements automatically generate index entries. If the TheIndex element (3.2-16) is not present in the document all Index elements are ignored.
3.5-5 <URL>
<!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*> <!-- Link, LinkText
variant for case where text needs further markup -->
<!ATTLIST URL Text CDATA #IMPLIED> <!-- This is for output formats
that have links like HTML -->
<!ELEMENT Link (%InnerText;)*> <!-- the URL -->
<!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup -->
This element is for references into the internet. It specifies an URL and optionally a text which can be used for a link (like in HTML or PDF versions of the document). This can be specified in two ways: Either the URL is given as element content and the text is given in the optional Text attribute (in this case the text cannot contain further markup), or the element contains the two elements Link and LinkText which in turn contain the URL and the text, respectively. The default value for the text is the URL itself.
3.5-6 <Email>
<!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*>
This element type is the special case of an URL specifying an email address. The content of the element should be the email address without any prefix like "mailto:". This address is typeset by all converters, also without any prefix. In the case of an output document format like HTML the converter can produce a link with a "mailto:" prefix.
3.5-7 <Homepage>
<!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*>
This element type is the special case of an URL specifying a WWW-homepage.
3.6 Structural Elements like Lists
The GAPDoc system offers some limited access to structural elements like lists, enumerations, and tables. Although it is possible to use all LaTeX constructs one always has to think about other output formats. The elements in this section are guaranteed to produce something reasonable in all output formats.
3.6-1 <List>
<!ELEMENT List ( ((Mark,Item)|(BigMark,Item)|Item)+ )>
<!ATTLIST List Only CDATA #IMPLIED
Not CDATA #IMPLIED>
This element produces a list. Each item in the list corresponds to an Item element. Every Item element is optionally preceded by a Mark element. The content of this is used as a marker for the item. Note that this marker can be a whole word or even a sentence. It will be typeset in some emphasized fashion and most converters will provide some indentation for the rest of the item.
The Only and Not attributes can be used to specify, that the list is included into the output by only one type of converter (Only) or all but one type of converter (Not). Of course at most one of the two attributes may occur in one element. The following values are allowed as of now: "LaTeX", "HTML", and "Text". See also the Alt element in 3.9-1 for more about text alternatives for certain converters.
3.6-2 <Mark>
<!ELEMENT Mark ( %InnerText;)*>
This element is used in the List element to mark items. See 3.6-1 for an explanation.
3.6-3 <Item>
<!ELEMENT Item ( %Text;)*>
This element is used in the List, Enum, and Table elements to specify the items. See sections 3.6-1, 3.6-4, and 3.6-5 for further information.
3.6-4 <Enum>
<!ELEMENT Enum ( Item+ )>
<!ATTLIST Enum Only CDATA #IMPLIED
Not CDATA #IMPLIED>
This element is used like the List element (see 3.6-1) except that the items must not have marks attached to them. Instead, the items are numbered automatically. The same comments about the Only and Not attributes as above apply.
A table in GAPDoc consists of an optional Caption element followed by a sequence of Row and HorLine elements. A HorLine element produces a horizontal line in the table. A Row element consists of a sequence of Item elements as they also occur in List and Enum elements. The Only and Not attributes have the same functionality as described in the List element in 3.6-1.
The Align attribute is written like a LaTeX tabular alignment specifier but only the letters "l", "r", "c", and "|" are allowed meaning left alignment, right alignment, centered alignment, and a vertical line as delimiter between columns respectively.
If the Label attribute is there, one can reference the table with the Ref element (see 3.5-1) using its Label attribute.
Usually only simple tables should be used. If you want a complicated table in the LaTeX output you should provide alternatives for text and HTML output. Note that in HTML-4.0 there is no possibility to interpret the "|" column separators and HorLine elements as intended. There are lines between all columns and rows or no lines at all.
3.7 Types of Text
This section covers the markup of text. Various types of "text" exist. The following elements are used in the GAPDoc system to mark them. They mostly come in pairs, one long name which is easier to remember and a shortcut to make the markup "lighter".
Most of the following elements are thought to contain only character data and no further markup elements. It is however necessary to allow Alt elements to resolve the entities described in section 2.2-3.
3.7-1 <Emph> and <E>
<!ELEMENT Emph (%InnerText;)*> <!-- Emphasize something -->
<!ELEMENT E (%InnerText;)*> <!-- the same as shortcut -->
This element is used to emphasize some piece of text. It may contain %InnerText; (see here).
3.7-2 <Quoted> and <Q>
<!ELEMENT Quoted (%InnerText;)*> <!-- Quoted (in quotes) text -->
<!ELEMENT Q (%InnerText;)*> <!-- Quoted text (shortcut) -->
This element is used to put some piece of text into " "-quotes. It may contain %InnerText; (see here).
This element is used to mark something as a keyword. Usually this will be a GAP keyword such as "if" or "for". No further markup elements are allowed within this element except for the Alt element, which is necessary.
This element is used inside Descriptions in ManSections to mark something as an argument (of a function, operation, or such). It is guaranteed that the converters typeset those exactly as in the definition of functions. No further markup elements are allowed within this element.
3.7-5 <Code> and
<C>
<!ELEMENT Code (#PCDATA|Arg|Alt)*> <!-- GAP code -->
<!ELEMENT C (#PCDATA|Arg|Alt)*> <!-- GAP code (shortcut) -->
This element is used to mark something as a piece of code like for example a GAP expression. It is guaranteed that the converters typeset this exactly as in the Listing element (compare section 3.7-9). The only further markup elements allowed within this element are <Arg> elements (see 3.7-4).
This element is used to mark something as a button. It can also be used for other items in a graphical user interface like menus, menu entries, or keys. No further markup elements are allowed within this element.
3.7-8 <Package>
<!ELEMENT Package (#PCDATA|Alt)*> <!-- A package name -->
This element is used to mark something as a name of a package. This is for example used to define the entities GAP, XGAP or GAPDoc (see section 2.2-3). No further markup elements are allowed within this element.
3.7-9 <Listing>
<!ELEMENT Listing (#PCDATA)> <!-- This is just for GAP code listings -->
<!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of
listed code, may appear in
output -->
This element is used to embed listings of programs into the document. Only character data and no other elements are allowed in the content. You should not use the character entities described in section 2.2-3 but instead type the characters directly. Only the general XML rules from section 2.1 apply. Note especially the usage of <![CDATA[ sections described there. It is guaranteed that all converters use a fixed width font for typesetting Listing elements. Compare also the usage of the Code and C elements in 3.7-5.
The Type attribute contains a comment about the type of listed code. It may appear in the output.
3.7-10 <Log> and
<Example>
<!ELEMENT Example (#PCDATA)> <!-- This is subject to the automatic
example checking mechanism -->
<!ELEMENT Log (#PCDATA)> <!-- This not -->
These two elements behave exactly like the Listing element (see 3.7-9). They are thought for protocols of GAP sessions. The only difference between the two is that Example sections are intended to be subject to an automatic manual checking mechanism used to ensure the correctness of the GAP manual whereas Log is not touched by this (see section 5.4 for checking tools).
To get a good layout of the examples for display in a standard terminal we suggest to use SizeScreen([72]); (see SizeScreen (Reference: SizeScreen)) in your GAP session before producing the content of Example elements.
3.7-11 <Verb>
There is one further type of verbatim-like element.
<!ELEMENT Verb (#PCDATA)>
The content of such an element is guaranteed to be put into an output version exactly as it is using some fixed width font. Before the content a new line is started. If the line after the end of the start tag consists of whitespace only then this part of the content is skipped.
This element is intended to be used together with the Alt element to specify pre-formatted ASCII alternatives for complicated Display formulae or Tables.
3.8 Elements for Mathematical Formulae
3.8-1 <Math>
and <Display>
<!-- Normal TeX math mode formula -->
<!ELEMENT Math (#PCDATA|A|Arg|Alt)*>
<!-- TeX displayed math mode formula -->
<!ELEMENT Display (#PCDATA|A|Arg|Alt)*>
<!-- Mode="M" causes <M>-style formatting -->
<!ATTLIST Display Mode CDATA #IMPLIED>
These elements are used for mathematical formulae. As described in section 2.2-2 they correspond to LaTeX's math and display math mode respectively.
The formulae are typed in as in LaTeX, except that the standard XML entities, see 2.1-9 (in particular the characters < and &), must be escaped - either by using the corresponding entities or by enclosing the formula between "<![CDATA[" and "]]>". (The main reference for LaTeX is [Lam85].)
It is also possible to use some unicode characters for mathematical symbols directly, provided that it can be translated by Encode (6.2-2) into "LaTeX" encoding and that SimplifiedUnicodeString (6.2-2) with arguments "latin1" and "single" returns something sensible. Currently, we support entities &CC;, &ZZ;, &NN;, &PP;, &QQ;, &HH;, &RR; for the corresponding black board bold letters ℂ, ℤ, ℕ,ℙ, ℚ, ℍ and ℝ, respectively.
The only element type that is allowed within the formula elements is the Arg or A element (see 3.7-4), which is used to typeset identifiers that are arguments to GAP functions or operations.
If a Display element has an attribute Mode with value "M", then the formula is formatted as in M elements (see 3.8-2). Otherwise in text and HTML output the formula is shown as LaTeX source code.
For simple formulae (and you should try to make all your formulae simple!) attempt to use the M element or the Mode="M" attribute in Display for which there is a well defined translation into text, which can be used for text and HTML output versions of the document. So, if possible try to avoid the Math elements and Display elements without attribute or provide useful text substitutes for complicated formulae via Alt elements (see 3.9-1 and 3.7-11).
3.8-2 <M>
<!-- Math with well defined translation to text output -->
<!ELEMENT M (#PCDATA|A|Arg|Alt)*>
The "M" element type is intended for formulae in the running text for which there is a sensible text version. For the LaTeX version of a GAPDoc document the M and Math elements are equivalent. The remarks in 3.8-1 about special characters and the Arg element apply here as well. A document which has all formulae enclosed in M elements can be well readable in text terminal output and printed output versions.
Compared to former versions of GAPDoc many more formulae can be put into M elements. Most modern terminal emulations support unicode characters and many mathematical symbols can now be represented by such characters. But even if a terminal can only display ASCII characters, the user will see some not too bad representation of a formula.
As examples, here are some LaTeX macros which have a sensible ASCII translation and are guaranteed to be translated accordingly by text (and HTML) converters (for a full list of handled Macros see RecFields(TEXTMTRANSLATIONS)):
Table: LaTeX macros with special text translation
\ast
*
\bf
\bmod
mod
\cdot
*
\colon
:
\equiv
=
\geq
>=
\germ
\hookrightarrow
->
\iff
<=>
\langle
<
\ldots
...
\left
\leq
<=
\leftarrow
<-
\Leftarrow
<=
\limits
\longrightarrow
-->
\Longrightarrow
==>
\mapsto
->
\mathbb
\mathop
\mid
|
\pmod
mod
\prime
'
\rangle
>
\right
\rightarrow
->
\Rightarrow
=>
\rm, \sf, \textrm, \text
\setminus
\
\thinspace
\times
x
\to
->
\vert
|
\!
\,
\;
\{
{
\}
}
In all other macros only the backslash is removed (except for some macros describing more exotic symbols). Whitespace is normalized (to one blank) but not removed. Note that whitespace is not added, so you may want to add a few more spaces than you usually do in your LaTeX documents.
Braces {} are removed in general, however pairs of double braces are converted to one pair of braces. This can be used to write <M>x^{12}</M> for x^12 and <M>x_{{i+1}}</M> for x_{i+1}.
3.9 Everything else
3.9-1 <Alt>
This element is used to specify alternatives for different output formats within normal text. See also sections 3.6-1, 3.6-4, and 3.6-5 for alternatives in lists and tables.
<!ELEMENT Alt (%InnerText;)*> <!-- This is only to allow "Only" and
"Not" attributes for normal text -->
<!ATTLIST Alt Only CDATA #IMPLIED
Not CDATA #IMPLIED>
Of course exactly one of the two attributes must occur in one element. The attribute values must be one word or a list of words, separated by spaces or commas. The words which are currently recognized by the converter programs contained in GAPDoc are: "LaTeX", "HTML", and "Text". If the Only attribute is specified then only the corresponding converter will include the content of the element into the output document. If the Not attribute is specified the corresponding converter will ignore the content of the element. You can use other words to specify special alternatives for other converters of GAPDoc documents.
We fix a rule for handling the content of an Alt element with Only attribute. In their content code for the corresponding output format is included directly. So, in case of HTML the content is HTML code, in case of LaTeX the content is LaTeX code. The converters don't apply any handling of special characters to this content.
Within the element only %InnerText; (see here) is allowed. This is to ensure that the same set of chapters, sections, and subsections show up in all output formats.
3.9-2 <Par> and
<P>
<!ELEMENT Par EMPTY> <!-- this is intentionally empty! -->
<!ELEMENT P EMPTY> <!-- the same as shortcut -->
This EMPTY element marks the boundary of paragraphs. Note that an empty line in the input does not mark a new paragraph as opposed to the LaTeX convention.
(Remark: it would be much easier to parse a document and to understand its sectioning and paragraph structure when there was an element whose content is the text of a paragraph. But in practice many paragraph boundaries are implicitly clear which would make it somewhat painful to enclose each paragraph in extra tags. The introduction of the P or Par elements as above delegates this pain to the writer of a conversion program for GAPDoc documents.)
3.9-3 <Br>
<!ELEMENT Br EMPTY> <!-- a forced line break -->
This element can be used to force a line break in the output versions of a GAPDoc element, it does not start a new paragraph. Please, do not use this instead of a Par element, this would often lead to ugly output versions of your document.
This element can appear anywhere. Its content is ignored by the standard converters. It can be used, for example, to include data which are not part of the actual GAPDoc document, like source code, or to make not finished parts of the document invisible.
Of course, one can use special converter programs which extract the contents of Ignore elements. Information on the type of the content can be stored in the optional attribute Remark.
This section describes some utility functions for handling texts within GAP. They are used by the functions in the GAPDoc package but may be useful for other purposes as well. We start with some variables containing useful strings and go on with functions for parsing and reformatting text.
6.1-1 WHITESPACE
‣ WHITESPACE
( global variable )
‣ CAPITALLETTERS
( global variable )
‣ SMALLLETTERS
( global variable )
‣ LETTERS
( global variable )
‣ DIGITS
( global variable )
‣ HEXDIGITS
( global variable )
‣ BOXCHARS
( global variable )
These variables contain sets of characters which are useful for text processing. They are defined as follows.
WHITESPACE
" \n\t\r"
CAPITALLETTERS
"ABCDEFGHIJKLMNOPQRSTUVWXYZ"
SMALLLETTERS
"abcdefghijklmnopqrstuvwxyz"
LETTERS
concatenation of CAPITALLETTERS and SMALLLETTERS
DIGITS
"0123456789"
HEXDIGITS
"0123456789ABCDEFabcdef"
BOXCHARS
"─│┌┬┐├┼┤└┴┘━┃┏┳┓┣╋┫┗┻┛═║╔╦╗╠╬╣╚╩╝" , these are in UTF-8 encoding, the i-th unicode character is BOXCHARS{[3*i-2..3*i]}.
6.1-2 TextAttr
‣ TextAttr
( global variable )
The record TextAttr contains strings which can be printed to change the terminal attribute for the following characters. This only works with terminals which understand basic ANSI escape sequences. Try the following example to see if this is the case for the terminal you are using. It shows the effect of the foreground and background color attributes and of the .bold, .blink, .normal, .reverse and .underscore which can partly be mixed.
extra := ["CSI", "reset", "delline", "home"];;
for t in Difference(RecNames(TextAttr), extra) do
Print(TextAttr.(t), "TextAttr.", t, TextAttr.reset,"\n");
od;
The suggested defaults for colors 0..7 are black, red, green, brown, blue, magenta, cyan, white. But this may be different for your terminal configuration.
The escape sequence .delline deletes the content of the current line and .home moves the cursor to the beginning of the current line.
for i in [1..5] do
Print(TextAttr.home, TextAttr.delline, String(i,-6), "\c");
Sleep(1);
od;
Whenever you use this in some printing routines you should make it optional. Use these attributes only when UserPreference("UseColorsInTerminal"); returns true.
6.1-3 WrapTextAttribute
‣ WrapTextAttribute( str, attr )
( function )
Returns: a string with markup
The argument str must be a text as GAP string, possibly with markup by escape sequences as in TextAttr (6.1-2). This function returns a string which is wrapped by the escape sequences attr and TextAttr.reset. It takes care of markup in the given string by appending attr also after each given TextAttr.reset in str.
gap>str := Concatenation("XXX",TextAttr.2, "BLUB", TextAttr.reset,"YYY");
"XXX\033[32mBLUB\033[0mYYY"
gap>str2 := WrapTextAttribute(str, TextAttr.1);
"\033[31mXXX\033[32mBLUB\033[0m\033[31m\027YYY\033[0m"
gap>str3 := WrapTextAttribute(str, TextAttr.underscore);
"\033[4mXXX\033[32mBLUB\033[0m\033[4m\027YYY\033[0m"
gap># use Print(str); and so on to see how it looks like.
This function formats a text given in the string str as a paragraph. The optional arguments have the following meaning:
len
the length of the lines of the formatted text, default is 78 (counted without a visible length of the strings specified in the attr argument)
flush
can be "left", "right", "center" or "both", telling that lines should be flushed left, flushed right, centered or left-right justified, respectively, default is "both"
attr
is a list of two strings; the first is prepended and the second appended to each line of the result (can for example be used for indenting, [" ", ""], or some markup, [TextAttr.bold, TextAttr.reset], default is ["", ""])
widthfun
must be a function which returns the display width of text in str. The default is Length assuming that each byte corresponds to a character of width one. If str is given in UTF-8 encoding one can use WidthUTF8String (6.2-3) here.
This function tries to handle markup with the escape sequences explained in TextAttr (6.1-2) correctly.
gap>str := "One two three four five six seven eight nine ten eleven.";;gap>Print(FormatParagraph(str, 25, "left", ["/* ", " */"]));
/* One two three four five */
/* six seven eight nine ten */
/* eleven. */
This function looks for (non-overlapping) occurrences of a sublist sublist in a list list (compare PositionSublist (Reference: PositionSublist)) and returns a list where these are substituted with the list new.
The optional argument flag can either be "all" (this is the default if not given) or "one". In the second case only the first occurrence of sublist is substituted.
If sublist does not occur in list then list itself is returned (and not a ShallowCopy(list)).
Here list and strip must be lists. This function returns the sublist of list which does not contain the leading and trailing entries which are entries of strip. If the result is equal to list then list itself is returned.
gap>StripBeginEnd(" ,a, b,c, ", ", ");
"a, b,c"
6.1-7 StripEscapeSequences
‣ StripEscapeSequences( str )
( function )
Returns: string without escape sequences
This function returns the string one gets from the string str by removing all escape sequences which are explained in TextAttr (6.1-2). If str does not contain such a sequence then str itself is returned.
6.1-8 RepeatedString
‣ RepeatedString( c, len )
( function )
‣ RepeatedUTF8String( c, len )
( function )
Here c must be either a character or a string and len is a non-negative number. Then RepeatedString returns a string of length len consisting of copies of c.
In the variant RepeatedUTF8String the argument c is considered as string in UTF-8 encoding, and it can also be specified as unicode string or character, see Unicode (6.2-1). The result is a string in UTF-8 encoding which has visible width len as explained in WidthUTF8String (6.2-3).
The argument str of NumberDigits must be a string consisting only of an optional leading '-' and characters in 0123456789abcdefABCDEF, describing an integer in base base with \(2 \leq \textit{base} \leq 16\). This function returns the corresponding integer.
Here str must be a string and delim a string with two different characters. This function searches the smallest position r of the character delim[2] in str such that the number of occurrences of delim[2] in str between positions pos+1 and r is by one greater than the corresponding number of occurrences of delim[1].
If such an r exists, it is returned. Otherwise fail is returned.
The first function translates arbitrary binary data given as a GAP string into a base 64 encoded string. This encoded string contains only printable ASCII characters and is used in various data transfer protocols (MIME encoded emails, weak password encryption, ...). We use the specification in RFC 2045.
The second function has the reverse functionality. Here we also accept the characters -_ instead of +/ as last two characters. Whitespace is ignored.
gap>b := Base64String("This is a secret!");
"VGhpcyBpcyBhIHNlY3JldCEA="
gap>StringBase64(b);
"This is a secret!"
6.2 Unicode Strings
The GAPDoc package provides some tools to deal with unicode characters and strings. These can be used for recoding text strings between various encodings.
6.2-1 Unicode Strings and Characters
‣ Unicode( list[, encoding] )
( operation )
‣ UChar( num )
( operation )
‣ IsUnicodeString
( filter )
‣ IsUnicodeCharacter
( filter )
‣ IntListUnicodeString( ustr )
( function )
Unicode characters are described by their codepoint, an integer in the range from \(0\) to \(2^{21}-1\). For details about unicode, see http://www.unicode.org.
The function UChar wraps an integer num into a GAP object lying in the filter IsUnicodeCharacter. Use Int to get the codepoint back. The argument num can also be a GAP character which is then translated to an integer via IntChar (Reference: IntChar).
Unicode produces a GAP object in the filter IsUnicodeString. This is a wrapped list of integers for the unicode characters in the string. The function IntListUnicodeString gives access to this list of integers. Basic list functionality is available for IsUnicodeString elements. The entries are in IsUnicodeCharacter. The argument list for Unicode is either a list of integers or a GAP string. In the latter case an encoding can be specified as string, its default is "UTF-8".
Currently supported encodings can be found in UNICODE_RECODE.NormalizedEncodings (ASCII, ISO-8859-X, UTF-8 and aliases). The encoding "XML" means an ASCII encoding in which non-ASCII characters are specified by XML character entities. The encoding "URL" is for URL-encoded (also called percent-encoded strings, as specified in RFC 3986 (see here). The listed encodings "LaTeX" and aliases cannot be used with Unicode. See the operation Encode (6.2-2) for mapping a unicode string to a GAP string.
gap>ustr := Unicode("a and \366", "latin1");
Unicode("a and \303\266")
gap>ustr = Unicode("a and ö", "XML");
true
gap>IntListUnicodeString(ustr);
[ 97, 32, 97, 110, 100, 32, 246 ]
gap>ustr[7];
'ö'
The operation Encode translates a unicode string ustr into a GAP string in some specified encoding. The default encoding is "UTF-8".
Supported encodings can be found in UNICODE_RECODE.NormalizedEncodings. Except for some cases mentioned below characters which are not available in the target encoding are substituted by '?' characters.
If the encoding is "URL" (see Unicode (6.2-1)) then an optional argument encreserved can be given, it must be a list of reserved characters which should be percent encoded; the default is to encode only the % character.
The encoding "LaTeX" substitutes non-ASCII characters and LaTeX special characters by LaTeX code as given in an ordered list LaTeXUnicodeTable of pairs [codepoint, string]. If you have a unicode character for which no substitution is contained in that list, you will get a warning and the translation is Unicode(nr). In this case find a substitution and add a corresponding [codepoint, string] pair to LaTeXUnicodeTable using AddSet (Reference: AddSet). Also, please, tell the GAPDoc authors about your addition, such that we can extend the list LaTeXUnicodeTable. (Most of the initial entries were generated from lists in the TeX projects encTeX and ucs.) There are some variants of this encoding:
"LaTeXleavemarkup" does the same translations for non-ASCII characters but leaves the LaTeX special characters (e.g., any LaTeX commands) as they are.
"LaTeXUTF8" does not give a warning about unicode characters without explicit translation, instead it translates the character to its UTF-8 encoding. Make sure to setup your LaTeX document such that all these characters are understood.
"LaTeXUTF8leavemarkup" is a combination of the last two variants.
Note that the "LaTeX" encoding can only be used with Encode but not for the opposite translation with Unicode (6.2-1) (which would need far too complicated heuristics).
The function SimplifiedUnicodeString can be used to substitute many non-ASCII characters by related ASCII characters or strings (e.g., by a corresponding character without accents). The argument ustr and the result are unicode strings, if encoding is "ASCII" then all non-ASCII characters are translated, otherwise only the non-latin1 characters. If the string "single" in an argument then only substitutions are considered which don't make the result string longer. The translations are stored in a sorted list SimplifiedUnicodeTable. Its entries are of the form [codepoint, trans1, trans2, ...]. Here trans1 and so on is either an integer for the codepoint of a substitution character or it is a list of codepoint integers. If you are missing characters in this list and know a sensible ASCII approximation, then add an entry (with AddSet (Reference: AddSet)) and tell the GAPDoc authors about it. (The initial content of SimplifiedUnicodeTable was mainly generated from the "transtab" tables by Markus Kuhn.)
The function LowercaseUnicodeString gets and returns a unicode string and translates each uppercase character to its corresponding lowercase version. This function uses a list LowercaseUnicodeTable of pairs of codepoint integers. This list was generated using the file UnicodeData.txt from the unicode definition (field 14 in each row).
The function UppercaseUnicodeString does the similar translation to uppercase characters.
gap>ustr := Unicode("a and ö", "XML");
Unicode("a and \303\266")
gap>SimplifiedUnicodeString(ustr, "ASCII");
Unicode("a and oe")
gap>SimplifiedUnicodeString(ustr, "ASCII", "single");
Unicode("a and o")
gap>ustr2 := UppercaseUnicodeString(ustr);;gap>Print(Encode(ustr2, GAPInfo.TermEncoding), "\n");
A AND Ö
6.2-3 Lengths of UTF-8 strings
‣ WidthUTF8String( str )
( function )
‣ NrCharsUTF8String( str )
( function )
Returns: an integer
Let str be a GAP string with text in UTF-8 encoding. There are three "lengths" of such a string which must be distinguished. The operation Length (Reference: Length) returns the number of bytes and so the memory occupied by str. The function NrCharsUTF8String returns the number of unicode characters in str, that is the length of Unicode(str).
In many applications the function WidthUTF8String is more interesting, it returns the number of columns needed by the string if printed to a terminal. This takes into account that some unicode characters are combining characters and that there are wide characters which need two columns (e.g., for Chinese or Japanese). (To be precise: This implementation assumes that there are no control characters in str and uses the character width returned by the wcwidth function in the GNU C-library called with UTF-8 locale.)
gap># A, German umlaut u, B, zero width space, C, newlinegap>str := Encode( Unicode( "AüB​C\n", "XML" ) );;gap>Print(str);
AüBC
gap># umlaut u needs two bytes and the zero width space threegap>Length(str);
9
gap>NrCharsUTF8String(str);
6
gap># zero width space and newline don't contribute to widthgap>WidthUTF8String(str);
4
6.3 Print Utilities
The following printing utilities turned out to be useful for interactive work with texts in GAP. But they are more general and so we document them here.
6.3-1 PrintTo1
‣ PrintTo1( filename, fun )
( function )
‣ AppendTo1( filename, fun )
( function )
The argument fun must be a function without arguments. Everything which is printed by a call fun() is printed into the file filename. As with PrintTo (Reference: PrintTo) and AppendTo (Reference: AppendTo) this overwrites or appends to, respectively, a previous content of filename.
These functions can be particularly efficient when many small pieces of text shall be written to a file, because no multiple reopening of the file is necessary.
gap>f := function() local i; > for i in [1..100000] do Print(i, "\n"); od; end;; gap>PrintTo1("nonsense", f); # now check the local file `nonsense'
6.3-2 StringPrint
‣ StringPrint( obj1[, obj2[, ...]] )
( function )
‣ StringView( obj )
( function )
These functions return a string containing the output of a Print or ViewObj call with the same arguments.
This should be considered as a (temporary?) hack. It would be better to have String (Reference: String) methods for all GAP objects and to have a generic Print (Reference: Print)-function which just interprets these strings.
6.3-3 PrintFormattedString
‣ PrintFormattedString( str )
( function )
This function prints a string str. The difference to Print(str); is that no additional line breaks are introduced by GAP's standard printing mechanism. This can be used to print lines which are longer than the current screen width. In particular one can print text which contains escape sequences like those explained in TextAttr (6.1-2), where lines may have more characters than visible characters.
6.3-4 Page
‣ Page( ... )
( function )
‣ PageDisplay( obj )
( function )
These functions are similar to Print (Reference: Print) and Display (Reference: Display), respectively. The difference is that the output is not sent directly to the screen, but is piped into the current pager; see Pager (Reference: Pager).
The function StringFile returns the content of file filename as a string. This works efficiently with arbitrary (binary or text) files. If something went wrong, this function returns fail.
Conversely the function FileString writes the content of a string str into the file filename. If the optional third argument append is given and equals true then the content of str is appended to the file. Otherwise previous content of the file is deleted. This function returns the number of bytes written or fail if something went wrong.
Both functions are quite efficient, even with large files.
GAPDoc-1.5.1/doc/textutil.xml 0000644 0001750 0001750 00000003240 12026346063 014353 0 ustar bill bill
String and Text UtilitiesText Utilities
This section describes some utility functions for handling texts within
&GAP;. They are used by the functions in the &GAPDoc; package but may be
useful for other purposes as well. We start with some variables containing
useful strings and go on with functions for parsing and reformatting text.
<#Include Label="CharsColls">
<#Include Label="TextAttr">
<#Include Label="WrapTextAttribute">
<#Include Label="FormatParagraph">
<#Include Label="SubstitutionSublist">
<#Include Label="StripBeginEnd">
<#Include Label="StripEscapeSequences">
<#Include Label="RepeatedString">
<#Include Label="NumberDigits">
<#Include Label="PositionMatchingDelimiter">
<#Include Label="WordsString">
<#Include Label="Base64String">
Unicode Strings
The &GAPDoc; package provides some tools to deal with unicode characters
and strings. These can be used for recoding text strings between various
encodings.
<#Include Label="Unicode">
<#Include Label="Encode">
<#Include Label="WidthUTF8String">
Print Utilities
The following printing utilities turned out to be useful for interactive
work with texts in &GAP;. But they are more general and so we document them
here.
<#Include Label="PrintTo1">
<#Include Label="StringPrint">
<#Include Label="PrintFormattedString">
<#Include Label="Page">
<#Include Label="StringFile">
GAPDoc-1.5.1/doc/chap2.txt 0000644 0001750 0001750 00000042202 12026346063 013506 0 ustar bill bill
[1X2 [33X[0;0YHow To Type a [5XGAPDoc[105X[101X[1X Document[133X[101X
[33X[0;0YIn this chapter we give a more formal description of what you need to start
to type documentation in [5XGAPDoc[105X XML format. Many details were already
explained by example in Section [14X1.2[114X of the introduction.[133X
[33X[0;0YWe do [13Xnot[113X answer the question [21XHow to [13Xwrite[113X a [5XGAPDoc[105X document?[121X in this
chapter. You can (hopefully) find an answer to this question by studying the
example in the introduction, see [14X1.2[114X, and learning about more details in the
reference Chapter [14X3[114X.[133X
[33X[0;0YThe definite source for all details of the official XML standard with useful
annotations is:[133X
[33X[0;0Y[7Xhttp://www.xml.com/axml/axml.html[107X[133X
[33X[0;0YAlthough this document must be quite technical, it is surprisingly well
readable.[133X
[1X2.1 [33X[0;0YGeneral XML Syntax[133X[101X
[33X[0;0YWe will now discuss the pieces of text which can occur in a general XML
document. We start with those pieces which do not contribute to the actual
content of the document.[133X
[1X2.1-1 [33X[0;0YHead of XML Document[133X[101X
[33X[0;0YEach XML document should have a head which states that it is an XML document
in some encoding and which XML-defined language is used. In case of a [5XGAPDoc[105X
document this should always look as in the following example.[133X
[4X[32X Example [32X[104X
[4X[28X[128X[104X
[4X[28X[128X[104X
[4X[32X[104X
[33X[0;0YSee [14X2.1-13[114X for a remark on the [21Xencoding[121X statement.[133X
[33X[0;0Y(There may be local entity definitions inside the [10XDOCTYPE[110X statement, see
Subsection [14X2.2-3[114X below.)[133X
[1X2.1-2 [33X[0;0YComments[133X[101X
[33X[0;0YA [21Xcomment[121X in XML starts with the character sequence [21X[10X[110X[121X. Between these sequences there must not be two adjacent dashes
[21X[10X--[110X[121X.[133X
[1X2.1-3 [33X[0;0YProcessing Instructions[133X[101X
[33X[0;0YA [21Xprocessing instruction[121X in XML starts with the character sequence [21X[10X[110X[121X must not occur
within the processing instruction.[133X
[33X[0;0Y [133X
[33X[0;0YAnd now we turn to those parts of the document which contribute to its
actual content.[133X
[1X2.1-4 [33X[0;0YNames in XML and Whitespace[133X[101X
[33X[0;0YA [21Xname[121X in XML (used for element and attribute identifiers, see below) must
start with a letter (in the encoding of the document) or with a colon [21X[10X:[110X[121X or
underscore [21X[10X_[110X[121X character. The following characters may also be digits, dots [21X[10X.[110X[121X
or dashes [21X[10X-[110X[121X.[133X
[33X[0;0YThis is a simplified description of the rules in the standard, which are
concerned with lots of unicode ranges to specify what a [21Xletter[121X is.[133X
[33X[0;0YSequences only consisting of the following characters are considered as
[13Xwhitespace[113X: blanks, tabs, carriage return characters and new line
characters.[133X
[1X2.1-5 [33X[0;0YElements[133X[101X
[33X[0;0YThe actual content of an XML document consists of [21Xelements[121X. An element has
some [21Xcontent[121X with a leading [21Xstart tag[121X ([14X2.1-6[114X) and a trailing [21Xend tag[121X
([14X2.1-7[114X). The content can contain further elements but they must be properly
nested. One can define elements whose content is always empty, those
elements can also be entered with a single combined tag ([14X2.1-8[114X).[133X
[1X2.1-6 [33X[0;0YStart Tags[133X[101X
[33X[0;0YA [21Xstart-tag[121X consists of a less-than-character [21X[10X<[110X[121X directly followed (without
whitespace) by an element name (see [14X2.1-4[114X), optional attributes, optional
whitespace, and a greater-than-character [21X[10X>[110X[121X.[133X
[33X[0;0YAn [21Xattribute[121X consists of some whitespace and then its name followed by an
equal sign [21X[10X=[110X[121X which is optionally enclosed by whitespace, and the attribute
value, which is enclosed either in single or double quotes. The attribute
value may not contain the type of quote used as a delimiter or the character
[21X[10X<[110X[121X, the character [21X[10X&[110X[121X may only appear to start an entity, see [14X2.1-9[114X. We
describe in [14X2.1-11[114X how to enter special characters in attribute values.[133X
[33X[0;0YNote especially that no whitespace is allowed between the starting [21X[10X<[110X[121X
character and the element name. The quotes around an attribute value cannot
be omitted. The names of elements and attributes are [13Xcase sensitive[113X.[133X
[1X2.1-7 [33X[0;0YEnd Tags[133X[101X
[33X[0;0YAn [21Xend tag[121X consists of the two characters [21X[10X[110X[121X.[133X
[1X2.1-8 [33X[0;0YCombined Tags for Empty Elements[133X[101X
[33X[0;0YElements which always have empty content can be written with a single tag.
This looks like a start tag (see [14X2.1-6[114X) [13Xexcept[113X that the trailing
greater-than-character [21X[10X>[110X[121X is substituted by the two character sequence [21X[10X/>[110X[121X.[133X
[1X2.1-9 [33X[0;0YEntities[133X[101X
[33X[0;0YAn [21Xentity[121X in XML is a macro for some substitution text. There are two types
of entities.[133X
[33X[0;0YA [21Xcharacter entity[121X can be used to specify characters in the encoding of the
document (can be useful for entering non-ASCII characters which you cannot
manage to type in directly). They are entered with a sequence [21X[10X&#[110X[121X, directly
followed by either some decimal digits or an [21X[10Xx[110X[121X and some hexadecimal digits,
directly followed by a semicolon [21X[10X;[110X[121X. Using such a character entity is just
equivalent to typing the corresponding character directly.[133X
[33X[0;0YThen there are references to [21Xnamed entities[121X. They are entered with an
ampersand character [21X[10X&[110X[121X directly followed by a name which is directly followed
by a semicolon [21X[10X;[110X[121X. Such entities must be declared somewhere by giving a
substitution text. This text is included in the document and the document is
parsed again afterwards. The exact rules are a bit subtle but you probably
want to use this only in simple cases. Predefined entities for [5XGAPDoc[105X are
described in [14X2.1-10[114X and [14X2.2-3[114X.[133X
[1X2.1-10 [33X[0;0YSpecial Characters in XML[133X[101X
[33X[0;0YWe have seen that the less-than-character [21X[10X<[110X[121X and the ampersand character [21X[10X&[110X[121X
start a tag or entity reference in XML. To get these characters into the
document text one has to use entity references, namely [21X[10X<[110X[121X to get [21X[10X<[110X[121X and
[21X[10X&[110X[121X to get [21X[10X&[110X[121X. Furthermore [21X[10X>[110X[121X must be used to get [21X[10X>[110X[121X when the string [21X[10X]]>[110X[121X
appears in element content (and not as delimiter of a [10XCDATA[110X section
explained below).[133X
[33X[0;0YAnother possibility is to use a [10XCDATA[110X statement explained in [14X2.1-12[114X.[133X
[1X2.1-11 [33X[0;0YRules for Attribute Values[133X[101X
[33X[0;0YAttribute values can contain entities which are substituted recursively. But
except for the entities < or a character entity it is not allowed that a
< character is introduced by the substitution (there is no XML parsing for
evaluating the attribute value, just entity substitutions).[133X
[1X2.1-12 [33X[0;0Y[10XCDATA[110X[101X[1X[133X[101X
[33X[0;0YPieces of text which contain many characters which can be misinterpreted as
markup can be enclosed by the character sequences [21X[10X[110X[121X.
Everything between these sequences is considered as content of the document
and is not further interpreted as XML text. All the rules explained so far
in this section do [13Xnot apply[113X to such a part of the document. The only
document content which cannot be entered directly inside a [10XCDATA[110X statement
is the sequence [21X[10X]]>[110X[121X. This can be entered as [21X[10X]]>[110X[121X outside the [10XCDATA[110X
statement.[133X
[4X[32X Example [32X[104X
[4X[28XA nesting of tags like is not allowed.[128X[104X
[4X[32X[104X
[1X2.1-13 [33X[0;0YEncoding of an XML Document[133X[101X
[33X[0;0YWe suggest to use the UTF-8 encoding for writing [5XGAPDoc[105X XML documents. But
the tools described in Chapter [14X5[114X also work with ASCII or the various
ISO-8859-X encodings (ISO-8859-1 is also called latin1 and covers most
special characters for western European languages).[133X
[1X2.1-14 [33X[0;0YWell Formed and Valid XML Documents[133X[101X
[33X[0;0YWe want to mention two further important words which are often used in the
context of XML documents. A piece of text becomes a [21Xwell formed[121X XML document
if all the formal rules described in this section are fulfilled.[133X
[33X[0;0YBut this says nothing about the content of the document. To give this
content a meaning one needs a declaration of the element and corresponding
attribute names as well as of named entities which are allowed. Furthermore
there may be restrictions how such elements can be nested. This [13Xdefinition
of an XML based markup language[113X is done in a [21Xdocument type definition[121X. An
XML document which contains only elements and entities declared in such a
document type definition and obeys the rules given there is called [21Xvalid
(with respect to this document type definition)[121X.[133X
[33X[0;0YThe main file of the [5XGAPDoc[105X package is [11Xgapdoc.dtd[111X. This contains such a
definition of a markup language. We are not going to explain the formal
syntax rules for document type definitions in this section. But in Chapter [14X3[114X
we will explain enough about it to understand the file [11Xgapdoc.dtd[111X and so the
markup language defined there.[133X
[1X2.2 [33X[0;0YEntering [5XGAPDoc[105X[101X[1X Documents[133X[101X
[33X[0;0YHere are some additional rules for writing [5XGAPDoc[105X XML documents.[133X
[1X2.2-1 [33X[0;0YOther special characters[133X[101X
[33X[0;0YAs [5XGAPDoc[105X documents are used to produce LaTeX and HTML documents, the
question arises how to deal with characters with a special meaning for other
applications (for example [21X[10X&[110X[121X, [21X[10X#[110X[121X, [21X[10X$[110X[121X, [21X[10X%[110X[121X, [21X[10X~[110X[121X, [21X[10X\[110X[121X, [21X[10X{[110X[121X, [21X[10X}[110X[121X, [21X[10X_[110X[121X, [21X[10X^[110X[121X, [21X[10X [110X[121X (this is a
non-breakable space, [21X[10X~[110X[121X in LaTeX) have a special meaning for LaTeX and [21X[10X&[110X[121X, [21X[10X<[110X[121X,
[21X[10X>[110X[121X have a special meaning for HTML (and XML). In [5XGAPDoc[105X you can usually just
type these characters directly, it is the task of the converter programs
which translate to some output format to take care of such special
characters. The exceptions to this simple rule are:[133X
[30X [33X[0;6Y& and < must be entered as [10X&[110X and [10X<[110X as explained in [14X2.1-10[114X.[133X
[30X [33X[0;6YThe content of the [5XGAPDoc[105X elements [10X[110X, [10X