[PATCH] emacs docstrings: consistent indentation, newlines, periods

[Daniel Kahn Gillmor]

On Mon 2020-05-04 00:21:36 +0300, Tomi Ollila wrote:
> Fixed emacs docstrings to be consistent. No functional change.
>
> - removed some (accidental) indentation
> - removed some trailing newlines
> - added trailing periods where missing (some exclusions)

This all looks good to me, except for the following changes.

I think if the last line of the docstring is an example, deliberately
indented to indicate that it is verbatim code, adding a trailing period
is a mistake, because it encourages naive users to make the obvious
error of including the period in their text.

These were the examples i noticed in a skim of the changeset:

> --- a/emacs/notmuch-draft.el
> +++ b/emacs/notmuch-draft.el
> @@ -45,7 +45,7 @@ (defcustom notmuch-draft-tags '("+draft")
>  For example, if you wanted to give the message a \"draft\" tag
>  but not the (normally added by default) \"inbox\" tag, you would
>  set:
> -    (\"+draft\" \"-inbox\")"
> +    (\"+draft\" \"-inbox\")."
>    :type '(repeat string)
>    :group 'notmuch-draft)
>  


> --- a/emacs/notmuch-lib.el
> +++ b/emacs/notmuch-lib.el
> @@ -145,7 +145,7 @@ (defcustom notmuch-archive-tags '("-inbox")
>  
>  For example, if you wanted to remove an \"inbox\" tag and add an
>  \"archived\" tag, you would set:
> -    (\"-inbox\" \"+archived\")"
> +    (\"-inbox\" \"+archived\")."
>    :type '(repeat string)
>    :group 'notmuch-search
>    :group 'notmuch-show)


> --- a/emacs/notmuch-message.el
> +++ b/emacs/notmuch-message.el
> @@ -33,7 +33,7 @@ (defcustom notmuch-message-replied-tags '("+replied")
>  
>  For example, if you wanted to add a \"replied\" tag and remove
>  the \"inbox\" and \"todo\" tags, you would set:
> -    (\"+replied\" \"-inbox\" \"-todo\")"
> +    (\"+replied\" \"-inbox\" \"-todo\")."
>    :type '(repeat string)
>    :group 'notmuch-send)
>  
> @@ -46,7 +46,7 @@ (defcustom notmuch-message-forwarded-tags '("+forwarded")
>  
>  For example, if you wanted to add a \"forwarded\" tag and remove
>  the \"inbox\" tag, you would set:
> -    (\"+forwarded\" \"-inbox\")"
> +    (\"+forwarded\" \"-inbox\")."
>    :type '(repeat string)
>    :group 'notmuch-send)


> --- a/emacs/notmuch-show.el
> +++ b/emacs/notmuch-show.el
> @@ -237,7 +237,7 @@ (defcustom notmuch-show-mark-read-tags '("-unread")
>  
>  For example, if you wanted to remove an \"unread\" tag and add a
>  \"read\" tag (which would make little sense), you would set:
> -    (\"-unread\" \"+read\")"
> +    (\"-unread\" \"+read\")."
>    :type '(repeat string)
>    :group 'notmuch-show)


I'd prefer this changeset to not have trailing periods when the
docstring ends in an example.   (and maybe also to clean up any trailing
periods that might already be in such a docstring, if they exist)

I recognize this is something of an aesthetic position with no
objectively correct answer, but so is the question of trailing periods,
i suppose.  I'm not going to die on this hill, though.

Regards,

        --dkg
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 227 bytes
Desc: not available
URL: <http://notmuchmail.org/pipermail/notmuch/attachments/20200521/6c968238/attachment.sig>