\load [vlna]
\enlang
\enquotes \enlang
\margins/1 a4 (,,,)mm
\fixmnotes\right
\fontfam[schola]
\def\TODO{{\Red TODO}}
\everytt{\typosize[9/]\catcode`<=13 } 
\everyintt{\catcode`<=13 }
\def\`{\bgroup \_setverb \toindex}
\def\toindex#1`{\egroup{\tt\Magenta #1}\ea\iindex\ea{\ignoreit#1}}
\def\_printii #1&{\noindent{\tt\bslash#1}\quad}
\def\watchout{\par\medskip\noindent {\bf What to watch out for:} }
\def\recommended{\par\medskip\noindent {\bf Recommended:} } 

\verbchar`
\catcode`<=13 \def<#1>{{$\langle$\it#1$\rangle$}}
\def\OpBible/{OpBible}
% “ ”
\hyperlinks\Blue\Blue

{\nopagenumbers

\tit \OpBible/

\centerline{\typosize [16/]\bf Automatic Study Bible Typesetting Using \TeX/}
\bigskip
\centerline{\bi Version 0.31}
\bigskip
\centerline{\setfontsize{at15pt}\it Petr Olšák, Šimon Konečný}
\bigskip\bigskip
\centerline{\it Revised \the\day. \the\month. \the\year}
\bigskip
%\centerline{https://petr.olsak.net/opbible.html}
\centerline{\url{http://opbible.org}}
\vfill
{\it
\rightline{It is too small a thing for you to be my servant}
\rightline{to restore the tribes of Jacob}
\rightline{and bring back those of Israel I have kept.}
\rightline{I will also make you a light for the Gentiles,}
\rightline{that my salvation may reach to the ends of the earth.}
\smallskip
\rightline{Isaiah 49:6} %CEP
}\eject


The \OpBible/ macro collection may be freely copied, distributed and used in accordance with GNU
General Public License (Version 2, 1991).

You can port parts of this software into your own macros and/or make them part of other
packages, but the package, however different from the original distribution, must not be named \OpBible/.

Adaptations of specific implementations (e.g.,\ fonts or other Bible versions) are 
considered additional files and their inclusion does not violate the license.


\vfill\eject

\nonum\sec[preface] Preface


The verse from Isaiah 49 on the title page is inspiring: It would be a small thing to write and typeset using \TeX/  just one Bible commentary on one Bible version as one's life's work. The \OpBible/ offers the opportunity to write a commentary on any Bible version (up to as many as there are Bible translations in one particular language) to anyone anywhere; once the notes apparatus is complete, the study Bible is typeset.

Šimon Konečný's long-standing vision of using \TeX/ to automatically typeset study Bibles came to fruition through a collaboration with Petr Olšák.  Starting from the realistic assumption that
those who will use OpBible the most will also be those who have the least experience with \TeX/, we tried to make the usage as simple as possible.

However, there is no point in pretending that typesetting a study Bible is something trivial.  
To claim that it is a little tricky is a bit understatement;
it is rather quite a challenge for any programmer.

Our intention to allow the production of a single commentary apparatus to go with multiple Bible translations simultaneously was
further complicated by the fact that different versions of the Bible have different verse numbers in some places, differently broken paragraphs, 
different structures of poetic passages, different placement of headings added by the translators; that  some translations have completely different book titles (and hence abbreviations),
that file names cannot contain diacritics but book references can and should, and countless other such oddities.

All the problems we encountered have been overcome and everything works just fine to our satisfaction.  The resulting collection of macros is quite complicated,
therefore  the definitions usage is irritatingly sensitive to any transgressions against \TeX's syntax.

That's why \OpBible/ includes tools to make it easier to find where typos, forgotten parentheses, etc. have been left; and in this documentation,
wherever we have seen fit, we add paragraphs entitled {\bf What to watch out for} and {\bf Recommended}.




\vfill 

\rightline{Petr Olšák}
\rightline{Šimon Konečný}
\eject








%\sec What is the \OpBible/?
%
%\noindent
%\OpBible/ is a set of tools (macros and other support software) for processing biblical texts. The main goal is to link the text of the Bible with the commentary notes.
%%according to the required criteria described below.
%The result after processing by \TeX/ is a study Bible, i.e., a Bible printed together with annotations and typeset automatically by \TeX/.
%%The %%PDF file is also richly hyperlinked.

%\medskip
 %%\centerline{\picw=15cm \inspic daniel.png }
%\medskip



\notoc\nonum\sec Contents
\maketoc
\vfil\break

} % end of \nopagenumbers

%\nonum\notoc
\sec What makes the \OpBible/ specific?

The main advantages of the \OpBible/ over traditional typesetting are:

\begitems
* {\bf Price:} \begitems
  * The software itself is free as public domain under an Open Source license (see Preface). 
  * More important, however, is the price which   you'll save on a typesetter you'd otherwise have 
  to pay for several years to hand-typeset the Study Bible.
        \enditems
* {\bf Time:} Typesetting an entire Study Bible takes minutes, not years. 
 When providing the full text of a~Study Bible  that breaks up the pages 
 so that the notes end up on the same pages with the verses they're commenting on, 
 it took about   ten minutes on a system with a quad-core Ryzen 3 processor. 
 If you're working on a particular book and only processing one, 
 it's usually a matter of seconds.
* {\bf Flexibility:} The result is not just one single version of the Bible in which you cannot 
 make  any changes. If you later decide to edit some notes, delete some or add some more, etc.,
  you have this new revised version immediately typeset and ready for print.
* {\bf Variability:} The result may not be
  just one Bible. The notes can be written in a way that allows as many Bibles as there are 
  different translations in a given language to be typeset with the same note apparatus. 
  For example, consider these six English translations of the Bible: 
(1)~Bible in Basic English (BBE); (2)~Jubilee2000; (3)~NETfree; (4)~Updated King James Version (UKJV); (5)~Restored Names King James Version (RNKJV); and (6)~Webster.
Now let's take a brief look at Daniel, chapter 2, where the animals, countries, and other stuff of Daniel's vision are rendered as follows: 

\begitems
* {\it Bear\/} is the same everywhere but
* {\it Leopard\/} of most tranlations is {\it Tiger\/} in Jubilee2000;
* usual {\it Ram\/} becomes {\it Male sheep,\/} as well as {\it clay\/} changes into {\it potter's earth\/} in BBE;
* ordinary {\it brass\/} turns into {\it bronze\/} in NETfree;
* {\it Greece\/} of BBE, Jubilee2000, and NETfree is {\it Grecia\/} in UKJV, RNKJV, and Webster; compare all six translations.
\enditems

You can write your commentary in the way that the result would be all six translations at the same time, with no need to modify the notes file, while the notes (or charts, maps, etc.), will display the phrases as they appear in your current Bible. See the sample book of Daniel, chapter two, the chart of Daniel's visions; compare all six translations.

In English, there are over 450 different translations of the Bible.
Most of them are not being used anymore, but still, 
you can choose from \ulink[https://bibleanswers.study/about-the-bible/types-of-bible-versions]{more than sixty} various English versions. 
Actually, you can write your notes in a way that sixty (or four hundred and fifty) various translations can be used with them at the same time, 
without a need to change anything in the notes.


* {\bf Interactive output format}:
  The result of the processing is a PDF file that is richly interwoven with active links. 
  These make an invaluable aid for proof-reading  before submission to the print (see below).

* {\bf Precision:} \begitems
  * The average study Bible contains around 20,000 notes and within them around 60 to 80,000
  references to Bible verses and other notes. The notes are written by humans; it is inevitable  that  they will contain errors from oversight or typos. It is practically beyond the human power 
  to find and correct  all of them. It is, however, within the power of a machine. \OpBible/ prints warning messages  if, for example, a note refers to a non-existent note or verse.
*  You can  check for the accurateness of references to verses and notes that do exist (thus they do 
   not trigger an error message), but for some reason they are not the right ones.
    The control is made possible by the fact that all references are active links that display the immediate context when the cursor hovers over
   the linked location (if you are viewing the PDF with the correct version of Evince, for example). And when clicked on, it jumps straight there. 
  * The phrase that the note comments on is highlighted with a different font (e.g.,bold).
    Moreover, OpBible will also search for it in the Bible text inside the verse in question, and the pages will be broken in the way that 
    the note ends up on the same page as the phrase it is commenting on.
    In case that there are two notes commenting on two different words in the same verse, and that    the page break will come between those words,  the notes will follow
   the phrases on their pages. See~\ref[break-verse] 
   * The Bible texts are prepared (for example, by downloading  from the internet) in separate files and there is no need for them to be modified in any way (assuming your source left no misprints in them). All notes on them and other typesetting instructions are written in separate files. Then \TeX/  puts everything together.
    \enditems
\enditems

%{\bf What to watch out for:} 
\watchout
Although the intent of this program is to spread God's Word and the Good news contained therein, the 
\OpBible/ itself {\it forgives nothing!} 
(After all, what'd you expect, it's a software. Go to God for forgiveness.) As you'll learn below, 
the \OpBible/ loads one entire book of the Bible into memory at a time and only then  
begins to digest your notes and piece them together into pages with their respective verses. If you 
happen to make a mistake in \TeX/ syntax (e.g., forget a closing bracket, etc.), \TeX/ will see the 
error somewhere in the middle of this matching procedure, and this in turn will result in a 
cluttered error message, in which it is highly likely that you will get lost and not find your way 
around.

The \OpBible/~ anticipates the occurrence of situations like this and offers useful tools to help 
you out of similar predicaments, but you'd better be careful and consistent. You won't go wrong with 
the first written note, to go through all the translations you plan to use to make sure everything 
works as it should.  After that you may only  work with one of them, but it is advisable to run 
\TeX\ every time  after you finish each new note, so by its protests  you can easily find the one 
in which you have the mistake.

\recommended Use the Linux operating system. \OpBible/, as a macro collection for \TeX, will run on any 
system with the same results, but the Linux installation has
several not-to-be-missed advantages. Among the most significant of these is the Evince PDF viewer, 
whose newer (as of 2023) version can display the immediate context of a hyperlinked
reference by simply hovering the cursor over it without having to click on it. This is an invaluable 
aid for checking the accuracy of links to Bible passages or notes.
Other systems do not (yet) offer this facility. While the hyperlinks in these systems do jump to the 
required location when clicked, they do not hit back to where the jump signal was sent from, which 
is tedious. In this documentation, we assume a Linux installation.

And of course, we recommend -- or rather, consider it a prerequisite -- at least basic literacy in 
\TeX.
If you don't have any experience with \TeX, try starting 
\ulink[https://www.ctan.org/tex-archive/info/gentle]{here}\fnote{This text is, to a degree, obsolete, as it refers to DVI output of \TeX/. Nowadays, modern \TeX/ ouputs directly to the PDF format.}. 
The time invested in this preliminary education will not be wasted; the more you understand \TeX/, 
the better (and more joyfully) you will write your notes.

\sec[Installation] What we need to run \OpBible/

It is necessary to have some kind of text editor that does not keep any hidden formatting 
information in the text (designed for editing programs, for example). It is up to the user what kind 
of editor suits them.
The ideal editor is one that recognizes the programming language by its source file's extension and 
colors words according to its syntax. E.g.,\ Vi, Emacs, ... 
\ulink[https://en.wikipedia.org/wiki/List_of_text_editors]{choose}, whichever would suit you. 


You also need to have a \TeX/ distribution with the \LuaTeX/ program and \OpTeX/ default macros, and 
finally you need some kind of output (i.e.,\ PDF files) viewer (we recommend the last version of 
Evince).

It isn't important on which operating system you will run this, but we recommend 
\ulink[https://www.hostinger.com/tutorials/best-linux-distro]{Linux}.

It is also possible to work in online mode without installing anything, see section~\ref[OverLeaf].

\secc[TeXlive] \TeX/ at the local machine

We recommend the latest \ulink[https://tug.org/texlive/]{\TeX/live} distribution.
It can be installed on any operating system directly from the web. It is also included in common 
Linux distributions. 

\TeX/live contains the program \LuaTeX/, which will process your input files and produce output 
PDFs. It also includes the default macro set \ulink[http://petr.olsak.net/optex/]{\OpTeX/} that the 
\OpBible/ macros need, and extends it with the options described in this manual. The default set of 
macros (often called format) defines how documents are marked up and controls formatting. The \TeX/ 
distributions include other default macro sets. The best known is probably \LaTeX/, but it is not 
needed for \OpBible/.

\secc[OverLeaf] Variant: remote access on Overleaf.com

Overleaf is a web-based environment for shared preparation of \TeX/ documents, perhaps 
by multiple users. You do not need to have \TeX/live installed; you can run it online 
via \ulink[https://www.overleaf.com]{Overleaf}. The \ulink[https://www.overleaf.com/read/wxmzmjnpjsjx]{default project} 
containing files for processing by \OpBible/ is also available. 
As an Overleaf user, you can copy (clone) it to your 
project and continue working there. However, working with the \TeX/ distribution 
directly on your 
computer is significantly faster and more convenient. 

\recommended
Something to consider is the time limit of Overleaf \TeX/ processing. 
Free Overleaf registration gives you just twenty seconds, 
all paid  subscriptions 4 minutes. 
While twenty seconds could be quite OK if you only work on one particular book, 
it can turn out that even 4 minutes might be not enough for the entire Study Bible 
when it is completed. 
This is just an opinion, not tested and verified fact, though. 
What we know for sure, is that one minute (the free time limit before October 6, 2023) 
is not sufficient even for a plain Bible with no notes at all.
So if you insist on working on Overleaf 
(for example, when you often  work from different locations), 
before compiling the entire Bible, it may be wise to download the project in your 
computer and finish it from there.



%\secc[evince] Evince

%`flatpak` : flatpak run org.gnome.Evince

%The full text of the Bible is available on the Internet in various translations and English

\sec Running \TeX/

If you have a \TeX/ distribution installed on your machine (for example, \TeX/live
2022 or newer) %; if not, see the \ref~[installation] chapter)
and if you have a command line available on your system, then you can run \TeX/ using:
\begtt
optex main.tex
\endtt
where `main.tex` is the name of the main file (it can have a different name). 
The `optex` command runs \LuaTeX/ with the \OpTeX/ macros. The result of the processing is a file 
`main.pdf` and the processing message is in the `log` file `main.log`.

You can test if this works for you (without \OpBible/ macros for now). Create a simple `main.tex` 
file in a text editor with this content:

\begtt
\fontfam[lm]
Hello world!
\bye
\endtt
and run `optex main.tex`. View the resulting PDF file `main.pdf` with a PDF viewer.


\sec Structure of files processed by \TeX/

\secc[main] Main file with information about all other files

The main file is the file that is submitted to \TeX/ first. For example, it is
listed on the command line to start \TeX/. It contains information about what
other files to be read by \TeX/. Finally, \TeX/ will create a PDF file of the same
name as the main file name but with the extension `.pdf`.

The main file for running \OpBible/ (for example, `main.tex` or `bible-en.tex`) might look something like this:

\begtt
\load[opbible] %  the OpBible macros
\enlang % initializing English hyphenation patterns

% Translation variants:
\def\tmark {BBE}      %  Bible in Basic English
%\def\tmark {Jubilee2000} % Jubilee 2000
%\def\tmark {NETfree} % New English Tranlation
%\def\tmark {UKJV}    % Updated King James Version
%\def\tmark {RNKJV}   % Restored Names King James Version
%\def\tmark {Webster} % Webster Bible

\input {vars.tex}  % Phrase declarations for different translation options
\input {books.tex} % Book titles and bookmarks \amark

\def\txsfile {sources/\tmark-\amark.txs} % Location of txs files
\def\fmtfile {formats/fmt-\tmark-\amark.tex} % Location of fmt files
\def\notesfile {notes/notes-\amark.tex} % Location of notes files
\def\introfile {others/intro-\amark.tex} % Location of book introduction files
\def\articlefile {others/articles-\amark.tex} % Location of article files

\def\printedbooks {%
 Gen Exod Lev Num Deut Josh Judg Ruth 1Sam 2Sam 1Kgs 2Kgs 1Chr 2Chr Ezra Neh Esth Job Ps 
 Prov Eccl Song Isa Jer Lam Ezek Dan Hos Joel Amos Obad Jonah Mic Nah Hab Zeph Hag Zech Mal    
 Matt Mark Luke John Acts Rom 1Cor 2Cor Gal Eph Phil Col 1Thess 2Thess 1Tim 2Tim Titus  
 Phlm Heb Jas 1Pet 2Pet 1John 2John 3John Jude Rev
}

\processbooks % Generates document with books declared in \printedbooks
\bye
\endtt

Now, let's see what each of these lines does and which ones will require modification on your part 
for the specific needs of your project.

Using `\load[opbible]`,  the \TeX/ loads macros of the \OpBible/ package. 
This set of macros is the most important program that takes care of the 
typesetting.

The \`\enlang` command sets the English word division patterns, so it assumes English
text. The `en` is an ISO language abbreviation; you can use other languages:
`\cslang` for Czech, `\delang` for German, `\eslang` for Spanish
etc. All available language options are listed in the \ulink[https://petr.olsak.net/optex/]{\OpTeX/ 
documentation.}

The command `\def\tmark {<mark>}` defines the macro \`\tmark` as a mark
of the translation used {\em Translation mark}. The marks of all available translations are listed 
in the file `vars.tex`. 
One of them should be selected as the mark of the currently processed
translation. For example, `BBE` is the mark for the Bible in Basic English.
In the example, six options for defining a translation mark in the case of English Bibles are 
given. Only one option (the one actually selected) does not have the `%` comment character in front 
of it. 

 
If you are currently working on a book  in the `BBE` translation, leave the `main.tex` file in the 
above form.
When you want to switch to, say, the UKJV, you will use the percent sign to comment out (i.e., make 
invisible to \TeX) the line with the BBE, but make visible (uncomment)
the line with the UKJV. Then the `\tmark` definition section will look like this:

\begtt
% Translation variants:
%\def\tmark {BBE}      %  Bible in Basic English
%\def\tmark {Jubilee2000} % Jubilee 2000
%\def\tmark {NETfree} % New English Tranlation
\def\tmark {UKJV}    % Updated King James Version
%\def\tmark {RNKJV}   % Restored Names King James Version
%\def\tmark {Webster} % Webster Bible
\endtt

One of the translations must always be active, in other words, \`\tmark` has to be defined. If 
you forget to put a percent sign before the line you want to comment out, the world won't fall 
apart; the very last definition that \TeX\ loads will apply, which will redefine any previous ones.

The command \`\input {vars.tex}` reads the configuration concerning the translation variants
from the `vars.tex` file. 
See section~\ref[vars] for details. Do not touch this line, even though you will probably be editing 
the `vars.tex` file called by this line.

The \`\input {books.tex}` reads the information about the marks (abbreviations) of the books of the Bible and the book names are assigned here. 
This information is discussed in more detail in section~\ref[books]. 

The macro \`\txsfile` (defined by `\def`) specifies the location of `.txs`
files in the directory structure. For each book of the Bible, there has to be
one `.txs` file containing the core text for that book. File
 names vary by book mark, and if there are multiple translations, the file name 
also includes the translation mark. In the \`\txsfile` macro, you can use 
 \`\tmark` as the translation mark and \`\amark` or \`\bmark` as the book mark. 
 For book marks, see section~\ref[books]; for the format of `.txs` files, see the  discussion in the section~\ref[txs]. 
 In the example shown above,  `.txs` files are  located in the `sources/` directory and are  named `<translation-mark>-<book-mark>.txs`, so for example `BBE-Gen.txs`.
 %%To asi potřebujeme doladit. PO: Nebudeme pouzivat predponu Eng, opravil jsem to.


The English translations mentioned above are ready to go, you don't have to create them for yourself.
If you need some other existing translation, you need to get it into a format usable for OpBible,  in the same form as the `*.txs` files in the `sources/` directory.
The `maketxs` script (see~\ref[txs]) will help you prepare individual `.txs` books from an existing source.

If you are going to create a brand new translation and plan to use it with OpBible, it probably wouldn't hurt to compose files one by one for each book directly in the desired format, 
or even better: create the file `your-translation.out` for the entire Bible, and run `maketxs your-translation.out` to create all the `.txs` files needed; see also~\ref[txs].

The \`\fmtfile` macro defines the location of the files specifying the formatting
of the core text. Each book of the Bible of each translation uses its own formatting file.
This is something that  cannot be common to all translations (unlike notes),
because the paragraph breaks and added headings can (and do) differ for each translation.
Our intent was so-called non-destructive editing, in other words, formatting the biblical text
without interfering with the `.txs` files.
The formatting files are discussed in section~\ref[fmt].

The macro \`\notesfile` defines the location of the notes files.
That's  where you will write your commenting notes printed with the core text. 

Each book of the Bible has its own notes file. 
The notes refer to a place in the core text, and it is the job of \TeX/ to create pages with both the core text and the notes commenting on it. 
For more details on how to write notes files, see section~\ref[note]. 
Notice that the note files are common to all translations, i.e., there are no separate files distinguished by \`\tmark`. 
The note writing rules allow for the possibility to have various translations over 
one common notation, so long as they are in one language (e.g., English; see section~\ref[translations]). If you want to write
notes for a completely different language, it is the best  to start a new project (preferably in 
another main directory) with different `.txs` files, different formatting and note files.

The macro \`\introfile` specifies the files where the introductions to
each book are written. So, it is possible (and advisable) to create an individual introduction text for each Bible book.

The macro \`\articlefile` specifies the names of files  which contain the theological articles.
The articles and similar stuff can be placed practically anywhere in the Bible, on any page interleaved with the core text but not within an introduction text. 


The macro \`\printedbooks` contains the marks of the books you want to process by \TeX/.
The example above calls to process of the entire Bible, i.e., all 66~books of the Protestant canon are printed.
If you're only doing test prints, for example, you can process only some of the
books of the Bible and have an alternative definition in the main file, for example
`\def\printedbooks{Dan}`. Just put it after the definition for the entire Bible, because
later definitions of the same macro take precedence over any earlier ones.


The \`\processbooks` command starts processing all the books specified in the macro
\`\printedbooks`.  For each book, \TeX/ will read the corresponding core text from
`.txs` file, formats it using the data from the appropriate formatting
file and appends the notes from the appropriate note file. The introduction text for books and the articles are added too.
%You don't need to change anything here.

The \`\bye` command will terminate \TeX/.
Anything you type after this farewell to \TeX/ will be ignored.




You can also add your own macros and settings to the main file before \`\processbooks`, which will affect the entire typesetting.

For example, you can put a \`\ChapterPre``{<code>}` or \`\ChapterPost``{<code>}` declaration. These codes are then executed before and after each chapter.
%For example, \readplan -- we need to finish


\secc[vars] File declaring translation variants

If we are working with a single translation variant, there is no need to create this file
and use it. Then just remove (comment out) the instruction to read it from the main file.

In the example in section~\ref[main], the file `vars.tex` is read, which
should contain the declaration of translation variant marks using \`\variants`:
\begtt
\variants <number-of-variants> {<mark>} {<mark>} ... {<mark>}
\endtt
where `<number-of-variants>` is the number of translation variants (into one and 
the same  language, e.g., English), and then all the marks of the variant 
translations are listed.
For example,
\begtt
\variants 6 {BBE} {Jubilee2000} {NETfree} {UKJV} {RNKJV} {Webster}
\endtt
declares the abbreviations for the 6 English translation variants:
BBE for  Bible in Basic English, Jubilee2000 for Jubilee 2000, NETfree for New English Tranlation, UKJV for Updated King James Version, RNKJV for Restored Names King James Version, and Webster for the Webster Bible.


The translation variants thus defined must match the definitions of `\tmark` in the main `main.tex` file, including upper or lower case.

Consider in advance the number of translations you want to use (changing their number later will be very difficult, though not impossible)
and especially the order of the translations: the same order in which they are declared in the definition of \`\variants`  will apply to the entire project.
In all the notes commenting on a phrase that spells differently in different translations, you will be listing the different phrase versions in that precise order.


If you know that a phrase or word will appear more often than just in a single note, 
you can define it directly in the `vars.tex` file using the \`\vdef` command.
The number of phrases listed after \`\vdef` must be exactly the same as the number of
`<number-of-variants>`, each of them enclosed in brackets, and they must correspond to the translation variants in the same order as the variants listed in the declaration of \`\variants`. For example:

\begtt
\vdef {Greece} {Greece} {Greece} {Grecia} {Grecia} {Grecia}
\endtt
declares that the name of Greece is transcribed differently in different
variants of translation: it is {\it Greece\/} in BBE, Jubilee2000, and NETfree, but changes to Grecia in UKJV, RNKJV, and Webster. 

When we write notes concerning this country in the
notes file, we will just write `\x/Greece/` (the first translation variant in the definition of `\variants`)
and this will be turned into the corresponding phrase used in the currently processed
translation that we have declared in the main file using `\def\tmark{...}`.

So after changing `\def\tmark{...}` in the main file, all occurrences of
of `\x/Greece/` in the text of notes will automatically start behaving differently
and adapt to the phraseology of that particular translation variant.
Then such words can be inflected or added various endings, for example: The entry `\x/Greece/'s` will yield the form `Grecia's` in the note under the UKJV, RNKJV, and Webster translations but will remain `Greece's` with BBE, Jubilee2000, and NETfree. 
This is discussed in more detail in section~\ref[translations].

The command \`\variants` declaring the abbreviations of the translation variants is unique (the only one) for the variants file, 
whereas there can be more \`\vdef` commands defining variant phrases in the file, because there are of course many phrases that are used in different
translation variants,  not just the country of Greece.


The whole passages of text can be handled differently depending on the translation variant set. The branching command  \`\switch` is used for this purpose. 
It is discussed in more detail in the section~\ref[switch]. 
For example, the names of individual translations (which are then used in the page header) can be declared differently for different translations using `\def\bibname`:
\begtt

\switch {BBE}{\def\bibname{Bible in Basic English}}%
        {Jubilee2000}{\def\bibname{Jubilee 2000}}%
        {NETfree}{\def\bibname{New English Tranlation}}%
        {UKJV}{\def\bibname{Updated King James Version}}%
        {RNKJV}{\def\bibname{Restored Names King James Version}}%
        {Webster}{\def\bibname{Webster Bible}}

\endtt
This particular declaration is a part of the already prepared `vars.tex` file.
%% zkontrolovat, zda tomu tak opravdu je

\secc[books] Books names file

In the main file, there is an instruction to read the books names file. The example
above from section~\ref[main] uses `\input {books.tex}`. That file must contain the commands
\`\BookTitle` in the format:
\begtt
\BookTitle <a-mark> <b-mark> {<non-abbreviated book title>}
\endtt
There must be at least one space between the marks and the book title.
The beginning of a file `books.tex` might look like this:

\begtt
\BookTitle Gn Gen {The First Book of Moses (Genesis)}
\BookTitle Ex Exod {The Second Book of Moses (Exodus)}
\BookTitle Lev Lev {The Third Book of Moses (Levicitus)}
\BookTitle Nu Num {The Fourth Book of Moses (Numeri)}
\BookTitle Dt Deut {The Fifth Book of Moses (Deuteronomy)}
\BookTitle Jos Josh {Joshua}
\BookTitle Jdg Judg {Judges}
...
\endtt
In the first column after \`\BookTitle`, there are `<a-mark>`s, which are further
used in the text of the notes and are used to create links to the Bible passages and other notes. The <a-mark>s are visible in printed text when the references are used.

In the second column, there are `<b-mark>`s, which can be the same as
`<a-mark>`s, but may also be different. It is possible, for example, that the names of the `.txs`
files were created by exporting from some software and the bookmarks are different than
we need to use in the text of our notes. Then it is possible that in the main file
declare the location of the `.txs` files using \`\bmark` instead of \`\amark`, i.e.
\begtt
\def\txsfile {sources/\tmark-\bmark.txs}
\endtt
and have the files `BBE-Gen.txs`, `BBE-Exod.txs`, while in the text (including the references) we use
the marks `Gn`, `Ex`, etc., not `Gen`, `Exod`. The <b-mark>s are never printed in the text.

The macro \`\amark` contains the `<a-mark>` of the currently processed book and the 
macro \`\bmark` includes the `<b-mark>` of the  currently  processed book.

Note that the macro \`\printedbooks` (in the file `main.tex`) with the marks of all the books we want to
process (see section~\ref[main]) contains `<a-mark>`s, not `<b-mark>`s.

In the third parameter after \`\BookTitle`, the book names are in brackets.

File with 66 entries of \`\BookTitle` %(Protestant canon) The 
is generated automatically after extracting
the core texts from Sword download using a program `mod2tex` and a python script `maketxs` (see
section~\ref[txs]). Feel free to use them, but `<a-mark>`s and book titles will
probably need to be manually modified according to the conventions of the translation, as demonstrated in the example above.

Additional information about individual books can be added to the book title file
using the \`\BookException`, \`\BookPre`, \`\BookPost` commands. They have the following syntax:
\begtt
\BookException <a-mark> {<exception-text>}
\BookPre <a-mark> {<text-before-book>}
\BookPost <a-mark> {<text-after-book>}
\endtt

The <exception-text> is inserted before reading all files of the book (`.txs`, format, notes, intro, article files)
inside the cycle  for reading all books with \`\processbooks`. Then
the <text-before-book> is inserted after the book files have been read but before
the first verse (or introduction text) is processed. Finally, the <text-after-book> is inserted after the last
verse of the book.

Example of using \`\BookException`:
Let's assume your language has diacritical marks that happen to be a part of the abbreviations of some Biblical books, and even though you cannot use diacritics in the file names, you still want to use them in your text  to refer to those books as they appear in your Bible.  
What you can do is to modify the value of the macro \`\amark` so that it does not contain
diacritics as follows (following example applies for Czech language):
\begtt
\BookException Ž {\def\amark{Z}}
\BookException Př {\def\amark{Pr}}
\BookException Pís {\def\amark{Pis}}
\BookException Ř {\def\amark{R}}
\BookException Žd {\def\amark{Zd}}
\endtt

Then the `notes-\amark.tex` files, for example, are actually named `notes-Z.tex`,
`notes-Pr.tex` etc. In the notes text you normally use the  marks of usual book abbreviations, e.g.,
Ž, Př, Pís, etc.

There are five books in the Bible that have only one chapter (Obadiah, Philemon, 2 and 3 John and Jude).
Because the references to them are not written with the chapter number (`Phlm 1:4`) but only with the verse number (`Phlm 4`), 
we have to teach \TeX\ which ones they are so that it does not expect the chapter number but knows that it's the number 1 which in turn is not printed anywhere.
When you refer to one of such books, the reference is being interpreted in a different way, see section~\ref[vudaj].
This is achieved by defining a macro \`\nochapbooks` which must contain the <a-marks> of these books:
`\def\nochapbooks {Obad Phlm 2John 3John Jude}`, obviously identical to those already listed in the `\BookTitle` definition (in the `books.tex` file), as well as those listed in `\printedbooks` definition in the `main.tex` file.


\secc[txs] Core text format, called `.txs` files

The core text of the Bible is assumed to be stored in `.txs` files
(text source). Each of the ~66~ books of the Bible is stored in its own `.txs` file.
The names of the `.txs` files and their locations must match the `\def\txsfile` declaration
in the `main.tex` file (see~section~\ref[main]).

Each line of the `.txs` file contains one Bible verse started with 
`#<chapter-num>:<verse-num>`. The verses must be listed in the correct
order. For example, the beginning of the `BBE-Dan.txs` file looks like this (parts of the text are omitted in the sample):

\begtt
#1:1 In the third year of the rule of Jehoiakim, king of Judah ... with his forces.
#1:2 And the Lord gave into his hands Jehoiakim, king of Judah ... store-house of his god. 
...
\endtt


The core texts of the Bible can be obtained, for example, from the Sword modules 
\url{https://www.crosswire.org/sword/modules/ModDisp.jsp?modType=Bibles}.
Individual `.txs` files can then be generated using the following procedure (on Linux):
%http://www.biblesupport.com/e-sword-downloads/file/2574-english-jubilee-2000-bible-jb2000bblxexe/ %e-Sword module installer for Windoze
Unzip the ZIP downloaded from the  web page above (the so-called module). You need
have the `libsword-dev` package installed on your computer and the program
`mod2tex`, which is part of \OpBible/. Use `installmgr -l` to find out
list of downloaded modules. If your current directory is the location where you
have unzipped the ZIPs and where the `modules` directory was created, then the modules will be found. The modules contain text in binary format and we need 
to convert them into text format. To do this, just type the following into the command line: 
\begtt 
mod2tex module > file
\endtt 
where `module` is the name of the module. In the resulting file
you have the complete core text of the translation (module).
For example, after
\begtt
mod2tex KJVA > KJVA.out
\endtt
the complete translation of the King James Bible (including Apocrypha) is in the file `KJVA.out`.
This can now be split into `.txs` files with the command
\begtt
maketxs KJVA.out
\endtt
This command will create the `KJVA-books.tex` file in addition to the 66 `.txs` files, in which
contains the titles and abbreviations of each book, so there is:
\begtt
\BookTitle Gen Gen {Genesis}
\BookTitle Exod Exod {Exodus}
\BookTitle Lev Lev {Leviticus}
\BookTitle Num Num  {Numbers}
\BookTitle Deut Deut {Deuteronomy}
\BookTitle Josh Josh {Joshua}
\BookTitle Judg Judg {Judges}
...
\endtt

These titles are in English, as the Sword source does not use non-English module names. 
If your language is a non-English then it is necessary to manually edit this file and insert the titles of your local language instead of English ones.
The abbreviations of the books are listed twice as well. The first one `<a-mark>` should be changed according to convention of abbreviations in your language's Bibles and the second column of abbreviations can stay in English as it already is (as these second abbreviations, the <b-marks>, will be part of the `.txs` file names).  

Then the declaration 
\begtt
\def\txsfile {sources/Eng\tmark-\bmark.txs}
\endtt
in the main file will cause the created `.txs` files to be searched for 
in the `sources/` directory and their names are assumed
`EngKJVA-Gen.txs`, `EngKJVA-Exod.txs`, `EngKJVA-Lev.txs`, etc.

If the rare case should arise that you were to compile the Bible from several different sources, say the Old Testament you wanted in Dr. Jan Hejčl's translation and the New Testament in František Žilka's translation, you would have to play a bit with the file names so that the resulting definition of `\tmark` would be the same for the whole Bible. The two `*.out` files (e.g., `HEJCL.out` and `ZILKA.out`)\fnote{Their modules aren't on Sword; the `.out` files would have to be created by downloading them from e.g., `https://obohu.cz` and converting them to the desired form with some clever script (or manually?).} would have to be merged into one and then named e.g., `CzeHecjlZilka.out` and  only then execute `maketxs CzeHejclZilka.out`.  Now you can have a `\def\tmark{HejclZilka}` definition in the main `main.tex` file and 
the resulting study Bible will have Hejčl's Old Testament and Žilka's New Testament.




From now on, you no longer need to modify  `.txs` files in any way.
In the `sources/` directory, you can have a “data” store of all the core Bible texts for all used translation variants at one place. In the case of the six translation variants
of the Protestant canon, you have $6 \times 66=396$ files here.



If you have something in the `.txs` files that you want to format differently, it is 
possible to use \`\cnvtext``{<what>}{<how>}` in the main file. 
\TeX/  will look up all occurrences of `<what>` in each verse of `.txs` file and replace them with `<how>`.
For example, if you have sections of text in square brackets in the `.txs` files, i.e.
`[something like this]` and you want to print them in italics, write in the main file:
\begtt
\cnvtext{[}{\bgroup\it} \cnvtext{]}{\/\egroup}
\endtt

It may turn out that the `.txs` file does not use the correct typographical quotation marks (i.e., in English “...”), but instead there are the programmer's quote marks {\tt"}...{\tt"}. 
Without interfering with the `.txs` file, this can be fixed by adding an instruction to
the main file:
`\quotationmarks{`“`}{`”`}`.
This will automatically replace the programmer's quote marks in the `.txs` file with correct English  typographical quotation marks. 
Similarly, you can declare the replacement of the programmer's quote marks
with Czech or any other other quotation marks, for example by declaring
`\quotationmarks{`„`}{`“`}`.
The programmer's quote mark is then implicitly
replaced by the opening typographical quotation mark (the first parameter in the 
declaration), but if it is followed by a space, end-of-verse, end-of-paragraph, period, 
or comma, it is is replaced by a closing typographical quotation mark (the second 
parameter).

\secc[fmt] Entries specifying the formatting of the core text in `fmt-*.tex` files

The core text in `.txs` files does not contain any formatting or additional information, 
such as chapter titles or where to end a paragraph or where to switch from block format 
to center-justification   and back, or how to display poetry.

%\mnote{\code{\\fmtadd} \code{\fmtpre} \code{\fmtins}}

Since we don't want to interfere with the core text,\fnote{Think of them as the
Holy Scriptures, therefore  “untouchable” texts. The only reason that might entitle 
you to interfere with the core text is the possibility that you might find an 
error in the source from the Sword (or wherever you've got it from), when compared against the hard copy. Then it is really better to fix such error on the spot; if so, do it in `*.out` file and recompile it with `maketxs` afterwards. 
Never rely too much on internet sources; always check them out. They can and do contain errors. For example, Sword modules are full of missing spaces, occasionally you'll find a wrong character there, or even a missing part of a verse, etc. See the file `errata-BKR.txt` on the project's \ulink[opbible.org]{homepage} 
to learn how many such errors can one Sword module contain.} 
you need to declare this additional information and link it to the corresponding verses using the special commands \`\fmtadd`, \`\fmtpre`, \`\fmtins`, \`\fmtfont`, \`\fmtkeep` and \`\fmtrepl`. 
These commands are typically in the `fmt-*-*.tex` files,
for example, `fmt-BBE-Dan.tex`. It is advisable to maintain these formatting files
dependent both on the book (Daniel in the example above) and on the translation (the Bible in Basic English in the example). 
You can always start with one file for each book and  create the files for  other translations as copies of this default one.  At the end of a day, 
however, it may turn out to be be necessary to modify the formatting instructions for different variants of the core text according to the translation used.


The syntax for using these commands is as follows:
\begtt
\fmtpre{<chapter-number>:<verse-number>}{<fmt-command>}
\fmtadd{<chapter-number>:<verse-number>}{<fmt-command>}
\fmtins{<chapter-number>:<verse-number>}{<phrase>}{<fmt-command>}
\fmtfont{<chapter-number>:<verse-number>}{<phrase>}{<fmt-command>}
\fmtrepl{<chapter-number>:<verse-number>}{<phrase>}{<replaced phrase>}
\fmtkeep{<chapter-number>:<verse-number>}{<phrase>}
\endtt
where <fmt-command> is the \"command" given to \TeX/ for formatting.
%\mnote{\code{\\endgraf} \code{\\begcenter} \code{\\endcenter}}
For example, \`\endgraf` marks the end of a paragraph; \`\begcenter` opens a passage with
centered text which must be somewhere later closed  with \`\endcenter`. Or 
\`\chaptit{<text>}` inserts <text> as the chapter title, whereas
\`\schaptit{<text>}` inserts the pericope title elsewhere, other than before the first verse of the chapter, and makes space above and below that title.

%\mnote{\code{\\fmtadd} \code{\fmtpre} \code{\fmtins}}
The \`\fmtpre`  inserts <fmt-command>
at the beginning of the specified verse (before the verse number which is printed in a form 
of a superscript). 
The \`\fmtadd`  inserts <fmt-command> at the end of the specified verse.
Finally, \`\fmtins` inserts <fmt-command> inside the verse after the first occurrence of the 
specified <phrase> that must exist exactly as given in the verse. Otherwise, \TeX/ prints a warning 
message and inserts no <fmt-command> at all.

An example of how the `\fmt*` commands can be used can be seen in the file
`fmt-BBE-Dan.tex`.

The command \`\fmtfont``{<chapter-number>:<verse-number>}{<phrase>}{<font>}`
is used to highlight the selected phrase with the selected font.
For example, the `\fmtfont{1:7}{the name of}{\em}` in the book of Daniel will print the words
\"the name of\thinspace "  in italics (to indicate the word not in original language), because `\em` is an intelligent italics switch (it automatically adds the italics correction `\/` after the word, which you don't have to worry about, but which you would have to if you switched to italics with an ordinary `\it`).
Any other font switch can be used instead of `\em`.

The command \`\fmtrepl``{<chapter-number>:<verse-number>}{<phrase>}{<replaced phrase>}`
replaces first occurrence of <phrase> by <replaced-phrase>.

Occasionally (although rather rarely) you may run across the situation where something in the core text requires very specific 
handling. For example, the RNKJV translation attempts to display Hebrew names, especially God's name YHWH, in Hebrew alphabet, even in 
the midst of  surrounding text in Latin alphabet.  Hebrew language writes from right to left and you will have to manage to typeset Hebrew words 
correctly.  In case you download the core text containing such Hebrew words (like RNKJV does), you can use the macro \`\fmtrepl` which searches the occurrences of such Hebrew words and does what we want to print. 
Consult the file `fmt-RNKJV-Dan.tex`. 

The command \`\fmtkeep``{<chapter-number>:<verse-number>}{<phrase>}` makes first occurrence of the <phrase> unsearchable. So you can apply a next `\fmt*` command to the next occurrence of the <phrase>. You will probably not need this too often; if you do, see the section~\ref[dirty].

In addition to \`\begcenter` and \`\endcenter`, it is also possible to use controlled 
indentation with \`\ind``<number>` (as indent). 
At the point of insertion, the line is terminated and the next line begins indented by the
`<number>` of paragraph indents. However, inserting such `\ind` commands
via `\fmtins` or `\fmtpre` can be quite laborious and
cluttered, yet the Bible is rife with poetic passages that require a lot of
of differently indented lines. The command \`\fmtpoetry` can be used for this purpose.
We will first demonstrate its use in the example of the NETfree translation of 
Daniel 6:26--27:

\medskip
\centerline{\picw=.7\hsize\inspic{images/NETfree-Dan-crop.pdf} }
\vskip-2pt % it's on two sides, so it looks a little smooth


The poetic part of this sample was typeset this way:
\begtt
\fmtpoetry{6:26}{God;// forever./ destroyed;//}
\fmtpoetry{6:27}{/ delivers// wonders/// earth./ Daniel// }
  \fmtins{6:26}{Daniel.}{\medskip\hglue-2mm}
  \fmtadd{6:27}{\bigskip}
\endtt

\`\fmtpoetry``{<chapter-number>:<verse-number>}{<formatting-data>}` determines the 
format of a particular verse. The <formatting-data>
contain the word from the end of the line followed by one or more slashes. Number of
of slashes indicates how many paragraph indents the next line after 
that word will be shifted to the right. <formatting-data> must necessarily end with one or more
slashes and may (but do not have to) begin with one or more slashes.  If
it does, then the beginning of the line is indented by the appropriate number of paragraph indents,
but the verse number is set off slightly to the left to the space of a paragraph
indentation (see the explanation below in the {\bf Recommended} paragraph).

If you want to insert extra vertical spaces when using \`\fmtpoetry`, 
you can do that, but only after the \`\fmtpoetry` command, as you can  see in the example above where
\`\medskip` (half line space) is inserted. 
The rule is that when you use more formatting commands like \`\fmtins` or \`\fmtpre` in poetry, 
these multiple formatting instructions will eventually be executed
in reverse order, so for example, for the verse 6:26 in the  example above, 
the first `\medskip` is executed at the beginning of the poetic part of the verse 
26, after the name Daniel, followed by a period: `\fmtins{6:26}{Daniel.}{\medskip\hglue-2mm}`.

\recommended
If the poetry line starts with the left quotation marks, it is a typographical convention to let 
them sick out to the left of the text block so that only the letters are aligned, and the empty 
space bellow the quotation marks does not disturb that alignment. (The same reason applies for the verse numbers but you don't have to 
worry about these, as they are shifted automatically.)
Therefore, you can add some negative horizontal space in order to stick the quotation marks out of 
the poetry block. In the example above, we used `\hglue-2mm`. 


%\secc Notes in `notes-*.tex` files
%These files (located according to the `\notesfile` declaration in the main file)
%contain, among other things, notes on individual verses or parts of verses. 
% The command \`\Note` will be the most frequent command in the `notes-*.tex` files, designed to type in the particular notes.  Since 
% the commentary apparatus is the main reason why the
%the \OpBible/ package was created, an entire section~\ref[note] is devoted to it.

\sec Notes and other objects linked to the core text

Notes in `notes-*.tex` files (located according to the `\notesfile` declaration in the main file)
contain, among other things, notes on individual verses or parts of verses. 
The command \`\Note` will be the most frequent command in the `notes-*.tex` files, designed to type in the particular notes.  Since 
the commentary apparatus is the main reason why the the \OpBible/ package was created, the entire section~\ref[note] is devoted to it.



\secc[note] Notes linked to core text phrases: The `\Note` command

The main purpose of the \OpBible/ tool is to create a PDF from the core text not only
with the Bible text itself, but with notes linked to their verses. 
In order to achieve that we use the `notes-*.tex` files (for example, `notes-Gen.tex` for the book of Genesis), which contain notes on individual phrases of the core text according to
the following  format. Each individual note is prefixed with the command \`\Note` in this required form:




\begtt
\Note <chapter-number>:<verse-number> {<phrase>}
<note-text>
<blank line>
\endtt
For example:
\begtt
\Note 1:2 {the temple of his god} 
Marduk was the chief god of the Babylonian pantheon (cf. <Jer 50:2>).
\endtt
The example is from the `notes-Dan.tex` file, i.e., the notes file on the book of Daniel. 
More precisely, the note refers to chapter one, verse two, and the phrase “the temple of his god.”
This phrase, case-sensitive, must necessarily exist in the specified verse
of the core text. Then \TeX/ links it to the corresponding place 
of the core text,  ensuring that the phrase and its commenting note occur
on the same page. In other words, the pages do not break by verse number and its corresponding note number; they break by the commented phrase.
When a page break occurs inside a verse between two phrases that are being commented on, the notes follow their phrases, not just the beginning of the verse.
See an example of this in section~\ref[break-verse].


If the <phrase> is not present exactly in the specified verse of the core text,
\TeX/ reports a warning to the log and to the terminal during processing and
matches the note with the given verse as if the <phrase> were at the beginning of the verse.
You will use the notes without specified <phrase> for summarizing comment on a larger portion of the text; see the first two notes in the sample book of Daniel.

However, if two consecutive notes should both be without a specified <phrase>, they will be printed in the reverse order to the order in which they appear in the `notes-*.tex` file. In the sample book of Daniel you'll see the note on 1:1-21 to go {\it before\/} the note on 1:1-6:28. In the `notes-Dan.tex` you'll find `\Note 1:1-21` typed {\it after\/} `\Note 1:1-6:28`. If you want to change the order of the notes in such rare cases, simply switch their order in the `notes-*.tex` file. 

The printed note (depending on the typographic design) then contains
the repeated chapter and verse numbers, followed by the <phrase> that is being commented on (for example, in bold) followed by the actual text of the note.

Sometimes it is necessary to search for a slightly different phrase in the core text than what
we want to have in the printed note (e.g., the word in the core text is in
a different case, or it is a slightly differently worded phrase). Then it is possible to type an equal sign immediately after the `{<phrase>}`, which in turn is followed by the  `{<phrase-to-be-printed>}`, i.e.,

\begtt
\Note <chapter-number>:<verse-number> {<phrase>}={<phrase-to-be-printed>}
<note-text>
<blank line>
\endtt
In this case, <phrase> is searched for in the core text, but in the actual
note, <phrase-to-be-printed> is printed as the note entry. For example:

\begtt
\Note 2:32-33 {head}={The head ... gold, its chest and arms ... silver, its belly 
   and thighs ... bronze, its legs ... iron, its feet partly ... iron and partly ... clay} 
Moving from the head to the feet of the image, there is a decrease not only in the  weight
of the materials but also in its value. The image was clearly too heavy with fragile feet.
It is an illustration of the fate of all human kingdoms and civilizations:  at the end,
each of them will collapse by its own weight.
\endtt

In this example, the phrase “head” is being searched for but the text “The head ... gold, its chest and arms ... silver, its belly and thighs ... 
bronze, its legs ... iron, its feet partly ... iron and partly ... clay” will be printed in bold font as the first part of the note.
In this particular example, the note (or at least its beginning) will occur on the page where the first occurrence of the word “head” in the verse 2:32 takes place.

It is  possible to have more notes on the same Bible verse. Each of the notes, however, have to be separated by a blank line as always. 
In case that two or more consequent notes have identical <chapter-number>:<verse-number>, these numbers are printed only in the first instance, not in following notes on the same verse.

The individual notes in the source notes file are separated by blank
lines. This is necessary, otherwise \TeX/ would not know where the text ends when reading them. 
It also increases the clarity of the source file. 
%Additional lines of the note can (but need not) be indented. %really needed?

If the note refers to the whole verse (without a specified phrase), write
`{}`, i.e., an empty search phrase. For example:
\begtt
\Note 1:1-21 {}={Keeping ritual purity}
The prophet introduces the context of his book by recounting a personal history
(of his and of his friends) in the captivity, education, loyalty to God and service 
to King Nebuchadnezzar.
\endtt

Moreover, the last two examples also demonstrate the possibility to give a range of verse numbers.
The verse range will be printed in the beginning of the note as expected.
If the <phrase> for the search is blank (as in this very last example), then the note
will be placed on the same page as the beginning of the first verse in the~specified range.
If <phrase> is non-empty, it must occur in the first verse of the range of verses. 
The range symbol “`-`” is the only “minus” character normally available on
keyboard. Its ASCII code is~45. It must not be any special character that somehow resembles a horizontal 
dash.


The order of printed notes on the same verse corresponds to the order of the phrases on which
they comment in the core text. That means that the order in which they are written 
in the source file is irrelevant. Notes that link to an entire verse using the empty parameter `{}`  are placed as the first, and if there are more than one of them, then their order is reverse to that in the source file, as stated above.

The phrases linked to the notes are printed in the \`\notecolor` color. By default it is red, but you can say (for example) `\let\notecolor=\relax` in your main file, if you don't want to colorize these phrases.


\secc[break-verse] Page break inside a verse  

If different notes comment on different phrases within a single verse, and at the same time a page break after all the formatting happens to come between those phrases in the core text, then the notes follow their phrases to their respective pages. In other words, the page break is not determined by the verse number but by the phrase found  in the core text and synchronized with the note. 

In the sample Book of Daniel (of the Webster Bible translation), you can see this happen at the verse 10:20 
(all the searched phrases are highlighted in red color). Look at page 23
where you read “will I return to fight with the prince of Persia” and then at page 24 where the same verse continues with the phrase “the prince of Grecia.” The notes follow their respective phrases to correct pages. 
(You probably do understand that in a real hard copy Bible the page 23 would be the right one, as all odd pages are, and 24 would be its other side after you turn the page, don't you?)

\filbreak
\bigskip
\picw=200pt
\line{\hskip10pt\inspic{images/Webster-Dan-10-20A-crop.pdf} \hss
                        \inspic{images/Webster-Dan-10-20B-crop.pdf} 
                       \hskip10pt}


\secc[articles] Commands to insert other objects

In addition to the \`\Note` commands, the `notes-*.tex` file can be used to write instructions for 
inserting additional objects related to a particular verse in the core text. Such an object is 
placed on the bottom of the page under the two columns of notes.\fnote{According to the implicit  
page design; this can be redefined. } If the object is a quotation, it is placed on
top of the page. We define the link to the location of the text using the 
`<chapter-number>:<verse-number>`, similar to \`\Note`. The object is placed on the same page where 
the corresponding verse begins.
If the object does not fit on the page below the verse, it is placed at the bottom of the
of the following page.
%% I guess it would take some examples

You can insert images using \`\putImage` (section~\ref[putimage]), articles using \`\putArticle` 
(section~\ref[putarticle]), quotations using \`\putCite` (section~\ref[topcite]), images across two 
pages in an open book using \`\putSpanImage` or \`\putSpanText` (section~\ref[spanimage]).

The order in which you write the commands to insert these objects in the `notes-*.tex` file has no 
effect on the final appearance. You can have all objects of one type concentrated in one place in 
the source file, or you can  have them placed between `\Notes`, typically by the verse number to 
which the objects are bound.





\secc[putimage] Inserting Images

To place images with a link to a specific verse, use the \`\putImage` command:

%\mnote{\code{\\putImage}}
\begtt
\putImage <chapter-number>:<verse-number> {<caption>} [<label>] (<parameters>) {<file>}
\endtt
For example:

\begtt
\putImage 2:1 {Daniel's Visions} [daniels-visions] () {Nabuco.pdf}
\endtt



\begitems
* `<chapter-number>:<verse-number>` indicates the location where the image is placed.
* `<caption>` is the caption to the image. 
In the default typographic settings, it is printed in a strip that separates the upper part of the 
page from the  the image itself.
* `<label>` specifies the image's  reference label. You can then refer to it using \hfil\break
\code{...see image \\ref [daniels-visions] on page \\pg}, which, 
%  ...see image` \`\ref` `[<daniels-visions>]` on page \`\pg`, which,  
  in the case of our example, prints ... see image {\Blue Daniel's Visions} on page~{\Blue 123}.
  In doing so, the text in this link will be hyperlinked to the place where the image occurs. 
  If you don't want to use `<label>`, type `[]`   (an empty label).
  
* `<parameter>` specifies optional additional instructions for formatting the image. They can  be 
non-present, as the example suggests.
  By default, the image is stretched to the full width of the page. If you want it
  smaller, for example, type `<parameters>` in the space for `\picw=9cm` which
  will cause the image to be 9\,cm wide and centered.
* `<file>` is the full name of the image file. It can have the extension `pdf` (for
  vector images) or `png` or `jpg` (for bitmap images).
  Image files must be stored in the `images/` directory. If they
  are located elsewhere, the parameter \`\picdir` must be set for that location,
  for example `\picdir={BibleImages/}`. It is sensible to have it set in the main file, see 
  section~\ref[main].
\enditems



\secc[putarticle] Inserting Articles

Articles with text (typically significantly longer than a note) can be placed on a page in a 
similar manner as images, i.e., in the default typographic setting at the bottom of the of 
the page on which the verse specified by
`<chapter-number>:<verse-number>` happens to occur. 
If it does not fit there, it is inserted at the bottom of the  next page. 
If it does not fit on a single page, its next part is inserted  at the bottom of the next page (and 
so on until the whole article is complete).



Write the text of  articles for each Biblical book in a file called by the macro \`\articlefile`. 
For example, the file `articles-Gen.tex` contains all the articles for the book of Genesis. 
For how the content of such file has to look like, see below.


In the `notes-*.tex` file, you need to specify the article location request
using \`\putArticle`:


\begtt
\putArticle <chapter-number>:<verse-number> {<title>} [<article-number>] (<parameters>)
\endtt
For example:
\begtt
\putArticle 6:1 {Who Was Darius the Mede?} [6] ()
\endtt

\begitems
* `<chapter-number>:<verse-number>` indicates the location to which the article will be placed.
* `<title>` is the title of the article. It is printed in a similar way as the caption of an image.
* `<article-number>` is a numeric designation of the article that must be unique within each single 
Biblical book. 
As articles are typically linked to chapters (we don't assume more than one article in a single 
chapter), then the
  `<article-number>` can (and should but does not necessarily have to) be the number of the 
  corresponding chapter. 
  The article is not placed following this number, however, the number is being used for references.
 For example, you can type \code{...see <"article" Da 6>a} and it will print
  ...see {\Blue article~Da~6}. The format and properties of such links
  are described in section~\ref[links]. In addition, the `<article-number>` is used to find
  the actual text of the article in the corresponding `atricles-*.tex` file.
The * `<parameters>` are optional parameters that specify the formatting of the article. 
If you are satisfied with the default settings (e.g., the width = `\hsize`) then leave the 
parentheses `()` empty.
\enditems

The text of the articles to be inserted must be in the `articles-*.tex` file.
This file must contain a line started by \`\Article` as follows:

\begtt
\Article [<article-number>] <text-of-the-article> 
\endtt
Then it can continue with the next article given by another command 
`\Article` `[<article-number>]` followed by more text, etc.
All the articles for a given book are thus grouped in a singe file.

If you specify the request \`\putArticle` but the corresponding file `article-*.tex`
or the corresponding line  \`\Article` `[<article-number>]` does not exist,  \TeX/ will end with 
an error.





\secc[topcite] Inserting quotations at the top of the page

%\mnote{\code{\\putCite}}
The command \`\putCite` `<chapter-number>:<chapter-number> {<text>}`, 
by default, inserts <text> as a quotation at the beginning of
page containing `<chapter-number>:<verse-number>`.

The <text> itself may contain a \`\quotedby {<author>}` at the end. In such a case
 <author> is printed on a new line (if the  quotation is placed on the right page) or, assuming 
 there is enough space, it is shifted more to the right on the last line (if the quotations  is 
 placed on the left page).



For a controlled transition to a new line, you can use the \`\nl` (new line) command in <text>.
For example:

\begtt
\putCite 1:8 {You can’t get second things by putting them first. \nl
              You get second things only by putting first things first.
\quotedby{C. S. Lewis}}
  
\endtt



\secc[cite] Inserting quotations in the margin of an article 

Article text is formatted in two columns by default.
It is possible to break the outer column and insert a quotation or something similar.
Such text will stick out into the outer margin.

Inside the article (i.e., just after \`\Article` `[<article-number>]`) 
you need to insert a declaration of the quoted text using:
\`\Cite` `<letter> {<text>}`. %\mnote{\code{\\Cite}}
Here <letter> is typically `A`. But if you want to insert more than one
quotations in a single article, you need to distinguish between 
them with additional letters, i.e., `B`, `C`, etc., 
and all quotations have to be written at the beginning of the article.


%\mnote{\code{\\insertCite}}
The \`\Cite` command only declares the quote. Its actual insertion into the text
is done by \`\insertCite` `<letter>\left` and at the same time  \`\insertCite` `<letter>\right` 
elsewhere in the text of the article.
If the article is on the left-hand side of a double page, the quotation is placed
only by `\insertCite<letter>\left`, in other words, `\insertCite<letter>\right` is
ignored. If the article is on the right-hand side of an open double page, the placement is
is governed only by `\insertCite <letter>\right`. The quotation will appear
right below the line in which the \`\insertCite` is given. The line itself is
is not split because of this (in other words, the paragraph is not terminated because of the 
insertion of the quotation).

The reason why it is necessary to give two locations for \`\insertCite` is  following: 
We don't know ahead on which page (odd or even) the article with the inserted quotation
will appear. Since the quotation should stick out in the outer margin, 
it should be placed  in the first column on the left page, 
and in the second column on the right page, that is 
somewhere slightly different. The location of `\insertCite <letter>\left` should therefore
correspond to a line in the first column and `\insertCite <letter>\right`
to another line in the second column of the article.


It is wise to debug (i.e., test in advance) what the placement of the quote looks like
for both options that may occur (left/right). If you want to
to see how it works for the variant that doesn't match the correct position
of a page, you can use the command \`\swapCites` at the beginning of the article text which will 
switch the left/right position of the quotation.
%\mnote{\code{\\swapCites}}
But this should not be left on for the final printing, thus activated
`\swapCites` will cause a warning printed to the terminal and to the log file.

\sec[translations] Different (but similar) versions of the core text

See section~\ref[vars] for an introduction to this issue. This is detailed documentation for 
each option.

\secc[cmdx] Declaring translation variants and using the `\x` command

If the variants are not declared with the \`\vdef` command, then
\`\x``/<phrase>/` command used in the text will output the same <phrase>. 
However, it is possible to declare translation variants. 
The number of variants must be specified with the \`\variants` command
(see section~\ref[vars]). 
This is done just once for the whole document (the entire Bible). 
Then the \`\vdef` commands can follow, always with exactly as many parameters 
and in the same order
as the number of variants specified by the \`\variants` command. For example:

\begtt
\variants 6 {BBE} {Jubilee2000} {NETfree} {UKJV} {RNKJV} {Webster} 

\vdef {took the kingdom} % BBE
      {possessed the kingdom} % Jubilee2000
      {take possession of the kingdom} % NETfree
      {possessed the kingdom} % UKJV
      {possessed the kingdom} % RNKJV    
      {possessed the kingdom} % Webster
      
\vdef {He-goat} % BBE
      {Goat} % Jubilee2000
      {Male goat} % NETfree
      {He goat} % UKJV
      {Goat} % RNKJV
      {He-goat} % Webster

\endtt

If `\def\tmark {<variant>}` is now declared in the main file,
then the `\x``/<phrase>/` will turn into the <phrase> of the specified <variant>.
In doing so, the <phrase> parameter of the \`\x` command must be identical 
to the~first phrase specified in the \`\vdef` command (in the examples above, 
it's BBE's `took the kingdom` and `He-goat`). 
If, in our case, the main file says `\def\tmark{BBE}`, then
\medskip
\code{\\x/took the kingdom/} yields: took the kingdom 

\code{\\x/He-goat/} gives: He-goat

\code{\\x/Whatever/} prints: Whatever

\medskip

But if there is a `\def\tmark{Jubilee2000}` in the main file, then

\medskip
\code{\\x/took the kingdom/} yields: possessed the kingdom 

\code{\\x/He-goat/} gives: Goat

\code{\\x/Whatever/}  will print Whatever and the terminal will warn
                                  that the phrase `\x/Whatever/` has no declared translation in `\vdef`.
\medskip



Selected parameters of \`\vdef` may be empty (written as ~`{}`),
indicating an undefined phrase for that translation.
If such undefined phrase needs to be used with \`\x/.../`, a warning message 
will be printed in the `.log` file.

In addition, the parameter may contain a single `"` character, indicating that the
the same phrase is used as in the previous parameter. So our
example above might also look like this:
\begtt
\vdef {took the kingdom} % BBE
      {possessed the kingdom} % Jubilee2000
      {take possession of the kingdom} % NETfree
      {possessed the kingdom} % UKJV
      {"} % RNKJV    
      {"} % Webster
\endtt

\secc[ww] Variant phrase declarations for matching notes with text

The \`\Note` command may be immediately preceded by a declaration of the search
phrase by variant translations using \`\ww` (this is an abbreviation for watchword).
The \`\ww` command has as many parameters as there are translation variants declared by
\`\variants` command, and these parameters can be simple (in the format
`{<wanted-phrase>}`) or compound (in the format
`{<search-phrase>}={<what-to-print>}`). The immediately following \`\Note`
will then ignore its parameter for the search phrase and use the parameter from \`\ww`
corresponding to the translation variant being processed. For example:

\begtt \typosize[8/11] \catcode`<=12
\ww {if you do not make clear to me the dream and the sense of it} % BBE
    {if ye will not make known unto me the dream with its interpretation} % Jubilee2000
    {If you do not inform me of both the dream and its interpretation} % NETfree
    {if all of you will not make known unto me the dream, with the interpretation thereof} % UKJV
    {if ye will not make known unto me the dream, with the interpretation thereof} % RNKJV
    {if ye will not make known to me the dream, with the interpretation of it} % Webster
\Note 2:5 {If you do not tell me what my dream was and interpret it.}
    Nebuchadnezzar formulated a plan for testing his advisors. If they could not relate the dream back 
    to him he would have no confidence in their interpretation (see <"v." 9>). 
\endtt

The `Note 2:5` given here searches the text in verse 2:5 for \"if you do not make clear to me the 
dream and the sense of it" when a variant translation of the BBE is being processed, and looks up 
the text \"if ye will not make known unto me the dream with its interpretation" when the Jubilee2000 
translation variant is being processed.
The example assumes that six `\variants` have been declared using the 
`\variants` command for translation variants in the specified order. 

Whenever \`\ww` preceeds a \`\Note`, the brackets for a `{<phrase>}` after the \`\Note` can contain anything and it will not be displayed, as it will be replaced by the content of \`\ww`. However, they always have to be present, even if empty.

You can also specify a different phrase
for searching and for printing in a note, as shown in the following example:

\begtt \typosize[8/11]
\ww {head}={head ... gold, ... breast and arms ... silver, ... middle and sides ... brass, legs ... 
        iron, ... feet in part of iron and in part of potter's earth} % BBE
    {head}={head ... gold, ... breast and arms ... silver, ... belly and thighs... brass, legs ... 
        iron, ... feet  part of iron and part of baked clay} % Jubilee2000
    {head}={head ... gold, ... breast and arms ... silver, ... belly and thighs... brass, legs ... 
        iron, ... feet  part of iron and part of clay} % NETfree
    {head}={head ... gold, ... breast and arms ... silver, ... belly and thighs... brass, legs ... 
        iron, ... feet  part of iron and part of clay} % UKJV
    {head}={head ... gold, ... breast and arms ... silver, ... belly and thighs... brass, legs ... 
        iron, ... feet  part of iron and part of clay} % RNKJV
    {head}={head ... gold, ... breast and arms ... silver, ... belly and thighs... brass, legs ... 
        iron, ... feet  part of iron and part of clay} % Webster
\Note 2:32-33 {} Moving from the head to the feet of the image, there is a decrease not only in the  
    weight of the materials but also in its value. The image was clearly too heavy with fragile feet.
    It is an illustration of the fate of all human kingdoms and civilizations:  at the end, each 
    of them will collapse by its own weight.
\endtt

The \`\ww` also accepts the parameters in the form `{"}` like the \`\vdef` does. The value of previous parameter is used instead of `{"}`.

The search and replace phrases are used exactly as they are written in
parameters of the \`\ww` command. This does not apply to \`\Note` notes, which are not preceeded by
\`\ww`. Then when using

\begtt
\Note <chapter:verse> {<search-phrase>} <text> <blank line>
\endtt
or
\begtt
\Note <chapter:verse> {<search-phrase>}={<what-to-print>} <text> <blank line>
\endtt
the <search-phrase> is first transformed by the data from `\vdef`. Only if
such data do not exist for the search phrase, <search-phrase> is being used as it is.

\watchout
Keep in mind that formatting a phrase (see~\ref[fmt]) 
prevents it from being found, as the formatting sticks its own commands to it.
So if your note is commenting on a phrase that already underwent 
some formatting  
(e.g., a line break  within a poetry passage, or a font change, etc.)
pick the closest  word that is not influenced by this formatting as the search 
phrase, and use the complete phrase that you want to display as the replacement 
(`<what-to-print>`) one.

For example, you want to comment on the phrase  {\em How great are his signs!} 
in Daniel 4:3. Writing directly 
`\Note 4:3 {How great are his signs!}` would yield a warning message and the 
phrase would not be found. That is because in some translations (e.g., NETfree, 
see the file `fmt-NETfree-Dan.tex`), the word {\em sign!} at the end of the 
sentence is part of formatting, while in some  others 
(e.g., Jubilee2000 or Webster) the core 
text contains extra characters `[]` around some words that are being 
converted into font change command using `\cnvtext` (see~\ref[txs]) .

Therefore, you have to work around by using replacement (`<what-to-print>`) 
phrase: 

\begtt
\Note 4:3 {How great}={How great are his signs!}
\endtt


\recommended 
For clarity, it is worthwhile to have each translation on a new line, and to label it after 
the commenting percentage sign, so that we know what belongs where without groping.
The last line of the `notes-*.tex` file for a particular book that \TeX\ loads should contain a 
single `\endinput` command.
Whatever follows below this instruction on subsequent lines will not be seen by \TeX. (But don't 
confuse it with `\end` or `\bye` so that \TeX\ doesn't stop running at this point but continues 
reading
other files.)

Then, below `\endinput`, you can have a few lines prepared, e.g., in this form:

\begtt
\ww {}={} % BBE
    {}={} % Jubilee2000
    {}={} % NETfree
    {}={} % UKJV
    {}={} % RNKJV
    {}={} % Webster
\Note 1:1 {}={}
\endtt
and then just copy these lines in place of the new note, edit the chapter  and verse number after 
`\Note`, or delete `={}` where they are not needed. This way you don't lose track of
which phrases belong where, whether you write them out manually or paste them from a Bible program 
or online resources.


\secc[switch] Text processing branching by translation variants

%\mnote{\code{\\switch}}
You can use the \`\switch` command to branch the text processing,
depending on the set value of the \`\tmark` parameter, i.e., depending on
the translation variant currently being processed. The command has the following syntax:
\begtt
\switch {<list of variants>} {<what to do>}%
        {<list of variants>} {<what to do>}% ... etc.
        {<list of variants>} {<what to do>}
\endtt
The pairs `{<list of variants>} {<what to do>}` can be given as many times as you like.
After each pair `{<list of variants>}{<what to do>}` (except for the very last pair) must be 
followed immediately and without spaces by another such pair.
Therefore, when moving to the next line, write a percent sign after the closing parenthesis to cover 
the space from the end of the line. Spaces at the beginning of the next line do not matter.
You can understand the percent sign after the pair as “next pair continues”.

The `<list of variants>` is a single translation variant mark or a list of translation variant marks separated by a comma and no spaces.  \TeX/ then works as follows:
If a variant defined by the \`\tmark` parameter occurs in the `<variant list>`, then
the following `<what to do>` is executed. If there is no such variant,
the following `<what to do>` is skipped. Example:
\begtt
\switch {BBE}         {water-door of the Ulai}% BBE
        {NETfree}     {Ulai Canal}%             NETfree
        {Webster}     {river Ulai}%             Webster
        {Jubilee2000,UKJV,RNKJV} {river of Ulai} % UKJV, RNKJV, Jubilee2000 
 \endtt
The example shows how to print the name of Ulai river, depending on
the translation variant being processed.

Once \TeX/ finds a match and does `<what to do>`, then the possible following
entries within the same `\switch` command are skipped. Furthermore, the rule is that
if `<list of variants>` is empty, then `<what to do>` is always executed, if
not skipped according to the previous rule. So an empty `<list of variants>` 
at the end of the `\switch` parameter pairs is evaluated as “all other
cases”. The example above can also be written as follows:
\begtt
\switch {BBE}         {water-door of the Ulai}% BBE
        {NETfree}     {Ulai Canal}%             NETfree
        {Webster}     {river Ulai}%             Webster
        {}            {river of Ulai}           % UKJV, RNKJV, Jubilee2000 
\endtt

The `\switch` command can be used not only for single phrases within notes
`\Note`, but also to entire sections of input text containing, for example, `\Note`,
several `\Note` notes, several definitions, etc.

The `\switch` command cannot be used in the parameters of other macros. On the other hand, the
command `\x/<phrase>/` works inside `\switch`.




\secc[renum] Renumbering verses according to translation variants

%\mnote{\code{\\renum}}
Some translation variants have different verse numbering. In such cases, the
\`\renum` command can be used as follows:

\begtt
\renum <book-abbreviation> <default-chapter-number>:<default-verse-number> = <translation> 
<chapter-number>:<verse-number-from>-<verse-number-to>
\endtt
where `<translation>` is the mark of a particular translation. If the `\tmark` is declared as `<translation>` using `\def\tmark{<translation>}` then
the `<default-chapter-number>:<default-verse-number>`  is replaced with
<chapter-number>:<verse-number-from>-<verse-number-to>.
Such renumbering applies to the entire range of verses defined by `<verse-number-from>-<verse-number-to>`.

For example, let's suppose that
in the book of Daniel, in verses 10:20 and 10:21 we want to comment on several phrases, such as 
“angel of Persia” and “true writings”. For some reason (not entirely clear) BBE has these phrases in 
opposing verses then the rest of the translations.

We number the notes according to the translation given as the first parameter of the definition of 
`\variants` in the `vars.tex` file, (in our example `BBE`) including references like “See note on 
10:20.”
Renumbered translations change the note number according to the actual verse number that the note 
comments on, including the reference, which is then printed as “See note on 10:21.”

If the renumbering refers to a single verse only, then the identical 
`<verse-number-from>` and `<verse-number-to>`  should be given, as in the example below:

\begtt
\renum Dan 10:20 = Jubilee2000 10:21-21
\renum Dan 10:20 = NETfree 10:21-21
\renum Dan 10:20 = UKJV 10:21-21
\renum Dan 10:20 = RNKJV 10:21-21
\renum Dan 10:20 = Webster 10:21-21
\endtt



%After such a declaration, the final remark 
%\begtt \catcode`\<=12
%\Note 5:31 {Darius}={\x/Darius/Median} Some schools claim that this and other 
%   (<6:1>, <6:6>, <6:9>, <6:25>, <6:28>; <9:1>; <11:1>)     
%   The references to \x/Darius/ Medes in the book of \x/Daniel/ are historical errors.
%\endtt
%prints as follows:
%
%{\medskip\leftskip=\parindent\noindent
%{\bf 6:1 Darius the Mede} \ Some schools claim that this and other 
%(6:2, 6:7, 6:10, 6:26, 6:29; 9:1; 11:1)     
%references to Darius the Mede in the book of Daniel are historical errors.
%\medskip}

The macro `\renum` can handle even such tidbits as shifting a number of a mere part of a verse.
This example comes from the Czech SNC translation where the phrase \uv{jen Bůh, který je v nebesích, odhaluje tajemství} (\"there is a God in heaven 
who reveals secret things"), is for no clear reason a part of the verse 2:27 while all other Bibles have it in the verse 2:28. 
But the fun does not end here; if you want to comment also on the phrase \uv{posledních dnů} (\"the latter days") you'll now find it in the verse 2:28
where the rest of the Bibles have it as well. What are you going to do? How can you renumber just half of the verse?

Well, you can do it by applying `\renum` on the same verse twice: the first time {\em before} the `\Note` on the first phrase, and the second time {\em after} it.
So you type:
\begtt
\renum Da 2:28 = SNC 2:27-27
\ww {jest Bůh na nebi, kterýž zjevuje tajné věci}       %BKR
    {v nebesích je Bůh, zjevující tajemství}            %PSP
    {jest Bůh na nebesích, zjevující tajemství}         %CSP
    {je Bůh v nebesích, který odhaluje tajemství}       %CEP
    {Na nebi je však Bůh, který zjevuje tajemství}      %B21 
    {jen Bůh, který je v nebesích, odhaluje tajemství}  %SNC    
\Note 2:28 {} Podobně jako Josef v Egyptě (<Gn 40:8>; <Gn 41:16>) si ani \x/Daniel/
nepřisvojuje poznání a výklad snu, nýbrž připisuje je Bohu.

\renum Da 2:28 = SNC 2:28-28
\ww {v potomních dnech}   %BKR
    {v posledku dní}      %PSP
    {v budoucích dnech}   %CSP
    {v posledních dnech}  %CEP
    {v posledních dnech}  %B21 
    {posledních dnů}      %SNC
\Note 2:28 {} Dosl. \uv{v posledních dnech}, čemuž sz lidé rozuměli jako době obnovy národa
po návratu z exilu (viz <Dt 4:30>). Tatáž fráze může označovat jakoukoliv budoucnost
(<Gn 49:1>). V NZ je použita celkem pětkrát, z čehož dvakrát odkazuje na věk, započatý
o Letnicích (<Sk 2:17>; <Žd 1:2>), a třikrát na závěr dějin
před Kristovým druhým příchodem (<2Tm 3:1>; <Jk 5:3> a <2Pt 3:3>). 

\endtt

Now everything works as it should: Where the numbering diverges, it renumbers; where it it matches, it stays the same. All Bibles except SNC have the first `\Note` numbered 2:28 but SNC has it as 2:27; then all of them have the second `\Note` as 2:28.

\recommended
You may want to use `\renum` also in other files, e.g., intro or fmt, not just 
notes. In such cases, if would be advisable to use `\renum` inside the 
`vars.tex` file, so that it applies everywhere without the need to retype 
the same instruction more times (for example, both in Introduction and Notes 
files).



\sec[links] Methods of creating hyperlinks

A reference is a part of the text by which the reader, even after printing it, can tell to what other place in the text (or in the~internet) one can look at. Thus, it typically contains a numerical indication of page or the number of a chapter, section, etc. In addition, if the reader is working with a PDF viewer, then this part of the text can be {\em active}, i.e., when the mouse hovers over
this text you can click on it and the PDF viewer will go to the specified place in the document (or to the Internet).

The Bible is invariably
structured text. It contains (in the Protestant canon) 66 books with established markers for those books,
each book has its chapters numbered from one and each chapter has verses
numbered from one. So there is no need to have \TeX/ generate these numbers
automatically (as it does when typesetting, say, a technical text that is divided into
chapters and sections), and thus there is no need to use labels in the source
document (which \TeX/ would assigns to the numbers generated during processing) and to refer by these labels in the source file, 
as described in section \ulink[http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf]{1.4.3} of the 
\ulink[http://petr.olsak.net/optex/]{\OpTeX/} documentation. 
It is much more efficient to refer directly to a specific place in the Bible that already has
for many centuries now,  fixed chapter and verse numbers.\fnote{%
The Archbishop of Canterbury, Stephen Langton, in the early 13th century, when he was teaching at the University of Paris (and has not yet become an 
archbishop) divided the Bible into chapters. 
Then, in the mid-16th century, the French books printer Robert Estienne divided the New Testament into verses and added the Old Testament, 
which Jewish scribes had centuries earlier divided into verses (but not into chapters).
Since 1553, when Estienne published the first French Bible thus numbered, we have used this system to this day.}


 
 
The references to a specific place in the Bible are written between \code{<} and \code{>} in the source file.
The text between these characters is printed as written (with the exceptions mentioned below). 
Nevertheless, \TeX/ has to be able to interpret the reference correctly in order to
make it active with a clicking capability to the correct place in the Bible. This is done by
rather large amount of rules, therefore this section is dedicated to them.


\secc[uudaj] Basic rule with complete data

The reference between \code{<} and \code{>} is of the form 
\begtt\catcode`<=12
<"text" data>
\endtt
\ or just \code{<}`data`\code{>}. 
The complete `<data>` is of the form `<book> <chapter>:<verse>`. Here `<book>` is the abbreviation of the book (it must be followed by
space), `<chapter>` is the chapter number, and `<verse>` is the verse number.
Example:

\begtt \catcode`<=12
... see also verse <Jer 8:13>
... see also <"verse" Jer 8:13>
\endtt
In the first case it prints ... see also verse {\Blue Jer 8:13} and in the second case
... see also {\Blue verse Jer 8:13}. 
In both cases the area marked in blue will be active (clickable) and will lead to Jer 8:13.


\secc Link specifier

The link's closing  character `>` may be immediately (i.e., without a space) followed by a link 
specifier, which is one of the letters:
\begitems
* `n` ... refers to a note,
* `a` ... refers to an article,
* `i` ... refers to an introduction,
* `g` ... refers to a gloss (which will hopefully come into play in one of the future versions of \OpBible/ with the core text typeset in two columns).
\enditems
The link specifier is not printed in PDF, it is just internal information where 
the active link should click. If the closing character `>` 
 is not followed by any of these specifiers, it is a link to the verse 
(probably the most common case).
Example of a note reference:

\begtt \catcode`\<=12
... see <"note on" Jer 7:4>n for more information.
\endtt
prints ... see {\Blue note on Jer 7:4} for more information.
The click leads to the first note on Jer~7:4, not to the verse itself.

In the case of a reference to an article (specifier `a`), the full entry has the format
`<book> <chapter>`, i.e., the verse information is missing because the articles can be understood as introductions to chapters. In the case of a reference to the introduction to a book (specifier `i`), the full entry is in the format `<book>` (lacking both chapter and verse information) because these
are book introductions. In~other cases, the full entry has the format as 
described in section~\ref[uudaj], with the  exception described in~section~\ref[vudaj].

\secc[tochapter] References to whole chapters

You can omit `:` and verse number in your reference text. Then the reference points to the first verse  of the given chapter. Examples:
\begtt \catcode`<=12
... see <"chapter" Dan 7>
... Joseph's story (<Gn 39-41>)
\endtt
In the second example, the range of chapters is given and \TeX/ creates an internal link to
the first verse of chapter 39. Compare also with the section~\ref[verse range].


\secc[vudaj] Exception for the format of the full entry for some books

Books Obad, Phlm, 2John, 3John, and Jude are not divided into chapters. 
In a reference to a verse, note to a verse or a gloss to one of these books, 
the chapter information is missing and the format of a complete reference looks like this: 
`<book> <verse>`. In order to teach \TeX/ to apply this exception, the list of abbreviations for these books needs to be defined in macro \`\nochapbooks`. For example, the `books.tex` file says
\begtt
\def\nochapbooks{Obad Phlm 2John 3John Jude}
\endtt
Since there are different book abbreviations for different languages, this macro  needs to be defined
according to the language used. In any case, the abbreviations have to be exactly the same as the ones declared by the `\printedbooks` macro in the main file.

Example: \code{see <Phlm 3>} prints
see {\Blue Phlm 3} and it refers to verse 3 of the Philemon, not to chapter~3. On the other hand, \code{see <Gen 3>} prints see {\Blue Gen 3} and refers to the beginning of the chapter 3 of  Genesis. It is the reference to the whole chapter, as described in the section~\ref[tochapter].

\secc[bored] Incomplete data

Sometimes the reader can determine the location of a verse from the context, therefore `<data>` does not need to be complete. In the {{\em incomplete data}}, there may be a  `<book>` missing, or
`<book> <chapter>:` or even  everything. For example:

\begtt \catcode`<=12
... we also see an analogy in <"verses" Jer 8:13>, <9:7> and <11:3>
... see verses <Jer 8:13>, <15>, <17>
... see all of the <"verses" Jr 8:13>--<22>,
... (cf. <Jr 8:13> and <"its note">n).
\endtt
This yields:
... we also see an analogy in {\Blue verses Jer 8:13}, {\Blue 9:7} and {\Blue 11:3}
... see verses {\Blue Jer 8:13}, {\Blue 15}, {\Blue 17}
... see all of the {\Blue verses Jer 8:13}--{\Blue 22}.
... (cf. {\Blue Jer 8:13} and {\Blue its note}).

The entries `9:7`, `11:3`, `15`, `17`, `22` and the last blank one
in these examples are incomplete data. The reader knows that they refer to
the book of Jeremiah and where no chapter is given, they refer to chapter 8 of
Jeremiah. In the last example with a blank, the reader knows that it is a note
on~Jer~8:13.
\TeX/ knows that too, and it assigns  correct links (to be clicked on) to the incomplete entries
because incomplete entries take the unspecified information from the previous last entry. 
This rule applies locally to a single text object: note, article, introduction, etc. If the very 
first entry in  a given text object is incomplete, the unspecified information is replaced with by 
the abbreviation of the book currently being processed, or by the number of the current chapter,
or verse, respectively.

If an incomplete entry is prefixed with `\`, the unspecified information is taken from
the book or chapter or verse currently being processed, regardless of which entry
precedes. For example:
\begtt \catcode`<=12
\Note 4.5 {} The idea is repeated in <Jer 4:5>. Also, compare to \<8:3>.
\endtt
Here the reference {\Blue 8:3} leads to verse 3 of chapter 8 of the actual current book. If 
the backslash sign `\`  were not there, then this reference would click to 8:3 of Jeremiah.

An incomplete entry is printed as is, as incomplete. The above rules 
only apply internally so that the active link will work properly after a mouse click.



\secc[verse range] Format for the verse range and for the section in the verse

In each entry, it is possible to have  a range of verses in the format `<from>-<to>`
instead of just `<verse>` or `<chapter>:<verse>`. 
 The \TeX/ will create an internal link to the first verse of the range only and
turns the hyphen sign (character `-`, ASCII 45) in the range into an en-dash. 

Examples:

\begtt \catcode`<=12
<Jer 8:3-7>,
<Jer 8:3-9:5>,
<3-7>,
<8:3-7>.
\endtt
For example, the first link in this example prints as {\Blue Jer 8:3--7}
and offers a link only to Jer~8:3.

The same can be applied to the chapter range, as shown in the example in the section~\ref[tochapter].

\secc References to subverses

Sometimes we need to refer to a part of a verse, not the whole verse. This is done
by appending a letter immediately after the verse number. For example,
\begtt \catcode`<=12
... see <Dan 9:11b>
\endtt
You can append such a letter to both complete and incomplete references. For the purpose of
hyperlink, these letters are ignored but printed in PDF. Thus, the example given
prints ... see {\Blue Dan~9:11b}, but the link leads to Dan~9:11.

\secc Hidden data

When none of the rules are sufficient to create an internal link from a link
listed above, you can enclose everything in the link to be printed in the programmer's 
quotation marks `"..."` and hide the subsequent entry to create the internal link. 
To do this, just append underscore `_` followed by the data right after the closing programmers' quotation mark  `"` Such entry is not printed. For example,
\begtt \catcode`<=12
<"First Book of Samuel"_1Sam 1:1>
\endtt
prints only the text {\Blue First Book of Samuel}, which internally refers (the click jumps) to the first verse of this book.



\secc[Renum] Renumbering the reference

If a link points to a verse that has a different number than the default translation 
(the first translation among the parameters  of \`\variants` declaration), then  
 enter the reference according to the default numbering and \TeX/ will recalculate it itself according to the data specified by `\renum`. 
 It prints the recalculated data and uses it for the internal reference.
Cf.~\ref[renum]. 

\secc Data reduction when printing

You may find it helpful to be able to write the complete data in parentheses for the reference and expect it to be automatically  reduced to incomplete if they refer to the current book.
If they do not refer to the current book, the entry will remain complete. You can do this by
by adding a \`\re` before the opening parenthesis of the entry (the eventual reduction rule 
applies only to this single entry) or by using the \`\reduceref` command. If you
you use it in a note (or inside a \TeX group), the reduction rule is applied 
for all subsequent complete entries of that note (or of that \TeX/ group). 
When used in a document declaration, the eventual reduction rule is applied to all complete data in the document. 

Example:

\begtt \catcode`<=12
\re<"verse" Dan 7:3>
\endtt
is printed as {\Blue verse Dan~7:3} if this reference is given outside the book
Daniel. However, when this reference is given inside the book of Daniel, it is printed
only as {\Blue verse~7:3}, which internally refers to Dan~7:3. 

The reference reduction rule set by \`\reduceref` can be turned off 
with the \`\noreduceref` command. From there to the end of the note (\TeX/ group)
links behave as if \`\reduceref` were not turned on.




\secc[knihajinak] The book's abbreviation (a-mark) can be printed differently

If the mark for a book is declared differently in different translations following
\`\vdef`, then use only the <book> entry in the references according to the first (default)
variant. However, if you currently use an  alternative translation via \`\tmark`, 
the link will be printed according to the \`\vdef` entry of that alternative translation variant.
Internally, nevertheless, references are linked according to the default variant.

You'll find this feature is useful when you run across two different translations 
which name the same book differently.
In English it is rarely the case but let's suppose that (hypothetically) there exists an English 
translation that prefers “Paralipomenon” over “Chronicles”. Let's call this hypothetical 
translation “Greek.”
Your default translation (the first translation in the \`\variants` declaration)
uses “Chronicles” as all English translations usually do. 

Now  you can declare `\vdef` for marks `1Chr` and `2Chr` (Chronicles) for most of English 
translations, especially the first one, and an alternative text for `1Par` and `2Par` 
(Paralipomenon) for the “Greek” translation. 
Then you can type the reference \code{<"see" 1Chr 2:3>}, you get {\Blue see 1Chr~2:3} in the usual
translation variants, but it will print {\Blue see 1Par~2:3} if you use
translation variant~“Greek”.

Non-English languages may use it more often, though. 
For example, in the Czech language, most translations 
use “Paralipomenon” where English Bibles use “Chronicles” but there is one translation (B21) that uses 
the title “Letopisů” instead of “Paralipomenon”. 
Then \code{<"viz" 1Pa 2:3>} yields  {\Blue viz 1Pa~2:3} in most of Czech translations, except in B21 where it gives {\Blue viz 1Let~2:3}.

\secc[fudaj] Bad links, i.e., links to a non-existent spot

If a reference is made to a non-existent verse or a non-existent note, then
there are two possibilities. If it is a reference to a book that is intentionally not being printed
(because, for example, you are working on a test books selection,
see also \`\printedbooks` in section~\ref[main]), then the link is  colored
as if it were active, but it is not, and \TeX/ gives
no warning. However, if the link points to a non-existent verse or
note within the printed books, then the link is active, the click goes to
the last page of the PDF file, and a warning appears in the log, saying that the link
is incorrect. Be aware, though, that when\TeX/ runs for the first time, all
links lead to nowhere (as they are being created for the first time), 
thus there is a large number of warnings about incorrect links in the log.
Only after you run \TeX/ the second time, 
the links pointing to existing places are correctly interlinked.


\secc Link Tracing

By default, detailed link tracing is enabled in the log file.
You can turn this off by saying \`\notracinglinks` and back on with \`\tracinglinks`.
In addition, you can use \`\tracingouterlinks` to disable the suppression of link warnings on
non-existent books, allowing the log to find any non-existent links resulting from
 a typo in the reference text.

\secc Links to  books and chapters 

If you want a reference to a book that would click to the beginning of that book, 
write \`\cref``[<book>]`. For example, `\cref[Gen]` will print {\Blue Gen} with a link to
the beginning of the book of Genesis. Similarly, `\cref[Gen 2]` will print {\Blue Gen~2} with a click 
leading to Gen 2:1. If you want to print something else, then 
`[...]` must be closely followed by `{<text>}`, where `<text>` is the text 
to be printed and to become the active link. So, for example
`\cref[Gen 2]{The Day of Rest}` will print {\Blue The Day of Rest} with a~link to the beginning of 
the corresponding chapter (Gen 2:1).

\secc Links to pages

You can place an invisible page link target in your text using \`\pglabel``[<label>]` and
then you can link to that page using \`\pgref``[<label>]`; this
 will print the clickable number of that target page.
Similar to `\cref`, you can use `\pgref[<label>]{<text>}`
to print a `<text>` other than the page number; the text now clicks  to the place where
where the `\pglabel[<label>]` is located.

\sec[maps] Maps, images and their legends

The images (maps etc.) can be inserted to the bottom of the page by the \`\insertBot` or \`\putBot` command:

\begtt
\insertBot {<title>} [<label>] (<params>) {<data>}
or
\putBot <chapter>:<verse> {<title>} [<label>] (<params>) {<data>}
\endtt

The first one can be used in introductions, the image is inserted at the bottom of the current or the next page. The second one can be used in note files, the image is inserted at the bottom of the page where the given verse is (or at the bottom of the next page). The `<title>` is a caption of the image, the `<label>` can be used for references, the `<params>` can include more typesetting parameters and `<data>` includes commands for inserting the image itself. A comprehensive example will follow in section~\ref[map-variants].

\secc[map-variants] Translation variants

Just as you can change the wording of a search phrase in a note to match the current core text, 
you can also create map legends (and similar graphical objects showing expressions that vary in different translations) to always match the current version of the Bible.

Suppose that we insert a separate blank map and  text for the legend. Any text can be placed over an image using \`\puttext` command: 
\begtt
\puttext <x-dimen> <y-dimen> {<text>}
\endtt
where <x-dimen> determines the horizontal offset on the x-axis, <y-dimen> the vertical offset on the y-axis,  with the coordinates `0mm 0mm` being the bottom left corner of the image. The <text> is printed text.
For example:
\begtt
\puttext 5mm 62mm {Mediterranean sea}
\endtt

You can insert a text over the map with a white semitransparent shadow as a background of the text. Use \`\putstext` instead \`\puttext` in this case. The parameters are the same with the same meaning. See section~\ref[bkgrnd] for more information about it.

\medskip
\centerline{\picw=200pt \inspic{images/BBE.png} \hss\inspic{images/NETfree.png} } 
\medskip
\leftline{Map from the Introduction to Daniel:  BBE \hss NETfree}
\medskip
For example, you can notice how in the sample above not only that the biblical references are active hyperlinks, but also that the name of the city of Susan (just above the Persian Gulf) changes from the BBE's  Shushan into Susa of NETfree.

The image must be loaded before the description can start, and everything in it must be inside the definition of \`\insertBot`. 
The above sample has been written as

\begtt \catcode`<=12
\insertBot {Daniel's Remote Visions Empires}[map](){
  \inspic{fertile-crescent-crop.pdf}% blind map 
  \Heros \cond \setfontsize{at 9pt}\rm %font
  \vskip-1mm 
  \putstext 2mm 108mm {\vtop{\hsize6.5cm %box width
                     \baselineskip10pt %line spacing inside the box
                     \noindent %space saving, no need to indent
    \leftskip=3pt \rightskip=3pt %how much the semi-transparent shadow will overlap the text 
     Soon after Alexander's death ... was conquered by Rome.}%end\vtop
  }%end \putstext
  \LMfonts\sans \setfontsize{at9pt}\rm
  \puttext 145mm 29mm {<"Acts 2:9"_Acts 2:9>}
  \puttext 145mm 32.5mm {<"Ez 32:16"_Ez 32:16>}
   .
   .
   .
  \puttext 2mm 5mm{{{{Heros \setfontsize{at 7pt}\it Satellite Bible Atlas,\rm W.Schlegel}}
  \puttext 2mm 2mm{\Heros \setfontsize{at 7pt}\rm Used with permission.}
}%end \insertBot
\endtt


{\bf What to watch out for:} 
 There must not be a blank line inside `\insertBot`.



\secc[town] Macro `\town` for the town symbol on the map


The towns of Jerusalem, Babylon, Tolul Dura, Susan and Ur are visible on the map as tiny circles 
with a red center and black perimeter.
The properties of this circle can be set with the macro \`\townparams`, whose default values are 
as follows:

\begtt
\def\townparams{
   \hhkern=.8pt % radius of the circle
   \lwidth=.5pt % contour line thickness
   \fcolor=\Red % circle color
   \lcolor=\Black % contour line color
}
\endtt

The macro \`\town` itself places this circle with coordinates, similar to the macro `\puttext`, 
but without additional text, e.g.,

\begtt
  \town 101.5mm 53mm %the city Babylon
\endtt



\secc[maptitles] Inscriptions along the curve

Some of the inscriptions on the map require “bending” according to the terrain, especially the 
names of large areas, as in our case  “The Ptolemies” and “The Seleucids,” or the “Persian 
Gulf,” or perhaps even the tiny names of rivers (“Euphrates,” “Tigris,” “Nile”). 
In order to do this we can use the \`\c` command inside the \`\puttext` parameter.
\begtt
\c[<first-angle>/<kern and rotate parameters>]{<text>}
\endtt
For example:
\begtt
\puttext 62mm 70mm {\c[10/\kern7pt\pdfrotate{-1}]{THE SELEUCIDS}}
\puttext 2mm 37mm {\c[0/\kern4pt\pdfrotate{2.5}]{THE PTOLEMIES}}
\endtt

The first number (before `/`) denotes the angle of the first letter of the text.
The \`\kern` command determines the spacing between letters; the number in the \`\pdfrotate``{<number>}` 
determines the strength of the curvature (the angle change between two successive letters). A negative value bends the text concavely 
(like a rainbow), a positive value convexly (like a bowl).

If we need a sign that waves in the shape of the letter S (is concave and convex at 
the same time), we would have to assemble it from two or more `\puttext` statements, glued 
together to look like one continuous text. 


In the example above we have the name of the city of Jerusalem printed at an oblique angle but along a straight line so that it 
does not clash with “king of the South” and can be seen clearly.
This can be achieved by using the \`\c` command without `\pdfrotate` parameter:

\begtt
\puttext 48mm 55mm {\c[-40/\kern1pt]{Jerusalem}}
\endtt
The number `-40` was used to tilt the inscription.


\secc[bkgrnd] Partially transparent background of continuous text

In the sample above, the continuous blocks of text have slightly lighter background 
through which the map from beneath is still visible.
This can be achieved by typing \`\putstext` (think of Put-Shadowed-Text) in the place of 
\`\puttext`. This way you don't need any pre-prepared lighter spots on the blind map (see the 
image bellow), having to “hit” it with the text. 


\medskip
\centerline{\picw=150pt\inspic{images/fertile-crescent-crop-old.pdf} }
%\hss \inspic{images/Da-map-shadowed-text.png}%

\smallskip

Before using \`\putstext` for the first time, the level of transparency of the white shadow can be set.  The default value is `\def\shadowparameter{.1}`. 
If you set `\def\shadowparameter{1}` you get a solid opaque white background; the smaller the number the more transparency. 

However, this value is then stored in the page-resources of the output PDF and is used 
the same  on all subsequent pages, so you cannot change it and have it  different in 
different places of the same document. 
If perhaps there should be an unexpectedly excessive 
demand for the ability to change the transparency level on the fly, this may be an incentive for 
implementation in a possible future version of \OpBible/.
For the time being, we did not find it necessary to complicate the macros by creating more and more 
page-resources, so the user should be satisfied with the option to set the transparency of the 
shadow under the text on maps uniformly for the entire Bible.  


%\medskip
%\centerline{\picw=150pt \hss\inspic{images/Da-map-shaded-text.png} } 
%\medskip

\sec Timeline inclusion tools

\secc[spanimage] Image or text over two pages

If we want to insert an image or text across two pages in an open double page, we can
use
\begitems
* \`\insertSpanImage`: inserts a prepared PDF image, can be used in the book introduction,
* \`\insertSpanText`: insert text (for example a timeline), can be used in the book introduction,
* \`\putSpanImage`: insert a prepared PDF image, anchored relative to the number
   chapter and verse, can be used in the notes file,
* \`\putSpanText`: like \`\putSpanImage`, but inserts text instead of an image.
\enditems
The \`\insertSpanImage` and \`\insertSpanText` commands place the image or text 
at the bottom of two pages according to the following rule. Suppose that
the command itself is executed when \TeX/ creates the current page of
the number $c$. Then
\begitems
* if $c$ is even and the image's (or text's) height allows it to fit on the current page,
  it will be placed on pages $c$ and $c+1$,
* if $c$ is even and the image or text does not fit on the current page,
  it will be placed on pages $c+2$ and $c+3$,
* if $c$ is odd, the image or text will be placed on pages $c+1$, $c+2$.
\enditems
This ensures that the image or text will always be visible on the double page
of an open book.

The \`\putSpanImage` or \`\putSpanText` commands work according to the same rule,
only the number $c$ in this case corresponds to the page number on which the
the beginning of the verse specified in the command parameter.

These commands have the following parameters:
\medskip
\`\insertSpanImage` `{Title} [<label>] (<parameters>) {<filename>}`
\medskip\noindent
The <Title> is used in the header of the image and <label> can be set,
to refer to the image (and thus create an active link) using `\ref[<label>]` at another place.
If unused, you can leave the parameter empty: `[]`.
Furthermore, <parameters> can specify how the image is placed, typically this
parameter is empty: `()`. Finally, <filename> is the name of the image file
including the extension. Typically this is a PDF file, i.e., it has the extension `.pdf`.
\medskip
\`\insertSpanText` `{Title} [<column>] (<parameters>) {<text>}`
\medskip\noindent
The parameters are the same as \`\insertSpanImage`, only the last parameter is different.
It contains the text to be printed across two pages. Typically there might be
a set of `\timeline`, `\timelinewidth`, `\arrowtext`, `\tlput`, `\tline`, `\tlines` commands to create a timeline, see the section~\ref[timeline].
\medskip
\`\putSpanImage` `<chapter>:<string> {Title} [<column>] (<parameters>) {<filename>}`
\medskip\noindent
In addition, there is a <chapter>:<verse> specifying the verse whose beginning is on page $c$
and the image is positioned according to the rules mentioned above. The other parameters are the same as
for \`\insertSpanImage`.
\medskip
\`\putSpanText` `<chapter>:<verse> {Title} [<image>] (<parameters>) {<text>}`
\medskip\noindent
It behaves the same as \`\insertSpanText`, but with the addition of the <chapter>:<string> parameter
has the same meaning as in the \`\putSpanImage` command.


\secc[timeline] Commands to create a timeline

These commands can be used in the <text> parameter of the \`\insertSpanText` or \`\putSpanText` commands.

First, you need to specify the number of years (or other units) for the full width of the timeline. 
All other data will be entered in these units. In the following text
we will refer to these units as years.
Set the timeline parameters using \`\timeline` and \`\timelinewidth`:
\begtt \catcode`\<=13
   \timeline <number of years>
   \timelinewidth <width of the timeline>
\endtt
For example, after
\begtt
   \timeline 500
   \timelinewidth 25cm
\endtt
the timeline will be 25cm wide and 500 years will be included in that width, so one year
will represent a width of 0.5 millimeters. However, it is more usual to specify the width of the timeline
as some fraction of the total width of the page (or double-sided image, if using
timeline in \`\insertSpanText` or \`\putSpanText`). For example:
`\timelinewidth=.95\hsize`.

The timeline is built line by line. Commands for text or line segments that
are on the same line are written below each other in any order. 
 \`\vskip` `<dimension>` command moves to the next line, where the dimension can be specified
in multiples of the line height using the unit \`\l`, i.e., `\vskip 1.5\l`
means a shift of one and a half lines down.

Text is inserted via \`\tlput` `<symbol> <position> <flag> (<setting>) {<text>}`.
The <symbol> parameter can be \"`a`" if we want the text to be above the current
rate position, or \"`b`" if we want the text to be below the current rate position.
When the <symbol> is \"`a`", multiline text extends upwards, and when \"`b`", it extends downwards.

The <position> parameter is the location on the timeline (in years) to which the text should be attached. 
From this point, the text will flow to the right if <flag> is specified by the \`\rlap` instruction, 
and it will flow to the left if the <flag> is specified by the \`\llap`. Finally, if <flag> is empty, the text will have centered lines and
<position> then corresponds to this line center. The `<setting>` parameter can be be empty, i.e., `()`, 
or it may contain font settings, font color, etc., for following <text>. 
A <text> contains the text to be printed. In the case of multi-line text, separate the lines with \`\cr` 
(remember what carriage return meant in the era of typewriters?), for example:
\begtt
   \tlput b 25 (\it) {Abraham is\cr 100 years old}
\endtt 
The text has two lines, their common center is below point 25 of the timeline.

\`\tline` `<from>..<to>` creates a horizontal line starting at <from> and
ending at <to>. The data is in years.

\`\tlines` `<w1>|<w2>|<w3>|` (and possibly more) inserts short vertical lines on the timeline.
The number of `<w>|` parameters can be arbitrary, each representing one
vertical line, and the numbers between them indicate the distance between adjacent lines in years. For example
\begtt
\tline 0..100
\tlines 20|20|20|20|20|
\endtt
creates a 100 horizontal line and vertical lines on top of it to denote 20,
40, 60 and 80 years.

\`\arrowtext` `<from>..<to> (<setting>) {<text>}`
prints a horizontal line from <from> to <to> (data in years)
and the middle of the line is broken to give space for the <text> which written at that point. 
Arrows pointing outwards from the line are at the edges of the line.

This timeline has been shrinked from a double-page size:
\medskip
\picw=1.1\hsize
\inspic{images/timeline-crop.pdf}

and was typeset as follows:

\begtt \typosize[8/11]
\def\small{\typosize[8/10]}
\putSpanText 12:40 {How long have been the Israelites in Egypt?} [] () {%we are in Exodus
\timeline 430         % total number of years (or other units) in the timeline
\timelinewidth 36cm   % the width of timeline (here: 430 years = 36 cm)
\arrowtext 0..430 (\bf) {\hskip20mm 430 years \hskip1cm (Exod 12:40; Gal 3:16--17)} 
                        % prints arrow from..to, (format) {text} in the middle; 
                        %\hskip controls the spaces in the middle where two pages meet
\vskip 2\l            % \vskip 2\baseineskip; \l is only shortcut for \baselineskip
\tlput a   0 \rlap(\bf)   {Abraham received\cr promise (Gen 12:3-5,7; 15:5--6)}  % print text
\tlput a 430 \llap(\bf)   {Moses received \cr the Law (Exod 24:12)}   % see \_doc above 
                                                                      % for more details
\vskip 1.5\l          % \vskip 1.5\baselineskip
\tlput a   0 \rlap()      {Entered do Canaan (Gen 12:4)}              % print text
\tlput a 430 \llap()      {Left Egypt (Exod 12:41)}                   % print text
\tlput a 215      (\bf)   {\hskip-6mm Entire \hskip8mm Israel\cr 
                                             \hskip 8mm arrived to 
                                             \hskip7mm  Egypt (Gen 47:9)} % print text
                      % all \tlput's between \vskip's is printed in the single line
\vskip 1\l
\tlput a 25   (\small)   {Isaac born (Gen 21:5)}  % text
\tlput a 85   (\small)   {Jacob born (Gen 25:26)}  % text
\vskip1.1\l
\tline 0..430         % the horizontal line from..to
\tlines {0|25|60|130|215|0} % the vertical short lines, numbers mean distance between them
\vskip.2\l
\tlput b 12.5 (\small)    {25 years}    % text printed below     
\tlput b 55   (\small)    {60 years}    % i.e the current position is at the top of the text
\vskip.7\l
\tlput b 0    (\small)      {Abraham\cr 75 years}
\tlput b 25   (\small)      {Abraham\cr 100 years}
\tlput b 85   (\small)      {Isaac\cr 60 years}
\tlput b 215  (\small)      {\hskip1cm Jacob\cr\hskip1cm 130 years}
\vskip2.5\l
\tlines {|215|215|}    % the vertical short lines
\arrowtext 0..215 (\bf) {215 years in Canaan}  % arrows and text
\arrowtext 215..430 (\bf) {215 years in Egypt}
\vskip2\l
\tlines {|30|400|}    % the vertical short lines
\arrowtext 30..430 (\bf) {Abraham's seed afflicted in a land not theirs for 400 years (Gen 15:13)}
\tlput b 15 (\small) {25$+$5$=$30\cr Isaac weaned\cr in 5 years}
\vskip.5\l
\tlput b 65 (\small) {Ishmael bullied Isaac in Canaan \cr since the day Isaac was weaned (Gen 21:8--9)}
\tlput b 385 (\small) {Israel afflicted in Egypt (Exod 1:11)}
\tlput b 215 () {\hskip2.5cm 430$-$30$=$400}
}%end of \putSpanText
\endtt

\filbreak

\sec Page formatting variants

By default, a single-column design is set for the main text of the Bible
and for book introductions and annotations. Two-column type is set for
notes on verses.

By default, chapter numbers are capitalized and in the outer margin. 
In the outer margin there are also enlarged quotation marks attached to quotations. 
The command \`\normalchapnumbers` changes this setting: chapter numbers are then inserted in the left
upper corner of the first paragraph and the enlarged quotation marks are removed.
The outer margin is then shrunk because there is no more printed material in it.  



By default, each \`\Note` occupies a new paragraph in a  double column print. 
The command \`\mergednotes` makes sure that all notes on a single verse are always 
combined into a common paragraph. 
However, this comes at a cost of loosing the ability for the phrase in the note
to follow its original in the Biblical verse on the same page.
In other words, the entire paragraph (compound of several notes on the same verse)
links only  to the beginning of the verse, i.e., the beginning of the verse 
and the beginning of the note to that verse are on the same page,
but the phrases themselves are not being searched for.

Other page formatting options are still in the planning stages and are not implemented in this version of \OpBible/.


\sec Error search options

It may happen that you make a typo in the `notes-*`, `intro-*`,
`articles-*` files. If you had included the file with a typo to the whole Bible processing,
\TeX/ would report an error at a completely different point in time than when it had read the file. 
Unfortunately, tracing back such an error is then very difficult. Moreover, typically the error
occurs at a different stage of processing and thus it is often reported in a very
incomprehensible and misleading message.

However, it is possible to process the newly written files directly first, 
but with no connection to the core text. 
In this mode, potential errors are reported more directly.
To search for errors directly, use \`\checksyntax` <file list> `{}`
Here the file list are the names of the files to be checked (without the `.tex` extension).
You can have, for example, at the end of the main file, line like this:

\begtt
\checksyntax intro-Dan articles-Dan notes-Dan {}
\endtt

This will perform a direct check of the listed files. The output is the text of these
files without any formatting. Syntax errors in the files 
will show up in significantly more straightforward manner.

Note: using \`\checksyntax` disables the \`\processbooks` command, which in turn
does nothing, so the core text of the Bible is not loaded at all.


\sec Generating default files `notes`, `fmt`, `intro`

If the files `notes`, `fmt`, `intro` do not exist, \OpBible/ does not complain and
behaves as if they were empty. But you might want to have these
files for all the books of the Bible already prepared in the appropriate directories and
with a short introduction. Templates for such files can be
written  in a separate file (e.g.,`templates.tex`) and then
run such file using the `optex templates` command. This will generate the default files
according to the specified templates for all the books of the Bible.
If a file with the specified name already exists, it is retained (i.e., it is not
overwritten by the default file) and a warning about it will appear on the terminal and
in the `log` file.

First you need the `books.tex` file with the names and abbreviations for all the books of the Bible,
as mentioned in the~\ref[books] section. This can be generated, for example
from Sword using the `mod2tex` script, see section~\ref[txs].

In the `templates.tex` file, the packagge `opbible.opm` must first be loaded using `\input`, 
then the `books.tex` file, 
and then you can specify file templates with the \`\filegen` command as follows:

\begtt
\filegen {<file-name>}
<file-content>
\endfile
\endtt
%
The <filename> must (and <file-content> can) contain the double character `@@`, 
which is automatically replaced by the book abbreviation <b-mark> specified in `books.tex`. 
As  many default files as there are book titles declared in `books.tex` are then automatically generated.
For example, `templates.tex` might look like this:

\begtt
\input opbible.opm
\input books.tex

\filegen {intro-@@.tex}
%  Introduction to the book @@
\endfile

\filegen {notes-@@.tex}

%  Notes on the book @@

\endinput
\ww 
    {}={} % BBE
    {}={} % Jubilee2000
    {}={} % NETfree
    {}={} % UKJV
    {}={} % RNKJV
    {}={} % Webster
\Note 1:1 {}={} %text terminated with a blank line
\endfile
\endtt
%
The `optex templates` command will generate 66 files in this case
`intro-1John.tex`, `intro-1Cor.tex`, etc. with the specified single line
and 66 `notes` files  (`notes-1John.tex`, etc.) with the content of the specified nine lines.

You can also use the triple character `@@@` in the <file-content>, which is then converted into
the full title of the book. So after specifying 
`% Introduction to @@@` in the `templates.tex` file
you will get the file with the text `% Introduction to The First Book of Moses (Genesis)`, 
another with `% Introduction to The Second Book of Moses (Exodus)` etc.

In the example, the file names are chosen so that they are generated in the current
directory. If you have prepared subdirectories in this directory corresponding to
names, it is possible to generate files directly into them, for example, write
\`\filegen {intros/intro-@@.tex}`.

To generate a list of files with the names other than the <b-mark> list  in the `books.tex` file, 
after reading in `books.tex`, define macro \`\genbooks` with your chosen set of abbreviations. 
For example, after
\begtt
\def\genbooks {Gn Ex Lv Nu Dt}
\endtt
%
the \`\filegen` command will only generate templates for the five books with the specified
abbreviations. You can also define \`\genbooks` before each \`\filegen`, in which case
you'll be able to have different book abbreviations for different file types (e.g., `intro-Gen.tex` and `notes-Gn.tex`).

\watchout 
If you work online on Overleaf, you must not forget that Overleaf does not keep the files that have been generated during \TeX/ run. This makes generating the templates a bit clumsy: after generating them (but before quitting Overleaf) you would have to download the file(s) and manually upload it (them) again. The files that you manually upload do not get deleted when you leave the project.

\sec[tricks] Tricks and Stunts  

This sections offers some inspiration for demanding users, eager to perform even greater miracles
than what average \OpBible/ users might be satisfied with.

\secc Chiasm

Serious students of the Bible probably know that some parts of it are written in form of chiasm; for example, a single verse:
\medskip
\leftline{\hskip 2em{\bf A} Many that are first}
\leftline{\hskip 3em{\bf B} shall be last;}
\leftline{\hskip 3em{\bf B'} and the last}
\leftline{\hskip 2em{\bf A'} shall be first.}
\leftline{\hskip 4em{(Matthew 19:30) } }
\medskip

\noindent or a larger portion of text:

\medskip
Life of Abraham in Genesis:

\leftline{\hskip 2em{\bf A} Background and Early Experiences (11:10--12:9)}
\leftline{\hskip 3em{\bf B} Earlier Contacts with Others (12:10--14:24)}
\leftline{\hskip 4em{\bf C} Covenant with God (15:1--17:27)}
\leftline{\hskip 3em{\bf B'} Later Contacts with Others (18:1--21:34)}
\leftline{\hskip 2em{\bf A'} Progeny and Death (22:1--25:18)}
\medskip

\noindent or, for that matter, an entire book:

\medskip
Leviticus:

\leftline{\hskip 2em{\bf A} Ritual (1--7)}
\leftline{\hskip 3em{\bf B} Priesthood (8--10)}
\leftline{\hskip 4em{\bf C} Purity (11--15)}
\leftline{\hskip 5em{\bf D} Day of Atonement (16)}
\leftline{\hskip 4em{\bf C'} Purity (17--20)}
\leftline{\hskip 3em{\bf B'} Priesthood (21--22)}
\leftline{\hskip 2em{\bf A'} Ritual (23--27)}
\medskip

The way to type such structures is rather easy.
Entire chiasm has to be enclosed inside `\begChiasm` and `\endChiasm` pair; then number of asterixes at the beginning of each new line determines the indentation.
You only have to type:

\medskip
\begtt
\begChiasm 
* Many that are first
** shall be last;
** and the last
* shall be first.
\endChiasm
\medskip
\endtt
%
and \OpBible/ will take care of the rest. If you don't want to have the boldfaced {\bf A, B, C... B', 
A'} at the beginning of the lines, type `\style q` right after `\begChiasm`. 
If you then want them back, start the new chiasm with `\begChiasm \style Q`.

%...

\secc[dirty] Formatting Tricks

This section  follows the section~\ref[fmt].
We are formatting the text of the book of Daniel, in the BBE translation, 
therefore we work inside the `fmt-BBE-Dan.tex` file.
Let's suppose you want to let the reader know which words have been added by the 
translators that are not in the original language.

In BBE,  Daniel 1:7, we read:

\medskip
\moveright 1in\vbox{\advance\hsize by -2in 
\noindent
And the captain of the unsexed servants gave them names; 
to Daniel he gave the name of Belteshazzar, 
to Hananiah the name of Shadrach, 
to Mishael the name of Meshach, 
and to Azariah the name of Abed-nego.} 
\medskip

The phrase {\em the name of} was added by the BBE translators, it is not in the 
original Hebrew Bible and you want to indicate that by a font change.
Typing `\fmtfont{1:7}{the name of}{\em}` would do the job just fine, but only 
for the very first occurrence of the phrase. In this particular case, however, 
we run into a problem because the exactly same phrase is there four times in the 
same verse, and  all in the need of the font change. The phrase that have been 
already searched for and found cannot be searched for again.

There is a way around, as mentioned in \ref[fmt].

The macro \`\fmtkeep``{<chapter-number>:<verse-number>}{<phrase>}` will help us here because it will make the first occurrence of the `<phrase>` unsearchable by hiding it inside the brackets `{}`.  
We use it repeatedly because we also need to exclude from search  the second and the third occurrences of the phrase. The second time it will disable the next first visible phrase, which is now the second one, and so forth.
\medskip
Typing 

\begtt
\fmtfont{1:7}{the name of}{\em}
\fmtkeep{1:7}{the name of}
\fmtfont{1:7}{the name of}{\em}
\fmtkeep{1:7}{the name of}
\fmtfont{1:7}{the name of}{\em}
\fmtkeep{1:7}{the name of}
\fmtfont{1:7}{the name of}{\em}
\endtt


solves the problem neatly and to everybody's satisfaction, resulting in:

\medskip
\moveright 1in\vbox{\advance\hsize by -2in 
\noindent
And the captain of the unsexed servants gave them names; 
to Daniel he gave {\em the name of} Belteshazzar, 
to Hananiah {\em the name of} Shadrach, 
to Mishael {\em the name of} Meshach, 
and to Azariah {\em the name of} Abed-nego.} 
\medskip

See the sample file of Daniel in BBE translation, verse 1:7.


\watchout
If you want to insert vertical space (e.g., `\medskip`) after the verse in which you have 
applied the font change on a word, then `\fmtins` containing `\medskip` must precede `\fmtfont` 
command. Otherwise \TeX/ will crash and you end up with the mysterious message
`You can't use \/ in vertical mode.`
In other words, use 

\begtt
\fmtins{1:7}{Abed-nego.}{\medskip}
\fmtfont{1:7}{the name of}{\em}
\endtt
%
and do not switch the order of these two lines.

%???





%
\sec[sum] Summary of basic commands and definitions

This section lists the files necessary to run OpBible, and their typical content.
\recommended
Compare the instructions below with the sample files that come as a part of the bundle. 


%I would put everything the user might need to set up in 
%Sem. If this could fit on two pages, we might recommend printing it as a cheat-sheet.

\secc Typically in the `main.tex` file

\begitems
* \`\load`: Macro package to be loaded:`\load [<macro package>]`. Example: `\load [opbible]`.
* \`\tmark`: `\def\tmark{<t-abbreviation>}`: declaration of the t-abbreviation of a Bible 
translation, e.g., BBE, RNKJV, etc. 
   Example: `\def\tmark{BBE}`.
* \`\txsfile`: `\def\txsfile {<filename mask>}`: `.txs` location declaration. 
    You can use \`\amark` or \`\bmark` in the filename mask. 
    Example: `\def\txsfile {./txs/\tmark-\bmark.txs}`.
* \`\notesfile`: `\def\notesfile {<filename mask>}`:  notes files location declaration. 
Example: 
`\def\notesfile {./notes/notes-\amark.tex}`.
* \`\introfile`: `\def\introfile {<filename mask>}`:  book introductions location 
declaration. 
Example: `\def\introfile {./intros/intro-\amark.tex}`.
* \`\articlefile`: `\def\articlefile {<filename mask>}`: article files location declaration. 
   Example: `\def\articlefile {./articles/articles-\amark.tex}`.
* \`\fmtfile`: `\def\fmtfile {<filename mask>}`:  formatting data files location declaration. 
Example: `\def\fmtfile {./fmt/fmt-\tmark-\amark.tex}`.
* \`\input`: File to be read in: `\input {<file-name>}`. Example: `\input vars.tex`.
* \`\printedbooks`: `\def\printedbooks {<list of a-marks>}` declares a list of the books, 
separated by a space:   the listed books are processed then by `\processbooks`. 
Example:\nl `\def\printedbooks {Gen Exod Lev Num Deut}`
* \`\processbooks`: instruction to process the Bible, or to be more  specific, to process the books 
listed in `\printedbooks`.
\enditems
You need to define the commands above in the main file, then
read in the files `books.tex`, `vars.tex` and finally start processing with the command
\`\processbooks`.

\secc Typically in the `books.tex` file

\begitems
* \`\BookTitle` `<a-mark> <b-mark> {<title>}`: declares  a-mark, b-mark and title for each book.
  As each individual book is processed, the  `\def\amark{<a-mark>}` and `\def\bmark{b-mark}` is 
  executed. 
  The a-mark is used in references within the Bible text, while  b-mark may be used in file names.
  Example: `\BookTitle 2Sa 2Sam {II Samuel}`.
* \`\BookException` `<a-mark> {<code>}`: before processing a book, the
  <code> is executed.
* \`\BookPre` `<a-mark> {<code>}`: after printing the introduction, before the main text of
  the declared book, <code> is executed.
* \`\BookPost` `<a-mark> {<code>}`: after printing the main text of the declared book, <code> is 
executed.
  Perhaps could be found useful for printing a reading plan but such example of this feature is not 
  implemented in this version of OpBible. 
  Nevertheless, feel free to create your own.
* \`\nochapbooks`: `\def\nochapbooks{<list>}`: list of the a-marks of the books that
  are not divided into chapters (only have one chapter). Example:\nl `\def\nochabooks {Obad Phlm 2John 3John Jude}`.
\enditems

\secc Typically in the `vars.tex` file

This file declares variant phrases for different versions of the Bible translation.

\begitems
* \`\variants` `<number>` `<list of t-abbreviations of translation variants>`: declares the number of
  translation variants and a list of \hbox{t-abbreviations}. The `<number>` must match the number of
  t-abbreviations as well as the number of parameters of the \`\vdef` and \`\ww` commands.
Example:
`\variants 6 {BBE} {Jubilee2000} {NETfree} {UKJV} {RNKJV} {Webster}`. 
  
* \`\vdef` `<phrase variants>`; declares the variants of the phrase, the first of which is
 the reference one. The phrase variants are placed in brackets `{<like this>}`.
 Example: 
 \begtt
 \vdef {He-goat}   % BBE
       {Goat}      % Jubilee2000
       {Male goat} % NETfree
       {He goat}   % UKJV
       {Goat}      % RNKJV
       {He-goat}   % Webster
\endtt      
\enditems

\secc Typically in the `notes-*.tex` file

\begitems
* \`\Note` `<chap-num>:<verse-num> {<commented phrase>} <note text terminated by a blank line>`:
  declares a note. Example:   \code{\\Note 5:12 {Belteshazzar} See <"note on" 1:7>n.}
* \`\ww` `<variants of phrase>`: must precede \`\Note`. In
  each translation variant, the following note will be bound to the phrase
  of a particular phrase according to the currently defined t-mark.
 Example:
\begtt \catcode`<=12
\ww {by the order of Belshazzar} % BBE
    {Belshazzar commanded}       % Jubilee2000
    {on Belshazzar's orders}     % NETfree
    {commanded Belshazzar}       % UKJV
    {commanded Belshazzar}       % RNKJV    
    {commanded Belshazzar}       % Webster
 \Note 5:29 {}  Belshazzar honored Daniel like Nebuchadnezzar (<2:48>),  
       but unlike Nebuchadnezzar he did not honor Daniel's God (<2:46-47>).    
\endtt
* \`\x``/<phrase>/`: prints the phrase according to the current t-mark and according to   \`\vdef` 
declaration. 
  The <phrase> parameter is the reference phrase, i.e., it must be exactly the same as the first 
  parameter of \`\vdef`.
    If no t-mark is defined or if the first t-mark from the \`\variants` list is defined, then 
  <phrase> is printed as is. In any other case (t-mark other than the very first one of the 
  \`\variants` list is defined),  <phrase> is printed as whatever is declared by \`\vdef` for that 
  particular t-mark.
  Example: `\x/He-goat/`.
* \`\putBot` `<verse number> {<title>} [<label>] (<commands>) {<code>}`:
  sets up an image/diagram at the bottom of the page containing the <verse number>.   
  Example:\nl
`\putBot 2:1 {Daniel's Visions of the Four Kingdoms} [danielsvisions] () {...}`.

* \`\putArticle`: Inserts an article, declared in the `articles-*.tex` file. 
Example:\nl `\putArticle 5:20 {Who was Darius the Mede?} [6] ()`

* \`\putCite`: Inserts a quotation on the top of a page above the Biblical text. 
Example: `\putCite 5:4 {Power corrupts; and absolute power corrupts absolutely.`\nl\null\qquad
         `\quotedby {Lord Acton}}` 




\enditems

\secc Typically in a `intro-*.tex` introduction file

%\begtt

\begitems
* \`\title`: 
After you define `\title` as something like this:
\nl
`\def\title#1{\medskip\noindent{\bf#1}\par\nobreak}`
then you can begin some paragraphs with it. 
Example:
`\title{Overview:}`, `\title{Author:}`, etc.

* \`\insertBot` `{<MapTitle>}[<label>](<params>){<data>}` inserts `<data>` at the bottom of the current page. Example
\begtt
\insertBot {Map title} [label] () {
   \inspic{map-crop.pdf}
   \putstext 10mm 25mm {Text on the map}
}
\endtt


*\`\Outline` starts the last part of the introduction text. It enables nested lists declared by `\begitems`, `\enditems` and the text is printed only to the left column of the page. The command \`\rightnote {<comment>}` can be used here; the <comment> is printed to the right column.
Example: see the end of the file `intro-Dan.tex`.

%... \TODO, add
\enditems

\secc Typically in an `articles-*.tex` file

\begitems

*\`\Article` `[<chapter-number>]` `<text of the article>`:
    Declares <text of the article> for the given <chapter-number>. The <text of the article> ends at the end of the file or by another `\Article` declaration.
    The `<chapter-number>` could be any label, unique for that particular article, but 
    as we suppose that there will most likely not be more than one article per chapter,
    it sounds logical to assign the number of the chapter where we want the article to occur.
    This also ensures that you will easily remember the article's label when you call it to appear 
    from  the `notes-*.tex` file (see above).

* \`\Cite` `<capital-letter>` `{<text of the quotation>` `\quotedby{<author of the quotation>}}`.
%`\swapCites
This is the way to declare a quotation within an article, as described in the section~\ref[cite]. 
Capital letter that identifies the article can be <A> if it is the first quotation in that article, 
then <B> if it is already the second one, etc.
After such declaration, you will probably want to make it visible somewhere. 
You have to decide where in the article it would be best to insert it, and there you type

* \`\insertCite` `A\left ` or \`\insertCite` `A\right`.
See section~\ref[cite] for more information.

\enditems

%... \TODO, complete

\secc Typically in a  `fmt-*-*.tex` file

Data formatting file (named, for example, `fmt-BBE-Gen.tex`) can contain any of the following 
commands:

\begitems
* \`\fmtpre` `{<chapter-number>:<verse-number>}{<commands>}` inserts <commands> before specified verse.
* \`\fmtadd` `{<chapter-number>:<verse-number>}{<commands>}` inserts <commands> after specified verse.
* \`\fmtins` `{<chapter-number>:<verse-number>}{<phrase>}{<commands>}` inserts commands just after the 
   <phrase> that has to exist in the specified verse.
* \`\chaptit` `{<chapter-title>}` specifies the title to go before the first verse of a chapter, to 
  be used inside `\fmtpre` as its parameter, for example, `\fmtpre{1:1}{\chaptit{CHAPTER TITLE}}`.
* \`\subtit` `{<pericope title>}` is similar to `\chaptit` except that it comes inside chapter as a 
title of just part of a chapter. However, it could be used even before the first verse of a chapter, 
usually in situations where the chapter title is to be immediately followed by a pericope title. Example:
`\fmtpre{1:1}{\chaptit{CHAPTER TITLE}\subtit{Pericope Title}}`.

\enditems
%... \TODO, complete

\secc When creating maps

A map or any sort of similar images will be always placed within some text, 
thus its commands will be called from either Introduction file or Notes file.
OpBible allows you to place text on the top of such image. The text over a map has not only the 
advantages of the notes text (like hyperlinked references, variations according to the translation, 
or renumbering verses) but also few other as well, like  placement by coordinates, text along 
curved path, partially transparent background under the text, etc., see the section~\ref[maps]. 
It makes sense to use these features if the image you use is a blank map with no characters in it.

\begitems

* \`\insertBot` `{<Map's title>}[<label>](<optional parameters>){<data>}` 
Map's title will show up in a horizontal bar above the image;
<label> serves for reference purposes as usually. 
Optional parameters can modify the dimensions of the image (e.g., `\picw=3in`) but if you are happy 
with the default setting 
(which is `\picw=\hsize`), type in empty parentheses `()`.
The last parameter <data> includes \`\inspic` `{image-file}` command followed by an optional map legend. 
The map legend is everything that will show over the image as text of any kind. 
In can include definitions like
* `\Heros \cond \setfontsize{at 9pt}\rm` to set the font;
* \`\putstext` `2mm 108mm {\vtop{\hsize6.5cm \baselineskip9pt \noindent`

  `\leftskip=3pt \rightskip=3pt   Soon after Alexander' death...}}` to type a text with partially 
  transparent background over a map.
* \`\puttext` {\everyintt={}`55mm 53mm 
{<"Dan 11:5 (`“`king of the south`”`)"_Dan 11:5>}`} to place a text that is an 
   active hyperlink at the same time;
*  `\puttext` `48mm 55mm {`\`\c``[-40/\kern1pt]{Jerusalem}}` to place a text rotated 40°; 
* `\puttext` `130mm 50mm {`\`\c``[-40/\kern4pt\pdfrotate{-1}]{ELAM}}` to place a concave or convex text.

\enditems

%... \TODO, complete

\secc When creating timelines
\begitems
*\`\putSpanText` `12:40 {<title>} [<label>] (<parameters>)` 
                 `{<the timeline itself>}` --
you can use an pre-prepared image for a timeline, in which case you would call it by 
\`\putSpanImage` instead of `\putSpanText`. Remember, however, that this will rob you of the 
possibility to have references as active hyperlinks and variations of phrases following different 
Bible versions. If you insist on having these features, it is preferable to stick with `\putSpanText`.

\noindent The timeline itself can be created by:
* \`\timeline` `430`  --     sets the  total number of years (or other units) in the timeline.
* \`\timelinewidth` `36cm` --   the width of timeline (here: 430 years = 36 cm).
* \`\arrowtext` `0..430 (\bf)` `{430 years (Exod 12:40; Gal 3:16--17)}` -- 
                         prints arrow between from..to units with the text in the middle. 
* \`\vskip` `2\l` is equal to             `\vskip 2\baselineskip`; `\l` is only shortcut for `\baselineskip`
* \`\tlput` `a 0 \rlap(\bf)`   `{Abraham received\cr promise (Gen 12:3-5,7; 15:5--6)}` --  
       prints text; 
* \`\tline` `0..430`   --      prints horizontal line from..to units;
* \`\tlines` `{0|25|60|130|215|0}` -- prints vertical short lines, numbers mean distance between them.

\enditems

%... \TODO, complete

%\recommended
%Compare these instructions with the files that come as a part of the bundle. 

\sec Generating technical documentation of \OpBible/

The detailed technical documentation is prepared. The text of this documentation is part of the file `opbible.opm` itself. You can generate a PDF from this text by the command:
\begtt
optex -jobname opbible-techdoc '\docgen opbible'
\endtt
The `opbible-techdoc.pdf` is created.
Use this command three times because the references must be correctly linked and the created Index and Table of contents need data from previous \TeX/ run.

\sec After you're done

After you finish writing your commentary, you have all the formatting done, 
you have checked all the references to make sure they are correct, 
there are no more warning messages in the log file, 
and you are quite happy about how your Study Bible looks like, you can now 
disable blue color of the 
links by typing (somewhere in the `main.tex` file) `\hyperlinks\relax\relax`.
(They will still function as hyperlinks, though, only now in `\Black` color, 
thus indistinguishable from the surrounding text.)


The printing house to which you would submit your resulting PDF should be able to add their own 
crop marks. If for some reason you want to do it yourself, you can use the macro `cropmarks.tex` which is part of \ulink[https://ctan.org/tex-archive/macros/generic/olsak-misc]{olsak-miscs} macro collection.

\vfill
\eject

\sec Index

\def\_sortinglang{en}
\begmulti 3
\typosize[9/]
\makeindex
\endmulti

\bye












































































% what's below should be in the same Overleaf project with the corresponding 00-README in the individual directories.

\secc[summa-main] Main file `main.tex`

\begtt
\load[opbible] % macros OpBible
\cslang

%\checksyntax notes-Da intro-Da articles-Da fmt-BKR-Da {} % Error tracer; when active, \processbooks is disabled (does nothing)
%\normalchapnumbers % smaller chapter number (just over first 2 lines); no big quote marks next to the quotations
%\mergednotes % more than one note to a single verse make one paragraph but at the expanse of ignoring the search phrases
%\let\notecolor=\relax % disables \Red search phrases 
\def\shadowparameter{.1}%text background transparency; {1}=solid white
%\def\townparams{
% \hhkern=.8pt % radius of the sphere
% \lwidth=.5pt % contour line thickness
% \fcolor=\Red % ring color
% \lcolor=\Black % contour line colour
%} 


%\input hebrew % Hebrew phrases are declared here
%\input greek % Greek - "-

% Variants of translation:
\def\tmark {BKR} % Bible Royal
%\def\tmark {PSP} % Pavlik's study translation
%\def\tmark {CSP} % Czech study translation
%\def\tmark {CEP} % Czech Ecumenical Translation
%\def\tmark {B21} % Bible for the 21st century
%\def\tmark {SNC} % Word for the Journey

\input {Cze-vars.tex} % Variants of translation
\input {Cze-books.tex} % Book titles and marks

\def\txsfile {sources/Cze\tmark-\bmark.txs} % Location of .txs files
\def\fmtfile {formats/fmt-Cze\tmark-\amark.tex} % Location of fmts
\def\notesfile {notes/notes-\amark.tex} % Location of notes
\def\introfile {others/intro-\amark.tex} % Location of introductions
\def\articlefile {others/articles-\amark.tex} % Location of articles

\def\printedbooks {%
   Gn Ex Lv Nu Dt Joz Sd Rt 1Sa 2Sa 1Kr 2Kr 1Pa 2Pa Ezd Neh
   Est Jb Ž Př Kaz Pís Iz Jr Pl Ez Da Oz Jl Am Abd Jon Mi
   Na Abk Sf Ag Za Mal 
   Mt Mk Lk Jn Sk Ř 1K 2K Ga Ef Fp Ko 1Te 2Te 1Tm 2Tm 
   Tt Fm Žd Jk 1Pt 2Pt 1Jn 2Jn 3Jn Ju Zj
}

\def\printedbooks{Da} 
\processbooks % Generates books declared in \printedbooks
\bye
\endtt

 

\secc[summa-intro] File `intro-*.tex`

\secc[summa-notes] File `notes-*.tex`

\begtt
%\ww {}%searched phrase of each translation
% ={}printed phrase % BKR
% {}={} % PSP
% {}={} % CSP
% {}={} % CEP
% {}={} % B21
% {}={} % SNC
\Note 1:1 {} %phrase common to all translations, e.g.,wisdom, otherwise empty group{}
            %={}%a phrase not in the Bible but printed, e.g., Vision of the four \x/selem/
        Text notes.
\endtt




\secc[summa-article] File `article-*.tex`

\secc[summa-quote] Command `\putCite`

\secc[summa-maps] Map description

\secc[summa-fmt] Format files `fmt-*-*-*.tex`

\secc[summa-vars] Translation variants file `Cze-vars.tex`






\vfill\eject

\sec Index

\def\_sortinglang{en}
\begmulti 3
\typosize[9/]
\makeindex
\endmulti

\bye