Re: SPITupleTable members missing in docs

2019-07-12 Thread Fabien COELHO



Hello Daniel,

Since this makes the number of internal members far outnumber the public 
ones, also reword the statement about which fields can be used to try 
and improve clarity.


Patch applies cleanly, doc build ok.

To take into account Tom's comment, I'd suggest a middle ground by 
commenting a public and private part explicitely in the struct, something 
like:


  typedef struct {
/* PUBLIC members to be used by callers ... */
...
...
/* PRIVATE members, not intended for external usage ... */
...
  } ... ;

Another option would be to use some python-like naming convention on such 
members, eg with a leading underline character.


Even if it is redundant with the paragraph below, it would make things 
visually clear as well.


Note: I'm probaly not a member of the pgdoc list, so the delivery may fail 
there.


--
Fabien.




Re: SPITupleTable members missing in docs

2019-07-12 Thread Fabien COELHO



Hello,

To take into account Tom's comment, I'd suggest a middle ground by 
commenting a public and private part explicitely in the struct,

   typedef struct {
 /* PUBLIC members to be used by callers ... */
 /* PRIVATE members, not intended for external usage ... */
   } ... ;


One problem is that the members we've retroactively decided are "public"
are in the middle of the struct :-(.


Argh, I did not notice this tiny but relevant detail.


But it occurs to me that there's no good reason we couldn't re-order the
members, as long as we only do so on HEAD and not in released versions.
That would make it a bit less inconsistent and easier to add labels
such as you suggest.


Indeed. SPI-dependent extensions are likely recompiled between major 
version, so a reordering should not cause significant problems.


This mean that a simple doc patch is turned into a code patch.

--
Fabien.




Re: SPITupleTable members missing in docs

2019-07-15 Thread Fabien COELHO


Hello Daniel,

I quite like this suggestion, so I’ve changed the patch to do this. 
Removed the doc: in the commit message to indicate that this is no 
longer just touching documentation.


And it should be posted to .

--
Fabien.

Re: SPITupleTable members missing in docs

2019-07-15 Thread Fabien COELHO



I quite like this suggestion, so I’ve changed the patch to do this.  Removed
the doc: in the commit message to indicate that this is no longer just touching
documentation.


About v2: applies cleanly, compiles, make check and doc gen ok.

However, the documentation does not look right, field comments are not 
aligned. Do not use tabs in the sgml file, use spaces only, otherwise the 
display layout is left to chance.


--
Fabien.

Re: SPITupleTable members missing in docs

2019-07-17 Thread Fabien COELHO



I quite like this suggestion, so I’ve changed the patch to do this.  Removed
the doc: in the commit message to indicate that this is no longer just touching
documentation.


About v2: applies cleanly, compiles, make check and doc gen ok.

However, the documentation does not look right, field comments are not 
aligned. Do not use tabs in the sgml file, use spaces only, otherwise 
the display layout is left to chance.


Of course, that was me fat-fingering.  Fixed in the attached v3. 
Thanks for reviewing!


V3 fixes the html display alignment issue. Patch marked as ready.

--
Fabien.

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-04 Thread Fabien COELHO


Hello Tom,


oid oid
Row identifier

adrelid oid (references pg_class.oid)
The table this column belongs to

adnum int2 (references pg_attribute.attnum)
The number of the column

adbin pg_node_tree
The column default value, in nodeToString() representation. Use
pg_get_expr(adbin, adrelid) to convert it to an SQL expression.

Thoughts?


+1

My 0.02€: I'm wondering whether the description could/should match SQL 
syntax, eg:


  oid OID
  adrelid OID REFERENCES pg_class(oid)
  adnum INT2 REFERENCES pg_attribute(attnum)
  …

Or maybe just uppercase type names, especially when repeated?

  oid OID
  adrelid OID (references pg_class.oid)
  adnum INT2 (references pg_attribute.attnum)
  …

I guess that reference targets would still be navigable.

--
Fabien.

Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-05 Thread Fabien COELHO



Hello Tom,


   oid OID


Meh.  I'm not a fan of overuse of upper case --- it's well established
that that's harder to read than lower or mixed case.  And it's definitely
project policy that type names are generally treated as identifiers not
keywords, even if some of them happen to be keywords under the hood.


I found "oid oid" stuttering kind of strange, hence an attempt at 
suggesting something that could distinguish them.



The markup I had in mind was  for the field name
and  for the type name, but no decoration beyond that.


Ok. If they are displayed a little differently afterwards that'd may help.


As for the references, it seems to me that your notation would lead
people to think that there are actual FK constraints in place, which
of course there are not (especially not on the views).


In practice the system ensures that the target exists, so it is as-if 
there would be a foreign key enforced?


My point is that using differing syntaxes for the more-or-less the same 
concept does not help user understand the semantics, but maybe that is 
just me.



I'm not hugely against it but I prefer what I suggested.


Ok!

--
Fabien.




Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-08 Thread Fabien COELHO



Hello Tom,


Here's a more fully fleshed out draft for this, with stylesheet
markup to get extra space around the column type names.


I find this added spacing awkward, espacially as attribute names are 
always one word anyway. I prefer the non spaced approach.


If spacing is discussed, should the layout rather try to align type 
information, eg:


  attributetype
  description
  ---
  foo  bla
  this does this and that ...
  and here is an example about it
  ---
  foo-foo-foo  bla-bla
  whatever bla bla blah bla foo foo foo ...
  and stuff

I'm not sure how achievable it is from a xml & processing point of view,
and how desirable it is, I'm just throwing it for consideration.

--
Fabien.




Re: Another modest proposal for docs formatting: catalog descriptions

2020-05-09 Thread Fabien COELHO


Hello Tom,


Here's a more fully fleshed out draft for this, with stylesheet
markup to get extra space around the column type names.



I find this added spacing awkward, espacially as attribute names are
always one word anyway. I prefer the non spaced approach.


It's certainly arguable that that look is too heavy-handed.  In the
attached, I knocked down the extra space from 1em to 0.25em, which
makes it quite a bit subtler --- are you any happier with this?


Yes, definitely.


BTW, I don't think it's very accurate that "attribute names are
always one word" --- see the second attachment.


Indeed.


Here if anything I'm wanting a little more space.


I'm fine with 0.25em which allows some breathing without looking awkward. 
Maybe a little more would still be okay, but not much more.



If spacing is discussed, should the layout rather try to align type
information, eg:


I thought about that, but it seems extremely close to some of the
earlier function-table layouts that were so widely panned.  The SGML
source would have to be a lot uglier too, probably with explicit use
of spanspec's on every row.


Hmmm, that's the kind of things I was afraid of.

It could be done no doubt, but I think people would not see it as an 
improvement.


Possibly. I'm a little at odds with Type not being above types, but far on 
the left, so that you cannot really "see" that it is about the format, 
especially with long attribute names:


  Column Type
   Description
  quite_a_long_attribute and_its_type
   ...

The horizontal distance between "Type" and "and_its_type" is so wide as to 
hide the clue that the former is describing the later. But maybe aligning 
would be too ugly.


If I can suggest more adjustements, maybe the description margin is a too 
much, I'd propose reduce it to about 3 chars wide. Obviously any aesthetic 
opinion is by definition subjective and prone to differ from one person to 
the next…


--
Fabien.