В Emacs существуют соглашения по использованию специальных комментариев в Lisp-библиотеках для разделения их на разделы и предоставления информации, такой как авторство. Использование стандартного формата для этих элементов облегчает инструментам (и людям) извлечение соответствующей информации. В этом разделе объясняются эти соглашения, начиная с примера:
;;; foo.el --- Поддержка языка программирования Foo -*- lexical-binding: t; -*- ;; Copyright (C) 2010-2025 Ваше Имя
;; Author: Ваше Имя <yourname@example.com> ;; Maintainer: Кто-то Ещё <someone@example.com> ;; Created: 14 Jul 2010
;; Keywords: языки ;; URL: https://example.com/foo ;; Этот файл не является частью GNU Emacs. ;; Этот файл является свободным программным обеспечением… … ;; вместе с этим файлом. Если нет, см. <https://www.gnu.org/licenses/>.
Самая первая строка должна иметь следующий формат:
;;; имя_файла --- описание -*- lexical-binding: t; -*-
Описание должно помещаться в одну строку. Если файлу необходимо задать
дополнительные переменные в спецификации ‘-*-’, добавьте их после
lexical-binding. Если это сделает первую строку слишком длинной, используйте
раздел локальных переменных в конце файла.
Уведомление об авторских правах обычно содержит ваше имя (если вы написали файл). Если у вас есть работодатель, который претендует на авторские права на вашу работу, вам, возможно, потребуется указать его вместо вас. Не указывайте, что обладателем авторских прав является Free Software Foundation (или что файл является частью GNU Emacs), если ваш файл не был принят в дистрибутив Emacs или GNU ELPA. Дополнительную информацию о форме уведомлений об авторских правах и лицензиях см. в руководстве на сайте GNU.
После уведомления об авторских правах следуют несколько строк заголовочных комментариев, каждая из которых начинается с ‘;; имя-заголовка:’. Ниже приведена таблица стандартных возможных значений для имя-заголовка:
Этот заголовок указывает имя и адрес электронной почты как минимум основного
автора библиотеки. Если авторов несколько, перечислите их на
строках продолжения, начинающихся с ;; и табуляции или как минимум двух пробелов.
Мы рекомендуем включать контактный адрес электронной почты в форме
‘<…>’. Например:
;; Author: Ваше Имя <yourname@example.com> ;; Кто-то Ещё <someone@example.com> ;; Другой Человек <another@example.com>
Этот заголовок имеет тот же формат, что и заголовок Author. Он перечисляет лицо (лиц), которое в настоящее время поддерживает файл (отвечает на сообщения об ошибках и т. д.).
Если заголовок Maintainer отсутствует, предполагается, что лицо (лица), указанные в заголовке Author, являются сопровождающими. В некоторых файлах Emacs в качестве сопровождающего используется ‘emacs-devel@gnu.org’, что означает, что автор больше не несёт ответственности за файл, и он поддерживается как часть Emacs.
Эта необязательная строка указывает исходную дату создания файла и предназначена только для исторического интереса.
Если вы хотите записывать номера версий для отдельной Lisp-программы, поместите их в эту строку. Lisp-файлы, распространяемые с Emacs, как правило, не имеют заголовка ‘Version’, поскольку номер версии самого Emacs служит той же цели. Если вы распространяете набор из нескольких файлов, мы рекомендуем указывать версию не в каждом файле, а только в главном.
Эта строка содержит ключевые слова для команды справки finder-by-keyword.
Пожалуйста, используйте эту команду, чтобы увидеть список значимых ключевых слов.
Команда M-x checkdoc-package-keywords RET найдёт и отобразит
все ключевые слова, которых нет в finder-known-keywords. Если вы установите
переменную checkdoc-package-keywords-flag в значение, отличное от nil,
команды checkdoc будут включать проверку ключевых слов в свои проверки.
Это поле предназначено для того, чтобы люди могли найти ваш пакет, когда они ищут что-то по теме. Для разделения ключевых слов можно использовать пробелы, запятые или то и другое.
Название этого поля неудачно, поскольку люди часто предполагают, что это место для произвольных ключевых слов, описывающих их пакет, а не только для соответствующих ключевых слов Finder.
Эти строки указывают веб-сайт библиотеки.
Если ‘Version’ не подходит для использования менеджером пакетов, пакет
может определить ‘Package-Version’; он будет использован вместо него.
Это удобно, если ‘Version’ является идентификатором RCS или чем-то ещё,
что не может быть обработано version-to-list. См. Основы упаковки.
Если этот заголовок существует, он указывает пакеты, от которых зависит текущий пакет для корректной работы. См. Основы упаковки. Это используется менеджером пакетов как при загрузке (чтобы убедиться, что загружен полный набор пакетов), так и при активации (чтобы гарантировать, что пакет активируется только после того, как все его зависимости будут удовлетворены).
Его формат — это список списков в одной строке. car
каждого подсписка — это имя пакета в виде символа. cadr
каждого подсписка — это минимально допустимый номер версии в виде строки,
которая может быть обработана version-to-list. Запись без
версии (т. е. запись, которая является просто символом или подсписком из одного
элемента) эквивалентна записи с версией "0". Например:
;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2") cl-lib (seq))
Пакеты, которым не требуется поддержка версий Emacs старше Emacs 27, могут иметь заголовок ‘Package-Requires’, разбитый на несколько строк, например так:
;; Package-Requires: ((emacs "27.1") ;; (compat "29.1.4.1"))
Обратите внимание, что при таком формате вам всё равно нужно начинать список в той же строке, что и ‘Package-Requires’.
Код пакета автоматически определяет пакет с именем ‘emacs’ с номером версии текущего запущенного Emacs. Это можно использовать для указания минимальной версии Emacs, необходимой для пакета.
Практически каждая Lisp-библиотека должна содержать строки заголовков ‘Author’ и ‘Keywords’. Используйте остальные, если они уместны. Вы также можете добавлять строки заголовков с другими именами — у них нет стандартного значения, поэтому они не навредят.
Мы используем дополнительные стилизованные комментарии для подразделения содержимого файла библиотеки. Они должны быть отделены от всего остального пустыми строками. Вот их таблица:
Это начало вводных комментариев, объясняющих, как работает библиотека. Он должен находиться сразу после разрешений на копирование и завершаться одной из строк комментариев, описанных ниже: ‘Change Log’, ‘History’ или ‘Code’. Этот текст используется пакетом Finder, поэтому он должен иметь смысл в этом контексте.
Это начало необязательного журнала изменений файла с течением времени. Не помещайте слишком много информации в этот раздел — лучше хранить подробные журналы в системе контроля версий (как это делает Emacs) или в отдельном файле ChangeLog. ‘History’ является альтернативой ‘Change Log’.
Это начало непосредственно кода программы.
Это нижний колонтитул; он находится в самом конце файла. Его цель — позволить людям обнаружить усечённые версии файла по отсутствию строки колонтитула.