Thread: [PATCH] Improve documentation of REINDEX options

[PATCH] Improve documentation of REINDEX options

From
Josef Šimánek
Date:
Hello!

According to discussion at pgsql-general (https://www.postgresql.org/message-id/flat/CAFp7QwqFYcHiARfT91rOQj%3DmFT0MWBE%2BkxEmjfQh3QmRN1UBiw%40mail.gmail.com#05b75be4fd11c0e6216f0b329c808f72) I have prepared patch to improve documentation for REINDEX. It should be more inline with another documentation pages.

You can see the change applied in attached file. Patch can be found at https://github.com/simi/postgres/pull/3 (diff - https://github.com/simi/postgres/pull/3.diff, patch - https://github.com/simi/postgres/pull/3.patch).

This change is based on idea of Pave Stěhule, thanks a lot for that! Similar approach was used recently in https://www.postgresql.org/docs/devel/sql-dropdatabase.html.

Attachment

Re: [PATCH] Improve documentation of REINDEX options

From
Michael Paquier
Date:
On Fri, Dec 13, 2019 at 10:28:33AM +0100, Josef Šimánek wrote:
> I have prepared patch to improve documentation for REINDEX. It
> should be more inline with another documentation pages.
>
> You can see the change applied in attached file. Patch can be found at
> https://github.com/simi/postgres/pull/3 (diff -
> https://github.com/simi/postgres/pull/3.diff, patch -
> https://github.com/simi/postgres/pull/3.patch).

Please, always attach your patches to emails sent on this mailing
list.  If for a reason or another, the data located to with external
link is lost (imagine for example that your github account is gone or
that github is reduced to ashes), then such patches would be lost, and
anybody looking at this email 10 years from now would not know what
you have been writing about here.  I am attaching it here for the
archive's sake.

+<phrase>where <replaceable class="parameter">option</replaceable> can
be:</phrase>
+
+    VERBOSE
Why not...  We did that in the docs of ANALYZE for v11 when
introducing the parenthesized grammar flavor for the options
available.

-   Rebuild all the indexes on the table <literal>my_table</literal>:
+   Rebuild all the indexes on the table <literal>my_table</literal>
    with progress report per index:

 <programlisting>
-REINDEX TABLE my_table;
+REINDEX (VERBOSE) TABLE my_table;
Not sure if this part brings much to the reader though.  It is not
like the command description of REINDEX is complicated with dozens
of option choices.
--
Michael

Attachment

Re: [PATCH] Improve documentation of REINDEX options

From
Josef Šimánek
Date:


út 17. 12. 2019 v 6:36 odesílatel Michael Paquier <michael@paquier.xyz> napsal:
On Fri, Dec 13, 2019 at 10:28:33AM +0100, Josef Šimánek wrote:
> I have prepared patch to improve documentation for REINDEX. It
> should be more inline with another documentation pages.
>
> You can see the change applied in attached file. Patch can be found at
> https://github.com/simi/postgres/pull/3 (diff -
> https://github.com/simi/postgres/pull/3.diff, patch -
> https://github.com/simi/postgres/pull/3.patch).

Please, always attach your patches to emails sent on this mailing
list.  If for a reason or another, the data located to with external
link is lost (imagine for example that your github account is gone or
that github is reduced to ashes), then such patches would be lost, and
anybody looking at this email 10 years from now would not know what
you have been writing about here.  I am attaching it here for the
archive's sake.

Sorry, I'm attaching the same patch now for future reference.
 

+<phrase>where <replaceable class="parameter">option</replaceable> can
be:</phrase>
+
+    VERBOSE
Why not...  We did that in the docs of ANALYZE for v11 when
introducing the parenthesized grammar flavor for the options
available.

-   Rebuild all the indexes on the table <literal>my_table</literal>:
+   Rebuild all the indexes on the table <literal>my_table</literal>
    with progress report per index:

 <programlisting>
-REINDEX TABLE my_table;
+REINDEX (VERBOSE) TABLE my_table;
Not sure if this part brings much to the reader though.  It is not
like the command description of REINDEX is complicated with dozens
of option choices.
--
Michael
Attachment

Re: [PATCH] Improve documentation of REINDEX options

From
Josef Šimánek
Date:


út 17. 12. 2019 v 6:36 odesílatel Michael Paquier <michael@paquier.xyz> napsal:
On Fri, Dec 13, 2019 at 10:28:33AM +0100, Josef Šimánek wrote:
> I have prepared patch to improve documentation for REINDEX. It
> should be more inline with another documentation pages.
>
> You can see the change applied in attached file. Patch can be found at
> https://github.com/simi/postgres/pull/3 (diff -
> https://github.com/simi/postgres/pull/3.diff, patch -
> https://github.com/simi/postgres/pull/3.patch).

Please, always attach your patches to emails sent on this mailing
list.  If for a reason or another, the data located to with external
link is lost (imagine for example that your github account is gone or
that github is reduced to ashes), then such patches would be lost, and
anybody looking at this email 10 years from now would not know what
you have been writing about here.  I am attaching it here for the
archive's sake.

+<phrase>where <replaceable class="parameter">option</replaceable> can
be:</phrase>
+
+    VERBOSE
Why not...  We did that in the docs of ANALYZE for v11 when
introducing the parenthesized grammar flavor for the options
available.

-   Rebuild all the indexes on the table <literal>my_table</literal>:
+   Rebuild all the indexes on the table <literal>my_table</literal>
    with progress report per index:

 <programlisting>
-REINDEX TABLE my_table;
+REINDEX (VERBOSE) TABLE my_table;
Not sure if this part brings much to the reader though.  It is not
like the command description of REINDEX is complicated with dozens
of option choices.

For me this is the default way how to reindex whole table manually in psql since you get some "progress". Anyway I can remove it if you don't see any benefit in extending this example.
 
--
Michael

Re: [PATCH] Improve documentation of REINDEX options

From
Michael Paquier
Date:
On Tue, Dec 17, 2019 at 10:23:51AM +0100, Josef Šimánek wrote:
> For me this is the default way how to reindex whole table manually in psql
> since you get some "progress". Anyway I can remove it if you don't see any
> benefit in extending this example.

I have thought more about this one through the night, and I am still
not sure that this brings much.  So, committed a simpler version
handling only the option part.
--
Michael

Attachment