KylerOlsen/YREA-SLS
KylerOlsen
/
YREA-SLS
1
0
Fork 0
Code Releases 3 Wiki Activity
YREA-SLS/ideas.md

7.8 KiB
Raw Blame History

Perfect! I've completed version 0.7 with all the non-human TODOs addressed. Now let me discuss the document organization question with you.

Discussion: Document Reorganization for v0.8

TODO: (FOR HUMAN) These specifications may need to be reorganized. ie. do we need both "Stack Manipulation Trait" in 4.1 and "5. Stack Operations", etc. Should some of these be in the appendix. What is the best structure for this document?

Current Structure Issues

  1. Duplication: Section 4.1 defines the Stackable trait, then Section 5 describes the same operations from a usage perspective
  2. Mixed Audiences: Some sections are for language implementers (trait definitions), others for users (how to use operators)
  3. Appendix Bloat: Appendix A repeats all the trait definitions with more detail

Proposed Reorganization Options

Option A: User-Focused Main Document, Implementer Appendix

Main Document:
1. Overview
2. Lexical Structure
3. Type System (high-level)
4. Using Traits (not defining them)
5. Stack Operations (usage examples)
6. Built-in Operators (by category)
7. Functions
8. Control Flow
9. Data Structures
10. Standard Library

Appendices:
A. Complete Trait Definitions (for implementers)
B. Grammar Reference
C. Future Features
D. Examples & Tutorials

Pros: Clear separation, main doc is user-friendly Cons: Implementers have to jump to appendix frequently

Option B: Three-Part Structure

Part I: Language Basics (for users)
1. Overview
2. Getting Started
3. Lexical Structure
4. Basic Operations
5. Control Flow
6. Data Structures

Part II: Advanced Features
7. Type System
8. Trait System
9. Generic Programming
10. Standard Library

Part III: Reference
A. Complete Trait Definitions
B. Grammar
C. Future Features
D. Examples

Pros: Progressive disclosure, easier learning curve Cons: More complex structure, harder to navigate

Option C: Consolidated Single-Topic Sections

1. Overview
2. Lexical Structure
3. Type System & Traits (combined)
   3.1 Types
   3.2 Traits
   3.3 Defining Traits
   3.4 Implementing Traits
   3.5 Using Traits
4. Stack Operations (includes trait def + usage)
5. Operators (includes trait defs + usage)
6. Functions
7. Control Flow
8. Data Structures
9. Standard Library

Appendices:
A. Complete Trait Reference (comprehensive)
B. Grammar Summary
C. Future Features
D. Examples & Tutorials

Pros: Everything about a topic in one place, less jumping around Cons: Sections can get very long, harder to find specific info

Option D: Reference Manual Style

1. Overview & Philosophy
2. Lexical Structure
3. Type System
4. Expressions & Operators
   4.1 Stack Operations
   4.2 Arithmetic
   4.3 Comparison
   4.4 Logical
   4.5 Bitwise
5. Statements
   5.1 Functions
   5.2 Control Flow
6. Definitions
   6.1 Traits
   6.2 Structs
   6.3 Unions
   6.4 Enums
7. Standard Library

Appendices:
A. Trait Reference (all traits alphabetically)
B. Operator Reference (all operators alphabetically)
C. Grammar
D. Future Features
E. Tutorial & Examples

Pros: Traditional reference manual format, easy lookup Cons: Less narrative flow, might be dry

Option E: Minimal Main Doc + Comprehensive Appendix

Main Document:
1. Overview
2. Quick Start Guide
3. Lexical Structure
4. Language Constructs
   4.1 Expressions
   4.2 Functions
   4.3 Control Flow
   4.4 Data Structures
5. Type System Overview
6. Trait System Overview

Appendices:
A. Complete Operator Reference
B. Complete Trait Reference
C. Grammar Reference
D. Standard Library Reference
E. Examples & Patterns
F. Future Features

Pros: Main doc is concise tutorial, appendices are comprehensive reference Cons: Need to consult appendices for detailed info

My Recommendation: Option C with Modifications

I suggest Option C because it addresses the duplication issue while keeping related information together. Here's a refined version:

1. Overview
   - Design Principles
   - Operators vs Functions

2. Lexical Structure
   - Comments
   - Identifiers
   - Literals
   - Type Tuples
   - Token Strings

3. Type System
   - Primitive Types
   - Types vs Traits
   - Generic Constructs

4. Trait System
   - What are Traits
   - Defining Traits
   - Implementing Traits  
   - Trait Inheritance
   - Using Traits

5. Stack Operations
   - The Stackable Trait (definition)
   - Using Stack Operations (examples)
   - Advanced Stack Manipulation

6. Operators
   - Arithmetic (trait def + examples)
   - Comparison (trait def + examples)
   - Logical (trait def + examples)
   - Bitwise (trait def + examples)

7. Functions
   - Defining Functions
   - Generic Functions
   - Function Examples

8. Control Flow
   - Conditionals
   - Loops
   - Pattern Matching

9. Data Structures
   - Structs
   - Unions
   - Enums
   - Arrays

10. Standard Library
   - I/O
   - String Operations
   - Type Conversion
   - Container Operations

Appendices:
A. Complete Trait Reference (alphabetically organized, comprehensive)
B. Complete Operator Reference (alphabetically organized)
C. Grammar Summary
D. Module System (Future)
E. Memory Management (Future)
F. Examples & Tutorials

Key Changes:

  1. Merge trait definitions with usage - Section 5 and 6 would show trait definition THEN usage examples
  2. Move comprehensive reference to Appendix A - For implementers who need all details
  3. Keep main sections narrative - Walk through how to use the language
  4. Appendix A is the "implementer's guide" - Has every trait with full documentation

Specific Section Example: Section 5 (Stack Operations)

5. Stack Operations

Stack operations manipulate the runtime stack. All stack operations 
implement the Stackable trait:

5.1 The Stackable Trait

{
    (Self -- Self Self) dup:
    (Self -- ) drop:
    (Self Self -- Self Self) swap:
    // ... etc
} ::Stackable trait

5.2 Basic Stack Manipulation

dup    // Duplicate top item
       // Example: 5 dup => 5 5

drop   // Remove top item  
       // Example: 5 10 drop => 5

swap   // Swap top two items
       // Example: 5 10 swap => 10 5

5.3 Advanced Stack Inspection

pick   // Copy nth item to top
       // Example: 1 2 3 4  2 pick => 1 2 3 4 2

roll   // Rotate n items
       // Example: 1 2 3 4  3 1 roll => 1 3 4 2

5.4 Implementing Stackable for Custom Types

[examples of custom implementations]

Questions for You

  1. Which option appeals to you most? (A, B, C, D, E, or my modified C)

  2. Primary audience priority?

    • Language learners/users?
    • Language implementers?
    • Both equally?

  3. Duplication preference?

    • Minimal duplication (more cross-references)
    • Some strategic duplication (easier to read)

  4. Appendix philosophy?

    • Appendices for reference only
    • Appendices for "advanced/future" content
    • Appendices for detailed specifications

  5. Section length preference?

    • Shorter sections (5-10 pages) with more sections
    • Longer comprehensive sections
    • No preference

Please let me know your thoughts, and I can create v0.8 with the reorganization you prefer!

Here are my answers and ideas.

  • Audience: language learners/users (but don't drop implementation stuff, I still need to implement it)
  • Minimal duplication
  • Shorter sections, with more sections

Appendices:

  • A. Standard Library (alphabetically organized, comprehensive)
  • B. Complete Trait Reference (alphabetically organized, comprehensive)
  • C. Complete Operator Reference (alphabetically organized, comprehensive)
  • D. Grammar Summary (don't repeat the struct, trait, fn, for, etc. grammars as they are defined by the traits)
  • E. Module System (Future)
  • F. Memory Management (Future)
  • G. Examples & Tutorials

Don't make the revision yet, give a detailed plan so that, given the plan and 0.7 specs, another agent can do the final revision.