# docgen — generating the interactive mini-help

`src/frontend/minihelp_gen.c` is **generated**, not written by hand. It is the table
`com_help()` serves when you type `help <command>` in the interactive shell. Edit the
manual, regenerate, rebuild — never edit `minihelp_gen.c` directly, your change is lost on
the next regeneration.

## Regenerating

Run this from the top of the source tree:

```sh
docgen/gen_minihelp.py docs/reference_manual/ngspice_manual.html \
    --cktsopt  src/spicelib/analysis/cktsopt.c \
    --cktntask src/spicelib/analysis/cktntask.c \
    --c        src/frontend/minihelp_gen.c
```

It should report two things:

```
harvested 95 .options from the C sources
wrote src/frontend/minihelp_gen.c: 164 sections
```

**`--cktsopt` and `--cktntask` are not optional.** Leave them off and the generator still
succeeds, still writes a well-formed file — and silently drops every `.option` entry, about
1100 lines, roughly 45% of the content. There is no error and the build does not break; you
only find out when `help reltol` says nothing. If the section count comes back near 69
instead of 164, that is what happened.

The three `collision:` lines it prints are expected. Two manual sections legitimately claim
the same keyword (`print`, `if`, `else`); first one wins.

## Where the content comes from

| source | what it contributes |
|---|---|
| `docs/reference_manual/ngspice_manual.html` | one entry per `<div class="cmd">`: its Synopsis, Description and See also fields |
| `src/spicelib/analysis/cktsopt.c` | the `.option` table — names, types, descriptions |
| `src/spicelib/analysis/cktntask.c` | each option's real default |

Every `<table>` in a Description is rendered as `name [default] - effect` lines, so a table
is the way to document a set of things (the `.option` list, `hier_op`'s rung ladder and its
command-line options). All tables in a section are rendered, not just the first — `hier_op`
has two, and only rendering the first is how its options table went missing once.

## Checking your work

`--text` dumps the generated help as plain text without touching any C file, which is the
fast way to see what an entry will actually look like:

```sh
docgen/gen_minihelp.py docs/reference_manual/ngspice_manual.html --text | less
```

After regenerating, rebuild and confirm the text really reached the binary:

```sh
make -C src && strings src/ngspice | grep -- '--rshunt OHMS'
```

## Not included here

A second, unrelated proof-of-concept tool (`ngspice_docgen.py`) harvests the `.options`
table and `devhelp` output to report which options the manual never mentions. It is
one-shot analysis rather than a build input, it hardcodes absolute paths, and it needs the
separate `ngspice-manuals` LyX repo checked out, so it is deliberately not carried here.
