summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/fetchbibpes/fetchbibpes_man.tex
blob: 25690bb4cefcd1c9c15c3eb2fe301afbdf0fa43f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
\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}
\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.9, 2018/07/30},
    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}
    (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}
    (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, it 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, 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}
is transformed 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 do
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.

\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}
\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,
!qquad(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,
!qquad(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}