diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/lispref/display.texi | 50 | ||||
| -rw-r--r-- | doc/lispref/frames.texi | 2 | ||||
| -rw-r--r-- | doc/lispref/os.texi | 37 | ||||
| -rw-r--r-- | doc/misc/flymake.texi | 75 |
4 files changed, 111 insertions, 53 deletions
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index afd09cfb330..17126ce72b9 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2050,13 +2050,17 @@ calculations. @defun line-number-display-width &optional pixelwise This function returns the width used for displaying the line numbers -in the selected window. Optional argument @var{pixelwise}, if -non-@code{nil}, means return the value in pixels; otherwise the value -is returned in column units of the font defined for the -@code{line-number} face. If line numbers are not displayed in the -selected window, the value is zero. Use @code{with-selected-window} -(@pxref{Selecting Windows}) if you need this information about another -window. +in the selected window. If the optional argument @var{pixelwise} is +the symbol @code{columns}, the return value is a float number of the +frame's canonical columns; if @var{pixelwise} is @code{t} or any other +non-@code{nil} value, the value is an integer and is measured in +pixels. If @var{pixelwise} is omitted or @code{nil}, the value is the +integer number of columns of the font defined for the +@code{line-number} face, and doesn't include the 2 columns used to pad +the numbers on display. If line numbers are not displayed in the +selected window, the value is zero regardless of the value of +@var{pixelwise}. Use @code{with-selected-window} (@pxref{Selecting +Windows}) if you need this information about another window. @end defun @@ -4635,7 +4639,7 @@ as an absolute number of pixels. @smallexample @group - @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{form} + @var{expr} ::= @var{num} | (@var{num}) | @var{unit} | @var{elem} | @var{pos} | @var{image} | @var{xwidget} | @var{form} @var{num} ::= @var{integer} | @var{float} | @var{symbol} @var{unit} ::= in | mm | cm | width | height @end group @@ -4651,22 +4655,34 @@ as an absolute number of pixels. The form @var{num} specifies a fraction of the default frame font height or width. The form @code{(@var{num})} specifies an absolute number of pixels. If @var{num} is a symbol, @var{symbol}, its -buffer-local variable binding is used. +buffer-local variable binding is used; that binding can be either a +number or a cons cell of the forms shown above (including yet another +cons cell whose @code{car} is a symbol that has a buffer-local +binding). The @code{in}, @code{mm}, and @code{cm} units specify the number of pixels per inch, millimeter, and centimeter, respectively. The @code{width} and @code{height} units correspond to the default width -and height of the current face. An image specification @code{image} -corresponds to the width or height of the image. +and height of the current face. An image specification of the form +@w{@code{(image . @var{props})}} (@pxref{Image Descriptors}) +corresponds to the width or height of the specified image. Similarly, +an xwidget specification of the form @w{@code{(xwidget . @var{props})}} +stands for the width or height of the specified xwidget. +@xref{Xwidgets}. The elements @code{left-fringe}, @code{right-fringe}, @code{left-margin}, @code{right-margin}, @code{scroll-bar}, and -@code{text} specify to the width of the corresponding area of the -window. +@code{text} specify the width of the corresponding area of the window. +When the window displays line numbers (@pxref{Size of Displayed +Text}), the width of the @code{text} area is decreased by the screen +space taken by the line-number display. The @code{left}, @code{center}, and @code{right} positions can be used with @code{:align-to} to specify a position relative to the left -edge, center, or right edge of the text area. +edge, center, or right edge of the text area. When the window +displays line numbers, the @code{left} and the @code{center} positions +are offset to account for the screen space taken by the line-number +display. Any of the above window elements (except @code{text}) can also be used with @code{:align-to} to specify that the position is relative to @@ -4682,13 +4698,15 @@ the left-margin, use If no specific base offset is set for alignment, it is always relative to the left edge of the text area. For example, @samp{:align-to 0} in a -header-line aligns with the first text column in the text area. +header-line aligns with the first text column in the text area. When +the window displays line numbers, the text is considered to start where +the space used for line-number display ends. A value of the form @code{(@var{num} . @var{expr})} stands for the product of the values of @var{num} and @var{expr}. For example, @code{(2 . in)} specifies a width of 2 inches, while @code{(0.5 . @var{image})} specifies half the width (or height) of the specified -image. +@var{image} (which should be given by its image spec). The form @code{(+ @var{expr} ...)} adds up the value of the expressions. The form @code{(- @var{expr} ...)} negates or subtracts diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 07a8b825026..ad853418ac4 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -3202,7 +3202,7 @@ a number of other ways as well. Here we sketch a few of them: @item The semantics of maximizing and iconifying child frames is highly window-system dependent. As a rule, applications should never invoke -these operations for on frames. By default, invoking +these operations on child frames. By default, invoking @code{iconify-frame} on a child frame will try to iconify the top-level frame corresponding to that child frame instead. To obtain a different behavior, users may customize the option @code{iconify-child-frame} diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 59c269a3084..0cb9de9f9a8 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1486,8 +1486,8 @@ This stands for the full name of the month. @item %c This is a synonym for @samp{%x %X}. @item %C -This has a locale-specific meaning. In the default locale (named C), it -is equivalent to @samp{%A, %B %e, %Y}. +This stands for the century, that is, the year divided by 100, +truncated toward zero. @item %d This stands for the day of month, zero-padded. @item %D @@ -1530,8 +1530,11 @@ This stands for the calendar quarter (1--4). This is a synonym for @samp{%I:%M:%S %p}. @item %R This is a synonym for @samp{%H:%M}. +@item %s +This stands for the integer number of seconds since the epoch. @item %S -This stands for the seconds (00--59). +This stands for the second (00--59, or 00--60 on platforms +that support leap seconds). @item %t This stands for a tab character. @item %T @@ -1561,22 +1564,31 @@ This stands for the year with century. @item %Z This stands for the time zone abbreviation (e.g., @samp{EST}). @item %z -This stands for the time zone numerical offset (e.g., @samp{-0500}). +This stands for the time zone numerical offset. The @samp{z} can be +preceded by one, two, or three colons; if plain @samp{%z} stands for +@samp{-0500}, then @samp{%:z} stands for @samp{-05:00}, @samp{%::z} +stands for @samp{-05:00:00}, and @samp{%:::z} is like @samp{%::z} +except it suppresses trailing instances of @samp{:00} so it stands for +@samp{-05} in the same example. +@item %% +This stands for a single @samp{%}. @end table +One or more flag characters can appear immediately after the @samp{%}. +@samp{0} pads with zeros, @samp{_} pads with blanks, @samp{-} +suppresses padding, @samp{^} upper-cases letters, and @samp{#} +reverses the case of letters. + You can also specify the field width and type of padding for any of these @samp{%}-sequences. This works as in @code{printf}: you write -the field width as digits in the middle of a @samp{%}-sequences. If you -start the field width with @samp{0}, it means to pad with zeros. If you -start the field width with @samp{_}, it means to pad with spaces. - +the field width as digits in a @samp{%}-sequence, after any flags. For example, @samp{%S} specifies the number of seconds since the minute; @samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros, because that is how @samp{%S} normally pads to two positions. -The characters @samp{E} and @samp{O} act as modifiers when used between -@samp{%} and one of the letters in the table above. @samp{E} specifies +The characters @samp{E} and @samp{O} act as modifiers when used after +any flags and field widths in a @samp{%}-sequence. @samp{E} specifies using the current locale's alternative version of the date and time. In a Japanese locale, for example, @code{%Ex} might yield a date format based on the Japanese Emperors' reigns. @samp{E} is allowed in @@ -1587,6 +1599,11 @@ based on the Japanese Emperors' reigns. @samp{E} is allowed in representation of numbers, instead of the ordinary decimal digits. This is allowed with most letters, all the ones that output numbers. +To help debug programs, unrecognized @samp{%}-sequences stand for +themselves and are output as-is. Programs should not rely on this +behavior, as future versions of Emacs may recognize new +@samp{%}-sequences as extensions. + This function uses the C library function @code{strftime} (@pxref{Formatting Calendar Time,,, libc, The GNU C Library Reference Manual}) to do most of the work. In order to communicate with that diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 05d879d8f4b..b0a56492bcd 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -361,34 +361,38 @@ priority but without an overlay face. (flymake-category . flymake-note)))) @end example -@vindex flymake-text +@vindex flymake-diagnostics +@vindex flymake-diagnostic-backend +@vindex flymake-diagnostic-buffer +@vindex flymake-diagnostic-text +@vindex flymake-diagnostic-beg +@vindex flymake-diagnostic-end As you might have guessed, Flymake's annotations are implemented as overlays (@pxref{Overlays,,, elisp, The Emacs Lisp Reference Manual}). Along with the properties that you specify for the specific type of -diagnostic, Flymake adds the property @code{flymake-text} to these -overlays, and sets it to the message string that the backend used to -describe the diagnostic. +diagnostic, Flymake adds the property @code{flymake-diagnostic} to +these overlays, and sets it to the object that the backend created +with @code{flymake-make-diagnostic}. -Since overlays also support arbitrary keymaps, you can use this -property @code{flymake-text} to create interactive annotations, such -as in the following example of binding a @kbd{mouse-3} event (middle -mouse button click) to an Internet search for the text of a -@code{:warning} or @code{:error}. +Since overlays also support arbitrary keymaps, you can use this along +with the functions @code{flymake-diagnostics} and +@code{flymake-diagnostic-text} (@pxref{Flymake utility functions}) to +create interactive annotations, such as in the following example of +binding a @code{mouse-3} event (middle mouse button click) to an +Internet search for the text of a @code{:warning} or @code{:error}. @example (defun my-search-for-message (event) (interactive "e") - (let ((ovs (overlays-at (posn-point (event-start event)))) - ov) - ;; loop until flymake overlay we clicked on is recovered - (while (not (overlay-get (setq ov (pop ovs)) 'flymake-text))) - (when ov - (eww-browse-url - (concat "https://duckduckgo.com/?q=" - (replace-regexp-in-string " " - "+" - (overlay-get ov 'flymake-text))) - t)))) + (let* ((diags (flymake-diagnostics (posn-point (event-start event)))) + (topmost-diag (car diags))) + (eww-browse-url + (concat + "https://duckduckgo.com/?q=" + (replace-regexp-in-string " " + "+" + (flymake-diagnostic-text topmost-diag))) + t))) (dolist (type '(:warning :error)) (let ((a (assoc type flymake-diagnostic-types-alist))) @@ -513,6 +517,24 @@ Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to of the problem detected in this region. @end deffn +@cindex access diagnostic object +These objects' properties can be accessed with the functions +@code{flymake-diagnostic-backend}, @code{flymake-diagnostic-buffer}, +@code{flymake-diagnostic-text}, @code{flymake-diagnostic-beg}, +@code{flymake-diagnostic-end} and @code{flymake-diagnostic-type}. + +Additionally, the function @code{flymake-diagnostics} will collect +such objects in the region you specify. + +@cindex collect diagnostic objects +@deffn Function flymake-diagnostics beg end +Get a list of Flymake diagnostics in the region determined by +@var{beg} and @var{end}. If neither @var{beg} or @var{end} is +supplied, use the whole buffer, otherwise if @var{beg} is +non-@code{nil} and @var{end} is @code{nil}, consider only diagnostics +at @var{beg}. +@end deffn + @cindex buffer position from line and column number It is often the case with external syntax tools that a diagnostic's position is reported in terms of a line number, and sometimes a column @@ -520,9 +542,10 @@ number. To convert this information into a buffer position, backends can use the following function: @deffn Function flymake-diag-region buffer line &optional col -Compute @var{buffer}'s region (@var{beg} . @var{end}) corresponding to -@var{line} and @var{col}. If @var{col} is nil, return a region just -for @var{line}. Return nil if the region is invalid. +Compute @var{buffer}'s region (@var{beg} . @var{end}) corresponding +to @var{line} and @var{col}. If @var{col} is @code{nil}, return a +region just for @var{line}. Return @code{nil} if the region is +invalid. @end deffn @cindex add a log message @@ -560,7 +583,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active. (defun ruby-flymake (report-fn &rest _args) ;; Not having a ruby interpreter is a serious problem which should cause - ;; the backend to disable itself, so an @code{error} is signalled. + ;; the backend to disable itself, so an @code{error} is signaled. ;; (unless (executable-find "ruby") (error "Cannot find a suitable ruby")) @@ -600,7 +623,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active. ;; `ruby--flymake-proc', which indicates that ;; `proc' is not an obsolete process. ;; - (if (eq proc ruby--flymake-proc) + (if (with-current-buffer source (eq proc ruby--flymake-proc)) (with-current-buffer (process-buffer proc) (goto-char (point-min)) ;; Parse the output buffer for diagnostic's @@ -625,7 +648,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active. msg) into diags finally (funcall report-fn diags))) - (flymake-log :warning "Cancelling obsolete check %s" + (flymake-log :warning "Canceling obsolete check %s" proc)) ;; Cleanup the temporary buffer used to hold the ;; check's output. |