wed
Version:
Wed is a schema-aware editor for XML documents.
1,656 lines • 110 kB
HTML
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<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">
<!-- Local TOC -->
<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 selections.</li>
</ul>
<div class="figure align-center" id="id43">
<img alt="A user unwraps the content of an element." src="_images/unwrapping.gif" />
<p class="caption"><span class="caption-text">The user unwraps the content of an element.</span></p>
</div>
</div>
<div class="section" id="searching">
<h2>Searching<a class="headerlink" href="#searching" title="Permalink to this headline">¶</a></h2>
<p>Wed offers two types of searches: quick searches, and dialog searches.</p>
<p>Moreover, wed will search through text in two possible contexts. Do not confuse
context and scope. The scope is the range of the document within which the
search operates. The context determines what <em>in this range</em> is part of the
search. Here are the two contexts:</p>
<ul>
<li><p class="first">Element text. This encompasses only the text of elements. For instance,
searching for <code class="docutils literal notranslate"><span class="pre">some</span></code> in the XML <code class="docutils literal notranslate"><span class="pre"><some.element</span> <span class="pre">some.attribute="some</span>
<span class="pre">value">some</span> <span class="pre">text</some.element></span></code> would only hit the word <code class="docutils literal notranslate"><span class="pre">some</span></code> that
appears before the word <code class="docutils literal notranslate"><span class="pre">text</span></code> and nothing else.</p>
<p>Note that because this context ignores the XML tags, it is possible for it to
perform matches across element boundaries. For instance if you search for <code class="docutils literal notranslate"><span class="pre">I</span>
<span class="pre">am</span> <span class="pre">happy</span></code> in the XML <code class="docutils literal notranslate"><span class="pre"><p>I</span> <span class="pre"><bold>am</bold></span> <span class="pre">happy</p></span></code>, the search will
match the entire content of <code class="docutils literal notranslate"><span class="pre">p</span></code>. That is, the <code class="docutils literal notranslate"><span class="pre">bold</span></code> element does not
prevent the match.</p>
</li>
<li><p class="first">Attribute values. This encompasses only the values of element attributes. In
the example above, a search for <code class="docutils literal notranslate"><span class="pre">some</span></code> would match only the word <code class="docutils literal notranslate"><span class="pre">some</span></code>
appearing before <code class="docutils literal notranslate"><span class="pre">value</span></code>.</p>
<p>Note that this kind of search does not span attributes. For instance, if you
have <code class="docutils literal notranslate"><span class="pre"><p</span> <span class="pre">type="abc"</span> <span class="pre">subtype="def"/></span></code> and search for <code class="docutils literal notranslate"><span class="pre">abcdef</span></code> you will
<strong>not</strong> get a match that spans the values of <code class="docutils literal notranslate"><span class="pre">@type</span></code> and <code class="docutils literal notranslate"><span class="pre">@subtype</span></code>. This
is probably not a desirable behavior at any rate, but we’re mentioning it,
just in case.</p>
</li>
</ul>
<p>It is not possible to search for element names or attribute names with the quick
search or dialog search. Nor is it possible to search for text which is purely
created for the sake of displaying the XML. Here’s an example of the
latter. Suppose the following document:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">doc</span><span class="o">></span>
<span class="o"><</span><span class="n">p</span><span class="o">></span>
<span class="n">Johnson</span> <span class="n">demonstrated</span> <span class="p">(</span><span class="o"><</span><span class="n">ref</span> <span class="n">target</span><span class="o">=</span><span class="s2">"/some/bibliographical/item"</span><span class="o">/></span><span class="p">)</span> <span class="n">that</span> <span class="o">...</span>
<span class="o"></</span><span class="n">p</span><span class="o">></span>
<span class="o"></</span><span class="n">doc</span><span class="o">></span>
</pre></div>
</div>
<p>In this example, <code class="docutils literal notranslate"><span class="pre">ref</span></code> is a reference to a bibliographical item. Your wed
mode, fetches the bibliographical information and shows it instead of showing
the XML element as-is. So what you see is something like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">doc</span> <span class="o">></span>
<span class="n">p</span> <span class="o">></span>
<span class="n">Johnson</span> <span class="n">demonstrated</span> <span class="p">(</span><span class="n">Johnson</span><span class="p">,</span> <span class="n">Five</span> <span class="n">Ways</span> <span class="n">to</span> <span class="n">Eat</span> <span class="n">Sushi</span><span class="p">)</span> <span class="n">that</span> <span class="o">...</span>
<span class="o"><</span> <span class="n">p</span>
<span class="o"><</span> <span class="n">doc</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">doc</span> <span class="pre">></span></code>, <code class="docutils literal notranslate"><span class="pre">p</span> <span class="pre">></span></code>, <code class="docutils literal notranslate"><span class="pre">p</span> <span class="pre"><</span></code> and <code class="docutils literal notranslate"><span class="pre"><</span> <span class="pre">doc</span></code> are the start and end labels that
normally shows for elements. The string <code class="docutils literal notranslate"><span class="pre">Johnson,</span> <span class="pre">Five</span> <span class="pre">Ways</span> <span class="pre">to</span> <span class="pre">Eat</span> <span class="pre">Sushi</span></code> is
text that is not part of the XML but that the editing mode adds when it shows
you your document. It is more informative than <code class="docutils literal notranslate"><span class="pre"><ref</span>
<span class="pre">target="/some/bibliographical/item"/></span></code>. At any rate, neither searching through
element text or element attributes can find that text.</p>
<p>If you need to search for element names, attribute names or text created for
display purposes, you must use your browser’s built-in search.</p>
<div class="section" id="quick-search">
<h3>Quick Search<a class="headerlink" href="#quick-search" title="Permalink to this headline">¶</a></h3>
<p>You can use <kbd class="kbd docutils literal notranslate">Ctrl-f</kbd> to quick-search forward, and <kbd class="kbd docutils literal notranslate">Ctrl-b</kbd> to
quick-search backwards. When you hit either of these shortcuts, the <a class="reference internal" href="#the-minibuffer">minibuffer</a> becomes active and prompts you for a search term. As you
type the term you are searching for, wed will search through the document and
highlight in yellow the term it finds. To move to another hit, press
<kbd class="kbd docutils literal notranslate">Ctrl-f</kbd> or <kbd class="kbd docutils literal notranslate">Ctrl-b</kbd> again. Type <kbd class="kbd docutils literal notranslate">ESCAPE</kbd> to end the search.</p>
<p>If you have a selection in effect when you start the search, the search will be
scoped to that selection. That is, the search will only search between the start
and end of the selection. (The selection disappears while you are searching:
this is normal and a current limitation of wed.) If you have no selection in
effect when you start the search, then the whole document will be searched.</p>
<div class="figure align-center" id="id44">
<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. You can see the word “original” was found and
highlighted in yellow. When you hit the end of the search scope in either
direction, the highlight will disappear. If you then hit the shortcut to
continue in the same direction you were going, the search will continue from the
start of your search scope.</p>
</div>
<div class="section" id="dialog-search">
<h3>Dialog Search<a class="headerlink" href="#dialog-search" title="Permalink to this headline">¶</a></h3>
<p>You can use <kbd class="kbd docutils literal notranslate">Ctrl-Shift-f</kbd> to search forward, and <kbd class="kbd docutils literal notranslate">Ctrl-Shift-b</kbd> to
search backwards. Dialog searches are thus named because they bring up a dialog
box to provide the user with more search options than the quick searches.</p>
<p>Just like quick searches, if you have a selection in effect when you start the
search, the search will be scoped to that selection. That is, the search will
only search between the start and end of the selection. (The selection
disappears while you are searching: this is normal and a current limitation of
wed.) If you have no selection in effect when you start the search, then the
whole document will be searched.</p>
<div class="figure align-center" id="id45">
<img alt="Shows the dialog that is brought up by dialog searches." src="_images/dialog_search.png" />
<p class="caption"><span class="caption-text">A dialog search.</span></p>
</div>
<p>The “Search for:” field is where you type the term you are searching for.</p>
<p>The “Replace with:” field is where you type the text you want to use to replace
the hits you find.</p>
<p>The “Direction”: buttons determine in which direction the search goes. The
direction is initially determined by which shortcut you use to bring up the
search but you may change it later if you want.</p>
<p>The “Context:” buttons determine what is searched. There are two possible
contexts:</p>
<ul class="simple">
<li>“Only element text”: this searches only through the text of
elements. Consequently, attributes are not searched.</li>
<li>“Only attributes”: this searches only through the attribute values of
elements. Consequently, the text of elements is not searched.</li>
</ul>
<p>The buttons:</p>
<ul class="simple">
<li>“Find” looks for the next match.</li>
<li>“Replace and Find” replaces the current match and finds the next.</li>
<li>“Replace All” replaces all matches until the search reaches a boundary of the
search scope currently in effect. The boundary depends on the direction of the
search. If searching forward, the boundary marking the end of the search is
the end of the scope. If searching backwards, it is the start of the scope.</li>
<li>“Close” closes the dialog.</li>
</ul>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>Wed cannot replace hits that select an ill-formed portion of an XML
document. For instance, you have the XML <code class="docutils literal notranslate"><span class="pre">tea<bold>pot</bold></span></code>
and you search for <code class="docutils literal notranslate"><span class="pre">ap</span></code>. If we mark the start and end of the hit
with the element <code class="docutils literal notranslate"><span class="pre">mark</span></code> we’d have
<code class="docutils literal notranslate"><span class="pre">te<mark>a<bold>p</mark>ot</bold></span></code>. This is not well-formed XML
because <code class="docutils literal notranslate"><span class="pre">mark</span></code> and <code class="docutils literal notranslate"><span class="pre">bold</span></code> are straddling. Wed cannot replace
such cases, and will disable the “Replace and Find” button when you
land on such a case.</p>
<p class="last">Note however that the “Replace All” button is never disabled. When
you use “Replace All”, wed replaces all instances that it <strong>can</strong>
replace.</p>
</div>
</div>
</div>
<div class="section" id="saving">
<h2>Saving<a class="headerlink" href="#saving" title="Permalink to this headline">¶</a></h2>
<p>You can save by using <kbd class="kbd docutils literal notranslate">Ctrl-s</kbd> or whatever means provided by the
application that uses wed. Possible outcomes:</p>
<ul>
<li><p class="first">The data is saved. You will see a message telling you that the data was saved,
and the <a class="reference external" href="ModificationandSaveStatus">save status</a> will indicate the data
was saved.</p>
<div class="figure align-center" id="id46">
<img alt="A green message saying "Saved"." src="_images/saved_message.png" />
<p class="caption"><span class="caption-text">This is the message that a user gets when a document was saved.</span></p>
</div>
</li>
<li><p class="first">Wed is disconnected from the server. You will get a dialog box saying:</p>
<blockquote>
<div><p>It appears your browser is disconnected from the server. Editing is frozen
until the connection is reestablished. Dismissing this dialog will retry
saving. If the operation is successful, you’ll be able to continue
editing. If not, this message will reappear.</p>
</div></blockquote>
<p>You’re effectively prevented from further edits until wed is able to
reestablish connectivity with the server.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">It is possible to configure wed to use other types of saving
mechanisms than sending data to a server. For instance,
<code class="docutils literal notranslate"><span class="pre">localStorage</span></code> can be used to record data in the browser
itself. What mechanism wed uses depends on how the application in
which wed is used has configured wed.</p>
</div>
</li>
<li><p class="first">The server responded to the save request with a message that indicated that
the document being edited with wed changed on the server. In other words,
while you were editing a document someone else edited and saved the same
document, or an automated process modified the document. You’ll get a dialog
box with the following message:</p>
<blockquote>
<div><p>Your document was edited by someone else since you last loaded or saved
it. You must reload it before trying to edit further.</p>
</div></blockquote>
<p>On reload, wed will acquire a fresh copy of the document from the
server. <strong>The edits you performed on your document will be lost.</strong> Wed is not
currently equipped to deal with concurrent modifications from multiple
sources.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>This is another instance where application that makes use of wed is
the party responsible for providing the means to resolve concurrent
modification conflicts or prevent them from happening in the first
place.</p>
<p class="last">The solution is really application-specific. For <a class="reference external" href="https://btw.mangalamresearch.org">BTW</a> we decided
that locking documents to prevent concurrent modifications was the
right solution. Another project could conceivably decide to solve
conflicts in a way similar to what <code class="docutils literal notranslate"><span class="pre">git</span></code> does for merge
conflicts. There’s no single answer here.</p>
</div>
</li>
<li><p class="first">There is an application-specific error which prevents saving the data. You
will see a message in a red notification bubble telling you what error
happened, and the <a class="reference external" href="ModificationandSaveStatus">save status</a> will not be
updated. The content of the error message depends on the specific nature of
the error. For instance, an application which requires that documents be given
titles before they are saved could report an error if you try to save a
document without a title.</p>
</li>
</ul>
</div>
<div class="section" id="copy-cut-and-paste">
<h2>Copy, Cut and Paste<a class="headerlink" href="#copy-cut-and-paste" title="Permalink to this headline">¶</a></h2>
<p>Wed allows copying, cutting and pasting parts of a document. When you perform a
copy operation, the data is copied from the document to the clipboard. When you
perform a cut operation, the data is copied from the document to the clipboard,
and is also removed from the document. When you perform a paste operation, the
data is copied from the clipboard to the document. This is not specific to wed
but is the standard way software manipulates the keyboard.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Readers needing more details about how copy, cut and paste interact
with the clipboard should consult general-purpose documentation about
how to use computers.</p>
</div>
<p>Wed supports two selection modes:</p>
<ul class="simple">
<li>Span mode: a mode by which you must select a span of the document to operate
on. This is similar to how you would select text in common plain text editors
like Notepad or word-processors like Word.</li>
<li>Unit mode: a mode by which you direct the editor to copy or cut entire XML
structural units, like attributes or elements.</li>
</ul>
<p>You can use the toolbar or <kbd class="kbd docutils literal notranslate">Ctrl-SPACE</kbd> to change the selection mode. Wed
operates in a way that prevents mixing data from the two modes described
above. If you start copying data to the clipboard in span mode, then switch to
unit mode and copy more data, then the data you copied in span mode will be
removed from the clipboard. The same is true if you start in unit mode and
switch to span mode.</p>
<div class="section" id="span-mode">
<h3>Span Mode<a class="headerlink" href="#span-mode" title="Permalink to this headline">¶</a></h3>
<p>This mode works mostly like how copy, cut, and paste works in plain text editors
like Notepad, or word-processors like Word. You select a span of the document
and direct the editor to perform an operation on it. However, because wed edits
XML, there are some limitations to what you can do.</p>
<div class="section" id="copy">
<h4>Copy<a class="headerlink" href="#copy" title="Permalink to this headline">¶</a></h4>
<p>Copying contents <em>as XML</em> works only if the selection being cut starts and ends
inside the same XML element or the same XML attribute value. The selection can
span over XML elements, provided that it completely contains these elements. If
your selection straddles XML elements, then it will be copied <em>naively</em>, and you
will get a notification telling you that your selection was copied as such.</p>
<p>Note that “copied naively” here means that the content will be copied by the
browser itself, as if you were copying text from any web page. This means that
any decorations that wed creates and is part of the selection, will have its
textual content copied.</p>
<div class="figure align-center" id="id47">
<img alt="A selection which cannot be copied as XML." src="_images/invalid_selection_cut.png" />
<p class="caption"><span class="caption-text">This selection cannot be copied as XML because it begins in one <code class="docutils literal notranslate"><span class="pre">p</span></code>
element but ends in the subsequent <code class="docutils literal notranslate"><span class="pre">p</span></code> element.</span></p>
</div>
<div class="figure align-center" id="id48">
<img alt="A selection which can be copied as XML." src="_images/valid_selection_cut.png" />
<p class="caption"><span class="caption-text">This selection can be copied as XML because it begins and ends in the same
<code class="docutils literal notranslate"><span class="pre">p</span></code> element. There is an <code class="docutils literal notranslate"><span class="pre">lb</span></code> element inside the selection, which is
fine.</span></p>
</div>
</div>
<div class="section" id="cut">
<h4>Cut<a class="headerlink" href="#cut" title="Permalink to this headline">¶</a></h4>
<p>Cutting will work only if the selection being cut starts and ends inside the
same XML element or the same XML attribute value. The selection can span over
XML elements, provided that it completely contains these elements.</p>
<div class="figure align-center" id="id49">
<img alt="A selection which cannot be cut." src="_images/invalid_selection_cut.png" />
<p class="caption"><span class="caption-text">This selection cannot be cut from the document because it begins in one <code class="docutils literal notranslate"><span class="pre">p</span></code>
element but ends in the subsequent <code class="docutils literal notranslate"><span class="pre">p</span></code> element.</span></p>
</div>
<div class="figure align-center" id="id50">
<img alt="A selection which can be cut." src="_images/valid_selection_cut.png" />
<p class="caption"><span class="caption-text">This selection can be cut from the document because it begins and ends in the
same <code class="docutils literal notranslate"><span class="pre">p</span></code> element. There is an <code class="docutils literal notranslate"><span class="pre">lb</span></code> element inside the selection, which is
fine.</span></p>
</div>
<p>A selection that cannot be cut can still be copied.</p>
</div>
<div class="section" id="paste">
<h4>Paste<a class="headerlink" href="#paste" title="Permalink to this headline">¶</a></h4>
<p>Wed will attempt parsing the pasted text, and if it is a well-formed XML
fragment, it will insert into your document the <em>parsed XML</em>, even if the
original document was plain text. Here’s an example. Suppose you have a plain
text editor opened, and you have the text <code class="docutils literal notranslate"><span class="pre"><foo>something</foo></span></code> in it. If you
select that text and paste it into wed, wed will create a <code class="docutils literal notranslate"><span class="pre">foo</span></code> element that
contains the text <code class="docutils literal notranslate"><span class="pre">something</span></code>. It will not paste the text
<code class="docutils literal notranslate"><span class="pre"><foo>something</foo></span></code> <em>as text</em>.</p>
<p>If the text in the clipboard is not well-formed XML, then wed will insert it
into your document as text. So if you have the copy the text <code class="docutils literal notranslate"><span class="pre"><foo</span> <span class="pre">blah</foo></span></code>
from your plain text editor, and paste it into wed, this will be pasted <em>as
text</em>.</p>
<p>Note that pasting into attribute values always pastes the clipboard data as text
because attributes cannot contain anything else than text.</p>
</div>
</div>
<div class="section" id="unit-mode">
<h3>Unit Mode<a class="headerlink" href="#unit-mode" title="Permalink to this headline">¶</a></h3>
<p>In unit mode, the editor copies entire XML structural units. There are two kinds
of XML structural units that wed operates on:</p>
<ul class="simple">
<li>attributes,</li>
<li>elements.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">We talk of “units” because other candidate terms already have specific
meanings in XML. We cannot talk of “elements mode” because XML
elements are just <em>one</em> specific type of XML structure, and the mode
also works on attributes, which are not elements. We cannot talk of
“entities mode” because entities are another specific XML
structure. “Unit” was one term that does not already have a special
meaning in basic XML parlance.</p>
</div>
<p>Besides operating on XML structural unit, unit mode also allows a kind of
operation that span mode does not allow: it allows adding to the contents of the
clipboard instead of replacing it. So besides copy and cut, you can also
copy-add and cut-add.</p>
<div class="section" id="indicating-units">
<h4>Indicating Units<a class="headerlink" href="#indicating-units" title="Permalink to this headline">¶</a></h4>
<p>In this mode you do not use a selection to indicate which unit you want to
operate on. Indeed, <strong>you cannot set a selection while in unit mode</strong>. Instead,
when you copy or cut, the editor will copy or cut the smallest unit enclosing
the current caret position. We call it the “smallest enclosing unit”, for short.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">People who are used to think of XML as a tree of nodes might find it
easier to use an alternative way to think about how units are
selected. The “smallest enclosing unit” is always equivalent to the
tree leaf that immediately contains the caret, with the caveat that
text nodes are ignored. For instance, if one imagines the XML document
as a DOM tree and the caret is in a text node, then the smallest
enclosing unit is the element which contains the text node, not the
text node itself.</p>
</div>
<p>Look at the following example:</p>
<div class="figure align-center">
<img alt="A caret in an attribute." src="_images/caret_in_attribute.png" />
</div>
<p>In this example, the caret is in the <code class="docutils literal notranslate"><span class="pre">rend</span></code> attribute of the first <code class="docutils literal notranslate"><span class="pre">p</span></code>
element. The units that enclose the caret are:</p>
<ul class="simple">
<li>the attribute <code class="docutils literal notranslate"><span class="pre">rend</span></code>,</li>
<li>the element <code class="docutils literal notranslate"><span class="pre">p</span></code> (the first one),</li>
<li>the element <code class="docutils literal notranslate"><span class="pre">body</span></code>,</li>
<li>the element <code class="docutils literal notranslate"><span class="pre">text</span></code>.</li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">rend</span></code> is the <em>smallest</em> enclosing unit because all other enclosing units
contain more data than <code class="docutils literal notranslate"><span class="pre">rend</span></code> does. For instance, <code class="docutils literal notranslate"><span class="pre">p</span></code> contains another
attribute besides <code class="docutils literal notranslate"><span class="pre">rend</span></code> and contains text.</p>
<p>Consider this example:</p>
<div class="figure align-center">
<img alt="A caret in text." src="_images/caret_in_text.png" />
</div>
<p>In this example, the caret is in the text of the first <code class="docutils literal notranslate"><span class="pre">p</span></code> element. The units
that enclose the caret are:</p>
<ul class="simple">
<li>the element <code class="docutils literal notranslate"><span class="pre">p</span></code> (the first one),</li>
<li>the element <code class="docutils literal notranslate"><span class="pre">body</span></code>,</li>
<li>the element <code class="docutils literal notranslate"><span class="pre">text</span></code>.</li>
</ul>
<p><code class="docutils literal notranslate"><span class="pre">p</span></code> is the <em>smallest</em> enclosing unit because all other enclosing units contain
more than <code class="docutils literal notranslate"><span class="pre">p</span></code>. For instance, <code class="docutils literal notranslate"><span class="pre">body</span></code> contains two other elements besides the
<code class="docutils literal notranslate"><span class="pre">p</span></code> element in which the caret is located.</p>
<p>Consider this similar example:</p>
<div class="figure align-center">
<img alt="Caret in an element's name." src="_images/caret_in_element_name.png" />
</div>
<p>In the example, the caret is at the start of the start label for the element
<code class="docutils literal notranslate"><span class="pre">p</span></code>. Since it is outside of any attribute, then the smallest enclosing unit is
like in the previous example: the first <code class="docutils literal notranslate"><span class="pre">p</span></code> element.</p>
<p>Consider this example:</p>
<div class="figure align-center">
<img alt="Caret between elements." src="_images/caret_between_elements.png" />
</div>
<p>In this example, the caret is just before the first <code class="docutils literal notranslate"><span class="pre">p</span></code> element in
<code class="docutils literal notranslate"><span class="pre">body</span></code>. The caret is not in any of the elements that are children of <code class="docutils literal notranslate"><span class="pre">body</span></code>
(the two <code class="docutils literal notranslate"><span class="pre">p</span></code> elements and the <code class="docutils literal notranslate"><span class="pre">div</span></code> element). The smallest enclosing element
is <code class="docutils literal notranslate"><span class="pre">body</span></code>.</p>
</div>
<div class="section" id="copy-and-cut">
<h4>Copy and Cut<a class="headerlink" href="#copy-and-cut" title="Permalink to this headline">¶</a></h4>
<p>Performing a copy replaces the data in the clipboard with the smallest enclosing
unit. A cut is the same as a copy, except that the data that is put into
the clipboard is also removed from the document.</p>
</div>
<div class="section" id="copy-add-and-cut-add">
<h4>Copy-Add and Cut-Add<a class="headerlink" href="#copy-add-and-cut-add" title="Permalink to this headline">¶</a></h4>
<p>The keyboard shortcuts for these operations are those for the non-adding
operations but with the alphabetical letter capitalized. So whereas a plain copy
operation is <kbd class="kbd docutils literal notranslate">Ctrl-s</kbd>, the copy-add operation is <kbd class="kbd docutils literal notranslate">Ctrl-Shift-s</kbd>. The
practical difference is that the user must hold the <kbd class="kbd docutils literal notranslate">Shift</kbd> key to get the
“-add” variant. (On OS X, the corresponding combinations are <a href="#id2"><span class="problematic" id="id3">:kdb:`Cmd-s`</span></a> and
<a href="#id4"><span class="problematic" id="id5">:kdb:`Cmd-Shift-s`</span></a>. Again, the practical difference is whether or not the
<kbd class="kbd docutils literal notranslate">Shift</kbd> key is held.)</p>
<p>A copy-add operation <strong>adds</strong> the smallest enclosing unit to data already
in the clipboard. Suppose you are in unit selection mode, and you put your caret
in an attribute named <code class="docutils literal notranslate"><span class="pre">a</span></code> and do a copy. The clipboard data is <em>replaced</em> with
the attribute <code class="docutils literal notranslate"><span class="pre">a</span></code>. Then you put your caret in an attribute named <code class="docutils literal notranslate"><span class="pre">b</span></code> and do
a copy-add. The attribute <code class="docutils literal notranslate"><span class="pre">b</span></code> is <em>added</em> to the attribute already in the
clipboard, so that the clipboard will contain two attributes: <code class="docutils literal notranslate"><span class="pre">a</span></code> and
<code class="docutils literal notranslate"><span class="pre">b</span></code>. If you had done a copy instead of a copy-add when you were in <code class="docutils literal notranslate"><span class="pre">b</span></code>, then
the clipboard would contain only one attribute, the attribute <code class="docutils literal notranslate"><span class="pre">b</span></code>.</p>
<p>The same thing happens if you place your caret to select elements instead of
attributes. You could copy into the clipboard an element <code class="docutils literal notranslate"><span class="pre">p</span></code> from the start of
your document, and then copy-add an element <code class="docutils literal notranslate"><span class="pre">quote</span></code> from the end of your
document. The clipboard will contain both elements.</p>
<p>It is important to note that the “..-add” operations do not allow mixing
heterogeneous units in the clipboard:</p>
<ul class="simple">
<li>if you copy an attribute into the clipboard and then copy-add an element, the
copy-add operation will do nothing, and you will get a notification.</li>
<li>if you copy an element into the clipboard and then copy-add an attribute, the
copy-add operation will do nothing, and you will get a notification.</li>
</ul>
<p>As usual, the only difference between copy-add and cut-add is that the cut-add
operation copies to the clipboard but <em>also</em> removes the copied data from the
document.</p>
</div>
<div class="section" id="pasting">
<h4>Pasting<a class="headerlink" href="#pasting" title="Permalink to this headline">¶</a></h4>
<p>Note that because wed is an XML editor, there are a special considerations
regarding how attributes are handled. Wed does not ever violate the general XML
rule that elements cannot hold the same attribute twice. For instance, this is
not well-formed XML:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">p</span> <span class="n">n</span><span class="o">=</span><span class="s2">"value one"</span> <span class="n">n</span><span class="o">=</span><span class="s2">"value two"</span><span class="o">></span><span class="n">text</span><span class="o"></</span><span class="n">p</span><span class="o">></span>
</pre></div>
</div>
<p>Wed does not allow you to create this kind of structure. The consequence of this
is that if you use the copy-add or cut-add operations on an attribute you have
already put into the clipboard, then you are changing the value of that
attribute in the clipboard. Consider the following XML:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">p</span> <span class="n">n</span><span class="o">=</span><span class="s2">"value one"</span><span class="o">></span><span class="n">First</span> <span class="n">paragraph</span><span class="o"></</span><span class="n">p</span><span class="o">></span>
<span class="o"><</span><span class="n">p</span> <span class="n">n</span><span class="o">=</span><span class="s2">"value two"</span><span class="o">></span><span class="n">Second</span> <span class="n">paragraph</span><span class="o"></</span><span class="n">p</span><span class="o">></span>
<span class="o"><</span><span class="n">p</span> <span class="n">n</span><span class="o">=</span><span class="s2">"value three"</span><span class="o">></span><span class="n">Third</span> <span class="n">paragraph</span><span class="o"></</span><span class="n">p</span><span class="o">></span>
</pre></div>
</div>
<p>Suppose you set the editor to unit selection mode, and put your caret in the
<code class="docutils literal notranslate"><span class="pre">n</span></code> attribute of the first paragraph and copy it. The clipboard contains
<code class="docutils literal notranslate"><span class="pre">n="value</span> <span class="pre">one"</span></code>. Then you put your caret into the <code class="docutils literal notranslate"><span class="pre">n</span></code> attribute of the
second paragraph, and copy-add it. Because of the XML rule mentioned above, the
clipboard will contain <code class="docutils literal notranslate"><span class="pre">n="value</span> <span class="pre">two"</span></code>. It will not contain two <code class="docutils literal notranslate"><span class="pre">n</span></code>
attributes.</p>
<p>This XML rule against duplicate attributes applies when pasting too. In the same
example above, if after the operations described earlier, you move the caret to
the third paragraph, and paste, then the paragraph will be changed to:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">p</span> <span class="n">n</span><span class="o">=</span><span class="s2">"value two"</span><span class="o">></span><span class="n">Third</span> <span class="n">paragraph</span><span class="o"></</span><span class="n">p</span><span class="o">></span>
</pre></div>
</div>
<p>It will not get two <code class="docutils literal notranslate"><span class="pre">n</span></code> attributes.</p>
</div>
</div>
</div>
<div class="section" id="undo-and-redo">
<h2>Undo and Redo<a class="headerlink" href="#undo-and-redo" title="Permalink to this headline">¶</a></h2>
<p>Wed maintains a list of the operations that have been performed on the document
being edited. This list is created anew with each editing session. In other
words, each time you open a document with wed, it creates a new list. You can
use <kbd class="kbd docutils literal notranslate">Ctrl-z</kbd> to undo the last operation. Undoing again, will undo the
operation before the last one, etc. You can undo as many editing operations as
you want, up to the start of the undo list. Conversely, <kbd class="kbd docutils literal notranslate">Ctrl-y</kbd> will redo
the operation that was just undone. It is useful in cases where you’ve undone
more than you meant to.</p>
</div>
<div class="section" id="keyboard-shortcuts">
<span id="help-keyboard-shortcuts"></span><h2>Keyboard Shortcuts<a class="headerlink" href="#keyboard-shortcuts" title="Permalink to this headline">¶</a></h2>
<p>“Shortcut” is a bit of a misnomer, since some of the functions mentioned here
are available only through the keyboard, but we’ll stick with it.</p>
<p>In the following table, key names that are more than one character specify the
keys name. For instance, <code class="docutils literal notranslate"><span class="pre">SPACE</span></code> is the space bar on the keyboard.</p>
<table border="1" class="docutils">
<colgroup>
<col width="20%" />
<col width="20%" />
<col width="60%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">PC Key</th>
<th class="head">Mac Key</th>
<th class="head">Function</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">F1</kbd></td>
<td><kbd class="kbd docutils literal notranslate">F1</kbd></td>
<td>Bring up the help.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-/</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-/</kbd></td>
<td>Bring up the <a class="reference internal" href="#contextual-menus">contextual menu</a>.</td>
</tr>
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">Ctrl-?</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-?</kbd></td>
<td>Bring up the <a class="reference internal" href="#replacement-menus">replacement menu</a>.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-[</kbd></td>
<td> </td>
<td>Decrease the <a class="reference internal" href="#label-visibility">label visibility level</a>.</td>
</tr>
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">Ctrl-]</kbd></td>
<td> </td>
<td>Increase the <a class="reference internal" href="#label-visibility">label visibility level</a>.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-SPACE</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Ctrl-SPACE</kbd></td>
<td>Switch to the next <a href="#id57"><span class="problematic" id="id58">`selection mode <Cut, Copy and Paste_>`_</span></a>.</td>
</tr>
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">Ctrl-z</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-z</kbd></td>
<td><a class="reference internal" href="#undo-and-redo">Undo</a> an operation.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-y</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-y</kbd></td>
<td><a class="reference internal" href="#undo-and-redo">Redo</a> an operation.</td>
</tr>
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">Ctrl-c</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-c</kbd></td>
<td><a href="#id59"><span class="problematic" id="id60">`Copy <Cut, Copy and Paste_>`_</span></a> content.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-Shift-c</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-Shift-c</kbd></td>
<td><a href="#id61"><span class="problematic" id="id62">`Copy-add <Cut, Copy and Paste_>`_</span></a> content.</td>
</tr>
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">Ctrl-x</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-x</kbd></td>
<td><a href="#id63"><span class="problematic" id="id64">`Cut <Cut, Copy and Paste_>`_</span></a> content.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-Shift-x</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-Shift-x</kbd></td>
<td><a href="#id65"><span class="problematic" id="id66">`Cut-add <Cut, Copy and Paste_>`_</span></a> content.</td>
</tr>
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">Ctrl-v</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-v</kbd></td>
<td><a href="#id67"><span class="problematic" id="id68">`Paste <Cut, Copy and Paste_>`_</span></a> content.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-s</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-s</kbd></td>
<td><a class="reference internal" href="#saving">Save</a> content.</td>
</tr>
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">Ctrl-f</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-f</kbd></td>
<td><a class="reference internal" href="#quick-search">Quick search</a> forward.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-b</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-b</kbd></td>
<td><a class="reference internal" href="#quick-search">Quick search</a> backwards.</td>
</tr>
<tr class="row-even"><td><kbd class="kbd docutils literal notranslate">Ctrl-Shift-f</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-Shift-f</kbd></td>
<td><a class="reference internal" href="#dialog-search">Dialog search</a> forward.</td>
</tr>
<tr class="row-odd"><td><kbd class="kbd docutils literal notranslate">Ctrl-Shift-b</kbd></td>
<td><kbd class="kbd docutils literal notranslate">Cmd-Shift-b</kbd></td>
<td><a class="reference internal" href="#dialog-search">Dialog search</a> backwards.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="browser-requirements">
<span id="help-browser-requirements"></span><h2>Browser Requirements<a class="headerlink" href="#browser-requirements" title="Permalink to this headline">¶</a></h2>
<p>Wed is primarily developed using a recent version of Chrome. (But see a note
about Chrome 34 below.)</p>
<p>Here is the list of officially supported browsers, in order of decreasing
priority. The higher a browser is in the list, the less likely you are to run
into issues and the higher the priority for resolving bugs happening with this
browser.</p>
<ul class="simple">
<li>The latest stable version of Chrome.</li>
<li>The latest stable version of Edge, but <a class="reference internal" href="#edge">see the section on Edge</a>.</li>
<li>Versions of Chrome or Edge older than the latest stable version, but not very
old. (Yeah, this is vague. Sorry about that.)</li>
</ul>
<p>File an issue on github if you find a problem with one of the supported browsers
above.</p>
<p>We would like to support phone and tablet browsers but due to a lack of
development resources, such support is unlikely to materialize soon. In
decreasing order of likelihood, the following cases are unlikely to ever be
supported:</p>
<ul class="simple">
<li>Versions of Chrome or Edge older than those mentioned above.</li>
<li>Firefox. It deserves its own <a class="reference internal" href="#firefox">discussion</a>.</li>
<li>IE. Support for IE 11 has become too costly. Resuming support for IE is
extremely unlikely, because wed has accumulated features and methods that do
not work on these browsers.</li>
<li>Chrome 34: the luminaries at Google decided to remove <code class="docutils literal notranslate"><span class="pre">Attr.ownerElement</span></code>
from Chrome 34. It was reintroduced in Chrome 35. We’ll probably never have
support for Chrome 34.</li>
<li>Antique browsers.</li>
<li>Oddball browsers or other software or hardware systems that present web
pages. (E.g. gaming consoles, smart TVs.)</li>
<li>Operating systems or browsers no longer supported by their own vendors.</li>
</ul>
<div class="section" id="edge">
<h3>Edge<a class="headerlink" href="#edge" title="Permalink to this headline">¶</a></h3>
<p>Cut-copy-paste are not working well in Edge, and there is currently no
development resource available to devote to it. The root cause is that the
luminaries who develop Edge cannot be bothered to implement the clipboard API
correctly. See:</p>
<ul class="simple">
<li><a class="reference external" href="https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/14080506/">https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/14080506/</a></li>
<li><a class="reference external" href="https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/14110451/">https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/14110451/</a></li>
</ul>
<p>At the time of writing this, the bugs were reported over a year ago: response
from Microsoft… crickets.</p>
</div>
<div class="section" id="firefox">
<h3>Firefox<a class="headerlink" href="#firefox" title="Permalink to this headline">¶</a></h3>
<p>We’re hoping that the lack of Firefox support is going to be temporary. The
paragraphs below give the state of Firefox support, in reverse chronological
order (most recent on top):</p>
<p>Update August 2018: Firefox support is still suspended. Geckodriver is plagued
by asinine regressions like <a class="reference external" href="https://github.com/SeleniumHQ/selenium/issues/5621">this one</a> Returning DOM elements
is supported on all browsers and has been supported by Selenium since time
immemorial, but they managed to screw it up. <em>sigh</em></p>
<p>Update November 2017: Firefox support is still suspended. The Marionette driver
has been released. However it is so buggy that there’s no way we can run our
tests with it. And yes, we do mean “buggy” with the full force of that word. For
instance, the WebDriver specs specify that performing a click on an element
should scroll the element into view. Our tests rely on this, but Marionette does
not implement the scroll, which causes failures during testing.</p>
<p>Update Summer 2016: things are looking up. The Firefox developers have
been working on a driver named “Marionette” that <em>should</em> solve the
support problems. Stay tuned.</p>
<p>February 2016: For years, wed was supporting Firefox. Early on, Firefox was even
better supported than Chrome. However, the people responsible for maintaining
Selenium decided to stop supporting native events in Firefox and forced
developers to use synthetic events instead. The problem is that Selenium’s
support for synthetic events on Firefox is unable to accurately reproduce what
happens when a user is actually interacting with a browser, <em>which is the entire
point of using Selenium in the first place</em>. The problem has been reported, at
length:</p>
<ul class="simple">
<li>In the <cite>selenium-developers</cite> group <a class="reference external" href="https://groups.google.com/d/msg/selenium-developers/DKnG2lA-KxM/EMLiT87ykZYJ">here</a> and in following replies.</li>
<li>And these unresolved bugs <a class="reference external" href="https://github.com/SeleniumHQ/selenium/issues/825">here</a>, and <a class="reference external" href="https://github.com/SeleniumHQ/selenium/issues/1463">here</a>.</li>
<li>And these resolved bugs <a class="reference external" href="https://github.com/SeleniumHQ/selenium/issues/862">here</a> and <a class="reference external" href="https://github.com/SeleniumHQ/selenium/issues/813">here</a>.</li>
</ul>
<p>It is taking forever for the problem to get resolved. In the meantime,
we have no resources to devote to solving the issue of synthetic event
support in Firefox and so Firefox support has been temporarily pulled.</p>
</div>
<div class="section" id="ie11">
<h3>IE11<a class="headerlink" href="#ie11" title="Permalink to this headline">¶</a></h3>
<p>We no longer support any version of IE. The benefit/cost ratio does not make it
viable for us to continue supporting IE. If <strong>you</strong> want to bring back support
for IE 11 you’ll have to champion it: concretely, this means you need to provide
the development time to support it.</p>
<p>If somehow we were to reintroduce IE 11 support, we’d still be facing the
following issue. At some point in 2017 Selenium, IEDriver, or something else
changed in such a way that makes the test suite run incredibly slowly on
IE11. Wed itself runs at normal speed, as we can assess by running it manually
in IE11. We’ve looked for a solution but could not find one. Tracking down what
broke is more work than we can spend on this now. We accept bug reports due to
issues on IE11 and accept patches that would resolve the slowdown on IE11.</p>
<p>It is perhaps related to a bug whereby keystrokes are extremely slow in IE11,
but we’ve tried the solutions outlined there and nothing worked.</p>
</div>
<div class="section" id="os-x">
<h3>OS X<a class="headerlink" href="#os-x" title="Permalink to this headline">¶</a></h3>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">If you are using any version of OS X that hides
scroll bars by default, you probably want to modify your
OS X settings so that scroll bars are always
shown. Otherwise, there are situations where you won’t
know about contents being scrollable. If you need help
doing so, <a class="reference external" href="http://heresthethingblog.com/2013/02/25/mac-tip-missing-scroll-bars/">see this blog post</a>. Note
that wed will work either way, and you will be able to
scroll either way, but wed relies on the traditional
scroll bar behavior to indicate that something can be
scrolled. So if you do not make the change above, you can
end up in situations where something is scrollable
without having any visual indication that <em>it is</em>.</p>
</div>
<p>The test suite depends on native events to do its work, but support
for native events in OS X is spotty:</p>
<ul class="simple">
<li>Chrome: it is possible to generate <em>some</em> native events.</li>
<li>Firefox reports that it does not support native events at all.</li>
<li>Safari does not support native events at all.</li>
</ul>
<p>Your best bet in OS X is to use Chrome because we can’t run the test
suite with Firefox or Safari.</p>
</div>
<div class="section" id="safari">
<h3>Safari<a class="headerlink" href="#safari" title="Permalink to this headline">¶</a></h3>
<p>Safari is a vexing case. Wed may or may not work on Safari. We currently cannot
run the automated test suite with Safari. Manual testing is out of the question.</p>
<p>We would like to have wed be supported on recent versions of Safari to the same
extent it is supported on recent versions of Chrome. The tool we use to test it
is Selenium. For better or for worse this is the go-to tool to do the kind of
test wed needs. We’ve not seen evidence of any collaboration between the
Selenium project and Apple. Thus testing support for Safari is deficient, and it
is not something that we here have the resources to fix.</p>
<p>If you desire that wed be actually tested on Safari and are in a position to
contribute substantial monetary or technical resources towards this goal, you
are welcome to contact us. In particular, immediate problem we’ve run into when
trying to test on Safari is this <a class="reference external" href="http://code.google.com/p/selenium/issues/detail?id=4136">Selenium issue</a>. If you want fix
it, then this would bring us one step closer to being able to test wed on
Safari. And regarding the state of Selenium support for Safari, take note this
response from a Selenium project member:</p>
<blockquote>
<div>Safari is not a priority, sorry. But your patches are welcome!</div></blockquote>
<p>Absent these patches, wed is unlikely to support Safari.</p>
</div>
</div>
<div class="section" id="complex-name-patterns">
<span id="id6"></span><h2>Complex Name Patterns<a class="headerlink" href="#complex-name-patterns" title="Permalink to this headline">¶</a></h2>
<p>When you open the contextual menu to check what it is possible to insert in a
document you may see a menu item with an exclamation mark, labeled “Complex name
pattern”. What’s the deal?</p>
<div class="section" id="brief-explanation">
<h3>Brief Explanation<a class="headerlink" href="#brief-explanation" title="Permalink to this headline">¶</a></h3>
<p>In brief, this occurs if the Relax NG schema uses a wildcard (so to speak) that
allows an unlimited number of possibilities for the name of an element or of an
attribute. (Or a set of possibilities that cannot be expressed as a set of
positive matches.) Wed is able to validate such documents. However its
capability to edit them is currently limited. Wed will actually mark as <strong>read
only</strong> elements and attributes that are allowed only due to a wildcard. These
may not be modified in wed. The menu item that wed shows is a warning that the
schema allows for more than what wed is able to do. If this is a problem for
you, you should contact whoever provides you with technical support to discuss
the problem. You may direct them to read the explanation that follows.</p>
</div>
<div class="section" id="long-technical-explanation">
<h3>Long Technical Explanation<a class="headerlink" href="#long-technical-explanation" title="Permalink to this headline">¶</a></h3>
<p>A Relax NG schema normally constrains the set of possible valid structures to a
limited set. Take the following schema:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">start</span> <span class="o">=</span> <span class="n">element</span> <span class="n">a</span> <span class="p">{</span> <span class="p">(</span><span class="n">element</span> <span class="n">b</span> <span class="p">{</span> <span class="n">empty</span> <span class="p">}</span> <span class="o">|</span> <span class="n">element</span> <span class="n">c</span> <span class="p">{</span> <span class="n">empty</span> <span class="p">})</span><span class="o">+</span> <span class="p">}</span>
</pre></div>
</div>
<p>If we have finished reading the start tag for <code class="docutils literal notranslate"><span class="pre">a</span></code>, then there are only two
possibilities: either a start tag for the element named <code class="docutils literal notranslate"><span class="pre">b</span></code> or a start tag for
the element named <code class="docutils literal notranslate"><span class="pre">c</span></code>. However, Relax NG allows schemas that effectively say
“any element is fine here”. For instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">start</span> <span class="o">=</span> <span class="n">element</span> <span class="n">a</span> <span class="p">{</span> <span class="nb">any</span><span class="o">+</span> <span class="p">}</span>
<span class="nb">any</span> <span class="o">=</span> <span class="n">element</span> <span class="o">*</span> <span class="p">{</span> <span class="nb">any</span><span class="o">*</span> <span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">*</span></code> that appears after the second <code class="docutils literal notranslate"><span class="pre">element</span></code> tells the validator that any
element name is possible. With this schema, once we’ve processed the start tag
for element <code class="docutils literal notranslate"><span class="pre">a</span></code>, then it is possible to encounter any element whatsoever. This
is a problem for wed because, in addition to validation, it provides <em>guided</em>
editing.</p>
<p>For now, we’ve decided that wed will not support such patterns in editing. Why?
In our experience, these patterns are normally used to provide opportunities to
expand a schema. An excellent example is DocBook, which has provisions for
including XML structures encoded according to the MathML or SVG schemas. From
the standpoint of validating the document it makes good sense to have the
DocBook schema declare that some elements will allow any element, provided that
they come from the MathML or SVG namespaces. There are scenarios where it is not
necessary to know anything about MathML or SVG. This is fine insofar as
validation is concerned.</p>
<p>However, when <em>editing</em> to add a MathML section to a DocBook document, there’s a
problem. Suppose a user wants to add a formula encoded with MathML to a DocBook
document, and user is using the default DocBook schema. The only thing wed has
to help the editing is “any element from MathML is valid here”, because this is
what the default schema says. What are the consequences?</p>
<ul class="simple">
<li>First, wed is unable to check that the MathML is in fact <em>valid MathML</em>. The
DocBook schema does not contain any information regarding what is valid
MathML. It allows anything and everything, so long as it is declared to be in
the MathML namespace. It therefore allows constructs that may not be valid
MathML. (Note that wed is just following what the <em>schema specifies</em>, no more,
no less.)</li>
<li>Second, wed would have to prompt the user for every element and attribute
name. For every MathML element to be added, the user would get a dialog box
and have to enter an element’s name, because wed has no finite set of options
to choose from. Editing becomes a slog.</li>
</ul>
<p>We’ve estimated that it is not worth adding to wed any facilities to support
scenarios like the one just described. If someone wants to edit DocBook
documents that allow MathML, they should provide wed with a DocBook schema that
has been merged with the MathML schema so that the final schema uses the actual
elements specified by MathML rather than say “anything from MathML is valid
here”. This takes care of the problems mentioned above.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
© Copyright Mangalam Research Center for Buddhist Languages.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'v3.0.1-2-g39938100',
LANGUAGE:'None',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>