On 06/28/2018 07:12 AM, Christopher Leonard wrote:
> I am writing to inform you of my brief feedback regarding the readability of
> your manual. This message does not regard a “bug”; this message is an
> informal suggestion to improve the experience of the human manual-reader.
Thanks for the feedback and the suggestions.
> 4.1 Make the Compiler Find the Bugs(fourth paragraph) there is a typo
> “not-fuly-implemented” should be “not-fully-implemented”, but my
> suggestion is to remove the double negative, and rephrase the
> style-guide positively, for example
> “Only use ‘assert’ to catch fully-implemented features of your code.”
________________________^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This sounds odd to me - as non-native English speaker - as well.
What about "Avoid to use 'assert' to mark not-fully-implemented features ...".
> 4.2. Factor Out Repeated Code“To pick a contrived example, perhaps
> it modifies a global variable which it (that [original] code) shouldn’t
> be touching in its new home.” I added the parentheses around “that code”
> and further specified the ambiguous reference.
ok
> 4.5 The File System Is Being Modyified(second paragraph)
> In this section, the form “it is possible...could be” sounded redundant.
> My suggestion: “...it is possible for the directory ‘find’ is
> searching to be concurrently moved elsewhere in the file system,
nice
> and [it is possible that] the directory in which ‘find’ is invoked be deleted
> during the search process.”
I'd like to avoid too many clarifying brackets [...] as this disturbs
the reading as well. I'd leave the latter part as is.
I've wrapped the above into a patch in your name.
Okay?
Thanks & have a nice day,
Berny
From 087a9693482476ad1a5f65133b9c8b6c57cd62ab Mon Sep 17 00:00:00 2001
From: Christopher Leonard <christopherthomasleon...@yahoo.com>
Date: Thu, 12 Jul 2018 00:43:58 +0200
Subject: [PATCH] doc: improve readability of find-maint.texi
* doc/find-maint.texi: s/fuly/fully/, and re-phrase some sentences,
e.g. use active voice.
Copyright-paperwork-exempt: Yes
---
doc/find-maint.texi | 14 +++++++-------
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/doc/find-maint.texi b/doc/find-maint.texi
index 2a5e7eaa..bbefde28 100644
--- a/doc/find-maint.texi
+++ b/doc/find-maint.texi
@@ -263,9 +263,9 @@ relating to problems with the program's execution environment should
be diagnosed with a user-oriented error message. An assertion failure
should always denote a bug in the program.
-Don't use @code{assert} to catch not-fuly-implemented features of your
-code. Finish the implementation, disable the code, or leave the
-unfinished version on a local branch.
+Avoid to use @code{assert} to mark not-fully-implemented features of
+your code as such. Finish the implementation, disable the code, or
+leave the unfinished version on a local branch.
Several programs in the findutils suite perform self-checks. See for
example the function @code{pred_sanity_check} in @file{find/pred.c}.
@@ -357,9 +357,9 @@ to be fixed. It's all to easy to miss some out when trying to fix the
bug. Equally, it's quite possible that when pasting the code into
some function, the pasted code was not quite adapted correctly to its
new environment. To pick a contrived example, perhaps it modifies a
-global variable which it that code shouldn't be touching in its new
-home. Worse, perhaps it makes some unstated assumption about the
-nature of the input arguments which is in fact not true for the
+global variable which it (that [original] code) shouldn't be touching
+in its new home. Worse, perhaps it makes some unstated assumption about
+the nature of the input arguments which is in fact not true for the
context of the now duplicated code.
A good example of the use of refactoring in findutils is the
@@ -435,7 +435,7 @@ file is deleted from the one directory you are interested in, but if
less helpful.
Bear in mind also that it is possible for the directory @code{find} is
-currently searching could be moved to another point in the filesystem,
+searching to be concurrently moved elsewhere in the file system,
and that the directory in which @code{find} was started could be
deleted.
--
2.18.0
