By default, Bugzilla does not search the list of RESOLVED bugs.
You can force it to do so by putting the upper-case word ALL in front of your search query, e.g.: ALL tdelibs
We recommend searching for bugs this way, as you may discover that your bug has already been resolved and fixed in a later release.

Bug 2558

Summary:	katepart - find & replace - Placeholder Help Missing
Product:	TDE	Reporter:	David C. Rankin <trin>
Component:	tdebase	Assignee:	Michele Calgaro <michele.calgaro>
Status:	RESOLVED FIXED
Severity:	normal	CC:	bugwatch, michele.calgaro, trin
Priority:	P5
Version:	R14.1.x [Trinity]
Hardware:	Other
OS:	Linux
Compiler Version:		TDE Version String:
Application Version:		Application Name:
Bug Depends on:
Bug Blocks:	2885

Description David C. Rankin 2015-12-12 13:13:53 CST

All,

Looking at the kwrite/kate find & replace help, there is no explanation regarding what the Use Placeholders checkbox, or Placeholders button does. Apparently this was added to kde4 later:

https://docs.kde.org/trunk4/en/kde-runtime/fundamentals/find.html

Since the kde4 authors seem to have struggled a bit it arriving at a proper description, the following should be used rather than the kde4 language:

===
Replacement Text

Here you may enter the text to replace the text or expression entered in the "Text to find:" entry combobox.

You can reuse all or part of the "Text to find:" text or expression in the "Replacement text" by selecting the "Use placeholders" checkbox. Placeholders, also known as 'backreferences', are a special character sequence that will be replaced with all or part of the original text or expression. They offer a short-cut to entering a full "Replacement text" expression. For instance, by default "\0" represents the complete 'pattern space' matched as a result of the text or expression entered in the "Text to find:" box. (a backreference to the entire matched string).

You may insert placeholders into the "Replacement text" box by clicking the "Insert Placeholder" button, then selecting an option from the menu like 'Complete Match'. For example, if you are searching for "message", and you want to replace it with messages insert the Complete Match placeholder and add and "s". The replace field will then contain "\0s".

If Kate is installed, you can learn more about placeholders in the 'Regular Expressions' appendix of its documentation.
===

The remainder could probably use cleanup as well, but at least this will take care of the glaring omission of any explanation of what the Placeholder checkbox and button does.

Comment 1 Michele Calgaro 2015-12-14 10:15:13 CST

David,
have you seen the following section in Kate's helpbook?

Kate Handbook -> 4. Working with the Kate editor -> Finding and Replacing Text -> navigate to the section "Use placeholders" (around middle of the page)

--------
"Use placeholders"
If enabled, any occurrence of \N where N is an integer number, will be replaced with the corresponding string capture (parenthesized substring) from the search pattern. A button for listing all available string captures will also be enabled. You can click on any of the available string captures to include them in your replacement string.
Note
Placeholders can only be used when searching using regular expressions.
--------

Is this not enough in your opinion?

Comment 2 Michele Calgaro 2018-08-04 05:47:53 CDT

David, 
as per comment 1, what do you think? Still need more description?

Comment 3 David C. Rankin 2018-08-05 00:18:17 CDT

Michele,

  I don't have a current TDE install to check. I'm sure whatever improvement were made help. The use placeholders was always confusing at first glance. It was basically to serve as the equivalent of a `sed` backreference. Do you have a link to the current git location for the help file? It would take me quite a while to grep around the old source I have to find the right file. Don't let this hold up any releases, it certainly isn't a show stopper :)

Comment 4 Michele Calgaro 2018-08-05 01:56:49 CDT

Hi David,
see section around line 353 here
https://mirror.git.trinitydesktop.org/gitea/TDE/tdebase/src/branch/master/doc/kate/part.docbook

Actually there has been no improvement, that description has always been there :-) If you think it is not adequate, we can improve it further.

Comment 5 David C. Rankin 2018-08-13 02:47:11 CDT

Michele,

  I would add something similar to the following at the beginning. This will at least provide anyone familiar Linux and sed with an understanding of what kate "placehoders" are and how they work:

"Placeholders allow you to designate parts of your search text (by enclosing it within parenthesis) and then insert that text at the location of placeholders \N (e.g. \1, \2, ...) in the replacement string. (similar to how backreferences are used with sed)"

Comment 6 Michele Calgaro 2018-08-19 23:07:03 CDT

Thanks :-)

Comment 7 Michele Calgaro 2018-08-20 10:12:32 CDT

Description in both What's this and in handbook improved in commits 3b290985, f6d6df46 (R14.1) and 8d7dfc5b, 0057230e (R14.0).

David, the text is now as follow. Is it ok to close this bug?

HANDBOOK
When regular expressions are enabled, you can select part of the searched text by enclosing it within parenthesis. Placeholders allow you to insert such text in the replacement string, similar to how backreferences are used in sed. When enabled, any occurrence of <keycap>\N</keycap> (where <keycap>N</keycap> is an integer number, e.g. \1, \2, ...) will be replaced with the corresponding string capture (parenthesized substring) from the search pattern. A button for listing all available string captures will also be enabled. You can click on any of the available string captures to include them in your replacement string.

WHAT'S THIS
When regular expressions are enabled, you can select part of the searched text by enclosing it within parenthesis. Placeholders allow you to insert such text in the replacement string, similar to how backreferences are used in sed. When enabled, any occurrence of <code><b>\\N</b></code> (where <code><b>N</b></code> is a integer number, e.g. \\1, \\2, ...), will be replaced with the corresponding capture (\"parenthesized substring\") from the pattern.<p>To include a literal <code><b>\\N</b></code> in your replacement, put an extra backslash in front of it, like <code><b>\\\\N</b></code>.

Comment 8 David C. Rankin 2018-08-21 02:55:55 CDT

Michele,

  I think that is a good reading and provides enough by way of example and explanation that those that will get it -- will get it, there will always be some that have never used sed or been exposed to regexes who will just never get it. This comes as close as anything I've seen to insure that those who have a chance to get it -- will. Good job.

  I've marked this as resolved (because I found no "Provides Info" entry) so the next most logical was a close. I think it is fine, if it still needs other eyes, just change it back to confirmed and send to those remaining that may want to chime in. In my view it is resolved and much better than before.

Comment 9 Michele Calgaro 2018-08-21 08:46:36 CDT

Glad to here that. Thanks for reporting and for the feedback.