Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Grammar, formatting, readability fixes [skip ci] #14851

Closed
wants to merge 1 commit into from

3 participants

@jonatack

No description provided.

@robin850 robin850 commented on the diff
guides/source/form_helpers.md
((12 lines not shown))
* How to generate select boxes from multiple types of data.
-* The date and time helpers Rails provides.
+* What date and time helpers Rails provides.
@robin850 Collaborator

We should use "which" instead of "what" here I think.

@robin850 thanks for the feedback. From elementary school we were taught to begin these kind of titles with one of the following words: "Who", "What", "When", "Where", "Why" & "How". They are called the 5 Ws and H.

Kipling made it easy for us to remember:
"I keep six honest serving-men
(They taught me all I knew);
Their names are What and Why and When
And How and Where and Who."

@matthewd Collaborator

"you will know the date and time helpers" and "you will know what date and time helpers" mean rather different things, but both seem perfectly valid.

Anyway, "what" is better than "which" here.

@robin850 Collaborator

Ah sorry for the noise then ! :-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@robin850 robin850 commented on the diff
guides/source/form_helpers.md
@@ -146,11 +146,9 @@ Output:
<label for="age_adult">I'm over 21</label>
```
-As with `check_box_tag`, the second parameter to `radio_button_tag` is the value of the input. Because these two radio buttons share the same name (age) the user will only be able to select one, and `params[:age]` will contain either "child" or "adult".
+As with `check_box_tag`, the second parameter to `radio_button_tag` is the value of the input. Because these two radio buttons share the same name (age), the user will only be able to select one of the two, and `params[:age]` will contain either "child" or "adult".
@robin850 Collaborator

We can say "the same name (i.e. age)" here I think. Also the "of the two" addition doesn't seem worthy, this is still crystal clear at the beginning of the sentence that there are two radio buttons, what do you think ?

Thanks. I don't feel strongly about this, but "one of the two" refers back to "two radio buttons" which IMHO is more precise and clear.

@matthewd Collaborator

I don't think "i.e." is called for... but maybe "(:age)"?

I agree that "of the two" feels more repetitious than clear... "of them"?

"of them" could be good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@robin850 robin850 commented on the diff
guides/source/form_helpers.md
((6 lines not shown))
-NOTE: Always use labels for checkbox and radio buttons. They associate text with a specific option and,
-by expanding the clickable region,
-make it easier for users to click the inputs.
+NOTE: Always use labels for checkbox and radio buttons. They associate text with a specific option and, by expanding the clickable region, make it easier for users to click the inputs.
@robin850 Collaborator

Could you please remove this change ? Actually we are slowly wrapping new additions in guides, this is why the whole file is not consistent. :-) If you want you can provide an extra commit wrapping the whole file to 80 chars (but exceptionally please do not squash them to make the review process easier).

I agree about wrapping everything to 80 characters :) but in this case the resulting formatting of that NOTE section is currently not displaying well, at least when viewing the guide on my Retina MBP, and removing the line breaks makes the section format properly again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@robin850
Collaborator

Thanks for your contribution so far @jonatack ! :-)

@jonatack

Thanks for reviewing, @robin850 :+1:

@matthewd matthewd commented on the diff
guides/source/form_helpers.md
((15 lines not shown))
* What makes a file upload form different.
-* Some cases of building forms to external resources.
+* How to build some forms to external resources.
@matthewd Collaborator

This needs a rephrase... "how to build some forms" means something quite different. But I agree the previous spelling can be improved.

Agreed.
After re-reading the section in question, how about:
"How to post forms to external resources and specify setting an authenticity_token."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@jonatack jonatack referenced this pull request from a commit in jonatack/rails
@jonatack jonatack Grammar and formatting fixes in Form Helpers Guide
Improved version of #14851 after helpful feedback from @robin850 and @matthewd.

[skip ci]
c354d33
@jonatack

Closed and feedback incorporated into #14872. Thanks.

@jonatack jonatack closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 23, 2014
  1. @jonatack
This page is out of date. Refresh to see the latest.
Showing with 12 additions and 9 deletions.
  1. +12 −9 guides/source/form_helpers.md
View
21 guides/source/form_helpers.md
@@ -1,16 +1,16 @@
Form Helpers
============
-Forms in web applications are an essential interface for user input. However, form markup can quickly become tedious to write and maintain because of form control naming and their numerous attributes. Rails does away with these complexities by providing view helpers for generating form markup. However, since they have different use-cases, developers are required to know all the differences between similar helper methods before putting them to use.
+Forms in web applications are an essential interface for user input. However, form markup can quickly become tedious to write and maintain because of the need to handle form control naming and its numerous attributes. Rails does away with these complexities by providing view helpers for generating form markup. However, since these helpers have different use cases, developers need to know all the differences between similar helper methods before putting them to use.
After reading this guide, you will know:
* How to create search forms and similar kind of generic forms not representing any specific model in your application.
-* How to make model-centric forms for creation and editing of specific database records.
+* How to make model-centric forms for creating and editing specific database records.
* How to generate select boxes from multiple types of data.
-* The date and time helpers Rails provides.
+* What date and time helpers Rails provides.
@robin850 Collaborator

We should use "which" instead of "what" here I think.

@robin850 thanks for the feedback. From elementary school we were taught to begin these kind of titles with one of the following words: "Who", "What", "When", "Where", "Why" & "How". They are called the 5 Ws and H.

Kipling made it easy for us to remember:
"I keep six honest serving-men
(They taught me all I knew);
Their names are What and Why and When
And How and Where and Who."

@matthewd Collaborator

"you will know the date and time helpers" and "you will know what date and time helpers" mean rather different things, but both seem perfectly valid.

Anyway, "what" is better than "which" here.

@robin850 Collaborator

Ah sorry for the noise then ! :-)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
* What makes a file upload form different.
-* Some cases of building forms to external resources.
+* How to build some forms to external resources.
@matthewd Collaborator

This needs a rephrase... "how to build some forms" means something quite different. But I agree the previous spelling can be improved.

Agreed.
After re-reading the section in question, how about:
"How to post forms to external resources and specify setting an authenticity_token."

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
* How to build complex forms.
--------------------------------------------------------------------------------
@@ -146,11 +146,9 @@ Output:
<label for="age_adult">I'm over 21</label>
```
-As with `check_box_tag`, the second parameter to `radio_button_tag` is the value of the input. Because these two radio buttons share the same name (age) the user will only be able to select one, and `params[:age]` will contain either "child" or "adult".
+As with `check_box_tag`, the second parameter to `radio_button_tag` is the value of the input. Because these two radio buttons share the same name (age), the user will only be able to select one of the two, and `params[:age]` will contain either "child" or "adult".
@robin850 Collaborator

We can say "the same name (i.e. age)" here I think. Also the "of the two" addition doesn't seem worthy, this is still crystal clear at the beginning of the sentence that there are two radio buttons, what do you think ?

Thanks. I don't feel strongly about this, but "one of the two" refers back to "two radio buttons" which IMHO is more precise and clear.

@matthewd Collaborator

I don't think "i.e." is called for... but maybe "(:age)"?

I agree that "of the two" feels more repetitious than clear... "of them"?

"of them" could be good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
-NOTE: Always use labels for checkbox and radio buttons. They associate text with a specific option and,
-by expanding the clickable region,
-make it easier for users to click the inputs.
+NOTE: Always use labels for checkbox and radio buttons. They associate text with a specific option and, by expanding the clickable region, make it easier for users to click the inputs.
@robin850 Collaborator

Could you please remove this change ? Actually we are slowly wrapping new additions in guides, this is why the whole file is not consistent. :-) If you want you can provide an extra commit wrapping the whole file to 80 chars (but exceptionally please do not squash them to make the review process easier).

I agree about wrapping everything to 80 characters :) but in this case the resulting formatting of that NOTE section is currently not displaying well, at least when viewing the guide on my Retina MBP, and removing the line breaks makes the section format properly again.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
### Other Helpers of Interest
@@ -442,7 +440,12 @@ WARNING: when `:include_blank` or `:prompt` are not present, `:include_blank` is
You can add arbitrary attributes to the options using hashes:
```html+erb
-<%= options_for_select([['Lisbon', 1, {'data-size' => '2.8 million'}], ['Madrid', 2, {'data-size' => '3.2 million'}]], 2) %>
+<%= options_for_select(
+ [
+ ['Lisbon', 1, { 'data-size' => '2.8 million' }],
+ ['Madrid', 2, { 'data-size' => '3.2 million' }]
+ ], 2
+) %>
output:
Something went wrong with that request. Please try again.