httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Slive <jos...@slive.ca>
Subject Re: meta-data
Date Wed, 11 Aug 2004 13:53:06 GMT
[Can I suggest you post in plain text?  Your message is pretty hard on the 
eyes.]

Thanks very much for the feedback.  Some comments below.


On Wed, 11 Aug 2004 Michael.Schroepl@telekurs.de wrote:

> Who is the intended target group for this document?

It is intended as an overview of Apache features in a particular area for 
people who are new to Apache.  I would prefer for it to be as short as it 
can reasonably be, with additional details being provided in the module 
documentation.  (I think of a division between the "users guide" to which 
this belongs, and the "reference manual" which includes the module docs.)

>
> My first idea was that this document would list each and every HTTP
> response header Apache is able to send, and explain the situation
> when this might happen (mostly by providing links to the appropriate
> documents).
> If so, a browser coder might get an impression which parts of
> HTTP/1.1 are supported by Apache to which degree.
> (Given the market share of the Apache HTTP server, this might be
> quite a relevant information. ;-)

At the moment, I've focused only on the *configurable* metadata.  The 
stuff that apache handles automatically behind the scenes is certainly 
relevant to some people (like browser designers), but I don't think it is 
relevant to the average reader.

What I should do is add a prominent link to section 14 of the HTTP/1.1 
spec.  This is really quite readable, and since Apache is HTTP/1.1 
compliant, it explains apache's behaviour quite well.  Of course, there 
are some areas where clarification of the exact way apache interprets the 
spec would be interesting, but I think it is too technical for this doc.

> Actually, the HTTP request headers being accepted/evaluated and
> the HTTP response headers sent by the Apache server are strongly
> related, therefore a document limiting itself to only one half of them
> has to be rather a link list than a How-To.

There are two ways that I can think of that the request headers interact 
with the response headers:

1. Content negotiation.  This is covered in a separate doc, but should be 
better linked into metadata, I agree.

2. Protocol issues (Connection, etc).  Again, this can be understood 
simply by reading the spec for those who need that knowledge.

>> Anyone have suggestions on additions/changes?
>
> I'd like the Content Encoding section to have some reference to
> mod_deflate (probably as "Related Module").

Good idea.

>
> What about explaining the function of the "Vary:" header in this file?
> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.44)
> Having Content Encoding, Content Negotiation and Expiration/Caching
> here, it seems the logical place for me to explain the nature of "Vary:"
> as well, as this is related to all three mechanisms.
> (The latest version of mod_deflate is sending this header IIRC because
> compression is a negotiation about at least the "Accept-Encoding:"
> header, and maybe more, depending on the granularity of configuration.)

Apache sends Vary in a bunch of different circumstances -- I hope
everywhere where it is required by HTTP/1.1.  If additional docs are 
needed, I think they should go in the content-negotiation docs.

> I just made a quick walk though the HTTP/1.1 specification:
>
> The "Expiration" section might at least mention the names of the "ETag"
> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.19)
> and "LastModified"
> (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.29)
> headers.

That's what I meant in the "other information" comment and why I linked to 
a caching tutorial.  Do you think that isn't sufficient?  Caching is a big 
topic, involving lots of different stuff.  I think linking to a more 
complete guide is better than doing a partial job.

[suggestions for other headers to document]

The only ones of those that are really user-configurable are Server and 
Via.  The rest are just handled according to the spec internally by 
Apache, and I don't want to document HTTP/1.1 when there is a perfectly 
good doc already.

>> Can anyone suggest a title better than "Response Metadata", which
>> could be kind of obscure to the new user?
>
> What about explicitly naming the "HTTP response headers" for what
> they are? After all, we are talking about a HTTP server...

Not a bad idea.  Do you think that would be clearer to the newcomer than 
Response Metadata, or does it just assume that the person already knows 
what response headers are used for?

Thanks again for the comments, I will try to incorporate them.

Joshua.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message