1 \input texinfo @c -*- texinfo -*-
3 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
4 @comment %**start of header (This is for running Texinfo on a region)
5 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
7 @setfilename vhdl-mode.info
8 @settitle VHDL Mode Version 3 Documentation
10 * VHDL Mode: (vhdl-mode). VHDL Mode Version 3 Documentation.
12 @c footnotestyle separate
17 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
18 @comment @setchapternewpage odd !! we don't want blank pages !!
19 @comment %**end of header (This is for running Texinfo on a region)
20 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
23 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
25 @comment texinfo manual for @file{vhdl-mode.el} version 3
26 @comment manual version: 3.1
27 @comment adapted from the VHDL Mode texinfo manual version 2 by
28 @comment Rodney J. Whitby <rwhitby@geocities.com>
29 @comment adapted from the CC Mode texinfo manual by Barry A. Warsaw
30 @comment <bwarsaw@cnri.reston.va.us>
32 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
35 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
36 @comment The following line inserts the copyright notice
37 @comment into the Info file.
38 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
41 Copyright @copyright{} 1997 Reto Zimmermann <Reto.Zimmermann@@iaeth.ch>
42 Copyright @copyright{} 1995 - 1997 Rodney J. Whitby <rwhitby@@geocities.com>
45 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
46 @comment !!!The titlepage section does not appear in the Info file.!!!
47 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
53 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
54 @comment The title is printed in a large font.
55 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
57 @center @titlefont{VHDL Mode Version 3}
59 @center A GNU Emacs mode for editing VHDL code.
60 @center (manual revision: 3.1)
62 @center Reto Zimmermann
63 @center @code{Reto.Zimmermann@@iaeth.ch}
65 @center @code{rwhitby@@geocities.com}
68 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
69 @comment The following two commands start the copyright page
70 @comment for the printed manual. This will not appear in the Info file.
71 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
74 @vskip 0pt plus 1filll
75 Copyright @copyright{} 1997 Reto Zimmermann <Reto.Zimmermann@@iaeth.ch>
76 Copyright @copyright{} 1995 - 1997 Rodney J. Whitby <rwhitby@@geocities.com>
80 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
81 @comment The Top node contains the master menu for the Info file.
82 @comment This appears only in the Info file, not the printed manual.
83 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
85 @node Top, Introduction, (dir), (dir)
86 @comment node-name, next, previous, up
89 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
90 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
95 * New Indentation Engine::
96 * Customizing Indentation::
98 * Indentation Commands::
99 * Frequently Asked Questions::
100 * Getting the latest VHDL Mode release::
101 * Sample .emacs File::
103 * Limitations and Known Bugs::
104 * Mailing Lists and Submitting Bug Reports::
106 * Command Index:: Command Index
107 * Key Index:: Key Index
108 * Variable Index:: Variable Index
111 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
112 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
114 @node Introduction, Getting Connected, Top, Top
115 @comment node-name, next, previous, up
116 @chapter Introduction
119 Welcome to VHDL Mode version 3. This is a GNU Emacs mode for editing
120 files containing VHDL code.
122 This manual will describe the following:
126 How to get started using VHDL Mode.
129 How the indentation engine works.
132 How to customize the indentation engine.
137 The major version number was incremented to 3 with the addition of
138 many new features for editing VHDL code to the new indentation engine,
139 which was introduced in major version 2. To find the minor revision
140 number of this release, use @kbd{M-x vhdl-version RET}.
142 A special word of thanks goes to Rod Whitby, who wrote the
143 VHDL Mode indentation engine, and to Barry Warsaw, who wrote
144 the CC Mode indentation engine that formed the basis
145 thereof. Their manuals were also the basis for this manual.
147 This manual is not very up-to-date. It basically contains the
148 indentation machine documentation by Rod Whitby with only minor
149 adaptions. A short documentation of the entire VHDL Mode is available
150 within the mode itself by typing @kbd{C-c C-h}. Also, all commands and the
151 customization of most variables is available through the menu, which
152 makes everything highly self-explaining.
155 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
157 @node Getting Connected, New Indentation Engine, Introduction, Top
158 @comment node-name, next, previous, up
159 @chapter Getting Connected
160 @cindex Getting Connected
162 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
164 VHDL Mode works well under FSF Emacs 20 and XEmacs 19.15 and higher.
165 FSF Emacs 19 is not supported anymore since several new features of
166 Emacs 20 are used in this VHDL Mode version (you can download VHDL
167 Mode version 1.10 for Emacs 19). Also, Win-Emacs is currently not
168 supported, simply because I am not able to test and maintain the code
172 The first thing you will want to do is put @file{vhdl-mode.el} somewhere
173 on your @code{load-path} so Emacs can find it. Do a @kbd{C-h v
174 load-path RET} to see all the directories Emacs looks at when loading a
175 file. If none of these directories are appropriate, create a new
176 directory and add it to your @code{load-path}:
179 @emph{[in the shell]}
185 % mv vhdl-mode.el mylisp
192 @emph{[in your .emacs file add]}
195 (setq load-path (cons "~/mylisp" load-path))
200 Next you want to @dfn{byte compile} @file{vhdl-mode.el}. The mode uses a
201 lot of macros so if you don't byte compile it, things will be unbearably
202 slow. @emph{You can ignore all byte-compiler warnings!} They are the
203 result of the supporting different versions of Emacs, and none of the
204 warnings have any effect on operation. Let me say this again:
205 @strong{You really can ignore all byte-compiler warnings!}
207 Here's what to do to byte-compile the file [in emacs]:
210 M-x byte-compile-file RET ~/mylisp/vhdl-mode.el RET
214 Now add the following autoloads to your @file{.emacs} file so that
215 @code{vhdl-mode} gets loaded at the right time:
218 (autoload 'vhdl-mode "vhdl-mode" "VHDL Editing Mode" t)
222 Alternatively, if you want to make sure VHDL Mode is loaded when
223 Emacs starts up, you could use this line instead of the autoload above:
230 Next, you will want to set up Emacs so that it edits VHDL files in
231 VHDL Mode. All users should add the following to their
232 @file{.emacs} file. Note that this assumes you'll be editing @code{.vhd}
233 and files as VHDL. YMMV:
237 (setq auto-mode-alist
239 '(("\\.vhd$" . vhdl-mode)
245 That's all you need -- I know, I know, it sounds like a lot @code{:-)},
246 but after you've done all this, you should only need to quit and restart
247 Emacs. The next time you visit a VHDL file you should be using
248 VHDL Mode. You can check this easily by hitting @kbd{M-x
249 vhdl-version RET} in the VHDL Mode buffer. You should see this
250 message in the echo area:
253 Using VHDL Mode version 3.@var{XX}
258 where @var{XX} will be some minor revision number.
260 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
262 @node New Indentation Engine, Indentation Commands, Getting Connected, Top
263 @comment node-name, next, previous, up
265 @chapter New Indentation Engine
266 @cindex New Indentation Engine
268 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
270 VHDL Mode has a new indentation engine, providing a simplified, yet
271 flexible and general mechanism for customizing indentation. It breaks
272 indentation calculation into two steps. First for the line of code being
273 indented, VHDL Mode analyzes what kind of language construct it's
274 looking at, then it applies user defined offsets to the current line
275 based on this analysis.
277 This section will briefly cover how indentation is calculated in
278 VHDL Mode. It is important to understand the indentation model
279 being used so that you will know how to customize VHDL Mode for
280 your personal coding style.
282 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
284 * Syntactic Analysis:: Step 1 -- Syntactic Analysis
285 * Indentation Calculation:: Step 2 -- Indentation Calculation
287 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
289 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
290 @node Syntactic Analysis, Indentation Calculation, , New Indentation Engine
291 @comment node-name, next, previous, up
292 @section Syntactic Analysis
293 @cindex Syntactic Analysis
294 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
296 @vindex vhdl-offsets-alist
297 @vindex offsets-alist (vhdl-)
298 @cindex relative buffer position
299 @cindex syntactic symbol
300 @cindex syntactic component
301 @cindex syntactic component list
302 @cindex relative buffer position
303 The first thing VHDL Mode does when indenting a line of code, is
304 to analyze the line, determining the @dfn{syntactic component list} of
305 the construct on that line. A @dfn{syntactic component} consists of a
306 pair of information (in lisp parlance, a @emph{cons cell}), where the
307 first part is a @dfn{syntactic symbol}, and the second part is a
308 @dfn{relative buffer position}. Syntactic symbols describe elements of
309 VHDL code, e.g. @code{statement}, @code{comment}, @code{block-open},
310 @code{block-close}, etc. @xref{Syntactic Symbols}, for a complete list
311 of currently recognized syntactic symbols and their semantics. Also,
312 the variable @code{vhdl-offsets-alist} contains the list of currently
313 supported syntactic symbols.
315 Conceptually, a line of VHDL code is always indented relative to the
316 indentation of some line higher up in the buffer. This is represented
317 by the relative buffer position in the syntactic component.
319 It might help to see an example. Suppose we had the following code as
320 the only thing in a VHDL Mode buffer @footnote{The line numbers
321 in this and future examples don't actually appear in the buffer.}:
325 1: inverter : process
335 @findex vhdl-show-syntactic-information
336 @findex show-syntactic-information (vhdl-)
337 We can use the command @kbd{C-c C-x}
338 (@code{vhdl-show-syntactic-information}) to simply report what the
339 syntactic analysis is for the current line. Running this command on
340 line 4 of example 1, we'd see in the echo area:
347 This tells us that the line is a statement and it is indented relative
348 to buffer position 28, which happens to be the @samp{q} on line 3. If
349 you were to move point to line 3 and hit @kbd{C-c C-x}, you would see:
352 ((statement-block-intro . 20))
356 This indicates that line 3 is the first statement in a block, and is
357 indented relative to buffer position 20, which is the @samp{b} in the
358 @code{begin} keyword on line 2.
360 @cindex comment only line
361 Syntactic component lists can contain more than one component, and
362 individual syntactic compenents need not have relative buffer positions.
363 The most common example of this is a line that contains a @dfn{comment
374 Hitting @kbd{C-c C-x} on line 3 of the example gives us:
377 ((comment-intro) (block-intro . 46))
382 so you can see that the syntactic component list contains two syntactic
383 components. Also notice that the first component,
384 @samp{(comment-intro)} has no relative buffer position.
386 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
387 @node Indentation Calculation, , Syntactic Analysis, New Indentation Engine
388 @comment node-name, next, previous, up
389 @section Indentation Calculation
390 @cindex Indentation Calculation
391 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
393 @vindex vhdl-offsets-alist
394 @vindex offsets-alist (vhdl-)
395 Indentation for the current line is calculated using the syntactic
396 component list derived in step 1 above (see @ref{Syntactic
397 Analysis}). Each component contributes to the final total indentation
398 of the line in two ways.
400 First, the syntactic symbols are looked up in the @code{vhdl-offsets-alist}
401 variable, which is an association list of syntactic symbols and the
402 offsets to apply for those symbols. These offsets are added to the
405 Second, if the component has a relative buffer position, VHDL Mode
406 adds the column number of that position to the running total. By adding
407 up the offsets and columns for every syntactic component on the list,
408 the final total indentation for the current line is computed.
410 Let's use our code example above to see how this works. Here is our
415 1: inverter : process
425 Let's say point is on line 3 and we hit the @key{TAB} key to re-indent
426 the line. Remember that the syntactic component list for that
430 ((statement-block-intro . 20))
435 VHDL Mode looks up @code{statement-block-intro} in the
436 @code{vhdl-offsets-alist} variable. Let's say it finds the value @samp{2};
437 it adds this to the running total (initialized to zero), yielding a
438 running total indentation of 2 spaces.
440 Next VHDL Mode goes to buffer position 20 and asks for the
441 current column. Since the @code{begin} keyword at buffer position 20 is
442 in column zero, it adds @samp{0} to the running total. Since there is
443 only one syntactic component on the list for this line, indentation
444 calculation is complete, and the total indentation for the line is 2
448 Actually, the mode usually just does The Right Thing without you having
449 to think about it in this much detail. But when customizing
450 indentation, it's helpful to understand the general indentation model
453 @vindex vhdl-echo-syntactic-information-p
454 @vindex echo-syntactic-information-p (vhdl-)
456 To help you configure VHDL Mode, you can set the variable
457 @code{vhdl-echo-syntactic-information-p} to non-@code{nil} so that the
458 syntactic component list and calculated offset will always be echoed in
459 the minibuffer when you hit @kbd{TAB}.
462 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
463 @node Indentation Commands, Customizing Indentation, New Indentation Engine, Top
464 @comment node-name, next, previous, up
466 @chapter Indentation Commands
467 @cindex Indentation Commands
468 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
472 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
473 @node Customizing Indentation, Syntactic Symbols, Indentation Commands, Top
474 @comment node-name, next, previous, up
476 @chapter Customizing Indentation
477 @cindex Customizing Indentation
478 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
480 @cindex vhdl-set-offset
481 @cindex set-offset (vhdl-)
482 The @code{vhdl-offsets-alist} variable is where you customize all your
483 indentations. You simply need to decide what additional offset you want
484 to add for every syntactic symbol. You can use the command @kbd{C-c
485 O} (@code{vhdl-set-offset}) as the way to set offsets, both
486 interactively and from your mode hook. Also, you can set up
487 @emph{styles} of indentation. Most likely, you'll find one of the
488 pre-defined styles will suit your needs, but if not, this section will
489 describe how to set up basic editing configurations. See @ref{Styles} for
490 an explanation of how to set up named styles.
492 @cindex vhdl-basic-offset
493 @cindex basic-offset (vhdl-)
494 As mentioned previously, the variable @code{vhdl-offsets-alist} is an
495 association list between syntactic symbols and the offsets to be applied
496 for those symbols. In fact, these offset values can be an integer, a
497 function or variable name, or one of the following symbols: @code{+},
498 @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The symbol
499 values have the following meanings:
504 @code{+} -- 1 x @code{vhdl-basic-offset}
506 @code{-} -- -1 x @code{vhdl-basic-offset}
508 @code{++} -- 2 x @code{vhdl-basic-offset}
510 @code{--} -- -2 x @code{vhdl-basic-offset}
512 @code{*} -- 0.5 x @code{vhdl-basic-offset}
514 @code{/} -- -0.5 x @code{vhdl-basic-offset}
519 So, for example, because most of the default offsets are defined in
520 terms of @code{+}, @code{-}, and @code{0}, if you like the general
521 indentation style, but you use 2 spaces instead of 4 spaces per level,
522 you can probably achieve your style just by changing
523 @code{vhdl-basic-offset} like so (in your @file{.emacs} file):
526 (setq vhdl-basic-offset 2)
530 To change indentation styles more radically, you will want to change the
531 value associated with the syntactic symbols in the
532 @code{vhdl-offsets-alist} variable. First, I'll show you how to do that
533 interactively, then I'll describe how to make changes to your
534 @file{.emacs} file so that your changes are more permanent.
537 * Interactive Customization::
538 * Permanent Customization::
540 * Advanced Customizations::
543 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
544 @node Interactive Customization, Permanent Customization, , Customizing Indentation
545 @comment node-name, next, previous, up
547 @section Interactive Customization
548 @cindex Interactive Customization
549 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
551 As an example of how to customize indentation, let's change the
552 style of the example above from:
556 1: inverter : process
569 1: inverter : process
578 In other words, we want to change the indentation of the statements
579 inside the inverter process. Notice that the construct we want to
580 change starts on line 3. To change the indentation of a line, we need
581 to see which syntactic component affect the offset calculations for that
582 line. Hitting @kbd{C-c C-x} on line 3 yields:
585 ((statement-block-intro . 20))
589 @findex vhdl-set-offset
590 @findex set-offset (vhdl-)
593 So we know that to change the offset of the first signal assignment, we need to
594 change the indentation for the @code{statement-block-intro} syntactic
595 symbol. To do this interactively, just hit @kbd{C-c O}
596 (@code{vhdl-set-offset}). This prompts you for the syntactic symbol to
597 change, providing a reasonable default. In this case, the default is
598 @code{statement-block-intro}, which is just the syntactic symbol we want to
601 After you hit return, VHDL Mode will then prompt you for the new
602 offset value, with the old value as the default. The default in this
603 case is @samp{+}, so hit backspace to delete the @samp{+}, then hit
604 @samp{++} and @kbd{RET}. This will associate an offset of twice the
605 basic indent with the syntactic symbol @code{statement-block-intro} in
606 the @code{vhdl-offsets-alist} variable.
608 @findex vhdl-indent-defun
609 @findex indent-defun (vhdl-)
610 To check your changes quickly, just enter @kbd{M-x vhdl-indent-defun} to
611 reindent the entire function. The example should now look like:
615 1: inverter : process
624 Notice how just changing the offset on line 3 is all we needed to do.
625 Since the other affected lines are indented relative to line 3, they are
626 automatically indented the way you'd expect. For more complicated
627 examples, this may not always work. The general approach to take is to
628 always start adjusting offsets for lines higher up in the file, then
629 re-indent and see if any following lines need further adjustments.
631 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
632 @node Permanent Customization, Styles, Interactive Customization, Customizing Indentation
633 @comment node-name, next, previous, up
635 @section Permanent Indentation
636 @cindex Permanent Indentation
637 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
639 @vindex vhdl-mode-hook
641 To make this change permanent, you need to add some lisp code to your
642 @file{.emacs} file. VHDL Mode provides a @code{vhdl-mode-hook}
643 that you can use to customize your language editing styles. This hook
644 gets run as the last thing when you enter VHDL Mode.
646 Here's a simplified example of what you can add to your @file{.emacs}
647 file to make the changes described in the previous section
648 (@ref{Interactive Customization}) more permanent. See the Emacs
649 manuals for more information on customizing Emacs via hooks.
650 See @ref{Sample .emacs File} for a more complete sample @file{.emacs} file.
651 @footnote{The use of @code{add-hook} in this example only works for
652 Emacs 19. Workarounds are available if you are using Emacs 18, but this
653 just points out another reason for you to upgrade to Emacs 19!
658 (defun my-vhdl-mode-hook ()
659 ;; my customizations for all of vhdl-mode
660 (vhdl-set-offset 'statement-block-intro '++)
661 ;; other customizations can go here
663 (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)
668 For complex customizations, you will probably want to set up a
669 @emph{style} that groups all your customizations under a single
670 name. See @ref{Styles} for details.
672 The offset value can also be a function, and this is how power users
673 gain enormous flexibility in customizing indentation.
674 See @ref{Advanced Customizations} for details.
676 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
677 @node Styles, Advanced Customizations, Permanent Customization, Customizing Indentation
678 @comment node-name, next, previous, up
682 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
684 Most people only need to edit code formatted in just a few well-defined
685 and consistent styles. For example, their organization might impose a
686 ``blessed'' style that all its programmers must conform to. Similarly,
687 people who work on GNU software will have to use the GNU coding style on
688 C code. Some shops are more lenient, allowing some variety of coding
689 styles, and as programmers come and go, there could be a number of
690 styles in use. For this reason, VHDL Mode makes it convenient for
691 you to set up logical groupings of customizations called @dfn{styles},
692 associate a single name for any particular style, and pretty easily
693 start editing new or existing code using these styles. This chapter
694 describes how to set up styles and how to edit your C code using styles.
703 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
704 @node Built-in Styles, Adding Styles, , Styles
705 @comment node-name, next, previous, up
707 @subsection Built-in Styles
708 @cindex Built-in Styles
709 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
711 If you're lucky, one of VHDL Mode's built-in styles might be just
712 what you're looking for. Some of the most common VHDL styles are
713 already built-in. These include:
718 @code{GNU} -- the coding style in the IEEE Language Reference Manual.
722 @findex vhdl-set-style
723 @findex set-style (vhdl-)
724 If you'd like to experiment with these built-in styles you can simply
725 type the following in a VHDL Mode buffer:
729 @kbd{M-x vhdl-set-style RET}.
734 You will be prompted for one of the above styles (with completion).
735 Enter one of the styles and hit @kbd{RET}. Note however that setting a
736 style in this way does @emph{not} automatically re-indent your file.
737 For commands that you can use to view the effect of your changes, see
738 @ref{Indentation Commands}.
740 Once you find a built-in style you like, you can make the change
741 permanent by adding a call to your @file{.emacs} file. Let's say for
742 example that you want to use the @code{IEEE} style in all your
743 files. You would add this:
747 (defun my-vhdl-mode-hook ()
748 ;; use IEEE style for all VHDL code
749 (vhdl-set-style "IEEE")
750 ;; other customizations can go here
752 (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)
758 @xref{Permanent Customization}.
760 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
761 @node Adding Styles, File Styles, Built-in Styles, Styles
762 @comment node-name, next, previous, up
764 @subsection Adding Styles
765 @cindex Adding Styles
766 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
768 @vindex vhdl-style-alist
769 @vindex style-alist (vhdl-)
770 @findex vhdl-add-style
771 @findex add-style (vhdl-)
772 If none of the built-in styles is appropriate, you'll probably want to
773 add a new style definition. Styles are kept in the @code{vhdl-style-alist}
774 variable, but you probably won't want to modify this variable directly.
775 VHDL Mode provides a function, called @code{vhdl-add-style}, that you
776 can use to easily add new styles or update existing styles. This
777 function takes two arguments, a @var{stylename} string, and an
778 association list @var{description} of style customizations. If
779 @var{stylename} is not already in @code{vhdl-style-alist}, the new style is
780 added, otherwise the style already associated with @var{stylename} is
781 changed to the new @var{description}. This function also takes an
782 optional third argument, which if non-@code{nil}, automatically
783 institutes the new style in the current buffer.
785 The sample @file{.emacs} file provides a concrete example of how a new
786 style can be added and automatically set. @xref{Sample .emacs File}.
788 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
789 @node File Styles, , Adding Styles, Styles
790 @comment node-name, next, previous, up
792 @subsection File Styles
794 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
796 @cindex local variables
797 The Emacs manual describes how you can customize certain variables on a
798 per-file basis by including a @dfn{Local Variable} block at the end of
799 the file. So far, you've only seen a functional interface to
800 VHDL Mode, which is highly inconvenient for use in a Local Variable
801 block. VHDL Mode provides two variables that make it easier for
802 you to customize your style on a per-file basis.
804 @vindex vhdl-file-style
805 @vindex file-style (vhdl-)
806 @vindex vhdl-file-offsets
807 @vindex file-offsets (vhdl-)
809 The variable @code{vhdl-file-style} can be set to a style name string as
810 described in @ref{Built-in Styles}. When the file is visited,
811 VHDL Mode will automatically set the file's style to this style
812 using @code{vhdl-set-style}.
814 @vindex vhdl-offsets-alist
815 @vindex offsets-alist (vhdl-)
816 @findex vhdl-set-offset
817 @findex set-offset (vhdl-)
818 Another variable, @code{vhdl-file-offsets}, takes an association list
819 similar to what is allowed in @code{vhdl-offsets-alist}. When the file is
820 visited, VHDL Mode will automatically institute these offets using
821 @code{vhdl-set-offset}. @xref{Customizing Indentation}.
823 Note that file style settings (i.e. @code{vhdl-file-style}) are applied
824 before file offset settings (i.e. @code{vhdl-file-offsets}).
827 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
828 @node Advanced Customizations, , Styles, Customizing Indentation
829 @comment node-name, next, previous, up
831 @section Advanced Customizations
832 @cindex Advanced Customizations
833 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
835 @vindex vhdl-style-alist
836 @vindex style-alist (vhdl-)
837 @vindex vhdl-basic-offset
838 @vindex basic-offset (vhdl-)
839 For most users, VHDL Mode will support their coding styles with
840 very little need for customizations. Usually, one of the standard
841 styles defined in @code{vhdl-style-alist} will do the trick. Sometimes,
842 one of the syntactic symbol offsets will need to be tweeked slightly, or
843 perhaps @code{vhdl-basic-offset} will need to be changed. However, some
844 styles require a more advanced ability for customization, and one of the
845 real strengths of VHDL Mode is that the syntactic analysis model
846 provides a very flexible framework for customizing indentation. This
847 allows you to perform special indentation calculations for situations
848 not handled by the mode directly.
851 * Custom Indentation Functions::
852 * Other Special Indentations::
855 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
856 @node Custom Indentation Functions, Other Special Indentations, , Advanced Customizations
857 @comment node-name, next, previous, up
859 @subsection Custom Indentation Functions
860 @cindex Custom Indentation Functions
861 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
863 @cindex custom indentation functions
864 One of the most common ways to customize VHDL Mode is by writing
865 @dfn{custom indentation functions} and associating them with specific
866 syntactic symbols (see @ref{Syntactic Symbols}). VHDL Mode itself
867 uses custom indentation functions to provide more sophisticated
868 indentation, for example when lining up selected signal assignments:
877 In this example, the @code{statement-cont} syntactic symbol has an
878 offset of @code{+}, and @code{vhdl-basic-offset} is 2, so lines 4
879 through 6 are simply indented two spaces to the right of line 3. But
880 perhaps we'd like VHDL Mode to be a little more intelligent so
881 that it offsets the waveform descriptions relative to the signal
882 assignment operator in line 3. To do this, we have to write a custom
883 indentation function which finds the column of signal assignment
884 operator on the first line of the statement. Here is the lisp code
885 (from the @file{vhdl-mode.el} source file) that implements this:
889 (defun vhdl-lineup-statement-cont (langelem)
890 ;; line up statement-cont after the assignment operator
892 (let* ((relpos (cdr langelem))
893 (assignp (save-excursion
894 (goto-char (vhdl-point 'boi))
895 (and (re-search-forward "\\(<\\|:\\)="
897 (- (point) (vhdl-point 'boi)))))
902 (while (and (not foundp)
903 (< (point) (vhdl-point 'eol)))
904 (re-search-forward "\\(<\\|:\\)=\\|(" (vhdl-point 'eol) 'move)
905 (if (vhdl-in-literal (cdr langelem))
907 (if (= (preceding-char) ?\()
908 ;; skip over any parenthesized expressions
909 (goto-char (min (vhdl-point 'eol)
910 (scan-lists (point) 1 1)))
911 ;; found an assignment operator (not at eol)
912 (setq foundp (not (looking-at "\\s-*$"))))))
914 ;; there's no assignment operator on the line
916 ;; calculate indentation column after assign and ws, unless
917 ;; our line contains an assignment operator
921 (skip-chars-forward " \t")
923 (- (current-column) assignp curcol))
929 Custom indent functions take a single argument, which is a syntactic
930 component cons cell (see @ref{Syntactic Analysis}). The
931 function returns an integer offset value that will be added to the
932 running total indentation for the lne. Note that what actually gets
933 returned is the difference between the column that the signal assignment
934 operator is on, and the column of the buffer relative position passed in
935 the function's argument. Remember that VHDL Mode automatically
936 adds in the column of the component's relative buffer position and we
937 don't want that value added into the final total twice.
939 @cindex statement-cont syntactic symbol
940 @findex vhdl-lineup-statement-cont
941 @findex lineup-statement-cont (vhdl-)
942 Now, to associate the function @code{vhdl-lineup-statement-cont} with the
943 @code{statement-cont} syntactic symbol, we can add something like the
944 following to our @code{vhdl-mode-hook}:
947 (vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont)
951 @findex vhdl-indent-defun
952 Now the function looks like this after re-indenting (using @kbd{M-x
962 @vindex vhdl-offsets-alist
963 @vindex offsets-alist (vhdl-)
964 Custom indentation functions can be as simple or as complex as you like,
965 and any syntactic symbol that appears in @code{vhdl-offsets-alist} can have
966 a custom indentation function associated with it. Note however that
967 using many custom indentation functions may have a performance impact on
970 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
971 @node Other Special Indentations, , Custom Indentation Functions, Advanced Customizations
972 @comment node-name, next, previous, up
974 @subsection Other Special Indentations
975 @cindex Other Special Indentations
976 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
978 @vindex vhdl-special-indent-hook
979 @vindex special-indent-hook (vhdl-)
980 One other variable is available for you to customize VHDL Mode:
981 @code{vhdl-special-indent-hook}. This is a standard hook variable that
982 is called after every line is indented by VHDL Mode. You can use
983 it to do any special indentation or line adjustments your style
984 dictates, such as adding extra indentation to the port map clause in a
985 component instantiation, etc. Note however, that you should not change
986 @code{point} or @code{mark} inside your @code{vhdl-special-indent-hook}
990 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
991 @node Syntactic Symbols, Frequently Asked Questions, Customizing Indentation, Top
992 @comment node-name, next, previous, up
994 @chapter Syntactic Symbols
995 @cindex Syntactic Symbols
996 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
998 @vindex vhdl-offsets-alist
999 The complete list of recognized syntactic symbols is described in the
1000 @code{vhdl-offsets-alist} variable. This chapter will provide some
1001 examples to help clarify these symbols.
1003 @cindex -open syntactic symbols
1004 @cindex -close syntactic symbols
1005 Most syntactic symbol names follow a general naming convention. When a
1006 line begins with a @code{begin} or @code{end} keyword, the syntactic
1007 symbol will contain the suffix @code{-open} or @code{-close}
1010 @cindex -intro syntactic symbols
1011 @cindex -cont syntactic symbols
1012 @cindex -block-intro syntactic symbols
1013 Usually, a distinction is made between the first line that introduces a
1014 construct and lines that continue a construct, and the syntactic symbols
1015 that represent these lines will contain the suffix @code{-intro} or
1016 @code{-cont} respectively. As a sub-classification of this scheme, a
1017 line which is the first of a particular block construct will contain the
1018 suffix @code{-block-intro}.
1020 @strong{<TBD> include the name and a brief example of every syntactic
1021 symbol currently recognized}
1023 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1024 @node Frequently Asked Questions, Getting the latest VHDL Mode release, Syntactic Symbols, Top
1025 @comment node-name, next, previous, up
1027 @chapter Frequently Asked Questions
1028 @cindex Frequently Asked Questions
1029 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1037 @findex newline-and-indent
1040 @strong{Q.} @emph{How do I re-indent the whole file?}
1042 @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole
1043 buffer. Then hit @kbd{@key{ESC} C-\} to re-indent the entire region
1044 which you've just marked. Or just enter @kbd{M-x vhdl-indent-buffer}.
1047 @strong{Q.} @emph{How do I re-indent the entire function?}
1049 @strong{A.} Hit @kbd{@key{ESC} C-h} to mark the entire function. Then
1050 hit @kbd{@key{ESC} C-\} to re-indent the entire region which you've just
1054 @strong{Q.} @emph{How do I re-indent the current block?}
1056 @strong{A.} First move to the brace which opens the block with
1057 @kbd{@key{ESC} C-u}, then re-indent that expression with
1058 @kbd{@key{ESC} C-q}.
1061 @strong{Q.} @emph{How do I re-indent the current statement?}
1063 @strong{A.} First move to the beginning of the statement with
1064 @kbd{@key{ESC} a}, then re-indent that expression with @kbd{@key{ESC}
1068 @strong{Q.} @emph{Why doesn't the @key{RET} key indent the line to
1069 where the new text should go after inserting the newline?}
1071 @strong{A.} Emacs' convention is that @key{RET} just adds a newline,
1072 and that @key{LFD} adds a newline and indents it. You can make
1073 @key{RET} do this too by adding this to your
1074 @code{vhdl-mode-hook} (see the sample @file{.emacs} file
1075 @ref{Sample .emacs File}):
1078 (define-key vhdl-mode-map "\C-m" 'newline-and-indent)
1082 This is a very common question. @code{:-)} If you want this to be the
1083 default behavior, don't lobby me, lobby RMS!
1086 @strong{Q.} @emph{I put @code{(vhdl-set-offset 'statement-cont 0)}
1087 in my @file{.emacs} file but I get an error saying that
1088 @code{vhdl-set-offset}'s function definition is void.}
1090 @strong{A.} This means that VHDL Mode wasn't loaded into your
1091 Emacs session by the time the @code{vhdl-set-offset} call was reached,
1092 mostly likely because VHDL Mode is being autoloaded. Instead
1093 of putting the @code{vhdl-set-offset} line in your top-level
1094 @file{.emacs} file, put it in your @code{vhdl-mode-hook}, or
1095 simply add the following to the top of your @file{.emacs} file:
1098 (require 'vhdl-mode)
1102 See the sample @file{.emacs} file @ref{Sample .emacs File} for
1108 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1109 @node Getting the latest VHDL Mode release, Sample .emacs File, Frequently Asked Questions, Top
1110 @comment node-name, next, previous, up
1112 @chapter Getting the latest VHDL Mode release
1113 @cindex Getting the latest VHDL Mode release
1114 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1116 The best way to be sure you always have the latest VHDL Mode release
1117 is to join the @code{vhdl-mode-announce} mailing list. If you are a
1118 brave soul, and wish to participate in beta testing of new releases of
1119 VHDL Mode, you may also join the @code{vhdl-mode-victims} mailing
1120 list. Send email to the maintainers <vhdl-mode@@geocities.com> to join
1121 either of these lists.
1123 The official Emacs VHDL Mode Home Page can be found at
1124 <http://www.geocities.com/SiliconValley/Peaks/8287/>.
1126 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1127 @node Sample .emacs File, Requirements, Getting the latest VHDL Mode release, Top
1128 @comment node-name, next, previous, up
1130 @chapter Sample @file{.emacs} file
1131 @cindex Sample @file{.emacs} file
1132 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1134 Most customizations can be done using the `Customize' entry in the
1135 VHDL Mode menu, which requires no editing of the .emacs file.
1136 If you want to customize indentation, here you go:
1139 ;; Here's a sample .emacs file that might help you along the way. Just
1140 ;; copy this region and paste it into your .emacs file. You may want to
1141 ;; change some of the actual values.
1143 (defconst my-vhdl-style
1144 '((vhdl-tab-always-indent . t)
1145 (vhdl-comment-only-line-offset . 4)
1146 (vhdl-offsets-alist . ((arglist-close . vhdl-lineup-arglist)
1147 (statement-cont . 0)
1148 (case-alternative . 4)
1150 (vhdl-echo-syntactic-information-p . t)
1152 "My VHDL Programming Style")
1154 ;; Customizations for vhdl-mode
1155 (defun my-vhdl-mode-hook ()
1156 ;; add my personal style and set it for the current buffer
1157 (vhdl-add-style "PERSONAL" my-vhdl-style t)
1158 ;; offset customizations not in my-vhdl-style
1159 (vhdl-set-offset 'statement-case-intro '++)
1160 ;; other customizations
1162 ;; this will make sure spaces are used instead of tabs
1163 indent-tabs-mode nil)
1164 ;; keybindings for VHDL are put in vhdl-mode-map
1165 (define-key vhdl-mode-map "\C-m" 'newline-and-indent)
1168 ;; the following only works in Emacs 19
1169 ;; Emacs 18ers can use (setq vhdl-mode-hook 'my-vhdl-mode-hook)
1170 (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)
1173 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1174 @node Requirements, Limitations and Known Bugs, Sample .emacs File, Top
1175 @comment node-name, next, previous, up
1176 @chapter Requirements
1177 @cindex Requirements
1178 @comment * Requirements
1179 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1181 All required files are distributed with FSF Emacs 20 and XEmacs 19.15.
1183 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1184 @node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Requirements, Top
1185 @comment node-name, next, previous, up
1186 @chapter Limitations and Known Bugs
1187 @cindex Limitations and Known Bugs
1188 @comment * Limitations and Known Bugs
1189 @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1193 Re-indenting large regions or expressions can be slow.
1196 The index menu does not work on my XEmacs installation (don't know why).
1200 @node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top
1201 @comment node-name, next, previous, up
1202 @chapter Mailing Lists and Submitting Bug Reports
1203 @cindex Mailing Lists and Submitting Bug Reports
1204 @comment * Mailing Lists and Submitting Bug Reports
1207 @findex vhdl-submit-bug-report
1208 @findex submit-bug-report (vhdl-)
1209 @cindex beta testers mailing list
1210 @cindex announcement mailing list
1211 To report bugs, use the @kbd{C-c C-b} (@code{vhdl-submit-bug-report})
1212 command. This provides vital information I need to reproduce your
1213 problem. Make sure you include a concise, but complete code example.
1214 Please try to boil your example down to just the essential code needed
1215 to reproduce the problem, and include an exact recipe of steps needed to
1216 expose the bug. Be especially sure to include any code that appears
1217 @emph{before} your bug example.
1219 For other help or suggestions, send a message to
1220 <vhdl-mode@@geocities.com>.
1222 Send an add message to <vhdl-mode@@geocities.com> to get on the
1223 @code{vhdl-mode-victims} beta testers list where beta releases of
1224 VHDL Mode are posted. Note that you shouldn't expect beta
1225 releases to be as stable as public releases.
1227 There is also an announce only list where the latest public releases
1228 of VHDL Mode are posted. Send an add message to
1229 <vhdl-mode@@geocities.com> to be added to this list.
1231 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1232 @node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top
1233 @comment node-name, next, previous, up
1234 @unnumbered Concept Index
1235 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1240 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1241 @node Command Index, Key Index, Concept Index, Top
1242 @comment node-name, next, previous, up
1243 @unnumbered Command Index
1244 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1249 Since all VHDL Mode commands are prepended with the string
1250 @samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its
1251 @code{<thing> (vhdl-)} name.
1258 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1259 @node Key Index, Variable Index, Command Index, Top
1260 @comment node-name, next, previous, up
1261 @unnumbered Key Index
1262 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1267 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1268 @node Variable Index, , Key Index, Top
1269 @comment node-name, next, previous, up
1270 @unnumbered Variable Index
1271 @c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
1276 Since all VHDL Mode variables are prepended with the string
1277 @samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its
1278 @code{<thing> (vhdl-)} name.