From 32b020bf05af255912b3081399ceb9675b13ecae Mon Sep 17 00:00:00 2001
From: Dion Hulse <dd32@git.wordpress.org>
Date: Mon, 12 Jan 2015 04:32:35 +0000
Subject: [PATCH] More concise documentation for
 wp_install_maybe_enable_pretty_permalinks() See #6481. Props ericlewis.

git-svn-id: https://develop.svn.wordpress.org/trunk@31160 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/upgrade.php | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/src/wp-admin/includes/upgrade.php b/src/wp-admin/includes/upgrade.php
index abcd39e88c..0c7c1ecccd 100644
--- a/src/wp-admin/includes/upgrade.php
+++ b/src/wp-admin/includes/upgrade.php
@@ -263,11 +263,9 @@ As a new WordPress user, you should go to <a href=\"%s\">your dashboard</a> to d
 endif;
 
 /**
- * Enable pretty permalinks if available.
+ * Enable pretty permalinks.
  *
- * This function will enable pretty permalinks if it can verify they work.
- * If all pretty permalinks formats fail to work, WordPress will fall back
- * to ugly permalinks by setting an empty permalink structure.
+ * If after enabling pretty permalinks don't work, fallback to query-string permalinks.
  *
  * @since 4.2.0
  *
@@ -276,16 +274,18 @@ endif;
 function wp_install_maybe_enable_pretty_permalinks() {
 	global $wp_rewrite;
 
-	// Bail if we alredy have permalinks enabled (Multisite)
+	// Bail if a permalink structure is already enabled.
 	if ( get_option( 'permalink_structure' ) ) {
 		return;
 	}
 
 	/*
-	 * The Permalink structures which WordPress should attempt to use.
+	 * The Permalink structures to attempt.
+	 *
 	 * The first is designed for mod_rewrite or nginx rewriting.
-	 * The second is PATHINFO based permalinks offered under configurations 
-	 * without rewrites enabled.
+	 *
+	 * The second is PATHINFO-based permalinks for web server configurations
+	 * without a true rewrite module enabled.
 	 */
 	$permalink_structures = array(
 		'/%year%/%monthnum%/%day%/%postname%/',
@@ -293,7 +293,6 @@ function wp_install_maybe_enable_pretty_permalinks() {
 	);
 
 	foreach ( (array) $permalink_structures as $permalink_structure ) {
-		// Set the desired Permalink structure to try
 		$wp_rewrite->set_permalink_structure( $permalink_structure );
 
 		/*
@@ -302,15 +301,18 @@ function wp_install_maybe_enable_pretty_permalinks() {
 	 	 */
 		$wp_rewrite->flush_rules( true );
 
-		// Test against a real WordPress Post, or if none were created, a Page URI
+		// Test against a real WordPress Post, or if none were created, a random 404 page.
 		$test_url = get_permalink( 1 );
 		if ( ! $test_url ) {
 			$test_url = home_url( '/wordpress-check-for-rewrites/' );
 		}
 
 		/*
-	 	 * Send a HEAD request to a random page on the site, and check whether
+	 	 * Send a request to the site, and check whether
 	 	 * the 'x-pingback' header is returned as expected.
+	 	 *
+	 	 * Uses wp_remote_get() instead of wp_remote_head() because web servers
+	 	 * can block head requests.
 	 	 */
 		$response          = wp_remote_get( $test_url, array( 'timeout' => 5 ) );
 		$x_pingback_header = wp_remote_retrieve_header( $response, 'x-pingback' );
@@ -322,8 +324,8 @@ function wp_install_maybe_enable_pretty_permalinks() {
 	}
 
 	/*
-	 * If it makes it this far, Pretty Permalinks failed to activate.
-	 * Reset and allow the user to select it themselves.
+	 * If it makes it this far, pretty permalinks failed.
+	 * Fallback to query-string permalinks.
 	 */
 	$wp_rewrite->set_permalink_structure( '' );
 	$wp_rewrite->flush_rules( true );