1 2;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 3;; 4;; MODULE : generic-doc.scm 5;; DESCRIPTION : documentation of general tags 6;; COPYRIGHT : (C) 2010 Joris van der Hoeven 7;; 8;; This software falls under the GNU general public license version 3 or later. 9;; It comes WITHOUT ANY WARRANTY WHATSOEVER. For details, see the file LICENSE 10;; in the root directory or <http://www.gnu.org/licenses/gpl-3.0.html>. 11;; 12;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 13 14(texmacs-module (generic generic-doc) 15 (:use (generic generic-menu))) 16 17;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 18;; Brief description of the tag 19;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 20 21(define (avoid-conflict name prev-names i) 22 (with s (if (== i 1) name (string-append name (number->string i))) 23 (if (nin? s prev-names) s 24 (avoid-conflict name prev-names (+ i 1))))) 25 26(define (focus-doc-arg-name t i prev-names) 27 (with s (tree-child-name t i) 28 (avoid-conflict 29 (cond ((!= s "") s) 30 ((== (tree-child-type t i) "regular") "body") 31 (else (tree-child-type t i))) 32 prev-names 1))) 33 34(tm-define (focus-doc-arg-names t i prev-names) 35 (if (>= i (tree-arity t)) '() 36 (with s (focus-doc-arg-name t i prev-names) 37 (cons s (focus-doc-arg-names t (+ i 1) (cons s prev-names)))))) 38 39(tm-generate (focus-doc-usage-args t) 40 ($with l (focus-doc-arg-names t 0 '()) 41 ($description-aligned 42 ($for (i (.. 0 (tree-arity t))) 43 ($with s (list-ref l i) 44 ($describe-item ($src-arg s) 45 ($if (== s "body") 46 "The main body of the macro." 47 ($begin 48 "An argument of type ``" (tree-child-type t i) "''.")))))))) 49 50(tm-generate (focus-doc-usage t) 51 ($let* ((lab (tree-label t)) 52 (l (focus-doc-arg-names t 0 '()))) 53 ($explain `(explain-macro ,(symbol->string lab) ,@l) 54 (focus-doc-usage-args t)))) 55 56;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 57;; Show current definition of the tag 58;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 59 60(tm-generate (focus-doc-source t) 61 ($with s (symbol->string (tree-label t)) 62 ($with def (get-env-tree s) 63 ($tm-fragment `(inactive* (assign ,s ,def))) 64 $lf))) 65 66;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 67;; Document structured variants 68;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 69 70(define (tree->markup t) 71 ($markup (symbol->string (tree-label t)))) 72 73(tm-generate (focus-doc-variants t) 74 ($let* ((lab (tree-label t)) 75 (l (focus-variants-of t))) 76 ($para 77 "The " ($markup lab) " tag admits various " 78 ($tmdoc-link "main/editing/man-structured-variants" 79 "structured variants") 80 ": " ($markup (car l)) 81 ($for (x (cdr l)) ", " ($markup x)) ". " 82 "You may circle among these variants using the keyboard shortcuts " 83 ($shortcut (variant-circulate (focus-tree) #t)) " and " 84 ($shortcut (variant-circulate (focus-tree) #f)) ". " 85 "You may also pick a specific variant from the " 86 ($menu "Focus" (focus-tag-name lab)) " menu or the " 87 ($menu (focus-tag-name lab)) " menu on the focus toolbar."))) 88 89(tm-generate (focus-doc-numbered t) 90 ($let* ((lab (tree-label t)) 91 (lab* (symbol-toggle-number lab))) 92 ($para 93 ($when (numbered-numbered? t) 94 "For most style files, the " ($markup lab) 95 " environment is numbered. " 96 "The environment admits an unnumbered variant " ($markup lab*) ". ") 97 ($when (not (numbered-numbered? t)) 98 "For most style files, the " ($markup lab) 99 " environment is unnumbered. " 100 "The environment admits a numbered variant " ($markup lab*) ". ") 101 "You may toggle the numbering using the keyboard shortcut " 102 ($shortcut (numbered-toggle (focus-tree))) ", the menu entry " 103 ($menu "Focus" "Numbered") ", or by pressing the " 104 ($tmdoc-icon "tm_numbered.xpm") " icon on the focus toolbar."))) 105 106(tm-generate (focus-doc-alternate t) 107 ($let* ((lab (tree-label t)) 108 (lab* (symbol-toggle-alternate lab))) 109 ($para 110 ($when (alternate-first? t) 111 "The " ($markup lab) " environment is ``folded'' " 112 "and admits an unfolded variant " ($markup lab*) ". " 113 "You may unfold the environment using the keyboard shortcut " 114 ($shortcut (alternate-toggle (focus-tree))) ", the menu entry " 115 ($menu "Focus" "Folded") ", or by pressing the " 116 ($tmdoc-icon "tm_alternate_first.xpm") 117 " icon on the focus toolbar. ") 118 ($when (alternate-second? t) 119 "The " ($markup lab) " environment is ``unfolded'' " 120 "and admits a folded variant " ($markup lab*) ". " 121 "You may fold the environment using the keyboard shortcut " 122 ($shortcut (alternate-toggle (focus-tree))) ", the menu entry " 123 ($menu "Focus" (alternate-second-name t)) ", or by pressing the " 124 ($tmdoc-icon (alternate-second-icon t)) 125 " icon on the focus toolbar. ") 126 "Folding and unfolding is performed automatically during " 127 "the traversal of a document in " 128 ($tmdoc-link "main/beamer/man-beamer" 129 "presentation mode") 130 "."))) 131 132(tm-generate (focus-doc-toggles t) 133 ($when (numbered-context? t) 134 (focus-doc-numbered t)) 135 ($when (alternate-context? t) 136 (focus-doc-alternate t))) 137 138(tm-generate (focus-doc-toggles-variants t) 139 ($when (focus-has-variants? t) 140 (focus-doc-variants t)) 141 ($when (focus-has-toggles? t) 142 (focus-doc-toggles t))) 143 144;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 145;; Stylistic preferences for tag 146;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 147 148(tm-generate (focus-doc-style-option opt) 149 ($with opt-doc (tmdoc-search-style opt) 150 ($when opt-doc opt-doc) 151 ($when (not opt-doc) 152 ($explain ($inline `(tmpackage ,opt) 153 `(explain-synopsis ,(style-get-menu-name opt))) 154 ($with brief-doc (style-get-documentation opt) 155 ($when brief-doc brief-doc ".") 156 ($when (not brief-doc) "Undocumented style package.")))))) 157 158(tm-generate (focus-doc-parameter par) 159 ($with par-doc (tmdoc-search-parameter par) 160 ($when par-doc par-doc) 161 ($when (not par-doc) 162 ($explain `(src-var ,par) 163 "A parameter of type " (tree-label-type (string->symbol par)) ".")))) 164 165(tm-generate (focus-doc-preferences t) 166 ($let* ((lab (tree-label t)) 167 (opts (search-tag-options t)) 168 (pars (list-filter (search-tag-parameters t) 169 parameter-show-in-menu?))) 170 ($block 171 ($para 172 "The rendering of the " ($markup lab) 173 " tag can be customized by editing the macro which defines it. " 174 "This can be done by clicking on " ($menu "Edit macro") 175 " button in the " ($menu "Focus" "Preferences") " menu " 176 "(or in the equivalent " ($tmdoc-icon "tm_focus_prefs.xpm") 177 " icon menu on the focus toolbar). " 178 "You may also directly edit the macro in the style file or package " 179 "where it was defined, using " ($menu "Edit source") ".") 180 181 ($when (nnull? (append opts pars)) 182 ($para 183 "Still using the " ($menu "Focus" "Preferences") " menu, " 184 "you may also specify " 185 ($when (and (nnull? opts) (null? pars)) 186 "style options") 187 ($when (and (null? opts) (nnull? pars)) 188 "style parameters") 189 ($when (and (nnull? opts) (nnull? pars)) 190 "style options and parameters") 191 " which apply to the " ($markup lab) " tag. " 192 "These settings are global, so they will apply to all other " 193 ($markup lab) " tags in your document, and generally also to " 194 "other similar tags.")) 195 196 ($when (nnull? opts) 197 ($folded ($strong "Style options") 198 ($for (opt opts) 199 (focus-doc-style-option opt)))) 200 201 ($when (nnull? pars) 202 ($folded ($strong "Style parameters") 203 ($for (par pars) 204 (focus-doc-parameter par))))))) 205 206;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 207;; Document structured editing operations 208;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 209 210(tm-generate (focus-doc-similar t) 211 ($with lab (tree-label t) 212 ($if (focus-has-variants? t) 213 ($begin "tag similar to " ($markup lab)) 214 ($begin ($markup lab) " tag")))) 215 216(tm-generate (focus-doc-move t) 217 ($with lab (tree-label t) 218 ($para 219 "It is sometimes useful to quickly go through all " 220 ($markup lab) " tags" 221 ($when (focus-has-variants? t) " and its variants, ") 222 " inside a document. " 223 "This can be done efficiently using the following keyboard shortcuts, " 224 "menu entries, or icons on the focus toolbar: ") 225 ($description-long 226 ($describe-item 227 ($inline ($shortcut (traverse-first)) ", " 228 ($menu "Focus" "First similar") ", " 229 ($tmdoc-icon "tm_similar_first.xpm")) 230 "Jump to the first " (focus-doc-similar t) ".") 231 ($describe-item 232 ($inline ($shortcut (traverse-previous)) ", " 233 ($menu "Focus" "Previous similar") ", " 234 ($tmdoc-icon "tm_similar_previous.xpm")) 235 "Jump to the previous " (focus-doc-similar t) ".") 236 ($describe-item 237 ($inline ($shortcut (traverse-next)) ", " 238 ($menu "Focus" "Next similar") ", " 239 ($tmdoc-icon "tm_similar_next.xpm")) 240 "Jump to the next " (focus-doc-similar t) ".") 241 ($describe-item 242 ($inline ($shortcut (traverse-last)) ", " 243 ($menu "Focus" "Last similar") ", " 244 ($tmdoc-icon "tm_similar_last.xpm")) 245 "Jump to the last " (focus-doc-similar t) ".")) 246 ($para 247 "For more information and further useful shortcuts, " 248 "we refer to the section on " 249 ($tmdoc-link "main/editing/man-structured-move" 250 "structured cursor movements") 251 "."))) 252 253;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 254;; Insert and remove children 255;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 256 257(tm-generate (focus-doc-insert t) 258 ($with lab (tree-label t) 259 ($para 260 "The " ($markup lab) " tag has a variable number of arguments. " 261 "New arguments can be inserted using the following keyboard shortcuts, " 262 "menu entries, or icons on the focus toolbar: ") 263 ($description-long 264 ($when (structured-horizontal? t) 265 ($describe-item 266 ($inline ($shortcut (structured-insert-left)) ", " 267 ($menu "Focus" "Insert left") ", " 268 ($tmdoc-icon "tm_insert_left.xpm")) 269 "Insert a new argument on the left-hand side of the cursor.") 270 ($describe-item 271 ($inline ($shortcut (structured-insert-right)) ", " 272 ($menu "Focus" "Insert right") ", " 273 ($tmdoc-icon "tm_insert_right.xpm")) 274 "Insert a new argument on the right-hand side of the cursor.")) 275 ($when (structured-vertical? t) 276 ($describe-item 277 ($inline ($shortcut (structured-insert-up)) ", " 278 ($menu "Focus" "Insert above") ", " 279 ($tmdoc-icon "tm_insert_up.xpm")) 280 "Insert a new argument above the cursor.") 281 ($describe-item 282 ($inline ($shortcut (structured-insert-down)) ", " 283 ($menu "Focus" "Insert down") ", " 284 ($tmdoc-icon "tm_insert_down.xpm")) 285 "Insert a new argument below the cursor."))) 286 ($para 287 "Existing arguments can be removed as follows:") 288 ($description-long 289 ($when (structured-horizontal? t) 290 ($describe-item 291 ($inline ($shortcut (structured-remove-left)) ", " 292 ($menu "Focus" "Remove left") ", " 293 ($tmdoc-icon "tm_delete_left.xpm")) 294 "Remove the argument on the left-hand side of the cursor.") 295 ($describe-item 296 ($inline ($shortcut (structured-remove-right)) ", " 297 ($menu "Focus" "Remove right") ", " 298 ($tmdoc-icon "tm_delete_right.xpm")) 299 "Remove the current argument and move to the next one.")) 300 ($when (structured-vertical? t) 301 ($describe-item 302 ($inline ($menu "Focus" "Remove above") ", " 303 ($tmdoc-icon "tm_delete_up.xpm")) 304 "Remove the argument above the cursor.") 305 ($describe-item 306 ($inline ($menu "Focus" "Remove below") ", " 307 ($tmdoc-icon "tm_delete_down.xpm")) 308 "Remove the current argument and move to the one below."))))) 309 310;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 311;; Hidden arguments 312;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 313 314(tm-generate (focus-doc-hidden t) 315 ($let* ((lab (tree-label t)) 316 (l (focus-doc-arg-names t 0 '())) 317 (il (list-filter (.. 0 (length l)) 318 (lambda (i) (not (tree-accessible-child? t i))))) 319 (sl (map (lambda (i) (list-ref l i)) il))) 320 ($para 321 "When the " ($markup lab) " tag is " 322 ($tmdoc-link "main/text/keyboard/man-dynamic" "activated") ", " 323 "then the following arguments are hidden: " 324 ($src-arg (car sl)) 325 ($for (x (cdr sl)) ", " ($src-arg x)) ". " 326 "In order to edit the hidden arguments, you should use " 327 ($menu "Focus" "Show hidden") " or push the " 328 ($tmdoc-icon "tm_show_hidden.xpm") " icon on the focus toolbar. " 329 "Deactivated tags can be reactivated by pressing " 330 ($shortcut (kbd-return)) ".") 331 ($para 332 "Non internal hidden arguments which contain string values " 333 "can also be edited directly in the text fields on the focus toolbar; " 334 "no need to deactivate the " ($markup lab) " tag in this case."))) 335 336;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 337;; Change the geometry 338;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 339 340(tm-generate (focus-doc-geometry t) 341 "Not yet documented.") 342 343;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 344;; Default tag documentation 345;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 346 347(tm-define (focus-doc t) 348 ($tmdoc 349 ($tmdoc-title "Contextual help on the ``" 350 (symbol->string (tree-label t)) "'' tag") 351 ($when #t 352 ($unfolded-documentation "Usage" 353 (focus-doc-usage t))) 354 ($with tagdoc (tmdoc-search-tag (tree-label t)) 355 ($when tagdoc 356 ($unfolded-documentation "Description" 357 tagdoc))) 358 ($when (tree-label-extension? (tree-label t)) 359 ($unfolded-documentation "Current definition" 360 (focus-doc-source t))) 361 ($when (or (focus-has-variants? t) (focus-has-toggles? t)) 362 ($unfolded-documentation "Structured variants" 363 (focus-doc-toggles-variants t))) 364 ($when (focus-has-preferences? t) 365 ($unfolded-documentation "Style preferences" 366 (focus-doc-preferences t))) 367 ($when (focus-can-move? t) 368 ($unfolded-documentation "Structured navigation" 369 (focus-doc-move t))) 370 ($when (focus-can-insert-remove? t) 371 ($unfolded-documentation "Structured insert and delete" 372 (focus-doc-insert t))) 373 ($when (< (length (tree-accessible-children t)) 374 (length (tree-children t))) 375 ($unfolded-documentation "Hidden arguments" 376 (focus-doc-hidden t))) 377 ($when (focus-has-geometry? t) 378 ($unfolded-documentation "Structured geometry" 379 (focus-doc-geometry t))))) 380 381;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 382;; Lazy loading of further documentation 383;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 384 385(lazy-initialize (table table-doc) (table-markup-context? (focus-tree))) 386(lazy-initialize (generic document-doc) (tree-is-buffer? (focus-tree))) 387(lazy-initialize (dynamic session-doc) (in-session?)) 388 389;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 390;; Public interface 391;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; 392 393(tm-define (focus-help) 394 (lazy-initialize-force) 395 (cursor-history-add (cursor-path)) 396 (open-auxiliary "Contextual help" (focus-doc (focus-tree)))) 397