\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro},
    eforms,aebxmp
]{aeb_pro}
\usepackage{graphicx,array,fancyvrb}
\usepackage{annot-pro}
\usepackage{aeb_mlink}
%\usepackage{myriadpro}
%\usepackage{calibri}

\usepackage[altbullet]{lucidbry}

\usepackage[ignorecfg,
    useselverses,useverses=docverses,fetchsubtr]{fetchbibpes}

\usepackage{xbmks}
\DeclareInitView{layoutmag={navitab:UseOutlines}}
\xbmksetup{colors={int=red},styles={intbf}}


\addtoBibles{YLT,ESV,NKJV}

\selectedVersesFrom
{
    {from=YLT,onlyverses={Gen 1:1-2}}
}

\begin{declareBVs}
\BV(Gal 1:15 NKJV) But when it pleased God, who separated me from my mother's womb and called me through His grace,\null
\BV(Gal 1:16 NKJV) to reveal His Son in me, that I might preach Him among the Gentiles, I did not immediately confer with flesh and blood,\null
\end{declareBVs}

\addtolength{\marginparwidth}{20pt}

\makeatletter
\setcounter{secnumdepth}{4}
\setcounter{tocdepth}{5}
\makeatletter
\renewcommand*{\theparagraph}{\texorpdfstring{\protect\P\protect\ }{\textparagraph}}
\renewcommand{\paragraph}
    {\renewcommand{\@seccntformat}[1]{\theparagraph}%
    \@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\color{\aeb@subsubsectioncolor}\bfseries}}
\renewcommand*\l@paragraph{\@dottedtocline{4}{5.0em}{1em}} %{7.0em}{4.1em}}

\renewenvironment{quote}[1][]
   {\def\@rgi{#1}\ifx\@rgi\@empty
    \let\rghtm\@empty\else\def\rghtm{\rightmargin\leftmargin}\fi
    \list{}{\rghtm} %{\rightmargin\leftmargin}%
    \item\relax}
   {\endlist}
\@ifundefined{l@tex@@@@driver}{\let\yyPC\relax}
    {\def\yyPC{\special{color: pop}}}
\makeatother
\renewcommand{\hproportionwebtitle}{.8}


\def\hardspace{{\fontfamily{cmtt}\selectfont\symbol{32}}}


%\usepackage{makeidx}
%\makeindex
\usepackage{acroman}
\edef\amtIndent{\the\parindent}
\setlength{\leftmargini}{\the\parindent}
\usepackage[active]{srcltx}

\urlstyle{tt}

\def\STRUT{\rule{0pt}{14pt}}


\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \textsf{bibpes} and \textsf{fetchbibpes} Packages
    \texorpdfstring{\\[1ex]\Large}{: }Inserting Bible Passages from \textsf{e-Sword}},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject=Documentation for the fetchbibpes and bibpes packages,
    talksite={\url{www.acrotex.net}},
    version={2.4.10, 2021/03/08},
    Keywords={LaTeX, e-sword, Bible passages, AcroTeX},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-31.25pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The fetchbibpes Bundle";
var manualfilename="Manual_BG_Print_fetchbib.pdf";
var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
var doc;
var buildIt=false;
if ( buildIt ) {
    console.println("Creating new " + manualfilename + " file.");
    doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
    var _path=this.path;
    var pos=_path.lastIndexOf("/");
    _path=_path.substring(0,pos)+"/"+manualfilename;
    \docSaveAs\newDO ({ cPath: _path });
    doc.closeDoc();
    doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
    f=doc.getField("ManualTitle");
    f.value=titleOfManual;
    doc.flattenPages();
    \docSaveAs\newDO({ cPath: manualfilename });
    doc.closeDoc();
} else {
    console.println("Using the current "+manualfilename+" file.");
}
var _path=this.path;
var pos=_path.lastIndexOf("/");
_path=_path.substring(0,pos)+"/"+manualfilename;
\addWatermarkFromFile({
    bOnTop:false,
    bOnPrint:false,
    cDIPath:_path
});
\executeSave();
\end{docassembly}


\begin{document}

\maketitle

\pdfbookmarkx[1]{Title Page}[action={\Named{FirstPage}}]{TitlePage}
\pdfbookmarkx[1]{Links to AcroTeX.Net}[action={/S/GoTo/D(undefined)},%
  color=magenta,style={bf}]{acrotex}
\belowpdfbookmarkx{http://www.acrotex.net}[action={\URI{http://www.acrotex.net}},%
  color=magenta,style={bf}]{home}
\belowpdfbookmarkx{http://blog.acrotex.net}[action={\URI{http://blog.acrotex.net}},%
  color=magenta,style={bf}]{blog}


\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}


\section{Introduction}

The motivation for this pair of packages (\pkg{bibpes} and \pkg{fetchbibpes})
came from my friend Thomas Price, who was preparing Bible studies using a
combination of the application \app{e-Sword}
(\mlurl{http://www.e-sword.net/}) and \LaTeX. He wanted a `database' of Bible
passages from which he could simply `fetch' passages into the {\LaTeX} source
file. To that end, the pair of packages \pkg{bibpes} and \pkg{fetchbibpes}
were written.
\begin{itemize}
    \item \pkg{bibpes} is the `database' part of the problem. Use the
        \app{e-Sword} application to copy and paste desired passages into
        an (empty) \EXT{TXT} file. Use \texttt{makebibpes.tex} to convert the
        \EXT{TXT} file to a \EXT{DEF} file formatted in a way that
        is usable by \pkg{fetchbibpes}.

    \item \pkg{fetchbibpes} is the `fetch' portion. Using the fetch
        commands of \pkg{fetchbibpes} to reference the passages to be
        typeset into the {\LaTeX} source.
\end{itemize}

\section{The \texorpdfstring{\protect\pkg{bibpes}}{bibpes} Package}

    The \textsf{bibpes} package (\underbar{bib}le
    \underbar passages from \underbar e-\underbar sword) takes a \EXT{TXT} file,
    and writes a \EXT{DEF} file suitable for use by the \pkg{fetchbibpes}
    package. The contents of the \EXT{TXT} file consists of Bible passages that
    have been pasted in from the \textsf{e-Sword} desktop application or the
    \textsf{e-sword} macro add-in to \textsf{Microsoft Word}. This package reads in
    that \EXT{TXT} file and writes a \EXT{DEF} file where each passage referenced
    is made into a text macro that expands to the passage.

    This package correctly processes Bible verses in the \emph{English language}. With the exception
    of German (using the German Elberfelder Bible (\texttt{GEB}), no other language has been tested.

    \paragraph*{Package options} The package has several options, listed in display that follows.
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=*()]
\usepackage[%
  infolder=*ameta(infolder),
  outfolder=*ameta(outfolder),
  txtfilein=*ameta(base_name_txt),
  deffileout=*ameta(base_name_def),
  build|!build
]{bibpes}
\end{Verbatim}
\paragraph*{Description of options}
\begin{description}

    \item[\texttt{infolder=\ameta{infolder}}] The value \ameta{infolder} is
        the path to the folder location of the \EXT{TXT} file to be
        processed. If \texttt{infolder} is not specified, the \EXT{TXT} file is
        assumed to be in the source folder of the \texttt{makebibpes.tex}
        file (more on this file later); otherwise, the \EXT{TXT} file should be
        found in \ameta{infolder}.

    \item[\texttt{outfolder=\ameta{outfolder}}] The value of
        \ameta{outfolder} is the path to the folder location where the \EXT{DEF}
        file is to be placed. If \texttt{outfolder} is not specified, the
        \EXT{DEF} file is placed in the source folder of the
        \texttt{makebibpes.tex} file (more on this file later); otherwise,
        the \EXT{DEF} file is placed in \ameta{outfolder}.

    \item[\texttt{txtfilein=\ameta{base\_name\_txt}}] is the base name of
        the input \texttt{TXT} file, do not add the extension. For example,
        \texttt{txtfilein=myverses}; the file \texttt{myverses.txt} must be
        located in the folder specified by \texttt{infolder} or in the current folder
        if \texttt{infolder} is not specified.

        A value for \texttt{txtfilein} is required for this package to do its
        thing; otherwise, this package does nothing.

    \item[\texttt{deffileout=\ameta{base\_name\_def}}] is the base name of
        the output \texttt{DEF} file, no not add the extension. If
        \texttt{deffileout} is not specified, then the base name of the
        output file is the same as the base name of the input file. The new
        \EXT{DEF} file is saved in the folder specified by the
        \texttt{deffileout} option, or if that option is not specified, it
        is saved in the current folder.

    \item[\texttt{build|!build}] Two esoteric options that determine
        whether the \EXT{DEF} file is created (\texttt{build}) or not
        (\texttt{!build}). The default is \texttt{build} and need not
        appear in the option list, except in contrast to \texttt{!build}.
        By default (\texttt{build}), \pkg{bibpes} takes \texttt{txtfilein}
        and produces \texttt{deffileout} file; when \texttt{!build} is
        specified, the \texttt{deffileout} file is not produced. See
        \hyperref[para:crtDEF]{Section~\ref*{para:crtDEF}} for additional remarks on \texttt{build}
        verses \texttt{!build}.


\end{description}


    \paragraph*{Steps to create a \EXT{DEF} file from a \EXT{TXT} file.}
    There are two steps (1) create a \EXT{TXT} file containing the Bible
    passages to be referenced; (2) run the \texttt{makebibpes.tex} file with
    \texttt{txtfilein} and \texttt{deffileout} set as desired. For step~(1)
    read \hyperref[s:Methods]{Section~\ref*{s:Methods}} on
    `\mlnameref[\linktxtcolor{webgreen}]{s:Methods}'; for step~(2), read the
    paragraph \Nameref{para:crtDEF}.

     \subsection{Methodologies}\label{s:Methods}

    To create a \EXT{TXT} file consisting of Biblical verses obtained from the \textsf{e-Sword}
    application, there are two methodologies to consider.

    \paragraph*{Methodology 1.} Work directly with the \textsf{e-Sword} desktop
    application, located at URL \url{http://www.e-sword.net/}. In this workflow, we copy and
    paste the verses directly into a \EXT{TXT} file.
    \begin{enumerate}
        \item Open your favorite {\TeX} editor, create a new document or
            open an existing \EXT{TXT} file. If your {\TeX} editor can
            automatically wrap long lines, \emph{turn this feature off}
            before you paste any verses into the document.
        \item Open the \textsf{e-Sword} desktop application. Select \textsf{Bible
            > Copy Verses\ldots}
        \item From the \textsf{Copy Verses} dialog box, refer to
            \hyperref[fig:cpyVrs]{Figure~\ref*{fig:cpyVrs}}, choose the
            verses required. Select the following options from the dialog:
            \begin{itemize}
               \item \textsf{Abbreviated book names} option: check this option
               \item \textsf{Include translation name} option: this box \emph{must be checked}.
               \item \textsf{Include text formatting} option: clear this checkbox
               \item \textsf{Format} option: Be sure to use the \textsf{Format} labeled as~1.
               \item \textsf{Reference delimiter}: Keep the reference delimiters of
                   parentheses `\texttt{(}' and `\texttt{)}'. The delimiters are required to
                   be parentheses as they are used in the definition of the Bible
                   verses and use in the \pkg{fetchbibpes} package.
            \end{itemize}
        \item Press the \textsf{Copy} button.
        \item Paste the copied verses into your \EXT{TXT} file. \textbf{\textcolor{red}{Important!}}
            Verify that each verse is on a single line, do not allow your editor to wrap any line around.
            You should have \emph{one verse per line}.
        \item When you are finished pasting verses, save the \EXT{TXT} file
            using some appropriate base name, say
            \texttt{{\slshape{myverses}}.txt}.
    \end{enumerate}

    \paragraph*{Methodology 2.} Work within \textsf{Microsoft Word} and use the
    \textsf{e-Sword} ADD-IN (\mlurl{http://www.e-sword.net/extras.html}). The
    assumptions are that you have the \textsf{e-Sword} application and have installed
    the \textsf{Word} add-in.
    \begin{enumerate}
    \item Open an empty Word document
    \item Select ADD-INS
    \item Tap the icon e-Sword Macros: Paste Verses from e-Sword.
    \item See the description of step 3, in \textbf{Methodology 1} above.
    \item When satisfied, save the file as a \EXT{TXT} file (Plain text), choose a
        base name that is meaningful, say \texttt{{\slshape{myverses}}.txt}
    \item Place \texttt{{\slshape{myverses}}.txt} in the source folder.
    \end{enumerate}

\begin{figure}[htb]\centering
  \includegraphics[width=.67\linewidth]{copyVerses}
  \caption{\textsf{Copy Verses} dialog box}\label{fig:cpyVrs}
\end{figure}

    \paragraph*{Other comments.} Quotations (sometimes) appear as double quotes
    (\texttt{"}), the companion package \pkg{fetchbibpes} attempts to convert
    double quotes to the {\TeX} notion of quotes; therefore, it is important
    to copy verses that have matched double quotes.

    In some translations, Jesus' words are quoted in red and are not set off
    by quotation marks. You'll have to hand edit the \EXT{TXT} file.
\begin{Verbatim}[xleftmargin=\amtIndent]
(Mat 11:4) Jesus answered and said unto them, Go and shew John
again those things which ye do hear and see:
\end{Verbatim}
    can be changed to,
\begin{Verbatim}[xleftmargin=\amtIndent]
(Mat 11:4) Jesus answered and said unto them,
\textcolor{red}{Go and shew John again those things which ye do
hear and see:}
\end{Verbatim}
to be typeset as
    \begin{quote}
    (Mat 11:4) Jesus answered and said unto them, \textcolor{red}{Go and shew John
    again those things which ye do hear and see:}
    \end{quote}
    That is, should such emphasis of Jesus' words be desired.\footnote{Here,
    and throughout this manual, verses taken from the \EXT{TXT} or \EXT{DEF}
    files are wrapped to the next line, this is done for \emph{display
    purposes only}. In both the \EXT{TXT} and \EXT{DEF} files, the rule is
    \emph{one verse per line}.}

\subsection{Create the \EXT{DEF} file}\label{para:crtDEF}

After you have created your \EXT{TXT} file, open the file
 \texttt{makebibpes.tex}, which is found in the \texttt{examples} folder.
 This is a short file that reads:
\begin{equation}
\begin{minipage}{100pt}
\begin{Verbatim}[numbers=left,commandchars=!()]
\documentclass{article}
\usepackage[!ameta(options)]{bibpes}
\begin{document}
\reportOnBibPes
\readbackDefFile
\end{document}
\end{Verbatim}
\end{minipage}\label{display:bibpes1}
\end{equation}
 The \texttt{makebibpes.tex} file, also found in the root folder of this
 distribution, is used to convert a \texttt{TXT} file of Bible verses to a
 \EXT{DEF} file of Bible verses. The action of this package is to take each
 line of Bible verse in the \EXT{TXT} file, for example, the verse in the
 \EXT{TXT} file,
\begin{Verbatim}[xleftmargin=0pt,fontsize=\small]
(Gen 1:1 KJV) In the beginning God created the heaven and the earth.
\end{Verbatim}
and to transformed it to the following verse in the \EXT{DEF} file,
\begin{Verbatim}[xleftmargin=0pt,fontsize=\small]
\BV(Gen 1:1 KJV) In the beginning God created the heaven and the earth.\null
\end{Verbatim}
 The command \cs{BV} (\underbar{B}ible \underbar{V}erse) is defined in the \pkg{fetchbibpes} package.
 The end of the line is delimited by the \cs{null} command. \hyperref[s:declareBVs]{Section~\ref*{s:declareBVs}}
 discusses the general format of the argument \ameta{verse-ref} of \cs{BV}.

It is the \pkg{fetchbibpes} package that uses this special \EXT{DEF} file to fetch
a verse from the file and typesets it into the document. See the documentation of \pkg{fetchbibpes}
in \hyperref[fetch]{Section~\ref*{fetch}} below.

The two commands \cs{reportOnBibPes} and \cs{readbackDefFile} expand to useful information
when you compile the \pkg{bibpes} document, as seen in display~\eqref{display:bibpes1}.
The first command expands to the input and output information given by the options
\texttt{infolder}, \texttt{txtfilein}, \texttt{outfolder}, and \texttt{deffileout}; while
\cs{readbackDefFile} reads back a listing of all passage just created. As a simple example,
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\documentclass{article}
\usepackage[!textbf(build),
  infolder=mytxts,
  outfolder=mydefs,
  txtfilein=Gen1-KJV
]{bibpes}
\begin{document}
\reportOnBibPes
\readbackDefFile
\end{document}
\end{Verbatim}
When compiled, the \pkg{bibpes} document might typeset as,
\begin{flushleft}\parskip3pt
Input file: \texttt{mytxts/Gen1-KJV.txt}\\
Output file: \texttt{mydefs/Gen1-KJV.def}
\end{flushleft}
\begingroup
\parindent0pt\parskip3pt
    \def\BV(#1){\makebox[0pt][r]{#1\quad}\ignorespaces}%
    \def\null{\par}%
\BV(Gen 1:1 KJV) In the beginning God created the heaven and the earth.\null
\BV(Gen 1:2 KJV) And the earth was without form, and void; and darkness was upon the face of the deep. And the Spirit of God moved upon the face of the waters.\null
\BV(Gen 1:3 KJV) And God said, Let there be light: and there was light.\null
\BV(Gen 1:4 KJV) And God saw the light, that it was good: and God divided the light from the darkness.\null
\BV(Gen 1:5 KJV) And God called the light Day, and the darkness he called Night. And the evening and the morning were the first day.\null
\makebox[0pt][r]{\dots\dots\dots\dots\dots\dots\quad}\dots\dots\dots\dots\dots\dots
\endgroup\par\medskip\noindent
Passage references appear in the margins, while the passages themselves are
in the body of the document. When\marginpar{\small\raggedleft\opt{build}\\verses\\
\opt{!build}} the \texttt{build} option, shown in bold font above, is
specified, \pkg{bibpes} is fully functional in the sense that the \EXT{TXT}
file is read and the \EXT{DEF} file is created and saved. When \texttt{build}
is changed to \texttt{!build}, the typeset document displayed above appears,
but the \EXT{TXT} file is \emph{not read} and the \EXT{DEF} is \emph{not
created}. Using \opt{!build} is useful to get a typeset listing of the
passages in the \EXT{DEF} file, which, it is assumed, has \emph{already been built}.

\newtopic
As an application seen later, a special command \cs{bibpesBody} is also defined, basically
consisting of lines~(3)--(6), which include the beginning and ending of the document.
A revised \texttt{makebibpes.tex} document can, consequently, read as follows:
\begin{equation}
\begin{minipage}{200pt}
\begin{Verbatim}[numbers=left,commandchars=!()]
\documentclass{article}
\usepackage[!ameta(options)]{bibpes}
\bibpesBody\relax
\end{Verbatim}
\end{minipage}\label{display:bibpes2}
\end{equation}
It is important to have the \cs{relax} command following \cs{bibpesBody}.
This document should behave the same way as the other, more verbose one
given previously.

\newtopic\noindent
\hyperref[s:combpkg]{Section~\ref*{s:combpkg}} contains another application to \cs{bibpesBody}.


\subsection{Production and organization of your \texorpdfstring{\protect\EXT{TXT} and \protect\EXT{DEF}}
{TXT and DEF} files}

The file \texttt{makebibpes.tex} is found in the root folder of the
\pkg{fetchbibpes} distribution. Modern {\LaTeX} systems, {MiK\TeX} comes to
mind, do not allow you to compile a source file from their application
folder, and the folder itself is readonly. Therefore, you must move
\texttt{makebibpes.tex} to another folder.\footnote{That is why another copy
of \texttt{makebibpes.tex} is in the \texttt{examples} folder.}

\paragraph*{Production and organization.}
There are two thoughts that come to mind for producing \texttt{DEF} files.
\begin{enumerate}
\item Move \texttt{makebibpes.tex} into the working folder of your
    project. Within the working folder, you can create your \EXT{TXT}
    and \EXT{DEF} files as described in the \hyperref[s:Methods]{Sections~\ref*{s:Methods}}
    and~\ref{para:crtDEF}, respectively.

    Or, for a tidier setup, you can save your \EXT{TXT} and \EXT{DEF}
    file in subfolders of the working folder. Create two subfolders
    \texttt{mytxtfiles} and \texttt{mydeffiles}. When you convert your
    \EXT{TXT} files into \EXT{DEF} files, specify the options
    \texttt{infolder=mytxtfiles} and \texttt{outfolder=mydeffiles}.
    For example,
\begin{equation}
\begin{minipage}{100pt}
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[%
  infolder=mytxtfiles,
  outfolder=mydeffiles,
  txtfilein=1Cor1
]{bibpes}
\end{Verbatim}
\end{minipage}\label{display:bibpes}
\end{equation}
\pkg{bibpes} looks for \texttt{1Cor1.txt} in the \texttt{mytxtfiles} folder
and saves the newly created \texttt{1Cor1.def} file in the
\texttt{mydeffiles} folder. Later, when you use the \pkg{fetchbibpes}
package, specify \texttt{deffolder=mydeffiles} on the option list of
\pkg{fetchbibpes}, see
\hyperref[s:PkgOptsfetchbibpes]{Section~\ref*{s:PkgOptsfetchbibpes}} for a
description of the \opt{deffolder} option.

\item Create a folder named \texttt{mybibleverses}, or any such name, and
    move the conversion file \texttt{makebibpes.tex} to this folder. This
    folder acts as a `database' of Bible verses. As described above, create
    subfolders, one for \EXT{TXT} files and the other for \EXT{DEF} files
    (perhaps named \texttt{mytxtfiles} and \texttt{mydeffiles}).

    Over time, you save your \EXT{TXT} files from \app{e-Sword} into the
    \texttt{mytxtfiles}. Convert the \EXT{TXT} files into \EXT{DEF}
    by compiling \texttt{makebibpes.tex} with the options in
    equation~\eqref{display:bibpes} above.

    For any given project, move selected \EXT{DEF} files, as needed,
    into your the root of your working folder, or place them in a
    subfolder, \texttt{mydeffiles}. In the latter case, specify
    \texttt{deffolder=mydeffiles} on the open list of \pkg{fetchbibpes}, see
    \hyperref[s:PkgOptsfetchbibpes]{Section~\ref*{s:PkgOptsfetchbibpes}} for
    a description of the \opt{deffolder} option.

\end{enumerate}

\paragraph*{Just a few \EXT{DEF}s, many, or none?} The question addressed here is
whether, for a given project, develop many or a just a few \EXT{DEF} files
for use in the project.

\subparagraph*{Just a few \EXT{DEF}s.} From the \app{e-Sword} application,
you can save \emph{all the verses} you need for a given project into a
\emph{single} \EXT{TXT} file, then create a single \EXT{DEF} file. If you
have a `database' of \EXT{DEF} files already, you can copy and paste the
required verses into a single \EXT{DEF} file.

We preview the \pkg{fetchbibpes}, in the case of a single \EXT{DEF} file, you
can specify your only file (\texttt{lession1}) in the option list of
\pkg{fetchbibpes}:
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[%
  useverses=lesson1,
  deffolder=mydeffiles
]{fetchbibpes}
\end{Verbatim}
Here, \pkg{fetchbibpes} looks for \texttt{lession1.def} in the subfolder
\texttt{mydeffiles}.

This approach is useful for a small project (lesson) requiring verses of a limited scope.
As you need more verses, just add them into your \EXT{DEF} file.

\subparagraph*{Many \EXT{DEF} files.}
Another choice is to use several \EXT{DEF} files, perhaps from your
`data\-base' collection.
\begin{Verbatim}[xleftmargin=\amtIndent]
\usepackage[%
  useverses={Gen1,Mat2,Rom1,1Cor1},
  deffolder=mydeffiles
]{fetchbibpes}
\end{Verbatim}
Here, you plan to reference verses in the \texttt{Gen1.def} file (containing
Genesis, chapter~1), \texttt{Mat2.def}, \texttt{Rom1.def}, and
\texttt{1Cor1.def}. With this database approach, authoring Bible lessons is
more modular; just drop in the \texttt{DEF} files you need into the
appropriate folder.

The `database' approach is useful for large projects. It is critical to name
your \EXT{DEF} files to make it easy to determine which files to include
in your document. In the development of this package and \pkg{fetchbibpes}, I
started a naming convention: \texttt{Gen1.def} (Chapter~1, or a subset of
chapter~1, of Genesis of KJV)\footnote{KJV is the King James Version},
\texttt{Gen1-ISV.def} (Chapter~1, or a subset of chapter~1, of Genesis of
ISV)\footnote{ISV is the International Standard Version}, and so on.

\subparagraph*{No \EXT{DEF} files.} When the \opt{useverses} option does not
appear, or has no value, a warning is generated and written to the log to remind you to
specify a value of the \opt{useverses} option. You can suppress this warning by specifying
\texttt{useverses=none}. This declares that no \EXT{DEF} files are to be input. Instead, you
can manage the verses by hand through the use of the \env{declareBVs} environment, refer to
\hyperref[s:declareBVs]{Section~\ref*{s:declareBVs}} on page~\pageref*{s:declareBVs}.


\subsection{\textsf{e-Sword} Book abbreviations}

The \textsf{e-Sword} desktop application uses 3-letter abbreviations for the
books of the Bible, see the \textbf{\app{e-Sword} Abbr} column of
\hyperref[table:esabbr]{Table~\ref*{table:esabbr}}. (39 in Old Testament and
27 in the New Testament).

\begin{table}[htb]
\centering\footnotesize
$$\begin{tabular}{lll|lll}\\
 \textbf{Book} & \multicolumn{1}{l}{\shortstack[c]{\bfseries\hbox to0pt{\hss\app{e-Sword}\hss}\\\bfseries Abbr}}& \textbf{Alt\_Abbr} &
 \textbf{Book} & \multicolumn{1}{l}{\shortstack[c]{\bfseries\hbox to0pt{\hss\app{e-Sword}\hss}\\\bfseries Abbr}}& \textbf{Alt\_Abbr}\\\hline
 Genesis         & Gen & Genesis      & Nahum          &  Nah & Nahum           \\
 Exodus          & Exo & Exodus       & Habakkuk       &  Hab & Habakkuk        \\
 Leviticus       & Lev & Leviticus    & Zephaniah      &  Zep & Zephaniah       \\
 Numbers         & Num & Numbers      & Haggai         &  Hag & Haggai          \\
 Deuteronomy     & Deu & Deuteronomy  & Zechariah      &  Zec & Zechariah       \\
 Joshua          & Jos & Joshua       & Malachi        &  Mal & Malachi         \\
 Judges          & Jdg & Judges       & Matthew        &  Mat & Matthew         \\
 Ruth            & Rth & Ruth         & Mark           &  Mar & Mark            \\
 1 Samuel        & 1Sa & ISamuel      & Luke           &  Luk & Luke            \\
 2 Samuel        & 2Sa & IISamuel     & John           &  Joh & John            \\
 1 Kings         & 1Ki & IKings       & Acts           &  Act & Acts            \\
 2 Kings         & 2Ki & IIKings      & Romans         &  Rom & Romans          \\
 1 Chronicles    & 1Ch & IChronicles  & 1 Corinthians  &  1Co & ICorinthians    \\
 2 Chronicles    & 2Ch & IIChronicles & 2 Corinthians  &  2Co & IICorinthians   \\
 Ezra            & Ezr & Ezra         & Galatians      &  Gal & Galatians       \\
 Nehemiah        & Neh & Nehemiah     & Ephesians      &  Eph & Ephesians       \\
 Esther          & Est & Esther       & Philippians    &  Php & Philippians     \\
 Job             & Job & Job          & Colossians     &  Col & Colossians      \\
 Psalms          & Psa & Psalms       & 1 Thessalonians&  1Th & IThessalonians  \\
 Proverbs        & Pro & Proverbs     & 2 Thessalonians&  2Th & IIThessalonians \\
 Ecclesiastes    & Ecc & Ecclesiastes & 1 Timothy      &  1Ti & ITimothy        \\
 Song of Solomon & Son & SongofSolomon& 2 Timothy      &  2Ti & IITimothy       \\
 Isaiah          & Isa & Isaiah       & Titus          &  Tit & Titus           \\
 Jeremiah        & Jer & Jeremiah     & Philemon       &  Phm & Philemon        \\
 Lamentations    & Lam & Lamentations & Hebrews        &  Heb & Hebrews         \\
 Ezekiel         & Eze & Ezekiel      & James          &  Jas & James           \\
 Daniel          & Dan & Daniel       & 1 Peter        &  1Pe & IPeter          \\
 Hosea           & Hos & Hosea        & 2 Peter        &  2Pe & IIPeter         \\
 Joel            & Joe & Joel         & 1 John         &  1Jn & IJohn           \\
 Amos            & Amo & Amos         & 2 John         &  2Jn & IIJohn          \\
 Obadiah         & Oba & Obadiah      & 3 John         &  3Jn & IIIJohn         \\
 Jonah           & Jon & Jonah        & Jude           &  Jud & Jude            \\
 Micha           & Mic & Micha        & Revelation     &  Rev & Revelation
\end{tabular}$$
\caption{\textsf{e-Sword} abbreviations}\label{table:esabbr}
\end{table}

\section{The \texorpdfstring{\protect\pkg{fetchbibpes}}{fetchbibpes} Package}\label{fetch}

    The problem of fetching Bible verses was suggested to me by my friend Tom
    Price. He plans to write Bible lessons, notes and handouts prepared using
    {\LaTeX} and these packages (\textsf{bibpes} and \textsf{fetchbibpes}).

    This is a companion package to \textsf{bibpes}. Use the
    commands of this package to fetch the Bible passages that the \textsf{bibpes} package has
    defined.

\subsection{The fetch verse commands} % 202, 0CA 312
    The major commands of this package are \cs{fetchverse} and \cs{fetchverses}, latter one being more
    powerful than the former. The syntax for these two are,
\bVerb\takeMeasure{\cs{fetchverses*}[\ameta{opts}]\darg{\ameta{book}{\vissp}\ameta{ch}:\ameta{vrs\SUB{1}}-\ameta{vrs\SUB{2}}}}%
\setlength{\dimen0}{\bxSize}%
\def\1{\rlap{\hskip\dimen0\relax\ding{192}}}%
\def\2{\rlap{\hskip\dimen0\relax\ding{193}}}%
\def\3{\rlap{\hskip\dimen0\relax\ding{194}}}%
\def\4{\rlap{\hskip\dimen0\relax\ding{195}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
!1\fetchverse[!ameta(opts)]{!ameta(book)(!vissp)!ameta(ch):!ameta(vrs)}
!2\fetchverses*[!ameta(opts)]{!ameta(book)(!vissp)!ameta(ch):!ameta(vrs)}
!3\fetchverses*[!ameta(opts)]{!ameta(book)(!vissp)!ameta(ch):!ameta(vrs)-}
!4\fetchverses*[!ameta(opts)]{!ameta(book)(!vissp)!ameta(ch):!ameta(vrs!SUB(1))-!ameta(vrs!SUB(2))}
\end{dCmd}
\endgroup\noindent
    where \ameta{opts}, discussed in \Nameref{s:optsfetch}, are any of the
    supported options; \ameta{book} is either the three letter book
    abbreviation that \textsf{e-Sword} uses (refer to the
    \textbf{\app{e-Sword} Abbr} column of
    \hyperref[table:esabbr]{Table~\ref*{table:esabbr}}) or one of the
    alternate abbreviations, seen in the \textbf{Alt\_Abbr} column of
    \hyperref[table:esabbr]{Table~\ref*{table:esabbr}}; \ameta{ch}:\ameta{vrs} is a
    chapter-verse reference. The \cs{fetchverse} command only fetches a
    \emph{single verse}, while the \cs{fetchverses} (plural) command can
    fetch a single verse (\ameta{ch}:\ameta{vrs}) or can fetch \emph{multiple
    verses} (as in lines~\ding{194} and~\ding{195}). The run of verses
    must all be from the same chapter. The `\texttt{*}' parameter is
    optional, when present, the book and verse references are shown,
    otherwise they are not. We illustrate with \texttt{Gen\;1:1},
    \texttt{Gen\;1:1-}, and \texttt{Gen\;1:1-2}.

When the upper bound of the range is not specified, as in \ding{194}, the passages are displayed
from the starting verse until the \emph{first undefined verse} (with the same chapter number \ameta{ch}).
This `open-ended run' may go to the end of the chapter (if all verses are defined), or just run unto
there are no more verses from that chapter.

\newtopic\noindent
We present some simple examples of the syntax variations of \cs{fetchverses}:
 \begin{enumerate}
    \item[\ding{192}] \cs{fetchverse\darg{Gen\;1:1}}: \fetchverse{Gen 1:1}
    \item[\ding{193}] \cs{fetchverses\darg{Gen\;1:1}}: \fetchverses{Gen 1:1}
    \item[\ding{194}] \cs{fetchverses\darg{Gen\;1:1-}}: \fetchverses{Gen 1:1-}
    \item[\ding{195}] \cs{fetchverses*\darg{Gen\;1:1-2}}:\ \fetchverses*{Gen 1:1-2}
    \item[\ding{195}] \cs{fetchverses\darg{Gen\;1:1-2}}: \fetchverses{Gen 1:1-2}
 \end{enumerate}
 Though the thee-letter abbreviations are preferred for the book names, \pkg{fetchbibpes} does
 support an alternate set of names as seen in the \textbf{Alt\_Abbr} column of
    \hyperref[table:esabbr]{Table~\ref*{table:esabbr}}.
 \begin{itemize}
    \item \cs{fetchverse\darg{Genesis\;1:1}}: \fetchverse{Genesis 1:1}
    \item \cs{fetchverse\darg{IKings\;1:1}}: \fetchverse{IKings 1:1}
    \item \cs{fetchverses*\darg{ICorinthians\;1:1-2}}: \fetchverses*{ICorinthians 1:1-2}
 \end{itemize}

\subsubsection{Fetching a verse that is not available.}
An error that can occur surely.
For example,
\begin{quote}
\verb|\fetchverse{Gen 1:11}|\\[3pt]
\fetchverse{Gen 1:11}
\end{quote}
In this case, there is no Gen 1:11, the first chapter only has 10 verses. Instead of the passage,
the marker \fetchverses{Gen 1:11} appears. This signals that the passage is undefined.

Another possibility is that the passages are not in any of the \EXT{DEF}
files you've input into the current document.
\begin{quote}
\verb|\fetchverses{Gen 2:1-3}|\\[3pt]
\fetchverses{Gen 2:1-3}
\end{quote}
In this case, chapter 2 of the book of Genesis was not input into the current
document, so \pkg{fetchbibpes} cannot find them, and marks which of the
verses were not found.

Another error is simply mistyping the passage reference, for example, the
declaration,
\begin{quote}
\verb|\fetchverse{gen 1:1}| yields\\[3pt]\fetchverse{gen 1:1}
\end{quote}
Notice that the reference label (\textbf{??}gen\textbf{??} 1:1) has
`\textbf{??}' around the \emph{book name}, this means that the book name is
not recognized, possibly a misspelling. In this case, `gen' should be `Gen'.
A warning message appears in the log.

One last common mistake is to use \cs{fetchverse} (singular) when
\cs{fetchverses} (plural) is needed; for example,
\begin{quote}
\cs{fetchverse\darg{ICorinthians\;1:1-2}} yields\\[3pt]
\fetchverse{ICorinthians 1:1-2}
\end{quote}
In this case, we referenced a range of verses, but used \cs{fetchverse} to fetch.
It is perhaps always better to use \cs{fetchverses} for single and multiple verses.



\subsubsection{The options of the fetch verse commands}\label{s:optsfetch}

    In this section, we describe the \ameta{opts} argument of the fetch verse commands.
    These options control how the book names are displayed.

\begin{description}
     \item [\texttt{abbr=\ameta{\upshape{esword|none|long|short}}}] The
         \texttt{abbr} key designates how the book reference is displayed,
         possible values are \texttt{esword}, \texttt{none}, \texttt{long},
         and \texttt{short}. Specifying \texttt{abbr} is equivalent to
         \texttt{abbr=esword}. Initially, we set \texttt{abbr=esword}.


\paragraph*{Examples}\leavevmode
 \begin{itemize}
       \item \cs{fetchverse[abbr=esword]\brpr{Gen 1:1}}: \fetchverse[abbr=esword]{Gen 1:1}
       \item \cs{fetchverse[abbr=none]\brpr{Gen 1:1}}: \fetchverse[abbr=none]{Gen 1:1}
       \item \cs{fetchverse[abbr=long]\brpr{Gen 1:1}}: \fetchverse[abbr=long]{Gen 1:1}
       \item \cs{fetchverse[abbr=short]\brpr{Gen 1:1}}: \fetchverse[abbr=short]{Gen 1:1}
 \end{itemize}

% \useBookStyle{abbr,roman=false,from,transl}


 \item[\texttt{roman=\ameta{\upshape{true|false}}}] The \texttt{roman} key
     determines how book numbers are displayed, `1~Corinthians' versus `I
     Corinthians', for example. Possible values are \texttt{true} (use
     roman letters) of \texttt{false} (use arabic numbers). Specifying
     \texttt{roman} without a value is equivalent to \texttt{roman=true}.
     Initially, we set \texttt{roman=false}.

 This key has no effect when \texttt{abbr=esword}.

 \paragraph*{Examples}\leavevmode
 \begin{itemize}
       \item \fetchverse[abbr=long,roman=false]{1Co 1:1}
       \item \fetchverse[abbr=long,roman]{1Co 1:1}
 \end{itemize}

 \item[\texttt{from=\ameta{\upshape{KVJ|KVJ+|ISV}}}]\label{item:from} The
     value of the \texttt{from} key is the Bible translation to be used. For
     example, \texttt{from=ISV}.

    \textbf{Example} \verb|\fetchverse[abbr=none,from=ISV]{Gen 1:1}| yields,
    \begin{quote}
        \fetchverse[abbr=none,from=ISV]{Gen 1:1}
    \end{quote}

    The \texttt{from} key, only supports values \texttt{KJV},
    \texttt{KJV+}, \texttt{ISV}, these are the versions of the Bible are
    free versions available from \app{e-Sword} commonly used. When the
    \texttt{from} key is not specified, the default Bible is the \cs{defaultBible}, see
    \hyperref[s:suppfetch]{Section~\ref*{s:suppfetch}} for more information on setting the default
    Bible. Initially, the default Bible is set to \texttt{KJV}; thus,
    \verb|\fetchverse{Gen 1:1}| fetches Genesis 1:1 from the \texttt{KJV},
    if defined.

    If you want to introduce other Bible translations into your document, use
    the command \cs{addtoBibles} to declare them; see
    \mlhyperref[\linktxtcolor{webgreen}]{s:suppfetch}{Section~\protect\ref*{s:suppfetch}}
    for more information on \cs{addtoBibles}. To add Bible translations to all
    documents you produce, `register' them in the configuration files; refer
    to \hyperref[s:cfg]{Section~\ref*{s:cfg}} to read how to do this.

    \item[\texttt{alt=\ameta{word}}]\label{key:alt} The value \ameta{word}
        is a single word (containing no spaces). The \pkg{fetchbibpes}
        fetches the verses in the \EXT{DEF} files, as originally obtained
        from the \app{e-Sword} application. These verses are without
        formatting or emphasis or color. By hand-editing selected \EXT{DEF}
        files, you can create rich text Bible passages and retrieve them through the
        \texttt{alt} key. For example, we edit the file containing
        \texttt{Gen 1:1 KJV} and add a line:
\begin{Verbatim}[xleftmargin=\amtIndent]
\BV(Gen 1:1 KJV) In the beginning
   God created the heaven and the earth.\null
\BV(Gen 1:1 KJV Alt) \dots
   \emph{God created the heaven and the earth}.\null
\end{Verbatim}
(Lines are wrapped around above to fit within the margins, this \emph{should not
be done} in the \EXT{DEF} file itself.) To access this alternate version
of \texttt{Gen 1:1}, we use the \texttt{alt} key.
\begin{quote}
\verb|\fetchverse{Gen 1:1}|\\[3pt]\fetchverse{Gen 1:1}\\[6pt]
\verb|\fetchverse[alt=Alt]{Gen 1:1}|\\[3pt]\fetchverse[alt=Alt]{Gen 1:1}
\end{quote}
There can be many variations on verses, \texttt{alt=Alt},
\texttt{alt=Alt1}, \texttt{alt=Color}, and so on.

When you edit a \texttt{DEF} file to add an alternate version, there must
be a space between the Book (\texttt{KJV}), for example) and the
\ameta{word} (\texttt{\string\BV(Gen 1:1 KJV Alt)}).

Beginning at date 2016/11/07, the behavior of the \texttt{alt} key is
modified. If you specify an alternate version, say \texttt{alt=Alt}
(\cs{fetchverse[alt=Alt]\darg{Gen\,1:1}}) and that alternate version is
\emph{not available} (undefined), \pkg{fetchbibpes} attempts to typeset the
the same verse with no \texttt{alt} key, and writes an informative message
to the log. The previous behavior is to mark that passage with
`\texttt{??}', which indicates the passage is undefined. This new behavior
also manifests itself with the \texttt{alt*} key. The demo file
\texttt{bibpes\_alt-star.tex} tests this new behavior.

The command \cs{useOldAlt} reverts to the old behavior of \texttt{alt}
and \cs{useNewAlt} to returns to the new behavior. The default is
\cs{useNewAlt}.

    \item[\texttt{alt*=\ameta{list-of-words}}] The parameter
        \ameta{list-of-words} is a comma-delimited list of \texttt{alt}
        keywords. Empty entries are supported. Perhaps an example before
        further explanation.
\begin{Verbatim}[xleftmargin=\amtIndent]
\fetchverses[alt*={Alt1,,,Alt2,,Alt1}]{Gen 1:1-10}
\end{Verbatim}
The \pkg{fetchbibpes} package typesets the following verses: Gen 1:1 Alt1,
Gen 1:2, Gen~1:3, Gen 1:4 Alt2, Gen 1:5, Gen 1:6 Alt1, Gen 1:7, Gen 1:8,
Gen 1:9, Gen 1:10. If any of the \texttt{alt} versions are undefined,
\pkg{fetchbibpes} typesets the passage with no \texttt{alt} key specified
and an informative message is written to the log.

The demo file \texttt{bibpes\_alt-star.tex} tests this feature.

    \item[\texttt{transl=\ameta{text}}] The \texttt{transl} key is an
        annotation key that appends text (\ameta{text}) to the end of the
        Bible reference, such as \texttt{transl=KJV}, to obtain the
        \textit{translation note}. The \texttt{transl} internally defines a macro
        that holds its value, but also defines a public command \cs{gtransl}\marginpar{\small\raggedleft\cs{gtransl} defined} that
        expands to \ameta{text}. This command is redefined at the next use of the
        \texttt{transl} key within \cs{fetchverses} or \cs{fetchversestxt}.

\paragraph*{Examples} We set the translation note to `King James Version'.
\begin{quote}\small
\verb|\fetchverse[abbr=none,transl=King James Version]{Gen 1:1}|\\[3pt]\normalsize
\fetchverse[abbr=none,transl=King James Version]{Gen 1:1}
\end{quote}
Normally, the version abbreviation is used as the \ameta{text}:
\begin{quote}
\verb|\fetchverse[abbr=none,transl=KJV]{Gen 1:1}|\\[3pt]\normalsize
\fetchverse[abbr=none,transl=KJV]{Gen 1:1}
\end{quote}
The translation note does not appear unless the \texttt{transl} key is specified with a value.
In the example below, there is no \texttt{transl} key (and there is no \texttt{from} key so the
default Bible is used (\fbdefaultBible)).
\begin{quote}
\verb|\fetchverse[abbr=none]{Gen 1:1}|\\[3pt]\normalsize
\fetchverse[abbr=none,from=KJV]{Gen 1:1}
\end{quote}
To get the translation note to appear you can either specify a value for the
\texttt{transl} key, as we did above, or turn on the feature of always showing the translation
note.
\bVerb\takeMeasure{\string\showTranslAlways\quad\string\showTranslDecld}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\showTranslAlways!quad\showTranslDecld
\end{dCmd}
\eVerb \cs{showTranslAlways} turns on the translation note,\footnote{If the
\texttt{transl} key is not specified, tt uses the value of the \texttt{from}
key; if the \texttt{from} key is not specified, the default Bible is used.}
while \cs{showTranslDecld} to the default behavior, that is, show the
translation note only when the \texttt{transl} key has a declared value. Thus,
\begin{quote}
\verb|\showTranslAlways|\\
\verb|\fetchverse[abbr=none]{Gen 1:1}| expands to,\\[3pt]
\showTranslAlways
\fetchverse[abbr=none]{Gen 1:1}
\end{quote}
The Bible abbreviation is used (KJV), if the \texttt{transl} is present in the optional parameter
list, its value will be used instead.
\begin{quote}
\verb|\showTranslAlways|\\
\verb|\fetchverse[abbr=none,transl=KJ]{Gen 1:1}| expands to,\\[3pt]
\showTranslAlways
\fetchverse[abbr=none,transl=KJ]{Gen 1:1}
\end{quote}
The sample file \texttt{fetchversestxt.tex} illustrates \cs{showTranslAlways}.

\item[\texttt{from*=\ameta{version}}] The \texttt{from*} combines the
    actions of the options \texttt{from} and \texttt{transl} and is
    equivalent to \texttt{from=\ameta{version},transl=\ameta{version}}. Here
    \ameta{version} must be a recognized version of the Bible available on
    your computer.

\textbf{Example} \verb|\fetchverse[abbr=none,from*=ISV]{Gen 1:1}| yields,
\begin{quote}\fetchverse[abbr=none,from*=ISV]{Gen 1:1}\end{quote}
The value of the \texttt{from*} key must be a valid value of the \texttt{from} key.

\item[\texttt{pcolor=\ameta{color}}]\label{item:pcolor} Use the \opt{pcolor} key to color the passage text.
    The value \ameta{color} is any color specification accepted by the \cs{color} macro
    of the \pkg{color} or \pkg{xcolor} package.

\textbf{Example} \verb|\fetchverses*[pcolor=blue]{Gen 1:1-2}|
\begin{quote}
\fetchverses*[pcolor=blue]{Gen 1:1-2}
\end{quote}
The coloring includes the two tokens placed by the \opt{enclosewith} key.

Note that the verse numbers are also colored; to typeset the verse number in black, say,
redefine \cs{verseFmt}. For example
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\renewcommand\verseFmt[1]{{\normalcolor\verseFmtDef{#1}}}
\end{Verbatim}
the above passage becomes,
\begin{quote}
\renewcommand\verseFmt[1]{{\normalcolor\verseFmtDef{#1}}}
\fetchverses*[pcolor=blue]{Gen 1:1-2}
\end{quote}
The general treatment of \cs{verseFmt} is taken up in \hyperref[s:VerseNumbers]{Section~\ref*{s:VerseNumbers}}
on \autopageref*{s:VerseNumbers}.

In the option list of a fetch command, declaring \opt{pcolor} (without a
value) causes the passage text to be colored the default color (usually
black). All changes in the option list are local to the passage, but you can
use \cs{useBookStyle} to set `global' options. Continue reading on this
subject, beginning with the named paragraph \textbf{\nameref{para:useBookStyle}} on
\autopageref*{para:useBookStyle}.

\item[\texttt{pformat=\ameta{various}}] Use the \opt{pformat} key to change
    the formatting (or style) of the passage text. The \ameta{various}
    argument should be style declarations, such as \cs{bfseries},
    \cs{itshape}, \cs{slshape}, \cs{sffamily}, and so on, but can be anything that does not
    take an argument.

\textbf{Example} \verb|\fetchverses*[pformat=\slshape]{Gen 1:1-2}|
\begin{quote}
\fetchverses*[pformat=\slshape]{Gen 1:1-2}
\end{quote}
More than one formatting command may be used; for example, to obtain bold slant passage text,
we declare \opt{pformat=\string\bfseries\string\slshape}.

See the \opt{format} key for formatting the passage reference.

\item[\texttt{delims=\ameta{tok\SUB{1}tok\SUB{2}}}] The \texttt{delims} key
    takes a value of two characters (or tokens or groups enclosed in braces
    (\verb|{}|)) used to set off the Bible reference. The default is
    \texttt{delimin=()}.

If \texttt{delims} appears in the option list without a value, then there are
no characters delimiting the Bible passage.
\goodbreak
\textbf{Examples}
\begin{enumerate}
   \item \verb|\fetchverse[abbr=none,delims]{Gen 1:1}|
   \begin{quote}
   \fetchverse[abbr=none,delims]{Gen 1:1}
   \end{quote}
   \item \verb|\fetchverse[abbr=none,delims={[]}]{Gen 1:1}|
   \begin{quote}
   \fetchverse[abbr=none,delims={[]}]{Gen 1:1}
   \end{quote}
   \item \verb|\fetchverse[abbr=none,delims={According to }{,}]{Gen 1:1}|:
   \begin{quote}
   \fetchverse[abbr=none,delims={According to }{,}]{Gen 1:1}
   \end{quote}
 \end{enumerate}
 As seen in item~2, delimiters of `\texttt{[]}' must be enclosed in braces
 because this all takes place within an optional argument, without the
 braces, the parsing of the optional argument fails. The \texttt{delims}
 expects two tokens, they need not be characters, they can be anything, as
 long as they are enclosed in matching braces. In item~3, we set
 \verb|delims={According to }{,}|, the first token is placed before the
 passage reference, the second after; this results in a phrase that leads
 up to the passage itself.

\handpoint When \texttt{delim} is used with \cs{fetchverses} the star-option must be used, otherwise,
\texttt{delim} has  no effect.

\item[\texttt{enclosewith=\ameta{tok\SUB{1}tok\SUB{2}\upshape|\cs{quote}}}] The
    \texttt{enclosewith} key takes either a two-token argument or the command
    \cs{quote}. The latter is used to enclose the passage in quotation
    marks. The tokens are placed as follows:
    \ameta{tok\SUB1}\meta{passage}\ameta{tok\SUB2}. When \cs{quote} is specified
    \texttt{\ameta{tok\SUB1}=\darg{``}} (left quote) and
    \texttt{\ameta{tok\SUB2}=\darg{''}} (right quote).

   \textbf{Example} Enclose the passage in quotation marks:
   \begin{quote}
   {\small\verb|\fetchverse[delims={According to }{,},enclosewith=\quote]{Gen 1:1}|}\\[3pt]
   \fetchverse[abbr=none,delims={According to }{,},enclosewith=\quote]{Gen 1:1}\\[6pt]
   {\small\verb|\fetchverses*[delims={According to }{,},|\\
   \hspace*{16pt}\verb|enclosewith={\guillemotleft\space}{ \guillemotright}]{Gen 1:1-2}|}\\[3pt]
   \fetchverses*[abbr=none,delims={According to }{,},enclosewith={\guillemotleft\space}{ \guillemotright}
   ]{Gen 1:1-2}
   \end{quote}

   The \texttt{enclosewith} key must be used wisely as some passages, depending on the translation,
   already contain single and/or double quotation marks.

 \item[\texttt{format=\ameta{value}}] The \texttt{format} key is a general key for making formatting declarations,
 for example, we format the reference using \texttt{format=\string\bfseries\string\sffamily}.

\textbf{Example} \verb|\fetchverse[format=\bfseries\sffamily]{Gen 1:1}| produces
the passage:
 \fetchverse[format=\bfseries\sffamily]{Gen 1:1}

 The formatting only effects the passage label (reference) \textbf{Gen 1:1} and its surrounding
 delimiters.


\item[\texttt{caps=\ameta{\upshape{true|false}}}] Specifying the
    \texttt{caps} key displays the chapter name (the passage reference or
    label) in capital letters `GENESIS' versus `Genesis'. Specifying
    \texttt{caps} without a value is equivalent to
    \texttt{caps=true}.

\textbf{Example} Capitalize the full book name and while we're at it we format the passage
reference as well.
\begin{quote}\small
 \verb|\fetchverse[format=\bfseries\sffamily,abbr=none,caps]{Gen 1:1}|\\[3pt]\normalsize
 \fetchverse[format=\bfseries\sffamily,abbr=none,caps]{Gen 1:1}
 \end{quote}

 \item[\texttt{showfirst=\ameta{\upshape{true|false}}}] The
     \texttt{showfirst} key is a Boolean, which if \texttt{true}, the first verse
     number is typeset. The default is \texttt{false}, the first verse number is not
     typeset. Specifying \texttt{showfirst} without a value is equivalent to
    \texttt{showfirst=true}.

    \textbf{Examples} We compare the passages \texttt{Gen 1:1-2} with and
    without first verse number:
\begin{itemize}
   \item \verb|\fetchverses[showfirst]{Gen 1:1-2}|\\[3pt]
   \fetchverses[showfirst]{Gen 1:1-2}
   \item \verb|\fetchverses{Gen 1:1-2}|\\[3pt]
   \fetchverses{Gen 1:1-2}
 \end{itemize}

\item[\texttt{shownone}] When this valueless key is specified, no verse
    numbers are shown for the passage. In this case, the \texttt{showfirst}
    key has no effect.

\textbf{Example} \verb|\fetchverses[shownone]{Gen 1:1-3}| fetches the
passage, no verse numbers are shown.
\begin{quote}
\fetchverses[shownone]{Gen 1:1-3}
\end{quote}

 \item [\texttt{useperiod=\ameta{\upshape{true|false}}}] The
     \texttt{useperiod} key is a Boolean, which if \texttt{true} a period follows
     any abbreviation of a book name. If \texttt{useperiod=false} no period
     is affixed. The default is \texttt{true}. (`Matt.' versus `Matt', for example.)

\textbf{Examples}
\begin{itemize}
   \item \verb|\fetchverse[abbr=long]{Mat 2:1}|\\[3pt]
         \fetchverse[abbr=long]{Mat 2:1}
   \item \verb|\fetchverse[abbr=long,useperiod=false]{Mat 2:1}|\\[3pt]
         \fetchverse[abbr=long,useperiod=false]{Mat 2:1}
 \end{itemize}
 The period is used by default, you must say \texttt{useperiod=false} to
 remove it. This option is not obeyed when \texttt{abbr=esword} (or just
 \texttt{abbr}, the default).

 \item[\texttt{citeatend=\ameta{\upshape{true|false}}}] The
     \texttt{citeatend} key is a Boolean, which if \texttt{true}, places the
     citation reference at the end of the passage. Specifying
    \texttt{citeatend} without a value is equivalent to
    \texttt{citeatend=true}.

\textbf{Example} \verb|\fetchverses*[citeatend,showfirst]{Gen 1:1-2}|
\begin{quote} %\priorRefSpc{\fbFitItIn}\afterBookSpc{\nobreak\ }
\fetchverses*[citeatend,showfirst]{Gen 1:1-2}
 \end{quote}
It is possible to control the positioning of the citation using additional features,
yet to appear in the record, refer to \hyperref[s:suppfetch]{Section~\ref*{s:suppfetch}}.

\item[\texttt{nocite}] The \opt{nocite} key is only obeyed with the
\cs{fetchverse} command. If present, the citation for the passage does not appear.

\textbf{Example} \verb|\fetchverse[nocite]{Gen 1:1}| displays as:
\begin{quote}
\fetchverse[nocite]{Gen 1:1}
\end{quote}
Of course, the citation would normally appear prior to the appearance of the passage.
The above passage is equivalent to \verb~\fetchverses{Gen 1:1}~.

For \cs{fetchverse}, the citation \texttt{appears by default}, you must force it
away with \opt{nocite}; for \cs{fetchverses}, the citation \emph{does not
appear by default}, to make it appear, use \cs{fetchverses*}.

\item[\texttt{priorref=\ameta{value}}] The value of \texttt{priorref} is
    placed just before the book reference (\ameta{value}\darg{\cs{book@passage}}).
    The book reference itself (\cs{book@passage}) is enclosed in braces so
    \ameta{value} can be a macro with one argument.

    \textbf{Example} Place the passage reference in the margin. The command
    \cs{mpfmt} is defined locally, within the \texttt{quote} environment.
\begin{quote}
\def\mpfmt#1{\afterRef{{}}\marginpar{\small\raggedleft#1}}
\verb|\fetchverses*[priorref=\mpfmt,delims]{Gen 1:1-2}|\\[3pt]
\fetchverses*[priorref=\mpfmt,delims]{Gen 1:1-2}
 \end{quote}
 The definition of \cs{mpfmt} is made prior to the passage (and is not a
 command defined by the \pkg{fetchbibpes} package).
\begin{verbatim}
   \def\mpfmt#1{\afterRef{{}}\marginpar{\small\raggedleft#1}}
\end{verbatim}
The \cs{afterRef} command is described later in this documentation.

\item[\texttt{ltxquotes}] If this key is present (it has no value), it is assumed that
the corresponding passage or passages uses {\LaTeX} style quotes, as in
\texttt{\char018\char018God\char129s grace\char129\char129} or \texttt{\char018God\char129s grace\char129}.
Such a situation can occur if you've hand-edited the \EXT{DEF} file that contains the passages of interest.
In this case you want to use the \texttt{ltxquotes} key with the \cs{fetchverses} command; for example,
\begin{quote}
\verb|\fetchverses*[ltxquotes,from*=NKJV]{Mat 8:5-13}|\\[3pt]
\fetchverses*[ltxquotes,from*=NKJV]{Mat 8:5-13}
\end{quote}
This particular passage has been hand-edited, and uses {\LaTeX} quotation marks.

There are two commands related to \texttt{ltxquotes}, these are \cs{LaTeXQuotesOn} and \cs{LaTeXQuotesOff}, the default is \cs{LaTeXQuotesOff}. The option \texttt{ltxquotes} executes \cs{LaTeXQuotesOn} within a group. In extraordinary
situations, these commands my be explicitly expanded by the document author.

Refer to Section~\ref{ProbsQuotes} for a discussion of quotation marks and apostrophes.

\item[\texttt{replace=\darg{\ameta{find\SUB1}}\darg{\ameta{replc\SUB1}}%
      \darg{\ameta{find\SUB2}}\darg{\ameta{replc\SUB2}}...%
      \darg{\ameta{find\SUB{k}}}\darg{\ameta{replc\SUB{k}}}}]\label{item:replace}\leavevmode\\[3pt]The
      key performs (multiple) find and replace operations. There must be
      an even number of arguments. For each pair, \ameta{find\SUB{i}} is
      searched for and replaced by \ameta{replc\SUB{i}}. This is an exact
      match search. A command in the \ameta{replc\SUB{i}}
      argument might need to be protected using \cs{protect}.

      For example,
\begin{quote}
\verb|\fetchverse{Mat 2:1}|\\[3pt]
\fetchverse{Mat 2:1}
\end{quote}
As a stand alone quote, you'll note that the passage ends with a comma; we
want to change this to a period. Also, just to demonstrate multiple find
and replace, we'll also replace every instance of `Jesus' with
`\textcolor{red}{Jesus}'.
\begin{quote}
\verb|\fetchverse[replace={Jerusalem,}{Jerusalem.}|\\
\null\hskip20pt\verb|{Jesus}{\textcolor{red}{Jesus}}]{Mat 2:1}|\\[3pt]
\fetchverse[replace={Jerusalem,}{Jerusalem.}%{Jerusalem}{\textbf{Jerusalem}}
{Jesus}{\textcolor{red}{Jesus}}]{Mat 2:1}
\end{quote}
There are two commas in the sentence, so we must characterize the comma
we want to replace, the one that follows `Jerusalem'.

\textbf{Rule:} Do \emph{plain text replacements first} followed by any formatted text replacements last.
\begin{quote}
\verb|\fetchverse[replace={Jerusalem,}{Jerusalem.}|\\
\null\hskip20pt\verb|{Jerusalem}{\textbf{Jerusalem}}]{Mat 2:1}|\\[3pt]
\fetchverse[replace={Jerusalem,}{Jerusalem.}{Jerusalem}{\textbf{Jerusalem}}]{Mat 2:1}
\end{quote}
succeeds whereas,
\begin{quote}
\verb|\fetchverse[replace={Jerusalem}{\textbf{Jerusalem}}|\\
\null\hskip20pt\verb|{Jerusalem,}{Jerusalem.}]{Mat 2:1}|\\[3pt]
\fetchverse[replace={Jerusalem}{\textbf{Jerusalem}}{Jerusalem,}{Jerusalem.}]{Mat 2:1}
\end{quote}
fails. Notice the comma (\texttt{,}) was not replaced by a period (\texttt{.}). After the first
replacement, where is no string `\texttt{Jerusalem,}', there is `\verb|\textbf{Jerusalem},|'.

Additional examples are found in the sample files
\texttt{bibpes\_replace.tex} and in \texttt{bibpes\_replaces.tex} that
accompany this distribution. Examples include some `creative' use of
\opt{replace}.

\paragraph*{The \opt{replace} key and \cs{fetchverses}.}\label{para:replace}
A more detailed understanding of how \opt{replace} works when retrieving
multiple verses with \cs{fetchverses} is needed. The \opt{replace}
algorithm is run on \emph{each verse} individually -- not on the combined
verses -- as it is retrieved. This fact leads us to another rule.

\textbf{Rule:} The \ameta{find} text should only match text within a
single verse, not across several verses, for such a match will never be
successful. Restrict your searches to match fragments within a single
verse.


There is a command that may be useful with the \opt{replace} key.
\bVerb\takeMeasure{\string\gobbleto\darg{\ameta{word}}\darg{\ameta{\cs{cmd}}} }%
\begin{dCmd}[commandchars=!()]{\bxSize}
\gobbleto{!ameta(word)}{!ameta(\cmd)}}
\end{dCmd}
\eVerb The command defines another command \ameta{\cs{cmd}}, the action
of this command is to gobble up all token between it and the
\ameta{word}. The need for such a command arose when \ameta{find} text
contains one or more of the active characters. (The active characters are
the single left quote (\texttt{\char018}), the single right quote or
apostrophe (\texttt{'}), and the double quote (\texttt{"}).) It is
difficult to make things work (find/replace) when there is one of these
active characters in the \ameta{find} text. Below is an example from
\texttt{bibpes\_replaces.tex}. We quote a passage from Gal 1:15-16:
\begin{quote}\relax
\verb|\fetchverses*[from*=NKJV]{Gal 1:15-16}|\\[3pt]
\eSQ\fetchverses*[from*=NKJV]{Gal 1:15-16}
\end{quote}
We want to annotate this passage by removing unwanted sentence fragments,
so we can concentrate on the teaching of the passage. Note that \texttt{mother's womb}
is part of verse~15, the problem is to deal with the apostrophe.
\begin{Verbatim}[xleftmargin=\leftmargini,numbers=left]
\gobbleto{and}{\gobbletoand}\gobbleto{blood,}{\gobbletoblood}
\fetchverses*[from=NKJV,replace=
    {But when}{\leavevmode\ldots when}
    {who separated me from my}{who\gobbletoand}
    {, that I might preach Him}{ \ldots\gobbletoblood}
]{Gal 1:15-16}
\end{Verbatim}
Prior to the passage, we make two declarations
\verb|\gobbleto{and}{\gobbletoand}| and
\verb|\gobbleto{blood,}{\gobbletoblood}|, and insert them into our
\ameta{replace} text, as seen above.
\begin{quote}
\gobbleto{and}{\gobbletoand}\gobbleto{blood,}{\gobbletoblood}
\fetchverses*[from=NKJV,replace=
    {But when}{\leavevmode\ldots when}
    {who separated me from my}{who\gobbletoand}
    {, that I might preach Him}{ \ldots\gobbletoblood}
]{Gal 1:15-16}
\end{quote}
In line~(4) of the verbatim listing above, we find the text \texttt{who
separated me from my} (could have been shorter) and replace it by
\texttt{who\cs{gobbletoand}}. The \cs{gobbletoand} command is inserted
just after `\texttt{who}', and will gobble everything that follows it up
to and including the word `\texttt{and}. Included in the gobbled text is
the active character \texttt{'}, which now causes no grief. In line~(5),
another `gobble-replacement' is performed for a very long passage
(containing no active characters). In this way, Biblical fragments may be
displayed.

Obviously, great care must be taken to prevent unwanted replacements. The
\ameta{find} text must characterize what is to be found. Always check
your work to make sure you are getting the targeted replacement and not
spurious replacement.

The \opt{replace} option is a quick and easy way of making minor
editorial adjustments to the passage. Major revisions, such putting the
Jesus' words in red as some translations do, require editing the
\EXT{DEF} file and creating alternate passages; for more information on
how to create alternate passages, refer to the \opt{alt} key on
\autopageref{key:alt}.

\item[\texttt{localdefs=\ameta{localdefs}}] Use the \opt{localdefs} key
    to pass macro definitions into the group in which \cs{fetchverse} and
    \cs{fetchverses} operate. Any definitions, or other {\LaTeX} constructs, should
    not take up any space, nor should they disturb the {\LaTeX} code of \cs{fetchverse}
    and \cs{fetchverses}. The application of this key is to the \cs{gobbleto} command.
    Pass any \cs{gobbleto} declarations through the \opt{localdefs} key to make them
    local to the group.

    The `Gal 1:15-16' passages above were made within a \env{quote}
    environment, which made the \cs{gobbleto} declarations local; to
    quote the same passage outside of an enclosing group, yet avoiding a
    global declaration, use the \opt{localdefs} key.
\begin{Verbatim}[xleftmargin=\leftmargini]
\fetchverses*[from=NKJV,
  localdefs={\gobbleto{and}{\gobbletoand}%
    \gobbleto{blood,}{\gobbletoblood}},
  replace=
    {But when}{\leavevmode\ldots when}
    {who separated me from my}{who\gobbletoand}
    {, that I might preach Him}{ \ldots\gobbletoblood}
]{Gal 1:15-16}
\end{Verbatim}
This code expands to:
\fetchverses*[from=NKJV,
    localdefs={\gobbleto{and}{\gobbletoand}%
        \gobbleto{blood,}{\gobbletoblood}},
    replace=
        {But when}{\leavevmode\ldots when}
        {who separated me from my}{who\gobbletoand}
        {, that I might preach Him}{ \ldots\gobbletoblood}
]{Gal 1:15-16}

Note that because \cs{gobbleto\darg{blood,}} contains a comma, we must
enclose the value of \opt{localdefs} in braces so \pkg{xkeyval} will
parse it correctly.

The above example appears in \texttt{bibpes\_replaces.tex}.

\item[\texttt{typeset=\ameta{opts}}]\label{item:typeset} This option was designed for
    \cs{fetchversestxt}, but may be used with \cs{fetchverses} as
    well.\footnote{This key is not used with \cs{fetchverse}.} Refer to the
    subsection titled \mlNameref{fvtxt} for more information on the command.
  \begin{itemize}
    \item \textbf{For \cs{fetchverses}:} When \texttt{typeset} appears within
        the optional argument of \cs{fetchverses} its value (\ameta{opts}) is
        added \emph{to the end of the option list}. This may cause options
        specified by \texttt{typeset} to overwrite the options that are
        already declared. However, there is an important exception, that for
        the \texttt{replace} key\marginpar{\small\raggedleft\texttt{replace} option special case}; in this case, the arguments of the
        \texttt{replace} declared within \texttt{typeset} are appended to the
        arguments of the \texttt{replace} declared in the option list of
        \cs{fetchverses}. Thus,
\begin{Verbatim}[fontsize=\small,commandchars=!()]
\fetchverses[typeset={{brother}{\textbf{brother}},!ameta(other-opts)},
(!qquad)replace={brother,}{brother.},...]{1Co 1:1}
!STRUT!normalfont(This is equivalent to)
!STRUT\fetchverses[replace={brother,}{brother.}
!qquad{brother}{\textbf{brother}},...,!ameta(other-opts)]{1Co 1:1}
\end{Verbatim}

    \item \textbf{For \cs{fetchversestxt}:} If the \texttt{typeset} key
        appears (possibly with an empty value) within the option list of
        \cs{fetchversestxt}, it declares that the two macros \cs{versestxt} and
        \cs{passagetxt} (created by \cs{fetchversestxt}) are intended to be
        typeset into the document; the \ameta{opts} value \emph{is ignored}.
        The key itself effects the treatment of quotation marks and apostrophes;
        when present, `smart quotes' are used and \cs{bDQ}, \cs{eDQ}, \cs{bSQ},
        and \cs{eSQ} have effect. See \hyperref[ProbsQuotes]{Section~\ref*{ProbsQuotes}}
        for a discussion of these latter commands.
    \end{itemize}
    The purpose of \texttt{typeset} (as well as \texttt{typeset*}) is to
    enable the document author to write one set of options for both
    \cs{fetchverses} and \cs{fetchversestxt}. The value of \texttt{typeset}
    provides additional formatting options not available through
    \cs{fetchversestxt}.

\item[\texttt{typeset*=\ameta{opts}}] This key has the same features as
    \texttt{typeset} when specified within the option list of
    \cs{fetchverses}. Within the option list of \cs{fetchversestxt}, however,
    this key-value has no effect at all; \cs{fetchversestxt} has its normal
    characteristics: no {\LaTeX} formatting or font changes are supported;
    the `smart quotes' are not used; and the commands \cs{bDQ}, \cs{eDQ},
    \cs{bSQ}, and \cs{eSQ} are not obeyed.

    The section \Nameref{fvtxt} includes some discussion and examples of these last two keys.
\end{description}

\paragraph*{Predefined options using a `helper' command.}\label{para:PredefHelper} It can become
tedious to type the various options, nothing can be done about that, but if
you use the same collection of options consistently, you can package them in
a `helper' command:
\begin{Verbatim}[xleftmargin=\amtIndent]
\newcommand{\Optsi}{pcolor=blue,format=\bfseries,abbr=none}
\end{Verbatim}
Then you can say,
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\fetchverses*[!textbf(\Optsi),!ameta(more_options)]{Gen 1:1-2}
\end{Verbatim}
\textbf{\textcolor{red}{Important.}} The placement of the `helper' command is
important, it should placed just to the right of the left bracket (\texttt[),
as shown above. The first token (\cs{Optsi}) is expanded using the {\TeX}
primitive \cs{expandafter}, which is a limited kind of expansion.
\begin{quote}\newcommand{\Optsi}{pcolor=blue,format=\bfseries,abbr=none}%
\verb|\fetchverses*[\Optsi,caps]{Gen 1:1-2}|\\[3pt]
\fetchverses*[\Optsi,caps]{Gen 1:1-2}
\end{quote}

\subsection{Package options}\label{s:PkgOptsfetchbibpes}
The basic syntax for \pkg{fetchbibpes} is as follows:
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\usepackage[%
  useverses={!ameta(list)},
  deffolder=!ameta(path),
  useselverses,
  usesr,
  ignorecfg,
  cfg=!ameta(name)
]{fetchbibpes}
\end{Verbatim}

\paragraph*{Description of options}
\begin{description}\def\HR{\hspace{-\labelsep}}
\item[\texttt{useverses=\darg{\ameta{list}}}] The  \opt{useverses} option
     is the way the \EXT{DEF} files are input into the document. The
     value of \opt{useverses} is \texttt{\darg{\ameta{list}}}, a
     comma-delimited base names for \EXT{DEF} file created by
     \textsf{bibpes}. The listed base name \EXT{DEF} files contain
     verses that are to be referenced and fetched from the files. These
     files should be located in the folder containing the source file of
     the document or in the search path of your {\LaTeX} distribution. For
     example,
\begin{Verbatim}
\usepackage[useverses={Gen1,Mat2,Rom1,1Cor1}]{fetchbibpes}
\end{Verbatim}
The items listed in the \emph{comma-delimited} list are the base names of the
\texttt{DEF} files to be input. The above assumes the listed files
(\texttt{Gen1.def}, \texttt{Mat2.def}, \texttt{Rom1.def}, \texttt{1Cor1.def}) are
in the folder of the source file, or in the search path of your {\LaTeX} system.

\item[\texttt{useverses=none}] There is a second form for the
    \texttt{useverses} option where the value is not a \ameta{list},
    but the word `\texttt{none}'. When \opt{useverses} does not appear
    in the option list, or has no value, a {\LaTeX} warning is generate
    to remind you to specify one or more \EXT{DEF} files. To suppress
    this warning, use the special of `\texttt{none}', in which case no
    \EXT{DEF} files are expected to be input into the document. When
    using this option, you normally manually manage the Biblical
    passages by using the \env{declareBVs} environment, which is covered in
    \hyperref[s:declareBVs]{Section~\ref*{s:declareBVs}} on page~\pageref*{s:declareBVs}.

\item [\texttt{deffolder=\ameta{path}}] Through \texttt{deffolder} key you
    can specify the \ameta{path} to the \EXT{DEF} files. Ideally,
    \ameta{path} is a subfolder of your source file. Do not place a forward
    slash (`\texttt{/}') at the end of the path, this is done internally
    only if \ameta{path} is nonempty.
\begin{Verbatim}
\usepackage[%
  useverses={Gen1,Mat2,Rom1,1Cor1},
  deffolder=mydeffiles
]{fetchbibpes}
\end{Verbatim}
Here, {\LaTeX} looks for the listed files (\texttt{Gen1.def},
\texttt{Mat2.def}, \texttt{Rom1.def}, \texttt{1Cor1.def}) in the folder
\texttt{mydeffiles}, which is a subfolder of the source file.

This key is useful if you want to remove the clutter of numerous
\EXT{DEF} files from the root folder of your source file.

\item\HR\opt{useselverses} is an option that tries to economize memory
    usage, refer to Section~\ref{s:sf} for details.

\item\HR\opt{fetchsubtr} is an option that includes code to extract substrings
from a verse. See \hyperref[s:substr]{Section~\ref*{s:substr}} for details.

\item\HR\opt{usesr} is a specialize option that brings in the definition of
    the \cs{sr} command, see \hyperref[s:sr]{Section~\ref*{s:sr}} for more information.

\item[\opt{ignorecfg}] When this key is present (no value is required), the \EXT{CFG}
file for this package (\texttt{fbpes.cfg}) is \emph{not loaded}. Refer to \hyperref[s:cfg]{Section~\ref*{s:cfg}}
for more information on the \EXT{CFG} file.

\item[\opt{cfg=\ameta{name}}] The value of this key specifies the base name
    of the configuration file (\texttt{\ameta{name}.cfg}) to be used. If the
    \opt{cfg} does not appear or has no value, the default configuration file
    is used (\texttt{fbpes.cfg}). The configuration file is input only if the
    \opt{ignorecfg} option \emph{does not appear} on the package option list.
    An example of the default configuration file (\texttt{fbpes.cfg}) is
    provided with this distribution.
\end{description}

\paragraph*{Demo file:} \texttt{bibpes\_tst.tex}.

\subsection{Supporting commands for fetching verses}\label{s:suppfetch}

\subsubsection{Adding Bibles}\label{ss:addtoBibles}
Suppose you want to fetch verses from the American Standard Version (ASV) and
Young's Literal Translation (YLT), first download them (if not already on
your system) using the \app{e-Sword} desktop application; second, use the
\cmd{\addtoBibles} command to add them to the list of supported Bible
versions.
\bVerb\takeMeasure{\string\addtoBibles\darg{\ameta{list}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\addtoBibles{!ameta(list)}
\end{dCmd}
\endgroup\noindent
    This command is placed in the preamble, \ameta{list} is a comma
    delimited list of \app{e-Sword} Bible translation abbreviations.
    (These are apparent when you make your choice of Bible version to
    download.) For example, place
\begin{Verbatim}[xleftmargin=\amtIndent]
\addtoBibles{ASV,YLT}
\end{Verbatim}
    in the preamble to specify the American Standard Version (\texttt{ASV}) and Young's
    Literal Translation (\texttt{YLT}), assuming these versions are available
    on your system.

    \paragraph*{Example} \verb|\fetchverses[from=YLT]{Gen 1:1-2}| yields,
    \begin{quote}
        \fetchverses[from=YLT]{Gen 1:1-2}
    \end{quote}

\subsubsection{Setting the default Bible}
You can set your own default Bible using the \cs{defaultBible} command.
\bVerb\takeMeasure{\string\defaultBible\darg{\ameta{transl}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\defaultBible{!ameta(transl)}
\end{dCmd}
\eVerb where \ameta{transl} is the name of a Bible translation assigned by
the \app{e-Sword} application. The name \ameta{transl} must be a recognized
Bible translation: KJV, KJV+, ISV, or any Bible translation registered by the
\cs{addtoBibles} command. The command
\cs{fbdefaultBible}\marginpar{\small\raggedleft\cs{fbdefaultBible} defined}
holds the (current) default Bible abbreviation.

Other than the ones initially defined (\texttt{KJV}, \texttt{KJV+}, and
\texttt{ISV}), a Bible translation can be added on with the \cs{addtoBibles}
command, or by adding in a new Bible translation in the \EXT{CFG};
see \hyperref[s:cfg]{Section~\ref*{s:cfg}} for more information on how to do
this.

\paragraph*{Example} Purchase, download and install \texttt{NKJV} (a premium Bible)
and declare in a document:
\begin{Verbatim}[xleftmargin=\amtIndent]
\addtoBibles{NKJV}
\defaultBible{NKJV}
\end{Verbatim}
With these declarations, the command \cs{fetchverse\darg{Gen 1:1}} fetch \texttt{Gen 1:1}
from \texttt{NKJV}, assuming such verses exist in any of the \texttt{DEF} files that are
specified by the \opt{useverses} option.

\subsubsection{The \texorpdfstring{\protect\cs{useBookStyle}}{\textbackslash{useBookStyle}} command}\label{para:useBookStyle}
You can design your own default key-values using the \cs{useBookStyle} command.
\bVerb\takeMeasure{\string\useBookStyle\darg{\ameta{opts}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\useBookStyle{!ameta(opts)}
\end{dCmd}
\endgroup\noindent where \ameta{opts} is a comma-delimited list of key-values for
the fetch verses commands. This command may be used in the body of the
document to change the style.

\paragraph*{Example}
Declaring \cs{useBookStyle\darg{abbr=none,roman}}\cs{fetchverse\darg{1Co 1:1}}
produces the following passage:
\begin{quote}
\useBookStyle{abbr=long,roman=true}\fetchverse{1Co 1:1}
\end{quote}
The \pkg{fetchbibpes} package uses \cs{useBookStyle} to initially declare,
\begin{Verbatim}[xleftmargin=\amtIndent]
\useBookStyle{abbr,roman=false,from,transl}
\end{Verbatim}
The changes are local to any group in which they are made.

As with the fetch command options, see \textbf{\mlnameref[\linktxtcolor{webgreen}]{para:PredefHelper}}
on page~\pageref*{para:PredefHelper}, the first token in the argument of
\cs{useBookStyle} is expanded using \cs{expandafter}, this means that the
first token can be a macro command of key-values; for example,
\cs{useBookStyle\darg{\cs{Optsi,caps}}} sets the book style to your favorite
options (\cs{Optsi}), plus the \opt{caps} option.

When declared outside a group, the changes are considered global, which may
not always be what is wanted. For example, if we declare \cs{useBookStyle\darg{pcolor=blue}}, then all passages
are colored blue by default.
\begin{quote}\useBookStyle{pcolor=blue}%
\verb|\useBookStyle{pcolor=blue}|\\[3pt]
\verb|\fetchverse{Gen 1:1}|
results in \fetchverse{Gen 1:1} This may
not be what is wanted within a paragraph presentation. To revert to
default black passage text, use \opt{pcolor} with no
value. Thus, \verb|\fetchverse[pcolor]{Gen 1:1}|, yields
\fetchverse[pcolor]{Gen 1:1}
\end{quote}

\subsubsection{\texorpdfstring{\protect\cs{usePassage}}{\textbackslash{usePassage}}:
    The raw retrieval of a passage}

The \cs{fetchverse} and \cs{fetchverses} command are rather complex in
that they must process any of the many options before it produces the
passage. There may be an application to simply retrieving the passage
without any frills; in this case use \cs{usePassage}:
\bVerb\takeMeasure{\string\usePassage\darg{\ameta{verse-ref}}}%
\begin{dCmd}[commandchars=!~@]{\bxSize}
\usePassage{!ameta~verse-ref@}
\end{dCmd}
\eVerb where \ameta{verse-ref} is the argument of the \cs{BV} command as it is specified in one of
the \EXT{DEF} files. Thus, if we type \verb|\usePassage{Gen 1:1 KJV}|, we get,
\begin{quote}
\usePassage{Gen 1:1 KJV}
\end{quote}
That is, you get the `raw' passage without any annotations (translation, book, chapter, verse, and so on).
Only one passage (verse) may be retrieved this way.

\subsubsection{\texorpdfstring{{\protect\mlcs{fetchversestxt}}}{\textbackslash{fetchversestxt}}:
 raw retrieval with options}\label{fvtxt}

\def\myNote{type=text,name=Note,color=webyellow}


One user, a former friend, requested something more sophisticated than \cs{usePassage}. He wanted a \cs{fetchverses}-type
command, but with no typesetting commands embedded, just pure text. He would then pass the text as the argument of another
command.

\bVerb\takeMeasure{\normalfont{Each of these defines two macros: }\ttfamily\string\versetxt,\,\string\passagetxt}%
\setlength{\dimen0}{\bxSize}%
\def\1{\rlap{\hskip\dimen0\relax\ding{192}}}%
\def\2{\rlap{\hskip\dimen0\relax\ding{193}}}%
\def\3{\rlap{\hskip\dimen0\relax\ding{194}}}%
\def\4{\rlap{\hskip\dimen0\relax\ding{195}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\fetchversestxt[!ameta(opts)]{!ameta(book)(!vissp)!ameta(ch):!ameta(vrs)}
\fetchversestxt[!ameta(opts)]{!ameta(book)(!vissp)!ameta(ch):!ameta(vrs)-}
\fetchversestxt[!ameta(opts)]{!ameta(book)(!vissp)!ameta(ch):!ameta(vrs!SUB(1))-!ameta(vrs!SUB(2))}
!STRUT!normalfont(Each of these defines two macros: )!ttfamily(\versetxt,!,\passagetxt)
\end{dCmd}
\eVerb The \cs{fetchversestxt} command does not expand to typeset content,
rather, it defines two commands \cs{versetxt}, which contains the verse
reference, and \cs{passagetxt}, which contains the passage for that verse.
For example, \cs{fetchverses\darg{Gen 1:1-2}}\fetchversestxt{Gen 1:1-2}
expands to nothing typeset; however, the command `\cs{versetxt}' expands
to `\versetxt' and the command `\cs{passagetxt}' expands to `\passagetxt' The next
expansion of \cs{fetchversestxt} overwrites the \cs{versetxt} and
\cs{passagetxt} commands. You can use \cs{fetchversestxt} with the usual
options, any formatting options are ignored (I hope), otherwise, all options
should work as described earlier.

The application\fetchversestxt[showfirst]{Gen 1:1-}\annotpro[presets=\myNote,
margin,readonly,title={\versetxt},margintext={\hfill\versetxt},margprior=\hfill]{\passagetxt} my former friend had in mind
was to pass the \cs{passagetxt} command to an annotation macro such as \cs{annotpro} (\pkg{annot\_pro} package) or
\cs{pdfcomment} (\pkg{pdfcomment} package). What you see in the margin is \cs{annotpro}.
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
The application\fetchversestxt[showfirst]{Gen 1:1-}\annotpro[type=text,
  name=Note,color=webyellow,margin,readonly,
  title={\versetxt},margintext={\hfill\versetxt},
  margprior=\hfill]{\passagetxt}
my former friend had in mind ...
\end{Verbatim}
Refer to the manual, \texttt{annotpro\_man.pdf} for the particulars of using \cs{annotpro} from the
\pkg{annot\_pro} package.

\paragraph[The \texttt{typeset} option]{The \texttt{typeset} option.}
The \cs{fetchversestxt} command accepts \texttt{typeset} (see
page~\pageref{item:typeset} for a description) as an option. Without the
\opt{typeset} option, \cs{passagetxt} does not contain any {\LaTeX} styling
or font changes; if the \opt{typeset} option is taken,  \cs{passagetxt}
expands to the same passage as its non-txt counterpart. The accompanying
demonstration file \texttt{fetchversestxt.tex} extensively discusses the
\opt{typeset} option.

\newtopic\noindent
The demonstration file for this feature is \texttt{fetchversestxt.tex}. It
includes several examples of the use of \texttt{typeset} and
\texttt{typeset*} with both commands \cs{fetchverses} and \cs{fetchversestxt}, with
and without a value for the key.

\paragraph[Cobbling together verses]{Cobbling together verses.} In this paragraph the \cs{cobblevrs} command
is discussed and illustrated.
\bVerb\takeMeasure{\string\cobblevrs*\darg{\ameta{\cs{cmd}}\darg{\ameta{text}}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\cobblevrs*{!ameta(\cmd)}{!ameta(text)}
\end{dCmd}
\endgroup\noindent \cs{cobblevrs} takes \ameta{text} and adds it to the end
of the text macro \ameta{\cs{cmd}}. If \ameta{\cs{cmd}} is undefined
initially, \cs{cobblevrs} defines it as to be empty; if \ameta{\cs{cmd}} is
already defined, \cs{cobblevrs} adds \ameta{text} to \ameta{\cs{cmd}}. If
\ameta{\cs{cmd}} is already defined (perhaps used previously by
\cs{cobblevrs}), to empty its contents before using again (with
\cs{cobblevrs}) use the star-version of the command.

The \cs{cobblevrs} command was designed to be used with the commands \cs{versetxt} and \cs{passagetxt} generated
by \cs{fetchversetxt}, but can be use for any purpose. Example of intended usage:
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()]
\fetchversestxt[typeset,abbr=none]{Gen 1:1}\cobblevrs*\holdverses
  {(\versetxt)\space\passagetxt}
\fetchversestxt[typeset,from*=ISV]{Gen 1:1}\cobblevrs\holdverses
  { Now, the same quote from ISV: (\versetxt)\space\passagetxt}
\fetchversestxt[typeset,from*=YLT]{Gen 1:1}\cobblevrs\holdverses
  { Again, but now from YLT: (\versetxt)\space\passagetxt}%
\holdverses % !normalfont(expand our cobbled verses)
\end{Verbatim}
The \cs{holdverses} macro then expands to the following paragraph:
\begin{fpquote}
\fetchversestxt[typeset,abbr=none]{Gen 1:1}\cobblevrs*\holdverses
  {(\versetxt)\space\passagetxt}
\fetchversestxt[typeset,from*=ISV]{Gen 1:1}\cobblevrs\holdverses
  { Now, the same quote from ISV: (\versetxt)\space\passagetxt}
\fetchversestxt[typeset,from*=YLT]{Gen 1:1}\cobblevrs\holdverses
{ Again, but now from YLT: (\versetxt)\space\passagetxt}\holdverses
\end{fpquote}
\cs{cobblevrs} is a tool that is available if ever needed. The demo file for this feature
is \texttt{fetchversestxt\_cobble.tex}.

\subsection{Formatting the translation note}

By ``translation note'', we mean the value of the \texttt{transl} key. By default, the note appears
as plain text following the Bible reference and a space.
\begin{fpquote}[]
\verb|\fetchverses*[from=ISV,transl=ISV]{Gen 1:1}|\\
\fetchverses*[from=ISV,transl=ISV]{Gen 1:1}
\end{fpquote}

\subsubsection{Formatting through the \texorpdfstring{\protect\texttt{transl}}{\textbackslash{transl}} key}

In the next two paragraphs, we comment on formatting the translation note using the \texttt{transl} key.

\paragraph[Using \texorpdfstring{\protect\cs{fetchverses}}{\textbackslash{fetchverses}}]{Using \texorpdfstring{\protect\cs{fetchverses}}{\textbackslash{fetchverses}}.}
The translation note may be formatted for \emph{individual passages} using the
\texttt{transl} key.
\emph{Simple textual formatting} is possible, such as
\begin{fpquote}[]
\verb|\fetchverses*[from=ISV,transl={- ISV}]{Gen 1:1}|\\
\fetchverses*[from=ISV,transl={- ISV}]{Gen 1:1}
\end{fpquote}
You can change font styles as well.
\begin{fpquote}[]
\verb|\fetchverses*[from=ISV,transl=\textbf{ISV}]{Gen 1:1}|\\
\fetchverses*[from=ISV,transl=\textbf{ISV}]{Gen 1:1}
\end{fpquote}

\paragraph[Using \texorpdfstring{\protect\cs{fetchversestxt}}{\textbackslash{fetchversestxt}}]{Using \texorpdfstring{\protect\cs{fetchversestxt}}{\textbackslash{fetchversestxt}}.}
The command \cs{fetchversestxt} does not produce any typeset material, but defines to macros
\cs{versetxt} and \cs{passagetxt}. Simple changes to the translation note are no problem:
\begin{fpquote}[]
\verb|\fetchversestxt[from=ISV,transl={- ISV}]{Gen 1:1}|\\
\fetchversestxt[from=ISV,transl={- ISV}]{Gen 1:1}\verb|\versetxt| now expands to \versetxt
\end{fpquote}
To individually change the font styling, we have to protect style change with \cs{protect},
\begin{fpquote}[]
\verb|\fetchversestxt[from=ISV,|\\
\null\qquad\verb|transl={- |\textbf{\texttt{\string\protect}}\verb|\textbf{ISV}}]{Gen 1:1}|\\
\fetchversestxt[from=ISV,transl={- \protect\textbf{ISV}}]{Gen 1:1}\verb|\versetxt| expands to \versetxt
\end{fpquote}
Above, the \cs{protect} command is shown in bold font for emphasis.

\subsubsection{Setting the default format}

Another way to set the formatting of the translation note is by changing the default formatting. (The default is
plain text preceded by a space.)

\paragraph{\texorpdfstring{\protect\cs{fetchverses}}{\textbackslash{fetchverses}}}

As mentioned above, the default format is just plain text, though individual changes can be
made through the \texttt{transl} key. To change the default formatting for \cs{fetchverses} and \cs{fetchverse},
use the \cs{translFmt} command.
\bVerb\takeMeasure{\string\translFmt\darg{\ameta{fmt-transl-\#1}}}%
\setlength{\dimen0}{\bxSize}\edef\temp{\the\dimen0}\setlength{\dimen0}{\linewidth-\temp}%
\def\1{\makebox[0pt][l]{\hspace{\temp}\enspace\textrm{(}\string\translFmt\darg{\string\space\#1}\textrm{)}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\translFmt{!ameta(fmt-transl-#1)}
!1\translFmtDef
\end{dCmd}
\endgroup\noindent Within the argument of \cs{translFmt}, use \texttt{\#1} to symbolically represent the value of the \texttt{transl} key. The default
declaration for \cs{translFmt} is given to the right in parentheses.
For example,
\begin{fpquote}[]
\verb|\translFmt{ - \textbf{#1}}| (Note space after left brace)\\
\verb|\fetchverses*[from*=ISV]{Gen 1:1}|\\
\translFmt{ - \textbf{#1}}%
\fetchverses*[from*=ISV]{Gen 1:1}
\end{fpquote}
The presentation for the translation note becomes a hyphen followed by the
value of \texttt{transl} in bold font. This presentation of the translation
note will continue until you either leave the group where \cs{translFmt} was
used, or you expand \cs{translFmtDef} to return the presentation  to its
package default, given above to the right in parentheses.


\paragraph[\texorpdfstring{\protect\cs{fetchversestxt}}{\textbackslash{fetchversestxt}}]{\texorpdfstring{\protect\cs{fetchversestxt}}{\textbackslash{fetchversestxt}}.}

When using \cs{fetchversestxt}, change the default presentation style for the translation note using
\cs{translTxtFmt} and \cs{translTxtDef}.
\bVerb\takeMeasure{\string\translTxtFmt\darg{\ameta{fmt-transl-\#1}}}%
\setlength{\dimen0}{\bxSize}\edef\temp{\the\dimen0}\setlength{\dimen0}{\linewidth-\temp}%
\def\1{\makebox[0pt][l]{\hspace{\temp}\enspace\textrm{(}\string\translTxtFmt\darg{\string\space\#1}\textrm{)}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\translTxtFmt{!ameta(fmt-transl-#1)}
!1\translTxtFmtDef
\end{dCmd}
\endgroup\noindent These declarations only effect the \cs{versetxt} command defined by \cs{fetchversestxt}. Thus,
\begin{fpquote}[]
\verb|\translTxtFmt{ - \textbf{#1}}| (Note space after left brace)\\
\verb|\fetchversestxt[from*=ISV]{Gen 1:1}|\\
\translTxtFmt{\space- \textbf{#1}}%
\fetchversestxt[from*=ISV]{Gen 1:1}\versetxt
\end{fpquote}

When using \cs{fetchversestxt}, a common presentation style is given in the next example:
\begin{fpquote}[]
\verb|translTxtFmt{ (#1)}| (Note space after left brace)\\
\verb|\fetchversestxt[from*=ISV]{Gen 1:1}|\\
\translTxtFmt{ (#1)}%
\fetchversestxt[from*=ISV]{Gen 1:1}\verb|\versetxt| expands to \versetxt
\end{fpquote}
The sample file \texttt{fetchversestxt.tex} illustrates \cs{translTxtFmt}.

\subsection{Setting various spaces}

\subsubsection{The space prior to the reference for
\texorpdfstring{\protect\opt{citeatend}}{citeatend}}

When the option \texttt{citeatend=true}, the \cs{priorRefSpc} command sets the
spacing between the passage and the reference.
\bVerb\takeMeasure{\normalfont{Other choices for \ameta{arg} are \cs{fbFitItIn} and \cs{fbFillRght}}}%
\begin{dCmd}[commandchars=!~@]{\bxSize}
\priorRefSpc{!ameta~arg@}!quad!normalfont(!ttfamily\space!normalfont)
!normalfont~Other choices for !ameta~arg@ are !cs~fbFitItIn@ and !cs~fbFillRght@@
\end{dCmd}
\endgroup\noindent
Without any declaration, the default argument is \cs{space} (shown in parentheses); other
choices are also listed above for the \ameta{arg}. The \ameta{arg} can be some other custom
declaration.

\paragraph*{Examples} We illustrate the effects of \cs{priorRefSpc}.
\begin{quote}\useBookStyle{showfirst,citeatend}
\verb|\fetchverses*{Gen 1:1-2}| (the default)\\[3pt]
\fetchverses*{Gen 1:1-2}

\verb|\priorRefSpc{\fbFillRght}\fetchverses*{Gen 1:1-2}|\\[3pt]
\priorRefSpc{\fbFillRght}\fetchverses*{Gen 1:1-2}

\verb|\priorRefSpc{\fbFitItIn}\afterBookSpc{\nobreak\ }%|\\
\verb|\fetchverses*{Gen 1:1-2}|\\[3pt]
\priorRefSpc{\fbFitItIn}\afterBookSpc{\nobreak\ }\fetchverses*{Gen 1:1-2}
 \end{quote}

\subsubsection{Setting the space after the book name}\leavevmode
\bVerb\takeMeasure{\string\afterBookSpc\darg{\ameta{value}}\quad\normalfont(\texttt{\string\ })}%
\begin{dCmd}[commandchars=~!@]{\bxSize}
\afterBookSpc{~ameta!value@}~quad~normalfont(~ttfamily\~vissp~normalfont)
\resetAfterBookSpc
\end{dCmd}
\endgroup\noindent The \meta{value} of the \cs{afterBookSpc} determines the
spacing just after the book name and before the chapter and verse, it is
normally a hard space (\cs{\vissp}). However, you can pass a different value.

\paragraph*{Example} Illustrate the placement of the \meta{value} of
\cs{afterBookSpc}:
\begin{quote}
\verb|\afterBookSpc{\textbf{!!}}\fetchverse{Mat 2:1}\resetAfterBookSpc|\\[3pt]
\afterBookSpc{\textbf{!!}}\fetchverse{Mat 2:1}\resetAfterBookSpc
\end{quote}
The command \cmd{\resetAfterBookSpc} resets the change by to its default. In
the example, the use of \cmd{\resetAfterBookSpc} was not needed since the
change occurred within a \texttt{quote} environment. A declaration of
\cmd{\afterBookSpc\darg{}} removes the space completely. There may be some
application to this command.

\subsubsection{The space following the passage reference}\leavevmode
\bVerb\takeMeasure{\string\afterRef\darg{\ameta{value}}\quad\normalfont(\texttt{\string\@empty})}%
\begin{dCmd}[commandchars=~!^]{\bxSize}
\afterRef{~ameta!value^}~quad~normalfont(~ttfamily\@empty~normalfont)
\end{dCmd}
\endgroup\noindent The \cmd{\afterRef} command places its \ameta{value} immediately following
the passage \emph{reference} when the option \opt{citeatend} is \emph{not in effect}:
\begin{quote}
\verb|\afterRef{\textbf{!!}}\fetchverses*{1Jn 1:1}|\\[3pt]
\afterRef{\textbf{!!}}\fetchverses*{1Jn 1:1}
\end{quote}
The default value is \cs{space} obtained by declaring \cmd{\afterRef\darg{}}
with the empty argument. To get no space after the passage reference and the
beginning of the passage use \cmd{\afterRef\darg{\darg{}}}; this latter
declaration was used in the example of the \opt{priorref} key of the fetch
commands.

\subsubsection{The space between the book and book number}\leavevmode
\bVerb\takeMeasure{\string\afterBookSpc\darg{\ameta{value}}\quad\normalfont(\texttt{\string\space})}%
\begin{dCmd}[commandchars=~!@]{\bxSize}
\afterBookSpc{~ameta!value@}~quad~normalfont(~ttfamily\space~normalfont)
\resetAfterBookSpc
\end{dCmd}
\endgroup\noindent
The \cs{afterBookSpc} places \ameta{value} between the book number and the book,
if there is a book number. (E.g., 1 Corinthians).

\paragraph*{Example} Remove the space and use roman numbers:
\begin{quote}
\verb|\afterNumSpc{}\fetchverse[abbr=none]{1Co 1:1}|\\[3pt]
\afterNumSpc{}\fetchverse[abbr=none]{1Co 1:1}\\[6pt]
\verb|\afterNumSpc{}\fetchverse[abbr=none,roman]{1Co 1:1}|\\[3pt]
\afterNumSpc{}\fetchverse[abbr=none,roman]{1Co 1:1}
\end{quote}
Of course, the default is to leave a space between the number and the book.
\begin{quote}
\verb|\fetchverse[abbr=none,roman]{1Co 1:1}|\\[3pt]
\fetchverse[abbr=none,roman]{1Co 1:1}
\end{quote}


    \subsection{Formatting the verse numbers}\label{s:VerseNumbers}

    We define three commands to support the formatting of the verse numbers.
\bVerb\takeMeasure{\string\renewcommand\string\verseFmt{\ameta\darg{tex\_code\_for\_\#1}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\renewcommand\verseFmt{!ameta(tex_code_for_#1)}
\verseFmtReset
\end{dCmd}
\endgroup\noindent
The definition of \cs{verseFmt} determines the formatting of the verse number
in the passage; the argument of \cs{verseFmt} (\texttt{\#1}) is the verse
number. There is a default definition is
\begin{Verbatim}[xleftmargin=\amtIndent]
\newcommand{\verseFmt}[1]{\verseFmtDef{#1}}
\end{Verbatim}
where \cs{verseFmtDef} is the default command to typeset the verse numbers as
a superscript. (We don't present its definition in this documentation.)

After redefinition, to return to the default definition, just expand
\cmd{\verseFmtReset}. Of course, \cmd{\verseFmtDef} may be redefined to have
a different default definition. (Refer to \texttt{fetchbibpes.dtx} for its definition.)

 Below are verses showing the default representation of the verse numbers.
\begin{quote}
 \fetchverses*[showfirst,abbr=none]{Gen 1:1-5}
 \end{quote}
 The verse numbers appear as superscripts prior to the passages.

 However, this formatting can be redefined to obtain the style of numbers you want.
 In the passage that follows, I've changed the formatting style seen in some
 Bibles of the multiple passages.
\begin{quote}[1]
\newlength\verseBoxLength
\settowidth{\verseBoxLength}{\normalsize\normalfont000}
\renewcommand{\verseFmt}[1]{\par\noindent\makebox[\verseBoxLength][c]{#1}}
\afterRef{\par\kern3pt}
\fetchverses*[showfirst,delims,caps,format={\bfseries\sffamily},abbr=none]{Gen 1:1-5}
\end{quote}
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\begin{quote}
\newlength\verseBoxLength
\settowidth{\verseBoxLength}{\normalsize\normalfont000}
\renewcommand{\verseFmt}[1]{\par\noindent
    \makebox[\verseBoxLength][c]{#1}}
\afterRef{\par\kern3pt}
\fetchverses*[showfirst,delims,caps,
    format={\bfseries\sffamily},abbr=none]{Gen 1:1-5}
\end{quote}
\end{Verbatim}
It is not necessary in this example for the changes occurred within a group,
but to switch back to the default verse number style, we
declare \cs{afterRef\darg{}}\cs{verseFmtReset}.

\newtopic
The description of \opt{pcolor=\ameta{color}} on \autopageref{item:pcolor} has another example of
redefining \cs{verseFmt}.

\paragraph*{See demo file:} See the demo file \texttt{bibpes\_tst.tex} for a
working version of this example.

\newtopic\noindent
Immediately following the verse number is an opportunity to insert an
additional command (as a function of the verse number).
\bVerb\takeMeasure{\string\afterVerseFmt\darg{\meta{\string\cmd}}%
\quad\normalfont(\ttfamily{\string\afterVerseFmt\darg{}}\normalfont)}%
\begin{dCmd}[commandchars=!~@]{\bxSize}
\afterVerseFmt{!meta~\cmd@}!quad!normalfont(!ttfamily~\afterVerseFmt{}@!normalfont)
\end{dCmd}
\endgroup\noindent where \meta{\cs{cmd}} is a command taking one argument, the verse number.
 Consider the following quotation:
\begin{quote}\def\mrk#1{\textbf{!!Verse~#1!!}}\afterVerseFmt{\mrk}
\fetchverses[showfirst]{Gen 1:1-2}
\end{quote}
The verbatim listing of the above is
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\begin{quote}\def\mrk#1{\textbf{!!Verse~#1!!}}\afterVerseFmt{\mrk}
\fetchverses[showfirst]{Gen 1:1-2}
\end{quote}
\end{Verbatim}
This is not a very interesting application, but a more interesting use of
this command lies ahead. To revert to the default definition execute
\cs{afterVerseFmt\darg{}} with the empty argument.

\subsection{Dealing with \textsl{Strong's Concordance} numbers}

When the \texttt{KJV+} is used, for example, the text is annotated with
cross-references to \textsl{Strong's Concordance}. In the text file, the
references are of the form `\texttt{G\string|H\string\d+}', where
\texttt{\string\d+} means one or more natural numbers, `\texttt{G}' and
`\texttt{H}' refer to the Greek and Hebrew scriptural texts. The references
come through in the \EXT{TXT} files as `\texttt{G3739}' or `\texttt{H7225}'. When
using the \app{WinEdt} editor, you can use a regular expression find and
replace these references with command versions (e.g., \verb|\G{3739}| or
\verb|\H{7225}|):
\begin{quote}
\begin{tabular}{ll}
\textbf{Greek Strongs} & \textbf{Hebrew Strongs}\\
find: \verb|G\(+$Numeric$\)| & find: \verb|H\(+$Numeric$\)|\\
replace: \verb|\\G\{\0\}| & replace: \verb|\\H\{\0\}|
\end{tabular}
\end{quote}

\paragraph*{Macro File.} This can be done in either the \EXT{TXT} or \EXT{DEF} file. If you are using \textsf{WinEdt}, you can use the specially
written Macro File \texttt{bibpes\_strongs.edt}, which is found in the
\texttt{extras} folder. Open the \EXT{TXT} or \EXT{DEF} file (\EXT{DEF}
preferred) in \app{WinEdt}.

\subparagraph*{Procedure.} The procedure for using this Macro File is a follows:
(1) Use the menu \texttt{Macro\thinspace>\thinspace Execute Macro Script},
browse for \texttt{bibpes\_strongs.edt} and select it; (2) the Find and
Replace dialog box opens with various fields pre-filled; (3) Press `Replace
All', and the regular expression find and replace looks for expressions of
the form \texttt{Gnnnn} or \texttt{Hnnnn}, and replaces them with \verb|\G{nnnn}|
and \verb|\H{nnnn}|. The definitions of \cs{G} and \cs{H} follow; they may be
redefined.

\paragraph*{Example} Below is an example from \texttt{KJV+}, with annotations
to \textsl{Strong's Concordance}.

\begin{quote}
\verb|\fetchverses*[useperiod=false,abbr=short,from*=KJV+]{Rom 1:1}|\\[3pt]
\fetchverses*[useperiod=false,abbr=short,from*=KJV+]{Rom 1:1}

\end{quote}

\subsection{The \EXT{CFG} file of the package}\label{s:cfg}

Unless the option \marginpar{\small\raggedleft\opt{ignorecfg} option}\opt{ignorecfg} option
appears in the option list of \pkg{fetchbibpes}, the configuration file
\texttt{fbpes.cfg} is input at the end of the package.

There is not much to `configure' in this package, however. The application
that was in mind when this feature was created is the redefinition of the
\opt{from} key of the fetch command options.
\bVerb\takeMeasure{\string\registerBibles\darg{\ameta{comma-delimited-list}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\defaultBible{!ameta(transl)}
\registerBibles{!ameta(comma-delimited-list)}
\end{dCmd}
\endgroup\noindent The above is the suggest contents of the \texttt{fbpes.cfg}: (1) first establish
the default Bible, if different than the one already declared; (2) list the
Bible translations to be `registered'. The registered Bibles will be
recognized by the \texttt{from} key, without having to first pass them
through the \cs{addtoBibles} command (\Nameref{ss:addtoBibles}).

For example, you may routinely use many more books than the minimal ones set up by this package, so
in your own \EXT{CFG} file you might define,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\defaultBible{NKJV}
\registerBibles{NKJV,KJV,KJV+,ISV,RV,YLT}
\end{Verbatim}
The \cs{registerBibles}\marginpar{\small\raggedleft\cs{registerBibles}
discussed} is a command not previously mentioned. Its argument is a
comma-delimited list of Bible translations recognized by \textsf{e-Sword}.

A less complicated method that does not modify the definition of the
\opt{from} key of the \texttt{fbpes} family is to simply use the
\cs{addtoBibles} command in the \EXT{CFG} file. For example, in the \EXT{CFG}
you can have,
\begin{Verbatim}[xleftmargin=\amtIndent]
\defaultBible{NKJV}
\addtoBibles{NKJV,RV,YLT}
\end{Verbatim}
The \pkg{fetchbibpes} package already recognizes \texttt{KJV}, \texttt{KJV+}, and \texttt{ISV},
the above declarations adds to this list and makes \texttt{NKJV} the default Bible.

\subsection{Marginal notes}
We introduce a scheme for placing notes in the margins. The \cs{verseCmts}
command is used to define the notes (comments), each note corresponds to
a verse.
\bVerb\def\lp{(}\def\rp{)}\takeMeasure{\qquad\darg{\ameta{comment\SUB{n}}}\qquad
{\% \normalfont(second comment of passage)}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\verseCmts{
!qquad{!ameta(comment!SUB1)}!qquad(% !normalfont!lp(first comment of passage)!rp)
!qquad{!ameta(comment!SUB2)}!qquad(% !normalfont!lp(second comment of passage)!rp)
!qquad...
!qquad{!ameta(comment!SUB(n))}!qquad(% !normalfont!lp(last comment of passage)!rp)
}
\end{dCmd}
\endgroup\medskip\noindent
For example, the following declaration is used in the example below.
\begin{Verbatim}[xleftmargin=\amtIndent]
\verseCmts{%
  {In the beginning God creates\dots}    % v1
  {Earth void}                           % v2
  {Light!}                               % v3
  {}                                     % v4
  {First day}                            % v5
}
\end{Verbatim}
Its argument is a series of tokens (comments enclosed in braces), the first token is the comment
for verse 1, then verse 2, and so on. All verses must have a comment, even an empty comment.

The marginal notes are placed in the margin using \cs{marginpar}. The formatting for the marginal
notes is set by \cmd{\fbMarParFmt}:
\bVerb\takeMeasure{\qquad\string\marginpar\darg{\string\footnotesize%
\string\raggedright\string\verseFmt\darg{\string\vrseNum}\#1}\}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\newcommand{\fbMarParFmt}[1]{%
!qquad\marginpar{\footnotesize\raggedright\verseFmt{\vrseNum}#1}}
!STRUT\fbResetMarParFmt
\end{dCmd}
\endgroup\noindent The default definition of \cs{fbMarParFmt} is seen above.
The command may be redefined as needed. (This is done in the demo file
\texttt{bibpes\_tst.tex}.) If \cs{fbMarParFmt} is redefined, then expanding
\cs{fbResetMarParFmt} returns it to its original definition.

Now to make this all work -- that is, to make marginal comments appear -- you
need two more commands, these are \cmd{\fbMarNotesOn} and
\cmd{\fbMarNotesOff}. The former to turn on marginal notes, the latter to
turn switch off again.
\bVerb\takeMeasure{\string\fbMarNotesOn\quad\string\fbMarNotesOff}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\fbMarNotesOn!quad\fbMarNotesOff
\end{dCmd}
\endgroup\noindent Both make a \cmd{\afterVerseFmt} declaration to insert the marginal
the marginal notes (\cmd\fbMarNotesOn) or to turn off the insertion
(\cmd\fbMarNotesOff).

\paragraph*{Example} Begin by expanding \cs{fbMarNotesOn}, then using the \cs{verseCmts}
declared above, we fetch some verses.
\fbMarNotesOn
\verseCmts{%
    {In the beginning God creates\dots}
    {Earth void}
    {Light!}
    {}
    {First day}
}
%\bgroup
%\normalmarginpar
%\oddsidemargin=80pt
%\marginparpush0pt
\begin{fpquote}[leftmargin=0pt,rightmargin=\marginparsep+80pt]
\normalmarginpar\oddsidemargin=80pt\marginparpush0pt
\renewcommand{\fbMarParFmt}[1]{\marginpar{\footnotesize
    \makebox[0pt][r]{\verseFmt{\vrseNum}\parbox[t]{\oddsidemargin}{\raggedright\strut#1\strut}%
    \hspace{\marginparsep}}\hfill}}\afterRef{\par\kern3pt}%
%
\fetchverses*[showfirst,delims,caps,format={\bfseries\sffamily},abbr=none]{Gen 1:1-5}
\end{fpquote}\verseCmts{}\fbMarNotesOff
After this passage, we turn everything off with \verb|\fbMarNotesOff\verseCmts{}|, not required
if the passage is within a group.

Actually, for this example there is extensive background redefinitions to fit the marginal
notes to appear within the margins, as seen above.

\paragraph*{Demo file:} The verbatim listings for this example, as well as for
a basic example, are found in the demo file \texttt{bibpes\_tst.tex}.

\subsection{Retrieving only the verses needed}\label{s:sf}
    One user wants to have \emph{an entire book} (\texttt{1Jn}, for example) and to retrieve only the
    verses needed. Thus, if
\begin{quote}\ttfamily
\cs{BV}(\ameta{book}\vissp\ameta{chapter}:\ameta{verse}\vissp
    \ameta{transl})\vissp\ameta{passage}\cs{null}
\end{quote}
    is one of the required verses, it would be input as usual, otherwise the line
    is ignored.

To obtain selected verses, first specify the \marginpar{\small\raggedleft\opt{useselverses} option}\opt{useselverses}
option in the option list of \pkg{fetchbibpes}. (This option inputs this code
segment.) Now the document author needs to specify which of the verses
he or she is to use. For that purpose the \cs{selectedVersesFrom} is defined.
The syntax is presented next.
\bVerb\takeMeasure{\qquad\darg{from=\ameta{version},onlyverses=\darg{\ameta{verses}}}}%
\setlength{\dimen0}{\bxSize}\edef\temp{\the\dimen0}\setlength{\dimen0}{\linewidth-\temp}%
\def\1{\makebox[0pt][l]{\hspace{\temp}\smash{\parbox[t]{\dimen0}
{\normalfont\raggedright Recognized keys: \texttt{from}, \texttt{onlyverses}, \texttt{alt}}}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\selectedVersesFrom{
!1!qquad{from=!ameta(version),onlyverses={!ameta(verses)}}
   ...
}
\end{dCmd}
\endgroup\noindent The argument for \cs{selectedVersesFrom} is a series of key-values
enclosed in braces. Within the argument, three keys are recognized, \texttt{from},
\texttt{onlyversion}, and \texttt{alt}\marginpar{\small\raggedleft\texttt{from}, \texttt{alt}, \texttt{onlyversion}}. For example,
\begin{Verbatim}[xleftmargin=\amtIndent]
\selectedVersesFrom
{
  {onlyverses={1Jn 1:1-5,3:3-8}}
  {from=ISV,onlyverses={Gen 1:1-5}}
  {from=ISV,alt=Alt,onlyverses={Gen 1:1}}
  {onlyverses=Mat}
}
\end{Verbatim}
    It is assumed the required \EXT{DEF} files are listed in the value of
    the \texttt{useverses} option of \textsf{fetchbibpes}. Note that the
    syntax for the value of \texttt{onlyverses} is more general; in the
    \texttt{1Jn} book, the author intends to use verses \texttt{1:1-5} and
    \texttt{3:3-8}. Multiple references to the same book are separated by a
    comma. If the desired book is an alternate translation than the default
    one, use the \texttt{from} key, as above. In the case of \darg{onlyverses=Mat},
    all verses from the book of Matthew are excluded for no verses are specified.

    The book reference can be either the three-letter abbreviation of \app{e-Sword}
    of the acceptable alternate abbreviation, refer to the \textbf{\app{e-Sword} Abbr}
    and \textbf{Alt\_Abbr} columns of \hyperref[table:esabbr]{Table~\ref*{table:esabbr}}.

\paragraph*{Demo file:} See the test file \texttt{bibpes\_sf.tex}. Within this demo file,
many finer details are explained and illustrated.

\subsection{The \texorpdfstring{\protect\cs{sr}}{\CMD{sr}} command}\label{s:sr}

The \cs{sr} command is designed to be used with the \pkg{bibleref-parse}
package.
\bVerb\takeMeasure{\string\sr\darg{\ameta{text}}\darg{\ameta{passages}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\sr{!ameta(text)}{!ameta(passages)}
\end{dCmd}
\endgroup\noindent
    For \cs{sr} to be defined, the option \marginpar{\small\raggedleft
    \opt{usesr} option}\opt{usesr} must be specified in the options list of
    \pkg{fetchbibpes}.

    \cs{sr} is a command that takes two arguments, if the first one is non-empty,
    the \ameta{text} argument appears in \emph{italics}. The second
    argument, \ameta{passages}, are references to one or more books of the
    Bible and passages within the books. The syntax for the second argument
    is illustrated by an example:
\begin{quote}\ttfamily
Psa 91:3,14-16;1Co 11; Galatians 5:6
\end{quote}
    The first two books referenced uses the three-letter abbreviation of
    \textsf{e-Sword}, the last one (Galatians) uses a full book name. (Refer
    to \hyperref[table:esabbr]{Table~\ref*{table:esabbr}}) Multiple passages
    within the same book are separated by commas, while references of
    different books are separated by semicolons. There can be a space
    following a semicolon. This second argument is passed to the
    \cs{pibibleverse} command of the \textsf{bibleref-parse} package.

\paragraph*{Demo file:} The simple demo file is \texttt{bibps\_sr.tex}.

\subsection{The \texorpdfstring{\protect\env{declareBVs}}{declareBVs}
and \texorpdfstring{\protect\env{declareBVs*}}{declareBVs*} environment}\label{s:declareBVs}

The \env{declareBVs} and \env{declareBVs*} environments may be used
anywhere in the document -- preamble or body -- to declare Biblical
verses. Normally, it is used to declare verses not already included by
the \opt{useverses=\ameta{list}} option, or when there are no
\texttt{useverses} includes. The option \texttt{useverses=none} is
appropriate in this last case. The syntax for the content of the
\env{declareBVs} environment is,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\begin{declareBVs}
\BV(Gal 1:15 NKJV) But when it pleased God, who separated me from
    my mother's womb and called me through His grace,\null
\BV(Gal 1:16 NKJV) to reveal His Son in me, that I might preach Him
    among the Gentiles, I did not immediately confer with
    flesh and blood,\null
\end{declareBVs}
\end{Verbatim}
where \cs{BV} is the low-level command first discussed in
\hyperref[para:crtDEF]{Section~\ref*{para:crtDEF}} on
page~\pageref*{para:crtDEF}. The general syntax for \cs{BV} is,
\begin{quote}\ttfamily
\cs{BV}(\ameta{verse-ref})\vissp\ameta{passage}\cs{null}
\end{quote}
where \ameta{verse-ref} is the specification of the verse referenced. Note that
it is enclosed in parentheses, not braces. The general
form of \ameta{verse-ref} is given in the expanded display below.
\begin{quote}\ttfamily
\cs{BV}(\ameta{book}\vissp\ameta{chapter}:\ameta{verse}\vissp
    \ameta{transl}[\vissp\ameta{word}])\vissp\ameta{passage}\cs{null}
\end{quote}
The symbol `\texttt{\vissp}' here is a space-character (\emph{not} a
hard space). The \ameta{passage} ends with \cs{null}, which
acts as a delimiter for the \cs{BV} macro. Following \ameta{transl}
(which corresponds to the value of the \opt{from} key) is an optional
\opt{alt} \ameta{word} modification, refer to the discussion of the
\opt{alt} key on \autopageref{key:alt}.

Within the \env{declareBVs} environment, the passages can be allowed to wraparound, unlike
when they appear in a \EXT{DEF} file.

Once the passages are declared, they can be retrieved at any point thereafter:
\begin{quote}
\verb|\fetchverses*[from=NKJV]{Gal 1:15-16}|\\[3pt]
\fetchverses*[from=NKJV]{Gal 1:15-16}
\end{quote}

The \env{declareBVs} environment is used in the sample files \texttt{bibpes\_replace.tex},
\texttt{bibpes\_replaces.tex}, and \texttt{bibpes\_red.tex}.

The \env{declareBVs*} environment is the same as \env{declareBVs} but does not
define single and double quote as active characters. Refer to
\hyperref[ProbsQuotes]{Section~\ref*{ProbsQuotes}} for more information on quotation marks.

\subsection{Fetching a substring of a verse}\label{s:substr}

Why can't copy and paste just be used? A user wants it, I hear and obey.
The new code for extracting a substring of a (single) verse is loaded in
using the package option \opt{fetchsubtr}. The command tool for identifying the substring or substrings
of a verse to be extracted is \cs{makeverse}. The demonstration file for this feature is
\texttt{bibpes\_substr.tex}.
\bVerb\takeMeasure{\qquad\quad\darg{\ameta{bfind\SUB2}}%
\darg{\ameta{efind\SUB2}}...\darg{\ameta{bfind\SUB{k}}}\darg{\ameta{efind\SUB{k}}}}%
\setlength{\dimen0}{\bxSize}\edef\temp{\the\dimen0}\setlength{\dimen0}{\linewidth-\temp}%
\def\1{\makebox[0pt][l]{\hspace{\temp}\smash{\parbox[t]{\dimen0}
{\normalfont\raggedright Recognized keys: \texttt{from}, \texttt{onlyverses}, \texttt{alt}}}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\markverse[name=!ameta(name),from=!ameta(transl),
!qquad(marks={!ameta(bfind!SUB1)}{!ameta(efind!SUB1)})
!qquad!quad{!ameta(bfind!SUB2)}{!ameta(efind!SUB2)}...{!ameta(bfind!SUB(k))}{!ameta(efind!SUB(k))}
]{!ameta(book)(!vissp)!ameta(ch):!ameta(vrs)}
\end{dCmd}
\eVerb Only \emph{one verse may be marked off} at a time (of course
multiple uses of \cs{markverse} are permitted), but several substrings
within that verse may be marked off. There must be an even number of
\texttt{marks}. The substrings must be non-overlapping and the order the
markers appear in the list of \texttt{marks} is the order they appear in
the passage. The command \cs{markverse} uses the replace feature
developed earlier. The value of the \texttt{name} key must be unique
throughout all names declared by the \cs{markverse} command.

The marks (\ameta{bfind} and \ameta{efind}) are text (words or
phrases) found in the verse. Ideally, the marks \emph{should not contain any
quotes} (single or double) unless the verse is defined within the \env{declareBVs*}
environment, where quotes are not active.

Before illustrating, let's have a conceptual example. We begin with
\begin{quote}
\fetchverse{Gen 1:1}
\end{quote}
Suppose we wanted extract `In the beginning' and
`the heaven and earth' from this short verse. We use \cs{markverse} in this way:
\begin{quote}\ttfamily
\string\markverse[name=Gen1:1-,marks=\darg{In the}\darg{God}\\
\null\qquad\darg{the heaven}\darg{earth.}]\darg{Gen 1:1}
\end{quote}
When this command line is expanded, the supporting commands of the
\texttt{replace} key
(pages~\pageref*{item:replace}--\pageref*{para:replace}) are used to mark
up this passage, like so:
\begin{quote}\ttfamily\raggedright
\string\bMrkFP\space In the beginning God\string\eMrkFP\space created
\string\bMrkFP\space the heaven and the earth.\string\eMrkFP
\end{quote}
Each pair of marks is then used to scoop up the text string between them. Cool.

\markverse[name=Gen1:1-,marks={In the}{God}
{the heaven}{earth.}]{Gen 1:1}

Let's try now: The first substring is \fetchverses[alt=Gen1:1-1,enclosewith=\quote]{Gen 1:1};
the second substring is \fetchverses[alt=Gen1:1-2,enclosewith=\quote]{Gen 1:1}

The verbatim listing of the previous paragraph is,
\begin{Verbatim}[xleftmargin=\amtIndent]
Let's try now: The first substring is
\fetchverses[alt=Gen1:1-1,enclosewith=\quote]{Gen 1:1};
the second substring is
\fetchverses[alt=Gen1:1-2,enclosewith=\quote]{Gen 1:1}
\end{Verbatim}
The substrings are accessed through the fetch commands by concatenating
the value of the \ameta{name} key with the index of the substring (first
substring=1, second substring=2, and so on) and assigning it as the value
of the \texttt{alt} key.

The \cs{markverse} command saves the substrings to the file
\cs{jobname-bv.cut} and inputs them at the top of the file, as a result
it may take two compiles to see the changes. From the above
\cs{markverse} declaration, the file \texttt{\jobname-bv.cut} reads,
\begin{Verbatim}[xleftmargin=\amtIndent]
\begin{declareBVs*}
\BV(Gen 1:1 KJV Gen1:1-1) In the beginning God\null
\BV(Gen 1:1 KJV Gen1:1-2) the heaven and the earth.\null
\end{declareBVs*}
\end{Verbatim}
The substrings are accessed through the \texttt{alt} key of the fetch
commands. The declaration
\verb~\fetchverses[alt=Gen1:1-1,enclosewith=\quote]{Gen 1:1}~ retrieves
the \texttt{Gen 1:1 KJV Gen1:1-1} substring verse. Because the substrings are so
defined, the power of the fetch verse commands can be brought to bare.

\markverse[name=errorExmpl,marks={In the}{God}
{the Heaven}{earth.}]{Gen 1:1}

If a substring is not found (that is, for various reasons the
\ameta{bfind} and/or \ameta{efind} marks are not found), the an index
string is still defined and expands to an alert message. For example, we declare
\begin{quote}\ttfamily\raggedright
\string\markverse[name=errorExmpl,marks=\darg{In the}\darg{God}\linebreak
\null\qquad\darg{the Heaven}\darg{earth.}]\darg{Gen 1:1}
\end{quote}
You'll note the fourth mark is `the Heaven' not `the heaven' (the search
is case sensitive). What are the results:
\begin{itemize}
    \item \verb~\fetchverse[alt=errorExmpl1]{Gen 1:1}~:\\[3pt]\fetchverse[alt=errorExmpl1]{Gen 1:1}
    \item \verb~\fetchverse[alt=errorExmpl2]{Gen 1:1}~:\\[3pt]\fetchverse[alt=errorExmpl2]{Gen 1:1}
\end{itemize}
As predicted, search for the second substring failed, and we are so informed.

\paragraph*{Contiguous substrings.} One useful feature of the \texttt{marks}
key of \cs{markverse} is the odd numbered markers may be the empty
string. If one is empty, the search continues from where the previous
search stopped. The first example could have been posed as follows:
\begin{quote}\ttfamily
\string\markverse[name=Gen1:1-,marks=\darg{}\darg{God}\\
\null\qquad\darg{the heaven}\darg{earth.}]\darg{Gen 1:1}
\end{quote}
The first marker is empty (\darg{}) so the search begins where the
previous one left off, but this is the first search so the search begins
at the beginning of the verse. A more informative example would be the following.
Declare,

\begin{declareBVs*}
\BV(Mat 6:31 NKJV) ``Therefore do not worry, saying,
    `What shall we eat?' or `What shall we drink?' or
    `What shall we wear?'\null
\end{declareBVs*}

\begin{Verbatim}[xleftmargin=\amtIndent]
\begin{declareBVs*}
\BV(Mat 6:31 NKJV) ``Therefore do not worry, saying,
   `What shall we eat?' or `What shall we drink?' or
   `What shall we wear?'\null
\end{declareBVs*}
\end{Verbatim}
Note the presence of quote marks, hence, we declare this verse using \env{declareBVs*}.
We emit our \cs{markverse} command:
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\markverse[name=Mat6:31-,from=NKJV,
!quad(marks={}{eat?'}{}{drink?'}{}{wear?'}]{Mat 6:31})
\end{Verbatim}
\markverse[name=Mat6:31-,marks={}{eat?'}{}{drink?'}{}{wear?'},from=NKJV]{Mat 6:31}
Now, let's read out the substrings:
\begin{itemize}
    \item \verb~\fetchverse[alt=Mat6:31-1,from=NKJV]{Mat 6:31}~:\\[3pt]\fetchverse[alt=Mat6:31-1,from=NKJV]{Mat 6:31}
    \item \verb~\fetchverse[alt=Mat6:31-2,from=NKJV]{Mat 6:31}~:\\[3pt]\fetchverse[alt=Mat6:31-2,from=NKJV]{Mat 6:31}
    \item \verb~\fetchverse[alt=Mat6:31-3,from=NKJV]{Mat 6:31}~:\\[3pt]\fetchverse[alt=Mat6:31-3,from=NKJV]{Mat 6:31}
\end{itemize}
Contiguous substrings as promised!

In this example, \texttt{from=NKJV} was used in both the \cs{markverse}
and \cs{fetchverse} commands to identify the translation, this is
required if the passage comes from a translation other than the default
translation (KJV in this document).

\markverse[name=multihits,marks={`What}{wear?'},from=NKJV]{Mat 6:31}

\paragraph*{Warning!} Because the code for the \texttt{replace} feature is used, the entire verse is searched
for the  find text and replaced, possibly multiple times! Multiple
replacements in this context is never wanted, I would think. Therefore,
the markers \ameta{bfind} and \ameta{efind} should \emph{occur once and
only once} in the verse. For example the line
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\markverse[name=multihits,from=NKJV,
!quad(marks={`What}{wear?'}]{Mat 6:31})
\end{Verbatim}
produces the following \cs{BV} definition in the \texttt{\jobname-bv.cut} file:
\begin{quote}\ttfamily\raggedright
\string\BV(Mat 6:31 NKJV multihits1) `What shall we eat?' or
\string\bMrkFP\space`What shall we drink?' or \string\bMrkFP\space`What shall we
wear?'\null
\end{quote}
Oops, multiple \cs{bMrkFP} markers linger where they shouldn't.

\subsection{Some extended quote environment}

At the mild prompting of one of the (only two known) users, three environments are
also defined for quoting long passages. These are minor modifications of
the {\LaTeX} environments \env{quote}, \env{verse}, and \env{quotation}.
\bVerb\takeMeasure{\string\begin\darg{fpquotation}[\ameta{options}]}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\begin{fpquote}[!ameta(options)]
!qquad!ameta(content)
\end{fpquote}
!STRUT\begin{fpverse}[!ameta(options)]
!qquad!ameta(content)
\end{fpverse}
!STRUT\begin{fpquotation}[!ameta(options)]
!qquad!ameta(content)
\end{fpquotation}
\end{dCmd}
\endgroup\noindent When any of the three environments \env{fpquote},
\env{fpverse}, and \env{fpquotation} are used without the optional argument,
they behave exactly as the {\LaTeX} core counterparts do. The optional
argument recognizes three keys \opt{leftmargin}, \opt{rightmargin}, and
\opt{itemindent}; these \cs{leftmargin},
\cs{rightmargin}, and \cs{itemindent}, respectively.
A few examples suffice.
\begin{itemize}
    \item \env{fpquote} only obeys \opt{leftmargin}, \opt{rightmargin}.
    \begin{fpquote}[rightmargin=0pt]
    \verb|\begin{fpquote}[rightmargin=0pt]|\\[3pt]
    \fetchverses*{Gen 1:1-2}\par
    \fetchverses*{Gen 1:3-4}
    \end{fpquote}
    This is perhaps the most common use for this environment, to indent on
    the left, but not on the right. The key \opt{itemindent} is not obeyed
    for the \env{fpquote} environment.

    \item The \env{verse} gives an outdent effect.
    \begin{fpverse}[rightmargin=0pt]
    \verb|\begin{fpverse}[rightmargin=0pt]|\\[3pt]
    \fetchverses*{Gen 1:1-2}
    \end{fpverse}
    We can adjust the amount of outdent with \opt{itemindent}.
    \begin{fpverse}[itemindent=3em,rightmargin=0pt]
    \verb|\begin{fpverse}[itemindent=3em,rightmargin=0pt]|\\[3pt]
    \fetchverses*{Gen 1:1-2}\par
    \fetchverses*{Gen 1:3-4}
    \end{fpverse}
    The default for \opt{itemindent} is \texttt{1.5em}.
    \item The \env{fpquotation} environment is like the \env{fpverse} but each paragraph
    is indented by an amount of \cs{itemindent} (set by \opt{itemindent}).
    \begin{fpquotation}[rightmargin=0pt]
    \hspace*{-\leftmargin}\hspace{-\labelsep}\verb|\begin{fpquotation}[rightmargin=0pt]|\par\kern3pt
    \fetchverses*{Gen 1:1-2}\par
    \fetchverses*{Gen 1:3-4}
    \end{fpquotation}
    The default value for \opt{itemindent} is \texttt{1.5em}.
\end{itemize}

\subsection{Troubles with quotation marks and apostrophes}\label{ProbsQuotes}

Some Bible translations use more quotes (both single and double) than others.
The English Standard Version (ESV) uses an overabundance of such. Quotation
marks are not only used to quote the speaker, but the single quote
(\texttt{\char129}) is often used as an apostrophe to indicate possession, as in
``God's grace.'' (\texttt{\char018\char018God\char129s grace.\char129\char129}). `Most' Bible translations, as
copied from \textsf{e-Sword}, use double quotes (\texttt{"}) and single quotes
(\texttt{\char129}) for quoting passages. At least one translation, Young's Literal
Translation (YLT), uses single quotes in the same way as does {\LaTeX}; for
example, \eSQ\fetchverse[from=YLT,format=\itshape,delims={according to }{,},
pformat=\bfseries]{Gen 1:3} If you look in the DEF file you'll see that this
passage reads, in part, \texttt{\char018Let light be;\char129}, which is good for user's of
{\LaTeX}. But there are problems.

\texttt{fectchbibpes} tries to match pairs of double quotation
marks (\texttt{"}\ameta{text}\texttt{"}) and single quotes
(\texttt{\char129}\ameta{text}\texttt{\char129}). It maintains two count registers \cs{fp@dqcnt}
and \cs{fp@sqcnt}. When a double quote is encountered and \cs{fp@dqcnt} is
even, `\texttt{"}' is replaced by `\texttt{\char018\char018}'; similarly, when \cs{fp@dqcnt} is
odd, `\texttt{"}' is replaced by `\texttt{\char129\char129}'. For the single quote it's the same
thing. If a given passage has balanced quotes we don't have a problem, for
single quote used as an apostrophe, usually, we have to make adjustment so
the typesetting is correct. For this purpose, the commands \cs{bDQ}\marginpar{\small\raggedleft\cs{bDQ}, \cs{eDQ}},
\cs{eDQ}, \cs{bSQ}\marginpar{\small\raggedleft\cs{bSQ}, \cs{eSQ}}, and \cs{eSQ} are defined. \cs{bDQ} and \cs{bSQ} set their
respective counters to zero (0), which is an even number, while \cs{eDQ} and
\cs{eSQ} set their respective counter to one (1), which is odd.

\paragraph*{Example} Verses 3 and 5 use an apostrophe, we use the following commands to get the
single quite (apostrophe) correct. This passage comes from Matthew 7:1-7 \emph{(ESV):}
\begin{fpquote}[rightmargin=0pt]
\eSQ\fetchverses[showfirst,from=ESV]{Mat 7:1-4} \eSQ\fetchverses[showfirst,from=ESV]{Mat 7:5-7}\bDQ
\end{fpquote}
The verbatim listing is
\begin{Verbatim}[xleftmargin=\amtIndent]
\eSQ\fetchverses[showfirst,from=ESV]{Mat 7:1-4}
\eSQ\fetchverses[showfirst,from=ESV]{Mat 7:5-7}
\end{Verbatim}
It was necessary to break the passage up so the two apostrophe were included
in separate fetches; prior to each fetch we declared \cs{eSQ}, which makes
\cs{fp@sqcnt} odd, and so the next single quote (\texttt{\char129}) is typeset as
\texttt{'} rather than \texttt{`}. Notice that in verse~4 there are matching
single quotes, following the apostrophe of verse~3, \cs{fp@sqcnt} should be
even, so the matched single quotes are handled correctly. Again, in verse~5
there is an apostrophe, we use \cs{eSQ} to make the counter odd so the
apostrophe is typeset correctly.

\paragraph*{Example} In the next passage (Mat 7:13-20 \textit{(ESV)}) there are several troubling
quotation marks. In verse 13 a left double quote opens a quotation, but it is never closed; verse~15 starts
another left double quote. Also, there is an apostrophe in verse~15 that needs to be displayed correctly.
\begin{fpquote}[rightmargin=0pt]
\fetchverses[showfirst,from=ESV]{Mat 7:13-14} \eSQ\bDQ\fetchverses[showfirst,from=ESV]{Mat 7:15-20}
\end{fpquote}
The verbatim listing is
\begin{Verbatim}[xleftmargin=\amtIndent]
\fetchverses[showfirst,from=ESV]{Mat 7:13-14}
\eSQ\bDQ\fetchverses[showfirst,from=ESV]{Mat 7:15-20}
\end{Verbatim}
The double quote of verse~13 opens correctly. Beginning with verse~15, we make the adjustments
\cs{eSQ}\cs{bDQ}.

\newtopic\indent
The King James Version does not have many quote marks, if any, but does have
apostrophes; one runs into challenges with other translations. The rule here
is, when quoting from a translation that uses quotes and apostrophes, keep an
eagle eye out for them.

\section{Combining \texorpdfstring{\protect\pkg{bibpes}}{bibpes}
and \texorpdfstring{\protect\pkg{fetchbibpes}}{fetchbibpes}}\label{s:combpkg}

Though the two packages were originally designed to work separately, but in
concert with each other, it is possible to combine the two packages in one
source file, yet keep the functionalities of the two separated.

To do this, use the \pkg{spdef} package, which comes bundled with
the \pkg{aeb\_mobile} package (\url{http://ctan.org/pkg/aeb-mobile}). The technique
is roughly outlined below.

\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!(),numbers=left]
\RequirePackage[use=builddefs]{spdef}
!textbf(\ifbuilddefs)
\documentclass{article}
\usepackage[!ameta(opts)]{bibpes}
\bibpesBody!textbf(\fi)
%
% Begin the fetchbibpes portion of the document
%
\documentclass{article}
\usepackage[!ameta(opts)]{fetchbibpes}
\begin{document}
!qquad!ameta(document content, containing fetch verse commands)
\end{document}
\end{Verbatim}
Line~(1) introduces \pkg{spdef} using \cs{RequirePackage}. The option
\opt{use=builddefs} defines a Boolean switch \cs{ifbuilddefs} and sets it to
\texttt{true}. When the source document is \texttt{latexed} in this state,
only the lines~(2)--(5) (the \pkg{bibpes} portion of the document) are
compiled. When the source document is \texttt{latexed} with option
\opt{!use=builddefs} (note the exclamation mark), the Boolean switch
\cs{ifbuilddefs} is once again created but this time it is set to
\texttt{false}; consequently, lines~(2)--(5) are scanned over (ignored) and
lines~(9)--(13) (the \pkg{fetchbibpes} portion of the document) are compiled.

\paragraph*{Demo file:} \texttt{combpkgs.tex}

\section{My retirement}

Now, I simply must get back to it. \dps

\end{document}
