[bug-recutils] [bug #55411] No documentation for ob-rec.el

[Dominic Walden]

Please find attached my patch to doc/recutils.texi to add documentation
for ob-rec.el.

It was based on commit ea3f04d2e7978ccedc99c1a6fdf6198750392c5d

I have not implemented the suggestion of Charles Millar
(http://savannah.gnu.org/bugs/?55411#comment3) as that does not strictly
speaking involve ob-rec.el. Nevertheless, it is a good idea and could be
added elsewhere.

Thanks,

Dom Walden

diff --git a/doc/recutils.texi b/doc/recutils.texi
index f6c199d..2c7d9b1 100644
--- a/doc/recutils.texi
+++ b/doc/recutils.texi
@@ -111,6 +111,7 @@ Advanced Topics
 
 Reference Material
 * Invoking the Utilities::     Exhaustive list of command line arguments.
+* Using ob-rec.el::            Invoking Recutils from Emacs Org-mode source 
blocks.
 * Regular Expressions::        Flavor of regexps supported in recutils.
 * Date input formats::         Specifying dates and times.
 
@@ -5535,6 +5536,93 @@ line.
 Don't prune empty fields in the rec output.
 @end table
 
address@hidden Using ob-rec.el
address@hidden Using ob-rec.el
+
+ob-rec.el allows you to use Recutils as a language in org-mode source
+blocks.
+
address@hidden Setup
+
+Recutils should install the necessary files where emacs can see them.
+
+In your .emacs you may need to add:
address@hidden
+(require 'ob-rec)
address@hidden example
+
+You will need to add "rec" to your list of 'org-babel-load-languages' like
+below:
address@hidden
+(org-babel-do-load-languages
+ 'org-babel-load-languages
+ '((rec . t)))
address@hidden example
+
address@hidden Usage
+
+To your org file, add a src code block like:
address@hidden
+#+BEGIN_SRC rec :data books.rec
+  Location = 'loaned'
+#+END_SRC
address@hidden example
+
+This performs the equivalent of the command:
address@hidden
+ $ recsel -e "Location = 'loaned'" books.rec
address@hidden example
+
+It will produce a result like:
address@hidden
+#+RESULTS:
+| Title               | Author          | Date            | Location |
+|---------------------+-----------------+-----------------+----------|
+| The Colour of Magic | Terry Pratchett | 4/20/01 11:15pm | loaned   |
address@hidden example
+
address@hidden Header Arguments
+
address@hidden @samp
address@hidden :data
+The recfile you would like to query. Can be a relative path. Spaces in
+the filename or path need to be escaped with a backslash (for example,
+file\ name.rec). This is the only required header argument.
+
address@hidden :results
+If this list contains "scalar", "html", "code" or "verbatim" then the
+output will look the same as if called from the command line and it
+will not be put into an org table.
+
address@hidden :type
+Only returns this type of record. Corresponds to the -t argument. Accepts
+only one argument.
+
address@hidden :fields
+Comma-separated list of fields to print. Corresponds to the -p argument.
+
address@hidden :sort
+Comma-separated list of fields by which to sort records. Corresponds to
+the -S argument.
+
address@hidden :groupby
+Comma-separated list of fields by which to group records. If the
+records grouped together share fields in common, these will be in
+separate columns with a "_N" appended. Corresponds to the -G argument.
+
address@hidden :join
+Field on which to join records from one record set to another. Please see
+blah for more on how joins work. Corresponds to the -j argument.
address@hidden table
+
address@hidden Warnings
+
address@hidden
address@hidden
+Output may be unpredictable if fields contain newlines, as would be the case
+for a multi-line field. This appears to be a limitation in org-mode's
+'org-table-convert-region' function.
address@hidden enumerate
 
 @node Regular Expressions
 @chapter Regular Expressions