[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions
From: |
Lars Ingebrigtsen |
Subject: |
bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement. |
Date: |
Fri, 11 Oct 2019 22:10:57 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) |
MON KEY <monkey@sandpframing.com> writes:
> Documentation progmodes/grep.el -- numerous errors ommissions and
> opportunities for improvement.
>
> --
> There are 13 docstring references of the form: `grep-compute-defaults'
> in progmodes/grep.el and 7 more in lisp/loaddefs.el including the
> grep-compute-defaults autoload yet the function itself is not
> documented.
OK, added.
> --
> The following functions accept a CONFIRM argument:
> `lgrep', `rgrep', `zrgrep'
>
> There is no explicit documentation of the CONFIRM parameter in any of
> the docstrings for these functions.
Ditto.
> Likewise, `grep', `lgrep', `rgrep', `grep-find' docs have the
> following two vacuous statements:
>
> "[Cc]ollect output in a buffer."
> "in the grep output buffer"
>
> but do not specify which buffer e.g. the default: "*grep*".
Ditto.
> The constant `grep-expand-keywords' has the typo:
>
> "If car of an element matches, the cdr is evalled in to get the"
> ^
> Should probably be: "in order to"
>
> Also, the doc makes mention that one should
> "Note dynamic scoping of variables."
>
> but doesn't discuss what these variables are, nor why they should be
> noted.
I've now rephrased it and documented the variables.
> --
> The function `grep-expand-template' uses the term "Patch":
>
> "Patch grep COMMAND string replacing <C>, <D>, <F>, <R>, and <X>."
>
> This terminology should be avoided b/c it conflates with diff's `patch'.
> Likewise, it isn't clear what is getting replaced by the "patch".
I used "expand" instead.
> --
> The function `grep-read-files' does not document the REGEXP parameter.
Fixed.
> The variable `grep-find-ignored-directories' should indicate that it
> defaults to the value of the variable `vc-directory-exclusion-list' as
> this is an option that is user customizable it may be useful to simply
> modify the value of that variable instead.
Fixed.
> The variables `grep-template', `grep-find-template',
> `grep-highlight-matches', `grep-find-command', `grep-use-null-device'
> say:
>
> " {...} to change the default value, use Customize or call the function
> `grep-apply-setting'."
>
> "Customize" should be: "\\[customize]"
Fixed.
> Likewise, where this is a customizable variable and the intent seems
> to be that the user _customize_ them the sentence:
>
> "You can customize this variable."
>
> is already present at the bottom of each of these function's
> docstrings.
I'm guessing the intent here is to say that you can use
`grep-apply-setting' instead of Customize, so I think the repetition is OK.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
- bug#6598: Documentation: progmodes/grep.el -- numerous errors ommissions and opportunities for improvement.,
Lars Ingebrigtsen <=