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
[email protected]
