mirror of https://github.com/Chizi123/.emacs.d.git
view | history | commit | commitdiff
Chizi123
2018-11-18 c655eea759be1db69c5e6b45c228139d8390122a
commit | author | age
5cb5f7 1 This is magit-popup.info, produced by makeinfo version 6.5 from
C 2 magit-popup.texi.
3
4      Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
5
6      You can redistribute this document and/or modify it under the terms
7      of the GNU General Public License as published by the Free Software
8      Foundation, either version 3 of the License, or (at your option)
9      any later version.
10
11      This document is distributed in the hope that it will be useful,
12      but WITHOUT ANY WARRANTY; without even the implied warranty of
13      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14      General Public License for more details.
15 INFO-DIR-SECTION Emacs
16 START-INFO-DIR-ENTRY
17 * Magit-Popup: (magit-popup). Infix arguments with feedback.
18 END-INFO-DIR-ENTRY
19
20 
21 File: magit-popup.info,  Node: Top,  Next: Introduction,  Up: (dir)
22
23 Magit-Popup User Manual
24 ***********************
25
26 Taking inspiration from regular prefix commands and prefix arguments,
27 this library implements a similar abstraction; a new kind of prefix
28 command that is associated with a specific set of infix arguments and
29 suffix commands.
30
31 This manual is for Magit-Popup version 2.12.4 (v2.12.4+1).
32
33      Copyright (C) 2015-2018 Jonas Bernoulli <jonas@bernoul.li>
34
35      You can redistribute this document and/or modify it under the terms
36      of the GNU General Public License as published by the Free Software
37      Foundation, either version 3 of the License, or (at your option)
38      any later version.
39
40      This document is distributed in the hope that it will be useful,
41      but WITHOUT ANY WARRANTY; without even the implied warranty of
42      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
43      General Public License for more details.
44
45 * Menu:
46
47 * Introduction::
48 * Usage::
49 * Defining Prefix and Suffix Commands::
50
51 — The Detailed Node Listing —
52
53 Usage
54
55 * Customizing Existing Popups::
56 * Other Options::
57
58 Defining Prefix and Suffix Commands
59
60 * Defining Prefix Commands::
61 * Defining Suffix Commands::
62
63
64 
65 File: magit-popup.info,  Node: Introduction,  Next: Usage,  Prev: Top,  Up: Top
66
67 1 Introduction
68 **************
69
70 Taking inspiration from regular prefix commands and prefix arguments,
71 this library implements a similar abstraction; a new kind of prefix
72 command that is associated with a specific set of infix arguments and
73 suffix commands.
74
75    Invoking such a prefix command displays a popup buffer which lists
76 the associated infix arguments and suffix commands.  In that buffer each
77 argument is prefixed with the key sequence that can be used to toggle it
78 or change its value.  Likewise each suffix command is prefixed with the
79 key used to invoke it.  Such a popup buffer might look like this:
80
81      ,-----------------------------------------
82      |Switches
83      | -l Show graph (--graph)
84      | -d Show refnames (--decorate)
85      |
86      |Options
87      | =m Search messages (--grep="popup")
88      | =p Search patches (-G)
89      |
90      |Action
91      | l Show log for current branch
92      | o Show log for another branch
93      '-----------------------------------------
94
95    The user could then for example type ‘-l’ to toggle the ‘--graph’
96 *switch* (when it is on then it is shown in green, otherwise in gray),
97 or ‘=m’ to change the value of the *option* ‘--grep’.
98
99    Once all arguments are as desired one invokes a suffix command, which
100 causes the popup buffer to disappear.  The suffix command should then
101 retrieve the infix arguments in its ‘interactive’ form like this is done
102 for prefix arguments.
103
104    While such "prefix-infix-suffix" combos were inspired by regular
105 prefix commands and prefix arguments, they are also quite different.
106 This should illustrate the most basic differences:
107
108    • A regular prefix command
109
110                   /- command1
111           prefix --- command2
112                   \- command3
113
114    • Prefix arguments
115
116                    /- command1
117           C-u ... --- command2
118                    \- well any command
119
120    • A Prefix-Infix-Suffix combo
121
122                    /- argument1 -\ /- suffix1
123           prefix----- argument2 --+-- suffix2
124                  ^ \- argument3 -/
125                  |        |
126                  '--------'
127               (refresh buffer)
128
129    This library was written as a replacement for ‘magit-key-mode’, which
130 was used in Magit releases before 2.1.0.  It is used to implement all
131 "popups" in the current Magit release but a future release will switch
132 to yet another implementation.
133
134    This library does not depend on any other Magit libraries and it is
135 distributed as a separate package, which makes it possible to use it in
136 packages that are not related to Magit.  But keep in mind that it will
137 be deprecated eventually.
138
139 
140 File: magit-popup.info,  Node: Usage,  Next: Defining Prefix and Suffix Commands,  Prev: Introduction,  Up: Top
141
142 2 Usage
143 *******
144
145 Every popup buffers created with a prefix command contains a section
146 named "Actions" listing the available suffix commands.  Most buffers
147 also contain a "Switches" and/or an "Options" section which list the two
148 types of infix arguments separately.
149
150    Switches are arguments that can be toggled on or off.  When a switch
151 is active then it is shown in color, when it is off then it is shown in
152 gray (of course the details depend on the color theme in use).
153
154    Options are arguments that have a value.  When an option has a value
155 then that is shown after the option itself.  Because for some options
156 the empty string is a valid value, options are additionally colorized
157 like switches to indicate whether they are active or not.
158
159    The events bound to suffix commands are always single alphabetic
160 characters.  The bindings for arguments are always two events long.  For
161 switches the first key is always ‘-’, for options it is always ‘=’.  The
162 second key is always an alphabetic character.
163
164    By default popup buffers also feature a section listing commands
165 common to all popups.  To avoid conflicts with suffix commands, the
166 bindings of these common commands are not alphabetic characters.  This
167 section is shown by default so that documentation-resistant users get a
168 chance to notice them.
169
170  -- User Option: magit-popup-show-common-commands
171
172      This option controls whether the section that lists the commands
173      that are common to all popups is initially shown.
174
175      By default this is not the case, but note that you can temporarily
176      show this section using ‘C-t’, which therefore is the only common
177      command you actually have to memorize.
178
179 ‘C-t’     (‘magit-popup-toggle-show-common-commands’)
180
181      Show or hide the section listing the commands shared by all popups.
182
183 ‘C-g’     (‘magit-popup-quit’)
184
185      Quit popup buffer without invoking a suffix command.
186
187    Without further action, setting arguments only affects the next
188 suffix command.  Invoking the same prefix command again resets the
189 arguments to their default value, but the defaults can be changed
190 directly from the popup buffer itself.  For a prefix command named
191 ‘NAME-popup’ the default values are stored as the value of the custom
192 option named ‘NAME-arguments’.  While this option can be customized
193 using the Custom interface, it is better to do so directly from the
194 popup buffer.
195
196 ‘C-c C-c’     (‘magit-popup-set-default-arguments’)
197
198      This sets the default value for the arguments for the current
199      popup.
200
201      Then the popup buffer is closed without invoking a suffix command;
202      unless a prefix argument is used in which case the popup remains
203      open.
204
205 ‘C-x C-s’     (‘magit-popup-save-default-arguments’)
206
207      This sets the default value for the arguments for the current popup
208      and saves it for future Emacs sessions.
209
210      Then the popup buffer is closed without invoking an action; unless
211      a prefix argument is used in which case the popup remains open.
212
213    It is also possible to add additional arguments and commands to an
214 existing popup, but that cannot be done directly from the popup (or the
215 Custom interface).  See *note Customizing Existing Popups::.
216
217    Documentation about a popup’s arguments and commands can be shown
218 directly from the popup.
219
220 ‘C-h i’     (‘magit-popup-info’)
221
222      Show this manual.
223
224 ‘?’     (‘magit-popup-help’)
225
226      This command reads a key sequence and then shows the documentation
227      of the argument or command that sequence is bound to.  In other
228      words type the same keys that you would use to invoke the argument
229      or command, but prefix the sequence with ‘?’.
230
231      For suffix commands this shows the doc-string.  For arguments this
232      command can only show something for popups that have an associated
233      man-page.  If the man-page is set, then this command displays it in
234      a separate buffer and puts point on the entry about the argument in
235      question.
236
237      The buffer which is used to display the documentation is selected.
238      Simply press ‘q’ to leave that buffer and restore the old window
239      configuration.
240
241    While it isn’t very useful, it is possible to move around in a popup
242 buffer using ‘C-p’ and ‘C-n’, and to invoke the argument or command at
243 point using ‘RET’.  But it is much more efficient to use the dedicated
244 key bindings instead, so these commands are not listed in popup buffers
245 along with the other common commands.
246
247 * Menu:
248
249 * Customizing Existing Popups::
250 * Other Options::
251
252 
253 File: magit-popup.info,  Node: Customizing Existing Popups,  Next: Other Options,  Up: Usage
254
255 2.1 Customizing Existing Popups
256 ===============================
257
258 It is possible to define additional infix arguments and suffix commands
259 to an existing popup using the following functions.
260
261    You can find some examples which use the below commands at
262 <https://github.com/magit/magit/wiki/Additional-proposed-infix-arguments-and-suffix-commands>.
263
264  -- Function: magit-define-popup-switch popup key desc switch &optional
265           enable at prepend
266
267      In POPUP, define KEY as SWITCH.
268
269      POPUP is a popup command defined using ‘magit-define-popup’.
270      SWITCH is a string representing an argument that takes no value.
271      KEY is a character representing the second event in the sequence of
272      keystrokes used to toggle the argument.  (The first event, the
273      prefix, is shared among all switches, defaults to ‘-’, and can be
274      changed in ‘magit-popup-mode-keymap’).
275
276      DESC is a string describing the purpose of the argument, it is
277      displayed in the popup.
278
279      If optional ENABLE is non-nil then the switch is on by default.
280
281      SWITCH is inserted after all other switches already defined for
282      POPUP, unless optional PREPEND is non-nil, in which case it is
283      placed first.  If optional AT is non-nil then it should be the KEY
284      of another switch already defined for POPUP, the argument is then
285      placed before or after AT, depending on PREPEND.
286
287  -- Function: magit-define-popup-option popup key desc option &optional
288           reader value at prepend
289
290      In POPUP, define KEY as OPTION.
291
292      POPUP is a popup command defined using ‘magit-define-popup’.
293      OPTION is a string representing an argument that takes a value.
294      KEY is a character representing the second event in the sequence of
295      keystrokes used to set the argument’s value.  (The first event, the
296      prefix, is shared among all options, defaults to ‘=’, and can be
297      changed in ‘magit-popup-mode-keymap’).
298
299      DESC is a string describing the purpose of the argument, it is
300      displayed in the popup.
301
302      If optional VALUE is non-nil then the option is on by default, and
303      VALUE is its default value.
304
305      READER is used to read a value from the user when the option is
306      invoked and does not currently have a value.  (When the option has
307      a value, then invoking the option causes it to be unset.)  This
308      function must take two arguments but may choose to ignore them.
309      The first argument is the name of the option (with ": \" appended,
310      unless it ends with "=") and can be used as the prompt.  The second
311      argument is nil or the value that was in effect before the option
312      was unset, which may be suitable as initial completion input.  If
313      no reader is specified, then ‘read-from-minibuffer’ is used.
314
315      OPTION is inserted after all other options already defined for
316      POPUP, unless optional PREPEND is non-nil, in which case it is
317      placed first.  If optional AT is non-nil then it should be the KEY
318      of another option already defined for POPUP, the argument is then
319      placed before or after AT, depending on PREPEND.
320
321  -- Function: magit-define-popup-action popup key desc command &optional
322           at prepend
323
324      In POPUP, define KEY as COMMAND.
325
326      POPUP is a popup command defined using ‘magit-define-popup’.
327      COMMAND can be any command but should usually consume the popup
328      arguments in its ‘interactive’ form.  KEY is a character
329      representing the event used invoke the action, i.e.  to
330      interactively call the COMMAND.
331
332      DESC is a string describing the purpose of the action, it is
333      displayed in the popup.
334
335      COMMAND is inserted after all other commands already defined for
336      POPUP, unless optional PREPEND is non-nil, in which case it is
337      placed first.  If optional AT is non-nil then it should be the KEY
338      of another command already defined for POPUP, the command is then
339      placed before or after AT, depending on PREPEND.
340
341  -- Function: magit-define-popup-sequence-action popup key desc command
342           &optional at prepend
343
344      Like ‘magit-define-popup-action’, but modifies the value of the
345      ‘:sequence-actions’ property instead of ‘:actions’.
346
347  -- Function: magit-define-popup-variable popup key desc command
348           formatter &optional at prepend
349
350      In POPUP, define KEY as COMMAND.
351
352      POPUP is a popup command defined using ‘magit-define-popup’.
353      COMMAND is a command which calls ‘magit-popup-set-variable’.
354      FORMATTER is a function which calls ‘magit-popup-format-variable’.
355      These two functions have to be called with the same arguments.
356
357      KEY is a character representing the event used interactively call
358      the COMMAND.
359
360      DESC is the variable or a representation thereof.  It’s not
361      actually used for anything.
362
363      COMMAND is inserted after all other commands already defined for
364      POPUP, unless optional PREPEND is non-nil, in which case it is
365      placed first.  If optional AT is non-nil then it should be the KEY
366      of another command already defined for POPUP, the command is then
367      placed before or after AT, depending on PREPEND."
368
369  -- Function: magit-change-popup-key popup type from to
370
371      In POPUP, bind TO to what FROM was bound to.  TYPE is one of
372      ‘:action’, ‘:sequence-action’, ‘:switch’, or ‘:option’.  Bind TO
373      and unbind FROM, both are characters.
374
375  -- Function: magit-remove-popup-key popup type key
376
377      In POPUP, remove KEY’s binding of TYPE.  POPUP is a popup command
378      defined using ‘magit-define-popup’.  TYPE is one of ‘:action’,
379      ‘:sequence-action’, ‘:switch’, or ‘:option’.  KEY is the character
380      which is to be unbound.
381
382    It is also possible to change other aspects of a popup by setting a
383 property using ‘plist-put’.  See *note Defining Prefix Commands:: for
384 valid properties.  The most likely change Magit users might want to make
385 is:
386
387      (plist-put magit-show-refs-popup :use-prefix nil)
388
389 
390 File: magit-popup.info,  Node: Other Options,  Prev: Customizing Existing Popups,  Up: Usage
391
392 2.2 Other Options
393 =================
394
395  -- User Option: magit-popup-use-prefix-argument
396
397      This option controls the effect that the use of a prefix argument
398      before entering a popup has.
399
400         • ‘default’
401
402           With a prefix argument directly invoke the popup’s default
403           action (an Emacs command), instead of bringing up the popup.
404
405         • ‘popup’
406
407           With a prefix argument bring up the popup, otherwise directly
408           invoke the popup’s default action.
409
410         • ‘nil’
411
412           Ignore prefix arguments.
413
414      This option can be overridden for individual popups.
415      ‘magit-show-refs-popup’ for example defaults to invoking the
416      default action directly.  It only shows the popup buffer when a
417      prefix argument is used.  See *note Customizing Existing Popups::.
418
419  -- User Option: magit-popup-manpage-package
420
421      The Emacs package used to display man-pages, one of ‘man’ or
422      ‘woman’.
423
424  -- User Option: magit-popup-display-buffer-action
425
426      The option controls how the window used to display a popup buffer
427      is created.  Popup buffers are displayed using ‘display-buffer’
428      with the value of this option as ACTION argument.  You can also set
429      this to nil and instead add an entry to ‘display-buffer-alist’.
430
431    To emphasize the default action by making it bold use this:
432
433      (button-type-put 'magit-popup-action-button 'format " %k %D")
434
435 
436 File: magit-popup.info,  Node: Defining Prefix and Suffix Commands,  Prev: Usage,  Up: Top
437
438 3 Defining Prefix and Suffix Commands
439 *************************************
440
441 If you write an extension for Magit then you should use this library now
442 and later when ‘transient’ is released port to that.
443
444    If you are considering using this library to define popups for
445 packages not related to Magit, then keep in mind that it will be
446 superseded eventually.  Once ‘transient’ has been released I will only
447 fix bugs in ‘magit-popup’ but not implement any new features.
448
449    Also consider using ‘hydra’ instead.  To some extend ‘magit-popup’
450 and ‘hydra’ are similar but have a different focus.  The main purpose of
451 ‘magit-popup’ is to pass infix arguments to suffix commands.  If all you
452 need is a command dispatcher then you are better of using ‘hydra’.  Of
453 course ‘hydra’ may also be a better fit not only because of the features
454 it lacks, but also because of the features it provides, which are in
455 turn missing from ‘magit-popup’.
456
457    Here is an example of how one defines a prefix command along with its
458 infix arguments, and then also one of its suffix commands.
459
460      ;;;###autoload (autoload 'magit-tag-popup "magit" nil t)
461      (magit-define-popup magit-tag-popup
462        "Show popup buffer featuring tagging commands."
463        'magit-commands
464        :man-page "git-tag"
465        :switches '((?a "Annotate" "--annotate")
466                    (?s "Sign"     "--sign")
467                    (?f "Force"    "--force"))
468        :actions  '((?t "Create"   magit-tag)
469                    (?k "Delete"   magit-tag-delete)
470                    (?p "Prune"    magit-tag-prune))
471        :default-action 'magit-tag)
472
473      ;;;###autoload
474      (defun magit-tag (name rev &optional args)
475        "Create a new tag with the given NAME at REV."
476        (interactive (list (magit-read-tag "Tag name")
477                           (magit-read-branch-or-commit "Place tag on")
478                           (magit-tag-arguments)))
479        (magit-run-git-with-editor "tag" args name rev))
480
481 * Menu:
482
483 * Defining Prefix Commands::
484 * Defining Suffix Commands::
485
486 
487 File: magit-popup.info,  Node: Defining Prefix Commands,  Next: Defining Suffix Commands,  Up: Defining Prefix and Suffix Commands
488
489 3.1 Defining Prefix Commands
490 ============================
491
492 Prefix commands and their infix arguments are defined using the macro
493 ‘magit-define-popup’.  The key bindings and descriptions of suffix
494 commands are also defined using that macro, but the actual interactive
495 commands have to be defined separately using plain ‘defun’.
496
497  -- Macro: magit-define-popup name doc [group [mode [option]]] :keyword
498           value...
499
500      This macro defines a popup named NAME.  The NAME should begin with
501      the package prefix and by convention end with ‘-popup’, it is used
502      as the name of the command which shows the popup and for an
503      internal variable (whose value is used to store information about
504      the popup and should not be accessed directly).  DOC is the
505      doc-string of the popup command.
506
507      This macro also defines an option and a function both named
508      ‘SHORTNAME-arguments’, where SHORTNAME is NAME with the trailing
509      ‘-popup’ removed.  The name of this option and this function can be
510      overwritten using the optional argument OPTION, but that is rarely
511      advisable.  As a special case if OPTION is specified but ‘nil’,
512      then this option and this function are not defined at all, which is
513      useful for popups that are used as simple dispatchers that offer no
514      arguments.
515
516      The option ‘SHORTNAME-arguments’ holds the value for the popup
517      arguments.  It can be customized from within the popup or using the
518      Custom interface.  It can also have a buffer local value in any
519      non-popup buffer.  The local value for the buffer from which the
520      popup command was invoked, can be set from within the popup buffer.
521
522      The function ‘SHORTNAME-arguments’ returns the currently effective
523      value of the variable by the same name.  See below for more
524      information.
525
526      Optional argument GROUP specifies the Custom group into which the
527      option is placed.  If omitted then the option is placed into some
528      group the same way it is done when directly using ‘defcustom’ and
529      omitting the group, except when NAME begins with "magit-", in which
530      case the group ‘magit-git-arguments’ is used.
531
532      The optional argument MODE specifies the mode used by the popup
533      buffer.  If it is omitted or ‘nil’ then ‘magit-popup-mode’ is used.
534
535      The remaining arguments should have the form ‘[KEYWORD VALUE]...’.
536
537      The following keywords are meaningful (and by convention are
538      usually specified in that order):
539
540         • ‘:actions’
541
542           The actions which can be invoked from the popup.  VALUE is a
543           list whose members have the form (KEY DESC COMMAND), see
544           ‘magit-define-popup-action’ for details.
545
546           Actions are regular Emacs commands, which usually have an
547           ‘interactive’ form setup to consume the values of the popup
548           ‘:switches’ and ‘:options’ when invoked from the corresponding
549           popup, else when invoked as the default action or directly
550           without using the popup, the default value of the variable
551           ‘SHORTNAME-arguments’.  This is usually done by calling the
552           function ‘SHORTNAME-arguments’.
553
554           Members of VALUE may also be strings and functions, assuming
555           the first member is a string or function.  In that case the
556           members are split into sections and these special elements are
557           used as headings.  If such an element is a function then it is
558           called with no arguments and must return either a string,
559           which is used as the heading, or nil, in which case the
560           section is not inserted.
561
562           Members of VALUE may also be nil.  This should only be used
563           together with ‘:max-action-columns’ and allows having gaps in
564           the action grit, which can help arranging actions sensibly.
565
566         • ‘:default-action’
567
568           The default action of the popup which is used directly instead
569           of displaying the popup buffer, when the popup is invoked with
570           a prefix argument.  Also see ‘magit-popup-use-prefix-argument’
571           and ‘:use-prefix’, which can be used to inverse the meaning of
572           the prefix argument.
573
574         • ‘:use-prefix’
575
576           Controls when to display the popup buffer and when to invoke
577           the default action (if any) directly.  This overrides the
578           global default set using ‘magit-popup-use-prefix-argument’.
579           The value, if specified, should be one of ‘default’ or
580           ‘prefix’, or a function that is called with no arguments and
581           returns one of these symbols.
582
583         • ‘:max-action-columns’
584
585           The maximum number of actions to display on a single line, a
586           number or a function that return a number and takes the name
587           of the section currently being inserted as argument.  If there
588           isn’t enough room to display as many columns as specified
589           here, then fewer are used.
590
591         • ‘:switches’
592
593           The popup arguments which can be toggled on and off.  VALUE is
594           a list whose members have the form ‘(KEY DESC SWITCH)’, see
595           ‘magit-define-popup-switch’ for details.
596
597           Members of VALUE may also be strings and functions, assuming
598           the first member is a string or function.  In that case the
599           members are split into sections and these special elements are
600           used as headings.  If such an element is a function then it is
601           called with no arguments and must return either a string,
602           which is used as the heading, or nil, in which case the
603           section is not inserted.
604
605         • ‘:options’
606
607           The popup arguments which take a value, as in "–opt~OPTVAL".
608           VALUE is a list whose members have the form ‘(KEY DESC OPTION
609           READER)’, see ‘magit-define-popup-option’ for details.
610
611           Members of VALUE may also be strings and functions, assuming
612           the first member is a string or function.  In that case the
613           members are split into sections and these special elements are
614           used as headings.  If such an element is a function then it is
615           called with no arguments and must return either a string,
616           which is used as the heading, or nil, in which case the
617           section is not inserted.
618
619         • ‘:default-arguments’
620
621           The default arguments, a list of switches (which are then
622           enabled by default) and options with there default values, as
623           in ‘"--OPT=OPTVAL"’.
624
625         • ‘:variables’
626
627           Variables which can be set from the popup.  VALUE is a list
628           whose members have the form ‘(KEY DESC COMMAND FORMATTER)’,
629           see ‘magit-define-popup-variable’ for details.
630
631           Members of VALUE may also be strings and functions, assuming
632           the first member is a string or function.  In that case the
633           members are split into sections and these special elements are
634           used as headings.  If such an element is a function then it is
635           called with no arguments and must return either a string,
636           which is used as the heading, or nil, in which case the
637           section is not inserted.
638
639           Members of VALUE may also be actions as described above for
640           ‘:actions’.
641
642           VALUE may also be a function that returns a list as describe
643           above.
644
645         • ‘:sequence-predicate’
646
647           When this function returns non-nil, then the popup uses
648           ‘:sequence-actions’ instead of ‘:actions’, and does not show
649           the ‘:switches’ and ‘:options’.
650
651         • ‘:sequence-actions’
652
653           The actions which can be invoked from the popup, when
654           ‘:sequence-predicate’ returns non-nil.
655
656         • ‘:setup-function’
657
658           When this function is specified, then it is used instead of
659           ‘magit-popup-default-setup’.
660
661         • ‘:refresh-function’
662
663           When this function is specified, then it is used instead of
664           calling ‘magit-popup-insert-section’ three times with symbols
665           ‘magit-popup-switch-button’, ‘magit-popup-option-button’, and
666           finally ‘magit-popup-action-button’ as argument.
667
668         • ‘:man-page’
669
670           The name of the manpage to be displayed when the user requests
671           help for an argument.
672
673 
674 File: magit-popup.info,  Node: Defining Suffix Commands,  Prev: Defining Prefix Commands,  Up: Defining Prefix and Suffix Commands
675
676 3.2 Defining Suffix Commands
677 ============================
678
679 Commands intended to be invoked from a particular popup should determine
680 the currently effective arguments by calling the function
681 ‘SHORTNAME-arguments’ inside their ‘interactive’ form.  This function is
682 created by the ‘magit-define-popup’ macro.  For a popup named
683 ‘prefix-foo-popup’ the name of this function is ‘prefix-foo-arguments’.
684
685    When the command was invoked as an action in the respective popup,
686 then this function returns the arguments that were set in the popup.
687 Otherwise when the command was invoked as the default of the popup (by
688 calling the popup command with a prefix argument), or without using the
689 popup command at all, then this function returns the buffer-local or
690 global value of the variable ‘SHORTNAME-arguments’.
691
692    Internally arguments are handled as a list of strings.  This might
693 not be appropriate for the intended use inside commands, or it might be
694 necessary to manipulate that list somehow, i.e.  to split "–ARG=VAL"
695 into "–ARG""VAL". This should be done by advising or redefining the
696 function ‘SHORTNAME-arguments’.
697
698    Internally ‘SHORNAME-arguments’ used following variables and
699 function.  Except when redefining the former, you should not use these
700 directly.
701
702  -- Variable: magit-current-popup
703
704      The popup from which this editing command was invoked.
705
706  -- Variable: magit-current-popup-args
707
708      The value of the popup arguments for this editing command.
709
710      If the current command was invoked from a popup, then this is a
711      list of strings of all the set switches and options.  This includes
712      arguments which are set by default not only those explicitly set
713      during this invocation.
714
715      When the value is nil, then that can be because no argument is set,
716      or because the current command wasn’t invoked from a popup at all.
717
718  -- Function: magit-current-popup-args &rest args
719
720      This function returns the value of the popup arguments for this
721      editing command.  The value is the same as that of the variable by
722      the same name, except that FILTER is applied.  FILTER is a list of
723      regexps; only arguments that match one of them are returned.  The
724      first element of FILTER may also be ‘:not’ in which case only
725      arguments that don’t match any of the regexps are returned, or
726      ‘:only’ which doesn’t change the behavior.
727
728
729 
730 Tag Table:
731 Node: Top769
732 Node: Introduction2004
733 Node: Usage4703
734 Node: Customizing Existing Popups9400
735 Node: Other Options15541
736 Node: Defining Prefix and Suffix Commands17084
737 Node: Defining Prefix Commands19236
738 Node: Defining Suffix Commands27931
739 
740 End Tag Table
741
742 
743 Local Variables:
744 coding: utf-8
745 End: