Confusing beginners_guide description and suggested fix
Nobody has claimed this yet.
- Dominant language
- XSLT
- Stars
- 89
- Forks
- 60
- Avg merge
- 19h 11m
- Merged PRs (30d)
- 12
Description
As a new programmer learning to set up nginx, I find two things confusing about how the Beginner's Guide is written:
First, while there's an entire paragraph on the directive syntax, it's somewhat poorly defined.
"A simple directive consists of the name and parameters separated by spaces and ends with a semicolon (;). A block directive has the same structure as a simple directive, but instead of the semicolon it ends with a set of additional instructions surrounded by braces ({ and }). If a block directive can have other directives inside braces, it is called a context (examples: events, http, server, and location)."
In this explanation no examples are given of either a simple directive, or a block directive, nor are there any code blocks demonstrating them. There are examples of context names, but again no code example.
There are examples in the next section (Serving Static Content), but only the first describes the http and server directives as "blocks", the word "simple" (ie "simple directive") is not used again. So its a bit unclear where to use the "simple directive" syntax on first read.
Second, going by the examples given, a simple directive appears to be a { key : value } pair nested in an object, but this is the first syntax I've run into that uses the space character " " (or whitespace in general) to separate the key and the value (name and parameter?) instead of = or : or something more visible. This is easy to understand after looking at the location entry
http://nginx.org/en/docs/http/ngx_http_core_module.html#location
and scrolling down far enough to see several code examples, but in my humble opinion this part of the syntax could be more easily demonstrated here with some example code.
If it's acceptable, I'd like to suggest these changes:
A simple directive consists of the name and parameters separated by spaces and ends with a semicolon (;). (examples: root, listen, proxy_pass) *Note the number of spaces doesn't change the assignment#examples of simple directives
# name parameter;
listen 8080;
proxy_pass http://localhost:8080/;
root /data;
A block directive has the same structure as a simple directive, but instead of the semicolon it ends with a set of additional instructions surrounded by braces { and }. (examples: http, server, and location).
http { #block directive
server { #block directive
location /images/ { #block directive
root /data; #simple directive
}
}
}
If a block directive can have other directives inside braces, it is called a context (examples: events, http, server, and location).
#example of a context
server { #block context
location / { #block directive
root /data/www; #simple directive
}
location /images/ { #block directive
root /data; #simple directive
}
}
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Open xml/en/docs/beginners_guide.xml at lines 141-154 and compare the directive-syntax explanation with the following Serving Static Content examples. Revise the wording and add representative simple, block, and context directive examples as proposed. Done means beginners can distinguish the forms and understand whitespace-separated names and parameters from this section alone.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- xml
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100