Merge pull request #403 from garak/improve-texts

improve wording and format on texts

CHANGELOG.md

@@ -55,7 +55,7 @@
 * Added 2 new tests to twig: `knp_menu_current`, `knp_menu_ancestor`
 * Made the templates compatible with Twig 2
 * Add menu and renderer providers supporting any ArrayAccess implementations. The
-  Pimple-based providers (supporting only Pimple 1) are dperecated in favor of these
+  Pimple-based providers (supporting only Pimple 1) are deprecated in favor of these
   new providers.
 
 ## 2.0.1 (2014-08-01)
@@ -74,7 +74,7 @@
 ## 2.0.0 alpha 2 (2014-05-01)
 
 * [BC break] Changed the TwigRenderer to accept a menu template only as a string
-* [BC break] Refactored the way of rendering twig templates. Every template should extends
+* [BC break] Refactored the way of rendering twig templates. Every template should extend
   the `knp_menu.html.twig` template.
 * Introduced extension points in the MenuFactory through `Knp\Menu\Factory\ExtensionInterface`
 * [BC break compared to 2.0 alpha 1] The inheritance extension points introduced in alpha1 are
@@ -112,7 +112,7 @@
     )
     ```
 
-    The old syntax is kept until the final release, but using it will trigger a E_USER_DEPRECATED error.
+    The old syntax is kept until the final release, but using it will trigger an E_USER_DEPRECATED error.
 
 ## 2.0.0 alpha 1 (2013-06-23)
 
@@ -164,7 +164,7 @@
 * Added a ChainProvider for the menus.
 * Added the Silex extension
 * Added a RouterAwareFactory
-* Added an helper to be able to reuse the logic more easily for other templating engines
+* Added a helper to be able to reuse the logic more easily for other templating engines
 * Added a way to retrieve an item using a path in a menu tree
 * Changed the toArray method to use a depth instead of simply using a boolean flag
 * Refactored the export to array and the creation from an array

README.markdown

@@ -1,7 +1,6 @@
-KnpMenu
-=======
+# KnpMenu
 
-The KnpMenu library provides object oriented menus for PHP.
+The KnpMenu library provides object-oriented menus for PHP.
 It is used by the [KnpMenuBundle](https://github.com/KnpLabs/KnpMenuBundle) for Symfony
 but can now be used stand-alone.
 
@@ -12,9 +11,9 @@ but can now be used stand-alone.
 
 ## Installation
 
-KnpMenu uses Composer, please checkout the [composer website](https://getcomposer.org/) for more information.
+KnpMenu uses Composer, please check out the [composer website](https://getcomposer.org/) for more information.
 
-The simple following command will install `knp-menu` into your project. It also add a new
+The simple following command will install `knp-menu` into your project. It also adds a new
 entry in your `composer.json` and update the `composer.lock` as well.
 
 ```bash
@@ -96,3 +95,4 @@ the [Symfony community](https://github.com/KnpLabs/KnpMenu/graphs/contributors).
 [3]: https://github.com/derrabus
 [4]: https://github.com/garak
 [5]: https://github.com/stof
+

doc/01-Basic-Menus.md

@@ -1,5 +1,4 @@
-Creating Menus: The Basics
-==========================
+# Creating Menus: The Basics
 
 Let's face it, creating menus sucks. Menus - a common aspect of any
 site - can range from being simple and mundane to giant monsters that
@@ -9,8 +8,7 @@ This bundle solves the issue by giving you a small, yet powerful and flexible
 framework for handling your menus. While most of the examples shown here
 are simple, the menus can grow arbitrarily large and deep.
 
-Creating a menu
----------------
+## Creating a menu
 
 The menu framework centers around one main interface: `Knp\Menu\ItemInterface`.
 Items are created by a factory implementing `Knp\Menu\FactoryInterface`.
@@ -29,7 +27,7 @@ $factory = new MenuFactory();
 $menu = $factory->createItem('My menu');
 $menu->addChild('Home', ['uri' => '/']);
 $menu->addChild('Comments', ['uri' => '#comments']);
-$menu->addChild('Symfony', ['uri' => 'http://symfony.com/']);
+$menu->addChild('Symfony', ['uri' => 'https://symfony.com/']);
 
 $renderer = new ListRenderer(new Matcher());
 echo $renderer->render($menu);
@@ -46,21 +44,21 @@ The above would render the following html code:
     <a href="#comments">Comments</a>
   </li>
   <li class="last">
-    <a href="http://symfony.com/">Symfony</a>
+    <a href="https://symfony.com/">Symfony</a>
   </li>
 </ul>
 ```
 
 >**NOTE**
 >The menu framework automatically adds `first` and `last` classes to each
 >`<li>` tag at each level for easy styling. Notice also that a `current`
->class is added to the "current" menu item by uri and `current_ancestor`
+>class is added to the "current" menu item by URI and `current_ancestor`
 >to its ancestors (the classes are configurable) The above example assumes
 >the menu is being rendered on the `/comments` page, making the Comments
 >menu the "current" item.
 
 When the menu is rendered, it's actually spaced correctly so that it appears
-as shown in the source html. This is to allow for easier debugging and can
+as shown in the source HTML. This is to allow for easier debugging and can
 be turned off by passing the `true` as the second argument to the renderer.
 
 ```php
@@ -88,8 +86,7 @@ Note: You can customize the rendering by extending the `ListRenderer` and
 overwrite some of its methods. If you use the [TwigRenderer](02-Twig-Integration.md), you can overwrite
 templates. Or you can provide your own implementation of the `RendererInterface`.
 
-Working with your menu tree
----------------------------
+## Working with your menu tree
 
 Your menu tree works and acts like a multidimensional array. Specifically,
 it implements ArrayAccess, Countable and Iterator:
@@ -122,8 +119,7 @@ when creating it is the name you'll use when accessing it. By default,
 the name is also used when displaying the menu, but that can be overridden
 by setting the menu item's label (see below).
 
-Customizing each menu item
---------------------------
+## Customizing each menu item
 
 There are many ways to customize the output of each menu item. Each property
 can be customized in two ways: either by passing it as an option when creating
@@ -143,26 +139,26 @@ $menu->addChild('Home', ['uri' => '/', 'label' => 'Back to homepage']);
 $menu['Home']->setLabel('Back to homepage');
 ```
 
-### The uri
+### The URI
 
-If an item isn't given a url, then text will be output instead of a link:
+If an item isn't given a URL, then text will be output instead of a link:
 
 ```php
 <?php
 $menu->addChild('Not a link');
 $menu->addChild('Home', '/');
-$menu->addChild('Symfony', 'http://www.symfony-reloaded.org');
+$menu->addChild('Symfony', 'https://www.symfony-reloaded.org');
 ```
 
-You can also specify the uri after creation via the `setUri()` method:
+You can also specify the URI after creation via the `setUri()` method:
 
 ```php
 <?php
 $menu['Home']->setUri('/');
 ```
 
 >**NOTE**
->If you want to remove the uri of an item, set it to `null`.
+>If you want to remove the URI of an item, set it to `null`.
 
 ### Menu attributes
 
@@ -188,7 +184,7 @@ children attributes (rendered on the `<ul>` containing the list of children):
 
 ```php
 <?php
-$menu->addChild('KnpLabs.com', ['uri' => 'http://knplabs.com']);
+$menu->addChild('KnpLabs.com', ['uri' => 'https://knplabs.com']);
 $menu['KnpLabs.com']->setLinkAttribute('class', 'external-link');
 
 $menu->addChild('Not a link');
@@ -253,8 +249,7 @@ the second argument to the `render()` method:
 >extra in the item. Use it with caution as it can create some XSS holes in
 >your application if the label is coming from the user.
 
-The Current Menu Item
----------------------
+## The Current Menu Item
 
 If the menu item is matched as current, a `current` class will be added to
 the `li` around that item, as well as a `current_ancestor` around any of
@@ -307,14 +302,13 @@ $routeVoter = new \Knp\Menu\Silex\Voter\RouteVoter();
 $routeVoter->setRequest($symfonyRequest);
 ```
 
-Creating a Menu from a Tree structure
--------------------------------------
+## Creating a Menu from a Tree Structure
 
 See [Advanced Menu documentation page](01a-Advanced-Menu.md)
 
-Change the charset
-------------------
+## Change the charset
 
 ```php
 $renderer = new ListRenderer(new Matcher(), [], 'ISO-8859-1');
 ```
+

doc/01a-Advanced-Menu.md

@@ -1,5 +1,4 @@
-Advanced Menu
--------------
+# Advanced Menu
 
 You can create a menu easily from a Tree structure (a nested set for example) by
 making it implement `Knp\Menu\NodeInterface`. You will then be able

doc/02-Twig-Integration.md

@@ -1,5 +1,4 @@
-Twig Integration
-================
+# Twig Integration
 
 KnpMenu provides 2 different (and complementary) integrations with Twig:
 
@@ -9,8 +8,7 @@ KnpMenu provides 2 different (and complementary) integrations with Twig:
 
 <a name="menu-extension"></a>
 
-Using the MenuExtension
------------------------
+## Using the MenuExtension
 
 The easiest (but not best) way to render a menu inside a Twig template is
 to pass both the renderer and menu into a template:
@@ -214,8 +212,7 @@ $pimple['menu_main'] = $pimple->protect(function(array $options, $c) use ($facto
 
 <a name="twig-renderer"></a>
 
-Using the TwigRenderer
-----------------------
+## Using the TwigRenderer
 
 ### Registering the renderer
 
@@ -277,8 +274,7 @@ want.
 >The built-in templates contains some additional blocks to make it easier
 >to customize it when using the inheritance.
 
-Twig integration reference
---------------------------
+## Twig integration reference
 
 ### Functions
 

doc/03-Silex-Integration.md

@@ -1,5 +1,4 @@
-Silex 1 Integration
-===================
+# Silex 1 Integration
 
 The Silex service provider provided in KnpMenu itself is deprecated as of KnpMenu 2.3.
 Use [`knplabs/knp-menu-silex`](https://packagist.org/packages/knplabs/knp-menu-silex) instead.

doc/04-Iterators.md

@@ -1,5 +1,4 @@
-Iterating over Menus
-====================
+# Iterating over Menus
 
 The simplest way to iterate over your item object is to iterate over its
 direct children, thanks to the `IteratorAggregate` implementation. But the
@@ -18,8 +17,7 @@ D  E  F    G     H
 I          J
 ```
 
-Iterating recursively
----------------------
+## Iterating recursively
 
 The `Knp\Menu\Iterator\RecursiveItemIterator` allows you to iterate recursively
 over a tree of items. Using it is really easy: give it an item, and you will
@@ -48,7 +46,7 @@ B D I E F C G J H
 ```
 
 Changing the second argument to `\RecursiveIteratorIterator::CHILD_FIRST`
-allows you to visit children before their parent and will produce the following
+allows you to visit children before their parents and will produce the following
 order:
 
 ```
@@ -91,11 +89,10 @@ The output will now contain the root item:
 A B D I E F C G J H
 ```
 
-Filtering only current items
-----------------------------
+## Filtering only current items
 
 Getting the current items is easy with the `Knp\Menu\Iterator\CurrentItemFilterIterator`.
-It is a filter iterator applied on another iterator.
+It is a filter iterator applied to another iterator.
 
 ```php
 <?php
@@ -139,8 +136,7 @@ foreach ($iterator as $item) {
 }
 ```
 
-Filtering only displayed items
-------------------------------
+## Filtering only displayed items
 
 The `Knp\Menu\Iterator\DisplayedItemFilterIterator` allows you to filter
 items to keep only displayed ones. As hiding an item also hides its children,

doc/05-Matcher.md

@@ -1,14 +1,13 @@
-Matcher to determine the current page
-=====================================
+# Matcher to determine the current page
+
+## Basics
 
-Basics
-------
 
 A `Matcher` is capable of determining if a menu item is the menu entry for the
 current page, or an ancestor thereof. The default matcher implementation uses
 the *voter* pattern.
 
-Here is an example how to use the matcher:
+Here is an example of how to use the matcher:
 
 ```php
 use Knp\Menu\Matcher\Matcher;
@@ -25,18 +24,16 @@ use Knp\Menu\Renderer\ListRenderer;
 new ListRenderer($itemMatcher);
 ```
 
-Available voters
-----------------
+## Available voters
 
 KnpMenu provides some voters for standard cases:
 
 * `RegexVoter`: checks if the request matches a regular expression you pass to the voter
-* `RouteVoter`: uses a Symfony request to check if the current route is same as the route of the menu item
+* `RouteVoter`: uses a Symfony request to check if the current route is the same as the route of the menu item
 * `UriVoter`: compare the URI of the menu item with the URI passed to the voter
-* `CallbackVoter`: allows matching based on a callback set as `match_callback` under `extras` option of the menu item
+* `CallbackVoter`: allows matching based on a callback set as `match_callback` under the `extras` option of the menu item
 
-Create your own voters
-----------------------
+## Create your own voters
 
 You can create your own voters by implementing `VoterInterface`.
 
@@ -52,4 +49,4 @@ class MyAwesomeVoter implements VoterInterface
 Note: You can also write your own *matcher* that implements the `MatcherInterface`
 if you need something different than the voter approach.
 
-If you use the [KnpMenuBundle](http://symfony.com/doc/master/bundles/KnpMenuBundle/index.html), the RouteVoter is automatically loaded.
+If you use the [KnpMenuBundle](https://symfony.com/bundles/KnpMenuBundle/current/index.html), the RouteVoter is automatically loaded.

doc/06-FAQ.md

@@ -1,4 +1,3 @@
-FAQ
-===
+# FAQ
 
 * [How to apply the active class to an item and all ancestors](./examples/01_apply_active_class_to_whole_tree.md)

doc/examples/01_apply_active_class_to_whole_tree.md

@@ -1,8 +1,7 @@
-How to apply the active class to a item and all ancestors
-=========================================================
+# How to apply the active class to a item and all ancestors
 
-By default the active menu item is applied with a `current` class and it's ancestors are applied with a `current_ancestor` 
-class. To apply a class other than the default or apply the same class to both you can either pass it as option to the 
+By default the active menu item is applied with a `current` class and its ancestors are applied with a `current_ancestor` 
+class. To apply a class other than the default or apply the same class to both you can either pass it as an option to the 
 render method of your used renderer:
 
 ```php