VHDL Mode, an Emacs mode for editing VHDL code

This file documents VHDL Mode, an Emacs mode for editing VHDL code.

Copyright © 1995–2008, 2010, 2012, 2015–2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”

Table of Contents

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

1 Introduction

Welcome to VHDL Mode. This is a GNU Emacs mode for editing files containing VHDL code.

This manual will describe the following:

The major version number was incremented to 3 with the addition of many new features for editing VHDL code to the new indentation engine, which was introduced in major version 2. To find the minor revision number of this release, use M-x vhdl-version RET.

A special word of thanks goes to Rod Whitby, who wrote the VHDL Mode indentation engine, and to Barry Warsaw, who wrote the CC Mode indentation engine that formed the basis thereof. Their manuals were also the basis for this manual.

This manual is not very up-to-date. It basically contains the indentation machine documentation by Rod Whitby with only minor adaptions. A short documentation of the entire VHDL Mode is available within the mode itself by typing C-c C-h. Also, all commands and customization of most variables are available through the menu, which makes everything highly self-explaining.

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

2 Getting Connected

To get started, simply visit a .vhd file in Emacs; or type M-x vhdl-mode RET.

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

3 New Indentation Engine

VHDL Mode has a new indentation engine, providing a simplified, yet flexible and general mechanism for customizing indentation. It breaks indentation calculation into two steps. First for the line of code being indented, VHDL Mode analyzes what kind of language construct it’s looking at, then it applies user defined offsets to the current line based on this analysis.

This section will briefly cover how indentation is calculated in VHDL Mode. It is important to understand the indentation model being used so that you will know how to customize VHDL Mode for your personal coding style.

Next: , Up: New Indentation Engine   [Contents][Index]

3.1 Syntactic Analysis

The first thing VHDL Mode does when indenting a line of code, is to analyze the line, determining the syntactic component list of the construct on that line. A syntactic component consists of a pair of information (in lisp parlance, a cons cell), where the first part is a syntactic symbol, and the second part is a relative buffer position. Syntactic symbols describe elements of VHDL code, e.g., statement, comment, block-open, block-close, etc. See Syntactic Symbols, for a complete list of currently recognized syntactic symbols and their semantics. Also, the variable vhdl-offsets-alist contains the list of currently supported syntactic symbols.

Conceptually, a line of VHDL code is always indented relative to the indentation of some line higher up in the buffer. This is represented by the relative buffer position in the syntactic component.

It might help to see an example. Suppose we had the following code as the only thing in a VHDL Mode buffer 1: 


  1: inverter : process
  2: begin
  3:   q <= not d;
  4:   wait on d;
  5: end inverter;

We can use the command C-c C-x (vhdl-show-syntactic-information) to simply report what the syntactic analysis is for the current line. Running this command on line 4 of example 1, we’d see in the echo area: 


((statement . 28))

This tells us that the line is a statement and it is indented relative to buffer position 28, which happens to be the ‘q’ on line 3. If you were to move point to line 3 and hit C-c C-x, you would see: 


((statement-block-intro . 20))

This indicates that line 3 is the first statement in a block, and is indented relative to buffer position 20, which is the ‘b’ in the begin keyword on line 2.

Syntactic component lists can contain more than one component, and individual syntactic components need not have relative buffer positions. The most common example of this is a line that contains a comment only line. 


%%% TBD %%%

Hitting C-c C-x on line 3 of the example gives us: 


((comment-intro) (block-intro . 46))

so you can see that the syntactic component list contains two syntactic components. Also notice that the first component, ‘(comment-intro)’ has no relative buffer position.

Previous: , Up: New Indentation Engine   [Contents][Index]

3.2 Indentation Calculation

Indentation for the current line is calculated using the syntactic component list derived in step 1 above (see Syntactic Analysis). Each component contributes to the final total indentation of the line in two ways.

First, the syntactic symbols are looked up in the vhdl-offsets-alist variable, which is an association list of syntactic symbols and the offsets to apply for those symbols. These offsets are added to the running total.

Second, if the component has a relative buffer position, VHDL Mode adds the column number of that position to the running total. By adding up the offsets and columns for every syntactic component on the list, the final total indentation for the current line is computed.

Let’s use our code example above to see how this works. Here is our example again. 


  1: inverter : process
  2: begin
  3:   q <= not d;
  4:   wait on d;
  5: end inverter;

Let’s say point is on line 3 and we hit the TAB key to re-indent the line. Remember that the syntactic component list for that line is: 


((statement-block-intro . 20))

VHDL Mode looks up statement-block-intro in the vhdl-offsets-alist variable. Let’s say it finds the value ‘2’; it adds this to the running total (initialized to zero), yielding a running total indentation of 2 spaces.

Next VHDL Mode goes to buffer position 20 and asks for the current column. Since the begin keyword at buffer position 20 is in column zero, it adds ‘0’ to the running total. Since there is only one syntactic component on the list for this line, indentation calculation is complete, and the total indentation for the line is 2 spaces. Simple, huh?

Actually, the mode usually just does The Right Thing without you having to think about it in this much detail. But when customizing indentation, it’s helpful to understand the general indentation model being used.

To help you configure VHDL Mode, you can set the variable vhdl-echo-syntactic-information-p to non-nil so that the syntactic component list and calculated offset will always be echoed in the minibuffer when you hit TAB.

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

4 Customizing Indentation

The vhdl-offsets-alist variable is where you customize all your indentations. You simply need to decide what additional offset you want to add for every syntactic symbol. You can use the command C-c O (vhdl-set-offset) as the way to set offsets, both interactively and from your mode hook. Also, you can set up styles of indentation. Most likely, you’ll find one of the pre-defined styles will suit your needs, but if not, this section will describe how to set up basic editing configurations. See Styles, for an explanation of how to set up named styles.

As mentioned previously, the variable vhdl-offsets-alist is an association list between syntactic symbols and the offsets to be applied for those symbols. In fact, these offset values can be an integer, a function or variable name, or one of the following symbols: +, -, ++, --, *, or /. The symbol values have the following meanings:

So, for example, because most of the default offsets are defined in terms of +, -, and 0, if you like the general indentation style, but you use 2 spaces instead of 4 spaces per level, you can probably achieve your style just by changing vhdl-basic-offset like so (in your .emacs file): 


(setq vhdl-basic-offset 2)

To change indentation styles more radically, you will want to change the value associated with the syntactic symbols in the vhdl-offsets-alist variable. First, I’ll show you how to do that interactively, then I’ll describe how to make changes to your .emacs file so that your changes are more permanent.

Next: , Up: Customizing Indentation   [Contents][Index]

4.1 Interactive Customization

As an example of how to customize indentation, let’s change the style of the example above from: 


  1: inverter : process
  2: begin
  3:   q <= not d;
  4:   wait on d;
  5: end inverter;

to: 


  1: inverter : process
  2: begin
  3:     q <= not d;
  4:     wait on d;
  5: end inverter;

In other words, we want to change the indentation of the statements inside the inverter process. Notice that the construct we want to change starts on line 3. To change the indentation of a line, we need to see which syntactic component affect the offset calculations for that line. Hitting C-c C-x on line 3 yields: 


((statement-block-intro . 20))

So we know that to change the offset of the first signal assignment, we need to change the indentation for the statement-block-intro syntactic symbol. To do this interactively, just hit C-c O (vhdl-set-offset). This prompts you for the syntactic symbol to change, providing a reasonable default. In this case, the default is statement-block-intro, which is just the syntactic symbol we want to change!

After you hit return, VHDL Mode will then prompt you for the new offset value, with the old value as the default. The default in this case is ‘+’, so hit backspace to delete the ‘+’, then hit ‘++’ and RET. This will associate an offset of twice the basic indent with the syntactic symbol statement-block-intro in the vhdl-offsets-alist variable.

To check your changes quickly, just enter M-x vhdl-indent-defun to reindent the entire function. The example should now look like: 


  1: inverter : process
  2: begin
  3:     q <= not d;
  4:     wait on d;
  5: end inverter;

Notice how just changing the offset on line 3 is all we needed to do. Since the other affected lines are indented relative to line 3, they are automatically indented the way you’d expect. For more complicated examples, this may not always work. The general approach to take is to always start adjusting offsets for lines higher up in the file, then re-indent and see if any following lines need further adjustments.

Next: , Previous: , Up: Customizing Indentation   [Contents][Index]

4.2 Permanent Indentation

To make this change permanent, you need to add some lisp code to your .emacs file. VHDL Mode provides a vhdl-mode-hook that you can use to customize your language editing styles. This hook gets run as the last thing when you enter VHDL Mode.

Here’s a simplified example of what you can add to your .emacs file to make the changes described in the previous section (Interactive Customization) more permanent. See the Emacs manuals for more information on customizing Emacs via hooks. See Sample Init File, for a more complete sample .emacs file. 


(defun my-vhdl-mode-hook ()
  ;; my customizations for all of vhdl-mode
  (vhdl-set-offset 'statement-block-intro '++)
  ;; other customizations can go here
  )
(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)

For complex customizations, you will probably want to set up a style that groups all your customizations under a single name. See Styles.

The offset value can also be a function, and this is how power users gain enormous flexibility in customizing indentation. See Advanced Customizations.

Next: , Previous: , Up: Customizing Indentation   [Contents][Index]

4.3 Styles

Most people only need to edit code formatted in just a few well-defined and consistent styles. For example, their organization might impose a “blessed” style that all its programmers must conform to. Similarly, people who work on GNU software will have to use the GNU coding style on C code. Some shops are more lenient, allowing some variety of coding styles, and as programmers come and go, there could be a number of styles in use. For this reason, VHDL Mode makes it convenient for you to set up logical groupings of customizations called styles, associate a single name for any particular style, and pretty easily start editing new or existing code using these styles. This chapter describes how to set up styles and how to edit your C code using styles.

Next: , Up: Styles   [Contents][Index]

4.3.1 Built-in Styles

If you’re lucky, one of VHDL Mode’s built-in styles might be just what you’re looking for. Some of the most common VHDL styles are already built-in. These include:

  • GNU – the coding style in the IEEE Language Reference Manual.

If you’d like to experiment with these built-in styles you can simply type M-x vhdl-set-style RET in a VHDL Mode buffer.

You will be prompted for one of the above styles (with completion). Enter one of the styles and hit RET. Note however that setting a style in this way does not automatically re-indent your file.

Once you find a built-in style you like, you can make the change permanent by adding a call to your .emacs file. Let’s say for example that you want to use the IEEE style in all your files. You would add this: 


(defun my-vhdl-mode-hook ()
  ;; use IEEE style for all VHDL code
  (vhdl-set-style "IEEE")
  ;; other customizations can go here
  )
(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)

See Permanent Indentation.

Next: , Previous: , Up: Styles   [Contents][Index]

4.3.2 Adding Styles

If none of the built-in styles is appropriate, you’ll probably want to add a new style definition. Styles are kept in the vhdl-style-alist variable, but you probably won’t want to modify this variable directly. VHDL Mode provides a function, called vhdl-add-style, that you can use to easily add new styles or update existing styles. This function takes two arguments, a stylename string, and an association list description of style customizations. If stylename is not already in vhdl-style-alist, the new style is added, otherwise the style already associated with stylename is changed to the new description. This function also takes an optional third argument, which if non-nil, automatically institutes the new style in the current buffer.

The sample .emacs file provides a concrete example of how a new style can be added and automatically set. See Sample Init File.

Previous: , Up: Styles   [Contents][Index]

4.3.3 File Styles

The Emacs manual describes how you can customize certain variables on a per-file basis by including a Local Variable block at the end of the file. So far, you’ve only seen a functional interface to VHDL Mode, which is highly inconvenient for use in a Local Variable block. VHDL Mode provides two variables that make it easier for you to customize your style on a per-file basis.

The variable vhdl-file-style can be set to a style name string as described in Built-in Styles. When the file is visited, VHDL Mode will automatically set the file’s style to this style using vhdl-set-style.

Another variable, vhdl-file-offsets, takes an association list similar to what is allowed in vhdl-offsets-alist. When the file is visited, VHDL Mode will automatically institute these offsets using vhdl-set-offset. See Customizing Indentation.

Note that file style settings (i.e., vhdl-file-style) are applied before file offset settings (i.e., vhdl-file-offsets).

Previous: , Up: Customizing Indentation   [Contents][Index]

4.4 Advanced Customizations

For most users, VHDL Mode will support their coding styles with very little need for customizations. Usually, one of the standard styles defined in vhdl-style-alist will do the trick. Sometimes, one of the syntactic symbol offsets will need to be tweaked slightly, or perhaps vhdl-basic-offset will need to be changed. However, some styles require a more advanced ability for customization, and one of the real strengths of VHDL Mode is that the syntactic analysis model provides a very flexible framework for customizing indentation. This allows you to perform special indentation calculations for situations not handled by the mode directly.

Next: , Up: Advanced Customizations   [Contents][Index]

4.4.1 Custom Indentation Functions

One of the most common ways to customize VHDL Mode is by writing custom indentation functions and associating them with specific syntactic symbols (see Syntactic Symbols). VHDL Mode itself uses custom indentation functions to provide more sophisticated indentation, for example when lining up selected signal assignments: 


%%% TBD %%%

In this example, the statement-cont syntactic symbol has an offset of +, and vhdl-basic-offset is 2, so lines 4 through 6 are simply indented two spaces to the right of line 3. But perhaps we’d like VHDL Mode to be a little more intelligent so that it offsets the waveform descriptions relative to the signal assignment operator in line 3. To do this, we have to write a custom indentation function which finds the column of signal assignment operator on the first line of the statement. Here is the lisp code (from the vhdl-mode.el source file) that implements this: 


(defun vhdl-lineup-statement-cont (langelem)
  ;; line up statement-cont after the assignment operator
  (save-excursion
    (let* ((relpos (cdr langelem))
	   (assignp (save-excursion
		     (goto-char (vhdl-point 'boi))
		     (and (re-search-forward "\\(<\\|:\\)="
					     (vhdl-point 'eol) t)
			  (- (point) (vhdl-point 'boi)))))
	   (curcol (progn
		     (goto-char relpos)
		     (current-column)))
	   foundp)
      (while (and (not foundp)
		  (< (point) (vhdl-point 'eol)))
	(re-search-forward "\\(<\\|:\\)=\\|(" (vhdl-point 'eol) 'move)
	(if (vhdl-in-literal (cdr langelem))
	    (forward-char)
	  (if (= (preceding-char) ?\()
	      ;; skip over any parenthesized expressions
	      (goto-char (min (vhdl-point 'eol)
			      (scan-lists (point) 1 1)))
	    ;; found an assignment operator (not at eol)
	    (setq foundp (not (looking-at "\\s-*$"))))))
      (if (not foundp)
	  ;; there's no assignment operator on the line
	  vhdl-basic-offset
	;; calculate indentation column after assign and ws, unless
	;; our line contains an assignment operator
	(if (not assignp)
	    (progn
	      (forward-char)
	      (skip-chars-forward " \t")
	      (setq assignp 0)))
	(- (current-column) assignp curcol))
      )))

Custom indent functions take a single argument, which is a syntactic component cons cell (see Syntactic Analysis). The function returns an integer offset value that will be added to the running total indentation for the line. Note that what actually gets returned is the difference between the column that the signal assignment operator is on, and the column of the buffer relative position passed in the function’s argument. Remember that VHDL Mode automatically adds in the column of the component’s relative buffer position and we don’t want that value added into the final total twice.

Now, to associate the function vhdl-lineup-statement-cont with the statement-cont syntactic symbol, we can add something like the following to our vhdl-mode-hook: 


(vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont)

Now the function looks like this after re-indenting (using M-x vhdl-indent-defun): 


%%% TBD %%%

Custom indentation functions can be as simple or as complex as you like, and any syntactic symbol that appears in vhdl-offsets-alist can have a custom indentation function associated with it. Note however that using many custom indentation functions may have a performance impact on VHDL Mode.

Previous: , Up: Advanced Customizations   [Contents][Index]

4.4.2 Other Special Indentations

One other variable is available for you to customize VHDL Mode: vhdl-special-indent-hook. This is a standard hook variable that is called after every line is indented by VHDL Mode. You can use it to do any special indentation or line adjustments your style dictates, such as adding extra indentation to the port map clause in a component instantiation, etc. Note however, that you should not change point or mark inside your vhdl-special-indent-hook functions.

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

5 Syntactic Symbols

The complete list of recognized syntactic symbols is described in the vhdl-offsets-alist variable. This chapter will provide some examples to help clarify these symbols.

Most syntactic symbol names follow a general naming convention. When a line begins with a begin or end keyword, the syntactic symbol will contain the suffix -open or -close respectively.

Usually, a distinction is made between the first line that introduces a construct and lines that continue a construct, and the syntactic symbols that represent these lines will contain the suffix -intro or -cont respectively. As a sub-classification of this scheme, a line which is the first of a particular block construct will contain the suffix -block-intro.

<TBD> include the name and a brief example of every syntactic symbol currently recognized

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

6 Frequently Asked Questions

Q. How do I re-indent the whole file?

A. Visit the file and hit C-x h to mark the whole buffer. Then hit ESC C-\ to re-indent the entire region which you’ve just marked. Or just enter M-x vhdl-indent-buffer.



Q. How do I re-indent the entire function?

A. Hit ESC C-h to mark the entire function. Then hit ESC C-\ to re-indent the entire region which you’ve just marked.



Q. How do I re-indent the current block?

A. First move to the brace which opens the block with ESC C-u, then re-indent that expression with ESC C-q.



Q. How do I re-indent the current statement?

A. First move to the beginning of the statement with ESC a, then re-indent that expression with ESC C-q.



Q. I put (vhdl-set-offset 'statement-cont 0) in my .emacs file but I get an error saying that vhdl-set-offset’s function definition is void.

A. This means that VHDL Mode wasn’t loaded into your Emacs session by the time the vhdl-set-offset call was reached, mostly likely because VHDL Mode is being autoloaded. Instead of putting the vhdl-set-offset line in your top-level .emacs file, put it in your vhdl-mode-hook, or simply add the following to the top of your .emacs file: 


(require 'vhdl-mode)

See the sample .emacs file Sample Init File for details.

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

7 Getting the latest VHDL Mode release

The best way to be sure you always have the latest VHDL Mode release is to join the vhdl-mode-announce mailing list. If you are a brave soul, and wish to participate in beta testing of new releases of VHDL Mode, you may also join the vhdl-mode-victims mailing list. Send email to the maintainer reto@gnu.org to join either of these lists.

The official Emacs VHDL Mode Home Page can be found at https://www.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html.

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

8 Sample Init File

Most customizations can be done using the “Customize” entry in the VHDL Mode menu, which requires no editing of the .emacs file. If you want to customize indentation, here you go: 

;; Here's a sample .emacs file that might help you along the way.  Just
;; copy this region and paste it into your .emacs file.  You may want to
;; change some of the actual values.

(defconst my-vhdl-style
  '((vhdl-tab-always-indent        . t)
    (vhdl-comment-only-line-offset . 4)
    (vhdl-offsets-alist            . ((arglist-close    . vhdl-lineup-arglist)
                                      (statement-cont   . 0)
                                      (case-alternative . 4)
                                      (block-open       . 0)))
    (vhdl-echo-syntactic-information-p . t)
    )
  "My VHDL Programming Style")

;; Customizations for vhdl-mode
(defun my-vhdl-mode-hook ()
  ;; add my personal style and set it for the current buffer
  (vhdl-add-style "PERSONAL" my-vhdl-style t)
  ;; offset customizations not in my-vhdl-style
  (vhdl-set-offset 'statement-case-intro '++)
  ;; other customizations
  (setq tab-width 8
        ;; this will make sure spaces are used instead of tabs
        indent-tabs-mode nil)
  ;; key bindings for VHDL are put in vhdl-mode-map
  (define-key vhdl-mode-map "\C-m" 'newline-and-indent)
  )

(add-hook 'vhdl-mode-hook 'my-vhdl-mode-hook)

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

9 Limitations and Known Bugs

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

10 Mailing Lists and Submitting Bug Reports

To report bugs, use the C-c C-b (vhdl-submit-bug-report) command. This provides vital information I need to reproduce your problem. Make sure you include a concise, but complete code example. Please try to boil your example down to just the essential code needed to reproduce the problem, and include an exact recipe of steps needed to expose the bug. Be especially sure to include any code that appears before your bug example.

For other help or suggestions, send a message to reto@gnu.org.

Send an add message to reto@gnu.org to get on the vhdl-mode-victims beta testers list where beta releases of VHDL Mode are posted. Note that you shouldn’t expect beta releases to be as stable as public releases.

There is also an announce only list where the latest public releases of VHDL Mode are posted. Send an add message to reto@gnu.org to be added to this list.

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

Appendix A GNU Free Documentation License

Version 1.3, 3 November 2008 
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
https://fsf.org/

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
  1. PREAMBLE

    The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

    This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

    We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

  2. APPLICABILITY AND DEFINITIONS

    This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

    A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

    A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

    The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

    The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

    A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

    Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

    The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

    The “publisher” means any person or entity that distributes copies of the Document to the public.

    A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

    The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

  3. VERBATIM COPYING

    You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

    You may also lend copies, under the same conditions stated above, and you may publicly display copies.

  4. COPYING IN QUANTITY

    If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

    If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

    If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

    It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

  5. MODIFICATIONS

    You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

    1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
    2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
    3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
    4. Preserve all the copyright notices of the Document.
    5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
    6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
    7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
    8. Include an unaltered copy of this License.
    9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
    10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
    11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
    12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
    13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
    14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
    15. Preserve any Warranty Disclaimers.

    If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

    You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

    You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

    The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

  6. COMBINING DOCUMENTS

    You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

    The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

    In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”

  7. COLLECTIONS OF DOCUMENTS

    You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

    You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

  8. AGGREGATION WITH INDEPENDENT WORKS

    A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

    If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

  9. TRANSLATION

    Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

    If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

  10. TERMINATION

    You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

    However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

    Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

    Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.

  11. FUTURE REVISIONS OF THIS LICENSE

    The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/licenses/.

    Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.

  12. RELICENSING

    “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

    “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

    “Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

    An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

    The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: 

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this: 

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

Concept Index

Jump to:   -  
A   B   C   F   G   H   I   L   M   N   O   P   R   S   T   V  
Index Entry  Section
-
-block-intro syntactic symbols: Syntactic Symbols
-close syntactic symbols: Syntactic Symbols
-cont syntactic symbols: Syntactic Symbols
-intro syntactic symbols: Syntactic Symbols
-open syntactic symbols: Syntactic Symbols
A
Adding Styles: Adding Styles
Advanced Customizations: Advanced Customizations
announcement mailing list: Mailing Lists and Submitting Bug Reports
B
basic-offset (vhdl-): Customizing Indentation
beta testers mailing list: Mailing Lists and Submitting Bug Reports
Built-in Styles: Built-in Styles
C
comment only line: Syntactic Analysis
Custom Indentation Functions: Custom Indentation Functions
custom indentation functions: Custom Indentation Functions
Customizing Indentation: Customizing Indentation
F
File Styles: File Styles
Frequently Asked Questions: Frequently Asked Questions
G
Getting Connected: Getting Connected
Getting the latest VHDL Mode release: Getting the latest VHDL Mode release
H
hooks: Permanent Customization
I
IEEE style: Built-in Styles
Indentation Calculation: Indentation Calculation
Interactive Customization: Interactive Customization
Introduction: Introduction
L
Limitations and Known Bugs: Limitations and Known Bugs
local variables: File Styles
M
Mailing Lists and Submitting Bug Reports: Mailing Lists and Submitting Bug Reports
N
New Indentation Engine: New Indentation Engine
O
Other Special Indentations: Other Special Indentations
P
Permanent Indentation: Permanent Customization
R
relative buffer position: Syntactic Analysis
relative buffer position: Syntactic Analysis
S
Sample init file: Sample Init File
set-offset (vhdl-): Customizing Indentation
statement-cont syntactic symbol: Custom Indentation Functions
Styles: Styles
Syntactic Analysis: Syntactic Analysis
syntactic component: Syntactic Analysis
syntactic component list: Syntactic Analysis
syntactic symbol: Syntactic Analysis
Syntactic Symbols: Syntactic Symbols
T
TAB: Indentation Calculation
V
vhdl-basic-offset: Customizing Indentation
vhdl-set-offset: Customizing Indentation
Jump to:   -  
A   B   C   F   G   H   I   L   M   N   O   P   R   S   T   V  

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

Command Index

Since all VHDL Mode commands are prepended with the string ‘vhdl-’, each appears under its vhdl-<thing> name and its <thing> (vhdl-) name.

Jump to:   A   I   L   N   S   V  
Index Entry  Section
A
add-style (vhdl-): Adding Styles
I
indent-defun (vhdl-): Interactive Customization
L
lineup-statement-cont (vhdl-): Custom Indentation Functions
N
newline-and-indent: Frequently Asked Questions
S
set-offset (vhdl-): Interactive Customization
set-offset (vhdl-): File Styles
set-style (vhdl-): Built-in Styles
show-syntactic-information (vhdl-): Syntactic Analysis
submit-bug-report (vhdl-): Mailing Lists and Submitting Bug Reports
V
vhdl-add-style: Adding Styles
vhdl-indent-defun: Interactive Customization
vhdl-indent-defun: Custom Indentation Functions
vhdl-lineup-statement-cont: Custom Indentation Functions
vhdl-set-offset: Interactive Customization
vhdl-set-offset: File Styles
vhdl-set-style: Built-in Styles
vhdl-show-syntactic-information: Syntactic Analysis
vhdl-submit-bug-report: Mailing Lists and Submitting Bug Reports
vhdl-version: Introduction
Jump to:   A   I   L   N   S   V  

Next: , Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

Key Index

Jump to:   C   E   L   R   T  
Index Entry  Section
C
C-c C-b: Mailing Lists and Submitting Bug Reports
C-c C-x: Syntactic Analysis
C-c O: Interactive Customization
C-x h: Frequently Asked Questions
E
ESC C-q: Frequently Asked Questions
ESC C-u: Frequently Asked Questions
ESC C-\: Frequently Asked Questions
L
LFD: Frequently Asked Questions
R
RET: Frequently Asked Questions
T
TAB: Indentation Calculation
Jump to:   C   E   L   R   T  

Previous: , Up: VHDL Mode, an Emacs mode for editing VHDL code   [Contents][Index]

Variable Index

Since all VHDL Mode variables are prepended with the string ‘vhdl-’, each appears under its vhdl-<thing> name and its <thing> (vhdl-) name.

Jump to:   B   E   F   O   S   V  
Index Entry  Section
B
basic-offset (vhdl-): Advanced Customizations
E
echo-syntactic-information-p (vhdl-): Indentation Calculation
F
file-offsets (vhdl-): File Styles
file-style (vhdl-): File Styles
O
offsets-alist (vhdl-): Syntactic Analysis
offsets-alist (vhdl-): Indentation Calculation
offsets-alist (vhdl-): File Styles
offsets-alist (vhdl-): Custom Indentation Functions
S
special-indent-hook (vhdl-): Other Special Indentations
style-alist (vhdl-): Adding Styles
style-alist (vhdl-): Advanced Customizations
V
vhdl-basic-offset: Advanced Customizations
vhdl-echo-syntactic-information-p: Indentation Calculation
vhdl-file-offsets: File Styles
vhdl-file-style: File Styles
vhdl-mode-hook: Permanent Customization
vhdl-offsets-alist: Syntactic Analysis
vhdl-offsets-alist: Indentation Calculation
vhdl-offsets-alist: File Styles
vhdl-offsets-alist: Custom Indentation Functions
vhdl-offsets-alist: Syntactic Symbols
vhdl-special-indent-hook: Other Special Indentations
vhdl-style-alist: Adding Styles
vhdl-style-alist: Advanced Customizations
Jump to:   B   E   F   O   S   V  

Footnotes

(1)

The line numbers in this and future examples don’t actually appear in the buffer.