Freeware (IRIX)  »  Info Pages
find in page

elisp : Library Headers

table of contents

  Introduction
  Coding Conventions
  Lisp Data Types
  Numbers
  Strings and Characters
  Lists
  Sequences Arrays Vectors
  Hash Tables
  Symbols
  Evaluation
  Control Structures
  Variables
  Functions
  Macros
  Customization
  Loading
  Byte Compilation
  Advising Functions
  Debugging
  Read and Print
  Minibuffers
  Command Loop
  Keymaps
  Modes
  Documentation
  Files
  Backups and Auto-Saving
  Buffers
  Windows
  Frames
  Positions
  Markers
  Text
  Non-ASCII Characters
  Searching and Matching
  Syntax Tables
  Abbrevs
  Processes
  Display
  Calendar
  System Interface
  Antinews
  GNU Free Documentation License
  GPL
  Tips
  GNU Emacs Internals
  Standard Errors
  Standard Buffer-Local Variables
  Standard Keymaps
  Standard Hooks
  Index
  New Symbols
  Caveats
  Lisp History
  Conventions
  Acknowledgements
  Some Terms
  nil and t
  Evaluation Notation
  Printing Notation
  Error Messages
  Buffer Text Notation
  Format of Descriptions
  Coding Conventions
  Compilation Tips
  Documentation Tips
  Comment Tips
  Library Headers
  A Sample Function Description
  A Sample Variable Description
  Printed Representation
  Comments
  Programming Types
  Editing Types
  Type Predicates
  Equality Predicates
  Integer Type
  Floating Point Type
  Character Type
  Sequence Type
  Cons Cell Type
  Array Type
  String Type
  Vector Type
  Symbol Type
  Function Type
  Macro Type
  Primitive Function Type
  Byte-Code Type
  Autoload Type
  Dotted Pair Notation
  Association List Type
  Buffer Type
  Window Type
  Window Configuration Type
  Marker Type
  Process Type
  Stream Type
  Keymap Type
  Overlay Type
  Integer Basics
  Float Basics
  Predicates on Numbers
  Comparison of Numbers
  Arithmetic Operations
  Bitwise Operations
  Numeric Conversions
  Math Functions
  Random Numbers
  String Basics
  Predicates for Strings
  Creating Strings
  Text Comparison
  String Conversion
  Formatting Strings
  Case Conversion
  Cons Cells
  Lists as Boxes
  List-related Predicates
  List Elements
  Building Lists
  Modifying Lists
  Sets And Lists
  Association Lists
  Setcar
  Setcdr
  Rearrangement
  Sequence Functions
  Arrays
  Array Functions
  Vectors
  Symbol Components
  Definitions
  Creating Symbols
  Property Lists
  Intro Eval
  Eval
  Forms
  Quoting
  Self-Evaluating Forms
  Symbol Forms
  Classifying Lists
  Function Forms
  Macro Forms
  Special Forms
  Autoloading
  Sequencing
  Conditionals
  Combining Conditions
  Iteration
  Nonlocal Exits
  Catch and Throw
  Examples of Catch
  Errors
  Cleanups
  Signaling Errors
  Processing of Errors
  Handling Errors
  Error Symbols
  Global Variables
  Constant Variables
  Local Variables
  Void Variables
  Defining Variables
  Accessing Variables
  Setting Variables
  Variable Scoping
  Buffer-Local Variables
  Scope
  Extent
  Impl of Scope
  Using Scoping
  Intro to Buffer-Local
  Creating Buffer-Local
  Default Value
  What Is a Function
  Lambda Expressions
  Function Names
  Defining Functions
  Calling Functions
  Mapping Functions
  Anonymous Functions
  Function Cells
  Related Topics
  Lambda Components
  Simple Lambda
  Argument List
  Function Documentation
  Simple Macro
  Expansion
  Compiling Macros
  Defining Macros
  Backquote
  Problems with Macros
  How Programs Do Loading
  Autoload
  Named Features
  Repeated Loading
  Compilation Functions
  Disassembly
  Simple Advice
  Defining Advice
  Computed Advice
  Activation of Advice
  Enabling Advice
  Preactivation
  Argument Access in Advice
  Subr Arguments
  Combined Definition
  Debugger
  Syntax Errors
  Compilation Errors
  Edebug
  Error Debugging
  Function Debugging
  Explicit Debug
  Using Debugger
  Debugger Commands
  Invoking the Debugger
  Internals of Debugger
  Excess Open
  Excess Close
  Streams Intro
  Input Streams
  Input Functions
  Output Streams
  Output Functions
  Intro to Minibuffers
  Text from Minibuffer
  Object from Minibuffer
  Completion
  Yes-or-No Queries
  Minibuffer Misc
  Basic Completion
  Minibuffer Completion
  Completion Commands
  High-Level Completion
  Reading File Names
  Programmed Completion
  Command Overview
  Defining Commands
  Interactive Call
  Command Loop Info
  Input Events
  Reading Input
  Waiting
  Quitting
  Prefix Command Arguments
  Recursive Editing
  Disabling Commands
  Command History
  Keyboard Macros
  Using Interactive
  Interactive Codes
  Interactive Examples
  Keymap Terminology
  Format of Keymaps
  Creating Keymaps
  Inheritance and Keymaps
  Prefix Keys
  Menu Keymaps
  Active Keymaps
  Key Lookup
  Functions for Key Lookup
  Changing Key Bindings
  Key Binding Commands
  Scanning Keymaps
  Major Modes
  Minor Modes
  Mode Line Format
  Hooks
  Major Mode Conventions
  Example Major Modes
  Auto Major Mode
  Mode Help
  Minor Mode Conventions
  Keymaps and Minor Modes
  Mode Line Data
  Mode Line Variables
  %-Constructs
  Documentation Basics
  Accessing Documentation
  Keys in Documentation
  Describing Characters
  Help Functions
  Visiting Files
  Saving Buffers
  Reading from Files
  Writing to Files
  File Locks
  Information about Files
  Contents of Directories
  Changing Files
  File Names
  Visiting Functions
  Subroutines of Visiting
  Testing Accessibility
  Kinds of Files
  File Attributes
  File Name Components
  Directory Names
  Relative File Names
  File Name Expansion
  Unique File Names
  File Name Completion
  Backup Files
  Auto-Saving
  Reverting
  Making Backups
  Rename or Copy
  Numbered Backups
  Backup Names
  Buffer Basics
  Buffer Names
  Buffer File Name
  Buffer Modification
  Modification Time
  Read Only Buffers
  The Buffer List
  Creating Buffers
  Killing Buffers
  Current Buffer
  Basic Windows
  Splitting Windows
  Deleting Windows
  Selecting Windows
  Cyclic Window Ordering
  Buffers and Windows
  Displaying Buffers
  Window Point
  Window Start
  Vertical Scrolling
  Horizontal Scrolling
  Size of Window
  Resizing Windows
  Window Configurations
  Creating Frames
  Multiple Displays
  Frame Parameters
  Frame Titles
  Deleting Frames
  Finding All Frames
  Frames and Windows
  Minibuffers and Frames
  Input Focus
  Visibility of Frames
  Raising and Lowering
  Frame Configurations
  Mouse Tracking
  Mouse Position
  Pop-Up Menus
  Dialog Boxes
  Pointer Shapes
  Window System Selections
  Color Names
  Resources
  Display Feature Testing
  Point
  Motion
  Excursions
  Narrowing
  Character Motion
  Word Motion
  Buffer End Motion
  Text Lines
  Screen Lines
  List Motion
  Skipping Characters
  Overview of Markers
  Predicates on Markers
  Creating Markers
  Information from Markers
  Moving Markers
  The Mark
  The Region
  Near Point
  Buffer Contents
  Insertion
  Commands for Insertion
  Deletion
  User-Level Deletion
  The Kill Ring
  Undo
  Auto Filling
  Filling
  Margins
  Sorting
  Indentation
  Columns
  Case Changes
  Text Properties
  Substitution
  Transposition
  Registers
  Change Hooks
  Kill Ring Concepts
  Kill Functions
  Yank Commands
  Low-Level Kill Ring
  Internals of Kill Ring
  Primitive Indent
  Mode-Specific Indent
  Region Indent
  Relative Indent
  Indent Tabs
  Motion by Indent
  Examining Properties
  Changing Properties
  Property Search
  Special Properties
  Format Properties
  Sticky Properties
  Saving Properties
  Lazy Properties
  Clickable Text
  Fields
  Not Intervals
  Text Representations
  Converting Representations
  Selecting a Representation
  Character Codes
  Character Sets
  Chars and Bytes
  Splitting Characters
  Scanning Charsets
  Translation of Characters
  Coding Systems
  Input Methods
  Locales
  String Search
  Regular Expressions
  Regexp Search
  Match Data
  Saving Match Data
  Standard Regexps
  Searching and Case
  Syntax of Regexps
  Regexp Example
  Syntax Descriptors
  Syntax Table Functions
  Parsing Expressions
  Standard Syntax Tables
  Syntax Table Internals
  Syntax Class Table
  Syntax Flags
  Abbrev Mode
  Abbrev Tables
  Defining Abbrevs
  Abbrev Files
  Abbrev Expansion
  Standard Abbrev Tables
  Subprocess Creation
  Synchronous Processes
  Asynchronous Processes
  Deleting Processes
  Process Information
  Input to Processes
  Signals to Processes
  Output from Processes
  Sentinels
  Network
  Process Buffers
  Filter Functions
  Accepting Output
  Starting Up
  Getting Out
  System Environment
  Terminal Input
  Terminal Output
  Flow Control
  Batch Mode
  Startup Summary
  Init File
  Terminal-Specific
  Command-Line Arguments
  Killing Emacs
  Suspending Emacs
  Refresh Screen
  Truncation
  The Echo Area
  Selective Display
  Overlay Arrow
  Temporary Displays
  Waiting
  Blinking
  Usual Display
  Beeping
  Window Systems
  Building Emacs
  Pure Storage
  Garbage Collection
  Object Internals
  Writing Emacs Primitives
  Buffer Internals
  Window Internals
  Process Internals

Conventional Headers for Emacs Libraries
========================================

   Emacs has conventions for using special comments in Lisp libraries
to divide them into sections and give information such as who wrote
them.  This section explains these conventions.

   We'll start with an example, a package that is included in the Emacs
distribution.

   Parts of this example reflect its status as part of Emacs; for
example, the copyright notice lists the Free Software Foundation as the
copyright holder, and the copying permission says the file is part of
Emacs.  When you write a package and post it, the copyright holder would
be you (unless your employer claims to own it instead), and you should
get the suggested copying permission from the end of the GNU General
Public License itself.  Don't say your file is part of Emacs if we
haven't installed it in Emacs yet!

   With that warning out of the way, on to the example:

     ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers
     
     ;; Copyright (C) 1992 Free Software Foundation, Inc.
     
     ;; Author: Eric S. Raymond 
     ;; Maintainer: Eric S. Raymond 
     ;; Created: 14 Jul 1992
     ;; Version: 1.2
     ;; Keywords: docs
     
     ;; This file is part of GNU Emacs.
     ...
     ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     ;; Boston, MA 02111-1307, USA.

   The very first line should have this format:

     ;;; FILENAME --- DESCRIPTION

The description should be complete in one line.

   After the copyright notice come several "header comment" lines, each
beginning with `;; HEADER-NAME:'.  Here is a table of the conventional
possibilities for HEADER-NAME:

`Author'
     This line states the name and net address of at least the principal
     author of the library.

     If there are multiple authors, you can list them on continuation
     lines led by `;;' and a tab character, like this:

          ;; Author: Ashwin Ram 
          ;;      Dave Sill 
          ;;      Dave Brennan 
          ;;      Eric Raymond 

`Maintainer'
     This line should contain a single name/address as in the Author
     line, or an address only, or the string `FSF'.  If there is no
     maintainer line, the person(s) in the Author field are presumed to
     be the maintainers.  The example above is mildly bogus because the
     maintainer line is redundant.

     The idea behind the `Author' and `Maintainer' lines is to make
     possible a Lisp function to "send mail to the maintainer" without
     having to mine the name out by hand.

     Be sure to surround the network address with `<...>' if you
     include the person's full name as well as the network address.

`Created'
     This optional line gives the original creation date of the file.
     For historical interest only.

`Version'
     If you wish to record version numbers for the individual Lisp
     program, put them in this line.

`Adapted-By'
     In this header line, place the name of the person who adapted the
     library for installation (to make it fit the style conventions, for
     example).

`Keywords'
     This line lists keywords for the `finder-by-keyword' help command.
     Please use that command to see a list of the meaningful keywords.

     This field is important; it's how people will find your package
     when they're looking for things by topic area.  To separate the
     keywords, you can use spaces, commas, or both.

   Just about every Lisp library ought to have the `Author' and
`Keywords' header comment lines.  Use the others if they are
appropriate.  You can also put in header lines with other header
names--they have no standard meanings, so they can't do any harm.

   We use additional stylized comments to subdivide the contents of the
library file.  These should be separated by blank lines from anything
else.  Here is a table of them:

`;;; Commentary:'
     This begins introductory comments that explain how the library
     works.  It should come right after the copying permissions,
     terminated by a `Change Log', `History' or `Code' comment line.
     This text is used by the Finder package, so it should make sense
     in that context.

`;;; Documentation'
     This has been used in some files in place of `;;; Commentary:',
     but `;;; Commentary:' is preferred.

`;;; Change Log:'
     This begins change log information stored in the library file (if
     you store the change history there).  For Lisp files distributed
     with Emacs, the change history is kept in the file `ChangeLog' and
     not in the source file at all; these files generally do not have a
     `;;; Change Log:' line.  `History' is an alternative to `Change
     Log'.

`;;; Code:'
     This begins the actual code of the program.

`;;; FILENAME ends here'
     This is the "footer line"; it appears at the very end of the file.
     Its purpose is to enable people to detect truncated versions of
     the file from the lack of a footer line.

back to top
elisp : Library Headers

table of contents

  Introduction
  Coding Conventions
  Lisp Data Types
  Numbers
  Strings and Characters
  Lists
  Sequences Arrays Vectors
  Hash Tables
  Symbols
  Evaluation
  Control Structures
  Variables
  Functions
  Macros
  Customization
  Loading
  Byte Compilation
  Advising Functions
  Debugging
  Read and Print
  Minibuffers
  Command Loop
  Keymaps
  Modes
  Documentation
  Files
  Backups and Auto-Saving
  Buffers
  Windows
  Frames
  Positions
  Markers
  Text
  Non-ASCII Characters
  Searching and Matching
  Syntax Tables
  Abbrevs
  Processes
  Display
  Calendar
  System Interface
  Antinews
  GNU Free Documentation License
  GPL
  Tips
  GNU Emacs Internals
  Standard Errors
  Standard Buffer-Local Variables
  Standard Keymaps
  Standard Hooks
  Index
  New Symbols
  Caveats
  Lisp History
  Conventions
  Acknowledgements
  Some Terms
  nil and t
  Evaluation Notation
  Printing Notation
  Error Messages
  Buffer Text Notation
  Format of Descriptions
  Coding Conventions
  Compilation Tips
  Documentation Tips
  Comment Tips
  Library Headers
  A Sample Function Description
  A Sample Variable Description
  Printed Representation
  Comments
  Programming Types
  Editing Types
  Type Predicates
  Equality Predicates
  Integer Type
  Floating Point Type
  Character Type
  Sequence Type
  Cons Cell Type
  Array Type
  String Type
  Vector Type
  Symbol Type
  Function Type
  Macro Type
  Primitive Function Type
  Byte-Code Type
  Autoload Type
  Dotted Pair Notation
  Association List Type
  Buffer Type
  Window Type
  Window Configuration Type
  Marker Type
  Process Type
  Stream Type
  Keymap Type
  Overlay Type
  Integer Basics
  Float Basics
  Predicates on Numbers
  Comparison of Numbers
  Arithmetic Operations
  Bitwise Operations
  Numeric Conversions
  Math Functions
  Random Numbers
  String Basics
  Predicates for Strings
  Creating Strings
  Text Comparison
  String Conversion
  Formatting Strings
  Case Conversion
  Cons Cells
  Lists as Boxes
  List-related Predicates
  List Elements
  Building Lists
  Modifying Lists
  Sets And Lists
  Association Lists
  Setcar
  Setcdr
  Rearrangement
  Sequence Functions
  Arrays
  Array Functions
  Vectors
  Symbol Components
  Definitions
  Creating Symbols
  Property Lists
  Intro Eval
  Eval
  Forms
  Quoting
  Self-Evaluating Forms
  Symbol Forms
  Classifying Lists
  Function Forms
  Macro Forms
  Special Forms
  Autoloading
  Sequencing
  Conditionals
  Combining Conditions
  Iteration
  Nonlocal Exits
  Catch and Throw
  Examples of Catch
  Errors
  Cleanups
  Signaling Errors
  Processing of Errors
  Handling Errors
  Error Symbols
  Global Variables
  Constant Variables
  Local Variables
  Void Variables
  Defining Variables
  Accessing Variables
  Setting Variables
  Variable Scoping
  Buffer-Local Variables
  Scope
  Extent
  Impl of Scope
  Using Scoping
  Intro to Buffer-Local
  Creating Buffer-Local
  Default Value
  What Is a Function
  Lambda Expressions
  Function Names
  Defining Functions
  Calling Functions
  Mapping Functions
  Anonymous Functions
  Function Cells
  Related Topics
  Lambda Components
  Simple Lambda
  Argument List
  Function Documentation
  Simple Macro
  Expansion
  Compiling Macros
  Defining Macros
  Backquote
  Problems with Macros
  How Programs Do Loading
  Autoload
  Named Features
  Repeated Loading
  Compilation Functions
  Disassembly
  Simple Advice
  Defining Advice
  Computed Advice
  Activation of Advice
  Enabling Advice
  Preactivation
  Argument Access in Advice
  Subr Arguments
  Combined Definition
  Debugger
  Syntax Errors
  Compilation Errors
  Edebug
  Error Debugging
  Function Debugging
  Explicit Debug
  Using Debugger
  Debugger Commands
  Invoking the Debugger
  Internals of Debugger
  Excess Open
  Excess Close
  Streams Intro
  Input Streams
  Input Functions
  Output Streams
  Output Functions
  Intro to Minibuffers
  Text from Minibuffer
  Object from Minibuffer
  Completion
  Yes-or-No Queries
  Minibuffer Misc
  Basic Completion
  Minibuffer Completion
  Completion Commands
  High-Level Completion
  Reading File Names
  Programmed Completion
  Command Overview
  Defining Commands
  Interactive Call
  Command Loop Info
  Input Events
  Reading Input
  Waiting
  Quitting
  Prefix Command Arguments
  Recursive Editing
  Disabling Commands
  Command History
  Keyboard Macros
  Using Interactive
  Interactive Codes
  Interactive Examples
  Keymap Terminology
  Format of Keymaps
  Creating Keymaps
  Inheritance and Keymaps
  Prefix Keys
  Menu Keymaps
  Active Keymaps
  Key Lookup
  Functions for Key Lookup
  Changing Key Bindings
  Key Binding Commands
  Scanning Keymaps
  Major Modes
  Minor Modes
  Mode Line Format
  Hooks
  Major Mode Conventions
  Example Major Modes
  Auto Major Mode
  Mode Help
  Minor Mode Conventions
  Keymaps and Minor Modes
  Mode Line Data
  Mode Line Variables
  %-Constructs
  Documentation Basics
  Accessing Documentation
  Keys in Documentation
  Describing Characters
  Help Functions
  Visiting Files
  Saving Buffers
  Reading from Files
  Writing to Files
  File Locks
  Information about Files
  Contents of Directories
  Changing Files
  File Names
  Visiting Functions
  Subroutines of Visiting
  Testing Accessibility
  Kinds of Files
  File Attributes
  File Name Components
  Directory Names
  Relative File Names
  File Name Expansion
  Unique File Names
  File Name Completion
  Backup Files
  Auto-Saving
  Reverting
  Making Backups
  Rename or Copy
  Numbered Backups
  Backup Names
  Buffer Basics
  Buffer Names
  Buffer File Name
  Buffer Modification
  Modification Time
  Read Only Buffers
  The Buffer List
  Creating Buffers
  Killing Buffers
  Current Buffer
  Basic Windows
  Splitting Windows
  Deleting Windows
  Selecting Windows
  Cyclic Window Ordering
  Buffers and Windows
  Displaying Buffers
  Window Point
  Window Start
  Vertical Scrolling
  Horizontal Scrolling
  Size of Window
  Resizing Windows
  Window Configurations
  Creating Frames
  Multiple Displays
  Frame Parameters
  Frame Titles
  Deleting Frames
  Finding All Frames
  Frames and Windows
  Minibuffers and Frames
  Input Focus
  Visibility of Frames
  Raising and Lowering
  Frame Configurations
  Mouse Tracking
  Mouse Position
  Pop-Up Menus
  Dialog Boxes
  Pointer Shapes
  Window System Selections
  Color Names
  Resources
  Display Feature Testing
  Point
  Motion
  Excursions
  Narrowing
  Character Motion
  Word Motion
  Buffer End Motion
  Text Lines
  Screen Lines
  List Motion
  Skipping Characters
  Overview of Markers
  Predicates on Markers
  Creating Markers
  Information from Markers
  Moving Markers
  The Mark
  The Region
  Near Point
  Buffer Contents
  Insertion
  Commands for Insertion
  Deletion
  User-Level Deletion
  The Kill Ring
  Undo
  Auto Filling
  Filling
  Margins
  Sorting
  Indentation
  Columns
  Case Changes
  Text Properties
  Substitution
  Transposition
  Registers
  Change Hooks
  Kill Ring Concepts
  Kill Functions
  Yank Commands
  Low-Level Kill Ring
  Internals of Kill Ring
  Primitive Indent
  Mode-Specific Indent
  Region Indent
  Relative Indent
  Indent Tabs
  Motion by Indent
  Examining Properties
  Changing Properties
  Property Search
  Special Properties
  Format Properties
  Sticky Properties
  Saving Properties
  Lazy Properties
  Clickable Text
  Fields
  Not Intervals
  Text Representations
  Converting Representations
  Selecting a Representation
  Character Codes
  Character Sets
  Chars and Bytes
  Splitting Characters
  Scanning Charsets
  Translation of Characters
  Coding Systems
  Input Methods
  Locales
  String Search
  Regular Expressions
  Regexp Search
  Match Data
  Saving Match Data
  Standard Regexps
  Searching and Case
  Syntax of Regexps
  Regexp Example
  Syntax Descriptors
  Syntax Table Functions
  Parsing Expressions
  Standard Syntax Tables
  Syntax Table Internals
  Syntax Class Table
  Syntax Flags
  Abbrev Mode
  Abbrev Tables
  Defining Abbrevs
  Abbrev Files
  Abbrev Expansion
  Standard Abbrev Tables
  Subprocess Creation
  Synchronous Processes
  Asynchronous Processes
  Deleting Processes
  Process Information
  Input to Processes
  Signals to Processes
  Output from Processes
  Sentinels
  Network
  Process Buffers
  Filter Functions
  Accepting Output
  Starting Up
  Getting Out
  System Environment
  Terminal Input
  Terminal Output
  Flow Control
  Batch Mode
  Startup Summary
  Init File
  Terminal-Specific
  Command-Line Arguments
  Killing Emacs
  Suspending Emacs
  Refresh Screen
  Truncation
  The Echo Area
  Selective Display
  Overlay Arrow
  Temporary Displays
  Waiting
  Blinking
  Usual Display
  Beeping
  Window Systems
  Building Emacs
  Pure Storage
  Garbage Collection
  Object Internals
  Writing Emacs Primitives
  Buffer Internals
  Window Internals
  Process Internals