Polish docs for URL and XML helpers and deprecate obsolete options for String helper random_string() and URL helper url_title()

5 files changed, 225 insertions, 149 deletions

diff --git a/user_guide_src/source/changelog.rst b/user_guide_src/source/changelog.rst
index 3296e876d..27fc975b5 100644
--- a/user_guide_src/source/changelog.rst
+++ b/user_guide_src/source/changelog.rst
@@ -66,31 +66,33 @@ Release Date: Not Released
 	 - Added function ``date_range()`` that generates a list of dates between a specified period.
    -  ``create_captcha()`` accepts additional colors parameter, allowing for color customization.
    -  :doc:`URL Helper <helpers/url_helper>` changes include:
-	 - ``url_title()`` will now trim extra dashes from beginning and end.
-	 - ``anchor_popup()`` will now fill the *href* attribute with the URL and its JS code will return FALSE instead.
-	 - Added JS window name support to ``anchor_popup()`` function.
-	 - Added support (auto-detection) for HTTP/1.1 response code 303 in ``redirect()``.
-	 - "auto" method in ``redirect()`` now chooses the "refresh" method only on IIS servers, instead of all servers on Windows.
+	 - Deprecated *separator* options **dash** and **underscore** for function :php:func:`url_title()` (they are only aliases for '-' and '_' respectively).
+	 - :php:func:`url_title()` will now trim extra dashes from beginning and end.
+	 - :php:func:`anchor_popup()` will now fill the *href* attribute with the URL and its JS code will return FALSE instead.
+	 - Added JS window name support to the :php:func:`anchor_popup()` function.
+	 - Added support (auto-detection) for HTTP/1.1 response code 303 in :php:func:`redirect()`.
+	 - Changed :php:func:`redirect()` to only choose the **refresh** method only on IIS servers, instead of all servers on Windows (when **auto** is used).
    -  Added XHTML Basic 1.1 doctype to :doc:`HTML Helper <helpers/html_helper>`.
    -  :doc:`Inflector Helper <helpers/inflector_helper>` changes include:
-	 -  Changed :php:func:`humanize()` to allow passing an input separator as its second parameter.
-	 -  Refactored :php:func:`plural()` and :php:func:`singular()` to avoid double pluralization and support more words.
+	 - Changed :php:func:`humanize()` to allow passing an input separator as its second parameter.
+	 - Refactored :php:func:`plural()` and :php:func:`singular()` to avoid double pluralization and support more words.
    -  Added an optional third parameter to ``force_download()`` that enables/disables sending the actual file MIME type in the Content-Type header (disabled by default).
    -  Added a work-around in ``force_download()`` for a bug Android <= 2.1, where the filename extension needs to be in uppercase.
    -  :doc:`Form Helper <helpers/form_helper>` changes include:
-	 -  :php:func:`form_dropdown()` will now also take an array for unity with other form helpers.
-	 -  :php:func:`form_prep()`'s second argument now only accepts a boolean value, which determines whether the value is escaped for a <textarea> or a regular <input> element.
+	 - :php:func:`form_dropdown()` will now also take an array for unity with other form helpers.
+	 - :php:func:`form_prep()`'s second argument now only accepts a boolean value, which determines whether the value is escaped for a <textarea> or a regular <input> element.
    -  :doc:`Security Helper <helpers/security_helper>` changes include:
-	 -  :php:func:`do_hash()` now uses PHP's native ``hash()`` function (supporting more algorithms) and is deprecated.
-	 -  :php:func:`strip_image_tags()` is now an alias for the same method in the :doc:`Security Library <libraries/security>`.
+	 - :php:func:`do_hash()` now uses PHP's native ``hash()`` function (supporting more algorithms) and is deprecated.
+	 - :php:func:`strip_image_tags()` is now an alias for the same method in the :doc:`Security Library <libraries/security>`.
    -  Removed previously deprecated helper function ``js_insert_smiley()`` from :doc:`Smiley Helper <helpers/smiley_helper>`.
    -  :doc:`File Helper <helpers/file_helper>` changes include:
-	 - ``set_realpath()`` can now also handle file paths as opposed to just directories.
-	 - Added an optional paramater to ``delete_files()`` to enable it to skip deleting files such as .htaccess and index.html.
-	 - ``read_file()`` is now a deprecated alias of ``file_get_contents()``.
+	 - :php:func:`set_realpath()` can now also handle file paths as opposed to just directories.
+	 - Added an optional paramater to :php:func:`delete_files()` to enable it to skip deleting files such as *.htaccess* and *index.html*.
+	 - Deprecated function ``read_file()`` - it's just an alias for PHP's native ``file_get_contents()``.
    -  :doc:`String Helper <helpers/string_helper>` changes include:
-	 -  Deprecated function :php:func:`repeater()` - it's just an alias for PHP's native ``str_repeat()``.
-	 -  Deprecated function :php:func:`trim_slashes()` - it's just an alias for PHP's native ``trim()`` (with a slash as its second argument).
+	 - Deprecated function ``repeater()`` - it's just an alias for PHP's native ``str_repeat()``.
+	 - Deprecated function ``trim_slashes()`` - it's just an alias for PHP's native ``trim()`` (with a slash as its second argument).
+	 - Deprecated randomization type options **unique** and **encrypt** for funcion :php:func:`random_string()` (they are only aliases for **md5** and **sha1** respectively).
    -  :doc:`Directory Helper <helpers/directory_helper>` ``directory_map()`` will now append DIRECTORY_SEPARATOR to directory names in the returned array.
    -  Deprecated the :doc:`Email Helper <helpers/email_helper>` as its ``valid_email()``, ``send_email()`` functions are now only aliases for PHP native functions ``filter_var()`` and ``mail()`` respectively.
 
diff --git a/user_guide_src/source/helpers/string_helper.rst b/user_guide_src/source/helpers/string_helper.rst
index 1c2404400..d0d302476 100644
--- a/user_guide_src/source/helpers/string_helper.rst
+++ b/user_guide_src/source/helpers/string_helper.rst
@@ -31,18 +31,13 @@ Useful for creating passwords or generating random hashes.
 The first parameter specifies the type of string, the second parameter
 specifies the length. The following choices are available:
 
-alpha, alunum, basic, numeric, nozero, md5 and sha1
-
 -  **alpha**: A string with lower and uppercase letters only.
 -  **alnum**: Alpha-numeric string with lower and uppercase characters.
 -  **basic**: A random number based on ``mt_rand()``.
 -  **numeric**: Numeric string.
 -  **nozero**: Numeric string with no zeros.
--  **unique**: Encrypted with MD5 and uniqid(). Note: The length
-   parameter is not available for this type. Returns a fixed length 32
-   character string.
--  **md5**: An encrypted random number based on ``md5()``.
--  **sha1**: An encrypted random number based on ``sha1()``.
+-  **md5**: An encrypted random number based on ``md5()`` (fixed length of 32).
+-  **sha1**: An encrypted random number based on ``sha1()`` (fixed length of 40).
 
 Usage example::
 
diff --git a/user_guide_src/source/helpers/text_helper.rst b/user_guide_src/source/helpers/text_helper.rst
index 2b71432ef..aec36c9a7 100644
--- a/user_guide_src/source/helpers/text_helper.rst
+++ b/user_guide_src/source/helpers/text_helper.rst
@@ -59,7 +59,7 @@ The third parameter is an optional suffix added to the string, if
 undeclared this helper uses an ellipsis.
 
 .. note:: If you need to truncate to an exact number of characters please
-	see the :php:func:`ellipsize()` function below.
+	see the :ref:`ellipsize()` function below.
 
 ascii_to_entities()
 ===================
@@ -193,6 +193,8 @@ Example::
 
 	// Would produce:  Here is a simple string of text that will help us demonstrate this function
 
+.. _ellipsize():
+
 ellipsize()
 ===========
 
diff --git a/user_guide_src/source/helpers/url_helper.rst b/user_guide_src/source/helpers/url_helper.rst
index 1987dfb72..5b8fa5f44 100644
--- a/user_guide_src/source/helpers/url_helper.rst
+++ b/user_guide_src/source/helpers/url_helper.rst
@@ -9,9 +9,7 @@ The URL Helper file contains functions that assist in working with URLs.
 Loading this Helper
 ===================
 
-This helper is loaded using the following code
-
-::
+This helper is loaded using the following code::
 
 	$this->load->helper('url');
 
@@ -20,119 +18,135 @@ The following functions are available:
 site_url()
 ==========
 
+.. php:function:: site_url($uri = '')
+
+	:param	string	$uri: URI string
+	:returns:	string
+
 Returns your site URL, as specified in your config file. The index.php
-file (or whatever you have set as your site index_page in your config
+file (or whatever you have set as your site **index_page** in your config
 file) will be added to the URL, as will any URI segments you pass to the
-function, and the url_suffix as set in your config file.
+function, plus the **url_suffix** as set in your config file.
 
 You are encouraged to use this function any time you need to generate a
 local URL so that your pages become more portable in the event your URL
 changes.
 
 Segments can be optionally passed to the function as a string or an
-array. Here is a string example
+array. Here is a string example::
 
-::
-
-	echo site_url("news/local/123");
+	echo site_url('news/local/123');
 
 The above example would return something like:
-http://example.com/index.php/news/local/123
-
-Here is an example of segments passed as an array
+*http://example.com/index.php/news/local/123*
 
-::
+Here is an example of segments passed as an array::
 
 	$segments = array('news', 'local', '123');
 	echo site_url($segments);
 
+This function is an alias for ``CI_Config::site_url()``. For more info,
+please see the :doc:`Config Library <../libraries/config>` documentation.
+
 base_url()
 ===========
 
-Returns your site base URL, as specified in your config file. Example
+.. php:function:: base_url($uri = '')
 
-::
+	:param	string	$uri: URI string
+	:returns:	string
 
-	echo base_url();
+Returns your site base URL, as specified in your config file. Example::
 
-This function returns the same thing as `site_url`, without the
-index_page or url_suffix being appended.
+	echo base_url();
 
-Also like site_url, you can supply segments as a string or an array.
-Here is a string example
+This function returns the same thing as :php:func:`site_url()`, without
+the *index_page* or *url_suffix* being appended.
 
-::
+Also like :php:func:`site_url()`, you can supply segments as a string or
+an array. Here is a string example::
 
 	echo base_url("blog/post/123");
 
 The above example would return something like:
-http://example.com/blog/post/123
-
-This is useful because unlike `site_url()`, you can supply a string to a
-file, such as an image or stylesheet. For example
+*http://example.com/blog/post/123*
 
-::
+This is useful because unlike :php:func:`site_url()`, you can supply a
+string to a file, such as an image or stylesheet. For example::
 
 	echo base_url("images/icons/edit.png");
 
 This would give you something like:
-http://example.com/images/icons/edit.png
+*http://example.com/images/icons/edit.png*
+
+This function is an alias for ``CI_Config::base_url()``. For more info,
+please see the :doc:`Config Library <../libraries/config>` documentation.
 
 current_url()
 =============
 
+.. php:function:: current_url()
+
+	:returns:	string
+
 Returns the full URL (including segments) of the page being currently
 viewed.
 
+.. note:: Calling this function is the same as doing this:
+	|
+	| site_url(uri_string());
+
 uri_string()
 ============
 
-Returns the URI segments of any page that contains this function. For
-example, if your URL was this
+.. php:function:: uri_string()
 
-::
+	:returns:	string
 
-	http://some-site.com/blog/comments/123
+Returns the URI segments of any page that contains this function.
+For example, if your URL was this::
 
-The function would return
+	http://some-site.com/blog/comments/123
 
-::
+The function would return::
 
 	/blog/comments/123
 
+This function is an alias for ``CI_Config::uri_string()``. For more info,
+please see the :doc:`Config Library <../libraries/config>` documentation.
+
 index_page()
 ============
 
-Returns your site "index" page, as specified in your config file.
-Example
+.. php:function:: index_page()
+
+	:returns:	string
 
-::
+Returns your site **index_page**, as specified in your config file.
+Example::
 
 	echo index_page();
 
 anchor()
 ========
 
-Creates a standard HTML anchor link based on your local site URL
-
-::
+.. php:function:: anchor($uri = '', $title = '', $attributes = '')
 
-	<a href="http://example.com">Click Here</a>
+	:param	string	$uri: URI string
+	:param	string	$title: Anchor title
+	:param	mixed	$attributes: HTML attributes
+	:returns:	string
 
-The tag has three optional parameters
-
-::
-
-	anchor(uri segments, text, attributes)
+Creates a standard HTML anchor link based on your local site URL.
 
 The first parameter can contain any segments you wish appended to the
-URL. As with the site_url() function above, segments can be a string or
-an array.
+URL. As with the :php:func:`site_url()` function above, segments can
+be a string or an array.
 
 .. note:: If you are building links that are internal to your application
-	do not include the base URL (http://...). This will be added automatically
-	from the information specified in your config file. Include only the
-	URI segments you wish appended to the URL.
+	do not include the base URL (http://...). This will be added
+	automatically from the information specified in your config file.
+	Include only the URI segments you wish appended to the URL.
 
 The second segment is the text you would like the link to say. If you
 leave it blank, the URL will be used.
@@ -141,41 +155,43 @@ The third parameter can contain a list of attributes you would like
 added to the link. The attributes can be a simple string or an
 associative array.
 
-Here are some examples
-
-::
+Here are some examples::
 
 	echo anchor('news/local/123', 'My News', 'title="News title"');
-
-Would produce: <a href="http://example.com/index.php/news/local/123"
-title="News title">My News</a>
-
-::
+	// Prints: <a href="http://example.com/index.php/news/local/123" title="News title">My News</a>
 
 	echo anchor('news/local/123', 'My News', array('title' => 'The best news!'));
+	// Prints: <a href="http://example.com/index.php/news/local/123" title="The best news!">My News</a>
 
-Would produce: <a href="http://example.com/index.php/news/local/123"
-title="The best news!">My News</a>
+	echo anchor('', 'Click here');
+	// Prints: <a href="http://example.com">Click Here</a>
 
 anchor_popup()
 ==============
 
-Nearly identical to the anchor() function except that it opens the URL
-in a new window. You can specify JavaScript window attributes in the
-third parameter to control how the window is opened. If the third
-parameter is not set it will simply open a new window with your own
-browser settings. Here is an example with attributes
+.. php:function:: anchor_popup($uri = '', $title = '', $attributes = FALSE)
 
-::
+	:param	string	$uri: URI string
+	:param	string	$title: Anchor title
+	:param	mixed	$attributes: HTML attributes
+	:returns:	string
+
+Nearly identical to the :php:func:``anchor()`` function except that it
+opens the URL in a new window. You can specify JavaScript window
+attributes in the third parameter to control how the window is opened.
+If the third parameter is not set it will simply open a new window with
+your own browser settings.
+
+Here is an example with attributes::
 
 	$atts = array(
-		'width'       => '800',
-		'height'      => '600',
+		'width'       => 800,
+		'height'      => 600,
 		'scrollbars'  => 'yes',
 		'status'      => 'yes',
 		'resizable'   => 'yes',
-		'screenx'     => '0',
-		'screeny'     => '0',
+		'screenx'     => 0,
+		'screeny'     => 0,
 		'window_name' => '_blank'
 	);
 
@@ -184,13 +200,11 @@ browser settings. Here is an example with attributes
 .. note:: The above attributes are the function defaults so you only need to
 	set the ones that are different from what you need. If you want the
 	function to use all of its defaults simply pass an empty array in the
-	third parameter
-
-::
+	third parameter:
+	|
+	| echo anchor_popup('news/local/123', 'Click Me!', array());
 
-	echo anchor_popup('news/local/123', 'Click Me!', array());
-
-.. note:: The 'window_name' is not really an attribute, but an argument to
+.. note:: The **window_name** is not really an attribute, but an argument to
 	the JavaScript `window.open() <http://www.w3schools.com/jsref/met_win_open.asp>`
 	method, which accepts either a window name or a window target.
 
@@ -200,117 +214,149 @@ browser settings. Here is an example with attributes
 mailto()
 ========
 
-Creates a standard HTML email link. Usage example
+.. php:function:: mailto($email, $title = '', $attributes = '')
 
-::
+	:param	string	$email: E-mail address
+	:param	string	$title: Anchor title
+	:param	mixed	$attributes: HTML attributes
+	:returns:	string
 
-	echo mailto('me@my-site.com', 'Click Here to Contact Me');
+Creates a standard HTML e-mail link. Usage example::
 
-As with the anchor() tab above, you can set attributes using the third
-parameter:
+	echo mailto('me@my-site.com', 'Click Here to Contact Me');
 
-::
+As with the :php:func:`anchor()` tab above, you can set attributes using the
+third parameter::
 
-    $attributes = array('title' => 'Mail me');
-    echo mailto('me@my-site.com', 'Contact Me', $attributes);
+	$attributes = array('title' => 'Mail me');
+	echo mailto('me@my-site.com', 'Contact Me', $attributes);
 
 safe_mailto()
 =============
 
-Identical to the above function except it writes an obfuscated version
-of the mailto tag using ordinal numbers written with JavaScript to help
-prevent the email address from being harvested by spam bots.
+.. php:function:: safe_mailto($email, $title = '', $attributes = '')
+
+	:param	string	$email: E-mail address
+	:param	string	$title: Anchor title
+	:param	mixed	$attributes: HTML attributes
+	:returns:	string
+
+Identical to the :php:func:`mailto()` function except it writes an obfuscated
+version of the *mailto* tag using ordinal numbers written with JavaScript to
+help prevent the e-mail address from being harvested by spam bots.
 
 auto_link()
 ===========
 
-Automatically turns URLs and email addresses contained in a string into
-links. Example
+.. php:function:: auto_link($str, $type = 'both', $popup = FALSE)
+
+	:param	string	$str: Input string
+	:param	string	$type: Link type ('email', 'url' or 'both')
+	:param	bool	$popup: Whether to create popup links
+	:returns:	string
 
-::
+Automatically turns URLs and e-mail addresses contained in a string into
+links. Example::
 
 	$string = auto_link($string);
 
-The second parameter determines whether URLs and emails are converted or
+The second parameter determines whether URLs and e-mails are converted or
 just one or the other. Default behavior is both if the parameter is not
-specified. Email links are encoded as safe_mailto() as shown above.
+specified. E-mail links are encoded as :php:func:`safe_mailto()` as shown
+above.
 
-Converts only URLs
-
-::
+Converts only URLs::
 
 	$string = auto_link($string, 'url');
 
-Converts only Email addresses
-
-::
+Converts only e-mail addresses::
 
 	$string = auto_link($string, 'email');
 
 The third parameter determines whether links are shown in a new window.
-The value can be TRUE or FALSE (boolean)
-
-::
+The value can be TRUE or FALSE (boolean)::
 
 	$string = auto_link($string, 'both', TRUE);
 
 url_title()
 ===========
 
+.. php:function:: url_title($str, $separator = '-', $lowercase = FALSE)
+
+	:param	string	$str: Input string
+	:param	string	$separator: Word separator
+	:param	string	$lowercase: Whether to transform the output string to lower-case
+	:returns:	string
+
 Takes a string as input and creates a human-friendly URL string. This is
 useful if, for example, you have a blog in which you'd like to use the
-title of your entries in the URL. Example
-
-::
+title of your entries in the URL. Example::
 
 	$title = "What's wrong with CSS?";
-	$url_title = url_title($title);  // Produces:  Whats-wrong-with-CSS
+	$url_title = url_title($title);
+	// Produces: Whats-wrong-with-CSS
 
 The second parameter determines the word delimiter. By default dashes
-are used. Options are: dash, or underscore
+are used. Preferred options are: **-** (dash) or **_** (underscore)
 
-::
+Example::
 
 	$title = "What's wrong with CSS?";
-	$url_title = url_title($title, 'underscore');  // Produces:  Whats_wrong_with_CSS
+	$url_title = url_title($title, 'underscore');
+	// Produces: Whats_wrong_with_CSS
+
+.. note:: Old usage of 'dash' and 'underscore' as the second parameter
+	is DEPRECATED.
 
 The third parameter determines whether or not lowercase characters are
-forced. By default they are not. Options are boolean TRUE/FALSE
+forced. By default they are not. Options are boolean TRUE/FALSE.
 
-::
+Example::
 
 	$title = "What's wrong with CSS?";
-	$url_title = url_title($title, 'underscore', TRUE);  // Produces:  whats_wrong_with_css
+	$url_title = url_title($title, 'underscore', TRUE);
+	// Produces: whats_wrong_with_css
 
 prep_url()
 ----------
 
-This function will add http:// in the event that a scheme is missing
-from a URL. Pass the URL string to the function like this
+.. php:function:: prep_url($str = '')
+
+	:param	string	$str: URL string
+	:returns:	string
 
-::
+This function will add http:// in the event that a protocol prefix
+is missing from a URL.
 
-	$url = "example.com";
-	$url = prep_url($url);
+Pass the URL string to the function like this::
+
+	$url = prep_url('example.com');
 
 redirect()
 ==========
 
+.. php:function:: redirect($uri = '', $method = 'auto', $code = NULL)
+
+	:param	string	$uri: URI string
+	:param	string	$method: Redirect method ('auto', 'location' or 'refresh')
+	:param	string	$code: HTTP Response code (usually 302 or 303)
+	:returns:	void
+
 Does a "header redirect" to the URI specified. If you specify the full
 site URL that link will be built, but for local links simply providing
 the URI segments to the controller you want to direct to will create the
 link. The function will build the URL based on your config file values.
 
 The optional second parameter allows you to force a particular redirection
-method. The available methods are "location" or "refresh", with location
-being faster but less reliable on IIS servers. The default is "auto",
-which will attempt to intelligently choose the method based on the server
-environment.
+method. The available methods are **auto**, **location** and **refresh**,
+with location being faster but less reliable on IIS servers.
+The default is **auto**, which will attempt to intelligently choose the
+method based on the server environment.
 
 The optional third parameter allows you to send a specific HTTP Response
 Code - this could be used for example to create 301 redirects for search
 engine purposes. The default Response Code is 302. The third parameter is
-*only* available with 'location' redirects, and not 'refresh'. Examples::
+*only* available with **location** redirects, and not *refresh*. Examples::
 
 	if ($logged_in == FALSE)
 	{      
@@ -324,8 +370,14 @@ engine purposes. The default Response Code is 302. The third parameter is
 	is outputted to the browser since it utilizes server headers.
 
 .. note:: For very fine grained control over headers, you should use the
-	`Output Library </libraries/output>` set_header() function.
+	`Output Library </libraries/output>` ``set_header()`` method.
 
-.. note:: To IIS users: if you hide the `Server` HTTP header, the "auto"
+.. note:: To IIS users: if you hide the `Server` HTTP header, the *auto*
 	method won't detect IIS, in that case it is advised you explicitly
-	use the "refresh" method.
+	use the **refresh** method.
+
+.. note:: When the **location** method is used, an HTTP status code of 303
+	will *automatically* be selected when the page is currently accessed
+	via POST and HTTP/1.1 is used.
+
+.. important:: This function will terminate script execution.
\ No newline at end of file
diff --git a/user_guide_src/source/installation/upgrade_300.rst b/user_guide_src/source/installation/upgrade_300.rst
index 64f603a16..914b2ed53 100644
--- a/user_guide_src/source/installation/upgrade_300.rst
+++ b/user_guide_src/source/installation/upgrade_300.rst
@@ -248,4 +248,29 @@ As a result of that, the 'anchor_class' setting is now deprecated and scheduled
 CodeIgniter 3.1+.
 
 .. note:: This setting is still available, but you're strongly encouraged to remove its' usage sooner
-	rather than later.
\ No newline at end of file
+	rather than later.
+
+String helper random_string() types 'unique' and 'encrypt'
+==========================================================
+
+When using the :doc:`String Helper <helpers/string_helper>` function :php:func:`random_string()`,
+you should no longer pass the **unique** and **encrypt** randomization types. They are only
+aliases for **md5** and **sha1** respectively and are now deprecated and scheduled for removal
+in CodeIgniter 3.1+.
+
+.. note:: These options are still available, but you're strongly encouraged to remove their usage
+	sooner rather than later.
+
+URL helper url_title() separators 'dash' and 'underscore'
+=========================================================
+
+When using the :doc:`URL Helper <helpers/url_helper>` function :php:func:`url_title()`, you
+should no longer pass **dash** or **underscore** as the word separator. This function will
+now accept any character and you should just pass the chosen character directly, so you
+should write '-' instead of 'dash' and '_' instead of 'underscore'.
+
+**dash** and **underscore** now act as aliases and are deprecated and scheduled for removal
+in CodeIgniter 3.1+.
+
+.. note:: These options are still available, but you're strongly encouraged to remove their usage
+	sooner rather than later.
\ No newline at end of file