Bug 38785 - Punctuation inconsistencies in system preference descriptions
Summary: Punctuation inconsistencies in system preference descriptions
Status: Pushed to main
Alias: None
Product: Koha
Classification: Unclassified
Component: Templates (show other bugs)
Version: Main
Hardware: All All
: P5 - low normal
Assignee: Tomás Cohen Arazi (tcohen)
QA Contact: Katrin Fischer
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2024-12-26 17:51 UTC by Tomás Cohen Arazi (tcohen)
Modified: 2024-12-30 11:12 UTC (History)
4 users (show)

See Also:
Change sponsored?: ---
Patch complexity: String patch
Documentation contact:
Documentation submission:
Text to go in the release notes:
This fixes some punctuation inconsistencies for system preference descriptions, identified during translation. This includes: - missing full stops at the end of complete sentences - incorrect placement of full stops (for example, after each option value, instead of after the option selection box) - minor wording changes (for example, Opac to OPAC)
Version(s) released in:
25.05.00
Circulation function:


Attachments
Bug 38785: Punctuation inconsistencies in preferences descriptions (43.12 KB, patch)
2024-12-26 17:58 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 38785: Punctuation inconsistencies in preferences descriptions (41.55 KB, patch)
2024-12-27 11:00 UTC, Tomás Cohen Arazi (tcohen)
Details | Diff | Splinter Review
Bug 38785: Punctuation inconsistencies in preferences descriptions (41.67 KB, patch)
2024-12-27 21:12 UTC, David Nind
Details | Diff | Splinter Review
Bug 38785: Punctuation inconsistencies in preferences descriptions (41.67 KB, patch)
2024-12-27 21:16 UTC, David Nind
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Tomás Cohen Arazi (tcohen) 2024-12-26 17:51:23 UTC
While translating, I found a handful of inconsistencies in punctuation.
Comment 1 Tomás Cohen Arazi (tcohen) 2024-12-26 17:58:46 UTC
Created attachment 175945 [details] [review]
Bug 38785: Punctuation inconsistencies in preferences descriptions

This patch fixes some inconsistencies I noticed during translation. Most
of them are punctuation related.

To test:
1. Apply this patch
2. Check all the changed places and notice things display nicely on the
   `System preferences` UI.
3. Sign off :-D
Comment 2 Tomás Cohen Arazi (tcohen) 2024-12-26 18:14:54 UTC
Ok, this are my two cents. There are some cases like:

```
Use CAS for login authentication: [Yes/No]
```

that are not aligned with the more common use case:

```
[Enable/Don't] enable CAS for login authentication.
```

That deserves some discussion.
Comment 3 David Nind 2024-12-27 00:11:12 UTC
Thank you for taking the time to look at this Tomás!

I've noticed a lot of inconsistencies creeping in lately, but haven't got around to creating a bug to fix them.

I'll go through and review the changes properly tomorrow (for me).

Sentences in parentheses
------------------------

One thing I noticed after a quick review of the changes is that for complete standalone sentences in parentheses, the full stop should be inside the ending bracket, not outside.

For example:

- This change is correct - it should have a full stop, and it should be at the end of the sentence after the bracket: Automatic generation also has to be enabled for each credit type (<a href="/cgi-bin/koha/admin/credit_types.pl">Configure credit types</a>).

- This change is not correct - it should have a full stop, but as it is a complete sentence the full stop should go before the closing bracket .): (This is the default From: address for emails unless there is one for the particular library, and is referred to when an internal error occurs).

Reference: https://www.grammarly.com/blog/punctuation-capitalization/parentheses-and-brackets/

Enable/Don't enable vs Yes/No
-----------------------------

I agree with this change for consistency - it should be one or the other. Katrin and Caroline made a lot of changes a few years ago to standardise on Enable/Don't enable, or maybe it was Show/Don't show (I can't find the bug).

(The other pet peeve I have is when the system preference name includes enable or use, for example UseCashRegisters and EnablePointOfSale. I think the system preference name should describe the feature, and turning it on or off should an option for the system preference.)

Other things
------------

I think we should add any of these things that are inconsistent to the terminology list https://wiki.koha-community.org/wiki/Terminology - we added show/don't show vs display/don't display a while ago.

We should also probably cover some of the "rules" about naming system preferences (after agreement) in https://wiki.koha-community.org/wiki/System_Preferences

The documentation team has adopted the Google developer documentation style guide as our base style guide - once I've created an editable version of this for the documentation team, we can add our exceptions and specific rules to that as well.

(English grammar is hard, even for native speakers!)
Comment 4 David Nind 2024-12-27 00:16:31 UTC
Changing to a bug, instead of an enhancement - grammatical errors and other inconsistencies are "bugs" in my view!
Comment 5 Tomás Cohen Arazi (tcohen) 2024-12-27 10:45:41 UTC
Thanks for the feedback!

(In reply to David Nind from comment #3)
> Thank you for taking the time to look at this Tomás!
> 
> I've noticed a lot of inconsistencies creeping in lately, but haven't got
> around to creating a bug to fix them.
> 
> I'll go through and review the changes properly tomorrow (for me).
> 
> Sentences in parentheses
> ------------------------
> 
> One thing I noticed after a quick review of the changes is that for complete
> standalone sentences in parentheses, the full stop should be inside the
> ending bracket, not outside.

I really didn't understand the need for parenthesis there. But I agree: if the parenthesis is kept, the full stop should be inside of the parenthesis.

> (English grammar is hard, even for native speakers!)

I agree with all the things you said, including the above comment.

I will amend the patch with your suggestion to move full stops inside the parenthesis, and leave the next ones to more expert eyes for now. I just focused on what bugged me on translating.
Comment 6 Tomás Cohen Arazi (tcohen) 2024-12-27 11:00:53 UTC
Created attachment 175953 [details] [review]
Bug 38785: Punctuation inconsistencies in preferences descriptions

This patch fixes some inconsistencies I noticed during translation. Most
of them are punctuation related.

To test:
1. Apply this patch
2. Check all the changed places and notice things display nicely on the
   `System preferences` UI.
3. Sign off :-D
Comment 7 David Nind 2024-12-27 21:12:07 UTC Comment hidden (obsolete)
Comment 8 David Nind 2024-12-27 21:16:43 UTC
Created attachment 175966 [details] [review]
Bug 38785: Punctuation inconsistencies in preferences descriptions

This patch fixes some inconsistencies I noticed during translation. Most
of them are punctuation related.

To test:
1. Apply this patch
2. Check all the changed places and notice things display nicely on the
   `System preferences` UI.
3. Sign off :-D

Signed-off-by: David Nind <david@davidnind.com>
Comment 9 David Nind 2024-12-27 21:30:40 UTC
Thanks Tomás.

All the changes look great to me!

I made two minor changes and amended the patch - I changed "here" links:
- ElasticsearchCrossFields: ... See the [Elasticsearch cross_fields documentation].
- LibrisKey: ... [from LIBRIS].

Rationale: The web accessibility guidelines are that link text should be meaningful, not just "here". Screen readers read out all the links, so hearing "Here" multiple times is not very useful - you want to know where the link will take you.

David
Comment 10 Tomás Cohen Arazi (tcohen) 2024-12-27 21:39:09 UTC
(In reply to David Nind from comment #9)
> Rationale: The web accessibility guidelines are that link text should be
> meaningful, not just "here". Screen readers read out all the links, so
> hearing "Here" multiple times is not very useful - you want to know where
> the link will take you.

Thanks, David! I'll keep learning forever :-D
Comment 11 Katrin Fischer 2024-12-30 10:42:08 UTC
This type of patch makes me all warm and happy (must be the librarian side) :)
Comment 12 Katrin Fischer 2024-12-30 11:10:26 UTC
Pushed for 25.05!

Well done everyone, thank you!