path: root/macros/latex/contrib/fetchbibpes/bibpes.dtx

%\iffalse
% makeindex -s gglo.ist -o bibpes.gls bibpes.glo
% makeindex -s gind.ist -o bibpes.ind bibpes.idx
%<*copyright>
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% bibpes.sty package,                                   %%
%% Copyright (C) 2016  D. P. Story                       %%
%%   dpstory@uakron.edu                                  %%
%%                                                       %%
%% This program can redistributed and/or modified under  %%
%% the terms of the LaTeX Project Public License         %%
%% Distributed from CTAN archives in directory           %%
%% macros/latex/base/lppl.txt; either version 1.2 of the %%
%% License, or (at your option) any later version.       %%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%</copyright>
%<package>\NeedsTeXFormat{LaTeX2e}[1997/12/01]
%<package>\ProvidesPackage{bibpes}
%<package>   [2016/04/19 v1.3 Import e-sword passages: TXT to DEF (dps)]
%<*driver>
\documentclass{ltxdoc}
\usepackage[colorlinks,hyperindex=false]{hyperref}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\bgroup\ttfamily
\gdef\brpr#1{\char123\relax#1\char125\relax}\egroup
\def\EXCL{!}
\def\ameta#1{\ensuremath{\langle\textsl{\texttt{#1}}\rangle}}
\def\meta#1{\textsl{\texttt{#1}}}
\let\pkg\textsf \let\opt\texttt
\def\SUB#1{\ensuremath{{}_{\mbox{\scriptsize\ttfamily#1}}}}
\def\cs#1{\texttt{\bslash#1}}
\def\CMD#1{\textbackslash#1}
\makeatletter
\renewcommand{\paragraph}
    {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}
    {\normalfont\normalsize\bfseries}}
\makeatother
\InputIfFileExists{aebdocfmt.def}{\PackageInfo{bibpes}{Inputting aebdocfmt.def}}
    {\def\IndexOpt{\DescribeMacro}\def\IndexKey{\DescribeMacro}\let\setupFullwidth\relax
     \PackageInfo{bibpes}{aebdocfmt.def cannot be found}}
\begin{document}
  \GetFileInfo{bibpes.sty}
  \title{\textsf{bibpes}: Import e-sword passages: TXT to DEF}
  \author{D. P. Story\\
    Email: \texttt{dpstory@acrotex.net}}
  \date{processed \today}
  \maketitle
  \tableofcontents
  \DocInput{bibpes.dtx}
\IfFileExists{\jobname.ind}{\newpage\setupFullwidth\par\PrintIndex}{\paragraph*{Index} The index goes here.\\Execute
    \texttt{makeindex -s gind.ist -o bibpes.ind bibpes.idx} on the command line and recompile
    \texttt{bibpes.dtx}.}
\IfFileExists{\jobname.gls}{\PrintChanges}{\paragraph*{Change History} The list of changes goes here.\\Execute
    \texttt{makeindex -s gglo.ist -o bibpes.gls bibpes.glo} on the command line and recompile
    \texttt{bibpes.dtx}.}
\end{document}
%</driver>
% \fi
% \MakeShortVerb{|}
% \InputIfFileExists{aebdonotindex.def}{\PackageInfo{web}{Inputting aebdonotindex.def}}
%    {\PackageInfo{web}{cannot find aebdonotindex.def}}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%    \section{Description}
%    The \textsf{bibpes} package (\underbar{bib}le
%    \underbar passages from \underbar e-\underbar sword) takes a \textsf{TXT} file,
%    and writes a \textsf{DEF} file suitable for use by the \textsf{fetchbibpes}
%    package. The contents of the \textsf{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 \textsf{TXT} and writes a \textsf{DEF} file where each passage reference
%    is made into a text macro that expands to the passage. Clear?
%
%    This package correctly processes Bible verses in the \emph{English language only}. No languages that
%    use accents.\footnote{I've since tested it against a German Bible, and all works well enough.}
%
%    \paragraph*{Options.} The package has two options \texttt{txtfilein}
%    and \texttt{deffileout}:
%\begin{verbatim}
%\usepackage[%
%    infolder=<folder>,
%    outfolder=<folder>,
%    txtfilein=<file_txt>,
%    deffileout=<file_def>,
%    build|!build
%]{bibpes}
%\end{verbatim}
%    \texttt{txtfilein} is the base name of the input \textsf{TXT} file, do not add
%    the extension, \texttt{deffileout} 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. A value for \texttt{txtfilein} is required for this package to do its
%    thing; otherwise, this package does nothing. The keys \texttt{infolder} and \texttt{outfolder}
%    allow you to specify folders where the \textsf{TXT} and \textsf{DEF} file reside.
%    The \texttt{build} and \texttt{!build} options determines whether \pkg{bibpes} builds
%    the \textsf{DEF} file (\opt{!build}), or just displays it (\opt{!build}). The default
%    is to build.
%
%    \paragraph*{Steps to create a \textsf{DEF} file from a \textsf{TXT} file.}
%    There are two steps (1) create a \textsf{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
%    the paragraph on \textbf{Methodologies}, for step (2), read the paragraph
%    \textbf{Create the \textsf{DEF} file}.
%
%    \subsection{Methodologies}
%
%    To create a \textsf{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 \textsf{TXT} file.
%    \begin{enumerate}
%        \item Open your favorite {\TeX} editor, create a new document or open an
%            existing \textsf{TXT} file.
%        \item Open the \textsf{e-Sword} desktop application. Select \textsf{Bible
%            \texttt> Copy Verses\ldots}
%        \item From the \textsf{Copy Verses} dialog box, 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 \textsf{fetchbibpes} package.
%            \end{itemize}
%        \item When you are finished pasting verses, save the \textsf{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 (\url{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 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}
%
%    \paragraph*{Other comments.} Quotations appear as double quotes (\texttt{"}), the companion package
%    \textsf{fetchbibpes} attempts to convert double quotes to the {\TeX} notion of
%    quotes; therefore, it is important to copy verses that have matched double
%    quotes. I note that Jesus's words are quoted in red and are not set off by
%    quotation marks (in some translations). You'll have to hand edit the
%    \textsf{TXT} file.
%    \begin{quote}
%    (Mat 11:4)  Jesus answered and said unto them, Go and shew John again those
%    things which ye do hear and see:
%    \end{quote}
%    can be changed to,
%    \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}
%    if such emphasis of Jesus' words are desired.
%
% \subsection{Suggested use of \textsf{bibpes}}
%
% After you have created your \textsf{TXT} file,
% open the file \texttt{makebibpes.tex}. This is a short file, it reads:
%\begin{verbatim}
%   \documentclass{article}
%   \usepackage[txtfilein=1Cor1]{bibpes}
%   \begin{document}
%   \reportOnBibPes
%   \readbackDefFile
%   \end{document}
%\end{verbatim}
%Below is additional code for combining a \pkg{bibpes} document with a \pkg{fetchbibpes} document.
%Ordinary usage is
%\begin{verbatim}
%\documentclass{article}
%\usepackage[
%    infolder=<folder>,
%    outfolder=<folder>,
%    txtfilein=<file>
%]{bibpes}
%
%\bibpesBody\relax
%\end{verbatim}
%The \cs{relax} is required. To combine a \pkg{bibpes} and \pkg{fetchbibpes} document, you need
%to use \pkg{spdef} package that comes with \pkg{aeb\_mobile}. Below, we define a new Boolean
%switch \texttt{builddefs} (this name can be any command name) through the \texttt{use} key.
%\begin{verbatim}
%\RequirePackage[use=builddefs]{spdef}
%\ifbuilddefs
%\documentclass{article}
%\usepackage[
%    infolder=<folder>,
%    outfolder=<folder>,
%    txtfilein=<file>
%]{bibpes}
%
%\bibpesBody\fi
%...
%A fetchbibpes document follows.
%\end{verbatim}
%Now when the switch says, \texttt{use=builddefs}, the \pkg{bibpes} part is compiled, writing
%your (new) def file. Then when you specify \texttt{!use=builddefs}, the Boolean
%\cs{ifbuilddefs} is set to \texttt{false}, and the \pkg{bibpes} portion of the document is
%scanned past.
%    \begin{macrocode}
\def\bibpesBody{\@ifnextchar\fi{\expandafter\bibpes@Body}
    {\expandafter\endinput\bibpes@Body}}
\def\bibpes@Body{\begin{document}
\reportOnBibPes\readbackDefFile
\end{document}}
%    \end{macrocode}
%\paragraph*{Demo file:} \texttt{combpkgs.tex}
%
% \paragraph*{\textsf{e-Sword} Book appreviations} The \textsf{e-Sword} desktop application
% uses the abbreviations for the books of the Bible, shown in Table~\ref{table:eSAbbr} on
% page~\pageref{table:eSAbbr}.
%\begin{table}[bth]\centering
%\begin{tabular}{@{}llll@{}}
% Gen & Genesis         &  Nah & Nahum\\
% Exo & Exodus          &  Hab & Habakkuk\\
% Lev & Leviticus       &  Zep & Zephaniah\\
% Num & Numbers         &  Hag & Haggai\\
% Deu & Deuteronomy     &  Zec & Zechariah\\
% Jos & Joshua          &  Mal & Malachi\\
% Jdg & Judges          &  Mat & Matthew\\
% Rth & Ruth            &  Mar & Mark\\
% 1Sa & 1 Samuel        &  Luk & Luke\\
% 2Sa & 2 Samuel        &  Joh & John\\
% 1Ki & 1 Kings         &  Act & Acts\\
% 2Ki & 2 Kings         &  Rom & Romans\\
% 1Ch & 1 Chronicles    &  1Co & 1 Corinthians\\
% 2Ch & 2 Chronicles    &  2Co & 2 Corinthians\\
% Ezr & Ezra            &  Gal & Galatians\\
% Neh & Nehemiah        &  Eph & Ephesians\\
% Est & Esther          &  Php & Philippians\\
% Job & Job             &  Col & Colossians\\
% Psa & Psalms          &  1Th & 1 Thessalonians\\
% Pro & Proverbs        &  2Th & 2 Thessalonians\\
% Ecc & Ecclesiastes    &  1Ti & 1 Timothy\\
% Son & Song of Solomon &  2Ti & 2 Timothy\\
% Isa & Isaiah          &  Tit & Titus\\
% Jer & Jeremiah        &  Phm & Philemon\\
% Lam & Lamentations    &  Heb & Hebrews\\
% Eze & Ezekiel         &  Jas & James\\
% Dan & Daniel          &  1Pe & 1 Peter\\
% Hos & Hosea           &  2Pe & 2 Peter\\
% Joe & Joel            &  1Jn & 1 John\\
% Amo & Amos            &  2Jn & 2 John\\
% Oba & Obadiah         &  3Jn & 3 John\\
% Jon & Jonah           &  Jud & Jude\\
% Mic & Micha           &  Rev & Revelation
%\end{tabular}
%\caption{e-Sword abbreviations}\label{table:eSAbbr}
%\end{table}
% \textsf{e-Sword} uses a three-letter abbreviation for all the books of the Bible.
%
% \paragraph*{Working file:} \texttt{makebibpes.tex} is used to convert a \texttt{TXT} file
% of Bible verses to a \textsf{DEF} file of Bible verses. The action of this package is to take
% each line of Bible verse in the \textsf{TXT} file, for example,
%\begin{flushleft}\small\ttfamily
%(Gen\,1:1\,KJV)  In the beginning God created the heaven and the earth.
%\end{flushleft}
% and to transform it it into
%\begin{flushleft}\small\ttfamily
%\string\BV(Gen\,1:1\,KJV) In the beginning God created the heaven and the earth.\string\null
%\end{flushleft}
% in the \textsf{DEF} file. The command \cs{BV} (\underbar{B}ible \underbar{V}erse) is defined in the \textsf{fetchbibpes} package.
% The end of the line is delimited by the \cs{null} command.
%
% It is the \textsf{fetchbibpes} package that uses this special \textsf{DEF} file to fetch
% a verse from the file and typesets it into the document. See the documentation of \textsf{fetchbibpes}.
%
% \section{Documentation and Code}
% We begin by requiring \texttt{xkeyval}
%    \begin{macrocode}
\RequirePackage{xkeyval}
%    \end{macrocode}
% \subsection{Package options}
% The value of \IndexOpt{txtfilein}\texttt{txtfilein} is the path to the input TXT file, while
% \IndexOpt{deffileout}\texttt{deffileout} is the path of the output DEF file. These
% are specified without the extensions. For organization purposes, there are two other package
% options: \IndexOpt{infolder}\texttt{infolder} is the folder containing the TXT input file;
% \IndexOpt{outfolder}\texttt{outfolder} is the folder where the DEF file is to be placed.
%    \begin{macrocode}
\define@key{bibpes.sty}{txtfilein}[]{\def\bpes@txtfilein{#1}}
\define@key{bibpes.sty}{deffileout}[]{\def\bpes@deffileout{#1}}
\define@key{bibpes.sty}{infolder}[]{\def\bpes@infolder{#1/}}
\define@key{bibpes.sty}{outfolder}[]{\def\bpes@outfolder{#1/}}
\let\bpes@txtfilein\@empty \let\bpes@deffileout\@empty
\let\bpes@infolder\@empty \let\bpes@outfolder\@empty
%    \end{macrocode}
%Beginning with \texttt{2016/04/19}, two new options are available, there are
%\IndexOpt{build}\IndexOpt{!build}\texttt{build} and \texttt{!build}.
%The \texttt{build} option is the default, and need not be specified, unless it is
%as a convenience to using the \texttt{!build} option. When the \texttt{!build} option is used,
%the DEF file is not created. Use the \texttt{!build} option to simply obtain a listing of
%all passages in the DEF file specified by the \texttt{txtfilein} option.
%\changes{v1.3}{2016/04/19}{Added two new options \string\texttt{build} and \string\texttt{\string\EXCL\space build}}
%    \begin{macrocode}
\newif\ifbibpes@dobuild \bibpes@dobuildtrue
\DeclareOptionX{build}{\bibpes@dobuildtrue}
\DeclareOptionX{!build}{\bibpes@dobuildfalse}
%    \end{macrocode}
%Process the user's options.
%    \begin{macrocode}
\ProcessOptionsX
%    \end{macrocode}
%    If \texttt{txtfilein} is empty, issue a warning to the user.
%    \begin{macrocode}
\ifx\bpes@txtfilein\@empty
    \PackageWarning{bibpes}{The txtfilein option is required}\fi
%    \end{macrocode}
%    If \texttt{deffileout} is empty, notify the user that the base name
%    of the input file is used.
%    \begin{macrocode}
\ifx\bpes@deffileout\@empty\edef\bpes@deffileout{\bpes@txtfilein}
    \PackageInfo{bibpes}{The output file is named
        \bpes@txtfilein.def}\fi
%    \end{macrocode}
%    Setup paths and read and write streams.
%    \begin{macrocode}
\edef\bpes@txtfileinEXT{\ifx\bpes@txtfilein\@empty
    <unspecified>\else\bpes@txtfilein\fi.txt}
\edef\bpes@deffileoutEXT{\ifx\bpes@txtfilein\@empty
    <unspecified>\else\bpes@deffileout\fi.def}
\@ifundefined{CommentStream}{\newwrite\CommentStream}{}
\immediate\openout\CommentStream report.cut
\immediate\write\CommentStream{Input file:
    \string\texttt{\bpes@infolder\bpes@txtfileinEXT}}
\immediate\write\CommentStream{Output file:
    \string\texttt{\bpes@outfolder\bpes@deffileoutEXT}}
\immediate\closeout\CommentStream
%    \end{macrocode}
%    The next two commands can (optionally) be placed in the body of the working file
%    \texttt{makebibpes.tex} to read back information on what \textsf{bibpes} has done.
%
%    \medskip\noindent
%    The \DescribeMacro\reportOnBibPes\cmd{\reportOnBibPes} provides a simple read back
%    of the file input and the file written.
%    \begin{macrocode}
\def\reportOnBibPes{\begin{flushleft}\catcode`\_=12\relax\obeylines
    \parskip3pt
    \InputIfFileExists{report.cut}{}{}
    \end{flushleft}
}
%    \end{macrocode}
%    \DescribeMacro\readbackDefFile reads the \textsf{DEF} file just created back into the body of
%    the document.
%    \begin{macrocode}
\def\readbackDefFile{\begingroup\parindent0pt\parskip3pt
    \def\BV(##1){\makebox[0pt][r]{##1\quad}\ignorespaces}%
    \def\null{\par}%
%    \end{macrocode}
%Inserted \cs{bpes@outfolder} in the path to input the
%newly created \textsf{DEF} file.
%\changes{v1.3}{2016/04/19}{Inserted \string\cs{bpes@outfolder} in the path to input the
%newly created \string\textsf{DEF} file.}
%    \begin{macrocode}
    \InputIfFileExists{\bpes@outfolder\bpes@deffileoutEXT}{}
        {There is a problem locating the file
         \texttt{\bpes@deffileoutEXT}\ifx\bpes@txtfilein\@empty.
        (A value for the \texttt{txtfilein} package option key is
        \emph{required}, but it was not given a value; hence its
        value is considered \texttt{<unspecified>},
        please correct.)\else. (Check the path to the specified file;
        in particular, the value of \texttt{infolder} and/or
        \texttt{outfolder} may be incorrect.)\fi}\endgroup
}
%    \end{macrocode}
% \subsection{Main code}
%    We now begin the main code. If there is no \texttt{txtfilein} key, the package does nothing
%    and exits.
%    \begin{macrocode}
\ifbibpes@dobuild\else\endinput\fi
\ifx\bpes@txtfilein\@empty\expandafter\endinput\fi
\begingroup
\newread \inbiblepassage
\newwrite \outbiblepassage
\newif\ifreadOK\readOKtrue
\edef\bpes@in{\bpes@infolder\bpes@txtfileinEXT}
\edef\bpes@out{\bpes@outfolder\bpes@deffileoutEXT}
\immediate\openin\inbiblepassage=\bpes@in
\immediate\openout\outbiblepassage=\bpes@out
\endlinechar=-1
%    \end{macrocode}
% We write some metadata to the top of the \cs{outbiblepassage} file
%    \begin{macrocode}
\def\iwo{\immediate\write\outbiblepassage}
\def\FN{Filename: }\def\CO{Created on }\def\CF{From file: }
{\uccode`c=`\%\uppercase{%
      \iwo{cc}%
      \iwo{cc\space \FN\bpes@deffileoutEXT}%
      \iwo{cc\space \CO\today}%
      \iwo{cc\space \CF\bpes@txtfileinEXT}%
      \iwo{cc}%
}}
%    \end{macrocode}
%    Now we look through \cs{bpes@txtfileinEXT} line-by-line and write each line
%    to \cs{bpes@deffileoutEXT} in the proper format.
%    \begin{macrocode}
\loop
%    \end{macrocode}
% An input line has the form:
%\begin{flushleft}\small\ttfamily
%(Gen\,1:1\,KJV)  In the beginning God created the heaven and the earth.
%\end{flushleft}
%    \begin{macrocode}
    \read\inbiblepassage to \biblepassage
    \ifeof\inbiblepassage\readOKfalse
    \else\ifx\biblepassage\@empty\else
%    \end{macrocode}
% We output that same line to the \textsf{DEF} file as
%\begin{flushleft}\small\ttfamily
%\string\BV(Gen\,1:1\,KJV) In the beginning God created the heaven and the earth.\string\null
%\end{flushleft}
%    \begin{macrocode}
        \iwo{\string\BV\biblepassage\string\null}
    \fi\fi
\ifreadOK\repeat
%    \end{macrocode}
% Close out the streams.
%    \begin{macrocode}
\immediate\closeout\outbiblepassage
\immediate\closein\inbiblepassage
\endgroup
%    \end{macrocode}
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%\Finale