source: project/wiki/eggref/5/chicken-doc @ 37453

Last change on this file since 37453 was 37453, checked in by Jim Ursetto, 22 months ago

wiki/chicken-doc: -R chicken.platform for chicken-home on C5

Fixes #2 (https://github.com/ursetto/chicken-doc/issues/2)

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