From mboxrd@z Thu Jan 1 00:00:00 1970 From: Rasmus Subject: [patch][ox-koma-letter] checkdoc compatible (was: [patch][ox-koma-letter] set opening via headline) Date: Sat, 17 Aug 2013 22:55:42 +0200 Message-ID: <87pptcxcj5.fsf_-_@gmx.us> References: <877gfk6s5f.fsf@gmx.us> <8761v4umsd.fsf@gmail.com> <87zjsgqdxz.fsf@gmx.us> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:39519) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAnXY-0002Hz-Ab for emacs-orgmode@gnu.org; Sat, 17 Aug 2013 16:56:11 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VAnXS-00025a-2U for emacs-orgmode@gnu.org; Sat, 17 Aug 2013 16:56:04 -0400 Received: from plane.gmane.org ([80.91.229.3]:59958) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAnXR-00025V-MO for emacs-orgmode@gnu.org; Sat, 17 Aug 2013 16:55:57 -0400 Received: from list by plane.gmane.org with local (Exim 4.69) (envelope-from ) id 1VAnXP-0000tE-2l for emacs-orgmode@gnu.org; Sat, 17 Aug 2013 22:55:55 +0200 Received: from 87-57-37-13-dynamic.dk.customer.tdc.net ([87.57.37.13]) by main.gmane.org with esmtp (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sat, 17 Aug 2013 22:55:55 +0200 Received: from rasmus by 87-57-37-13-dynamic.dk.customer.tdc.net with local (Gmexim 0.1 (Debian)) id 1AlnuQ-0007hv-00 for ; Sat, 17 Aug 2013 22:55:55 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: emacs-orgmode@gnu.org Cc: alan.schmitt@polytechnique.org --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit > Nicolas Goaziou writes: >> (defcustom org-koma-letter-opening nil >> - "Letter's opening, as a string." >> + "Letter's opening, as a string. If (1) this value is nil; (2) > > Please start a new line after the first sentence. This patch changes some docstrings to make ox-koma-letter pass checkdoc. I've also renamed some functions with weird names (let me know if you disagree). It applies on top of the patch 0001-Set-opening-via-headline.patch. –Rasmus --=-=-= Content-Type: text/x-diff Content-Disposition: attachment; filename=0002-Make-ox-koma-letter-pass-checkdoc.patch >From 57e743d6ea8479b87370f7a48bef362975bfde3c Mon Sep 17 00:00:00 2001 From: rasmus Date: Sat, 17 Aug 2013 22:50:47 +0200 Subject: [PATCH 2/2] Make ox-koma-letter pass checkdoc. * ox-koma-letter.el: Reworded parts of the head of the file. (org-koma-letter-prefer-special-headings, org-koma-letter-subject-format, org-koma-letter-default-class, org-koma-letter-special-tags-in-letter, org-koma-letter-special-tags-after-closing, org-koma-letter-special-tags-after-letter, org-koma-letter-plug-into-ox, org-koma-letter-email, org-koma-letter--get-tagged-contents, org-koma-letter-special-contents): Changed docstring to pass checkdoc. (org-koma-letter--get-value): Renamed `org-koma-letter--get-custom'. Docstring changed to pass checkdoc. (org-koma-letter--special-contents-as-macro): Renamed `org-koma-letter--prepare-special-contents-as-macro'. Docstring changed to pass checkdoc. (org-koma-letter--normalize-string): Renamed org-koma-letter--remove-offending-new-lines. Docstring changed to pass checkdoc. (org-koma-letter--determine-to-and-from): Renamed org-koma-letter--determine-special-value. Docstring changed to pass checkdoc. Some functions have been renamed to make the names slightly more informative. --- contrib/lisp/ox-koma-letter.el | 117 +++++++++++++++++++++-------------------- 1 file changed, 60 insertions(+), 57 deletions(-) diff --git a/contrib/lisp/ox-koma-letter.el b/contrib/lisp/ox-koma-letter.el index bb68771..6f5529f 100644 --- a/contrib/lisp/ox-koma-letter.el +++ b/contrib/lisp/ox-koma-letter.el @@ -62,8 +62,8 @@ ;; (see `org-koma-letter-subject-format') ;; - after-closing-order, a list of the ordering of headings with ;; special tags after closing (see -;; `org-koma-letter-special-tags-after-closing') - -;; after-letter-order, as above, but after the end of the letter +;; `org-koma-letter-special-tags-after-closing') +;; - after-letter-order, as above, but after the end of the letter ;; (see `org-koma-letter-special-tags-after-letter'). ;; ;; The following variables works differently from the main LaTeX class @@ -91,7 +91,7 @@ ;; (eval-after-load "ox-koma-letter" ;; '(org-koma-letter-plug-into-ox)) ;; -;; to your init file. This will add a very sparse scrlttr2 class and +;; to your init file. This will add a sparse scrlttr2 class and ;; set it as the default `org-koma-latex-default-class'. You can also ;; add you own letter class. For instace: ;; @@ -138,8 +138,8 @@ "The sender's name. This variable defaults to calling the function `user-full-name' -which just returns the current `user-full-name'. Alternatively a -string, nil or a function may be given. Functions must return a +which just returns the current function `user-full-name'. Alternatively a +string, nil or a function may be given. Functions must return a string." :group 'org-export-koma-letter :type '(radio (function-item user-full-name) @@ -189,8 +189,7 @@ t the value opening will be implicit set as the headline title." :type 'string) (defcustom org-koma-letter-prefer-special-headings nil - "If both a TO or FROM is specified two places should the - heading version be preferred?" + "If TO and/or FROM is specified using both a heading and a keyword the heading value will be preferred if the variable is t." :group 'org-export-koma-letter :type 'boolean) @@ -200,21 +199,22 @@ t the value opening will be implicit set as the headline title." :type 'string) (defcustom org-koma-letter-subject-format t - "Use the title as the subject of the letter. At the time of -writing the following values are allowed: - - - afteropening: subject after opening - - beforeopening: subject before opening - - centered: subject centered - - left:subject left-justified - - right: subject right-justified - - titled: add title/description to subject - - underlined: set subject underlined (see note in text please) + "Use the title as the subject of the letter. + +At this time the following values are allowed: + + - afteropening: subject after opening. + - beforeopening: subject before opening. + - centered: subject centered. + - left:subject left-justified. + - right: subject right-justified. + - titled: add title/description to subject. + - underlined: set subject underlined. - untitled: do not add title/description to subject. - No-export: do no insert a subject even if present. Please refer to the KOMA-script manual (Table 4.16. in the -English manual of 2012-07-22)" +English manual of 2012-07-22)." :type '(radio (const :tag "No export" nil) (const :tag "Default options" t) @@ -263,8 +263,9 @@ Use `foldmarks:true' to activate default fold marks or :type 'boolean) (defcustom org-koma-letter-default-class nil - "Default class for `org-koma-letter'. Must be a member of - `org-latex-classes'" + "Default class for `org-koma-letter'. + +The value must be a member of `org-latex-classes'." :group 'org-export-koma-letter :type 'string) @@ -276,16 +277,16 @@ A headline is only used if #+OPENING is not set. See also :type 'boolean) (defconst org-koma-letter-special-tags-in-letter '(to from) - "header tags related to the letter itself") + "Header tags related to the letter itself.") (defconst org-koma-letter-special-tags-after-closing '(ps encl cc) - "Header tags to be inserted after closing") + "Header tags to be inserted after closing.") (defconst org-koma-letter-special-tags-after-letter '(after_letter) - "Header tags to be inserted after closing") + "Header tags to be inserted after closing.") (defvar org-koma-letter-special-contents nil - "holds special content temporarily.") + "Holds special content temporarily.") @@ -297,10 +298,10 @@ A headline is only used if #+OPENING is not set. See also (:latex-class "LATEX_CLASS" nil (if org-koma-letter-default-class org-koma-letter-default-class org-latex-default-class) t) - (:author "AUTHOR" nil (org-koma-letter--get-custom org-koma-letter-author) t) + (:author "AUTHOR" nil (org-koma-letter--get-value org-koma-letter-author) t) (:from-address "FROM_ADDRESS" nil nil newline) (:phone-number "PHONE_NUMBER" nil org-koma-letter-phone-number) - (:email "EMAIL" nil (org-koma-letter--get-custom org-koma-letter-email) t) + (:email "EMAIL" nil (org-koma-letter--get-value org-koma-letter-email) t) (:to-address "TO_ADDRESS" nil nil newline) (:place "PLACE" nil org-koma-letter-place) (:opening "OPENING" nil org-koma-letter-opening) @@ -341,8 +342,7 @@ A headline is only used if #+OPENING is not set. See also ;;; Initialize class function (defun org-koma-letter-plug-into-ox () - "Add a sparse `default-koma-letter' to `org-latex-classes' and set -`org-koma-letter-default-class' to `default-koma-letter'" + "Add a sparse `default-koma-letter' to `org-latex-classes' and set `org-koma-letter-default-class' to `default-koma-letter'." (let ((class "default-koma-letter")) (eval-after-load "ox-latex" `(unless (member ,class 'org-latex-classes) @@ -354,20 +354,20 @@ A headline is only used if #+OPENING is not set. See also ;;; Helper functions (defun org-koma-letter-email () - "Return the current `user-mail-address'" + "Return the current `user-mail-address'." user-mail-address) ;; The following is taken from/inspired by ox-grof.el ;; Thanks, Luis! (defun org-koma-letter--get-tagged-contents (key) - "Get tagged content from `org-koma-letter-special-contents'" - (cdr (assoc (org-koma-letter--get-custom key) + "Get contents from a headline tagged with KEY. +Technically, the contents is stored in `org-koma-letter-special-contents'." + (cdr (assoc (org-koma-letter--get-value key) org-koma-letter-special-contents))) -(defun org-koma-letter--get-custom (value) - "Determines whether a value is nil, a string or a -function (a symobl). If it is a function it it evaluates it." +(defun org-koma-letter--get-value (value) + "Determines if VALUE is nil, a string, a function or a symbol and return a string or nil." (when value (cond ((stringp value) value) ((functionp value) (funcall value)) @@ -375,20 +375,21 @@ function (a symobl). If it is a function it it evaluates it." (t value)))) -(defun org-koma-letter--prepare-special-contents-as-macro (a-list &optional keep-newlines no-tag) - "Finds all the components of `org-koma-letter-special-contents' -corresponding to members of the `a-list' and return them as a -string to be formatted. The function is used for inserting -content of speciall headings such as PS. +(defun org-koma-letter--special-contents-as-macro (a-list &optional keep-newlines no-tag) + "Find members of `org-koma-letter-special-contents' corresponding to A-LIST. +Return them as a string to be formatted. -If keep-newlines is t newlines will not be removed. If no-tag is +The function is used for inserting content of speciall headings +such as PS. + +If KEEP-NEWLINES is t newlines will not be removed. If NO-TAG is is t the content in `org-koma-letter-special-contents' will not -be wrapped in a macro named whatever the members of a-list are called. -" +be wrapped in a macro named whatever the members of A-LIST are +called." (let (output) (dolist (ac* a-list output) (let* - ((ac (org-koma-letter--get-custom ac*)) + ((ac (org-koma-letter--get-value ac*)) (x (org-koma-letter--get-tagged-contents ac))) (when x (setq output @@ -397,24 +398,26 @@ be wrapped in a macro named whatever the members of a-list are called. ;; sometimes LaTeX complains about newlines ;; at the end or beginning of macros. Remove them. (org-koma-letter--format-string-as-macro - (if keep-newlines x (org-koma-letter--remove-offending-new-lines x)) + (if keep-newlines x (org-koma-letter--normalize-string x)) (unless no-tag ac))))))))) (defun org-koma-letter--format-string-as-macro (string &optional macro) - "If a macro is given format as string as \"\\macro{string}\" else as \"string\"" + "Format STRING as \"\\macro{string}\" if MACRO is given else as \"string\"." (if macro (format "\\%s{%s}" macro string) (format "%s" string))) -(defun org-koma-letter--remove-offending-new-lines (string) - "Remove new lines in the begging and end of `string'" +(defun org-koma-letter--normalize-string (string) + "Remove new lines in the beginning and end of `STRING'." (replace-regexp-in-string "\\`[ \n\t]+\\|[\n\t ]*\\'" "" string)) -(defun org-koma-letter--determine-special-value (info key) - "Determine who the letter is to and whom it is from. - oxkoma-letter allows two ways to specify these things. If both - are present return the preferred one as determined by - `org-koma-letter-prefer-special-headings'." +(defun org-koma-letter--determine-to-and-from (info key) + "Given INFO determine KEY for the letter. +KEY should be `to' or `from'. + +`ox-koma-letter' allows two ways to specify to and from. If both +are present return the preferred one as determined by +`org-koma-letter-prefer-special-headings'." (let* ((plist-alist '((from . :from-address) (to . :to-address))) (default-alist `((from ,org-koma-letter-from-address) @@ -434,7 +437,7 @@ be wrapped in a macro named whatever the members of a-list are called. (when adr (replace-regexp-in-string "\n" "\\\\\\\\\n" - (org-koma-letter--remove-offending-new-lines adr))))) + (org-koma-letter--normalize-string adr))))) ;;; Transcode Functions @@ -537,7 +540,7 @@ holding export options." info))) (let ((lco (plist-get info :lco)) (author (plist-get info :author)) - (from-address (org-koma-letter--determine-special-value info 'from)) + (from-address (org-koma-letter--determine-to-and-from info 'from)) (phone-number (plist-get info :phone-number)) (email (plist-get info :email)) (signature (plist-get info :signature))) @@ -597,18 +600,18 @@ holding export options." (format "\\setkomavar{subject}{%s}\n\n" subject)))) ;; Letter start (format "\\begin{letter}{%%\n%s}\n\n" - (org-koma-letter--determine-special-value info 'to)) + (org-koma-letter--determine-to-and-from info 'to)) ;; Opening. (format "\\opening{%s}\n\n" (or (plist-get info :opening) "")) ;; Letter body. contents ;; Closing. (format "\n\\closing{%s}\n" (or (plist-get info :closing) "")) - (org-koma-letter--prepare-special-contents-as-macro + (org-koma-letter--special-contents-as-macro (plist-get info :with-after-closing)) ;; Letter end. "\n\\end{letter}\n" - (org-koma-letter--prepare-special-contents-as-macro + (org-koma-letter--special-contents-as-macro (plist-get info :with-after-letter) t t) ;; Document end. "\n\\end{document}" -- 1.8.3.4 --=-=-= Content-Type: text/plain -- . . . The proofs are technical in nature and provides no real understanding. --=-=-=--