tegwick
3003b9b8da
Some checks failed
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
Moved schema-of-schemas planning artifacts from roadmap to history with datestamp prefix, marking completion of all 6 implementation phases. **Changes:** - Moved roadmap/schema-of-schemas/ → history/2026-01-05-schema-of-schemas/ - Updated all documentation references to new location - Marked implementation as completed in TODO.md - Updated CHANGELOG.md to reflect archived status **Implementation Summary:** All 6 phases completed successfully: - Phase 1: Filename validation (50 tests) - Phase 2: Markdown schema loader (35 tests) - Phase 3: Schema-for-schemas metaschema (12 tests) - Phase 4: Schema migration (2 migrated, 3 deleted) - Phase 5: CLI enhancements (multi-schema validation) - Phase 6: Integration testing and documentation **Deliverables:** - 97 unit tests (100% passing) - 4 production schemas in registry - Comprehensive user documentation - Updated examples (manpages, terminology) - Complete schema management system The schema-of-schemas topic is now complete and archived for historical reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
335 lines
11 KiB
Markdown
335 lines
11 KiB
Markdown
---
|
|
schema-id: "https://markitect.dev/schemas/manpage/v1.0"
|
|
version: "1.0.0"
|
|
status: "stable"
|
|
domain: "manpage"
|
|
description: "JSON schema for Unix-style manual pages with section classification and content control"
|
|
---
|
|
|
|
# Unix Manual Page Schema v1.0
|
|
|
|
## Overview
|
|
|
|
This schema defines the structure and validation rules for Unix-style manual pages (manpages) in MarkiTect's markdown format. It includes comprehensive section classification, content control patterns, and quality guidelines to ensure consistent, high-quality documentation.
|
|
|
|
## Features
|
|
|
|
- **Section Classification System**: Categorizes manpage sections as required, recommended, optional, discouraged, or improper
|
|
- **Content Control**: Validates content patterns, quality metrics, and structural requirements
|
|
- **Flexible Section Names**: Supports alternative section names (e.g., "FLAGS" as alternative to "OPTIONS")
|
|
- **Quality Enforcement**: Minimum/maximum content requirements for paragraphs, code blocks, and words
|
|
|
|
## Section Classifications
|
|
|
|
### Required Sections
|
|
- **SYNOPSIS**: Brief command syntax with all options and arguments
|
|
- **DESCRIPTION**: Detailed explanation of command purpose and functionality
|
|
|
|
### Recommended Sections
|
|
- **EXAMPLES**: Practical usage examples demonstrating common use cases
|
|
- **OPTIONS**: Detailed option descriptions with all flags and behaviors
|
|
- **SEE ALSO**: Related commands and documentation references
|
|
|
|
### Optional Sections
|
|
- **BUGS**: Known issues and bug reporting information
|
|
- **AUTHORS**: Contributors and maintainers
|
|
- **COPYRIGHT**: License information
|
|
- **HISTORY**: Historical development information
|
|
|
|
### Discouraged Sections
|
|
- **DEPRECATED**: Legacy content (should move to HISTORY)
|
|
- **OLD_SYNTAX**: Outdated syntax (should move to HISTORY or be removed)
|
|
|
|
### Improper Sections
|
|
- **INTERNAL_NOTES**: Development notes (must not appear in published docs)
|
|
- **TODO**: Development tasks (remove before publication)
|
|
- **DRAFT**: Draft markers (remove before publication)
|
|
|
|
## Usage
|
|
|
|
### Validating a Manpage
|
|
|
|
```bash
|
|
markitect validate my-command.1.md --schema manpage-schema-v1.0
|
|
```
|
|
|
|
### Common Validation Errors
|
|
|
|
1. **Missing Required Sections**: Ensure SYNOPSIS and DESCRIPTION are present
|
|
2. **Content Too Brief**: DESCRIPTION should have at least 50 words
|
|
3. **No Examples**: While optional, EXAMPLES are highly recommended
|
|
4. **Improper Sections**: Remove TODO, DRAFT, and INTERNAL_NOTES before publication
|
|
|
|
## Content Quality Guidelines
|
|
|
|
### SYNOPSIS Section
|
|
- Show command name in bold: `**command**`
|
|
- Use brackets `[]` for optional arguments
|
|
- Use italic `*ARG*` for required arguments
|
|
- Keep concise (1-5 lines maximum)
|
|
- Include 5-150 words
|
|
|
|
### DESCRIPTION Section
|
|
- Start with what the command does
|
|
- Explain why users would use it
|
|
- Describe main functionality and features
|
|
- Minimum 50 words, maximum 1000 words
|
|
- At least 3 sentences
|
|
|
|
### EXAMPLES Section
|
|
- Use bash code blocks for commands
|
|
- Include comments explaining each example
|
|
- Start simple, progress to complex
|
|
- Show actual output when helpful
|
|
- Cover common use cases first
|
|
|
|
## Schema Definition
|
|
|
|
```json
|
|
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"title": "Enhanced Markdown Manpage Schema with Classifications",
|
|
"description": "JSON schema for Unix-style manual pages with section classification and content control",
|
|
"x-markitect-sections": {
|
|
"SYNOPSIS": {
|
|
"classification": "required",
|
|
"heading_level": 2,
|
|
"position": "after_title",
|
|
"content_instruction": "Brief command syntax showing all options and arguments in standard format",
|
|
"min_paragraphs": 1,
|
|
"max_paragraphs": 5,
|
|
"min_code_blocks": 0,
|
|
"max_code_blocks": 3,
|
|
"error_message": "SYNOPSIS section is mandatory for all manpages per Unix conventions"
|
|
},
|
|
"DESCRIPTION": {
|
|
"classification": "required",
|
|
"heading_level": 2,
|
|
"content_instruction": "Detailed explanation of what the command does, its purpose, and main functionality",
|
|
"min_paragraphs": 2,
|
|
"max_paragraphs": 50,
|
|
"error_message": "DESCRIPTION section is mandatory for all manpages"
|
|
},
|
|
"EXAMPLES": {
|
|
"classification": "recommended",
|
|
"heading_level": 2,
|
|
"content_instruction": "Practical usage examples with explanations demonstrating common use cases",
|
|
"min_code_blocks": 3,
|
|
"max_code_blocks": 20,
|
|
"warning_if_missing": "Examples greatly improve manpage usability - highly recommended"
|
|
},
|
|
"SEE ALSO": {
|
|
"classification": "recommended",
|
|
"heading_level": 2,
|
|
"content_instruction": "Related commands, configuration files, and documentation references",
|
|
"min_paragraphs": 1,
|
|
"warning_if_missing": "Cross-references help users discover related functionality"
|
|
},
|
|
"OPTIONS": {
|
|
"classification": "recommended",
|
|
"heading_level": 2,
|
|
"content_instruction": "Detailed option descriptions with all flags and their behaviors",
|
|
"alternatives": ["GLOBAL OPTIONS", "COMMAND OPTIONS", "FLAGS"],
|
|
"warning_if_missing": "Documenting command options helps users understand available functionality"
|
|
},
|
|
"BUGS": {
|
|
"classification": "optional",
|
|
"heading_level": 2,
|
|
"content_instruction": "Known issues, limitations, and bug reporting information"
|
|
},
|
|
"AUTHORS": {
|
|
"classification": "optional",
|
|
"heading_level": 2,
|
|
"content_instruction": "List of contributors and maintainers"
|
|
},
|
|
"COPYRIGHT": {
|
|
"classification": "optional",
|
|
"heading_level": 2,
|
|
"content_instruction": "Copyright statement and license information"
|
|
},
|
|
"HISTORY": {
|
|
"classification": "optional",
|
|
"heading_level": 2,
|
|
"content_instruction": "Historical information about command development"
|
|
},
|
|
"DEPRECATED": {
|
|
"classification": "discouraged",
|
|
"heading_level": 2,
|
|
"warning_if_missing": "Consider moving deprecated content to historical documentation or HISTORY section"
|
|
},
|
|
"OLD_SYNTAX": {
|
|
"classification": "discouraged",
|
|
"heading_level": 2,
|
|
"warning_if_missing": "Old syntax should be documented in HISTORY or removed entirely"
|
|
},
|
|
"INTERNAL_NOTES": {
|
|
"classification": "improper",
|
|
"heading_level": 2,
|
|
"error_message": "Internal notes must not appear in published manpages - move to developer documentation"
|
|
},
|
|
"TODO": {
|
|
"classification": "improper",
|
|
"heading_level": 2,
|
|
"error_message": "TODO sections are for development only - remove before publication"
|
|
},
|
|
"DRAFT": {
|
|
"classification": "improper",
|
|
"heading_level": 2,
|
|
"error_message": "DRAFT markers must be removed before publication"
|
|
}
|
|
},
|
|
"x-markitect-content-control": {
|
|
"synopsis": {
|
|
"required_patterns": [
|
|
"\\*\\*[a-z][a-z0-9-]*\\*\\*",
|
|
"\\[.*\\]"
|
|
],
|
|
"discouraged_patterns": [
|
|
"TODO",
|
|
"FIXME",
|
|
"TBD"
|
|
],
|
|
"content_quality": {
|
|
"min_words": 5,
|
|
"max_words": 150,
|
|
"readability_target": "technical"
|
|
},
|
|
"content_instructions": [
|
|
"Show command name in bold (e.g., **command**)",
|
|
"Use brackets [] for optional arguments",
|
|
"Use italic *ARG* for required arguments",
|
|
"Keep synopsis concise (1-5 lines maximum)",
|
|
"Use ellipsis ... to indicate repeatable arguments"
|
|
]
|
|
},
|
|
"description": {
|
|
"discouraged_patterns": [
|
|
"TODO",
|
|
"FIXME",
|
|
"\\bWIP\\b",
|
|
"\\bXXX\\b"
|
|
],
|
|
"forbidden_patterns": [
|
|
"password\\s*=\\s*[\"'].*[\"']",
|
|
"api[_-]?key\\s*=\\s*[\"'].*[\"']",
|
|
"secret\\s*=\\s*[\"'].*[\"']"
|
|
],
|
|
"content_quality": {
|
|
"min_words": 50,
|
|
"max_words": 1000,
|
|
"readability_target": "technical",
|
|
"min_sentences": 3
|
|
},
|
|
"content_instructions": [
|
|
"Start with what the command does",
|
|
"Explain why users would use it",
|
|
"Describe main functionality and features",
|
|
"Mention any prerequisites or requirements",
|
|
"Keep technical but accessible"
|
|
],
|
|
"link_validation": {
|
|
"check_internal": true,
|
|
"check_external": false,
|
|
"allow_fragments": true
|
|
}
|
|
},
|
|
"examples": {
|
|
"required_patterns": [
|
|
"```",
|
|
"#"
|
|
],
|
|
"content_quality": {
|
|
"min_words": 100,
|
|
"max_words": 2000,
|
|
"readability_target": "general"
|
|
},
|
|
"content_instructions": [
|
|
"Use bash code blocks for command examples",
|
|
"Include comments explaining what each example does",
|
|
"Start with simple examples, progress to complex",
|
|
"Show actual output when helpful",
|
|
"Cover common use cases first"
|
|
]
|
|
}
|
|
},
|
|
"type": "object",
|
|
"properties": {
|
|
"headings": {
|
|
"type": "object",
|
|
"description": "Document heading structure",
|
|
"properties": {
|
|
"level_1": {
|
|
"type": "array",
|
|
"description": "Title heading in format: command(section) - description",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"pattern": "^[a-z0-9-]+\\([0-9]\\) - .+"
|
|
}
|
|
}
|
|
},
|
|
"minItems": 1,
|
|
"maxItems": 1
|
|
},
|
|
"level_2": {
|
|
"type": "array",
|
|
"description": "Main section headings",
|
|
"minItems": 3,
|
|
"maxItems": 30
|
|
},
|
|
"level_3": {
|
|
"type": "array",
|
|
"description": "Subsection headings",
|
|
"minItems": 0,
|
|
"maxItems": 50
|
|
}
|
|
},
|
|
"required": ["level_1", "level_2"]
|
|
},
|
|
"paragraphs": {
|
|
"type": "array",
|
|
"description": "Text paragraphs",
|
|
"minItems": 10,
|
|
"maxItems": 500
|
|
},
|
|
"code_blocks": {
|
|
"type": "array",
|
|
"description": "Code examples",
|
|
"minItems": 1,
|
|
"maxItems": 50
|
|
},
|
|
"lists": {
|
|
"type": "array",
|
|
"description": "Lists for options and structured information",
|
|
"minItems": 0,
|
|
"maxItems": 100
|
|
},
|
|
"emphasis": {
|
|
"type": "array",
|
|
"description": "Bold and italic text for commands and arguments",
|
|
"minItems": 20,
|
|
"maxItems": 500
|
|
}
|
|
},
|
|
"required": ["headings", "paragraphs", "code_blocks", "emphasis"]
|
|
}
|
|
```
|
|
|
|
## Version History
|
|
|
|
### v1.0.0 (2026-01-04)
|
|
- Initial markdown schema version
|
|
- Migrated from enhanced-manpage JSON schema
|
|
- Added comprehensive documentation
|
|
- Implemented section classification system
|
|
- Added content control and quality guidelines
|
|
|
|
## Related Documentation
|
|
|
|
- [Schema Naming Specification](../../history/2026-01-05-schema-of-schemas/SCHEMA_NAMING_SPEC.md)
|
|
- [Schema Management Workplan](../../history/2026-01-05-schema-of-schemas/WORKPLAN.md) (archived)
|
|
- [Schema Management Guide](../../docs/SCHEMA_MANAGEMENT_GUIDE.md)
|
|
- [MarkiTect Documentation](../../README.md)
|