From 79d7167f20582b7d0e8743bec650bda1a12a85ab Mon Sep 17 00:00:00 2001 From: Tassilo Horn Date: Wed, 12 Jun 2013 14:42:35 +0200 Subject: [PATCH] * textmodes/reftex-cite.el (reftex-cite-regexp-hist) (reftex-citation-prompt, reftex-default-bibliography) (reftex-bib-or-thebib, reftex-get-bibfile-list) (reftex-pop-to-bibtex-entry, reftex-extract-bib-entries) (reftex-bib-sort-author, reftex-bib-sort-year) (reftex-bib-sort-year-reverse, reftex-get-crossref-alist) (reftex-extract-bib-entries-from-thebibliography) (reftex-get-bibkey-default, reftex-get-bib-names) (reftex-parse-bibtex-entry, reftex-get-bib-field) (reftex-format-bib-entry, reftex-parse-bibitem) (reftex-format-bibitem, reftex-do-citation) (reftex-figure-out-cite-format, reftex-offer-bib-menu) (reftex-restrict-bib-matches, reftex-extract-bib-file) (reftex-insert-bib-matches, reftex-format-citation) (reftex-make-cite-echo-string, reftex-bibtex-selection-callback) (reftex-create-bibtex-file): Add docstrings, mostly by converting existing comments into docstrings. --- lisp/ChangeLog | 20 +++++ lisp/textmodes/reftex-cite.el | 129 +++++++++++++-------------- lisp/textmodes/reftex-parse.el | 154 ++++++++++++++++----------------- 3 files changed, 157 insertions(+), 146 deletions(-) diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 5abb3b1b1bc..18f225ec308 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,23 @@ +2013-06-12 Rüdiger Sonderfeld + + * textmodes/reftex-cite.el (reftex-cite-regexp-hist) + (reftex-citation-prompt, reftex-default-bibliography) + (reftex-bib-or-thebib, reftex-get-bibfile-list) + (reftex-pop-to-bibtex-entry, reftex-extract-bib-entries) + (reftex-bib-sort-author, reftex-bib-sort-year) + (reftex-bib-sort-year-reverse, reftex-get-crossref-alist) + (reftex-extract-bib-entries-from-thebibliography) + (reftex-get-bibkey-default, reftex-get-bib-names) + (reftex-parse-bibtex-entry, reftex-get-bib-field) + (reftex-format-bib-entry, reftex-parse-bibitem) + (reftex-format-bibitem, reftex-do-citation) + (reftex-figure-out-cite-format, reftex-offer-bib-menu) + (reftex-restrict-bib-matches, reftex-extract-bib-file) + (reftex-insert-bib-matches, reftex-format-citation) + (reftex-make-cite-echo-string, reftex-bibtex-selection-callback) + (reftex-create-bibtex-file): Add docstrings, mostly by converting + existing comments into docstrings. + 2013-06-12 Xue Fuqiao * ibuf-ext.el (ibuffer-mark-help-buffers): Doc fix. diff --git a/lisp/textmodes/reftex-cite.el b/lisp/textmodes/reftex-cite.el index ca29709de2e..6c103294a06 100644 --- a/lisp/textmodes/reftex-cite.el +++ b/lisp/textmodes/reftex-cite.el @@ -25,18 +25,16 @@ ;;; Code: (eval-when-compile (require 'cl)) -(provide 'reftex-cite) -(require 'reftex) -;;; -;; Variables and constants +(require 'reftex) -;; The history list of regular expressions used for citations -(defvar reftex-cite-regexp-hist nil) +;;; Variables and constants +(defvar reftex-cite-regexp-hist nil + "The history list of regular expressions used for citations") -;; Prompt and help string for citation selection (defconst reftex-citation-prompt - "Select: [n]ext [p]revious [r]estrict [ ]full_entry [q]uit RET [?]Help+more") + "Select: [n]ext [p]revious [r]estrict [ ]full_entry [q]uit RET [?]Help+more" + "Prompt and help string for citation selection") (defconst reftex-citation-help " n / p Go to next/previous entry (Cursor motion works as well). @@ -51,8 +49,7 @@ e / E Create BibTeX file with all (marked/unmarked) entries a / A Put all (marked) entries into one/many \\cite commands.") -;; Find bibtex files - +;;; Find bibtex files (defmacro reftex-with-special-syntax-for-bib (&rest body) `(let ((saved-syntax (syntax-table))) (unwind-protect @@ -62,8 +59,8 @@ (set-syntax-table saved-syntax)))) (defun reftex-default-bibliography () - ;; Return the expanded value of `reftex-default-bibliography'. - ;; The expanded value is cached. + "Return the expanded value of variable `reftex-default-bibliography'. +The expanded value is cached." (unless (eq (get 'reftex-default-bibliography :reftex-raw) reftex-default-bibliography) (put 'reftex-default-bibliography :reftex-expanded @@ -74,9 +71,8 @@ (get 'reftex-default-bibliography :reftex-expanded)) (defun reftex-bib-or-thebib () - ;; Tests if BibTeX or \begin{thebibliography} should be used for the - ;; citation - ;; Find the bof of the current file + "Test if BibTeX or \begin{thebibliography} should be used for the citation. +Find the bof of the current file" (let* ((docstruct (symbol-value reftex-docstruct-symbol)) (rest (or (member (list 'bof (buffer-file-name)) docstruct) docstruct)) @@ -94,11 +90,11 @@ (if thebib 'thebib nil)))) (defun reftex-get-bibfile-list () - ;; Return list of bibfiles for current document. - ;; When using the chapterbib or bibunits package you should either - ;; use the same database files everywhere, or separate parts using - ;; different databases into different files (included into the mater file). - ;; Then this function will return the applicable database files. + "Return list of bibfiles for current document. +When using the chapterbib or bibunits package you should either +use the same database files everywhere, or separate parts using +different databases into different files (included into the mater file). +Then this function will return the applicable database files." ;; Ensure access to scanning info (reftex-access-scan-info) @@ -115,16 +111,14 @@ (cdr (assq 'bib (symbol-value reftex-docstruct-symbol))) (error "\\bibliography statement missing or .bib files not found"))) -;; Find a certain reference in any of the BibTeX files. - +;;; Find a certain reference in any of the BibTeX files. (defun reftex-pop-to-bibtex-entry (key file-list &optional mark-to-kill highlight item return) - ;; Find BibTeX KEY in any file in FILE-LIST in another window. - ;; If MARK-TO-KILL is non-nil, mark new buffer to kill. - ;; If HIGHLIGHT is non-nil, highlight the match. - ;; If ITEM in non-nil, search for bibitem instead of database entry. - ;; If RETURN is non-nil, just return the entry and restore point. - + "Find BibTeX KEY in any file in FILE-LIST in another window. +If MARK-TO-KILL is non-nil, mark new buffer to kill. +If HIGHLIGHT is non-nil, highlight the match. +If ITEM in non-nil, search for bibitem instead of database entry. +If RETURN is non-nil, just return the entry and restore point." (let* ((re (if item (concat "\\\\bibitem[ \t]*\\(\\[[^]]*\\]\\)?[ \t]*{" @@ -178,12 +172,11 @@ (progn (forward-list 1) (point))) (error (min (point-max) (+ 300 (point))))))) -;; Parse bibtex buffers - +;;; Parse bibtex buffers (defun reftex-extract-bib-entries (buffers) - ;; Extract bib entries which match regexps from BUFFERS. - ;; BUFFERS is a list of buffers or file names. - ;; Return list with entries." + "Extract bib entries which match regexps from BUFFERS. +BUFFERS is a list of buffers or file names. +Return list with entries." (let* (re-list first-re rest-re (buffer-list (if (listp buffers) buffers (list buffers))) found-list entry buffer1 buffer alist @@ -309,6 +302,8 @@ (t found-list)))) (defun reftex-bib-sort-author (e1 e2) + "Compare bib entries E1 and E2 by author. +The name of the first different author/editor is used." (let ((al1 (reftex-get-bib-names "author" e1)) (al2 (reftex-get-bib-names "author" e2))) (while (and al1 al2 (string= (car al1) (car al2))) @@ -320,15 +315,17 @@ (not (stringp (car al1)))))) (defun reftex-bib-sort-year (e1 e2) + "Compare bib entries E1 and E2 by year in ascending order." (< (string-to-number (or (cdr (assoc "year" e1)) "0")) (string-to-number (or (cdr (assoc "year" e2)) "0")))) (defun reftex-bib-sort-year-reverse (e1 e2) + "Compare bib entries E1 and E2 by year in descending order." (> (string-to-number (or (cdr (assoc "year" e1)) "0")) (string-to-number (or (cdr (assoc "year" e2)) "0")))) (defun reftex-get-crossref-alist (entry) - ;; return the alist from a crossref entry + "Return the alist from a crossref ENTRY." (let ((crkey (cdr (assoc "crossref" entry))) start) (save-excursion @@ -347,10 +344,9 @@ ;; Parse the bibliography environment (defun reftex-extract-bib-entries-from-thebibliography (files) - ;; Extract bib-entries from the \begin{thebibliography} environment. - ;; Parsing is not as good as for the BibTeX database stuff. - ;; The environment should be located in file FILE. - + "Extract bib-entries from the \begin{thebibliography} environment. +Parsing is not as good as for the BibTeX database stuff. +The environment should be located in FILES." (let* (start end buf entries re re-list file default) (unless files (error "Need file name to find thebibliography environment")) @@ -430,8 +426,8 @@ entries)) (defun reftex-get-bibkey-default () - ;; Return the word before the cursor. If the cursor is in a - ;; citation macro, return the word before the macro. + "Return the word before the cursor. +If the cursor is in a citation macro, return the word before the macro." (let* ((macro (reftex-what-macro 1))) (save-excursion (if (and macro (string-match "cite" (car macro))) @@ -439,10 +435,10 @@ (skip-chars-backward "^a-zA-Z0-9") (reftex-this-word)))) -;; Parse and format individual entries - +;;; Parse and format individual entries (defun reftex-get-bib-names (field entry) - ;; Return a list with the author or editor names in ENTRY + "Return a list with the author or editor names in ENTRY. +If FIELD is empty try \"editor\" field." (let ((names (reftex-get-bib-field field entry))) (if (equal "" names) (setq names (reftex-get-bib-field "editor" entry))) @@ -457,7 +453,9 @@ (split-string names "\n"))) (defun reftex-parse-bibtex-entry (entry &optional from to raw) - ; if RAW is non-nil, keep double quotes/curly braces delimiting fields + "Parse BibTeX ENTRY. +If ENTRY is nil then parse the entry in current buffer between FROM and TO. +If RAW is non-nil, keep double quotes/curly braces delimiting fields." (let (alist key start field) (save-excursion (save-restriction @@ -518,7 +516,8 @@ alist)) (defun reftex-get-bib-field (fieldname entry &optional format) - ;; Extract the field FIELDNAME from an ENTRY + "Extract the field FIELDNAME from ENTRY. +If FORMAT is non-nil `format' entry accordingly." (let ((cell (assoc fieldname entry))) (if cell (if format @@ -527,7 +526,7 @@ ""))) (defun reftex-format-bib-entry (entry) - ;; Format a BibTeX ENTRY so that it is nice to look at + "Format a BibTeX ENTRY so that it is nice to look at." (let* ((auth-list (reftex-get-bib-names "author" entry)) (authors (mapconcat 'identity auth-list ", ")) @@ -570,7 +569,7 @@ (concat key "\n " authors " " year " " extra "\n " title "\n\n"))) (defun reftex-parse-bibitem (item) - ;; Parse a \bibitem entry + "Parse a \bibitem entry in ITEM." (let ((key "") (text "")) (when (string-match "\\`{\\([^}]+\\)}\\([^\000]*\\)" item) (setq key (match-string 1 item) @@ -586,7 +585,7 @@ (cons "&entry" (concat key " " text))))) (defun reftex-format-bibitem (item) - ;; Format a \bibitem entry so that it is (relatively) nice to look at. + "Format a \bibitem entry in ITEM so that it is (relatively) nice to look at." (let ((text (reftex-get-bib-field "&text" item)) (key (reftex-get-bib-field "&key" item)) (lines nil)) @@ -603,7 +602,7 @@ (put-text-property 0 (length text) 'face reftex-bib-author-face text)) (concat key "\n " text "\n\n"))) -;; Make a citation +;;; Make a citation ;;;###autoload (defun reftex-citation (&optional no-insert format-key) @@ -627,7 +626,6 @@ The regular expression uses an expanded syntax: && is interpreted as `and'. Thus, `aaaa&&bbb' matches entries which contain both `aaaa' and `bbb'. While entering the regexp, completion on knows citation keys is possible. `=' is a good regular expression to match all entries in all files." - (interactive) ;; check for recursive edit @@ -645,8 +643,7 @@ While entering the regexp, completion on knows citation keys is possible. (reftex-kill-temporary-buffers))) (defun reftex-do-citation (&optional arg no-insert format-key) - ;; This really does the work of reftex-citation. - + "This really does the work of `reftex-citation'." (let* ((format (reftex-figure-out-cite-format arg no-insert format-key)) (docstruct-symbol reftex-docstruct-symbol) (selected-entries (reftex-offer-bib-menu)) @@ -743,8 +740,8 @@ While entering the regexp, completion on knows citation keys is possible. (mapcar 'car selected-entries))) (defun reftex-figure-out-cite-format (arg &optional no-insert format-key) - ;; Check if there is already a cite command at point and change cite format - ;; in order to only add another reference in the same cite command. + "Check if there is already a cite command at point and change cite format +in order to only add another reference in the same cite command." (let ((macro (car (reftex-what-macro 1))) (cite-format-value (reftex-get-cite-format)) key format) @@ -802,8 +799,7 @@ While entering the regexp, completion on knows citation keys is possible. (defvar reftex-select-bib-map) (defun reftex-offer-bib-menu () - ;; Offer bib menu and return list of selected items - + "Offer bib menu and return list of selected items." (let ((bibtype (reftex-bib-or-thebib)) found-list rtn key data selected-entries) (while @@ -917,7 +913,7 @@ While entering the regexp, completion on knows citation keys is possible. selected-entries)) (defun reftex-restrict-bib-matches (found-list) - ;; Limit FOUND-LIST with more regular expressions + "Limit FOUND-LIST with more regular expressions." (let ((re-list (split-string (read-string "RegExp [ && RegExp...]: " nil 'reftex-cite-regexp-hist) @@ -940,7 +936,7 @@ While entering the regexp, completion on knows citation keys is possible. found-list))) (defun reftex-extract-bib-file (all &optional marked complement) - ;; Limit FOUND-LIST with more regular expressions + "Limit FOUND-LIST with more regular expressions." (let ((file (read-file-name "File to create: "))) (find-file-other-window file) (if (> (buffer-size) 0) @@ -963,7 +959,7 @@ While entering the regexp, completion on knows citation keys is possible. (goto-char (point-min)))) (defun reftex-insert-bib-matches (list) - ;; Insert the bib matches and number them correctly + "Insert the bib matches and number them correctly." (let ((mouse-face (if (memq reftex-highlight-selection '(mouse both)) reftex-mouse-selected-face @@ -996,8 +992,7 @@ While entering the regexp, completion on knows citation keys is possible. last))))) (defun reftex-format-citation (entry format) - ;; Format a citation from the info in the BibTeX ENTRY - + "Format a citation from the info in the BibTeX ENTRY according to FORMAT." (unless (stringp format) (setq format "\\cite{%l}")) (if (and reftex-comment-citations @@ -1064,7 +1059,7 @@ While entering the regexp, completion on knows citation keys is possible. format) (defun reftex-make-cite-echo-string (entry docstruct-symbol) - ;; Format a bibtex entry for the echo area and cache the result. + "Format a bibtex ENTRY for the echo area and cache the result." (let* ((key (reftex-get-bib-field "&key" entry)) (string (let* ((reftex-cite-punctuation '(" " " & " " etal."))) @@ -1088,9 +1083,9 @@ While entering the regexp, completion on knows citation keys is possible. string)) (defun reftex-bibtex-selection-callback (data ignore no-revisit) - ;; Callback function to be called from the BibTeX selection, in - ;; order to display context. This function is relatively slow and not - ;; recommended for follow mode. It works OK for individual lookups. + "Callback function to be called from the BibTeX selection, in +order to display context. This function is relatively slow and not +recommended for follow mode. It works OK for individual lookups." (let ((win (selected-window)) (key (reftex-get-bib-field "&key" data)) bibfile-list item bibtype) @@ -1157,7 +1152,7 @@ While entering the regexp, completion on knows citation keys is possible. alist)))) (defun reftex-create-bibtex-file (bibfile) - "Create a new BibTeX database file with all entries referenced in document. + "Create a new BibTeX database BIBFILE with all entries referenced in document. The command prompts for a filename and writes the collected entries to that file. Only entries referenced in the current document with any \\cite-like macros are used. The sequence in @@ -1247,5 +1242,5 @@ created files in the variables `reftex-create-bibtex-header' or (message "%d entries extracted and copied to new database" (length entries)))) - +(provide 'reftex-cite) ;;; reftex-cite.el ends here diff --git a/lisp/textmodes/reftex-parse.el b/lisp/textmodes/reftex-parse.el index 3a64aad6a06..a99791e5427 100644 --- a/lisp/textmodes/reftex-parse.el +++ b/lisp/textmodes/reftex-parse.el @@ -49,7 +49,8 @@ (reftex-access-scan-info '(16))) (defun reftex-do-parse (rescan &optional file) - "Do a document rescan. When allowed, do only a partial scan from FILE." + "Do a document rescan. +When allowed, do only a partial scan from FILE." ;; Normalize the rescan argument (setq rescan (cond ((eq rescan t) t) @@ -191,7 +192,7 @@ of master file." (defvar index-tags) (defun reftex-parse-from-file (file docstruct master-dir) - ;; Scan the buffer for labels and save them in a list. + "Scan the buffer for labels and save them in a list." (let ((regexp (reftex-everything-regexp)) (bound 0) file-found tmp include-file @@ -350,8 +351,7 @@ of master file." docstruct)) (defun reftex-locate-bibliography-files (master-dir &optional files) - ;; Scan buffer for bibliography macro and return file list. - + "Scan buffer for bibliography macro and return file list." (unless files (save-excursion (goto-char (point-min)) @@ -379,10 +379,10 @@ of master file." (delq nil files))) (defun reftex-replace-label-list-segment (old insert &optional entirely) - ;; Replace the segment in OLD which corresponds to INSERT. - ;; Works with side effects, directly changes old. - ;; If entirely is t, just return INSERT. - ;; This function also makes sure the old toc markers do not point anywhere. + "Replace the segment in OLD which corresponds to INSERT. +Works with side effects, directly changes old. +If ENTIRELY is t, just return INSERT. +This function also makes sure the old toc markers do not point anywhere." (cond (entirely @@ -404,8 +404,8 @@ of master file." new)))) (defun reftex-section-info (file) - ;; Return a section entry for the current match. - ;; Careful: This function expects the match-data to be still in place! + "Return a section entry for the current match. +Careful: This function expects the match-data to be still in place!" (let* ((marker (set-marker (make-marker) (1- (match-beginning 3)))) (macro (reftex-match-string 3)) (prefix (save-match-data @@ -440,9 +440,9 @@ of master file." literal (marker-position marker)))) (defun reftex-ensure-index-support (&optional abort) - ;; When index support is turned off, ask to turn it on and - ;; set the current prefix argument so that `reftex-access-scan-info' - ;; will rescan the entire document. + "When index support is turned off, ask to turn it on and +set the current prefix argument so that `reftex-access-scan-info' +will rescan the entire document." (cond (reftex-support-index t) ((y-or-n-p "Turn on index support and rescan entire document? ") @@ -460,8 +460,8 @@ of master file." (defvar test-dummy) (defun reftex-index-info (file) - ;; Return an index entry for the current match. - ;; Careful: This function expects the match-data to be still in place! + "Return an index entry for the current match. +Careful: This function expects the match-data to be still in place!" (catch 'exit (let* ((macro (reftex-match-string 10)) (bom (match-beginning 10)) @@ -508,7 +508,7 @@ of master file." (list 'index index-tag context file bom arg key showkey sortkey key-end)))) (defun reftex-short-context (env parse &optional bound derive) - ;; Get about one line of useful context for the label definition at point. + "Get about one line of useful context for the label definition at point." (if (consp parse) (setq parse (if derive (cdr parse) (car parse)))) @@ -568,9 +568,9 @@ of master file." "INVALID VALUE OF PARSE")))) (defun reftex-where-am-I () - ;; Return the docstruct entry above point. Actually returns a cons - ;; cell in which the cdr is a flag indicating if the information is - ;; exact (t) or approximate (nil). + "Return the docstruct entry above point. +Actually returns a cons cell in which the cdr is a flag indicating +if the information is exact (t) or approximate (nil)." (let ((docstruct (symbol-value reftex-docstruct-symbol)) (cnt 0) rtn rtn-if-no-other @@ -748,10 +748,10 @@ of master file." ) (defsubst reftex-move-to-previous-arg (&optional bound) - ;; Assuming that we are in front of a macro argument, - ;; move backward to the closing parenthesis of the previous argument. - ;; This function understands the splitting of macros over several lines - ;; in TeX. + "Assuming that we are in front of a macro argument, +move backward to the closing parenthesis of the previous argument. +This function understands the splitting of macros over several lines +in TeX." (cond ;; Just to be quick: ((memq (preceding-char) '(?\] ?\}))) @@ -764,28 +764,27 @@ of master file." (t nil))) (defun reftex-what-macro-safe (which &optional bound) - ;; reftex-what-macro with special syntax table. + "Call `reftex-what-macro' with special syntax table." (reftex-with-special-syntax (reftex-what-macro which bound))) (defun reftex-what-macro (which &optional bound) - ;; Find out if point is within the arguments of any TeX-macro. - ;; The return value is either ("\\macro" . (point)) or a list of them. - - ;; If WHICH is nil, immediately return nil. - ;; If WHICH is 1, return innermost enclosing macro. - ;; If WHICH is t, return list of all macros enclosing point. - ;; If WHICH is a list of macros, look only for those macros and return the - ;; name of the first macro in this list found to enclose point. - ;; If the optional BOUND is an integer, bound backwards directed - ;; searches to this point. If it is nil, limit to nearest \section - - ;; like statement. - - ;; This function is pretty stable, but can be fooled if the text contains - ;; things like \macro{aa}{bb} where \macro is defined to take only one - ;; argument. As RefTeX cannot know this, the string "bb" would still be - ;; considered an argument of macro \macro. - + "Find out if point is within the arguments of any TeX-macro. +The return value is either (\"\\macro\" . (point)) or a list of them. + +If WHICH is nil, immediately return nil. +If WHICH is 1, return innermost enclosing macro. +If WHICH is t, return list of all macros enclosing point. +If WHICH is a list of macros, look only for those macros and return the + name of the first macro in this list found to enclose point. +If the optional BOUND is an integer, bound backwards directed + searches to this point. If it is nil, limit to nearest \\section - + like statement. + +This function is pretty stable, but can be fooled if the text contains +things like \\macro{aa}{bb} where \\macro is defined to take only one +argument. As RefTeX cannot know this, the string \"bb\" would still be +considered an argument of macro \\macro." (unless reftex-section-regexp (reftex-compile-variables)) (catch 'exit (if (null which) (throw 'exit nil)) @@ -832,20 +831,19 @@ of master file." (nreverse cmd-list))))) (defun reftex-what-environment (which &optional bound) - ;; Find out if point is inside a LaTeX environment. - ;; The return value is (e.g.) either ("equation" . (point)) or a list of - ;; them. - - ;; If WHICH is nil, immediately return nil. - ;; If WHICH is 1, return innermost enclosing environment. - ;; If WHICH is t, return list of all environments enclosing point. - ;; If WHICH is a list of environments, look only for those environments and - ;; return the name of the first environment in this list found to enclose - ;; point. - - ;; If the optional BOUND is an integer, bound backwards directed searches to - ;; this point. If it is nil, limit to nearest \section - like statement. - + "Find out if point is inside a LaTeX environment. +The return value is (e.g.) either (\"equation\" . (point)) or a list of +them. + +If WHICH is nil, immediately return nil. +If WHICH is 1, return innermost enclosing environment. +If WHICH is t, return list of all environments enclosing point. +If WHICH is a list of environments, look only for those environments and + return the name of the first environment in this list found to enclose + point. + +If the optional BOUND is an integer, bound backwards directed searches to +this point. If it is nil, limit to nearest \\section - like statement." (unless reftex-section-regexp (reftex-compile-variables)) (catch 'exit (save-excursion @@ -870,18 +868,17 @@ of master file." (nreverse env-list))))) (defun reftex-what-special-env (which &optional bound) - ;; Run the special environment parsers and return the matches. - ;; - ;; The return value is (e.g.) either ("my-parser-function" . (point)) - ;; or a list of them. - - ;; If WHICH is nil, immediately return nil. - ;; If WHICH is 1, return innermost enclosing environment. - ;; If WHICH is t, return list of all environments enclosing point. - ;; If WHICH is a list of environments, look only for those environments and - ;; return the name of the first environment in this list found to enclose - ;; point. + "Run the special environment parsers and return the matches. + +The return value is (e.g.) either (\"my-parser-function\" . (point)) +or a list of them. +If WHICH is nil, immediately return nil. +If WHICH is 1, return innermost enclosing environment. +If WHICH is t, return list of all environments enclosing point. +If WHICH is a list of environments, look only for those environments and + return the name of the first environment in this list found to enclose + point." (unless reftex-section-regexp (reftex-compile-variables)) (catch 'exit (save-excursion @@ -911,10 +908,10 @@ of master file." (car specials)))))) (defsubst reftex-move-to-next-arg (&optional ignore) - ;; Assuming that we are at the end of a macro name or a macro argument, - ;; move forward to the opening parenthesis of the next argument. - ;; This function understands the splitting of macros over several lines - ;; in TeX. + "Assuming that we are at the end of a macro name or a macro argument, +move forward to the opening parenthesis of the next argument. +This function understands the splitting of macros over several lines +in TeX." (cond ;; Just to be quick: ((memq (following-char) '(?\[ ?\{))) @@ -930,8 +927,8 @@ of master file." (reftex-nth-arg (nth 5 entry) (nth 6 entry)))) (defun reftex-nth-arg (n &optional opt-args) - ;; Return the nth following {} or [] parentheses content. - ;; OPT-ARGS is a list of argument numbers which are optional. + "Return the Nth following {} or [] parentheses content. +OPT-ARGS is a list of argument numbers which are optional." ;; If we are sitting at a macro start, skip to end of macro name. (and (eq (following-char) ?\\) (skip-chars-forward "a-zA-Z*\\\\")) @@ -974,8 +971,8 @@ of master file." (error nil))) (defun reftex-context-substring (&optional to-end) - ;; Return up to 150 chars from point - ;; When point is just after a { or [, limit string to matching parenthesis + "Return up to 150 chars from point. +When point is just after a { or [, limit string to matching parenthesis" (cond (to-end ;; Environment - find next \end @@ -1007,8 +1004,7 @@ of master file." (defvar reftex-section-numbers (make-vector reftex-max-section-depth 0)) (defun reftex-init-section-numbers (&optional toc-entry appendix) - ;; Initialize the section numbers with zeros or with what is found - ;; in the toc entry. + "Initialize the section numbers with zeros or with what is found in the TOC-ENTRY." (let* ((level (or (nth 5 toc-entry) -1)) (numbers (nreverse (split-string (or (nth 6 toc-entry) "") "\\."))) (depth (1- (length reftex-section-numbers))) @@ -1026,8 +1022,8 @@ of master file." (put 'reftex-section-numbers 'appendix appendix)) (defun reftex-section-number (&optional level star) - ;; Return a string with the current section number. - ;; When LEVEL is non-nil, increase section numbers on that level. + "Return a string with the current section number. +When LEVEL is non-nil, increase section numbers on that level." (let* ((depth (1- (length reftex-section-numbers))) idx n (string "") (appendix (get 'reftex-section-numbers 'appendix)) (partspecial (and (not reftex-part-resets-chapter) @@ -1073,7 +1069,7 @@ of master file." string)))) (defun reftex-roman-number (n) - ;; Return as a string the roman number equal to N. + "Return as a string the roman number equal to N." (let ((nrest n) (string "") (list '((1000 . "M") ( 900 . "CM") ( 500 . "D") ( 400 . "CD") -- 2.39.2