f6fac6c4bc
Fix bin/publish: use correct .env path for rspade_system Fix bin/publish script: prevent grep exit code 1 from terminating script 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
112 lines
3.4 KiB
Markdown
Executable File
112 lines
3.4 KiB
Markdown
Executable File
# RSX Framework Manual Pages
|
|
|
|
## Documentation Philosophy
|
|
|
|
These manual pages follow traditional Unix man page conventions from the late 1990s:
|
|
- **Plain text format** - No fancy formatting, boxes, or special characters
|
|
- **Simple indentation** - Code examples use 4-space indentation
|
|
- **Readable and copyable** - Easy to copy/paste examples
|
|
- **Traditional sections** - NAME, SYNOPSIS, DESCRIPTION, etc.
|
|
|
|
## Writing Style Requirements
|
|
|
|
### Format
|
|
- Use plain ASCII text only
|
|
- Code examples indented with 4 spaces
|
|
- No box drawing characters (└─┘│┌┐)
|
|
- No special Unicode symbols
|
|
- Section headers in ALL CAPS
|
|
- Subsection headers in Title Case
|
|
|
|
### Content Requirements
|
|
Each man page must include:
|
|
|
|
1. **General introduction** - Explain what the RSX feature is and its purpose
|
|
2. **RSX philosophy** - How it simplifies development compared to standard approaches
|
|
3. **Laravel differences** - Explicitly note how RSX differs from Laravel equivalents
|
|
4. **Practical examples** - Real-world usage patterns from actual RSX applications
|
|
5. **Common pitfalls** - What mistakes developers might make
|
|
|
|
### RSX vs Laravel Context
|
|
Always explain how RSX features differ from their Laravel counterparts:
|
|
- Path-agnostic class loading vs PSR-4 autoloading
|
|
- Manifest-based discovery vs service provider registration
|
|
- Static controller methods vs instance methods with DI
|
|
- Unified bundle system vs mix/vite configuration
|
|
- Automatic route discovery vs manual route files
|
|
|
|
## Manual Page Sections
|
|
|
|
Standard sections in order:
|
|
|
|
```
|
|
NAME
|
|
Component name and one-line description
|
|
|
|
SYNOPSIS
|
|
Quick usage examples showing the most common use case
|
|
|
|
DESCRIPTION
|
|
Overview of the component, its philosophy, and how it differs from Laravel
|
|
|
|
BASIC USAGE
|
|
Step-by-step introduction to using the feature
|
|
|
|
API REFERENCE
|
|
Detailed method/function documentation
|
|
|
|
EXAMPLES
|
|
Practical, real-world code examples
|
|
|
|
RSX VS LARAVEL
|
|
Explicit comparison with Laravel equivalents
|
|
|
|
TROUBLESHOOTING
|
|
Common errors and their solutions
|
|
|
|
SEE ALSO
|
|
Related manual pages
|
|
```
|
|
|
|
## File Naming
|
|
- Use lowercase with underscores: `manifest_api.txt`
|
|
- Extensions: Always `.txt` for man pages
|
|
- No special characters or spaces
|
|
|
|
## Example Introduction Template
|
|
|
|
```
|
|
DESCRIPTION
|
|
The RSX [feature] provides [what it does] through [how it works].
|
|
Unlike Laravel's [equivalent], which requires [Laravel approach],
|
|
RSX automatically [RSX approach] without any configuration.
|
|
|
|
This path-agnostic approach means developers never need to worry
|
|
about [common Laravel pain point]. The framework handles all
|
|
[technical detail] transparently.
|
|
|
|
Key differences from Laravel:
|
|
- Laravel: [how Laravel does it]
|
|
- RSX: [how RSX does it]
|
|
|
|
Benefits:
|
|
- No [configuration/boilerplate] required
|
|
- Automatic [feature]
|
|
- Works with [use case]
|
|
```
|
|
|
|
## Testing Documentation
|
|
After writing or updating a man page:
|
|
1. Test with `php artisan rsx:man [topic]`
|
|
2. Verify plain text output (no special characters)
|
|
3. Ensure code examples are properly indented
|
|
4. Confirm examples can be copy/pasted directly
|
|
|
|
## Future Documentation Topics
|
|
Planned manual pages to create:
|
|
- `model.txt` - ORM with enum constants and Ajax fetch
|
|
- `auth.txt` - Session-based authentication (no JWT)
|
|
- `testing.txt` - RSX test framework
|
|
- `ajax.txt` - Internal API system with auto-generated stubs
|
|
- `main.txt` - Application-wide middleware hooks
|
|
- `migration.txt` - Forward-only database migrations |