nginx / nginx/nginx.org

Confusing beginners_guide description and suggested fix

Open Beginner friendly
#72 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
XSLT
Stars
89
Forks
60
Avg merge
19h 11m
Merged PRs (30d)
12

Description

https://github.com/nginx/nginx.org/blob/6e199dec7bb66c7683a37531b802fa7fbf216cac/xml/en/docs/beginners_guide.xml#L141-L154

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.