PHP third-party extensions documentation structure

[jordikroon]

Add initial project structure for PHP third-party extensions documentation.

This currently depends on php/doc-base#335

[alfsb]

On .editorconfig

trim_trailing_whitespace = true

On .gitignore

only temp/

On manual.xml

⟨

[alfsb]

And about the "no translations" in doc-extensions, let me plant an inception. Instead of erasing the files on translations, renames the files from .xml to .old or .ext.

For three effects. In the hope that the translations are considered in future, to document these files were "moved" into doc-extensions, and to avoid any tracking by revcheck.

[alfsb]

On language-snippets.ent

<!--
Language snippets can be placed here. Note that
DTD entities are better converted into XML Entities
and saved as entities.ent in each extension.
-->

[jordikroon]

On language-snippets.ent

<!--
Language snippets can be placed here. Note that
DTD entities are better converted into XML Entities
and saved as entities.ent in each extension.
-->

I have just placed the file here for the time being as a starter, but my suggestion is to do it the right way as we have the opportunity now. So as a policy for doc-extensions, only use XML Entities that live in the entities folder.

[jordikroon]

On .editorconfig

trim_trailing_whitespace = true

On .gitignore

only temp/

On manual.xml

⟨

Can you elaborate on this? These changes reflect what is currently in doc-en.
Regarding the trim_trailing_whitespace, which you suggest to change to true. There has been a discussion about it a few years ago. So I am not sure if we should change it back to false here. I much prefer to be aligned on standards with doc-en.

php/doc-en#1655

[alfsb]

Can you elaborate on this?

Sure.

trim_trailing_whitespace to true as to:

• avoid adding cruft
• there are no translations to be afflicted with automatic changes.

On .giitignore, having only temp, and no temporary file created outside it, to avoid this manual becoming not idempotent, as doc-en/doc-base was before.

On manual.xml, replacing the LANG with "en", but I see the change on configure was reverted, so this point is now moot. I have some plans to remove this particular entity in future.

These changes reflect what is currently in doc-en. Regarding the trim_trailing_whitespace, which you suggest to change to true. There has been a discussion about it a few years ago. So I am not sure if we should change it back to false here.I much prefer to be aligned on standards with doc-en.

php/doc-en#1655

From the referenced issues, we have:

And fixing those trailing whitespace isn't a bad idea, but that should be done in a separate PR, so we can apply [skip-revcheck] so that translators don't have to bother with it.

doc-extensions has no translations, so the skip-revcheck point is moot. The only point that rests is fixing trailing whitespace, and avoiding that any more slips in.

[jordikroon]

@alfsb I made the changes you suggested.

The output folder is still required to be in the gitignore, and I prefer to leave that one as it is in order to distinguish between something that could be considered garbage and the final output.
Other files have been moved out of the gitignore.

[jordikroon]

Planning to merge this later today, we can iterate on top of that.

[lacatoire]

Looks good, the foundation is in place. One thing worth fixing, in integrate.yaml.

The "Checkout php/doc-en as fallback" step comes from doc-en, where it clones php/doc-en into en/. Here the matrix substitution turned it into a clone of php/doc-extensions into extensions/, the same repository into the same path as the step above, and without a ref it lands on the default branch. So it overwrites the PR checkout with main. Once php/doc-base#335 is in and this job can actually run, it would go green having built main rather than the pull request. A standalone manual has no doc-en fallback to make anyway, so the step can just go.

Also note the job stays red until php/doc-base#335 lands, as --with-base-lang only exists there. The lint workflow is fine, it checks out the PR head as it should.

The rest can follow later: language-snippets.ent is still empty, which the migrated extension pages will need, and .editorconfig still only covers *.xml while .gitattributes treats .ent as XML.