branch: externals/org-mathsheet
commit c22f1aece94bc3bf131f99396a102d9935fdc4e2
Author: Ian Martins <ia...@jhu.edu>
Commit: Ian Martins <ia...@jhu.edu>
Checkdoc fixes
---
mathsheet.org | 46 +++++++++++++++++++++++-----------------------
org-mathsheet.el | 50 +++++++++++++++++++++++++-------------------------
2 files changed, 48 insertions(+), 48 deletions(-)
diff --git a/mathsheet.org b/mathsheet.org
index 5b3bd55830..4c1440c4ce 100644
--- a/mathsheet.org
+++ b/mathsheet.org
@@ -222,10 +222,10 @@ assigns the constant directly to that named block.
#+name: variables
#+begin_src elisp :tangle org-mathsheet.el :var page=page
(defvar org-mathsheet--var-list '()
- "List of variables used in a problem")
+ "List of variables used in a problem.")
(defconst org-mathsheet--worksheet-template page
- "LaTeX template for the worksheet")
+ "LaTeX template for the worksheet.")
#+end_src
*** Scan problem
@@ -274,11 +274,11 @@ of ~open-fields~.
"Scan a problem.
This parses the problem and produces a list containing info about
- its fields. For each field it returns a list containing:
+ its fields. For each field it returns a list containing:
1. a symbol for the assigned variable or a unique placeholder
2. a list of variables this field depends on
3. a cons containing start and end markers for the field in the current
buffer
- 4. `nil' which is used by `dfs-visit' later"
+ 4. nil which is used by `dfs-visit' later"
(let ((field-index 0)
open-fields ; stack
closed-fields ; list
@@ -325,7 +325,7 @@ of ~open-fields~.
(symbol (or "." "," "+" "-" "*" "/" "^" "(" ")" "=")))
(peg-run (peg stuff)
- (lambda (x) (message "failed %s" x))
+ (lambda (x) (message "Failed %s" x))
(lambda (x)
(funcall x)
`((:fields . ,closed-fields)
@@ -376,8 +376,8 @@ both places to keep them synced.
"Reduce the field to a number.
Parse the field again, replacing spans with random numbers and
- evaluating arithmetic operations. The field shouldn't have any
- internal fields so this should result in a single number. Return
+ evaluating arithmetic operations. The field shouldn't have any
+ internal fields so this should result in a single number. Return
that number."
(with-peg-rules
((field "[" space (or math-func expression sequence assignment value)
space "]")
@@ -407,7 +407,7 @@ both places to keep them synced.
(var-lhs (substring letter)) ; var for assignment
(var-rhs "$" (substring letter) ; var for use
`(v -- (let ((val (alist-get (intern v)
org-mathsheet--var-list)))
- (or val (error "var %s not set" v)))))
+ (or val (error "Var %s not set" v)))))
(math-func (substring (or "sqrt" "sin" "cos" "tan" "asin" "acos"
"atan" "floor" "ceil" "round"))
parenthetical
`(f v -- (string-to-number (calc-eval (format "%s(%s)" f
v)))))
@@ -416,7 +416,7 @@ both places to keep them synced.
(digit [0-9]))
(peg-run (peg field)
- (lambda (x) (message "failed %s" x))
+ (lambda (x) (message "Failed %s" x))
(lambda (x) (car (funcall x))))))
#+end_src
@@ -447,10 +447,10 @@ the field.
#+name: replace-field
#+begin_src elisp :tangle org-mathsheet.el
(defun org-mathsheet--replace-field (node)
- "Replace a field with the number to which it reduces
+ "Replace a field with the number to which it reduces.
Update the current buffer by replacing the field at point in the
- current buffer with the number it reduces to. NODE contains the
+ current buffer with the number it reduces to. NODE contains the
info for the current field."
(let ((start (caaddr node))
(end (1+ (cdaddr node)))
@@ -473,13 +473,13 @@ track of which fields have been visited.
#+name: dfs-visit
#+begin_src elisp :tangle org-mathsheet.el
(defun org-mathsheet--dfs-visit (node fields)
- "Visit NODE as part of a DFS of the problem
+ "Visit NODE as part of a DFS of the problem.
Traverse the fields of a problem using depth first search to
- ensure that field replacement happens in dependency order. FIELDS
- is a list of all fields in the problem."
+ ensure that field replacement happens in dependency order.
+ FIELDS is a list of all fields in the problem."
(pcase (cadddr node)
- (1 (error "cycle detected")) ; cycle
+ (1 (error "Cycle detected")) ; cycle
(2) ; skip
(_ ; process
(setcar (cdddr node) 1) ; started
@@ -502,10 +502,10 @@ processes all fields in a problem.
#+begin_src elisp :tangle org-mathsheet.el
(defun org-mathsheet--fill-problem (full-problem)
- "Replace all fields in FULL-PROBLEM
+ "Replace all fields in FULL-PROBLEM.
Goes through all fields in the given problem in dependency order
- and replaces fields with numbers. When this completes the problem
+ and replaces fields with numbers. When this completes the problem
will be ready to solve."
(with-temp-buffer
;; stage problem in temp buffer
@@ -581,10 +581,10 @@ whole set and then reorder by ~order~.
#+name: generate-problems
#+begin_src elisp :tangle org-mathsheet.el
(defun org-mathsheet--generate-problems (template-name count)
- "Use templates from TEMPLATE-NAME to generate COUNT problems
+ "Use templates from TEMPLATE-NAME to generate COUNT problems.
Generate problems and answers based on what is defined in the
- given template table. The template table defines problem
+ given template table. The template table defines problem
templates as well as relative weights and how they should be
ordered."
(let (total-weight templates problems)
@@ -780,9 +780,9 @@ how to convert between formats, so we let it do it.
#+name: convert-to-latex
#+begin_src elisp :tangle org-mathsheet.el
(defun org-mathsheet--convert-to-latex (expr)
- "Format the given calc expression EXPR for LaTeX
+ "Format the given calc expression EXPR for LaTeX.
- EXPR should be in normal calc format. The result is the same
+ EXPR should be in normal calc format. The result is the same
expression (not simplified) but in LaTeX format."
(let* ((calc-language 'latex)
(calc-expr (math-read-expr expr))
@@ -801,8 +801,8 @@ will overwrite the same file.
(defun org-mathsheet--gen-worksheet (file-name instruction problems
prob-cols)
"Generate a worksheet with PROBLEMS.
- Write a file named FILE-NAME. Include the INSTRUCTION line at the
- top. The problems will be arranged in PROB-COLS columns. The
+ Write a file named FILE-NAME. Include the INSTRUCTION line at the
+ top. The problems will be arranged in PROB-COLS columns. The
answers will be in 4 columns."
(with-temp-file (concat file-name ".tex")
(insert org-mathsheet--worksheet-template)
diff --git a/org-mathsheet.el b/org-mathsheet.el
index 67ed7633d8..f76924c89f 100644
--- a/org-mathsheet.el
+++ b/org-mathsheet.el
@@ -25,8 +25,8 @@
;;; Commentary:
-;; This package generates dynamic math worksheets. The types and
-;; distribution of problems is highly customizable. Problem sets are
+;; This package generates dynamic math worksheets. The types and
+;; distribution of problems is highly customizable. Problem sets are
;; defined in org tables, generated in dynamic blocks for review, and
;; exported to PDF for printing.
@@ -69,21 +69,21 @@
\\end{document}"))
(defvar org-mathsheet--var-list '()
- "List of variables used in a problem")
+ "List of variables used in a problem.")
(defconst org-mathsheet--worksheet-template page
- "LaTeX template for the worksheet")
+ "LaTeX template for the worksheet.")
)
(defun org-mathsheet--scan-problem ()
"Scan a problem.
This parses the problem and produces a list containing info about
-its fields. For each field it returns a list containing:
+its fields. For each field it returns a list containing:
1. a symbol for the assigned variable or a unique placeholder
2. a list of variables this field depends on
3. a cons containing start and end markers for the field in the current buffer
-4. `nil' which is used by `dfs-visit' later"
+4. nil which is used by `dfs-visit' later"
(let ((field-index 0)
open-fields ; stack
closed-fields ; list
@@ -130,7 +130,7 @@ its fields. For each field it returns a list containing:
(symbol (or "." "," "+" "-" "*" "/" "^" "(" ")" "=")))
(peg-run (peg stuff)
- (lambda (x) (message "failed %s" x))
+ (lambda (x) (message "Failed %s" x))
(lambda (x)
(funcall x)
`((:fields . ,closed-fields)
@@ -140,8 +140,8 @@ its fields. For each field it returns a list containing:
"Reduce the field to a number.
Parse the field again, replacing spans with random numbers and
-evaluating arithmetic operations. The field shouldn't have any
-internal fields so this should result in a single number. Return
+evaluating arithmetic operations. The field shouldn't have any
+internal fields so this should result in a single number. Return
that number."
(with-peg-rules
((field "[" space (or math-func expression sequence assignment value)
space "]")
@@ -171,7 +171,7 @@ that number."
(var-lhs (substring letter)) ; var for assignment
(var-rhs "$" (substring letter) ; var for use
`(v -- (let ((val (alist-get (intern v)
org-mathsheet--var-list)))
- (or val (error "var %s not set" v)))))
+ (or val (error "Var %s not set" v)))))
(math-func (substring (or "sqrt" "sin" "cos" "tan" "asin" "acos" "atan"
"floor" "ceil" "round"))
parenthetical
`(f v -- (string-to-number (calc-eval (format "%s(%s)" f
v)))))
@@ -180,14 +180,14 @@ that number."
(digit [0-9]))
(peg-run (peg field)
- (lambda (x) (message "failed %s" x))
+ (lambda (x) (message "Failed %s" x))
(lambda (x) (car (funcall x))))))
(defun org-mathsheet--replace-field (node)
- "Replace a field with the number to which it reduces
+ "Replace a field with the number to which it reduces.
Update the current buffer by replacing the field at point in the
-current buffer with the number it reduces to. NODE contains the
+current buffer with the number it reduces to. NODE contains the
info for the current field."
(let ((start (caaddr node))
(end (1+ (cdaddr node)))
@@ -200,13 +200,13 @@ info for the current field."
(insert (number-to-string val)))))
(defun org-mathsheet--dfs-visit (node fields)
- "Visit NODE as part of a DFS of the problem
+ "Visit NODE as part of a DFS of the problem.
Traverse the fields of a problem using depth first search to
-ensure that field replacement happens in dependency order. FIELDS
-is a list of all fields in the problem."
+ensure that field replacement happens in dependency order.
+FIELDS is a list of all fields in the problem."
(pcase (cadddr node)
- (1 (error "cycle detected")) ; cycle
+ (1 (error "Cycle detected")) ; cycle
(2) ; skip
(_ ; process
(setcar (cdddr node) 1) ; started
@@ -219,10 +219,10 @@ is a list of all fields in the problem."
(setcar (cdddr node) 2)))) ; mark done
(defun org-mathsheet--fill-problem (full-problem)
- "Replace all fields in FULL-PROBLEM
+ "Replace all fields in FULL-PROBLEM.
Goes through all fields in the given problem in dependency order
-and replaces fields with numbers. When this completes the problem
+and replaces fields with numbers. When this completes the problem
will be ready to solve."
(with-temp-buffer
;; stage problem in temp buffer
@@ -244,10 +244,10 @@ will be ready to solve."
(:alg-vars . ,alg-vars)))))
(defun org-mathsheet--generate-problems (template-name count)
- "Use templates from TEMPLATE-NAME to generate COUNT problems
+ "Use templates from TEMPLATE-NAME to generate COUNT problems.
Generate problems and answers based on what is defined in the
-given template table. The template table defines problem
+given template table. The template table defines problem
templates as well as relative weights and how they should be
ordered."
(let (total-weight templates problems)
@@ -367,9 +367,9 @@ instruction line at the top of the page."
(plist-get params :prob-cols)))))
(defun org-mathsheet--convert-to-latex (expr)
- "Format the given calc expression EXPR for LaTeX
+ "Format the given calc expression EXPR for LaTeX.
-EXPR should be in normal calc format. The result is the same
+EXPR should be in normal calc format. The result is the same
expression (not simplified) but in LaTeX format."
(let* ((calc-language 'latex)
(calc-expr (math-read-expr expr))
@@ -380,8 +380,8 @@ expression (not simplified) but in LaTeX format."
(defun org-mathsheet--gen-worksheet (file-name instruction problems prob-cols)
"Generate a worksheet with PROBLEMS.
-Write a file named FILE-NAME. Include the INSTRUCTION line at the
-top. The problems will be arranged in PROB-COLS columns. The
+Write a file named FILE-NAME. Include the INSTRUCTION line at the
+top. The problems will be arranged in PROB-COLS columns. The
answers will be in 4 columns."
(with-temp-file (concat file-name ".tex")
(insert org-mathsheet--worksheet-template)
