Re: Documentation improvements for partitioning

Robert Haas <robertmhaas(at)gmail(dot)com> writes:
> This is about list-ifying a note, but I think we should try to
> de-note-ify it. It's a giant block of text that is not obviously more
> noteworthy than the surrounding text; I think <note> should be saved
> for things that particularly need to be called out.

Yeah. A big problem with the markup we use, imo, is that <note> segments
are displayed in a way that makes them more prominent than the surrounding
text, not less so. That doesn't really square with my intuitive view of
what a <note> ought to be used for; it forces it to be considered as
something only slightly less dangerous than a <caution> or <warning>, not
as a parenthetical remark. But that's what we have to deal with so
we should mark up our text accordingly.

regards, tom lane