wed

<!DOCTYPE html>   <html class="no-js" lang="en" >  <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Wed’s Help — Wed v3.0.1-2-g39938100 documentation</title> <link rel="stylesheet" href="_static/css/theme.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <script src="_static/js/modernizr.min.js"></script> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search"> <a href="#" class="icon icon-home"> Wed </a> <div class="version"> v3.0 </div> <div role="search"> <form id="rtd-search-form" class="wy-form" action="search.html" method="get"> <input type="text" name="q" placeholder="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">  <div class="local-toc"><ul> <li><a class="reference internal" href="#">Wed’s Help</a><ul> <li><a class="reference internal" href="#editing-controls">Editing Controls</a><ul> <li><a class="reference internal" href="#toolbar">Toolbar</a></li> <li><a class="reference internal" href="#the-validation-progress-bar">The Validation Progress Bar</a></li> <li><a class="reference internal" href="#modification-and-save-status">Modification and Save Status</a></li> <li><a class="reference internal" href="#the-error-pane">The Error Pane</a></li> <li><a class="reference internal" href="#the-navigation-pane">The Navigation Pane</a></li> <li><a class="reference internal" href="#the-minibuffer">The Minibuffer</a></li> <li><a class="reference internal" href="#the-location-bar">The Location Bar</a></li> <li><a class="reference internal" href="#the-editing-pane">The Editing Pane</a><ul> <li><a class="reference internal" href="#the-caret">The Caret</a></li> <li><a class="reference internal" href="#placeholders">Placeholders</a></li> <li><a class="reference internal" href="#element-labels">Element Labels</a><ul> <li><a class="reference internal" href="#label-visibility">Label Visibility</a></li> </ul> </li> <li><a class="reference internal" href="#error-markers">Error Markers</a></li> <li><a class="reference internal" href="#contextual-menus">Contextual Menus</a></li> <li><a class="reference internal" href="#completion-menus">Completion Menus</a></li> <li><a class="reference internal" href="#replacement-menus">Replacement Menus</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#kinds-of-xml-operations">Kinds of XML Operations</a></li> <li><a class="reference internal" href="#searching">Searching</a><ul> <li><a class="reference internal" href="#quick-search">Quick Search</a></li> <li><a class="reference internal" href="#dialog-search">Dialog Search</a></li> </ul> </li> <li><a class="reference internal" href="#saving">Saving</a></li> <li><a class="reference internal" href="#copy-cut-and-paste">Copy, Cut and Paste</a><ul> <li><a class="reference internal" href="#span-mode">Span Mode</a><ul> <li><a class="reference internal" href="#copy">Copy</a></li> <li><a class="reference internal" href="#cut">Cut</a></li> <li><a class="reference internal" href="#paste">Paste</a></li> </ul> </li> <li><a class="reference internal" href="#unit-mode">Unit Mode</a><ul> <li><a class="reference internal" href="#indicating-units">Indicating Units</a></li> <li><a class="reference internal" href="#copy-and-cut">Copy and Cut</a></li> <li><a class="reference internal" href="#copy-add-and-cut-add">Copy-Add and Cut-Add</a></li> <li><a class="reference internal" href="#pasting">Pasting</a></li> </ul> </li> </ul> </li> <li><a class="reference internal" href="#undo-and-redo">Undo and Redo</a></li> <li><a class="reference internal" href="#keyboard-shortcuts">Keyboard Shortcuts</a></li> <li><a class="reference internal" href="#browser-requirements">Browser Requirements</a><ul> <li><a class="reference internal" href="#edge">Edge</a></li> <li><a class="reference internal" href="#firefox">Firefox</a></li> <li><a class="reference internal" href="#ie11">IE11</a></li> <li><a class="reference internal" href="#os-x">OS X</a></li> <li><a class="reference internal" href="#safari">Safari</a></li> </ul> </li> <li><a class="reference internal" href="#complex-name-patterns">Complex Name Patterns</a><ul> <li><a class="reference internal" href="#brief-explanation">Brief Explanation</a></li> <li><a class="reference internal" href="#long-technical-explanation">Long Technical Explanation</a></li> </ul> </li> </ul> </li> </ul> </div> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> <nav class="wy-nav-top" aria-label="top navigation"> <i data-toggle="wy-nav-top" class="fa fa-bars"></i> <a href="#">Wed</a> </nav> <div class="wy-nav-content"> <div class="rst-content"> <div role="navigation" aria-label="breadcrumbs navigation"> <ul class="wy-breadcrumbs"> <li><a href="#">Docs</a> »</li> <li>Wed’s Help</li> <li class="wy-breadcrumbs-aside"> <a href="_sources/index.rst.txt" rel="nofollow"> View page source</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <div class="section" id="wed-s-help"> <h1>Wed’s Help<a class="headerlink" href="#wed-s-help" title="Permalink to this headline">¶</a></h1> <p>The following help covers the basic features of wed. There are some important caveats to keep in mind when reading this documentation.</p> <p>First caveat. Wed is designed to be an XML editor that provides on the fly validation, and <em>only</em> this. Consequently, wed has no notion of a “document collection” and provides no means to load documents from a collection or save documents under some name into a collection. Functions such as these are to be provided by the larger application in which wed is being used. <strong>The following documentation does not cover the functions which are outside the scope of wed.</strong></p> <p>Second caveat. The functions of wed are exposed to the user through <em>editing modes</em> (usually just referred to as “modes”). It is possible to use wed with custom modes that present the document differently from what the generic mode does, or include toolbars, menus, dialogs, etc. <strong>The following documentation covers only what the generic mode (bundled with wed) provides.</strong> Custom modes will have to provide their own documentation.</p> <p>Third caveat. Make sure that wed is supported on your browser before <a class="reference external" href="https://github.com/mangalam-research/wed/issues">filing a bug report</a>. See <a class="reference internal" href="#browser-requirements">Browser Requirements</a>.</p> <div class="section" id="editing-controls"> <h2>Editing Controls<a class="headerlink" href="#editing-controls" title="Permalink to this headline">¶</a></h2> <p>Wed divides the screen into various areas.</p> <div class="section" id="toolbar"> <h3>Toolbar<a class="headerlink" href="#toolbar" title="Permalink to this headline">¶</a></h3> <p>Above the validation progress bar, wed presents a toolbar that allows to perform some operations through the mouse.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">Wed does not include in the toolbar a button for every single operation that may be performed through the keyboard. It includes only some operations by default, and modes may add more custom operations to the toolbar.</p> </div> <div class="figure align-center" id="id7"> <img alt="This image shows the default toolbar." src="_images/toolbar.png" /> <p class="caption"><span class="caption-text">The default toolbar.</span></p> </div> <p>If you hover the mouse pointer over a button, you will get a prose description of what the button does. In the image above, from left to right the buttons perform the following actions:</p> <ul class="simple"> <li>Save the document.</li> <li>Undo.</li> <li>Redo.</li> <li>Decrease the <a class="reference internal" href="#label-visibility">label visibility level</a>.</li> <li>Increase the <a class="reference internal" href="#label-visibility">label visibility level</a>.</li> <li>Remove markup from mixed content.</li> <li>Toggle attribute autohiding off and on.</li> <li>Set the selection mode to <a class="reference internal" href="#span-mode">span</a>.</li> <li>Set the selection mode to <a class="reference internal" href="#unit-mode">unit</a>.</li> </ul> <p>The attribute autohiding button is a toggle. When autohiding is on, the button is pressed down, as shown by shadows. When autohiding is off, the button is flat, as shown by the absence of shadows.</p> <p>The buttons that set the selection mode are mutually exclusive. The button which corresponds to whichever mode is active will is pressed down.</p> <p>Mode-specific buttons may appear to the right of the double bar. The buttons that appear there are those that correspond to the mode in effect at the caret location.</p> </div> <div class="section" id="the-validation-progress-bar"> <h3>The Validation Progress Bar<a class="headerlink" href="#the-validation-progress-bar" title="Permalink to this headline">¶</a></h3> <p>As you edit your document, wed validates your document according to the Relax NG schema that was specified when wed was started. Whenever you make a change to the document, wed revalidates the document.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">At the moment, wed itself does not provide a GUI to select different schemas. It is up to the software that uses wed to provide to the user the means to select a schema. How to do this depends on the needs of the project. For instance, wed is used in <a class="reference external" href="https://btw.mangalamresearch.org">BTW</a> to allow the editing of scholarly documents. There there can be only one schema in use and thus no need to ask the user to select a schema.</p> </div> <p>The validation progress bar is located above the editing pane. The image below shows the general location of the bar.</p> <div class="figure align-center" id="id8"> <a class="reference internal image-reference" href="_images/validation_bar.png"><img alt="This image shows the location of the validation bar, above the editing pane." src="_images/validation_bar.png" style="width: 634.0px; height: 144.0px;" /></a> <p class="caption"><span class="caption-text">The location of the validation bar.</span></p> </div> <p>When an document is first loaded, or when a revalidation occurs, the bar starts empty (all white). It is progressively filled with color as validation proceeds. For small documents, validation will occur very quickly and consequently the user will see the bar instantly fill to completion. The color of the bar and the status that appears in the center of the bar will vary depending on the results of validation.</p> <ul> <li><p class="first">The bar will be green and the status will be “valid” if validation is complete and the document is valid.</p> <div class="figure align-center" id="id9"> <img alt="The validation bar is green and shows the status "valid"." src="_images/validation_bar_valid.png" /> <p class="caption"><span class="caption-text">A validation bar indicating a valid document.</span></p> </div> </li> <li><p class="first">The bar will be red and the status will be “invalid” if the document is not valid.</p> <div class="figure align-center" id="id10"> <img alt="The validation bar is red and shows the status "invalid"." src="_images/validation_bar_invalid.png" /> <p class="caption"><span class="caption-text">A validation bar indicating an invalid document.</span></p> </div> </li> <li><p class="first">The bar will be blue and the status will be “working” as long as validation is not complete.</p> <div class="figure align-center" id="id11"> <img alt="The validation bar is blue and shows the status "working"." src="_images/validation_bar_working.png" /> <p class="caption"><span class="caption-text">A validation bar indicating the validation is not complete.</span></p> </div> </li> <li><p class="first">There is also a “stopped” status, which you should never see.</p> </li> </ul> </div> <div class="section" id="modification-and-save-status"> <h3>Modification and Save Status<a class="headerlink" href="#modification-and-save-status" title="Permalink to this headline">¶</a></h3> <p>On the left side of the screen, at the top, wed shows you the modification and save status of the document being edited.</p> <div class="figure align-center" id="id12"> <a class="reference internal image-reference" href="_images/modification_and_save_status.png"><img alt="This image shows the location of the modification and save status, on the top left side of the screen." src="_images/modification_and_save_status.png" style="width: 634.0px; height: 144.0px;" /></a> <p class="caption"><span class="caption-text">The location of the modification and save status.</span></p> </div> <p>The rectangle on the left is the modification status. A green modification status indicates that the document has not been modified since it has last been loaded or last saved. To the right of the modification status is the save status. It starts gray to indicate that the document has never been saved <em>during the current editing session.</em></p> <div class="figure align-center" id="id13"> <img alt="An unmodified and unsaved status." src="_images/unmodified_unsaved.png" /> <p class="caption"><span class="caption-text">The status shown for a document that has not been modified since last loaded and has not yet been saved in this editing session.</span></p> </div> <p>When you modify the document, the modification status becomes orange and contains an asterisk to indicate that the document in the editor has modifications that have not been saved yet.</p> <div class="figure align-center" id="id14"> <img alt="A modified and unsaved status." src="_images/modified_unsaved.png" /> <p class="caption"><span class="caption-text">The status shown for a document that has been modified since last loaded and has not yet been saved in this editing session.</span></p> </div> <p>When you save manually (for instance, by doing <kbd class="kbd docutils literal notranslate">Ctrl-s</kbd>), the modification status returns to green and the saved status becomes green. The saved status also tells you how long ago the last save occurred. Hovering on the save status brings up a tooltip telling you what kind of save last occurred: autosave, or manual save.</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">The delay between autosaves is configurable, and can be turned off by the application which makes use of wed. The availability of autosaves and the delay between autosaves is determined by the application which makes use of wed for editing.</p> </div> <div class="figure align-center" id="id15"> <img alt="An unmodified and manually saved status, with tooltip." src="_images/unmodified_manual_save.png" /> <p class="caption"><span class="caption-text">The status shown for a document that has been manually saved moments ago.</span></p> </div> <p>The save status will update periodically to show approximately how long ago the document was last saved.</p> <div class="figure align-center" id="id16"> <img alt="An unmodified and saved status, which occurred minutes ago." src="_images/unmodified_manual_save_minutes_ago.png" /> <p class="caption"><span class="caption-text">The status shown for a document that has been saved almost five minutes ago.</span></p> </div> </div> <div class="section" id="the-error-pane"> <h3>The Error Pane<a class="headerlink" href="#the-error-pane" title="Permalink to this headline">¶</a></h3> <p>On the left of the screen, under the modification and save status, you can find the error pane. This is where XML validation errors are shown to the user.</p> <div class="figure align-center" id="id17"> <img alt="The location of the error pane." src="_images/error_pane.png" /> <p class="caption"><span class="caption-text">The error pane.</span></p> </div> <p>The error pane is collapsible. It can be collapsed or expanded by clicking on the pane’s heading. Clicking on <a class="reference internal" href="#error-markers">error markers</a> in the editing pane will expand the error pane. Clicking on an error description in the error pane will scroll the editing pane to the location of the error. It will also make the error “selected”. The selected error has its description blinking in the error page and has its error marker blinking in the editing pane.</p> <div class="figure align-center" id="id18"> <img alt="Shows what happens when the user clicks on an error description." src="_images/click_on_error_description.gif" /> <p class="caption"><span class="caption-text">Clicking on an error description scrolls the editing pane to that error.</span></p> </div> </div> <div class="section" id="the-navigation-pane"> <h3>The Navigation Pane<a class="headerlink" href="#the-navigation-pane" title="Permalink to this headline">¶</a></h3> <p>The navigation pane is a basic functionality of wed but will be visible only if a mode makes use of it. <strong>The generic mode does not make use of the navigation pane.</strong> The generic mode is meant to be truly <em>generic</em> and thus does not know what elements serve as section headings in a document. Therefore, it does not know how to build the content of the navigation pane. So if you are using the generic mode, you won’t see it.</p> <p>Custom modes that make use of the pane will show this pane under the <a class="reference internal" href="#modification-and-save-status">modification and save status</a>, above the error pane.</p> <div class="figure align-center" id="id19"> <img alt="Shows where the navigation pane is situated." src="_images/navigation_pane.png" /> <p class="caption"><span class="caption-text">The navigation pane.</span></p> </div> <p>The user can click on the headings in the navigation pane to quickly scroll the editing pane to the corresponding area of the document. Some modes may also support bringing up special contextual menus on the headings of the navigation pane.</p> </div> <div class="section" id="the-minibuffer"> <h3>The Minibuffer<a class="headerlink" href="#the-minibuffer" title="Permalink to this headline">¶</a></h3> <p>As the name suggests, this is inspired by Emacs’ minibuffer. However, wed’s minibuffer is much more primitive than Emacs’. The minibuffer is a space that wed uses to quickly prompt for input <em>instead of</em> bringing up a dialog box. It allows for quick operations like <a class="reference internal" href="#quick-search">quick searches</a>. When it is not in use, the minibuffer is empty. A prompt appears there when wed prompts the user.</p> <div class="figure align-center" id="id20"> <img alt="Shows the minibuffer just under the editing pane." src="_images/minibuffer.png" /> <p class="caption"><span class="caption-text">The minibuffer.</span></p> </div> <p>In the example above, the minibuffer is prompting the user for a quick search, forward in the document.</p> </div> <div class="section" id="the-location-bar"> <h3>The Location Bar<a class="headerlink" href="#the-location-bar" title="Permalink to this headline">¶</a></h3> <p>The location bar appears right under the minibuffer. It indicates the hierarchy of elements that contain the caret. Each XML element in the hierarchy is separated from the next by a forward slash (<code class="docutils literal notranslate"><span class="pre">/</span></code>).</p> <div class="figure align-center" id="id21"> <img alt="Shows where the location bar is situated." src="_images/location_bar.png" /> <p class="caption"><span class="caption-text">The location bar.</span></p> </div> <p>In the example above, reading from the end of the location bar, the caret is located in a <code class="docutils literal notranslate"><span class="pre">note</span></code> element contained by a <code class="docutils literal notranslate"><span class="pre">notesStmt</span></code> element contained by a <code class="docutils literal notranslate"><span class="pre">biblFull</span></code> element, etc.</p> </div> <div class="section" id="the-editing-pane"> <h3>The Editing Pane<a class="headerlink" href="#the-editing-pane" title="Permalink to this headline">¶</a></h3> <p>The editing pane is where the document being edited is displayed and where most changes to a document are performed. It appears under the validation progress bar, above the location bar and to the right of the error pane.</p> <div class="figure align-center" id="id22"> <img alt="Shows where the editing pane is located." src="_images/editing_pane.png" /> <p class="caption"><span class="caption-text">The editing pane.</span></p> </div> <p>If the document is too long for the space given to wed, the editing pane will show a scroll bar on the right that allows scrolling the document.</p> <p>We will now go over each distinctive element of the editing pane.</p> <div class="section" id="the-caret"> <h4>The Caret<a class="headerlink" href="#the-caret" title="Permalink to this headline">¶</a></h4> <p>The caret indicates where the document is being edited. It is a blinking vertical bar. It can be moved by left clicking. When the caret is already in the document, the arrow keys on your keyboard can be used to move the caret.</p> <div class="figure align-center" id="id23"> <img alt="Shows the caret." src="_images/caret.gif" /> <p class="caption"><span class="caption-text">The caret can be moved with left clicks of the mouse or the arrow keys.</span></p> </div> <p>The element that contains the caret also acquires a pale yellow background color while the caret is in it. Only the element which immediately contains the caret acquires this color. The elements that contain this element do not change background color.</p> </div> <div class="section" id="placeholders"> <h4>Placeholders<a class="headerlink" href="#placeholders" title="Permalink to this headline">¶</a></h4> <p>Empty elements contain placeholders. The placeholders are meant to help users easily put the caret in empty elements. Without the placeholder, the start and end labels of empty elements would be immediately adjacent, and getting the caret between them would be more difficult. (It would require clicking on the start label and moving right or clicking on the end label and moving left.) When an element is edited to contain text or other elements, it loses its placeholder. When an element is emptied it gains a placeholder. When the caret is in a placeholder, the placeholder blinks to indicate that it contains the caret.</p> <div class="figure align-center" id="id24"> <img alt="Text editing add and removes placeholders." src="_images/placeholder.gif" /> <p class="caption"><span class="caption-text">The <code class="docutils literal notranslate"><span class="pre">hi</span></code> element gains a placeholder when the text is removed, and loses the placeholder when text is added back.</span></p> </div> <p>Placeholders also appear as the value of those attributes which have no value set.</p> </div> <div class="section" id="element-labels"> <h4>Element Labels<a class="headerlink" href="#element-labels" title="Permalink to this headline">¶</a></h4> <p>By default, the generic mode bundled with wed shows the start of each XML element with a start label, and the end of each XML element with an end label. The start and end labels can be distinguished from one another by the fact that a start label ends with a right angle bracket (<code class="docutils literal notranslate"><span class="pre">></span></code>) and an end label starts with a left angle bracket (<code class="docutils literal notranslate"><span class="pre"><</span></code>).</p> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">It is possible for custom modes to display elements using more specialized rendering, and omit the start and end labels. For instance, a custom mode could distinguish “paragraph” elements through line breaks and indentation, and omit the start and end labels of these elements.</p> </div> <div class="figure align-center" id="id25"> <img alt="An example of start and end labels." src="_images/start_end_labels.png" /> <p class="caption"><span class="caption-text">This figure contains a total of 8 labels: two start labels for two elements <code class="docutils literal notranslate"><span class="pre">p</span></code>, and the corresponding two end labels, two start labels for two elements <code class="docutils literal notranslate"><span class="pre">hi</span></code> and the corresponding two end labels.</span></p> </div> <p>Clicking on an element’s label selects the element and allows the user to perform actions on the element as a whole. When the element is selected, both the start and end labels are colored orange.</p> <div class="figure align-center" id="id26"> <img alt="An example of selected labels." src="_images/selected_labels.png" /> <p class="caption"><span class="caption-text">This figure shows a <code class="docutils literal notranslate"><span class="pre">p</span></code> element which is selected. Its labels are orange.</span></p> </div> <p>Right-clicking on an element label will bring up a <a class="reference internal" href="#contextual-menus">contextual menu</a> appropriate for the element. Start labels may contain the attributes associated with the XML element to which the label belongs. For each attribute, the label first shows the attribute’s name, followed by the equal sign (<code class="docutils literal notranslate"><span class="pre">=</span></code>) and the attribute value in double quotes (<code class="docutils literal notranslate"><span class="pre">"</span></code>). The attribute’s value appears in black on a white background.</p> <div class="figure align-center" id="id27"> <img alt="An example of attributes in a start label." src="_images/attributes.png" /> <p class="caption"><span class="caption-text">This figure shows a <code class="docutils literal notranslate"><span class="pre">p</span></code> element with the attributes <code class="docutils literal notranslate"><span class="pre">rend</span></code> and <code class="docutils literal notranslate"><span class="pre">style</span></code>.</span></p> </div> <p>Modes may configure wed so that some elements are hidden if the caret is out of a start label, but shown then the caret is moved inside the start label. Labels that have hidden attributes will show an ellipsis (<code class="docutils literal notranslate"><span class="pre">...</span></code>) before the right angle bracket (<code class="docutils literal notranslate"><span class="pre">></span></code>).</p> <div class="figure align-center" id="id28"> <img alt="An example of start label with hidden attributes." src="_images/attributes_ellipsis.png" /> <p class="caption"><span class="caption-text">This figure shows a <code class="docutils literal notranslate"><span class="pre">div</span></code> element with the ellipsis that indicates some attributes have been hidden.</span></p> </div> <p>When the caret is moved inside the start label, the hidden attributes are shown, and they are hidden again as soon as the caret is moved out of the start label.</p> <div class="figure align-center" id="id29"> <img alt="An example of start label with hidden attributes that are shown." src="_images/attributes_shown.gif" /> <p class="caption"><span class="caption-text">This figure shows a <code class="docutils literal notranslate"><span class="pre">div</span></code> element with its hidden attributes shown.</span></p> </div> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">Attribute visibility is determined by the mode being used to edit the file, and how this mode is configured. The generic mode by default shows attributes. It is possible for an application using wed to configure the generic mode to hide attributes. Custom modes may be designed to hide attributes too.</p> </div> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">When a double quote appears as part of an attribute’s value, wed will show the double quote as a double quote. In other words, it does not visually escape it. <strong>However, wed does encode double quotes appearing in an attribute’s value properly.</strong></p> </div> <p>Whenever the mode being used has provided element documentation, hovering over a label will bring up a tooltip with the documentation of the element.</p> <div class="figure align-center" id="id30"> <img alt="An example of a start label with its tooltip open." src="_images/label_tooltip.png" /> <p class="caption"><span class="caption-text">This figure shows a label for a <code class="docutils literal notranslate"><span class="pre">p</span></code> element whose tooltip is open. The tooltip contains documentation on the element.</span></p> </div> <div class="admonition note"> <p class="first admonition-title">Note</p> <p>Whether documentation is actually available depends on the mode being used and how the mode was configured and packaged with wed.</p> <p class="last">Element documentation is not provided by wed itself. The generic mode used in Wed’s demo is set to work with TEI documents, and thus provide documentations on TEI elements. This documentation was converted for use by wed but its contents was created by the authors of the TEI schema. Wed merely extracted it.</p> </div> <div class="section" id="label-visibility"> <h5>Label Visibility<a class="headerlink" href="#label-visibility" title="Permalink to this headline">¶</a></h5> <p>The editing modes of wed can be designed to assign different levels of visibility to labels. Imagine for instance a mode that represents breaks in paragraphs through line breaks and indentation, or foreign text by showing it in italics, and so on. For each element that is represented on screen using styling, it is usually not necessary to show the end and start labels of the element: the presence of the element and its extent is already visible through styling.</p> <div class="figure align-center" id="id31"> <img alt="A document shown at default label visibility. There is no element label visible in the picture." src="_images/default_label_visibility.png" /> <p class="caption"><span class="caption-text">This is an example of the situation described above in the text.</span></p> </div> <p>It still may be useful sometimes for users to see the labels. Perhaps there is an operation they want to perform that is easier to do with labels. In such case, wed allows changing the label visibility level.</p> <div class="figure align-center" id="id32"> <img alt="A document shown at increased label visibility. Every single element gets labels." src="_images/increased_label_visibility.png" /> <p class="caption"><span class="caption-text">This is an example of the same document shown earlier but with increased label visibility. You’ll notice that the word “prasāda” now has start and end labels for <code class="docutils literal notranslate"><span class="pre">foreign</span></code>. Paragraphs also have the <code class="docutils literal notranslate"><span class="pre">p</span></code> element.</span></p> </div> </div> </div> <div class="section" id="error-markers"> <h4>Error Markers<a class="headerlink" href="#error-markers" title="Permalink to this headline">¶</a></h4> <p>Error markers indicate where in the document there is a validation error. They appear as red rectangles at the location of the errors they mark.</p> <div class="figure align-center" id="id33"> <img alt="An error marker." src="_images/error_marker.png" /> <p class="caption"><span class="caption-text">An error marker appearing in an attribute value.</span></p> </div> <p>Clicking an error marker will expand the error pane if it was closed, and will scroll the pane to show the error message corresponding to the error marker. Both the marker and the error message will become selected. Selected markers and their message blink slowly to indicate that they are selected.</p> <div class="figure align-center" id="id34"> <img alt="Clicking an error marker." src="_images/error_marker_click.gif" /> <p class="caption"><span class="caption-text">When an error marker is clicked, the marker and the error’s description become selected.</span></p> </div> </div> <div class="section" id="contextual-menus"> <h4>Contextual Menus<a class="headerlink" href="#contextual-menus" title="Permalink to this headline">¶</a></h4> <p>Right-clicking on element labels or in the text contained by elements or attributes brings up a contextual menu. As the term “contextual” suggests, the content of the menu is determined by the location where the contextual menu is being invoked. In particular, the list of operations available in the menu is determined by what the Relax NG schema that governs the editing session allows in the specific location where the menu was invoked. For instance, if an element allows only the attributes <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code>, and <code class="docutils literal notranslate"><span class="pre">b</span></code> is already present on the element, then the contextual menu that you get when right-clicking on the start label of the element will show only an option to add the <code class="docutils literal notranslate"><span class="pre">a</span></code> attribute, because adding a <code class="docutils literal notranslate"><span class="pre">b</span></code> attribute again would not be valid.</p> <div class="figure align-center" id="id35"> <img alt="A contextual menu." src="_images/contextual_menu.png" /> <p class="caption"><span class="caption-text">This is a contextual menu brought up on the start label of the <code class="docutils literal notranslate"><span class="pre">title</span></code> element.</span></p> </div> <p>The top of the contextual menu contains buttons and an input field that allow filtering the list of options presented by the menu. When editing a document using a complex schema, there can be dozens of options available. Filtering helps finding the desired option quickly.</p> <p>The input field filters the options that pertain to attributes or elements on the basis of attribute name or element name. It filters other options on the basis of the name of the option shown in the menu. When you bring up the contextual menu, the input field is focused automatically, so you can type in it right away, without having to focus it with the mouse.</p> <div class="figure align-center" id="id36"> <img alt="Using the input field to filter entries in the contextual menu." src="_images/contextual_menu_text_filter.gif" /> <p class="caption"><span class="caption-text">The user brings up a contextual menu and filters options to those that contain the text <code class="docutils literal notranslate"><span class="pre">xml</span></code>.</span></p> </div> <p>The buttons above the input field allow filtering the list of options according to characteristics other than text. The buttons are divided into two groups: the first group filters by the kind of operation performed, the second group filters by what kind of XML construct the operation affects. Hovering the mouse over each button will give you a description of the filtering performed by the button. The buttons in the first group filter as follows:</p> <ul class="simple"> <li><img alt="add" src="_images/filter_add.png" /> filters the list of options to those that add content. For instance, adding elements and attributes.</li> <li><img alt="delete" src="_images/filter_delete.png" /> filters the list of options to those that delete content. For instance, deleting elements and attributes.</li> <li><img alt="wrap" src="_images/filter_wrap.png" /> filters the list of options to those that wrap content into an element. For instance, wrapping text into a new element.</li> <li><img alt="unwrap" src="_images/filter_unwrap.png" /> filters the list of options to those that unwrap content. For instance, unwrapping an element.</li> <li><img alt="other" src="_images/filter_other.png" /> filters the list of options to those that are not in one of the previous categories.</li> </ul> <p>The buttons of the second group filter as follows:</p> <ul class="simple"> <li>< filters the list of options to those that perform operations on XML elements. For instance, if you select this filter, then all options that edit attributes would be removed.</li> <li>@ filters the list of options to those that perform operations on XML attributes. For instance, if you select this filter, then all options that edit elements will be removed.</li> <li><img alt="other" src="_images/filter_other.png" /> filters the list of options to those that are not in one of the previous categories. Therefore, it would filter the list of options to remove those options that perform operations on elements or attributes.</li> </ul> <p>The first characters typed into the input field can serve to select the buttons listed above by means of the keyboard rather than using the mouse. When one of these keys is used to select a button, this key only performs the task of selecting a button <em>but does not appear in the input field</em>. The keys recognized are:</p> <ul class="simple"> <li><kbd class="kbd docutils literal notranslate">+</kbd> selects <img alt="add" src="_images/filter_add.png" /></li> <li><kbd class="kbd docutils literal notranslate">-</kbd> selects <img alt="delete" src="_images/filter_delete.png" /></li> <li><kbd class="kbd docutils literal notranslate">,</kbd> selects <img alt="wrap" src="_images/filter_wrap.png" /></li> <li><kbd class="kbd docutils literal notranslate">.</kbd> selects <img alt="unwrap" src="_images/filter_unwrap.png" /></li> <li><kbd class="kbd docutils literal notranslate">?</kbd> selects <img alt="other" src="_images/filter_other.png" /> in the first group of buttons. That is, it filters options to those that do not add, delete, wrap or unwrap.</li> <li><kbd class="kbd docutils literal notranslate"><</kbd> selects <</li> <li><kbd class="kbd docutils literal notranslate">@</kbd> selects @</li> <li><kbd class="kbd docutils literal notranslate">!</kbd> selects <img alt="other" src="_images/filter_other.png" /> in the second group of buttons. That is, it filters options to those that do not operate on elements or attributes.</li> <li><kbd class="kbd docutils literal notranslate">ESC</kbd> resets filtering. It will clear all the filtering buttons and will clear the input field. If no filtering was in effect, then it will close the contextual menu.</li> </ul> <p>Once a button has been selected, <em>either with the mouse or by using one of the keys above</em>, then the keys that select filters from that group no longer have for effect to select filters. Instead, they will be added into the input field, just like any other key. Here are some examples of this behavior:</p> <ul class="simple"> <li>If the user opens a contextual menu and types <code class="docutils literal notranslate"><span class="pre">+</span></code>, this will have for effect to select the <img alt="add" src="_images/filter_add.png" /> button and filter the options to those that add content. So far so good. Then if the user types <code class="docutils literal notranslate"><span class="pre">-</span></code>, this will <em>not</em> unselect <img alt="add" src="_images/filter_add.png" /> to select <img alt="delete" src="_images/filter_delete.png" /> instead. Rather, the <code class="docutils literal notranslate"><span class="pre">-</span></code> character will appear literally in the input field so that the end result will be that only options that add content and operate on attribute or elements which have <code class="docutils literal notranslate"><span class="pre">-</span></code> in their name.</li> <li>If the user opens a contextual menu and types <code class="docutils literal notranslate"><span class="pre">+</span></code>, and then <code class="docutils literal notranslate"><span class="pre">@</span></code>, the <img alt="add" src="_images/filter_add.png" /> and @ buttons will be selected and the list will show only those options that add attributes. After the user types <code class="docutils literal notranslate"><span class="pre">+</span></code>, the keys associated with the first group of buttons cease to select buttons, but those associated with the second group continue to be available to select one of the buttons in the second group. Once <code class="docutils literal notranslate"><span class="pre">@</span></code> has been typed too, then none of the keys that select buttons perform button selections anymore.</li> </ul> <p>Resetting filtering by typing <kbd class="kbd docutils literal notranslate">ESC</kbd> resets this behavior. In other words, the keys that select buttons become operational again.</p> <p>It is possible to select an option from the contextual menu by using the up and down arrow keys on the keyboard and typing <kbd class="kbd docutils literal notranslate">ENTER</kbd> on the desired option. <kbd class="kbd docutils literal notranslate">ESC</kbd> closes the contextual menu without performing a selection, provided there is no filtering in effect, otherwise it will clear the filtering. If filtering is in effect, then using <kbd class="kbd docutils literal notranslate">ESC</kbd> twice in a row will close the contextual menu.</p> </div> <div class="section" id="completion-menus"> <h4>Completion Menus<a class="headerlink" href="#completion-menus" title="Permalink to this headline">¶</a></h4> <p>If the schema used to edit the document specifies an enumerated list of possible values, wed will present the user with a completion menu. A common case is for attributes that may take only a limited set of values. Upon first placing the caret in a location that can be auto-completed, wed will present the whole list of possible values.</p> <div class="figure align-center" id="id37"> <img alt="A completion menu in its initial state." src="_images/completion_initial.png" /> <p class="caption"><span class="caption-text">The user just clicked into the <code class="docutils literal notranslate"><span class="pre">sample</span></code> attribute. Wed presents the list of possible values.</span></p> </div> <p>The user may use the arrows on the keyboard to go up and down the list of values to highlight a value, and hit <kbd class="kbd docutils literal notranslate">ENTER</kbd> to insert it as the attribute value. Note that hitting <kbd class="kbd docutils literal notranslate">ENTER</kbd> when no value is highlighted in the menu will insert the first value in the menu. Or the user may start typing a value at the keyboard. As a value is entered, the list of completions will be narrowed to those values that begin with the characters entered by the user. The matched prefix will be bolded in the list of values. The user may then use the keyboard arrows and <kbd class="kbd docutils literal notranslate">ENTER</kbd> to complete the value already begun. It is possible also to just type the whole value at the keyboard (which may be faster, in some cases, than fiddling with a menu), in which case the menu will close once the value is complete.</p> <div class="figure align-center" id="id38"> <img alt="A completion menu as the user types in." src="_images/completion_typing.gif" /> <p class="caption"><span class="caption-text">The user types <code class="docutils literal notranslate"><span class="pre">med</span></code> into the completion menu and then hits <kbd class="kbd docutils literal notranslate">ENTER</kbd> to complete the value.</span></p> </div> </div> <div class="section" id="replacement-menus"> <h4>Replacement Menus<a class="headerlink" href="#replacement-menus" title="Permalink to this headline">¶</a></h4> <p>Replacement menus are similar to completion menus. Completion menus appear automatically but only <em>when the document contains a value that can be completed</em>. Given an attribute that has a limited set of possible values, if the attribute is already filled with a complete value, then the completion menu does not appear. Suppose an attribute <code class="docutils literal notranslate"><span class="pre">height</span></code> which can take the values <code class="docutils literal notranslate"><span class="pre">high</span></code>, <code class="docutils literal notranslate"><span class="pre">medium</span></code>, <code class="docutils literal notranslate"><span class="pre">low</span></code>, and it is already filled with the value <code class="docutils literal notranslate"><span class="pre">medium</span></code>. If you want to change the value, you won’t be able to use the completion menu, because there’s nothing to complete since <code class="docutils literal notranslate"><span class="pre">medium</span></code> is already complete. So if you want to change the value with the help of the editor, you have to use a replacement menu by hitting <kbd class="kbd docutils literal notranslate">Ctrl-?</kbd>.</p> <p>Replacement menus are available in the same places completion menus are available. The list of values they offer is the same as the list provided by a completion menu in the same location. Choosing an item from the list in a replacement menu replaces the entire attribute value with the item selected.</p> <p>Note that replacement menus, contrarily to completion menus, do not support changing the document while the menu is open. You need to exit the menu before you can continue editing the document. If you don’t want to make a change, click outside the menu or hit <kbd class="kbd docutils literal notranslate">ESCAPE</kbd>.</p> <div class="figure align-center" id="id39"> <img alt="A replacement menu." src="_images/replacement_menu.png" /> <p class="caption"><span class="caption-text">The user just brought up the replacement menu in the <code class="docutils literal notranslate"><span class="pre">sample</span></code> attribute.</span></p> </div> </div> </div> </div> <div class="section" id="kinds-of-xml-operations"> <h2>Kinds of XML Operations<a class="headerlink" href="#kinds-of-xml-operations" title="Permalink to this headline">¶</a></h2> <p>Wed divides operations on elements and attributes into a few categories:</p> <ul class="simple"> <li>Adding. Such operations are usually marked with the <img alt="add" src="_images/filter_add.png" /> symbol. These are operations that add entirely new elements or attributes to the document. They normally do not operate on selections.</li> </ul> <div class="figure align-center" id="id40"> <img alt="A user adds an element." src="_images/adding.gif" /> <p class="caption"><span class="caption-text">The user adds an <code class="docutils literal notranslate"><span class="pre">abbr</span></code> element to the document.</span></p> </div> <ul class="simple"> <li>Deleting. Such operations are usually marked with the <img alt="delete" src="_images/filter_delete.png" /> symbol. These are operations that remove whole elements or attributes from the document. They normally do not operate on selections.</li> </ul> <div class="figure align-center" id="id41"> <img alt="A user deletes an element." src="_images/deleting.gif" /> <p class="caption"><span class="caption-text">The user deletes an <code class="docutils literal notranslate"><span class="pre">abbr</span></code> element from the document.</span></p> </div> <ul class="simple"> <li>Wrapping. Such operations are usually marked with the <img alt="wrap" src="_images/filter_wrap.png" /> symbol. These operations add an element around a section of the document being edited. The section is indicated by clicking and dragging with the mouse to select a part of the document. Therefore, wrapping operations appear in the contextual menu only if a selection is in effect. They “wrap” the selection in a new element.</li> </ul> <div class="figure align-center" id="id42"> <img alt="A user wraps an element." src="_images/wrapping.gif" /> <p class="caption"><span class="caption-text">The user wraps text in an <code class="docutils literal notranslate"><span class="pre">abbr</span></code> element.</span></p> </div> <ul class="simple"> <li>Unwrapping. Such operations are usually marked with the <img alt="unwrap" src="_images/filter_unwrap.png" /> symbol. This is the reverse of wrapping. These operations operate on an element so as to remove the element but put the element’s original content in place of the element being removed. They normally do not operate on select