\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}