1% generated by GAPDoc2LaTeX from XML source (Frank Luebeck) 2\documentclass[a4paper,11pt]{report} 3 4\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry} 5\sloppy 6\pagestyle{myheadings} 7\usepackage{amssymb} 8\usepackage[latin1]{inputenc} 9\usepackage{makeidx} 10\makeindex 11\usepackage{color} 12\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083} 13\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179} 14\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894} 15\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894} 16\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000} 17\definecolor{Black}{rgb}{0.0,0.0,0.0} 18 19\definecolor{linkColor}{rgb}{0.0,0.0,0.554} 20\definecolor{citeColor}{rgb}{0.0,0.0,0.554} 21\definecolor{fileColor}{rgb}{0.0,0.0,0.554} 22\definecolor{urlColor}{rgb}{0.0,0.0,0.554} 23\definecolor{promptColor}{rgb}{0.0,0.0,0.589} 24\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0} 25\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0} 26\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0} 27 28%% for a long time these were red and blue by default, 29%% now black, but keep variables to overwrite 30\definecolor{FuncColor}{rgb}{0.0,0.0,0.0} 31%% strange name because of pdflatex bug: 32\definecolor{Chapter }{rgb}{0.0,0.0,0.0} 33\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064} 34 35 36\usepackage{fancyvrb} 37 38\usepackage{mathptmx,helvet} 39\usepackage[T1]{fontenc} 40\usepackage{textcomp} 41 42 43\usepackage[ 44 pdftex=true, 45 bookmarks=true, 46 a4paper=true, 47 pdftitle={Written with GAPDoc}, 48 pdfcreator={LaTeX with hyperref package / GAPDoc}, 49 colorlinks=true, 50 backref=page, 51 breaklinks=true, 52 linkcolor=linkColor, 53 citecolor=citeColor, 54 filecolor=fileColor, 55 urlcolor=urlColor, 56 pdfpagemode={UseNone}, 57 ]{hyperref} 58 59\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont} 60 61% write page numbers to a .pnr log file for online help 62\newwrite\pagenrlog 63\immediate\openout\pagenrlog =\jobname.pnr 64\immediate\write\pagenrlog{PAGENRS := [} 65\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}} 66%% were never documented, give conflicts with some additional packages 67 68\newcommand{\GAP}{\textsf{GAP}} 69 70%% nicer description environments, allows long labels 71\usepackage{enumitem} 72\setdescription{style=nextline} 73 74%% depth of toc 75\setcounter{tocdepth}{1} 76 77 78 79 80 81%% command for ColorPrompt style examples 82\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}} 83\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}} 84\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}} 85 86 87\begin{document} 88 89\logpage{[ 0, 0, 0 ]} 90\begin{titlepage} 91\mbox{}\vfill 92 93\begin{center}{\maintitlesize \textbf{\textsf{GAPDoc}\mbox{}}}\\ 94\vfill 95 96\hypersetup{pdftitle=\textsf{GAPDoc}} 97\markright{\scriptsize \mbox{}\hfill \textsf{GAPDoc} \hfill\mbox{}} 98{\Huge ( Version 1.6.3 ) \mbox{}}\\[1cm] 99{July 2019\mbox{}}\\[1cm] 100\mbox{}\\[2cm] 101{\Large \textbf{ Frank L{\"u}beck \mbox{}}}\\ 102{\Large \textbf{ Max Neunh{\"o}ffer \mbox{}}}\\ 103\hypersetup{pdfauthor= Frank L{\"u}beck ; Max Neunh{\"o}ffer } 104\end{center}\vfill 105 106\mbox{}\\ 107{\mbox{}\\ 108\small \noindent \textbf{ Frank L{\"u}beck } Email: \href{mailto://Frank.Luebeck@Math.RWTH-Aachen.De} {\texttt{Frank.Luebeck@Math.RWTH-Aachen.De}}\\ 109 Homepage: \href{http://www.math.rwth-aachen.de/~Frank.Luebeck} {\texttt{http://www.math.rwth-aachen.de/\texttt{\symbol{126}}Frank.Luebeck}}}\\ 110{\mbox{}\\ 111\small \noindent \textbf{ Max Neunh{\"o}ffer } Email: \href{mailto://neunhoef at mcs.st-and.ac.uk} {\texttt{neunhoef at mcs.st-and.ac.uk}}\\ 112 Homepage: \href{http://www-groups.mcs.st-and.ac.uk/~neunhoef/} {\texttt{http://www-groups.mcs.st-and.ac.uk/\texttt{\symbol{126}}neunhoef/}}}\\ 113\end{titlepage} 114 115\newpage\setcounter{page}{2} 116{\small 117\section*{Copyright} 118\logpage{[ 0, 0, 1 ]} 119 \index{License} {\copyright} 2000-2019 by Frank L{\"u}beck and Max Neunh{\"o}ffer 120 121 \textsf{GAPDoc} is free software; you can redistribute it and/or modify it under the terms of 122the \href{http://www.fsf.org/licenses/gpl.html} {GNU General Public License} as published by the Free Software Foundation; either version 2 of the License, 123or (at your option) any later version. \mbox{}}\\[1cm] 124\newpage 125 126\def\contentsname{Contents\logpage{[ 0, 0, 2 ]}} 127 128\tableofcontents 129\newpage 130 131 132\chapter{\textcolor{Chapter }{Introduction and Example}}\label{ch:intro} 133\logpage{[ 1, 0, 0 ]} 134\hyperdef{L}{X7D4EE663818DA109}{} 135{ 136 The main purpose of the \textsf{GAPDoc} package is to define a file format for documentation of \textsf{GAP}-programs and -packages (see \cite{GAP4}). The problem is that such documentation should be readable in several output 137formats. For example it should be possible to read the documentation inside 138the terminal in which \textsf{GAP} is running (a text mode) and there should be a printable version in high 139typesetting quality (produced by some version of {\TeX}). It is also popular to view \textsf{GAP}'s online help with a Web-browser via an HTML-version of the documentation. 140Nowadays one can use {\LaTeX} and standard viewer programs to produce and view on the screen \texttt{dvi}- or \texttt{pdf}-files with full support of internal and external hyperlinks. Certainly there 141will be other interesting document formats and tools in this direction in the 142future. 143 144 Our aim is to find a \emph{format for writing} the documentation which allows a relatively easy translation into the output 145formats just mentioned and which hopefully makes it easy to translate to 146future output formats as well. 147 148 To make documentation written in the \textsf{GAPDoc} format directly usable, we also provide a set of programs, called converters, 149which produce text-, hyperlinked {\LaTeX}- and HTML-output versions of a \textsf{GAPDoc} document. These programs are developed by the first named author. They run 150completely inside \textsf{GAP}, i.e., no external programs are needed. You only need \texttt{latex} and \texttt{pdflatex} to process the {\LaTeX} output. These programs are described in Chapter{\nobreakspace}\ref{ch:conv}. 151\section{\textcolor{Chapter }{XML}}\label{sec:XML} 152\logpage{[ 1, 1, 0 ]} 153\hyperdef{L}{X8590236E858F7E93}{} 154{ 155 \index{XML} The definition of the \textsf{GAPDoc} format uses XML, the ``eXtendible Markup Language''. This is a standard (defined by the W3C consortium, see \href{http://www.w3c.org} {\texttt{http://www.w3c.org}}) which lays down a syntax for adding markup to a document or to some data. It 156allows to define document structures via introducing markup \emph{elements} and certain relations between them. This is done in a \emph{document type definition}. The file \texttt{gapdoc.dtd} contains such a document type definition and is the central part of the \textsf{GAPDoc} package. 157 158 The easiest way for getting a good idea about this is probably to look at an 159example. The Appendix{\nobreakspace}\ref{app:3k+1} contains a short but complete \textsf{GAPDoc} document for a fictitious share package. In the next section we will go 160through this document, explain basic facts about XML and the \textsf{GAPDoc} document type, and give pointers to more details in later parts of this 161documentation. 162 163 In the last Section{\nobreakspace}\ref{sec:faq} of this introductory chapter we try to answer some general questions about the 164decisions which lead to the \textsf{GAPDoc} package. } 165 166 167\section{\textcolor{Chapter }{A complete example}}\label{sec:3k+1expl} 168\logpage{[ 1, 2, 0 ]} 169\hyperdef{L}{X7B47AFA881BFC9DC}{} 170{ 171 In this section we recall the lines from the example document in 172Appendix{\nobreakspace}\ref{app:3k+1} and give some explanations. 173\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 174 <?xml version="1.0" encoding="UTF-8"?> 175\end{Verbatim} 176 This line just tells a human reader and computer programs that the file is a 177document with XML markup and that the text is encoded in the UTF-8 character 178set (other common encodings are ASCII or ISO-8895-X encodings). 179\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 180 <!-- A complete "fake package" documentation 181 --> 182\end{Verbatim} 183 Everything in a XML file between ``\texttt{{\textless}!--}'' and ``\texttt{--{\textgreater}}'' is a comment and not part of the document content. 184\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 185 <!DOCTYPE Book SYSTEM "gapdoc.dtd"> 186\end{Verbatim} 187 This line says that the document contains markup which is defined in the 188system file \texttt{gapdoc.dtd} and that the markup obeys certain rules defined in that file (the ending \texttt{dtd} means ``document type definition''). It further says that the actual content of the document consists of an 189element with name ``Book''. And we can really see that the remaining part of the file is enclosed as 190follows: 191\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 192 <Book Name="3k+1"> 193 [...] (content omitted) 194 </Book> 195\end{Verbatim} 196 This demonstrates the basics of the markup in XML. This part of the document 197is an ``element''. It consists of the ``start tag'' \texttt{{\textless}Book Name="3k+1"{\textgreater}}, the ``element content'' and the ``end tag'' \texttt{{\textless}/Book{\textgreater}} (end tags always start with \texttt{{\textless}/}). This element also has an ``attribute'' \texttt{Name} whose ``value'' is \texttt{3k+1}. 198 199 If you know HTML, this will look familiar to you. But there are some important 200differences: The element name \texttt{Book} and attribute name \texttt{Name} are \emph{case sensitive}. The value of an attribute must \emph{always} be enclosed in quotes. In XML \emph{every} element has a start and end tag (which can be combined for elements defined as ``empty'', see for example \texttt{{\textless}TableOfContents/{\textgreater}} below). 201 202 If you know {\LaTeX}, you are familiar with quite different types of markup, for example: The 203equivalent of the \texttt{Book} element in {\LaTeX} is \texttt{\texttt{\symbol{92}}begin\texttt{\symbol{123}}document\texttt{\symbol{125}} 204... \texttt{\symbol{92}}end\texttt{\symbol{123}}document\texttt{\symbol{125}}}. The sectioning in {\LaTeX} is not done by explicit start and end markup, but implicitly via heading 205commands like \texttt{\texttt{\symbol{92}}section}. Other markup is done by using braces \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} and putting some commands inside. And for mathematical formulae one can use 206the \texttt{\$} for the start \emph{and} the end of the markup. In XML \emph{all} markup looks similar to that of the \texttt{Book} element. 207 208 The content of the book starts with a title page. 209\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 210 <TitlePage> 211 <Title>The <Package>ThreeKPlusOne</Package> Package</Title> 212 <Version>Version 42</Version> 213 <Author>Dummy Auth�r 214 <Email>3kplusone@dev.null</Email> 215 </Author> 216 217 <Copyright>©right; 2000 The Author. <P/> 218 You can do with this package what you want.<P/> Really. 219 </Copyright> 220 </TitlePage> 221\end{Verbatim} 222 The content of the \texttt{TitlePage} element consists again of elements. In Chapter{\nobreakspace}\ref{DTD} we describe which elements are allowed within a \texttt{TitlePage} and that their ordering is prescribed in this case. In the (stupid) name of 223the author you see that a German umlaut is used directly (in ISO-latin1 224encoding). 225 226 Contrary to {\LaTeX}- or HTML-files this markup does not say anything about the actual layout of 227the title page in any output version of the document. It just adds information 228about the \emph{meaning} of pieces of text. 229 230 Within the \texttt{Copyright} element there are two more things to learn about XML markup. The \texttt{{\textless}P/{\textgreater}} is a complete element. It is a combined start and end tag. This shortcut is 231allowed for elements which are defined to be always ``empty'', i.e., to have no content. You may have already guessed that \texttt{{\textless}P/{\textgreater}} is used as a paragraph separator. Note that empty lines do not separate 232paragraphs (contrary to {\LaTeX}). 233 234 The other construct we see here is \texttt{\©right;}. This is an example of an ``entity'' in XML and is a macro for some substitution text. Here we use an entity as a 235shortcut for a complicated expression which makes it possible that the term \emph{copyright} is printed as some text like \texttt{(C)} in text terminal output and as a copyright character in other output formats. 236In \textsf{GAPDoc} we predefine some entities. Certain ``special characters'' must be typed via entities, for example ``{\textless}'', ``{\textgreater}'' and ``\&'' to avoid a misinterpretation as XML markup. It is possible to define 237additional entities for your document inside the \texttt{{\textless}!DOCTYPE ...{\textgreater}} declaration, see{\nobreakspace}\ref{GDent}. 238 239 Note that elements in XML must always be properly nested, as in this example. 240A construct like \texttt{{\textless}a{\textgreater}{\textless}b{\textgreater}...{\textless}/a{\textgreater}{\textless}/b{\textgreater}} is \emph{not} allowed. 241\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 242 <TableOfContents/> 243\end{Verbatim} 244 This is another example of an ``empty element''. It just means that a table of contents for the whole document should be 245included into any output version of the document. 246 247 After this the main text of the document follows inside certain sectioning 248elements: 249\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 250 <Body> 251 <Chapter> <Heading>The <M>3k+1</M> Problem</Heading> 252 <Section Label="sec:theory"> <Heading>Theory</Heading> 253 [...] (content omitted) 254 </Section> 255 <Section> <Heading>Program</Heading> 256 [...] (content omitted) 257 </Section> 258 </Chapter> 259 </Body> 260\end{Verbatim} 261 These elements are used similarly to ``\texttt{\symbol{92}}chapter'' and ``\texttt{\symbol{92}}section'' in {\LaTeX}. But note that the explicit end tags are necessary here. 262 263 The sectioning commands allow to assign an optional attribute ``Label''. This can be used for referring to a section inside the document. 264 265 The text of the first section starts as follows. The whitespace in the text is 266unimportant and the indenting is not necessary. 267\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 268 269 Let <M>k \in &NN;</M> be a natural number. We consider the 270 sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and 271 else 272\end{Verbatim} 273 Here we come to the interesting question how to type mathematical formulae in 274a \textsf{GAPDoc} document. We did not find any alternative for writing formulae in {\TeX} syntax. (There is MATHML, but even simple formulae contain a lot of markup, 275become quite unreadable and they are cumbersome to type. Furthermore there 276seem to be no tools available which translate such formulae in a nice way into {\TeX} and text.) So, formulae are essentially typed as in {\LaTeX}. (Actually, it is also possible to type unicode characters of some 277mathematical symbols directly, or via an entity like the \texttt{\&NN;} above.) There are three types of elements containing formulae: ``M'', ``Math'' and ``Display''. The first two are for in-text formulae and the third is for displayed 278formulae. Here ``M'' and ``Math'' are equivalent, when translating a \textsf{GAPDoc} document into {\LaTeX}. But they are handled differently for terminal text (and HTML) output. For 279the content of an ``M''-element there are defined rules for a translation into well readable terminal 280text. More complicated formulae are in ``Math'' or ``Display'' elements and they are just printed as they are typed in text output. So, to 281make a section well readable inside a terminal window you should try to put as 282many formulae as possible into ``M''-elements. In our example text we used the notation \texttt{n(i, k)} instead of \texttt{n{\textunderscore}i(k)} because it is easier to read in text mode. See Sections{\nobreakspace}\ref{GDformulae} and{\nobreakspace}\ref{sec:misc} for more details. 283 284 A few lines further on we find two non-internal references. 285\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 286 problem, see <Cite Key="Wi98"/> or 287 <URL>http://mathsrv.ku-eichstaett.de/MGF/homes/wirsching/</URL> 288\end{Verbatim} 289 The first within the ``Cite''-element is the citation of a book. In \textsf{GAPDoc} we use the widely used Bib{\TeX} database format for reference lists. This does not use XML but has a well 290documented structure which is easy to parse. And many people have collections 291of references readily available in this format. The reference list in an 292output version of the document is produced with the empty element 293\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 294 <Bibliography Databases="3k+1" /> 295\end{Verbatim} 296 close to the end of our example file. The attribute ``Databases'' give the name(s) of the database (\texttt{.bib}) files which contain the references. 297 298 Putting a Web-address into an ``URL''-element allows one to create a hyperlink in output formats which allow this. 299 300 The second section of our example contains a special kind of subsection 301defined in \textsf{GAPDoc}. 302\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 303 <ManSection> 304 <Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/> 305 <Description> 306 This function computes for a natural number <A>k</A> the 307 beginning of the sequence <M>n(i, k)</M> defined in section 308 <Ref Sect="sec:theory"/>. The sequence stops at the first 309 <M>1</M> or at <M>n(<A>max</A>, k)</M>, if <A>max</A> is 310 given. 311 <Example> 312 gap> ThreeKPlusOneSequence(101); 313 "Sorry, not yet implemented. Wait for Version 84 of the package" 314 </Example> 315 </Description> 316 </ManSection> 317\end{Verbatim} 318 A ``ManSection'' contains the description of some function, operation, method, filter and so 319on. The ``Func''-element describes the name of a \emph{function} (there are also similar elements ``Oper'', ``Meth'', ``Filt'' and so on) and names for its arguments, optional arguments enclosed in square 320brackets. See Section{\nobreakspace}\ref{sec:mansect} for more details. 321 322 In the ``Description'' we write the argument names as ``A''-elements. A good description of a function should usually contain an example 323of its use. For this there are some verbatim-like elements in \textsf{GAPDoc}, like ``Example'' above (here, clearly, whitespace matters which causes a slightly strange 324indenting). 325 326 The text contains an internal reference to the first section via the 327explicitly defined label \texttt{sec:theory}. 328 329 The first section also contains a ``Ref''-element which refers to the function described here. Note that there is no 330explicit label for such a reference. The pair \texttt{{\textless}Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/{\textgreater}} and \texttt{{\textless}Ref Func="ThreeKPlusOneSequence"/{\textgreater}} does the cross referencing (and hyperlinking if possible) implicitly via the 331name of the function. 332 333 Here is one further element from our example document which we want to 334explain. 335\begin{Verbatim}[fontsize=\small,frame=single,label=from 3k+1.xml] 336 <TheIndex/> 337\end{Verbatim} 338 This is again an empty element which just says that an output version of the 339document should contain an index. Many entries for the index are generated 340automatically because the ``Func'' and similar elements implicitly produce such entries. It is also possible to 341include explicit additional entries in the index. } 342 343 344\section{\textcolor{Chapter }{Some questions}}\label{sec:faq} 345\logpage{[ 1, 3, 0 ]} 346\hyperdef{L}{X79A97B867F45E5C7}{} 347{ 348 349\begin{description} 350\item[{Are those XML files too ugly to read and edit?}] Just have a look and decide yourself. The markup needs more characters than 351most {\TeX} or {\LaTeX} markup. But the structure of the document is easier to see. If you configure 352your favorite editor well, you do not need more key strokes for typing the 353markup than in {\LaTeX}. 354\item[{Why do we not use {\LaTeX} alone?}] {\LaTeX} is good for writing books. But {\LaTeX} files are generally difficult to parse and to process to other output formats 355like text for browsing in a terminal window or HTML (or new formats which may 356become popular in the future). \textsf{GAPDoc} markup is one step more abstract than {\LaTeX} insofar as it describes meaning instead of appearance of text. The inner 357workings of {\LaTeX} are too complicated to learn without pain, which makes it difficult to 358overcome problems that occur occasionally. 359\item[{Why XML and not a newly defined markup language?}] XML is a well defined standard that is more and more widely used. Lots of 360people have thought about it. Years of experience with SGML went into the 361design. It is easy to explain, easy to parse and lots of tools are available, 362there will be more in the future. 363\end{description} 364 } 365 366 } 367 368 369\chapter{\textcolor{Chapter }{How To Type a \textsf{GAPDoc} Document}}\label{HowEnter} 370\logpage{[ 2, 0, 0 ]} 371\hyperdef{L}{X7890CF967F3E2FED}{} 372{ 373 In this chapter we give a more formal description of what you need to start to 374type documentation in \textsf{GAPDoc} XML format. Many details were already explained by example in 375Section{\nobreakspace}\ref{sec:3k+1expl} of the introduction. 376 377 We do \emph{not} answer the question ``How to \emph{write} a \textsf{GAPDoc} document?'' in this chapter. You can (hopefully) find an answer to this question by 378studying the example in the introduction, see{\nobreakspace}\ref{sec:3k+1expl}, and learning about more details in the reference Chapter{\nobreakspace}\ref{DTD}. 379 380 The definite source for all details of the official XML standard with useful 381annotations is: 382 383 \href{http://www.xml.com/axml/axml.html} {\texttt{http://www.xml.com/axml/axml.html}} 384 385 Although this document must be quite technical, it is surprisingly well 386readable. 387 388 389\section{\textcolor{Chapter }{General XML Syntax}}\label{EnterXML} 390\logpage{[ 2, 1, 0 ]} 391\hyperdef{L}{X7B3A544986A1A9EA}{} 392{ 393 We will now discuss the pieces of text which can occur in a general XML 394document. We start with those pieces which do not contribute to the actual 395content of the document. 396\subsection{\textcolor{Chapter }{Head of XML Document}}\label{XMLhead} 397\logpage{[ 2, 1, 1 ]} 398\hyperdef{L}{X84E8D39687638CF0}{} 399{ 400 Each XML document should have a head which states that it is an XML document 401in some encoding and which XML-defined language is used. In case of a \textsf{GAPDoc} document this should always look as in the following example. 402\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example] 403 <?xml version="1.0" encoding="UTF-8"?> 404 <!DOCTYPE Book SYSTEM "gapdoc.dtd"> 405\end{Verbatim} 406 See{\nobreakspace}\ref{XMLenc} for a remark on the ``encoding'' statement. 407 408 (There may be local entity definitions inside the \texttt{DOCTYPE} statement, see Subsection{\nobreakspace}\ref{GDent} below.) } 409 410 411\subsection{\textcolor{Chapter }{Comments}}\label{XMLcomment} 412\logpage{[ 2, 1, 2 ]} 413\hyperdef{L}{X780C79EB85C32138}{} 414{ 415 A ``comment'' in XML starts with the character sequence ``\texttt{{\textless}!--}'' and ends with the sequence ``\texttt{--{\textgreater}}''. Between these sequences there must not be two adjacent dashes ``\texttt{--}''. } 416 417 418\subsection{\textcolor{Chapter }{Processing Instructions}}\label{XMLprocinstr} 419\logpage{[ 2, 1, 3 ]} 420\hyperdef{L}{X82DBCCAD8358BB63}{} 421{ 422 A ``processing instruction'' in XML starts with the character sequence ``\texttt{{\textless}?}'' followed by a name (``\texttt{xml}'' is only allowed at the very beginning of the document to declare it being an 423XML document, see \ref{XMLhead}). After that any characters may follow, except that the ending sequence ``\texttt{?{\textgreater}}'' must not occur within the processing instruction. } 424 425 {\nobreakspace} 426 427 And now we turn to those parts of the document which contribute to its actual 428content. 429\subsection{\textcolor{Chapter }{Names in XML and Whitespace}}\label{XMLnames} 430\logpage{[ 2, 1, 4 ]} 431\hyperdef{L}{X7A0FB16C7FEC0B53}{} 432{ 433 A ``name'' in XML (used for element and attribute identifiers, see below) must start with 434a letter (in the encoding of the document) or with a colon ``\texttt{:}'' or underscore ``\texttt{{\textunderscore}}'' character. The following characters may also be digits, dots ``\texttt{.}'' or dashes ``\texttt{-}''. 435 436 This is a simplified description of the rules in the standard, which are 437concerned with lots of unicode ranges to specify what a ``letter'' is. 438 439 Sequences only consisting of the following characters are considered as \emph{whitespace}: blanks, tabs, carriage return characters and new line characters. } 440 441 442\subsection{\textcolor{Chapter }{Elements}}\label{XMLel} 443\logpage{[ 2, 1, 5 ]} 444\hyperdef{L}{X79B130FC7906FB4C}{} 445{ 446 The actual content of an XML document consists of ``elements''. An element has some ``content'' with a leading ``start tag'' (\ref{XMLstarttag}) and a trailing ``end tag'' (\ref{XMLendtag}). The content can contain further elements but they must be properly nested. 447One can define elements whose content is always empty, those elements can also 448be entered with a single combined tag (\ref{XMLcombtag}). } 449 450 451\subsection{\textcolor{Chapter }{Start Tags}}\label{XMLstarttag} 452\logpage{[ 2, 1, 6 ]} 453\hyperdef{L}{X7DD1DCB783588BD5}{} 454{ 455 A ``start-tag'' consists of a less-than-character ``\texttt{{\textless}}'' directly followed (without whitespace) by an element name (see{\nobreakspace}\ref{XMLnames}), optional attributes, optional whitespace, and a greater-than-character ``\texttt{{\textgreater}}''. 456 457 An ``attribute'' consists of some whitespace and then its name followed by an equal sign ``\texttt{=}'' which is optionally enclosed by whitespace, and the attribute value, which is 458enclosed either in single or double quotes. The attribute value may not 459contain the type of quote used as a delimiter or the character ``\texttt{{\textless}}'', the character ``\texttt{\&}'' may only appear to start an entity, see{\nobreakspace}\ref{XMLent}. We describe in{\nobreakspace}\ref{AttrValRules} how to enter special characters in attribute values. 460 461 Note especially that no whitespace is allowed between the starting ``\texttt{{\textless}}'' character and the element name. The quotes around an attribute value cannot be 462omitted. The names of elements and attributes are \emph{case sensitive}. } 463 464 465\subsection{\textcolor{Chapter }{End Tags}}\label{XMLendtag} 466\logpage{[ 2, 1, 7 ]} 467\hyperdef{L}{X7E5A567E83005B62}{} 468{ 469 An ``end tag'' consists of the two characters ``\texttt{{\textless}/}'' directly followed by the element name, optional whitespace and a 470greater-than-character ``\texttt{{\textgreater}}''. } 471 472 473\subsection{\textcolor{Chapter }{Combined Tags for Empty Elements}}\label{XMLcombtag} 474\logpage{[ 2, 1, 8 ]} 475\hyperdef{L}{X843A02A88514D919}{} 476{ 477 Elements which always have empty content can be written with a single tag. 478This looks like a start tag (see{\nobreakspace}\ref{XMLstarttag}) \emph{except} that the trailing greater-than-character ``\texttt{{\textgreater}}'' is substituted by the two character sequence ``\texttt{/{\textgreater}}''. } 479 480 481\subsection{\textcolor{Chapter }{Entities}}\label{XMLent} 482\logpage{[ 2, 1, 9 ]} 483\hyperdef{L}{X78FB56C77B1F391A}{} 484{ 485 An ``entity'' in XML is a macro for some substitution text. There are two types of entities. 486 487 A ``character entity'' can be used to specify characters in the encoding of the document (can be 488useful for entering non-ASCII characters which you cannot manage to type in 489directly). They are entered with a sequence ``\texttt{\&\#}'', directly followed by either some decimal digits or an ``\texttt{x}'' and some hexadecimal digits, directly followed by a semicolon ``\texttt{;}''. Using such a character entity is just equivalent to typing the corresponding 490character directly. 491 492 Then there are references to ``named entities''. They are entered with an ampersand character ``\texttt{\&}'' directly followed by a name which is directly followed by a semicolon ``\texttt{;}''. Such entities must be declared somewhere by giving a substitution text. This 493text is included in the document and the document is parsed again afterwards. 494The exact rules are a bit subtle but you probably want to use this only in 495simple cases. Predefined entities for \textsf{GAPDoc} are described in \ref{XMLspchar} and \ref{GDent}. 496 497 } 498 499 500\subsection{\textcolor{Chapter }{Special Characters in XML}}\label{XMLspchar} 501\logpage{[ 2, 1, 10 ]} 502\hyperdef{L}{X84A95A19801EDE76}{} 503{ 504 We have seen that the less-than-character ``\texttt{{\textless}}'' and the ampersand character ``\texttt{\&}'' start a tag or entity reference in XML. To get these characters into the 505document text one has to use entity references, namely ``\texttt{\<}'' to get ``\texttt{{\textless}}'' and ``\texttt{\&}'' to get ``\texttt{\&}''. Furthermore ``\texttt{\>}'' must be used to get ``\texttt{{\textgreater}}'' when the string ``\texttt{]]{\textgreater}}'' appears in element content (and not as delimiter of a \texttt{CDATA} section explained below). 506 507 Another possibility is to use a \texttt{CDATA} statement explained in{\nobreakspace}\ref{XMLcdata}. } 508 509 510\subsection{\textcolor{Chapter }{Rules for Attribute Values}}\label{AttrValRules} 511\logpage{[ 2, 1, 11 ]} 512\hyperdef{L}{X7F49E7AD785AED22}{} 513{ 514 Attribute values can contain entities which are substituted recursively. But 515except for the entities \< or a character entity it is not allowed that a 516{\textless} character is introduced by the substitution (there is no XML 517parsing for evaluating the attribute value, just entity substitutions). } 518 519 520\subsection{\textcolor{Chapter }{\texttt{CDATA}}}\label{XMLcdata} 521\logpage{[ 2, 1, 12 ]} 522\hyperdef{L}{X82E77E707A062908}{} 523{ 524 Pieces of text which contain many characters which can be misinterpreted as 525markup can be enclosed by the character sequences ``\texttt{{\textless}![CDATA[}'' and ``\texttt{]]{\textgreater}}''. Everything between these sequences is considered as content of the document 526and is not further interpreted as XML text. All the rules explained so far in 527this section do \emph{not apply} to such a part of the document. The only document content which cannot be 528entered directly inside a \texttt{CDATA} statement is the sequence ``\texttt{]]{\textgreater}}''. This can be entered as ``\texttt{]]\>}'' outside the \texttt{CDATA} statement. 529\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 530 A nesting of tags like <a> <b> </a> </b> is not allowed. 531\end{Verbatim} 532 } 533 534 535\subsection{\textcolor{Chapter }{Encoding of an XML Document}}\label{XMLenc} 536\logpage{[ 2, 1, 13 ]} 537\hyperdef{L}{X8709BD337DA09ED5}{} 538{ 539 We suggest to use the UTF-8 encoding for writing \textsf{GAPDoc} XML documents. But the tools described in Chapter \ref{ch:conv} also work with ASCII or the various ISO-8859-X encodings (ISO-8859-1 is also 540called latin1 and covers most special characters for western European 541languages). } 542 543 544\subsection{\textcolor{Chapter }{Well Formed and Valid XML Documents}}\label{XMLvalid} 545\logpage{[ 2, 1, 14 ]} 546\hyperdef{L}{X8561F07A81CABDD6}{} 547{ 548 We want to mention two further important words which are often used in the 549context of XML documents. A piece of text becomes a ``well formed'' XML document if all the formal rules described in this section are fulfilled. 550 551 But this says nothing about the content of the document. To give this content 552a meaning one needs a declaration of the element and corresponding attribute 553names as well as of named entities which are allowed. Furthermore there may be 554restrictions how such elements can be nested. This \emph{definition of an XML based markup language} is done in a ``document type definition''. An XML document which contains only elements and entities declared in such a 555document type definition and obeys the rules given there is called ``valid (with respect to this document type definition)''. 556 557 The main file of the \textsf{GAPDoc} package is \texttt{gapdoc.dtd}. This contains such a definition of a markup language. We are not going to 558explain the formal syntax rules for document type definitions in this section. 559But in Chapter{\nobreakspace}\ref{DTD} we will explain enough about it to understand the file \texttt{gapdoc.dtd} and so the markup language defined there. } 560 561 } 562 563 564\section{\textcolor{Chapter }{Entering \textsf{GAPDoc} Documents}}\label{EnterGD} 565\logpage{[ 2, 2, 0 ]} 566\hyperdef{L}{X7BDE59B17CF1D5D2}{} 567{ 568 Here are some additional rules for writing \textsf{GAPDoc} XML documents. 569\subsection{\textcolor{Chapter }{Other special characters}}\label{otherspecchar} 570\logpage{[ 2, 2, 1 ]} 571\hyperdef{L}{X79171E047B069F94}{} 572{ 573 As \textsf{GAPDoc} documents are used to produce {\LaTeX} and HTML documents, the question arises how to deal with characters with a 574special meaning for other applications (for example ``\texttt{\&}'', ``\texttt{\#}'', ``\texttt{\$}'', ``\texttt{\%}'', ``\texttt{\texttt{\symbol{126}}}'', ``\texttt{\texttt{\symbol{92}}}'', ``\texttt{\texttt{\symbol{123}}}'', ``\texttt{\texttt{\symbol{125}}}'', ``\texttt{{\textunderscore}}'', ``\texttt{\texttt{\symbol{94}}}'', ``\texttt{{\nobreakspace}}'' (this is a non-breakable space, ``\texttt{\texttt{\symbol{126}}}'' in {\LaTeX}) have a special meaning for {\LaTeX} and ``\texttt{\&}'', ``\texttt{{\textless}}'', ``\texttt{{\textgreater}}'' have a special meaning for HTML (and XML). In \textsf{GAPDoc} you can usually just type these characters directly, it is the task of the 575converter programs which translate to some output format to take care of such 576special characters. The exceptions to this simple rule are: 577\begin{itemize} 578\item \& and {\textless} must be entered as \texttt{\&} and \texttt{\<} as explained in \ref{XMLspchar}. 579\item The content of the \textsf{GAPDoc} elements \texttt{{\textless}M{\textgreater}}, \texttt{{\textless}Math{\textgreater}} and \texttt{{\textless}Display{\textgreater}} is {\LaTeX} code, see \ref{MathForm}. 580\item The content of an \texttt{{\textless}Alt{\textgreater}} element with \texttt{Only} attribute contains code for the specified output type, see \ref{Alt}. 581\end{itemize} 582 Remark: In former versions of \textsf{GAPDoc} one had to use particular entities for all the special characters mentioned 583above (\texttt{\&tamp;}, \texttt{\&hash;}, \texttt{\$}, \texttt{\&percent;}, \texttt{\˜}, \texttt{\&bslash;}, \texttt{\&obrace;}, \texttt{\&cbrace;}, \texttt{\&uscore;}, \texttt{\&circum;}, \texttt{\&tlt;}, \texttt{\&tgt;}). These are no longer needed, but they are still defined for backwards 584compatibility with older \textsf{GAPDoc} documents. } 585 586 587\subsection{\textcolor{Chapter }{Mathematical Formulae}}\label{GDformulae} 588\logpage{[ 2, 2, 2 ]} 589\hyperdef{L}{X7EAE0C5A835F126F}{} 590{ 591 Mathematical formulae in \textsf{GAPDoc} are typed as in {\LaTeX}. They must be the content of one of three types of \textsf{GAPDoc} elements concerned with mathematical formulae: ``\texttt{Math}'', ``\texttt{Display}'', and ``\texttt{M}'' (see Sections{\nobreakspace}\ref{Math} and{\nobreakspace}\ref{M} for more details). The first two correspond to {\LaTeX}'s math mode and display math mode. The last one is a special form of the ``\texttt{Math}'' element type, that imposes certain restrictions on the content. On the other 592hand the content of an ``\texttt{M}'' element is processed in a well defined way for text terminal or HTML output. 593The ``\texttt{Display}'' element also has an attribute such that its content is processed as in ``\texttt{M}'' elements. 594 595 Note that the content of these element is {\LaTeX} code, but the special characters ``\texttt{{\textless}}'' and ``\texttt{\&}'' for XML must be entered via the entities described in{\nobreakspace}\ref{XMLspchar} or by using a \texttt{CDATA} statement, see{\nobreakspace}\ref{XMLcdata}. 596 597 } 598 599 600\subsection{\textcolor{Chapter }{More Entities}}\label{GDent} 601\logpage{[ 2, 2, 3 ]} 602\hyperdef{L}{X7BDFF6D37FBED400}{} 603{ 604 In \textsf{GAPDoc} there are some more predefined entities: \begin{center} 605\begin{tabular}{|l|l|}\hline 606\texttt{\&GAP;}& 607\textsf{GAP}\\ 608\hline 609\texttt{\&GAPDoc;}& 610\textsf{GAPDoc}\\ 611\hline 612\texttt{\&TeX;}& 613{\TeX}\\ 614\hline 615\texttt{\&LaTeX;}& 616{\LaTeX}\\ 617\hline 618\texttt{\&BibTeX;}& 619Bib{\TeX}\\ 620\hline 621\texttt{\&MeatAxe;}& 622\textsf{MeatAxe}\\ 623\hline 624\texttt{\&XGAP;}& 625\textsf{XGAP}\\ 626\hline 627\texttt{\©right;}& 628{\copyright}\\ 629\hline 630\texttt{\ }& 631``{\nobreakspace}''\\ 632\hline 633\texttt{\–}& 634{\textendash}\\ 635\hline 636\end{tabular}\\[2mm] 637\textbf{Table: }Predefined Entities in the \textsf{GAPDoc} system\end{center} 638 639 Here \texttt{\ } is a non-breakable space character. 640 641 Additional entities are defined for some mathematical symbols, see \ref{MathForm} for more details. 642 643 One can define further local entities right inside the head 644(see{\nobreakspace}\ref{XMLhead}) of a \textsf{GAPDoc} XML document as in the following example. 645\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 646 <?xml version="1.0" encoding="UTF-8"?> 647 648 <!DOCTYPE Book SYSTEM "gapdoc.dtd" 649 [ <!ENTITY MyEntity "some longish <E>text</E> possibly with markup"> 650 ]> 651\end{Verbatim} 652 These additional definitions go into the \texttt{{\textless}!DOCTYPE} tag in square brackets. Such new entities are used like this: \texttt{\&MyEntity;} 653 654 } 655 656 } 657 658 } 659 660 661\chapter{\textcolor{Chapter }{The Document Type Definition}}\label{DTD} 662\logpage{[ 3, 0, 0 ]} 663\hyperdef{L}{X7859CFF180D52D49}{} 664{ 665 In this chapter we first explain what a ``document type definition'' is and then describe \texttt{gapdoc.dtd} in detail. That file together with the current chapter define how a \textsf{GAPDoc} document has to look like. It can be found in the main directory of the \textsf{GAPDoc} package and it is reproduced in Appendix{\nobreakspace}\ref{GAPDocdtd}. 666 667 We do not give many examples in this chapter which is more intended as a 668formal reference for all \textsf{GAPDoc} elements. Instead, we provide a separate help book, see{\nobreakspace} ??? . This uses all the constructs introduced in this chapter and you can easily 669compare the source code and how it looks like in the different output formats. 670Furthermore recall that many basic things about XML markup were already 671explained by example in the introductory chapter{\nobreakspace}\ref{ch:intro}. 672\section{\textcolor{Chapter }{What is a DTD?}}\logpage{[ 3, 1, 0 ]} 673\hyperdef{L}{X7B76F6F786521F6B}{} 674{ 675 A document type definition (DTD) is a formal declaration of how an XML 676document has to be structured. It is itself structured such that programs that 677handle documents can read it and treat the documents accordingly. There are 678for example parsers and validity checkers that use the DTD to validate an XML 679document, see{\nobreakspace}\ref{XMLvalid}. 680 681 The main thing a DTD does is to specify which elements may occur in documents 682of a certain document type, how they can be nested, and what attributes they 683can or must have. So, for each element there is a rule. 684 685 Note that a DTD can \emph{not} ensure that a document which is ``valid'' also makes sense to the converters! It only says something about the formal 686structure of the document. 687 688 For the remaining part of this chapter we have divided the elements of \textsf{GAPDoc} documents into several subsets, each of which will be discussed in one of the 689next sections. 690 691 See the following three subsections to learn by example, how a DTD works. We 692do not want to be too formal here, but just enable the reader to understand 693the declarations in \texttt{gapdoc.dtd}. For precise descriptions of the syntax of DTD's see again the official 694standard in: 695 696 {\nobreakspace}{\nobreakspace}\href{http://www.xml.com/axml/axml.html} {\texttt{http://www.xml.com/axml/axml.html}} 697 698 } 699 700 701\section{\textcolor{Chapter }{Overall Document Structure}}\logpage{[ 3, 2, 0 ]} 702\hyperdef{L}{X7DB0F9E57879CC76}{} 703{ 704 A \textsf{GAPDoc} document contains on its top level exactly one element with name \texttt{Book}. This element is declared in the DTD as follows: 705\subsection{\textcolor{Chapter }{\texttt{{\textless}Book{\textgreater}}}}\logpage{[ 3, 2, 1 ]} 706\hyperdef{L}{X7C7258A57B831934}{} 707{ 708 \index{Book@\texttt{Book}} 709\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 710 <!ELEMENT Book (TitlePage, 711 TableOfContents?, 712 Body, 713 Appendix*, 714 Bibliography?, 715 TheIndex?)> 716 <!ATTLIST Book Name CDATA #REQUIRED> 717\end{Verbatim} 718 After the keyword \texttt{ELEMENT} and the name \texttt{Book} there is a list in parentheses. This is a comma separated list of names of 719elements which can occur (in the given order) in the content of a \texttt{Book} element. Each name in such a list can be followed by one of the characters ``\texttt{?}'', ``\texttt{*}'' or ``\texttt{+}'', meaning that the corresponding element can occur zero or one time, an 720arbitrary number of times, or at least once, respectively. Without such an 721extra character the corresponding element must occur exactly once. Instead of 722one name in this list there can also be a list of elements names separated by ``\texttt{|}'' characters, this denotes any element with one of the names (i.e., ``\texttt{|}'' means ``or''). 723 724 So, the \texttt{Book} element must contain first a \texttt{TitlePage} element, then an optional \texttt{TableOfContents} element, then a \texttt{Body} element, then zero or more elements of type \texttt{Appendix}, then an optional \texttt{Bibliography} element, and finally an optional element of type \texttt{TheIndex}. 725 726 Note that \emph{only} these elements are allowed in the content of the \texttt{Book} element. No other elements or text is allowed in between. An exception of this 727is that there may be whitespace between the end tag of one and the start tag 728of the next element - this should be ignored when the document is processed to 729some output format. An element like this is called an element with ``element content''. 730 731 The second declaration starts with the keyword \texttt{ATTLIST} and the element name \texttt{Book}. After that there is a triple of whitespace separated parameters (in general 732an arbitrary number of such triples, one for each allowed attribute name). The 733first (\texttt{Name}) is the name of an attribute for a \texttt{Book} element. The second (\texttt{CDATA}) is always the same for all of our declarations, it means that the value of 734the attribute consists of ``character data''. The third parameter \texttt{\#REQUIRED} means that this attribute must be specified with any \texttt{Book} element. Later we will also see optional attributes which are declared as \texttt{\#IMPLIED}. } 735 736 737\subsection{\textcolor{Chapter }{\texttt{{\textless}TitlePage{\textgreater}}}}\logpage{[ 3, 2, 2 ]} 738\hyperdef{L}{X842B421A7FBCDD2C}{} 739{ 740 \index{TitlePage@\texttt{TitlePage}} 741\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 742 <!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?, 743 Author+, Date?, Address?, Abstract?, Copyright?, 744 Acknowledgements? , Colophon? )> 745\end{Verbatim} 746 Within this element information for the title page is collected. Note that 747more than one author can be specified. The elements must appear in this order 748because there is no sensible way to specify in a DTD something like ``the following elements may occur in any order but each exactly once''. 749 750 Before going on with the other elements inside the \texttt{Book} element we explain the elements for the title page. } 751 752 753\subsection{\textcolor{Chapter }{\texttt{{\textless}Title{\textgreater}}}}\label{Title} 754\logpage{[ 3, 2, 3 ]} 755\hyperdef{L}{X7BCC8E6F79021294}{} 756{ 757 \index{Title@\texttt{Title}} \label{Text} 758\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 759 <!ELEMENT Title (%Text;)*> 760\end{Verbatim} 761 Here is the last construct you need to understand for reading \texttt{gapdoc.dtd}. The expression ``\texttt{\%Text;}'' is a so-called ``parameter entity''. It is something like a macro within the DTD. It is defined as follows: \label{InnerText} 762\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 763 <!ENTITY % Text "%InnerText; | List | Enum | Table"> 764\end{Verbatim} 765 This means, that every occurrence of ``\texttt{\%Text;}'' in the DTD is replaced by the expression \label{Innertext} 766\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 767 %InnerText; | List | Enum | Table 768\end{Verbatim} 769 which is then expanded further because of the following definition: 770\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 771 <!ENTITY % InnerText "#PCDATA | 772 Alt | 773 Emph | E | 774 Par | P | Br | 775 Keyword | K | Arg | A | Quoted | Q | Code | C | 776 File | F | Button | B | Package | 777 M | Math | Display | 778 Example | Listing | Log | Verb | 779 URL | Email | Homepage | Address | Cite | Label | 780 Ref | Index" > 781\end{Verbatim} 782 These are the only two parameter entities we are using. They expand to lists 783of element names which are explained in the sequel \emph{and} the keyword \texttt{\#PCDATA} (concatenated with the ``or'' character ``\texttt{|}''). 784 785 So, the element (\texttt{Title}) is of so-called ``mixed content'': It can contain \emph{parsed character data} which does not contain further markup (\texttt{\#PCDATA}) or any of the other above mentioned elements. Mixed content must always have 786the asterisk qualifier (like in \texttt{Title}) such that any sequence of elements (of the above list) and character data 787can be contained in a \texttt{Title} element. 788 789 The \texttt{\%Text;} parameter entity is used in all places in the DTD, where ``normal text'' should be allowed, including lists, enumerations, and tables, but \emph{no} sectioning elements. 790 791 The \texttt{\%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, 792and tables are allowed. This is used for example in headings. 793 794 } 795 796 797\subsection{\textcolor{Chapter }{\texttt{{\textless}Subtitle{\textgreater}}}}\logpage{[ 3, 2, 4 ]} 798\hyperdef{L}{X82E82AF48217CC14}{} 799{ 800 \index{Subtitle@\texttt{Subtitle}} 801\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 802 <!ELEMENT Subtitle (%Text;)*> 803\end{Verbatim} 804 Contains the subtitle of the document. } 805 806 807\subsection{\textcolor{Chapter }{\texttt{{\textless}Version{\textgreater}}}}\label{Version} 808\logpage{[ 3, 2, 5 ]} 809\hyperdef{L}{X876962807DCC52B3}{} 810{ 811 \index{Version@\texttt{Version}} 812\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 813 <!ELEMENT Version (#PCDATA|Alt)*> 814\end{Verbatim} 815 Note that the version can only contain character data and no further markup 816elements (except for \texttt{Alt}, which is necessary to resolve the entities described in \ref{GDent}). The converters will \emph{not} put the word ``Version'' in front of the text in this element. } 817 818 819\subsection{\textcolor{Chapter }{\texttt{{\textless}TitleComment{\textgreater}}}}\logpage{[ 3, 2, 6 ]} 820\hyperdef{L}{X87E7CD5B79230B90}{} 821{ 822 \index{TitleComment@\texttt{TitleComment}} 823\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 824 <!ELEMENT TitleComment (%Text;)*> 825\end{Verbatim} 826 Sometimes a title and subtitle are not sufficient to give a rough idea about 827the content of a package. In this case use this optional element to specify an 828additional text for the front page of the book. This text should be short, use 829the \texttt{Abstract} element (see{\nobreakspace}\ref{elAbstract}) for longer explanations. } 830 831 832\subsection{\textcolor{Chapter }{\texttt{{\textless}Author{\textgreater}}}}\logpage{[ 3, 2, 7 ]} 833\hyperdef{L}{X8731459C7E4C56DA}{} 834{ 835 \index{Author@\texttt{Author}} 836\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 837 <!ELEMENT Author (%Text;)*> <!-- There may be more than one Author! --> 838\end{Verbatim} 839 As noted in the comment there may be more than one element of this type. This 840element should contain the name of an author and probably an \texttt{Email}-address and/or WWW-\texttt{Homepage} element for this author, see{\nobreakspace}\ref{elEmail} and{\nobreakspace}\ref{elHomepage}. You can also specify an individual postal address here, instead of using the \texttt{Address} element described below, see{\nobreakspace}\ref{elAddress}. } 841 842 843\subsection{\textcolor{Chapter }{\texttt{{\textless}Date{\textgreater}}}}\logpage{[ 3, 2, 8 ]} 844\hyperdef{L}{X8264A69D7DCDD773}{} 845{ 846 \index{Date@\texttt{Date}} 847\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 848 <!ELEMENT Date (#PCDATA)> 849\end{Verbatim} 850 Only character data is allowed in this element which gives a date for the 851document. No automatic formatting is done. } 852 853 854\subsection{\textcolor{Chapter }{\texttt{{\textless}Address{\textgreater}}}}\label{elAddress} 855\logpage{[ 3, 2, 9 ]} 856\hyperdef{L}{X7EEF65A07A094F65}{} 857{ 858 \index{Date@\texttt{Address}} 859\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 860 <!ELEMENT Address (#PCDATA|Alt|Br)*> 861\end{Verbatim} 862 This optional element can be used to specify a postal address of the author or 863the authors. If there are several authors with different addresses then put 864the \texttt{Address} elements inside the \texttt{Author} elements. 865 866 Use the \texttt{Br} element (see{\nobreakspace}\ref{Br}) to mark the line breaks in the usual formatting of the address on a letter. 867 868 Note that often it is not necessary to use this element because a postal 869address is easy to find via a link to a personal web page. } 870 871 872\subsection{\textcolor{Chapter }{\texttt{{\textless}Abstract{\textgreater}}}}\label{elAbstract} 873\logpage{[ 3, 2, 10 ]} 874\hyperdef{L}{X833110FE79628313}{} 875{ 876 \index{Abstract@\texttt{Abstract}} 877\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 878 <!ELEMENT Abstract (%Text;)*> 879\end{Verbatim} 880 This element contains an abstract of the whole book. } 881 882 883\subsection{\textcolor{Chapter }{\texttt{{\textless}Copyright{\textgreater}}}}\logpage{[ 3, 2, 11 ]} 884\hyperdef{L}{X84BBD8307E08E62F}{} 885{ 886 \index{Copyright@\texttt{Copyright}} 887\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 888 <!ELEMENT Copyright (%Text;)*> 889\end{Verbatim} 890 This element is used for the copyright notice. Note the \texttt{\©right;} entity as described in section \ref{GDent}. } 891 892 893\subsection{\textcolor{Chapter }{\texttt{{\textless}Acknowledgements{\textgreater}}}}\logpage{[ 3, 2, 12 ]} 894\hyperdef{L}{X8143972D7C17838E}{} 895{ 896 \index{Acknowledgements@\texttt{Acknowledgements}} 897\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 898 <!ELEMENT Acknowledgements (%Text;)*> 899\end{Verbatim} 900 This element contains the acknowledgements. } 901 902 903\subsection{\textcolor{Chapter }{\texttt{{\textless}Colophon{\textgreater}}}}\logpage{[ 3, 2, 13 ]} 904\hyperdef{L}{X7C09A3398059D18C}{} 905{ 906 \index{Colophon@\texttt{Colophon}} 907\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 908 <!ELEMENT Colophon (%Text;)*> 909\end{Verbatim} 910 The ``colophon'' page is used to say something about the history of a document. } 911 912 913\subsection{\textcolor{Chapter }{\texttt{{\textless}TableOfContents{\textgreater}}}}\logpage{[ 3, 2, 14 ]} 914\hyperdef{L}{X7E97263A83DC26E9}{} 915{ 916 \index{TableOfContents@\texttt{TableOfContents}} 917\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 918 <!ELEMENT TableOfContents EMPTY> 919\end{Verbatim} 920 This element may occur in the \texttt{Book} element after the \texttt{TitlePage} element. If it is present, a table of contents is generated and inserted into 921the document. Note that because this element is declared to be \texttt{EMPTY} one can use the abbreviation 922\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 923 <TableOfContents/> 924\end{Verbatim} 925 to denote this empty element. } 926 927 928\subsection{\textcolor{Chapter }{\texttt{{\textless}Bibliography{\textgreater}} }}\label{Bibliography} 929\logpage{[ 3, 2, 15 ]} 930\hyperdef{L}{X84F3DF21786A8751}{} 931{ 932 \index{Bibliography@\texttt{Bibliography}} 933\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 934 <!ELEMENT Bibliography EMPTY> 935 <!ATTLIST Bibliography Databases CDATA #REQUIRED 936 Style CDATA #IMPLIED> 937\end{Verbatim} 938 This element may occur in the \texttt{Book} element after the last \texttt{Appendix} element. If it is present, a bibliography section is generated and inserted 939into the document. The attribute \texttt{Databases} must be specified, the names of several data files can be specified, separated 940by commas. 941 942 Two kinds of files can be specified in \texttt{Databases}: The first are Bib{\TeX} files as defined in{\nobreakspace}\cite[Appendix B]{La85}. Such files must have a name with extension \texttt{.bib}, and in \texttt{Databases} the name must be given \emph{without} this extension. Note that such \texttt{.bib}-files should be in latin1-encoding (or ASCII-encoding). The second are files 943in BibXMLext format as defined in Section{\nobreakspace}\ref{BibXMLformat}. These files must have an extension \texttt{.xml} and in \texttt{Databases} the \emph{full} name must be specified. 944 945 We suggest to use the BibXMLext format because it allows to produce 946potentially nicer bibliography entries in text and HTML documents. 947 948 A bibliography style may be specified with the \texttt{Style} attribute. The optional \texttt{Style} attribute (for {\LaTeX} output of the document) must also be specified without the \texttt{.bst} extension (the default is \texttt{alpha}). See also section \ref{Cite} for a description of the \texttt{Cite} element which is used to include bibliography references into the text. 949 950 } 951 952 953\subsection{\textcolor{Chapter }{\texttt{{\textless}TheIndex{\textgreater}}}}\label{TheIndex} 954\logpage{[ 3, 2, 16 ]} 955\hyperdef{L}{X7C53615A8477F1E5}{} 956{ 957 \index{TheIndex@\texttt{TheIndex}} 958\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 959 <!ELEMENT TheIndex EMPTY> 960\end{Verbatim} 961 This element may occur in the \texttt{Book} element after the \texttt{Bibliography} element. If it is present, an index is generated and inserted into the 962document. There are elements in \textsf{GAPDoc} which implicitly generate index entries (e.g., \texttt{Func} (\ref{Func})) and there is an element \texttt{Index} (\ref{Index}) for explicitly adding index entries. } 963 964 } 965 966 967\section{\textcolor{Chapter }{Sectioning Elements}}\logpage{[ 3, 3, 0 ]} 968\hyperdef{L}{X80E2AD7481DD69D9}{} 969{ 970 A \textsf{GAPDoc} book is divided into \emph{chapters}, \emph{sections}, and \emph{subsections}. The idea is of course, that a chapter consists of sections, which in turn 971consist of subsections. However for the sake of flexibility, the rules are not 972too restrictive. Firstly, text is allowed everywhere in the body of the 973document (and not only within sections). Secondly, the chapter level may be 974omitted. The exact rules are described below. 975 976 \emph{Appendices} are a flavor of chapters, occurring after all regular chapters. There is a 977special type of subsection called ``\texttt{ManSection}''. This is a subsection devoted to the description of a function, operation or 978variable. It is analogous to a manpage in the UNIX environment. Usually each 979function, operation, method, and so on should have its own \texttt{ManSection}. 980 981 Cross referencing is done on the level of \texttt{Subsection}s, respectively \texttt{ManSection}s. The topics in \textsf{GAP}'s online help are also pointing to subsections. So, they should not be too 982long. 983 984 We start our description of the sectioning elements ``top-down'': 985\subsection{\textcolor{Chapter }{\texttt{{\textless}Body{\textgreater}}}}\logpage{[ 3, 3, 1 ]} 986\hyperdef{L}{X7B38415687510D0A}{} 987{ 988 \index{Body@\texttt{Body}} The \texttt{Body} element marks the main part of the document. It must occur after the \texttt{TableOfContents} element. There is a big difference between \emph{inside} and \emph{outside} of this element: Whereas regular text is allowed nearly everywhere in the \texttt{Body} element and its subelements, this is not true for the \emph{outside}. This has also implications on the handling of whitespace. \emph{Outside} superfluous whitespace is usually ignored when it occurs between elements. \emph{Inside} of the \texttt{Body} element whitespace matters because character data is allowed nearly 989everywhere. Here is the definition in the DTD: 990\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 991 <!ELEMENT Body ( %Text;| Chapter | Section )*> 992\end{Verbatim} 993 The fact that \texttt{Chapter} and \texttt{Section} elements are allowed here leads to the possibility to omit the chapter level 994entirely in the document. For a description of \texttt{\%Text;} see \ref{Text}. 995 996 (Remark: The purpose of this element is to make sure that a \emph{valid} \textsf{GAPDoc} document has a correct overall structure, which is only possible when the top 997element \texttt{Book} has element content.) } 998 999 1000\subsection{\textcolor{Chapter }{\texttt{{\textless}Chapter{\textgreater}}}}\label{Chapter} 1001\logpage{[ 3, 3, 2 ]} 1002\hyperdef{L}{X7A86B2BA7D688B6B}{} 1003{ 1004 \index{Chapter@\texttt{Chapter}} 1005\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1006 <!ELEMENT Chapter (%Text;| Heading | Section)*> 1007 <!ATTLIST Chapter Label CDATA #IMPLIED> <!-- For reference purposes --> 1008\end{Verbatim} 1009 A \texttt{Chapter} element can have a \texttt{Label} attribute, such that this chapter can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the chapter as there is 1010no automatic labelling! 1011 1012 \texttt{Chapter} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), \texttt{Section} elements, and \texttt{Heading} elements. 1013 1014 The following \emph{additional} rule cannot be stated in the DTD because we want a \texttt{Chapter} element to have mixed content. There must be \emph{exactly one} \texttt{Heading} element in the \texttt{Chapter} element, containing the heading of the chapter. Here is its definition: } 1015 1016 1017\subsection{\textcolor{Chapter }{\texttt{{\textless}Heading{\textgreater}}}}\label{Heading} 1018\logpage{[ 3, 3, 3 ]} 1019\hyperdef{L}{X79825E1C821D0B79}{} 1020{ 1021 \index{Heading@\texttt{Heading}} 1022\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1023 <!ELEMENT Heading (%InnerText;)*> 1024\end{Verbatim} 1025 This element is used for headings in \texttt{Chapter}, \texttt{Section}, \texttt{Subsection}, and \texttt{Appendix} elements. It may only contain \texttt{\%InnerText;} (for a description see \ref{InnerText}). 1026 1027 Each of the mentioned sectioning elements must contain exactly one direct \texttt{Heading} element (i.e., one which is not contained in another sectioning element). } 1028 1029 1030\subsection{\textcolor{Chapter }{\texttt{{\textless}Appendix{\textgreater}}}}\logpage{[ 3, 3, 4 ]} 1031\hyperdef{L}{X7C701B2779767556}{} 1032{ 1033 \index{Appendix@\texttt{Appendix}} 1034\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1035 <!ELEMENT Appendix (%Text;| Heading | Section)*> 1036 <!ATTLIST Appendix Label CDATA #IMPLIED> <!-- For reference purposes --> 1037\end{Verbatim} 1038 The \texttt{Appendix} element behaves exactly like a \texttt{Chapter} element (see \ref{Chapter}) except for the position within the document and the numbering. While 1039chapters are counted with numbers (1., 2., 3., ...) the appendices are counted 1040with capital letters (A., B., ...). 1041 1042 Again there is an optional \texttt{Label} attribute used for references. } 1043 1044 1045\subsection{\textcolor{Chapter }{\texttt{{\textless}Section{\textgreater}}}}\logpage{[ 3, 3, 5 ]} 1046\hyperdef{L}{X844DC2B47FB37339}{} 1047{ 1048 \index{Section@\texttt{Section}} 1049\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1050 <!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*> 1051 <!ATTLIST Section Label CDATA #IMPLIED> <!-- For reference purposes --> 1052\end{Verbatim} 1053 A \texttt{Section} element can have a \texttt{Label} attribute, such that this section can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the section as there is 1054no automatic labelling! 1055 1056 \texttt{Section} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), \texttt{Heading} elements, and subsections. 1057 1058 There must be exactly one direct \texttt{Heading} element in a \texttt{Section} element, containing the heading of the section. 1059 1060 Note that a subsection is either a \texttt{Subsection} element or a \texttt{ManSection} element. } 1061 1062 1063\subsection{\textcolor{Chapter }{\texttt{{\textless}Subsection{\textgreater}}}}\logpage{[ 3, 3, 6 ]} 1064\hyperdef{L}{X803ACA187E292969}{} 1065{ 1066 \index{Subsection@\texttt{Subsection}} 1067\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1068 <!ELEMENT Subsection (%Text;| Heading)*> 1069 <!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes --> 1070\end{Verbatim} 1071 The \texttt{Subsection} element can have a \texttt{Label} attribute, such that this subsection can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). Note that you have to specify a label to reference the subsection as there 1072is no automatic labelling! 1073 1074 \texttt{Subsection} elements can contain text (for a description of \texttt{\%Text;} see \ref{Text}), and \texttt{Heading} elements. 1075 1076 There must be exactly one \texttt{Heading} element in a \texttt{Subsection} element, containing the heading of the subsection. 1077 1078 Another type of subsection is a \texttt{ManSection}, explained now: } 1079 1080 } 1081 1082 1083\section{\textcolor{Chapter }{ManSection{\textendash}a special kind of subsection}}\label{sec:mansect} 1084\logpage{[ 3, 4, 0 ]} 1085\hyperdef{L}{X877B8B7C7EDD09E9}{} 1086{ 1087 \texttt{ManSection}s are intended to describe a function, operation, method, variable, or some 1088other technical instance. It is analogous to a manpage in the UNIX 1089environment. 1090\subsection{\textcolor{Chapter }{\texttt{{\textless}ManSection{\textgreater}}}}\logpage{[ 3, 4, 1 ]} 1091\hyperdef{L}{X8375D9CC8672A1D5}{} 1092{ 1093 \index{ManSection@\texttt{ManSection}} \index{Description@\texttt{Description}} \index{Returns@\texttt{Returns}} 1094\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1095 <!ELEMENT ManSection ( Heading?, 1096 ((Func, Returns?) | (Oper, Returns?) | 1097 (Meth, Returns?) | (Filt, Returns?) | 1098 (Prop, Returns?) | (Attr, Returns?) | 1099 (Constr, Returns?) | 1100 Var | Fam | InfoClass)+, Description )> 1101 <!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes --> 1102 1103 <!ELEMENT Returns (%Text;)*> 1104 <!ELEMENT Description (%Text;)*> 1105\end{Verbatim} 1106 The \texttt{ManSection} element can have a \texttt{Label} attribute, such that this subsection can be referenced later on with a \texttt{Ref} element (see section \ref{Ref}). But this is probably rarely necessary because the elements \texttt{Func} and so on (explained below) generate automatically labels for cross 1107referencing. 1108 1109 The content of a \texttt{ManSection} element is one or more elements describing certain items in \textsf{GAP}, each of them optionally followed by a \texttt{Returns} element, followed by a \texttt{Description} element, which contains \texttt{\%Text;} (see \ref{Text}) describing it. (Remember to include examples in the description as often as 1110possible, see{\nobreakspace}\ref{Log}). The classes of items \textsf{GAPDoc} knows of are: functions (\texttt{Func}), operations (\texttt{Oper}), constructors (\texttt{Constr}), methods (\texttt{Meth}), filters (\texttt{Filt}), properties (\texttt{Prop}), attributes (\texttt{Attr}), variables (\texttt{Var}), families (\texttt{Fam}), and info classes (\texttt{InfoClass}). One \texttt{ManSection} should only describe several of such items when these are very closely 1111related. 1112 1113 Each element for an item corresponding to a \textsf{GAP} function can be followed by a \texttt{Returns} element. In output versions of the document the string ``Returns: '' will be put in front of the content text. The text in the \texttt{Returns} element should usually be a short hint about the type of object returned by 1114the function. This is intended to give a good mnemonic for the use of a 1115function (together with a good choice of names for the formal arguments). 1116 1117 \texttt{ManSection}s are also sectioning elements which count as subsections. Usually there 1118should be no \texttt{Heading}-element in a \texttt{ManSection}, in that case a heading is generated automatically from the first \texttt{Func}-like element. Sometimes this default behaviour does not look appropriate, for 1119example when there are several \texttt{Func}-like elements. For such cases an optional \texttt{Heading} is allowed. } 1120 1121 1122\subsection{\textcolor{Chapter }{\texttt{{\textless}Func{\textgreater}}}}\label{Func} 1123\logpage{[ 3, 4, 2 ]} 1124\hyperdef{L}{X7C41A7B5845205C4}{} 1125{ 1126 \index{Func@\texttt{Func}} 1127\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1128 <!ELEMENT Func EMPTY> 1129 <!ATTLIST Func Name CDATA #REQUIRED 1130 Label CDATA #IMPLIED 1131 Arg CDATA #REQUIRED 1132 Comm CDATA #IMPLIED> 1133\end{Verbatim} 1134 This element is used within a \texttt{ManSection} element to specify the usage of a function. The \texttt{Name} attribute is required and its value is the name of the function. The value of 1135the \texttt{Arg} attribute (also required) contains the full list of arguments including 1136optional parts, which are denoted by square brackets. The argument names can 1137be separated by whitespace, commas or the square brackets for the optional 1138arguments, like \texttt{"grp[,{\nobreakspace}elm]"} or \texttt{"xx[y[z]{\nobreakspace}]"}. If \textsf{GAP} options are used, this can be followed by a colon \texttt{:} and one or more assignments, like \texttt{"n[,{\nobreakspace}r]: tries := 100"}. 1139 1140 The name of the function is also used as label for cross referencing. When the 1141name of the function appears in the text of the document it should \emph{always} be written with the \texttt{Ref} element, see{\nobreakspace}\ref{Ref}. This allows to use a unique typesetting style for function names and 1142automatic cross referencing. 1143 1144 If the optional \texttt{Label} attribute is given, it is appended (with a colon \texttt{:} in between) to the name of the function for cross referencing purposes. The 1145text of the label can also appear in the document text. So, it should be a 1146kind of short explanation. 1147\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 1148 <Func Arg="x[, y]" Name="LibFunc" Label="for my objects"/> 1149\end{Verbatim} 1150 The optional \texttt{Comm} attribute should be a short description of the function, usually at most one 1151line long (this is currently nowhere used). 1152 1153 This element automatically produces an index entry with the name of the 1154function and, if present, the text of the \texttt{Label} attribute as subentry (see also{\nobreakspace}\ref{TheIndex} and{\nobreakspace}\ref{Index}). } 1155 1156 1157\subsection{\textcolor{Chapter }{\texttt{{\textless}Oper{\textgreater}}}}\logpage{[ 3, 4, 3 ]} 1158\hyperdef{L}{X7A15825E818A81CD}{} 1159{ 1160 \index{Oper@\texttt{Oper}} 1161\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1162 <!ELEMENT Oper EMPTY> 1163 <!ATTLIST Oper Name CDATA #REQUIRED 1164 Label CDATA #IMPLIED 1165 Arg CDATA #REQUIRED 1166 Comm CDATA #IMPLIED> 1167\end{Verbatim} 1168 This element is used within a \texttt{ManSection} element to specify the usage of an operation. The attributes are used exactly 1169in the same way as in the \texttt{Func} element (see \ref{Func}). 1170 1171 Note that multiple descriptions of the same operation may occur in a document 1172because there may be several declarations in \textsf{GAP}. Furthermore there may be several \texttt{ManSection}s for methods of this operation (see{\nobreakspace}\ref{Meth}) which also use the same name. For reference purposes these must be 1173distinguished by different \texttt{Label} attributes. } 1174 1175 1176\subsection{\textcolor{Chapter }{\texttt{{\textless}Constr{\textgreater}}}}\logpage{[ 3, 4, 4 ]} 1177\hyperdef{L}{X7FBFD7A3786C7CAB}{} 1178{ 1179 \index{Constr@\texttt{Constr}} 1180\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1181 <!ELEMENT Constr EMPTY> 1182 <!ATTLIST Constr Name CDATA #REQUIRED 1183 Label CDATA #IMPLIED 1184 Arg CDATA #REQUIRED 1185 Comm CDATA #IMPLIED> 1186\end{Verbatim} 1187 This element is used within a \texttt{ManSection} element to specify the usage of a constructor. The attributes are used exactly 1188in the same way as in the \texttt{Func} element (see \ref{Func}). 1189 1190 Note that multiple descriptions of the same constructor may occur in a 1191document because there may be several declarations in \textsf{GAP}. Furthermore there may be several \texttt{ManSection}s for methods of this constructor (see{\nobreakspace}\ref{Meth}) which also use the same name. For reference purposes these must be 1192distinguished by different \texttt{Label} attributes. } 1193 1194 1195\subsection{\textcolor{Chapter }{\texttt{{\textless}Meth{\textgreater}}}}\label{Meth} 1196\logpage{[ 3, 4, 5 ]} 1197\hyperdef{L}{X81196E2B7F286A01}{} 1198{ 1199 \index{Meth@\texttt{Meth}} 1200\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1201 <!ELEMENT Meth EMPTY> 1202 <!ATTLIST Meth Name CDATA #REQUIRED 1203 Label CDATA #IMPLIED 1204 Arg CDATA #REQUIRED 1205 Comm CDATA #IMPLIED> 1206\end{Verbatim} 1207 This element is used within a \texttt{ManSection} element to specify the usage of a method. The attributes are used exactly in 1208the same way as in the \texttt{Func} element (see \ref{Func}). 1209 1210 Frequently, an operation is implemented by several different methods. 1211Therefore it seems to be interesting to document them independently. This is 1212possible by using the same method name in different \texttt{ManSection}s. It is however required that these subsections and those describing the 1213corresponding operation are distinguished by different \texttt{Label} attributes. } 1214 1215 1216\subsection{\textcolor{Chapter }{\texttt{{\textless}Filt{\textgreater}}}}\logpage{[ 3, 4, 6 ]} 1217\hyperdef{L}{X7D8D2C38828D5854}{} 1218{ 1219 \index{Filt@\texttt{Filt}} 1220\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1221 <!ELEMENT Filt EMPTY> 1222 <!ATTLIST Filt Name CDATA #REQUIRED 1223 Label CDATA #IMPLIED 1224 Arg CDATA #IMPLIED 1225 Comm CDATA #IMPLIED 1226 Type CDATA #IMPLIED> 1227\end{Verbatim} 1228 This element is used within a \texttt{ManSection} element to specify the usage of a filter. The first four attributes are used 1229in the same way as in the \texttt{Func} element (see \ref{Func}), except that the \texttt{Arg} attribute is optional. 1230 1231 The \texttt{Type} attribute can be any string, but it is thought to be something like ``\texttt{Category}'' or ``\texttt{Representation}''. } 1232 1233 1234\subsection{\textcolor{Chapter }{\texttt{{\textless}Prop{\textgreater}}}}\logpage{[ 3, 4, 7 ]} 1235\hyperdef{L}{X7D6400A67C30B752}{} 1236{ 1237 \index{Prop@\texttt{Prop}} 1238\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1239 <!ELEMENT Prop EMPTY> 1240 <!ATTLIST Prop Name CDATA #REQUIRED 1241 Label CDATA #IMPLIED 1242 Arg CDATA #REQUIRED 1243 Comm CDATA #IMPLIED> 1244\end{Verbatim} 1245 This element is used within a \texttt{ManSection} element to specify the usage of a property. The attributes are used exactly in 1246the same way as in the \texttt{Func} element (see \ref{Func}). 1247 1248 } 1249 1250 1251\subsection{\textcolor{Chapter }{\texttt{{\textless}Attr{\textgreater}}}}\logpage{[ 3, 4, 8 ]} 1252\hyperdef{L}{X78CEEC5986987A97}{} 1253{ 1254 \index{Attr@\texttt{Attr}} 1255\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1256 <!ELEMENT Attr EMPTY> 1257 <!ATTLIST Attr Name CDATA #REQUIRED 1258 Label CDATA #IMPLIED 1259 Arg CDATA #REQUIRED 1260 Comm CDATA #IMPLIED> 1261\end{Verbatim} 1262 This element is used within a \texttt{ManSection} element to specify the usage of an attribute (in \textsf{GAP}). The attributes are used exactly in the same way as in the \texttt{Func} element (see \ref{Func}). 1263 1264 } 1265 1266 1267\subsection{\textcolor{Chapter }{\texttt{{\textless}Var{\textgreater}}}}\logpage{[ 3, 4, 9 ]} 1268\hyperdef{L}{X7C3AACBE7BC6AABF}{} 1269{ 1270 \index{Var@\texttt{Var}} 1271\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1272 <!ELEMENT Var EMPTY> 1273 <!ATTLIST Var Name CDATA #REQUIRED 1274 Label CDATA #IMPLIED 1275 Comm CDATA #IMPLIED> 1276\end{Verbatim} 1277 This element is used within a \texttt{ManSection} element to document a global variable. The attributes are used exactly in the 1278same way as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute. 1279 1280 } 1281 1282 1283\subsection{\textcolor{Chapter }{\texttt{{\textless}Fam{\textgreater}}}}\logpage{[ 3, 4, 10 ]} 1284\hyperdef{L}{X85EE992E7FED2FE6}{} 1285{ 1286 \index{Fam@\texttt{Fam}} 1287\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1288 <!ELEMENT Fam EMPTY> 1289 <!ATTLIST Fam Name CDATA #REQUIRED 1290 Label CDATA #IMPLIED 1291 Comm CDATA #IMPLIED> 1292\end{Verbatim} 1293 This element is used within a \texttt{ManSection} element to document a family. The attributes are used exactly in the same way 1294as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute. 1295 1296 } 1297 1298 1299\subsection{\textcolor{Chapter }{\texttt{{\textless}InfoClass{\textgreater}}}}\logpage{[ 3, 4, 11 ]} 1300\hyperdef{L}{X78F0D4D1811E5BAE}{} 1301{ 1302 \index{InfoClass@\texttt{InfoClass}} 1303\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1304 <!ELEMENT InfoClass EMPTY> 1305 <!ATTLIST InfoClass Name CDATA #REQUIRED 1306 Label CDATA #IMPLIED 1307 Comm CDATA #IMPLIED> 1308\end{Verbatim} 1309 This element is used within a \texttt{ManSection} element to document an info class. The attributes are used exactly in the same 1310way as in the \texttt{Func} element (see \ref{Func}) except that there is no \texttt{Arg} attribute. 1311 1312 } 1313 1314 } 1315 1316 1317\section{\textcolor{Chapter }{Cross Referencing and Citations}}\logpage{[ 3, 5, 0 ]} 1318\hyperdef{L}{X78595FB585569617}{} 1319{ 1320 Cross referencing in the \textsf{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 1321the converters can produce better output. The HTML converter can for example 1322typeset a function reference just as the name of the function with a link to 1323the description of the function, or a chapter reference as a number with a 1324link in the other case. 1325 1326 Referencing is done with the \texttt{Ref} element: 1327\subsection{\textcolor{Chapter }{\texttt{{\textless}Ref{\textgreater}}}}\label{Ref} 1328\logpage{[ 3, 5, 1 ]} 1329\hyperdef{L}{X8656F2338007406E}{} 1330{ 1331 \index{Ref@\texttt{Ref}} 1332\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1333 <!ELEMENT Ref EMPTY> 1334 <!ATTLIST Ref Func CDATA #IMPLIED 1335 Oper CDATA #IMPLIED 1336 Constr CDATA #IMPLIED 1337 Meth CDATA #IMPLIED 1338 Filt CDATA #IMPLIED 1339 Prop CDATA #IMPLIED 1340 Attr CDATA #IMPLIED 1341 Var CDATA #IMPLIED 1342 Fam CDATA #IMPLIED 1343 InfoClass CDATA #IMPLIED 1344 Chap CDATA #IMPLIED 1345 Sect CDATA #IMPLIED 1346 Subsect CDATA #IMPLIED 1347 Appendix CDATA #IMPLIED 1348 Text CDATA #IMPLIED 1349 1350 Label CDATA #IMPLIED 1351 BookName CDATA #IMPLIED 1352 Style (Text | Number) #IMPLIED> <!-- normally automatic --> 1353\end{Verbatim} 1354 The \texttt{Ref} element is defined to be \texttt{EMPTY}. If one of the attributes \texttt{Func}, \texttt{Oper}, \texttt{Constr}, \texttt{Meth}, \texttt{Prop}, \texttt{Attr}, \texttt{Var}, \texttt{Fam}, \texttt{InfoClass}, \texttt{Chap}, \texttt{Sect}, \texttt{Subsect}, \texttt{Appendix} is given then there must be exactly one of these, making the reference one to 1355the corresponding object. The \texttt{Label} attribute can be specified in addition to make the reference unique, for 1356example if more than one method with a given name is present. (Note that there 1357is no way to specify in the DTD that exactly one of the first listed 1358attributes must be given, this is an additional rule.) 1359 1360 A reference to a \texttt{Label} element defined below (see \ref{Label}) is done by giving the \texttt{Label} attribute and optionally the \texttt{Text} attribute. If the \texttt{Text} attribute is present its value is typeset in place of the \texttt{Ref} element, if linking is possible (for example in HTML). If this is not 1361possible, the section number is typeset. This type of reference is also used 1362for references to tables (see \ref{Table}). 1363 1364 An external reference into another book can be specified by using the \texttt{BookName} attribute. In this case the \texttt{Label} attribute or, if this is not given, the function or section like attribute, is 1365used to resolve the reference. The generated reference points to the first hit 1366when asking ``?book name: label'' inside \textsf{GAP}. 1367 1368 The optional attribute \texttt{Style} can take only the values \texttt{Text} and \texttt{Number}. It can be used with references to sectioning units and it gives a hint to 1369the converter programs, whether an explicit section number is generated or 1370text. Normally all references to sections generate numbers and references to a \textsf{GAP} object generate the name of the corresponding object with some additional link 1371or sectioning information, which is the behavior of \texttt{Style="Text"}. In case \texttt{Style="Number"} in all cases an explicit section number is generated. So 1372\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 1373 <Ref Subsect="Func" Style="Text"/> described in section 1374 <Ref Subsect="Func" Style="Number"/> 1375\end{Verbatim} 1376 produces: \hyperref[Func]{`\texttt{{\textless}Func{\textgreater}}'} described in section \ref{Func}. } 1377 1378 1379\subsection{\textcolor{Chapter }{\texttt{{\textless}Label{\textgreater}}}}\label{Label} 1380\logpage{[ 3, 5, 2 ]} 1381\hyperdef{L}{X7C85CA5484344DB5}{} 1382{ 1383 \index{Label@\texttt{Label}} 1384\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1385 <!ELEMENT Label EMPTY> 1386 <!ATTLIST Label Name CDATA #REQUIRED> 1387\end{Verbatim} 1388 This element is used to define a label for referencing a certain position in 1389the document, if this is possible. If an exact reference is not possible (like 1390in a printed version of the document) a reference to the corresponding 1391subsection is generated. The value of the \texttt{Name} attribute must be unique under all \texttt{Label} elements. } 1392 1393 1394\subsection{\textcolor{Chapter }{\texttt{{\textless}Cite{\textgreater}}}}\label{Cite} 1395\logpage{[ 3, 5, 3 ]} 1396\hyperdef{L}{X851DE9D279D8FB04}{} 1397{ 1398 \index{Cite@\texttt{Cite}} 1399\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1400 <!ELEMENT Cite EMPTY> 1401 <!ATTLIST Cite Key CDATA #REQUIRED 1402 Where CDATA #IMPLIED> 1403\end{Verbatim} 1404 This element is for bibliography citations. It is \texttt{EMPTY} by definition. The attribute \texttt{Key} is the key for a lookup in a Bib{\TeX} database that has to be specified in the \texttt{Bibliography} element (see \ref{Bibliography}). The value of the \texttt{Where} attribute specifies the position in the document as in the corresponding {\LaTeX} syntax \texttt{\texttt{\symbol{92}}cite[Where value]\texttt{\symbol{123}}Key 1405value\texttt{\symbol{125}}}. } 1406 1407 1408\subsection{\textcolor{Chapter }{\texttt{{\textless}Index{\textgreater}}}}\label{Index} 1409\logpage{[ 3, 5, 4 ]} 1410\hyperdef{L}{X811042BA78843777}{} 1411{ 1412 \index{Index@\texttt{Index}} 1413\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1414 <!ELEMENT Index (%InnerText;|Subkey)*> 1415 <!ATTLIST Index Key CDATA #IMPLIED 1416 Subkey CDATA #IMPLIED> 1417 <!ELEMENT Subkey (%InnerText;)*> 1418\end{Verbatim} 1419 This element generates an index entry. The content of the element is typeset 1420in the index. It can optionally contain a \texttt{Subkey} element. If one or both of the attributes \texttt{Key} and \texttt{Subkey} are given, then the attribute values are used for sorting the index entries. 1421Otherwise the content itself is used for sorting. The attributes should be 1422used when the content contains markup. Note that all \texttt{Func} and similar elements automatically generate index entries. If the \texttt{TheIndex} element (\ref{TheIndex}) is not present in the document all \texttt{Index} elements are ignored. } 1423 1424 1425\subsection{\textcolor{Chapter }{\texttt{{\textless}URL{\textgreater}}}}\label{URL} 1426\logpage{[ 3, 5, 5 ]} 1427\hyperdef{L}{X81B3E46F839E1C5B}{} 1428{ 1429 \index{URL@\texttt{URL}} 1430\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1431 <!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*> <!-- Link, LinkText 1432 variant for case where text needs further markup --> 1433 <!ATTLIST URL Text CDATA #IMPLIED> <!-- This is for output formats 1434 that have links like HTML --> 1435 <!ELEMENT Link (%InnerText;)*> <!-- the URL --> 1436 <!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup --> 1437 1438\end{Verbatim} 1439 This element is for references into the internet. It specifies an URL and 1440optionally a text which can be used for a link (like in HTML or PDF versions 1441of the document). This can be specified in two ways: Either the URL is given 1442as element content and the text is given in the optional \texttt{Text} attribute (in this case the text cannot contain further markup), or the 1443element contains the two elements \texttt{Link} and \texttt{LinkText} which in turn contain the URL and the text, respectively. The default value 1444for the text is the URL itself. } 1445 1446 1447\subsection{\textcolor{Chapter }{\texttt{{\textless}Email{\textgreater}}}}\label{elEmail} 1448\logpage{[ 3, 5, 6 ]} 1449\hyperdef{L}{X8310C4F084CD9DB9}{} 1450{ 1451 \index{Email@\texttt{Email}} 1452\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1453 <!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*> 1454\end{Verbatim} 1455 This element type is the special case of an URL specifying an email address. 1456The content of the element should be the email address without any prefix like ``\texttt{mailto:}''. This address is typeset by all converters, also without any prefix. In the 1457case of an output document format like HTML the converter can produce a link 1458with a ``\texttt{mailto:}'' prefix. } 1459 1460 1461\subsection{\textcolor{Chapter }{\texttt{{\textless}Homepage{\textgreater}}}}\label{elHomepage} 1462\logpage{[ 3, 5, 7 ]} 1463\hyperdef{L}{X7D5CC4267D04D7E7}{} 1464{ 1465 \index{Homepage@\texttt{Homepage}} 1466\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1467 <!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*> 1468\end{Verbatim} 1469 This element type is the special case of an URL specifying a WWW-homepage. } 1470 1471 } 1472 1473 1474\section{\textcolor{Chapter }{Structural Elements like Lists}}\logpage{[ 3, 6, 0 ]} 1475\hyperdef{L}{X840099DF83823686}{} 1476{ 1477 The \textsf{GAPDoc} system offers some limited access to structural elements like lists, 1478enumerations, and tables. Although it is possible to use all {\LaTeX} constructs one always has to think about other output formats. The elements in 1479this section are guaranteed to produce something reasonable in all output 1480formats. 1481\subsection{\textcolor{Chapter }{\texttt{{\textless}List{\textgreater}}}}\label{List} 1482\logpage{[ 3, 6, 1 ]} 1483\hyperdef{L}{X785183F67DA402A0}{} 1484{ 1485 \index{List@\texttt{List}} 1486\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1487 <!ELEMENT List ( ((Mark,Item)|Item)+ )> 1488 <!ATTLIST List Only CDATA #IMPLIED 1489 Not CDATA #IMPLIED> 1490\end{Verbatim} 1491 This element produces a list. Each item in the list corresponds to an \texttt{Item} element. Every \texttt{Item} element is optionally preceded by a \texttt{Mark} element. The content of this is used as a marker for the item. Note that this 1492marker can be a whole word or even a sentence. It will be typeset in some 1493emphasized fashion and most converters will provide some indentation for the 1494rest of the item. 1495 1496 The \texttt{Only} and \texttt{Not} attributes can be used to specify, that the list is included into the output 1497by only one type of converter (\texttt{Only}) or all but one type of converter (\texttt{Not}). Of course at most one of the two attributes may occur in one element. The 1498following values are allowed as of now: ``\texttt{LaTeX}'', ``\texttt{HTML}'', and ``\texttt{Text}''. See also the \texttt{Alt} element in \ref{Alt} for more about text alternatives for certain converters. } 1499 1500 1501\subsection{\textcolor{Chapter }{\texttt{{\textless}Mark{\textgreater}}}}\logpage{[ 3, 6, 2 ]} 1502\hyperdef{L}{X7B1545A9797442DC}{} 1503{ 1504 \index{Mark@\texttt{Mark}} 1505\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1506 <!ELEMENT Mark ( %InnerText;)*> 1507\end{Verbatim} 1508 This element is used in the \texttt{List} element to mark items. See \ref{List} for an explanation. } 1509 1510 1511\subsection{\textcolor{Chapter }{\texttt{{\textless}Item{\textgreater}}}}\label{Item} 1512\logpage{[ 3, 6, 3 ]} 1513\hyperdef{L}{X86C204987AB4B13D}{} 1514{ 1515 \index{Item@\texttt{Item}} 1516\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1517 <!ELEMENT Item ( %Text;)*> 1518\end{Verbatim} 1519 This element is used in the \texttt{List}, \texttt{Enum}, and \texttt{Table} elements to specify the items. See sections \ref{List}, \ref{Enum}, and \ref{Table} for further information. } 1520 1521 1522\subsection{\textcolor{Chapter }{\texttt{{\textless}Enum{\textgreater}}}}\label{Enum} 1523\logpage{[ 3, 6, 4 ]} 1524\hyperdef{L}{X78A52B00846562DE}{} 1525{ 1526 \index{Enum@\texttt{Enum}} 1527\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1528 <!ELEMENT Enum ( Item+ )> 1529 <!ATTLIST Enum Only CDATA #IMPLIED 1530 Not CDATA #IMPLIED> 1531\end{Verbatim} 1532 This element is used like the \texttt{List} element (see \ref{List}) except that the items must not have marks attached to them. Instead, the 1533items are numbered automatically. The same comments about the \texttt{Only} and \texttt{Not} attributes as above apply. } 1534 1535 1536\subsection{\textcolor{Chapter }{\texttt{{\textless}Table{\textgreater}}}}\label{Table} 1537\logpage{[ 3, 6, 5 ]} 1538\hyperdef{L}{X7F9CAA577EB4070B}{} 1539{ 1540 \index{Table@\texttt{Table}} \index{Caption@\texttt{{\textless}Caption{\textgreater}}} \index{Row@\texttt{{\textless}Row{\textgreater}}} \index{Align@\texttt{{\textless}Align{\textgreater}}} \index{HorLine@\texttt{{\textless}HorLine{\textgreater}}} \index{Item in Table@\texttt{{\textless}Item{\textgreater}} in \texttt{{\textless}Table{\textgreater}}} 1541\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1542 <!ELEMENT Table ( Caption?, (Row | HorLine)+ )> 1543 <!ATTLIST Table Label CDATA #IMPLIED 1544 Only CDATA #IMPLIED 1545 Not CDATA #IMPLIED 1546 Align CDATA #REQUIRED> 1547 <!-- We allow | and l,c,r, nothing else --> 1548 <!ELEMENT Row ( Item+ )> 1549 <!ELEMENT HorLine EMPTY> 1550 <!ELEMENT Caption ( %InnerText;)*> 1551\end{Verbatim} 1552 A table in \textsf{GAPDoc} consists of an optional \texttt{Caption} element followed by a sequence of \texttt{Row} and \texttt{HorLine} elements. A \texttt{HorLine} element produces a horizontal line in the table. A \texttt{Row} element consists of a sequence of \texttt{Item} elements as they also occur in \texttt{List} and \texttt{Enum} elements. The \texttt{Only} and \texttt{Not} attributes have the same functionality as described in the \texttt{List} element in \ref{List}. 1553 1554 The \texttt{Align} attribute is written like a {\LaTeX} tabular alignment specifier but only the letters ``\texttt{l}'', ``\texttt{r}'', ``\texttt{c}'', and ``\texttt{|}'' are allowed meaning left alignment, right alignment, centered alignment, and a 1555vertical line as delimiter between columns respectively. 1556 1557 If the \texttt{Label} attribute is there, one can reference the table with the \texttt{Ref} element (see \ref{Ref}) using its \texttt{Label} attribute. 1558 1559 Usually only simple tables should be used. If you want a complicated table in 1560the {\LaTeX} output you should provide alternatives for text and HTML output. Note that in 1561HTML-4.0 there is no possibility to interpret the ``\texttt{|}'' column separators and \texttt{HorLine} elements as intended. There are lines between all columns and rows or no lines 1562at all. } 1563 1564 } 1565 1566 1567\section{\textcolor{Chapter }{Types of Text}}\logpage{[ 3, 7, 0 ]} 1568\hyperdef{L}{X7CA1E1327AFBA578}{} 1569{ 1570 This section covers the markup of text. Various types of ``text'' exist. The following elements are used in the \textsf{GAPDoc} system to mark them. They mostly come in pairs, one long name which is easier 1571to remember and a shortcut to make the markup ``lighter''. 1572 1573 Most of the following elements are thought to contain only character data and 1574no further markup elements. It is however necessary to allow \texttt{Alt} elements to resolve the entities described in section \ref{GDent}. 1575\subsection{\textcolor{Chapter }{\texttt{{\textless}Emph{\textgreater}} and \texttt{{\textless}E{\textgreater}}}}\logpage{[ 3, 7, 1 ]} 1576\hyperdef{L}{X7B15C428861749FD}{} 1577{ 1578 \index{Emph@\texttt{Emph}} \index{E@\texttt{E}} 1579\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1580 <!ELEMENT Emph (%InnerText;)*> <!-- Emphasize something --> 1581 <!ELEMENT E (%InnerText;)*> <!-- the same as shortcut --> 1582\end{Verbatim} 1583 This element is used to emphasize some piece of text. It may contain \texttt{\%InnerText;} (see \ref{InnerText}). } 1584 1585 1586\subsection{\textcolor{Chapter }{\texttt{{\textless}Quoted{\textgreater}} and \texttt{{\textless}Q{\textgreater}}}}\logpage{[ 3, 7, 2 ]} 1587\hyperdef{L}{X80028C2483C9467E}{} 1588{ 1589 \index{Quoted@\texttt{Quoted}} \index{Q@\texttt{Q}} 1590\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1591 <!ELEMENT Quoted (%InnerText;)*> <!-- Quoted (in quotes) text --> 1592 <!ELEMENT Q (%InnerText;)*> <!-- Quoted text (shortcut) --> 1593\end{Verbatim} 1594 This element is used to put some piece of text into ``{\nobreakspace}''-quotes. It may contain \texttt{\%InnerText;} (see \ref{InnerText}). } 1595 1596 1597\subsection{\textcolor{Chapter }{\texttt{{\textless}Keyword{\textgreater}} and \texttt{{\textless}K{\textgreater}}}}\logpage{[ 3, 7, 3 ]} 1598\hyperdef{L}{X867BB95E7DC87014}{} 1599{ 1600 \index{Keyword@\texttt{Keyword}} \index{K@\texttt{K}} 1601\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1602 <!ELEMENT Keyword (#PCDATA|Alt)*> <!-- Keyword --> 1603 <!ELEMENT K (#PCDATA|Alt)*> <!-- Keyword (shortcut) --> 1604\end{Verbatim} 1605 This element is used to mark something as a \emph{keyword}. Usually this will be a \textsf{GAP} keyword such as ``\texttt{if}'' or ``\texttt{for}''. No further markup elements are allowed within this element except for the \texttt{Alt} element, which is necessary. } 1606 1607 1608\subsection{\textcolor{Chapter }{\texttt{{\textless}Arg{\textgreater}} and \texttt{{\textless}A{\textgreater}}}}\label{Arg} 1609\logpage{[ 3, 7, 4 ]} 1610\hyperdef{L}{X86FD4CCA7F98351F}{} 1611{ 1612 \index{Arg@\texttt{Arg}} \index{A@\texttt{A}} 1613\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1614 <!ELEMENT Arg (#PCDATA|Alt)*> <!-- Argument --> 1615 <!ELEMENT A (#PCDATA|Alt)*> <!-- Argument (shortcut) --> 1616\end{Verbatim} 1617 This element is used inside \texttt{Description}s in \texttt{ManSection}s to mark something as an \emph{argument} (of a function, operation, or such). It is guaranteed that the converters 1618typeset those exactly as in the definition of functions. No further markup 1619elements are allowed within this element. } 1620 1621 1622\subsection{\textcolor{Chapter }{\texttt{{\textless}Code{\textgreater}} and \texttt{{\textless}C{\textgreater}}}}\label{Code} 1623\logpage{[ 3, 7, 5 ]} 1624\hyperdef{L}{X8400998B7B3A4379}{} 1625{ 1626 \index{Code@\texttt{Code}} \index{C@\texttt{C}} 1627\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1628 <!ELEMENT Code (#PCDATA|Arg|Alt)*> <!-- GAP code --> 1629 <!ELEMENT C (#PCDATA|Arg|Alt)*> <!-- GAP code (shortcut) --> 1630\end{Verbatim} 1631 This element is used to mark something as a piece of \emph{code} like for example a \textsf{GAP} expression. It is guaranteed that the converters typeset this exactly as in 1632the \texttt{Listing} element (compare section \ref{Listing}). The only further markup elements allowed within this element are \texttt{{\textless}Arg{\textgreater}} elements (see \ref{Arg}). } 1633 1634 1635\subsection{\textcolor{Chapter }{\texttt{{\textless}File{\textgreater}} and \texttt{{\textless}F{\textgreater}}}}\logpage{[ 3, 7, 6 ]} 1636\hyperdef{L}{X875AF9B4812C5249}{} 1637{ 1638 \index{File@\texttt{File}} \index{F@\texttt{F}} 1639\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1640 <!ELEMENT File (#PCDATA|Alt)*> <!-- Filename --> 1641 <!ELEMENT F (#PCDATA|Alt)*> <!-- Filename (shortcut) --> 1642\end{Verbatim} 1643 This element is used to mark something as a \emph{filename} or a \emph{pathname} in the file system. No further markup elements are allowed within this 1644element. } 1645 1646 1647\subsection{\textcolor{Chapter }{\texttt{{\textless}Button{\textgreater}} and \texttt{{\textless}B{\textgreater}}}}\logpage{[ 3, 7, 7 ]} 1648\hyperdef{L}{X7929BA7D78A977FF}{} 1649{ 1650 \index{Button@\texttt{Button}} \index{B@\texttt{B}} 1651\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1652 <!ELEMENT Button (#PCDATA|Alt)*> <!-- "Button" (also Menu, Key, ...) --> 1653 <!ELEMENT B (#PCDATA|Alt)*> <!-- "Button" (shortcut) --> 1654\end{Verbatim} 1655 This element is used to mark something as a \emph{button}. It can also be used for other items in a graphical user interface like \emph{menus}, \emph{menu entries}, or \emph{keys}. No further markup elements are allowed within this element. } 1656 1657 1658\subsection{\textcolor{Chapter }{\texttt{{\textless}Package{\textgreater}}}}\logpage{[ 3, 7, 8 ]} 1659\hyperdef{L}{X7F4FFA877B775188}{} 1660{ 1661 \index{Package@\texttt{Package}} 1662\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1663 <!ELEMENT Package (#PCDATA|Alt)*> <!-- A package name --> 1664\end{Verbatim} 1665 This element is used to mark something as a name of a \emph{package}. This is for example used to define the entities \textsf{GAP}, \textsf{XGAP} or \textsf{GAPDoc} (see section \ref{GDent}). No further markup elements are allowed within this element. } 1666 1667 1668\subsection{\textcolor{Chapter }{\texttt{{\textless}Listing{\textgreater}}}}\label{Listing} 1669\logpage{[ 3, 7, 9 ]} 1670\hyperdef{L}{X7F531B157D656836}{} 1671{ 1672 \index{Listing@\texttt{Listing}} 1673\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1674 <!ELEMENT Listing (#PCDATA)> <!-- This is just for GAP code listings --> 1675 <!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of 1676 listed code, may appear in 1677 output --> 1678\end{Verbatim} 1679 This element is used to embed listings of programs into the document. Only 1680character data and no other elements are allowed in the content. You should \emph{not} use the character entities described in section \ref{GDent} but instead type the characters directly. Only the general XML rules from 1681section \ref{EnterXML} apply. Note especially the usage of \texttt{{\textless}![CDATA[} sections described there. It is guaranteed that all converters use a fixed 1682width font for typesetting \texttt{Listing} elements. Compare also the usage of the \texttt{Code} and \texttt{C} elements in \ref{Code}. 1683 1684 The \texttt{Type} attribute contains a comment about the type of listed code. It may appear in 1685the output. } 1686 1687 1688\subsection{\textcolor{Chapter }{\texttt{{\textless}Log{\textgreater}} and \texttt{{\textless}Example{\textgreater}}}}\label{Log} 1689\logpage{[ 3, 7, 10 ]} 1690\hyperdef{L}{X810DEA1E83A57CFE}{} 1691{ 1692 \index{Log@\texttt{Log}} \index{Example@\texttt{Example}} 1693\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1694 <!ELEMENT Example (#PCDATA)> <!-- This is subject to the automatic 1695 example checking mechanism --> 1696 <!ELEMENT Log (#PCDATA)> <!-- This not --> 1697\end{Verbatim} 1698 These two elements behave exactly like the \texttt{Listing} element (see \ref{Listing}). They are thought for protocols of \textsf{GAP} sessions. The only difference between the two is that \texttt{Example} sections are intended to be subject to an automatic manual checking mechanism 1699used to ensure the correctness of the \textsf{GAP} manual whereas \texttt{Log} is not touched by this (see section \ref{Sec:TestExample} for checking tools). 1700 1701 To get a good layout of the examples for display in a standard terminal we 1702suggest to use \texttt{SizeScreen([72]);} (see \texttt{SizeScreen} (\textbf{Reference: SizeScreen})) in your \textsf{GAP} session before producing the content of \texttt{Example} elements. } 1703 1704 1705\subsection{\textcolor{Chapter }{\texttt{{\textless}Verb{\textgreater}}}}\label{Verb} 1706\logpage{[ 3, 7, 11 ]} 1707\hyperdef{L}{X7F8C4D018346B2CF}{} 1708{ 1709 There is one further type of verbatim-like element. 1710\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1711 <!ELEMENT Verb (#PCDATA)> 1712\end{Verbatim} 1713 The content of such an element is guaranteed to be put into an output version 1714exactly as it is using some fixed width font. Before the content a new line is 1715started. If the line after the end of the start tag consists of whitespace 1716only then this part of the content is skipped. 1717 1718 This element is intended to be used together with the \texttt{Alt} element to specify pre-formatted ASCII alternatives for complicated \texttt{Display} formulae or \texttt{Table}s. } 1719 1720 } 1721 1722 1723\section{\textcolor{Chapter }{Elements for Mathematical Formulae}}\label{MathForm} 1724\logpage{[ 3, 8, 0 ]} 1725\hyperdef{L}{X8145F6B37C04AA0A}{} 1726{ 1727 1728\subsection{\textcolor{Chapter }{\texttt{{\textless}Math{\textgreater}} and \texttt{{\textless}Display{\textgreater}}}}\label{Math} 1729\logpage{[ 3, 8, 1 ]} 1730\hyperdef{L}{X7AA02845868AA533}{} 1731{ 1732 \index{Math@\texttt{Math}} \index{Display@\texttt{Display}} 1733\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1734 <!-- Normal TeX math mode formula --> 1735 <!ELEMENT Math (#PCDATA|A|Arg|Alt)*> 1736 <!-- TeX displayed math mode formula --> 1737 <!ELEMENT Display (#PCDATA|A|Arg|Alt)*> 1738 <!-- Mode="M" causes <M>-style formatting --> 1739 <!ATTLIST Display Mode CDATA #IMPLIED> 1740\end{Verbatim} 1741 These elements are used for mathematical formulae. As described in section \ref{GDformulae} they correspond to {\LaTeX}'s math and display math mode respectively. 1742 1743 The formulae are typed in as in {\LaTeX}, \emph{except} that the standard XML entities, see{\nobreakspace}\ref{XMLent} (in particular the characters \texttt{{\textless}} and \texttt{\&}), must be escaped - either by using the corresponding entities or by 1744enclosing the formula between ``\texttt{{\textless}![CDATA[}'' and ``\texttt{]]{\textgreater}}''. (The main reference for {\LaTeX} is \cite{La85}.) 1745 1746 It is also possible to use some unicode characters for mathematical symbols 1747directly, provided that it can be translated by \texttt{Encode} (\ref{Encode}) into \texttt{"LaTeX"} encoding and that \texttt{SimplifiedUnicodeString} (\ref{SimplifiedUnicodeString}) with arguments \texttt{"latin1"} and \texttt{"single"} returns something sensible. Currently, we support entities \texttt{\&CC;}, \texttt{\&ZZ;}, \texttt{\&NN;}, \texttt{\&PP;}, \texttt{\&QQ;}, \texttt{\&HH;}, \texttt{\&RR;} for the corresponding black board bold letters {\ensuremath{\mathbb C}}, 1748{\ensuremath{\mathbb Z}}, {\ensuremath{\mathbb N}}, {\ensuremath{\mathbb P}}, 1749{\ensuremath{\mathbb Q}}, {\ensuremath{\mathbb H}} and {\ensuremath{\mathbb 1750R}}, respectively. 1751 1752 The only element type that is allowed within the formula elements is the \texttt{Arg} or \texttt{A} element (see \ref{Arg}), which is used to typeset identifiers that are arguments to \textsf{GAP} functions or operations. 1753 1754 If a \texttt{Display} element has an attribute \texttt{Mode} with value \texttt{"M"}, then the formula is formatted as in \texttt{M} elements (see{\nobreakspace}\ref{M}). Otherwise in text and HTML output the formula is shown as {\LaTeX} source code. 1755 1756 For simple formulae (and you should try to make all your formulae simple!) 1757attempt to use the \texttt{M} element or the \texttt{Mode="M"} attribute in \texttt{Display} for which there is a well defined translation into text, which can be used for 1758text and HTML output versions of the document. So, if possible try to avoid 1759the \texttt{Math} elements and \texttt{Display} elements without attribute or provide useful text substitutes for complicated 1760formulae via \texttt{Alt} elements (see{\nobreakspace}\ref{Alt} and{\nobreakspace}\ref{Verb}). } 1761 1762 1763\subsection{\textcolor{Chapter }{\texttt{{\textless}M{\textgreater}}}}\label{M} 1764\logpage{[ 3, 8, 2 ]} 1765\hyperdef{L}{X7ABF42328467E966}{} 1766{ 1767 \index{M@\texttt{M}} 1768\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1769 <!-- Math with well defined translation to text output --> 1770 <!ELEMENT M (#PCDATA|A|Arg|Alt)*> 1771\end{Verbatim} 1772 The ``\texttt{M}'' element type is intended for formulae in the running text for which there is a 1773sensible text version. For the {\LaTeX} version of a \textsf{GAPDoc} document the \texttt{M} and \texttt{Math} elements are equivalent. The remarks in \ref{Math} about special characters and the \texttt{Arg} element apply here as well. A document which has all formulae enclosed in \texttt{M} elements can be well readable in text terminal output and printed output 1774versions. 1775 1776 Compared to former versions of \textsf{GAPDoc} many more formulae can be put into \texttt{M} elements. Most modern terminal emulations support unicode characters and many 1777mathematical symbols can now be represented by such characters. But even if a 1778terminal can only display ASCII characters, the user will see some not too bad 1779representation of a formula. 1780 1781 As examples, here are some {\LaTeX} macros which have a sensible ASCII translation and are guaranteed to be 1782translated accordingly by text (and HTML) converters (for a full list of 1783handled Macros see \texttt{RecNames(TEXTMTRANSLATIONS)}): \begin{center} 1784\begin{tabular}{|l|l|}\hline 1785\texttt{\symbol{92}}ast& 1786\texttt{*}\\ 1787\hline 1788\texttt{\symbol{92}}bf& 1789\texttt{}\\ 1790\hline 1791\texttt{\symbol{92}}bmod& 1792\texttt{mod}\\ 1793\hline 1794\texttt{\symbol{92}}cdot& 1795\texttt{*}\\ 1796\hline 1797\texttt{\symbol{92}}colon& 1798\texttt{:}\\ 1799\hline 1800\texttt{\symbol{92}}equiv& 1801\texttt{=}\\ 1802\hline 1803\texttt{\symbol{92}}geq& 1804\texttt{{\textgreater}=}\\ 1805\hline 1806\texttt{\symbol{92}}germ& 1807\texttt{}\\ 1808\hline 1809\texttt{\symbol{92}}hookrightarrow& 1810\texttt{-{\textgreater}}\\ 1811\hline 1812\texttt{\symbol{92}}iff& 1813\texttt{{\textless}={\textgreater}}\\ 1814\hline 1815\texttt{\symbol{92}}langle& 1816\texttt{{\textless}}\\ 1817\hline 1818\texttt{\symbol{92}}ldots& 1819\texttt{...}\\ 1820\hline 1821\texttt{\symbol{92}}left& 1822\texttt{{\nobreakspace}}\\ 1823\hline 1824\texttt{\symbol{92}}leq& 1825\texttt{{\textless}=}\\ 1826\hline 1827\texttt{\symbol{92}}leftarrow& 1828\texttt{{\textless}-}\\ 1829\hline 1830\texttt{\symbol{92}}Leftarrow& 1831\texttt{{\textless}=}\\ 1832\hline 1833\texttt{\symbol{92}}limits& 1834\texttt{{\nobreakspace}}\\ 1835\hline 1836\texttt{\symbol{92}}longrightarrow& 1837\texttt{--{\textgreater}}\\ 1838\hline 1839\texttt{\symbol{92}}Longrightarrow& 1840\texttt{=={\textgreater}}\\ 1841\hline 1842\texttt{\symbol{92}}mapsto& 1843\texttt{-{\textgreater}}\\ 1844\hline 1845\texttt{\symbol{92}}mathbb& 1846\texttt{{\nobreakspace}}\\ 1847\hline 1848\texttt{\symbol{92}}mathop& 1849\texttt{{\nobreakspace}}\\ 1850\hline 1851\texttt{\symbol{92}}mid& 1852\texttt{|}\\ 1853\hline 1854\texttt{\symbol{92}}pmod& 1855\texttt{mod}\\ 1856\hline 1857\texttt{\symbol{92}}prime& 1858\texttt{'}\\ 1859\hline 1860\texttt{\symbol{92}}rangle& 1861\texttt{{\textgreater}}\\ 1862\hline 1863\texttt{\symbol{92}}right& 1864\texttt{{\nobreakspace}}\\ 1865\hline 1866\texttt{\symbol{92}}rightarrow& 1867\texttt{-{\textgreater}}\\ 1868\hline 1869\texttt{\symbol{92}}Rightarrow& 1870\texttt{={\textgreater}}\\ 1871\hline 1872\texttt{\symbol{92}}rm, \texttt{\symbol{92}}sf, \texttt{\symbol{92}}textrm, 1873\texttt{\symbol{92}}text& 1874\texttt{}\\ 1875\hline 1876\texttt{\symbol{92}}setminus& 1877\texttt{\texttt{\symbol{92}}}\\ 1878\hline 1879\texttt{\symbol{92}}thinspace& 1880\texttt{ }\\ 1881\hline 1882\texttt{\symbol{92}}times& 1883\texttt{x}\\ 1884\hline 1885\texttt{\symbol{92}}to& 1886\texttt{-{\textgreater}}\\ 1887\hline 1888\texttt{\symbol{92}}vert& 1889\texttt{|}\\ 1890\hline 1891\texttt{\symbol{92}}!& 1892\texttt{}\\ 1893\hline 1894\texttt{\symbol{92}},& 1895\texttt{}\\ 1896\hline 1897\texttt{\symbol{92}};& 1898\texttt{{\nobreakspace}}\\ 1899\hline 1900\texttt{\symbol{92}}\texttt{\symbol{123}}& 1901\texttt{\texttt{\symbol{123}}}\\ 1902\hline 1903\texttt{\symbol{92}}\texttt{\symbol{125}}& 1904\texttt{\texttt{\symbol{125}}}\\ 1905\hline 1906\end{tabular}\\[2mm] 1907\textbf{Table: }{\LaTeX} macros with special text translation\end{center} 1908 1909 In all other macros only the backslash is removed (except for some macros 1910describing more exotic symbols). Whitespace is normalized (to one blank) but 1911not removed. Note that whitespace is not added, so you may want to add a few 1912more spaces than you usually do in your {\LaTeX} documents. 1913 1914 Braces \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} are removed in general, however pairs of double braces are converted to one 1915pair of braces. This can be used to write \texttt{{\textless}M{\textgreater}x\texttt{\symbol{94}}\texttt{\symbol{123}}12\texttt{\symbol{125}}{\textless}/M{\textgreater}} for \texttt{x\texttt{\symbol{94}}12} and \texttt{{\textless}M{\textgreater}x{\textunderscore}\texttt{\symbol{123}}\texttt{\symbol{123}}i+1\texttt{\symbol{125}}\texttt{\symbol{125}}{\textless}/M{\textgreater}} for \texttt{x{\textunderscore}\texttt{\symbol{123}}i+1\texttt{\symbol{125}}}. 1916 1917 } 1918 1919 } 1920 1921 1922\section{\textcolor{Chapter }{Everything else}}\label{sec:misc} 1923\logpage{[ 3, 9, 0 ]} 1924\hyperdef{L}{X7A0D26B180BEDE37}{} 1925{ 1926 1927\subsection{\textcolor{Chapter }{\texttt{{\textless}Alt{\textgreater}}}}\label{Alt} 1928\logpage{[ 3, 9, 1 ]} 1929\hyperdef{L}{X850E69017945AE3E}{} 1930{ 1931 \index{Alt@\texttt{Alt}} This element is used to specify alternatives for different output formats 1932within normal text. See also sections \ref{List}, \ref{Enum}, and \ref{Table} for alternatives in lists and tables. 1933\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1934 <!ELEMENT Alt (%InnerText;)*> <!-- This is only to allow "Only" and 1935 "Not" attributes for normal text --> 1936 <!ATTLIST Alt Only CDATA #IMPLIED 1937 Not CDATA #IMPLIED> 1938\end{Verbatim} 1939 Of course exactly one of the two attributes must occur in one element. The 1940attribute values must be one word or a list of words, separated by spaces or 1941commas. The words which are currently recognized by the converter programs 1942contained in \textsf{GAPDoc} are: ``\texttt{LaTeX}'', ``\texttt{HTML}'', and ``\texttt{Text}''. If the \texttt{Only} attribute is specified then only the corresponding converter will include the 1943content of the element into the output document. If the \texttt{Not} attribute is specified the corresponding converter will ignore the content of 1944the element. You can use other words to specify special alternatives for other 1945converters of \textsf{GAPDoc} documents. 1946 1947 In the case of ``\texttt{HTML}'' there is a second word which is recognized and this can either be ``\texttt{MathJax}'' or ``\texttt{noMathJax}''. For example a pair of \texttt{Alt} elements with \texttt{{\textless}Alt Only="HTML noMathJax"{\textgreater}...} and \texttt{{\textless}Alt Not="HTML noMathJax"{\textgreater}...} could provide special content for the case of HTML output without use of \textsf{MathJax} and every other output. 1948 1949 We fix a rule for handling the content of an \texttt{Alt} element with \texttt{Only} attribute. In their content code for the corresponding output format is 1950included 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 1951content. In the case of {\LaTeX} the formatting of the code is not changed. 1952 1953 Within the element only \texttt{\%InnerText;} (see \ref{InnerText}) is allowed. This is to ensure that the same set of chapters, sections, and 1954subsections show up in all output formats. } 1955 1956 1957\subsection{\textcolor{Chapter }{\texttt{{\textless}Par{\textgreater}} and \texttt{{\textless}P{\textgreater}}}}\label{Par} 1958\logpage{[ 3, 9, 2 ]} 1959\hyperdef{L}{X85D23A648444069F}{} 1960{ 1961 \index{Par@\texttt{Par}} \index{P@\texttt{P}} 1962\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1963 <!ELEMENT Par EMPTY> <!-- this is intentionally empty! --> 1964 <!ELEMENT P EMPTY> <!-- the same as shortcut --> 1965\end{Verbatim} 1966 This \texttt{EMPTY} element marks the boundary of paragraphs. Note that an empty line in the input 1967does not mark a new paragraph as opposed to the {\LaTeX} convention. 1968 1969 (Remark: it would be much easier to parse a document and to understand its 1970sectioning and paragraph structure when there was an element whose \emph{content} is the text of a paragraph. But in practice many paragraph boundaries are 1971implicitly clear which would make it somewhat painful to enclose each 1972paragraph in extra tags. The introduction of the \texttt{P} or \texttt{Par} elements as above delegates this pain to the writer of a conversion program 1973for \textsf{GAPDoc} documents.) } 1974 1975 1976\subsection{\textcolor{Chapter }{\texttt{{\textless}Br{\textgreater}}}}\label{Br} 1977\logpage{[ 3, 9, 3 ]} 1978\hyperdef{L}{X7A3EF0647B10C1EC}{} 1979{ 1980 \index{Br@\texttt{Br}} 1981\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1982 <!ELEMENT Br EMPTY> <!-- a forced line break --> 1983\end{Verbatim} 1984 This element can be used to force a line break in the output versions of a \textsf{GAPDoc} element, it does not start a new paragraph. Please, do not use this instead of 1985a \texttt{Par} element, this would often lead to ugly output versions of your document. } 1986 1987 1988\subsection{\textcolor{Chapter }{\texttt{{\textless}Ignore{\textgreater}}}}\label{Ignore} 1989\logpage{[ 3, 9, 4 ]} 1990\hyperdef{L}{X7A81FB717A30B485}{} 1991{ 1992 \index{Ignore@\texttt{Ignore}} 1993\begin{Verbatim}[fontsize=\small,frame=single,label=From gapdoc.dtd] 1994 <!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection | 1995 Heading)*> 1996 <!ATTLIST Ignore Remark CDATA #IMPLIED> 1997\end{Verbatim} 1998 This element can appear anywhere. Its content is ignored by the standard 1999converters. It can be used, for example, to include data which are not part of 2000the actual \textsf{GAPDoc} document, like source code, or to make not finished parts of the document 2001invisible. 2002 2003 Of course, one can use special converter programs which extract the contents 2004of \texttt{Ignore} elements. Information on the type of the content can be stored in the optional 2005attribute \texttt{Remark}. } 2006 2007 } 2008 2009 } 2010 2011 2012\chapter{\textcolor{Chapter }{Distributing a Document into Several Files}}\label{Distributing} 2013\logpage{[ 4, 0, 0 ]} 2014\hyperdef{L}{X7A3355C07F57C280}{} 2015{ 2016 In \textsf{GAPDoc} there are facilities to distribute a single document over several files. This 2017is for example interesting, if one wants to store the documentation of some 2018code in the same file as the code itself. Or, if one just wants to store 2019chapters of a document in separate files. There is a set of conventions how 2020this is done and some tools to collect the text for further processing. 2021 2022 The technique can also be used to distribute and collect other types of 2023documents into respectively from several files (e.g., source code, examples). 2024 2025 2026\section{\textcolor{Chapter }{The Conventions}}\label{DistrConv} 2027\logpage{[ 4, 1, 0 ]} 2028\hyperdef{L}{X7CE078A07E8256DC}{} 2029{ 2030 \index{Include@\texttt{{\textless}\#Include{\textgreater}}} \index{GAPDoc@\texttt{{\textless}\#GAPDoc{\textgreater}}} In this description we use the string \texttt{GAPDoc} for marking pieces of a document to collect. 2031 2032 Pieces of documentation that shall be incorporated into another document are 2033marked as follows: 2034\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 2035 ## <#GAPDoc Label="MyPiece"> 2036 ## <E>This</E> is the piece. 2037 ## The hash characters are removed. 2038 ## <#/GAPDoc> 2039\end{Verbatim} 2040 This piece is then included into another file by a statement like: \texttt{{\textless}\#Include Label="MyPiece"{\textgreater}} Here are the exact rules, how pieces are gathered: 2041\begin{itemize} 2042\item All lines up to a line containing the character sequence ``\texttt{{\textless}\#GAPDoc{\nobreakspace}Label="}'' (exactly one space character) are ignored. The characters on the same line 2043before this sequence are stored as ``prefix''. The characters after the sequence up to the next double quotes character 2044(which should not contain whitespace) are stored as ``label''. All other characters in the line are ignored. 2045\item The following lines up to a line containing the character sequence ``\texttt{{\textless}\#/GAPDoc{\textgreater}}'' are stored under the label. These lines are processed as follows: The longest 2046possible substring from the beginning of the line that equals the 2047corresponding substring of the prefix is removed. 2048\end{itemize} 2049 Having stored a list of labels and pieces of text gathered as above this can 2050be used as follows. 2051\begin{itemize} 2052\item In \textsf{GAPDoc} documentation files all statements of the form ``\texttt{{\textless}\#Include Label="Key"{\textgreater}}'' are replaced by the sequence of lines stored under the label \texttt{Key}. 2053\item Additionally, every occurrence of a statement of the form ``\texttt{{\textless}\#Include SYSTEM "Filename"{\textgreater}}'' is replaced by the whole file stored under the name \texttt{Filename} in the file system. 2054\item These substitutions are done recursively (although one should probably avoid 2055to use this extensively). 2056\end{itemize} 2057 Here is another example: 2058\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 2059 # # <#GAPDoc Label="AnotherPiece"> some characters 2060 # # This text is not indented. 2061 # This text is indented by one blank. 2062 #Not indented. 2063 #<#/GAPDoc> 2064\end{Verbatim} 2065 replaces \texttt{{\textless}\#Include Label="AnotherPiece"{\textgreater}} by 2066\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 2067 This text is not indented. 2068 This text is indented by one blank. 2069 Not indented. 2070\end{Verbatim} 2071 Since these rules are very simple it is quite easy to write a program in 2072almost any programming language which does this gathering of text pieces and 2073the substitutions. In \textsf{GAPDoc} there is the \textsf{GAP} function \texttt{ComposedDocument} (\ref{ComposedDocument}) which does this. 2074 2075 Note that the XML-tag-like markup we have used here is not a legal XML markup, 2076since the hash character is not allowed in element names. The mechanism 2077described here is a preprocessing step which composes a document. } 2078 2079 2080\section{\textcolor{Chapter }{A Tool for Collecting a Document}}\logpage{[ 4, 2, 0 ]} 2081\hyperdef{L}{X81E07B0F83EBDA5F}{} 2082{ 2083 2084 2085\subsection{\textcolor{Chapter }{ComposedDocument}} 2086\logpage{[ 4, 2, 1 ]}\nobreak 2087\hyperdef{L}{X857D77557D12559D}{} 2088{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ComposedDocument({\mdseries\slshape tagname, path, main, source[, info]})\index{ComposedDocument@\texttt{ComposedDocument}} 2089\label{ComposedDocument} 2090}\hfill{\scriptsize (function)}}\\ 2091\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ComposedXMLString({\mdseries\slshape path, main, source[, info]})\index{ComposedXMLString@\texttt{ComposedXMLString}} 2092\label{ComposedXMLString} 2093}\hfill{\scriptsize (function)}}\\ 2094\textbf{\indent Returns:\ } 2095a document as string, or a list with this string and information about the 2096source positions 2097 2098 2099 2100 The argument \mbox{\texttt{\mdseries\slshape tagname}} is the string used for the pseudo elements which mark the pieces of a document 2101to collect. (In \ref{DistrConv} we used \texttt{GAPDoc} as \mbox{\texttt{\mdseries\slshape tagname}}. The second function \texttt{ComposedXMLString}\texttt{( ... )} is an abbreviation for \texttt{ComposedDocument}\texttt{("GAPDoc", ... )}. 2102 2103 The argument \mbox{\texttt{\mdseries\slshape path}} must be a path to some directory (as string or directory object), \mbox{\texttt{\mdseries\slshape main}} the name of a file and \mbox{\texttt{\mdseries\slshape source}} a list of file names. These file names are relative to \mbox{\texttt{\mdseries\slshape path}}, except they start with \texttt{"/"} to specify an absolute path or they start with \texttt{"gap://"} to specify a file relative to the \textsf{GAP} roots (see \texttt{FilenameGAP} (\ref{FilenameGAP})). The document is constructed via the mechanism described in 2104Section{\nobreakspace}\ref{DistrConv}. 2105 2106 First the files given in \mbox{\texttt{\mdseries\slshape source}} are scanned for chunks of the document marked by \texttt{{\textless}\#\mbox{\texttt{\mdseries\slshape tagname}} Label="..."{\textgreater}} and \texttt{{\textless}/\#\mbox{\texttt{\mdseries\slshape tagname}}{\textgreater}} pairs. Then the file \mbox{\texttt{\mdseries\slshape main}} is read and all \texttt{{\textless}\#Include ... {\textgreater}}-tags are substituted recursively by other files or chunks of documentation 2107found in the first step, respectively. 2108 2109 If the optional argument \mbox{\texttt{\mdseries\slshape info}} is given and set to \texttt{true} this function returns a list \texttt{[str, origin]}, where \texttt{str} is a string containing the composed document and \texttt{origin} is a sorted list of entries of the form \texttt{[pos, filename, line]}. Here \texttt{pos} runs through all character positions of starting lines or text pieces from 2110different files in \texttt{str}. The \texttt{filename} and \texttt{line} describe the origin of this part of the collected document. 2111 2112 Without the fourth argument only the string \texttt{str} is returned. 2113 2114 By default \texttt{ComposedDocument} runs into an error if an \texttt{{\textless}\#Include ...{\textgreater}}-tag cannot be substituted (because a file or chunk is missing). This 2115behaviour can be changed by setting \texttt{DOCCOMPOSEERROR := false;}. Then the missing parts are substituted by a short note about what is 2116missing. Of course, this feature is only useful if the resulting document is a 2117valid XML document (e.g., when the missing pieces are complete paragraphs or 2118sections). 2119 2120 2121\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2122 !gapprompt@gap>| !gapinput@doc := ComposedDocument("GAPDoc", "/my/dir", "manual.xml", | 2123 !gapprompt@>| !gapinput@["../lib/func.gd", "../lib/func.gi"], true);;| 2124\end{Verbatim} 2125 } 2126 2127 2128 2129\subsection{\textcolor{Chapter }{OriginalPositionDocument}} 2130\logpage{[ 4, 2, 2 ]}\nobreak 2131\hyperdef{L}{X86D1141E7EDCAAC8}{} 2132{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{OriginalPositionDocument({\mdseries\slshape srcinfo, pos})\index{OriginalPositionDocument@\texttt{OriginalPositionDocument}} 2133\label{OriginalPositionDocument} 2134}\hfill{\scriptsize (function)}}\\ 2135\textbf{\indent Returns:\ } 2136A pair \texttt{[filename, linenumber]}. 2137 2138 2139 2140 Here \mbox{\texttt{\mdseries\slshape srcinfo}} must be a data structure as returned as second entry by \texttt{ComposedDocument} (\ref{ComposedDocument}) called with \mbox{\texttt{\mdseries\slshape info}}=\texttt{true}. It returns for a given position \mbox{\texttt{\mdseries\slshape pos}} in the composed document the file name and line number from which that text 2141was collected. } 2142 2143 2144 2145\subsection{\textcolor{Chapter }{FilenameGAP}} 2146\logpage{[ 4, 2, 3 ]}\nobreak 2147\hyperdef{L}{X81E67E4678FB6843}{} 2148{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FilenameGAP({\mdseries\slshape fname})\index{FilenameGAP@\texttt{FilenameGAP}} 2149\label{FilenameGAP} 2150}\hfill{\scriptsize (function)}}\\ 2151\textbf{\indent Returns:\ } 2152file name as string or fail 2153 2154 2155 2156 This functions returns the full path of a file with name \mbox{\texttt{\mdseries\slshape fname}} relative to a \textsf{GAP} root path, or \texttt{fail} if such a file does not exist. The argument \mbox{\texttt{\mdseries\slshape fname}} can optionally start with the prefix \texttt{"gap://"} which will be removed. 2157\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2158 !gapprompt@gap>| !gapinput@FilenameGAP("hsdkfhs.g");| 2159 fail 2160 !gapprompt@gap>| !gapinput@FilenameGAP("lib/system.g");| 2161 "/usr/local/gap4/lib/system.g" 2162 !gapprompt@gap>| !gapinput@FilenameGAP("gap://lib/system.g");| 2163 "/usr/local/gap4/lib/system.g" 2164\end{Verbatim} 2165 } 2166 2167 } 2168 2169 } 2170 2171 2172\chapter{\textcolor{Chapter }{The Converters and an XML Parser}}\label{ch:conv} 2173\logpage{[ 5, 0, 0 ]} 2174\hyperdef{L}{X845E7FDC7C082CC4}{} 2175{ 2176 The \textsf{GAPDoc} package contains a set of programs which allow us to convert a \textsf{GAPDoc} book into several output versions and to make them available to \textsf{GAP}'s online help. 2177 2178 Currently the following output formats are provided: text for browsing inside 2179a terminal running \textsf{GAP}, {\LaTeX} with \texttt{hyperref}-package for cross references via hyperlinks and HTML for reading with a 2180Web-browser. 2181 2182 2183\section{\textcolor{Chapter }{Producing Documentation from Source Files}}\label{MakeDoc} 2184\logpage{[ 5, 1, 0 ]} 2185\hyperdef{L}{X7D1BB5867C13FA14}{} 2186{ 2187 Here we explain how to use the functions which are described in more detail in 2188the following sections. We assume that we have the main file \texttt{MyBook.xml} of a book \texttt{"MyBook"} in the directory \texttt{/my/book/path}. This contains \texttt{{\textless}\#Include ...{\textgreater}}-statements as explained in Chapter{\nobreakspace}\ref{Distributing}. These refer to some other files as well as pieces of text which are found in 2189the comments of some \textsf{GAP} source files \texttt{../lib/a.gd} and \texttt{../lib/b.gi} (relative to the path above). A Bib{\TeX} database \texttt{MyBook.bib} for the citations is also in the directory given above. We want to produce a 2190text-, \texttt{pdf-} and HTML-version of the document. (A {\LaTeX} version of the manual is produced, so it is also easy to compile \texttt{dvi}-, and postscript-versions.) 2191 2192 All the commands shown in this Section are collected in the single function \texttt{MakeGAPDocDoc} (\ref{MakeGAPDocDoc}). 2193 2194 First we construct the complete XML-document as a string with \texttt{ComposedDocument} (\ref{ComposedDocument}). This interprets recursively the \texttt{{\textless}\#Include ...{\textgreater}}-statements. 2195\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2196 !gapprompt@gap>| !gapinput@path := Directory("/my/book/path");;| 2197 !gapprompt@gap>| !gapinput@main := "MyBook.xml";;| 2198 !gapprompt@gap>| !gapinput@files := ["../lib/a.gd", "../lib/b.gi"];;| 2199 !gapprompt@gap>| !gapinput@bookname := "MyBook";;| 2200 !gapprompt@gap>| !gapinput@doc := ComposedDocument("GAPDoc", path, main, files, true);;| 2201\end{Verbatim} 2202 Now \texttt{doc} is a list with two entries, the first is a string containing the XML-document, 2203the second gives information from which files and locations which part of the 2204document was collected. This is useful in the next step, if there are any 2205errors in the document. 2206 2207 Next we parse the document and store its structure in a tree-like data 2208structure. The commands for this are \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) and \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree}). 2209\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2210 !gapprompt@gap>| !gapinput@r := ParseTreeXMLString(doc[1], doc[2]);;| 2211 !gapprompt@gap>| !gapinput@CheckAndCleanGapDocTree(r);| 2212 true 2213\end{Verbatim} 2214 We start to produce a text version of the manual, which can be read in a 2215terminal (window). The command is \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). This produces a record with the actual text and some additional information. 2216The text can be written chapter-wise into files with \texttt{GAPDoc2TextPrintTextFiles} (\ref{GAPDoc2TextPrintTextFiles}). The names of these files are \texttt{chap0.txt}, \texttt{chap1.txt} and so on. The text contains some markup using ANSI escape sequences. This 2217markup is substituted by the \textsf{GAP} help system (user configurable) to show the text with colors and other 2218attributes. For the bibliography we have to tell \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}) the location of the Bib{\TeX} database by specifying a \texttt{path} as second argument. 2219\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2220 !gapprompt@gap>| !gapinput@t := GAPDoc2Text(r, path);;| 2221 !gapprompt@gap>| !gapinput@GAPDoc2TextPrintTextFiles(t, path);| 2222\end{Verbatim} 2223 This command constructs all parts of the document including table of contents, 2224bibliography and index. The functions \texttt{FormatParagraph} (\ref{FormatParagraph}) for formatting text paragraphs and \texttt{ParseBibFiles} (\ref{ParseBibFiles}) for reading Bib{\TeX} files with \textsf{GAP} may be of independent interest. 2225 2226 With the text version we have also produced the information which is used for 2227searching with \textsf{GAP}'s online help. Also, labels are produced which can be used by links in the 2228HTML- and \texttt{pdf}-versions of the manual. 2229 2230 Next we produce a {\LaTeX} version of the document. \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) returns a string containing the {\LaTeX} source. The utility function \texttt{FileString} (\ref{FileString}) writes the content of a string to a file, we choose \texttt{MyBook.tex}. 2231\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2232 !gapprompt@gap>| !gapinput@l := GAPDoc2LaTeX(r);;| 2233 !gapprompt@gap>| !gapinput@FileString(Filename(path, Concatenation(bookname, ".tex")), l);| 2234\end{Verbatim} 2235 Assuming that you have a sufficiently good installation of {\TeX} available (see \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) for details) this can be processed with a series of commands like in the 2236following example. 2237\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2238 cd /my/book/path 2239 pdflatex MyBook 2240 bibtex MyBook 2241 pdflatex MyBook 2242 makeindex MyBook 2243 pdflatex MyBook 2244 mv MyBook.pdf manual.pdf 2245\end{Verbatim} 2246 After this we have a \texttt{pdf}-version of the document in the file \texttt{manual.pdf}. It contains hyperlink information which can be used with appropriate 2247browsers for convenient reading of the document on screen (e.g., \texttt{xpdf} is nice because it allows remote calls to display named locations of the 2248document). Of course, we could also use other commands like \texttt{latex} or \texttt{dvips} to process the {\LaTeX} source file. Furthermore we have produced a file \texttt{MyBook.pnr} which is \textsf{GAP}-readable and contains the page number information for each (sub-)section of 2249the document. 2250 2251 We can add this page number information to the indexing information collected 2252by the text converter and then print a \texttt{manual.six} file which is read by \textsf{GAP} when the manual is loaded. This is done with \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}) and \texttt{PrintSixFile} (\ref{PrintSixFile}). 2253\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2254 !gapprompt@gap>| !gapinput@AddPageNumbersToSix(r, Filename(path, "MyBook.pnr"));| 2255 !gapprompt@gap>| !gapinput@PrintSixFile(Filename(path, "manual.six"), r, bookname);| 2256\end{Verbatim} 2257 Finally we produce an HTML-version of the document and write it (chapter-wise) 2258into files \texttt{chap0.html}, \texttt{chap1.html} and so on. They can be read with any Web-browser. The commands are \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) and \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}). We also add a link from \texttt{manual.html} to \texttt{chap0.html}. You probably want to copy stylesheet files into the same directory, see \ref{StyleSheets} for more details. The argument \texttt{path} of \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) specifies the directory containing the Bib{\TeX} database files. 2259\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2260 !gapprompt@gap>| !gapinput@h := GAPDoc2HTML(r, path);;| 2261 !gapprompt@gap>| !gapinput@GAPDoc2HTMLPrintHTMLFiles(h, path);| 2262\end{Verbatim} 2263 2264 2265\subsection{\textcolor{Chapter }{MakeGAPDocDoc}} 2266\logpage{[ 5, 1, 1 ]}\nobreak 2267\hyperdef{L}{X826F530686F4D052}{} 2268{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{MakeGAPDocDoc({\mdseries\slshape path, main, files, bookname[, gaproot][, ...]})\index{MakeGAPDocDoc@\texttt{MakeGAPDocDoc}} 2269\label{MakeGAPDocDoc} 2270}\hfill{\scriptsize (function)}}\\ 2271 2272 2273 This function collects all the commands for producing a text-, \texttt{pdf}- and HTML-version of a \textsf{GAPDoc} document as described in Section{\nobreakspace}\ref{MakeDoc}. It checks the \texttt{.log} file from the call of \texttt{pdflatex} and reports if there are errors, warnings or overfull boxes. 2274 2275 \emph{Note:} If this function works for you depends on your operating system and installed 2276software. It will probably work on most \texttt{UNIX} systems with a standard {\LaTeX} installation. If the function doesn't work for you look at the source code and 2277adjust it to your system. 2278 2279 Here \mbox{\texttt{\mdseries\slshape path}} must be the directory (as string or directory object) containing the main file \mbox{\texttt{\mdseries\slshape main}} of the document (given with or without the \texttt{.xml} extension. The argument \mbox{\texttt{\mdseries\slshape files}} is a list of (probably source code) files relative to \mbox{\texttt{\mdseries\slshape path}} which contain pieces of documentation which must be included in the document, 2280see Chapter{\nobreakspace}\ref{Distributing}. And \mbox{\texttt{\mdseries\slshape bookname}} is the name of the book used by \textsf{GAP}'s online help. The optional argument \mbox{\texttt{\mdseries\slshape gaproot}} must be a string which gives the relative path from \mbox{\texttt{\mdseries\slshape path}} to the main \textsf{GAP} root directory. If this is given, the HTML files are produced with relative 2281paths to external books. 2282 2283 If the string \texttt{"nopdf"} is given as optional argument then \texttt{MakeGAPDocDoc} will not produce a \texttt{pdf}-version of the help book (the source \texttt{.tex}-file is generated). Consequently, the index for the help system will not 2284contain page numbers for the \texttt{pdf}-version. This variant of \texttt{MakeGAPDocDoc} should work independently of the operating system because no external programs 2285are called. It is recommended that distributed manuals contain the \texttt{pdf}-version. 2286 2287 \index{MathJax@\textsf{MathJax}!in \texttt{MakeGAPDocDoc}} \texttt{MakeGAPDocDoc} can be called with additional arguments \texttt{"MathJax"}, \texttt{"Tth"} and/or \texttt{"MathML"}. If these are given additional variants of the HTML conversion are called, 2288see \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) for details. 2289 2290 It is possible to use \textsf{GAPDoc} with other languages than English, see \texttt{SetGapDocLanguage} (\ref{SetGapDocLanguage}) for more details. 2291 2292 } 2293 2294 } 2295 2296 2297\section{\textcolor{Chapter }{Parsing XML Documents}}\label{ParseXML} 2298\logpage{[ 5, 2, 0 ]} 2299\hyperdef{L}{X7FE2AF49838D9034}{} 2300{ 2301 Arbitrary well-formed XML documents can be parsed and browsed by the following 2302functions. 2303 2304\subsection{\textcolor{Chapter }{ParseTreeXMLString}} 2305\logpage{[ 5, 2, 1 ]}\nobreak 2306\hyperdef{L}{X847EB8498151D443}{} 2307{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseTreeXMLString({\mdseries\slshape str[, srcinfo][, entitydict]})\index{ParseTreeXMLString@\texttt{ParseTreeXMLString}} 2308\label{ParseTreeXMLString} 2309}\hfill{\scriptsize (function)}}\\ 2310\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseTreeXMLFile({\mdseries\slshape fname[, entitydict]})\index{ParseTreeXMLFile@\texttt{ParseTreeXMLFile}} 2311\label{ParseTreeXMLFile} 2312}\hfill{\scriptsize (function)}}\\ 2313\textbf{\indent Returns:\ } 2314a record which is root of a tree structure 2315 2316 2317 2318 The first function parses an XML-document stored in string \mbox{\texttt{\mdseries\slshape str}} and returns the document in form of a tree. 2319 2320 The optional argument \mbox{\texttt{\mdseries\slshape srcinfo}} must have the same format as in \texttt{OriginalPositionDocument} (\ref{OriginalPositionDocument}). If it is given then error messages refer to the original source of the text 2321with the problem. 2322 2323 With the optional argument \mbox{\texttt{\mdseries\slshape entitydict}} named entities can be given to the parser, for example entities which are 2324defined in the \texttt{.dtd}-file (which is not read by this parser). The standard XML-entities do not 2325need to be provided, and for \textsf{GAPDoc} documents the entity definitions from \texttt{gapdoc.dtd} are automatically provided. Entities in the document's \texttt{{\textless}!DOCTYPE} declaration are parsed and also need not to be provided here. The argument \mbox{\texttt{\mdseries\slshape entitydict}} must be a record where each component name is an entity name (without the 2326surrounding \& and ;) to which is assigned its substitution string. 2327 2328 The second function is just a shortcut for \texttt{ParseTreeXMLString( StringFile(}\mbox{\texttt{\mdseries\slshape fname}}\texttt{), ... )}, see \texttt{StringFile} (\ref{StringFile}). 2329 2330 After these functions return the list of named entities which were known 2331during the parsing can be found in the record \texttt{ENTITYDICT}. 2332 2333 A node in the result tree corresponds to an XML element, or to some parsed 2334character data. In the first case it looks as follows: 2335\begin{Verbatim}[fontsize=\small,frame=single,label=Example Node] 2336 rec( name := "Book", 2337 attributes := rec( Name := "EDIM" ), 2338 content := [ ... list of nodes for content ...], 2339 start := 312, 2340 stop := 15610, 2341 next := 15611 ) 2342\end{Verbatim} 2343 This means that \texttt{\mbox{\texttt{\mdseries\slshape str}}\texttt{\symbol{123}}[312..15610]\texttt{\symbol{125}}} looks like \texttt{{\textless}Book Name="EDIM"{\textgreater} ... content ... 2344{\textless}/Book{\textgreater}}. 2345 2346 The leaves of the tree encode parsed character data as in the following 2347example: 2348\begin{Verbatim}[fontsize=\small,frame=single,label=Example Node] 2349 rec( name := "PCDATA", 2350 content := "text without markup " ) 2351\end{Verbatim} 2352 This function checks whether the XML document is \emph{well formed}, see \ref{XMLvalid} for an explanation. If an error in the XML structure is found, a break loop is 2353entered and the text around the position where the problem starts is shown. 2354With \texttt{Show();} one can browse the original input in the \texttt{Pager} (\textbf{Reference: Pager}), starting with the line where the error occurred. All entities are resolved 2355when they are either entities defined in the \textsf{GAPDoc} package (in particular the standard XML entities) or if their definition is 2356included in the \texttt{{\textless}!DOCTYPE ..{\textgreater}} tag of the document. 2357 2358 Note that \texttt{ParseTreeXMLString} does not parse and interpret the corresponding document type definition (the \texttt{.dtd}-file given in the \texttt{{\textless}!DOCTYPE ..{\textgreater}} tag). Hence it also does not check the \emph{validity} of the document (i.e., it is no \emph{validating XML parser}). 2359 2360 If you are using this function to parse a \textsf{GAPDoc} document you can use \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree}) for some validation and additional checking of the document structure. } 2361 2362 2363 2364\subsection{\textcolor{Chapter }{StringXMLElement}} 2365\logpage{[ 5, 2, 2 ]}\nobreak 2366\hyperdef{L}{X835887057D0B4DA8}{} 2367{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringXMLElement({\mdseries\slshape tree})\index{StringXMLElement@\texttt{StringXMLElement}} 2368\label{StringXMLElement} 2369}\hfill{\scriptsize (function)}}\\ 2370\textbf{\indent Returns:\ } 2371a list \texttt{[string, positions]} 2372 2373 2374 2375 The argument \mbox{\texttt{\mdseries\slshape tree}} must have a format of a node in the parse tree of an XML document as returned 2376by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (including the root node representing the full document). This function 2377computes a pair \texttt{[string, positions]} where \texttt{string} contains XML code which is equivalent to the code which was parsed to get \mbox{\texttt{\mdseries\slshape tree}}. And \texttt{positions} is a list of lists of four numbers \texttt{[eltb, elte, contb, conte]}. There is one such list for each XML element occuring in \texttt{string}, where \texttt{eltb} and \texttt{elte} are the begin and end position of this element in \texttt{string} and where \texttt{contb} and \texttt{conte} are begin and end position of the content of this element, or both are \texttt{0} if there is no content. 2378 2379 Note that parsing XML code is an irreversible task, we can only expect to get 2380equivalent XML code from this function. But parsing the resulting \texttt{string} again and applying \texttt{StringXMLElement} again gives the same result. See the function \texttt{EntitySubstitution} (\ref{EntitySubstitution}) for back-substitutions of entities in the result. } 2381 2382 2383 2384\subsection{\textcolor{Chapter }{EntitySubstitution}} 2385\logpage{[ 5, 2, 3 ]}\nobreak 2386\hyperdef{L}{X786827BF793191B3}{} 2387{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{EntitySubstitution({\mdseries\slshape xmlstring, entities})\index{EntitySubstitution@\texttt{EntitySubstitution}} 2388\label{EntitySubstitution} 2389}\hfill{\scriptsize (function)}}\\ 2390\textbf{\indent Returns:\ } 2391a string 2392 2393 2394 2395 The argument \mbox{\texttt{\mdseries\slshape xmlstring}} must be a string containing XML code or a pair \texttt{[string, positions]} as returned by \texttt{StringXMLElement} (\ref{StringXMLElement}). The argument \mbox{\texttt{\mdseries\slshape entities}} specifies entity names (without the surrounding \mbox{\texttt{\mdseries\slshape \&}} and \texttt{;}) and their substitution strings, either a list of pairs of strings or as a 2396record with the names as components and the substitutions as values. 2397 2398 This function tries to substitute non-intersecting parts of \texttt{string} by the given entities. If the \texttt{positions} information is given then only parts of the document which allow a valid 2399substitution by an entity are considered. Otherwise a simple text substitution 2400without further check is done. 2401 2402 Note that in general the entity resolution in XML documents is a complicated 2403and non-reversible task. But nevertheless this utility may be useful in not 2404too complicated situations. } 2405 2406 2407 2408\subsection{\textcolor{Chapter }{DisplayXMLStructure}} 2409\logpage{[ 5, 2, 4 ]}\nobreak 2410\hyperdef{L}{X86589C5C859ACE38}{} 2411{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DisplayXMLStructure({\mdseries\slshape tree})\index{DisplayXMLStructure@\texttt{DisplayXMLStructure}} 2412\label{DisplayXMLStructure} 2413}\hfill{\scriptsize (function)}}\\ 2414 2415 2416 This utility displays the tree structure of an XML document as it is returned 2417by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (without the \texttt{PCDATA} leaves). 2418 2419 Since this is usually quite long the result is shown using the \texttt{Pager} (\textbf{Reference: Pager}). } 2420 2421 2422 2423\subsection{\textcolor{Chapter }{ApplyToNodesParseTree}} 2424\logpage{[ 5, 2, 5 ]}\nobreak 2425\hyperdef{L}{X7A7B223A83E38B40}{} 2426{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ApplyToNodesParseTree({\mdseries\slshape tree, fun})\index{ApplyToNodesParseTree@\texttt{ApplyToNodesParseTree}} 2427\label{ApplyToNodesParseTree} 2428}\hfill{\scriptsize (function)}}\\ 2429\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AddRootParseTree({\mdseries\slshape tree})\index{AddRootParseTree@\texttt{AddRootParseTree}} 2430\label{AddRootParseTree} 2431}\hfill{\scriptsize (function)}}\\ 2432\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RemoveRootParseTree({\mdseries\slshape tree})\index{RemoveRootParseTree@\texttt{RemoveRootParseTree}} 2433\label{RemoveRootParseTree} 2434}\hfill{\scriptsize (function)}}\\ 2435 2436 2437 The function \texttt{ApplyToNodesParseTree} applies a function \mbox{\texttt{\mdseries\slshape fun}} to all nodes of the parse tree \mbox{\texttt{\mdseries\slshape tree}} of an XML document returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}). 2438 2439 The function \texttt{AddRootParseTree} is an application of this. It adds to all nodes a component \texttt{.root} to which the top node tree \mbox{\texttt{\mdseries\slshape tree}} is assigned. These components can be removed afterwards with \texttt{RemoveRootParseTree}. } 2440 2441 Here are two more utilities which use \texttt{ApplyToNodesParseTree} (\ref{ApplyToNodesParseTree}). 2442 2443\subsection{\textcolor{Chapter }{GetTextXMLTree}} 2444\logpage{[ 5, 2, 6 ]}\nobreak 2445\hyperdef{L}{X7F76D4A27C7FB946}{} 2446{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GetTextXMLTree({\mdseries\slshape tree})\index{GetTextXMLTree@\texttt{GetTextXMLTree}} 2447\label{GetTextXMLTree} 2448}\hfill{\scriptsize (function)}}\\ 2449\textbf{\indent Returns:\ } 2450a string 2451 2452 2453 2454 The argument \mbox{\texttt{\mdseries\slshape tree}} must be a node of a parse tree of some XML document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). This function collects the content of this and all included elements 2455recursively into a string. } 2456 2457 2458 2459\subsection{\textcolor{Chapter }{XMLElements}} 2460\logpage{[ 5, 2, 7 ]}\nobreak 2461\hyperdef{L}{X8466F74C80442F7D}{} 2462{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{XMLElements({\mdseries\slshape tree, eltnames})\index{XMLElements@\texttt{XMLElements}} 2463\label{XMLElements} 2464}\hfill{\scriptsize (function)}}\\ 2465\textbf{\indent Returns:\ } 2466a list of nodes 2467 2468 2469 2470 The argument \mbox{\texttt{\mdseries\slshape tree}} must be a node of a parse tree of some XML document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). This function returns a list of all subnodes of \mbox{\texttt{\mdseries\slshape tree}} (possibly including \mbox{\texttt{\mdseries\slshape tree}}) of elements with name given in the list of strings \mbox{\texttt{\mdseries\slshape eltnames}}. Use \texttt{"PCDATA"} as name for leave nodes which contain the actual text of the document. As an 2471abbreviation \mbox{\texttt{\mdseries\slshape eltnames}} can also be a string which is then put in a one element list. } 2472 2473 And here are utilities for processing \textsf{GAPDoc} XML documents. 2474 2475\subsection{\textcolor{Chapter }{CheckAndCleanGapDocTree}} 2476\logpage{[ 5, 2, 8 ]}\nobreak 2477\hyperdef{L}{X84CFF72484B19C0D}{} 2478{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CheckAndCleanGapDocTree({\mdseries\slshape tree})\index{CheckAndCleanGapDocTree@\texttt{CheckAndCleanGapDocTree}} 2479\label{CheckAndCleanGapDocTree} 2480}\hfill{\scriptsize (function)}}\\ 2481\textbf{\indent Returns:\ } 2482nothing 2483 2484 2485 2486 The argument \mbox{\texttt{\mdseries\slshape tree}} of this function is a parse tree from \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) of some \textsf{GAPDoc} document. This function does an (incomplete) validity check of the document 2487according to the document type declaration in \texttt{gapdoc.dtd}. It also does some additional checks which cannot be described in the DTD 2488(like checking whether chapters and sections have a heading). For elements 2489with element content the whitespace between these elements is removed. 2490 2491 In case of an error the break loop is entered and the position of the error in 2492the original XML document is printed. With \texttt{Show();} one can browse the original input in the \texttt{Pager} (\textbf{Reference: Pager}). } 2493 2494 2495 2496\subsection{\textcolor{Chapter }{AddParagraphNumbersGapDocTree}} 2497\logpage{[ 5, 2, 9 ]}\nobreak 2498\hyperdef{L}{X84062CD67B286FF0}{} 2499{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AddParagraphNumbersGapDocTree({\mdseries\slshape tree})\index{AddParagraphNumbersGapDocTree@\texttt{AddParagraphNumbersGapDocTree}} 2500\label{AddParagraphNumbersGapDocTree} 2501}\hfill{\scriptsize (function)}}\\ 2502\textbf{\indent Returns:\ } 2503nothing 2504 2505 2506 2507 The argument \mbox{\texttt{\mdseries\slshape tree}} must be an XML tree returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) applied to a \textsf{GAPDoc} document. This function adds to each node of the tree a component \texttt{.count} which is of form \texttt{[Chapter[, Section[, Subsection, Paragraph] ] ]}. Here the first three numbers should be the same as produced by the {\LaTeX} version of the document. Text before the first chapter is counted as chapter \texttt{0} and similarly for sections and subsections. Some elements are always 2508considered to start a new paragraph. } 2509 2510 2511 2512\subsection{\textcolor{Chapter }{InfoXMLParser}} 2513\logpage{[ 5, 2, 10 ]}\nobreak 2514\hyperdef{L}{X78A22C58841E5D0B}{} 2515{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InfoXMLParser\index{InfoXMLParser@\texttt{InfoXMLParser}} 2516\label{InfoXMLParser} 2517}\hfill{\scriptsize (info class)}}\\ 2518 2519 2520 The default level of this info class is 1. Functions like \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) are then printing some information, in particular in case of errors. You can 2521suppress it by setting the level of \texttt{InfoXMLParser} to 0. With level 2 there may be some more information for debugging purposes. } 2522 2523 } 2524 2525 2526\section{\textcolor{Chapter }{The Converters}}\label{Converters} 2527\logpage{[ 5, 3, 0 ]} 2528\hyperdef{L}{X8560E1A2845EC2C1}{} 2529{ 2530 Here are more details about the conversion programs for \textsf{GAPDoc} XML documents. 2531 2532\subsection{\textcolor{Chapter }{GAPDoc2LaTeX}} 2533\logpage{[ 5, 3, 1 ]}\nobreak 2534\hyperdef{L}{X85BE6DF178423EF5}{} 2535{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2LaTeX({\mdseries\slshape tree})\index{GAPDoc2LaTeX@\texttt{GAPDoc2LaTeX}} 2536\label{GAPDoc2LaTeX} 2537}\hfill{\scriptsize (function)}}\\ 2538\textbf{\indent Returns:\ } 2539{\LaTeX} document as string 2540 2541\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SetGapDocLaTeXOptions({\mdseries\slshape [...]})\index{SetGapDocLaTeXOptions@\texttt{SetGapDocLaTeXOptions}} 2542\label{SetGapDocLaTeXOptions} 2543}\hfill{\scriptsize (function)}}\\ 2544\textbf{\indent Returns:\ } 2545Nothing 2546 2547 2548 2549 The argument \mbox{\texttt{\mdseries\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). The output is a string containing a version of the document which can be 2550written to a file and processed with {\LaTeX} or pdf{\LaTeX} (and probably Bib{\TeX} and \texttt{makeindex}). 2551 2552 The output uses the \texttt{report} document class and needs the following {\LaTeX} packages: \texttt{amssymb}, \texttt{inputenc}, \texttt{makeidx}, \texttt{color}, \texttt{fancyvrb}, \texttt{psnfss}, \texttt{pslatex}, \texttt{enumitem} and \texttt{hyperref}. These are for example provided by the \textsf{teTeX-1.0} or \textsf{texlive} distributions of {\TeX} (which in turn are used for most {\TeX} packages of current Linux distributions); see \href{http://www.tug.org/tetex/} {\texttt{http://www.tug.org/tetex/}}. 2553 2554 In particular, the resulting \texttt{pdf}-output (and \texttt{dvi}-output) contains (internal and external) hyperlinks which can be very useful 2555for onscreen browsing of the document. 2556 2557 The {\LaTeX} processing also produces a file with extension \texttt{.pnr} which is \textsf{GAP} readable and contains the page numbers for all (sub)sections of the document. 2558This can be used by \textsf{GAP}'s online help; see \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}). Non-ASCII characters in the \textsf{GAPDoc} document are translated to {\LaTeX} input in ASCII-encoding with the help of \texttt{Encode} (\ref{Encode}) and the option \texttt{"LaTeX"}. See the documentation of \texttt{Encode} (\ref{Encode}) for how to proceed if you have a character which is not handled (yet). 2559 2560 This function works by running recursively through the document tree and 2561calling a handler function for each \textsf{GAPDoc} XML element. Many of these handler functions (usually in \texttt{GAPDoc2LaTeXProcs.{\textless}ElementName{\textgreater}}) are not difficult to understand (the greatest complications are some 2562commands for index entries, labels or the output of page number information). 2563So it should be easy to adjust layout details to your own taste by slight 2564modifications of the program. 2565 2566 Former versions of \textsf{GAPDoc} supported some XML processing instructions to add some extra lines to the 2567preamble of the {\LaTeX} document. Its use is now deprecated, use the much more flexible \texttt{SetGapDocLaTeXOptions} instead: The default layout of the resulting documents can be changed with \texttt{SetGapDocLaTeXOptions}. This changes parts of the header of the {\LaTeX} file produced by \textsf{GAPDoc}. You can see the header with some placeholders by \texttt{Page(GAPDoc2LaTeXProcs.Head);}. The placeholders are filled with components from the record \texttt{GAPDoc2LaTeXProcs.DefaultOptions}. The arguments of \texttt{SetGapDocLaTeXOptions} can be records with the same structure (or parts of it) with different values. 2568As abbreviations there are also three strings supported as arguments. These 2569are \texttt{"nocolor"} for switching all colors to black; then \texttt{"nopslatex"} to use standard {\LaTeX} fonts instead of postscript fonts; and finally \texttt{"utf8"} to choose UTF-8 as input encoding for the {\LaTeX} document. } 2570 2571 2572 2573\subsection{\textcolor{Chapter }{GAPDoc2Text}} 2574\logpage{[ 5, 3, 2 ]}\nobreak 2575\hyperdef{L}{X86CD0B197CD58D2A}{} 2576{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2Text({\mdseries\slshape tree[, bibpath][, width]})\index{GAPDoc2Text@\texttt{GAPDoc2Text}} 2577\label{GAPDoc2Text} 2578}\hfill{\scriptsize (function)}}\\ 2579\textbf{\indent Returns:\ } 2580record containing text files as strings and other information 2581 2582 2583 2584 The argument \mbox{\texttt{\mdseries\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). This function produces a text version of the document which can be used 2585with \textsf{GAP}'s online help (with the \texttt{"screen"} viewer, see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer})). It includes title page, bibliography and index. The bibliography is made 2586from BibXMLext or Bib{\TeX} databases, see \ref{ch:bibutil}. Their location must be given with the argument \mbox{\texttt{\mdseries\slshape bibpath}} (as string or directory object). 2587 2588 The output is a record with one component for each chapter (with names \texttt{"0"}, \texttt{"1"}, ..., \texttt{"Bib"} and \texttt{"Ind"}). Each such component is again a record with the following components: 2589\begin{description} 2590\item[{\texttt{text}}] the text of the whole chapter as a string 2591\item[{\texttt{ssnr}}] list of subsection numbers in this chapter (like \texttt{[3, 2, 1]} for chapter{\nobreakspace}3, section{\nobreakspace}2, 2592subsection{\nobreakspace}1) 2593\item[{\texttt{linenr}}] corresponding list of line numbers where the subsections start 2594\item[{\texttt{len}}] number of lines of this chapter 2595\end{description} 2596 The result can be written into files with the command \texttt{GAPDoc2TextPrintTextFiles} (\ref{GAPDoc2TextPrintTextFiles}). 2597 2598 As a side effect this function also produces the \texttt{manual.six} information which is used for searching in \textsf{GAP}'s online help. This is stored in \texttt{\mbox{\texttt{\mdseries\slshape tree}}.six} and can be printed into a \texttt{manual.six} file with \texttt{PrintSixFile} (\ref{PrintSixFile}) (preferably after producing a {\LaTeX} version of the document as well and adding the page number information to \texttt{\mbox{\texttt{\mdseries\slshape tree}}.six}, see \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) and \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix})). 2599 2600 The text produced by this function contains some markup via ANSI escape 2601sequences. The sequences used here are usually ignored by terminals. But the \textsf{GAP} help system will substitute them by interpreted color and attribute sequences 2602(see \texttt{TextAttr} (\ref{TextAttr})) before displaying them. There is a default markup used for this but it can 2603also be configured by the user, see \texttt{SetGAPDocTextTheme} (\ref{SetGAPDocTextTheme}). Furthermore, the text produced is in UTF-8 encoding. The encoding is also 2604translated on the fly, if \texttt{GAPInfo.TermEncoding} is set to some encoding supported by \texttt{Encode} (\ref{Encode}), e.g., \texttt{"ISO-8859-1"} or \texttt{"latin1"}. 2605 2606 With the optional argument \mbox{\texttt{\mdseries\slshape width}} a different length of the output text lines can be chosen. The default is 76 2607and all lines in the resulting text start with two spaces. This looks good on 2608a terminal with a standard width of 80 characters and you probably don't want 2609to use this argument. } 2610 2611 2612 2613\subsection{\textcolor{Chapter }{GAPDoc2TextPrintTextFiles}} 2614\logpage{[ 5, 3, 3 ]}\nobreak 2615\hyperdef{L}{X7DFCE7357D6032A2}{} 2616{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2TextPrintTextFiles({\mdseries\slshape t[, path]})\index{GAPDoc2TextPrintTextFiles@\texttt{GAPDoc2TextPrintTextFiles}} 2617\label{GAPDoc2TextPrintTextFiles} 2618}\hfill{\scriptsize (function)}}\\ 2619\textbf{\indent Returns:\ } 2620nothing 2621 2622 2623 2624 The first argument must be a result returned by \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). The second argument is a path for the files to write, it can be given as 2625string or directory object. The text of each chapter is written into a 2626separate file with name \texttt{chap0.txt}, \texttt{chap1.txt}, ..., \texttt{chapBib.txt}, and \texttt{chapInd.txt}. 2627 2628 If you want to make your document accessible via the \textsf{GAP} online help you must put at least these files for the text version into a 2629directory, together with the file \texttt{manual.six}, see \texttt{PrintSixFile} (\ref{PrintSixFile}). Then specify the path to the \texttt{manual.six} file in the packages \texttt{PackageInfo.g} file, see (\textbf{Reference: The PackageInfo.g File}). 2630 2631 Optionally you can add the \texttt{dvi}- and \texttt{pdf}-versions of the document which are produced with \texttt{GAPDoc2LaTeX} (\ref{GAPDoc2LaTeX}) to this directory. The files must have the names \texttt{manual.dvi} and \texttt{manual.pdf}, respectively. Also you can add the files of the HTML version produced with \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}) to this directory, see \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}). The handler functions in \textsf{GAP} for this help format detect automatically which of the optional formats of a 2632book are actually available. } 2633 2634 2635 2636\subsection{\textcolor{Chapter }{AddPageNumbersToSix}} 2637\logpage{[ 5, 3, 4 ]}\nobreak 2638\hyperdef{L}{X7EB5E86F87A09F94}{} 2639{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AddPageNumbersToSix({\mdseries\slshape tree, pnrfile})\index{AddPageNumbersToSix@\texttt{AddPageNumbersToSix}} 2640\label{AddPageNumbersToSix} 2641}\hfill{\scriptsize (function)}}\\ 2642\textbf{\indent Returns:\ } 2643nothing 2644 2645 2646 2647 Here \mbox{\texttt{\mdseries\slshape tree}} must be the XML tree of a \textsf{GAPDoc} document, returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}). Running \texttt{latex} on the result of \texttt{GAPDoc2LaTeX(\mbox{\texttt{\mdseries\slshape tree}})} produces a file \mbox{\texttt{\mdseries\slshape pnrfile}} (with extension \texttt{.pnr}). The command \texttt{GAPDoc2Text(\mbox{\texttt{\mdseries\slshape tree}})} creates a component \texttt{\mbox{\texttt{\mdseries\slshape tree}}.six} which contains all information about the document for the \textsf{GAP} online help, except the page numbers in the \texttt{.dvi, .ps, .pdf} versions of the document. This command adds the missing page number 2648information to \texttt{\mbox{\texttt{\mdseries\slshape tree}}.six}. } 2649 2650 2651 2652\subsection{\textcolor{Chapter }{PrintSixFile}} 2653\logpage{[ 5, 3, 5 ]}\nobreak 2654\hyperdef{L}{X7D42CFED7885BC00}{} 2655{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrintSixFile({\mdseries\slshape tree, bookname, fname})\index{PrintSixFile@\texttt{PrintSixFile}} 2656\label{PrintSixFile} 2657}\hfill{\scriptsize (function)}}\\ 2658\textbf{\indent Returns:\ } 2659nothing 2660 2661 2662 2663 This function prints the \texttt{.six} file \mbox{\texttt{\mdseries\slshape fname}} for a \textsf{GAPDoc} document stored in \mbox{\texttt{\mdseries\slshape tree}} with name \mbox{\texttt{\mdseries\slshape bookname}}. Such a file contains all information about the book which is needed by the \textsf{GAP} online help. This information must first be created by calls of \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}) and \texttt{AddPageNumbersToSix} (\ref{AddPageNumbersToSix}). } 2664 2665 2666 2667\subsection{\textcolor{Chapter }{SetGAPDocTextTheme}} 2668\logpage{[ 5, 3, 6 ]}\nobreak 2669\hyperdef{L}{X7DEB37417BBD8941}{} 2670{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SetGAPDocTextTheme({\mdseries\slshape [optrec1[, optrec2], ...]})\index{SetGAPDocTextTheme@\texttt{SetGAPDocTextTheme}} 2671\label{SetGAPDocTextTheme} 2672}\hfill{\scriptsize (function)}}\\ 2673\textbf{\indent Returns:\ } 2674nothing 2675 2676 2677 2678 This utility function is for readers of the screen version of \textsf{GAP} manuals which are generated by the \textsf{GAPDoc} package. It allows to configure the color and attribute layout of the 2679displayed text. There is a default which can be reset by calling this function 2680without argument. 2681 2682 As an abbreviation the arguments \mbox{\texttt{\mdseries\slshape optrec1}} and so on can be strings for the known name of a theme. Information about 2683valid names is shown with \texttt{SetGAPDocTextTheme("");}. 2684 2685 Otherwise, \mbox{\texttt{\mdseries\slshape optrec1}} and so on must be a record. Its entries overwrite the corresponding entries in 2686the default and in previous arguments. To construct valid markup you can use \texttt{TextAttr} (\ref{TextAttr}). Entries must be either pairs of strings, which are put before and after the 2687corresponding text, or as an abbreviation it can be a single string. In the 2688latter case, the second string is implied; if the string contains an escape 2689sequence the second string is \texttt{TextAttr.reset}, otherwise the given string is used. The following components are recognized: 2690\begin{description} 2691\item[{\texttt{flush}}] \texttt{"both"} for left-right justified paragraphs, and \texttt{"left"} for ragged right ones 2692\item[{\texttt{Heading}}] chapter and (sub-)section headings 2693\item[{\texttt{Func}}] function, operation, ... names 2694\item[{\texttt{Arg}}] argument names in descriptions 2695\item[{\texttt{Example}}] example code 2696\item[{\texttt{Package}}] package names 2697\item[{\texttt{Returns}}] Returns-line in descriptions 2698\item[{\texttt{URL}}] URLs 2699\item[{\texttt{Mark}}] Marks in description lists 2700\item[{\texttt{K}}] \textsf{GAP} keywords 2701\item[{\texttt{C}}] code or text to type 2702\item[{\texttt{F}}] file names 2703\item[{\texttt{B}}] buttons 2704\item[{\texttt{M}}] simplified math elements 2705\item[{\texttt{Math}}] normal math elements 2706\item[{\texttt{Display}}] displayed math elements 2707\item[{\texttt{Emph}}] emphasized text 2708\item[{\texttt{Q}}] quoted text 2709\item[{\texttt{Ref}}] reference text 2710\item[{\texttt{Prompt}}] \textsf{GAP} prompt in examples 2711\item[{\texttt{BrkPrompt}}] \textsf{GAP} break prompt in examples 2712\item[{\texttt{GAPInput}}] \textsf{GAP} input in examples 2713\item[{\texttt{reset}}] reset to default, don't change this 2714\item[{\texttt{BibAuthor}}] author names in bibliography 2715\item[{\texttt{BibTitle}}] titles in bibliography 2716\item[{\texttt{BibJournal}}] journal names in bibliography 2717\item[{\texttt{BibVolume}}] volume number in bibliography 2718\item[{\texttt{BibLabel}}] labels for bibliography entries 2719\item[{\texttt{BibReset}}] reset for bibliography, don't change 2720\item[{\texttt{ListBullet}}] bullet for simple lists (2 visible characters long) 2721\item[{\texttt{EnumMarks}}] one visible character before and after the number in enumerated lists 2722\item[{\texttt{DefLineMarker}}] marker before function and variable definitions (2 visible characters long) 2723\item[{\texttt{FillString}}] for filling in definitions and example separator lines 2724\end{description} 2725 2726\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2727 !gapprompt@gap>| !gapinput@# use no colors for GAP examples and | 2728 !gapprompt@gap>| !gapinput@# change display of headings to bold green| 2729 !gapprompt@gap>| !gapinput@SetGAPDocTextTheme("noColorPrompt", | 2730 !gapprompt@>| !gapinput@ rec(Heading:=Concatenation(TextAttr.bold, TextAttr.2)));| 2731\end{Verbatim} 2732 } 2733 2734 2735 2736\subsection{\textcolor{Chapter }{GAPDoc2HTML}} 2737\logpage{[ 5, 3, 7 ]}\nobreak 2738\hyperdef{L}{X84F22EEB78845CFD}{} 2739{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2HTML({\mdseries\slshape tree[, bibpath[, gaproot]][, mtrans]})\index{GAPDoc2HTML@\texttt{GAPDoc2HTML}} 2740\label{GAPDoc2HTML} 2741}\hfill{\scriptsize (function)}}\\ 2742\textbf{\indent Returns:\ } 2743record containing HTML files as strings and other information 2744 2745 2746 2747 \index{MathJax@\textsf{MathJax}} The argument \mbox{\texttt{\mdseries\slshape tree}} for this function is a tree describing a \textsf{GAPDoc} XML document as returned by \texttt{ParseTreeXMLString} (\ref{ParseTreeXMLString}) (probably also checked with \texttt{CheckAndCleanGapDocTree} (\ref{CheckAndCleanGapDocTree})). Without an \mbox{\texttt{\mdseries\slshape mtrans}} argument this function produces an HTML version of the document which can be 2748read with any Web-browser and also be used with \textsf{GAP}'s online help (see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer})). It includes title page, bibliography, and index. The bibliography is made 2749from Bib{\TeX} databases. Their location must be given with the argument \mbox{\texttt{\mdseries\slshape bibpath}} (as string or directory object, if not given the current directory is used). 2750If the third argument \mbox{\texttt{\mdseries\slshape gaproot}} is given and is a string then this string is interpreted as relative path to \textsf{GAP}'s main root directory. Reference-URLs to external HTML-books which begin with 2751the \textsf{GAP} root path are then rewritten to start with the given relative path. This makes 2752the HTML-documentation portable provided a package is installed in some 2753standard location below the \textsf{GAP} root. 2754 2755 The output is a record with one component for each chapter (with names \texttt{"0"}, \texttt{"1"}, ..., \texttt{"Bib"}, and \texttt{"Ind"}). Each such component is again a record with the following components: 2756\begin{description} 2757\item[{\texttt{text}}] the text of an HTML file containing the whole chapter (as a string) 2758\item[{\texttt{ssnr}}] list of subsection numbers in this chapter (like \texttt{[3, 2, 1]} for chapter{\nobreakspace}3, section{\nobreakspace}2, 2759subsection{\nobreakspace}1) 2760\end{description} 2761 \emph{Standard output format without} \mbox{\texttt{\mdseries\slshape mtrans}} \emph{argument} 2762 2763 The HTML code produced with this converter conforms to the W3C specification ``XHTML 1.0 strict'', see \href{http://www.w3.org/TR/xhtml1} {\texttt{http://www.w3.org/TR/xhtml1}}. First, this means that the HTML files are valid XML files. Secondly, the 2764extension ``strict'' says in particular that the code doesn't contain any explicit font or color 2765information. 2766 2767 Mathematical formulae are handled as in the text converter \texttt{GAPDoc2Text} (\ref{GAPDoc2Text}). We don't want to assume that the browser can use symbol fonts. Some \textsf{GAP} users like to browse the online help with \texttt{lynx}, see \texttt{SetHelpViewer} (\textbf{Reference: SetHelpViewer}), which runs inside the same terminal windows as \textsf{GAP}. 2768 2769 To view the generated files in graphical browsers, stylesheet files with 2770layout configuration should be copied into the directory with the generated 2771HTML files, see \ref{StyleSheets}. 2772 2773 \label{mtransarg} \emph{Output format with} \mbox{\texttt{\mdseries\slshape mtrans}} argument 2774 2775 Currently, there are three variants of this converter available which handle 2776mathematical formulae differently. They are accessed via the optional last \mbox{\texttt{\mdseries\slshape mtrans}} argument. 2777 2778 If \mbox{\texttt{\mdseries\slshape mtrans}} is set to \texttt{"MathJax"} the formulae are essentially translated as for {\LaTeX} documents (there is no processing of \texttt{{\textless}M{\textgreater}} elements as decribed in \ref{M}). Inline formulae are delimited by \texttt{\texttt{\symbol{92}}(} and \texttt{\texttt{\symbol{92}})} and displayed formulae by \texttt{\texttt{\symbol{92}}[} and \texttt{\texttt{\symbol{92}}]}. With \textsf{MathJax} webpages can contain nicely formatted scalable and searchable formulae. The 2779resulting files link by default to \href{http://cdn.mathjax.org} {http://cdn.mathjax.org} to get the \textsf{MathJax} script and fonts. This means that they can only be used on computers with 2780internet access. An alternative URL can be set by overwriting \texttt{GAPDoc2HTMLProcs.MathJaxURL} before building the HTML version of a manual. This way a local installation of \textsf{MathJax} could be used. See \href{http://www.mathjax.org/} {http://www.mathjax.org/} for more details. 2781 2782 The following possibilities for \mbox{\texttt{\mdseries\slshape mtrans}} are still supported, but since the \textsf{MathJax} approach seems much better, their use is deprecated. 2783 2784 If the argument \mbox{\texttt{\mdseries\slshape mtrans}} is set to \texttt{"Tth"} it is assumed that you have installed the {\LaTeX} to HTML translation program \texttt{tth}. This is used to translate the contents of the \texttt{M}, \texttt{Math} and \texttt{Display} elements into HTML code. Note that the resulting code is not compliant with 2785any standard. Formally it is ``XHTML 1.0 Transitional'', it contains explicit font specifications and the characters of mathematical 2786symbols are included via their position in a ``Symbol'' font. Some graphical browsers can be configured to display this in a useful 2787manner, check \href{http://hutchinson.belmont.ma.us/tth/} {the Tth homepage} for more details. 2788 2789 This function works by running recursively through the document tree and 2790calling a handler function for each \textsf{GAPDoc} XML element. Many of these handler functions (usually in \texttt{GAPDoc2TextProcs.{\textless}ElementName{\textgreater}}) are not difficult to understand (the greatest complications are some 2791commands for index entries, labels or the output of page number information). 2792So it should be easy to adjust certain details to your own taste by slight 2793modifications of the program. 2794 2795 The result of this converter can be written to files with the command \texttt{GAPDoc2HTMLPrintHTMLFiles} (\ref{GAPDoc2HTMLPrintHTMLFiles}). 2796 2797 There are two user preferences for reading the HTML manuals produced by \textsf{GAPDoc}. A user can choose among several style files which determine the appearance 2798of the manual pages with \texttt{SetUserPreference("GAPDoc", "HTMLStyle", [...]);} where the list in the third argument are arguments for \texttt{SetGAPDocHTMLStyle} (\ref{SetGAPDocHTMLStyle}). The second preference is set by \texttt{SetUserPreference("GAPDoc", "UseMathJax", ...);} where the third argument is \texttt{true} or \texttt{false} (default). If this is set to \texttt{true}, the \textsf{GAP} help system displays the \textsf{MathJax} version of the HTML manuals. } 2799 2800 2801 2802\subsection{\textcolor{Chapter }{GAPDoc2HTMLPrintHTMLFiles}} 2803\logpage{[ 5, 3, 8 ]}\nobreak 2804\hyperdef{L}{X84A7007778073E7A}{} 2805{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GAPDoc2HTMLPrintHTMLFiles({\mdseries\slshape t[, path]})\index{GAPDoc2HTMLPrintHTMLFiles@\texttt{GAPDoc2HTMLPrintHTMLFiles}} 2806\label{GAPDoc2HTMLPrintHTMLFiles} 2807}\hfill{\scriptsize (function)}}\\ 2808\textbf{\indent Returns:\ } 2809nothing 2810 2811 2812 2813 The first argument must be a result returned by \texttt{GAPDoc2HTML} (\ref{GAPDoc2HTML}). The second argument is a path for the files to write, it can be given as 2814string or directory object. The text of each chapter is written into a 2815separate file with name \texttt{chap0.html}, \texttt{chap1.html}, ..., \texttt{chapBib.html}, and \texttt{chapInd.html}. 2816 2817 The \textsf{MathJax} versions are written to files \texttt{chap0{\textunderscore}mj.html}, ..., \texttt{chapInd{\textunderscore}mj.html}. 2818 2819 The experimental version which is produced with \texttt{tth} uses different names for the files, namely \texttt{chap0{\textunderscore}sym.html}, and so on for files which need symbol fonts. 2820 2821 You should also add stylesheet files to the directory with the HTML files, see \ref{StyleSheets}. } 2822 2823 2824\subsection{\textcolor{Chapter }{Stylesheet files}}\label{StyleSheets} 2825\logpage{[ 5, 3, 9 ]} 2826\hyperdef{L}{X788AB14383272FDB}{} 2827{ 2828 \index{CSS stylesheets} For graphical browsers the layout of the generated HTML manuals can be highly 2829configured by cascading stylesheet (CSS) and javascript files. Such files are 2830provided in the \texttt{styles} directory of the \textsf{GAPDoc} package. 2831 2832 We recommend that these files are copied into each manual directory (such that 2833each of them is selfcontained). There is a utility function \texttt{CopyHTMLStyleFiles} (\ref{CopyHTMLStyleFiles}) which does this. Of course, these files may be changed or new styles may be 2834added. New styles may also be sent to the \textsf{GAPDoc} authors for possible inclusion in future versions. 2835 2836 The generated HTML files refer to the file \texttt{manual.css} which conforms to the W3C specification CSS 2.0, see \href{http://www.w3.org/TR/REC-CSS2} {\texttt{http://www.w3.org/TR/REC-CSS2}}, and the javascript file \texttt{manual.js} (only in browsers which support CSS or javascript, respectively; but the HTML 2837files are also readable without any of them). To add a style \texttt{mystyle} one or both of \texttt{mystyle.css} and \texttt{mystyle.js} must be provided; these can overwrite default settings and add new javascript 2838functions. For more details see the comments in \texttt{manual.js}. 2839 2840 } 2841 2842 2843 2844\subsection{\textcolor{Chapter }{CopyHTMLStyleFiles}} 2845\logpage{[ 5, 3, 10 ]}\nobreak 2846\hyperdef{L}{X813599E982DE9B98}{} 2847{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CopyHTMLStyleFiles({\mdseries\slshape dir})\index{CopyHTMLStyleFiles@\texttt{CopyHTMLStyleFiles}} 2848\label{CopyHTMLStyleFiles} 2849}\hfill{\scriptsize (function)}}\\ 2850\textbf{\indent Returns:\ } 2851nothing 2852 2853 2854 2855 This utility function copies the \texttt{*.css} and \texttt{*.js} files from the \texttt{styles} directory of the \textsf{GAPDoc} package into the directory \mbox{\texttt{\mdseries\slshape dir}}. } 2856 2857 2858 2859\subsection{\textcolor{Chapter }{SetGAPDocHTMLStyle}} 2860\logpage{[ 5, 3, 11 ]}\nobreak 2861\hyperdef{L}{X85AFD98383174BB5}{} 2862{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SetGAPDocHTMLStyle({\mdseries\slshape [style1[, style2], ...]})\index{SetGAPDocHTMLStyle@\texttt{SetGAPDocHTMLStyle}} 2863\label{SetGAPDocHTMLStyle} 2864}\hfill{\scriptsize (function)}}\\ 2865\textbf{\indent Returns:\ } 2866nothing 2867 2868 2869 2870 This utility function is for readers of the HTML version of \textsf{GAP} manuals which are generated by the \textsf{GAPDoc} package. It allows to configure the display style of the manuals. This will 2871only have an effect if you are using a browser that supports \textsf{javascript}. There is a default which can be reset by calling this function without 2872argument. 2873 2874 The arguments \mbox{\texttt{\mdseries\slshape style1}} and so on must be strings. You can find out about the valid strings by 2875following the \textsc{[Style]} link on top of any manual page. (Going back to the original page, its address 2876has a setting for \texttt{GAPDocStyle} which is the list of strings, separated by commas, you want to use here.) 2877\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 2878 !gapprompt@gap>| !gapinput@# show/hide subsections in tables on contents only after click,| 2879 !gapprompt@gap>| !gapinput@# and don't use colors in GAP examples| 2880 !gapprompt@gap>| !gapinput@SetGAPDocHTMLStyle("toggless", "nocolorprompt");| 2881\end{Verbatim} 2882 } 2883 2884 2885 2886\subsection{\textcolor{Chapter }{InfoGAPDoc}} 2887\logpage{[ 5, 3, 12 ]}\nobreak 2888\hyperdef{L}{X864A528B81C661A2}{} 2889{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InfoGAPDoc\index{InfoGAPDoc@\texttt{InfoGAPDoc}} 2890\label{InfoGAPDoc} 2891}\hfill{\scriptsize (info class)}}\\ 2892 2893 2894 The default level of this info class is 1. The converter functions for \textsf{GAPDoc} documents are then printing some information. You can suppress this by setting 2895the level of \texttt{InfoGAPDoc} to 0. With level 2 there may be some more information for debugging purposes. } 2896 2897 2898 2899\subsection{\textcolor{Chapter }{SetGapDocLanguage}} 2900\logpage{[ 5, 3, 13 ]}\nobreak 2901\hyperdef{L}{X82AB468887ED0DBB}{} 2902{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SetGapDocLanguage({\mdseries\slshape [lang]})\index{SetGapDocLanguage@\texttt{SetGapDocLanguage}} 2903\label{SetGapDocLanguage} 2904}\hfill{\scriptsize (function)}}\\ 2905\textbf{\indent Returns:\ } 2906nothing 2907 2908 2909 2910 \index{Using \textsf{GAPDoc} with other languages} The \textsf{GAPDoc} converter programs sometimes produce text which is not explicit in the 2911document, e.g., headers like ``Abstract'', ``Appendix'', links to ``Next Chapter'', variable types ``function'' and so on. 2912 2913 With \texttt{SetGapDocLanguage} the language for these texts can be changed. The argument \mbox{\texttt{\mdseries\slshape lang}} must be a string. Calling without argument or with a language name for which 2914no translations are available is the same as using the default \texttt{"english"}. 2915 2916 If your language \mbox{\texttt{\mdseries\slshape lang}} is not yet available, look at the record \texttt{GAPDocTexts.english} and translate all the strings to \mbox{\texttt{\mdseries\slshape lang}}. Then assign this record to \texttt{GAPDocTexts.(\mbox{\texttt{\mdseries\slshape lang}})} and send it to the \textsf{GAPDoc} authors for inclusion in future versions of \textsf{GAPDoc}. (Currently, there are translations for \texttt{english}, \texttt{german}, \texttt{russian} and \texttt{ukrainian}.) 2917 2918 \emph{Further hints:} To get strings produced by {\LaTeX} right you will probably use the \texttt{babel} package with option \mbox{\texttt{\mdseries\slshape lang}}, see \texttt{SetGapDocLaTeXOptions} (\ref{SetGapDocLaTeXOptions}). If \mbox{\texttt{\mdseries\slshape lang}} cannot be encoded in \texttt{latin1} encoding you can consider the use of \texttt{"utf8"} with \texttt{SetGapDocLaTeXOptions} (\ref{SetGapDocLaTeXOptions}). } 2919 2920 } 2921 2922 2923\section{\textcolor{Chapter }{Testing Manual Examples}}\label{Sec:TestExample} 2924\logpage{[ 5, 4, 0 ]} 2925\hyperdef{L}{X800299827B88ABBE}{} 2926{ 2927 \index{\texttt{ManualExamples}} \index{\texttt{TestManualExamples}} We also provide some tools to check and adjust the examples given in \texttt{{\textless}Example{\textgreater}}-elements. 2928 2929 Former versions of \textsf{GAPDoc} provided functions \texttt{ManualExamples} and \texttt{TestManualExamples}. These functions are still available, but no longer documented. Their use is 2930deprecated. 2931 2932\subsection{\textcolor{Chapter }{ExtractExamples}} 2933\logpage{[ 5, 4, 1 ]}\nobreak 2934\hyperdef{L}{X8337B2BC79253B3F}{} 2935{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ExtractExamples({\mdseries\slshape path, main, files, units})\index{ExtractExamples@\texttt{ExtractExamples}} 2936\label{ExtractExamples} 2937}\hfill{\scriptsize (function)}}\\ 2938\textbf{\indent Returns:\ } 2939a list of lists 2940 2941\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ExtractExamplesXMLTree({\mdseries\slshape tree, units})\index{ExtractExamplesXMLTree@\texttt{ExtractExamplesXMLTree}} 2942\label{ExtractExamplesXMLTree} 2943}\hfill{\scriptsize (function)}}\\ 2944\textbf{\indent Returns:\ } 2945a list of lists 2946 2947 2948 2949 The argument \mbox{\texttt{\mdseries\slshape tree}} must be a parse tree of a \textsf{GAPDoc} document, see \texttt{ParseTreeXMLFile} (\ref{ParseTreeXMLFile}). The function \texttt{ExtractExamplesXMLTree} returns a data structure representing the \texttt{{\textless}Example{\textgreater}} elements of the document. The return value can be used with \texttt{RunExamples} (\ref{RunExamples}) to check and optionally update the examples of the document. 2950 2951 Depending on the argument \mbox{\texttt{\mdseries\slshape units}} several examples are collected in one list. Recognized values for \mbox{\texttt{\mdseries\slshape units}} are \texttt{"Chapter"}, \texttt{"Section"}, \texttt{"Subsection"} or \texttt{"Single"}. The latter means that each example is in a separate list. For all other 2952value of \mbox{\texttt{\mdseries\slshape units}} just one list with all examples is returned. 2953 2954 The arguments \mbox{\texttt{\mdseries\slshape path}}, \mbox{\texttt{\mdseries\slshape main}} and \mbox{\texttt{\mdseries\slshape files}} of \texttt{ExtractExamples} are the same as for \texttt{ComposedDocument} (\ref{ComposedDocument}). This function first contructs and parses the \textsf{GAPDoc} document and then applies \texttt{ExtractExamplesXMLTree}. } 2955 2956 2957 2958\subsection{\textcolor{Chapter }{RunExamples}} 2959\logpage{[ 5, 4, 2 ]}\nobreak 2960\hyperdef{L}{X781D56FC7B938DCB}{} 2961{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RunExamples({\mdseries\slshape exmpls[, optrec]})\index{RunExamples@\texttt{RunExamples}} 2962\label{RunExamples} 2963}\hfill{\scriptsize (function)}}\\ 2964\textbf{\indent Returns:\ } 2965\texttt{true} or \texttt{false} 2966 2967 2968 2969 The argument \mbox{\texttt{\mdseries\slshape exmpls}} must be the output of a call to \texttt{ExtractExamples} (\ref{ExtractExamples}) or \texttt{ExtractExamplesXMLTree} (\ref{ExtractExamplesXMLTree}). The optional argument \mbox{\texttt{\mdseries\slshape optrec}} must be a record, its components can change the default behaviour of this 2970function. 2971 2972 By default this function runs the \textsf{GAP} input of all examples and compares the actual output with the output given in 2973the examples. If differences occur these are displayed together with 2974information on the location of the source code of that example. Before running 2975the examples in each unit (entry of \mbox{\texttt{\mdseries\slshape exmpls}}) the function \texttt{START{\textunderscore}TEST} (\textbf{Reference: START{\textunderscore}TEST}) is called and the screen width is set to 72 characters. 2976 2977 This function returns \texttt{true} if no differences are found and \texttt{false} otherwise. 2978 2979 If the argument \mbox{\texttt{\mdseries\slshape optrec}} is given, the following components are recognized: 2980\begin{description} 2981\item[{\texttt{showDiffs}}] The default value is \texttt{true}, if set to something else found differences in the examples are not 2982displayed. 2983\item[{\texttt{width}}] The value must be a positive integer which is used as screen width when 2984running the examples. As mentioned above, the default is 72 which is a 2985sensible value for the text version of the \textsf{GAPDoc} document used in a 80 character wide terminal. 2986\item[{\texttt{ignoreComments}}] The default is \texttt{false}.\\ 2987 If set to \texttt{true} comments in the input will be ignored (as in the default behaviour of the \texttt{Test} (\textbf{Reference: Test}) function). 2988\item[{\texttt{changeSources}}] If this is set to \texttt{true} then the source code of all manual examples which show differences is adjusted 2989to the current outputs. The default is \texttt{false}.\\ 2990 Use this feature with care. Note that sometimes differences can indicate a 2991bug, and in such a case it is more appropriate to fix the bug instead of 2992changing the example output. 2993\item[{\texttt{compareFunction}}] The function used to compare the output shown in the example and the current 2994output. See \texttt{Test} (\textbf{Reference: Test}) for more details. 2995\item[{\texttt{checkWidth}}] If this option is a positive integer \texttt{n} the function prints warnings if an example contains any line with more than \texttt{n} characters (input and output lines are considered). By default this option is 2996set to \texttt{false}. 2997\end{description} 2998 } 2999 3000 } 3001 3002 } 3003 3004 3005\chapter{\textcolor{Chapter }{String and Text Utilities}}\label{ch:util} 3006\logpage{[ 6, 0, 0 ]} 3007\hyperdef{L}{X86CEF540862EE042}{} 3008{ 3009 3010\section{\textcolor{Chapter }{Text Utilities}}\label{TextUtil} 3011\logpage{[ 6, 1, 0 ]} 3012\hyperdef{L}{X847DA07C7C46B38A}{} 3013{ 3014 This section describes some utility functions for handling texts within \textsf{GAP}. They are used by the functions in the \textsf{GAPDoc} package but may be useful for other purposes as well. We start with some 3015variables containing useful strings and go on with functions for parsing and 3016reformatting text. 3017 3018 3019 3020\subsection{\textcolor{Chapter }{WHITESPACE}} 3021\logpage{[ 6, 1, 1 ]}\nobreak 3022\hyperdef{L}{X786D477C7AB636AA}{} 3023{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WHITESPACE\index{WHITESPACE@\texttt{WHITESPACE}} 3024\label{WHITESPACE} 3025}\hfill{\scriptsize (global variable)}}\\ 3026\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CAPITALLETTERS\index{CAPITALLETTERS@\texttt{CAPITALLETTERS}} 3027\label{CAPITALLETTERS} 3028}\hfill{\scriptsize (global variable)}}\\ 3029\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SMALLLETTERS\index{SMALLLETTERS@\texttt{SMALLLETTERS}} 3030\label{SMALLLETTERS} 3031}\hfill{\scriptsize (global variable)}}\\ 3032\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LETTERS\index{LETTERS@\texttt{LETTERS}} 3033\label{LETTERS} 3034}\hfill{\scriptsize (global variable)}}\\ 3035\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DIGITS\index{DIGITS@\texttt{DIGITS}} 3036\label{DIGITS} 3037}\hfill{\scriptsize (global variable)}}\\ 3038\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HEXDIGITS\index{HEXDIGITS@\texttt{HEXDIGITS}} 3039\label{HEXDIGITS} 3040}\hfill{\scriptsize (global variable)}}\\ 3041\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{BOXCHARS\index{BOXCHARS@\texttt{BOXCHARS}} 3042\label{BOXCHARS} 3043}\hfill{\scriptsize (global variable)}}\\ 3044 3045 3046 These variables contain sets of characters which are useful for text 3047processing. They are defined as follows. 3048 3049 3050\begin{description} 3051\item[{\texttt{WHITESPACE}}] \texttt{" \texttt{\symbol{92}}n\texttt{\symbol{92}}t\texttt{\symbol{92}}r"} 3052\item[{\texttt{CAPITALLETTERS}}] \texttt{"ABCDEFGHIJKLMNOPQRSTUVWXYZ"} 3053\item[{\texttt{SMALLLETTERS}}] \texttt{"abcdefghijklmnopqrstuvwxyz"} 3054\item[{\texttt{LETTERS}}] concatenation of \texttt{CAPITALLETTERS} and \texttt{SMALLLETTERS} 3055\item[{\texttt{DIGITS}}] \texttt{"0123456789"} 3056\item[{\texttt{HEXDIGITS}}] \texttt{"0123456789ABCDEFabcdef"} 3057\item[{\texttt{BOXCHARS}}] \texttt{Encode(Unicode(9472 + [ 0, 2, 12, 44, 16, 28, 3058 60, 36, 20, 52, 24, 1, 3, 15, 51, 19, 35, 75, 43, 23, 59, 27, 80, 81, 3059 84, 102, 87, 96, 108, 99, 90, 105, 93 ]), "UTF-8")}, these are in UTF-8 encoding, the \texttt{i}-th unicode character is \texttt{BOXCHARS\texttt{\symbol{123}}[3*i-2..3*i]\texttt{\symbol{125}}}. 3060\end{description} 3061 } 3062 3063 3064 3065\subsection{\textcolor{Chapter }{TextAttr}} 3066\logpage{[ 6, 1, 2 ]}\nobreak 3067\hyperdef{L}{X785F61E77899580E}{} 3068{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{TextAttr\index{TextAttr@\texttt{TextAttr}} 3069\label{TextAttr} 3070}\hfill{\scriptsize (global variable)}}\\ 3071 3072 3073 The record \texttt{TextAttr} contains strings which can be printed to change the terminal attribute for the 3074following characters. This only works with terminals which understand basic 3075ANSI escape sequences. Try the following example to see if this is the case 3076for the terminal you are using. It shows the effect of the foreground and 3077background color attributes and of the \texttt{.bold}, \texttt{.blink}, \texttt{.normal}, \texttt{.reverse} and \texttt{.underscore} which can partly be mixed. 3078\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 3079 extra := ["CSI", "reset", "delline", "home"];; 3080 for t in Difference(RecNames(TextAttr), extra) do 3081 Print(TextAttr.(t), "TextAttr.", t, TextAttr.reset,"\n"); 3082 od; 3083\end{Verbatim} 3084 The suggested defaults for colors \texttt{0..7} are black, red, green, brown, blue, magenta, cyan, white. But this may be 3085different for your terminal configuration. 3086 3087 The escape sequence \texttt{.delline} deletes the content of the current line and \texttt{.home} moves the cursor to the beginning of the current line. 3088\begin{Verbatim}[fontsize=\small,frame=single,label=Example] 3089 for i in [1..5] do 3090 Print(TextAttr.home, TextAttr.delline, String(i,-6), "\c"); 3091 Sleep(1); 3092 od; 3093\end{Verbatim} 3094 \index{UseColorsInTerminal} Whenever you use this in some printing routines you should make it optional. 3095Use these attributes only when \texttt{UserPreference("UseColorsInTerminal");} returns \texttt{true}. } 3096 3097 3098 3099\subsection{\textcolor{Chapter }{WrapTextAttribute}} 3100\logpage{[ 6, 1, 3 ]}\nobreak 3101\hyperdef{L}{X7B8AD7517E5FD0EA}{} 3102{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WrapTextAttribute({\mdseries\slshape str, attr})\index{WrapTextAttribute@\texttt{WrapTextAttribute}} 3103\label{WrapTextAttribute} 3104}\hfill{\scriptsize (function)}}\\ 3105\textbf{\indent Returns:\ } 3106a string with markup 3107 3108 3109 3110 The argument \mbox{\texttt{\mdseries\slshape str}} must be a text as \textsf{GAP} string, possibly with markup by escape sequences as in \texttt{TextAttr} (\ref{TextAttr}). This function returns a string which is wrapped by the escape sequences \mbox{\texttt{\mdseries\slshape attr}} and \texttt{TextAttr.reset}. It takes care of markup in the given string by appending \mbox{\texttt{\mdseries\slshape attr}} also after each given \texttt{TextAttr.reset} in \mbox{\texttt{\mdseries\slshape str}}. 3111\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3112 !gapprompt@gap>| !gapinput@str := Concatenation("XXX",TextAttr.2, "BLUB", TextAttr.reset,"YYY");| 3113 "XXX\033[32mBLUB\033[0mYYY" 3114 !gapprompt@gap>| !gapinput@str2 := WrapTextAttribute(str, TextAttr.1);| 3115 "\033[31mXXX\033[32mBLUB\033[0m\033[31m\027YYY\033[0m" 3116 !gapprompt@gap>| !gapinput@str3 := WrapTextAttribute(str, TextAttr.underscore);| 3117 "\033[4mXXX\033[32mBLUB\033[0m\033[4m\027YYY\033[0m" 3118 !gapprompt@gap>| !gapinput@# use Print(str); and so on to see how it looks like.| 3119\end{Verbatim} 3120 } 3121 3122 3123 3124\subsection{\textcolor{Chapter }{FormatParagraph}} 3125\logpage{[ 6, 1, 4 ]}\nobreak 3126\hyperdef{L}{X812058CE7C8E9022}{} 3127{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FormatParagraph({\mdseries\slshape str[, len][, flush][, attr][, widthfun]})\index{FormatParagraph@\texttt{FormatParagraph}} 3128\label{FormatParagraph} 3129}\hfill{\scriptsize (function)}}\\ 3130\textbf{\indent Returns:\ } 3131the formatted paragraph as string 3132 3133 3134 3135 This function formats a text given in the string \mbox{\texttt{\mdseries\slshape str}} as a paragraph. The optional arguments have the following meaning: 3136\begin{description} 3137\item[{\mbox{\texttt{\mdseries\slshape len}}}] the length of the lines of the formatted text, default is \texttt{78} (counted without a visible length of the strings specified in the \mbox{\texttt{\mdseries\slshape attr}} argument) 3138\item[{\mbox{\texttt{\mdseries\slshape flush}}}] can be \texttt{"left"}, \texttt{"right"}, \texttt{"center"} or \texttt{"both"}, telling that lines should be flushed left, flushed right, centered or 3139left-right justified, respectively, default is \texttt{"both"} 3140\item[{\mbox{\texttt{\mdseries\slshape attr}}}] is a list of two strings; the first is prepended and the second appended to 3141each line of the result (can for example be used for indenting, \texttt{[" ", ""]}, or some markup, \texttt{[TextAttr.bold, TextAttr.reset]}, default is \texttt{["", ""]}) 3142\item[{\mbox{\texttt{\mdseries\slshape widthfun}}}] must be a function which returns the display width of text in \mbox{\texttt{\mdseries\slshape str}}. The default is \texttt{Length} assuming that each byte corresponds to a character of width one. If \mbox{\texttt{\mdseries\slshape str}} is given in \texttt{UTF-8} encoding one can use \texttt{WidthUTF8String} (\ref{WidthUTF8String}) here. 3143\end{description} 3144 This function tries to handle markup with the escape sequences explained in \texttt{TextAttr} (\ref{TextAttr}) correctly. 3145\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3146 !gapprompt@gap>| !gapinput@str := "One two three four five six seven eight nine ten eleven.";;| 3147 !gapprompt@gap>| !gapinput@Print(FormatParagraph(str, 25, "left", ["/* ", " */"])); | 3148 /* One two three four five */ 3149 /* six seven eight nine ten */ 3150 /* eleven. */ 3151\end{Verbatim} 3152 } 3153 3154 3155 3156\subsection{\textcolor{Chapter }{SubstitutionSublist}} 3157\logpage{[ 6, 1, 5 ]}\nobreak 3158\hyperdef{L}{X82A9121678923445}{} 3159{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SubstitutionSublist({\mdseries\slshape list, sublist, new[, flag]})\index{SubstitutionSublist@\texttt{SubstitutionSublist}} 3160\label{SubstitutionSublist} 3161}\hfill{\scriptsize (function)}}\\ 3162\textbf{\indent Returns:\ } 3163the changed list 3164 3165 3166 3167 This function looks for (non-overlapping) occurrences of a sublist \mbox{\texttt{\mdseries\slshape sublist}} in a list \mbox{\texttt{\mdseries\slshape list}} (compare \texttt{PositionSublist} (\textbf{Reference: PositionSublist})) and returns a list where these are substituted with the list \mbox{\texttt{\mdseries\slshape new}}. 3168 3169 The optional argument \mbox{\texttt{\mdseries\slshape flag}} can either be \texttt{"all"} (this is the default if not given) or \texttt{"one"}. In the second case only the first occurrence of \mbox{\texttt{\mdseries\slshape sublist}} is substituted. 3170 3171 If \mbox{\texttt{\mdseries\slshape sublist}} does not occur in \mbox{\texttt{\mdseries\slshape list}} then \mbox{\texttt{\mdseries\slshape list}} itself is returned (and not a \texttt{ShallowCopy(list)}). 3172\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3173 !gapprompt@gap>| !gapinput@SubstitutionSublist("xababx", "ab", "a");| 3174 "xaax" 3175\end{Verbatim} 3176 } 3177 3178 3179 3180\subsection{\textcolor{Chapter }{StripBeginEnd}} 3181\logpage{[ 6, 1, 6 ]}\nobreak 3182\hyperdef{L}{X83DE31017B557136}{} 3183{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StripBeginEnd({\mdseries\slshape list, strip})\index{StripBeginEnd@\texttt{StripBeginEnd}} 3184\label{StripBeginEnd} 3185}\hfill{\scriptsize (function)}}\\ 3186\textbf{\indent Returns:\ } 3187changed string 3188 3189 3190 3191 Here \mbox{\texttt{\mdseries\slshape list}} and \mbox{\texttt{\mdseries\slshape strip}} must be lists. This function returns the sublist of list which does not 3192contain the leading and trailing entries which are entries of \mbox{\texttt{\mdseries\slshape strip}}. If the result is equal to \mbox{\texttt{\mdseries\slshape list}} then \mbox{\texttt{\mdseries\slshape list}} itself is returned. 3193\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3194 !gapprompt@gap>| !gapinput@StripBeginEnd(" ,a, b,c, ", ", ");| 3195 "a, b,c" 3196\end{Verbatim} 3197 } 3198 3199 3200 3201\subsection{\textcolor{Chapter }{StripEscapeSequences}} 3202\logpage{[ 6, 1, 7 ]}\nobreak 3203\hyperdef{L}{X7A5978CF84C3C2D3}{} 3204{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StripEscapeSequences({\mdseries\slshape str})\index{StripEscapeSequences@\texttt{StripEscapeSequences}} 3205\label{StripEscapeSequences} 3206}\hfill{\scriptsize (function)}}\\ 3207\textbf{\indent Returns:\ } 3208string without escape sequences 3209 3210 3211 3212 This function returns the string one gets from the string \mbox{\texttt{\mdseries\slshape str}} by removing all escape sequences which are explained in \texttt{TextAttr} (\ref{TextAttr}). If \mbox{\texttt{\mdseries\slshape str}} does not contain such a sequence then \mbox{\texttt{\mdseries\slshape str}} itself is returned. } 3213 3214 3215 3216\subsection{\textcolor{Chapter }{RepeatedString}} 3217\logpage{[ 6, 1, 8 ]}\nobreak 3218\hyperdef{L}{X7D71CB837EE969D4}{} 3219{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RepeatedString({\mdseries\slshape c, len})\index{RepeatedString@\texttt{RepeatedString}} 3220\label{RepeatedString} 3221}\hfill{\scriptsize (function)}}\\ 3222\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RepeatedUTF8String({\mdseries\slshape c, len})\index{RepeatedUTF8String@\texttt{RepeatedUTF8String}} 3223\label{RepeatedUTF8String} 3224}\hfill{\scriptsize (function)}}\\ 3225 3226 3227 Here \mbox{\texttt{\mdseries\slshape c}} must be either a character or a string and \mbox{\texttt{\mdseries\slshape len}} is a non-negative number. Then \texttt{RepeatedString} returns a string of length \mbox{\texttt{\mdseries\slshape len}} consisting of copies of \mbox{\texttt{\mdseries\slshape c}}. 3228 3229 In the variant \texttt{RepeatedUTF8String} the argument \mbox{\texttt{\mdseries\slshape c}} is considered as string in UTF-8 encoding, and it can also be specified as 3230unicode string or character, see \texttt{Unicode} (\ref{Unicode}). The result is a string in UTF-8 encoding which has visible width \mbox{\texttt{\mdseries\slshape len}} as explained in \texttt{WidthUTF8String} (\ref{WidthUTF8String}). 3231\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3232 !gapprompt@gap>| !gapinput@RepeatedString('=',51);| 3233 "===================================================" 3234 !gapprompt@gap>| !gapinput@RepeatedString("*=",51);| 3235 "*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*" 3236 !gapprompt@gap>| !gapinput@s := "b�h";;| 3237 !gapprompt@gap>| !gapinput@enc := GAPInfo.TermEncoding;;| 3238 !gapprompt@gap>| !gapinput@if enc <> "UTF-8" then s := Encode(Unicode(s, enc), "UTF-8"); fi;| 3239 !gapprompt@gap>| !gapinput@l := RepeatedUTF8String(s, 8);;| 3240 !gapprompt@gap>| !gapinput@u := Unicode(l, "UTF-8");;| 3241 !gapprompt@gap>| !gapinput@Print(Encode(u, enc), "\n");| 3242 b�hb�hb� 3243\end{Verbatim} 3244 } 3245 3246 3247 3248\subsection{\textcolor{Chapter }{NumberDigits}} 3249\logpage{[ 6, 1, 9 ]}\nobreak 3250\hyperdef{L}{X7CEEA5B57D7BB38F}{} 3251{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NumberDigits({\mdseries\slshape str, base})\index{NumberDigits@\texttt{NumberDigits}} 3252\label{NumberDigits} 3253}\hfill{\scriptsize (function)}}\\ 3254\textbf{\indent Returns:\ } 3255integer 3256 3257\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DigitsNumber({\mdseries\slshape n, base})\index{DigitsNumber@\texttt{DigitsNumber}} 3258\label{DigitsNumber} 3259}\hfill{\scriptsize (function)}}\\ 3260\textbf{\indent Returns:\ } 3261string 3262 3263 3264 3265 The argument \mbox{\texttt{\mdseries\slshape str}} of \texttt{NumberDigits} must be a string consisting only of an optional leading \texttt{'-'} and characters in \texttt{0123456789abcdefABCDEF}, describing an integer in base \mbox{\texttt{\mdseries\slshape base}} with $2 \leq \mbox{\texttt{\mdseries\slshape base}} \leq 16$. This function returns the corresponding integer. 3266 3267 The function \texttt{DigitsNumber} does the reverse. 3268\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3269 !gapprompt@gap>| !gapinput@NumberDigits("1A3F",16);| 3270 6719 3271 !gapprompt@gap>| !gapinput@DigitsNumber(6719, 16);| 3272 "1A3F" 3273\end{Verbatim} 3274 } 3275 3276 3277 3278\subsection{\textcolor{Chapter }{LabelInt}} 3279\logpage{[ 6, 1, 10 ]}\nobreak 3280\hyperdef{L}{X79EF038284598D41}{} 3281{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LabelInt({\mdseries\slshape n, type, pre, post})\index{LabelInt@\texttt{LabelInt}} 3282\label{LabelInt} 3283}\hfill{\scriptsize (function)}}\\ 3284\textbf{\indent Returns:\ } 3285string 3286 3287 3288 3289 The argument \mbox{\texttt{\mdseries\slshape n}} must be an integer in the range from 1 to 5000, while \mbox{\texttt{\mdseries\slshape pre}} and \mbox{\texttt{\mdseries\slshape post}} must be strings. 3290 3291 The argument \mbox{\texttt{\mdseries\slshape type}} can be one of \texttt{"Decimal"}, \texttt{"Roman"}, \texttt{"roman"}, \texttt{"Alpha"}, \texttt{"alpha"}. 3292 3293 The function returns a string that starts with \mbox{\texttt{\mdseries\slshape pre}}, followed by a decimal, respectively roman number or alphanumerical number 3294literal (capital, respectively small letters), followed by \mbox{\texttt{\mdseries\slshape post}}. 3295 3296 3297\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3298 !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"Decimal","","."));| 3299 [ "1.", "2.", "3.", "4.", "5.", "691." ] 3300 !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"alpha","(",")"));| 3301 [ "(a)", "(b)", "(c)", "(d)", "(e)", "(zo)" ] 3302 !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"alpha","(",")"));| 3303 [ "(a)", "(b)", "(c)", "(d)", "(e)", "(zo)" ] 3304 !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"Alpha","",".)"));| 3305 [ "A.)", "B.)", "C.)", "D.)", "E.)", "ZO.)" ] 3306 !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"roman","","."));| 3307 [ "i.", "ii.", "iii.", "iv.", "v.", "dcxci." ] 3308 !gapprompt@gap>| !gapinput@List([1,2,3,4,5,691], i-> LabelInt(i,"Roman","",""));| 3309 [ "I", "II", "III", "IV", "V", "DCXCI" ] 3310\end{Verbatim} 3311 } 3312 3313 3314 3315\subsection{\textcolor{Chapter }{PositionMatchingDelimiter}} 3316\logpage{[ 6, 1, 11 ]}\nobreak 3317\hyperdef{L}{X7AF694D9839BF65C}{} 3318{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PositionMatchingDelimiter({\mdseries\slshape str, delim, pos})\index{PositionMatchingDelimiter@\texttt{PositionMatchingDelimiter}} 3319\label{PositionMatchingDelimiter} 3320}\hfill{\scriptsize (function)}}\\ 3321\textbf{\indent Returns:\ } 3322position as integer or \texttt{fail} 3323 3324 3325 3326 Here \mbox{\texttt{\mdseries\slshape str}} must be a string and \mbox{\texttt{\mdseries\slshape delim}} a string with two different characters. This function searches the smallest 3327position \texttt{r} of the character \texttt{\mbox{\texttt{\mdseries\slshape delim}}[2]} in \mbox{\texttt{\mdseries\slshape str}} such that the number of occurrences of \texttt{\mbox{\texttt{\mdseries\slshape delim}}[2]} in \mbox{\texttt{\mdseries\slshape str}} between positions \texttt{\mbox{\texttt{\mdseries\slshape pos}}+1} and \texttt{r} is by one greater than the corresponding number of occurrences of \texttt{\mbox{\texttt{\mdseries\slshape delim}}[1]}. 3328 3329 If such an \texttt{r} exists, it is returned. Otherwise \texttt{fail} is returned. 3330\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3331 !gapprompt@gap>| !gapinput@PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 0);| 3332 fail 3333 !gapprompt@gap>| !gapinput@PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 1);| 3334 2 3335 !gapprompt@gap>| !gapinput@PositionMatchingDelimiter("{}x{ab{c}d}", "{}", 6);| 3336 11 3337\end{Verbatim} 3338 } 3339 3340 3341 3342\subsection{\textcolor{Chapter }{WordsString}} 3343\logpage{[ 6, 1, 12 ]}\nobreak 3344\hyperdef{L}{X832556617F10AAA8}{} 3345{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WordsString({\mdseries\slshape str})\index{WordsString@\texttt{WordsString}} 3346\label{WordsString} 3347}\hfill{\scriptsize (function)}}\\ 3348\textbf{\indent Returns:\ } 3349list of strings containing the words 3350 3351 3352 3353 This returns the list of words of a text stored in the string \mbox{\texttt{\mdseries\slshape str}}. All non-letters are considered as word boundaries and are removed. 3354\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=Example] 3355 @gapprompt|gap>A @gapinput|WordsString("one_two \n three!?");A 3356 [ "one", "two", "three" ] 3357\end{Verbatim} 3358 } 3359 3360 3361 3362\subsection{\textcolor{Chapter }{Base64String}} 3363\logpage{[ 6, 1, 13 ]}\nobreak 3364\hyperdef{L}{X83F2821783DA9826}{} 3365{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Base64String({\mdseries\slshape str})\index{Base64String@\texttt{Base64String}} 3366\label{Base64String} 3367}\hfill{\scriptsize (function)}}\\ 3368\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringBase64({\mdseries\slshape bstr})\index{StringBase64@\texttt{StringBase64}} 3369\label{StringBase64} 3370}\hfill{\scriptsize (function)}}\\ 3371\textbf{\indent Returns:\ } 3372a string 3373 3374 3375 3376 The first function translates arbitrary binary data given as a GAP string into 3377a \emph{base 64} encoded string. This encoded string contains only printable ASCII characters 3378and is used in various data transfer protocols (\texttt{MIME} encoded emails, weak password encryption, ...). We use the specification in \href{http://tools.ietf.org/html/rfc2045} {RFC 2045}. 3379 3380 The second function has the reverse functionality. Here we also accept the 3381characters \texttt{-{\textunderscore}} instead of \texttt{+/} as last two characters. Whitespace is ignored. 3382\begin{Verbatim}[commandchars=@|D,fontsize=\small,frame=single,label=Example] 3383 @gapprompt|gap>D @gapinput|b := Base64String("This is a secret!");D 3384 "VGhpcyBpcyBhIHNlY3JldCEA=" 3385 @gapprompt|gap>D @gapinput|StringBase64(b); D 3386 "This is a secret!" 3387\end{Verbatim} 3388 } 3389 3390 } 3391 3392 3393\section{\textcolor{Chapter }{Unicode Strings}}\label{sec:Unicode} 3394\logpage{[ 6, 2, 0 ]} 3395\hyperdef{L}{X8489C67D80399814}{} 3396{ 3397 The \textsf{GAPDoc} package provides some tools to deal with unicode characters and strings. These 3398can be used for recoding text strings between various encodings. 3399\subsection{\textcolor{Chapter }{Unicode Strings and Characters}}\logpage{[ 6, 2, 1 ]} 3400\hyperdef{L}{X8475671278948DDD}{} 3401{ 3402\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Unicode({\mdseries\slshape list[, encoding]})\index{Unicode@\texttt{Unicode}} 3403\label{Unicode} 3404}\hfill{\scriptsize (operation)}}\\ 3405\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UChar({\mdseries\slshape num})\index{UChar@\texttt{UChar}} 3406\label{UChar} 3407}\hfill{\scriptsize (operation)}}\\ 3408\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsUnicodeString\index{IsUnicodeString@\texttt{IsUnicodeString}} 3409\label{IsUnicodeString} 3410}\hfill{\scriptsize (filter)}}\\ 3411\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsUnicodeCharacter\index{IsUnicodeCharacter@\texttt{IsUnicodeCharacter}} 3412\label{IsUnicodeCharacter} 3413}\hfill{\scriptsize (filter)}}\\ 3414\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IntListUnicodeString({\mdseries\slshape ustr})\index{IntListUnicodeString@\texttt{IntListUnicodeString}} 3415\label{IntListUnicodeString} 3416}\hfill{\scriptsize (function)}}\\ 3417 3418 3419 Unicode characters are described by their \emph{codepoint}, an integer in the range from $0$ to $2^{21}-1$. For details about unicode, see \href{http://www.unicode.org} {\texttt{http://www.unicode.org}}. 3420 3421 The function \texttt{UChar} wraps an integer \mbox{\texttt{\mdseries\slshape num}} into a \textsf{GAP} object lying in the filter \texttt{IsUnicodeCharacter}. Use \texttt{Int} to get the codepoint back. The argument \mbox{\texttt{\mdseries\slshape num}} can also be a \textsf{GAP} character which is then translated to an integer via \texttt{IntChar} (\textbf{Reference: IntChar}). 3422 3423 \texttt{Unicode} produces a \textsf{GAP} object in the filter \texttt{IsUnicodeString}. This is a wrapped list of integers for the unicode characters in the string. 3424The function \texttt{IntListUnicodeString} gives access to this list of integers. Basic list functionality is available 3425for \texttt{IsUnicodeString} elements. The entries are in \texttt{IsUnicodeCharacter}. The argument \mbox{\texttt{\mdseries\slshape list}} for \texttt{Unicode} is either a list of integers or a \textsf{GAP} string. In the latter case an \mbox{\texttt{\mdseries\slshape encoding}} can be specified as string, its default is \texttt{"UTF-8"}. 3426 3427 \index{URL encoding}\index{RFC 3986} Currently supported encodings can be found in \texttt{UNICODE{\textunderscore}RECODE.NormalizedEncodings} (ASCII, ISO-8859-X, UTF-8 and aliases). The encoding \texttt{"XML"} means an ASCII encoding in which non-ASCII characters are specified by XML 3428character entities. The encoding \texttt{"URL"} is for URL-encoded (also called percent-encoded strings, as specified in RFC 34293986 (\href{http://www.ietf.org/rfc/rfc3986.txt} {see here}). The listed encodings \texttt{"LaTeX"} and aliases cannot be used with \texttt{Unicode}. See the operation \texttt{Encode} (\ref{Encode}) for mapping a unicode string to a \textsf{GAP} string. 3430 3431 3432\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3433 !gapprompt@gap>| !gapinput@ustr := Unicode("a and \366", "latin1");| 3434 Unicode("a and �") 3435 !gapprompt@gap>| !gapinput@ustr = Unicode("a and ö", "XML"); | 3436 true 3437 !gapprompt@gap>| !gapinput@IntListUnicodeString(ustr);| 3438 [ 97, 32, 97, 110, 100, 32, 246 ] 3439 !gapprompt@gap>| !gapinput@ustr[7];| 3440 '�' 3441\end{Verbatim} 3442 } 3443 3444 3445 3446\subsection{\textcolor{Chapter }{Encode}} 3447\logpage{[ 6, 2, 2 ]}\nobreak 3448\hyperdef{L}{X818A31567EB30A39}{} 3449{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Encode({\mdseries\slshape ustr[, encoding]})\index{Encode@\texttt{Encode}} 3450\label{Encode} 3451}\hfill{\scriptsize (operation)}}\\ 3452\textbf{\indent Returns:\ } 3453a \textsf{GAP} string 3454 3455\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SimplifiedUnicodeString({\mdseries\slshape ustr[, encoding][, "single"]})\index{SimplifiedUnicodeString@\texttt{SimplifiedUnicodeString}} 3456\label{SimplifiedUnicodeString} 3457}\hfill{\scriptsize (function)}}\\ 3458\textbf{\indent Returns:\ } 3459a unicode string 3460 3461\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LowercaseUnicodeString({\mdseries\slshape ustr})\index{LowercaseUnicodeString@\texttt{LowercaseUnicodeString}} 3462\label{LowercaseUnicodeString} 3463}\hfill{\scriptsize (function)}}\\ 3464\textbf{\indent Returns:\ } 3465a unicode string 3466 3467\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UppercaseUnicodeString({\mdseries\slshape ustr})\index{UppercaseUnicodeString@\texttt{UppercaseUnicodeString}} 3468\label{UppercaseUnicodeString} 3469}\hfill{\scriptsize (function)}}\\ 3470\textbf{\indent Returns:\ } 3471a unicode string 3472 3473\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LaTeXUnicodeTable\index{LaTeXUnicodeTable@\texttt{LaTeXUnicodeTable}} 3474\label{LaTeXUnicodeTable} 3475}\hfill{\scriptsize (global variable)}}\\ 3476\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SimplifiedUnicodeTable\index{SimplifiedUnicodeTable@\texttt{SimplifiedUnicodeTable}} 3477\label{SimplifiedUnicodeTable} 3478}\hfill{\scriptsize (global variable)}}\\ 3479\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LowercaseUnicodeTable\index{LowercaseUnicodeTable@\texttt{LowercaseUnicodeTable}} 3480\label{LowercaseUnicodeTable} 3481}\hfill{\scriptsize (global variable)}}\\ 3482 3483 3484 The operation \texttt{Encode} translates a unicode string \mbox{\texttt{\mdseries\slshape ustr}} into a \textsf{GAP} string in some specified \mbox{\texttt{\mdseries\slshape encoding}}. The default encoding is \texttt{"UTF-8"}. 3485 3486 Supported encodings can be found in \texttt{UNICODE{\textunderscore}RECODE.NormalizedEncodings}. Except for some cases mentioned below characters which are not available in 3487the target encoding are substituted by '?' characters. 3488 3489 If the \mbox{\texttt{\mdseries\slshape encoding}} is \texttt{"URL"} (see \texttt{Unicode} (\ref{Unicode})) then an optional argument \mbox{\texttt{\mdseries\slshape encreserved}} can be given, it must be a list of reserved characters which should be percent 3490encoded; the default is to encode only the \texttt{\%} character. 3491 3492 The encoding \texttt{"LaTeX"} substitutes non-ASCII characters and {\LaTeX} special characters by {\LaTeX} code as given in an ordered list \texttt{LaTeXUnicodeTable} of pairs [codepoint, string]. If you have a unicode character for which no 3493substitution is contained in that list, you will get a warning and the 3494translation is \texttt{Unicode(nr)}. In this case find a substitution and add a corresponding [codepoint, string] 3495pair to \texttt{LaTeXUnicodeTable} using \texttt{AddSet} (\textbf{Reference: AddSet}). Also, please, tell the \textsf{GAPDoc} authors about your addition, such that we can extend the list \texttt{LaTeXUnicodeTable}. (Most of the initial entries were generated from lists in the {\TeX} projects enc{\TeX} and \texttt{ucs}.) There are some variants of this encoding: 3496 3497 \texttt{"LaTeXleavemarkup"} does the same translations for non-ASCII characters but leaves the {\LaTeX} special characters (e.g., any {\LaTeX} commands) as they are. 3498 3499 \texttt{"LaTeXUTF8"} does not give a warning about unicode characters without explicit translation, 3500instead it translates the character to its \texttt{UTF-8} encoding. Make sure to setup your {\LaTeX} document such that all these characters are understood. 3501 3502 \texttt{"LaTeXUTF8leavemarkup"} is a combination of the last two variants. 3503 3504 Note that the \texttt{"LaTeX"} encoding can only be used with \texttt{Encode} but not for the opposite translation with \texttt{Unicode} (\ref{Unicode}) (which would need far too complicated heuristics). 3505 3506 The function \texttt{SimplifiedUnicodeString} can be used to substitute many non-ASCII characters by related ASCII 3507characters or strings (e.g., by a corresponding character without accents). 3508The argument \mbox{\texttt{\mdseries\slshape ustr}} and the result are unicode strings, if \mbox{\texttt{\mdseries\slshape encoding}} is \texttt{"ASCII"} then all non-ASCII characters are translated, otherwise only the non-latin1 3509characters. If the string \texttt{"single"} in an argument then only substitutions are considered which don't make the 3510result string longer. The translations are stored in a sorted list \texttt{SimplifiedUnicodeTable}. Its entries are of the form \texttt{[codepoint, trans1, trans2, ...]}. Here \texttt{trans1} and so on is either an integer for the codepoint of a substitution character 3511or it is a list of codepoint integers. If you are missing characters in this 3512list and know a sensible ASCII approximation, then add an entry (with \texttt{AddSet} (\textbf{Reference: AddSet})) and tell the \textsf{GAPDoc} authors about it. (The initial content of \texttt{SimplifiedUnicodeTable} was mainly generated from the ``\texttt{transtab}'' tables by Markus Kuhn.) 3513 3514 The function \texttt{LowercaseUnicodeString} gets and returns a unicode string and translates each uppercase character to 3515its corresponding lowercase version. This function uses a list \texttt{LowercaseUnicodeTable} of pairs of codepoint integers. This list was generated using the file \texttt{UnicodeData.txt} from the unicode definition (field 14 in each row). 3516 3517 The function \texttt{UppercaseUnicodeString} does the similar translation to uppercase characters. 3518\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3519 !gapprompt@gap>| !gapinput@ustr := Unicode("a and ö", "XML");| 3520 Unicode("a and �") 3521 !gapprompt@gap>| !gapinput@SimplifiedUnicodeString(ustr, "ASCII");| 3522 Unicode("a and oe") 3523 !gapprompt@gap>| !gapinput@SimplifiedUnicodeString(ustr, "ASCII", "single");| 3524 Unicode("a and o") 3525 !gapprompt@gap>| !gapinput@ustr2 := UppercaseUnicodeString(ustr);;| 3526 !gapprompt@gap>| !gapinput@Print(Encode(ustr2, GAPInfo.TermEncoding), "\n");| 3527 A AND � 3528\end{Verbatim} 3529 } 3530 3531 3532\subsection{\textcolor{Chapter }{Lengths of UTF-8 strings}}\logpage{[ 6, 2, 3 ]} 3533\hyperdef{L}{X801237207E06A876}{} 3534{ 3535\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WidthUTF8String({\mdseries\slshape str})\index{WidthUTF8String@\texttt{WidthUTF8String}} 3536\label{WidthUTF8String} 3537}\hfill{\scriptsize (function)}}\\ 3538\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NrCharsUTF8String({\mdseries\slshape str})\index{NrCharsUTF8String@\texttt{NrCharsUTF8String}} 3539\label{NrCharsUTF8String} 3540}\hfill{\scriptsize (function)}}\\ 3541\textbf{\indent Returns:\ } 3542an integer 3543 3544 3545 3546 Let \mbox{\texttt{\mdseries\slshape str}} be a \textsf{GAP} string with text in UTF-8 encoding. There are three ``lengths'' of such a string which must be distinguished. The operation \texttt{Length} (\textbf{Reference: Length}) returns the number of bytes and so the memory occupied by \mbox{\texttt{\mdseries\slshape str}}. The function \texttt{NrCharsUTF8String} returns the number of unicode characters in \mbox{\texttt{\mdseries\slshape str}}, that is the length of \texttt{Unicode(\mbox{\texttt{\mdseries\slshape str}})}. 3547 3548 In many applications the function \texttt{WidthUTF8String} is more interesting, it returns the number of columns needed by the string if 3549printed to a terminal. This takes into account that some unicode characters 3550are combining characters and that there are wide characters which need two 3551columns (e.g., for Chinese or Japanese). (To be precise: This implementation 3552assumes that there are no control characters in \mbox{\texttt{\mdseries\slshape str}} and uses the character width returned by the \texttt{wcwidth} function in the GNU C-library called with UTF-8 locale.) 3553\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3554 !gapprompt@gap>| !gapinput@# A, German umlaut u, B, zero width space, C, newline| 3555 !gapprompt@gap>| !gapinput@str := Encode( Unicode( "AüB​C\n", "XML" ) );;| 3556 !gapprompt@gap>| !gapinput@Print(str);| 3557 A�BC 3558 !gapprompt@gap>| !gapinput@# umlaut u needs two bytes and the zero width space three| 3559 !gapprompt@gap>| !gapinput@Length(str);| 3560 9 3561 !gapprompt@gap>| !gapinput@NrCharsUTF8String(str);| 3562 6 3563 !gapprompt@gap>| !gapinput@# zero width space and newline don't contribute to width| 3564 !gapprompt@gap>| !gapinput@WidthUTF8String(str);| 3565 4 3566\end{Verbatim} 3567 } 3568 3569 3570 3571\subsection{\textcolor{Chapter }{InitialSubstringUTF8String}} 3572\logpage{[ 6, 2, 4 ]}\nobreak 3573\hyperdef{L}{X7E2974CD84977819}{} 3574{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InitialSubstringUTF8String({\mdseries\slshape str, maxwidth[, suf]})\index{InitialSubstringUTF8String@\texttt{InitialSubstringUTF8String}} 3575\label{InitialSubstringUTF8String} 3576}\hfill{\scriptsize (function)}}\\ 3577\textbf{\indent Returns:\ } 3578UTF-8 encoded string 3579 3580 3581 3582 The arguments \mbox{\texttt{\mdseries\slshape str}} and \mbox{\texttt{\mdseries\slshape suf}} each must be a \textsf{GAP} string with text in UTF-8 encoding or a unicode string. The argument \mbox{\texttt{\mdseries\slshape suf}} is optional and its default value is the empty string. If the visible width of \mbox{\texttt{\mdseries\slshape str}} is at most \mbox{\texttt{\mdseries\slshape maxwidth}} then \mbox{\texttt{\mdseries\slshape str}} is returned as UTF-8 encoded \textsf{GAP} string. Otherwise, \mbox{\texttt{\mdseries\slshape suf}} is appended to the maximal initial substring of \mbox{\texttt{\mdseries\slshape str}} such that the total visible width of the result is at most \mbox{\texttt{\mdseries\slshape maxwidth}}. 3583\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3584 !gapprompt@gap>| !gapinput@# A, German umlaut u, B, zero width space, C, newline| 3585 !gapprompt@gap>| !gapinput@str := Encode( Unicode( "AüB​C\n", "XML" ) );;| 3586 !gapprompt@gap>| !gapinput@ini := InitialSubstringUTF8String(str, 3);;| 3587 !gapprompt@gap>| !gapinput@WidthUTF8String(ini);| 3588 3 3589 !gapprompt@gap>| !gapinput@IntListUnicodeString(Unicode(ini));| 3590 [ 65, 252, 66, 8203 ] 3591 !gapprompt@gap>| !gapinput@l := Unicode([ 23380, 22827, 23376 ] );; # three chars of width 2| 3592 !gapprompt@gap>| !gapinput@s := InitialSubstringUTF8String(l, 4, "*");;| 3593 !gapprompt@gap>| !gapinput@WidthUTF8String(s);| 3594 3 3595\end{Verbatim} 3596 } 3597 3598 } 3599 3600 3601\section{\textcolor{Chapter }{Print Utilities}}\label{PrintUtil} 3602\logpage{[ 6, 3, 0 ]} 3603\hyperdef{L}{X860C83047DC4F1BC}{} 3604{ 3605 The following printing utilities turned out to be useful for interactive work 3606with texts in \textsf{GAP}. But they are more general and so we document them here. 3607 3608\subsection{\textcolor{Chapter }{PrintTo1}} 3609\logpage{[ 6, 3, 1 ]}\nobreak 3610\hyperdef{L}{X8603B90C7C3F0AB1}{} 3611{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrintTo1({\mdseries\slshape filename, fun})\index{PrintTo1@\texttt{PrintTo1}} 3612\label{PrintTo1} 3613}\hfill{\scriptsize (function)}}\\ 3614\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AppendTo1({\mdseries\slshape filename, fun})\index{AppendTo1@\texttt{AppendTo1}} 3615\label{AppendTo1} 3616}\hfill{\scriptsize (function)}}\\ 3617 3618 3619 The argument \mbox{\texttt{\mdseries\slshape fun}} must be a function without arguments. Everything which is printed by a call \mbox{\texttt{\mdseries\slshape fun()}} is printed into the file \mbox{\texttt{\mdseries\slshape filename}}. As with \texttt{PrintTo} (\textbf{Reference: PrintTo}) and \texttt{AppendTo} (\textbf{Reference: AppendTo}) this overwrites or appends to, respectively, a previous content of \mbox{\texttt{\mdseries\slshape filename}}. 3620 3621 These functions can be particularly efficient when many small pieces of text 3622shall be written to a file, because no multiple reopening of the file is 3623necessary. 3624\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3625 !gapprompt@gap>| !gapinput@f := function() local i; | 3626 !gapprompt@>| !gapinput@ for i in [1..100000] do Print(i, "\n"); od; end;; | 3627 !gapprompt@gap>| !gapinput@PrintTo1("nonsense", f); # now check the local file `nonsense'| 3628\end{Verbatim} 3629 } 3630 3631 3632 3633\subsection{\textcolor{Chapter }{StringPrint}} 3634\logpage{[ 6, 3, 2 ]}\nobreak 3635\hyperdef{L}{X829B720C86E57E8B}{} 3636{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringPrint({\mdseries\slshape obj1[, obj2[, ...]]})\index{StringPrint@\texttt{StringPrint}} 3637\label{StringPrint} 3638}\hfill{\scriptsize (function)}}\\ 3639\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringView({\mdseries\slshape obj})\index{StringView@\texttt{StringView}} 3640\label{StringView} 3641}\hfill{\scriptsize (function)}}\\ 3642\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringDisplay({\mdseries\slshape obj})\index{StringDisplay@\texttt{StringDisplay}} 3643\label{StringDisplay} 3644}\hfill{\scriptsize (function)}}\\ 3645 3646 3647 These functions return a string containing the output of a \texttt{Print}, \texttt{ViewObj} or \texttt{Display} call, respectively, with the same arguments. 3648 3649 This should be considered as a (temporary?) hack. It would be better to have \texttt{String} (\textbf{Reference: String}) methods for all \textsf{GAP} objects and to have a generic \texttt{Print} (\textbf{Reference: Print})-function which just interprets these strings. } 3650 3651 3652 3653\subsection{\textcolor{Chapter }{PrintFormattedString}} 3654\logpage{[ 6, 3, 3 ]}\nobreak 3655\hyperdef{L}{X812A8326844BC910}{} 3656{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrintFormattedString({\mdseries\slshape str})\index{PrintFormattedString@\texttt{PrintFormattedString}} 3657\label{PrintFormattedString} 3658}\hfill{\scriptsize (function)}}\\ 3659 3660 3661 This function prints a string \mbox{\texttt{\mdseries\slshape str}}. The difference to \texttt{Print(str);} is that no additional line breaks are introduced by \textsf{GAP}'s standard printing mechanism. This can be used to print lines which are 3662longer than the current screen width. In particular one can print text which 3663contains escape sequences like those explained in \texttt{TextAttr} (\ref{TextAttr}), where lines may have more characters than \emph{visible characters}. } 3664 3665 3666 3667\subsection{\textcolor{Chapter }{Page}} 3668\logpage{[ 6, 3, 4 ]}\nobreak 3669\hyperdef{L}{X7BB6731F7E3AAA98}{} 3670{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Page({\mdseries\slshape ...})\index{Page@\texttt{Page}} 3671\label{Page} 3672}\hfill{\scriptsize (function)}}\\ 3673\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PageDisplay({\mdseries\slshape obj})\index{PageDisplay@\texttt{PageDisplay}} 3674\label{PageDisplay} 3675}\hfill{\scriptsize (function)}}\\ 3676 3677 3678 These functions are similar to \texttt{Print} (\textbf{Reference: Print}) and \texttt{Display} (\textbf{Reference: Display}), respectively. The difference is that the output is not sent directly to the 3679screen, but is piped into the current pager; see \texttt{Pager} (\textbf{Reference: Pager}). 3680\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3681 !gapprompt@gap>| !gapinput@Page([1..1421]+0);| 3682 !gapprompt@gap>| !gapinput@PageDisplay(CharacterTable("Symmetric", 14));| 3683\end{Verbatim} 3684 } 3685 3686 3687 3688\subsection{\textcolor{Chapter }{StringFile}} 3689\logpage{[ 6, 3, 5 ]}\nobreak 3690\hyperdef{L}{X7E14D32181FBC3C3}{} 3691{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringFile({\mdseries\slshape filename})\index{StringFile@\texttt{StringFile}} 3692\label{StringFile} 3693}\hfill{\scriptsize (function)}}\\ 3694\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FileString({\mdseries\slshape filename, str[, append]})\index{FileString@\texttt{FileString}} 3695\label{FileString} 3696}\hfill{\scriptsize (function)}}\\ 3697 3698 3699 The function \texttt{StringFile} returns the content of file \mbox{\texttt{\mdseries\slshape filename}} as a string. This works efficiently with arbitrary (binary or text) files. If 3700something went wrong, this function returns \texttt{fail}. 3701 3702 Conversely the function \texttt{FileString} writes the content of a string \mbox{\texttt{\mdseries\slshape str}} into the file \mbox{\texttt{\mdseries\slshape filename}}. If the optional third argument \mbox{\texttt{\mdseries\slshape append}} is given and equals \texttt{true} then the content of \mbox{\texttt{\mdseries\slshape str}} is appended to the file. Otherwise previous content of the file is deleted. 3703This function returns the number of bytes written or \texttt{fail} if something went wrong. 3704 3705 Both functions are quite efficient, even with large files. } 3706 3707 } 3708 3709 } 3710 3711 3712\chapter{\textcolor{Chapter }{Utilities for Bibliographies}}\label{ch:bibutil} 3713\logpage{[ 7, 0, 0 ]} 3714\hyperdef{L}{X7EB94CE97ABF7192}{} 3715{ 3716 A standard for collecting references (in particular to mathematical texts) is Bib{\TeX} (\href{http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/} {\texttt{http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/}}). A disadvantage of Bib{\TeX} is that the format of the data is specified with the use by {\LaTeX} in mind. The data format is less suited for conversion to other document types 3717like plain text or HTML. 3718 3719 In the first section we describe utilities for using data from Bib{\TeX} files in \textsf{GAP}. 3720 3721 In the second section we introduce a new XML based data format BibXMLext for 3722bibliographies which seems better suited for other tasks than using it with {\LaTeX}. 3723 3724 Another section will describe utilities to deal with BibXMLext data in \textsf{GAP}. 3725\section{\textcolor{Chapter }{Parsing Bib{\TeX} Files}}\label{ParseBib} 3726\logpage{[ 7, 1, 0 ]} 3727\hyperdef{L}{X7A4126EC7BD68F64}{} 3728{ 3729 Here are functions for parsing, normalizing and printing reference lists in Bib{\TeX} format. The reference describing this format is{\nobreakspace}\cite[Appendix B]{La85}. 3730 3731\subsection{\textcolor{Chapter }{ParseBibFiles}} 3732\logpage{[ 7, 1, 1 ]}\nobreak 3733\hyperdef{L}{X82555C307FDC1817}{} 3734{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseBibFiles({\mdseries\slshape bibfile1[, bibfile2[, ...]]})\index{ParseBibFiles@\texttt{ParseBibFiles}} 3735\label{ParseBibFiles} 3736}\hfill{\scriptsize (function)}}\\ 3737\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseBibStrings({\mdseries\slshape str1[, str2[, ...]]})\index{ParseBibStrings@\texttt{ParseBibStrings}} 3738\label{ParseBibStrings} 3739}\hfill{\scriptsize (function)}}\\ 3740\textbf{\indent Returns:\ } 3741list \texttt{[list of bib-records, list of abbrevs, list of expansions]} 3742 3743 3744 3745 The first function parses the files \mbox{\texttt{\mdseries\slshape bibfile1}} and so on (if a file does not exist the extension \texttt{.bib} is appended) in Bib{\TeX} format and returns a list as follows: \texttt{[entries, strings, texts]}. Here \texttt{entries} is a list of records, one record for each reference contained in \mbox{\texttt{\mdseries\slshape bibfile}}. Then \texttt{strings} is a list of abbreviations defined by \texttt{@string}-entries in \mbox{\texttt{\mdseries\slshape bibfile}} and \texttt{texts} is a list which contains in the corresponding position the full text for such 3746an abbreviation. 3747 3748 The second function does the same, but the input is given as \textsf{GAP} strings \mbox{\texttt{\mdseries\slshape str1}} and so on. 3749 3750 The records in \texttt{entries} store key-value pairs of a Bib{\TeX} reference in the form \texttt{rec(key1 = value1, ...)}. The names of the keys are converted to lower case. The type of the reference 3751(i.e., book, article, ...) and the citation key are stored as components \texttt{.Type} and \texttt{.Label}. The records also have a \texttt{.From} field that says that the data are read from a Bib{\TeX} source. 3752 3753 As an example consider the following Bib{\TeX} file. 3754\begin{Verbatim}[fontsize=\small,frame=single,label=doc/test.bib] 3755 @string{ j = "Important Journal" } 3756 @article{ AB2000, Author= "Fritz A. First and Sec, X. Y.", 3757 TITLE="Short", journal = j, year = 2000 } 3758\end{Verbatim} 3759 3760\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3761 !gapprompt@gap>| !gapinput@bib := ParseBibFiles("doc/test.bib");| 3762 [ [ rec( From := rec( BibTeX := true ), Label := "AB2000", 3763 Type := "article", author := "Fritz A. First and Sec, X. Y." 3764 , journal := "Important Journal", title := "Short", 3765 year := "2000" ) ], [ "j" ], [ "Important Journal" ] ] 3766\end{Verbatim} 3767 } 3768 3769 3770 3771\subsection{\textcolor{Chapter }{NormalizedNameAndKey}} 3772\logpage{[ 7, 1, 2 ]}\nobreak 3773\hyperdef{L}{X7C9F0C337A0A0FF0}{} 3774{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NormalizedNameAndKey({\mdseries\slshape namestr})\index{NormalizedNameAndKey@\texttt{NormalizedNameAndKey}} 3775\label{NormalizedNameAndKey} 3776}\hfill{\scriptsize (function)}}\\ 3777\textbf{\indent Returns:\ } 3778list of strings and names as lists 3779 3780\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NormalizeNameAndKey({\mdseries\slshape r})\index{NormalizeNameAndKey@\texttt{NormalizeNameAndKey}} 3781\label{NormalizeNameAndKey} 3782}\hfill{\scriptsize (function)}}\\ 3783\textbf{\indent Returns:\ } 3784nothing 3785 3786 3787 3788 The argument \mbox{\texttt{\mdseries\slshape namestr}} must be a string describing an author or a list of authors as described in the Bib{\TeX} documentation in \cite[Appendix B 1.2]{La85}. The function \texttt{NormalizedNameAndKey} returns a list of the form [ normalized name string, short key, long key, 3789names as lists]. The first entry is a normalized form of the input where names 3790are written as ``lastname, first name initials''. The second and third entry are the name parts of a short and long key for 3791the bibliography entry, formed from the (initials of) last names. The fourth 3792entry is a list of lists, one for each name, where a name is described by 3793three strings for the last name, the first name initials and the first name(s) 3794as given in the input. 3795 3796 The function \texttt{NormalizeNameAndKey} gets as argument \mbox{\texttt{\mdseries\slshape r}} a record for a bibliography entry as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). It substitutes \texttt{.author} and \texttt{.editor} fields of \mbox{\texttt{\mdseries\slshape r}} by their normalized form, the original versions are stored in fields \texttt{.authororig} and \texttt{.editororig}. 3797 3798 Furthermore a short and a long citation key is generated and stored in 3799components \texttt{.printedkey} (only if no \texttt{.key} is already bound) and \texttt{.keylong}. 3800 3801 We continue the example from \texttt{ParseBibFiles} (\ref{ParseBibFiles}). 3802\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3803 !gapprompt@gap>| !gapinput@bib := ParseBibFiles("doc/test.bib");;| 3804 !gapprompt@gap>| !gapinput@NormalizedNameAndKey(bib[1][1].author);| 3805 [ "First, F. A. and Sec, X. Y.", "FS", "firstsec", 3806 [ [ "First", "F. A.", "Fritz A." ], [ "Sec", "X. Y.", "X. Y." ] ] ] 3807 !gapprompt@gap>| !gapinput@NormalizeNameAndKey(bib[1][1]);| 3808 !gapprompt@gap>| !gapinput@bib[1][1];| 3809 rec( From := rec( BibTeX := true ), Label := "AB2000", 3810 Type := "article", author := "First, F. A. and Sec, X. Y.", 3811 authororig := "Fritz A. First and Sec, X. Y.", 3812 journal := "Important Journal", keylong := "firstsec2000", 3813 printedkey := "FS00", title := "Short", year := "2000" ) 3814\end{Verbatim} 3815 } 3816 3817 3818 3819\subsection{\textcolor{Chapter }{WriteBibFile}} 3820\logpage{[ 7, 1, 3 ]}\nobreak 3821\hyperdef{L}{X7C2B2F65851EAA0B}{} 3822{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WriteBibFile({\mdseries\slshape bibfile, bib})\index{WriteBibFile@\texttt{WriteBibFile}} 3823\label{WriteBibFile} 3824}\hfill{\scriptsize (function)}}\\ 3825\textbf{\indent Returns:\ } 3826nothing 3827 3828 3829 3830 This is the converse of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Here \mbox{\texttt{\mdseries\slshape bib}} either must have a format as list of three lists as it is returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Or \mbox{\texttt{\mdseries\slshape bib}} can be a record as returned by \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). A Bib{\TeX} file \mbox{\texttt{\mdseries\slshape bibfile}} is written and the entries are formatted in a uniform way. All given 3831abbreviations are used while writing this file. 3832 3833 We continue the example from \texttt{NormalizeNameAndKey} (\ref{NormalizeNameAndKey}). The command 3834\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3835 !gapprompt@gap>| !gapinput@WriteBibFile("nicer.bib", bib);| 3836\end{Verbatim} 3837 produces a file \texttt{nicer.bib} as follows: 3838\begin{Verbatim}[fontsize=\small,frame=single,label=nicer.bib] 3839 @string{j = "Important Journal" } 3840 3841 @article{ AB2000, 3842 author = {First, F. A. and Sec, X. Y.}, 3843 title = {Short}, 3844 journal = j, 3845 year = {2000}, 3846 authororig = {Fritz A. First and Sec, X. Y.}, 3847 keylong = {firstsec2000}, 3848 printedkey = {FS00} 3849 } 3850\end{Verbatim} 3851 } 3852 3853 3854 3855\subsection{\textcolor{Chapter }{LabelsFromBibTeX}} 3856\logpage{[ 7, 1, 4 ]}\nobreak 3857\hyperdef{L}{X783FD118794399DF}{} 3858{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LabelsFromBibTeX({\mdseries\slshape path, keys, bibfiles, style})\index{LabelsFromBibTeX@\texttt{LabelsFromBibTeX}} 3859\label{LabelsFromBibTeX} 3860}\hfill{\scriptsize (function)}}\\ 3861\textbf{\indent Returns:\ } 3862a list of pairs of strings \texttt{[key, label]} 3863 3864 3865 3866 This function uses \texttt{bibtex} to determine the ordering of a list of references and a label for each entry 3867which is typeset in a document citing these references. 3868 3869 The argument \mbox{\texttt{\mdseries\slshape path}} is a directory specified as string or directory object. The argument \mbox{\texttt{\mdseries\slshape bibfiles}} must be a list of files in Bib{\TeX} format, each specified by a path relative to the first argument, or an 3870absolute path (starting with \texttt{'/'}) or relative to the \textsf{GAP} roots (starting with \texttt{"gap://"}). The list \mbox{\texttt{\mdseries\slshape keys}} must contain strings which occur as keys in the given Bib{\TeX} files. Finally the string \mbox{\texttt{\mdseries\slshape style}} must be the name of a bibliography style (like \texttt{"alpha"}). 3871 3872 The list returned by this function contains pairs \texttt{[key, label]} where \texttt{key} is one of the entries of \mbox{\texttt{\mdseries\slshape keys}} and \texttt{label} is a string used for citations of the bibliography entry in a document. These 3873pairs are ordered as the reference list produced by Bib{\TeX}. 3874\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 3875 !gapprompt@gap>| !gapinput@f := Filename(DirectoriesPackageLibrary("gapdoc","doc"), "test.bib");;| 3876 !gapprompt@gap>| !gapinput@LabelsFromBibTeX(".", ["AB2000"], [f], "alpha");| 3877 [ [ "AB2000", "FS00" ] ] 3878\end{Verbatim} 3879 } 3880 3881 3882 3883\subsection{\textcolor{Chapter }{InfoBibTools}} 3884\logpage{[ 7, 1, 5 ]}\nobreak 3885\hyperdef{L}{X85C1D50F7E37A99A}{} 3886{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{InfoBibTools\index{InfoBibTools@\texttt{InfoBibTools}} 3887\label{InfoBibTools} 3888}\hfill{\scriptsize (info class)}}\\ 3889 3890 3891 The default level of this info class is 1. Functions like \texttt{ParseBibFiles} (\ref{ParseBibFiles}), \texttt{StringBibAs...} are then printing some information. You can suppress it by setting the level 3892of \texttt{InfoBibTools} to 0. With level 2 there may be some more information for debugging purposes. } 3893 3894 } 3895 3896 3897\section{\textcolor{Chapter }{The BibXMLext Format}}\label{BibXMLformat} 3898\logpage{[ 7, 2, 0 ]} 3899\hyperdef{L}{X7FB8F6BD80D859D1}{} 3900{ 3901 Bibliographical data in Bib{\TeX} files have the disadvantage that the actual data are given in {\LaTeX} syntax. This makes it difficult to use the data for anything but for {\LaTeX}, say for representations of the data as plain text or HTML. For example: 3902mathematical formulae are in {\LaTeX} \texttt{\$} environments, non-ASCII characters can be specified in many strange ways, and 3903how to specify URLs for links if the output format allows them? 3904 3905 Here we propose an XML data format for bibliographical data which addresses 3906these problems, it is called BibXMLext. In the next section we describe some 3907tools for generating (an approximation to) this data format from Bib{\TeX} data, and for using data given in BibXMLext format for various purposes. 3908 3909 The first motivation for this development was the handling of bibliographical 3910data in \textsf{GAPDoc}, but the format and the tools are certainly useful for other purposes as 3911well. 3912 3913 We started from a DTD \texttt{bibxml.dtd} which is publicly available, say from \href{http://bibtexml.sf.net/} {\texttt{http://bibtexml.sf.net/}}. This is essentially a reformulation of the definition of the Bib{\TeX} format, including several of some widely used further fields. This has already 3914the advantage that a generic XML parser can check the validity of the data 3915entries, for example for missing compulsary fields in entries. We applied the 3916following changes and extensions to define the DTD for BibXMLext, stored in 3917the file \texttt{bibxmlext.dtd} which can be found in the root directory of this \textsf{GAPDoc} package (and in Appendix \ref{bibxmlextdtd}): 3918\begin{description} 3919\item[{names}] Lists of names in the \texttt{author} and \texttt{editor} fields in Bib{\TeX} are difficult to parse. Here they must be given by a sequence of \texttt{{\textless}name{\textgreater}}-elements which each contain an optional \texttt{{\textless}first{\textgreater}}- and a \texttt{{\textless}last{\textgreater}}-element for the first and last names, respectively. 3920\item[{\texttt{{\textless}M{\textgreater}} and \texttt{{\textless}Math{\textgreater}}}] These elements enclose mathematical formulae, the content is {\LaTeX} code (without the \texttt{\$}). These should be handled in the same way as the elements with the same names 3921in \textsf{GAPDoc}, see \ref{M} and \ref{Math}. In particular, simple formulae which have a well defined plain text 3922representation can be given in \texttt{{\textless}M{\textgreater}}-elements. 3923\item[{Encoding}] Note that in XML files we can use the full range of unicode characters, see \href{http://www.unicode.org/} {\texttt{http://www.unicode.org/}}. All non-ASCII characters should be specified as unicode characters. This 3924makes dealing with special characters easy for plain text or HTML, only for 3925use with {\LaTeX} some sort of translation is necessary. 3926\item[{\texttt{{\textless}URL{\textgreater}}}] These elements are allowed everywhere in the text and should be represented by 3927links in converted formats which allow this. It is used in the same way as the 3928element with the same name in \textsf{GAPDoc}, see \ref{URL}. 3929\item[{\texttt{{\textless}Alt Only="..."{\textgreater}} and \texttt{{\textless}Alt Not="..."{\textgreater}}}] Sometimes information should be given in different ways, depending on the 3930output format of the data. This is possible with the \texttt{{\textless}Alt{\textgreater}}-elements with the same definition as in \textsf{GAPDoc}, see \ref{Alt}. 3931\item[{\texttt{{\textless}C{\textgreater}}}] This element should be used to protect text from case changes by converters 3932(the extra \texttt{\texttt{\symbol{123}}\texttt{\symbol{125}}} characters in Bib{\TeX} title fields). 3933\item[{\texttt{{\textless}string key="..." value="..."/{\textgreater}} and \texttt{{\textless}value key="..."/{\textgreater}}}] The \texttt{{\textless}string{\textgreater}}-element defines key-value pairs which can be used in any field via the \texttt{{\textless}value{\textgreater}}-element (not only for whole fields but also parts of the text). 3934\item[{\texttt{{\textless}other type="..."{\textgreater}}}] This is a generic element for fields which are otherwise not supported. An 3935arbitrary number of them is allowed for each entry, so any kind of additional 3936data can be added to entries. 3937\item[{\texttt{{\textless}Wrap Name="..."{\textgreater}}}] This generic element is allowed inside all fields. This markup will be just 3938ignored (but not the element content) by our standard tools. But it can be a 3939useful hook for introducing arbitrary further markup (and our tools can easily 3940be extended to handle it). 3941\item[{Extra entities}] The DTD defines the standard XML entities (\ref{XMLspchar} and the entities \texttt{\ } (non-breakable space), \texttt{\–} and \texttt{\©right;}. Use \texttt{\–} in page ranges. 3942\end{description} 3943 For further details of the DTD we refer to the file \texttt{bibxmlext.dtd} itself which is shown in appendix \ref{bibxmlextdtd}. That file also recalls some information from the Bib{\TeX} documentation on how the standard fields of entries should be used. Which 3944entry types and which fields are supported (and the ordering of the fields 3945which is fixed by a DTD) can be either read off the DTD, or within \textsf{GAP} one can use the function \texttt{TemplateBibXML} (\ref{TemplateBibXML}) to get templates for the various entry types. 3946 3947 Here is an example of a BibXMLext document: 3948\begin{Verbatim}[fontsize=\small,frame=single,label=doc/testbib.xml] 3949 <?xml version="1.0" encoding="UTF-8"?> 3950 <!DOCTYPE file SYSTEM "bibxmlext.dtd"> 3951 <file> 3952 <string key="j" value="Important Journal"/> 3953 <entry id="AB2000"><article> 3954 <author> 3955 <name><first>Fritz A.</first><last>First</last></name> 3956 <name><first>X. Y.</first><last>Secőnd</last></name> 3957 </author> 3958 <title>The <Wrap Name="Package"> <C>F</C>ritz</Wrap> package for the 3959 formula <M>x^y - l_{{i+1}} \rightarrow \mathbb{R}</M></title> 3960 <journal><value key="j"/></journal> 3961 <year>2000</year> 3962 <number>13</number> 3963 <pages>13–25</pages> 3964 <note>Online data at <URL Text="Bla Bla Publisher"> 3965 http://www.publish.com/~ImpJ/123#data</URL></note> 3966 <other type="mycomment">very useful</other> 3967 </article></entry> 3968 </file> 3969 3970\end{Verbatim} 3971 There is a standard XML header and a \texttt{DOCTYPE} declaration referring to the \texttt{bibxmlext.dtd} DTD mentioned above. Local entities could be defined in the \texttt{DOCTYPE} tag as shown in the example in \ref{GDent}. The actual content of the document is inside a \texttt{{\textless}file{\textgreater}}-element, it consists of \texttt{{\textless}string{\textgreater}}- and \texttt{{\textless}entry{\textgreater}}-elements. Several of the BibXMLext markup features are shown. We will use 3972this input document for some examples below. } 3973 3974 3975\section{\textcolor{Chapter }{Utilities for BibXMLext data}}\label{BibXMLtools} 3976\logpage{[ 7, 3, 0 ]} 3977\hyperdef{L}{X7AC255DE7D2531B6}{} 3978{ 3979 3980\subsection{\textcolor{Chapter }{Translating Bib{\TeX} to BibXMLext}}\label{Subsect:IntroXMLBib} 3981\logpage{[ 7, 3, 1 ]} 3982\hyperdef{L}{X7C5548E77ECA29D7}{} 3983{ 3984 First we describe a tool which can translate bibliography entries from Bib{\TeX} data to BibXMLext \texttt{{\textless}entry{\textgreater}}-elements. It also does some validation of the data. In some cases it is 3985desirable to improve the result by hand afterwards (editing formulae, adding \texttt{{\textless}URL{\textgreater}}-elements, translating non-ASCII characters to unicode, ...). 3986 3987 See \texttt{WriteBibXMLextFile} (\ref{WriteBibXMLextFile}) below for how to write the results to a BibXMLext file. } 3988 3989 3990 3991\subsection{\textcolor{Chapter }{HeuristicTranslationsLaTeX2XML.Apply}} 3992\logpage{[ 7, 3, 2 ]}\nobreak 3993\hyperdef{L}{X7A025E0A7A1CD390}{} 3994{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HeuristicTranslationsLaTeX2XML.Apply({\mdseries\slshape str})\index{HeuristicTranslationsLaTeX2XML.Apply@\texttt{Heuristic}\-\texttt{Translations}\-\texttt{La}\-\texttt{Te}\-\texttt{X2}\-\texttt{X}\-\texttt{M}\-\texttt{L.}\-\texttt{Apply}} 3995\label{HeuristicTranslationsLaTeX2XML.Apply} 3996}\hfill{\scriptsize (function)}}\\ 3997\textbf{\indent Returns:\ } 3998a string 3999 4000\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{HeuristicTranslationsLaTeX2XML.ApplyToFile({\mdseries\slshape fnam[, outnam]})\index{HeuristicTranslationsLaTeX2XML.ApplyToFile@\texttt{Heuristic}\-\texttt{Translations}\-\texttt{La}\-\texttt{Te}\-\texttt{X2}\-\texttt{X}\-\texttt{M}\-\texttt{L.}\-\texttt{Apply}\-\texttt{To}\-\texttt{File}} 4001\label{HeuristicTranslationsLaTeX2XML.ApplyToFile} 4002}\hfill{\scriptsize (function)}}\\ 4003\textbf{\indent Returns:\ } 4004nothing 4005 4006 4007 4008 These utilities translate some {\LaTeX} code into text in UTF-8 encoding. The input is given as a string \mbox{\texttt{\mdseries\slshape str}}, or a file name \mbox{\texttt{\mdseries\slshape fnam}}, respectively. The first function returns the translated string. The second 4009function with one argument overwrites the given file with the translated text. 4010Optionally, the translated file content can be written to another file, if its 4011name is given as second argument \mbox{\texttt{\mdseries\slshape outnam}}. 4012 4013 The record \texttt{HeuristicTranslationsLaTeX2XML} mainly contains translations of {\LaTeX} macros for special characters which were found in hundreds of Bib{\TeX} entries from \href{http://www.ams.org/mathscinet/} {MathSciNet}. Just look at this record if you want to know how it works. It is easy to 4014extend, and if you have improvements which may be of general interest, please 4015send them to the \textsf{GAPDoc} author. 4016\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 4017 !gapprompt@gap>| !gapinput@s := "\\\"u\\'{e}\\`e{\\ss}";;| 4018 !gapprompt@gap>| !gapinput@Print(s, "\n"); | 4019 \"u\'{e}\`e{\ss} 4020 !gapprompt@gap>| !gapinput@Print(HeuristicTranslationsLaTeX2XML.Apply(s),"\n");| 4021 ���� 4022\end{Verbatim} 4023 } 4024 4025 4026 4027\subsection{\textcolor{Chapter }{StringBibAsXMLext}} 4028\logpage{[ 7, 3, 3 ]}\nobreak 4029\hyperdef{L}{X85F33C64787A00B7}{} 4030{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringBibAsXMLext({\mdseries\slshape bibentry[, abbrvs, vals][, encoding]})\index{StringBibAsXMLext@\texttt{StringBibAsXMLext}} 4031\label{StringBibAsXMLext} 4032}\hfill{\scriptsize (function)}}\\ 4033\textbf{\indent Returns:\ } 4034a string with XML code, or \texttt{fail} 4035 4036 4037 4038 The argument \mbox{\texttt{\mdseries\slshape bibentry}} is a record representing an entry from a Bib{\TeX} file, as returned in the first list of the result of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). The optional two arguments \mbox{\texttt{\mdseries\slshape abbrvs}} and \mbox{\texttt{\mdseries\slshape vals}} can be lists of abbreviations and substitution strings, as returned as second 4039and third list element in the result of \texttt{ParseBibFiles} (\ref{ParseBibFiles}). The optional argument \mbox{\texttt{\mdseries\slshape encoding}} specifies the character encoding of the string components of \mbox{\texttt{\mdseries\slshape bibentry}}. If this is not given it is checked if all strings are valid UTF-8 encoded 4040strings, in that case it is assumed that the encoding is UTF-8, otherwise the 4041latin1 encoding is assumed. 4042 4043 The function \texttt{StringBibAsXMLext} creates XML code of an \texttt{{\textless}entry{\textgreater}}-element in \texttt{BibXMLext} format. The result is in UTF-8 encoding and contains some heuristic 4044translations, like splitting name lists, finding places for \texttt{{\textless}C{\textgreater}}-elements, putting formulae in \texttt{{\textless}M{\textgreater}}-elements, substituting some characters. The result should always be checked 4045and maybe improved by hand. Some validity checks are applied to the given 4046data, for example if all non-optional fields are given. If this check fails 4047the function returns \texttt{fail}. 4048 4049 If your Bib{\TeX} input contains {\LaTeX} markup for special characters, it can be convenient to translate this input 4050with \texttt{HeuristicTranslationsLaTeX2XML.Apply} (\ref{HeuristicTranslationsLaTeX2XML.Apply}) or \texttt{HeuristicTranslationsLaTeX2XML.ApplyToFile} (\ref{HeuristicTranslationsLaTeX2XML.ApplyToFile}) before parsing it as Bib{\TeX}. 4051 4052 As an example we consider again the short Bib{\TeX} file \texttt{doc/test.bib} shown in the example for \texttt{ParseBibFiles} (\ref{ParseBibFiles}). 4053\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 4054 !gapprompt@gap>| !gapinput@bib := ParseBibFiles("doc/test.bib");;| 4055 !gapprompt@gap>| !gapinput@str := StringBibAsXMLext(bib[1][1], bib[2], bib[3]);;| 4056 !gapprompt@gap>| !gapinput@Print(str, "\n");| 4057 <entry id="AB2000"><article> 4058 <author> 4059 <name><first>Fritz A.</first><last>First</last></name> 4060 <name><first>X. Y.</first><last>Sec</last></name> 4061 </author> 4062 <title>Short</title> 4063 <journal><value key="j"/></journal> 4064 <year>2000</year> 4065 </article></entry> 4066\end{Verbatim} 4067 } 4068 4069 The following functions allow parsing of data which are already in BibXMLext 4070format. 4071 4072\subsection{\textcolor{Chapter }{ParseBibXMLextString}} 4073\logpage{[ 7, 3, 4 ]}\nobreak 4074\hyperdef{L}{X86BD29AE7A453721}{} 4075{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseBibXMLextString({\mdseries\slshape str[, res]})\index{ParseBibXMLextString@\texttt{ParseBibXMLextString}} 4076\label{ParseBibXMLextString} 4077}\hfill{\scriptsize (function)}}\\ 4078\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ParseBibXMLextFiles({\mdseries\slshape fname1[, fname2[, ...]]})\index{ParseBibXMLextFiles@\texttt{ParseBibXMLextFiles}} 4079\label{ParseBibXMLextFiles} 4080}\hfill{\scriptsize (function)}}\\ 4081\textbf{\indent Returns:\ } 4082a record with fields \texttt{.entries}, \texttt{.strings} and \texttt{.entities} 4083 4084 4085 4086 The first function gets a string \mbox{\texttt{\mdseries\slshape str}} containing a \texttt{BibXMLext} document or a part of it. It returns a record with the three mentioned fields. 4087Here \texttt{.entries} is a list of partial XML parse trees for the \texttt{{\textless}entry{\textgreater}}-elements in \mbox{\texttt{\mdseries\slshape str}}. The field \texttt{.strings} is a list of key-value pairs from the \texttt{{\textless}string{\textgreater}}-elements in \mbox{\texttt{\mdseries\slshape str}}. And \texttt{.strings} is a list of name-value pairs of the named entities which were used during the 4088parsing. 4089 4090 The optional argument \mbox{\texttt{\mdseries\slshape res}} can be the result of a former call of this function, in that case the newly 4091parsed entries are added to this data structure. 4092 4093 The second function \texttt{ParseBibXMLextFiles} uses the first on the content of all files given by filenames \mbox{\texttt{\mdseries\slshape fname1}} and so on. It collects the results in a single record. 4094 4095 As an example we parse the file \texttt{testbib.xml} shown in \ref{BibXMLformat}. 4096\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 4097 !gapprompt@gap>| !gapinput@bib := ParseBibXMLextFiles("doc/testbib.xml");;| 4098 !gapprompt@gap>| !gapinput@RecNames(bib);| 4099 [ "entries", "strings", "entities" ] 4100 !gapprompt@gap>| !gapinput@bib.entries;| 4101 [ <BibXMLext entry: AB2000> ] 4102 !gapprompt@gap>| !gapinput@bib.strings;| 4103 [ [ "j", "Important Journal" ] ] 4104 !gapprompt@gap>| !gapinput@bib.entities[1]; | 4105 [ "amp", "&#38;" ] 4106\end{Verbatim} 4107 } 4108 4109 4110 4111\subsection{\textcolor{Chapter }{WriteBibXMLextFile}} 4112\logpage{[ 7, 3, 5 ]}\nobreak 4113\hyperdef{L}{X7811108C7E5B1709}{} 4114{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{WriteBibXMLextFile({\mdseries\slshape fname, bib})\index{WriteBibXMLextFile@\texttt{WriteBibXMLextFile}} 4115\label{WriteBibXMLextFile} 4116}\hfill{\scriptsize (function)}}\\ 4117\textbf{\indent Returns:\ } 4118nothing 4119 4120 4121 4122 This function writes a BibXMLext file with name \mbox{\texttt{\mdseries\slshape fname}}. 4123 4124 There are three possibilities to specify the bibliography entries in the 4125argument \mbox{\texttt{\mdseries\slshape bib}}. It can be a list of three lists as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}). Or it can be just the first of such three lists in which case the other two 4126lists are assumed to be empty. To all entries of the (first) list the function \texttt{StringBibAsXMLext} (\ref{StringBibAsXMLext}) is applied and the resulting strings are written to the result file. 4127 4128 The third possibility is that \mbox{\texttt{\mdseries\slshape bib}} is a record in the format as returned by \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}) and \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). In this case the entries for the BibXMLext file are produced with \texttt{StringXMLElement} (\ref{StringXMLElement}), and if \mbox{\texttt{\mdseries\slshape bib}}\texttt{.entities} is bound then it is tried to resubstitute parts of the string by the given 4129entities with \texttt{EntitySubstitution} (\ref{EntitySubstitution}). 4130 4131 As an example we write back the result of the example shown for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}) to an equivalent XML file. 4132\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 4133 !gapprompt@gap>| !gapinput@bib := ParseBibXMLextFiles("doc/testbib.xml");;| 4134 !gapprompt@gap>| !gapinput@WriteBibXMLextFile("test.xml", bib);| 4135\end{Verbatim} 4136 } 4137 4138 4139\subsection{\textcolor{Chapter }{Bibliography Entries as Records}}\label{Subsect:RecBib} 4140\logpage{[ 7, 3, 6 ]} 4141\hyperdef{L}{X82167F1280F4310E}{} 4142{ 4143 For working with BibXMLext entries we find it convenient to first translate 4144the parse tree of an entry, as returned by \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}), to a record with the field names of the entry as components whose value is 4145the content of the field as string. These strings are generated with respect 4146to a result type. The records are generated by the following function which 4147can be customized by the user. } 4148 4149 4150 4151\subsection{\textcolor{Chapter }{RecBibXMLEntry}} 4152\logpage{[ 7, 3, 7 ]}\nobreak 4153\hyperdef{L}{X786C33ED79F425F1}{} 4154{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RecBibXMLEntry({\mdseries\slshape entry[, restype][, strings][, options]})\index{RecBibXMLEntry@\texttt{RecBibXMLEntry}} 4155\label{RecBibXMLEntry} 4156}\hfill{\scriptsize (function)}}\\ 4157\textbf{\indent Returns:\ } 4158a record with fields as strings 4159 4160 4161 4162 This function generates a content string for each field of a bibliography 4163entry and assigns them to record components. This content may depend on the 4164requested result type and possibly some given options. 4165 4166 The arguments are as follows: \mbox{\texttt{\mdseries\slshape entry}} is the parse tree of an \texttt{{\textless}entry{\textgreater}} element as returned by \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}) or \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). The optional argument \mbox{\texttt{\mdseries\slshape restype}} describes the type of the result. This package supports currently the types \texttt{"BibTeX"}, \texttt{"Text"} and \texttt{"HTML"}. The default is \texttt{"BibTeX"}. The optional argument \mbox{\texttt{\mdseries\slshape strings}} must be a list of key-value pairs as returned in the component \texttt{.strings} in the result of \texttt{ParseBibXMLextString} (\ref{ParseBibXMLextString}). The argument \mbox{\texttt{\mdseries\slshape options}} must be a record. 4167 4168 If the entry contains an \texttt{author} field then the result will also contain a component \texttt{.authorAsList} which is a list containing for each author a list with three entries of the 4169form \texttt{[last name, first name initials, first name]} (the third entry means the first name as given in the data). Similarly, an \texttt{editor} field is accompanied by a component \texttt{.editorAsList}. 4170 4171 The following \mbox{\texttt{\mdseries\slshape options}} are currently supported. 4172 4173 If \texttt{options.fullname} is bound and set to \texttt{true} then the full given first names for authors and editors will be used, the 4174default is to use the initials of the first names. Also, if \texttt{options.namefirstlast} is bound and set to \texttt{true} then the names are written in the form ``first-name(s) last-name'', the default is the form ``last-name, first-name(s)''. 4175 4176 If \texttt{options.href} is bound and set to \texttt{false} then the \texttt{"BibTeX"} type result will not use \texttt{\texttt{\symbol{92}}href} commands. The default is to produce \texttt{\texttt{\symbol{92}}href} commands from \texttt{{\textless}URL{\textgreater}}-elements such that {\LaTeX} with the \texttt{hyperref} package can produce links for them. 4177 4178 The content of an \texttt{{\textless}Alt{\textgreater}}-element with \texttt{Only}-attribute is included if \mbox{\texttt{\mdseries\slshape restype}} is given in the attribute and ignored otherwise, and vice versa in case of a \texttt{Not}-attribute. If \texttt{options.useAlt} is bound, it must be a list of strings to which \mbox{\texttt{\mdseries\slshape restype}} is added. Then an \texttt{{\textless}Alt{\textgreater}}-element with \texttt{Only}-attribute is evaluated if the intersection of \texttt{options.useAlt} and the types given in the attribute is not empty. In case of a \texttt{Not}-attribute the element is evaluated if this intersection is empty. 4179 4180 If \mbox{\texttt{\mdseries\slshape restype}} is \texttt{"BibTeX"} then the string fields in the result will be recoded with \texttt{Encode} (\ref{Encode}) and target \texttt{"LaTeX"}. If \texttt{options.hasLaTeXmarkup} is bound and set to \texttt{true} (for example, because the data are originally read from Bib{\TeX} files), then the target \texttt{"LaTeXleavemarkup"} will be used. 4181 4182 We use again the file shown in the example for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). 4183\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 4184 !gapprompt@gap>| !gapinput@bib := ParseBibXMLextFiles("doc/testbib.xml");;| 4185 !gapprompt@gap>| !gapinput@e := bib.entries[1];; strs := bib.strings;;| 4186 !gapprompt@gap>| !gapinput@Print(RecBibXMLEntry(e, "BibTeX", strs), "\n");| 4187 rec( 4188 From := rec( 4189 BibXML := true, 4190 options := rec( 4191 ), 4192 type := "BibTeX" ), 4193 Label := "AB2000", 4194 Type := "article", 4195 author := "First, F. A. and Sec{\\H o}nd, X. Y.", 4196 authorAsList := 4197 [ [ "First", "F. A.", "Fritz A." ], 4198 [ "Sec\305\221nd", "X. Y.", "X. Y." ] ], 4199 journal := "Important Journal", 4200 mycomment := "very useful", 4201 note := 4202 "Online data at \\href {http://www.publish.com/~ImpJ/123#data} {Bla\ 4203 Bla Publisher}", 4204 number := "13", 4205 pages := "13{\\textendash}25", 4206 printedkey := "FS00", 4207 title := 4208 "The {F}ritz package for the \n formula $x^y - l_{{i+1}} \ 4209 \\rightarrow \\mathbb{R}$", 4210 year := "2000" ) 4211 !gapprompt@gap>| !gapinput@Print(RecBibXMLEntry(e, "HTML", strs).note, "\n");| 4212 Online data at <a href="http://www.publish.com/~ImpJ/123#data">Bla Bla\ 4213 Publisher</a> 4214\end{Verbatim} 4215 } 4216 4217 4218 4219\subsection{\textcolor{Chapter }{AddHandlerBuildRecBibXMLEntry}} 4220\logpage{[ 7, 3, 8 ]}\nobreak 4221\hyperdef{L}{X8067261385905A36}{} 4222{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AddHandlerBuildRecBibXMLEntry({\mdseries\slshape elementname, restype, handler})\index{AddHandlerBuildRecBibXMLEntry@\texttt{AddHandlerBuildRecBibXMLEntry}} 4223\label{AddHandlerBuildRecBibXMLEntry} 4224}\hfill{\scriptsize (function)}}\\ 4225\textbf{\indent Returns:\ } 4226nothing 4227 4228 4229 4230 The argument \mbox{\texttt{\mdseries\slshape elementname}} must be the name of an entry field supported by the BibXMLext format, the name 4231of one of the special elements \texttt{"C"}, \texttt{"M"}, \texttt{"Math"}, \texttt{"URL"} or of the form \texttt{"Wrap:myname"} or any string \texttt{"mytype"} (which then corresponds to entry fields \texttt{{\textless}other type="mytype"{\textgreater}}). The string \texttt{"Finish"} has an exceptional meaning, see below. 4232 4233 \mbox{\texttt{\mdseries\slshape restype}} is a string describing the result type for which the handler is installed, see \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}). 4234 4235 For both arguments, \mbox{\texttt{\mdseries\slshape elementname}} and \mbox{\texttt{\mdseries\slshape restype}}, it is also possible to give lists of the described ones for installing 4236several handler at once. 4237 4238 The argument \mbox{\texttt{\mdseries\slshape handler}} must be a function with five arguments of the form \mbox{\texttt{\mdseries\slshape handler}}\texttt{(entry, r, restype, strings, options)}. Here \mbox{\texttt{\mdseries\slshape entry}} is a parse tree of a BibXMLext \texttt{{\textless}entry{\textgreater}}-element, \mbox{\texttt{\mdseries\slshape r}} is a node in this tree for an element \mbox{\texttt{\mdseries\slshape elementname}}, and \mbox{\texttt{\mdseries\slshape restype}}, \mbox{\texttt{\mdseries\slshape strings}} and \mbox{\texttt{\mdseries\slshape options}} are as explained in \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}). The function should return a string representing the content of the node \mbox{\texttt{\mdseries\slshape r}}. If \mbox{\texttt{\mdseries\slshape elementname}} is of the form \texttt{"Wrap:myname"} the handler is used for elements of form \texttt{{\textless}Wrap Name="myname"{\textgreater}...{\textless}/Wrap{\textgreater}}. 4239 4240 If \mbox{\texttt{\mdseries\slshape elementname}} is \texttt{"Finish"} the handler should look like above except that now \mbox{\texttt{\mdseries\slshape r}} is the record generated by \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) just before it is returned. Here the handler should return nothing. It can be 4241used to manipulate the record \mbox{\texttt{\mdseries\slshape r}}, for example for changing the encoding of the strings or for adding some more 4242components. 4243 4244 The installed handler is called by \texttt{BuildRecBibXMLEntry(}\mbox{\texttt{\mdseries\slshape entry}}, \mbox{\texttt{\mdseries\slshape r}}, \mbox{\texttt{\mdseries\slshape restype}}, \mbox{\texttt{\mdseries\slshape strings}}, \mbox{\texttt{\mdseries\slshape options}}\texttt{)}. The string for the whole content of an element can be generated by \texttt{ContentBuildRecBibXMLEntry(}\mbox{\texttt{\mdseries\slshape entry}}, \mbox{\texttt{\mdseries\slshape r}}, \mbox{\texttt{\mdseries\slshape restype}}, \mbox{\texttt{\mdseries\slshape strings}}, \mbox{\texttt{\mdseries\slshape options}}\texttt{)}. 4245 4246 We continue the example from \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) and install a handler for the \texttt{{\textless}Wrap Name="Package"{\textgreater}}-element such that {\LaTeX} puts its content in a sans serif font. 4247\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 4248 !gapprompt@gap>| !gapinput@AddHandlerBuildRecBibXMLEntry("Wrap:Package", "BibTeX",| 4249 !gapprompt@>| !gapinput@function(entry, r, restype, strings, options)| 4250 !gapprompt@>| !gapinput@ return Concatenation("\\textsf{", ContentBuildRecBibXMLEntry(| 4251 !gapprompt@>| !gapinput@ entry, r, restype, strings, options), "}");| 4252 !gapprompt@>| !gapinput@end);| 4253 !gapprompt@gap>| !gapinput@| 4254 !gapprompt@gap>| !gapinput@Print(RecBibXMLEntry(e, "BibTeX", strs).title, "\n");| 4255 The \textsf{ {F}ritz} package for the 4256 formula $x^y - l_{{i+1}} \rightarrow \mathbb{R}$ 4257 !gapprompt@gap>| !gapinput@Print(RecBibXMLEntry(e, "Text", strs).title, "\n"); | 4258 The Fritz package for the 4259 formula x^y - l_{i+1} -> R 4260 !gapprompt@gap>| !gapinput@AddHandlerBuildRecBibXMLEntry("Wrap:Package", "BibTeX", "Ignore");| 4261\end{Verbatim} 4262 } 4263 4264 4265 4266\subsection{\textcolor{Chapter }{StringBibXMLEntry}} 4267\logpage{[ 7, 3, 9 ]}\nobreak 4268\hyperdef{L}{X790A295680F7CD24}{} 4269{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{StringBibXMLEntry({\mdseries\slshape entry[, restype][, strings][, options]})\index{StringBibXMLEntry@\texttt{StringBibXMLEntry}} 4270\label{StringBibXMLEntry} 4271}\hfill{\scriptsize (function)}}\\ 4272\textbf{\indent Returns:\ } 4273a string 4274 4275 4276 4277 The arguments of this function have the same meaning as in \texttt{RecBibXMLEntry} (\ref{RecBibXMLEntry}) but the return value is a string representing the bibliography entry in a 4278format specified by \mbox{\texttt{\mdseries\slshape restype}} (default is \texttt{"BibTeX"}). 4279 4280 Currently, the following cases for \mbox{\texttt{\mdseries\slshape restype}} are supported: 4281\begin{description} 4282\item[{\texttt{"BibTeX"}}] A string with Bib{\TeX} source code is generated. 4283\item[{\texttt{"Text"}}] A text representation of the text is returned. If \texttt{options.ansi} is bound it must be a record. The components must have names \texttt{Bib{\textunderscore}Label}, \texttt{Bib{\textunderscore}author}, and so on for all fieldnames. The value of each component is a pair of 4284strings which will enclose the content of the field in the result or the first 4285of these strings in which case the default for the second is \texttt{TextAttr.reset} (see \texttt{TextAttr} (\ref{TextAttr})). If you give an empty record here, some default ANSI color markup will be 4286used. 4287\item[{\texttt{"HTML"}}] An HTML representation of the bibliography entry is returned. The text from 4288each field is enclosed in markup (mostly \texttt{{\textless}span{\textgreater}}-elements) with the \texttt{class} attribute set to the field name. This allows a detailed layout of the code via 4289a style sheet file. If \texttt{options.MathJax} is bound and has the value \texttt{true} then formulae are encoded for display on pages with \textsf{MathJax} support. 4290\end{description} 4291 We use again the file shown in the example for \texttt{ParseBibXMLextFiles} (\ref{ParseBibXMLextFiles}). 4292\begin{Verbatim}[commandchars=!|C,fontsize=\small,frame=single,label=Example] 4293 !gapprompt|gap>C !gapinput|bib := ParseBibXMLextFiles("doc/testbib.xml");;C 4294 !gapprompt|gap>C !gapinput|e := bib.entries[1];; strs := bib.strings;;C 4295 !gapprompt|gap>C !gapinput|ebib := StringBibXMLEntry(e, "BibTeX", strs);;C 4296 !gapprompt|gap>C !gapinput|PrintFormattedString(ebib);C 4297 @article{ AB2000, 4298 author = {First, F. A. and Sec{\H o}nd, X. Y.}, 4299 title = {The {F}ritz package for the formula $x^y - 4300 l_{{i+1}} \rightarrow \mathbb{R}$}, 4301 journal = {Important Journal}, 4302 number = {13}, 4303 year = {2000}, 4304 pages = {13{\textendash}25}, 4305 note = {Online data at \href 4306 {http://www.publish.com/~ImpJ/123#data} {Bla 4307 Bla Publisher}}, 4308 mycomment = {very useful}, 4309 printedkey = {FS00} 4310 } 4311 !gapprompt|gap>C !gapinput|etxt := StringBibXMLEntry(e, "Text", strs);; C 4312 !gapprompt|gap>C !gapinput|etxt := SimplifiedUnicodeString(Unicode(etxt), "latin1", "single");;C 4313 !gapprompt|gap>C !gapinput|etxt := Encode(etxt, GAPInfo.TermEncoding);; C 4314 !gapprompt|gap>C !gapinput|PrintFormattedString(etxt);C 4315 [FS00] First, F. A. and Second, X. Y., The Fritz package for the 4316 formula x^y - l_{i+1} ? R, Important Journal, 13 (2000), 13-25, 4317 (Online data at Bla Bla Publisher 4318 (http://www.publish.com/~ImpJ/123#data)). 4319 !gapprompt|gap>C !gapinput|ehtml := StringBibXMLEntry(e, "HTML", strs, rec(MathJax := true));;C 4320 !gapprompt|gap>C !gapinput|ehtml := Encode(Unicode(ehtml), GAPInfo.TermEncoding);;C 4321 !gapprompt|gap>C !gapinput|PrintFormattedString(ehtml);C 4322 <p class='BibEntry'> 4323 [<span class='BibKey'>FS00</span>] 4324 <b class='BibAuthor'>First, F. A. and Second, X. Y.</b>, 4325 <i class='BibTitle'>The Fritz package for the 4326 formula \(x^y - l_{{i+1}} \rightarrow \mathbb{R}\)</i>, 4327 <span class='BibJournal'>Important Journal</span> 4328 (<span class='BibNumber'>13</span>) 4329 (<span class='BibYear'>2000</span>), 4330 <span class='BibPages'>13-25</span><br /> 4331 (<span class='BibNote'>Online data at 4332 <a href="http://www.publish.com/~ImpJ/123#data">Bla Bla 4333 Publisher</a></span>). 4334 </p> 4335 4336\end{Verbatim} 4337 } 4338 4339 The following command may be useful to generate completly new bibliography 4340entries in BibXMLext format. It also informs about the supported entry types 4341and field names. 4342 4343\subsection{\textcolor{Chapter }{TemplateBibXML}} 4344\logpage{[ 7, 3, 10 ]}\nobreak 4345\hyperdef{L}{X7C6FF57087016019}{} 4346{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{TemplateBibXML({\mdseries\slshape [type]})\index{TemplateBibXML@\texttt{TemplateBibXML}} 4347\label{TemplateBibXML} 4348}\hfill{\scriptsize (function)}}\\ 4349\textbf{\indent Returns:\ } 4350list of types or string 4351 4352 4353 4354 Without an argument this function returns a list of the supported entry types 4355in BibXMLext documents. 4356 4357 With an argument \mbox{\texttt{\mdseries\slshape type}} of one of the supported types the function returns a string which is a 4358template for a corresponding BibXMLext entry. Optional field elements have a \texttt{*} appended. If an element has the word \texttt{OR} appended, then either this element or the next must/can be given, not both. If \texttt{AND/OR} is appended then this and/or the next can/must be given. Elements which can 4359appear several times have a \texttt{+} appended. Places to fill are marked by an \texttt{X}. 4360\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 4361 !gapprompt@gap>| !gapinput@TemplateBibXML();| 4362 [ "article", "book", "booklet", "conference", "inbook", 4363 "incollection", "inproceedings", "manual", "mastersthesis", "misc", 4364 "phdthesis", "proceedings", "techreport", "unpublished" ] 4365 !gapprompt@gap>| !gapinput@Print(TemplateBibXML("inbook"));| 4366 <entry id="X"><inbook> 4367 <author> 4368 <name><first>X</first><last>X</last></name>+ 4369 </author>OR 4370 <editor> 4371 <name><first>X</first><last>X</last></name>+ 4372 </editor> 4373 <title>X</title> 4374 <chapter>X</chapter>AND/OR 4375 <pages>X</pages> 4376 <publisher>X</publisher> 4377 <year>X</year> 4378 <volume>X</volume>*OR 4379 <number>X</number>* 4380 <series>X</series>* 4381 <type>X</type>* 4382 <address>X</address>* 4383 <edition>X</edition>* 4384 <month>X</month>* 4385 <note>X</note>* 4386 <key>X</key>* 4387 <annotate>X</annotate>* 4388 <crossref>X</crossref>* 4389 <abstract>X</abstract>* 4390 <affiliation>X</affiliation>* 4391 <contents>X</contents>* 4392 <copyright>X</copyright>* 4393 <isbn>X</isbn>*OR 4394 <issn>X</issn>* 4395 <keywords>X</keywords>* 4396 <language>X</language>* 4397 <lccn>X</lccn>* 4398 <location>X</location>* 4399 <mrnumber>X</mrnumber>* 4400 <mrclass>X</mrclass>* 4401 <mrreviewer>X</mrreviewer>* 4402 <price>X</price>* 4403 <size>X</size>* 4404 <url>X</url>* 4405 <category>X</category>* 4406 <other type="X">X</other>*+ 4407 </inbook></entry> 4408\end{Verbatim} 4409 } 4410 4411 } 4412 4413 4414\section{\textcolor{Chapter }{Getting Bib{\TeX} entries from \textsf{MathSciNet}}}\label{MathSciNet} 4415\logpage{[ 7, 4, 0 ]} 4416\hyperdef{L}{X842336AF7B20048E}{} 4417{ 4418 We provide utilities to access the \href{http://www.ams.org/mathscinet/} {\textsf{ MathSciNet}} data base from within GAP. The first condition for this to work is that one of 4419the programs \texttt{wget} or \texttt{curl} is installed on your system. The second is, of course, that you use these 4420functions from a computer which has access to \textsf{MathSciNet}. 4421 4422 Please note, that the usual license for \textsf{MathSciNet} access does not allow for automated searches in the database. Therefore, only 4423use the \texttt{SearchMR} (\ref{SearchMR}) function for single queries, as you would do using your webbrowser. 4424 4425 4426 4427\subsection{\textcolor{Chapter }{SearchMR}} 4428\logpage{[ 7, 4, 1 ]}\nobreak 4429\hyperdef{L}{X8009F8A17DDFF9AF}{} 4430{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SearchMR({\mdseries\slshape qurec})\index{SearchMR@\texttt{SearchMR}} 4431\label{SearchMR} 4432}\hfill{\scriptsize (function)}}\\ 4433\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SearchMRBib({\mdseries\slshape bib})\index{SearchMRBib@\texttt{SearchMRBib}} 4434\label{SearchMRBib} 4435}\hfill{\scriptsize (function)}}\\ 4436\textbf{\indent Returns:\ } 4437a list of strings, a string or \texttt{fail} 4438 4439 4440 4441 The first function \texttt{SearchMR} provides the same functionality as the Web interface \href{http://www.ams.org/mathscinet/} {\textsf{ MathSciNet}}. The query strings must be given as a record, and the following components of 4442this record are recognized: \texttt{Author}, \texttt{AuthorRelated}, \texttt{Title}, \texttt{ReviewText}, \texttt{Journal}, \texttt{InstitutionCode}, \texttt{Series}, \texttt{MSCPrimSec}, \texttt{MSCPrimary}, \texttt{MRNumber}, \texttt{Anywhere}, \texttt{References} and \texttt{Year}. 4443 4444 Furthermore, the component \texttt{type} can be specified. It can be one of \texttt{"bibtex"} (the default if not given), \texttt{"pdf"}, \texttt{"html"} and probably others. In the last cases the function returns a string with the 4445content of the web page returned by \textsf{MathSciNet}. In the first case the \textsf{MathSciNet} interface returns a web page with Bib{\TeX} entries, for convenience this function returns a list of strings, each 4446containing the Bib{\TeX} text for a single result entry. 4447 4448 If a component \texttt{uri} is bound and set to \texttt{true} the function does not actually send a request to \textsf{MathSciNet} but returns a string with the URI that can be called for the request. 4449 4450 The format of a \texttt{.Year} component can be either a four digit number, optionally preceded by one of the 4451characters \texttt{'{\textless}'}, \texttt{'{\textgreater}'} or \texttt{'='}, or it can be two four digit numbers separated by a \texttt{-} to specify a year range. 4452 4453 The function \texttt{SearchMRBib} gets a record of a parsed Bib{\TeX} entry as input as returned by \texttt{ParseBibFiles} (\ref{ParseBibFiles}) or \texttt{ParseBibStrings} (\ref{ParseBibStrings}). It tries to generate some sensible input from this information for \texttt{SearchMR} and calls that function. 4454 4455 4456\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example] 4457 !gapprompt@gap>| !gapinput@ll := SearchMR(rec(Author:="Gauss", Title:="Disquisitiones"));;| 4458 !gapprompt@gap>| !gapinput@ll2 := List(ll, HeuristicTranslationsLaTeX2XML.Apply);;| 4459 !gapprompt@gap>| !gapinput@bib := ParseBibStrings(Concatenation(ll2));;| 4460 !gapprompt@gap>| !gapinput@bibxml := List(bib[1], StringBibAsXMLext);;| 4461 !gapprompt@gap>| !gapinput@bib2 := ParseBibXMLextString(Concatenation(bibxml));;| 4462 !gapprompt@gap>| !gapinput@for b in bib2.entries do | 4463 !gapprompt@>| !gapinput@ PrintFormattedString(StringBibXMLEntry(b, "Text")); od; | 4464 [Gau95] Gauss, C. F., Disquisitiones arithmeticae, Academia 4465 Colombiana de Ciencias Exactas, F�sicas y Naturales, Bogot�, 4466 Colecci�n Enrique P�rez Arbel�ez [Enrique P�rez Arbel�ez 4467 Collection], 10 (1995), xliv+495 pages, (Translated from the Latin 4468 by Hugo Barrantes Campos, Michael Josephy and �ngel Ruiz Z��iga, 4469 With a preface by Ruiz Z��iga). 4470 4471 [Gau86] Gauss, C. F., Disquisitiones arithmeticae, Springer-Verlag, 4472 New York (1986), xx+472 pages, (Translated and with a preface by 4473 Arthur A. Clarke, Revised by William C. Waterhouse, Cornelius 4474 Greither and A. W. Grootendorst and with a preface by Waterhouse). 4475 4476 [Gau66] Gauss, C. F., Disquisitiones arithmeticae, Yale University 4477 Press, New Haven, Conn.-London, Translated into English by Arthur A. 4478 Clarke, S. J (1966), xx+472 pages. 4479 4480\end{Verbatim} 4481 } 4482 4483 } 4484 4485 } 4486 4487 4488 4489\appendix 4490 4491 4492\chapter{\textcolor{Chapter }{The File \texttt{3k+1.xml}}}\label{app:3k+1} 4493\logpage{[ "A", 0, 0 ]} 4494\hyperdef{L}{X830C58F97F9CD901}{} 4495{ 4496 Here is the complete source of the example \textsf{GAPDoc} document \texttt{3k+1.xml} discussed in Section{\nobreakspace}\ref{sec:3k+1expl}. 4497\begin{Verbatim}[fontsize=\small,frame=single,label=3k+1.xml] 4498 <?xml version="1.0" encoding="UTF-8"?> 4499 4500 <!-- A complete "fake package" documentation 4501 --> 4502 4503 <!DOCTYPE Book SYSTEM "gapdoc.dtd"> 4504 4505 <Book Name="3k+1"> 4506 4507 <TitlePage> 4508 <Title>The <Package>ThreeKPlusOne</Package> Package</Title> 4509 <Version>Version 42</Version> 4510 <Author>Dummy Auth�r 4511 <Email>3kplusone@dev.null</Email> 4512 </Author> 4513 4514 <Copyright>©right; 2000 The Author. <P/> 4515 You can do with this package what you want.<P/> Really. 4516 </Copyright> 4517 </TitlePage> 4518 4519 <TableOfContents/> 4520 4521 <Body> 4522 <Chapter> <Heading>The <M>3k+1</M> Problem</Heading> 4523 <Section Label="sec:theory"> <Heading>Theory</Heading> 4524 Let <M>k \in &NN;</M> be a natural number. We consider the 4525 sequence <M>n(i, k), i \in &NN;,</M> with <M>n(1, k) = k</M> and 4526 else <M>n(i+1, k) = n(i, k) / 2</M> if <M>n(i, k)</M> is even 4527 and <M>n(i+1, k) = 3 n(i, k) + 1</M> if <M>n(i, k)</M> is odd. 4528 <P/> It is not known whether for any natural number <M>k \in 4529 &NN;</M> there is an <M>m \in &NN;</M> with <M>n(m, k) = 1</M>. 4530 <P/> 4531 <Package>ThreeKPlusOne</Package> provides the function <Ref 4532 Func="ThreeKPlusOneSequence"/> to explore this for given 4533 <M>n</M>. If you really want to know something about this 4534 problem, see <Cite Key="Wi98"/> or 4535 <URL>http://www.ku.de/mgf/mathematik/lehrstuhlstatistik/team/dr-guenther-wirsching/</URL> 4536 for more details (and forget this package). 4537 </Section> 4538 4539 <Section> <Heading>Program</Heading> 4540 In this section we describe the main function of this package. 4541 <ManSection> 4542 <Func Name="ThreeKPlusOneSequence" Arg="k[, max]"/> 4543 <Description> 4544 This function computes for a natural number <A>k</A> the 4545 beginning of the sequence <M>n(i, k)</M> defined in section 4546 <Ref Sect="sec:theory"/>. The sequence stops at the first 4547 <M>1</M> or at <M>n(<A>max</A>, k)</M>, if <A>max</A> is 4548 given. 4549 <Example> 4550 gap> ThreeKPlusOneSequence(101); 4551 "Sorry, not yet implemented. Wait for Version 84 of the package" 4552 </Example> 4553 </Description> 4554 </ManSection> 4555 </Section> 4556 </Chapter> 4557 </Body> 4558 4559 <Bibliography Databases="3k+1" /> 4560 <TheIndex/> 4561 4562 </Book> 4563 4564\end{Verbatim} 4565 } 4566 4567 4568\chapter{\textcolor{Chapter }{The File \texttt{gapdoc.dtd}}}\label{GAPDocdtd} 4569\logpage{[ "B", 0, 0 ]} 4570\hyperdef{L}{X85366C6480D58C51}{} 4571{ 4572 For easier reference we repeat here the complete content of the file \texttt{gapdoc.dtd}. 4573\begin{Verbatim}[fontsize=\small,frame=single,label=gapdoc.dtd] 4574 <?xml version="1.0" encoding="UTF-8"?> 4575 <!-- ================================================================== 4576 gapdoc.dtd - XML Document type definition for GAP documentation 4577 By Frank L�beck and Max Neunh�ffer 4578 ================================================================== --> 4579 4580 4581 <!-- Note that this definition goes "bottom-up" because entities can only 4582 be used after their definition in the file. --> 4583 4584 4585 <!-- ================================================================== 4586 Some entities: 4587 ================================================================== --> 4588 4589 <!-- The standard XML entities: --> 4590 4591 <!ENTITY lt "&#60;"> 4592 <!ENTITY gt ">"> 4593 <!ENTITY amp "&#38;"> 4594 <!ENTITY apos "'"> 4595 <!ENTITY quot """> 4596 4597 4598 <!-- The following were introduced in GAPDoc version < 1.0, it is no longer 4599 necessary to take care of LaTeX special characters 4600 (we keep the entities with simplified definitions for compatibility) --> 4601 4602 <!ENTITY tamp "&"> 4603 <!ENTITY tlt "<"> 4604 <!ENTITY tgt ">"> 4605 <!ENTITY hash "#"> 4606 <!ENTITY dollar "$"> 4607 <!ENTITY percent "%"> 4608 <!ENTITY tilde "~"> 4609 <!ENTITY bslash "\\"> 4610 <!ENTITY obrace "{"> 4611 <!ENTITY cbrace "}"> 4612 <!ENTITY uscore "_"> 4613 <!ENTITY circum "^"> 4614 4615 <!-- ================================================================== 4616 Our predefined entities: 4617 ================================================================== --> 4618 4619 <!ENTITY nbsp " "> 4620 <!ENTITY ndash "–"> 4621 <!ENTITY GAP "<Package>GAP</Package>"> 4622 <!ENTITY GAPDoc "<Package>GAPDoc</Package>"> 4623 <!ENTITY TeX 4624 "<Alt Only='LaTeX'>{\TeX}</Alt><Alt Not='LaTeX'>TeX</Alt>"> 4625 <!ENTITY LaTeX 4626 "<Alt Only='LaTeX'>{\LaTeX}</Alt><Alt Not='LaTeX'>LaTeX</Alt>"> 4627 <!ENTITY BibTeX 4628 "<Alt Only='LaTeX'>{Bib\TeX}</Alt><Alt Not='LaTeX'>BibTeX</Alt>"> 4629 <!ENTITY MeatAxe "<Package>MeatAxe</Package>"> 4630 <!ENTITY XGAP "<Package>XGAP</Package>"> 4631 <!ENTITY copyright "©"> 4632 4633 <!-- and unicode math symbols --> 4634 <!ENTITY CC "ℂ" > <!-- double struck --> 4635 <!ENTITY ZZ "ℤ" > 4636 <!ENTITY NN "ℕ" > 4637 <!ENTITY PP "ℙ" > 4638 <!ENTITY QQ "ℚ" > 4639 <!ENTITY HH "ℍ" > 4640 <!ENTITY RR "ℝ" > 4641 4642 4643 <!-- ================================================================== 4644 The following describes the "innermost" documentation text which 4645 can occur at various places in the document like for example 4646 section headings. It does neither contain further sectioning 4647 elements nor environments like Enums or Lists. 4648 ================================================================== --> 4649 4650 <!ENTITY % InnerText "#PCDATA | 4651 Alt | 4652 Emph | E | 4653 Par | P | Br | 4654 Keyword | K | Arg | A | Quoted | Q | Code | C | 4655 File | F | Button | B | Package | 4656 M | Math | Display | 4657 Example | Listing | Log | Verb | 4658 URL | Email | Homepage | Address | Cite | Label | 4659 Ref | Index | 4660 Ignore" > 4661 4662 4663 <!ELEMENT Alt (%InnerText;)*> <!-- This is only to allow "Only" and 4664 "Not" attributes for normal text --> 4665 <!ATTLIST Alt Only CDATA #IMPLIED 4666 Not CDATA #IMPLIED> 4667 4668 <!-- The following elements declare a certain block of InnerText to 4669 have a certain property. They are non-terminal and can contain 4670 any InnerText recursively. --> 4671 4672 <!ELEMENT Emph (%InnerText;)*> <!-- Emphasize something --> 4673 <!ELEMENT E (%InnerText;)*> <!-- the same as shortcut --> 4674 4675 4676 <!-- The following is an empty element marking a paragraph boundary. --> 4677 4678 <!ELEMENT Par EMPTY> <!-- this is intentionally empty! --> 4679 <!ELEMENT P EMPTY> <!-- the same as shortcut --> 4680 4681 <!-- And here is an element for forcing a line break, not starting 4682 a new paragraph. --> 4683 4684 <!ELEMENT Br EMPTY> <!-- a forced line break --> 4685 4686 <!-- The following elements mark a word or sentence to be of a certain 4687 kind, such that it can be typeset differently. They are terminal 4688 elements that should only contain character data. But we have to 4689 allow Alt elements for handling special characters. For these 4690 elements we introduce a long name - which is easy to remember - 4691 and a short name - which you may prefer because of the shorter 4692 markup. --> 4693 4694 <!ELEMENT Keyword (#PCDATA|Alt)*> <!-- Keyword --> 4695 <!ELEMENT K (#PCDATA|Alt)*> <!-- Keyword (shortcut) --> 4696 4697 <!ELEMENT Arg (#PCDATA|Alt)*> <!-- Argument --> 4698 <!ELEMENT A (#PCDATA|Alt)*> <!-- Argument (shortcut) --> 4699 4700 <!ELEMENT Code (#PCDATA|Alt|A|Arg)*> <!-- GAP code --> 4701 <!ELEMENT C (#PCDATA|Alt|A|Arg)*> <!-- GAP code (shortcut) --> 4702 4703 <!ELEMENT File (#PCDATA|Alt)*> <!-- Filename --> 4704 <!ELEMENT F (#PCDATA|Alt)*> <!-- Filename (shortcut) --> 4705 4706 <!ELEMENT Button (#PCDATA|Alt)*> <!-- "Button" (also Menu, Key) --> 4707 <!ELEMENT B (#PCDATA|Alt)*> <!-- "Button" (shortcut) --> 4708 4709 <!ELEMENT Package (#PCDATA|Alt)*> <!-- A package name --> 4710 4711 <!ELEMENT Quoted (%InnerText;)*> <!-- Quoted (in quotes) text --> 4712 <!ELEMENT Q (%InnerText;)*> <!-- Quoted text (shortcut) --> 4713 4714 4715 <!-- The following elements contain mathematical formulae. They are 4716 terminal elements that contain character data in TeX notation. --> 4717 4718 <!-- Math with well defined translation to text output --> 4719 <!ELEMENT M (#PCDATA|A|Arg|Alt)*> 4720 <!-- Normal TeX math mode formula --> 4721 <!ELEMENT Math (#PCDATA|A|Arg|Alt)*> 4722 <!-- TeX displayed math mode formula --> 4723 <!ELEMENT Display (#PCDATA|A|Arg|Alt)*> 4724 <!-- Mode="M" causes <M>-style formatting --> 4725 <!ATTLIST Display Mode CDATA #IMPLIED> 4726 4727 4728 <!-- The following elements contain GAP related text like code, 4729 session logs or examples. They are all terminal elements and 4730 consist of character data which is normally typeset verbatim. The 4731 different types of the elements only control how they are 4732 treated. --> 4733 4734 <!ELEMENT Example (#PCDATA)> <!-- This is subject to the automatic 4735 example checking mechanism --> 4736 <!ELEMENT Log (#PCDATA)> <!-- This not --> 4737 <!ELEMENT Listing (#PCDATA)> <!-- This is just for code listings --> 4738 <!ATTLIST Listing Type CDATA #IMPLIED> <!-- a comment about the type of 4739 listed code, may appear in 4740 output --> 4741 4742 <!-- One further verbatim element, this is truely verbatim without 4743 any processing and intended for ASCII substitutes of complicated 4744 displayed formulae or tables. --> 4745 4746 <!ELEMENT Verb (#PCDATA)> 4747 4748 <!-- The following elements are for cross-referencing purposes like 4749 URLs, citations, references, and the index. All these elements 4750 are terminal and need special methods to make up the actual 4751 output during document generation. --> 4752 4753 <!ELEMENT URL (#PCDATA|Alt|Link|LinkText)*> <!-- Link, LinkText 4754 variant for case where text needs further markup --> 4755 <!ATTLIST URL Text CDATA #IMPLIED> <!-- This is for output formats 4756 that have links like HTML --> 4757 <!ELEMENT Link (%InnerText;)*> <!-- the URL --> 4758 <!ELEMENT LinkText (%InnerText;)*> <!-- text for links, can contain markup --> 4759 <!-- The following two are actually URLs, but the element name determines 4760 the type. --> 4761 <!ELEMENT Email (#PCDATA|Alt|Link|LinkText)*> 4762 <!ELEMENT Homepage (#PCDATA|Alt|Link|LinkText)*> 4763 4764 <!-- Those who still want to give postal addresses can use the following 4765 element. Use <Br/> for specifying typical line breaks --> 4766 4767 <!ELEMENT Address (#PCDATA|Alt|Br)*> 4768 4769 <!ELEMENT Cite EMPTY> 4770 <!ATTLIST Cite Key CDATA #REQUIRED 4771 Where CDATA #IMPLIED> 4772 4773 <!ELEMENT Label EMPTY> 4774 <!ATTLIST Label Name CDATA #REQUIRED> 4775 4776 <!ELEMENT Ref EMPTY> 4777 <!ATTLIST Ref Func CDATA #IMPLIED 4778 Oper CDATA #IMPLIED 4779 Constr CDATA #IMPLIED 4780 Meth CDATA #IMPLIED 4781 Filt CDATA #IMPLIED 4782 Prop CDATA #IMPLIED 4783 Attr CDATA #IMPLIED 4784 Var CDATA #IMPLIED 4785 Fam CDATA #IMPLIED 4786 InfoClass CDATA #IMPLIED 4787 Chap CDATA #IMPLIED 4788 Sect CDATA #IMPLIED 4789 Subsect CDATA #IMPLIED 4790 Appendix CDATA #IMPLIED 4791 Text CDATA #IMPLIED 4792 4793 Label CDATA #IMPLIED 4794 BookName CDATA #IMPLIED 4795 Style (Text|Number) #IMPLIED> <!-- normally automatic --> 4796 4797 <!-- Note that only one attribute of Ref is used normally. BookName 4798 and Style can be specified in addition to handle external 4799 references and the typesetting style of the reference. --> 4800 4801 <!-- For explicit index entries (Func and so on should cause an 4802 automatically generated index entry). Use the attributes Key, 4803 Subkey for sorting (simplified, without markup). The Subkey value 4804 also gets printed. Use the optional Subkey element if the printed 4805 version needs some markup. --> 4806 <!ELEMENT Index (%InnerText;|Subkey)*> 4807 <!ATTLIST Index Key CDATA #IMPLIED 4808 Subkey CDATA #IMPLIED> 4809 <!ELEMENT Subkey (%InnerText;)*> 4810 4811 4812 <!-- ================================================================== 4813 The following describes the normal documentation text which can 4814 occur at various places in the document. It does not contain 4815 further sectioning elements. In addition to InnerText it can contain 4816 environments like enumerations, lists, and such. 4817 ================================================================== --> 4818 4819 <!ENTITY % Text "%InnerText; | List | Enum | Table"> 4820 4821 <!ELEMENT Item ( %Text;)*> 4822 <!ELEMENT Mark ( %InnerText;)*> 4823 4824 <!ELEMENT List ( ((Mark,Item)|Item)+ )> 4825 <!ATTLIST List Only CDATA #IMPLIED 4826 Not CDATA #IMPLIED> 4827 <!ELEMENT Enum ( Item+ )> 4828 <!ATTLIST Enum Only CDATA #IMPLIED 4829 Not CDATA #IMPLIED> 4830 4831 <!ELEMENT Table ( Caption?, (Row | HorLine)+ )> 4832 <!ATTLIST Table Label CDATA #IMPLIED 4833 Only CDATA #IMPLIED 4834 Not CDATA #IMPLIED 4835 Align CDATA #REQUIRED> <!-- A TeX tabular string --> 4836 <!-- We allow | and l,c,r, nothing else --> 4837 <!ELEMENT Row ( Item+ )> 4838 <!ELEMENT HorLine EMPTY> 4839 <!ELEMENT Caption ( %InnerText;)*> 4840 4841 <!-- ================================================================== 4842 We start defining some things within the overall structure: 4843 ================================================================== --> 4844 4845 <!-- The TitlePage consists of several sub-elements: --> 4846 4847 <!ELEMENT TitlePage (Title, Subtitle?, Version?, TitleComment?, 4848 Author+, Date?, Address?, Abstract?, Copyright?, 4849 Acknowledgements? , Colophon? )> 4850 4851 <!ELEMENT Title (%Text;)*> 4852 <!ELEMENT Subtitle (%Text;)*> 4853 <!ELEMENT Version (%Text;)*> 4854 <!ELEMENT TitleComment (%Text;)*> 4855 <!ELEMENT Author (%Text;)*> <!-- There may be more than one Author! --> 4856 <!ELEMENT Date (%Text;)*> 4857 <!ELEMENT Abstract (%Text;)*> 4858 <!ELEMENT Copyright (%Text;)*> 4859 <!ELEMENT Acknowledgements (%Text;)*> 4860 <!ELEMENT Colophon (%Text;)*> 4861 4862 4863 <!-- The following things just specify some information about the 4864 corresponding parts of the Book: --> 4865 4866 <!ELEMENT TableOfContents EMPTY> 4867 <!ELEMENT Bibliography EMPTY> 4868 <!ATTLIST Bibliography Databases CDATA #REQUIRED 4869 Style CDATA #IMPLIED> 4870 <!ELEMENT TheIndex EMPTY> 4871 4872 <!-- ================================================================== 4873 The Ignore element can be used everywhere to include further 4874 information in a GAPDoc document which is not intended for the 4875 standard converters (e.g., source code, not yet finished stuff, 4876 and so on. This information can be extracted by special converter 4877 routines, more precise information about the content of an Ignore 4878 element can be given by the "Remark" attribute. 4879 ================================================================== --> 4880 4881 <!ELEMENT Ignore (%Text;| Chapter | Section | Subsection | ManSection | 4882 Heading)*> 4883 <!ATTLIST Ignore Remark CDATA #IMPLIED> 4884 4885 <!-- ================================================================== 4886 Now we go on with the overall structure by defining the sectioning 4887 structure, which includes the Synopsis element: 4888 ================================================================== --> 4889 4890 4891 <!ELEMENT Subsection (%Text;| Heading)*> 4892 <!ATTLIST Subsection Label CDATA #IMPLIED> <!-- For reference purposes --> 4893 4894 <!ELEMENT ManSection ( Heading?, 4895 ((Func, Returns?) | (Oper, Returns?) | 4896 (Meth, Returns?) | (Filt, Returns?) | 4897 (Prop, Returns?) | (Attr, Returns?) | 4898 (Constr, Returns?) | 4899 Var | Fam | InfoClass)+, Description )> 4900 <!ATTLIST ManSection Label CDATA #IMPLIED> <!-- For reference purposes --> 4901 4902 <!ELEMENT Returns (%Text;)*> 4903 <!ELEMENT Description (%Text;)*> 4904 4905 4906 <!-- Note that the ManSection element is actually a subsection with 4907 respect to labelling, referencing, and counting of sectioning 4908 elements. --> 4909 4910 <!ELEMENT Func EMPTY> 4911 <!ATTLIST Func Name CDATA #REQUIRED 4912 Label CDATA #IMPLIED 4913 Arg CDATA #REQUIRED 4914 Comm CDATA #IMPLIED> 4915 4916 <!-- Note that Arg contains the full list of arguments, including 4917 optional parts, which are denoted by square brackets []. 4918 Arguments are separated by whitespace, commas count as 4919 whitespace. --> 4920 4921 <!-- Note further that although Name and Label are CDATA (and not ID) 4922 Label must make up a unique identifier. --> 4923 4924 <!ELEMENT Oper EMPTY> 4925 <!ATTLIST Oper Name CDATA #REQUIRED 4926 Label CDATA #IMPLIED 4927 Arg CDATA #REQUIRED 4928 Comm CDATA #IMPLIED> 4929 4930 <!ELEMENT Constr EMPTY> 4931 <!ATTLIST Constr Name CDATA #REQUIRED 4932 Label CDATA #IMPLIED 4933 Arg CDATA #REQUIRED 4934 Comm CDATA #IMPLIED> 4935 4936 <!ELEMENT Meth EMPTY> 4937 <!ATTLIST Meth Name CDATA #REQUIRED 4938 Label CDATA #IMPLIED 4939 Arg CDATA #REQUIRED 4940 Comm CDATA #IMPLIED> 4941 4942 <!ELEMENT Filt EMPTY> 4943 <!ATTLIST Filt Name CDATA #REQUIRED 4944 Label CDATA #IMPLIED 4945 Arg CDATA #IMPLIED 4946 Comm CDATA #IMPLIED 4947 Type CDATA #IMPLIED> 4948 4949 <!ELEMENT Prop EMPTY> 4950 <!ATTLIST Prop Name CDATA #REQUIRED 4951 Label CDATA #IMPLIED 4952 Arg CDATA #REQUIRED 4953 Comm CDATA #IMPLIED> 4954 4955 <!ELEMENT Attr EMPTY> 4956 <!ATTLIST Attr Name CDATA #REQUIRED 4957 Label CDATA #IMPLIED 4958 Arg CDATA #REQUIRED 4959 Comm CDATA #IMPLIED> 4960 4961 <!ELEMENT Var EMPTY> 4962 <!ATTLIST Var Name CDATA #REQUIRED 4963 Label CDATA #IMPLIED 4964 Comm CDATA #IMPLIED> 4965 4966 <!ELEMENT Fam EMPTY> 4967 <!ATTLIST Fam Name CDATA #REQUIRED 4968 Label CDATA #IMPLIED 4969 Comm CDATA #IMPLIED> 4970 4971 <!ELEMENT InfoClass EMPTY> 4972 <!ATTLIST InfoClass Name CDATA #REQUIRED 4973 Label CDATA #IMPLIED 4974 Comm CDATA #IMPLIED> 4975 4976 4977 <!ELEMENT Heading (%InnerText;)*> 4978 4979 <!ELEMENT Section (%Text;| Heading | Subsection | ManSection)*> 4980 <!ATTLIST Section Label CDATA #IMPLIED> <!-- For reference purposes --> 4981 4982 4983 <!ELEMENT Chapter (%Text;| Heading | Section)*> 4984 <!ATTLIST Chapter Label CDATA #IMPLIED> <!-- For reference purposes --> 4985 4986 4987 <!-- Note that the entity %InnerText; is documentation that contains 4988 neither sectioning elements nor environments like enumerations, 4989 but only formulae, labels, references, citations, and other 4990 terminal elements. --> 4991 4992 <!ELEMENT Appendix (%Text;| Heading | Section)*> 4993 <!ATTLIST Appendix Label CDATA #IMPLIED> <!-- For reference purposes --> 4994 4995 <!-- Note that an Appendix is exactly the same as a Chapter. They 4996 differ only in the numbering. --> 4997 4998 <!-- ================================================================== 4999 At last we define the overall structure of a gapdoc Book: 5000 ================================================================== --> 5001 5002 <!ELEMENT Body ( %Text;| Chapter | Section )*> 5003 5004 <!ELEMENT Book (TitlePage, 5005 TableOfContents?, 5006 Body, 5007 Appendix*, 5008 Bibliography?, 5009 TheIndex?)> 5010 <!ATTLIST Book Name CDATA #REQUIRED> 5011 5012 <!-- Note that the entity %Text; is documentation that contains 5013 no further sectioning elements but possibly environments like 5014 enumerations, and formulae, labels, references, and citations. 5015 --> 5016 5017 <!-- ============================================================== --> 5018 5019 5020\end{Verbatim} 5021 } 5022 5023 5024\chapter{\textcolor{Chapter }{The File \texttt{bibxmlext.dtd}}}\label{bibxmlextdtd} 5025\logpage{[ "C", 0, 0 ]} 5026\hyperdef{L}{X7E2788757A1AA098}{} 5027{ 5028 For easier reference we repeat here the complete content of the file \texttt{bibxmlext.dtd} which is explained in \ref{BibXMLformat}. 5029\begin{Verbatim}[fontsize=\small,frame=single,label=bibxmlext.dtd] 5030 <?xml version="1.0" encoding="UTF-8"?> 5031 <!-- 5032 - (C) Frank L�beck (http://www.math.rwth-aachen.de/~Frank.Luebeck) 5033 - 5034 - The BibXMLext data format. 5035 - 5036 - This DTD expresses XML markup similar to the BibTeX language 5037 - specified for LaTeX, or actually its content model. 5038 - 5039 - It is a variation of a file bibxml.dtd developed by the project 5040 - http://bibtexml.sf.net/ 5041 - 5042 - For documentation on BibTeX, see 5043 - http://www.ctan.org/tex-archive/biblio/bibtex/distribs/doc/ 5044 - 5045 - A previous version of the code originally developed by 5046 - Vidar Bronken Gundersen, http://bibtexml.sf.net/ 5047 - Reuse and repurposing is approved as long as this 5048 - notification appears with the code. 5049 - 5050 --> 5051 5052 <!-- ..................................................................... --> 5053 <!-- Main structure --> 5054 5055 <!-- key-value pairs as in BibTeX @string entries are put in empty elements 5056 (but here they can be used for parts of an entry field as well) --> 5057 <!ELEMENT string EMPTY> 5058 <!ATTLIST string 5059 key CDATA #REQUIRED 5060 value CDATA #REQUIRED > 5061 5062 <!-- entry may contain one of the bibliographic types. --> 5063 <!ELEMENT entry ( article | book | booklet | 5064 manual | techreport | 5065 mastersthesis | phdthesis | 5066 inbook | incollection | 5067 proceedings | inproceedings | 5068 conference | 5069 unpublished | misc ) > 5070 <!ATTLIST entry 5071 id CDATA #REQUIRED > 5072 5073 <!-- file is the documents top element. --> 5074 <!ELEMENT file ( string | entry )* > 5075 5076 5077 <!-- ..................................................................... --> 5078 <!-- Parameter entities --> 5079 5080 <!-- these are additional elements often used, but not included in the 5081 standard BibTeX distribution, these must be added to the 5082 bibliography styles, otherwise these fields will be omitted by 5083 the formatter, we allow an arbitrary number of 'other' elements 5084 to specify any further information --> 5085 5086 <!ENTITY % n.user " abstract?, affiliation?, 5087 contents?, copyright?, 5088 (isbn | issn)?, 5089 keywords?, language?, lccn?, 5090 location?, mrnumber?, mrclass?, mrreviewer?, 5091 price?, size?, url?, category?, other* "> 5092 5093 <!ENTITY % n.common "key?, annotate?, crossref?, 5094 %n.user;"> 5095 5096 <!-- content model used more than once --> 5097 5098 <!ENTITY % n.InProceedings "author, title, booktitle, 5099 year, editor?, 5100 (volume | number)?, 5101 series?, pages?, address?, 5102 month?, organization?, publisher?, 5103 note?, %n.common;"> 5104 5105 <!ENTITY % n.PHDThesis "author, title, school, 5106 year, type?, address?, month?, 5107 note?, %n.common;"> 5108 5109 <!-- ..................................................................... --> 5110 <!-- Entries in the BibTeX database --> 5111 5112 <!-- [article] An article from a journal or magazine. 5113 - Required fields: author, title, journal, year. 5114 - Optional fields: volume, number, pages, month, note. --> 5115 <!ELEMENT article (author, title, journal, 5116 year, volume?, number?, pages?, 5117 month?, note?, %n.common;) 5118 > 5119 5120 <!-- [book] A book with an explicit publisher. 5121 - Required fields: author or editor, title, publisher, year. 5122 - Optional fields: volume or number, series, address, 5123 - edition, month, note. --> 5124 <!ELEMENT book ((author | editor), title, 5125 publisher, year, (volume | number)?, 5126 series?, address?, edition?, month?, 5127 note?, %n.common;) 5128 > 5129 5130 <!-- [booklet] A work that is printed and bound, but without a named 5131 - publisher or sponsoring institution 5132 - Required field: title. 5133 - Optional fields: author, howpublished, address, month, year, note. --> 5134 <!ELEMENT booklet (author?, title, 5135 howpublished?, address?, month?, 5136 year?, note?, %n.common;) 5137 > 5138 5139 <!-- [conference] The same as INPROCEEDINGS, 5140 - included for Scribe compatibility. --> 5141 <!ELEMENT conference (%n.InProceedings;) 5142 > 5143 5144 <!-- [inbook] A part of a book, which may be a chapter (or section or 5145 - whatever) and/or a range of pages. 5146 - Required fields: author or editor, title, chapter and/or pages, 5147 - publisher, year. 5148 - Optional fields: volume or number, series, type, address, 5149 - edition, month, note. --> 5150 <!ELEMENT inbook ((author | editor), title, 5151 ((chapter, pages?) | pages), 5152 publisher, year, (volume | 5153 number)?, series?, type?, 5154 address?, edition?, month?, 5155 note?, %n.common;) 5156 > 5157 5158 <!-- 5159 - > I want to express that the elements a and/or b are legal that is one 5160 - > of them or both must be present in the document instance (see the 5161 - > element content for BibTeX entry `InBook'). 5162 - > How do I specify this in my DTD? 5163 - 5164 - Dave Peterson: 5165 - in content model: ((a , b?) | b) if order matters 5166 - ((a , b?) | (b , a?)) otherwise 5167 --> 5168 5169 <!-- [incollection] A part of a book having its own title. 5170 - Required fields: author, title, booktitle, publisher, year. 5171 - Optional fields: editor, volume or number, series, type, 5172 - chapter, pages, address, edition, month, note. --> 5173 <!ELEMENT incollection (author, title, 5174 booktitle, publisher, year, 5175 editor?, (volume | number)?, 5176 series?, type?, chapter?, 5177 pages?, address?, edition?, 5178 month?, note?, 5179 %n.common;) 5180 > 5181 5182 <!-- [inproceedings] An article in a conference proceedings. 5183 - Required fields: author, title, booktitle, year. 5184 - Optional fields: editor, volume or number, series, pages, 5185 - address, month, organization, publisher, note. --> 5186 <!ELEMENT inproceedings (%n.InProceedings;) 5187 > 5188 5189 <!-- [manual] Technical documentation 5190 - Required field: title. 5191 - Optional fields: author, organization, address, 5192 - edition, month, year, note. --> 5193 <!ELEMENT manual (author?, title, 5194 organization?, address?, edition?, 5195 month?, year?, note?, %n.common;) 5196 > 5197 5198 <!-- [mastersthesis] A Master's thesis. 5199 - Required fields: author, title, school, year. 5200 - Optional fields: type, address, month, note. --> 5201 <!ELEMENT mastersthesis (%n.PHDThesis;) 5202 > 5203 5204 <!-- [misc] Use this type when nothing else fits. 5205 - Required fields: none. 5206 - Optional fields: author, title, howpublished, month, year, note. --> 5207 <!ELEMENT misc (author?, title?, 5208 howpublished?, month?, year?, note?, 5209 %n.common;) 5210 > 5211 5212 <!-- [phdthesis] A PhD thesis. 5213 - Required fields: author, title, school, year. 5214 - Optional fields: type, address, month, note. --> 5215 <!ELEMENT phdthesis (%n.PHDThesis;) 5216 > 5217 5218 <!-- [proceedings] The proceedings of a conference. 5219 - Required fields: title, year. 5220 - Optional fields: editor, volume or number, series, 5221 - address, month, organization, publisher, note. --> 5222 <!ELEMENT proceedings (editor?, title, year, 5223 (volume | number)?, series?, 5224 address?, month?, organization?, 5225 publisher?, note?, %n.common;) 5226 > 5227 5228 <!-- [techreport] A report published by a school or other institution, 5229 - usually numbered within a series. 5230 - Required fields: author, title, institution, year. 5231 - Optional fields: type, number, address, month, note. --> 5232 <!ELEMENT techreport (author, title, 5233 institution, year, type?, number?, 5234 address?, month?, note?, %n.common;) 5235 > 5236 5237 <!-- [unpublished] A document having an author and title, but not 5238 - formally published. 5239 - Required fields: author, title, note. 5240 - Optional fields: month, year. --> 5241 <!ELEMENT unpublished (author, title, note, 5242 month?, year?, %n.common;) 5243 > 5244 5245 <!-- ..................................................................... --> 5246 <!-- Fields from the standard bibliography styles --> 5247 5248 <!-- 5249 - Below is a description of all fields recognized by the standard 5250 - bibliography styles. An entry can also contain other fields, which 5251 - are ignored by those styles. 5252 - 5253 - [address] Usually the address of the publisher or other type of 5254 - institution For major publishing houses, van~Leunen recommends 5255 - omitting the information entirely. For small publishers, on the other 5256 - hand, you can help the reader by giving the complete address. 5257 - 5258 - [annote] An annotation It is not used by the standard bibliography 5259 - styles, but may be used by others that produce an annotated 5260 - bibliography. 5261 - 5262 - [author] The name(s) of the author(s), here *not* in the format 5263 - described in the LaTeX book. Contains elements <name> which in turn 5264 - contains elements <first>, <last> for the first name (or first names, 5265 - fully written or as initials, and including middle initials) and 5266 - the last name. 5267 - 5268 - [booktitle] Title of a book, part of which is being cited. See the 5269 - LaTeX book for how to type titles. For book entries, use the title 5270 - field instead. 5271 - 5272 - [chapter] A chapter (or section or whatever) number. 5273 - 5274 - [crossref] The database key of the entry being cross referenced. 5275 - 5276 - [edition] The edition of a book-for example, ``Second''. This 5277 - should be an ordinal, and should have the first letter capitalized, as 5278 - shown here; the standard styles convert to lower case when necessary. 5279 - 5280 - [editor] Name(s) of editor(s), typed as indicated in the LaTeX book. 5281 - If there is also an author field, then the editor field gives the 5282 - editor of the book or collection in which the reference appears. 5283 - 5284 - [howpublished] How something strange has been published. The first 5285 - word should be capitalized. 5286 - 5287 - [institution] The sponsoring institution of a technical report. 5288 - 5289 - [journal] A journal name. Abbreviations are provided for many 5290 - journals; see the Local Guide. 5291 - 5292 - [key] Used for alphabetizing, cross referencing, and creating a label 5293 - when the ``author'' information (described in Section [ref: ] is 5294 - missing. This field should not be confused with the key that appears 5295 - in the \cite command and at the beginning of the database entry. 5296 - 5297 - [month] The month in which the work was published or, for an 5298 - unpublished work, in which it was written. You should use the 5299 - standard three-letter abbreviation, as described in Appendix B.1.3 of 5300 - the LaTeX book. 5301 - 5302 - [note] Any additional information that can help the reader. The first 5303 - word should be capitalized. 5304 - 5305 - [number] The number of a journal, magazine, technical report, or of a 5306 - work in a series. An issue of a journal or magazine is usually 5307 - identified by its volume and number; the organization that issues a 5308 - technical report usually gives it a number; and sometimes books are 5309 - given numbers in a named series. 5310 - 5311 - [organization] The organization that sponsors a conference or that 5312 - publishes a manual. 5313 - 5314 - [pages] One or more page numbers or range of numbers, such as 42-111 5315 - or 7,41,73-97 or 43+ (the `+' in this last example indicates pages 5316 - following that don't form a simple range). To make it easier to 5317 - maintain Scribe-compatible databases, the standard styles convert a 5318 - single dash (as in 7-33) to the double dash used in TeX to denote 5319 - number ranges (as in 7-33). Here, we suggest to use the entity 5320 - – for a dash in page ranges. 5321 - 5322 - [publisher] The publisher's name. 5323 - 5324 - [school] The name of the school where a thesis was written. 5325 - 5326 - [series] The name of a series or set of books. When citing an entire 5327 - book, the the title field gives its title and an optional series field 5328 - gives the name of a series or multi-volume set in which the book is 5329 - published. 5330 - 5331 - [title] The work's title. For mathematical formulae use the <M> or 5332 - <Math> elements explained below (and LaTeX code in the content, without 5333 - surrounding '$'). 5334 - 5335 - [type] The type of a technical report-for example, ``Research 5336 - Note''. 5337 - 5338 - [volume] The volume of a journal or multivolume book. 5339 - 5340 - [year] The year of publication or, for an unpublished work, the year 5341 - it was written. Generally it should consist of four numerals, such as 5342 - 1984, although the standard styles can handle any year whose last four 5343 - nonpunctuation characters are numerals, such as `(about 1984)'. 5344 --> 5345 5346 <!-- Here is the main extension compared to the original BibXML definition 5347 from which is DTD is derived: We want to allow more markup in some 5348 elements such that we can use the bibliography for high quality 5349 output in other formats than LaTeX. 5350 5351 - <M> and <Math>, mathematical formulae: Specify LaTeX code for "simple" 5352 formulae as content of <M> elements; "simple" means that they can be 5353 translated to a fairly readable ASCII representation as explained in 5354 the GAPDoc documentation on "<M>". 5355 More complicated formulae are given as content of <Math> elements. 5356 (Think about an <Alt> alternative for text or HTML representations.) 5357 5358 - <URL>: use these elements to specify URLs, they can be properly 5359 converted to links if possible in an output format (in that case 5360 the Text attribute is used for the visible text). 5361 5362 - <value key="..."/>: substituted by the value-attribute specified 5363 in a <string key="..." value="..."/> element. Can be used anywhere, 5364 not only for complete fields as in BibTeX. 5365 5366 - <C> protect case changes: should be used instead of {}'s which are 5367 used in BibTeX title fields to protect the case of letters from 5368 changes. 5369 5370 - <Alt Only="...">, <Alt Not="...">, alternatives for different 5371 output formats: Use this to specify alternatives, the GAPDoc 5372 utilities will do some special handling for "Text", "HTML", 5373 and "BibTeX" as output type. 5374 5375 - <Wrap Name="...">, generic wrapper for other markup: 5376 Use this for any other type of markup you are interested in. The 5377 GAPDoc utilities will ignore the markup, but provide a hook 5378 to do install handler functions for them. 5379 --> 5380 <!ELEMENT M (#PCDATA | Alt)* > <!-- math with simple text 5381 representation, in LaTeX --> 5382 <!ELEMENT Math (#PCDATA | Alt)* > <!-- other math in LaTeX --> 5383 <!ELEMENT URL (#PCDATA | Alt | Link | LinkText)* > <!-- an URL --> 5384 <!ATTLIST URL Text CDATA #IMPLIED> <!-- text to be printed 5385 (default is content) --> 5386 <!ELEMENT value EMPTY > <!-- placeholder for value given .. --> 5387 <!ATTLIST value key CDATA #REQUIRED > <!-- .. by key, defined in a string 5388 element --> 5389 <!ELEMENT C (#PCDATA | value | Alt | 5390 M | Math | Wrap | URL)* > <!-- protect from case changes --> 5391 <!ELEMENT Alt (#PCDATA | value | C | Alt | 5392 M | Math | Wrap | URL)* > <!-- specify alternatives for 5393 various types of output --> 5394 <!ATTLIST Alt Only CDATA #IMPLIED 5395 Not CDATA #IMPLIED > <!-- specify output types in comma and 5396 whitespace separated list (use exactly one of Only or Not) --> 5397 5398 <!ENTITY % withMURL "(#PCDATA | value | M | Math | Wrap | URL | C | Alt )*" > 5399 5400 <!ELEMENT Wrap %withMURL; > <!-- a generic wrapper --> 5401 <!ATTLIST Wrap Name CDATA #REQUIRED > <!-- needs a 'Name' attribute --> 5402 5403 <!ELEMENT address %withMURL; > 5404 <!-- here we don't want the complicated definition from the LaTeX book, 5405 use markup for first/last name(s): a <name> element for each 5406 author which contains <first> (optional), <last> elements: --> 5407 <!ELEMENT author (name)* > 5408 <!ELEMENT name (first?, last) > 5409 <!ELEMENT first (#PCDATA) > 5410 <!ELEMENT last (#PCDATA) > 5411 5412 <!ELEMENT booktitle %withMURL; > 5413 <!ELEMENT chapter %withMURL; > 5414 <!ELEMENT edition %withMURL; > 5415 <!-- same as for author field --> 5416 <!ELEMENT editor (name)* > 5417 <!ELEMENT howpublished %withMURL; > 5418 <!ELEMENT institution %withMURL; > 5419 <!ELEMENT journal %withMURL; > 5420 <!ELEMENT month %withMURL; > 5421 <!ELEMENT note %withMURL; > 5422 <!ELEMENT number %withMURL; > 5423 <!ELEMENT organization %withMURL; > 5424 <!ELEMENT pages %withMURL; > 5425 <!ELEMENT publisher %withMURL; > 5426 <!ELEMENT school %withMURL; > 5427 <!ELEMENT series %withMURL; > 5428 <!ELEMENT title %withMURL; > 5429 <!ELEMENT type %withMURL; > 5430 <!ELEMENT volume %withMURL; > 5431 <!ELEMENT year (#PCDATA) > 5432 5433 <!-- These were not listed in the documentation for entry content, but 5434 - appeared in the list of fields in the BibTeX documentation --> 5435 5436 <!ELEMENT annotate %withMURL; > 5437 <!ELEMENT crossref %withMURL; > 5438 <!ELEMENT key (#PCDATA) > 5439 5440 5441 <!-- ..................................................................... --> 5442 <!-- Other popular fields 5443 - 5444 - From: http://www.ecst.csuchico.edu/~jacobsd/bib/formats/bibtex.html 5445 - BibTeX is extremely popular, and many people have used it to store 5446 - information. Here is a list of some of the more common fields: 5447 - 5448 - [affiliation] The authors affiliation. 5449 - [abstract] An abstract of the work. 5450 - [contents] A Table of Contents 5451 - [copyright] Copyright information. 5452 - [ISBN] The International Standard Book Number. 5453 - [ISSN] The International Standard Serial Number. 5454 - Used to identify a journal. 5455 - [keywords] Key words used for searching or possibly for annotation. 5456 - [language] The language the document is in. 5457 - [location] A location associated with the entry, 5458 - such as the city in which a conference took place. 5459 - [LCCN] The Library of Congress Call Number. 5460 - I've also seen this as lib-congress. 5461 - [mrnumber] The Mathematical Reviews number. 5462 - [mrclass] The Mathematical Reviews class. 5463 - [mrreviewer] The Mathematical Reviews reviewer. 5464 - [price] The price of the document. 5465 - [size] The physical dimensions of a work. 5466 - [URL] The WWW Universal Resource Locator that points to the item being 5467 - referenced. This often is used for technical reports to point to the 5468 - ftp site where the postscript source of the report is located. 5469 - 5470 - When using BibTeX with LaTeX you need 5471 - BibTeX style files to print these data. 5472 --> 5473 5474 <!ELEMENT abstract %withMURL; > 5475 <!ELEMENT affiliation %withMURL; > 5476 <!ELEMENT contents %withMURL; > 5477 <!ELEMENT copyright %withMURL; > 5478 <!ELEMENT isbn (#PCDATA) > 5479 <!ELEMENT issn (#PCDATA) > 5480 <!ELEMENT keywords %withMURL; > 5481 <!ELEMENT language %withMURL; > 5482 <!ELEMENT lccn (#PCDATA) > 5483 <!ELEMENT location %withMURL; > 5484 <!ELEMENT mrnumber %withMURL; > 5485 <!ELEMENT mrclass %withMURL; > 5486 <!ELEMENT mrreviewer %withMURL; > 5487 <!ELEMENT price %withMURL; > 5488 <!ELEMENT size %withMURL; > 5489 <!ELEMENT url %withMURL; > 5490 5491 5492 <!-- Added by Zeger W. Hendrikse 5493 - [category] Category of this bibitem 5494 --> 5495 <!ELEMENT category %withMURL; > 5496 5497 <!-- A container element [other] for any further information, a description 5498 - of the type of data must be given in the attribute 'type' 5499 --> 5500 <!ELEMENT other %withMURL; > 5501 <!ATTLIST other 5502 type CDATA #REQUIRED > 5503 5504 5505 <!-- ..................................................................... --> 5506 <!-- Predefined/reserved character entities --> 5507 5508 <!ENTITY amp "&#38;"> 5509 <!ENTITY lt "&#60;"> 5510 <!ENTITY gt ">"> 5511 <!ENTITY apos "'"> 5512 <!ENTITY quot """> 5513 5514 5515 <!-- Some more generally useful entities --> 5516 <!ENTITY nbsp " "> 5517 <!ENTITY copyright "©"> 5518 <!ENTITY ndash "–"> 5519 5520 5521 <!-- ..................................................................... --> 5522 <!-- End of BibXMLext dtd --> 5523 5524\end{Verbatim} 5525 } 5526 5527\def\bibname{References\logpage{[ "Bib", 0, 0 ]} 5528\hyperdef{L}{X7A6F98FD85F02BFE}{} 5529} 5530 5531\bibliographystyle{alpha} 5532\bibliography{gapdocbib.xml} 5533 5534\addcontentsline{toc}{chapter}{References} 5535 5536\def\indexname{Index\logpage{[ "Ind", 0, 0 ]} 5537\hyperdef{L}{X83A0356F839C696F}{} 5538} 5539 5540\cleardoublepage 5541\phantomsection 5542\addcontentsline{toc}{chapter}{Index} 5543 5544 5545\printindex 5546 5547\newpage 5548\immediate\write\pagenrlog{["End"], \arabic{page}];} 5549\immediate\closeout\pagenrlog 5550\end{document} 5551