From 542ddd8c891e27278cdac26763b6ff8aadbfdf68 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Fri, 1 Oct 2010 23:16:05 +0200 Subject: brings csrf_meta_tags back to the generated layout After more discussion, it has be agreed that this kind of changes within reasonable margins are OK for 3.1. That is, it is fine to change a little bit the generators even if that means examples in existing books won't be exact. (Note that the singular csrf_meta_tag exists as an alias and thus those outdated examples will run, same for existing applications.) --- railties/guides/source/getting_started.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides') diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 92b9131b59..9eae712a93 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -559,7 +559,7 @@ The view is only part of the story of how HTML is displayed in your web browser. Blog <%= stylesheet_link_tag :all %> <%= javascript_include_tag :defaults %> - <%= csrf_meta_tag %> + <%= csrf_meta_tags %> -- cgit v1.2.3 From 360a8780706cc95144bef429d6fe42e9475a5400 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 5 Oct 2010 19:34:27 +0200 Subject: new guide: Ruby on Rails Guides Guidelines --- railties/guides/source/index.html.erb | 4 ++ railties/guides/source/layout.html.erb | 1 + .../source/ruby_on_rails_guides_guidelines.textile | 78 ++++++++++++++++++++++ 3 files changed, 83 insertions(+) create mode 100644 railties/guides/source/ruby_on_rails_guides_guidelines.textile (limited to 'railties/guides') diff --git a/railties/guides/source/index.html.erb b/railties/guides/source/index.html.erb index e6d327168a..d28ea24a76 100644 --- a/railties/guides/source/index.html.erb +++ b/railties/guides/source/index.html.erb @@ -161,6 +161,10 @@ Ruby on Rails Guides <%= guide('API Documentation Guidelines', 'api_documentation_guidelines.html') do %>

This guide documents the Ruby on Rails API documentation guidelines.

<% end %> + + <%= guide('Ruby on Rails Guides Guidelines', 'ruby_on_rails_guides_guidelines.html') do %> +

This guide documentes the Ruby on Rails guides Guidelines.

+ <% end %>

Release Notes

diff --git a/railties/guides/source/layout.html.erb b/railties/guides/source/layout.html.erb index 2039c76213..f0aa227c7e 100644 --- a/railties/guides/source/layout.html.erb +++ b/railties/guides/source/layout.html.erb @@ -81,6 +81,7 @@
Contributing to Rails
Contributing to Rails
API Documentation Guidelines
+
Ruby on Rails Guides Guidelines
Release Notes
Ruby on Rails 3.0 Release Notes
diff --git a/railties/guides/source/ruby_on_rails_guides_guidelines.textile b/railties/guides/source/ruby_on_rails_guides_guidelines.textile new file mode 100644 index 0000000000..818d96da79 --- /dev/null +++ b/railties/guides/source/ruby_on_rails_guides_guidelines.textile @@ -0,0 +1,78 @@ +h2. Ruby on Rails Guides Guidelines + +This guide documents guidelines for writing guides. This guide follows itself in a gracile loop. + +endprologue. + +h3. Textile + +Guides are written in "Textile":http://www.textism.com/tools/textile/. There's comprehensive documentation "here":http://redcloth.org/hobix.com/textile/ and a cheatsheet for markup "here":http://redcloth.org/hobix.com/textile/quick.html. + +h3. Prologue + +Each guide should start with motivational text at the top. That's the little introduction in the blue area. The prologue should tell the readers what's the guide about, and what will they learn. See for example the "Routing Guide":routing.html. + +h3. Titles + +The title of every guide uses +h2+, guide sections use +h3+, subsections +h4+, etc. + +Capitalize all words except for internal articles, prepositions, conjuctions, and forms of the verb to be: + + +h5. Middleware Stack is an Array +h5. When are Objects Saved? + + +Use same typography as in regular text: + + +h3. Brief Note About +Test::Unit+ +h6. The +:content_type+ Option + + +h3. API Documentation Guidelides + +The guides and the API should be coherent where appropriate. Please have a look at these particular sections of the "API Documentation Guidelines":api_documentation_guidelines.html: + +* "Wording":api_documentation_guidelines.html#wording +* "Example Code":api_documentation_guidelines.html#example-code +* "Filenames":api_documentation_guidelines.html#filenames +* "Fonts":api_documentation_guidelines.html#fonts + +Those guidelines apply also to guides. + +h3. HTML Generation + +To generate all the guides just cd into the +railties+ directory and execute + + +rake generate_guides + + +You'll need the gems erubis, i18n, and RedCloth. + +To process +my_guide.textile+ and nothing else use the +ONLY+ environment variable: + + +rake generate_guides ONLY=my_guide + + +Although by default guides that have not been modified are not processed, so +ONLY+ is rarely needed in practice. + +To force process of al the guides pass +ALL=1+. + +It is also recommended that you work with +WARNINGS=1+, this detects duplicate IDs and warns about broken internal links. + +h3. HTML validation + +Please do validate the generated HTML with + + +rake validate_guides + + +Particularly, titles get an ID generated from their content and this often leads to duplicates. Please set +WARNINGS=1+ when generating guides to detect them. The warning messages suggest a way to fix them. + +h3. Changelog + +* October 5, 2010: ported from the docrails wiki and revised by "Xavier Noria":credits.html#fxn -- cgit v1.2.3 From da34ee423f3d43c368e33d834bb70d59af16273b Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 5 Oct 2010 19:38:05 +0200 Subject: aaaaannnddd, your beloved typo only spotted in the github colored diff no matter how many passes you did before pushing --- railties/guides/source/index.html.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides') diff --git a/railties/guides/source/index.html.erb b/railties/guides/source/index.html.erb index d28ea24a76..6b897e3a6a 100644 --- a/railties/guides/source/index.html.erb +++ b/railties/guides/source/index.html.erb @@ -163,7 +163,7 @@ Ruby on Rails Guides <% end %> <%= guide('Ruby on Rails Guides Guidelines', 'ruby_on_rails_guides_guidelines.html') do %> -

This guide documentes the Ruby on Rails guides Guidelines.

+

This guide documents the Ruby on Rails guides guidelines.

<% end %> -- cgit v1.2.3 From 3b7d48cc455a04a40328e8f29b4200fdfb4f73b7 Mon Sep 17 00:00:00 2001 From: Xavier Noria Date: Tue, 5 Oct 2010 22:52:43 +0200 Subject: a couple of touches to the guides guidelines --- railties/guides/source/ruby_on_rails_guides_guidelines.textile | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'railties/guides') diff --git a/railties/guides/source/ruby_on_rails_guides_guidelines.textile b/railties/guides/source/ruby_on_rails_guides_guidelines.textile index 818d96da79..0bc409cbda 100644 --- a/railties/guides/source/ruby_on_rails_guides_guidelines.textile +++ b/railties/guides/source/ruby_on_rails_guides_guidelines.textile @@ -26,11 +26,10 @@ h5. When are Objects Saved? Use same typography as in regular text: -h3. Brief Note About +Test::Unit+ h6. The +:content_type+ Option -h3. API Documentation Guidelides +h3. API Documentation Guidelines The guides and the API should be coherent where appropriate. Please have a look at these particular sections of the "API Documentation Guidelines":api_documentation_guidelines.html: -- cgit v1.2.3 From afd76d7fe9bb5e1b90a3b1c75abe45488e871f72 Mon Sep 17 00:00:00 2001 From: Santiago Pastorino Date: Sat, 9 Oct 2010 14:50:25 -0200 Subject: Fix error in routing guide edit_photo_path needs the id as param --- railties/guides/source/routing.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides') diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile index 7d4fb69d3b..a8a8ee58ec 100644 --- a/railties/guides/source/routing.textile +++ b/railties/guides/source/routing.textile @@ -91,7 +91,7 @@ Creating a resourceful route will also expose a number of helpers to the control * +photos_path+ returns +/photos+ * +new_photo_path+ returns +/photos/new+ -* +edit_photo_path+ returns +/photos/:id/edit+ +* +edit_photo_path(id)+ returns +/photos/:id/edit+ (for instance, +edit_photo_path(10)+ returns +/photos/10/edit+) * +photo_path(id)+ returns +/photos/:id+ (for instance, +photo_path(10)+ returns +/photos/10+) Each of these helpers has a corresponding +_url+ helper (such as +photos_url+) which returns the same path prefixed with the current host, port and path prefix. -- cgit v1.2.3 From ef74ad8e0c0a1c46f7e8983e9d5460dea9bec95e Mon Sep 17 00:00:00 2001 From: Ryan Bigg Date: Mon, 11 Oct 2010 13:28:50 +1100 Subject: Remove mention to register_javascript_include_default in documentation --- railties/guides/source/action_view_overview.textile | 3 --- 1 file changed, 3 deletions(-) (limited to 'railties/guides') diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index 843dfe530d..0e1a352ebd 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -253,9 +253,6 @@ javascript_include_tag :monkey # => -h5. register_javascript_include_default - -Register one or more additional JavaScript files to be included when +javascript_include_tag :defaults+ is called. This method is typically intended to be called from plugin initialization to register additional +.js+ files that the plugin installed in +public/javascripts+. h5. register_stylesheet_expansion -- cgit v1.2.3 From 70ad6e499f405efb8b0a2e58c9742d4957c6b7c5 Mon Sep 17 00:00:00 2001 From: "Philip R. Dutton" Date: Sun, 10 Oct 2010 22:31:30 -0400 Subject: I corrected a code snippet typo in the railties/guides/source/initialization.textile file [#5779 state:resolved] --- railties/guides/source/initialization.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides') diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile index 599ddccdd6..3e02bc0158 100644 --- a/railties/guides/source/initialization.textile +++ b/railties/guides/source/initialization.textile @@ -3070,7 +3070,7 @@ The +Rails::Plugin::Configuration+ class may be a bit difficult to find at first module Rails - class Plugin < Railtie + class Plugin < Engine ... end end -- cgit v1.2.3 From a37e1a6a692cd2cc82b9b885f2a289d28bc35a33 Mon Sep 17 00:00:00 2001 From: Ugis Ozols Date: Wed, 13 Oct 2010 23:31:37 +0300 Subject: Removed miscelenous letters. --- railties/guides/source/command_line.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides') diff --git a/railties/guides/source/command_line.textile b/railties/guides/source/command_line.textile index cbdfda9215..752b5926f7 100644 --- a/railties/guides/source/command_line.textile +++ b/railties/guides/source/command_line.textile @@ -145,7 +145,7 @@ $ rails generate controller Greetings hello What all did this generate? It made sure a bunch of directories were in our application, and created a controller file, a functional test file, a helper for the view, and a view file. -Check out the controller and modify it a little (in +app/controllers/greetings_controller.rb+):ma +Check out the controller and modify it a little (in +app/controllers/greetings_controller.rb+): class GreetingsController < ApplicationController -- cgit v1.2.3 From cfb1ba023b11f82d776f9744ddbe7c826c8d7fbc Mon Sep 17 00:00:00 2001 From: Ryan Bigg and Xavier Noria Date: Thu, 14 Oct 2010 08:12:25 +1100 Subject: Use rather than underscores to fix display issue with 4.1.1.1 in the asssociation basics guide --- railties/guides/source/association_basics.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides') diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index 6996dab8c5..f6d61373e1 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -550,7 +550,7 @@ build_customer create_customer -h6(#belongs_to-association). _association_(force_reload = false) +h6(#belongs_to-association). association(force_reload = false) The association method returns the associated object, if any. If no associated object is found, it returns +nil+. -- cgit v1.2.3 From a18cefbc3a9a025a076a0f5e18f6b9991e7df8e3 Mon Sep 17 00:00:00 2001 From: Nick Quaranto Date: Thu, 14 Oct 2010 17:24:59 -0400 Subject: Fixing a small typo in the generators guide --- railties/guides/source/generators.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides') diff --git a/railties/guides/source/generators.textile b/railties/guides/source/generators.textile index b1f8ea29da..0f2cbb76dc 100644 --- a/railties/guides/source/generators.textile +++ b/railties/guides/source/generators.textile @@ -144,7 +144,7 @@ generators/initializer_generator.rb If none is found you get an error message. -INFO: The examples above put files under the application's +lib+ because said directoty belongs to +$LOAD_PATH+. +INFO: The examples above put files under the application's +lib+ because said directory belongs to +$LOAD_PATH+. h3. Customizing Your Workflow -- cgit v1.2.3 From 8be96a3bcf1a21bac38437512cac10ac9c1f952f Mon Sep 17 00:00:00 2001 From: Neil Middleton Date: Thu, 14 Oct 2010 23:11:34 +0100 Subject: Fixed casing of JavaScript (and RJS) [#183 state:resolved] --- railties/guides/source/layouts_and_rendering.textile | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'railties/guides') diff --git a/railties/guides/source/layouts_and_rendering.textile b/railties/guides/source/layouts_and_rendering.textile index 50c5986a64..088e1f817c 100644 --- a/railties/guides/source/layouts_and_rendering.textile +++ b/railties/guides/source/layouts_and_rendering.textile @@ -90,7 +90,7 @@ If we want to display the properties of all the books in our view, we can do so <%= link_to 'New book', new_book_path %> -NOTE: The actual rendering is done by subclasses of +ActionView::TemplateHandlers+. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. In Rails 2, the standard extensions are +.erb+ for ERB (HTML with embedded Ruby), +.rjs+ for RJS (javascript with embedded ruby) and +.builder+ for Builder (XML generator). +NOTE: The actual rendering is done by subclasses of +ActionView::TemplateHandlers+. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. In Rails 2, the standard extensions are +.erb+ for ERB (HTML with embedded Ruby), +.rjs+ for RJS (JavaScript with embedded ruby) and +.builder+ for Builder (XML generator). h4. Using +render+ @@ -252,7 +252,7 @@ render :inline => h5. Using +render+ with +:update+ -You can also render javascript-based page updates inline using the +:update+ option to +render+: +You can also render JavaScript-based page updates inline using the +:update+ option to +render+: render :update do |page| @@ -260,7 +260,7 @@ render :update do |page| end -WARNING: Placing javascript updates in your controller may seem to streamline small updates, but it defeats the MVC orientation of Rails and will make it harder for other developers to follow the logic of your project. We recommend using a separate rjs template instead, no matter how small the update. +WARNING: Placing JavaScript updates in your controller may seem to streamline small updates, but it defeats the MVC orientation of Rails and will make it harder for other developers to follow the logic of your project. We recommend using a separate RJS template instead, no matter how small the update. h5. Rendering Text @@ -276,7 +276,7 @@ NOTE: By default, if you use the +:text+ option, the text is rendered without us h5. Rendering JSON -JSON is a javascript data format used by many AJAX libraries. Rails has built-in support for converting objects to JSON and rendering that JSON back to the browser: +JSON is a JavaScript data format used by many AJAX libraries. Rails has built-in support for converting objects to JSON and rendering that JSON back to the browser: render :json => @product @@ -655,7 +655,7 @@ I'll discuss each of these in turn. h4. Asset Tags -Asset tags provide methods for generating HTML that links views to assets like images, videos, audio, javascript, stylesheets, and feeds. There are six types of include tag: +Asset tags provide methods for generating HTML that links views to assets like images, videos, audio, JavaScript, stylesheets, and feeds. There are six types of include tag: * +auto_discovery_link_tag+ * +javascript_include_tag+ @@ -715,7 +715,7 @@ The +defaults+ option loads the Prototype and Scriptaculous libraries: <%= javascript_include_tag :defaults %> -The +all+ option loads every javascript file in +public/javascripts+, starting with the Prototype and Scriptaculous libraries: +The +all+ option loads every JavaScript file in +public/javascripts+, starting with the Prototype and Scriptaculous libraries: <%= javascript_include_tag :all %> @@ -727,7 +727,7 @@ You can supply the +:recursive+ option to load files in subfolders of +public/ja <%= javascript_include_tag :all, :recursive => true %> -If you're loading multiple javascript files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify +:cache => true+ in your +javascript_include_tag+: +If you're loading multiple JavaScript files, you can create a better user experience by combining multiple files into a single download. To make this happen in production, specify +:cache => true+ in your +javascript_include_tag+: <%= javascript_include_tag "main", "columns", :cache => true %> @@ -962,7 +962,7 @@ The result of rendering this page into the supplied layout would be this HTML: -The +content_for+ method is very helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content inserted. It's also useful for inserting tags that load page-specific javascript or css files into the header of an otherwise generic layout. +The +content_for+ method is very helpful when your layout contains distinct regions such as sidebars and footers that should get their own blocks of content inserted. It's also useful for inserting tags that load page-specific JavaScript or css files into the header of an otherwise generic layout. h4. Using Partials -- cgit v1.2.3 From ebe61bf37c174a98019225d4aa227c6d45e69a59 Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Fri, 15 Oct 2010 21:40:32 +1100 Subject: WEBrick is the default web server, not Mongrel [#186 state:resolved] --- railties/guides/source/getting_started.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'railties/guides') diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 42b3313752..3f433c9704 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -282,7 +282,7 @@ You actually have a functional Rails application already. To see it, you need to $ rails server -This will fire up an instance of the Mongrel web server by default (Rails can also use several other web servers). To see your application in action, open a browser window and navigate to "http://localhost:3000":http://localhost:3000. You should see Rails' default information page: +This will fire up an instance of the WEBrick web server by default (Rails can also use several other web servers). To see your application in action, open a browser window and navigate to "http://localhost:3000":http://localhost:3000. You should see Rails' default information page: !images/rails_welcome.png(Welcome Aboard screenshot)! -- cgit v1.2.3 From cffae06a4f1b7aac86a7e99cfb244890f837f976 Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Fri, 15 Oct 2010 23:38:31 +1100 Subject: remove Mongrel from debugger docs --- railties/guides/source/debugging_rails_applications.textile | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) (limited to 'railties/guides') diff --git a/railties/guides/source/debugging_rails_applications.textile b/railties/guides/source/debugging_rails_applications.textile index 35069f33ad..b9d45fb13a 100644 --- a/railties/guides/source/debugging_rails_applications.textile +++ b/railties/guides/source/debugging_rails_applications.textile @@ -250,7 +250,7 @@ Make sure you have started your web server with the option +--debugger+: ~/PathTo/rails_project$ rails server --debugger -=> Booting Mongrel (use 'rails server webrick' to force WEBrick) +=> Booting WEBrick => Rails 3.0.0 application starting on http://0.0.0.0:3000 => Debugger enabled ... @@ -258,8 +258,6 @@ Make sure you have started your web server with the option +--debugger+: TIP: In development mode, you can dynamically +require \'ruby-debug\'+ instead of restarting the server, if it was started without +--debugger+. -In order to use Rails debugging you'll need to be running either *WEBrick* or *Mongrel*. For the moment, no alternative servers are supported. - h4. The Shell As soon as your application calls the +debugger+ method, the debugger will be started in a debugger shell inside the terminal window where you launched your application server, and you will be placed at ruby-debug's prompt +(rdb:n)+. The _n_ is the thread number. The prompt will also show you the next line of code that is waiting to run. -- cgit v1.2.3