[DOCS] literalinclude: marker-based selection hint - #547
Closed
CybotTM wants to merge 1 commit into
Closed
Conversation
Mentions the partial-inclusion options (`:lines:`, and the more edit-robust `:start-after:`/`:end-before:` markers) and links the underscore naming convention for include-only files. Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
CybotTM
marked this pull request as draft
August 14, 2026 12:47
Contributor
Author
|
Closing after a deeper check: the TYPO3 renderer does not implement literalinclude line selection at all — typo3-docs-theme's LiteralincludeDirective renders the whole file, and phpDocumentor/guides' option mapper knows only language/caption/emphasize-lines/linenos/name. Documenting :lines:/:start-after:/:end-before: here would describe Sphinx behaviour the toolchain does not have — the same class of problem that #490 removed for the :diff: example (render-guides#974). If line selection ever lands in render-guides, this can be revived. |
CybotTM
added a commit
to netresearch/typo3-docs-skill
that referenced
this pull request
Aug 14, 2026
…derer ignores (#80) ## Summary Adds checkpoint TD-51 (severity: warning) that flags literalinclude line-selection options (`:lines:`, `:start-after:`, `:end-before:`, `:start-at:`, `:end-at:`) in `Documentation/` — the TYPO3 renderer (typo3-docs-theme `LiteralincludeDirective` / phpDocumentor guides option mapper) does not implement them; the whole file is rendered and the option is silently ignored. Also adds a matching `[regression]` note to `references/code-structure-elements.md` telling authors to verify any literalinclude option against the renderer source before using or documenting it. Upstream precedent: [TYPO3CMS-Guide-HowToDocument#547](TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#547) (closed after renderer-source check), [#490](TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument#490) / [render-guides#974](TYPO3-Documentation/render-guides#974). ## Came from /retro Session 2026-08-14, finding `retro-20260814-literalinclude-renderer-gap`. ## Calibration Ran the TD-51 grep over all 19 local `t3x-*` extension worktrees with a `Documentation/` directory: it fires in 1 of 19 repos — `t3x-nr-vault` with 5 matches, all genuine `:lines:` options on literalinclude directives (`Usage/ExtensionSettings.rst`, `Usage/ApiEndpointExample.rst` ×2, `Developer/Adr/ADR-009-ExtensionConfigurationSecrets.rst` ×2), i.e. true positives of exactly the defect class the checkpoint targets. The other 18 repos (including t3x-nr-llm, t3x-rte_ckeditor_image, t3x-universal-messenger) fire zero times, so no false-positive noise on clean docs. ## Test plan - `python3 -c "yaml.safe_load(...)"` on `skills/typo3-docs/checkpoints.yaml` — parses clean after the insert. - Byte-compared both inserted blocks against the approved verbatim texts and their anchor positions — exact match. - `pre-commit run --files skills/typo3-docs/checkpoints.yaml skills/typo3-docs/references/code-structure-elements.md` — all hooks pass (yamllint, check yaml, markdownlint-cli2, skill-repo structure validation, whitespace/EOF). - Calibration grep run over 19 local extension repos as described above. https://claude.ai/code/session_012NiLDH3iWw8CVdAnimJbF8
Member
|
Should we open an issue in the phpdocumentor/guides about thisß |
Contributor
Author
|
tried my best:
but I am not feeling lucky they will get through. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Mentions the partial-inclusion options (
:lines:, and the more edit-robust:start-after:/:end-before:markers) and links the underscore naming convention for include-only files.