Re: Документация, директива pid

[Maxim Dounin]

Hello!

On Wed, Nov 29, 2017 at 08:05:04PM +0200, Gena Makhomed wrote:

> On 29.11.2017 17:50, Maxim Dounin wrote:
> 
> > Patches, что называется, are welcome.
> 
> # HG changeset patch
> # User Gena Makhomed <gmm at csdoc.com>
> # Date 1511977733 -7200
> #      Wed Nov 29 19:48:53 2017 +0200
> # Node ID 41edc73c0662fa9d62cb2cc7983fd9068fd9b390
> # Parent  26e547b1022d5e64fe5dd4060f64f15c678c2e8a
> Updated documentation of directive "pid".
> 
> diff -r 26e547b1022d -r 41edc73c0662 xml/ru/docs/ngx_core_module.xml
> --- a/xml/ru/docs/ngx_core_module.xml	Mon Nov 27 11:56:06 2017 +0300
> +++ b/xml/ru/docs/ngx_core_module.xml	Wed Nov 29 19:48:53 2017 +0200
> @@ -401,12 +401,19 @@
> 
> 
>   <directive name="pid">
> -<syntax><value>файл</value></syntax>
> -<default>nginx.pid</default>
> +<syntax><value>имя файла</value></syntax>

Использование пробела тут ломает синтаксис - получается, что 
директива принимает два праметра, "имя" и "файла".  Не надо так.

> +<default>Зависит от параметров сборки nginx</default>
>   <context>main</context>

Это необычайно информативно, и наверное всё, что можно тут 
сделать, это осознать, что некоторые идеи - просто плохие.

> 
>   <para>
> -Задаёт <value>файл</value>, в котором будет храниться номер (PID) 
> главного процесса.
> +Задаёт <value>имя файла</value>, в котором будет храниться 
> идентификатор (PID) главного процесса nginx.
> +Значение по умолчанию задается в момент конфигурирования nginx 
> параметром <literal>configure --pid-path</literal>.
> +Узнать значение по умолчанию для директивы <literal>pid</literal> можно 
> запустив команду <literal>nginx -V</literal>
> +и посмотрев на значение параметра <literal>configure --pid-path</literal>.
> +</para>

Это мало соответствует тому, что хотелось бы видеть в описании 
директивы.

> +
> +<para>
> +Не рекомендуется явно указывать значение директивы 
> <literal>pid</literal> в конфигурационном файле.
>   </para>

Это не соответствует действительности.  PID-файл можно и нужно 
задавать во многих ситуациях, например - если на машине 
запускается несколько независимых экземпляров nginx'а.  Скажем, в 
портах FreeBSD такое поддерживается из коробки штатными 
rc-скриптами.

> 
>   </directive>

Отмечу также в скобках, что

- не стоит смешивать несколько изменений в один патч;

- при смысловых изменениях содержимого документации следует менять 
  ревизию в заголовке соответствующего файл.  Это позволяет 
  показывать на сайте плашку "этот перевод может быть устаревшим,
  смотрите английскую версию для ознакомления с последними 
  изменениями", если перевод по какой-то причине не 
  обновлён до текущей версии.

- русский язык - не единственный язык документации, и делать патчи 
  только на один язык - плохая идея.  Более того, основной язык 
  документации - английский, см. выше про ревизии, так что обычно 
  лучше начинать с него.

- в предыдущем письме было перечислено 11 параметров configure, 
  которые влияют на значения различных директив.  Нет никакого смысла 
  дублировать эту информацию в описании одной из директив, и не 
  дублировать в описаниях остальных.  Наоборот, есть смысл так не 
  делать: текущий подход может быть не очень удобен для новичков, 
  ни разу не сталкивавшихся с configure, но консистентен и логичен.

-- 
Maxim Dounin
http://mdounin.ru/