Re: Formatting of warning about using ident

On 2019-07-01 13:48, Daniel Gustafsson wrote:
>> On 26 Jun 2019, at 15:09, Peter Eisentraut <peter(dot)eisentraut(at)2ndquadrant(dot)com> wrote:
>>
>> On 2019-06-14 10:47, Daniel Gustafsson wrote:
>>> The warning about using ident for authorization or access control is using a
>>> <blockquote> with an <attribution> rather than a <warning>, making it look
>>> quite different from the rest of the manual, and less like a warning IMO.
>>
>> But this is a quote from the RFC. If you want to change it to a warning
>> box, then you also need to rephrase the surrounding text. But I don't
>> really see the need. It seems fine as it is.
>
> It is indeed a quote, but to my reading/understanding the only reason we’ve
> included it is to act as a warning? Thats why the formatting stood out as it’s
> not consistent for warnings. The attached v2 instead wraps the quote in a
> <warning> with a slight rewording to make it even more prominent.

Being a quote and being a warning are two orthogonal properties. So in
that sense, wrapping the quote in a warning element is more correct.
But the problem is now that a warning box is meant to be formatted out
of line, so writing something like

<para>This feature does this and that and the other, but
<warning>
You can really make a mess with this.
</warning>
</para>

is not correct. (I'm surprised the schema even allows this.) If you
want to do this, you need to rewrite the surrounding text to be
independent of the warning and rewrite the warning to be outside of the
para and independent of it. I don't think that would be an improvement
though.

In general, I would argue in favor of fewer "note", "warning", etc.
Some documentation pages are now just a sequence of "note"s and little
proper text. If the normal text properly explains a topic and its pros
and cons, then we don't need all that extra decoration and it makes the
text easier to read.

--
Peter Eisentraut http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services