diff --git a/ebooks.mk b/ebooks.mk index 4d8f317..663d56c 100644 --- a/ebooks.mk +++ b/ebooks.mk @@ -23,29 +23,37 @@ pdf: $(name).pdf html: $(name).html %.pdf: $(name).html + cp tutorial-simple.css tutorial.css ebook-convert $< $@ \ - --margin-bottom 30 \ - --margin-top 30 \ - --margin-left 20 \ - --margin-right 20 \ + --margin-bottom 5 \ + --margin-top 5 \ + --margin-left 5 \ + --margin-right 5 \ --no-chapters-in-toc \ --book-producer 'agentzh' \ - --output-profile kindle \ + --pdf-default-font-size 12 \ + --pdf-mono-font-size 12 \ + --paper-size letter \ --title "$(title)" --publisher 'agentzh' \ --language $(lang2) --authors 'agentzh' + git co tutorial.css %.mobi: $(name).html + cp tutorial-simple.css tutorial.css ebook-convert $< $@ \ --output-profile kindle_dx --no-inline-toc \ --title "$(title)" --publisher 'agentzh' \ --language $(lang2) --authors 'agentzh' + git co tutorial.css %.epub: $(name).html + cp tutorial-simple.css tutorial.css ebook-convert $< $@ \ --no-default-epub-cover \ --output-profile kindle_dx \ --title "$(title)" --publisher 'agentzh' \ --language $(lang2) --authors 'agentzh' + git co tutorial.css $(name).html: $(htmlfiles) ./utils/gen-html-index-$(lang2).pl ./utils/gen-html-index-$(lang2).pl -v $(ver) -o $@ $(htmlfiles) diff --git a/en/00-Foreword01.tut b/en/00-Foreword01.tut index e7ccc13..b8ba133 100644 --- a/en/00-Foreword01.tut +++ b/en/00-Foreword01.tut @@ -1,54 +1,52 @@ = Foreword = -I've been doing a lot of work in the Nginx world over the last few years -and I've also been thinking about writing series of tutorial-like articles -to -explain to more people what I've done and what I've learned in -this area. Now I have finally decided to post serial tutorials to the -Sina Blog L in Chinese. Every article -will have one rough topic and will be in a rather casual style. They're -not parts of a book after all. But I do have plans to re-orginaize these -stuffs to form a real book. - -Now the tutorials being written is devided into "series". For example, -the first series is "Nginx Variables". Each series can be roughly mapped -to a chapter in the Nginx book that I may publish in the future (of course, -I will also reorganize the contents to form "sections"). The tutorials -are -intended for Nginx users at various levels, including those Apache and -Lighttpd -users who have never used Nginx before. - -The samples in my tutorials are at least compatible with Nginx C<0.8.54>; -do not try the samples with older versions of Nginx. The latest stable -version as of this writing is C<1.0.10> after all. - -All of the Nginx modules mentioned in these tutorials are production-ready. -I will not even mention those standard Nginx modules that are either experimental -or buggy. - -I'm going to make extensive use of Nginx 3rd-party modules here. If you' -re too -lazy to download and install those modules one by one, then you are recommended -to download and install the C software bundle that is maintained -by me. +I've been doing a lot of work in the Nginx world over the last few years and +I've also been thinking about writing a series of tutorial-like articles to +explain to more people what I've done and what I've learned in this area. Now I +have finally decided to post serial articles to the Sina Blog +L in Chinese. Every article will roughly +cover a single topic and will be in a rather casual style. But at some point in +the future I may restructure the articles and their style in order to turn them +into a "real" book. + +The articles are divided into series. For example, the first series is +"Nginx Variables". Each series can be thought of as mapping to a chapter in the +Nginx book that I may publish in the future. + +The articles are intended for Nginx users of all experience levels, including +users with extensive Apache and Lighttpd experience who may have never used +Nginx before. + +The examples in the articles are at least compatible with Nginx C<0.8.54>. Do +not try the examples with older versions of Nginx. The latest stable version of +Nginx as of this writing is C<1.7.9>. + +All of the Nginx modules referenced in the articles are production-ready. I will +not be covering any Nginx core modules that are either experimental or buggy. +Additionally, I will be making extensive use of 3rd-party Nginx modules in the +examples. If it's inconvenient for you to download and install the individual +modules one at a time then I highly recommend that you download and install the +C software bundle that I maintain. L -All of the modules mentioned in these tutorials, including the Nginx stable -core that is fresh enough, have been included in this bundle. +All of the modules referenced in the articles, including the core Nginx modules +that are new (but stable), are included in the OpenResty bundle. -One principle that I've been trying to follow in these tutorials is to -use small and concise configure examples to validate the concepts and principles -that are being explained. I hope this can help the reader to build the -good habit of not accepting others' viewpoints or statements without testing -them. This style may have something to do with my QA background. In fact, -I keep adjusting and correcting my words according to the running results -of my little samples in the process of writing. +A principle that I will be trying to adhere to is to use small concise examples +to explain and validate the concepts and behaviors being described. My hope is +that it will help the reader to develop the good habit of not accepting others' +viewpoints or statements at face value without testing them first. This approach +may have something to do with my QA background. In fact, I keep tweaking and +correcting the articles based on the results of running the examples while +writing. -For problematic code samples, we will intentionally make them look different -from those good samples, that is, all the lines of bad samples will -be prefixed with a question mark, i.e., "C". Here is an example: +The examples in the articles fall into one of two categories, good and +problematic. The purpose of the problematic examples is to highlight potential +pitfalls and other areas where Nginx or its modules behave in ways that readers +may not expect. Problematic examples are easy to identify because each line of +text in the example will be prefixed with a question mark, i.e., "C". Here is +an example: :nginx ? server { @@ -62,27 +60,25 @@ be prefixed with a question mark, i.e., "C". Here is an example: Do not reproduce these articles without explicit permissions from us. Copyright reserved. -I welcome the readers to send feedback to me (C), especially constructive criticisms. +I encourage readers to send feedback (C), especially +constructive criticism. -The source for all the articles has been put onto the GitHub web site -and is under version control: +The source for all the articles is on GitHub: L -The source files are under the F directory. I am using a little -markup language that is a mixture of C and C to write these -articles. -They are just those F<.tut> files. You are very welcome to create forks -and/or provide patches. +The source files are under the F directory. I am using a little markup +language that is a mixture of C and C to write these articles. They +are the F<.tut> files. You are welcome to create forks and/or provide patches. -The e-books files that are suitable for cellphones, Kindle, -iPad/iPhone, Sony Readers, and other devices, can be downloaded from here: +The e-books files that are suitable for cellphones, Kindle, iPad/iPhone, +Sony Readers, and other devices can be downloaded from here: L -Special thanks go to Kai Wu (kai10k) who kindly translates these tutorials to English. +Special thanks go to Kai Wu (kai10k) who kindly translates these articles to +English. agentzh at home in the Fuzhou city October 30, 2011 - diff --git a/en/01-NginxVariables01.tut b/en/01-NginxVariables01.tut index d8d0381..fc45645 100644 --- a/en/01-NginxVariables01.tut +++ b/en/01-NginxVariables01.tut @@ -183,7 +183,7 @@ around the variable name (excluding the C<$> prefix), as in C<${first}>. Let's test this sample: :bash - $ curl 'http://localhost:8080/test + $ curl 'http://localhost:8080/test' hello world == Variable Declaration and Creation == diff --git a/en/01-NginxVariables02.tut b/en/01-NginxVariables02.tut index 1b076cc..a0bebeb 100644 --- a/en/01-NginxVariables02.tut +++ b/en/01-NginxVariables02.tut @@ -97,7 +97,7 @@ request being processed, and is irrelevant to C. The Nginx variables we have seen so far are all (implicitly) created by directives like L. We usually call such variables "user-defined -varaibles", or simply "user variables". There is also another kind of Nginx +variables", or simply "user variables". There is also another kind of Nginx variables that are I by either the Nginx core or Nginx modules. Let's call this kind of variables "built-in variables". diff --git a/en/01-NginxVariables05.tut b/en/01-NginxVariables05.tut index 46dba1c..f279e23 100644 --- a/en/01-NginxVariables05.tut +++ b/en/01-NginxVariables05.tut @@ -5,7 +5,7 @@ === A Detour to Subrequests === We have seen earlier that the lifetime of variable containers is bound to the -request, but I own you a formal definition of "requests" there. You might have +request, but I owe you a formal definition of "requests" there. You might have assumed that the "requests" in that context are just those HTTP requests initiated from the client side. In fact, there are two kinds of "requests" in the Nginx world. One is called "main requests", and the other is called diff --git a/en/01-NginxVariables06.tut b/en/01-NginxVariables06.tut index f474147..290fb71 100644 --- a/en/01-NginxVariables06.tut +++ b/en/01-NginxVariables06.tut @@ -212,8 +212,8 @@ construct such a horrible example: Here we use our old friend, the L directive, to map the value of the built-in variable L to our user variable C<$tag>. When L takes the value C, the value C<1> is assigned to -C<$tags>; when L takes the value C, the value C<2> is -assigned instead to C<$tags>; under all the other conditions, C<0> is assigned. +C<$tag>; when L takes the value C, the value C<2> is +assigned instead to C<$tag>; under all the other conditions, C<0> is assigned. Next, in C, we first initiate a subrequest to C by using the L directive, and then output the value of C<$tag>. And within C, we directly output the value of C<$tag>. Guess diff --git a/en/01-NginxVariables08.tut b/en/01-NginxVariables08.tut index 55df923..e600d51 100644 --- a/en/01-NginxVariables08.tut +++ b/en/01-NginxVariables08.tut @@ -135,7 +135,7 @@ is requested: :bash - $ curl 'http://localhost:8080/test?names=Tom,Jim,Bob + $ curl 'http://localhost:8080/test?names=Tom,Jim,Bob' [Tom] [Jim] [Bob] Clearly module L make it easier to handle inputs with variable diff --git a/en/02-NginxDirectiveExecOrder01.tut b/en/02-NginxDirectiveExecOrder01.tut index db02d49..71dd83c 100644 --- a/en/02-NginxDirectiveExecOrder01.tut +++ b/en/02-NginxDirectiveExecOrder01.tut @@ -1,13 +1,12 @@ = Nginx directive execution order (01) = -It can be really frustrated for many Nginx users, that -if multiple Nginx module's commands are written within -one C directive, the execution order can be -very different from the order they were written. For those -impatient who choose "try out possibilities before everything -else", the directive commands can be scattered like a hell. -This series is to uncover the mysteries and help you better -understand the execution ordering behind the scene. +When there are multiple Nginx module commands in a +C directive, the execution order can be +different from what you expect. Busy Nginx users who +attempt to configure Nginx by "trial and error" may be +very confused by this behavior. This series is to +uncover the mysteries and help you better +understand the execution ordering behind the scenes. We start with a confused example: @@ -22,33 +21,31 @@ We start with a confused example: Clearly, we'd expect to output C<32>, followed by C<56>. Because variable C<$a> has been reset after command L "is -executed". Really? you are welcomed to the reality: +executed". Really? the reality is: :bash - $ curl 'http://localhost:8080/test + $ curl 'http://localhost:8080/test' 56 56 Wow, statement C must have had been executed before -the first C command, but why? Is it a Nginx bug ? +the first C command, but why? Is it a Nginx bug? -There ain't any Nginx bug here, or we'd rather rephrase it as a -feature, and it's a long story. When Nginx handles every request, +No, this is not an Nginx bug. When Nginx handles every request, the execution follows a few predefined phases. -There can be altogehter 11 phases when Nginx handles a request, let's +There can be altogether 11 phases when Nginx handles a request, let's start with three most common ones: C, C and C -(later on the other phases will be addressed) +(The other phases will be addressed later.) -Usually a Nginx module and its commands register their execution +Usually an Nginx module and its commands register their execution in only one of those phases. For example command L runs in phase C, and command L runs in phase C. Since phase C occurs before phase C for every request processing, its commands are executed earlier as well. Therefore, command L always gets executed before command L within one C directive, regardless of their statement ordering -in the -configuration. +in the configuration. Back to our example: @@ -69,19 +66,17 @@ The actual execution ordering is: It's clear now, two commands L are executed in phase C, two commands L are executed afterwards in -phase C. Commands belonging to different phases cannot be -executed back and forth. +phase C. Commands in different phases cannot be executed +back and forth. -To prove ourselves and better uncover these points, We can -troubleshoot Nginx's "debug log". +To prove this, we can enable Nginx's "debug log". -We've not checked Nginx "debug log" before, so let's briefly introduce -its usage."debug log" by default is disabled, because it has very -big runtime overheads and overall Nginx service is degraded. To enable -"debug log" we would need to reconfigure and recompile Nginx binary, by -giving C<--with-debug> option for the package's C<./configure> script. -The typical steps are as following when build under Linux or Mac OS X -from source: +If you have not worked with Nginx "debug log" before, here is a brief +introduction. The "debug log" is disabled by default because +performance is degraded when it is enabled. To enable "debug log" +you must reconfigure and recompile Nginx, and set the +C<--with-debug> option for the package's C<./configure> script. +When building under Linux or Mac OS X from source: :bash tar xvf nginx-1.0.10.tar.gz @@ -240,4 +235,3 @@ of execution ordering. Igor Sysoev, the author of Nginx, has made the statements a few times publicly, that Nginx mini language in its configuration is "declarative" not "procedural". - diff --git a/en/02-NginxDirectiveExecOrder07.tut b/en/02-NginxDirectiveExecOrder07.tut index 97154fe..910fb11 100644 --- a/en/02-NginxDirectiveExecOrder07.tut +++ b/en/02-NginxDirectiveExecOrder07.tut @@ -120,7 +120,7 @@ is F. Many newbies might take it for granted that error C<404> is caused when the needed C does not exist. The former example tells us, C<404> error could be returned even if the needed C is configured -and matched. This is because error C<404> means the non-existence of a +and matched. This is because error C<404> means the non-existence of an abstract "resource", not the specific C. Another frequent mistake is missing the command for phase C, diff --git a/en/02-NginxDirectiveExecOrder08.tut b/en/02-NginxDirectiveExecOrder08.tut index 0954612..478c514 100644 --- a/en/02-NginxDirectiveExecOrder08.tut +++ b/en/02-NginxDirectiveExecOrder08.tut @@ -106,7 +106,7 @@ from its original address and the proxies in between are transparent. For this exact purpose, module L needs hook handlers in the first phase, the C phase, so the rewriting occurs as early as possible. -Behind C is the C phase. We briefly mentioned +Behind C is the C phase. We briefly mentioned in L, when module L and its commands are configured in C directive, they basically execute in C phase. We have an example below: diff --git a/tutorial-simple.css b/tutorial-simple.css new file mode 100644 index 0000000..6bc727f --- /dev/null +++ b/tutorial-simple.css @@ -0,0 +1,50 @@ +div.thumb img.thumbimage { + background-color: #FFFFFF; +} + +html .thumbimage { + border: 1px solid #CCCCCC; +} + +img { + vertical-align: middle; +} + +div.thumbinner { + background-color: #F9F9F9; + border: 1px solid #CCCCCC; + font-size: 94%; + overflow: hidden; + padding: 3px !important; + text-align: center; + min-width: 100px; +} + +.thumbcaption { + text-align: left; + border: medium none; + font-size: 94%; + line-height: 1.4em; + padding: 3px !important; +} + +div.tright { + margin: 0.5em 1.3em 1.3em 1.4em; +} + +div.thumb { + background-color: transparent; + width: auto; +} + +div.tright, div.floatright, table.floatright { + clear: right; + float: right; +} + +.magnify { + float: right; + background: none repeat scroll 0 0 transparent !important; + border: medium none !important; + direction: ltr; +} diff --git a/utils/gen-html-index-cn.pl b/utils/gen-html-index-cn.pl index 936d37f..a989a24 100755 --- a/utils/gen-html-index-cn.pl +++ b/utils/gen-html-index-cn.pl @@ -1,6 +1,7 @@ #!/usr/bin/env perl -use encoding 'utf8'; +use v5.10.1; +use utf8; use strict; use warnings; @@ -85,7 +86,7 @@ $res .= "\n"; for my $infile (@ARGV) { - open my $in, $infile + open my $in, "<:encoding(utf-8)", $infile or die "Cannot open $infile for reading: $!\n"; $res .= do { local $/; <$in> }; close $in; @@ -94,7 +95,7 @@ $res .= ""; if ($outfile) { - open my $out, ">:encoding(UTF-8)", $outfile + open my $out, ">:encoding(utf-8)", $outfile or die "Cannot open $outfile for writing: $!\n"; print $out $res; diff --git a/utils/gen-html-index-en.pl b/utils/gen-html-index-en.pl index 59ea7fc..06588fc 100755 --- a/utils/gen-html-index-en.pl +++ b/utils/gen-html-index-en.pl @@ -1,6 +1,7 @@ #!/usr/bin/env perl -use encoding 'utf8'; +use v5.10.1; +use utf8; use strict; use warnings; @@ -91,7 +92,7 @@ $res .= "
\n"; for my $infile (@ARGV) { - open my $in, $infile + open my $in, "<:encoding(utf-8)", $infile or die "Cannot open $infile for reading: $!\n"; $res .= "
\n"; my $c = do { local $/; <$in> }; diff --git a/utils/tut2wiki-cn.pl b/utils/tut2wiki-cn.pl index 145903b..0689855 100755 --- a/utils/tut2wiki-cn.pl +++ b/utils/tut2wiki-cn.pl @@ -1,8 +1,9 @@ #!/usr/bin/env perl +use v5.10.1; +use utf8; use strict; use warnings; -use encoding 'utf8'; use Getopt::Std; my %opts; @@ -36,7 +37,7 @@ my $infile = shift or usage(); -open my $in, "<:encoding(UTF-8)", $infile +open my $in, "<:encoding(utf-8)", $infile or die "cannot open $infile for reading: $!\n"; my $prev; @@ -74,7 +75,9 @@ close $in; -open $in, "<:encoding(UTF-8)", \$src; +utf8::encode($src); + +open $in, "<:encoding(utf-8)", \$src or die $!; my $wiki = ''; undef $prev; @@ -209,7 +212,7 @@ $wiki =~ s/^\s+|\s+$//sg; if ($outfile) { - open my $out, ">:encoding(UTF-8)", $outfile + open my $out, ">:encoding(utf-8)", $outfile or die "Cannot open $outfile for writing: $!\n"; print $out $wiki; @@ -225,4 +228,3 @@ sub usage { die "Usage: $0 [-o ] \n"; } - diff --git a/utils/tut2wiki-en.pl b/utils/tut2wiki-en.pl index 0288544..b90c5de 100755 --- a/utils/tut2wiki-en.pl +++ b/utils/tut2wiki-en.pl @@ -1,8 +1,9 @@ #!/usr/bin/env perl +use v5.10.1; +use utf8; use strict; use warnings; -use encoding 'utf8'; use Getopt::Std; my %opts; diff --git a/utils/wiki2html-cn.pl b/utils/wiki2html-cn.pl index cab37b6..5d3c66e 100755 --- a/utils/wiki2html-cn.pl +++ b/utils/wiki2html-cn.pl @@ -1,6 +1,7 @@ #!/usr/bin/env perl -use encoding 'utf8'; +use v5.10.1; +use utf8; use strict; use warnings; @@ -44,7 +45,7 @@ die "Bad input file $infile\n"; } -open my $in, "<:encoding(UTF-8)", $infile +open my $in, "<:encoding(utf-8)", $infile or die "Cannot open $infile for reading: $!\n"; my $ctx = {}; @@ -96,7 +97,7 @@ #$html .= " \n\n"; if ($outfile) { - open my $out, ">:encoding(UTF-8)", $outfile + open my $out, ">:encoding(utf-8)", $outfile or die "Cannot open $outfile for writing: $!\n"; print $out $html; @@ -232,4 +233,3 @@ sub fmt_code { sub usage { die "Usage: $0 [-o ] \n"; } - diff --git a/utils/wiki2html-en.pl b/utils/wiki2html-en.pl index b2fd679..51a5c68 100755 --- a/utils/wiki2html-en.pl +++ b/utils/wiki2html-en.pl @@ -1,6 +1,7 @@ #!/usr/bin/env perl -use encoding 'utf8'; +use v5.10.1; +use utf8; use strict; use warnings; diff --git a/zh-cn/01-NginxVariables01.tut b/zh-cn/01-NginxVariables01.tut index fc171eb..4742907 100644 --- a/zh-cn/01-NginxVariables01.tut +++ b/zh-cn/01-NginxVariables01.tut @@ -128,7 +128,7 @@ C<$> 字符给转义 名围起来，比如这里的 C<${first}>. 上面这个例子的输出是： :bash - $ curl 'http://localhost:8080/test + $ curl 'http://localhost:8080/test' hello world L 指令（以及前面提到的 L diff --git a/zh-cn/01-NginxVariables08.tut b/zh-cn/01-NginxVariables08.tut index 1670861..987b208 100644 --- a/zh-cn/01-NginxVariables08.tut +++ b/zh-cn/01-NginxVariables08.tut @@ -115,7 +115,7 @@ C 和 C 这三条配置指令，其含 ： :bash - $ curl 'http://localhost:8080/test?names=Tom,Jim,Bob + $ curl 'http://localhost:8080/test?names=Tom,Jim,Bob' [Tom] [Jim] [Bob] 我们看到，使用 L 模块可以很方便地处理这样具有不 diff --git a/zh-cn/02-NginxDirectiveExecOrder01.tut b/zh-cn/02-NginxDirectiveExecOrder01.tut index 12f40b4..5543204 100644 --- a/zh-cn/02-NginxDirectiveExecOrder01.tut +++ b/zh-cn/02-NginxDirectiveExecOrder01.tut @@ -25,7 +25,7 @@ C<$a>. 然而不幸的是，事实并非如此： :bash - $ curl 'http://localhost:8080/test + $ curl 'http://localhost:8080/test' 56 56