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

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