From f2ecb8595d074981ee004d882dcad5ba9d0e63c6 Mon Sep 17 00:00:00 2001 From: Jean-Francois Dockes Date: Mon, 25 Aug 2014 16:23:55 +0200 Subject: [PATCH] doc --- src/doc/user/usermanual.xml | 123 +++++++++++++++++++++++++++--------- 1 file changed, 94 insertions(+), 29 deletions(-) diff --git a/src/doc/user/usermanual.xml b/src/doc/user/usermanual.xml index 8b15ad02..7c0d9d3f 100644 --- a/src/doc/user/usermanual.xml +++ b/src/doc/user/usermanual.xml @@ -1327,6 +1327,8 @@ fs.inotify.max_user_watches=32768 Preview Open + Open With + Run Script Copy File Name Copy Url Save to File @@ -1343,6 +1345,18 @@ fs.inotify.max_user_watches=32768 Open entries do the same thing as the corresponding links. + Open With lets you open the document + with one of the applications claiming to be able to handle its MIME + type (the information comes from the .desktop + files in + /usr/share/applications). + + Run Script allows starting an arbitrary + command on the result file. It will only appear for results which + are top-level files. See further for a more + detailed description. + The Copy File Name and Copy Url copy the relevant data to the clipboard, for later pasting. @@ -1354,33 +1368,34 @@ fs.inotify.max_user_watches=32768 email attachment). It is especially useful to extract attachments with no associated editor. - The Find similar entry will select - a number of relevant term from the current document and enter - them into the simple search field. You can then start a simple - search, with a good chance of finding documents related to the - current result. + The Open/Preview Parent document entries + allow working with the higher level document (e.g. the email + message an attachment comes from). &RCL; is sometimes not totally + accurate as to what it can or can't do in this area. For example + the Parent entry will also appear for an + email which is part of an mbox folder file, but you can't actually + visualize the mbox (there will be an error dialog if you + try). - The Parent document entries will - appear for documents which are not actually files but are part - of, or attached to, a higher level document. This entry is mainly - useful for email attachments and permits viewing the message to - which the document is attached. Note that the entry will also - appear for an email which is part of an mbox folder file, but - that you can't actually visualize the folder (there will be an - error dialog if you try). &RCL; is unfortunately not yet smart - enough to disable the entry in this case. In other cases, the - Open option makes sense, for example to - start a chm viewer on the parent - document for a help page. + If the document is a top-level file, Open + Parent will start the default file manager on the + enclosing filesystem directory. + + The Find similar entry will select + a number of relevant term from the current document and enter + them into the simple search field. You can then start a simple + search, with a good chance of finding documents related to the + current result. I can't remember a single instance where this + function was actually useful to me... The Open Snippets Window entry will only - appear for documents which support page breaks (typically - PDF, Postscript, DVI). The snippets window lists extracts from - the document, taken around search terms occurrences, along with the - corresponding page number, as links which can be used to start - the native viewer on the appropriate page. If the viewer supports - it, its search function will also be primed with one of the - search terms. + appear for documents which support page breaks (typically + PDF, Postscript, DVI). The snippets window lists extracts from + the document, taken around search terms occurrences, along with the + corresponding page number, as links which can be used to start + the native viewer on the appropriate page. If the viewer supports + it, its search function will also be primed with one of the + search terms. @@ -1420,6 +1435,50 @@ fs.inotify.max_user_watches=32768 + + Running arbitrary commands on result files (1.20 and later) + + Apart from the Open and Open + With operations, which allow starting an application on a + result document (or a temporary copy), based on its MIME type, it is + also possible to run arbitrary commands on results which are + top-level files, using the Run Script entry in + the results pop-up menu. + + The commands which will appear in the Run + Script submenu must be defined by + .desktop files inside the + scripts subdirectory of the current + configuration directory. + + Here follows an example of a .desktop file, + which could be named for example, + ~/.recoll/scripts/myscript.desktop (the exact + file name inside the directory is irrelevant): + +[Desktop Entry] +Type=Application +Name=MyFirstScript +Exec=/home/me/bin/tryscript %F +MimeType=*/* + + The Name attribute defines the label which will + appear inside the Run Script menu. The + Exec attribute defines the program to be run, + which does not need to actually be a script, of course. The + MimeType attribute is not used, but needs to exist. + + + The commands defined this way can also be used from links + inside the + result paragraph. + + As an example, it might make sense to write a script which + would move the document to the trash and purge it from the &RCL; + index. + + + Displaying thumbnails @@ -2467,14 +2526,20 @@ fs.inotify.max_user_watches=32768 where docnum (%N) expands to the document number inside the result page). - It is also possible to use a "F%N" value - as a link target. This will open the document corresponding to the - %P parent folder expansion, usually creating a - file manager window on the folder where the container file - resides. E.g.: + A link target defined as "F%N" will open + the document corresponding to the %P parent + folder expansion, usually creating a file manager window on the + folder where the container file resides. E.g.: <a href="F%N">%P</a> + A link target defined as + R%N|scriptname will + run the corresponding script on the result file (if the document is + embedded, the script will be started on the top-level parent). + See the section about + defining scripts. + In addition to the predefined values above, all strings like %(fieldname) will be replaced by the value of the field named fieldname for this