From 76eab884033f8545dbf495d60952a8b9c8a6f243 Mon Sep 17 00:00:00 2001 From: David Lamparter Date: Mon, 18 Feb 2019 14:23:03 +0100 Subject: [PATCH] doc: document VTYSH_PAGER and "terminal paginate" Signed-off-by: David Lamparter --- doc/user/vtysh.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/user/vtysh.rst b/doc/user/vtysh.rst index 07109a0e54..6d569f5fb0 100644 --- a/doc/user/vtysh.rst +++ b/doc/user/vtysh.rst @@ -22,6 +22,37 @@ administrator with an external editor. have effect for vtysh) need to be manually updated in :file:`vtysh.conf`. +Pager usage +=========== + +*vtysh* can call an external paging program (e.g. *more* or *less*) to +paginate long output from commands. This feature used to be enabled by +default but is now controlled by the ``VTYSH_PAGER`` environment variable +and the :clicmd:`terminal paginate` command: + +.. envvar:: VTYSH_PAGER + + If set, the ``VTYSH_PAGER`` environment variable causes *vtysh* to pipe + output from commands through the given command. Note that this happens + regardless of the length of the output. As such, standard pager behavior + (particularly waiting at the end of output) tends to be annoying to the + user. Using ``less -EFX`` is recommended for a better user experience. + + If this environment variable is unset, *vtysh* defaults to not using any + pager. + + This variable should be set by the user according to their preferences, + in their :file:`~/.profile` file. + +.. index:: [no] terminal paginate +.. clicmd:: [no] terminal paginate + + Enables/disables vtysh output pagination. This command is intended to + be placed in :file:`vtysh.conf` to set a system-wide default. If this + is enabled but ``VTYSH_PAGER`` is not set, the system default pager + (likely ``more`` or ``/usr/bin/pager``) will be used. + + Permissions and setup requirements ================================== -- 2.39.5