.emacs.d.git - Gitblit

Chizi123

2018-11-17 c4001ccd1864293b64aa37d83a9d9457eb875e70

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: