Bug 128543
| Summary: | [patch] remove extra line in developers handbook (tools chapter) | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Eitan Adler <eadler> | ||||
| Component: | Books & Articles | Assignee: | Gabor Pali <pgj> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Eitan Adler
2008-11-02 18:10:01 UTC
Responsible Changed From-To: freebsd-doc->pgj Snatch Hello Eitan, Could you explain why to remove this sentence? By reading the text, I do not feel any problem with it. Please, describe the reasons more in detail, otherwise I will simply close this PR. Thanks in advance. State Changed From-To: open->feedback Requires further reasoning Eitan Adler wrote:
> I feel that from the preceding sentences the statement is obvious.
> "In order to cut the grass you must use a lawnmower"
> <command>lawnmower</command>
> This cuts the grass.
>
> It seems obvious
>
I think it is primarily a didactic vehicle, a method for trying to
explain commands clearly. In your example, a specific command is given
the reader to issue, and this command may be more complex in other
situations. It may seem obvious to you, but it may not for some readers:
- What does indicate the lawnmower is started by command `lawnmower`?
(In the first sentence, there is no such postulate, it is just a general
statement.)
- If I issue command `lawnmower` what should happen exactly?
It is only a unfortunate coincidence that effect of command `lawnmower`
is the same as in the general case.
It is a very common style for presenting concepts, FreeBSD documentation
is full of them, you might also kill all the other instances in the same
section.
Please, do not think that your efforts are not appreciated, but the
proposed changes in question are highly disputable in my humble opinion.
It is rather matter of taste, and "de gustibus non est disputandum" :)
By the way... Have you tested your changes? For your information,
applying your patch directly results a broken build (because it leaves a
<para> tag unmatched.)
Cheers,
:g
Eitan Adler wrote: > Gabor PALI wrote: >> [..] >> It is a very common style for presenting concepts, FreeBSD documentation >> is full of them, you might also kill all the other instances in the same >> section. > I'll accept that. It just looked odd to me when I first saw it. > >> Please, do not think that your efforts are not appreciated, but the >> proposed changes in question are highly disputable in my humble opinion > No problem ;) > . >> It is rather matter of taste, and "de gustibus non est disputandum" :) > I could google that but, it means? "the tastes is not a thing to discuss" -- there is no reason to argue about certain topics, because there are several good solutions for a problem. Changing them would result a continuous, but senseless alternation in the sources. In this case, it is matter of choice what type of presentation style is chosen. It is also very good candidate for bike shed painting :) [1] >> By the way... Have you tested your changes? For your information, >> applying your patch directly results a broken build (because it leaves a >> <para> tag unmatched.) > 1) I created patch 2) tested 3) fixed and recreated patch 4) submitted > old patch Ah, I see. > This was my first patch to the handbook anyways. ;) It is a start. Next time you will know what to care about :) Well, I close this PR. Thanks for the submission, though. [1] http://www.freebsd.org/doc/en/books/faq/misc.html#BIKESHED-PAINTING State Changed From-To: feedback->closed We have agreed on that there is no need to change anything. |