In the description of sub(), give a better explanation of the

interface when repl is a function.  Also give a simple example of
using a function repl.

Doc/lib/libre.tex

@@ -308,10 +308,24 @@ regular expression metacharacters in it.
 \begin{funcdesc}{sub}{pattern\, repl\, string\optional{, count=0}}
 Return the string obtained by replacing the leftmost non-overlapping
 occurrences of \var{pattern} in \var{string} by the replacement
-\var{repl}, which can be a string or the function that returns a string.  If the pattern isn't found, \var{string} is returned unchanged. The
+\var{repl}.  If the pattern isn't found, \var{string} is returned
-pattern may be a string or a regexp object; if you need to specify
+unchanged.  \var{repl} can be a string or a function; if a function,
-regular expression flags, you must use a regexp object, or use
+it is called for every non-overlapping occurance of \var{pattern}.
-embedded modifiers in a pattern string; e.g.
+The function takes a single match object argument, and 
+returns the replacement string.  For example:
+%
+\bcode\begin{verbatim}
+>>> def dashrepl(matchobj):
+...    if matchobj.group(0) == '-': return ' '
+...    else: return '-'
+>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
+'pro--gram files'
+\end{verbatim}\ecode
+%
+The pattern may be a string or a
+regexp object; if you need to specify regular expression flags, you
+must use a regexp object, or use embedded modifiers in a pattern
+string; e.g.
 %
 \bcode\begin{verbatim}
 sub("(?i)b+", "x", "bbbb BBBB") returns 'x x'.

Doc/libre.tex

@@ -308,10 +308,24 @@ regular expression metacharacters in it.
 \begin{funcdesc}{sub}{pattern\, repl\, string\optional{, count=0}}
 Return the string obtained by replacing the leftmost non-overlapping
 occurrences of \var{pattern} in \var{string} by the replacement
-\var{repl}, which can be a string or the function that returns a string.  If the pattern isn't found, \var{string} is returned unchanged. The
+\var{repl}.  If the pattern isn't found, \var{string} is returned
-pattern may be a string or a regexp object; if you need to specify
+unchanged.  \var{repl} can be a string or a function; if a function,
-regular expression flags, you must use a regexp object, or use
+it is called for every non-overlapping occurance of \var{pattern}.
-embedded modifiers in a pattern string; e.g.
+The function takes a single match object argument, and 
+returns the replacement string.  For example:
+%
+\bcode\begin{verbatim}
+>>> def dashrepl(matchobj):
+...    if matchobj.group(0) == '-': return ' '
+...    else: return '-'
+>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')
+'pro--gram files'
+\end{verbatim}\ecode
+%
+The pattern may be a string or a
+regexp object; if you need to specify regular expression flags, you
+must use a regexp object, or use embedded modifiers in a pattern
+string; e.g.
 %
 \bcode\begin{verbatim}
 sub("(?i)b+", "x", "bbbb BBBB") returns 'x x'.