Authoring schemas

Prohelp accepts several schema forms. The in-memory model is always the same Command tree; only the on-disk authoring format changes.

SDL (help.sdl)

Canonical structured schema. Nested section tags, option entries, locales, and content-ref for shared body files.

command "myapp" {
    title "My App"
    summary "Does a thing"
    homepage "https://example.com/myapp"
    docs "https://example.com/myapp/docs"
    issues "https://github.com/example/myapp/issues"

    section "usage" {
        summary "How to invoke"
        content-ref "docs/usage.adoc" { format "asciidoc" }
    }
}

content-ref formats: text, asciidoc / adoc, markdown / md, centrmark / cmk, sdl. When format is omitted, the path extension (.adoc, .md, .cmk, .sdl) selects the converter.

Whole-document Markdown / AsciiDoc / CentrMark

Author the entire schema as one of:

  • help.md / help.markdown — YAML frontmatter (--- … ---)

  • help.adoc / help.asciidoc — document title + :attr: header

  • help.cmk — CentrMark SDL frontmatter fence

Headings become sections (## / == → top-level; deeper headings nest).

---
name: myapp
title: My App
summary: Does a thing
homepage: https://example.com/myapp
docs: https://example.com/myapp/docs
issues: https://github.com/example/myapp/issues
---

# My App

## Usage

Run `myapp ?` for progressive help.

Preview:

prohelp examples/help.md ?
prohelp examples/help.adoc ?

Discovery (prohelp --as-help / shell help)

Beside the binary (and one parent directory), prohelp looks for, in order:

  1. help.sdl

  2. help.md / help.markdown

  3. help.adoc / help.asciidoc

  4. help.cmk

  5. <cmd>.help.sdl / .help.md / .help.adoc / .help.cmk

Essential metadata notices

After loading a schema, prohelp warns only when these essential discovery fields are empty:

  • homepage

  • docs

  • issues

If a field is set in SDL or frontmatter, it is never warned about. summary, description, title, and issues-ai do not trigger this notice.

Each missing essential field gets a DuckDuckGo link seeded with the binary name/path.

When no prohelp schema is found at all, prohelp prints a separate notice nudging a feature request upstream (also with a filled search link), then falls back to info / man / --help.

Suppress notices with PROHELP_QUIET=1.

Init, fill, and check

prohelp init writes a shaped help.sdl immediately (empty summaries and discovery URLs). It does not wait on a questionnaire.

prohelp init --name myapp
prohelp init path/to/help.sdl --force
prohelp init --name myapp --fill    # then the questionnaire

prohelp fill edits that file. In a TTY it asks for empty fields. In CI or pipes, pass --set:

prohelp fill help.sdl --set summary="Does a thing" --set homepage=https://example.com

prohelp check prints completeness findings (empty summaries, missing homepage/docs/issues, empty sections, line budgets). Exit 0 while findings are warnings.

--strict promotes those warnings to failures. That is the ship gate. Prohelp cannot enable it in someone else’s pipeline; they add a job that calls the reusable workflow:

name: Prohelp
on: [push, pull_request]
jobs:
  check:
    uses: openshellorg/prohelp/.github/workflows/check-schema.yml@main
    with:
      schema-path: help.sdl
      strict: true

Pin @vX.Y.Z when you depend on a release tag instead of main.