2b687a4ca8
refactor: upgrade manpage schema to use new classification system
...
Modernize the original markdown-manpage-schema.json to leverage Phase 1
classification features for improved flexibility and content guidance.
## Changes
**Replaced old extension format:**
```json
"x-markitect-required-sections": ["SYNOPSIS", "DESCRIPTION"],
"x-markitect-recommended-sections": ["OPTIONS", "EXAMPLES"],
"x-markitect-optional-sections": ["COMMANDS", "FILES"]
```
**With new classification system:**
```json
"x-markitect-sections": {
"SYNOPSIS": {
"classification": "required",
"heading_level": 2,
"content_instruction": "...",
"error_message": "..."
}
}
```
## New Features Added
**Section Classifications:**
- 2 required: SYNOPSIS, DESCRIPTION
- 4 recommended: OPTIONS, EXAMPLES, SEE ALSO, COPYRIGHT
- 7 optional: COMMANDS, CONFIGURATION, FILES, EXIT STATUS, ENVIRONMENT, BUGS, AUTHORS
**Content Control:**
- Synopsis: Required patterns for command syntax, discouraged TODO/FIXME
- Description: Quality metrics (50-1000 words), forbidden credential patterns
- Examples: Required code blocks and comments
**Enhanced Guidance:**
- Per-section content instructions for authors
- Custom error/warning messages
- Alternative section names (e.g., OPTIONS | GLOBAL OPTIONS | FLAGS)
- Content quality targets (word count, readability level)
## Validation
✅ Tested: markdown-schema-validation.1.md still validates successfully
✅ Backward compatible: Existing validation behavior preserved
✅ Enhanced: Now provides content guidance and flexible classifications
This demonstrates the practical value of Phase 1 enhancements - the same
schema now offers much richer validation and authoring guidance.
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-01-04 21:09:34 +01:00
d68e762612
feat: implement Phase 1 - Enhanced Schema Format with Classifications
...
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled
Complete Phase 1 of Schema Evolution Workplan implementing flexible content
control and section classification system.
## New Features
### 1. x-markitect-sections Extension
- Five classification levels: required, recommended, optional, discouraged, improper
- Per-section content constraints (paragraphs, code blocks, lists)
- Position hints for section ordering
- Custom error/warning messages
- Alternative section names support
- Content instructions for authors
### 2. x-markitect-content-control Extension
- Required/discouraged/forbidden pattern matching
- Content quality metrics (word count, readability target, sentence count)
- Content instruction arrays
- Link validation configuration
### 3. Metaschema Validation
- Updated markitect-metaschema.json with complete validation rules
- Enhanced metaschema.py with validation methods for both extensions
- Comprehensive validation of all extension properties
- Clear error messages for invalid schemas
### 4. Documentation & Examples
- Complete specification in docs/specifications/schema-extensions-spec.md
- Enhanced manpage schema demonstrating all 5 classification levels
- API documentation schema showing alternative patterns
- Detailed usage examples and validation behavior
## Implementation Details
**Files Modified:**
- markitect/schemas/markitect-metaschema.json: Added extension definitions
- markitect/metaschema.py: Added _validate_sections() and _validate_content_control()
**Files Created:**
- docs/specifications/schema-extensions-spec.md: Complete specification (v1.0)
- examples/manpages/enhanced-manpage-schema.json: Demonstrates all classifications
- examples/manpages/api-documentation-schema.json: Shows API doc patterns
## Validation Behavior
**Classification Levels:**
- required: Missing = ERROR (validation fails)
- recommended: Missing = WARNING (validation succeeds with warnings)
- optional: No validation impact
- discouraged: Present = WARNING (validation succeeds with warnings)
- improper: Present = ERROR (validation fails)
## Next Steps
Phase 2: Schema Refinement Tools (schema-analyze, schema-refine, schema-compose)
Phase 3: Enhanced Validation Engine (classification-aware validation, quality metrics)
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-01-04 21:02:51 +01:00
b51999582e
feat: add manpages example demonstrating schema validation
...
Add comprehensive example showcasing schema validation with self-documenting
manpage system:
- markdown-manpage-schema.json: Reusable schema for Unix manpage structure
- markdown-schema-validation.1.md: Complete manual about schema validation
- README.md: Usage guide, integration examples, and best practices
- SCHEMA_EVOLUTION_WORKPLAN.md: Roadmap for enhanced schema system
The manual validates against its own schema, demonstrating dogfooding
principle. Workplan outlines 5-phase evolution from rigid structural
validation to flexible content control with blueprints.
Key features demonstrated:
- Schema-driven documentation structure
- Self-validating documentation
- Reusable validation patterns
- Classification system design (required/recommended/optional/discouraged/improper)
This sets foundation for Phase 1 implementation: enhanced schema format
with section classification and content control.
🤖 Generated with [Claude Code](https://claude.com/claude-code )
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-01-04 20:58:05 +01:00
