Thread: Re: Documentation improvement patch
> On 5 Sep 2024, at 11:33, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote: > > Dear all, > I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look. > The inconsistencies were noticed by: Ekaterina Kiryanova, Elena Indrupskaya, Maxim Yablokov, Anna Uraskova, Elena Karavaeva,and me. > We will be looking forward to your feedback. > The patch shall be applied to the REL_17_STABLE branch. Most of these seem fine, but I need another read-through to digest them fully. Just a few small comments: - Specifies the builtin provider locale for the database default - collation order and character classification, overriding the setting - <xref linkend="create-database-locale"/>. The <link + Specifies the <literal>builtin</literal> provider locale for the database + default collation order and character classification, overriding the + setting <xref linkend="create-database-locale"/>. The <link and - Specifies the locale name when the builtin provider is used. Locale support - is described in <xref linkend="locale"/>. + Specifies the locale name when the <literal>builtin</literal> provider + is used. Locale support is described in <xref linkend="locale"/>. I don't think this use of "builtin" refers to the config value but rather the type of locale, so I think it's correct to not use <literal> here. - for not-null constraints at all, so they are not + for <literal>NOT NULL</literal> constraints at all, so they are not This seems mostly to be a question of taste, I don't think not-null is incorrect here. -- Daniel Gustafsson
Thank you for your feedback. 1. Since we do not want to use <literal> here, I suggest we hyphenate it as "built-in". What's your take on it? 2. Leaving not-null is fine. -- Oleg Sibiryakov On 06.09.2024 16:20, Daniel Gustafsson wrote: >> On 5 Sep 2024, at 11:33, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote: >> >> Dear all, >> I have prepared a patch containing some minor inconsistencies in the documentation. Please, take a look. >> The inconsistencies were noticed by: Ekaterina Kiryanova, Elena Indrupskaya, Maxim Yablokov, Anna Uraskova, Elena Karavaeva,and me. >> We will be looking forward to your feedback. >> The patch shall be applied to the REL_17_STABLE branch. > Most of these seem fine, but I need another read-through to digest them fully. > Just a few small comments: > > - Specifies the builtin provider locale for the database default > - collation order and character classification, overriding the setting > - <xref linkend="create-database-locale"/>. The <link > + Specifies the <literal>builtin</literal> provider locale for the database > + default collation order and character classification, overriding the > + setting <xref linkend="create-database-locale"/>. The <link > and > - Specifies the locale name when the builtin provider is used. Locale support > - is described in <xref linkend="locale"/>. > + Specifies the locale name when the <literal>builtin</literal> provider > + is used. Locale support is described in <xref linkend="locale"/>. > > > I don't think this use of "builtin" refers to the config value but rather the > type of locale, so I think it's correct to not use <literal> here. > > > - for not-null constraints at all, so they are not > + for <literal>NOT NULL</literal> constraints at all, so they are not > > This seems mostly to be a question of taste, I don't think not-null is > incorrect here. > > -- > Daniel Gustafsson > > >
> On 10 Sep 2024, at 13:46, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote: > 1. Since we do not want to use <literal> here, I suggest we hyphenate it as "built-in". What's your take on it? I think that's the right choice given the hyphenation used in the rest of the docs. There are a few more places on that same page which should be built-in rather than builtin to separate the concept from the parameter value. -- Daniel Gustafsson
On 10.09.24 15:02, Daniel Gustafsson wrote: >> On 10 Sep 2024, at 13:46, Oleg Sibiryakov <o.sibiryakov@postgrespro.ru> wrote: > >> 1. Since we do not want to use <literal> here, I suggest we hyphenate it as "built-in". What's your take on it? > > I think that's the right choice given the hyphenation used in the rest of the > docs. There are a few more places on that same page which should be built-in > rather than builtin to separate the concept from the parameter value. I suspect that this would lead to the opposite confusion, people complaining that the provider is called "builtin" not "built-in". Arguably, the other providers are also "built in". There are no user-pluggable providers at this time.