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–2017 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.”
|New Indentation Engine|
|Frequently Asked Questions|
|Getting the latest VHDL Mode release|
|Sample Init File|
|Limitations and Known Bugs|
|Mailing Lists and Submitting Bug Reports|
|GNU Free Documentation License||The license for this documentation.|
|Command Index||Command Index|
|Key Index||Key Index|
|Variable Index||Variable Index|
This manual will describe the following:
- How to get started using VHDL Mode.
- How the indentation engine works.
- How to customize the indentation engine.
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.
2 Getting Connected
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.
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.,
block-close, etc. See Syntactic Symbols, for a complete list
of currently recognized syntactic symbols and their semantics. Also,
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.
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
variable, which is an association list of syntactic symbols and the
offsets to apply for those symbols. These offsets are added to the
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;
((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
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.
4 Customizing Indentation
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
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:
/. The symbol
values have the following meanings:
+– 1 x
-– -1 x
++– 2 x
--– -2 x
*– 0.5 x
/– -0.5 x
So, for example, because most of the default offsets are defined in
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.
4.1 Interactive Customization
1: inverter : process 2: begin 3: q <= not d; 4: wait on d; 5: end inverter;
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
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
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
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.
4.2 Permanent Indentation
To make this change permanent, you need to add some lisp code to your
.emacs file. VHDL Mode provides a
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.
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.
4.3.1 Built-in Styles
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)
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
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-
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.
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.
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
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.,
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
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.
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
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 lne. 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.
(vhdl-set-offset 'statement-cont 'vhdl-lineup-statement-cont)
%%% 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
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
mark inside your
5 Syntactic Symbols
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
-cont respectively. As a sub-classification of this scheme, a
line which is the first of a particular block construct will contain the
<TBD> include the name and a brief example of every syntactic symbol currently recognized
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-offsetcall was reached, mostly likely because VHDL Mode is being autoloaded. Instead of putting the
vhdl-set-offsetline 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.
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
list. Send email to the maintainer email@example.com to join
either of these lists.
The official Emacs VHDL Mode Home Page can be found at http://www.iis.ee.ethz.ch/~zimmi/emacs/vhdl-mode.html.
8 Sample Init File
;; 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) ;; keybindings 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)
9 Limitations and Known Bugs
- Re-indenting large regions or expressions can be slow.
10 Mailing Lists and Submitting Bug Reports
To report bugs, use the C-c C-b (
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 firstname.lastname@example.org.
Send an add message to email@example.com 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 firstname.lastname@example.org to be added to this list.
Appendix A GNU Free Documentation License
Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. http://fsf.org/ Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
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.
- 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.
- 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.
- 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.
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:
- 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.
- 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.
- State on the Title page the name of the publisher of the Modified Version, as the publisher.
- Preserve all the copyright notices of the Document.
- Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
- 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.
- Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
- Include an unaltered copy of this License.
- 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.
- 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.
- 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.
- 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.
- Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
- Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
- 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.
- 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.”
- 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.
- 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.
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.
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.
- 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 http://www.gnu.org/copyleft/.
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.
“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.
- -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
- Adding Styles: Adding Styles
- Advanced Customizations: Advanced Customizations
- announcement mailing list: Mailing Lists and Submitting Bug Reports
- basic-offset (vhdl-): Customizing Indentation
- beta testers mailing list: Mailing Lists and Submitting Bug Reports
- Built-in Styles: Built-in Styles
- comment only line: Syntactic Analysis
- custom indentation functions: Custom Indentation Functions
- Custom Indentation Functions: Custom Indentation Functions
- Customizing Indentation: Customizing Indentation
- File Styles: File Styles
- Frequently Asked Questions: Frequently Asked Questions
- Getting Connected: Getting Connected
- Getting the latest VHDL Mode release: Getting the latest VHDL Mode release
- hooks: Permanent Customization
- IEEE style: Built-in Styles
- Indentation Calculation: Indentation Calculation
- Interactive Customization: Interactive Customization
- Introduction: Introduction
- Limitations and Known Bugs: Limitations and Known Bugs
- local variables: File Styles
- Mailing Lists and Submitting Bug Reports: Mailing Lists and Submitting Bug Reports
- New Indentation Engine: New Indentation Engine
- Other Special Indentations: Other Special Indentations
- Permanent Indentation: Permanent Customization
- relative buffer position: Syntactic Analysis
- 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
- TAB: Indentation Calculation
- vhdl-basic-offset: Customizing Indentation
- vhdl-set-offset: Customizing Indentation
Since all VHDL Mode commands are prepended with the string
‘vhdl-’, each appears under its
vhdl-<thing> name and its
<thing> (vhdl-) name.
add-style (vhdl-): Adding Styles
indent-defun (vhdl-): Interactive Customization
lineup-statement-cont (vhdl-): Custom Indentation Functions
newline-and-indent: Frequently Asked Questions
set-offset (vhdl-): File Styles
set-offset (vhdl-): Interactive Customization
set-style (vhdl-): Built-in Styles
show-syntactic-information (vhdl-): Syntactic Analysis
submit-bug-report (vhdl-): Mailing Lists and Submitting Bug Reports
vhdl-add-style: Adding Styles
vhdl-indent-defun: Custom Indentation Functions
vhdl-indent-defun: Interactive Customization
vhdl-lineup-statement-cont: Custom Indentation Functions
vhdl-set-offset: File Styles
vhdl-set-offset: Interactive Customization
vhdl-set-style: Built-in Styles
vhdl-show-syntactic-information: Syntactic Analysis
vhdl-submit-bug-report: Mailing Lists and Submitting Bug Reports
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
ESC C-\: Frequently Asked Questions
ESC C-q: Frequently Asked Questions
ESC C-u: Frequently Asked Questions
LFD: Frequently Asked Questions
RET: Frequently Asked Questions
TAB: Indentation Calculation
Since all VHDL Mode variables are prepended with the string
‘vhdl-’, each appears under its
vhdl-<thing> name and its
<thing> (vhdl-) name.
basic-offset (vhdl-): Advanced Customizations
echo-syntactic-information-p (vhdl-): Indentation Calculation
file-offsets (vhdl-): File Styles
file-style (vhdl-): File Styles
offsets-alist (vhdl-): Custom Indentation Functions
offsets-alist (vhdl-): File Styles
offsets-alist (vhdl-): Indentation Calculation
offsets-alist (vhdl-): Syntactic Analysis
special-indent-hook (vhdl-): Other Special Indentations
style-alist (vhdl-): Advanced Customizations
style-alist (vhdl-): Adding Styles
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 Symbols
vhdl-offsets-alist: Custom Indentation Functions
vhdl-offsets-alist: File Styles
vhdl-offsets-alist: Indentation Calculation
vhdl-offsets-alist: Syntactic Analysis
vhdl-special-indent-hook: Other Special Indentations
vhdl-style-alist: Advanced Customizations
vhdl-style-alist: Adding Styles
 The line numbers in this and future examples don't actually appear in the buffer.