Feature request: Option to align search results to page boundaries

[kaz-utashiro]

Summary

I'd like to propose an option to align search results to page boundaries. This is useful when using less as a pager for page-oriented output, where each screenful represents a logical unit.

Use Case

Some tools generate output designed to be viewed one screen at a time, where each page forms a coherent visual unit. With standard search behavior:

1. Search results appear at arbitrary positions on the screen
2. The n command finds the next match, which may be on the same logical page

An option to snap search results to page boundaries would make navigation more intuitive for such content.

Example: nup command

nup is a tool I developed that formats output in multi-column layouts. It currently uses less -F +Gg as the default pager:

nup man grep

This displays the grep manual in a multi-column format (the number of columns is automatically adjusted to fit the screen width), where each screen represents one "page" of formatted content. With the proposed option:

NUP_PAGER="less -SF +Gg --align-page -j1" nup man grep

users can search and navigate page-by-page through the formatted output, with each search result displayed at a page boundary.

Proposed Behavior

• When enabled and a search match is found, the display snaps to the page boundary containing the match
• The n command skips to the next page containing a match
• Works well with -j1 to position the page start at the top of the screen

Implementation

I have a working implementation available at:
https://github.com/kaz-utashiro/less/tree/align-page

The changes are minimal (~44 lines across 3 files) and leverage the existing -a option mechanism.

Note: The current implementation calculates page boundaries based on screen height and line numbers. It does not take --form-feed into account. While it would be possible to allow specifying a custom line count for alignment, the current implementation keeps it simple by aligning to the screen height.

The option name (--align-page) and whether to assign a short option are just suggestions—I leave those decisions to your judgment.

[avih]

I have a working implementation available at: https://github.com/kaz-utashiro/less/tree/align-page

The changes are minimal ...

Why is this feature controlled by ALIGN_PAGE at defines.h?

configure can't control it anyway (e.g. there's no configure --with-align-page=no as far as I can tell), and there's also nothing to detect at configure-time, because it appears to not depend on any other features which are detectable or configurable, as far as I can tell.

Typically a feature can be toggled at build/configure time if some systems don't support it, or support it differently, or if it results in some general different "mode" of the resulting build, like a secure build, but with this feature it simply adds a (runtime) option which is disabled by default, no?

Also, are you aware of anything other than nup which uses "less" to paginate a strictly page-based content?

[kaz-utashiro]

Thank you for your feedback.

Regarding #if ALIGN_PAGE: I simply followed the pattern used by other features like HILITE_SEARCH and TAGS. If it's unnecessary for a runtime-only feature, it can certainly be removed. I leave that decision to the maintainer.

As for other use cases: while I'm not aware of other tools that paginate strictly page-based content like nup, the --align-page feature can be useful even for non-page-oriented output. Having content always appear at consistent screen positions can be helpful when reviewing large documents. nup, as a general-purpose multi-column output filter, amplifies this benefit.

[gwsw]

I'll take a look at this. A few initial comments:

1. The use of a #if probably isn't necessary. I used it long ago for large features like HILITE_SEARCH, to allow building a version of less that used less memory. This was back in the 20th century when memory size was a serious concern. It's much less of a concern now, and it's really of no concern at all for a small feature like this.
2. Setting --align-page should probably force -j1. Using --align-page with -j set to a larger value results in erroneous behavior, like having a search command display a page which doesn't contain the search match. Alternatively, the feature could be enhanced to work better with all -j values, which would be a little more complicated.
3. You could use --file-size rather than +Gg, which would work better if you view another file within less.

[gwsw]

I don't know, I'm on the fence about this. It seems a feature of rather limited utility. The fact that the paging is based on the size of the screen means the page size has nothing to do with the file content and is purely an artifact of the terminal window that the user happens to be using. And the pagination would be disrupted if the user uses any movement commands other than full screen paging (f and b) or searching. It's hard for me to conceive of many situations when this would be useful.

[avih]

The fact that the paging is based on the size of the screen means the page size has nothing to do with the file content and is purely an artifact of the terminal window that the user happens to be using.

While I personally don't think this feature belongs in less, mainly due to rarity or almost non-existance of tools with which it's useful, combined with the complexities it might induce initially and down the line, I think this argument misses the point a bit.

Because I think with this class of usage, the content is generated on the fly to fit the screen size, not unlike the man command which formats the content for the specific current screen width (and which then is typically displayed using "less"), except that nup would likely do so for both width and height.

So in its usage class, it's not really a "happens to be" thing.

On the other hand, man likely doesn't require any width-specific behavior in "less", while nup does require a height-specific behavior.

[gwsw]

Yes, I understand that. I was just saying that the vast majority of use cases don't involve content that is generated based on the screen size. I understand that nup is one of the rare exceptions.

I haven't used nup but it seems to me that even in that case, doing something innocuous like scrolling with the arrow keys will mess up the pagination.

[avih]

I haven't used nup but it seems to me that even in that case, doing something innocuous like scrolling with the arrow keys will mess up the pagination.

Same, and yes.

That's why I felt that it might have consequences and leftovers to handle down the line of how various things currently behave in less, which might be inappropriate with strictly page-based content.

Hence the "happens to be" is inaccurate in this class of usage, but I agreed with the rarity and other arguments, and overall I don't think it belongs in less.

[kaz-utashiro]

I've updated the implementation based on the feedback. The main changes are:

Renamed to --snap-line

Instead of --align-page, the option is now --snap-line=N. This better reflects the generalized functionality.

Flexible line-count alignment

• --snap-line=N: Snap to N-line boundaries (e.g., 66 for pr output)
• --snap-line=[+|-]N (signed): Snap to (screen height + N) boundaries (e.g., -1 for nup output)

This allows alignment to various intervals, not just full page boundaries.

Examples

pr -2 -w132 search.c | less --snap-line=66

The pr -2 command formats output into 2 columns with 66-line pages, suitable for line printer output. With --snap-line=66, search results snap to pr's page boundaries.

NUP_PAGER='less -F --file-size --snap-line=-1' nup search.c

The nup command happens to format output to fit screen height minus 1 line. With --snap-line=-1, search results snap to nup's page boundaries.

Implementation

The updated branch is at: https://github.com/kaz-utashiro/less/tree/snap-line

Note that this is a proof-of-concept level implementation, not yet thoroughly reviewed for production quality.

Future possibility

A pattern-based boundary specification (e.g., --snap-line=/pattern) could handle variable-length records by snapping to lines matching the pattern. This would be useful for more flexible data formats, but the implementation would be considerably more complex.

A bit of history

Actually, my original implementation was --snap-line=N, which aligned search results to arbitrary N-line boundaries. I then simplified it to --align-page, thinking page alignment would be the most common use case (who would use pr when nup exists?). But the generalized version might be useful for some.

[gwsw]

The link https://github.com/kaz-utashiro/less/tree/snap-line is a 404.

[kaz-utashiro]

Sorry, the branch was pushed after my comment. The link should work now.

Here's another example:

curl -s https://www.rfc-editor.org/rfc/rfc7994.txt | sed 1,3d | less --snap-line=56 --form-feed

RFC documents use form feeds for page breaks. With --snap-line=56 and --form-feed, search results snap to RFC page boundaries.

[kaz-utashiro]

Update: Pattern-based boundary specification

I've also implemented pattern-based snapping as mentioned in "Future possibility":

less --snap-line='/^RFC' rfc7994.txt

This snaps search results to lines matching the pattern.

This is a bit tricky, but with +/^ to initiate a search, you can navigate between snap boundaries using n and N:

less --snap-line='/^RFC' +/^ rfc7994.txt

For C source code, snapping to code segments:

less --snap-line='/^/\*' +/snap_line search.c

This displays code segments containing snap_line.

Form feeds can also be matched this way:

less --snap-line=$'/\f' rfc791.txt

Though for form feeds, it would be cleaner if less's page navigation natively supported them.

Branch: https://github.com/kaz-utashiro/less/tree/snap-line-pattern

This is an even more experimental proof-of-concept than the line-count version, with minimal testing.

[gwsw]

My first concern is that if there is a large number of lines between a search match and preceding snap-line pattern, I think this will show a page containing the snap-line pattern but not the search match. That is probably not what the user wants to see.

[kaz-utashiro]

In most cases users would expect the search match to appear on the first screen, and the feature is most effective when used with content structured that way.

That said, your concern is exactly what happens with:

less --snap-line='/^/\*' +/snap_line search.c

When reviewing code, this is often the desired behavior - seeing the function header and context rather than jumping directly to the match. If that's not what the user wants, they simply don't use the option.

I have a similar feature in my tool greple (--border option):

greple -n --border '^(?=/\*)' snap_line search.c --blockend='--' | less

It's great that less alone can now achieve something similar.

[gwsw]

It seems to me that rather than typing --snap-line=pattern1 and /pattern2, it's easier to search forward with /pattern2 and then search backwards with ?pattern1 if that is desired. That involves less typing and has clearer semantics since it's just using one feature.

[kaz-utashiro]

In the example above, do you mean searching with /snap_line and then going back with ?^/\*? That would clear the highlight from /snap_line, and repeating this for 4 (or more) sections would be tedious - probably nobody would actually do that. It would be different if you could specify different strings for forward-search and backward-search.

The idea is that when you search, what's displayed is not the matching line itself, but the section containing it. For example, with a markdown document and --snap-line='/^## ', searching displays the section containing the match. In the case of nup, sections coincide with pages.

What I originally wanted was the fixed line-count version, and that's sufficient for nup. Pattern-based snapping is a nice addition, but it also makes the implementation more complex. Perhaps it would be better to discuss pattern support in a separate issue. Sorry for complicating the discussion.