Skip to content

Nits: incomplete and broken sentences#5583

Open
lacatoire wants to merge 1 commit into
php:masterfrom
lacatoire:fix/broken-sentences
Open

Nits: incomplete and broken sentences#5583
lacatoire wants to merge 1 commit into
php:masterfrom
lacatoire:fix/broken-sentences

Conversation

@lacatoire
Copy link
Copy Markdown
Member

@lacatoire lacatoire commented May 25, 2026

Fixes a batch of incomplete or broken sentences (missing words or verbs, fragments) spotted while comparing the English and French manuals.

Each change is a minimal grammar fix that preserves the original meaning. The inline-only paragraphs touched by these fixes are switched from para to simpara. A few sibling files carrying the identical broken sentence are included for consistency (array_all/array_find/array_find_key, Ds\Deque::allocate).

@lacatoire lacatoire requested a review from kamil-tekiela as a code owner May 25, 2026 15:27
@lacatoire lacatoire force-pushed the fix/broken-sentences branch from 9365f5b to 200a68b Compare May 25, 2026 15:30
Comment thread reference/com/constants.xml Outdated
Comment thread reference/cubrid/functions/cubrid-prepare.xml Outdated
Comment thread reference/cubrid/functions/cubrid-prepare.xml Outdated
Comment thread reference/cubrid/functions/cubrid-prepare.xml Outdated
Comment thread reference/cubrid/functions/cubrid-prepare.xml Outdated
Comment thread reference/sockets/functions/socket-create-listen.xml Outdated
@kamil-tekiela
Copy link
Copy Markdown
Member

I think the cubrid_prepare changes should have been made in a separate PR.

@lacatoire lacatoire force-pushed the fix/broken-sentences branch from aeca180 to 8c3e4fc Compare May 25, 2026 18:38
@jordikroon
Copy link
Copy Markdown
Member

I am a little bit hesitant towards this since this will give a lot of unnecessary conflicts to currently open merge requests. I would prefer to stick to the standard extensions that are in our direct control and leave the third party extensions as it is so far.

A good example is #5493 that already contains 6 conflicts while we are waiting for the author to handle feedback. Merging this will make it even worse and it just doesn't improve much.

Instead I prefer we focus on the missing PHP 8.4 and PHP 8.5 issues that are not implemented yet. If we however go for this approach, I want to be absolutely sure that there are no major MR's open for the given extension.

@kamil-tekiela
Copy link
Copy Markdown
Member

I am a little bit hesitant towards this since this will give a lot of unnecessary conflicts to currently open merge requests. I would prefer to stick to the standard extensions that are in our direct control and leave the third party extensions as it is so far.

A good example is #5493 that already contains 6 conflicts while we are waiting for the author to handle feedback. Merging this will make it even worse and it just doesn't improve much.

Instead I prefer we focus on the missing PHP 8.4 and PHP 8.5 issues that are not implemented yet. If we however go for this approach, I want to be absolutely sure that there are no major MR's open for the given extension.

I understand the concern, but this PR is relatively simple. This is why I said that cubrid_prepare doesn't belong here. The rest is just typo-type fixes.

Merge conflicts will happen no matter what. This is just the nature of Git. What makes reviewing difficult is not that; it's the 10000 changed lines in a single PR. Reviewing just a 100 is already burdensome, and I doubt any one of us can review a PR that changes the whole extension manual in one go.

On the topic of non-standard extensions, I don't like the fact that we even have them included in the PHP manual. What even is the criteria that determines whether the documentation for an extension is included or not? Including them in doc-en makes it our responsibility to care for quality and fix issues (the reported issues do not go to the maintainers, but are clustered with all other issues here). And it makes it difficult for us to fact-check or even understand how things work. The manual pages for these extensions already lack a lot of information. If we ignore them, then the problem only becomes worse and they remain in no-man's-land-care-area.

So I say merge this PR, and either wait for the author of the other mega-PR to fix merge conflicts quickly or just decline the other PR and ask them to submit smaller ones.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants