From 7479dbc77dd6b5dbf09fd04baddab8e44d47603b Mon Sep 17 00:00:00 2001 From: "Roy T. Fielding" Date: Tue, 3 Feb 2009 20:29:55 +0000 Subject: [PATCH] Document the disabling of DefaultType and update terminology regarding Internet message metadata. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@740420 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/developer/API.xml | 2 +- docs/manual/mod/core.xml | 105 ++++++++++++-------------- docs/manual/mod/mod_mime.xml | 120 ++++++++++++++++-------------- docs/manual/mod/mod_proxy_ftp.xml | 2 +- 4 files changed, 111 insertions(+), 118 deletions(-) diff --git a/docs/manual/developer/API.xml b/docs/manual/developer/API.xml index 6af161ce77..3278aa52d8 100644 --- a/docs/manual/developer/API.xml +++ b/docs/manual/developer/API.xml @@ -903,7 +903,7 @@ void *request_config; /* Notes on *this* request */ control and authorization information, but also information on how to determine file types from suffixes, which can be modified by AddType and DefaultType directives, and so forth. In general, + module="core">ForceType directives, and so forth. In general, the governing philosophy is that anything which can be made configurable by directory should be; per-server information is generally used in the standard set of modules for information like diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml index 4a2da43f97..c6b3aea437 100644 --- a/docs/manual/mod/core.xml +++ b/docs/manual/mod/core.xml @@ -212,7 +212,7 @@ content-type is text/plain or text/html a default charset of iso-8859-1. Any other value is assumed to be the charset to be used, which should be one of the IANA registered - charset values for use in MIME media types. + charset values for use in Internet media types (MIME types). For example:

@@ -235,9 +235,9 @@ content-type is text/plain or text/html AddOutputFilterByType -assigns an output filter to a particular MIME-type +assigns an output filter to a particular media-type AddOutputFilterByType filter[;filter...] -MIME-type [MIME-type] ... +media-type [media-type] ... server config virtual hostdirectory .htaccess @@ -247,7 +247,7 @@ content-type is text/plain or text/html

This directive activates a particular output filter for a request depending on the - response MIME-type. Because of certain + response media-type. Because of certain problems discussed below, this directive is deprecated. The same functionality is available using mod_filter.

@@ -283,14 +283,10 @@ content-type is text/plain or text/html Note

Enabling filters with AddOutputFilterByType may fail partially or completely in some cases. For example, no - filters are applied if the MIME-type could not be determined and falls - back to the DefaultType setting, - even if the DefaultType is the - same.

- -

However, if you want to make sure, that the filters will be - applied, assign the content type to a resource explicitly, for - example with AddType or + filters are applied if the media-type could not + be determined. If you want to make sure that the filters will be + applied, assign the content type to a resource explicitly; for + example, with AddType or ForceType. Setting the content type within a (non-nph) CGI script is also safe.

@@ -385,16 +381,15 @@ be passed through
FileInfo
- Allow use of the directives controlling document types (DefaultType, ErrorDocument, ForceType, LanguagePriority, - SetHandler, SetInputFilter, SetOutputFilter, and - mod_mime Add* and Remove* - directives, etc.), document meta data (ErrorDocument, + ForceType, + LanguagePriority, + SetHandler, + SetInputFilter, + SetOutputFilter, and + mod_mime Add* and Remove* directives), + document meta data (Header, RequestHeader, SetEnvIf, DefaultType -MIME content-type that will be sent if the -server cannot determine a type in any other way -DefaultType MIME-type|none -DefaultType text/plain +This directive has no effect other than to emit warnings +if the value is not none. In prior versions, DefaultType +would specify a default media type to assign to response content for +which no other media type configuration could be found. + +DefaultType media-type|none +DefaultType none server configvirtual host directory.htaccess FileInfo -The argument none is available in Apache 2.2.7 and later +The argument none is available in Apache 2.2.7 and later. All other choices are DISABLED for 2.3.x and later. -

There will be times when the server is asked to provide a - document whose type cannot be determined by its MIME types mappings.

+

This directive has been disabled. For backwards compatibility + of configuration files, it may be specified with the value + none, meaning no default media type. For example:

-

The server SHOULD inform the client of the content-type of the - document. If the server is unable to determine this by normal - means, it will set it to the configured - DefaultType. For example:

- - - DefaultType image/gif - - -

would be appropriate for a directory which contained many GIF - images with filenames missing the .gif extension.

- -

In cases where it can neither be determined by the server nor - the administrator (e.g. a proxy), it is preferable to omit the MIME - type altogether rather than provide information that may be false. - This can be accomplished using

DefaultType None -

DefaultType None is only available in httpd-2.2.7 and later.

-

Note that unlike ForceType, this directive only - provides the default mime-type. All other mime-type definitions, - including filename extensions, that might identify the media type - will override this default.

+

DefaultType None is only available in + httpd-2.2.7 and later.

+ +

Use the mime.types configuration file and the + AddType to configure media + type assignments via file extensions, or the + ForceType directive to configure + the media type for specific resources. Otherwise, the server will + send the response without a Content-Type header field and the + recipient may attempt to guess the media type.

 @@ -1224,8 +1210,8 @@ filenames ForceType Forces all matching files to be served with the specified -MIME content-type -ForceType MIME-type|None +media type in the HTTP Content-Type header field +ForceType media-type|None directory.htaccess FileInfo @@ -1238,7 +1224,7 @@ MIME content-type Files section, this directive forces all matching files to be served with the content type identification given by - MIME-type. For example, if you had a directory full of + media-type. For example, if you had a directory full of GIF files, but did not want to label them all with .gif, you might want to use:

@@ -1246,11 +1232,12 @@ MIME content-type ForceType image/gif -

Note that unlike DefaultType, - this directive overrides all mime-type associations, including - filename extensions, that might identify the media type.

+

Note that this directive overrides other indirect media type + associations defined in mime.types or via the + AddType.

-

You can override any ForceType setting +

You can also override more general + ForceType settings by using the value of None:

diff --git a/docs/manual/mod/mod_mime.xml b/docs/manual/mod/mod_mime.xml index a17d33268d..292f38af01 100644 --- a/docs/manual/mod/mod_mime.xml +++ b/docs/manual/mod/mod_mime.xml @@ -32,13 +32,15 @@ mime_module -

This module is used to associate various bits of "meta - information" with files by their filename extensions. This - information relates the filename of the document to it's - mime-type, language, character set and encoding. This - information is sent to the browser, and participates in content - negotiation, so the user's preferences are respected when - choosing one of several possible files to serve. See +

This module is used to assign content metadata to the content + selected for an HTTP response by mapping patterns in the + URI or filenames to the metadata values. For example, the filename + extensions of content files often define the content's Internet + media type, language, character set, and content-encoding. This + information is sent in HTTP messages containing that content and + used in content negotiation when selecting alternatives, such that + the user's preferences are respected when choosing one of several + possible contents to serve. See mod_negotiation for more information about content negotiation.

@@ -47,11 +49,11 @@ module="mod_mime">AddEncoding, AddLanguage and AddType are all used to map file - extensions onto the meta-information for that file. Respectively + extensions onto the metadata for that file. Respectively they set the character set, content-encoding, content-language, - and MIME-type (content-type) of documents. The directive media-type (content-type) of documents. The directive TypesConfig is used to specify a - file which also maps extensions onto MIME types.

+ file which also maps extensions onto media types.

In addition, mod_mime may define the handler and mod_negotiation to consider these file extensions to be included when testing Multiviews matches.

-

While mod_mime associates meta-information +

While mod_mime associates metadata with filename extensions, the core server provides directives that are used to associate all the files in a given container (e.g., Location, Directory, or Files) with particular - meta-information. These directives include ForceType, SetHandler, SetInputFilter, and mod_mime.

-

Note that changing the meta-information for a file does not +

Note that changing the metadata for a file does not change the value of the Last-Modified header. Thus, previously cached copies may still be used by a client or proxy, with the previous headers. If you change the - meta-information (language, content type, character set or + metadata (language, content type, character set or encoding) you may need to 'touch' affected files (updating their last modified date) to ensure that all visitors are receive the corrected content headers.

@@ -93,25 +95,24 @@ module="mod_mime_magic">MimeMagicFile AddDefaultCharset ForceType -DefaultType SetHandler SetInputFilter SetOutputFilter
Files with Multiple Extensions -

Files can have more than one extension, and the order of the +

Files can have more than one extension; the order of the extensions is normally irrelevant. For example, if the file welcome.html.fr maps onto content type text/html and language French then the file welcome.fr.html will map onto exactly the same information. If more than one extension is given that maps onto - the same type of meta-information, then the one to the right will + the same type of metadata, then the one to the right will be used, except for languages and content encodings. For example, - if .gif maps to the MIME-type + if .gif maps to the media-type image/gif and .html maps to the - MIME-type text/html, then the file + media-type text/html, then the file welcome.gif.html will be associated with the - MIME-type text/html.

+ media-type text/html.

Languages and content encodings are treated accumulative, because one can assign @@ -121,14 +122,15 @@ module="mod_mime_magic">MimeMagicFile text/html.

Care should be taken when a file with multiple extensions - gets associated with both a MIME-type and a handler. This will + gets associated with both a media-type + and a handler. This will usually result in the request being handled by the module associated with the handler. For example, if the .imap extension is mapped to the handler imap-file (from mod_imagemap) and the .html extension is - mapped to the MIME-type text/html, then the file + mapped to the media-type text/html, then the file world.imap.html will be associated with both the - imap-file handler and text/html MIME-type. + imap-file handler and text/html media-type. When it is processed, the imap-file handler will be used, and so it will be treated as a mod_imagemap imagemap file.

@@ -151,7 +153,7 @@ module="mod_mime_magic">MimeMagicFile
Content encoding -

A file of a particular MIME-type can additionally be encoded a +

A file of a particular media-type can additionally be encoded a particular way to simplify transmission over the Internet. While this usually will refer to compression, such as gzip, it can also refer to encryption, such a @@ -252,9 +254,10 @@ charset

The AddCharset directive maps the given - filename extensions to the specified content charset. charset - is the MIME - charset parameter of filenames containing + filename extensions to the specified content charset (the Internet + registered name for a given character encoding). charset + is the media + type's charset parameter for resources with filenames containing extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension.

@@ -291,7 +294,7 @@ charset AddEncoding Maps the given filename extensions to the specified encoding type -AddEncoding MIME-enc extension +AddEncoding encoding extension [extension] ... server configvirtual host directory.htaccess @@ -299,8 +302,9 @@ type

The AddEncoding directive maps the given - filename extensions to the specified encoding type. MIME-enc - is the MIME encoding to use for documents containing the + filename extensions to the specified HTTP content-encoding. + encoding is the HTTP content coding to append to the + value of the Content-Encoding header field for documents named with the extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension.

@@ -326,7 +330,7 @@ type AddEncoding directive. To make this long story short, you should always use x-gzip and x-compress for these two specific encodings. More - recent encodings, such as deflate should be + recent encodings, such as deflate, should be specified without the x-.

The extension argument is case-insensitive and can @@ -411,7 +415,7 @@ later. AddLanguage Maps the given filename extension to the specified content language -AddLanguage MIME-lang extension +AddLanguage language-tag extension [extension] ... server configvirtual host directory.htaccess @@ -419,10 +423,11 @@ language

The AddLanguage directive maps the given - filename extension to the specified content language. - MIME-lang is the MIME language of filenames containing - extension. This mapping is added to any already in force, - overriding any mappings that already exist for the same + filename extension to the specified content language. Files with the + filename extension are assigned an HTTP Content-Language + value of language-tag corresponding to the language + identifiers defined by RFC 3066. + This directive overrides any mappings that already exist for the same extension.

Example @@ -511,7 +516,7 @@ later. AddType Maps the given filename extensions onto the specified content type -AddType MIME-type extension +AddType media-type extension [extension] ... server configvirtual host directory.htaccess @@ -520,12 +525,12 @@ type

The AddType directive maps the given filename extensions onto the specified content - type. MIME-type is the MIME + type. media-type is the media type to use for filenames containing extension. This mapping is added to any already in force, overriding any mappings that already exist for the same extension. This directive can be used to add mappings - not listed in the MIME types file (see the TypesConfig directive).

Example @@ -539,7 +544,7 @@ type - It is recommended that new MIME types be added using the + It is recommended that new media types be added using the AddType directive rather than changing the TypesConfig file. @@ -550,7 +555,6 @@ type extension argument will be compared against each of them.

 -DefaultType ForceType @@ -611,30 +615,31 @@ a matching file with MultiViews DefaultLanguage -Sets all files in the given scope to the specified -language -DefaultLanguage MIME-lang +Defines a default language-tag to be sent in the Content-Language +header field for all resources in the current context that have not been +assigned a language-tag by some other means. +DefaultLanguage language-tag server configvirtual host directory.htaccess FileInfo

The DefaultLanguage directive tells Apache - that all files in the directive's scope (e.g., all files + that all resources in the directive's scope (e.g., all resources covered by the current Directory container) that don't have an explicit language extension (such as .fr or .de as configured by AddLanguage) should be - considered to be in the specified MIME-lang language. This - allows entire directories to be marked as containing Dutch content, for + assigned a Content-Language of language-tag. This allows + entire directory trees to be marked as containing Dutch content, for instance, without having to rename each file. Note that unlike using extensions to specify languages, DefaultLanguage can only specify a single language.

-

If no DefaultLanguage directive is in force, +

If no DefaultLanguage directive is in force and a file does not have any language extensions as configured - by AddLanguage, then that file - will be considered to have no language attribute.

+ by AddLanguage, then no + Content-Language header field will be generated.

Example DefaultLanguage en @@ -876,7 +881,7 @@ extensions

The RemoveType directive removes any - MIME type associations for files with + media type associations for files with the given extensions. This allows .htaccess files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use @@ -888,8 +893,8 @@ extensions

This will remove any special handling of .cgi files in the /foo/ directory and any beneath it, - causing the files to be treated as being of the DefaultType.

+ causing responses containing those files to omit the HTTP + Content-Type header field.

Note

RemoveType directives are processed @@ -912,16 +917,17 @@ extensions

The TypesConfig directive sets the - location of the MIME types + location of the media types configuration file. File-path is relative to the ServerRoot. This file sets the default list of mappings from filename extensions to content types. Most administrators use the provided mime.types file, which associates common filename - extensions with IANA registered content types. The current list is + extensions with the official list of IANA registered media types maintained at http://www.iana.org/assignments/media-types/index.html. This + >http://www.iana.org/assignments/media-types/index.html + as well as a large number of unofficial types. This simplifies the httpd.conf file by providing the majority of media-type definitions, and may be overridden by AddType directives as @@ -932,7 +938,7 @@ extensions an AddType directive:

- MIME-type [extension] ... + media-type [extension] ...

The case of the extension does not matter. Blank lines, and lines diff --git a/docs/manual/mod/mod_proxy_ftp.xml b/docs/manual/mod/mod_proxy_ftp.xml index a6ea79a54b..133407793b 100644 --- a/docs/manual/mod/mod_proxy_ftp.xml +++ b/docs/manual/mod/mod_proxy_ftp.xml @@ -59,7 +59,7 @@

Alternatively you may prefer to default everything to binary:

-
DefaultType application/octet-stream
+
ForceType application/octet-stream
-- 2.40.0