\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 {}` 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 `-.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``{}` or \`\ChapterPost``{}` 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 {} {} ... {} \endtt where `` 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 ``, 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 {} \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 ``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 s are visible in printed text when the references are used. In the second column, there are ``s, which can be the same as ``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 s are never printed in the text. The macro \`\amark` contains the `` of the currently processed book and the macro \`\bmark` includes the `` 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 ``s, not ``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 ``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 {} \BookPre {} \BookPost {} \endtt The 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 is inserted after the book files have been read but before the first verse (or introduction text) is processed. Finally, the 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 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 `#:`. 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 `` 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 , 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``{}{}` in the main file. \TeX/ will look up all occurrences of `` in each verse of `.txs` file and replace them with ``. 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{:}{} \fmtadd{:}{} \fmtins{:}{}{} \fmtfont{:}{}{} \fmtrepl{:}{}{} \fmtkeep{:}{} \endtt where 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{}` inserts as the chapter title, whereas \`\schaptit{}` 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 at the beginning of the specified verse (before the verse number which is printed in a form of a superscript). The \`\fmtadd` inserts at the end of the specified verse. Finally, \`\fmtins` inserts inside the verse after the first occurrence of the specified that must exist exactly as given in the verse. Otherwise, \TeX/ prints a warning message and inserts no 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``{:}{}{}` 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``{:}{}{}` replaces first occurrence of by . 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``{:}{}` makes first occurrence of the unsearchable. So you can apply a next `\fmt*` command to the next occurrence of the . 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``` (as indent). At the point of insertion, the line is terminated and the next line begins indented by the `` 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``{:}{}` determines the format of a particular verse. The 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. 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 : {} \endtt For example: \begtt \Note 1:2 {the temple of his god} Marduk was the chief god of the Babylonian pantheon (cf. ). \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 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 were at the beginning of the verse. You will use the notes without specified 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 , 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 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 `{}`, which in turn is followed by the `{}`, i.e., \begtt \Note : {}={} \endtt In this case, is searched for in the core text, but in the actual note, 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 :, 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 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 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 `:`, 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 : {} [