Re: how to needed for apache

[Rich Bowen <rb...@rcbowen.com>]

On Aug 25, 2010, at 10:44 AM, James Godrej wrote:

>
>
> See when some one uses Apache for the first time they are not aware  
> of a  lot of things.
> The term definition of virtual host itself is quite confusing for  
> newbies.
> What is a VirtualHost and why is that used.

How's this for a definition:

------------
The term Virtual Host refers to the practice of running more than one  
web site (such as www.company1.com and www.company2.com) on a single  
machine. Virtual hosts can be "IP-based", meaning that you have a  
different IP address for every web site, or "name-based", meaning that  
you have multiple names running on each IP address. The fact that they  
are running on the same physical server is not apparent to the end user.
-------------

That is the definition copied and pasted directly from the  
documentation. Please feel free to enhance it, or clarify it, in any  
way that seems best to you, and let us know what you come up with.  
That was the best I could do.

> For example let us take the page
> http://httpd.apache.org/docs/2.0/vhosts/examples.html

This is the examples doc, and references the main VirtualHosts  
document, which defines what a virtualhost is. We can't repeat the  
definition on every page, but we can certainly link to the definition  
when the term is used. I've added this link this morning.

> Some one reading the above doc for the first time surely may not be  
> clear.
> Having said that if some people are able to understand that does not  
> mean that the doc is really Great.
> You do give an example
> but among the list of other directives
> what is the meaning of word directive with reference to Apache.
>
> Why is a directive being used at all.
> Sure there are other pages which do mention what you just said but  
> then again this is as if
> I write a  module for /proc file system and ask some one to read
> fs/proc/version.c
> and ask the guy to find  what seq_files are doing and how are they  
> being used.
>
> Some people may understand some may not.

I'm at a bit of a loss to know how to respond to this.

On the one hand, yes, we need to define our terms.

On the other hand, it's not at all clear to me that it is the  
responsibility of the Apache httpd documentation to introduce to the  
reader the concept of a server and the concept of a configuration  
file. We've rather intentionally stayed away from being a tutorial on  
system management, editing files, or managing your DNS server, and  
we'll probably continue to hold that line.

Having said that, no, I don't think I can find anywhere in the  
documentation where we define the term "Directive" except for here: http://httpd.apache.org/docs/2.2/glossary.html#directive



>
> The documentation that you people have does have some technical  
> references.
> But I see a lot of blogs forums and links here and there and  
> questions which newbies do suffer
> that included me.
> Did I answer your question?

Well, a little. You gave two specific examples, one of which I fixed  
while writing this email, and the other of which I'm really quite  
uncertain is an actual problem, but I'm willing to see what solutions  
you propose for it.

We are, always, very welcoming of actual patches to the documentation.  
General "you suck" kinds of criticisms tend to be received much less  
gracefully. I'm sure you can understand this, given that I have spent  
considerable portions of the last ten years writing the documentation,  
and, so, feel somewhat personally indicted when you say that it is  
missing "a lot of basic things."

However, I *think* that the direction you're going is that every time  
we use a basic term we need to define it, and I don't have any  
objection to that position. That's what we were trying to do with the  
glossary, and we could probably do a better job of linking to the  
relevant term in the glossary when a new term is used in a document. I  
don't object to that at all.


> --

Rich Bowen
rbowen@rcbowen.com