pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedFirst Person being used (only occurs in 2 other places in all of documentation)
4+ messages / 2 participants
[nested] [flat]
* First Person being used (only occurs in 2 other places in all of documentation)
@ 2022-10-28 02:44 PG Doc comments form <noreply@postgresql.org>
2022-10-28 09:30 ` Re: First Person being used (only occurs in 2 other places in all of documentation) Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 4+ messages in thread
From: PG Doc comments form @ 2022-10-28 02:44 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: wolakk@gmail.com
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/15/cube.html
Description:
I believe the use of First Person (I) is to be avoided in the documentation.
It is incredibly rare in all of the documentation.
This is a NUANCE issue, but so are white space comments in code!
I will paste in what is written => what is suggested (fix as you wish)
On this page:
F.9.4. Defaults
I believe this union: => This union:
Below that:
... I assume the ... => ... one can assume the ...
F.9.6. Credits
>> Note that changing the credits someone is giving might be pushing it, but
again, it does not exist like this elsewhere!
I am also grateful to all Postgres ... => With gratitude to all Postgres
...
And I would like to acknowledge my gratitude to Argonne ... => With further
gratitude to Argonne ...
[I will add a separate comment for the other 2 occurrences]
Thanks in advance!
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: First Person being used (only occurs in 2 other places in all of documentation)
2022-10-28 02:44 First Person being used (only occurs in 2 other places in all of documentation) PG Doc comments form <noreply@postgresql.org>
@ 2022-10-28 09:30 ` Daniel Gustafsson <daniel@yesql.se>
2022-10-28 10:50 ` Re: First Person being used (only occurs in 2 other places in all of documentation) Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 4+ messages in thread
From: Daniel Gustafsson @ 2022-10-28 09:30 UTC (permalink / raw)
To: wolakk@gmail.com; pgsql-docs@lists.postgresql.org
> On 28 Oct 2022, at 04:44, PG Doc comments form <noreply@postgresql.org> wrote:
>
> The following documentation comment has been logged on the website:
>
> Page: https://www.postgresql.org/docs/15/cube.html
> Description:
>
> I believe the use of First Person (I) is to be avoided in the documentation.
> It is incredibly rare in all of the documentation.
I agree with this (and the other two emails about the same), these instances
would be better reworded to match the rest of the documentation.
--
Daniel Gustafsson https://vmware.com/
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: First Person being used (only occurs in 2 other places in all of documentation)
2022-10-28 02:44 First Person being used (only occurs in 2 other places in all of documentation) PG Doc comments form <noreply@postgresql.org>
2022-10-28 09:30 ` Re: First Person being used (only occurs in 2 other places in all of documentation) Daniel Gustafsson <daniel@yesql.se>
@ 2022-10-28 10:50 ` Daniel Gustafsson <daniel@yesql.se>
2022-12-02 12:56 ` Re: First Person being used (only occurs in 2 other places in all of documentation) Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 4+ messages in thread
From: Daniel Gustafsson @ 2022-10-28 10:50 UTC (permalink / raw)
To: wolakk@gmail.com; pgsql-docs@lists.postgresql.org
> On 28 Oct 2022, at 11:30, Daniel Gustafsson <daniel@yesql.se> wrote:
>
>> On 28 Oct 2022, at 04:44, PG Doc comments form <noreply@postgresql.org> wrote:
>>
>> The following documentation comment has been logged on the website:
>>
>> Page: https://www.postgresql.org/docs/15/cube.html
>> Description:
>>
>> I believe the use of First Person (I) is to be avoided in the documentation.
>> It is incredibly rare in all of the documentation.
>
> I agree with this (and the other two emails about the same), these instances
> would be better reworded to match the rest of the documentation.
The attached patch rewords the first person form sentences to match the rest of
the documentation. The "acknowledgment" sections are left as-is as I believe
they are free to have a more personal form.
I also re-arranged the section on PO file editors a bit to keep the PO file
editor paragraph on editors only and not also contain important translation
information.
--
Daniel Gustafsson https://vmware.com/
Attachments:
[application/octet-stream] first_person.diff (2.9K, ../../A324F1A0-5E09-47F0-A83E-F9AB0D35853D@yesql.se/2-first_person.diff)
download | inline diff:
diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml
index adf8dbaa91..52506fc822 100644
--- a/doc/src/sgml/cube.sgml
+++ b/doc/src/sgml/cube.sgml
@@ -537,7 +537,7 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5;
<title>Defaults</title>
<para>
- I believe this union:
+ This union:
</para>
<programlisting>
select cube_union('(0,5,2),(2,3,1)', '0');
@@ -548,7 +548,7 @@ cube_union
</programlisting>
<para>
- does not contradict common sense, neither does the intersection
+ does not contradict common sense, neither does the intersection:
</para>
<programlisting>
@@ -560,8 +560,8 @@ cube_inter
</programlisting>
<para>
- In all binary operations on differently-dimensioned cubes, I assume the
- lower-dimensional one to be a Cartesian projection, i. e., having zeroes
+ In all binary operations on differently-dimensioned cubes,
+ the lower-dimensional one is assumed to be a Cartesian projection, i. e., having zeroes
in place of coordinates omitted in the string representation. The above
examples are equivalent to:
</para>
diff --git a/doc/src/sgml/nls.sgml b/doc/src/sgml/nls.sgml
index 5a4387a03f..827e867c67 100644
--- a/doc/src/sgml/nls.sgml
+++ b/doc/src/sgml/nls.sgml
@@ -205,13 +205,16 @@ make update-po
<para>
The PO files can be edited with a regular text editor. There are also
several specialized editors for PO files which can help the process with
- translation specific features. The
- translator should only change the area between the quotes after
- the msgstr directive, add comments, and alter the fuzzy flag.
- There is (unsurprisingly) a PO mode for Emacs, which I find quite
+ translation specific features.
+ There is (unsurprisingly) a PO mode for Emacs, which can be quite
useful.
</para>
+ <para>
+ The translator should only change the area between the quotes after
+ the msgstr directive, add comments, and alter the fuzzy flag.
+ </para>
+
<para>
The PO files need not be completely filled in. The software will
automatically fall back to the original string if no translation
diff --git a/doc/src/sgml/pgcrypto.sgml b/doc/src/sgml/pgcrypto.sgml
index 43fb8dbe66..5316472b96 100644
--- a/doc/src/sgml/pgcrypto.sgml
+++ b/doc/src/sgml/pgcrypto.sgml
@@ -415,8 +415,8 @@ gen_salt(type text [, iter_count integer ]) returns text
<listitem>
<para>
<literal>crypt-bf</literal> numbers are taken using a simple program that
- loops over 1000 8-character passwords. That way I can show the speed
- with different numbers of iterations. For reference: <literal>john
+ loops over 1000 8-character passwords. That way the speed
+ with different numbers of iterations can be shown. For reference: <literal>john
-test</literal> shows 13506 loops/sec for <literal>crypt-bf/5</literal>.
(The very small
difference in results is in accordance with the fact that the
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: First Person being used (only occurs in 2 other places in all of documentation)
2022-10-28 02:44 First Person being used (only occurs in 2 other places in all of documentation) PG Doc comments form <noreply@postgresql.org>
2022-10-28 09:30 ` Re: First Person being used (only occurs in 2 other places in all of documentation) Daniel Gustafsson <daniel@yesql.se>
2022-10-28 10:50 ` Re: First Person being used (only occurs in 2 other places in all of documentation) Daniel Gustafsson <daniel@yesql.se>
@ 2022-12-02 12:56 ` Daniel Gustafsson <daniel@yesql.se>
0 siblings, 0 replies; 4+ messages in thread
From: Daniel Gustafsson @ 2022-12-02 12:56 UTC (permalink / raw)
To: wolakk@gmail.com; pgsql-docs@lists.postgresql.org
> On 28 Oct 2022, at 12:50, Daniel Gustafsson <daniel@yesql.se> wrote:
> The attached patch rewords the first person form sentences to match the rest of
> the documentation. The "acknowledgment" sections are left as-is as I believe
> they are free to have a more personal form.
>
> I also re-arranged the section on PO file editors a bit to keep the PO file
> editor paragraph on editors only and not also contain important translation
> information.
Hearing no objections I've gone ahead and applied this.
--
Daniel Gustafsson https://vmware.com/
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2022-12-02 12:56 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2022-10-28 02:44 First Person being used (only occurs in 2 other places in all of documentation) PG Doc comments form <noreply@postgresql.org>
2022-10-28 09:30 ` Daniel Gustafsson <daniel@yesql.se>
2022-10-28 10:50 ` Daniel Gustafsson <daniel@yesql.se>
2022-12-02 12:56 ` Daniel Gustafsson <daniel@yesql.se>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox