Exam Shuffler Helper

A VS Code extension that provides comprehensive support for LaTeX exam templates with special markup tags for exam shuffling and randomization.

🔗 Companion Tool

This extension is designed to work with the Exam Shuffler web application - a professional exam generation tool that creates multiple randomized versions of exams.

Complete Workflow:

1. 📝 Write - Use this VS Code extension to create your LaTeX exam file

   • Get syntax highlighting for all markup tags
   • Use snippets for rapid question creation (exammc5, examfull, etc.)
   • Real-time validation ensures your markup is correct
   • Auto-completion for exam settings

2. ⬆️ Upload - Upload your .tex file to the Exam Shuffler web application

   • The web app reads the same %{#q} markup format
   • No conversion needed - files are directly compatible

3. ✨ Generate - Web app creates randomized exam versions

   • Questions and options are shuffled based on your markup tags
   • Multiple versions generated with automatic answer keys
   • Download complete LaTeX document ready for compilation in Overleaf or local LaTeX

Format Compatibility: Both tools use identical markup (%{#q}, %{#o}, %{#fixed}, etc.), ensuring seamless integration.

Features

🎨 Syntax Highlighting

Beautiful syntax highlighting for all exam markup tags:

• Settings block (%{#setting}...%{/setting})
• Question blocks (%{#q}...%{/q})
• Option blocks (%{#o}...%{/o})
• Instructions block (%{#instructions}...%{/instructions})
• Preamble block (%{#preamble}...%{/preamble})
• Special tags (%{#fixed}, %{#fixed-options:X}, %{#separate-page})

⚡ Code Snippets

Powerful snippets to speed up exam creation:

✅ Real-time Validation

Comprehensive validation to catch errors before uploading to the web app:

Tag Matching

• Validates matching opening/closing tags for questions, options, and settings
• Detects unclosed tags and closing tags without opening tags
• Shows precise error locations

Content Validation

• Warns about empty question content
• Warns about empty option content
• Info messages for empty instructions or preamble blocks

Conflict Detection

• Error: Detects conflicting %{#fixed} + %{#fixed-options} tags on same question
• Shows both tag locations with related information links
• Prevents invalid tag combinations

Fixed-Options Validation

• Validates that answer letter corresponds to an actual option
• Example: %{#fixed-options:D} with only 3 options shows warning

🔍 Auto-completion & Hover Documentation

Smart features to speed up your workflow:

Tag Completion - Type %{# and get instant suggestions:

• Block tags: setting, instructions, preamble, q, o (automatically adds closing tags)
• Special tags: fixed, fixed-options:A, separate-page
• Each with helpful descriptions and examples

Settings Completion - Inside %{#setting} blocks, type % to get:

• university, department, term, coursecode
• examname, examdate, timeallowed
• numberofvestions, groups, examtype
• code_name, code_numbering, includeCoverPage
• paper_size, seed

Hover Documentation - Hover over any tag to see detailed information:

• Block tags show purpose and usage examples
• %{#fixed} vs %{#fixed-options:A} explains the difference
• Closing tags show which opening tag they match
• Quick reference without leaving your code

📊 Status Bar

Real-time statistics displayed in the bottom status bar:

• Question count (e.g., "📝 10 questions")
• Option count (e.g., "☑ 45 options")
• Updates automatically as you type
• At-a-glance progress tracking

Installation

From VS Code Marketplace

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "Exam Shuffler Helper"
4. Click Install

From VSIX File

1. Download the .vsix file from Releases
2. In VS Code: Extensions → ... → Install from VSIX
3. Select the downloaded .vsix file

Usage

Quick Start

1. Create a new .tex file
2. Type examfull and press Tab
3. Fill in your exam details
4. Add questions using snippets like exammc5

Example: Creating a Question

Type exammc5 and press Tab to get:

% ============================================================ 
% question 1
%=============================================================
 
\item 
%{#q}
Question text
%{/q}

  \begin{enumerate}

    \item
    %{#o}
    Correct answer
    %{/o}

    \item
    %{#o}
    Wrong answer
    %{/o}

    \item
    %{#o}
    Wrong answer
    %{/o}

    \item
    %{#o}
    Wrong answer
    %{/o}

    \item
    %{#o}
    Wrong answer
    %{/o}

  \end{enumerate}
\questionseparator

Tag Reference

Settings Block

%{#setting}
%   university=Your University Name
%   department=Department Name
%   coursecode=MATH 101
%   examname=Midterm Exam
%   numberofvestions=10
%{/setting}

Question Block

%{#q}
What is the derivative of f(x) = x^2?
%{/q}

Option Block

%{#o}
f'(x) = 2x
%{/o}

Fixed Position Question

\item
%{#fixed}
%{#q}
Write your student ID
%{/q}

Fixed Options (Answer = C)

\item
%{#fixed-options:C}
%{#q}
Which is correct?
%{/q}

Separate Page Question

\item
%{#separate-page}
%{#q}
Complex problem requiring lots of space
%{/q}

Next Steps

Once you've created your exam file:

1. Save your .tex file - Your exam template is ready
2. Upload to Exam Shuffler - Go to the Exam Shuffler web application
3. Generate versions - The web app will create multiple randomized exam versions
4. Download & compile - Get your shuffled exams ready for printing

The markup format you create with this extension is fully compatible with the Exam Shuffler web application - no manual conversion needed!

Configuration

Access settings via: File → Preferences → Settings → Search "Exam Shuffler"

• Validate Tags: Enable/disable tag matching validation (default: true)
• Validate Fixed Options: Enable/disable fixed-options letter validation (default: true)

Requirements

• VS Code 1.80.0 or higher
• LaTeX workshop or similar LaTeX extension (recommended for full LaTeX support)

Known Issues

• Validation is file-scoped (doesn't check across multiple files)
• Large files (>10,000 lines) may experience slight performance delays

Release Notes

0.1.0 - Initial Release

• Syntax highlighting for all exam markup tags
• 11 code snippets for rapid exam creation
• Real-time tag validation
• Fixed-options letter validation
• Auto-completion for settings parameters

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you encounter any issues or have suggestions, please open an issue on GitHub.

Author

Mohammed - Mathematics Professor at KFUPM

Acknowledgments

• Built for educators creating randomized exams
• Perfect for maintaining academic integrity
• Designed for mathematics and STEM courses
• Works seamlessly with the Exam Shuffler web application for complete exam randomization workflow

Enjoy creating better exams! 🎓

This extension is part of the Exam Shuffler ecosystem - helping educators maintain academic integrity through intelligent exam randomization.