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.”
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.
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.
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.
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.
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:
+ – 1 x vhdl-basic-offset
- – -1 x vhdl-basic-offset
++ – 2 x vhdl-basic-offset
-- – -2 x vhdl-basic-offset
* – 0.5 x vhdl-basic-offset
/ – -0.5 x vhdl-basic-offset
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.
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.
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.
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.
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:
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)
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.
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).
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.
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.
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.
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
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 thatvhdl-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 thevhdl-set-offsetline in your top-level .emacs file, put it in yourvhdl-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.
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.
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)
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.
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.
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.
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.
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.
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:
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.
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.”
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.
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.
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.
“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.
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.
Since all VHDL Mode commands are prepended with the string
‘vhdl-’, each appears under its vhdl-<thing> name and its
<thing> (vhdl-) name.
Since all VHDL Mode variables are prepended with the string
‘vhdl-’, each appears under its vhdl-<thing> name and its
<thing> (vhdl-) name.