diff --git a/docs/advanced_foreword.rst b/docs/advanced_foreword.rst
deleted file mode 100644
index 9c36158a8d..0000000000
--- a/docs/advanced_foreword.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-Foreword for Experienced Programmers
-====================================
-
-Thread-Locals in Flask
-----------------------
-
-One of the design decisions in Flask was that simple tasks should be simple;
-they should not take a lot of code and yet they should not limit you. Because
-of that, Flask has a few design choices that some people might find
-surprising or unorthodox. For example, Flask uses thread-local objects
-internally so that you don’t have to pass objects around from
-function to function within a request in order to stay threadsafe.
-This approach is convenient, but requires a valid
-request context for dependency injection or when attempting to reuse code which
-uses a value pegged to the request. The Flask project is honest about
-thread-locals, does not hide them, and calls out in the code and documentation
-where they are used.
-
-Develop for the Web with Caution
---------------------------------
-
-Always keep security in mind when building web applications.
-
-If you write a web application, you are probably allowing users to register
-and leave their data on your server. The users are entrusting you with data.
-And even if you are the only user that might leave data in your application,
-you still want that data to be stored securely.
-
-Unfortunately, there are many ways the security of a web application can be
-compromised. Flask protects you against one of the most common security
-problems of modern web applications: cross-site scripting (XSS). Unless you
-deliberately mark insecure HTML as secure, Flask and the underlying Jinja2
-template engine have you covered. But there are many more ways to cause
-security problems.
-
-The documentation will warn you about aspects of web development that require
-attention to security. Some of these security concerns are far more complex
-than one might think, and we all sometimes underestimate the likelihood that a
-vulnerability will be exploited - until a clever attacker figures out a way to
-exploit our applications. And don't think that your application is not
-important enough to attract an attacker. Depending on the kind of attack,
-chances are that automated bots are probing for ways to fill your database with
-spam, links to malicious software, and the like.
-
-Flask is no different from any other framework in that you the developer must
-build with caution, watching for exploits when building to your requirements.
diff --git a/docs/config.rst b/docs/config.rst
index bc16e4bac1..bdcbdcd43c 100644
--- a/docs/config.rst
+++ b/docs/config.rst
@@ -394,13 +394,11 @@ The following configuration values are used internally by Flask:
Configuring from Python Files
-----------------------------
-Configuration becomes more useful if you can store it in a separate file,
-ideally located outside the actual application package. This makes
-packaging and distributing your application possible via various package
-handling tools (:doc:`/patterns/distribute`) and finally modifying the
-configuration file afterwards.
+Configuration becomes more useful if you can store it in a separate file, ideally
+located outside the actual application package. You can deploy your application, then
+separately configure it for the specific deployment.
-So a common pattern is this::
+A common pattern is this::
app = Flask(__name__)
app.config.from_object('yourapplication.default_settings')
@@ -692,10 +690,8 @@ your configuration files. However here a list of good recommendations:
code at all. If you are working often on different projects you can
even create your own script for sourcing that activates a virtualenv
and exports the development configuration for you.
-- Use a tool like `fabric`_ in production to push code and
- configurations separately to the production server(s). For some
- details about how to do that, head over to the
- :doc:`/patterns/fabric` pattern.
+- Use a tool like `fabric`_ to push code and configuration separately
+ to the production server(s).
.. _fabric: https://www.fabfile.org/
diff --git a/docs/design.rst b/docs/design.rst
index a5ef2568cd..066cf107c1 100644
--- a/docs/design.rst
+++ b/docs/design.rst
@@ -130,9 +130,25 @@ being present. You can easily use your own templating language, but an
extension could still depend on Jinja itself.
-Micro with Dependencies
+What does "micro" mean?
-----------------------
+“Micro” does not mean that your whole web application has to fit into a single
+Python file (although it certainly can), nor does it mean that Flask is lacking
+in functionality. The "micro" in microframework means Flask aims to keep the
+core simple but extensible. Flask won't make many decisions for you, such as
+what database to use. Those decisions that it does make, such as what
+templating engine to use, are easy to change. Everything else is up to you, so
+that Flask can be everything you need and nothing you don't.
+
+By default, Flask does not include a database abstraction layer, form
+validation or anything else where different libraries already exist that can
+handle that. Instead, Flask supports extensions to add such functionality to
+your application as if it was implemented in Flask itself. Numerous extensions
+provide database integration, form validation, upload handling, various open
+authentication technologies, and more. Flask may be "micro", but it's ready for
+production use on a variety of needs.
+
Why does Flask call itself a microframework and yet it depends on two
libraries (namely Werkzeug and Jinja2). Why shouldn't it? If we look
over to the Ruby side of web development there we have a protocol very
@@ -201,5 +217,12 @@ requirements and Flask could not meet those if it would force any of this
into the core. The majority of web applications will need a template
engine in some sort. However not every application needs a SQL database.
+As your codebase grows, you are free to make the design decisions appropriate
+for your project. Flask will continue to provide a very simple glue layer to
+the best that Python has to offer. You can implement advanced patterns in
+SQLAlchemy or another database tool, introduce non-relational data persistence
+as appropriate, and take advantage of framework-agnostic tools built for WSGI,
+the Python web interface.
+
The idea of Flask is to build a good foundation for all applications.
Everything else is up to you or extensions.
diff --git a/docs/foreword.rst b/docs/foreword.rst
deleted file mode 100644
index 28b272d716..0000000000
--- a/docs/foreword.rst
+++ /dev/null
@@ -1,53 +0,0 @@
-Foreword
-========
-
-Read this before you get started with Flask. This hopefully answers some
-questions about the purpose and goals of the project, and when you
-should or should not be using it.
-
-What does "micro" mean?
------------------------
-
-“Micro” does not mean that your whole web application has to fit into a single
-Python file (although it certainly can), nor does it mean that Flask is lacking
-in functionality. The "micro" in microframework means Flask aims to keep the
-core simple but extensible. Flask won't make many decisions for you, such as
-what database to use. Those decisions that it does make, such as what
-templating engine to use, are easy to change. Everything else is up to you, so
-that Flask can be everything you need and nothing you don't.
-
-By default, Flask does not include a database abstraction layer, form
-validation or anything else where different libraries already exist that can
-handle that. Instead, Flask supports extensions to add such functionality to
-your application as if it was implemented in Flask itself. Numerous extensions
-provide database integration, form validation, upload handling, various open
-authentication technologies, and more. Flask may be "micro", but it's ready for
-production use on a variety of needs.
-
-Configuration and Conventions
------------------------------
-
-Flask has many configuration values, with sensible defaults, and a few
-conventions when getting started. By convention, templates and static
-files are stored in subdirectories within the application's Python
-source tree, with the names :file:`templates` and :file:`static`
-respectively. While this can be changed, you usually don't have to,
-especially when getting started.
-
-Growing with Flask
-------------------
-
-Once you have Flask up and running, you'll find a variety of extensions
-available in the community to integrate your project for production.
-
-As your codebase grows, you are free to make the design decisions appropriate
-for your project. Flask will continue to provide a very simple glue layer to
-the best that Python has to offer. You can implement advanced patterns in
-SQLAlchemy or another database tool, introduce non-relational data persistence
-as appropriate, and take advantage of framework-agnostic tools built for WSGI,
-the Python web interface.
-
-Flask includes many hooks to customize its behavior. Should you need
-more customization, the Flask class is built for subclassing. If you are
-curious about the Flask design principles, head over to the section
-about :doc:`design`.
diff --git a/docs/htmlfaq.rst b/docs/htmlfaq.rst
deleted file mode 100644
index 4807c2662d..0000000000
--- a/docs/htmlfaq.rst
+++ /dev/null
@@ -1,206 +0,0 @@
-HTML/XHTML FAQ
-==============
-
-The Flask documentation and example applications are using HTML5. You
-may notice that in many situations, when end tags are optional they are
-not used, so that the HTML is cleaner and faster to load. Because there
-is much confusion about HTML and XHTML among developers, this document tries
-to answer some of the major questions.
-
-
-History of XHTML
-----------------
-
-For a while, it appeared that HTML was about to be replaced by XHTML.
-However, barely any websites on the Internet are actual XHTML (which is
-HTML processed using XML rules). There are a couple of major reasons
-why this is the case. One of them is Internet Explorer's lack of proper
-XHTML support. The XHTML spec states that XHTML must be served with the MIME
-type :mimetype:`application/xhtml+xml`, but Internet Explorer refuses
-to read files with that MIME type.
-While it is relatively easy to configure Web servers to serve XHTML properly,
-few people do. This is likely because properly using XHTML can be quite
-painful.
-
-One of the most important causes of pain is XML's draconian (strict and
-ruthless) error handling. When an XML parsing error is encountered,
-the browser is supposed to show the user an ugly error message, instead
-of attempting to recover from the error and display what it can. Most of
-the (X)HTML generation on the web is based on non-XML template engines
-(such as Jinja, the one used in Flask) which do not protect you from
-accidentally creating invalid XHTML. There are XML based template engines,
-such as Kid and the popular Genshi, but they often come with a larger
-runtime overhead and are not as straightforward to use because they have
-to obey XML rules.
-
-The majority of users, however, assumed they were properly using XHTML.
-They wrote an XHTML doctype at the top of the document and self-closed all
-the necessary tags (`` `` becomes `` `` or `` `` in XHTML).
-However, even if the document properly validates as XHTML, what really
-determines XHTML/HTML processing in browsers is the MIME type, which as
-said before is often not set properly. So the valid XHTML was being treated
-as invalid HTML.
-
-XHTML also changed the way JavaScript is used. To properly work with XHTML,
-programmers have to use the namespaced DOM interface with the XHTML
-namespace to query for HTML elements.
-
-History of HTML5
-----------------
-
-Development of the HTML5 specification was started in 2004 under the name
-"Web Applications 1.0" by the Web Hypertext Application Technology Working
-Group, or WHATWG (which was formed by the major browser vendors Apple,
-Mozilla, and Opera) with the goal of writing a new and improved HTML
-specification, based on existing browser behavior instead of unrealistic
-and backwards-incompatible specifications.
-
-For example, in HTML4 ``
Hello``. However, since people were using
-XHTML-like tags along the lines of ````, browser vendors implemented
-the XHTML syntax over the syntax defined by the specification.
-
-In 2007, the specification was adopted as the basis of a new HTML
-specification under the umbrella of the W3C, known as HTML5. Currently,
-it appears that XHTML is losing traction, as the XHTML 2 working group has
-been disbanded and HTML5 is being implemented by all major browser vendors.
-
-HTML versus XHTML
------------------
-
-The following table gives you a quick overview of features available in
-HTML 4.01, XHTML 1.1 and HTML5. (XHTML 1.0 is not included, as it was
-superseded by XHTML 1.1 and the barely-used XHTML5.)
-
-.. tabularcolumns:: |p{9cm}|p{2cm}|p{2cm}|p{2cm}|
-
-+-----------------------------------------+----------+----------+----------+
-| | HTML4.01 | XHTML1.1 | HTML5 |
-+=========================================+==========+==========+==========+
-| ``value`` | |Y| [1]_ | |N| | |N| |
-+-----------------------------------------+----------+----------+----------+
-| `` `` supported | |N| | |Y| | |Y| [2]_ |
-+-----------------------------------------+----------+----------+----------+
-| ```` supported | |N| | |Y| | |N| |
-+-----------------------------------------+----------+----------+----------+
-| should be served as `text/html` | |Y| | |N| [3]_ | |Y| |
-+-----------------------------------------+----------+----------+----------+
-| should be served as | |N| | |Y| | |N| |
-| `application/xhtml+xml` | | | |
-+-----------------------------------------+----------+----------+----------+
-| strict error handling | |N| | |Y| | |N| |
-+-----------------------------------------+----------+----------+----------+
-| inline SVG | |N| | |Y| | |Y| |
-+-----------------------------------------+----------+----------+----------+
-| inline MathML | |N| | |Y| | |Y| |
-+-----------------------------------------+----------+----------+----------+
-| ``