lyx_mirror/lib/doc/AdvancedSearch.lyx
Tommaso Cucinotta 2aa13815a1 Added description of replace functionality and missing options.
git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@32933 a592a061-630c-0410-9148-cb99ea01b6c8
2010-01-10 12:21:05 +00:00

722 lines
14 KiB
Plaintext

#LyX 2.0.0svn created this file. For more info see http://www.lyx.org/
\lyxformat 375
\begin_document
\begin_header
\textclass amsart
\use_default_options false
\begin_modules
theorems-ams
eqs-within-sections
figs-within-sections
\end_modules
\language english
\inputencoding auto
\fontencoding global
\font_roman default
\font_sans default
\font_typewriter default
\font_default_family default
\use_xetex false
\font_sc false
\font_osf false
\font_sf_scale 100
\font_tt_scale 100
\graphics default
\default_output_format default
\bibtex_command default
\index_command default
\paperfontsize default
\spacing single
\use_hyperref false
\papersize default
\use_geometry false
\use_amsmath 1
\use_esint 1
\use_mhchem 1
\cite_engine basic
\use_bibtopic false
\use_indices false
\paperorientation portrait
\suppress_date false
\index Index
\shortcut idx
\color #008000
\end_index
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\html_use_mathml true
\html_be_strict true
\end_header
\begin_body
\begin_layout Title
Advanced Find&Replace
\end_layout
\begin_layout Author
by the LyX Team
\end_layout
\begin_layout Section
Introduction
\end_layout
\begin_layout Standard
The Advanced Find&Replace feature
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
For suggestions, comments or clarification requests regarding this document,
as well as for notifying possible issues or bugs arising from the use of
this feature, please use the standard support channels of LyX (i.e., bug
tracking and mailing lists).
\end_layout
\end_inset
of LyX allows for searching of complex, format-sensitive text segments
and mathematics contents within LyX documents.
This constitutes an enhancement of the standard (quick) Find&Replace feature.
\end_layout
\begin_layout Standard
The set of capabilities of the
\begin_inset Quotes eld
\end_inset
Find
\begin_inset Quotes erd
\end_inset
part of the enhanced Find&Replace feature may be summarised as follows:
\end_layout
\begin_layout Itemize
the text to search for is entered by means of a full-featured LyX mini-editor;
\end_layout
\begin_layout Itemize
searching of the entered text occurs both within text and within mathematical
formulas possibly present in the document;
\end_layout
\begin_layout Itemize
both searching of text and of mathematical formulas is allowed, where the
latter is done by entering mathematics in the usual way the LyX user is
accustomed to do; not only entire mathematical formulas are found, but
also parts occurring within more complex formulas;
\end_layout
\begin_layout Itemize
both case-sensitive and case-insensitive search is possible;
\end_layout
\begin_layout Itemize
search may be restricted so as to match only at word-boundaries;
\end_layout
\begin_layout Itemize
search may be format-insensitive, so that the searched text is found in
any context/style (standard text, section headings, notes, and even mathematics
), or it may be format-sensitive, so that, for example, a word entered with
a section heading will only be found within section headings;
\end_layout
\begin_layout Itemize
search may be widened to a specific
\emph on
scope
\emph default
, i.e., a set of files which may be all the children of the document being
edited, all the open files, or all the manuals available from the
\noun on
Help
\noun default
menu.
\end_layout
\begin_layout Standard
The set of capabilities related to the
\begin_inset Quotes eld
\end_inset
Replace
\begin_inset Quotes erd
\end_inset
part of the Find&Replace feature may be summarised as follows:
\end_layout
\begin_layout Itemize
the replaced text may be entered by means of a full-featured LyX mini-editor;
\end_layout
\begin_layout Itemize
replace may optionally preserve capitalisation, so that the replaced text
capitalisation is adapted so as to mimic the one of the matching text (i.e.,
all lowercase, all uppercase, first uppercase followed by lowercase).
\end_layout
\begin_layout Standard
The Advanced Find&Replace feature is activated with a set of default options
which is suitable for the most common needs.
A detailed discussion of the available options follows in Sections
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Basic-usage"
\end_inset
and
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "sec:Advanced-usage"
\end_inset
.
\end_layout
\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Basic-usage"
\end_inset
Basic usage
\end_layout
\begin_layout Standard
The advanced Find&Replace feature of LyX is activated through the [C-S-f]
sequence (Ctrl+Shift+f), or through the
\noun on
Edit->Find&Replace (Advanced)
\noun default
menù item.
This causes the Advanced Find&Replace dialog to show up, as shown in Figure
\begin_inset space ~
\end_inset
\begin_inset CommandInset ref
LatexCommand ref
reference "fig:AdvancedFindReplaceDialog"
\end_inset
.
\begin_inset Wrap figure
lines 0
placement O
overhang 0in
width "40col%"
status open
\begin_layout Plain Layout
\begin_inset Graphics
filename clipart/AdvancedFindAndReplace.png
lyxscale 60
\end_inset
\end_layout
\begin_layout Plain Layout
\begin_inset Caption
\begin_layout Plain Layout
\begin_inset CommandInset label
LatexCommand label
name "fig:AdvancedFindReplaceDialog"
\end_inset
The Advanced Find&Replace Dialog.
\end_layout
\end_inset
\end_layout
\begin_layout Plain Layout
\end_layout
\end_inset
\end_layout
\begin_layout Subsection
Searching for text
\end_layout
\begin_layout Standard
Enter into the
\noun on
Find...
\noun default
LyX mini-editor a simple word, and search for occurrences of it by clicking
on the
\noun on
Next
\noun default
button below it (or just pressing the
\noun on
[Return]
\noun default
or
\noun on
[Enter
\noun default
] keys).
The entered word is found both in text mode and in math mode, and both
in emphasized, bold or normal face, and both in section titles and in standard
text.
Pressing repeatedly
\noun on
[Enter]
\noun default
keeps searching forward.
Similarly, pressing
\noun on
[Shift+Enter]
\noun default
searches for the entered text backwards.
\end_layout
\begin_layout Standard
While searching, the
\noun on
case sensitive
\noun default
option allows matches to occur only with the same case as entered in the
\noun on
Find...
\noun default
box.
The
\noun on
whole words
\noun default
option allows matches to occur only at word boundaries.
\end_layout
\begin_layout Subsection
Searching for mathematics
\end_layout
\begin_layout Standard
Mathematical formulas may be searched for by typing in the
\noun on
Find...
\noun default
mini-editor a mathematical formula, such as
\begin_inset Formula $x^{2}$
\end_inset
or also something more complex like
\begin_inset Formula $\frac{x^{2}}{1+x^{2}}$
\end_inset
.
When searching for such formula, it is found both when it is alone and
when it occurs in subformulas and nested parts of subformulas, for example
the mentioned segments would be found in something like
\begin_inset Formula $\frac{x^{2}}{\sqrt{\frac{x^{2}}{1+x^{2}}}}.$
\end_inset
\end_layout
\begin_layout Subsection
Style-aware search
\end_layout
\begin_layout Standard
It is also possible to search for text with specific styles.
This is done by switching to the
\noun on
Advanced
\noun default
pane and unchecking the
\noun on
ignore format
\noun default
option.
This way:
\end_layout
\begin_layout Enumerate
Entering in the
\noun on
Find...
\noun default
LyX mini-editor a plain word and searching for it would not find instances
of the word occurring in emphasized or boldface.
\end_layout
\begin_layout Enumerate
Entering in the
\noun on
Find...
\noun default
LyX mini-editor an emphasized or boldface word and searching for it would
find the respective instances with same face only, and within the same
text style only.
Note that, for example, an emphasized text is found not only when occurring
alone, but also when it is contained in a longer emphasized sentence.
\end_layout
\begin_layout Enumerate
Entering in the
\noun on
Find...
\noun default
LyX mini-editor a plain word and giving it a Section style from the style
selection dropdown menu, and searching for it, finds occurrences of if
only within Section titles.
Also, if the text to search is given an emphasized or bold face, in addition
to a
\noun on
Section
\noun default
style, then it is found only when occurring with the same style.
\end_layout
\begin_layout Enumerate
Entering in the
\noun on
Find...
\noun default
LyX mini-editor some mathematics in centered line math (C-S-m) mode, like
this
\begin_inset Formula \[
x^{2}\]
\end_inset
finds only instances of the text within the same kind of mathematical environmen
t.
\end_layout
\begin_layout Subsection
Replace
\end_layout
\begin_layout Standard
The text segments matching the text entered in the
\noun on
Find...
\noun default
LyX mini-editor may be replaced with the text segments entered in the
\noun on
Replace...
\noun default
LyX mini-editor.
In order to find the next occurrence and replace it, click on the
\noun on
Next
\noun default
and
\noun on
Prev
\noun default
buttons below the
\noun on
Replace...
\noun default
mini-editor.
Alternatively, you can use the [
\noun on
Enter
\noun default
] and [
\noun on
Shift+Enter
\noun default
] keys while in the
\noun on
Replace...
\noun default
LyX mini-editor.
\end_layout
\begin_layout Standard
You can replace full-featured formatted LyX segments in place of the matching
text segments in your document.
Typical scenarios in which to use this capability may be (just to mention
a few):
\end_layout
\begin_layout Itemize
replacing occurrences of a word with a customized formatted version of the
same word, for example replacing occurrences of a name like
\begin_inset Quotes eld
\end_inset
func()
\begin_inset Quotes erd
\end_inset
with its monospace version
\family typewriter
\begin_inset Quotes eld
\end_inset
func()
\begin_inset Quotes erd
\end_inset
;
\end_layout
\begin_layout Itemize
performing a notation rework of mathematical symbols, for example replacing
occurrences of
\begin_inset Quotes eld
\end_inset
\begin_inset Formula $R$
\end_inset
\begin_inset Quotes erd
\end_inset
with
\begin_inset Quotes eld
\end_inset
\begin_inset Formula $\mathbb{R}$
\end_inset
\begin_inset Quotes erd
\end_inset
(you may want to disable the
\family typewriter
Ignore Format
\family default
option in the
\family typewriter
Advanced
\family default
pane, in order to avoid replacing all
\begin_inset Quotes eld
\end_inset
R
\begin_inset Quotes erd
\end_inset
letters occurring in normal text), or occurrences of
\begin_inset Formula $x_{j}^{i}$
\end_inset
with
\begin_inset Formula $x_{i,\, j}$
\end_inset
, or occurrences of
\begin_inset Formula $x[k]$
\end_inset
with
\begin_inset Formula $x_{k}$
\end_inset
.
\end_layout
\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Advanced-usage"
\end_inset
Advanced usage
\end_layout
\begin_layout Subsection
About using regular expressions in the Find...
box
\end_layout
\begin_layout Standard
There is a regular expression based searching facility.
Users may arbitrarily insert, within text or math material to search for,
regexp-mode insets that allow to enter regular subexpressions.
This is done either through the
\noun on
[Match...]
\noun default
dropdown button or by the [C-S-r] key sequence.
Characters entered in the
\noun on
Find...
\noun default
LyX mini-editor within regexp insets are matched according to the regular
expression matching rules
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
but under the constraint that any subexpression must match a well-formed
LyX text segment, i.e., when matching LaTeX code, no segments with unbalanced
{} braces are allowed to match subexpressions entered by the user.
\end_layout
\end_inset
, while text entered outside regexp insets is matched exactly against the
same text in the document.
Note that it is allowed to cut and paste regexp-mode insets as usual.
Examples of using such a feature may be:
\end_layout
\begin_layout Enumerate
Searching for all fractions with a given denominator: for example, entering
in the
\noun on
Find...
\noun default
LyX mini-editor the fraction
\begin_inset Formula $\frac{.*}{1+x^{2}}$
\end_inset
(where the
\begin_inset Formula $.*$
\end_inset
on the numerator is the match-everything regular expression that may be
added by clicking on the
\noun on
[Match...]->[Anything]
\noun default
button, or entering the regexp-mode through the [C-S-r] key sequence and
by typing
\begin_inset Formula $.*$
\end_inset
) finds all fractions with the given denominator.
\end_layout
\begin_layout Enumerate
Searching for all text with a given style: for example, after unchecking
the
\noun on
Ignore Format
\noun default
option from the
\noun on
Advanced
\noun default
pane, entering a
\series bold
\begin_inset Formula $.*$
\end_inset
\series default
regular expression and adding it an emphasized or bold face, finds all
emphasized and bold face text, respectively.
Also, giving to the
\begin_inset Formula $.*$
\end_inset
regular expression a bullet-list, enumerated or Section style, you can
find all bullet or enumerated lists, or section titles.
\end_layout
\begin_layout Standard
Finally, references to subexpressions in regular expressions may be used
as usual, enclosing parts of the expression within round braces
\begin_inset Formula $()$
\end_inset
, and referring back to them through
\begin_inset Formula $\backslash1$
\end_inset
,
\begin_inset Formula $\backslash2$
\end_inset
, etc..., where a
\begin_inset Formula $\backslash$
\end_inset
symbol is entered in regular-expression mode by pressing twice the backslash
key.
For example, try searching for the
\begin_inset Formula $([a-z]+)[[:blank:]]\backslash1$
\end_inset
regular expression in order to find word repetitions, if any.
\end_layout
\begin_layout Standard
Note that back references work both when occurring within the same regular
expression, and when occurring in multiple different regular expressions,
where numbering of back-referenced sub-expressions is absolute, i.e.,
\begin_inset Formula $\backslash1$
\end_inset
always refers to the first occurrence of
\begin_inset Formula $()$
\end_inset
in all entered regular expressions.
\end_layout
\begin_layout Standard
Note that the use of back references in the replaced text is not (yet) implement
ed.
\end_layout
\end_body
\end_document