what are .rst files?

While debugging Bro, during one of the runs it created:

-rw-r--r-- 1 vern admin 0 Jul 19 11:39 <internal error>^<stdin>.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 bro.bif.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 bro.init.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 const.bif.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 event.bif.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^logging^__load__.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^logging^base.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^logging^plugins^ascii.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^notice^__load__.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^notice^base.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^notice^weird.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^packet-filter^__load__.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^packet-filter^base.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 frameworks^packet-filter^netstats.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 logging.bif.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 reporter.bif.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 site.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 strings.bif.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 types.bif.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 utils^conn_ids.rst
-rw-r--r-- 1 vern admin 0 Jul 19 11:39 utils^pattern.rst

(Note the charmingly named "<internal error>^<stdin>.rst"!)

What's up with this?

    Vern

Output from the Documentation framework?

Output from the Documentation framework?

Well, if you want to call zero-length files "documentation" :-).

Yeah, I must have tripped across one of Bro's flags to do that. That said,
(1) why are these files empty, and (2) why does one of them have the name
<internal error>^<stdin>.rst ?

    Vern

> Output from the Documentation framework?

Yes. (the command line args to toggle it are -Z and --doc-scripts)

(1) why are these files empty,

because bro crashed at a point point during parsing, but before writing them?

and (2) why does one of them have the name <internal error>^<stdin>.rst

The <internal error> part is a bug, it should be called just <stdin>.rst
(meaning generated documentation for scripting given to bro on standard input)

- Jon

because bro crashed at a point point during parsing, but before writing them?

Ah - yeah, pretty much. I reproduced the behavior - running bro -Z and
then issuing ^C to terminate it results in zero-length files. If instead
I provide it with any valid input, then I get the generated files.

The <internal error> part is a bug, it should be called just <stdin>.rst
(meaning generated documentation for scripting given to bro on standard input)

Okay, I've filed a ticket on it.

    Vern