\documentclass[a4paper,11pt]{report} \addtolength{\topmargin}{-1in} \setlength{\textwidth}{6.0in} \setlength{\textheight}{9.5in} \addtolength{\oddsidemargin}{-0.7in} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \usepackage[english]{babel} \usepackage{graphicx} \usepackage{color} \usepackage{amssymb} %\usepackage[dvips]{changebar} %\renewcommand{\baselinestretch}{1.5} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newenvironment{code} { \renewcommand{\baselinestretch}{1} \footnotesize \begin{quote} } { \end{quote} \normalsize \renewcommand{\baselinestretch}{1.5} } \newenvironment{tblenv} { \renewcommand{\baselinestretch}{1} \begin{figure}[h] \begin{center} \footnotesize } { \normalsize \end{center} \end{figure} \renewcommand{\baselinestretch}{1.5} } % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newcommand{\book}[4]{#1. {\em #2}. #3, #4.} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newcommand{\lt}{$<$} \newcommand{\gt}{$>$} \newcommand{\back}{$\backslash$} \newcommand{\home}{\~{}} \newcommand{\da}{$\doublearrow$} \newcommand{\dad}{$\rightarrow$} \newcommand{\underlines}{\underline{\ }\ \underline{\ }\ \underline{\ }\ } % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newcommand{\lz}{$l_0$} \newcommand{\lo}{$l_1$} \newcommand{\uz}{$u_0$} \newcommand{\uo}{$u_1$} \newcommand{\ut}{$u_2$} \newcommand{\Tz}{$\mathsf{T_0}$} \newcommand{\To}{$\mathsf{T_1}$} \newcommand{\Tt}{$\mathsf{T_2}$} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newcommand{\lispt}{{\tt t}} \newcommand{\lispnil}{{\tt nil}} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newcommand{\lu}[1]{{\sffamily #1}} \newcommand{\luele}{\lu{Element}} \newcommand{\luheader}{\lu{Header}} \newcommand{\luelename}{\lu{Element~name}} \newcommand{\luattlist}{\lu{Attribute~list}} \newcommand{\luatt}{\lu{Attribute}} \newcommand{\luattname}{\lu{Attribute~name}} \newcommand{\luattvalue}{\lu{Attribute~value}} \newcommand{\luchardata}{\lu{CharData}} \newcommand{\lupi}{\lu{Processing~Instruction}} \newcommand{\lupitarget}{\lu{Processing~Instruction~Target}} \newcommand{\lupibody}{\lu{Processing~Instruction~Body}} \newcommand{\lucomment}{\lu{Comment}} \newcommand{\luintdtd}{\lu{Internal~DTD}} \newcommand{\luentref}{\lu{Entity~reference}} \newcommand{\logu}{logical unit} \newcommand{\logus}{logical units} \newcommand{\Logu}{Logical unit} \newcommand{\Logus}{Logical units} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newcommand{\logl}{logical line} \newcommand{\ebuf}{Ebuffer} \newcommand{\etree}{Etree} \newcommand{\traveller}{climbing transparency} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newcommand{\key}[1]{\framebox{#1}} \newcommand{\kl}{\key{$\leftarrow$}} \newcommand{\kr}{\key{$\rightarrow$}} \newcommand{\ku}{\key{$\uparrow$}} \newcommand{\kd}{\key{$\downarrow$}} \newcommand{\ra}{$\rightarrow$} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \newcommand{\C}{\color{red}} \newcommand{\todo}[1]{{\color{blue} \Large {\bf TODO:} \normalsize #1}} \newcommand{\todoweb}[1]{{\color{blue} \Large {\bf TODOWEB:} \normalsize #1}} \newcommand{\jbw}[1]{{\color{blue} \Large {\bf JBW:} \normalsize #1}} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \renewcommand{\baselinestretch}{1.5} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \title{Emaxml {\Large }\\ \textbf{\large An Emacs mode for editing XML}\large } \author{Paolo Debetto\\ Supervisor: Dr. Joe Wells} \date{CS4 Dissertation\\ Deliverable 2} \begin{document} \maketitle \newpage \tableofcontents %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Introduction} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{quote} Emaxml is an extension of Emacs, written in Emacs Lisp, to edit XML documents. Major Emacs modes for editing SGML and XML already exist; this is different in that it allows viewing the document as a tree structure, both visually and logically. \end{quote} %================================================================ \section{\C Aims and objectives of the project}\label{sec:AimsAndObjectives} %================================================================ {\bf [}An XML document is often generated automatically by an application. Nevertheless, in many occasions XML code is edited directly by a human author. When a normal text editor (i.e. one with no XML-specific editing facilities) is used to this end, the author's creativity has to deal with the XML document at three levels: \begin{enumerate} \item At the {\bf contents level}, the author is concerned with what the document is about, the actual information or concepts. \item At the {\bf structure level}, the author organises the document hierarchically, according to the rules set by the DTD for that particular class of documents. For non-trivial documents the overhead activity involved with keeping the structure in order or with changing the current structure can be very expensive. Moreover, the author has to be concerned with indentation or some other means to visually see the structure of the document. However, this activity is related to the conceptual contents of the document. \item At the {\bf syntactic level}, the author is concerned with getting the XML syntactic sugar right. This activity is strictly XML-related and has nothing to do with the topic of the document. It is an error-prone activity and the overhead involved can be very expensive. \end{enumerate} Obviously most of the work mentioned in the previous section can be automated to various degrees by an editor with XML editing facilities, to the purpose of letting the author concentrating on the contents and the structure of the document abstractly. The approach of Emaxml is that of taking care of the XML syntax and providing means of seeing and manipulating the structure of the document effectively, by displaying the document in a tree-like fashion. Figure~\ref{fig:Emaxml} shows Emaxml at work. {\C The final concrete objective is to implement a fully functional Emacs mode, with a limited number of functionalities, but designed so that it can easily be limitlessly improved by anyone who might possibly want to work on it later.} %================================================================ \section{\C Fundamental concepts of Emaxml} %================================================================ This chapter is a brief reminder of the concepts central to Emaxml specification, detailed in Deliverable 1\footnote{The terms in {\bf bold} are specific to Emaxml.}. Figure~\ref{fig:Emaxml} shows an XML document displayed by Emaxml. The parts of the display are called {\bf logical units}; their properties influence the response of Emaxml to the user's input. A list of the types of \logus\ is in Appendix~\ref{app:thelogus}. Not all locations in the display belong to a \logu. For instance, the colored spaces at the left of an \luelename\ or the colon following an \luattname\ are not part of any logical unit. All such locations and their contents are said to be {\bf automatic}, because they are managed by Emaxml and cannot be reached by the user. Non-automatic locations of the buffer form the {\bf user space} of the buffer. The user may place the cursor on some automatic locations, namely where such a location is immediately on the right of a user location. These locations are therefore not completely automatic, are called {\bf ubiquitous}, and allow the insertion of new text. For example, the colon in an \luatt\ is ubiquitous and when the cursor is over it any text inserted is appended to the relative \luattname. A {\bf logical line} is either one line (up to a newline) of a multiline \logu\ or an entire monoline \logu. The {\bf previous} \logl\ with respect to a \logl\ is the first \logl\ that is encountered by going left and up {in the display}. The {\bf following} \logl\ with respect to a \logl\ is the \logl\ that is encountered by going right and down. The topmost element is called the {\bf seed element}\footnote{Because it comes before the root element...}, and does not correspond to an actual XML element; it contains information relative to the document, such as that contained in the XML declaration. From the user's point of view, the header of the seed element is treated as a normal header, whose attributes are the said information. \begin{figure}[h] \begin{center} \includegraphics[width=16cm]{../deliv1/fig-Emaxml_lu-16x20.eps} \end{center} \caption{Screenshot of Emaxml, with the indication of the Logical Units.} \label{fig:Emaxml} \end{figure} An element (and the relative subtree rooted at it) can be displayed {\bf outline} or {\bf inline} (that is, vertically or horizontally) and {\bf expanded} or {\bf collapsed} (that is, completely visible or displayed as the element name only). These characteristics are independent so there are four ways of displaying a subtree (see Fig.~\ref{fig:ilol}), called {\bf display modes}: outline-expanded, outline-collapsed, inline-expanded, inline-collapsed. \begin{figure}[h] \begin{center} \includegraphics[width=18cm]{../deliv1/fig-tree_views-24x12.eps} \end{center} \caption{Display modes} \label{fig:ilol} \end{figure} The {\bf display state} of a subtree is defined by the display mode of all the elements it is formed by. %================================================================ \section{Changes to the original project plan} %================================================================ The most important change to the specification of Emaxml as described in Deliverable 1 regards the set of \logus\, which has been modified as follows: \begin{itemize} \item \lu{CDATA} \logus\ have been eliminated. A CDATA section in an XML document serves the purpose of letting the author write any sequence of characters without having to ``escape'' them as entity references. In the previous specification, Emaxml had a \logu\ for CDATA sections. The change is that now the author writes whatever s/he wants as character data, and the Writer will codify the character data optimally using combinations of CDATA sections, entity references, character references and plain character data. \item \luentref\ \logus\ have been introduced. Entity references are a sort of macro facility used in XML. They are substituted with the text they refer to when the specific application processes the information contained in the XML file. An \luentref\ \logu\ is an elementary, special, monoline, primary \logu, according to the definitions of these properties given in Appendix~\ref{app:thelogus}. \end{itemize} This changes have affected the design of the Parser, the Writer and the Emaxml mode; in particular, the hierarchy of types (the XD data model) that governs the main data structure (the \etree) has been changed accordingly. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Functional specification of the system} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The expected functionality of the system has been set in Deliverable~1; what follows is a revision of it, according to the feedback from the readers and discussion with the project supervisor. The functionalities are divided in two main categories: standard Emacs operations revisited for Emaxml, and Emaxml-specific operations. %================================================================ \section{Standard Emacs editing operations {\em \`{a} la} Emaxml}\label{sec:edop} %================================================================ The typical Emacs user will expect a number of standard editing facilities to be available in Emaxml mode, and their behavior to parallel that of other modes. It is not as important to implement a large number of functionalities immediately as it is to design the code in a modular fashion and document it properly, and choose at least a few operations from each of the following categories: \begin{itemize} \item {\bf PM}: point movement; \item {\bf ID}: insertion and deletion; \item {\bf MK}: mark operations; \item {\bf RE}: region setting; \item {\bf SR}: search \& replacement; \item {\bf GE}: general common operations (e.g. 'undo'). \end{itemize} Appendix~\ref{app:stdcmd} lists a set of commands that may be implemented for Emaxml as part of this project. %------------------------------------------------------------ \subsection{Visiting a file} %------------------------------------------------------------ Emaxml mode will be activated on visiting a file with extension {\em .xml} and when a buffer containing a file with extension other than {\em .xml} is saved with extension {\em .xml}\footnote{In Emacs, if a buffer is saved with 'C-x C-w' ('Save Buffer As...' in the Files menu) with a different extension, its major mode changes accordingly.}. In the latter case, the buffer needs be re-displayed also. In case the file does not already exist, the buffer will contain the seed element, blank, as described in section \ref{sec:create}. %------------------------------------------------------------ \subsection{Saving a file}\label{sec:savingAFile} %------------------------------------------------------------ When a file needs saving, the Writer is invoked to produce the XML code from the internal representation of the document. Also, the \luintdtd\ is syntactically checked before the file is saved, because it may contain sequences of characters that would make the written file illegal\footnote{Consider for example an \luintdtd\ containing {\tt ...]]> ...}. If this is written without being checked, the file will be subsequently unparsable.}. In the case that the \luintdtd\ is recognised as incorrect, the file will be saved without it, and the user will be advised so that s/he can take whichever action s/he thinks appropriate. %------------------------------------------------------------ \subsection{Highlighting the region} \label{sec:high} %------------------------------------------------------------ When using the mouse to highlight the region, or in Transient Mark mode\footnote{In Transient Mark mode, when the mark is active, the region is highlighted.}, only the locations of user space included in the region will be highlighted. However, when a primary \logu\ is completely included in the highlighted region, all of its physical space will be colored, including the non-user space, otherwise only the included user space will be colored. Two useful commands are implemented in Emaxml: mark-more and mark-less. \begin{description} \item[Mark more] is to expand the region to the next bigger \logu\ containing the region (or containing point if mark is undefined). \item[Mark less] does the opposite. Calls to mark-less always select the first child when there is more than one. \end{description} For example, if the region is currently a string in an \luattvalue, mark-more sets region to the containing \luatt. Further calls to mark-more set region to the containing \luattlist, then to the \luheader, then to the \luele, and so on up to the entire buffer. %------------------------------------------------------------ \subsection{Text search and replacement} %------------------------------------------------------------ Text search and replacement in Emaxml will operate on the user space only. Both string and regular expression search and replacement will be implemented. %------------------------------------------------------------ \subsection{Moving point} \label{sec:move} %------------------------------------------------------------ This section has not changed from Deliverable~1. %% Movement in Emaxml acquires different meanings (and names) %% depending on which level it is performed at: %% \begin{itemize} %% \item At character level: {\bf sliding}. %% \begin{description} %% \item[Horizontal sliding]: moving by one character. %% Point can slide inside the current \logl\ one character backward %% or forward. %% Sliding point backward when at the beginning of a \logl\ moves it %% to the end of the previous \logl. %% Sliding point forward when at the end of a \logl\ moves it to the %% beginning of the previous \logl. %% \item[Vertical sliding]: moving by one \logl. %% When performing a vertical sliding movement (e.g. 'next-line'), %% point is expected to behave as closely as possible to the usual %% behavior. %% A movement that starts at the $l$th location of a \logl, and ends %% at a different \logl, will end at the $l$th location of the %% arrival \logl\ if that has at least $l$ characters, or at its last %% location otherwise. However, $l$ is remembered for successive %% vertical movements. This Emacs standard property I will call {\bf %% \traveller}, because it is proved for an editor by demonstrating %% that performing a vertical movement in one direction followed %% immediately by a vertical movement in the opposite direction, %% point will always return to the initial location. %% Point can slide one \logl\ up or down with \traveller. %% \end{description} %% \item At the logical level: {\bf traversing}. %% Traversing (the XML tree) refers to moving from one XML %% component to another, hence the \logus\ involved are the primary \logus. %% Traversing will be implemented with no \traveller; point is %% always moved to the first character of the arrival \logu. %% \begin{description} %% \item[Horizontal traversing]: moving hierarchically\footnote{The %% choice of adjectives {\em horizontal} and {\em vertical} for %% traversing is due to the fact that, according to the general idea %% on which the layout style of Emaxml is based, the parent of a %% \logu\ can be thought of as being ``on the left'', while a %% peer is up or down.}. %% Point can traverse left from one of the said \logus\ to its XML %% parent. %% Traversing right can only be done from a \luheader\ to the first %% child of the current element, if any. %% \item[Vertical traversing]: moving to peers. %% Point can traverse from one of the said \logus\ (except %% the seed element, which has no peers) to the next or %% previous instance of the same \logu\ found in the buffer, %% regardless of them being sibling. %% \end{description} %% \end{itemize} %------------------------------------------------------------ \subsection{Mark and the mark ring} %------------------------------------------------------------ The mark ring will be implemented in Emaxml, consistently with its standard definition and functionality. Obviously, the internals relative to such implementation will be specific to Emaxml; markers have to be objects of a different data structure, since they must describe a location in terms of the tree. An important property of a marker that must be preserved is that it ``moves'' with the position in the buffer to which it is pointing, i.e. if some text is added or deleted before that position, the marker always points to the same character. %------------------------------------------------------------ \subsection{Killing and yanking} %------------------------------------------------------------ {\em Killing} and {\em yanking} in Emacs jargon mean {\em cutting} and {\em pasting} respectively. In standard Emacs operation when a portion of the buffer is killed it is deleted from the buffer and stored in the kill ring for later use. One property (I shall call it {\bf yanking transparency}) of an Emacs buffer is that if some text is killed and immediately yanked, the buffer does not change. Point may be in a different location, though. Yanking is an insertion operation; the portion of buffer being yanked is inserted before point. % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{Killing in Emaxml} \label{sec:kill} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - Many Emacs commands exist for killing. The ones considered here are: kill-line, kill-region, kill-word, kill-sexp, kill-buffer. Their names are self-explanatory, (a part from kill-sexp, maybe, which in Emaxml kills the current element). Kill-line kills a \logl\ instead of a normal line. Since the object of the editing in Emaxml is a tree, the killing and yanking operations must be redefined in terms of \logus. Let us consider a portion $p$ of an Emaxml buffer being killed that starts from location \lz\ in primary \logu\ \uz\ and ends at location \lo\ in primary \logu\ \uo. When $p$ is killed, it is stored in the kill ring. If $p$ is a string, it is stored as such, whith no information regarding wich \logu\ it was part of. On the other hand, Emaxml stores killed \logus\ and il\logus\ as {\em trees}. This stored tree is: \begin{itemize} \item If $p$ is an entire \logu, the tree rooted at \uz, including all its children. \item If $p$ is an il\logu, the tree rooted at the smallest \logu\ $s$ that include all the \logus\ totally or partially in $p$, and that does not include the children of $s$ which are not in $p$ and the portions of user space of $s$ not in $p$. This implies that the stored tree may have some blank \logus\ in it. \end{itemize} Killing $p$ has the following effects: \begin{itemize} \item[(1)] If $p$ is a string, point is left at \lz. \item[(2)] If $p$ is a primary \logu\, then point is left: \begin{itemize} \item if $p$ has a peer $q$ below it, at the first character of $q$'s user space; \item otherwise if $p$ has a peer $q$ above it, at the first character of $q$'s user space; \item otherwise at the first character of $p$'s parent's user space. \end{itemize} \item[(3)] If $p$ is a secondary \logu, then it must be one of the elementary \logus\ in an \luele\ or in a \lupi; a blank \logu\ of the same type as $p$ is inserted in place of $p$ with point at its first location. \item[(4)] If $p$ is an il\logu, then point is left as in policies (1), (2), (3) but substituting ``the portion of \uz\ in $p$'' for $p$. When killing an il\logu, Emaxml rebuilds the tree as follows, in order: \begin{itemize} \item[(i)] all primary \logus\ entirely included in $p$ are pruned; \item[(ii)] all secondary \logus\ entirely included in $p$ are blanked and possibly removed; \item[(iii)] all characters in $p$ are eliminated. \end{itemize} \end{itemize} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{\C Yanking in Emaxml} \label{sec:yank} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - The following are the main general properties of yanking in Emaxml: \begin{itemize} \item The object $p$ to be yanked is either a string or a subtree in the kill ring. \item Yanking leaves point after the last location of the user space of the yanked unit, i.e. the cursor is left under the first character of the user space after the yanked unit. \item If $p$ is a string, it is yanked at point. This involves applying low-level control\footnote{See section~\ref{sec:lowlevelcontrol} for definition of low-level control.}. \end{itemize} Yanking a non-string unit involves somehow tree manipulation. The only limitation posed by Emaxml is that secondary \logus\ (such as \luattname\ or \lupitarget) cannot be yanked other than in an appropriate compound \logu\footnote{\C This could be improved in future by giving a meaning to such operations. For example, yanking a secondary \logu\ $s$ of type $t$ into an unappropriate primary \logu\ $u$ may be defined as inserting a new appropriate primary \logu\ as a sibling of $p$, blank but with the field $t$ equal to $s$.}. Since both logical and illogical units are complete subtrees, there is no difference in yanking them. Let us consider a unit $p$ stored by Emaxml in the kill ring. If $p$ is a primary \logu, then yanking transparency does not hold \footnote{See Deliverable 1 for a discussion of this.}, so $p$ must be explicitly yanked as a peer or as a child. If yanked as a peer it is inserted before the current primary \logu, if yanked as a child it is inserted as its last child. The Emaxml policies for yanking $p$ into some \logu\ \ut\ are described in Fig.~\ref{fig:yankingcriteria}. \begin{tblenv} \begin{tabular}{l|l|p{5cm}} \hline {\bf $p$ is a} & {\bf \ut\ is a} & {\bf Yanking $p$ into \ut} \\ \hline string & elementary \logu & $p$ can be yanked anywhere in \ut \\ primary \logu & \luheader & $p$ can be yanked either as child or as peer of the element which \ut\ belongs to\\ primary \logu & primary \logu & $p$ yanked as a peer of \ut \\ \luattlist\ or \luatt & \luheader & $p$ inserted at end of \ut's \luattlist \\ \hline \end{tabular} \caption{Yanking criteria for $p$ not illogical.}\label{fig:yankingcriteria} \end{tblenv} %================================================================ \section{Emaxml specialized editing operations} %================================================================ Appendix~\ref{app:newcmd} lists the minimum set of new commands specific to Emaxml to be implemented as part of this project. They are described in the following sections. %------------------------------------------------------------ \subsection{Creating a new instance of a logical unit}\label{sec:create} %------------------------------------------------------------ Creating a new instance inserts a {\bf blank \logu}. A blank \logu\ is an instance of a \logu\ with the strings referring to the user space empty. For example, an \luatt\ is of the form: $$ \overbrace{\mbox{\tt \underline{name}}}^\mathcal{U} \underbrace{\mbox{\tt :}\Box}_{\mathcal{A}} \overbrace{\mbox{\tt value}}^{\mathcal{U}} $$ where `$\Box$' indicates a space, `$\mathcal{U}$' indicates user space and `$\mathcal{A}$' indicates automatic/ubiquitous space. A blank \luatt\ is therefore displayed as a colon followed by a space (which cannot be seen) and represented internally\footnote{See section~\ref{sec:DataStructures} for details on internal representation} as \begin{code} \begin{verbatim} (attribute (attName "") (attValue "")) \end{verbatim} \end{code} In the example, the user is able to move with the cursor over the colon and insert characters which are taken as part of the attribute name, or to place the cursor after the space to insert characters of the attribute value. Specifically, the blank \logus\ are described in terms of both displaying and internal representation in Fig.~\ref{tbl:blanklogus}. \begin{tblenv} \begin{tabular}{|p{3cm}|p{4cm}|p{8cm}|} \hline {\bf \logu} & {\bf Display} & {\bf Internal representation} \\ \hline \hline \luattname & & {\tt (attName "")} \\ \hline \luattvalue & & {\tt (attValue "")} \\ \hline \luatt & {\tt :$\Box$} & {\tt (attribute (attName "") (attValue ""))} \\ \hline \luattlist & {\tt :$\Box$} & {\tt (attList (attribute (attName "") (attValue "")))} \\ \hline \luelename & $\Box$ & {\tt (eleName "")} \\ \hline \luheader & \underline{$\Box$}\underlines & {\tt (header (eleName ""))} \\ \hline \luele & \underline{$\Box$}\underlines & {\tt (element (header (eleName "")))} \\ \hline \luchardata & Three blank lines (one as top ``margin'', one for the text and one as bottom ``margin'') & {\tt (charData "")} \\ \hline \lupitarget & & {\tt (PITarget "")} \\ \hline \lupibody & & {\tt (PIBody "")} \\ \hline \lupi & \underline{\tt $<$?$\Box$:$\Box$}\underlines & {\tt (PI (PITarget "") (PIBody ""))} \\ \hline \lucomment & \underline{\tt $<$!--}$\Box$ & {\tt (comment "")} \\ \hline \luintdtd & \underline{\tt $\Box$[}$\Box$ & {\tt (intDTD "")} \\ \hline \luentref & \underline{\tt $\Box$\&$\Box\Box$;$\Box$} & {\tt (entRef "")} \\ \hline \end{tabular} \caption{Blank \logus. `$\Box$' indicates a space, underlined text indicates a colored background.} \label{tbl:blanklogus} \end{tblenv} When a new \logu\ is created, point is placed at its first ubiquitous location, since there are no available user locations in a blank \logu. Inserting a new \logu\ does not always make sense, for example creating a new \luattname\ alone, or creating a \lupibody\ when the cursor is on the middle of an \luentref. The meaning of such commands must be interpreted guessing what the user may be wanting when s/he issues them. That depends on where point is and what type of \logu\ the user wants to create. The following is the set of rules that governs the insertion of new \logus. \begin{itemize} %A new child is inserted as the first child of the element, if point is %on the \luheader\ of the element, while a %sibling is inserted in place of the primary component. %\item Creating a primary \logu\ results in a new instance of such a % \logu\ being inserted as a sibling of the current primary, immediately % before that, unless the current primary is the \luseed, in which case % the new \logu\ is inserted after the seed (if such a \logu\ is % allowed, see Fig.~\ref{tbl:XD:types}). \item A primary \logu\ can be created as a child of an element or as a sibling of the current primary \logu. Different commands are provided for these two operations. \item Creating a \luattlist, a \luattname\ or a \luattvalue\ is equivalent to creating an \luatt. \item Creating a \lupitarget\ or a \lupibody\ is equivalent to creating a \lupi. \end{itemize} %------------------------------------------------------------ \subsection{Adjusting the displaying of the tree structure} %------------------------------------------------------------ This section has not changed from Deliverable~1. %% The following statements define the manipulation of the visual %% tree: %% \begin{itemize} %% \item The tree structure is by default displayed entirely %% outline-expanded when the document is initially visited. %% \item Making an outline subtree inline makes all its children %% temporarily inline, and does not change its or its children's %% expansion mode. %% \item Expanding a collapsed subtree brings it back to the %% display status it was before being collapsed (i.e. all its %% elements return to their previous display mode). %% \item The root element and the seed cannot be made %% inline. %% \item The \luheader\ of a collapsed or inline element has no %% user space. %% \end{itemize} %% An optional further development may be that the entire document %% display status be saved along with the file (e.g. encoded somehow %% inside the document) and restored the next time the document is %% visited in Emaxml mode. %================================================================ \section{Control issues} \label{sec:ctrl} %================================================================ Emaxml, at the stage of development I set as target for my project, will not enforce control over the tree structure created by the user or read from an XML file in terms of the DTD. Emaxml will see the document ``simply'' as a syntactic structure that must comply with the grammar set out by the BNF rules in \cite{w3c}. Note that the internal DTD is {\em not} parsed. The user will be able to manipulate the tree as s/he wants without being bothered with indentation. The ``less-thans'', quotes, and other syntactic sugar of XML will be hidden. This should hopefully let the user concentrate more on the contents, but, on the other end, the user will also be able to create documents that are not well-formed, or invalid. However, the actual code implementing the editing mode must be designed so that adding semantic awareness and control should be easy. Examples of events that may trigger a contents check or other semantics-related operations are: \begin{itemize} \item the contents of a secondary elementary \logu\ (i.e. \luelename, \luattname, \luattvalue) is changed at the character level; \item point leaves an elementary \logu. \item the tree is changed; this includes creation of instances of any \logu, killing and yanking at the logical and illogical levels, \item the contents of the seed element are changed; \item the contents of the \luintdtd\ are changed. \end{itemize} These and other such events must be easily recognizable and exploitable from the programmer's point of view. %------------------------------------------------------------ \subsection{Low-level control}\label{sec:lowlevelcontrol} %------------------------------------------------------------ Some \logus, by their nature, have limitations on what can be inserted in them. For instance, no spaces may be inserted in a \lupitarget, since the target of a processing instruction can only be one word. Emaxml enforces low-level control on the text inserted by the user, by matching the contents of the current elementary \logu\ with a suitable regular expression. By {\em low-level control} I mean that only the wellformedness is checked, as opposed to checking the validity as well, which would involve ensuring that what the user inserts is also consistent with the DTD declarations (for instance, that a referenced entity has been declared in the DTD). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Background: Emacs buffer-related technologies}\label{sec:backgroundBuffer} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% A buffer in Emacs is a data structure that contains the information needed to display something in a window, according to the mode the buffer is set to. For example, a buffer in Text mode contains simply a sequence of ASCII\footnote{Or Unicode, or ...} characters, while a buffer in Enriched mode contains also information about characteristics of portion of text, such as the color, the weight, the justification, etc. A buffer in Enriched mode, when saved, may look like this: \begin{code} \begin{verbatim} Content-Type: text/enriched Text-Width: 70 This text is normal. redThis text is red. This text is bold. \end{verbatim} \end{code} This will produce a line of normal text, one of red text and one of bold text. Information is in this case stored as markup {\em in the buffer}, and it is saved in the file. Enriched mode is the simplest way of controlling the layout of text in a window. In sections more powerful approaches are examined. These sections are mainly a resume from the Emacs Lisp manual (\cite{elisp}). %================================================================ \section{Text properties} %================================================================ Each character position in a buffer or a string can be associated to a {\em text property list}. Each property has a name and a value, and there exist Lisp functions to access and modify them. Copying text between strings and buffers preserves the properties along with the characters; this includes such diverse functions as `substring', `insert', and `buffer-substring'. There are many predefined text properties, not only related to layout, but also to the behavior of Emacs related to a character position. Fig.~\ref{tbl:textproperties} is a list of some text properties that may be useful in designing Emaxml. New text properties can be created and managed with the relative built-in functions. For example, in Emaxml may be useful to attach to a portion of the buffer a property called `subtree' in which to store the corresponding portion of the \etree, in order to associate the logical and the physical view of the document. By default, inserted characters take on the same properties as the preceding character. This is called {\em inheritance} of properties. Which properties are inherited, and from where, depends on which properties are {\em sticky}. Insertion after a character inherits those of its properties that are {\em rear-sticky}. Insertion before a character inherits those of its properties that are {\em front-sticky}. When both sides offer different sticky values for the same property, the previous character's value takes precedence. It is possible to save text properties along with the text in a buffer, by exploiting the hook `write-region-annotate-functions'. %================================================================ \section{Overlays} %================================================================ Overlays are used to alter the appearance of a buffer's text on the screen, for the sake of presentation features. An overlay is an object that belongs to a particular buffer, and has a specified beginning and end. It also has properties that can be examined and set; these affect the display of the text within the overlay. Overlay properties are like text properties in that the properties that alter how a character is displayed can come from either source. But in most respects they are different. Text properties are considered a part of the text; overlays are specifically considered not to be part of the text. Thus, copying text between various buffers and strings preserves text properties, but does not try to preserve overlays. Changing a buffer's text properties marks the buffer as modified, while moving an overlay or changing its properties does not. Unlike text property changes, overlay changes are not recorded in the buffer's undo list. Many overlay properties are common with text properties. Figure~\ref{tbl:overlayproperties} is a list of some peculiar overlay properties that may be useful in Emaxml design. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{\C Implementation design} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The project is to be implemented as an extension to Emacs, i.e. as an Emacs mode. Thus, it is to be coded in Emacs Lisp. The following priorities have to be kept in mind during coding: \begin{itemize} \item \underline{Consistency} with the XML specification given in \cite{w3c}, in particular with the BNF definitions numbered in square brackets ({\bf BNF-defs} for short). \item \underline{Modularity}, so that functions and constants can be re-used in different contexts and extended easily. \item \underline{Readability} of the code, to facilitate future possible improvement. \end{itemize} %================================================================ \section{Data structures}\label{sec:DataStructures} %================================================================ The object of the editing, an XML file, will be seen by Emaxml in two ways at the same time: as an Emacs buffer (the {\bf \ebuf}), used to display the visual representation of the tree, and as a list (the {\bf \etree}), structured as to allow an abstract, logical view of the document and appropriate manipulation. An interface to manipulate the \etree\ and its components is provided as the {\em XD data model} described below. % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsection{The XD data model}\label{sec:theXDDataModel} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - The {\bf XML Document data model} ({\bf XD}) is composed of: \begin{itemize} \item a hierarchy of types ({\bf XD-types}) that reflect Emaxml \logus; \item a set of functions ({\bf XD-functions}) to manipulate the objects in the data model ({\bf XD-objects}). \item a set of constants ({\bf XDRE Toolkit}) that reflect the BNF-defs; \end{itemize} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{The XD-types} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - An XD-object belongs to one of the XD-types listed in Fig.~\ref{tbl:XD:types}, and represents an instance of a \logu\ in the display. In concrete terms an XD-object $p$ is a list $(C\; s_1\; [s_2 \cdots])$ whose first element $C$ is a symbol denoting the XD-type of $p$ and whose other element(s) $s_i$ may be branches of the tree generating from $p$ (that is, $p$'s {\bf children}, which are XD-objects themselves) or a string which refers to the part of the user space connected with $p$. An example of an XD-object of type `attribute' may be: \begin{code} \begin{verbatim} (attribute (attName "length") (attValue "25.52cm")) \end{verbatim} \end{code} The XD-type are listed in Fig.~\ref{tbl:XD:types} together with the children they may have. A `seed' object is a special kind of 'element' object: it may have only four attributes in its header (namely ``version'', ``encoding'', ``standalone'' and ``external DTD''), does not have an element name and its children are limited as defined in Fig.~\ref{tbl:XD:types}. % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{The XD-functions} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - The XD data model provides functions for the manipulation of its objects. Their names start with {\tt XD-} and follow these naming conventions: \begin{itemize} \item {\tt XD-\lt...\gt} refers to a function that performs an operation on a child, for example {\tt (XD-\lt get\gt\ etree 'header)} returns the entire object of type {\em header} of the object {\tt etree}; \item {\tt XD-\gt...\lt} refers to a function that performs an operation on the contents of a child, for example {\tt (XD-\gt get\lt\ etree 'seed 'header 'eleName)} returns the string associated with the element name in the header of the seed of the object {\tt etree}; \item {\tt XD-\{...\}} refers to a function that returns a list of objects, for example {\tt (XD-\{getall\} elt 'PI 'comment)} returns a list of all the comments and processing instructions contained in the element {\tt elt}; \item {\tt XD-...-p} indicates a predicate function, as for standard Lisp convention, i.e. a function that checks some condition and returns \lispnil\ or \lispt. \end{itemize} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{The XDRE toolkit}\label{sec:theXDREToolkit} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - The {\bf XDRE} toolkit is a set of string constants which are regular expressions that match some of the basic building blocks of XML, defined by the BNF-defs\footnote{Not all the BNF-defs can be translated into regular expressions, mostly because there is no trivial way of translating a BNF difference construct, such as in `(Char - ']')*', which indicates a sequence of zero or more instances of the BNF production `Char' which are not `]'.}. Their purpose is to be used in the parsing functions instead of literal regexps, for readability. Each constant's name is of the form {\tt XDRE-component} , where {\tt component} reflects the name of a rule in the BNF-defs. In constructing the regexp, the symbols {\tt `\lt\lt', `\gt\gt', `||', `**', `++', `--'} are used in place of {\tt `\back \back (', `\back \back )', `\back \back |', `*', `+', `?'} respectively. The table in Appendix \ref{app:XDRE_constants} describes what each XDRE represents. %------------------------------------------------------------ \subsection{The \etree} %------------------------------------------------------------ The \etree\ is the structural representation of the file being edited. It is maintained and manipulated through the facilities provided by the XD data model. The \etree\ is practically a `seed' XD-object, that is, a list of objects which are lists themselves. A simple example of an \etree\ object may be: \begin{code} \begin{verbatim} (seed (header (eleName "") (attList (attribute (attName "version") (attValue "1.0")) (attribute (attName "encoding") (attValue "UTF-8")) (attribute (attName "standalone") (attValue "no")) (attribute (attName "extDTD") (attValue "SYSTEM \"dtdfile.dtd\""))))) (comment "Simple document") (element (header (eleName "root") (attList (attribute (attName "att1") (attValue "val1")))) (charData "This is some character data") (element (header (eleName "child"))) (PI (PITarget "aTarget") (PIBody "aBody")))) \end{verbatim} \end{code} This may be extracted from an XML document that looks like: \begin{code} \begin{verbatim} This is some character data \end{verbatim} \end{code} %------------------------------------------------------------ \subsection{\C The \ebuf} %------------------------------------------------------------ The \ebuf\ is an instance of an Emacs buffer, which is an internal data structure that Emacs is able to display\footnote{See section~\ref{sec:backgroundBuffer} for details on Emacs buffers)}. It contains therefore the information that relates the \etree\ to its visual representation. Some of this information is implicitly given in terms of the `syntax table', which relates patterns to layout and behavioral characteristics. Emacs is made aware of these relations and takes care of displaying text that matches those patterns according to the relevant layout. Other layout information is explicitly attached dynamically to portions of the \ebuf\ using text properties and/or overlays, and it is maintained constantly consistent with the \etree. At this point of the development I have not designed the details of the implementation of the \ebuf. It will be mostly developed experimentally, since I am not familiar with the technologies involved. The background knowledge has been collected and looks very promising; the next steps in the design of the \ebuf\ will be parallel to the development of the prototype of the Emaxml mode, and finally a proper specification will be produced for documentation purposes. %================================================================ \section{\C Whitespace handling}\label{sec:whitespace} %================================================================ A piece of whitespace is a sequence of one or more spaces, tab characters, carriage return characters or linefeed characters. In the following discussion I refer to whitespace which is not part of markup, i.e. it is part of a piece of character data. Whitespace which is between other non-whitespace characters is certainly part of the character data and must be preserved, while whitespace which is immediately before or after a piece of markup (from now on referred to as {\bf boundary} whitespace), may be there for one of two reasons: \begin{itemize} \item Because it is integral part of the topic of the document (e.g. indentation such as in C code or poetry), and must be preserved. \item Because it is used to make the XML file more human-readable in raw XML format (e.g. blank lines, or tabs used for indentation). This whitespace does not affect the semantics of an XML file, and it should be up to the user whether to preserve it or not. \end{itemize} A sequence of whitespace characters only between two markup constructs corresponds in the \etree\ to a {\tt charData} object whose string is whitespace only. Such an instance is called {\bf void}. In general, Emaxml is set to comply with one of the following policies for boundary whitespace, at the user's choice: \begin{itemize} \item {\bf Allow-all}: do not perform any processing on the boundary whitespace. \item {\bf Allow-none}: no boundary whitespace is preserved at all. \item {\bf Allow-all-but-void}: preserve boundary whitespace but discard void {\tt charData} objects. In practice, whitespace between markup that not contains any character data is considered to be for indentation purposes only. This is the default policy. \end{itemize} In practice, the software components apply the chosen policy as described in the below sections concerned with their definitions. %================================================================ \section{\C Software components} %================================================================ As said, the system is concretely an Emacs mode called Emaxml mode. This is the major infrastructure that manages the editing, using the Parser and the Writer (the other two components of the system) for specific tasks. The Parser and the Writer are effectively two independent, reusable pieces of software, based upon a common data model, the XD data model. %------------------------------------------------------------ \subsection{\C The Parser} %------------------------------------------------------------ The {\bf XMLDoc Parser} ({\bf XDP} for short) takes as input an Emacs buffer in Fundamental mode (hence with no meta-information about text properties) containing an XML document and extracts the relative \etree. The Parser checks the syntax of the document and gives an indication of the error in case it is not correct. XDP has been implemented already, and tested informally, so the following is a description rather than a design specification. The idea behind XDP is to provide an independent, reusable tool for parsing XML files according to the XD data model. In some respect, XDP and the XD data model are quite limited, since they do not cover all the aspects of an XML document to a high degree of detail, but they can be useful for any application that, like Emaxml, needs to represent and manipulate the skeleton of an XML document for practical purposes. Emaxml parses an XML document by moving point in the buffer which contains the XML file. At the current position of point, the parser expects to find a sequence of characters that corresponds to one of a series of possible XD-object, according to the BNF-defs. If such a sequence is found, the relative XD-object is built ({\bf object extraction}), and point is advanced, otherwise the parsing is unsuccessful. The parsing process is a recursive one, so at the end of the day it consists of placing point at the beginning of the buffer and trying to extract a `seed' object. XDP is coded in the {\tt \home /tesi/XDP/XDP.el} file and consists of: \begin{itemize} \item a set of auxiliary functions (the {\bf XDP Toolkit}), that carry out general operations related to parsing; \item a set of extracting functions (the {\bf XDC-functions}), each of which is concerned with parsing an XML component. \end{itemize} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{\C Whitespace in parsing} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - The Parser is responsible of filtering the whitespace present in the XML file according to the chosen whitespace policy. If the policy is ``Allow-none'', all boundary whitespace is removed from the character data. If the policy is ``Allow-all'', all whitespace is preserved in the character data. If the policy is ``Allow-all-but-void'', all whitespace is preserved, but void `charData' objects are not. % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{\C XDP Toolkit} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - Parsing and in particular object extraction involve some elementary operations, provided by the XDP toolkit, that fall in one of the following categories: \begin{itemize} \item {\bf Matching and skipping} The parser often needs to check if the text starting at point matches a particular regexp. It may need to retrieve it or ignore it. Functions like {\tt XDC-match-minus} or {\tt XDC-skip} provide such operations. \item {\bf BNF construct handling} The objects to be extracted derive from the BNF-defs, which are composed of {\em conjuctions} (sequences), {\em disjunctions} (selections, `$\mid$') and {\em repetitions} (`*', `+', `?'). Functions in this category (such as {\tt XDP-and} or {\tt XDP-*}) provide these features. \item {\bf Object manipulation} Functions in this category provide operations that are object-specific such as translating a standard entity reference to the corresponding character, or extracting information from the prolog of the XML document, or building an object from its components. \end{itemize} Generally speaking, XDP functions try to match the contents of the buffer at point with something (a regular expression, the result of one or more other XDP functions, ...) and return what matched. A return value of \lispt\ means that the requested match was not found but the function is successful anyway. For example, when trying to match '0 or more instancies of something', a non-match is a success nonetheless. All XDP functions are expected to leave point at the end of what they matched, or where it was if nothing was matched. See Appendix \ref{app:XDP_functions} for the list and details of the XDP functions. % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{\C XDC parsing functions} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - Every XD-class has a corresponding XDC-function that parses the text at point and returns an object of that class if one was there, or \lispnil. Moreover, there are several XDC-functions that refer to some BNF-defs. The object returned by such a function is not in the XD data model, but is of the same structure of an XD-object. For example, {\tt XDC-prolog} parses the prolog of an XML document as defined by the BNF-def number 22. A return value of \lispnil\ means that the object was not recognized at point. Most of XDC functions are straight-forwardly constructed by reproducing the BNF-def using a combination of XDP functions, XDRE regexps and XDC functions themselves, e.g.: \begin{code} \begin{verbatim} 01 ;; [28] doctypedecl ::= '' 03 ;; doctypedecl -> Name ExternalID? InternalID? 04 05 (defun XDC-doctypedecl () ; 06 (XDP-build 'doctypedecl ; 07 (XDP-skip "!DOCTYPE" XDRE-S) ; '"))) ; '>' \end{verbatim} \end{code} Lines 1-2 contain the BNF-def as from \cite{w3c}. Line 3 describes what the object is composed of, i.e. a Name object, possibly an ExternalId object, possibly an InternalID object. Line 6 invokes the XDP-build function to build a `doctypedecl' object as described by lines 7-16. Line 7 skips over '\lt!DOCTYPE' and whitespace. Line 8 extracts a Name object. Lines 9 and 10 deal with an optional pair of whitespace followed by an ExternalID object, and extract the latter. Line 11 skips over some optional white space. ...and so on. %------------------------------------------------------------ \subsection{\C The Writer} %------------------------------------------------------------ The Writer carries out the opposite of the Parser: it takes an \etree\ and produces an Emacs buffer, in Fundamental mode, whose contents are the XML document corresponding to that \etree. The \etree\ received as input can be assumed to be always errorless (i.e. to be formed of legal XD-objects as defined in Fig.~\ref{sec:theXDDataModel}), since it may only have been produced by the Parser or by the Emaxml mode, which both enforce syntactic control over the structure. An XML document $d$ is said to be {\bf correctly produced} from an \etree\ $e$ under a certain whitespace policy\footnote{Please refer to section~\ref{sec:whitespace} for definition of whitespace policy.} $w$ if and only if the result of parsing $d$ under $w$ is equal to $e$. A set of functions ({\bf XWC-functions}\footnote{The prefix ``XWC-'' is chosen to match that of the XDC-functions, because an XWC function is the inverse of the XDC-function for the same XD-type. For example, if $p$ is an XD-object of type `attList', then $p$=({\tt XDC-attList}({\tt XWC-attList}($p$))).} provide translation from an XD-object to an equivalent string in XML syntax with no whitespace added. This string is then processed to add whitespace according to the current whitespace policy; in terms of whitespace, the Writer can produce an XML file optimized for: \begin{itemize} \item \underline{Storage} (i.e. with no extra whitespace added), if the policy is `Allow-none'. \item \underline{Human inspection} (i.e. the markup is indented), if the policy is `Allow-all' or `Allow-all-but-void'. The indentation style is implemented very simply at this stage of development, and can be improved later. \end{itemize} In any case, the character data is written as it is (hence the Parser and the Emaxml mode are responsible for this), but in the second case the markup is also indented. The indentation style is implemented very simply at this stage of development, and can be improved later. As said, the result of the Writer is a buffer containing plain text, which can be saved, or inspected and modified. Before saving it, Emaxml checks the possible internal DTD as described in section~\ref{sec:savingAFile}, using the Parser. %------------------------------------------------------------ \subsection{\C The Emaxml mode} %------------------------------------------------------------ Emaxml is to be implemented as a major Emacs mode. The design of this implementation is described in the following sections at a very high level, i.e. it is a set of steps that must be carried out rather than a detailed definition. A suitable specification will finally be produced for documentation purposes. The main source of information about the features of an Emacs mode and the techniques used to set one up is the Emacs Lisp manual (\cite{elisp}), to which one may refer for further detail. See also Appendix~\ref{app:glossary} for brief definitions of some Emacs concepts. % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{\C General description of an Emacs mode}\label{sec:modeDefn} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - A {\em mode} is a set of definitions that customize Emacs and can be turned on and off by the user. There are two varieties of modes: {\em major modes}, which are mutually exclusive and used for editing particular kinds of text, and {\em minor modes}, which provide features that users can enable individually. An example of a mode is `C' mode, whose purpose is to edit C code files. This mode is activated when loading a C file, or by calling the Emacs Lisp function `c-mode'. Some of the many features available when a buffer is in C mode are: \begin{itemize} \item the syntactic constructs of C are highlighted in different colors; this provides also instantaneous syntactic check; \item when the user types a closing brace the corresponding opening brace blinks; \item the text can automatically be indented according to one of many styles; \item the program can be compiled in Emacs; \item point can be moved to next/previous function; \item there are tools for version control and debug. \end{itemize} Some of these functionalities are automatically managed by the mode, others are activated by a key sequence or by an item in a menu. Most features of the mode can be finely tuned using Emacs customization system. % - - - - - - - - - - - - - - - - - - - - - - - - - - - - \subsubsection{\C Implementing an Emacs mode}\label{sec:implementingMode} % - - - - - - - - - - - - - - - - - - - - - - - - - - - - Implementing a mode consists basically of two phases\footnote{Please refer to Appendix~\ref{app:glossary} for the definition of the technical terms in this section.}: \begin{itemize} \item writing the Lisp functions that perform the various operations; \item setting up the mode, that is, making Emacs aware of when and how to use those functions, and which way it should perform its common operations. \end{itemize} In general, a mode is set up by defining its components: \begin{itemize} \item The {\em keymap} maps key sequences to Lisp functions. \item The {\em syntax table} defines categories of characters in terms of the syntax; \item The {\em buffer-local variables} can be used to define the behavior of Emacs relative to some common functions. For example, C mode and Lisp mode both set the variable `paragraph-start' to specify that only blank lines separate paragraphs. They do this by making the variable buffer-local in the buffer that is being put into C mode or Lisp mode, and then setting it to the new value for that mode. \item The {\em standard hooks} can be used to make Emacs perform some common operation in an appropriate way, peculiar to the new mode. \item {\em New hooks} are defined and set to default values. The new mode will call the functions listed in these hooks when performing particular operations, so allowing the user or a developer to customize the behavior of the mode by changing the values of the hooks. \end{itemize} %% \todo{whitespace:If Allow-none is applied, Emaxml automatically %% removes whitespace at the beginning and end of a \luchardata\ when %% point leaves that \luchardata. If Allow-none or Allow-all-but-void %% is applied, Emaxml ensures that no void \luchardata\ \logus\ are %% created by enforcing low-level control. (rewrite)} %================================================================ \section{\C Implementation of low-level control} %================================================================ Low-level control (see section~\ref{sec:lowlevelcontrol}) concerns the contents of elementary \logus, and can be achieved in two ways: \begin{description} \item[by constant monitoring:] the check is triggered by a change in the \logu, by means of hooking a function to the appropriate text property or overlay; \item[by checking on exit:] the check is triggered by point moving out of the \logu, in the functions that are mapped to the keys used for moving point. \end{description} In both cases the user should be adviced of the error, yet be let free of keeping it if s/he wants to. A \logu\ containing an accepted error should be highlighted on the display. The first policy offers a more sophisticated control, but involves matching a regular expression every time the user inserts/deletes a character or kills/yanks a string. This may prove very resource-consuming. The second policy lets the user type anything and then advices him/her that something is wrong when s/he tries to leave the \logu. Therefore if ``checking on exit'' is implemented, Emaxml should reasonably also: \begin{itemize} \item advice on where exactly the error is; \item remember somehow which errors have been already accepted, and keep this information updated automatically if the error is corrected, otherwise the same error would be detected every time the user moves point through the incriminated elementary \logu; \item save this information for successive sessions. \end{itemize} Which policy is best? ``Constant monitoring'' is more resource-consuming, but resources are abundant these days (and more in the future). ``Checking on exit'' relies on surplus information, whose maintenance increases the overall complexity of the system, hence decreasing its expandibility. As a conclusion, ``constant monitoring'' is chosen as low-level control policy. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\chapter{Testing design} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %\todo{Starting point: Plan, chapter ``Testing''} %\todo{More ideas: testing the system on users.} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{\C Documentation design} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Following the Emacs philosophy and spirit, Emaxml is meant to be an extendible system. Useful and usable documentation is a key requirement. If only part of the target functionalities is implemented, but it is well documented, it will still be a partial success. Although the most comprehensive source of documentation for future (possible) developers will be the Dissertation Deliverable, two more documentation source are required: code documentation (again for developers) and Emacs on line help (for the end\footnote{...possible...} users). The Emacs Lisp Manual (\cite{elisp}) has a chapter (``Tips and Conventions'') that covers the conventions to be used in writing, commenting and documenting code for Emacs. Emaxml documentation is to comply with those conventions. %================================================================ \section{\C Code documentation} %================================================================ The code is to be documented internally and as a set of tables listing the functions and included as appendices in the Dissertation Document. The latter is not required by the Emacs standard, but it is included for quick reference and a general view of the structure of the code. %------------------------------------------------------------ \subsection{\C Internal documentation} %------------------------------------------------------------ In Lisp a semicolon starts a comment, but, as a convention in Emacs Lisp, a comment is classified according to the number of semicolons put at the beginning. The indentation commands of the Lisp modes in Emacs, such as `M-;' (`indent-for-comment') and (`lisp-indent-line'), automatically indent comments according to these conventions, depending on the number of semicolons. These are the conventions recommended: \begin{itemize} \item Comments that start with a single semicolon, `;', usually explain how the code on the same line does its job. In Lisp mode and related modes, the `M-;' (`indent-for-comment') command automatically inserts such a `;' in the right place, or aligns such a comment if it is already present. \item Comments that start with two semicolons, `;;', usually describe the purpose of the following lines or the state of the program at that point. \item Comments that start with four semicolons, `;;;;', are used for headings of major sections of a program. \end{itemize} %------------------------------------------------------------ \subsection{\C Function tables} %------------------------------------------------------------ Functions belonging to an Emacs mode are of two types: interactive functions, meant to be called by the end user (via a key combination, a menu, or by name) and internal functions, which perform the auxiliary computation. All functions are listed in tables (put in appendices in the Dissertation Document), grouped by software component. One further table lists the interactive functions from all software components. The purpose of these tables is to give a general, wide view of the structure of the entire program, its main components and the naming conventions adopted, and as quick reference in terms of number and type of arguments. Each entry contains the name of the function, the name and type of its arguments, and a brief description. %================================================================ \section{\C Emacs on line documentation} %================================================================ The standard on line documentation for an Emacs mode includes: \begin{description} \item[Function documentation strings] Every command, function, or variable intended for users to know about should have a documentation string. This is enclosed in the function or variable definition itself as the very first line of the code, and it is displayed when information is asked about that particular function or variable using Emacs help facilities such as Apropos, `C-h f' (`describe-function') or `C-h v' (`describe-variable'). Documentation strings are described in the Emacs Lisp Manual (\cite{elisp}, nodes ``Documentation Basics'' and ``Documentation Tips'') and allow easy inclusion of hyperlinks to other parts of the documentation. \item[Manual] An Emacs mode is documented in a manual for the end user, written in the Texinfo language and organized in terms of topics of discussion. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{\C Point of the situation and plan} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% So far, I have implemented the Parser, which works has described and has been tested informally on a set of XML files. The work has been carried out in a sort of experimental fashion. By this I mean that I have been loosely following a cycle \begin{figure}[h] \begin{center} \includegraphics[width=8cm]{../deliv1/fig-waterfall.eps} \end{center} \end{figure} This is due to my initial lack of experience with Emacs internals, Lisp, and XML. What is missing is testing, which has been discussed in Deliverable 1 to some degree. My plan for the future is to implement the Writer and test it with the Parser, then implement the Emaxml mode and test it. Finally, I will work on the Dissertation Document. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \clearpage \addcontentsline{toc}{chapter}{Bibliography} \begin{thebibliography}{99} \bibitem{w3c} \book{W3C XML Core Working Group}{Extensible Markup Language (XML) 1.0 (Second Edition)}{http://www.w3.org/TR/2000/REC-xml-20001006}{2001} This is the official specification of XML. Includes the BNF grammar describing the syntax of XML. \bibitem{nut} \book{E. Rusty Harold and E. Scott Means}{XML in a Nutshell}{O'Reilly}{2001} Good discursive explanation of the basics of the various aspects of XML, plus a comprehensive coverage of all related topics and applications. I found it useful for initial documentation, and also as a quick reference. \bibitem{info} \book{Free Software Foundation}{Emacs Info Manual}{Free Software Foundation}{1999} Major source of information about the usage of Emacs. It is more than a help on-line; it can be searched in many ways and, as far as my experience is concerned, always answers one's questions. Moreover, it does not pop up unwanted saying that you are writing a letter. \bibitem{elisp} \book{B. Lewis, D. LaLiberte and R. Stallman and the GNU Manual Group}{Emacs Lisp Manual}{http://www.gnu.org/manual/elisp-manual-20-2.5/elisp.html}{1993} A book on Lisp, Emacs Lisp, Emacs internals, Emacs Lisp libraries. As readable as a novel, as useful as a quick reference. Available in a variety of formats including Info, which makes it embedded in Emacs. \bibitem{extend} \book{B. Glickstein}{Writing GNU Emacs Extensions}{O'Reilly}{1997} Covers the customization of Emacs from the very basics of Lisp to a full major mode implementation. Very rich of practical examples paired with Lisp theory. \bibitem{holybible} \book{H. Abelson, G. J. Sussman and J. Sussman}{Structure and Interpretation of Computer Programs}{The MIT Press}{1985} An inspiring book, accidentally about Lisp, and purposefully about abstraction. It has been said that its footnotes alone are more interesting than most books around. \bibitem{newtestament} \book{M. Gankarz}{The UNIX Philosophy}{Digital Press}{1995} Software Engineering is not just a waterfall. \end{thebibliography} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \appendix %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{\C \Logus\ and their categories}\label{app:thelogus} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Fig.~\ref{tbl:lus} is a list of the types of \logus\ in Emaxml. \begin{tblenv} \begin{tabular}{|p{6cm}|p{8cm}|} \hline \luele & A whole element, including its header and its children \\ \hline \luheader & An element's name and its attributes \\ \hline \luelename & The first word of a \luheader \\ \hline \luattlist & The set of attributes of an element and their values \\ \hline \luatt & An attribute's name and its value \\ \hline \luattname & An attribute's name \\ \hline \luattvalue & An attribute's value \\ \hline \luchardata & The plain text. In \luchardata\ \logus, illegal characters ('"\lt\gt\&) are edited and displayed normally. However, they are codified to entity references when the XML file is written.\\ \hline \lupi & A processing instruction \\ \hline \lupitarget & The target of a processing instruction, i.e. the first word of a \lupi \\ \hline \lupibody & The command of a processing instruction \\ \hline \lucomment & A comment text \\ \hline \luintdtd & The text relative to the definition of the internal DTD \\ \hline \luentref & The text of an entity reference \\ \hline \end{tabular} \caption{Logical Units} \label{tbl:lus} \end{tblenv} Subsets of \Logus\ are grouped into categories according to some properties, as described in Table \ref{tbl:lucat}. \begin{tblenv} \begin{tabular}{|p{3cm}|p{3cm}|p{8cm}|} \hline {\bf Category} & {\bf Property} & {\bf \Logus} \\ \hline \hline {\bf Elementary} & Composed of characters only. & \luelename, \luattname, \luattvalue, \luchardata, \lupitarget, \lupibody, \lucomment, \luintdtd, \luentref. \\ \hline {\bf Compound} & Composed of elementary and compound \logus. & \luele, \luheader, \luattlist, \luatt, \lupi. \\ \hline {\bf \C Primary} & \Logus\ that are the main building blocks of the structure of the document at the {\em structure level} of document authoring, as opposed to the {\em syntactic level} (see \ref{sec:AimsAndObjectives}). & \luele, \luchardata, \lupi, \lucomment, \luentref, \luintdtd \\ \hline {\bf \C Secondary} & \Logus\ that are not really part of the structure of the document from a high level point of view, but which it is useful to identify on the display for editing purposes. & \luheader, \luattlist, \luatt, \luelename, \luattname, \luattvalue , \lupibody, \lupitarget. \\ \hline {\bf Special} & Primary \logus\ which cannot contain other primary \logus, i.e. are terminal nodes of the structure of the document. & \luchardata, \lupi, \lucomment, \luentref, \luintdtd. \\ \hline {\bf Multiline} & May contain {\em newline} characters. & \luintdtd, \lucomment, \luchardata, {\luattvalue}.\\ \hline {\bf Monoline} & May not contain {\em newline} characters. & \luelename, \luattname, \luattvalue, \lupitarget, \lupibody, \luentref. \\ \hline \end{tabular} \caption{Categories of \Logus} \label{tbl:lucat} \end{tblenv} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Standard Emacs commands recoded for Emaxml} \label{app:stdcmd} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% {\bf \underline{Notes}}: \begin{itemize} \item Editing operations are here referred to by their Emacs Lisp names, due to lack of space. For an exact definition, where these names are not self-explanatory, use 'F1~f~$<$command$>$' in Emacs. \item The {\bf Cat} column refers to the editing categories listed in section \ref{sec:edop}. \end{itemize} \begin{tblenv} \begin{tabular}{|l|l|l|p{8cm}|} \hline \hline {\bf Cat} & {\bf Shortcut} & {\bf Emacs Lisp name} & {\bf Action} \\ \hline \hline ID & C-d & delete-char & Delete the following character. No action at end of an elementary \logu. \\ ID & ESC k & kill-sentence & Performs kill-element. \\ ID & C-y & yank & Described in \ref{sec:yank}. Perform ``yanking as a child''.\\ ID & S-\key{insert} & yank & Described in \ref{sec:yank}. Perform ``yanking as a sibling''.\\ ID & \key{BACKSPACE} & delete-backward-char & In the middle of an elementary \logu, behave as usual. At beginning, behave as C-b.\\ ID & \key{RET} & newline & Multiline \logu: add a newline at point.\\ ID & \key{insert} & overwrite-mode & Usual behavior. \\ GE & C-l & recenter & Usual behavior \\ GE & C-\_, C-/ & undo & Usual behavior \\ KY & C-k & kill-line & Monoline: Kill the rest of the current \logl.Multiline: also, if no non-blanks there, kill thru newline.\\ MK & C-@, C-\key{SPC} & set-mark-command & Usual behavior.\\ MK & C-x C-x & exchange-point-and-mark & Usual behavior. \\ PM & C-a & beginning-of-line & Move point to beginning of current \logl.\\ PM & C-b, \kl & backward-char & Slide backward.\\ PM & C-\kd & forward-paragraph & Traverse down. \\ PM & C-e & end-of-line & Move point to end of current \logl.\\ PM & C-f, \kr & forward-char & Slide forward.\\ PM & C-\kl & backward-word & Usual behavior, through user space. \\ PM & C-n, \kd & next-line & Slide to next \logl, with \traveller.\\ PM & C-p, \ku & previous-line & Slide to previous \logl, with \traveller.\\ PM & C-\kr & forward-word & Usual behavior, through user space.\\ PM & C-\ku & backward-paragraph & Traverse up. \\ PM & \key{end} & end-of-buffer & Usual behavior. \\ PM & \key{home} & beginning-of-buffer & Usual behavior. \\ RE & C-x h & mark-whole-buffer & Usual behavior. \\ RE & ESC @ & mark-word & Usual behavior. \\ RE & double-mouse-1 & mouse-set-point & Usual behavior, but highlighting the region as described in section \ref{sec:high}.\\ RE & drag-mouse-1 & mouse-set-region & Usual behavior. Region as described in section \ref{sec:high}.\\ RE & mouse-1 & mouse-set-point & Usual behavior, but highlighting the region as described in section \ref{sec:high}.\\ RE & mouse-2 & mouse-yank-at-click & Usual behavior, but yanking done a la Emaxml (see section \ref{sec:yank}.\\ RE & triple-mouse-1 & mouse-set-point & Usual behavior, but region set to the whole \logu, and highlighting as described in section \ref{sec:high}.\\ \hline \end{tabular} \caption{New meanings for old commands} \end{tblenv} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Emaxml-specific commands} \label{app:newcmd} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{tblenv} \begin{tabular}{l|p{8cm}} {\bf Lisp-like non-definitive name} & {\bf Action} \\ \hline create-element-child & Create a blank \luele\ as a child of the current smallest element. Described in section~\ref{sec:create}.\\ create-element-sibling & Create a blank \luele\ as a sibling of the current smallest element. Described in section~\ref{sec:create}.\\ create-{\em logun} & Create a blank instance of a \logu\ of type {\em logun}.\\ create-primary & Create a sibling of the current primary \logu\ just before the current primary \logu. \\ traverse-right & Traverse right. Described in section~\ref{sec:move}. \\ traverse-left & Traverse left. Described in section~\ref{sec:move}. \\ mark-more & Described in section \ref{sec:high} \\ mark-less & Described in section \ref{sec:high} \\ \end{tabular} \caption{New commands to be implemented} \end{tblenv} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Details of XDRE constants}\label{app:XDRE_constants} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{tblenv} \begin{tabular}{l|l|p{8cm}} {\bf BNF-def} & {\bf XDRE constant} & {\bf Explanation} \\ \hline [2] Char & XDRE-Char & Unicode character range \\ [3] S & XDRE-S & White Space \\ [87] CombiningChar & XDRE-CombiningChar & Among others, this class contains most diacritics \\ [89] Extender & XDRE-Extender & Extenders \\ [85] BaseChar & XDRE-BaseChar & Among others, this class contains the Unicode alphabetic characters of the Latin alphabet \\ [86] Ideographic & XDRE-Ideographic & Unicode ideographic characters \\ [84] Letter & XDRE-Letter & BaseChar's + ideographic characters \\ [88] Digit & XDRE-Digit & Unicode digits \\ [4] NameChar & XDRE-NameChar & Characters allowed in Names \\ [5] Name & XDRE-Name & Matches a legal Name \\ [25] Eq & XDRE-Eq & Equality sign \\ [68] EntityRef & XDRE-EntityRef & Matches an entity reference (eg. `\&cright;') \\ [66] CharRef & XDRE-CharRef & Matches a character reference (eg. `\&\#x040B;') \\ [19] CDStart & XDRE-CDStart & Matches `\lt![CDATA[' \\ [21] CDEnd & XDRE-CDEnd & Matches `]]\gt', the CDATA section terminator \\ [69] PEReference & XDRE-PEReference & Matches a Parameter Entity (eg. `\%abc;') \\ [26] VersionNum & XDRE-VersionNum & Matches the version number declaration in an Xml Declaration \\ [81] EncName & XDRE-EncName & Matches the encoding name in an Encoding~Declaration \\ [13] PubidChar & XDRE-PubidChar & Characters allowed in names of PubidLiteral's \\ \end{tabular} \caption{The XDRE toolkit} \end{tblenv} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Details of the XD-types} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Table \ref{tbl:XD:types} is the list of the types belonging to the XD data model. The notation used is: \begin{itemize} \item[] $\to$: ``has as children''; \item[] *: ``zero or more''; \item[] ?: ``zero or one''; \item[] +: ``one or more''; \item[] $\mid$: indicates alternative children. \end{itemize} \begin{tblenv} \begin{tabular}{|lll|} \hline seed & $\to$ & header intDTD? (comment $\mid$ PI)* element (comment $\mid$ PI)* \\ intDTD & $\to$ & {\em string} \\ element & $\to$ & header (element $\mid$ comment $\mid$ PI $\mid$ entRef $\mid$ charRef $\mid$ charData)*\\ header & $\to$ & eleName attList* \\ eleName & $\to$ & {\em string} \\ attList & $\to$ & attribute+ \\ attribute & $\to$ & attName attValue \\ attName & $\to$ & {\em string} \\ attValue & $\to$ & ({\em string} $\mid$ entRef $\mid$ charRef)* \\ comment & $\to$ & {\em string} \\ PI & $\to$ & PITarget PIBody \\ PITarget & $\to$ & {\em string} \\ PIBody & $\to$ & {\em string} \\ charRef & $\to$ & {\em string} \\ entRef & $\to$ & {\em string} \\ charData & $\to$ & {\em string} \\ \hline \end{tabular} \caption{Data types in the XD data model.} \label{tbl:XD:types} \end{tblenv} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Details of XDP functions}\label{app:XDP_functions} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{tblenv} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-* \\ {\bf Functionality performed} & Checks if point is at 0 or more occurrencies of FORM. \\ {\bf BNF construct handled} & Char* \\ {\bf Parameters} & FORM - a Lisp form composed of XDP and XDC constructs. \\ {\bf Return} & \lispt\ if 0 occurrencies found. A list of the occurrencies found otherwise.\\ \hline \end{tabular} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-01 \\ {\bf Functionality performed} & Checks if point is at 0 or 1 occurrencies of FORM. \\ {\bf BNF construct handled} & \\ {\bf Parameters} & S? \\ {\bf Return} & \lispt\ if 0 occurrencies found. The occurrency found otherwise.\\ \hline \end{tabular} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-match \\ {\bf Functionality performed} & Checks if point is looking-at RE. \\ {\bf BNF construct handled} & [\^ \lt \& '] \\ {\bf Parameters} & RE - a regular expression. \\ {\bf Return} & The match-string if matched. \lispnil\ otherwise.\\ \hline \end{tabular} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-match-minus \\ {\bf Functionality performed} & Checks if point is looking-at the difference regexp (RE1 - RE2). \\ {\bf BNF construct handled} & Name - (('X' | 'x') ('M' | 'm') ('L' | 'l')) \\ {\bf Parameters} & RE1 and RE2 - two regexps. \\ {\bf Return} & The match-string if matched. \lispnil\ otherwise. \\ \hline \end{tabular} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-match-until \\ {\bf Functionality performed} & If looking-at 'RE1*TERMINATOR' return what matches 'RE1*' and set point at end of it. \\ {\bf BNF construct handled} & ((Char - '-') | ('-' (Char - '-')))* \\ {\bf Parameters} & RE1 - a regexp. TERMINATOR - a string.\\ {\bf Return} & What matches `RE1*' if matched. - \lispnil\ otherwise.\\ \hline \end{tabular} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-skip \\ {\bf Functionality performed} & Skips over a regular expression. Used for portions of buffer that don't represent any object. \\ {\bf BNF construct handled} & "'" \\ {\bf Parameters} & RE - a list of one or more regexps.\\ {\bf Return} & \lispt\ if RE is matched. \lispnil\ otherwise.\\ \hline \end{tabular} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-build\\ {\bf Functionality performed} & Constructs an object by putting together the results of the forms in ITEMS. It is based on a call to XDP-and whose result is put in a one-element list.\\ {\bf BNF construct handled} & [32] SDDecl ::= ...\\ {\bf Parameters} & ITEMS - a list of Lisp forms.\\ {\bf Return} & An object, if all of ITEMS matched. \lispnil\ otherwise.\\ \hline \end{tabular} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-and \\ {\bf Functionality performed} & Handles sequences. It also deals with forms that return \lispt\ to mean a successful non-match, by not appending the \lispt\ to the list returned.\\ {\bf BNF construct handled} & STag content ETag\\ {\bf Parameters} & FORMS - a list of Lisp forms.\\ {\bf Return} & A list with the results of evaluating FORMS if all non-\lispnil. \lispnil\ otherwise.\\ \hline \end{tabular} \begin{tabular}{|l|p{8cm}|} \hline {\bf XDP} & XDP-or \\ {\bf Functionality performed} & Handles selections.\\ {\bf BNF construct handled} & Comment | PI | S\\ {\bf Parameters} & FORMS - a list of Lisp forms.\\ {\bf Return} & The first form in FORMS that matches what point is at, if any. \lispnil\ otherwise.\\ \hline \end{tabular} \end{tblenv} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Glossary of Emacs technologies}\label{app:glossary} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% This chapter briefly defines some technologies related to the design of Emaxml. It is not intended to be exhaustive. For a complete and better explanation refer to the Emacs manual (\cite{elisp}). \begin{description} \item[Face] A face in Emacs jargon is a set of layout attributes, namely: font family, width, height, weight, slant, underline, overline, strike-through, box, inverse-video, foreground, background, stipple, inherit. \item[Echo Area] The Echo Area is a line at the bottom of an Emacs frame, for displaying messages. \item[Keymap] The keymap is the data structure that records the bindings of key sequences to the commands that they run. For example, the global keymap binds the character `Ctrl-n' to the command function `next-line', therefore when `Ctrl-n' is pressed the cursor moves to the next line. One of the characteristics of an Emacs mode is which key combinations trigger which operations. These are defined by the mode keymap. \item[Syntax Table] A syntax table provides Emacs with the information that determines the syntactic use of each character in a buffer. This information is used by the parsing commands, the complex movement commands, and others to determine where words, symbols, and other syntactic constructs begin and end. Each buffer has its own major mode, and each major mode has its own idea of the syntactic class of various characters. For example, in Lisp mode, the character `;' begins a comment, but in C mode, it terminates a statement. To support these variations, Emacs makes the choice of syntax table local to each buffer. Typically, each major mode has its own syntax table and installs that table in each buffer that uses that mode. \item[Hook] A hook is a variable where it is possible to store a function or functions to be called on a particular occasion by an existing program. For instance, if the name of a function is added to the variable `after-save-hook' (using function `add-hook'), that function will be called after saving any file. \end{description} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Text properties} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The following is a list of some text properties that may be useful in designing Emaxml. \begin{tblenv} \begin{tabular}{|l|p{10cm}|} \hline {\bf Property} & {\bf Description} \\ \hline \hline face & Face associated with the position. \\ \hline mouse-face & Face used instead of `face' when the mouse is on or near the character. This allows the text to change layout according to the mouse pointer position. \\ \hline display & This property activates various features that change the way text is displayed. For example, it can make text appear taller or shorter, higher or lower, wider or narrow, or replaced with an image. \\ \hline help-echo & If text has a string as its `help-echo' property, then when the mouse is moved onto that text, Emacs displays that string in the echo area. The value of this property can also be a function to be executed. \\ \hline local-map & Used for key lookup instead of the buffer's local map. {\em (Controlling movement of point only to user/ubiquitous space.)} \\ \hline syntax-table & The `syntax-table' property overrides what the syntax table says about this particular character. {\em (This affects many existing Emacs commands, especially at the character level of editing.)}\\ \hline read-only & If a character has the property `read-only', then modifying that character is not allowed. {\em (Ubiquitous space.)} \\ \hline invisible & A non-`nil' `invisible' property can make a character invisible on the screen. {\em (Storage of information related to Emaxml internals; implementation of display modes.)} \\ \hline intangible & If a group of consecutive characters have equal and non-`nil' `intangible' properties, then point cannot be placed between them. If the user tries to move point forward into the group, point actually moves to the end of the group. If the user tries to move point backward into the group, point actually moves to the start of the group. {\em (Automatic space.)} \\ \hline modification-hooks & Functions to be executed when the character is modified. {\em (Controlling what the user writes.)} \\ \hline \end{tabular} \caption{Some text properties and (in {\em italic}) examples of use in Emaxml. See appendix~\ref{app:glossary} for definitions of Emacs terminology.} \label{tbl:textproperties} \end{tblenv} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Overlays} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% The following is a list of some peculiar overlay properties that may be useful in Emaxml design. \begin{tblenv} \begin{tabular}{|l|p{10cm}|} \hline {\bf Property} & {\bf Description} \\ \hline \hline priority & When two or more overlays cover the same character and both specify a face for display, the face attributes of the one whose `priority' value is larger override the face attributes of the lower priority overlay. Overlays take priority over text properties. \\ window & If the `window' property is non-`nil', then the overlay applies only on that window. Useful to display the same buffer with different layouts in different windows. \\ insert-in-front-hooks & This property's value is a list of functions to be called before and after inserting text right at the beginning of the overlay. \\ insert-behind-hooks & This property's value is a list of functions to be called before and after inserting text right at the end of the overlay. \\ before-string & This property's value is a string to add to the display at the beginning of the overlay. The string does not appear in the buffer in any sense--only on the screen. {\em Displaying automatic space.} \\ after-string & This property's value is a string to add to the display at the end of the overlay. The string does not appear in the buffer in any sense--only on the screen. {\em Displaying automatic space.} \\ evaporate & If this property is non-`nil', the overlay is deleted automatically if it ever becomes empty (i.e., if it spans no characters). \\ \hline \end{tabular} \caption{Some overlay properties and (in {\em italic}) examples of use in Emaxml. See appendix~\ref{app:glossary} for definitions of Emacs terminology.} \label{tbl:overlayproperties} \end{tblenv} \end{document} % LocalWords: XW %% \begin{description} %% \item[In parsing] When a {\tt charData} object has been parsed, its %% string is processed according to the whitespace policy, and possibly %% discarded. %% \item[In editing] If Allow-none is applied, Emaxml automatically %% removes whitespace at the beginning and end of a \luchardata\ when %% point leaves that \luchardata. If Allow-none or Allow-all-but-void %% is applied, Emaxml ensures that no void \luchardata\ \logus\ are %% created by enforcing low-level control. %% \item[In writing] %% \end{description}