next iteration

Proceed as sketched in the discussion of the pull request:
- Extend the documentation of `Pager` such that `start` can be a string,
  meaning a search string (without initial `/`),
- change the calls of the different pagers accordingly, and
- state that external pagers must have command line options `+n` and `+str`.

(Also fix a problem with `PAGER_BUILTIN` if a too large line number
is given as `start`.)

Author: ThomasBreuer

lib/methwhy.g

@@ -522,7 +522,7 @@ BIND_GLOBAL("PageSource", function ( fun, nr... )
               s := First(ss, a-> ':' in a);
               if s <> fail then
                 ss := SplitString(s,":","");
-                l := Concatenation("/Obj Func", ss[2]);
+                l := Concatenation("Obj Func", ss[2]);
               fi;
           fi;
         fi;

lib/pager.gd

@@ -30,8 +30,10 @@
 ##  <P/>
 ##  At least on a UNIX system one should use an external pager program like
 ##  <C>less</C> or <C>more</C>.
-##  &GAP; assumes that this program has a command line option <C>+nr</C>
-##  which starts the display of the text with line number <C>nr</C>.
+##  &GAP; assumes that this program has command line options <C>+nr</C> and
+##  <C>+/str</C> which start the display of the text with line number
+##  <C>nr</C> or at the line with the first occurrence of the string
+##  <C>str</C>.
 ##  <P/>
 ##  Which pager is used can be controlled by setting the user preference
 ##  <C>"Pager"</C>.
@@ -77,9 +79,12 @@
 ##  </Item>
 ##  <Mark><C>start</C></Mark>
 ##  <Item>
-##    must be a positive integer.
-##    This is interpreted as the number of the first line shown by the pager
-##    (one may see the beginning of the text via back scrolling).
+##    must be a positive integer or a string.
+##    An integer is interpreted as the number of the first line shown by the
+##    pager, a string is interpreted as a search string such that the first
+##    line containing this string is the first line shown by the pager
+##    (in both cases, one may see the beginning of the text via back
+##    scrolling),
 ##  </Item>
 ##  <Mark><C>exitAtEnd</C></Mark>
 ##  <Item>

lib/pager.gi

@@ -35,10 +35,12 @@
 ##
 ##   .formatted (true/false) If true, the builtin pager tries to avoid
 ##                           line breaks by GAP's Print.
-##   .start (number)         The display is started with line .start, but
+##   .start (number/string)  The display is started with line .start or
+##                           at the first line containing .start, but
 ##                           beginning is available via back scrolling.
-##   .exitAtEnd (true/false) If true (default), the pager is terminated
-##                           as soon as the end of the list is reached;
+##   .exitAtEnd (true/false) If true (default), the builtin pager is
+##                           terminated as soon as the end of the list is
+##                           reached;
 ##                           if false, entering 'q' is necessary in order to
 ##                           return from the pager.
 ##
@@ -117,8 +119,8 @@ GAPInfo.UserPreferences.Pager := UserPreference("Pager");
 ##  <Item>
 ##    a positive integer denoting the position of the first line that is
 ##    shown,
-##    or a string starting with <C>"/"</C>, meaning that the first line
-##    containing the substring behind <C>"/"</C> shall be shown;
+##    or a string meaning that the first line containing this string
+##    shall be shown;
 ##    the default is 1,
 ##  </Item>
 ##  <Mark>exitAtEnd</Mark>
@@ -132,8 +134,8 @@ GAPInfo.UserPreferences.Pager := UserPreference("Pager");
 # If  the text contains ANSI color sequences we reset  the terminal before
 # we print the last line.
 BindGlobal("PAGER_BUILTIN", function( r )
-  local formatted, linepos, exitAtEnd, lines, search, size, wd, pl, count, i,
-        stream, halt, lenhalt, delhaltline, from, len, emptyline, char, out;
+  local formatted, linepos, exitAtEnd, lines, size, wd, pl, count, i, stream,
+        halt, lenhalt, delhaltline, from, len, emptyline, char, out;
 
   formatted := false;
   linepos := 1;
@@ -167,10 +169,12 @@ BindGlobal("PAGER_BUILTIN", function( r )
     if IsBound(r.start) then
       if IsPosInt(r.start) then
         linepos := r.start;
-      elif IsString(r.start) and StartsWith(r.start, "/") then
-        search := r.start{[2..Length(r.start)]};
+      elif IsString(r.start) then
         linepos := PositionProperty(lines,
-                     l -> PositionSublist(l, search) <> fail);
+                     l -> PositionSublist(l, r.start) <> fail);
+        if linepos = fail then
+          linepos := 1;
+        fi;
       else
         Error("unsupported r.start value: ", r.start);
       fi;
@@ -240,6 +244,11 @@ BindGlobal("PAGER_BUILTIN", function( r )
   from := linepos;
   len := Length(lines);
   emptyline:= String( "", size[1]-2 );
+  if len < from then
+    # Ignore the start line.
+    # (The pager 'less' shows a warning and then goes to the first line.)
+    from:= 1;
+  fi;
   repeat
     for i in [from..Minimum(len, from+size[2]-2)] do
       pl(lines[i], "\n");
@@ -312,7 +321,9 @@ BindGlobal("PAGER_EXTERNAL",  function( lines )
     od;
     lines := str;
   fi;
-  if linepos > 1 then
+  if IsString(linepos) then
+    cmdargs := [Concatenation("+/", linepos)];
+  elif linepos > 1 then
     cmdargs := [Concatenation("+", String(linepos))];
   else
     cmdargs := [];