ldoc_cli

Run the command-line entry point for ldoc with escript arguments.

The entry point requires UTF-8 native filename encoding and configures only standard output and error for Unicode. It prints help or the absolute index path, sends diagnostics to standard error, and halts with status 0 for success or help, 2 for usage errors, and 1 for other failures. It is the only public function that halts the BEAM. The child rebar3 build is trusted and may execute project scripts, hooks, or compile-time code; target BEAM inspection itself does not load target modules.

Run one command without halting the caller.

Accepts proper Unicode character-list arguments for --help or build PROJECT --output FRESH_ROOT and its optional settings. Success is {ok, help} or {ok, IndexBinary} containing the absolute site/index.html path; expected failures return {error, Reason}. A build starts ldoc's required applications, reconciles the flat default-profile source/app/BEAM inventory, and compiles with a trusted child rebar3 process. Child compilation may run project scripts, hooks, and compile-time code. The tool VM inspects BEAM data without loading target modules. A CLI failure after output ownership can retain a partial tree for diagnosis.

Caller environment, code path, IO, and filename encoding are preserved. The caller group leader is restored after the existing bracketed EDoc diagnostic redirection. Shell argv, child-native decoding, filesystem paths, and printed text have distinct encoding boundaries.