Address Issue-18.

This commit adds a new field to each rule type: :comment. Since
Lisp source comments are discarded on read, this provides a way
for rule authors to attach a note, or docstring, to each rule.

ChangeLog

@@ -1,4 +1,11 @@
-2021-09-16  Michael Herstine  <sp1ff@pobox.com>
+2021-10-08  Michael Herstine  <sp1ff@pobox.com>
+
+	Address Issue-18.
+	This commit adds a new field to each rule type: :comment. Since
+	Lisp source comments are discarded on read, this provides a way
+	for rule authors to attach a note, or docstring, to each rule.
+
+2021-09-24  Michael Herstine  <sp1ff@pobox.com>
 
 	elfeed-score 1.0.
 	The last obsolete symbols have been removed, with the exception of
@@ -7,6 +14,8 @@
 
 2021-09-15  Michael Herstine  <sp1ff@pobox.com>
 
+	Fixing release workflow
+
 	Remove all symbols made obsolete as of release 0.2.0.
 
 	Revising test suite.

NEWS

@@ -1,5 +1,14 @@
 elfeed-score News -- history of user-visible changes -*- outline -*-
 
+* elfeed-score 1.1
+
+** Changes in elfeed-score 1.1.0
+
+*** New Features
+
+**** address issue 18
+
+Add a :comment field to all rule types.
 * elfeed-score 1.0
 
 ** Changes to elfeed-score 1.0.0
@@ -281,7 +290,7 @@ Fixed.
 
 modeled on that of `elfeed' itself.
 
-* Changes in elfeed-score 0.3.0
+* elfeed-score 0.3
 
 ** New Features
 
@@ -301,7 +310,7 @@ A new type of scoring rule is introduced: `title-or-content'. Such a rule perfor
 
 `elfeed-score' now provides an `elfeed-search-print-entry-function' compliant function that will display each entry's score in the first column of the search view. The score format can be controlled by the customization variable `elfeed-score-score-format'.  See the README for instructions.
 
-* Changes in elfeed-score 0.2.0
+* elfeed-score 0.2
 
 ** New Features
 
@@ -313,10 +322,6 @@ Loading the package no longer affects Elfeed; the package must be enabled via a
 
 The naming scheme for public symbols changed from "elfeed-score/" to "elfeed-score-" (in accordance with the Emacs Lisp Coding Conventions. Aliases are defined for all 0.1 symbols.
 
-* elfeed-score 0.1.0
+* elfeed-score 0.1
 
 Initial release of the `elfeed-score' package.
-
-Local Variables:
-eval: (visual-line-mode)
-End:

README.org

@@ -2,7 +2,7 @@
 #+DESCRIPTION: Gnus-style scoring for Elfeed
 #+AUTHOR: Michael Herstine
 #+EMAIL: sp1ff@pobox.com
-#+DATE: <2021-09-16 Thu 08:53>
+#+DATE: <2021-10-08 Fri 15:56>
 #+AUTODATE: t
 #+OPTIONS: toc:nil org-md-headline-style:setext *:t ^:nil
 #+STARTUP: overview
@@ -23,27 +23,28 @@ While you can manually assign a score to an entry, you will likely find it more
 For instance, here's a subset of my scoring file at the moment:
 
 #+BEGIN_SRC elisp
-  ;;; Elfeed score file                                     -*- lisp -*-
-  (("title"
-    (:text "OPEN THREAD" :value -1000 :type S)
-    (:text "raymond c\\(hen\\)?" :value 250 :type r) :tags (t .(@dev)))
-   ("content"
-    (:text "type erasure" :value 500 :type s))
-   ("title-or-content"
-    (:text "california" 150 100 :type s)
-    (:text "china" 150 100 :type w))
-   ("feed"
-    (:text "Essays in Idleness" :value 250 :type S :attr t)
-    (:text "Irreal" :value 250 :type S :attr t)
-    (:text "Julia Evans" :value 100 :type :type s :attr t)
-    (:text "National Weather Service" :value 400 :type S :attr t)
-    (:text "emacs-news – sacha chua" :value 350 :type S :attr t))
-   ("authors"
-     (:text "Jim Geraghty" :value 500 :type s))
-   ("tag"
-    (:tags (t . reddit-question)
-     :value 750))
-   (mark -2500))
+    ;;; Elfeed score file                                     -*- lisp -*-
+    (("title"
+      (:text "OPEN THREAD" :value -1000 :type S)
+      (:text "raymond c\\(hen\\)?" :value 250 :type r) :tags (t .(@dev)))
+     ("content"
+      (:text "type erasure" :value 500 :type s))
+     ("title-or-content"
+      (:text "california" 150 100 :type s)
+      (:text "china" 150 100 :type w))
+     ("feed"
+      (:text "Essays in Idleness" :value 250 :type S :attr t)
+      (:text "Irreal" :value 250 :type S :attr t)
+      (:text "Julia Evans" :value 100 :type :type s :attr t)
+      (:text "National Weather Service" :value 400 :type S :attr t)
+      (:text "emacs-news – sacha chua" :value 350 :type S :attr t :comment "Essential!"))
+     ("authors"
+       (:text "Jim Geraghty" :value 500 :type s))
+     ("tag"
+      (:tags (t . reddit-question)
+       :value 750
+       :comment "Add 750 points to any entry with a tag of reddit-question"))
+     (mark -2500))
 #+END_SRC
 
 Like Gnus scoring, this may look like Lisp code, but it is not directly eval'd. It will be read by the Lisp reader, so it must at least be a valid Lisp s-expression. 
@@ -72,7 +73,7 @@ The easiest way to install elfeed-score is [[https://github.com/melpa/melpa][MEL
 If you would prefer to install the package manually, you can also download the Emacs package file on the GitHub releases [[https://github.com/sp1ff/elfeed-score/releases][page]] or from my personal [[https://www.unwoundstack/distros.html][page]]. Then say:
 
 #+BEGIN_SRC elisp
-(package-install-file "elfeed-score-1.0.0.tar")
+(package-install-file "elfeed-score-1.1.0.tar")
 #+END_SRC
 
 ** Autotools Source Distributions
@@ -81,8 +82,8 @@ You can also download Autotools source tarballs (again available either on the G
 
 #+BEGIN_SRC bash
 cd /tmp
-curl -L --output elfeed-score-1.0.0.tar.gz https://github.com/sp1ff/elfeed-score/releases/download/1.0.0/elfeed-score-1.0.0.tar.gz
-tar xvf elfeed-score-1.0.0.tar.gz && cd elfeed-score-1.0.0
+curl -L --output elfeed-score-1.1.0.tar.gz https://github.com/sp1ff/elfeed-score/releases/download/1.1.0/elfeed-score-1.1.0.tar.gz
+tar xvf elfeed-score-1.1.0.tar.gz && cd elfeed-score-1.1.0
 export EMACSLOADPATH=$HOME/.emacs.d/elpa/elfeed-20200209.1942:$EMACSLOADPATH
 ./configure
 make
@@ -97,16 +98,16 @@ The unit tests require some macros defined by the [[https://github.com/skeeto/el
 #+BEGIN_SRC bash
 cd /tmp
 git clone https://github.com/skeeto/elfeed.git
-curl -L --output=elfeed-score-1.0.0.tar.gz https://github.com/sp1ff/elfeed-score/releases/download/1.0.0/elfeed-score-1.0.0.tar.gz
-tar xvf elfeed-score-1.0.0.tar.gz && cd elfeed-score-1.0.0
-export EMACSLOADPATH=/tmp/elfeed-score-1.0.0:/tmp/elfeed:/tmp/elfeed/tests:$EMACSLOADPATH
+curl -L --output=elfeed-score-1.1.0.tar.gz https://github.com/sp1ff/elfeed-score/releases/download/1.1.0/elfeed-score-1.1.0.tar.gz
+tar xvf elfeed-score-1.1.0.tar.gz && cd elfeed-score-1.1.0
+export EMACSLOADPATH=/tmp/elfeed-score-1.1.0:/tmp/elfeed:/tmp/elfeed/tests:$EMACSLOADPATH
 ./configure
 make
 make check
 sudo make install
 #+END_SRC
 
-Again, unless you already use =EMACSLOADPATH=, you'll need to set =EMACSLOADPATH= appropriately to your system, something like =EMACSLOADPATH=/tmp/elfeed-score-1.0.0:/tmp/elfeed:/tmp/elfeed/tests:/usr/share/emacs/25.2/lisp=.
+Again, unless you already use =EMACSLOADPATH=, you'll need to set =EMACSLOADPATH= appropriately to your system, something like =EMACSLOADPATH=/tmp/elfeed-score-1.1.0:/tmp/elfeed:/tmp/elfeed/tests:/usr/share/emacs/25.2/lisp=.
 ** Building From Source
 
 Finally, you can of course just clone this repo & build there. I've started a [[https://github.com/sp1ff/elfeed-score/wiki][wiki]], whose intended audience are people looking to hack on elfeed-score, that includes build instructions.

configure.ac

@@ -1,5 +1,5 @@
 AC_PREREQ([2.69])
-AC_INIT([elfeed-score], [1.0.0], [sp1ff@pobox.com], [elfeed-score], [https://github.com/sp1ff/elfeed-score])
+AC_INIT([elfeed-score], [1.1.0], [sp1ff@pobox.com], [elfeed-score], [https://github.com/sp1ff/elfeed-score])
 AC_CONFIG_AUX_DIR([build-aux])
 AC_CONFIG_SRCDIR([./elfeed-score.el])
 AC_PROG_MAKE_SET

doc/elfeed-score.texi

@@ -371,7 +371,8 @@ The score file is plain-text file containing a single Lisp form. Under
 the hood, elfeed-score opens your file, inserts its contents into a
 temporary buffer, and calls @code{read-from-string} (@pxref{Input
 Functions, read-from-string, read-from-string, elisp, Emacs Lisp}) on
-the contents.
+the contents. Note that this means any comments will be discarded; use
+the @code{:comment} field to attach notes to your rules, instead.
 
 The form is a list of lists; each sub-list begins with a symbol or a
 string identifying that sub-list's nature & purpose. The sub-list
@@ -582,6 +583,13 @@ Rules by Feed} for how to do that.
 
 This property is optional.
 
+@item
+@code{:comment}: Rule comment
+
+An optional, free-form note on this rule. Since Lisp comments will be
+lost on read, this provides a way for the score file author to
+annotate rules.
+
 @end enumerate
 
 So, for instance, the following rule:
@@ -627,6 +635,9 @@ represented by seven properties:
 @item
 @code{:feeds} Feed scoping rules
 
+@item
+@code{:comment} Comment
+
 @end enumerate
 
 As @ref{title Rules, above, above}, only the first three elements are
@@ -669,6 +680,9 @@ The value by which an entry's score will be adjusted when the
 @item
 @code{:feeds} Feed scoping rules
 
+@item
+@code{:comment} Comment
+
 @end enumerate
 
 Note that both entry attributes are checked, so both score values have
@@ -720,6 +734,9 @@ You may wish to apply this rule only to entries that have certain tags
 (or that do @emph{not} have certain tags). See @ref{Scoping Rules by
 Tags, below, below} for how to do that.
 
+@item
+@code{:comment} Comment
+
 @end enumerate
 
 For example, this rule:
@@ -772,6 +789,9 @@ You may wish to apply this rule only to entries that came from certain
 feeds (or did @emph{not} come from certain feeds). See @ref{Scoping
 Rules by Feed, below, below} for how to do that.
 
+@item
+@code{:comment} Comment
+
 @end enumerate
 
 @node tag Rules
@@ -811,6 +831,9 @@ will apply to entries who posses @emph{none} of the tags in
 The amount by which an entry's score shall be adjusted should this
 rule match.
 
+@item
+@code{:comment} Comment
+
 @end enumerate
 
 @node link Rules
@@ -842,6 +865,9 @@ represented by seven properties:
 @item
 @code{:feeds} Feed scoping rules
 
+@item
+@code{:comment} Comment
+
 @end enumerate
 
 As @ref{title Rules, above, above}, only the first three elements are
@@ -898,6 +924,9 @@ If @code{switch} is @code{t} & the rule applies, @code{tags} (either a
 single tag or a list of tags) will be added to the entry; if
 @code{switch} is @code{nil}, they will be removed
 
+@item
+@code{:comment} Comment
+
 @end enumerate
 
 For example, the following rules:

doc/version.texi

@@ -1,4 +1,4 @@
-@set UPDATED 16 September 2021
-@set UPDATED-MONTH September 2021
-@set EDITION 1.0.0
-@set VERSION 1.0.0
+@set UPDATED 8 October 2021
+@set UPDATED-MONTH October 2021
+@set EDITION 1.1.0
+@set VERSION 1.1.0

elfeed-score-pkg.el

@@ -1,5 +1,5 @@
 (define-package
   "elfeed-score"
-  "1.0.0"
+  "1.1.0"
   "Gnus-style scoring for Elfeed"
   '((emacs "26.1") (elfeed "3.3.0")))