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