markitect-main/examples/manpages/README.md

# 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

### Schema File

The manpage schema is now managed in MarkiTect's schema registry:
- **Schema Name**: `manpage-schema-v1.0.md`
- **Location**: `markitect/schemas/manpage-schema-v1.0.md`
- **Format**: Markdown with embedded JSON (following schema-of-schemas standard)

This schema defines 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. List Available Schemas

View all registered schemas (including the manpage schema):

```bash
markitect schema-list
```

You should see `manpage-schema-v1.0.md` listed with a number.

### 2. Validate the Manual Against the Schema

Verify that the manual conforms to the manpage schema using the new multi-schema validation:

```bash
cd examples/manpages

# Validate by schema filename (from registry)
markitect schema-validate manpage-schema-v1.0.md

# Or validate by number (if schema is #2 in the list)
markitect schema-validate 2

# Or validate a specific document file
markitect validate markdown-schema-validation.1.md \
    --schema manpage-schema-v1.0.md
```

Expected output: ✅ **VALID** - Document structure matches schema requirements

### 3. Show Detailed Validation

See detailed validation information:

```bash
markitect schema-validate manpage-schema-v1.0.md --detailed-errors
```

### 4. Validate Multiple Schemas

Validate all registered schemas at once:

```bash
# Validate all schemas
markitect schema-validate --all

# Validate a range of schemas
markitect schema-validate 1-3

# Validate specific schemas
markitect schema-validate 1,3,5
```

### 5. Examine the Schema

View the manpage schema in markdown format:

```bash
markitect schema-get manpage-schema-v1.0.md

# Or view the file directly
cat ../../markitect/schemas/manpage-schema-v1.0.md
```

### 6. Validate Other Manpages

Use the schema to validate other manual pages in the project:

```bash
# Validate using schema name from registry
markitect validate ../../docs/manuals/markitect.1.md \
    --schema manpage-schema-v1.0.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 manpage-schema-v1.0.md \
        || 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 manpage-schema-v1.0.md \
        --quiet || {
        echo "Manpage validation failed: $manpage"
        markitect validate "$manpage" \
            --schema manpage-schema-v1.0.md \
            --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 manpage-schema-v1.0.md \
			|| 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 markitect/schemas/manpage-schema-v1.0.md command-manpage-schema-v1.0.md
# Edit to require COMMANDS section
markitect schema-validate ./command-manpage-schema-v1.0.md
markitect schema-ingest ./command-manpage-schema-v1.0.md

# For format manpages (section 5)
cp markitect/schemas/manpage-schema-v1.0.md format-manpage-schema-v1.0.md
# Edit to require FORMAT section

# For convention manpages (section 7)
cp markitect/schemas/manpage-schema-v1.0.md convention-manpage-schema-v1.0.md
# Edit to be more flexible
```

### Validate Your Own Documentation

Apply the manpage schema to your project:

```bash
# Validate README (if it follows manpage structure)
markitect validate README.md \
    --schema manpage-schema-v1.0.md

# 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.