Skip to content

Use the Gutter

This chapter follows the complete Gutter workflow: read stable line numbers, change numbering for one view, inspect semantic markers, invoke marker actions, and add a personal theme-aware marker that leaves document text unchanged.

Before You Begin

If you enter this chapter directly, first complete Prepare the User Guide Exercises, then complete Read and Configure the Status Bar. The configuration source used below is created by the reader from the complete displayed block.

Read Stable Line Numbers

Open an ordinary text file. The left Gutter shows one-based logical line numbers. Its number field reserves at least four digits, so moving from line 9 to 10 or from 99 to 100 does not shift the document text.

The Gutter is presentation owned by the active view. Its numbers, separators, and markers are not part of selection, copying, search, replacement, editing history, language offsets, or reported text columns. If a pane becomes too narrow, Gutter lanes hide before they consume the protected text area.

Change Numbering in the Active View

Run these commands through M-x and observe the active pane:

The explicit commands gutter-set-line-numbers-none, gutter-set-line-numbers-absolute, gutter-set-line-numbers-relative, and gutter-set-line-numbers-hybrid select a mode without cycling. Numbering uses logical lines. gutter-set-numbering-visual reports that visual-line scope is currently unavailable and preserves the last valid policy.

Split the current pane and change numbering in only one side. Both views share the same text, but each retains its own Gutter policy.

Establish the Personal Numbering Default

Open ${XDG_CONFIG_HOME:-$HOME/.config}/odra/init.rkt. Retain any existing exports and add odra-gutter-configuration:

#lang racket/base

(provide odra-gutter-configuration)

(define odra-gutter-configuration
  '#hash((mode . hybrid)
          (current-line . zero)
          (minimum-digits . 4)))

Run M-x reload-personal-commands. New views use hybrid numbering, display zero on the current line, and reserve at least four digits. Existing explicit view overrides remain local. An invalid complete configuration is rejected without replacing the last valid policy.

Read Semantic Markers

The factory semantic lane appears opposite the number lane only when the current viewport contains a marker. Its presentation follows the active theme and terminal capabilities.

Current language diagnostics contribute error, warning, information, and hint markers. Open a document with live language diagnostics and move to a marked line. Run M-x gutter-inspect-markers; a compact popup anchored to the Gutter row shows the marker detail. Source, collision, and action metadata remain internal. Its border and content styles follow the active theme through the contextual presentation profile. The document remains focused. Press C-g or move the cursor to dismiss the popup.

When several markers share the line, repeat gutter-inspect-markers to replace the popup with the next collision member, including members hidden behind the visible marker. A terminal without overlap support, or one too narrow for the minimum popup, shows the same essential detail through the compact shared feedback region.

The shared placement diagram in Use Language Completion contrasts a point-anchored candidate surface with this line-anchored marker detail. Both preserve the surrounding document as context.

Run M-x gutter-invoke-primary-marker-action on a diagnostic marker. The action opens the ordinary diagnostic surface through normal command dispatch. Run M-x gutter-refresh-markers to ask the active buffer's semantic owner for a current publication.

For the language-service setup that produces diagnostics, follow Use Language Services and Diagnostics.

Observe Horizontal Clipping

Open a line wider than the active pane and move the cursor far enough across the line to change the horizontal viewport. The semantic lane indicates when content is clipped on the left, right, or both sides. These markers belong to the exact view snapshot: another pane over the same buffer can show a different clipping state.

Add a Personal Marker

In init.rkt, require the public Gutter API and export one personal provider:

#lang racket/base

(require odra/gutters)

(provide odra-gutter-provider)

(define notes-lane
  (gutter-lane 'notes #:side 'right #:style 'ordinary))

(define odra-gutter-provider
  (gutter-provider
   "Personal Notes"
   'personal-notes
   (list notes-lane)
   (list
    (gutter-marker
     'review
     'notes
     5
     "◆"
     #:fallback "*"
     #:style 'ordinary
     #:detail "Review this line"
     #:actions '(cursor-next-line)))))

Run M-x reload-personal-commands, open a document with at least six lines, and move to line 5. The right Gutter shows the marker without inserting it into the document. Inspect it in the anchored popup with gutter-inspect-markers, then run gutter-invoke-primary-marker-action; the admitted cursor-next-line action moves the cursor through ordinary command dispatch.

The primary glyph follows the active theme and terminal capabilities. The fallback preserves its meaning when the primary glyph cannot be presented.

Previous: Read and Configure the Status Bar · User Guide · Next: Read Feedback and Progress