BEASTIE(1)                  General Commands Manual                 BEASTIE(1)

NAME
       beastie

SYNOPSIS
       beastie [-Ehqrv] [-d int] [-e expr] [-I input] [-O output] [-l
       loadfile] [-L language] [-m module] [inputfile [args/opts...]]

       beastie [-v] -V

DESCRIPTION
       beastie is an experimental BibTeX processor.

       Beastie is intended to be an experiment in supporting a decent language
       for processing BibTeX bibliographies (by which I mean a language which
       isn't the .bst language, which is perhaps a little too amusing for
       everyday use; and by which I mean more specifically Scheme ).  As a
       functionality goal, it also implements the .bst language (in Scheme).

       As far as the .bst language is concerned, it aims to support it quite
       fully, in the sense that it will produce the same resuls as BibTeX, for
       the standard styles.  However it doesn't support it slavishly, and
       there are some deviations noted in the main documentation.

       The behaviour depends on the input file.  If there is no input file,
       then the program reads from stdin, expecting an input format indicated
       by the -I input-type option.  The default input-type is (currently)
       .bib .

       If the input file is foo.aux then it will parse the aux file, looking
       for \citation , \bibdata and \bibstyle commands, just like BibTeX, and
       process the bibliography with the indicated `.bst` program.  That is,
       this is (very tentatively) intended to be a drop-in alternative to the
       bibtex program.

       If the input file is foo.scm [args...]  then the program foo.scm is
       interpreted as Scheme, extended with suitable BibTeX-friendly
       functions.  See the associated documentation for a summary of these.
       Any args/opts...  are available within the program in the global
       variable *command-line*.

       Re args/opts , note the distinction between options for the beastie
       program, which appear before this .scm script argument, and arguments
       and options for the script, which appear after it.

       If the input file is foo.md then it is interpreted as a Markdown file.
       The program contains a basic Markdown parser.  It's ambitions are
       modest – it is not intended to be a comprehensive implementation.  The
       markdown output is in the form of ‘x-expressions’ – XML represented as
       scheme s-expressions, which is easy to wrangle (see the documentation
       for the xexpr-* functions).  If you add the option -O xml or -O xhtml
       then the output will instead be written as XHTML; and if you add option
       -O python the output will be written in a form which is readable by
       Python (specifically, it's the format wrangled by
       https://pypi.org/project/listxml/ which may be of interest in any
       case).

       Similarly, if the input file is foo.json then it is interpreted as a
       JSON file, parsed, and written out as an s-expression.  This is
       sometimes useful for testing purposes.  The goal here is to parse valid
       JSON correctly; the parser is rather strict and supports no extensions.

       If the input file is foo.bib then the given file will be parsed and
       written as a sequence of s-expressions.  With the option -O bib or -O
       json it'll be written as .bib or JSON instead.  In each case, the
       format should currently be regarded as provisional.

OPTIONS
       -d integer
              Output lots of debugging information (not generally useful).
              The option -d-1 turns on all debugging; to be more selective,
              see the source-code (but eg, -d32 turns on only markdown block
              debugging).

       -e expr
              Evaluate the given scheme expression.  Currently, this is only
              evaluated for side-effects, so that -e '(define x 1)' will not
              define the variable in the top-level.

       -E     Force an Emacs-compatible REPL (see the mention of
              BEASTIE_LOAD_PATH below).

       -h     Display help.

       -I input-type
              Indicate the input type.  Usually this is determined by the file
              extension on the input file, but this option will override that
              default.

              If the file extension is unrecognised, or if there is no input
              specified and the program is reading from stdin, then the type
              of input must be specified if it is not the default .bib .  The
              value can be bib for BibTeX input, bst for .bst programs (this
              is intended to parse .bst programs and dump a parse-tree, and
              will be of interest to very few people), scm for scheme
              programs, aux for LaTeX .aux files, .json for JSON files, or md
              for Markdown.

              As a special case, if the inputfile doesn't end in .aux , but
              there does exist a file when we append .aux , then we use that
              file as a LaTeX aux-file (this is intended to mimic BibTeX
              behaviour).

       -l loadfile
              Load the file of scheme code before starting processing.

       -L language
              The language/locale to use when sorting (some) strings.  This
              should be something like en_GB .  This is currently
              underspecified in this documentation; more detail should appear
              in future versions.  See also BEASTIE_LOCALE below.

       -m module-name
              Load the given internal module, as if by (module 'module-name)

       -O output-type
              Usually, the output format is implied by the input format, but
              in a couple of cases there are alternatives.  The output formats
              are scm , json , bstscm , xml (XML body), xhtml (whole XHTML
              document), python , and bib .  If the input is not writable as
              the requested format, then the specifier is ignored and the
              default used.

              The scm format refers to scheme s-expressions; bstscm is a
              version of .bst files in that form.  The xml format is generally
              in fact XHTML.

       -q     Run quietly

       -r     Start in a simple REPL.  For a more sophisticated REPL see the
              mention of BEASTIE_LOAD_PATH below.  If this option is present,
              and the program is reading from stdin, then it will expect to
              read .scm input.

              If the program is started with program name repl , then it will
              start in this REPL mode.  In this case the option -emacs is
              recognised and is equivalent to -E (a special case: Emacs sends
              this option by default).

       -v     Chatter more.

       -V     Show the program version, and exit.

S7 SCHEME
       This program is implemented in an embedded version of s7 Scheme, which
       you can find more information about at
       https://ccrma.stanford.edu/software/snd/snd/s7.html

ENVIRONMENT
       BEASTIE_LOAD_PATH
              If present, this indicates a colon-separated sequence of
              directories to be included in the s7 *load-path* variable.  If
              this includes a directory containing the s7 libc.so then useful
              s7 functionality is available (eg, an alternative interface to
              regexps, but see the s7 docs for fuller discussion).  If this
              finds libc_s7.so then the REPL will be slightly more full-
              featured than otherwise (but not compatible with an Emacs
              inferior scheme, so the option -E is available, to force a
              compatible version in this situation).

       BEASTIE_DEBUG_FLAGS
              If set to a number, then this is equivalent to setting debug
              flags via -d (qv).

       BEASTIE_LOCALE
              This indicates the language/locale to be used for sorting (some)
              strings.  This is currently underspecified in this
              documentation; more detail should appear in future versions.
              See also option -L .

              A comma-separated list of BibTeX fields to ‘untexify’ during
              parsing, replacing, eg, {\'e} with é .  The default is (in
              effect) author,editor,title .  Setting this to the empty string
              disables such escaping.

              By default, beastie will untexify the contents of (selected)
              BibTeX fields at all brace levels, rather than the BibTeX
              behaviour of doing so only at brace-level 1.  Setting this
              environment variable to anything non-empty restores the BibTeX
              behaviour.

       Beastie respects the standard kpse BIBINPUTS and BSTINPUTS environment
       variables.

SEE ALSO
       The canonical Beastie URL is https://purl.org/nxg/dist/beastie (please
       use this, rather than the page it redirects to, in any persistent
       references to the software).

EXIT VALUE
       The program exits with status 0 on success, or non-zero on error.

BUGS
       Probably.  See https://codeberg.org/nxg/beastie

AUTHOR
       Norman Gray, https://nxg.me.uk

                                                                    BEASTIE(1)
