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–2022 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.”

1 Introduction
**************

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

   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
*******************

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

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., ‘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.

   ---------- Footnotes ----------

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

3.2 Indentation Calculation
===========================

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

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

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

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

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

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

     ((statement-block-intro . 20))

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

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

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

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

4 Customizing Indentation
*************************

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

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

   • ‘+’ – 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.

4.1 Interactive Customization
=============================

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

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

to:

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

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

     ((statement-block-intro . 20))

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

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

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

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

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

4.2 Permanent Indentation
=========================

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

   Here’s a simplified example of what you can add to your ‘.emacs’ file
to make the changes described in the previous section (see 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.

4.3 Styles
==========

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

4.3.1 Built-in Styles
---------------------

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

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

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

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

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

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

See Permanent Customization.

4.3.2 Adding Styles
-------------------

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

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

4.3.3 File Styles
-----------------

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

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

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

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

4.4 Advanced Customizations
===========================

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

4.4.1 Custom Indentation Functions
----------------------------------

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

     %%% TBD %%%

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

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

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

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

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

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

     %%% TBD %%%

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

4.4.2 Other Special Indentations
--------------------------------

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

5 Syntactic Symbols
*******************

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

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

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

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

6 Frequently Asked Questions
****************************

     *Q.* _How do I re-indent the whole file?_

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

     *Q.* _How do I re-indent the entire function?_

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

     *Q.* _How do I re-indent the current block?_

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

     *Q.* _How do I re-indent the current statement?_

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

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

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

          (require 'vhdl-mode)

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

7 Getting the latest VHDL Mode release
**************************************

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

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

8 Sample Init File
******************

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

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

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

     ;; Customizations for vhdl-mode
     (defun my-vhdl-mode-hook ()
       ;; add my personal style and set it for the current buffer
       (vhdl-add-style "PERSONAL" my-vhdl-style t)
       ;; offset customizations not in my-vhdl-style
       (vhdl-set-offset 'statement-case-intro '++)
       ;; other customizations
       (setq tab-width 8
             ;; this will make sure spaces are used instead of tabs
             indent-tabs-mode nil)
       ;; 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’ (‘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.

Appendix A GNU Free Documentation License
*****************************************

                     Version 1.3, 3 November 2008

     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     <https://fsf.org/>

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

  0. PREAMBLE

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

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

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

  1. 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.

  2. 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.

  3. 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.

  4. MODIFICATIONS

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

       A. 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.

       B. 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.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. 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.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document’s
          license notice.

       H. Include an unaltered copy of this License.

       I. 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.

       J. 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.

       K. 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.

       L. 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.

       M. Delete any section Entitled “Endorsements”.  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          “Endorsements” or to conflict in title with any Invariant
          Section.

       O. 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.

  5. 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.”

  6. 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.

  7. 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.

  8. TRANSLATION

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

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

  9. TERMINATION

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

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

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

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

  10. FUTURE REVISIONS OF THIS LICENSE

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

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

  11. RELICENSING

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

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

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

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

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

ADDENDUM: How to use this License for your documents
====================================================

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

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

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

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

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

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

Command Index
*************

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

Variable Index
**************

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