From 37ba4834f714bf98742cb090674fae2fe6115663 Mon Sep 17 00:00:00 2001 From: Maggie Linden <150281935+maggielinden@users.noreply.github.com> Date: Tue, 7 Apr 2026 15:30:04 -0700 Subject: [PATCH] Sidebar & misc .md link updates Updates to reflect changes in directory names (generate-docs.js and astro.config.mjs) while being mindful of astro component names (SLuaEvents.astro, etc). Ideally, publicly visible labels should show Lua, even if backend functions currently retain the older names. Also updated CLAUDE.md, taxonomy.md & CONTRIBUTING.md for SLua terms & links. --- CLAUDE.md | 42 ++++++++++++++++++++-------------------- CONTRIBUTING.md | 16 +++++++-------- astro.config.mjs | 8 ++++---- scripts/generate-docs.js | 14 +++++++------- taxonomy.md | 42 ++++++++++++++++++++-------------------- 5 files changed, 61 insertions(+), 61 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d598179..acddd72 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,7 @@ All commands use pnpm: - `pnpm build` - Build production site to ./dist/ - `pnpm preview` - Preview production build locally - `pnpm astro check` - Run TypeScript type checking -- `pnpm generate:docs` - Generate all reference pages (functions, events, and constants) for both LSL and SLua from src/definitions/lsl_definitions.yaml +- `pnpm generate:docs` - Generate all reference pages (functions, events, and constants) for both LSL and Lua from src/definitions/lsl_definitions.yaml ## Architecture @@ -30,8 +30,8 @@ Documentation lives in `src/content/docs/` with two main areas: **script/** - Scripting documentation (primary focus: LSL portal) - `script/guides/` - Scripting guides - `script/lsl-reference/` - LSL language reference -- `script/slua-reference/` - SLua reference -- `script/learn-slua/` - SLua learning materials +- `script/lua-reference/` - Lua reference +- `script/learn-lua/` - Lua learning materials Files are `.md` or `.mdx` format. Routes auto-generate from file paths (e.g., `docs/script/lsl-reference/example.md` → `/script/lsl-reference/example/`). @@ -71,13 +71,13 @@ All documentation should use a balanced and pragmatic tone that: - Use "you" to address the reader directly - Be clear and precise without being overly formal - Explain the "why" behind concepts, not just the "what" -- Anticipate common confusion points (especially for LSL-to-SLua migration) +- Anticipate common confusion points (especially for LSL-to-Lua migration) - Use code examples to illustrate concepts - Avoid excessive enthusiasm or marketing language - Don't oversimplify or condescend to the reader **Example of preferred tone:** -> "Tables are SLua's most powerful data structure. Unlike LSL's separate `list` type, tables serve two purposes: they work as both arrays (like LSL lists) and dictionaries/maps (which LSL doesn't have)." +> "Tables are Lua's most powerful data structure. Unlike LSL's separate `list` type, tables serve two purposes: they work as both arrays (like LSL lists) and dictionaries/maps (which LSL doesn't have)." ## Adding Documentation @@ -104,7 +104,7 @@ All documentation should use a balanced and pragmatic tone that: The repository includes reference materials in the `context/` directory (gitignored): -**context/lsl_definitions.yaml** - Comprehensive language definitions for both LSL and SLua, including: +**context/lsl_definitions.yaml** - Comprehensive language definitions for both LSL and Lua, including: - Constants with types, values, and tooltips - Functions with signatures, parameters, return types, and descriptions - Events and their parameters @@ -117,8 +117,8 @@ The repository includes reference materials in the `context/` directory (gitigno - `flow-control/` - Control flow documentation - `lsl-portal/` - General LSL portal pages, tutorials, protocols, examples -**context/slua-guide/** - Suzanna's SLua Guide (https://suzanna-linn.github.io/slua/): -- Comprehensive educational resource for the SLua language +**context/lua-guide/** - Suzanna's SLua Guide (https://suzanna-linn.github.io/slua/): +- Comprehensive educational resource for the Lua language - Jekyll-based documentation with markdown files in `docs/` directory - Content includes: - Language fundamentals: `language1.md`, `language2.md` @@ -126,13 +126,13 @@ The repository includes reference materials in the `context/` directory (gitigno - Practical examples: `scripts-*.md` files with working examples (coroutines, enums, floating texts, sets, web integration) - Reference materials: `classes.md`, `transpiler.md`, `beta.md`, `future.md`, `history.md` - Licensed under Creative Commons Attribution 4.0 (text) and MIT License (code examples) -- Use as reference for SLua language documentation and migration patterns +- Use as reference for Lua language documentation and migration patterns **context/taxonomy.md** - Proposed site architecture and content taxonomy: - Scripting portal structure with sections for Getting Started, Features, Guides, and Recipes -- Planned organization for SLua/LSL language documentation +- Planned organization for Lua/LSL language documentation - Standard library/reference organization patterns -- Site-wide SLua/LSL toggle considerations +- Site-wide Lua/LSL toggle considerations These files are reference materials for building the new documentation. They should be transformed into clean, modern Markdown/MDX format in `src/content/docs/`. @@ -153,20 +153,20 @@ When building documentation, use `context/lsl_definitions.yaml` as the authorita ## Reference Page Generation -The project includes an automated generator for creating LSL and SLua reference pages for functions, events, and constants: +The project includes an automated generator for creating LSL and Lua reference pages for functions, events, and constants: **Generator Script:** `scripts/generate-docs.js` - Parses `src/definitions/lsl_definitions.yaml` to extract definitions -- Supports both LSL and SLua/Luau generation -- Creates MDX pages with appropriate components (LSLFunction/SLuaFunction, LSLEvent/SLuaEvent, LSLConstant/SLuaConstant) +- Supports both LSL and Lua/Luau generation +- Creates MDX pages with appropriate components (LSLFunction/LuaFunction, LSLEvent/LuaEvent, LSLConstant/LuaConstant) - Run with: `pnpm generate:docs` - Generates pages in: - LSL functions: `src/content/docs/script/lsl-reference/functions/` - - SLua functions: `src/content/docs/script/slua-reference/functions/` + - Lua functions: `src/content/docs/script/lua-reference/functions/` - LSL events: `src/content/docs/script/lsl-reference/events/` - - SLua events: `src/content/docs/script/slua-reference/events/` + - Lua events: `src/content/docs/script/lua-reference/events/` - LSL constants: `src/content/docs/script/lsl-reference/constants/` - - SLua constants: `src/content/docs/script/slua-reference/constants/` + - Lua constants: `src/content/docs/script/lua-reference/constants/` **Custom Content Preservation:** Generated pages support custom content that persists across regenerations. Any content after the component tag (e.g., ``, ``, ``) and before the optional attribution footer will be preserved when re-running the generator. This allows you to: @@ -178,7 +178,7 @@ Generated pages support custom content that persists across regenerations. Any c **Generated Page Structure:** 1. Frontmatter with title and description 2. Component import statements -3. Reference component tag (LSLFunction/SLuaFunction, LSLEvent/SLuaEvent, or LSLConstant/SLuaConstant) +3. Reference component tag (LSLFunction/LuaFunction, LSLEvent/LuaEvent, or LSLConstant/LuaConstant) 4. Custom content marker comment: `{/* DO NOT EDIT ABOVE THIS LINE */}` 5. Custom content section for examples, notes, and related links 6. Optional WikiAttribution footer (for LSL pages) @@ -188,17 +188,17 @@ Generated pages support custom content that persists across regenerations. Any c Functions: - `src/components/FunctionReference.astro` - Base function reference component - `src/components/LSLFunction.astro` - LSL function wrapper -- `src/components/SLuaFunction.astro` - SLua function wrapper +- `src/components/SLuaFunction.astro` - Lua function wrapper Events: - `src/components/EventReference.astro` - Base event reference component - `src/components/LSLEvent.astro` - LSL event wrapper -- `src/components/SLuaEvent.astro` - SLua event wrapper +- `src/components/SLuaEvent.astro` - Lua event wrapper Constants: - `src/components/ConstantReference.astro` - Base constant reference component - `src/components/LSLConstant.astro` - LSL constant wrapper -- `src/components/SLuaConstant.astro` - SLua constant wrapper +- `src/components/SLuaConstant.astro` - Lua constant wrapper These components dynamically load data from `src/definitions/lsl_definitions.yaml` at build time, requiring only the name as a prop. All metadata (signatures, parameters, types, values, energy costs, sleep times, badges) is loaded from the YAML file. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88d7de9..86da3d1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,10 +44,10 @@ Visit http://localhost:4321 to see your changes. The project auto-generates function and event reference pages from LSL definitions: ```bash -# Fetch latest LSL/SLua definitions from GitHub +# Fetch latest LSL/Lua definitions from GitHub pnpm fetch:definitions -# Generate all documentation (LSL + SLua functions and events) +# Generate all documentation (LSL + Lua functions and events) pnpm generate:docs ``` @@ -58,7 +58,7 @@ pnpm generate:docs All documentation lives in `src/content/docs/` as Markdown (`.md`) or MDX (`.mdx`) files: - `script/lsl-reference/` - LSL language reference -- `script/slua-reference/` - SLua language reference +- `script/lua-reference/` - Lua language reference - `script/guides/` - Scripting tutorials and guides - `build/` - Building and construction documentation @@ -73,7 +73,7 @@ Use a **balanced, pragmatic tone**: - Avoid marketing language or excessive enthusiasm **Example:** -> "Tables are SLua's most powerful data structure. Unlike LSL's separate `list` type, tables serve two purposes: they work as both arrays (like LSL lists) and dictionaries/maps (which LSL doesn't have)." +> "Tables are Lua's most powerful data structure. Unlike LSL's separate `list` type, tables serve two purposes: they work as both arrays (like LSL lists) and dictionaries/maps (which LSL doesn't have)." ### Adding New Pages @@ -123,7 +123,7 @@ default { ``` ```` -### SLua Code Blocks +### Lua Code Blocks Use `luau` (not `lua`) and **always include type annotations**: @@ -135,7 +135,7 @@ end) ``` ```` -See [SLUA_REFERENCE.md](SLUA_REFERENCE.md) for detailed SLua documentation guidelines. +See [LUA_REFERENCE.md](src/content/docs/script/lua-reference/index.mdx) for detailed Lua documentation guidelines. ## Internationalization @@ -156,7 +156,7 @@ The site supports additional languages. To add translated content: │ ├── components/ # Astro components │ ├── content/ │ │ └── docs/ # Documentation content (Markdown/MDX) -│ ├── definitions/ # LSL/SLua language definitions (YAML) +│ ├── definitions/ # LSL/Lua language definitions (YAML) │ └── styles/ # Custom CSS ├── astro.config.mjs # Astro configuration └── CLAUDE.md # Detailed project guidance @@ -173,7 +173,7 @@ This repository uses different licenses for different types of content: - **Legacy wiki content** (pages with `` component) remains under [CC-BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/) **Code Examples:** -- **All code examples** (LSL, SLua, JavaScript, etc.) must be contributed under [CC0 1.0 (Public Domain)](https://creativecommons.org/publicdomain/zero/1.0/) +- **All code examples** (LSL, Lua, JavaScript, etc.) must be contributed under [CC0 1.0 (Public Domain)](https://creativecommons.org/publicdomain/zero/1.0/) - This means anyone can use your code examples freely without attribution requirements ### What This Means for Contributors diff --git a/astro.config.mjs b/astro.config.mjs index 3d9966b..80a30b5 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -68,9 +68,9 @@ export default defineConfig({ // autogenerate: { directory: 'script/recipes' }, // }, { - label: 'Learn SLua', + label: 'Learn Lua', collapsed: true, - autogenerate: { directory: 'script/learn-slua' }, + autogenerate: { directory: 'script/learn-lua' }, }, { label: 'Reference', @@ -81,9 +81,9 @@ export default defineConfig({ autogenerate: { directory: 'script/lsl-reference' }, }, { - label: 'SLua', + label: 'Lua', collapsed: true, - autogenerate: { directory: 'script/slua-reference' }, + autogenerate: { directory: 'script/lua-reference' }, }, ], }, diff --git a/scripts/generate-docs.js b/scripts/generate-docs.js index 5cf018a..3f113dc 100644 --- a/scripts/generate-docs.js +++ b/scripts/generate-docs.js @@ -1,6 +1,6 @@ #!/usr/bin/env node -// Generates documentation pages for LSL/SLua functions, events, and constants +// Generates documentation pages for LSL/Lua functions, events, and constants // based on the lsl_definitions.yaml file located in src/definitions. import { readFile } from 'fs/promises'; @@ -81,7 +81,7 @@ async function generateDocs() { const events = Object.keys(lslDefs.events); const constants = Object.keys(lslDefs.constants); - // Events that are LSL-specific and should not be included in SLua documentation + // Events that are LSL-specific and should not be included in Lua documentation const lslOnlyEvents = ['state_entry', 'state_exit']; for (const funcName of functions) { @@ -90,25 +90,25 @@ async function generateDocs() { continue; } generateFor(funcName, lslDefs.functions[funcName]?.tooltip, 'LSLFunction', '../src/content/docs/script/lsl-reference/functions'); - generateFor(funcName, lslDefs.functions[funcName]?.tooltip, 'SLuaFunction', '../src/content/docs/script/slua-reference/functions'); + generateFor(funcName, lslDefs.functions[funcName]?.tooltip, 'SLuaFunction', '../src/content/docs/script/lua-reference/functions'); } console.log(`✅ Generated ${Object.keys(lslDefs.functions).length*2} doc pages for ${Object.keys(lslDefs.functions).length} functions.`); let sluaEventCount = 0; for (const eventName of events) { generateFor(eventName, lslDefs.events[eventName]?.tooltip, 'LSLEvent', '../src/content/docs/script/lsl-reference/events'); - // Skip LSL-only events when generating SLua documentation + // Skip LSL-only events when generating Lua documentation if (!lslOnlyEvents.includes(eventName)) { - generateFor(eventName, lslDefs.events[eventName]?.tooltip, 'SLuaEvent', '../src/content/docs/script/slua-reference/events'); + generateFor(eventName, lslDefs.events[eventName]?.tooltip, 'SLuaEvent', '../src/content/docs/script/lua-reference/events'); sluaEventCount++; } } const totalEvents = events.length; - console.log(`✅ Generated ${totalEvents} LSL event pages and ${sluaEventCount} SLua event pages for ${totalEvents} events.`); + console.log(`✅ Generated ${totalEvents} LSL event pages and ${sluaEventCount} Lua event pages for ${totalEvents} events.`); for (const constantName of constants) { generateFor(constantName, lslDefs.constants[constantName]?.tooltip, 'LSLConstant', '../src/content/docs/script/lsl-reference/constants'); - generateFor(constantName, lslDefs.constants[constantName]?.tooltip, 'SLuaConstant', '../src/content/docs/script/slua-reference/constants'); + generateFor(constantName, lslDefs.constants[constantName]?.tooltip, 'SLuaConstant', '../src/content/docs/script/lua-reference/constants'); } console.log(`✅ Generated ${Object.keys(lslDefs.constants).length*2} doc pages for ${Object.keys(lslDefs.constants).length} constants.`); } diff --git a/taxonomy.md b/taxonomy.md index c037b51..98f8eff 100755 --- a/taxonomy.md +++ b/taxonomy.md @@ -3,7 +3,7 @@ **Site:** create.secondlife.io **Base Path:** `/script/` -This document defines the information architecture for the scripting section of Second Life's creation documentation site. The structure supports both LSL (Linden Scripting Language) and SLua (Lua for Second Life). +This document defines the information architecture for the scripting section of Second Life's creation documentation site. The structure supports both LSL (Linden Scripting Language) and Lua (Lua for Second Life). --- @@ -15,9 +15,9 @@ This document defines the information architecture for the scripting section of - All users reference "recipes" for quick solutions - "reference" is comprehensive API documentation -2. **Language-Agnostic Structure**: Most top-level sections work for both LSL and SLua +2. **Language-Agnostic Structure**: Most top-level sections work for both LSL and Lua - Only "learn" section splits by language since fundamentals differ - - Functions/events/constants are shared (with SLua-specific additions) + - Functions/events/constants are shared (with Lua-specific additions) - Guides and recipes can include code examples in both languages using tabs 3. **Flat, Discoverable Hierarchy**: Maximum 3 levels deep @@ -32,7 +32,7 @@ This document defines the information architecture for the scripting section of - **Recipes**: Task-focused solutions (door, chair, teleporter) - **Reference**: Comprehensive API docs -5. **Migration-Friendly**: SLua includes "from-lsl" subsection to help LSL scripters transition +5. **Migration-Friendly**: Lua includes "from-lsl" subsection to help LSL scripters transition --- @@ -46,7 +46,7 @@ script/ │ ├── index.md # Quick intro for beginners │ ├── your-first-script.md # Tutorial: Hello World │ ├── editor-setup.md # VS Code extension setup -│ └── lsl-vs-slua.md # Choosing your language +│ └── lsl-vs-lua.md # Choosing your language │ ├── learn/ │ ├── lsl/ # LSL Language Tutorial @@ -57,8 +57,8 @@ script/ │ │ ├── states-events.md # State machines & events │ │ └── lists-strings.md # Working with lists & strings │ │ -│ └── slua/ # SLua Language Tutorial -│ ├── index.md # SLua overview & why Lua +│ └── lua/ # Lua Language Tutorial +│ ├── index.md # Lua overview & why Lua │ ├── basics.md # Variables, types, operators │ ├── control-flow.md # if, while, for, repeat │ ├── functions.md # Function definitions @@ -115,12 +115,12 @@ script/ │ ├── permissions.md # PERMISSION_* constants │ └── ... # Grouped by prefix/category │ - └── slua/ - ├── index.md # SLua reference overview + └── lua/ + ├── index.md # Lua reference overview ├── functions/ # ll* functions (same as LSL) ├── events/ # Event handling reference ├── constants/ # Constants reference - └── libraries/ # SLua-specific libraries + └── libraries/ # Lua-specific libraries ├── index.md ├── ll-events.md # LLEvents API ├── ll-timers.md # LLTimers API @@ -143,13 +143,13 @@ Onboarding content for absolute beginners: - No prior scripting knowledge assumed - Step-by-step first script tutorial - Editor setup instructions -- Guidance on choosing LSL vs SLua +- Guidance on choosing LSL vs Lua ### Learn (`/script/learn/`) Systematic language tutorials teaching fundamentals: - **LSL section**: State-based scripting, LSL-specific patterns -- **SLua section**: Lua fundamentals, modern scripting concepts -- **SLua from-lsl**: Migration guides leveraging existing LSL knowledge +- **Lua section**: Lua fundamentals, modern scripting concepts +- **Lua from-lsl**: Migration guides leveraging existing LSL knowledge - Progressive difficulty within each section - Hands-on examples and exercises @@ -158,7 +158,7 @@ Long-form, topic-focused articles explaining complex concepts: - Deep dives into specific domains (vehicles, HTTP, pathfinding) - Multiple approaches and best practices - Advanced techniques and optimizations -- Both LSL and SLua examples (using tabs) +- Both LSL and Lua examples (using tabs) - Example: "Scripting Vehicles" covers Physical Linden Vehicles, raycast vehicles, custom physics, non-physical movement, wearable vehicles ### Recipes (`/script/recipes/`) @@ -166,7 +166,7 @@ Short, task-focused how-tos with working examples: - Single, specific task (e.g., "How to script a door") - Copy-paste-ready code with explanations - Beginner-friendly -- Both LSL and SLua versions +- Both LSL and Lua versions - Quick solutions for common needs ### Reference (`/script/reference/`) @@ -174,7 +174,7 @@ Comprehensive API documentation: - **Functions**: Auto-generated from `lsl_definitions.yaml` with custom examples - **Events**: Complete event reference with parameters and usage - **Constants**: Searchable/filterable constant reference, grouped by category -- **SLua Libraries**: Documentation for LLEvents, LLTimers, Luau standard library +- **Lua Libraries**: Documentation for LLEvents, LLTimers, Luau standard library - Searchable and filterable overview pages - Consistent formatting across all entries @@ -189,7 +189,7 @@ Comprehensive API documentation: - Related content links at bottom of pages ### Code Examples -- Use Starlight's `` and `` components for LSL/SLua side-by-side +- Use Starlight's `` and `` components for LSL/Lua side-by-side - Syntax highlighting for both languages - Copy buttons on all code blocks - Link to relevant reference pages from examples @@ -228,9 +228,9 @@ This taxonomy is designed to scale: - Update examples and best practices - Distribute to appropriate sections (guides, recipes, learn) -### From context/slua-guide/ -- **language1.md, language2.md** → `/learn/slua/` tutorial pages -- **moving-*.md** → `/learn/slua/from-lsl/` migration guides +### From context/lua-guide/ +- **language1.md, language2.md** → `/learn-lua/` tutorial pages +- **moving-*.md** → `/learn-lua/from-lsl/` migration guides - **scripts-*.md** → `/recipes/` or `/guides/` depending on complexity - Modernize formatting and integrate with site design @@ -249,4 +249,4 @@ A successful taxonomy enables users to: 2. **Learn progressively**: Natural path from beginner to advanced 3. **Solve problems**: Recipes for quick solutions, guides for deep understanding 4. **Reference easily**: Fast lookup of functions, events, constants -5. **Transition smoothly**: LSL scripters can migrate to SLua with clear guidance +5. **Transition smoothly**: LSL scripters can migrate to Lua with clear guidance