1 \input texinfo @c -*- texinfo -*-
3 @setfilename ../../info/vhdl-mode
4 @settitle VHDL Mode, an Emacs mode for editing VHDL code
6 @c Adapted from the VHDL Mode texinfo manual version 2 by Rodney J. Whitby.
7 @c Adapted from the CC Mode texinfo manual by Barry A. Warsaw.
10 This file documents VHDL Mode, an Emacs mode for editing VHDL code.
12 Copyright @copyright{} 1995--2008, 2010, 2012, 2014 Free Software
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3 or
18 any later version published by the Free Software Foundation; with no
19 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
20 and with the Back-Cover Texts as in (a) below. A copy of the license
21 is included in the section entitled ``GNU Free Documentation License.''
23 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
24 modify this GNU manual.''
28 @dircategory Emacs editing modes
30 * VHDL Mode: (vhdl-mode). Emacs mode for editing VHDL code.
38 @subtitle A GNU Emacs mode for editing VHDL code.
40 @author Reto Zimmermann
41 @author @email{reto@@gnu.org}
43 @author @email{software.vhdl-mode@@rwhitby.net}
46 @vskip 0pt plus 1filll
54 @top VHDL Mode, an Emacs mode for editing VHDL code
62 * New Indentation Engine::
63 * Customizing Indentation::
65 * Frequently Asked Questions::
66 * Getting the latest VHDL Mode release::
67 * Sample .emacs File::
68 * Limitations and Known Bugs::
69 * Mailing Lists and Submitting Bug Reports::
70 * GNU Free Documentation License:: The license for this documentation.
72 * Command Index:: Command Index
73 * Key Index:: Key Index
74 * Variable Index:: Variable Index
81 Welcome to VHDL Mode. This is a GNU Emacs mode for editing files
84 This manual will describe the following:
88 How to get started using VHDL Mode.
91 How the indentation engine works.
94 How to customize the indentation engine.
99 The major version number was incremented to 3 with the addition of
100 many new features for editing VHDL code to the new indentation engine,
101 which was introduced in major version 2. To find the minor revision
102 number of this release, use @kbd{M-x vhdl-version RET}.
104 A special word of thanks goes to Rod Whitby, who wrote the
105 VHDL Mode indentation engine, and to Barry Warsaw, who wrote
106 the CC Mode indentation engine that formed the basis
107 thereof. Their manuals were also the basis for this manual.
109 This manual is not very up-to-date. It basically contains the
110 indentation machine documentation by Rod Whitby with only minor
111 adaptions. A short documentation of the entire VHDL Mode is available
112 within the mode itself by typing @kbd{C-c C-h}. Also, all commands and
113 customization of most variables are available through the menu, which
114 makes everything highly self-explaining.
116 @node Getting Connected
117 @chapter Getting Connected
118 @cindex Getting Connected
120 To get started, simply visit a @file{.vhd} file in Emacs; or type
121 @kbd{M-x vhdl-mode RET}.
123 @node New Indentation Engine
124 @chapter New Indentation Engine
125 @cindex New Indentation Engine
127 VHDL Mode has a new indentation engine, providing a simplified, yet
128 flexible and general mechanism for customizing indentation. It breaks
129 indentation calculation into two steps. First for the line of code being
130 indented, VHDL Mode analyzes what kind of language construct it's
131 looking at, then it applies user defined offsets to the current line
132 based on this analysis.
134 This section will briefly cover how indentation is calculated in
135 VHDL Mode. It is important to understand the indentation model
136 being used so that you will know how to customize VHDL Mode for
137 your personal coding style.
140 * Syntactic Analysis:: Step 1 -- Syntactic Analysis
141 * Indentation Calculation:: Step 2 -- Indentation Calculation
144 @node Syntactic Analysis
145 @section Syntactic Analysis
146 @cindex Syntactic Analysis
148 @vindex vhdl-offsets-alist
149 @vindex offsets-alist (vhdl-)
150 @cindex relative buffer position
151 @cindex syntactic symbol
152 @cindex syntactic component
153 @cindex syntactic component list
154 @cindex relative buffer position
155 The first thing VHDL Mode does when indenting a line of code, is
156 to analyze the line, determining the @dfn{syntactic component list} of
157 the construct on that line. A @dfn{syntactic component} consists of a
158 pair of information (in lisp parlance, a @emph{cons cell}), where the
159 first part is a @dfn{syntactic symbol}, and the second part is a
160 @dfn{relative buffer position}. Syntactic symbols describe elements of
161 VHDL code, e.g. @code{statement}, @code{comment}, @code{block-open},
162 @code{block-close}, etc. @xref{Syntactic Symbols}, for a complete list
163 of currently recognized syntactic symbols and their semantics. Also,
164 the variable @code{vhdl-offsets-alist} contains the list of currently
165 supported syntactic symbols.
167 Conceptually, a line of VHDL code is always indented relative to the
168 indentation of some line higher up in the buffer. This is represented
169 by the relative buffer position in the syntactic component.
171 It might help to see an example. Suppose we had the following code as
172 the only thing in a VHDL Mode buffer @footnote{The line numbers
173 in this and future examples don't actually appear in the buffer.}:
177 1: inverter : process
187 @findex vhdl-show-syntactic-information
188 @findex show-syntactic-information (vhdl-)
189 We can use the command @kbd{C-c C-x}
190 (@code{vhdl-show-syntactic-information}) to simply report what the
191 syntactic analysis is for the current line. Running this command on
192 line 4 of example 1, we'd see in the echo area:
199 This tells us that the line is a statement and it is indented relative
200 to buffer position 28, which happens to be the @samp{q} on line 3. If
201 you were to move point to line 3 and hit @kbd{C-c C-x}, you would see:
204 ((statement-block-intro . 20))
208 This indicates that line 3 is the first statement in a block, and is
209 indented relative to buffer position 20, which is the @samp{b} in the
210 @code{begin} keyword on line 2.
212 @cindex comment only line
213 Syntactic component lists can contain more than one component, and
214 individual syntactic compenents need not have relative buffer positions.
215 The most common example of this is a line that contains a @dfn{comment
226 Hitting @kbd{C-c C-x} on line 3 of the example gives us:
229 ((comment-intro) (block-intro . 46))
234 so you can see that the syntactic component list contains two syntactic
235 components. Also notice that the first component,
236 @samp{(comment-intro)} has no relative buffer position.
238 @node Indentation Calculation
239 @section Indentation Calculation
240 @cindex Indentation Calculation
242 @vindex vhdl-offsets-alist
243 @vindex offsets-alist (vhdl-)
244 Indentation for the current line is calculated using the syntactic
245 component list derived in step 1 above (see @ref{Syntactic
246 Analysis}). Each component contributes to the final total indentation
247 of the line in two ways.
249 First, the syntactic symbols are looked up in the @code{vhdl-offsets-alist}
250 variable, which is an association list of syntactic symbols and the
251 offsets to apply for those symbols. These offsets are added to the
254 Second, if the component has a relative buffer position, VHDL Mode
255 adds the column number of that position to the running total. By adding
256 up the offsets and columns for every syntactic component on the list,
257 the final total indentation for the current line is computed.
259 Let's use our code example above to see how this works. Here is our
264 1: inverter : process
274 Let's say point is on line 3 and we hit the @key{TAB} key to re-indent
275 the line. Remember that the syntactic component list for that
279 ((statement-block-intro . 20))
284 VHDL Mode looks up @code{statement-block-intro} in the
285 @code{vhdl-offsets-alist} variable. Let's say it finds the value @samp{2};
286 it adds this to the running total (initialized to zero), yielding a
287 running total indentation of 2 spaces.
289 Next VHDL Mode goes to buffer position 20 and asks for the
290 current column. Since the @code{begin} keyword at buffer position 20 is
291 in column zero, it adds @samp{0} to the running total. Since there is
292 only one syntactic component on the list for this line, indentation
293 calculation is complete, and the total indentation for the line is 2
297 Actually, the mode usually just does The Right Thing without you having
298 to think about it in this much detail. But when customizing
299 indentation, it's helpful to understand the general indentation model
302 @vindex vhdl-echo-syntactic-information-p
303 @vindex echo-syntactic-information-p (vhdl-)
305 To help you configure VHDL Mode, you can set the variable
306 @code{vhdl-echo-syntactic-information-p} to non-@code{nil} so that the
307 syntactic component list and calculated offset will always be echoed in
308 the minibuffer when you hit @kbd{TAB}.
312 @node Indentation Commands
313 @chapter Indentation Commands
314 @cindex Indentation Commands
320 @node Customizing Indentation
321 @chapter Customizing Indentation
322 @cindex Customizing Indentation
324 @cindex vhdl-set-offset
325 @cindex set-offset (vhdl-)
326 The @code{vhdl-offsets-alist} variable is where you customize all your
327 indentations. You simply need to decide what additional offset you want
328 to add for every syntactic symbol. You can use the command @kbd{C-c
329 O} (@code{vhdl-set-offset}) as the way to set offsets, both
330 interactively and from your mode hook. Also, you can set up
331 @emph{styles} of indentation. Most likely, you'll find one of the
332 pre-defined styles will suit your needs, but if not, this section will
333 describe how to set up basic editing configurations. @xref{Styles}, for
334 an explanation of how to set up named styles.
336 @cindex vhdl-basic-offset
337 @cindex basic-offset (vhdl-)
338 As mentioned previously, the variable @code{vhdl-offsets-alist} is an
339 association list between syntactic symbols and the offsets to be applied
340 for those symbols. In fact, these offset values can be an integer, a
341 function or variable name, or one of the following symbols: @code{+},
342 @code{-}, @code{++}, @code{--}, @code{*}, or @code{/}. The symbol
343 values have the following meanings:
348 @code{+} -- 1 x @code{vhdl-basic-offset}
350 @code{-} -- -1 x @code{vhdl-basic-offset}
352 @code{++} -- 2 x @code{vhdl-basic-offset}
354 @code{--} -- -2 x @code{vhdl-basic-offset}
356 @code{*} -- 0.5 x @code{vhdl-basic-offset}
358 @code{/} -- -0.5 x @code{vhdl-basic-offset}
363 So, for example, because most of the default offsets are defined in
364 terms of @code{+}, @code{-}, and @code{0}, if you like the general
365 indentation style, but you use 2 spaces instead of 4 spaces per level,
366 you can probably achieve your style just by changing
367 @code{vhdl-basic-offset} like so (in your @file{.emacs} file):
370 (setq vhdl-basic-offset 2)
374 To change indentation styles more radically, you will want to change the
375 value associated with the syntactic symbols in the
376 @code{vhdl-offsets-alist} variable. First, I'll show you how to do that
377 interactively, then I'll describe how to make changes to your
378 @file{.emacs} file so that your changes are more permanent.
381 * Interactive Customization::
382 * Permanent Customization::
384 * Advanced Customizations::
387 @node Interactive Customization
388 @section Interactive Customization
389 @cindex Interactive Customization
391 As an example of how to customize indentation, let's change the
392 style of the example above from:
396 1: inverter : process
409 1: inverter : process
418 In other words, we want to change the indentation of the statments
419 inside the inverter process. Notice that the construct we want to
420 change starts on line 3. To change the indentation of a line, we need
421 to see which syntactic component affect the offset calculations for that
422 line. Hitting @kbd{C-c C-x} on line 3 yields:
425 ((statement-block-intro . 20))
429 @findex vhdl-set-offset
430 @findex set-offset (vhdl-)
433 So we know that to change the offset of the first signal assignment, we need to
434 change the indentation for the @code{statement-block-intro} syntactic
435 symbol. To do this interactively, just hit @kbd{C-c O}
436 (@code{vhdl-set-offset}). This prompts you for the syntactic symbol to
437 change, providing a reasonable default. In this case, the default is
438 @code{statement-block-intro}, which is just the syntactic symbol we want to
441 After you hit return, VHDL Mode will then prompt you for the new
442 offset value, with the old value as the default. The default in this
443 case is @samp{+}, so hit backspace to delete the @samp{+}, then hit
444 @samp{++} and @kbd{RET}. This will associate an offset of twice the
445 basic indent with the syntactic symbol @code{statement-block-intro} in
446 the @code{vhdl-offsets-alist} variable.
448 @findex vhdl-indent-defun
449 @findex indent-defun (vhdl-)
450 To check your changes quickly, just enter @kbd{M-x vhdl-indent-defun} to
451 reindent the entire function. The example should now look like:
455 1: inverter : process
464 Notice how just changing the offset on line 3 is all we needed to do.
465 Since the other affected lines are indented relative to line 3, they are
466 automatically indented the way you'd expect. For more complicated
467 examples, this may not always work. The general approach to take is to
468 always start adjusting offsets for lines higher up in the file, then
469 re-indent and see if any following lines need further adjustments.
471 @node Permanent Customization
472 @section Permanent Indentation
473 @cindex Permanent Indentation
475 @vindex vhdl-mode-hook
477 To make this change permanent, you need to add some lisp code to your
478 @file{.emacs} file. VHDL Mode provides a @code{vhdl-mode-hook}
479 that you can use to customize your language editing styles. This hook
480 gets run as the last thing when you enter VHDL Mode.
482 Here's a simplified example of what you can add to your @file{.emacs}
483 file to make the changes described in the previous section
484 (@ref{Interactive Customization}) more permanent. See the Emacs
485 manuals for more information on customizing Emacs via hooks.
486 @xref{Sample .emacs File}, for a more complete sample @file{.emacs} file.
491 (defun my-vhdl-mode-hook ()
492 ;; my customizations for all of vhdl-mode
493 (vhdl-set-offset 'statement-block-intro '++)
494 ;; other customizations can go here
496 (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)
501 For complex customizations, you will probably want to set up a
502 @emph{style} that groups all your customizations under a single
505 The offset value can also be a function, and this is how power users
506 gain enormous flexibility in customizing indentation. @xref{Advanced
513 Most people only need to edit code formatted in just a few well-defined
514 and consistent styles. For example, their organization might impose a
515 ``blessed'' style that all its programmers must conform to. Similarly,
516 people who work on GNU software will have to use the GNU coding style on
517 C code. Some shops are more lenient, allowing some variety of coding
518 styles, and as programmers come and go, there could be a number of
519 styles in use. For this reason, VHDL Mode makes it convenient for
520 you to set up logical groupings of customizations called @dfn{styles},
521 associate a single name for any particular style, and pretty easily
522 start editing new or existing code using these styles. This chapter
523 describes how to set up styles and how to edit your C code using styles.
532 @node Built-in Styles
533 @subsection Built-in Styles
534 @cindex Built-in Styles
536 If you're lucky, one of VHDL Mode's built-in styles might be just
537 what you're looking for. Some of the most common VHDL styles are
538 already built-in. These include:
543 @code{GNU} -- the coding style in the IEEE Language Reference Manual.
547 @findex vhdl-set-style
548 @findex set-style (vhdl-)
549 If you'd like to experiment with these built-in styles you can simply
550 type @kbd{M-x vhdl-set-style RET} in a VHDL Mode buffer.
552 You will be prompted for one of the above styles (with completion).
553 Enter one of the styles and hit @kbd{RET}. Note however that setting a
554 style in this way does @emph{not} automatically re-indent your file.
556 For commands that you can use to view the effect of your changes, see
557 @ref{Indentation Commands}.
560 Once you find a built-in style you like, you can make the change
561 permanent by adding a call to your @file{.emacs} file. Let's say for
562 example that you want to use the @code{IEEE} style in all your
563 files. You would add this:
567 (defun my-vhdl-mode-hook ()
568 ;; use IEEE style for all VHDL code
569 (vhdl-set-style "IEEE")
570 ;; other customizations can go here
572 (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)
578 @xref{Permanent Customization}.
581 @subsection Adding Styles
582 @cindex Adding Styles
584 @vindex vhdl-style-alist
585 @vindex style-alist (vhdl-)
586 @findex vhdl-add-style
587 @findex add-style (vhdl-)
588 If none of the built-in styles is appropriate, you'll probably want to
589 add a new style definition. Styles are kept in the @code{vhdl-style-alist}
590 variable, but you probably won't want to modify this variable directly.
591 VHDL Mode provides a function, called @code{vhdl-add-style}, that you
592 can use to easily add new styles or update existing styles. This
593 function takes two arguments, a @var{stylename} string, and an
594 association list @var{description} of style customizations. If
595 @var{stylename} is not already in @code{vhdl-style-alist}, the new style is
596 added, otherwise the style already associated with @var{stylename} is
597 changed to the new @var{description}. This function also takes an
598 optional third argument, which if non-@code{nil}, automatically
599 institutes the new style in the current buffer.
601 The sample @file{.emacs} file provides a concrete example of how a new
602 style can be added and automatically set. @xref{Sample .emacs File}.
605 @subsection File Styles
608 @cindex local variables
609 The Emacs manual describes how you can customize certain variables on a
610 per-file basis by including a @dfn{Local Variable} block at the end of
611 the file. So far, you've only seen a functional interface to
612 VHDL Mode, which is highly inconvenient for use in a Local Variable
613 block. VHDL Mode provides two variables that make it easier for
614 you to customize your style on a per-file basis.
616 @vindex vhdl-file-style
617 @vindex file-style (vhdl-)
618 @vindex vhdl-file-offsets
619 @vindex file-offsets (vhdl-)
621 The variable @code{vhdl-file-style} can be set to a style name string as
622 described in @ref{Built-in Styles}. When the file is visited,
623 VHDL Mode will automatically set the file's style to this style
624 using @code{vhdl-set-style}.
626 @vindex vhdl-offsets-alist
627 @vindex offsets-alist (vhdl-)
628 @findex vhdl-set-offset
629 @findex set-offset (vhdl-)
630 Another variable, @code{vhdl-file-offsets}, takes an association list
631 similar to what is allowed in @code{vhdl-offsets-alist}. When the file is
632 visited, VHDL Mode will automatically institute these offets using
633 @code{vhdl-set-offset}. @xref{Customizing Indentation}.
635 Note that file style settings (i.e. @code{vhdl-file-style}) are applied
636 before file offset settings (i.e. @code{vhdl-file-offsets}).
639 @node Advanced Customizations
640 @section Advanced Customizations
641 @cindex Advanced Customizations
643 @vindex vhdl-style-alist
644 @vindex style-alist (vhdl-)
645 @vindex vhdl-basic-offset
646 @vindex basic-offset (vhdl-)
647 For most users, VHDL Mode will support their coding styles with
648 very little need for customizations. Usually, one of the standard
649 styles defined in @code{vhdl-style-alist} will do the trick. Sometimes,
650 one of the syntactic symbol offsets will need to be tweeked slightly, or
651 perhaps @code{vhdl-basic-offset} will need to be changed. However, some
652 styles require a more advanced ability for customization, and one of the
653 real strengths of VHDL Mode is that the syntactic analysis model
654 provides a very flexible framework for customizing indentation. This
655 allows you to perform special indentation calculations for situations
656 not handled by the mode directly.
659 * Custom Indentation Functions::
660 * Other Special Indentations::
663 @node Custom Indentation Functions
664 @subsection Custom Indentation Functions
665 @cindex Custom Indentation Functions
667 @cindex custom indentation functions
668 One of the most common ways to customize VHDL Mode is by writing
669 @dfn{custom indentation functions} and associating them with specific
670 syntactic symbols (see @ref{Syntactic Symbols}). VHDL Mode itself
671 uses custom indentation functions to provide more sophisticated
672 indentation, for example when lining up selected signal assignments:
681 In this example, the @code{statement-cont} syntactic symbol has an
682 offset of @code{+}, and @code{vhdl-basic-offset} is 2, so lines 4
683 through 6 are simply indented two spaces to the right of line 3. But
684 perhaps we'd like VHDL Mode to be a little more intelligent so
685 that it offsets the waveform descriptions relative to the signal
686 assignment operator in line 3. To do this, we have to write a custom
687 indentation function which finds the column of signal assignment
688 operator on the first line of the statement. Here is the lisp code
689 (from the @file{vhdl-mode.el} source file) that implements this:
693 (defun vhdl-lineup-statement-cont (langelem)
694 ;; line up statement-cont after the assignment operator
696 (let* ((relpos (cdr langelem))
697 (assignp (save-excursion
698 (goto-char (vhdl-point 'boi))
699 (and (re-search-forward "\\(<\\|:\\)="
701 (- (point) (vhdl-point 'boi)))))
706 (while (and (not foundp)
707 (< (point) (vhdl-point 'eol)))
708 (re-search-forward "\\(<\\|:\\)=\\|(" (vhdl-point 'eol) 'move)
709 (if (vhdl-in-literal (cdr langelem))
711 (if (= (preceding-char) ?\()
712 ;; skip over any parenthesized expressions
713 (goto-char (min (vhdl-point 'eol)
714 (scan-lists (point) 1 1)))
715 ;; found an assignment operator (not at eol)
716 (setq foundp (not (looking-at "\\s-*$"))))))
718 ;; there's no assignment operator on the line
720 ;; calculate indentation column after assign and ws, unless
721 ;; our line contains an assignment operator
725 (skip-chars-forward " \t")
727 (- (current-column) assignp curcol))
733 Custom indent functions take a single argument, which is a syntactic
734 component cons cell (see @ref{Syntactic Analysis}). The
735 function returns an integer offset value that will be added to the
736 running total indentation for the lne. Note that what actually gets
737 returned is the difference between the column that the signal assignment
738 operator is on, and the column of the buffer relative position passed in
739 the function's argument. Remember that VHDL Mode automatically
740 adds in the column of the component's relative buffer position and we
741 don't want that value added into the final total twice.
743 @cindex statement-cont syntactic symbol
744 @findex vhdl-lineup-statement-cont
745 @findex lineup-statement-cont (vhdl-)
746 Now, to associate the function @code{vhdl-lineup-statement-cont} with the
747 @code{statement-cont} syntactic symbol, we can add something like the
748 following to our @code{vhdl-mode-hook}:
751 (vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont)
755 @findex vhdl-indent-defun
756 Now the function looks like this after re-indenting (using @kbd{M-x
766 @vindex vhdl-offsets-alist
767 @vindex offsets-alist (vhdl-)
768 Custom indentation functions can be as simple or as complex as you like,
769 and any syntactic symbol that appears in @code{vhdl-offsets-alist} can have
770 a custom indentation function associated with it. Note however that
771 using many custom indentation functions may have a performance impact on
774 @node Other Special Indentations
775 @subsection Other Special Indentations
776 @cindex Other Special Indentations
778 @vindex vhdl-special-indent-hook
779 @vindex special-indent-hook (vhdl-)
780 One other variable is available for you to customize VHDL Mode:
781 @code{vhdl-special-indent-hook}. This is a standard hook variable that
782 is called after every line is indented by VHDL Mode. You can use
783 it to do any special indentation or line adjustments your style
784 dictates, such as adding extra indentation to the port map clause in a
785 component instantiation, etc. Note however, that you should not change
786 @code{point} or @code{mark} inside your @code{vhdl-special-indent-hook}
790 @node Syntactic Symbols
791 @chapter Syntactic Symbols
792 @cindex Syntactic Symbols
794 @vindex vhdl-offsets-alist
795 The complete list of recognized syntactic symbols is described in the
796 @code{vhdl-offsets-alist} variable. This chapter will provide some
797 examples to help clarify these symbols.
799 @cindex -open syntactic symbols
800 @cindex -close syntactic symbols
801 Most syntactic symbol names follow a general naming convention. When a
802 line begins with a @code{begin} or @code{end} keyword, the syntactic
803 symbol will contain the suffix @code{-open} or @code{-close}
806 @cindex -intro syntactic symbols
807 @cindex -cont syntactic symbols
808 @cindex -block-intro syntactic symbols
809 Usually, a distinction is made between the first line that introduces a
810 construct and lines that continue a construct, and the syntactic symbols
811 that represent these lines will contain the suffix @code{-intro} or
812 @code{-cont} respectively. As a sub-classification of this scheme, a
813 line which is the first of a particular block construct will contain the
814 suffix @code{-block-intro}.
816 @strong{<TBD> include the name and a brief example of every syntactic
817 symbol currently recognized}
819 @node Frequently Asked Questions
820 @chapter Frequently Asked Questions
821 @cindex Frequently Asked Questions
829 @findex newline-and-indent
832 @strong{Q.} @emph{How do I re-indent the whole file?}
834 @strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole
835 buffer. Then hit @kbd{@key{ESC} C-\} to re-indent the entire region
836 which you've just marked. Or just enter @kbd{M-x vhdl-indent-buffer}.
839 @strong{Q.} @emph{How do I re-indent the entire function?}
841 @strong{A.} Hit @kbd{@key{ESC} C-h} to mark the entire function. Then
842 hit @kbd{@key{ESC} C-\} to re-indent the entire region which you've just
846 @strong{Q.} @emph{How do I re-indent the current block?}
848 @strong{A.} First move to the brace which opens the block with
849 @kbd{@key{ESC} C-u}, then re-indent that expression with
853 @strong{Q.} @emph{How do I re-indent the current statement?}
855 @strong{A.} First move to the beginning of the statement with
856 @kbd{@key{ESC} a}, then re-indent that expression with @kbd{@key{ESC}
860 @strong{Q.} @emph{I put @code{(vhdl-set-offset 'statement-cont 0)}
861 in my @file{.emacs} file but I get an error saying that
862 @code{vhdl-set-offset}'s function definition is void.}
864 @strong{A.} This means that VHDL Mode wasn't loaded into your
865 Emacs session by the time the @code{vhdl-set-offset} call was reached,
866 mostly likely because VHDL Mode is being autoloaded. Instead
867 of putting the @code{vhdl-set-offset} line in your top-level
868 @file{.emacs} file, put it in your @code{vhdl-mode-hook}, or
869 simply add the following to the top of your @file{.emacs} file:
876 See the sample @file{.emacs} file @ref{Sample .emacs File} for
882 @node Getting the latest VHDL Mode release
883 @chapter Getting the latest VHDL Mode release
884 @cindex Getting the latest VHDL Mode release
886 The best way to be sure you always have the latest VHDL Mode release
887 is to join the @code{vhdl-mode-announce} mailing list. If you are a
888 brave soul, and wish to participate in beta testing of new releases of
889 VHDL Mode, you may also join the @code{vhdl-mode-victims} mailing
890 list. Send email to the maintainer @email{reto@@gnu.org} to join
891 either of these lists.
893 The official Emacs VHDL Mode Home Page can be found at
894 @uref{http://www.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html}.
896 @node Sample .emacs File
897 @chapter Sample @file{.emacs} file
898 @cindex Sample @file{.emacs} file
900 Most customizations can be done using the `Customize' entry in the
901 VHDL Mode menu, which requires no editing of the .emacs file.
902 If you want to customize indentation, here you go:
905 ;; Here's a sample .emacs file that might help you along the way. Just
906 ;; copy this region and paste it into your .emacs file. You may want to
907 ;; change some of the actual values.
909 (defconst my-vhdl-style
910 '((vhdl-tab-always-indent . t)
911 (vhdl-comment-only-line-offset . 4)
912 (vhdl-offsets-alist . ((arglist-close . vhdl-lineup-arglist)
914 (case-alternative . 4)
916 (vhdl-echo-syntactic-information-p . t)
918 "My VHDL Programming Style")
920 ;; Customizations for vhdl-mode
921 (defun my-vhdl-mode-hook ()
922 ;; add my personal style and set it for the current buffer
923 (vhdl-add-style "PERSONAL" my-vhdl-style t)
924 ;; offset customizations not in my-vhdl-style
925 (vhdl-set-offset 'statement-case-intro '++)
926 ;; other customizations
928 ;; this will make sure spaces are used instead of tabs
929 indent-tabs-mode nil)
930 ;; keybindings for VHDL are put in vhdl-mode-map
931 (define-key vhdl-mode-map "\C-m" 'newline-and-indent)
934 (add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)
937 @node Limitations and Known Bugs
938 @chapter Limitations and Known Bugs
939 @cindex Limitations and Known Bugs
943 Re-indenting large regions or expressions can be slow.
947 The index menu does not work on my XEmacs installation (don't know why).
952 @node Mailing Lists and Submitting Bug Reports
953 @chapter Mailing Lists and Submitting Bug Reports
954 @cindex Mailing Lists and Submitting Bug Reports
957 @findex vhdl-submit-bug-report
958 @findex submit-bug-report (vhdl-)
959 @cindex beta testers mailing list
960 @cindex announcement mailing list
961 To report bugs, use the @kbd{C-c C-b} (@code{vhdl-submit-bug-report})
962 command. This provides vital information I need to reproduce your
963 problem. Make sure you include a concise, but complete code example.
964 Please try to boil your example down to just the essential code needed
965 to reproduce the problem, and include an exact recipe of steps needed to
966 expose the bug. Be especially sure to include any code that appears
967 @emph{before} your bug example.
969 For other help or suggestions, send a message to @email{reto@@gnu.org}.
971 Send an add message to @email{reto@@gnu.org} to get on the
972 @code{vhdl-mode-victims} beta testers list where beta releases of
973 VHDL Mode are posted. Note that you shouldn't expect beta
974 releases to be as stable as public releases.
976 There is also an announce only list where the latest public releases
977 of VHDL Mode are posted. Send an add message to
978 @email{reto@@gnu.org} to be added to this list.
981 @node GNU Free Documentation License
982 @appendix GNU Free Documentation License
983 @include doclicense.texi
987 @unnumbered Concept Index
993 @unnumbered Command Index
995 Since all VHDL Mode commands are prepended with the string
996 @samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its
997 @code{<thing> (vhdl-)} name.
1005 @unnumbered Key Index
1010 @node Variable Index
1011 @unnumbered Variable Index
1013 Since all VHDL Mode variables are prepended with the string
1014 @samp{vhdl-}, each appears under its @code{vhdl-<thing>} name and its
1015 @code{<thing> (vhdl-)} name.