summaryrefslogtreecommitdiff
path: root/support/ultratex/texi/light.texi
blob: c50859c242ecb1f6168980799a2f3c2b0f34a504 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
\input texinfo   @c -*-texinfo-*-
@setfilename light.info
@settitle Lightning Completion Manual
@c footnotestyle separate
@c paragraphindent 2
@iftex
@tolerance 10000
@end iftex

@comment  use 'perl texi2html -menu -split_chapter light.texi' to get an
@comment  html file

@ifinfo
This is edition 0.50, December 1998, of the @cite{Lightning completion
Manual}.  Copyright @copyright{} 1996, 1997, 1998 John H. Palmieri
@end ifinfo

@titlepage
@title{Lightning Completion Manual}

@author (info by John H. Palmieri)

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1996, 1997, 1998 John H. Palmieri

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``Copying'' is included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end titlepage
@page

@ifinfo
@node top, Overview, (dir), (dir)
@comment node-name, next,          previous, up
@top Lightning Completion
@end ifinfo

The Lightning Completion package was written in emacs lisp by Mark
Haiman and Nick Reingold, with modifications by John Palmieri.

This is version 0.50, December 1998, of the Lightning completion
manual.  Bug reports and suggestions for new features should go to
@samp{palmieri@@member.ams.org}.

This is a revised version of this manual; it is done.

@menu
* Overview::                    Overview of lightning completion
* Completion functions::        Functions incorporating lightning completion
* Key bindings::                Which keys do what in lightning completion mode
* Lightning completion::        Adding lightning completion to other functions
* Installation and customization::  How to install
* Miscellany::                  Miscellany
* Function Index::              Function index
* Concept Index::               Concept index

@detailmenu
 --- The Detailed Node Listing ---

Lightning completion

* Enabling automatic lightning completion::
* Settings for lightning completion::  Disabling lightning completion
                                       in certain circumstances

Installation and customization

* Customizable options::        A list of customizable options

Miscellany

* Ignoring some files::         Don't to complete on certain file names
* Buffer completion::           An application of lightning completion
* HTML mode completion::        Another example

@end detailmenu
@end menu

@comment in any given node: 
@comment use '@cindex CONCEPT' to add node to concept index
@comment use '@findex FUNCTION' for function index
@comment use '@vindex VARIABLE' for variable index
@comment use '@kindex KEY' for key index

@comment ---------------------------------------------------------

@node Overview, Completion functions, top, top
@chapter Overview

As you are probably aware, Emacs does various sorts of completion, if
you ask it to.  For instance, if you hit @kbd{C-x C-f} to find a file,
then (once you are in the minibuffer) if you hit the @key{TAB} key, Emacs
completes the file name if there is a unique completion.  Lightning
completion offers an improvement to this, an improvement in several
ways:

@itemize @bullet
@item
Once lightning completion is initiated, it remains active until a
completion is found, or until turned off.  If I have three files,
@file{alphabet}, @file{alpo}, and @file{bozo}, and I initiate completion
on file names, if I hit @kbd{a}, then @samp{alp} is inserted; hitting
@kbd{h} would then produce @samp{alphabet}, and hitting @kbd{o} would
produce @samp{alpo}.  Similarly, hitting @kbd{b} at the start, instead
of @kbd{a}, would have produced @samp{bozo}.  This sort of completion,
in which completion is always on---you don't have to keep hitting the
@key{SPC} or @key{TAB} key to complete---is called ``dynamic''
completion.
@refill

@item
Lightning completion takes effect only if Emacs is idle for a length of
time specified by the variable @code{lc-complete-idle-time-default}, the
default value of which is 0.5 seconds.  So in the above example, you can
type "alph" or "alpha" or "alphab"; then if you wait for half a second,
Emacs will automatically complete it for you.  This is a new feature of
lightning completion; if you are used to the old version, you can set
this delay to be 0.  If you are a slow typist and you don't want Emacs
completing unless you take a very deliberate pause, you can set it to
something like 2.
@refill

@item
Lightning completion can be initiated anywhere, not just in the
minibuffer.  If I'm writing email to someone, and I want to include the
path name for some file, I type the first few letters of the path, then
run the function @code{completing-insert-file-name}, and I'm in
lightning completion mode.  There are similar function calls for
completion on buffer names, lisp objects, lisp functions, lisp
variables, and the contents of the kill ring.
@refill
@end itemize

Some remarks:
@enumerate
@item
Dynamic completion, like any completion, has a nice side-effect: you can
use long (and hence descriptive) file names, variable names, function
names, whatever, because you hardly ever have to type the whole thing
in.  So I don't mind that my directory structure in my account is deep
and the directories have long names---I can find the file
@file{~/tex/work/papers/hovey-strickland/axiomatic.tex} with 6
keystrokes: one each for ``t'', ``w'', ``p'', ``h'', and ``a'', and then
@key{RET}. (One also gets in the habit of trying to arrange it so that
each of one's files in any given directory starts with a different
letter.)
@refill

@item
If you mainly use lightning completion with file names and if you edit
the same files over and over again, you will quickly learn exactly which
characters you have to type to find each file.  In this case, you might
want to set @code{lc-complete-idle-time-default} to be close to zero.
If you don't want to bother learning this, and if you are worried that
lightning completion will make you watch the screen all the time to see
what has been completed and what hasn't, then you should set
@code{lc-complete-idle-time-default} to be a larger number, so that
completions only occur after a good pause.

@item
Lightning completion is also one of the main ingredients to
Ultra-@TeX{} mode, a major mode for typing @TeX{} documents.  Most
@TeX{} commands start with a backslash, so in that mode, hitting ``\''
starts lightning completion on @TeX{} commands.
@refill

@item
This package should be compatible with GNU Emacs 19, GNU Emacs 20, and
XEmacs (''should be compatible'' means that I've at least tried it out a
bit with each one of these, without running into problems).  I mostly
use GNU Emacs 20, so I know it works there.  I expect it to work pretty
well with XEmacs, too, but I don't use GNU Emacs 19 anymore, and I don't
test this package very vigorously there.
@refill

@item
Dynamic completion is an acquired taste.  It can be rather off-putting
at the start, especially with a short
@code{lc-complete-idle-time-default}, but once you get used to it, it's
just wonderful.
@refill
@end enumerate

In the following sections, I describe what functions to call to start
lightning completion, which keys do what once completion is engaged, how
to automate things a bit (e.g., so that @code{find-file} automatically
uses lightning completion on file names), and how to install all of
this.



@comment ---------------------------------------------------------

@node Completion functions, Key bindings, Overview, top
@chapter Completion functions

@findex completing-insert-file-name
@findex completing-insert-buffer-name
@findex completing-insert-lisp-object
@findex completing-insert-lisp-function
@findex completing-insert-kill
@findex completing-insert-buffer-contents
@findex completing-insert-according-to-mode
@cindex Completion functions
@cindex Lightning completion functions
@cindex Functions for completion
@cindex C-x c is completion
@cindex C-\ completes a la mode

The file @file{light.el} defines several functions that do lightning
completion:

@itemize @bullet
@item
@code{completing-insert-file-name} completes on file names.
@item
@code{completing-insert-buffer-name} completes on buffer names.
@item
@code{completing-insert-lisp-object} completes on lisp objects. 
@item
@code{completing-insert-lisp-function} completes on lisp functions. 
@item
@code{completing-insert-lisp-variable} completes on lisp variables. 
@item
@code{completing-insert-kill} completes on the contents of the kill
ring. 
@item
@code{completing-insert-buffer-contents} completes on the contents of
the current buffer, or with a prefix argument on the contents of any
specified buffer.  @xref{Buffer completion}.
@item
@code{completing-insert-according-to-mode} makes a guess as to
what sort of completion it should do; if it can't figure it out, it
completes on lisp objects.  (This one is mainly useful in the
minibuffer.)
@refill
@end itemize

(These functions all call the function @code{completing-insert}, which
I'm too lazy to document.  The casual user won't want to call it
directly, anyway, and the more serious user can figure it out for
herself.)

For example, if I'm typing an info page for lightning completion, and I
want to insert the string @samp{completing-insert-kill}, I run
@code{completing-insert-lisp-function}, and then use lightning
completion to produce the function name, avoiding typing the
whole thing in (and also avoiding typos).  In detail: once I start 
@code{completing-insert-lisp-function}, the following happens:

@itemize @bullet
@item
I type the letters @kbd{c}, @kbd{o}, @kbd{m}, @kbd{p}, and
Emacs inserts @samp{comp}.
@item
I type @kbd{l} and pause, and Emacs inserts @samp{let} (so I have
@samp{complet} so far). 
@item
I type @kbd{i} and @kbd{n} and pause, and Emacs inserts @samp{ing-} (so
I have @samp{completing-} so far). 
@item
I type @kbd{i} and pause, and Emacs inserts @samp{insert} (so I have
@samp{completing-insert} so far). 
@item
I type @kbd{-} and pause, and Emacs inserts @samp{-} (so I have
@samp{completing-insert-} so far).
@item
I type @kbd{k} and pause, and Emacs inserts @samp{kill} (so I have
@samp{completing-insert-kill}, and completion stops).
@end itemize

There are user customizable variables (in the customization group
"lightning-completion") related to these functions.  If the variable
@code{lc-ctrl-x-c-is-completion} is non-nil, then @kbd{C-x c} is the
prefix key for these commands.  This is one of the few global key
bindings available, probably because it is too close to @kbd{C-x C-c}.
So be warned, if you use these key bindings, you may occasionally hit
@kbd{C-x C-c} instead of @kbd{C-x c}.  Anyway, enabling this options
provides the following key bindings:

@table @kbd
@item C-x c F
runs @code{completing-insert-file-name}.

@item C-x c b
runs @code{completing-insert-buffer-name}.

@item C-x c o
runs @code{completing-insert-lisp-object}.

@item C-x c f
runs @code{completing-insert-lisp-function}.

@item C-x c v
runs @code{completing-insert-lisp-variable}.

@item C-x c k
runs @code{completing-insert-kill}.

@item C-x c y
runs @code{completing-insert-buffer-contents}.

@item C-x c u
runs @code{completing-insert-according-to-mode}.

@end table

Note that if one plans on using lightning completion only occasionally,
and always from the minibuffer, one might be able to get away with only
using the function @code{completing-insert-according-to-mode}.  There is
a customizable variable @code{lc-ctrl-backslash-completes-a-la-mode}.
If it is non-nil, then @kbd{C-\} runs
@code{completing-insert-according-to-mode}.







@comment ---------------------------------------------------------

@node Key bindings, Lightning completion, Completion functions, top
@chapter Key bindings

@cindex Keys in completion
@cindex Key bindings
@cindex Light mode keys

While in lightning completion, the behavior of each key is modified.
Here is a description of what each key does; these functions are loosely
based on the behavior of standard completion in Emacs.  I have also
included examples; for all of the examples, suppose that you are
completing on file names, and you have files @file{albatross},
@file{alpo}, @file{alphabet}, and @file{alphabet-soup}.

There is a customizable variable @code{lc-complete-idle-time-default},
the default value of which is 0.5.  In lightning completion mode, after
this number of seconds of idle time, Emacs tries to complete.

@itemize @bullet
@item
@kbd{a-z, A-Z, 0-9}, etc.: After the delay, you get an error if there is
no valid completion based on that character.  If there are valid
completions, then Emacs inserts the characters in common with all the
valid completions.  If there is a unique such completion, then Emacs
inserts that completion, and completion stops.  (Example: if you have
@samp{alp} and you hit @kbd{x}, you get an error
(but you're still in lightning completion mode); if you hit @kbd{h},
then @samp{habet} is inserted, resulting in @samp{alphabet} (and you're
still in lightning completion mode).  If you then hit @kbd{-}, then
@samp{-soup} is inserted, and completion stops.)

When there are no valid completions, the value of the customizable
variable @code{lc-clean-up} is relevant.  If it is nil, then Emacs beeps
and warns you that there are no valid completions.  If it is non-nil,
then in addition, Emacs deletes the offending characters.  (Example: if
you have @samp{alp} and you hit @kbd{x}, then @samp{x} is inserted.  If
@code{lc-clean-up} is nil, then Emacs beeps.  If @code{lc-clean-up} is
non-nil, then Emacs beeps and deletes the @samp{x}.  If you have
@samp{al} and you type @kbd{phx}, if @code{lc-clean-up} is non-nil, then
the @samp{x} is deleted and @samp{abet} is inserted.)

@item
@key{SPC}: If you have a valid completion, this key ends lightning
completion, keeping the current completion; otherwise, if there is a
valid completion based on the current string together with " ", then a
space is inserted.  Otherwise, @key{SPC} acts like the @key{TAB} key.
(Example: if you have @samp{alp} and you hit @kbd{h}, resulting in
@samp{alphabet}, then hitting @key{SPC} would end completion and do
nothing else.  If you also have a file @file{al jolson}, then
typing @samp{al} followed by @key{SPC} produces @samp{al jolson}.
Typing @samp{alp} followed by @key{SPC} is just like typing @samp{alp}
and hitting @key{TAB}.)

@item
@key{RET}: This key exits lightning completion, regardless of whether
you have a valid completion, and inserts a new line or exits the
minibuffer, whichever is appropriate.  (Example: if you have @samp{alp}
and you hit @key{RET} would end completion and either insert a new line
or exit the minibuffer.)  (This is actually an example of the behavior
of ``Other control characters,'' described below.)

@item
@key{DEL}: This deletes the last thing that was typed along with
anything inserted automatically as a result.  (Example: if you had
@samp{alp} and you hit @kbd{h}, resulting in @samp{alphabet}, then
hitting @key{DEL} would delete @samp{habet}---the characters that were
just inserted.)

@item
@kbd{C-f}: Hitting this key repeatedly cycles through the possible
completions, in some order or other.  (Example: if you have @samp{a},
then hitting @kbd{C-f} once will give @samp{albatross}; hitting it again
will give @samp{alpo}, etc.)

@item
@kbd{C-b}: This works like @kbd{C-f}, but it cycles through the choices
in the reverse order.

@item
@key{TAB}: Hitting this key completes as far as possible.  If there are
several choices, then it opens up a new buffer in another window,
called @code{*Completions*}, in which all of the valid completions are
displayed.  That buffer is buried once completion ends.  (Example, if I
have @samp{alp} and I hit @key{TAB}, then a new buffer opens up,
containing @samp{alpo}, @samp{alphabet}, and @samp{alphabet-soup}.  If I
then hit @kbd{h} and then @key{TAB}, the @code{*Completions*} buffer
then displays @samp{alphabet} and @samp{alphabet-soup}.)  You can select
a completion by clicking on it with @kbd{mouse-2}.

@item
@kbd{M-v}: Hitting this key opens up a new buffer in another window,
called @code{*Completions*}, just as with the @key{TAB} key, but also
moves the point to that window.  You can then move from one completion
choice to another with the arrow keys, and you can select a completion
with @key{RET} or with @kbd{mouse-2}.

@item
@kbd{C-c}: Hitting this key exits lightning completion mode (useful if
you've had enough of this completion nonsense, and you just want to type
in the file name yourself; also useful if you want to type in the name
of a file that doesn't exist).

@item
@kbd{C-q}: This key quotes the next character (useful if you have a file
name containing a control character like @kbd{C-c} or @key{TAB}, for
instance).

@item
@kbd{C-h}: Hitting this key displays a very brief help message in the
minibuffer. 

@item
Other control characters: Hitting any other control character (or other
non-printing character) has two effects: completion stops, and that
character then has its normal effect.  So @kbd{C-g} stops completion and
beeps, @kbd{C-e} stops completion and moves you to the end of the line,
etc.
@end itemize

Many of these keys can be customized (in the customization group
@code{lightning-completion-keys}).






@comment ---------------------------------------------------------

@node Lightning completion, Installation and customization, Key bindings, top
@chapter Lightning completion

Suppose you want to find a file, and you want to use lightning
completion on file names.  One way to accomplish this is to run
@code{find-file} (by hitting @kbd{C-x C-f}, say), then once in the
minibuffer, either running @code{completing-insert-according-to-mode} or
@code{completing-insert-file-name} (by hitting @kbd{C-x c F}, say, if
you have turned on the option @code{lc-ctrl-x-c-is-completion}
(@pxref{Completion functions})).

Another way to accomplish this is to have lightning completion
potentially active whenever you enter the minibuffer, and to specify
when "potentially active" should mean "active".

@menu
* Enabling automatic lightning completion::
* Settings for lightning completion::  Disabling lightning completion
                                       in certain circumstances
@end menu

@comment ---------------------------------------------------------

@comment  node-name,  next,  previous,  up
@node Enabling automatic lightning completion, Settings for lightning completion, , Lightning completion 
@section Enabling automatic lightning completion

@cindex Enabling lightning completion
@cindex Toggling lightning completion
@cindex Contexts for lightning completion
@cindex Situations for lightning completion
@cindex Lightning completion--enabling
@cindex Lightning completion--contexts
@findex lightnify

To use lightning completion automatically in the minibuffer (in
various circumstances), you should turn on the option 
@code{toggle-lightning-completion}, either by customization or by
setting the variable @code{toggle-lightning-completion} to t.
Once you've done this, then the variable
@code{lightning-completion-list} specifies in which contexts lightning
completion should be active; the possible contexts 
are:
@table @code
@item file names

@item commands

@item lisp functions

@item lisp variables

@item lisp objects

@item user variables

@item buffer names

@item info menu items

@item query-replace
Enable lightning completion on buffer contents when using
@code{query-replace}.  This may not work very well, but I'm working on
it...

@item miscellaneous
Enable lightning completion on everything else.

@end table

The easiest way to specify which contexts you want to enable is to
customize the variable @code{lightning-completion-list} (in the
customization group @code{lightning-completion}).  For each context, you
can turn lightning completion on (with the default delay time) or off,
or you can also specify a number.  If the number is negative, lightning
completion is off; otherwise, lightning completion is on, with that
number for the delay time for that context.  (You can instead use the
@code{lightnify} function to turn completion on or off, if you prefer.
This function is a bit obsolete; in particular, it does not allow you to
set a different delay time for each context.)

I suppose I should explain the effect of the "miscellaneous" context.
Basically, if in some situation you can complete in the minibuffer by
hitting the @key{TAB} key, then enabling miscellaneous completion
means that lightning completion will be on in that situation.  For
example, in the news-reader Gnus, if you hit @kbd{j} (to run
@code{gnus-group-jump-to-group}), then you will be thrown into lightning
completion mode, completing on newsgroup names (you will see the message
``Completing something...'').



@comment ---------------------------------------------------------

@comment  node-name,  next,  previous,  up
@node Settings for lightning completion, , Enabling automatic lightning completion, Lightning completion
@section Settings for lightning completion

@cindex Recursive minibuffers
@cindex Lightning completion and recursive minibuffers
@cindex Disabling lightning completion for particular commands
@cindex lc-dark-commands

Lightning completion doesn't always work the way you want it, so there
are some ways of partially disabling it.

For example, lightning completion doesn't work terribly well with
recursive minibuffers, so there is a customizable variable
@code{lc-dark-recursive-minibufs}.  If this is nil, then lightning
completion proceeds unhindered.  If this has a numerical value @var{N},
then lightning completion is disabled when the recursion depth is larger
than @var{N}.  If this has some other non-nil value, then it is treated
as if it had value 1 (disabling lightning completion in any recursive
situation).

You might also want to, say, enable lightning completion on file names,
but disable it for particular commands.  To do this, customize the
variable @code{lc-dark-commands}, which is a list of functions.  For
example, if you want to disable lightning completion when using
@code{insert-file}, then add @code{insert-file} to this list.
If you want two versions of a command like @code{insert-file}, only one
of which uses lightning completion, then make an alias to
@code{insert-file}, and disable lightning completion on that function: 

@example
(defalias 'insert-file-dark 'insert-file)
@end example

@noindent
and add @code{insert-file-dark} to @code{lc-dark-commands}.  I
personally have functions like @code{dired-create-directory},
@code{dired-do-symlink}, and @code{query-replace-regexp} in my list of
dark commands.




@comment ---------------------------------------------------------

@node Installation and customization, Miscellany, Lightning completion, top
@chapter Installation and customization

@cindex Installation
@cindex Customization

Once you've unpacked the archive, you need to make sure that the file
@file{light.el} is in your emacs load-path.  Then put

@example
(require 'light)
@end example

@noindent
in your @file{.emacs} file.  Restart emacs; then you can set all of the
lightning completion options via customization: run

@example
M-x customize-group lightning-completion
@end example

@menu
* Customizable options::        A list of customizable options
@end menu




@comment ---------------------------------------------------------

@comment  node-name,  next,  previous,  up
@node Customizable options, , , Installation and customization
@section Customizable options

@cindex Customizable options
@cindex List of customizable options
@cindex Options

Here is a list of the customizable options for lightning completion,
with pointers to relevant sections of this documentation.  Use this
command:

@example
M-x customize-group lightning-completion
@end example

@noindent
to customize any of these options.

@table @code
@item lc-complete-idle-time-default
Default value: 0.5.  Effect: when in lightning completion mode, after
this much idle time (in seconds) has elapsed, try to complete.
@xref{Overview}, @xref{Key bindings}.

@item toggle-lightning-completion
Default value: off.  Effect: toggle whether lightning completion is
potentially active in the minibuffer.  If on, you should customize
@code{lightning-completion-list} to specify contexts in which to use
lightning completion.
@xref{Enabling automatic lightning completion}.

@item lightning-completion-list
Default value: all off.  Effect: toggle lightning completion in, and
specify the idle-time for, specific contexts: files, functions,
commands, variables, user variables, lisp objects, info menu items,
buffer names, query replace, miscellany.
@xref{Enabling automatic lightning completion}.

@item lc-clean-up
Default value: nil.  Effect: If on, when there is no valid completion,
remove the invalid characters.  If off, just give warning when no valid
completion.
@xref{Key bindings}.

@item lc-ignored-file-extensions
Default value: equal to @code{completion-ignored-extensions}.
Description: a list of strings like ".dvi" and ".o"; files ending in
these strings are ignored when doing lightning completion on file names.
@xref{Ignoring some files}.

@item lc-dark-commands
Default value: nil.  Description: list of commands for which lightning
completion is disabled.
@xref{Settings for lightning completion}.

@item lc-dark-recursive-minibufs
Default value: nil.  Effect: If a number @var{N}, then don't use
lightning completion when recursion-depth is bigger than @var{N}.  If
nil, then no restrictions on when to use lightning completion.
@xref{Settings for lightning completion}.

@item lc-override-flag
Default value: nil.  Effect: If non-nil, override other local maps when
using lightning completion.  You may want to turn this on if using
outline mode or some other minor mode which uses C-c as prefix.  This
may not be necessary, though.

@item lc-keep-key
Default value: @key{SPC}.  Description: Key to keep current completion
in lightning completion mode.
@xref{Key bindings}.

@item lc-del-key
Default value: @key{DEL}.  Description: Key to delete last
completion unit in lightning completion mode.
@xref{Key bindings}.

@item lc-stop-key
Default value: @kbd{C-c}.  Description: Key to exit lightning completion
mode. 
@xref{Key bindings}.

@item lc-quote-key
Default value: @kbd{C-q}.  Description: Key to quote next character in 
lightning completion mode. 
@xref{Key bindings}.

@item lc-help-key
Default value: @kbd{C-h}.  Description: Help key in lightning completion
mode.
@xref{Key bindings}.

@item lc-cycle-key
Default value: @kbd{C-f}.  Description: Key to cycle to next completion
in lightning completion mode.
@xref{Key bindings}.

@item lc-back-cycle-key
Default value: @kbd{C-b}.  Description: Key to cycle to previous
completion in lightning completion mode.
@xref{Key bindings}.

@item lc-display-key
Default value: @key{TAB}.  Description: Key to display all completions
in lightning completion mode.
@xref{Key bindings}.

@item lc-ctrl-x-c-is-completion
Default value: nil.  Effect: if on, @kbd{C-x c} is the prefix key for
the various lightning completion commands.
@xref{Completion functions}.

@item lc-ctrl-backslash-completes-a-la-mode
Default value: nil.  Effect: if on, @kbd{C-\} runs the function
@code{completing-insert-according-to-mode}.
@xref{Completion functions}.

@end table





@comment ---------------------------------------------------------

@node Miscellany, , Installation and customization, top
@chapter Miscellany

@menu
* Ignoring some files::         Don't to complete on certain file names
* Buffer completion::           An application of lightning completion
* HTML mode completion::        Another example
@end menu



@comment ---------------------------------------------------------

@comment  node-name,  next,  previous,  up
@node Ignoring some files, Buffer completion, , Miscellany
@section Ignoring some files

@cindex Ignoring some files
@cindex Ignored file extensions
@cindex lc-ignored-file-extensions
@cindex completion-ignored-extensions

If you are using this package to complete on file names, then you should
be aware of the lisp variable @code{completion-ignored-extensions}.
(Lightning completion on file names is based on a completion mode
already present in Emacs, and this variable comes from that mode.)

Here is its documentation: ``Completion ignores filenames ending in
any string in this list.  This variable does not affect lists of
possible completions, but does affect the commands that actually do
completions.''

Lightning completion mode uses a similar variable, called
@code{lc-ignored-file-extensions}, whose default value is equal to
@code{completion-ignored-extensions}.

I use La@TeX{}, and when I start with a file @file{bozo.tex}, then 
La@TeX{} produces a number of auxiliary files: @file{bozo.aux},
@file{bozo.dvi}, @file{bozo.log}, and possibly @file{bozo.bbl},
@file{bozo.blg}, @file{bozo.toc}, @file{bozo.lof}, etc.  When I am
editing such a file, I edit the file @file{bozo.tex} frequently, and I
almost never touch the others.  So I make sure that
@code{lc-ignored-file-extensions} contains the strings ``.toc''
``.log'' ''.aux'' ``.lof'' ``.blg'' ``.bbl'' ``.dvi''.  The easiest way
to do this is to customize this variable.

In case you haven't been paying attention: suppose I have added "aux" to
@code{lc-ignored-file-extensions}, and I want to find the file
@file{bozo.aux}, with lightning completion enabled.  One way to do this
is to type @samp{bozo.aux} quickly enough that emacs is never idle for
half a second.  Another option is to hit @kbd{C-c} right at the start,
to turn off lightning completion; then just type in @samp{bozo.aux} at
one's leisure.  Another way to do this is to use lightning completion to
get @samp{bozo.tex} and ending completion there (if this is the only
file that starts @samp{bozo} that doesn't end in an ignored extension,
completion will end automatically at this point; otherwise, hit
@key{SPC}).  Then delete @samp{tex} and type in @samp{aux}.  There are
other ways of doing this, no doubt, but I'll let you figure them out.



@comment ---------------------------------------------------------

@node  Buffer completion, HTML mode completion, Ignoring some files, Miscellany
@section Buffer completion

@cindex Buffer completion
@cindex Completion on buffer contents
@cindex Lightning completion on buffer contents
@findex completing-insert-buffer-contents

Buffer completion is an example of a use of lightning completion: it
lets you complete on reasonably balanced substrings of a buffer.  The
main function is

@example
(completing-insert-buffer-contents BUF)
@end example

@noindent
where @var{BUF} is interactively the current buffer or, with a prefix
argument, a buffer specified by the user.

In other words, if I want to repeat something I said somewhere else in
this buffer, I call the function
@code{completing-insert-buffer-contents}.  At that point, I enter
lightning completion mode on the contents of this buffer.  If I want to
repeat something I said in a different buffer, I hit @kbd{C-u} and then
call @code{completing-insert-buffer-contents}.  Emacs prompts me for a
buffer name, and then does lightning completion on the contents of that
other buffer.  This is useful if you're too lazy to switch buffers, find
the material you want to copy, mark it, kill it, and yank it.

The @file{dabbrev} package (included as part of the standard GNU Emacs
distribution) does some similar things, so you might want to look at
that, too.  I won't advocate the use of one package over the other---I
think each has its uses.


@comment ---------------------------------------------------------

@node  HTML mode completion, , Buffer completion, Miscellany
@section HTML mode completion

@cindex HTML tags
@cindex Completion on HTML tags
@cindex Lightning completion on HTML tags

Here is another example of how to use lightning completion: you can
automatically complete on HTML tags when in html mode.  I have the
following lines in my @file{.emacs} file.  The first line binds the @kbd{<}
key to the function @code{html-lightning-tag} (you could use a different
key, if you wanted, but since HTML tags all start with this character,
it seems to make sense).  The next lines define this function---it does
lightning completion on HTML tags.  And the remaining lines (starting
with @samp{(defvar html-light-alist}) define the list of HTML tags on
which to complete.  A typical line is @samp{("<h3></h3>" -5)}; the first
entry is the tag, and the second entry is the number of characters from
the end by which the point should be offset (i.e., Emacs inserts the
string @samp{"<h3></h3>"} and then moves forward -5 characters).  (This
whole business is intended to be used with the version of
@code{html-mode} that is contained in the file @file{sgml-mode.el}, part
of (for example) the standard GNU Emacs distribution.

@example
(define-key html-mode-map "<" 'html-lightning-tag)

(defun html-lightning-tag nil
  "Lightning complete control sequence."
  (interactive)
  (insert "<")
  (completing-insert html-light-alist nil 1 'point-adjust-hook
		     "html tags"))

(defvar html-light-alist
  '(
    ("<a href=\"\"></a>" -6)
    ("<h1></h1>" -5)
    ("<h2></h2>" -5)
    ("<h3></h3>" -5)
    ("<h4></h4>" -5)
    ("<h-5></h-5>" -5)
    ("<h6></h6>" -5)
    ("<hr>

" 0)
    ("<!--   -->" -5)    
    ("<img src=\"\" alt=\"\">" -9)
    ("<ol>
<li> 
</ol>" -6)
    ("<ul>
<li> 
</ul>" -6)
    ("<li> " 0)
    ("<dl>
<dt> 
<dd> 
</dl>" -12)
    ("<dt> 
<dd> " -6)
    ("<p>
" 0)
    ("<table>
<tr>
<th> </th>
</tr>
</table>" -20)
    ("<th> </th>" -5)
    ("<tr>
<td> </td>
</tr>" -11)
    ("<td> </td>" -5)
    ("<html>
<head>
<title> </title>
</head>
<body lang=\"EN\">

</body>
</html>" -32)
    ("<address>John H. Palmieri, Department of Mathematics, University
of Notre Dame, John.H.Palmieri.2@@nd.edu</address>
" 0)
    ("<address></address>
" -11)
    ("<cite></cite>" -7)
    ("<kbd></kbd>" -6)
    ("<dfn></dfn>" -6)
    ("<em></em>" -5)
    ("<samp></samp>" -7)
    ("<small></small>" -8)
    ("<strong></strong>" -9)
    ("<sub></sub>" -6)
    ("<sup></sup>" -6)
    ("<tt></tt>" -5)
    ("<var></var>" -6)
    ("<code></code>" -7)
    ("<blockquote>

</blockquote>
" -15)
    ("<math>

</math>
" -9)
    ("<pre>

</pre>
" -8)
    ("<br>

" 0))
  "Alist of html tags for use with lightning completion")
@end example




@comment ---------------------------------------------------------

@node    Function Index, Concept Index,  , top
@unnumbered Function Index

@printindex fn


@comment ---------------------------------------------------------

@node    Concept Index,    ,  Function Index, top
@unnumbered Concept Index

@printindex cp


@comment ---------------------------------------------------------

@contents
@bye