# A wrong sentence?



## fender0107401 (Aug 26, 2010)

From Handbook 29.2.3 Command-Line Options 



> Novice users may be pleased to note that these parameters usually do not need to be modified, although we mention the rate-limiting options below as they be useful should you find that you are receiving an excessive amount of connections.


----------



## SirDice (Aug 26, 2010)

Nothing wrong with the sentence. Although I can imagine it's a bit hard to read if you're not that good with English.


----------



## mix_room (Aug 26, 2010)

SirDice said:
			
		

> Nothing wrong with the sentence. Although I can imagine it's a bit hard to read if you're not that good with English.



Actually there is something wrong with the sentence, but it might be a bit hard to spot if you are not good at reading.  



> although we mention the rate-limiting options below as they be useful should you find that you are receiving an excessive amount of connections.



should probably be something like 'as they _could_ be useful'. 

A much easier sentence would be: 


> Novice users may be pleased to note that these parameters usually do not need to be modified. The rate limiting-options are mentioned as they could be useful if you find that you are receiving an excessive amount of connections.


----------



## SirDice (Aug 26, 2010)

mix_room said:
			
		

> A much easier sentence would be:
> 
> 
> > Novice users may be pleased to note that these parameters usually do not need to be modified. The rate limiting-options are mentioned as they could be useful if you find that you are receiving an excessive amount of connections.


I fully agree.


----------



## DutchDaemon (Aug 26, 2010)

File a doc-pr. They usually find their way into the next incarnation of the relevant manuals (if they be useful).


----------



## mix_room (Aug 26, 2010)

Since I am unable to find the corresponding section in the handbook I suggest TS files the doc-pr. Feel free to use my suggestion, even to take credit for it.


----------



## wblock@ (Aug 26, 2010)

fender0107401 said:
			
		

> From Handbook 29.2.3 Command-Line Options



It's in "The inetd Super-Server" chapter (chapter numbers change).



> Novice users may be pleased to note that these parameters usually do not need to be modified, although we mention the rate-limiting options below as they be useful should you find that you are receiving an excessive amount of connections.



If you're working on it anyway, best to rewrite to get rid of the overly long sentences, the wishy-washy "may/could/should" (I want to call this "passive voice", but I'm not sure that's right), and make it more concise:

"These parameters usually do not need to be modified.  Useful rate-limiting options are mentioned below in case you are receiving an excessive number of connections."


----------



## fender0107401 (Aug 26, 2010)

The exact location is: FreeBSD Handbook -> Chapter 29 Network Servers -> 29.2 The inetd â€œSuper-Serverâ€ -> 29.2.3 Command-Line Options

Next time I will write it clearly.

Nevertheless, I will file a report.

Sometimes the long sentence cause some confusion.


----------



## mix_room (Aug 27, 2010)

wblock said:
			
		

> If you're working on it anyway, best to rewrite to get rid of the overly long sentences, the wishy-washy "may/could/should" (I want to call this "passive voice", but I'm not sure that's right), and make it more concise:



'may/could/should/must' are not 'wishy-washy'. They have well defined meaning and are very useful. See eg.: http://www.faqs.org/rfcs/rfc2119.html



> "These parameters usually do not need to be modified.  Useful rate-limiting options are mentioned below in case you are receiving an excessive number of connections."



'The rate-limiting options mentioned below can be used if you are receiving an excessive number of connections' is even shorter, and perhaps clearer.


----------



## Savagedlight (Aug 27, 2010)

Some of these new sentence suggestions lose some important data, though.
The original sentence claims that the parameters are fine at their default values; But they may not be optimal when you receive an excessive amount of connections.

My suggestion:
"The following rate-limiting parameters should be fine at their default values, but it may be beneficial to adjust them if you receive an excessive amount of connections."
or
"The following rate-limiting parameters should be fine at their default values, but they may not be optimal if you receive an excessive amount of connections."


----------



## wblock@ (Aug 27, 2010)

Savagedlight said:
			
		

> Some of these new sentence suggestions lose some important data, though.
> The original sentence claims that the parameters are fine at their default values; But they may not be optimal when you receive an excessive amount of connections.
> 
> My suggestion:
> ...



But here you've changed the meaning also.  The original wording was talking about all of the inetd options being fine at their defaults.  This rewording makes that apply only to the rate-limiting options.


----------



## wblock@ (Aug 27, 2010)

mix_room said:
			
		

> 'may/could/should/must' are not 'wishy-washy'. They have well defined meaning and are very useful. See eg.: http://www.faqs.org/rfcs/rfc2119.html



You added "must", which is not in the same class as the others.  But we're not writing an RFC, and these words aren't being defined for use in a standard.

May/could/should/might/probably often means "I don't really know, and don't blame me if this doesn't work".  (I'm guilty of this far too often, but we're talking about the Handbook here.)

Most of the time, these words add no value.  Or worse; if it says I may/could/should do something, it implies the question of why, often without an answer.


----------



## mix_room (Aug 30, 2010)

wblock said:
			
		

> You added "must", which is not in the same class as the others.  But we're not writing an RFC, and these words aren't being defined for use in a standard.



I linked the RFC because I like the way the words are defined there. They are very clear in their meaning when used properly. 



> May/could/should/might/probably often means "I don't really know, and don't blame me if this doesn't work".  (I'm guilty of this far too often, but we're talking about the Handbook here.)


Incorrect usage of the word does not imply that the word is inaccurate. That is like saying that a hammer is an inaccurate tool because you are attempting to use it as a foot-rest. 



> Most of the time, these words add no value.  Or worse; if it says I may/could/should do something, it implies the question of why, often without an answer.


could/should imply two different things: should is a suggestion, while could is purely voluntary. If it says could you need a reason to do something, if is says should you need a reason not to do it. 

IMO: 

```
must not < could < should < must
```

I agree that words are often misused. BUT I do not agree that the words should be avoided, as they clearly add meaning when correctly used.


----------

