dnavigate.1 (2743B)
1 .TH DNAVIGATE 1 2 .sh NAME 3 dnavigate \- render menu tree from shell script 4 .SH SYNOPSIS 5 .B dnavigate 6 .IR tree 7 [\fIbranch\fR [\fIargs...\fR]] 8 .PP 9 .B dnavigate 10 \fB-d\fR \fIdmenu options...\fR -- 11 .IR tree 12 [\fIbranch\fR [\fIargs...\fR]] 13 .PP 14 .B child 15 .IR branch 16 [\fIargs...\fR] 17 .PP 18 .B tchild 19 .IR tree 20 .IR branch 21 [\fIargs...\fR] 22 .PP 23 .B run 24 .IR exec... 25 .SH DESCRIPTION 26 \fBdnavigate\fR executes shell script \fItree\fR, passing \fIbranch\fR and \fIargs\fR. 27 The script in turn sets several variables that define a menu layout, described below. 28 If no \fIbranch\fR was specified on the command line, dnavigate assumes 'main'. 29 .PP The \fBchild\fR function will execute \fBdnavigate\fR on the same tree, passing along its arguments. \fBtchild\fR does the same, but executes a different tree. 30 .PP After selecting an item, \fBdnavigate\fR will execute the corresponding command. 31 \fBdnavigate\fR will re-show the menu if the command returned a non-zero exit status. 32 \fBdnavigate\fR itself will return non-zero if the user cancels out of dmenu, or selects a blank option. 33 Combined with the \fBchild\fR command, this replicates the behaviour of a menu tree. 34 .PP By default, \fBdnavigate\fR will block until the selected command has finished executing. 35 The \fBrun\fR command will execute its arguments as a background process and \fBdnavigate\fR will exit promptly. 36 .PP All arguments to the \fB-d\fR option are passed along to dmenu. 37 .SH MENU DEFINITIONS 38 The \fItree\fR script sets several variables that define the look, layout and content of the menu to be rendered: 39 .PP 40 \fBLEAVES\fR defines an array of menu items to be displayed by dmenu. 41 .PP 42 \fBACTIONS\fR defines an array of commands, corresponding one-to-one with the items in \fBLEAVES\fR. 43 The two must have the same number of items. 44 When an item from \fBLEAVES\fR is selected, the corresponding \fBACTIONS\fR item is executed as a command. 45 This variable will be ignored if \fBINPUT\fR is set. 46 .PP 47 (Optional) \fBINPUT\fR defines a command that dnavigate will pass the user's input to. 48 If set, \fBLEAVES\fR will still be drawn but \fBACTIONS\fR will be ignored. 49 .PP 50 (Optional) \fBPROMPT\fR defines the dmenu prompt. 51 You must set this variable to allow dnavigate to build a prompt from a stack of parents; specifying \fB-p\fR as a dmenu option breaks this behaviour. 52 .PP 53 (Optional) \fBLINES\fR defines the number of rows drawn by dmenu. 54 dnavigate will pad the \fBLEAVES\fR and \fBACTIONS\fR arrays with empty elements if necessary. 55 .PP 56 (Optional) \fBOPTIONS\fR contains the list of dmenu options passed during invocation, and may be modified before the menu is drawn. 57 .SH ENVIRONMENT VARIABLES 58 \fBDNAVIGATE_DIR\fR defines the directory that \fBdnavigate\fR searches for trees ($HOME/.dnavigate.d by default)