Hello!

On Tue, Aug 29, 2023 at 08:54:46PM +0300, Sergey A. Osokin wrote:

> Hi Maxim,
>
> thanks for the review.
>
> On Tue, Aug 29, 2023 at 07:03:12PM +0300, Maxim Dounin wrote:
> > On Tue, Aug 29, 2023 at 06:28:09PM +0300, Sergey A. Osokin wrote:
> >
> > > # HG changeset patch
> > > # User Sergey A. Osokin <osa@FreeBSD.org.ru>
> > > # Date 1693322780 -10800
> > > # Tue Aug 29 18:26:20 2023 +0300
> > > # Node ID e3b7490c492c7865baf950e20f0430cf035b6cf3
> > > # Parent 4e25281328fa2152cadedc52e05f8a1b1bf531cd
> > > Provided more details about ssl_protocol directive usage by
> > > adding link to the "Server names" document.
> >
> > Please follow style as outlined at
> > http://nginx.org/en/docs/contributing_changes.html:
>
> Updated.
>
> [...]
>
> > > +<para>
> > > +The directive usage details with virtual servers are provided in the
> > > +“<link doc="server_names.xml" id="virtual_server_selection">Virtual
> > > +server selection</link>” section.
> > > +</para>
> > > +
> > > </directive>
> >
> > I would rather follow generic form of the reference, such as in
> > http://nginx.org/r/merge_slashes and other directives mentioned in
> > the section. Probably with some additional clarification, such as
> > "will be used" instead of "can be used".
> >
> > In particular, this will make translation trivial (which is also
> > desired for Russian language, which we used to maintain in the
> > up-to-date state).
> >
> > Also, this probably should be before notes, which apply to the
> > whole directive description and not the particular paragraph.
>
> Sure, here's the updated version.
>
> # HG changeset patch
> # User Sergey A. Osokin <osa@FreeBSD.org.ru>
> # Date 1693331420 -10800
> # Tue Aug 29 20:50:20 2023 +0300
> # Node ID ccc0bacc1869bebae054020c6856d045b2a11b85
> # Parent 4e25281328fa2152cadedc52e05f8a1b1bf531cd
> Updated ngx_http_ssl_module module documentation.
>
> Provided details about ssl_protocol directive usage by
> adding link to the "Server names" document.
>
> diff -r 4e25281328fa -r ccc0bacc1869 xml/en/docs/http/ngx_http_ssl_module.xml
> --- a/xml/en/docs/http/ngx_http_ssl_module.xml Tue Aug 29 09:11:57 2023 +0100
> +++ b/xml/en/docs/http/ngx_http_ssl_module.xml Tue Aug 29 20:50:20 2023 +0300
> @@ -10,7 +10,7 @@
> <module name="Module ngx_http_ssl_module"
> link="/en/docs/http/ngx_http_ssl_module.html"
> lang="en"
> - rev="61">
> + rev="62">
>
> <section id="summary">
>
> @@ -602,6 +602,15 @@
>
> <para>
> Enables the specified protocols.
> +
> +<para>

$ make
...
xmllint --noout --valid xml/en/docs/http/ngx_http_ssl_module.xml
xml/en/docs/http/ngx_http_ssl_module.xml:626: element para:
validity error : Element para is not declared in para list of
possible children
</para>
^
gmake[1]: *** [GNUmakefile:164:
libxslt/en/docs/http/ngx_http_ssl_module.html] Error 4


In this particular case, appropriate solution would be to close
the paragraph, and put notes into their own paragraph.

> +If the directive is specified on the <link id="server"/> level,
> +the value from the default will be used.

s/the default/the default server/

Also, reading it again I tend to think that "will be used" might
be misleading. It might be good to adjust this somehow to make it
clear that ssl_protocols works if used in the default server, but
will use the configuration from the default server if used in a
name-based virtual server. Not sure how though.

Alternatively, just using "can be used" as in other directives
might be good enough.

> +Defails are provided in the

s/Defails/Details/

> +“<link doc="server_names.xml" id="virtual_server_selection">Virtual
> +server selection</link>” section.
> +</para>
> +
> <note>
> The <literal>TLSv1.1</literal> and <literal>TLSv1.2</literal> parameters
> (1.1.13, 1.0.12) work only when OpenSSL 1.0.1 or higher is used.
> diff -r 4e25281328fa -r ccc0bacc1869 xml/ru/docs/http/ngx_http_ssl_module.xml
> --- a/xml/ru/docs/http/ngx_http_ssl_module.xml Tue Aug 29 09:11:57 2023 +0100
> +++ b/xml/ru/docs/http/ngx_http_ssl_module.xml Tue Aug 29 20:50:20 2023 +0300
> @@ -10,7 +10,7 @@
> <module name="Модуль ngx_http_ssl_module"
> link="/ru/docs/http/ngx_http_ssl_module.html"
> lang="ru"
> - rev="61">
> + rev="62">
>
> <section id="summary">
>
> @@ -607,6 +607,15 @@
>
> <para>
> Разрешает указанные протоколы.
> +
> +<para>
> +Если директива указана на уровне <link id="server"/>,
> +то будет использоваться значение из сервера по умолчанию.
> +Подробнее см. в разделе
> +“<link doc="server_names.xml" id="virtual_server_selection">Выбор
> +виртуального сервера</link>”.
> +</para>
> +
> <note>
> Параметры <literal>TLSv1.1</literal> и <literal>TLSv1.2</literal>
> (1.1.13, 1.0.12) работают только при использовании OpenSSL 1.0.1 и выше.

Same here.

--
Maxim Dounin
http://mdounin.ru/
_______________________________________________
nginx-devel mailing list
nginx-devel@nginx.org
https://mailman.nginx.org/mailman/listinfo/nginx-devel