source: project/wiki/eggref/4/chicken-doc @ 29556

Last change on this file since 29556 was 29556, checked in by Jim Ursetto, 6 years ago

chicken-doc: doc 0.4.6

File size: 18.0 KB
Line 
1[[tags: egg]]
2== chicken-doc
3
4chicken-doc is a tool for exploring Chicken documentation.
5[[toc:]]
6=== Overview
7
8chicken-doc provides facilities to explore Chicken documentation
9from the command-line and from the REPL.  It also provides an
10API to access this documentation from your own programs.
11
12You need to obtain Chicken documentation separately.  To generate a
13documentation database from a copy of the wiki, see the
14[[chicken-doc-admin]] egg.  You can also use a pre-built
15documentation package, described below.
16
17=== Documentation repository
18
19The documentation database is located, by default, under
20{{(chicken-home)}} in the {{chicken-doc/}} directory.  If you have
21installed it in a different location, set the
22{{CHICKEN_DOC_REPOSITORY}} enviroment variable:
23
24 export CHICKEN_DOC_REPOSITORY=/path/to/repository
25
26==== Pre-built packages
27
28Documentation tarballs are provided in
29[[http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz|gzip]],
30[[http://3e8.org/pub/chicken-doc/chicken-doc-repo.tar.bz2|bzip2]] and
31[[http://3e8.org/pub/chicken-doc/chicken-doc-repo.zip|zip]] format at
32[[http://3e8.org/pub/chicken-doc/]].  They are updated daily from
33the latest wiki documentation.
34
35Download your preferred format and extract it into the default
36location {{(chicken-home)}} or into some other writable directory of your
37choice.  For example, on UNIX:
38
39 $ cd `csi -p '(chicken-home)'`
40 $ curl http://3e8.org/pub/chicken-doc/chicken-doc-repo.tgz | sudo tar zx
41
42The tarball will be extracted into the directory {{chicken-doc/}}.
43If you installed into a non-default location, {{CHICKEN_DOC_REPOSITORY}}
44must include this entire path.
45
46===== Cleaning up old repository crust
47
48Occasionally, or when the repository format changes significantly, you
49should wipe out your repository before extracting a new one, to get
50rid of dead wood.  Simply delete the directory shown by the
51following command:
52
53 $ csi -R chicken-doc -p "(locate-repository)"
54 /usr/local/share/chicken/chicken-doc
55
56If you have chicken-doc-admin installed, just do instead:
57
58 $ chicken-doc-admin -D
59
60==== Structure
61
62The documentation is arranged in a tree structure, where each node may
63contain descriptive text, a signature, and other nodes.  Nodes may be
64searched for by name or specified by an absolute path through the
65tree, and you may request the text, signature or table of contents
66(children) for any node.
67
68With the standard documentation install, each unit (posix, lolevel)
69and egg (9p, base64) is assigned a toplevel node whose text contains
70that unit or egg's full documentation.  The identifiers in each become
71these nodes' children, and contain the signature and descriptive text
72just for that identifier.  Core bindings in the {{chicken}} module
73are similar, but because they are divided into several manual
74pages, each page is placed in a separate node under the toplevel
75node {{chicken}}.
76
77So in general, if you know the full path of an identifier, you can
78pull it into your program with (use NODE) or (import NODE) where
79NODE is the name of the toplevel node.  For example,
80
81  and-let* -> (chicken macros and-let*) -> (import chicken)
82  find-files -> (posix find-files) -> (use posix)
83
84Here's an abbreviated example of the tree structure:
85
86 |- 9p +- alloc-handle
87 |     |- call-with-input-file
88 |     |- call-with-output-file
89 |
90 |- base64 +- base64-decode
91 |         |- base64-encode
92 |
93 |- chicken +- macros +- and-let*
94 |          |         |- assert
95 |          |
96 |          |- parameters -- make-parameter
97 |
98 |- posix +- find-files
99 |        |- glob
100 |        |- open/rdonly
101 |
102
103
104=== From the command-line
105
106 chicken-doc -s|-c|-i path
107 chicken-doc -f node
108 chicken-doc node | path
109 
110 -s path        Show signature
111 -c path        Show table of contents (children)
112 -i path        Show documentation
113 -f node        Show all matching paths for node
114
115where NODE is a single identifier and PATH is one or
116more node names comprising a path from the documentation root,
117separated by spaces.
118
119 -m re          Show all matching paths for RE
120
121where RE is a POSIX regular expression.  Similar to -f.
122
123When no option is given, guess the user's intent.  With
124a single node name, find the node (as with -f) and show its
125documentation (as with -i) or show all matching paths
126if multiple matches exist.  If more than one node is
127provided, show documentation on the path (as if called
128with -i).
129
130==== Pager
131
132When output is sent to a terminal, {{chicken-doc}} pipes its output to
133the pager of your choice.  It looks for a pager in the following
134places:
135
136* the CHICKEN_DOC_PAGER environment variable
137* the PAGER environment variable
138* the default pager, which is {{less}} on UNIX and {{more}} on Windows
139
140If an environment variable is set but empty, for example:
141
142 export CHICKEN_DOC_PAGER=
143
144then the output is not paginated.  Windows does not distinguish
145between an empty and unset variable, so you can use the special
146value {{cat}} instead:
147
148 set CHICKEN_DOC_PAGER=cat
149
150==== Text wrapping
151
152{{chicken-doc}} will wrap its output text nicely if it can determine how
153wide your terminal is.  If it can't (e.g. on Windows) it will wrap at
15476 columns.  If you wish to fix the wrap column to, say, 120:
155
156 export CHICKEN_DOC_WRAP=120
157
158or to disable wrapping, which won't look very good:
159
160 export CHICKEN_DOC_WRAP=0
161
162==== Colorization
163
164Alpha-quality feature added in 0.4.3, adding ANSI bold and underline
165support rather than the usual ASCII chars.  The attributes cannot
166currently be configured beyond enabling and disabling colorization.
167
168To enable:
169
170 export CHICKEN_DOC_COLORS=auto
171
172Colorization will then be enabled when output is directed to a
173terminal and your TERM variable is set (to anything other than
174"dumb").  Using {{chicken-doc}}'s pager facility counts as
175a terminal; we assume your pager supports ANSI escape sequences,
176as in {{less -R}}.
177
178==== Examples
179
180Show matches for identifier {{file-open}}, which occurs in
181Unit posix and in the 9p egg:
182
183 $ chicken-doc -f file-open
184 (9p file-open)        (file-open connection path mode)
185 (posix file-open)     (file-open FILENAME FLAGS [MODE])
186
187Show signature of {{open/rdonly}} in Unit posix:
188
189 $ chicken-doc -s posix open/rdonly
190 (posix open/rdonly)     open/rdonly
191
192Show documentation for {{file-open}} in the 9p egg:
193
194 $ chicken-doc -i 9p open/rdonly
195 procedure: (file-open connection path mode)
196 
197 Opens the file indicated by `path` on the `connection` with the given
198 `mode` and returns an opaque handle object which you can use for the [...]
199
200Show table of contents (identifiers) in Unit posix:
201
202 $ chicken-doc -c posix
203  [...]
204 get-host-name        (get-host-name)
205 glob                 (glob PATTERN1 ...)
206 group-information    (group-information GROUP)
207  [...]
208
209Show identifiers containing call-:
210
211 $ chicken-doc -m call-
212 (scheme call-with-values)      (call-with-values producer consumer)
213 (xml-rpc call-xml-rpc-proc)    (call-xml-rpc-proc call-sxml procedures)
214 (library get-call-chain)       (get-call-chain [START [THREAD]])
215 [...]
216
217Show identifiers ending in -file:
218
219 $ chicken-doc -m -file$
220 (spiffy access-file)           (access-file [string])
221 (scheme call-with-input-file)  (call-with-input-file string proc)
222 (scheme call-with-output-file) (call-with-output-file string proc)
223 [...]
224
225Show `with-...-port` identifiers:
226
227 $ chicken-doc -m with-.+-port
228 (ports with-error-output-to-port)  (with-error-output-to-port PORT THUNK)
229 (ports with-input-from-port)       (with-input-from-port PORT THUNK)
230 (ports with-output-to-port)        (with-output-to-port PORT THUNK)
231
232Show documentation for {{use}} in chicken core:
233
234 $ chicken-doc use
235 path: (chicken macros use)
236 macro: (use ID ...)
237 
238 `use` is just a shorter alias for `require-extension`.
239
240Show full documentation for Unit posix:
241
242 $ chicken-doc posix
243
244Show matches for {{open/rdonly}}, as with -f:
245
246 $ chicken-doc open/rdonly
247
248Show documentation for {{open/rdonly}} in Unit posix:
249
250 $ chicken-doc posix open/rdonly
251
252
253=== From the REPL
254
255To load {{chicken-doc}} for REPL use:
256
257 (require-library chicken-doc)
258
259The following {{csi}} commands then become available:
260
261 ,doc node
262 ,doc (node ...)
263
264Show documentation for the identifier {{node}} or the absolute
265path {{(node ...)}}.  If a single {{node}} is given, a search
266is performed across all identifiers, and documentation will
267be shown if the node is unique --- otherwise, the matches
268are listed.
269
270 ,toc node
271 ,toc (node ...)
272
273Show a table of contents for the identifier {{node}} or the path
274{{(node ...)}}.  As with {{,doc}}, a search will be performed
275if a single {{node}} is given.
276
277 ,wtf regex
278
279The "where to find" command.  Search identifiers using POSIX
280regular expression {{regex}} (like the -m command-line option)
281and display the matches.
282
283==== Examples
284
285Search for identifier {{define-foreign-type}} and display its
286documentation.
287
288 #;> ,doc define-foreign-type
289 path: (foreign access define-foreign-type)
290 macro: (define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])
291 
292 Defines an alias for `TYPE` with the name `NAME` (a symbol).
293 `TYPE` may be a type-specifier or a string naming a C type. The
294 [...]
295
296Search for identifier {{file-open}} and (as multiple matches
297occur) display the matches:
298
299 #;> ,doc file-open
300 Found 2 matches:
301 (9p file-open)        (file-open connection path mode)
302 (posix file-open)     (file-open FILENAME FLAGS [MODE])
303
304Display TOC for absolute path {{(chicken macros)}}.  This should list
305all the core chicken macros from [[Non-standard macros and special forms]].
306
307 #;> ,toc (chicken macros)
308 and-let*              (and-let* (BINDING ...) EXP1 EXP2 ...)
309 assert                (assert EXP [STRING ARG ...])
310 begin-for-syntax      (begin-for-syntax EXP ...)
311 [...]
312
313==== Emacs
314
315This elisp snippet will look up the word at point and display its
316documentation (or matches) in your *scheme* window and display it in a
317split window unless it is already visible.
318
319<enscript highlight="elisp">
320(defun chicken-doc (&optional obtain-function)
321  (interactive)
322  (let ((func (funcall (or obtain-function 'current-word))))
323    (when func
324      (process-send-string (scheme-proc)
325                           (format "(require-library chicken-doc) ,doc %S\n" func))
326      (save-selected-window
327        (select-window (display-buffer (get-buffer scheme-buffer) t))
328        (goto-char (point-max))))))
329 
330(eval-after-load 'cmuscheme
331 '(define-key scheme-mode-map "\C-cd" 'chicken-doc))
332</enscript>
333
334Additionally, because multiple matches may be listed, this snippet
335will allow you to place your cursor at the beginning of the match
336s-expression and get the actual documentation:
337
338<enscript highlight="elisp">
339(eval-after-load 'cmuscheme
340 '(define-key inferior-scheme-mode-map "\C-cd"
341    (lambda () (interactive) (chicken-doc 'sexp-at-point))))
342</enscript>
343
344=== API
345
346==== Configuration
347
348<parameter>wrap-column [default: 76]</parameter>
349
350Wrap column for text output.  0 or {{#f}} for no wrapping.
351
352<parameter>chicken-doc-warnings [default: #f]</parameter>
353
354For debugging.  Controls emission of warnings from the text renderer.
355
356When using the command-line tool, you can set the environment variable
357{{CHICKEN_DOC_WARNINGS}} to any value to enable warnings.
358
359==== Repository
360
361<procedure>(verify-repository)</procedure>
362
363Open the repository found in the standard location with {{(locate-repository)}}
364and set the {{(current-repository)}} for the thread.
365Throws an error if the open fails.
366
367This is the standard way to open the chicken-doc repository,
368because the node lookup procedures require {{(current-repository)}} to be set.
369
370<procedure>(open-repository base)</procedure>
371
372Open repository at pathname ''base'' and return a new repository object or
373throw an error if nonexistent or unknown format.
374
375Generally, you will want to use {{verify-repository}} to open
376the repository instead.
377
378<procedure>(close-repository r)</procedure>
379
380Close repository object ''r''.
381
382<parameter>current-repository</parameter>
383
384The current repository; used by the node lookup API.  It is usually set by calling
385{{verify-repository}}.
386
387<procedure>(locate-repository)</procedure>
388
389Return the standard location of the repository, according to
390the rules described in [[#Documentation repository]].  Does not
391check if the repository actually exists.
392
393==== Node lookup
394
395<procedure>(lookup-node path)</procedure>
396
397Return node record at ''path'', or throw an error if the record does
398not exist.  ''path'' is a list of string or symbols which identify
399the node; for example {{'(posix open/rdonly)}}.
400
401<procedure>(match-nodes idre #!optional (limit #f))</procedure>
402
403Return a list of node records whose identifiers match ''idre'', which
404may be an identifier symbol, identifier string or a regular expression
405object.  ''limit'' is an optional integer limit on
406the number of nodes returned, or {{#f}} for no limit.
407
408<procedure>(match-node-paths/re re #!optional (limit #f))</procedure>
409
410Return a list of node records whose full paths match ''re'', a regular
411expression string or object.  ''re'' matches against the string
412representation of the node path, which is composed of each node id
413joined with spaces.  For example, {{'(chicken foreign access)}}
414becomes {{"chicken foreign access"}}.
415
416''limit'' is an optional integer limit on
417the number of nodes returned, or {{#f}} for no limit.
418
419<procedure>(match-ids/prefix str #!optional (limit #f))</procedure>
420
421Return a list of node records whose identifiers match the string
422prefix ''str''.  ''limit'' is an optional integer limit on
423the number of records returned, or {{#f}} for no limit.
424
425<procedure>(match-paths/prefix str #!optional (limit #f))</procedure>
426
427Return a list of node records whose full paths match the string prefix
428''str''.  This matches against the string representation of the node
429path, which is composed of each node id joined with spaces.  For
430example, {{'(chicken foreign access)}} becomes {{"chicken foreign
431access"}}.  ''limit'' is an optional integer limit on
432the number of records returned, or {{#f}} for no limit.
433
434==== Node description
435
436The command-line utility is a thin wrapper around these procedures,
437which print descriptive information to {{current-output-port}}.
438
439<procedure>(describe node)</procedure>
440
441Formats and displays the text contents of ''node''.  An error
442is thrown if no textual content is available.
443
444<procedure>(describe-contents node)</procedure>
445
446Displays the names and signatures of all child nodes
447of ''node''.
448
449<procedure>(describe-signatures nodes)</procedure>
450
451Displays the signatures of all nodes in the list ''nodes''.
452
453<procedure>(doc-dwim pathspec)</procedure>
454
455This "do-what-I-mean" procedure is used by the command line when
456no options are provided.
457
458If ''pathspec'' is a list, it is treated as a node
459path and the node at that path is looked up and described.
460
461If it is a string or symbol, it is decomposed into a list of node
462identifiers by splitting at each {{#}}.  If this results in one
463identifier, it is matched against and the node is described (if
464exactly one match) or all matched paths are displayed.  Otherwise, the
465identifier list is treated as a node path and the node at that path is
466described.
467
468<procedure>(search-only idre)</procedure>
469
470Search for all nodes matching the identifier or regular expression
471''idre'', and print a description of their signatures.  Equivalent to
472
473 (describe-signatures (match-nodes idre))
474
475==== Node information
476
477<record>chicken-doc-node</record>
478
479The ''chicken-doc-node'' record represents an individual repository node,
480such as {{'(posix)}} or {{'(posix open/rdonly)}}.
481
482<procedure>(node-signature node)</procedure>
483
484Return the signature of ''node'' as a string.  The signature is a node's short
485identifying description.  For example, it may be a procedure signature,
486an identifier or the name of a manual page.
487
488<procedure>(node-type node)</procedure>
489
490Return a symbol representing the type of ''node''.  The currently
491defined node types are: ''egg'' (egg documentation), ''unit'' (manual
492page), ''procedure'', ''parameter'', ''syntax'', ''constant'',
493''read'' (read syntax), ''record'', ''setter'', ''class'', and
494''method''.
495
496Returns {{'unknown}} if type information is not available for some
497reason; however, the current repository backend always provides
498type information.
499
500<procedure>(node-sxml node)</procedure>
501
502Return the sxml contents of ''node'' (as a pair).
503
504<procedure>(node-path node)</procedure>
505
506Return the full node path of ''node'' as a list of identifiers.
507Each returned identifier may be a symbol or a string (this may be
508tightened up in the future).
509
510<procedure>(node-id node)</procedure>
511
512Return the node id of ''node'', which is the last component in
513the full path.  The return value may be a symbol or a string
514(this may be tightened up in the future).
515
516<procedure>(node-timestamp node)</procedure>
517
518Return the timestamp of a node in seconds since the UNIX epoch, or
519{{#f}} if no timestamp is available.  In general, the timestamp is
520that of the source document used to generate this node.
521
522<procedure>(node-children node)</procedure>
523
524Return the children of ''node'' as a list of node records.
525
526<procedure>(node-child node id)</procedure>
527
528Return the child of node record ''node'' having identifier ''id'', as a node record.
529''id'' is a symbol or string.
530
531<procedure>(node-child-ids node)</procedure>
532
533Return a list of identifiers (symbols or strings) of the children of
534''node''.  Semantically equivalent to {{(map node-id (node-children node))}},
535but may be significantly less expensive than calling {{node-children}}.
536
537<procedure>(node-definition-ids node)</procedure>
538
539''Experimental''.  Returns a list of identifiers for the definition children of ''node''.
540This is a subset of the identifiers returned by {{node-children}}.
541
542<procedure>(node-definition-id? node id)</procedure>
543
544''Experimental''.  Returns {{#t}} if ''id'' is a definition child of ''node''.
545
546=== About this egg
547
548==== Author
549
550Jim Ursetto
551
552==== Version history
553
554; 0.4.6 : Fix for letrec behavior change in 4.8.3
555; 0.4.5 : Use pre-post-order* to avoid apply limit
556; 0.4.4 : Add limit option to node matching API
557; 0.4.3 : Experimental ANSI bold/underline support; improve int-link display
558; 0.4.2 : Decrease pre and highlight indent from 4 to 2; depend on regex egg
559; 0.4.1 : Improve DL rendering; add {{chicken-doc-warnings}}
560; 0.4.0 : Repository version 3
561; 0.3.2 : POSIX regular expression search
562; 0.3.0 : SXML database, formatting improvements
563; 0.2.0 : Pagination
564; 0.1.1 : Initial release
565
566==== License
567
568BSD
Note: See TracBrowser for help on using the repository browser.