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 >> wrote: >> >> On 2019-06-14 10:47, Daniel Gustafsson wrote: >>> The warning about using ident for authorization or access control is using a >>> with an rather than a , 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 > 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 This feature does this and that and the other, but You can really make a mess with this. 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
Re: Formatting of warning about using ident
Peter Eisentraut writes: > 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. +1. With the way these things are rendered in the current HTML output, they are so visually distracting that they ought to be reserved for absolutely critical info. I almost feel that we should ban entirely, because the rendering is completely disproportional to the meaning. (Or, maybe, somebody could tinker with the stylesheets?) regards, tom lane
Re: Formatting of warning about using ident
On 7/22/19 10:09 AM, Tom Lane wrote: > Peter Eisentraut writes: >> 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. > > +1. With the way these things are rendered in the current HTML output, > they are so visually distracting that they ought to be reserved for > absolutely critical info. I almost feel that we should ban > entirely, because the rendering is completely disproportional to the > meaning. Based on the example of auth-ident.html, removing "note" seems to make sense. It just seems like it's a part of the regular documentation. However, perhaps the reason people feel the need to highlight such things is that they want to ensure the reader catches an important point, particularly as one is often reading the documentation quickly to find the piece of info they're looking for (speaking from personal experience). That said, looking through some other pages, the "notes" feel like they're other "asides" to add more detail around a particular point, or calling out a specific fact. It seems like they could be inlined as part of the regular documentation. Something like a "warning" should be visually distracting...it's a warning that the user could end up in a dangerous situation with their data, so they should heed it. > (Or, maybe, somebody could tinker with the stylesheets?) I think lessening the use of "note" would help. It would require some rewriting in places it's being used. That way, if we need something that's truly a "warning" we won't feel as hesitant to add it to the docs. Thanks, Jonathan signature.asc Description: OpenPGP digital signature
