@c $Id$ @node Document Authoring @section Document Authoring The Emacspeak environment provides a rich collection of structured document authoring tools. These are well-suited for working in an eyes-free environment --you clearly do not want to use a @b{What You See Is What You Get} (WYSIWYG) authoring tool if you cannot see what you're getting. Structure-based authoring tools allow you to focus on the act of content creation, leaving the minutiae of visual layout to the computer. @menu * Creating Well-formatted Documents:: Authoring Content. * Search replace and spell check:: Fixing errors. @end menu @node Creating Well-formatted Documents @subsection Creating Well-formatted Documents Before authoring a document, decide its primary audience if the document contains relatively simple content e.g., no mathematical equations etc. and is primarily targeted at the WWW, you are probably better off using HTML. You can create well-structured HTML documents with the help of package @code{html-helper-mode} available from @code{ftp://ftp.reed.edu/pub/src/html-helper-mode.tar.gz} --- note this is now mostly obsoleted by James Clarke's excellent @code{nxml-mode} for editting XML documents. Package @code{html-helper-mode} is speech-enabled by Emacspeak to provide auditory icons, structured navigation and outlines, as well as voice locking for audio formatted feedback as you work. If the document being authored is more complex, you are usually better off creating it in LaTeX. Note that LaTeX documents can be converted to HTML either via package package @code{tex4ht} -- available on the WWW. The TeX family of typesetting languages is suitable for producing well-formatted documents in an eyes-free environment. Unlike WYSIWYG environments, the author of a TeX or LaTeX document works with the content of the document, leaving it to the formatting system (TeX) to format the document for good visual presentation. The auctex package is an Emacs extension that facilitates authoring and maintaining structured documents in TeX and LaTeX. Package @code{bibtex} facilitates maintenance and use of @code{bibtex} bibliography databases. The Texinfo package allows creation of software documentation that is suitable for both printing as well as online viewing as hypertext. Emacspeak speech-enables packages @code{auctex}, @code{bibtex} and @code{texinfo} to provide convenient spoken feedback as you create and compile documents. For details on using these packages, see their accompanying online info documentation. The most recent version of package @code{auctex} is always available by ftp at @code{ftp://ftp.iesd.auc.dk/pub/emacs-lisp/auctex.tar.gz}. Packages @code{bibtex} and @code{texinfo} are part of the standard Emacs distribution. As the document preparation system of choice, Emacspeak supports a fluent speech-enabled interface to editing and formatting LaTeX documents. This interface is provided by speech-enabling @emph{auctex} mode. Mode @emph{auctex} provides efficient keyboard shortcuts for inserting and maintaining LaTeX markup as a document is being authored. All of these editing commands provide succinct auditory feedback when used with Emacspeak. The syntax coloring provided by this mode is extended to provide @emph{ voice locking} --- consequently, Emacspeak uses different voices to speak the embedded markup to set it apart from the content. Mode @emph{auctex} can be used to create empty document templates and to insert document content at the appropriate places in the template. The mode also enables structured navigation of the document as it is being edited. Emacspeak speech-enables these template creation and structured navigation commands to produce auditory icons and succinct spoken feedback. For example, while editing, the user can quickly browse through the sections of the document and have each section title spoken. Document elements such as paragraphs and bulleted lists can be manipulated as logical units. These features are especially relevant in an eyes-free environment where the user needs to select logical parts of the document without having to point at portions of a visual display. Finally, Emacs supports creating and maintaining SGML and XML documents. Emacs comes with a fairly simple @code{sgml-mode} --in addition, package @code{psgml} provides sophisticated parsing and validation facilities for working with SGML and XML documents. Package @code{psgml} can be downloaded from @code{http://w4.lns.cornell.edu/public/COMP/info/psgml/psgml_toc.html}. @node Search replace and spell check @subsection Searching, Replacing, And Spell Checking Incremental search, a process by which the system prompts the user for a search string and moves the selection to the next available match while allowing the user to add more characters to the search string, is the search technique of choice among most Emacs users. As the system successively finds each match and provides the user the option of continuing the search. Incremental search is a more complex instance of traditional search interaction because in addition to either stopping or continuing the search, the user can modify the current search in a number of ways including specifying a longer (or shorter) search string. All of the user commands available during incremental search are documented in the online Emacs info manual. These are speech-enabled by Emacspeak to provide spoken prompts as the dialogue begins; auditory icons indicate a search hit or search miss as the search progresses. Along with auditory icons @emph{search-hit} and @emph{search-miss} the user also hears the current line spoken, and in the case of a search hit, the matching text is @emph{aurally} highlighted by using the standard audio formatting technique of changing voice characteristic. This feedback proves extremely effective when the search pattern appears several times on a single line; the user is unambiguously cued to the current match. Search and replace actions are an extension to the basic conversational gestures of a search dialogue. In addition to specifying a search string, the user also specifies a replacement string. On the Emacspeak desktop, this functionality is provided by command @emph{query-replace}. The speech-enabled version of this interaction prompts the user for the search and replacement texts. The auditory feedback during the interactive search and replacement process parallels that described in the case of incremental search. Audio formatting to indicate the occurrence that is about to be replaced proves an effective means of avoiding erroneous modifications to the text being edited. As an example, consider using command @emph{ query-replace} to locate and replace the second occurrence of @b{foo} with @b{bar} in the text @samp{Do not change this fool, but change this food.} When the search matches the first occurrence of @b{foo} in word @emph{fool}, the aural highlighting helps the user in answering ``no'' in response to question ``should this occurrence be replaced''. In addition to allowing the user to supply a simple ``yes or no'' answer for each match, command @emph{ query-replace} also allows the user to specify a number of other valid answers as described in the online Emacs documentation. @unnumberedsubsubsec Spell Checking A more complex instance of conversational gesture ``search and replace'' is exhibited by standard spell checking dialogues. Spell checking differs from the search and replace dialogue described above in that the search and replacement text is guessed by the system based on an available dictionary. Words that are not found in the dictionary are flagged as potential spelling errors, and the system offers an interactive search and replace dialogue for each of these possible errors. During this dialogue, the system successively selects each occurrence of the possibly erroneous word and offers a set of possible replacements. Unlike in the case of simple search and replace, more than one possible replacement string is offered, since a potential spelling error can be corrected by more than one word appearing in the dictionary. In the visual interface, such spell checking dialogues are realized by displaying the available choices in a pop-up window and allowing the user to pick a correction Once a correction is selected, the user is offered the choice of interactively replacing the erroneous word with the correction. The spell checking interface on the Emacspeak desktop is speech-enabled to provide fluent auditory feedback. The visual interface parallels that described above and is provided by package @code{ispell} which is part of the standard Emacs distribution. Emacspeak provides a spoken prompt that is composed of the line containing the possibly erroneous word (which is aurally highlighted to set it apart from the rest of the text on that line) and the available corrections. Each correction is prefixed with a number that the user can use to select it. Once a correction is selected, the interaction continues with the query and replace interaction described earlier. The speech interface to the spell checker is as fluent as the visual interface. Notice that Emacspeak users do not need to concern themselves with the details of the visual display such as ``the corrections are displayed in a window at the top of the screen''. In addition to the standard spell checker described above, newer versions of Emacs include an ``on-the-fly'' spell checker that flags erroneous words as they are typed. Emacspeak speech-enables package @code{flyspell} so that such erroneous words are aurally highlighted.