# Man Pages
Man pages for `git-lfs` are automatically generated. Here is
how it works:
- The `NAME`, `SYNOPSIS`, `DESCRIPTION` and `OPTIONS` are automatically
generated by clap, using `clap_mangen`.
- Any other sections are injected into this generated man output, from
the markdown sources in this folder. They are organized into
`man/<subcommand>/<section>.md`.
- The individual sections are defined in `src/man.rs` in the `cli/` crate.
- A common `REPORTING BUGS` section is appended to every page from
`reporting_bugs.md` — change the wording or URL there and every
page picks it up.
- Pages that aren't backed by a clap subcommand (e.g. `git-lfs-config(5)`)
are listed in the `SYNTHETIC_PAGES` array in `xtask/src/lib.rs`.
Their extras live alongside subcommand extras in `<topic>/`.
- The man page generation doesn't support the full markdown syntax.
Only a subset of it is handled, which is currently paragraphs, bold,
italic, code spans, fenced code blocks, lists, definition lists,
and inline links. It is possible to add code to handle more syntax
as needed.
From these sections, both the mdbook documentation (in `docs/cmds`)
and the man pages are generated. Generation lives in the `xtask/`
crate.
## Generating
To generate the man pages, run:
cargo xtask gen-man
This will generate them to `target/man/`.
To generate/update the mdbook sources, run:
cargo xtask gen-md
This needs to be run any time you make changes to these sections.
There is a unit test which checks that they are up-to-date, which
will alert you if you need to re-run this.