| blob | 739660967908ff03e54a891e1534ae63e51e282d |
1 ;;; org-footnote.el --- Footnote support in Org and elsewhere
2 ;;
3 ;; Copyright (C) 2009-2015 Free Software Foundation, Inc.
4 ;;
5 ;; Author: Carsten Dominik <carsten at orgmode dot org>
6 ;; Keywords: outlines, hypermedia, calendar, wp
7 ;; Homepage: http://orgmode.org
8 ;;
9 ;; This file is part of GNU Emacs.
10 ;;
11 ;; GNU Emacs is free software: you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation, either version 3 of the License, or
14 ;; (at your option) any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
23 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
24 ;;
25 ;;; Commentary:
27 ;; This file contains the code dealing with footnotes in Org-mode.
28 ;; The code can also be used in arbitrary text modes to provide
29 ;; footnotes. Compared to Steven L Baur's footnote.el it provides
30 ;; better support for resuming editing. It is less configurable than
31 ;; Steve's code, though.
33 ;;; Code:
76 ;; Only [1]-like footnotes are closed in this regexp, as footnotes
77 ;; from other types might contain square brackets (i.e. links) in
78 ;; their definition.
79 ;;
80 ;; `org-re' is used for regexp compatibility with XEmacs.
82 ;; Match inline footnotes.
84 ;; Match other footnotes.
99 "Footnotes in Org-mode."
104 "Outline heading containing footnote definitions.
106 This can be nil, to place footnotes locally at the end of the
107 current outline node. If can also be the name of a special
108 outline heading under which footnotes should be put.
110 This variable defines the place where Org puts the definition
111 automatically, i.e. when creating the footnote, and when sorting
112 the notes. However, by hand you may place definitions
113 *anywhere*.
115 If this is a string, during export, all subtrees starting with
116 this heading will be ignored.
118 If you don't use the customize interface to change this variable,
119 you will need to run the following command after the change:
133 "Tag marking the beginning of footnote section.
134 The Org footnote engine can be used in arbitrary text files as well
135 as in Org-mode. Outside Org mode, new footnotes are always placed at
136 the end of the file. When you normalize the notes, any line containing
137 only this tag will be removed, a new one will be inserted at the end
138 of the file, followed by the collected and normalized footnotes.
140 If you don't want any tag in such buffers, set this variable to nil."
147 "Non-nil means define footnotes inline, at reference location.
148 When nil, footnotes will be defined in a special section near
149 the end of the document. When t, the [fn:label:definition] notation
150 will be used to define the footnote at the reference position."
155 "Non-nil means define automatically new labels for footnotes.
156 Possible values are:
158 nil Prompt the user for each label.
159 t Create unique labels of the form [fn:1], [fn:2], etc.
160 confirm Like t, but let the user edit the created value.
161 The label can be removed from the minibuffer to create
162 an anonymous footnote.
163 random Automatically generate a unique, random label.
164 plain Automatically create plain number labels like [1]."
174 "Non-nil means automatically adjust footnotes after insert/delete.
175 When this is t, after each insertion or deletion of a footnote,
176 simple fn:N footnotes will be renumbered, and all footnotes will be sorted.
177 If you want to have just sorting or just renumbering, set this variable
178 to `sort' or `renumber'.
180 The main values of this variable can be set with in-buffer options:
182 #+STARTUP: fnadjust
183 #+STARTUP: nofnadjust"
192 "Non-nil means fill paragraphs after extracting footnotes.
193 When extracting inline footnotes, the lengths of lines can change a lot.
194 When this option is set, paragraphs from which an inline footnote has been
195 extracted will be filled again."
200 "Is point in a context where footnotes are allowed?"
204 ;; Avoid literal example.
209 ;; Avoid cited text and headers in message-mode.
215 ;; Avoid forbidden blocks.
219 "Is the cursor at a footnote reference?
221 If so, return a list containing its label, beginning and ending
222 positions, and the definition, when inlined."
231 ;; Anonymous footnotes don't have labels
234 ;; Inline footnotes don't end at (match-end 0) as
235 ;; `org-footnote-re' stops just after the second colon.
236 ;; Find the real ending with `scan-sexps', so Org doesn't
237 ;; get fooled by unrelated closing square brackets.
239 ;; Point is really at a reference if it's located before true
240 ;; ending of the footnote.
242 ;; Verify match isn't a part of a link.
249 ;; Verify point doesn't belong to a LaTeX macro.
252 ;; Definition: ensure this is an inline footnote first.
258 "Is point within a footnote definition?
260 This matches only pure definitions like [1] or [fn:name] at the
261 beginning of a line. It does not match references like
262 \[fn:name:definition], where the footnote text is included and
263 defined locally.
265 The return value will be nil if not at a footnote definition, and
266 a list with label, start, end and definition of the footnote
267 otherwise."
271 ;; Footnotes definitions are separated by new headlines, another
272 ;; footnote definition or 2 blank lines.
281 ;; In message-mode, do not search after signature.
286 message-signature-separator nil t)))))
299 "Return complete reference of the next footnote.
301 If LABEL is provided, get the next reference of that footnote. If
302 BACKWARD is non-nil, find previous reference instead. LIMIT is
303 the buffer position bounding the search.
305 Return value is a list like those provided by `org-footnote-at-reference-p'.
306 If no footnote is found, return nil."
312 label-fmt limit t)
319 "Move point to next footnote reference or definition.
321 LIMIT is the buffer position bounding the search.
323 Return value is a list like those provided by
324 `org-footnote-at-reference-p' or `org-footnote-at-definition-p'.
325 If no footnote is found, return nil."
332 ;; Beware: with [1]-like footnotes point will be just after
333 ;; the closing square bracket.
338 ;; Definition: also grab the last square bracket, only
339 ;; matched in `org-footnote-re' for [1]-like footnotes.
347 "Return label, boundaries and definition of the footnote LABEL."
359 label
366 ""
368 cbeg
370 nil))))
373 "Move point to the definition of the footnote LABEL.
375 LOCATION, when non-nil specifies the buffer position of the
376 definition.
378 Throw an error if there is no definition or if it cannot be
379 reached from current narrowed part of buffer. Return a non-nil
380 value if point was successfully moved."
398 t))
401 "Find the first closest (to point) reference of footnote with label LABEL."
419 "Return LABEL as an appropriate string."
428 "Return list with all defined foot labels used in the buffer.
430 If WITH-DEFS is non-nil, also associate the definition to each
431 label. The function will then return an alist whose key is label
432 and value definition."
436 ;; Depending on WITH-DEFS, store label or (label . def) of
437 ;; footnote reference/definition given as argument in RTN.
444 ;; Find all labels found in definitions.
450 ;; Find all labels found in references.
458 rtn))
461 "Return a new unique footnote label.
464 currently not used.
466 Optional argument CURRENT is the list of labels active in the
467 buffer."
476 "Non-nil when a footnote reference can be inserted at point."
477 ;; XXX: This is similar to `org-footnote-in-valid-context-p' but
478 ;; more accurate and usually faster, except in some corner cases.
479 ;; It may replace it after doing proper benchmarks as it would be
480 ;; used in fontification.
485 ;; No footnote reference in attributes.
488 nil)
489 ;; Paragraphs and blank lines at top of document are fine.
491 ;; So are contents of verse blocks.
495 ;; In an headline or inlinetask, point must be either on the
496 ;; heading itself or on the blank lines below.
507 ;; White spaces after an object or blank lines after an element
508 ;; are OK.
514 ;; Other elements are invalid.
516 ;; Just before object is fine.
518 ;; Within recursive object too, but not in a link.
525 "Insert a new footnote.
526 This command prompts for a label. If this is a label referencing an
527 existing label, only insert the label. If the footnote label is empty
528 or new, let the user edit the definition of the footnote."
540 "Label (leave empty for anonymous): "
558 ;; Since definition was created outside current
559 ;; scope, edit it remotely.
565 "Start the definition of a footnote with label LABEL.
566 Return buffer position at the beginning of the definition. In an
567 Org buffer, this function doesn't move point."
571 ;; In an Org document.
573 ;; If `org-footnote-section' is defined, find it, or create it
574 ;; at the end of the buffer.
583 nil t))
590 ;; Insert new section. Separate it from the previous one
591 ;; with a blank line, unless `org-blank-before-new-entry'
592 ;; explicitly says no.
601 ;; In a non-Org file. Search for footnote tag, or create it if
602 ;; specified (at the end of buffer, or before signature if in
603 ;; Message mode). Set point after any definition already there.
606 org-footnote-tag-for-non-org-mode-files)
611 message-signature-separator nil t))
613 ;; Ensure one blank line separates last
614 ;; footnote from signature.
621 ;; Check if the footnote tag is defined but missing. In this
622 ;; case, insert it, before any footnote or one blank line
623 ;; after any previous text.
629 ;; Remove superfluous white space and clear marker.
640 ;;;###autoload
642 "Do the right thing for footnotes.
644 When at a footnote reference, jump to the definition.
646 When at a definition, jump to the references if they exist, offer
647 to create them otherwise.
649 When neither at definition or reference, create a new footnote,
650 interactively if possible.
652 With prefix arg SPECIAL, or when no footnote can be created,
653 offer additional commands in a menu."
661 ;; Anonymous footnote: move point at the beginning of its
662 ;; definition.
665 ;; Check if a definition exists: then move to it.
668 ;; No definition exists: offer to create it.
672 ;; Since definition was created outside current scope,
673 ;; edit it remotely.
693 ;;;###autoload
695 "Collect the footnotes in various formats and normalize them.
697 This finds the different sorts of footnotes allowed in Org, and
698 normalizes them to the usual [N] format.
700 When SORT-ONLY is set, only sort the footnote definitions into the
701 referenced sequence."
702 ;; This is based on Paul's function, but rewritten.
703 ;;
704 ;; Re-create `org-with-limited-levels', but not limited to Org
705 ;; buffers.
708 org-inlinetask-min-level
712 limit-level)))
716 ins-point ref ref-table)
718 ;; 1. Find every footnote reference, extract the definition, and
719 ;; collect that data in REF-TABLE. If SORT-ONLY is nil, also
720 ;; normalize references.
725 ;; When footnote isn't anonymous, check if it's label
726 ;; (REF) is already stored in REF-TABLE. In that case,
727 ;; extract number used to identify it (MARKER). If
728 ;; footnote is unknown, increment the global counter
729 ;; (COUNT) to create an unused identifier.
732 ;; Is the reference inline or pointing to an inline
733 ;; footnote?
735 ;; Replace footnote reference with [MARKER]. Maybe fill
736 ;; paragraph once done. If SORT-ONLY is non-nil, only move
737 ;; to the end of reference found to avoid matching it twice.
743 org-footnote-fill-after-inline-note-extraction
745 ;; Add label (REF), identifier (MARKER), definition (DEF)
746 ;; type (INLINEP) and position (POS) to REF-TABLE if data was
747 ;; unknown.
752 ;; Reference beginning position is a marker
753 ;; to preserve it during further buffer
754 ;; modifications.
756 ;; 2. Find and remove the footnote section, if any. Also
757 ;; determine where footnotes shall be inserted (INS-POINT).
765 ;; A new footnote section is inserted by default at the end of
766 ;; the buffer.
771 ;; No footnote section set: Footnotes will be added at the end
772 ;; of the section containing their first reference.
775 ;; Remove any left-over tag in the buffer, if one is set up.
778 org-footnote-tag-for-non-org-mode-files)
784 ;; In Message mode, ensure footnotes are inserted before the
785 ;; signature.
792 ;; 3. Clean-up REF-TABLE.
798 ;; When only sorting, ignore inline footnotes.
799 ;; Also clear position marker.
802 ;; No definition available: provide one.
809 ref-table)))
811 ;; 4. Remove left-over definitions in the buffer.
814 ;; 5. Insert the footnotes again in the buffer, at the
815 ;; appropriate spot.
818 ;; No footnote: exit.
820 ;; Cases when footnotes should be inserted in one place.
822 ;; Insert again the section title, if any. Ensure that title,
823 ;; or the subsequent footnotes, will be separated by a blank
824 ;; lines from the rest of the document. In an Org buffer,
825 ;; separate section with a blank line, unless explicitly stated
826 ;; in `org-blank-before-new-entry'.
838 ;; Insert the footnotes, separated by a blank line.
842 ;; Clean markers.
847 ;; Each footnote definition has to be inserted at the end of the
848 ;; section where its first reference belongs.
853 ;; Clean marker.
861 "Find insertion point for footnote, just before next outline heading.
862 Assume insertion point is within currently accessible part of the buffer."
864 ;; Skip file local variables. See `modify-file-local-variable'.
869 t)))
875 "Delete every reference to footnote LABEL.
876 Return the number of footnotes removed."
884 nref)))
887 "Delete every definition of the footnote LABEL.
888 Return the number of footnotes removed."
896 ;; Remove the footnote, and all blank lines before it.
902 ndef)))
905 "Delete the footnote at point.
906 This will remove the definition (even multiple definitions if they exist)
907 and all references of a footnote label.
909 If LABEL is non-nil, delete that footnote instead."
912 ;; 1. Determine LABEL of footnote at point.
914 ;; LABEL is provided as argument.
916 ;; Footnote reference at point. If the footnote is
917 ;; anonymous, delete it and exit instead.
924 ;; Footnote definition at point.
928 ;; 2. Now that LABEL is non-nil, find every reference and every
929 ;; definition, and delete them.
932 ;; 3. Verify consistency of footnotes and notify user.
935 ndef nref label))))
938 "Renumber the simple footnotes like fn:17 into a sequence in the document."
946 ;; Ensure match is a footnote reference or definition.
957 "Renumber and/or sort footnotes according to user settings."
966 nil t)
972 ;; Local variables:
973 ;; generated-autoload-file: "org-loaddefs.el"
974 ;; End:
976 ;;; org-footnote.el ends here