Update template

.github/copilot-instructions.md

@@ -2,46 +2,64 @@
 applyTo: "**.typ"
 ---
 
-# GitHub Copilot Instructions for Template
+# GitHub Copilot Instructions for Academic Notes
 
 ## Project Context
 
-This repository contains academic notes and materials for the Template course, written in Typst format.
+This repository contains academic course notes written in Typst, using the [typst-notes-template](https://github.com/Favo02/typst-notes-template).
+All custom functions and packages are made available via `#import "template.typ": *` (or a similar relative import) in each file.
 
 ## Review Focus Areas
 
 ### 1. Typst Syntax
 
 - You are not up to date with the Typst compiler, so if you find anything weird or uncommon, triple check before suggesting an edit
-- The project uses specific external packages that are already imported: `gentle-clues`, `equate`, `codly`, `fletcher`, `cetz`, and `cetz-venn`
-- Do NOT suggest importing NEW Typst external packages beyond those already in use
+- All external packages (`gentle-clues`, `equate`, `codly`, `fletcher`, `cetz`, `cetz-venn`, `lovelace`, `pinit`) are already available through the template import - do NOT suggest importing them directly in note files
+- Do NOT suggest importing NEW Typst external packages beyond those already provided by the template
 - It is guaranteed that the code compiles into a valid PDF document
 
 ### 2. Template Consistency
 
-- Ensure consistent use of custom helper functions: `nota`, `attenzione`, `informalmente`, `dimostrazione`, `teorema`, and `esempio`
-- Check proper application of the document template and styling
+- Ensure consistent use of custom info box functions (English names): `note`, `warning`, `informally`, `example`, `proof`, and `theorem`
+  - All accept an optional `title:` named argument to override the default title
+- Check proper application of the `academic-notes` template function and its parameters
+- The template supports bilingual output via `lang: "en"` or `lang: "it"` in `academic-notes`; individual label overrides are available as optional named parameters
 - Check proper use of inline math `$...$` and display math `$ ... $`
-- Ensure consistent use of colored math helpers: `mg` (olive), `mm` (maroon), `mo` (orange), `mr` (red), `mp` (purple), `mb` (blue)
+- Ensure consistent use of colored math helpers: `mg` (green), `mm` (maroon), `mo` (orange), `mr` (red), `mp` (purple), `mb` (blue)
+- Also check use of `comment()` for small inline comments inside equations
 - Verify proper use of diagram creation tools (`fletcher`, `cetz`, `cetz-venn`) for visual elements
-- Check consistent formatting of definition lists using `/` notation
-- Check that TODO comments are properly formatted and tracked
+- Check consistent formatting of definition lists using `/` notation (`:` is the separator set by the template)
+- Check that incomplete sections are marked with `#todo` (not any other pattern)
+- Verify proper use of cross-reference helpers: `link-section()`, `link-theorem()`, `link-equation()`
+- Check proper use of `part()` for major document divisions (numbered with Roman numerals)
+- Verify pseudocode is written using `pseudocode()` and `indent()` from the `lovelace` package
 
 ### 3. Content Clarity
 
-- Italian Language: Check for proper Italian grammar and academic writing style
+- Language: Check for proper grammar and academic writing style matching the `lang` setting (`"en"` or `"it"`)
 - Explanations: Ensure complex concepts are explained clearly and progressively
 - Examples: Verify that examples effectively illustrate the concepts
 - Mathematical Accuracy: Verify mathematical formulas, algorithms, and proofs for correctness
 - Algorithmic Descriptions: Check that algorithm descriptions are clear, complete, and accurate
 - Complexity Analysis: Ensure Big O, Omega, and Theta notations are used correctly
-- Terminology: Verify proper use of computer science and algorithmic terminology in Italian
+- Terminology: Verify proper use of computer science and algorithmic terminology in the document's language
 
-### 4. Code Examples and Pseudocode
+### 4. Diagrams and Drawings
+
+Choose the right abstraction level for each drawing task - neither always high-level nor always low-level:
+
+- Prefer package-level abstractions when they match the concept: use `fletcher` nodes and edges for graphs, automata, and flowcharts; use `cetz-venn` for Venn diagrams. These map naturally to the concept and produce cleaner code.
+- Fall back to `cetz` primitives for custom or geometric drawings: lines, rectangles, circles, arcs, and labels via `cetz.draw` are reliable and well-understood - use them for diagrams that don't fit a higher-level abstraction (e.g., geometric proofs, custom data structure illustrations).
+- Avoid reinventing what packages already provide: do not draw a graph by manually placing circles and lines with `cetz` if `fletcher` can express the same thing with nodes and edges.
+- Avoid over-relying on high-level API details you are uncertain about: `fletcher` and `cetz-venn` have specific APIs that may be mis-recalled - when in doubt, fall back to `cetz` primitives rather than guessing high-level parameters.
+- Mixed use is fine: it is acceptable to combine `fletcher` for the graph structure and `cetz` for additional annotations in the same diagram.
+
+### 5. Code Examples and Pseudocode
 
 - Review algorithm implementations for correctness
 - Check that code examples follow good programming practices
-- Verify syntax highlighting and code formatting using codly
+- Verify syntax highlighting and code formatting using `codly`
+- Ensure pseudocode uses `pseudocode()` and `indent()` from `lovelace`, not ad-hoc formatting
 - Ensure code examples match the theoretical explanations
 
 ## Specific Review Guidelines
@@ -53,30 +71,32 @@ This repository contains academic notes and materials for the Template course, w
 3. Suggest improvements for clarity and educational value
 4. Check for consistency with existing content style
 5. Do not suggest importing new Typst packages or features
-6. Pay attention to TODO comments and incomplete sections marked by the `appunti` separator
+6. Pay attention to `#todo` markers indicating incomplete or unverified sections
 
 ### Content Review Priorities:
 
 1. **Mathematical Accuracy**: Verify all formulas, proofs, and complexity analysis
 2. **Educational Flow**: Ensure concepts build logically and examples support theory
-3. **Italian Grammar**: Check for proper academic Italian language usage
+3. **Language Grammar**: Check for proper academic language usage matching the `lang` setting
 4. **Template Consistency**: Verify proper use of all custom helper functions and styling
 5. **Visual Elements**: Check that diagrams and mathematical formatting enhance understanding
 
 ### Common Patterns to Watch:
 
 - Proper use of `$` for inline math and `$ ... $` for display math
-- Consistent use of colored math helpers: `mg()`, `mm()`, `mo()`, `mr()`, `mp()`, `mb()`
-- Correct application of info boxes: `nota()`, `attenzione()`, `informalmente()`, `esempio()`, `dimostrazione()`, `teorema()`
-- Proper Italian academic terminology for computer science concepts
+- Consistent use of colored math helpers: `mg()`, `mm()`, `mo()`, `mr()`, `mp()`, `mb()`, `comment()`
+- Correct application of info boxes: `note()`, `warning()`, `informally()`, `example()`, `proof()`, `theorem()`
 - Consistent use of definition lists with `/` separator for terminology sections
-- Proper formatting of algorithms and pseudocode using `codly`
-- Appropriate use of diagram tools (`fletcher`, `cetz`, `cetz-venn`) for visual representations
+- Proper formatting of pseudocode using `lovelace`: `pseudocode()` and `indent()`
+- Proper formatting of highlighted code using `codly`
+- Appropriate use of diagram tools: `fletcher` for graphs/automata/flowcharts, `cetz-venn` for Venn diagrams, `cetz` primitives for custom geometric drawings - balanced between high-level APIs and low-level directives (see section 4)
+- Cross-references using `link-section()`, `link-theorem()`, `link-equation()`
+- Use of `#todo` to flag incomplete sections
 
 ## Interaction Style
 
 - Suggest improvements for complex errors
 - Simply point out minor issues (like typos) without extensive explanations
-- Consider the academic context and Italian language requirements
-- When reviewing TODO sections, provide constructive guidance on completion
+- Consider the academic context and the document's language requirements
+- When reviewing `#todo` sections, provide constructive guidance on completion
 - Respect the established template structure and don't suggest major architectural changes

.github/workflows/pr-pdf-comment.yml

@@ -12,56 +12,79 @@ jobs:
     permissions:
       contents: read
       pull-requests: write
+      actions: read
 
     steps:
-    - name: Announce PDF artifact on PR
-      uses: actions/github-script@v7
-      with:
-        script: |
-          const run = context.payload.workflow_run
-          const pr = run.pull_requests && run.pull_requests[0]
-
-          if (!pr) {
-            core.warning('No pull request associated with the workflow run; skipping comment.')
-            return
-          }
-
-          const owner = context.repo.owner
-          const repo = context.repo.repo
-          const runId = run.id
-          const workflowUrl = run.html_url || `${context.payload.repository.html_url}/actions/runs/${runId}`
-          const expectedName = `pr-${pr.number}-preview`
-
-          const artifactsResponse = await github.rest.actions.listWorkflowRunArtifacts({
-            owner,
-            repo,
-            run_id: runId,
-          })
-
-          const artifact = artifactsResponse.data.artifacts.find(a => a.name === expectedName)
-
-          if (!artifact) {
-            core.warning(`Artifact ${expectedName} not found on run ${runId}; skipping comment.`)
-            return
-          }
-
-          const body = `
-          📄 **Anteprima PDF disponibile**
-
-          L'ultima compilazione è stata eseguita sul commit \`${run.head_sha.substring(0, 7)}\`.
-
-          **📥 Per scaricare il PDF:**
-          1. [Apri il workflow run](${workflowUrl})
-          2. Vai alla sezione **Artifacts**
-          3. Scarica \`${expectedName}\`
-
-          L'artifact resta disponibile per 30 giorni.
-          `
-
-          await github.rest.issues.createComment({
-            owner,
-            repo,
-            issue_number: pr.number,
-            body,
-          })
-          core.info(`Created new comment on PR #${pr.number}`)
+      - name: Announce PDF artifact on PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const run = context.payload.workflow_run
+            const pr = run.pull_requests && run.pull_requests[0]
+
+            if (!pr) {
+              core.warning('No pull request associated with the workflow run; skipping comment.')
+              return
+            }
+
+            const owner = context.repo.owner
+            const repo = context.repo.repo
+            const runId = run.id
+            const shortSha = run.head_sha.substring(0, 7)
+            const workflowUrl = run.html_url || `${context.payload.repository.html_url}/actions/runs/${runId}`
+            const expectedName = `pr-${pr.number}-preview`
+            const marker = `<!-- pdf-preview-bot pr-${pr.number} -->`
+
+            const artifactsResponse = await github.rest.actions.listWorkflowRunArtifacts({
+              owner,
+              repo,
+              run_id: runId,
+            })
+
+            const artifact = artifactsResponse.data.artifacts.find(a => a.name === expectedName)
+
+            if (!artifact) {
+              core.warning(`Artifact ${expectedName} not found on run ${runId}; skipping comment.`)
+              return
+            }
+
+            const body = `${marker}
+            📄 **PDF Preview available**
+
+            Latest build ran on commit \`${shortSha}\`.
+
+            **📥 To download the PDF:**
+            1. [Open the workflow run](${workflowUrl})
+            2. Go to the **Artifacts** section
+            3. Download \`${expectedName}\`
+
+            The artifact is available for 30 days.`
+
+            const existingComments = await github.rest.issues.listComments({
+              owner,
+              repo,
+              issue_number: pr.number,
+            })
+
+            const existing = existingComments.data.find(c => c.body && c.body.includes(marker))
+
+            if (existing) {
+              try {
+                await github.rest.issues.deleteComment({
+                  owner,
+                  repo,
+                  comment_id: existing.id,
+                })
+                core.info(`Deleted previous comment on PR #${pr.number}`)
+              } catch (e) {
+                core.warning(`Could not delete previous comment: ${e.message}`)
+              }
+            }
+
+            await github.rest.issues.createComment({
+              owner,
+              repo,
+              issue_number: pr.number,
+              body,
+            })
+            core.info(`Created new comment on PR #${pr.number}`)

.github/workflows/pr-pdf-preview.yml

@@ -3,9 +3,9 @@ name: PR PDF Preview
 on:
   pull_request:
     types: [opened, synchronize, reopened, ready_for_review]
-    branches: [ main ]
+    branches: [main]
     paths:
-      - '**.typ'
+      - "**.typ"
 
 jobs:
   generate-pdf:
@@ -16,21 +16,21 @@ jobs:
       pull-requests: read
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-      with:
-        ref: ${{ github.event.pull_request.head.sha }}
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
 
-    - name: Setup Typst
-      uses: typst-community/setup-typst@v3
+      - name: Setup Typst
+        uses: typst-community/setup-typst@v3
 
-    - name: Compile Typst document
-      run: |
-        typst compile main.typ template-preview.pdf
+      - name: Compile Typst document
+        run: |
+          typst compile main.typ ${{ github.event.repository.name }}-preview.pdf
 
-    - name: Upload PDF as artifact
-      uses: actions/upload-artifact@v4
-      with:
-        name: pr-${{ github.event.pull_request.number }}-preview
-        path: template-preview.pdf
-        retention-days: 30
+      - name: Upload PDF as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: pr-${{ github.event.pull_request.number }}-preview
+          path: ${{ github.event.repository.name }}-preview.pdf
+          retention-days: 30

.github/workflows/release-pdf.yml

@@ -2,9 +2,9 @@ name: Create Release with compiled PDF
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
     paths:
-      - '**.typ'
+      - "**.typ"
 
 jobs:
   create-release:
@@ -13,43 +13,45 @@ jobs:
       contents: write
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v4
-
-    - name: Setup Typst
-      uses: typst-community/setup-typst@v3
-
-    - name: Compile Typst document
-      run: |
-        typst compile main.typ template.pdf
-
-    - name: Upload PDF as artifact
-      uses: actions/upload-artifact@v4
-      with:
-        name: template-pdf-release
-        path: template.pdf
-        retention-days: 90
-
-    - name: Get current date
-      id: date
-      run: echo "date=$(date +'%d/%m/%Y')" >> $GITHUB_OUTPUT
-
-    - name: Create Release with PDF
-      uses: softprops/action-gh-release@v2
-      with:
-        tag_name: release-${{ github.sha }}
-        name: Compiled PDF ${{ steps.date.outputs.date }} (${{ github.sha }})
-        body: |
-          🎓 **Template - PDF ${{ steps.date.outputs.date }} (${{ github.sha }})**
-
-          Automated release created from main branch with the latest version of the course notes.
-
-          **Release Details:**
-          - Generated from commit: ${{ github.sha }}
-          - Build date: ${{ steps.date.outputs.date }}
-          - PDF compiled with latest Typst version
-
-          **Download:** The PDF is attached to this release as `template.pdf`
-        files: template.pdf
-        draft: false
-        prerelease: false
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Typst
+        uses: typst-community/setup-typst@v3
+
+      - name: Compile Typst document
+        run: |
+          typst compile main.typ ${{ github.event.repository.name }}.pdf
+
+      - name: Upload PDF as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ github.event.repository.name }}-release
+          path: ${{ github.event.repository.name }}.pdf
+          retention-days: 90
+
+      - name: Get current date and short SHA
+        id: meta
+        run: |
+          echo "date=$(date +'%d/%m/%Y')" >> $GITHUB_OUTPUT
+          echo "sha=${GITHUB_SHA::7}" >> $GITHUB_OUTPUT
+
+      - name: Create Release with PDF
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: release-${{ steps.meta.outputs.sha }}
+          name: Compiled PDF ${{ steps.meta.outputs.date }} (${{ steps.meta.outputs.sha }})
+          body: |
+            🎓 **${{ github.event.repository.name }} - PDF ${{ steps.meta.outputs.date }} (${{ steps.meta.outputs.sha }})**
+
+            Automated release created from main branch with the latest version of the course notes.
+
+            **Release Details:**
+            - Generated from commit: ${{ steps.meta.outputs.sha }}
+            - Build date: ${{ steps.meta.outputs.date }}
+            - PDF compiled with latest Typst version
+
+            **Download:** The PDF is attached to this release as `${{ github.event.repository.name }}.pdf`
+          files: ${{ github.event.repository.name }}.pdf
+          draft: false
+          prerelease: false