Re: documentation structure - Mailing list pgsql-hackers

From Corey Huinker
Subject Re: documentation structure
Date
Msg-id CADkLM=dKrJdGt0mNMNA=P4a9C9dY-zy3h+xAX8SZ1G4yzVSMsQ@mail.gmail.com
Whole thread Raw
In response to Re: documentation structure  (Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>)
List pgsql-hackers
I havent dealt with variadic yet, since the two styles are visually
different, not just markup (<optional>...</optional> renders as [...]).

The two styles for variadic are the what I call caller-style:

   concat ( val1 "any" [, val2 "any" [, ...] ] )
   format(formatstr text [, formatarg "any" [, ...] ])

While this style is obviously clumsier for us to compose, it does avoid relying on the user understanding what the word variadic means. Searching through online documentation of the python *args parameter, the word variadic never comes up, the closest they get is "variable length argument". I realize that python is not SQL, but I think it's a good point of reference for what concepts the average reader is likely to know.

Looking at the patch, I think it is good, though I'd consider doing some indentation for the nested <optional>s to allow the author to do more visual tag-matching. The ']'s were sufficiently visually distinct that we didn't really need or want nesting, but <optional> is just another tag to my eyes in a sea of tags.

pgsql-hackers by date:

Previous
From: Alvaro Herrera
Date:
Subject: Re: Add SPLIT PARTITION/MERGE PARTITIONS commands
Next
From: Peter Eisentraut
Date:
Subject: Re: plenty code is confused about function level static