Re: libpq host/hostaddr/conninfo inconsistencies

Hello Kyotaro-san,

> On such standpoint, the first hunk in the patch attracted my
> eyes.
>
>       <term><literal>host</literal></term>
>       <listitem>
>        <para>
> -        Name of host to connect to.<indexterm><primary>host name</primary></indexterm>
> -        If a host name begins with a slash, it specifies Unix-domain
> -        communication rather than TCP/IP communication; the value is the
> -        name of the directory in which the socket file is stored.
> +       </para>
>
> I don't think this is user-friendly since almost all of them don't write 
> multiple hosts there. So I prefer the previous organization.

ISTM that specifying the expected syntax is the first information needed?

The previous organization says "this is a host name (bla bla bla) btw I 
lied at the beginning this is a list".

> The description about IP-address looks too verbose, especially we don't 
> need explain what is IP-address here.

Ok.

I agree that the order is not the best possible one. Here is a simplified 
and reordered version:

""" Comma-separated list of hosts to connect to. Each item may be a host 
name that will be resolved with a look-up, a numeric IP address that will 
be used directly, or the name of a directory which contains the socket 
file for Unix-domain communication, if the specification begins with a 
slash. Each specified target will be tried in turn in the order given. See 
<xref linkend="libpq-multiple-hosts"/> for details. """

What do you think about that version.

-- 
Fabien.