[PATCH] minor doc fix for create-role

tara@anne.cat writes:

Attached is a minor patch to fix the name param documentation for create role, just adding a direct quote from user-manag.sgml talking about what the role name is allowed to be. I was searching for this information and figured the reference page should have it as well.

Hm, I guess my reaction to this proposal is "why just here?". We have
an awful lot of different CREATE commands, and none of them say more
about the target name than this one does. (Not to mention ALTER, DROP,
etc.) Perhaps it's worth adding some boilerplate text to all those
places, but I'm dubious.

Also, the specific text proposed for addition doesn't seem that helpful,
since it doesn't define which characters are "special characters".
I'd rather see something like "The name must be a valid SQL identifier
as defined in <link to section 4.1.1>." But, while that would work fine
in HTML output, it would not be particularly short or useful in man-page
output.

Perhaps the ideal solution would be further markup on the synopsis
sections that somehow identifies each term as an "identifier" or
other appropriate syntactic category, and provides a hyperlink to
a definition (in output formats that are friendly to that). Seems
like a lot of work though :-(

regards, tom lane

Hi Tom,

I agree mostly. It actually does have the words “SQL identifier” in the patch. But you are right it doesn’t link to what a SQL identifier is, but it does provide a practical solution of quoting. That was the part I cared about as a user, I just wanted to solve my problem of an email address as a role name (yes I know that’s sort of dumb as email addresses change). This also addresses the question, why just here, because this was a pain point in the docs for me yesterday :)

I also agree your ideal solution is definitely better than what I pushed. But I’m not ready to take that on. If someone else is, I welcome their patch over mine.

-Tara

—
“Rivers know this: there is no hurry. We shall get there some day.”