On Wed, 17 Jul 2024 at 07:29, Andy Fan <zhihuifan1213@163.com> wrote:
>
> It is just not clear to me how verbose the document should to be, and
> where the document should be, tablefunc.sgml, the comment above the
> function or the places just the code? In many cases you provides above
> or below are just implementation details, not the API declaimed purpose.
>
> > Something else that's not obvious is that this patch is relying on the
> > core random functions, which means that it's using the same PRNG state
> > as those functions. That's probably OK, but it should be documented,
> > because it's different from tablefunc's normal_rand() function, which
> > uses pg_global_prng_state.
>
> My above question applies to this comment.
>
> > One thing that's definitely needed is more documentation. It should
> > have its own new subsection, like the other tablefunc functions.
>
I was really referring to the SGML docs. Try to follow the style used
for the existing functions in tablefunc.sgml -- so in addition to
adding the row to the table at the top, also add one or more sections
further down the page to give more details, and example output.
Something like this:
https://www.postgresql.org/docs/current/tablefunc.html#TABLEFUNC-FUNCTIONS-NORMAL-RAND
That would be a good place to mention that setseed() can be used to
produce repeatable results.
> I did have some issue to run 'make html', but the
> error exists before my patch, so I change the document carefully without
> testing it. do you know how to fix the below error in 'make html'?
>
> $/usr/bin/xsltproc --nonet --path . --path . --stringparam pg.version '18devel' stylesheet.xsl postgres-full.xml
>
> I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl
> warning: failed to load external entity "http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"
> compilation error: file stylesheet.xsl line 6 element import
> xsl:import : unable to load http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl
> I/O error : Attempt to load network entity http://docbook.sourceforge.net/release/xsl/current/common/entities.ent
> stylesheet-html-common.xsl:4: warning: failed to load external entity
"http://docbook.sourceforge.net/release/xsl/current/common/entities.ent"
> %common.entities;
> ^
> stylesheet-html-common.xsl:124: parser error : Entity 'primary' not defined
> translate(substring(&primary;, 1, 1),
>
This looks like you're missing a required package. Try installing
docbook-xsl or docbook-xsl-stylesheets or something similar (the
package name varies depending on your distro).
Regards,
Dean