Org mode version 9.7-pre (9.7-pre-n/a-g63e8ca @ /home/n/.emacs.d/elpaca/builds/org/); [PATCH]: fix ob-lilypond docstrings

Org mode version 9.7-pre (9.7-pre-n/a-g63e8ca @ /home/n/.emacs.d/elpaca/builds/org/); [PATCH]: fix ob-lilypond docstrings

[No Wayman]

[-- Attachment #1: Type: text/plain, Size: 123 bytes --]


The attached patch satisfies all but two checkdoc warnings.
I left those two for someone more familiar with the package.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-ob-lilypond.el-satisfy-checkdoc.patch --]
[-- Type: text/x-patch, Size: 4690 bytes --]

From ecd5fe22458db64d86650a1a7a1e697d9ccff020 Mon Sep 17 00:00:00 2001
From: Nicholas Vollmer <iarchivedmywholelife@gmail.com>
Date: Thu, 24 Aug 2023 08:20:22 -0400
Subject: [PATCH] * lisp/ob-lilypond.el: satisfy checkdoc

(org-babel-lilypond-compile-post-tangle): fix docstring
(org-babel-lilypond-display-pdf-post-tangle): fix docstring
(org-babel-lilypond-play-midi-post-tangle): fix docstring
(org-babel-execute:lilypond): fix docstring
(org-babel-lilypond-tangle): fix docstring
(org-babel-lilypond-process-basic): fix docstring
(org-babel-lilypond-parse-line-num): fix docstring
(org-babel-lilypond-set-header-args): fix docstring
---
 lisp/ob-lilypond.el | 37 ++++++++++++-------------------------
 1 file changed, 12 insertions(+), 25 deletions(-)

diff --git a/lisp/ob-lilypond.el b/lisp/ob-lilypond.el
index 8b2bd231f..47ad0a25d 100644
--- a/lisp/ob-lilypond.el
+++ b/lisp/ob-lilypond.el
@@ -58,23 +58,13 @@ ob-lilypond-header-args
 See `org-babel-lilypond-set-header-args'.")
 
 (defvar org-babel-lilypond-compile-post-tangle t
-  "Following the org-babel-tangle (C-c C-v t) command,
-org-babel-lilypond-compile-post-tangle determines whether ob-lilypond should
-automatically attempt to compile the resultant tangled file.
-If the value is nil, no automated compilation takes place.
-Default value is t.")
+  "When non-nil, compile tangled file after `org-babel-tangle'.")
 
 (defvar org-babel-lilypond-display-pdf-post-tangle t
-  "Following a successful LilyPond compilation
-org-babel-lilypond-display-pdf-post-tangle determines whether to automate the
-drawing / redrawing of the resultant pdf.  If the value is nil,
-the pdf is not automatically redrawn.  Default value is t.")
+  "When non-nil, display pdf after successful LilyPond compilation.")
 
 (defvar org-babel-lilypond-play-midi-post-tangle t
-  "Following a successful LilyPond compilation
-org-babel-lilypond-play-midi-post-tangle determines whether to automate the
-playing of the resultant midi file.  If the value is nil,
-the midi file is not automatically played.  Default value is t")
+  "When non-nil, play midi file after successful LilyPond compilation.")
 
 (defvar org-babel-lilypond-ly-command ""
   "Command to execute lilypond on your system.
@@ -155,20 +145,17 @@ org-babel-expand-body:lilypond
     body))
 
 (defun org-babel-execute:lilypond (body params)
-  "This function is called by `org-babel-execute-src-block'.
-Depending on whether we are in arrange mode either:
-1. Attempt to execute lilypond block according to header settings
-  (This is the default basic mode)
-2. Tangle all lilypond blocks and process the result (arrange mode)"
+  "Execute lilypond src blcok according to arragne mode.
+See `org-babel-execute-src-block' for BODY and PARAMS.
+When in arrange mode, tangle all blocks and process the result.
+Otherwise, execute block according to header settings."
   (org-babel-lilypond-set-header-args org-babel-lilypond-arrange-mode)
   (if org-babel-lilypond-arrange-mode
       (org-babel-lilypond-tangle)
     (org-babel-lilypond-process-basic body params)))
 
 (defun org-babel-lilypond-tangle ()
-  "ob-lilypond specific tangle, attempts to invoke
-=ly-execute-tangled-ly= if tangle is successful.  Also passes
-specific arguments to =org-babel-tangle=."
+  "Tangle lilypond blocks, then `org-babel-liypond-execute-tangled-ly'."
   (interactive)
   (if (org-babel-tangle nil "yes" "lilypond")
       (org-babel-lilypond-execute-tangled-ly) nil))
@@ -190,7 +177,8 @@ org-babel-lilypond-paper-settings
 They are needed for mixing music and text in basic-mode.")
 
 (defun org-babel-lilypond-process-basic (body params)
-  "Execute a lilypond block in basic mode."
+  "Execute a lilypond block in basic mode.
+See `org-babel-execute-src-block' for BODY and PARAMS."
   (let* ((out-file (cdr (assq :file params)))
          (file-type (file-name-extension out-file))
 	 (cmdline (or (cdr (assq :cmdline params))
@@ -308,7 +296,7 @@ org-babel-lilypond-mark-error-line
       (goto-char temp))))
 
 (defun org-babel-lilypond-parse-line-num (&optional buffer)
-  "Extract error line number."
+  "Extract error line number in BUFFER or `current-buffer'."
   (when buffer (set-buffer buffer))
   (let ((start
          (and (search-backward ":" nil t)
@@ -441,8 +429,7 @@ org-babel-lilypond-get-header-args
          ob-lilypond-header-args)))
 
 (defun org-babel-lilypond-set-header-args (mode)
-  "Set org-babel-default-header-args:lilypond
-dependent on ORG-BABEL-LILYPOND-ARRANGE-MODE."
+  "Set lilypond babel header args from ORG-BABEL-LILYPOND-ARRANGE-MODE."
   (setq org-babel-default-header-args:lilypond
         (org-babel-lilypond-get-header-args mode)))
 
-- 
2.41.0

Re: Org mode version 9.7-pre (9.7-pre-n/a-g63e8ca @ /home/n/.emacs.d/elpaca/builds/org/); [PATCH]: fix ob-lilypond docstrings

[Ihor Radchenko]

No Wayman <iarchivedmywholelife@gmail.com> writes:

> The attached patch satisfies all but two checkdoc warnings.
> I left those two for someone more familiar with the package.

Thanks!

> Subject: [PATCH] * lisp/ob-lilypond.el: satisfy checkdoc

_S_atisfy.

> (org-babel-lilypond-compile-post-tangle): fix docstring
> (org-babel-lilypond-display-pdf-post-tangle): fix docstring
> (org-babel-lilypond-play-midi-post-tangle): fix docstring
> (org-babel-execute:lilypond): fix docstring
> (org-babel-lilypond-tangle): fix docstring
> (org-babel-lilypond-process-basic): fix docstring
> (org-babel-lilypond-parse-line-num): fix docstring
> (org-babel-lilypond-set-header-args): fix docstring

It is enough to say "Fix docstring" just for the last line and leave all
other : ... empty.

>  (defun org-babel-lilypond-set-header-args (mode)
> -  "Set org-babel-default-header-args:lilypond
> -dependent on ORG-BABEL-LILYPOND-ARRANGE-MODE."
> +  "Set lilypond babel header args from ORG-BABEL-LILYPOND-ARRANGE-MODE."

What is ORG-BABEL-LILYPOND-ARRANGE-MODE?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Org mode version 9.7-pre (9.7-pre-n/a-g63e8ca @ /home/n/.emacs.d/elpaca/builds/org/); [PATCH]: fix ob-lilypond docstrings

[No Wayman]

[-- Attachment #1: Type: text/plain, Size: 1681 bytes --]


Ihor Radchenko <yantar92@posteo.net> writes:

> No Wayman <iarchivedmywholelife@gmail.com> writes:
>
>> The attached patch satisfies all but two checkdoc warnings.
>> I left those two for someone more familiar with the package.
>
> Thanks!
>
>> Subject: [PATCH] * lisp/ob-lilypond.el: satisfy checkdoc
>
> _S_atisfy.
>
>> (org-babel-lilypond-compile-post-tangle): fix docstring
>> (org-babel-lilypond-display-pdf-post-tangle): fix docstring
>> (org-babel-lilypond-play-midi-post-tangle): fix docstring
>> (org-babel-execute:lilypond): fix docstring
>> (org-babel-lilypond-tangle): fix docstring
>> (org-babel-lilypond-process-basic): fix docstring
>> (org-babel-lilypond-parse-line-num): fix docstring
>> (org-babel-lilypond-set-header-args): fix docstring
>
> It is enough to say "Fix docstring" just for the last line and 
> leave all
> other : ... empty.

Fixed in attached patch.
 
>>  (defun org-babel-lilypond-set-header-args (mode)
>> -  "Set org-babel-default-header-args:lilypond
>> -dependent on ORG-BABEL-LILYPOND-ARRANGE-MODE."
>> +  "Set lilypond babel header args from 
>> ORG-BABEL-LILYPOND-ARRANGE-MODE."
>
> What is ORG-BABEL-LILYPOND-ARRANGE-MODE?

Looks like it's a variable that would be better served by a 
minor-mode.

#+begin_src emacs-lisp
(defvar org-babel-lilypond-arrange-mode nil
  "Non-nil turns Arrange mode on.
In Arrange mode the following settings are altered from default:
:tangle yes,    :noweb yes
:results silent :comments yes.
In addition lilypond block execution causes tangling of all 
lilypond
blocks.")
#+end_src

A minor mode would also obviate the need for 
`org-babel-lilypond-toggle-arrange-mode'.
Let's do that in a separate patch.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-lisp-ob-lilypond.el-Satisfy-checkdoc.patch --]
[-- Type: text/x-patch, Size: 4568 bytes --]

From 2acc8e219011040d76e0faa0a6f642ace480f2df Mon Sep 17 00:00:00 2001
From: Nicholas Vollmer <iarchivedmywholelife@gmail.com>
Date: Thu, 24 Aug 2023 08:20:22 -0400
Subject: [PATCH] * lisp/ob-lilypond.el: Satisfy checkdoc

(org-babel-lilypond-compile-post-tangle):
(org-babel-lilypond-display-pdf-post-tangle):
(org-babel-lilypond-play-midi-post-tangle):
(org-babel-execute:lilypond):
(org-babel-lilypond-tangle):
(org-babel-lilypond-process-basic):
(org-babel-lilypond-parse-line-num):
(org-babel-lilypond-set-header-args):
Fix docstring
---
 lisp/ob-lilypond.el | 37 ++++++++++++-------------------------
 1 file changed, 12 insertions(+), 25 deletions(-)

diff --git a/lisp/ob-lilypond.el b/lisp/ob-lilypond.el
index 8b2bd231f..b6ee91f58 100644
--- a/lisp/ob-lilypond.el
+++ b/lisp/ob-lilypond.el
@@ -58,23 +58,13 @@ ob-lilypond-header-args
 See `org-babel-lilypond-set-header-args'.")
 
 (defvar org-babel-lilypond-compile-post-tangle t
-  "Following the org-babel-tangle (C-c C-v t) command,
-org-babel-lilypond-compile-post-tangle determines whether ob-lilypond should
-automatically attempt to compile the resultant tangled file.
-If the value is nil, no automated compilation takes place.
-Default value is t.")
+  "When non-nil, compile tangled file after `org-babel-tangle'.")
 
 (defvar org-babel-lilypond-display-pdf-post-tangle t
-  "Following a successful LilyPond compilation
-org-babel-lilypond-display-pdf-post-tangle determines whether to automate the
-drawing / redrawing of the resultant pdf.  If the value is nil,
-the pdf is not automatically redrawn.  Default value is t.")
+  "When non-nil, display pdf after successful LilyPond compilation.")
 
 (defvar org-babel-lilypond-play-midi-post-tangle t
-  "Following a successful LilyPond compilation
-org-babel-lilypond-play-midi-post-tangle determines whether to automate the
-playing of the resultant midi file.  If the value is nil,
-the midi file is not automatically played.  Default value is t")
+  "When non-nil, play midi file after successful LilyPond compilation.")
 
 (defvar org-babel-lilypond-ly-command ""
   "Command to execute lilypond on your system.
@@ -155,20 +145,17 @@ org-babel-expand-body:lilypond
     body))
 
 (defun org-babel-execute:lilypond (body params)
-  "This function is called by `org-babel-execute-src-block'.
-Depending on whether we are in arrange mode either:
-1. Attempt to execute lilypond block according to header settings
-  (This is the default basic mode)
-2. Tangle all lilypond blocks and process the result (arrange mode)"
+  "Execute lilypond src blcok according to arragne mode.
+See `org-babel-execute-src-block' for BODY and PARAMS.
+When in arrange mode, tangle all blocks and process the result.
+Otherwise, execute block according to header settings."
   (org-babel-lilypond-set-header-args org-babel-lilypond-arrange-mode)
   (if org-babel-lilypond-arrange-mode
       (org-babel-lilypond-tangle)
     (org-babel-lilypond-process-basic body params)))
 
 (defun org-babel-lilypond-tangle ()
-  "ob-lilypond specific tangle, attempts to invoke
-=ly-execute-tangled-ly= if tangle is successful.  Also passes
-specific arguments to =org-babel-tangle=."
+  "Tangle lilypond blocks, then `org-babel-liypond-execute-tangled-ly'."
   (interactive)
   (if (org-babel-tangle nil "yes" "lilypond")
       (org-babel-lilypond-execute-tangled-ly) nil))
@@ -190,7 +177,8 @@ org-babel-lilypond-paper-settings
 They are needed for mixing music and text in basic-mode.")
 
 (defun org-babel-lilypond-process-basic (body params)
-  "Execute a lilypond block in basic mode."
+  "Execute a lilypond block in basic mode.
+See `org-babel-execute-src-block' for BODY and PARAMS."
   (let* ((out-file (cdr (assq :file params)))
          (file-type (file-name-extension out-file))
 	 (cmdline (or (cdr (assq :cmdline params))
@@ -308,7 +296,7 @@ org-babel-lilypond-mark-error-line
       (goto-char temp))))
 
 (defun org-babel-lilypond-parse-line-num (&optional buffer)
-  "Extract error line number."
+  "Extract error line number in BUFFER or `current-buffer'."
   (when buffer (set-buffer buffer))
   (let ((start
          (and (search-backward ":" nil t)
@@ -441,8 +429,7 @@ org-babel-lilypond-get-header-args
          ob-lilypond-header-args)))
 
 (defun org-babel-lilypond-set-header-args (mode)
-  "Set org-babel-default-header-args:lilypond
-dependent on ORG-BABEL-LILYPOND-ARRANGE-MODE."
+  "Set lilypond babel header according to MODE."
   (setq org-babel-default-header-args:lilypond
         (org-babel-lilypond-get-header-args mode)))
 
-- 
2.41.0

Re: Org mode version 9.7-pre (9.7-pre-n/a-g63e8ca @ /home/n/.emacs.d/elpaca/builds/org/); [PATCH]: fix ob-lilypond docstrings

[Ihor Radchenko]

No Wayman <iarchivedmywholelife@gmail.com> writes:

> Fixed in attached patch.

Thanks!
Applied, onto main.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=538ddecb3
  
>> What is ORG-BABEL-LILYPOND-ARRANGE-MODE?
> ...
> A minor mode would also obviate the need for 
> `org-babel-lilypond-toggle-arrange-mode'.
> Let's do that in a separate patch.

+1

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>