coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions Projects 12 Releases 1 Wiki Activity
522 Commits 1 Branch 12 Tags
fecc2fd4fac63c64febdd7c9d67dc048b9a2e2be
Commit Graph

2 Commits

Author SHA1 Message Date
tegwick
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
tegwick
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