Skip to content

gdscript highlighting and packaging #3024

Open
DavidCooperWCU wants to merge 15 commits into
PreTeXtBook:masterfrom
DavidCooperWCU:gdscript-lang
Open

gdscript highlighting and packaging #3024
DavidCooperWCU wants to merge 15 commits into
PreTeXtBook:masterfrom
DavidCooperWCU:gdscript-lang

Conversation

@DavidCooperWCU

Copy link
Copy Markdown

A new prism format was added for gdscript 2.0
A new component was added to generate gdscript packs as zip files The documentation was updated to describe the new gdscript highlighting and active code capabilities 1 program example and 3 activecode examples were added to the Runestone Testing section of the sample book.

@DavidCooperWCU

Copy link
Copy Markdown
Author

To test this:

  1. checkout the pr with gh pr checkout 3024
  2. cd examples/sample-book
  3. mkdir out-test
  4. python ../../pretext/pretext -vvv -d out-test -f html -c all -p publication-structural.xml sample-book.xml
  5. mkdir out-test/generated/gdscript
  6. python ../../pretext/pretext -vvv -d out-test/generated/gdscript -f html -c gdscript -p publication-structural.xml sample-book.xml

Then serve the book and look at Listing 5.1.3 to see the godot highlighting.

Activities 5.2.1, 5.2.2, and 5.2.3 are examples how the ActiveCode will look, but it won't work fully until rs - PR 1233 has been accepted.

This is a circular dependency, but this PR is the first step.

1. gdscript-prism.js does gdscript 2.0 highlighting for code in programs
2. pretext-html.xsl and pretext-runestone.xsl were modified for the highlighting
3. gdscript_pck function in pretext.py uses extract-gdscript.xsl, and godot_helper.py to build godot packs in zip
   format as generated files.
1 noninteractive example in the programs section
3 activecode examples in the activecode section, and 2 noninteractive programs in one of the activities
as part of an activecode example.
@DavidCooperWCU

Copy link
Copy Markdown
Author

@rbeezer I worked with @ascholerChemeketa to make sure that things were working properly without the pretext cli, and I made some additional changes based on reviews by @oscarlevin

I think it's ready for you to review.

@rbeezer

rbeezer commented Jul 16, 2026

Copy link
Copy Markdown
Collaborator

This is the resubmission of #2892 (closed in favor of this PR, and described here as cleaned up). Before a detailed pass, the PR needs to meet conventions that were already stated explicitly in the #2892 review. A number of them recur unchanged, and several new ones appear. The consistent issue is code that does not follow PreTeXt's established conventions.

Raised on #2892, still present here

  • f-strings. GDScript code highlighting #2892: "We like to use .format(), not 'f-strings'." godot_helper.py still contains log.info(f"Export templates for {GODOT_VERSION} already installed at {template_dir}.") — the only f-string in a file that otherwise uses .format().
  • log.error for normal output. GDScript code highlighting #2892: "log.debug/log.info are used for progress, not log.error." gd_pack calls log.error(result.stderr) on the success branches of both the trial and export runs (returncode == 0). Godot writes to stderr routinely, so successful builds will report errors.
  • Dead commented code and trailing whitespace. GDScript code highlighting #2892: "Remove the dead commented line … (and its trailing whitespace)." This PR still ships commented-out code — #_, external_dir = common.get_managed_directories(...) in gdscript_pck, and a commented-out template match in extract-gdscript.xsl — and adds trailing whitespace on many lines.
  • .gitignore to suppress stray files. GDScript code highlighting #2892: ".DSStore … should not be precluded by .gitignore, it is up to an author … to clean up that sort of stuff before it becomes part of source." This PR adds examples/sample-book/gdpractice/.gitignore containing *.uid, *.import, .godot — the same pattern that was asked against.
  • XSL formatting in pretext-runestone.xsl. GDScript code highlighting #2892 itemized "stray blank lines and inconsistent indentation inside <xsl:attribute>" and "leftover commented-out lines." The data-wasm/data-pck/data-scene construction here still has inconsistent indentation and stray blank lines.

New convention problems in this submission

  • Tabs. godot_helper.py is indented with tabs throughout (111 lines); the codebase uses four spaces. gd_pack additionally mixes in three-space indentation.
  • A committed empty file: …/L2.P9.visual_2d/practices/L2.P9.visual_2d_input_motion/practice.gd is 0 bytes.
  • A committed binary blob: …/first_script/project.binary (binary "blobs make my ears prick up" was already noted on GDScript code highlighting #2892).
  • Stale copied comments. extract-gdscript.xsl's header says it "prepares a Python dictionary" and refers to a "YouTube ID … comma-separated pair," but it emits a comma-separated triple; pretext.py carries "# no format … (*.jpg)". Typos: "providews", "activcode".
  • Grammar in the Guide: "GDScript has it's own way" → "its".

Correctness and substance

  • Cleanup bug in gd_pack. In the finally block, the project-file removal is guarded by config_already_existed where it must be project_already_existed. As written, a pre-existing project.godot may not be restored, or the template copy may be left behind in the author's source.
  • New attributes are not in the schema. @pck and @scene on <program> are used by the XSL and Python, but <program> has a closed attribute list, so documents using them do not validate. The schema source needs these attributes added. (Deriving the schema files is a maintainer step — no need to touch the generated files.)
  • The Godot version is pinned in two places$godot.version in pretext-runestone.xsl and GODOT_VERSION in godot_helper.py — which can drift.
  • gd_pack writes into the author's source directory (project.godot, export_presets.cfg) and relies on best-effort restoration in finally; an interrupted run leaves the source tree modified. Work from a temporary copy instead.
  • New third-party dependency. godot_helper.py imports certifi; the toolchain is standard-library only. And the download-and-run of the Godot engine/templates carries no integrity check — both are design questions to settle (the pretext-dev thread is the place for that) before code review continues.

For the next round: bring the Python and XSL into line with the conventions already given on #2892 (four-space indentation, .format(), log.info/log.debug for progress, no commented-out code, no trailing whitespace, no .gitignore/binary/empty files in the examples), fix the cleanup bug, and add the schema entries. The build behavior (source-tree mutation, engine download) should be resolved on the dev list.

Claude Opus 4.8, acting as a review assistant for Rob Beezer

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.

2 participants