Finalized first version of Advanced Find and Replace documentation.

git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@32793 a592a061-630c-0410-9148-cb99ea01b6c8
This commit is contained in:
Tommaso Cucinotta 2010-01-06 17:56:47 +00:00
parent c22298c97b
commit aabd587fef

View File

@ -1,168 +1,359 @@
#LyX 1.6.5svn created this file. For more info see http://www.lyx.org/
\lyxformat 345
#LyX 2.0.0svn created this file. For more info see http://www.lyx.org/
\lyxformat 374
\begin_document
\begin_header
\textclass article
\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
\defskip medskip
\paragraph_indentation default
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\author ""
\author ""
\html_use_mathml true
\html_be_strict true
\end_header
\begin_body
\begin_layout Title
Advanced Find&Replace
\begin_inset Foot
status collapsed
\begin_layout Plain Layout
This document is currently maintained by Tommaso Cucinotta, the main developer
of this feature at the moment.
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
\end_layout
\begin_layout Author
by the LyX Team
\end_layout
\begin_layout Section
Introduction to the find advanced feature
Introduction
\end_layout
\begin_layout Standard
This is an introduction to the find advanced feature of LyX, that is activated
through the [C-S-f] sequence (Ctrl+Shift+f) and can be closed just by hitting
[
\noun on
Esc
\noun default
] unlike other panes.
The Advanced Find&Replace feature 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
First, leave the ignore format option
\series bold
checked
\series default
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 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 Enumerate
Search for the word
\series bold
about
\series default
and see how it 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.
When finished typing the text to find in the
\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.
\end_layout
\begin_layout Subsection
Searching for text
\end_layout
\begin_layout Standard
Enter into the
\noun on
Find...
\noun default
box, pressing repeatidly
LyX mini-editor a simple word, and search for occurrences of it by pushing
the
\noun on
Next
\noun default
button below it (or just pressing
\noun on
[Return]
\noun default
or
\noun on
[Enter
\noun default
]).
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
will search for it forward, while pressing
keeps searching forward.
Similarly, pressing
\noun on
[Shift+Enter]
\noun default
will search backwards.
searches for the entered text backwards.
\end_layout
\begin_layout Enumerate
Search for some math by typing in the
\noun on
Find...
\noun default
box a
\begin_inset Formula $x^{2}$
\end_inset
in simple math (C-m) mode (you can directly copy it from this text and
paste into the
\noun on
Find...
\noun default
box), or also something more elaborate like
\begin_inset Formula $\frac{gh}{ij}$
\end_inset
.
See how it is found both when alone and when in subformulas and nested
parts of subformulas.
\begin_layout Subsection
Searching for mathematics
\end_layout
\begin_layout Standard
Now, uncheck the ignore format option.
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
Search for a plain 'about' word and see how emphasized and boldface instances,
as well as the ones in non-standard style, are not found anymore.
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
Search for
\emph on
emphasized about
\emph default
or
\series bold
boldface about
\series default
and see how you can find the respective instances with same face only,
and within same text style only (e.g.
in order to find the words in this paragraph, you need to also add an enumerate
style).
Note that e.g.
emphasized text is found not only when alone, but also when it is in a
longer emphasized sentence.
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
Search for the word 'about' (again plain face) giving it a Section style
from the style selection dropdown menu, and see how it is found only within
Section titles.
Repeat with the word '
\emph on
advanced
\emph default
' in emphasized face, with
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, and see how its corresponding instance is found.
style, then it is found only when occurring with the same style.
\end_layout
\begin_layout Enumerate
Search for some math in centered line math (C-S-m) mode, like this
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
and see how only instances of the text within the same kind of environment
are found.
finds only instances of the text within the same kind of mathematical environmen
t.
\end_layout
\begin_layout Section
\begin_inset CommandInset label
LatexCommand label
name "sec:Advanced-usage"
\end_inset
Advanced usage
\end_layout
\begin_layout Subsection
@ -171,28 +362,28 @@ About using regular expressions in the Find...
\end_layout
\begin_layout Standard
Now you can try the regular expression based searching facility.
Users may arbitrarily insert, within text or math material, regexp-mode
insets that allow to enter regular subexpressions.
This is done either through
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
[Insert]->[Regexp]
[Match...]
\noun default
or by typing [C-S-r].
dropdown button or by typing [C-S-r].
Characters entered in the
\noun on
[Find...]
Find...
\noun default
box within regexp insets are matched according to the regular expression
matching rules
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.
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
@ -200,179 +391,103 @@ but under the constraint that any subexpression must match a well-formed
, 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.
In order to try the feature, first leave the ignore format option checked.
Examples of using such a feature may be:
\end_layout
\begin_layout Enumerate
Search for the fraction
\begin_inset Formula $\frac{\regexp{.*}}{mn}$
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 '.*' on the numerator is the match-everything regular expression
that may be added by pressing the
, where the
\begin_inset Formula $.*$
\end_inset
on the numerator is the match-everything regular expression that may be
added by pressing the
\noun on
[Match...]->[Anything]
\noun default
button, or entering the regexp-mode through C-S-r and by typing '.*'.
See how all fractions with the specified denominator are found.
button, or entering the regexp-mode through C-S-r and by typing
\begin_inset Formula $.*$
\end_inset
, finds all fractions with the given denominator.
\end_layout
\begin_layout Enumerate
Now uncheck the Ignore Format option and search for '
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
' in boldface, or '
\emph on
.*
\emph default
' in emphasized face.
See how, respectively, all boldface and all emphasized text is found.
\end_layout
\begin_layout Enumerate
Search for a plain '.*' giving it a Section style, and navigate across section
titles (similarly, navigate across enumerated or bulletted lists).
\end_layout
\begin_layout Enumerate
You can use references to subexpressions as usual, enclosing parts of the
regex expression within round braces '()', and referring back to them through
\backslash
1,
\backslash
2, etc...
(within either the same or another regexp-mode inset, where a '
\backslash
' symbol is entered by pressing twice the '
\backslash
' key).
For example, try searching for '
\begin_inset Formula \regexp{[\^a-z]([a-z]+)}
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
\begin_inset Formula \regexp{\backslash1}
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
' in order to find word repetitions, if any.
\end_layout
\begin_layout Standard
What follows is just a set of meaningless formulas and sentences useful
for for testing purposes.
\end_layout
\begin_layout Standard
\begin_inset Formula $y+x+X^{2}+\frac{gh}{ij}-1+x_{j}^{i}+y_{jk}^{ip}+i$
, and referring back to them through
\begin_inset Formula $\backslash1$
\end_inset
and
\begin_inset Formula $z+x_{j}^{i}.$
,
\begin_inset Formula $\backslash2$
\end_inset
\end_layout
\begin_layout Standard
Hi, world !
\emph on
what
\emph default
about your
\begin_inset Formula $X+y^{2}+\frac{x+x^{2}+\frac{gh}{ij}}{y^{x+x^{2}}+\frac{kl}{mn}}-about$
, etc..., where a
\begin_inset Formula $\backslash$
\end_inset
?
\end_layout
\begin_layout Standard
\begin_inset Formula \[
X+y^{2}+\frac{x+x^{2}+\frac{gh}{ij}}{y^{x+x^{2}}+\frac{kl}{mn}}-about\]
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
Hi, universe ! what
\emph on
about
\emph default
my
\begin_inset Formula $c+\frac{kl}{mn}+\frac{\sqrt{\frac{gh}{ij}}}{mn}-\frac{1+\sqrt{\frac{about}{mn}}}{mn}+\textrm{about}$
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
?
\end_layout
\begin_layout Section
Conclusion and future work about the find
\emph on
advanced
\emph default
feature
\end_layout
\begin_layout Standard
This feature seems very useful to me.
Hope others will find it useful as well.
Currently, I'm not really happy with the implementation, because it has
at least quadratic complexity (document size multiplied by maximum paragraph
size, plus regexp matching complexity, if enabled, and infact it is quite
slow), but hopefully that will be fixable by changing the TeXOnePar() function
and simpleTeXOnePar() method, and possibly other TeX related methods.
\end_layout
\begin_layout Standard
Infact, a DocIterator could be used to keep track of the current position,
and an externally supplied functor could be called at each position providing
the DocIterator and LaTeX string translated so far to the external code.
This would allow to couple each DocIterator state with the position in
the output LaTeX string, allowing to recover the DocIterator positions
after a regexp-based find operation made (only once this time) on translated
LaTeX.
\end_layout
\begin_layout Standard
Again, a few meaningless sentences useful for testing purposes on about.
\end_layout
\begin_layout Standard
But
\emph on
what about your
\emph default
health ?
\end_layout
\begin_layout Standard
But
\series bold
what about your health
\series default
?
\end_layout
\begin_layout Itemize
search for plain 'about'
\end_layout
\begin_layout Itemize
search for
\emph on
emphasized about
\emph default
or
\series bold
boldface about
\end_layout
\begin_layout Standard
\begin_inset Formula $y+x-x^{2}\cdot2$
always refers to the first occurrence of
\begin_inset Formula $()$
\end_inset
in all entered regular expressions.
\end_layout
\end_body