markitect-main/examples/schemas/manpage-schema-v1.md

# Manpage Schema v1.0

**Schema ID:** `https://markitect.dev/schemas/manpage/v1`
**Version:** 1.0.0
**Status:** Stable
**Created:** 2026-01-04
**Document Types:** Manual pages, CLI documentation

## Overview

This schema validates Unix/Linux manual page documentation following standard conventions. Manual pages (man pages) are the traditional form of documentation for Unix commands and system calls.

## Typical Structure

A well-formed manual page includes:

1. **NAME** - Command name and one-line description
2. **SYNOPSIS** - Command syntax showing all options
3. **DESCRIPTION** - Detailed explanation of what the command does
4. **OPTIONS** - Description of each command-line option
5. **EXAMPLES** - Practical usage examples
6. **SEE ALSO** - Related commands or documentation

## Usage

### Validate a Manpage

```bash
markitect validate mycommand.1.md --schema manpage-schema-v1
```

### Generate Manpage Template

```bash
markitect generate-stub manpage-schema-v1.json --output newcommand.1.md
```

### Refine Existing Schema

```bash
markitect schema-refine manpage-schema-v1.json --loosen-counts
```

## Examples

Complete examples can be found in:
- [examples/manpages/markdown-schema-validation.1.md](../manpages/markdown-schema-validation.1.md)

## Validation Rules

### Required Sections (Level 2 Headings)

**NAME**
- **Classification:** Required
- **Content:** Command name in bold followed by brief description
- **Format:** `**command** - one line description`
- **Example:** `**markitect** - validate and analyze markdown documents`

**SYNOPSIS**
- **Classification:** Required
- **Content:** Command syntax with all options
- **Min code blocks:** 1
- **Max paragraphs:** 3
- **Example:**
  ```bash
  markitect [OPTIONS] COMMAND [ARGS]
  ```

**DESCRIPTION**
- **Classification:** Required
- **Content:** Detailed explanation of the command
- **Min paragraphs:** 2
- **Min words:** 50

### Recommended Sections

**OPTIONS**
- **Classification:** Recommended
- **Content:** Definition list or table of command-line options
- **Format:** Each option as `**--option** *type*` followed by description

**EXAMPLES**
- **Classification:** Recommended
- **Content:** Practical usage examples with explanations
- **Min code blocks:** 1
- **Benefit:** Greatly improves documentation usability

### Optional Sections

**ENVIRONMENT**
- Environment variables affecting command behavior

**FILES**
- Important files used or created by the command

**EXIT STATUS**
- Explanation of exit codes

**BUGS**
- Known issues or limitations

**AUTHORS**
- Command authors and contributors

**SEE ALSO**
- Related commands or documentation

## Schema Definition

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://markitect.dev/schemas/manpage/v1",
  "version": "1.0.0",
  "title": "Unix Manual Page Schema",
  "description": "Schema for validating Unix/Linux manual page documentation",
  "type": "object",
  "properties": {
    "headings": {
      "type": "object",
      "properties": {
        "level_1": {
          "type": "array",
          "description": "Document title (command name)",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "pattern": ".*"
              }
            }
          },
          "minItems": 1,
          "maxItems": 1
        },
        "level_2": {
          "type": "array",
          "description": "Section headings",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "enum": [
                  "NAME",
                  "SYNOPSIS",
                  "DESCRIPTION",
                  "OPTIONS",
                  "EXAMPLES",
                  "ENVIRONMENT",
                  "FILES",
                  "EXIT STATUS",
                  "BUGS",
                  "AUTHORS",
                  "SEE ALSO"
                ]
              }
            }
          },
          "minItems": 3,
          "maxItems": 20
        }
      },
      "required": ["level_1", "level_2"]
    },
    "paragraphs": {
      "type": "array",
      "description": "Paragraph content",
      "items": {
        "type": "object",
        "properties": {
          "content": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "minItems": 3
    },
    "code_blocks": {
      "type": "array",
      "description": "Code examples and command syntax",
      "items": {
        "type": "object",
        "properties": {
          "language": {
            "type": "string"
          },
          "content": {
            "type": "string"
          }
        }
      },
      "minItems": 1
    }
  },
  "required": ["headings", "paragraphs"],
  "x-markitect-sections": {
    "NAME": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Command name in bold followed by brief description",
      "pattern": "\\*\\*[a-z-]+\\*\\*.*",
      "error_if_missing": "NAME section is required in all manual pages"
    },
    "SYNOPSIS": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Command syntax showing all options and arguments",
      "min_code_blocks": 1,
      "error_if_missing": "SYNOPSIS section is required to show command usage"
    },
    "DESCRIPTION": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Detailed explanation of what the command does and when to use it",
      "min_paragraphs": 2,
      "min_words": 50,
      "error_if_missing": "DESCRIPTION section is required for detailed explanation"
    },
    "OPTIONS": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Description of each command-line option with syntax and explanation",
      "warning_if_missing": "OPTIONS section recommended for commands with options"
    },
    "EXAMPLES": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Practical usage examples with explanations",
      "min_code_blocks": 1,
      "warning_if_missing": "EXAMPLES greatly improve documentation usability"
    },
    "ENVIRONMENT": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Environment variables that affect command behavior"
    },
    "FILES": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Important files used or created by the command"
    },
    "SEE ALSO": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Related commands or documentation references"
    }
  },
  "x-markitect-content-control": {
    "name_section": {
      "required_pattern": "\\*\\*[a-z-]+\\*\\*",
      "description": "Command name must be in bold",
      "example": "**markitect** - validate and analyze markdown documents"
    },
    "synopsis_section": {
      "min_code_blocks": 1,
      "code_block_language": "bash",
      "description": "Must include at least one code block showing command syntax"
    },
    "description_section": {
      "min_paragraphs": 2,
      "min_words": 50,
      "description": "Detailed description with at least 50 words across 2+ paragraphs"
    }
  },
  "x-markitect-metadata": {
    "schema-type": "document-schema",
    "domain": "manpage",
    "document-types": ["manual-page", "man-page", "cli-documentation"],
    "version": "1.0.0",
    "author": "MarkiTect Project",
    "created": "2026-01-04",
    "updated": "2026-01-04",
    "example": "examples/manpages/markdown-schema-validation.1.md",
    "supersedes": null,
    "superseded-by": null
  }
}
```

## Version History

### v1.0.0 (2026-01-04)
- Initial stable release
- Validates standard manpage sections
- Classification system (required/recommended/optional)
- Content control for NAME, SYNOPSIS, DESCRIPTION
- MarkiTect extensions for improved validation

## Future Enhancements

Planned for v2.0:
- Multi-language support (internationalization)
- Extended sections (DIAGNOSTICS, SECURITY, STANDARDS)
- Cross-reference validation
- Version-specific section variants (man1, man5, man8)

## Contributing

To suggest improvements to this schema:
1. Open an issue describing the enhancement
2. Provide example documents demonstrating the need
3. Propose specific schema changes

## License

This schema is part of the MarkiTect project and follows the same license.