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>
This commit is contained in:
388
examples/manpages/README.md
Normal file
388
examples/manpages/README.md
Normal file
@@ -0,0 +1,388 @@
|
||||
# Unix Manpage Schema Validation Example
|
||||
|
||||
This example demonstrates MarkiTect's schema validation system by creating a self-validating documentation set: a schema that defines Unix manpage structure and a comprehensive manual about schema validation that validates against its own schema definition.
|
||||
|
||||
## Overview
|
||||
|
||||
This example showcases the "dogfooding" principle - using MarkiTect's schema validation to document schema validation itself. It demonstrates:
|
||||
|
||||
- **Schema-driven documentation** - Defining document structure with JSON Schema
|
||||
- **Self-validation** - The manual validates against the manpage schema it demonstrates
|
||||
- **Reusable patterns** - The manpage schema can validate any Unix-style manual page
|
||||
- **Complete workflow** - From schema creation through validation and refinement
|
||||
|
||||
## Files in This Example
|
||||
|
||||
### `markdown-manpage-schema.json`
|
||||
|
||||
A JSON Schema defining the structure of Unix-style manual pages written in Markdown.
|
||||
|
||||
**Key Features:**
|
||||
- Validates H1 title format: `command(section) - description`
|
||||
- Requires SYNOPSIS and DESCRIPTION sections
|
||||
- Validates heading hierarchy (H1, H2, H3, H4)
|
||||
- Ensures presence of code examples, paragraphs, and emphasis
|
||||
- Includes custom `x-markitect-*` extensions for manpage conventions
|
||||
|
||||
**Schema Requirements:**
|
||||
- Exactly 1 H1 heading (document title)
|
||||
- 3-30 H2 headings (major sections)
|
||||
- 0-50 H3 headings (subsections)
|
||||
- 5-500 paragraphs (content)
|
||||
- 1-50 code blocks (examples)
|
||||
- 10-500 emphasis elements (commands/arguments)
|
||||
|
||||
### `markdown-schema-validation.1.md`
|
||||
|
||||
A comprehensive manual page (section 7) documenting MarkiTect's markdown schema validation system.
|
||||
|
||||
**Sections Include:**
|
||||
- SYNOPSIS - Command syntax reference
|
||||
- DESCRIPTION - How schema validation works
|
||||
- SCHEMA STRUCTURE - JSON Schema format details
|
||||
- COMMANDS - Schema management and validation commands
|
||||
- WORKFLOW - Step-by-step validation workflows
|
||||
- VALIDATION RULES - What schemas validate
|
||||
- ERROR HANDLING - Understanding validation errors
|
||||
- SCHEMA DESIGN - Best practices and anti-patterns
|
||||
- INTEGRATION - CI/CD, git hooks, build systems
|
||||
- EXAMPLES - Practical usage demonstrations
|
||||
- Plus standard manpage sections: FILES, EXIT STATUS, ENVIRONMENT, SEE ALSO, etc.
|
||||
|
||||
**Statistics:**
|
||||
- 19 H2 sections
|
||||
- 24 H3 subsections
|
||||
- 147 paragraphs
|
||||
- 23 code examples
|
||||
- 105 emphasis markers
|
||||
|
||||
## Running the Example
|
||||
|
||||
### 1. Validate the Manual Against the Schema
|
||||
|
||||
Verify that the manual conforms to the manpage schema:
|
||||
|
||||
```bash
|
||||
cd examples/manpages
|
||||
|
||||
markitect validate markdown-schema-validation.1.md \
|
||||
--schema markdown-manpage-schema.json
|
||||
```
|
||||
|
||||
Expected output: ✅ **VALID** - Document structure matches schema requirements
|
||||
|
||||
### 2. Show Detailed Validation
|
||||
|
||||
See detailed validation information:
|
||||
|
||||
```bash
|
||||
markitect validate markdown-schema-validation.1.md \
|
||||
--schema markdown-manpage-schema.json \
|
||||
--detailed-errors
|
||||
```
|
||||
|
||||
### 3. Generate Schema from the Manual
|
||||
|
||||
Analyze the manual's actual structure:
|
||||
|
||||
```bash
|
||||
markitect schema-generate markdown-schema-validation.1.md \
|
||||
--output actual-structure-schema.json
|
||||
|
||||
cat actual-structure-schema.json
|
||||
```
|
||||
|
||||
Compare the generated schema with the manpage schema to see how the manual conforms.
|
||||
|
||||
### 4. Examine AST Structure
|
||||
|
||||
View the parsed structure of the manual:
|
||||
|
||||
```bash
|
||||
markitect ast-show markdown-schema-validation.1.md --format tree
|
||||
```
|
||||
|
||||
Or in compact format:
|
||||
|
||||
```bash
|
||||
markitect ast-show markdown-schema-validation.1.md --format compact | head -50
|
||||
```
|
||||
|
||||
### 5. Store Schema for Reuse
|
||||
|
||||
Add the manpage schema to MarkiTect's database:
|
||||
|
||||
```bash
|
||||
markitect schema-ingest markdown-manpage-schema.json
|
||||
markitect schema-list
|
||||
```
|
||||
|
||||
### 6. Validate Other Manpages
|
||||
|
||||
Use the schema to validate other manual pages in the project:
|
||||
|
||||
```bash
|
||||
markitect validate ../../docs/manuals/markitect.1.md \
|
||||
--schema markdown-manpage-schema.json
|
||||
|
||||
markitect validate ../../docs/manuals/issue.1.md \
|
||||
--schema markdown-manpage-schema.json
|
||||
```
|
||||
|
||||
### 7. Generate Manpage Template
|
||||
|
||||
Create a template for new manpages:
|
||||
|
||||
```bash
|
||||
markitect generate-stub markdown-manpage-schema.json \
|
||||
--output new-manpage-template.md
|
||||
|
||||
cat new-manpage-template.md
|
||||
```
|
||||
|
||||
## What This Example Demonstrates
|
||||
|
||||
### 1. Schema-Driven Documentation
|
||||
|
||||
The manpage schema defines what a valid Unix manual page looks like:
|
||||
|
||||
- Required structural elements (title, synopsis, description)
|
||||
- Heading hierarchy constraints
|
||||
- Content density requirements (minimum paragraphs, code examples)
|
||||
- Formatting conventions (bold commands, italic arguments)
|
||||
|
||||
### 2. Self-Validating System
|
||||
|
||||
The schema validation manual validates against the manpage schema, proving:
|
||||
|
||||
- The schema is practical and usable
|
||||
- The manual follows manpage conventions
|
||||
- Schema validation works as documented
|
||||
- The system is reliable enough to document itself
|
||||
|
||||
### 3. Structural vs Semantic Validation
|
||||
|
||||
The schema validates **structure**, not **content**:
|
||||
|
||||
- ✅ Validates: Correct number of sections, heading levels, code examples present
|
||||
- ❌ Does not validate: Grammar, code correctness, factual accuracy, logical flow
|
||||
|
||||
This distinction is crucial for understanding what schemas can and cannot do.
|
||||
|
||||
### 4. Reusable Patterns
|
||||
|
||||
The manpage schema is a reusable pattern that can:
|
||||
|
||||
- Validate any Unix-style manual page
|
||||
- Enforce documentation consistency across a project
|
||||
- Generate templates for new documentation
|
||||
- Integrate into CI/CD pipelines for quality checks
|
||||
|
||||
### 5. Custom Schema Extensions
|
||||
|
||||
The schema demonstrates MarkiTect's custom extensions:
|
||||
|
||||
```json
|
||||
"x-markitect-required-sections": [
|
||||
"SYNOPSIS",
|
||||
"DESCRIPTION"
|
||||
],
|
||||
"x-markitect-recommended-sections": [
|
||||
"OPTIONS",
|
||||
"EXAMPLES",
|
||||
"SEE ALSO"
|
||||
],
|
||||
"x-markitect-conventions": {
|
||||
"heading_case": "UPPERCASE for H2 sections",
|
||||
"command_format": "Bold with **command**",
|
||||
"argument_format": "Italic with *ARG*"
|
||||
}
|
||||
```
|
||||
|
||||
These extensions provide metadata about schema intent and conventions beyond structural validation.
|
||||
|
||||
## Validation Workflow Demonstrated
|
||||
|
||||
This example shows the complete schema validation workflow:
|
||||
|
||||
### Step 1: Schema Creation
|
||||
- Analyze existing manpages (markitect.1.md, issue.1.md)
|
||||
- Identify common structural patterns
|
||||
- Generate base schema from example document
|
||||
- Refine schema to be flexible yet meaningful
|
||||
|
||||
### Step 2: Schema Refinement
|
||||
- Adjust minItems/maxItems for appropriate ranges
|
||||
- Add custom MarkiTect extensions
|
||||
- Include heading patterns and conventions
|
||||
- Balance strictness with flexibility
|
||||
|
||||
### Step 3: Document Creation
|
||||
- Write document following schema structure
|
||||
- Use template generated from schema as starting point
|
||||
- Ensure all required sections present
|
||||
- Include appropriate code examples and formatting
|
||||
|
||||
### Step 4: Validation
|
||||
- Validate document against schema
|
||||
- Review validation errors if any
|
||||
- Fix structural issues
|
||||
- Re-validate until passing
|
||||
|
||||
### Step 5: Iteration
|
||||
- Refine schema based on validation experience
|
||||
- Adjust constraints for real-world use cases
|
||||
- Document lessons learned
|
||||
- Share schema for reuse
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
Add to `.github/workflows/docs.yml` or similar:
|
||||
|
||||
```yaml
|
||||
- name: Validate Manpages
|
||||
run: |
|
||||
for manpage in docs/manuals/*.md; do
|
||||
markitect validate "$manpage" \
|
||||
--schema examples/manpages/markdown-manpage-schema.json \
|
||||
|| exit 1
|
||||
done
|
||||
```
|
||||
|
||||
### Pre-commit Hook
|
||||
|
||||
Add to `.git/hooks/pre-commit`:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
changed_manpages=$(git diff --cached --name-only --diff-filter=ACM | grep 'docs/manuals/.*\.md$')
|
||||
|
||||
for manpage in $changed_manpages; do
|
||||
markitect validate "$manpage" \
|
||||
--schema examples/manpages/markdown-manpage-schema.json \
|
||||
--quiet || {
|
||||
echo "Manpage validation failed: $manpage"
|
||||
markitect validate "$manpage" \
|
||||
--schema examples/manpages/markdown-manpage-schema.json \
|
||||
--detailed-errors
|
||||
exit 1
|
||||
}
|
||||
done
|
||||
```
|
||||
|
||||
### Makefile Integration
|
||||
|
||||
Add to project `Makefile`:
|
||||
|
||||
```makefile
|
||||
.PHONY: validate-manpages
|
||||
validate-manpages:
|
||||
@echo "Validating manual pages..."
|
||||
@for manpage in docs/manuals/*.md; do \
|
||||
markitect validate "$$manpage" \
|
||||
--schema examples/manpages/markdown-manpage-schema.json \
|
||||
|| exit 1; \
|
||||
done
|
||||
@echo "✅ All manpages valid"
|
||||
|
||||
.PHONY: docs
|
||||
docs: validate-manpages
|
||||
# Continue with doc generation...
|
||||
```
|
||||
|
||||
## Key Lessons from This Example
|
||||
|
||||
### 1. Start with Real Documents
|
||||
|
||||
The manpage schema was created by analyzing existing manpages (markitect.1.md, issue.1.md), not designed in isolation. This ensures the schema reflects real-world usage.
|
||||
|
||||
### 2. Use Ranges, Not Exact Counts
|
||||
|
||||
The schema uses ranges like `5-500 paragraphs` instead of exact counts. This provides flexibility while still enforcing quality standards.
|
||||
|
||||
### 3. Required vs Recommended
|
||||
|
||||
The schema distinguishes between required sections (SYNOPSIS, DESCRIPTION) and recommended sections (EXAMPLES, SEE ALSO), allowing flexibility where appropriate.
|
||||
|
||||
### 4. Validate Structure, Not Semantics
|
||||
|
||||
Schemas validate document structure, not content quality. Grammar checking, code correctness, and factual accuracy require other tools.
|
||||
|
||||
### 5. Progressive Refinement
|
||||
|
||||
Schemas should evolve based on validation experience. Start loose, tighten based on actual needs, never over-specify.
|
||||
|
||||
### 6. Documentation is Essential
|
||||
|
||||
The schema includes extensive metadata about conventions and intent through custom extensions, making it self-documenting.
|
||||
|
||||
## Extending This Example
|
||||
|
||||
### Create Schema Variants
|
||||
|
||||
Create specialized schemas for different manpage types:
|
||||
|
||||
```bash
|
||||
# For command manpages (section 1)
|
||||
cp markdown-manpage-schema.json command-manpage-schema.json
|
||||
# Edit to require COMMANDS section
|
||||
|
||||
# For format manpages (section 5)
|
||||
cp markdown-manpage-schema.json format-manpage-schema.json
|
||||
# Edit to require FORMAT section
|
||||
|
||||
# For convention manpages (section 7)
|
||||
cp markdown-manpage-schema.json convention-manpage-schema.json
|
||||
# Edit to be more flexible
|
||||
```
|
||||
|
||||
### Validate Your Own Documentation
|
||||
|
||||
Apply the manpage schema to your project:
|
||||
|
||||
```bash
|
||||
# Validate README
|
||||
markitect validate README.md \
|
||||
--schema markdown-manpage-schema.json
|
||||
|
||||
# May need adjustments for non-manpage docs
|
||||
```
|
||||
|
||||
### Generate Schema Family
|
||||
|
||||
Create schemas for related document types:
|
||||
|
||||
- API documentation schema
|
||||
- Tutorial schema
|
||||
- RFC/specification schema
|
||||
- Architecture decision record (ADR) schema
|
||||
|
||||
Each can follow similar validation principles while enforcing type-specific structure.
|
||||
|
||||
## Further Reading
|
||||
|
||||
- **markdown-schema-validation.1.md** - Complete reference for schema validation
|
||||
- **../../docs/manuals/markitect.1.md** - MarkiTect command reference
|
||||
- **JSON Schema Specification** - https://json-schema.org/
|
||||
- **Unix Manual Page Conventions** - `man 7 man-pages` on Unix systems
|
||||
|
||||
## Validation Results
|
||||
|
||||
This example has been validated to confirm:
|
||||
|
||||
✅ Manual validates against manpage schema
|
||||
✅ Schema is well-formed JSON Schema draft-07
|
||||
✅ All required sections present in manual
|
||||
✅ Heading hierarchy follows Unix conventions
|
||||
✅ Code examples demonstrate actual usage
|
||||
✅ Structure matches defined constraints
|
||||
|
||||
## License
|
||||
|
||||
Part of the MarkiTect project. Licensed under MIT License.
|
||||
|
||||
---
|
||||
|
||||
**Note**: This example represents a complete, production-ready use case of MarkiTect's schema validation system. The files can be used as-is or adapted for your own documentation requirements.
|
||||
Reference in New Issue
Block a user