summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex245
1 files changed, 180 insertions, 65 deletions
diff --git a/Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex b/Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex
index abd811656ac..ac507246864 100644
--- a/Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex
+++ b/Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex
@@ -1,57 +1,18 @@
-%%
-%% This is file `bibleref-manual.tex',
-%% generated with the docstrip utility.
-%%
-%% The original source files were:
-%%
-%% bibleref.dtx (with options: `bibleref-manual.tex,package')
-%%
-%% bibleref.dtx
-%% Copyright 2010 Nicola Talbot
-%%
-%% This work may be distributed and/or modified under the
-%% conditions of the LaTeX Project Public License, either version 1.3
-%% of this license of (at your option) any later version.
-%% The latest version of this license is in
-%% http://www.latex-project.org/lppl.txt
-%% and version 1.3 or later is part of all distributions of LaTeX
-%% version 2005/12/01 or later.
-%%
-%% This work has the LPPL maintenance status `maintained'.
-%%
-%% The Current Maintainer of this work is Nicola Talbot.
-%%
-%% This work consists of the files bibleref.dtx and bibleref.ins and the derived files bibleref.sty, bibleref-manual.tex, sample-multind.tex, sample.tex, bibleref.perl.
-%%
-%% \CharacterTable
-%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
-%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
-%% Digits \0\1\2\3\4\5\6\7\8\9
-%% Exclamation \! Double quote \" Hash (number) \#
-%% Dollar \$ Percent \% Ampersand \&
-%% Acute accent \' Left paren \( Right paren \)
-%% Asterisk \* Plus \+ Comma \,
-%% Minus \- Point \. Solidus \/
-%% Colon \: Semicolon \; Less than \<
-%% Equals \= Greater than \> Question mark \?
-%% Commercial at \@ Left bracket \[ Backslash \\
-%% Right bracket \] Circumflex \^ Underscore \_
-%% Grave accent \` Left brace \{ Vertical bar \|
-%% Right brace \} Tilde \~}
\documentclass{nlctdoc}
\usepackage{bibleref}
\usepackage[colorlinks,bookmarks,pdfauthor={Nicola L.C. Talbot},
hyperindex=false,
- pdftitle={bibleref.sty: a LaTeX package for
+ pdftitle={bibleref.sty: a LaTeX package for
typesetting bible references}]{hyperref}
\usepackage{creatdtx}
-\CheckSum{1893}
+\CheckSum{2503}
+\OnlyDescription
\begin{document}
-\title{bibleref.sty v1.13:
+\title{bibleref.sty v1.14:
a \LaTeXe\ package for typesetting bible references}
\author{Nicola Talbot\\[10pt]
School of Computing Sciences\\
@@ -59,7 +20,7 @@ University of East Anglia\\
Norwich. Norfolk. NR4 7TJ.\\
United Kingdom\\
\url{http://theoval.cmp.uea.ac.uk/~nlct/}}
-\date{2010-07-07}
+\date{2011-01-19}
\maketitle
\tableofcontents
@@ -72,14 +33,22 @@ parts of the bible.
\begin{definition}[\DescribeMacro{\bibleverse}]
\cs{bibleverse}\marg{book title}\texttt(\meta{chapter}\texttt{:}\meta{verse(s)}\texttt)
\end{definition}
-This command can be used to cite a bible book, chapter or verse
+This command can be used to cite a bible book, chapter or verse
or range of chapters or verses.
+\begin{important}
+Be careful if you use \sty{bibleref} with \sty{babel} as some of
+\styfmt{babel}'s language options make the colon character active,
+which will cause a problem for \cs{bibleverse} (and \ics{ibibleverse},
+described later). Check the \styfmt{babel} documentation to find out
+how to make the colon non-active.
+\end{important}
+
The book title, \meta{book title}, may be given either as the
full title (e.g.\ \texttt{Matthew}) or as an abbreviation (e.g.\
\texttt{Mt} or \texttt{Matt}), most standard abbreviations are
recognised. Books with multiple parts should be preceded by the
-book number in uppercase roman numerals. For example, the second
+book number in uppercase Roman numerals. For example, the second
book of Kings should be entered as \verb|\bibleverse{IIKings}|
You may have any number, or zero, sets of parenthesis
@@ -100,6 +69,11 @@ A range of verses spanning more than one chapter can
be entered as \texttt(\meta{ch}\texttt:\meta{v}\texttt{)-(}\meta
{ch}\texttt:\meta{v}\texttt)
+If there is no verse, but there are multiple chapters or chapter
+ranges, these may be specified in the \meta{chapter} part, using a
+comma to separate individual chapters and a hyphen to separate
+ranges. Note that you still need a colon at the end of the list.
+
Examples:
\begin{center}
\begin{tabular}{ll}
@@ -112,11 +86,12 @@ Examples:
\verb|\bibleverse{Ex}(15:)(17:)(20:)| & \bibleverse{Ex}(15:)(17:)(20:)\\
\verb|\bibleverse{Rev}(1:2,5,7-9,11)| & \bibleverse{Rev}(1:2,5,7-9,11)\\
\verb|\bibleverse{IChronicles}(1:3)-(2:7)| &
-\bibleverse{IChronicles}(1:3)-(2:7)
+\bibleverse{IChronicles}(1:3)-(2:7)\\
+\verb|\bibleverse{Luke}(1,4-5,8:)| &\bibleverse{Luke}(1,4-5,8:)
\end{tabular}
\end{center}
-The style of the reference can be specified either by
+The style of the reference can be specified either by
package option or as the argument to the command
\begin{definition}[\DescribeMacro{\biblerefstyle}]
\cs{biblerefstyle}\marg{style}
@@ -124,7 +99,7 @@ package option or as the argument to the command
Styles are listed in Table~\ref{tab:styles}.
\begin{table}[tbh]
-\caption{Bible Citation Styles (can be used as package option or in the argument to
+\caption{Bible Citation Styles (can be used as package option or in the argument to
\cs{biblerefstyle})}
\label{tab:styles}
\vspace{10pt}
@@ -143,15 +118,15 @@ text & \biblerefstyle{text}\bibleverse{IICor}(12:1-5)
\end{center}
\end{table}
-You can change the name of a book using
+You can change the name of a book using
\begin{definition}[\DescribeMacro{\setbooktitle}]
\cs{setbooktitle}\marg{name}\marg{new title}
\end{definition}
Note that \meta{name} must be the full name, not the
abbreviated name of the book. For example, to change
-Revelation to Apoc, do
+Revelation to Apoc, do
\verb|\setbookname{Revelation}{Apoc}|
-(\textbf{Note} that you shouldn't do
+(\textbf{Note} that you shouldn't do
\verb|\setbookname{Rev}{Apoc}|)
If you want a different title for a book depending on whether it's
@@ -160,7 +135,7 @@ index version using:
\begin{definition}[\DescribeMacro{\setindexbooktitle}]
\cs{setindexbooktitle}\marg{name}\marg{title}
\end{definition}
-In this case, \meta{name} should be the name you'll use in
+In this case, \meta{name} should be the name you'll use in
\cs{ibibleverse}. For example, if you do:
\begin{verbatim}
\setbooktitle{Psalms}{Psalm}
@@ -188,7 +163,7 @@ You can define a new style using the command
where \meta{commands} are
the commands needed to modify the citation style.
-Example:
+Example:
This new style is based on the \qt{default} style, but
has verses in lower case Roman numerals, and redefines
\qt{Revelation} as \qt{Apocalypse}.
@@ -201,19 +176,22 @@ has verses in lower case Roman numerals, and redefines
\end{verbatim}
Note the use of \verb|##1| instead of \verb|#1|.
+If you want to distribute a new style, see
+section~\ref{sec:distnewstyles}.
+
\section{Indexing Bible References}
\begin{definition}[\DescribeMacro{\ibibleverse}]
-\cs{ibibleverse}\marg{book title}\texttt(\marg{chapter}\texttt{:}\meta{verse(s)}\texttt)
+\cs{ibibleverse}\oarg{format}\marg{book title}\texttt(\marg{chapter}\texttt{:}\meta{verse(s)}\texttt)
\end{definition}
This does the same as \cs{bibleverse}
-but also adds an index entry (provided you have used
-\cs{makeindex} in the preamble.) The default page number
-format is given by the command
+but also adds an index entry (provided you have used
+\cs{makeindex} in the preamble.) The default page number
+format is given by the command
\begin{definition}[\DescribeMacro{\bvidxpgformat}]
\cs{bvidxpgformat}
\end{definition}
-This is \texttt{textrm} by default, but can be redefined. To
+This is \texttt{textrm} by default, but can be redefined. To
override the page number format for a particular entry you can
use the optional argument to \cs{ibibleverse}. For example:
\begin{verbatim}
@@ -221,6 +199,19 @@ use the optional argument to \cs{ibibleverse}. For example:
\end{verbatim}
(Note there is no backslash.)
+\begin{definition}[\DescribeMacro{\ibiblechvs}]
+\cs{ibiblechvs}\oarg{format}\marg{book title}\texttt(\marg{chapter}\texttt{:}\meta{verse(s)}\texttt)
+\end{definition}
+This is similar to \cs{ibibleverse} except that it doesn't display
+the book name in the text. The reference is indexed under the book
+title in the same way as \cs{ibibleverse}.
+
+\begin{definition}[\DescribeMacro{\ibiblevs}]
+\cs{ibiblevs}\oarg{format}\marg{book title}\texttt(\marg{chapter}\texttt{:}\meta{verse(s)}\texttt)
+\end{definition}
+This is similar to \cs{ibiblechvs} except that it only displays the
+verse(s) in the text.
+
You may need to create your own custom \app{makeindex} style file
as the default uses a comma and space to separate the item from
the page number, which may cause confusion. For example, you
@@ -233,6 +224,67 @@ delim_2 "\\dotfill "
\end{verbatim}
See the \app{makeindex} documentation for further details.
+\subsection{Index Categories}
+
+You may prefer to index the bible reference under a category with
+the book title as a sub item of that category. This can be achieved
+using:
+\begin{definition}[\DescribeMacro{\biblerefcategory}]
+\cs{biblerefcategory}\oarg{sort key}\marg{category title}
+\end{definition}
+The optional argument is the sort key to be used by
+\app{makeindex} or \app{xindy}. If omitted \meta{category title} is
+used.
+
+Note that \ics{ibibleverse}, \ics{ibiblechvs} and \ics{ibiblevs}
+use the category that is currently set. If you need to keep
+switching categories, you may find it easier to define a shortcut
+command. For example, suppose you're discussing the differences
+between the King James and the New Jerusalem versions, you could
+define the following:
+\begin{verbatim}
+\newcommand{\kjref}{\biblerefcategory{King James}\ibibleverse}
+\newcommand{\njref}{\biblerefcategory{New Jerusalem}\ibibleverse}
+\end{verbatim}
+You can now use \cs{kjref} and \cs{njref} in the same way that you
+would use \cs{ibibleverse}
+
+You can disable the category by setting it to nothing:
+\begin{verbatim}
+\biblerefcategory{}
+\end{verbatim}
+
+\subsection{The \sty{bibleref-xidx} Package}
+
+The \sty{bibleref} package comes with a supplementary package
+\sty{bibleref-xidx} that modifies the way bible references are added to
+the index. With no package options, i.e., just
+\begin{verbatim}
+\usepackage{bibleref-xidx}
+\end{verbatim}
+the verses will appear as sub-items of the chapters. Note that a
+verse range will be considered a single item so, for example,
+\begin{verbatim}
+\ibibleverse{Ex}(9:1)
+\ibibleverse{Ex}(9:4)
+\ibibleverse{Ex}(9:1-4)
+\end{verbatim}
+will occur as three separate entries under Exodus chapter~9.
+Also note that \verb|(9-14:)| and \verb|(9:)-(14:)| will be treated
+differently.
+
+The \sty{bibleref-xidx} package can be loaded with the following options:
+\begin{description}
+\item[\pkgopt{noverses}] Don't show the verses in the index.
+\item[\pkgopt{verses}] Show the verses (and chapters) in the index
+(default).
+\item[\pkgopt{nochapters}] Don't show the chapters (and verses) in the
+index.
+\item[\pkgopt{chapters}] Show the chapters in the index (default).
+\end{description}
+All other package options will be passed to the \sty{bibleref}
+package, which \sty{bibleref-xidx} automatically loads.
+
\subsection{Separate Scripture Index}
If you want a separate index for bible verses, in addition to
@@ -287,7 +339,7 @@ For example, in the preamble:
When you run \app{makeindex}, the references will now be sorted
in numerical order.
-If you want to subdivide the index into, say, old and new
+If you want to subdivide the index into, say, old and new
testament, you can add this to the mapping. For example:
\begin{verbatim}
\biblerefmap{Genesis}{1@Old Testament!01}
@@ -301,16 +353,79 @@ testament, you can add this to the mapping. For example:
...
\end{verbatim}
+\section{Distributing New Styles}
+\label{sec:distnewstyles}
+
+If you want a new bible reference style (or translation) publicly
+available, then it's a good idea to upload it to CTAN
+(\url{www.ctan.org}). If you've never done this before, you might
+find it a bit daunting, so here are a few pointers.
+
+I suggest that you give the name of your new package the prefix \texttt{bibleref-} as
+then it will appear close to \sty{bibleref} in the alphabetical list
+in the catalogue. Suppose your new style is called
+``mystyle''\footnote{Choose a more descriptive name than this.},
+then create a file called \texttt{bibleref-mystyle.sty}. At the
+start of the file, do:
+\begin{verbatim}
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{bibleref-mystyle}[2011/01/19 v1.0 Bible reference
+style conforming to something or other]
+\end{verbatim}
+(Change the date and the brief description in the line above to
+something more appropriate.) Next you need to load \sty{bibleref}:
+\begin{verbatim}
+\RequirePackage{bibleref}
+\end{verbatim}
+Now do the new style stuff (or redefine styles to provide
+translations):
+\begin{verbatim}
+\newbiblerefstyle{mystyle}{%
+\biblerefstyle{default}%
+\renewcommand{\BRversestyle}[1]{\romannumeral##1}%
+\setbooktitle{Revelation}{Apocalypse}%
+}
+\end{verbatim}
+(Again change the above to whatever is appropriate.) Put any new
+book definitions that your style may require, for example:
+\begin{verbatim}
+\addbiblebook{Susanna}{Story of Susanna}
+\end{verbatim}
+and add any \cs{biblerefmap} commands that are required. Then set
+your new style as the current style, if appropriate:
+\begin{verbatim}
+\biblerefstyle{mystyle}
+\end{verbatim}
+On the last line of the file add:
+\begin{verbatim}
+\endinput
+\end{verbatim}
+
+Next you need to create a file called ``README'' that contains some
+information about your new package, including what license you want
+to distribute it under. (If you don't know anything about licenses,
+I recommend you choose the \LaTeX\ Project Public License, LPPL.)
+
+It's worth adding a sample file or a little bit of documentation
+that illustrates how the references appear.
+
+Put your .sty file, README file and samples or documentation into a
+zip archive. You're now ready to upload it. There are several upload
+pages. The main one is at \url{http://www.ctan.org/upload.html}.
+The name of your contribution is the name of your package
+(``bibleref-mystyle'' in this example). Remember to put your name
+and email in the relevant input boxes. Sometime after you've
+uploaded your zip file, you'll get a copy of the announcement from
+one of the CTAN maintainers. It usually takes a day to establish
+itself. After that people can download and use it.
+
\section{Acknowledgements}
-Many thanks to all the useful comments from comp.text.tex,
+Many thanks to all the useful comments from comp.text.tex,
especially from Jesse~Billett, Brooks~Moses and Ulrich~M.~Schwarz.
-\StopEventually{\phantomsection
+\StopEventually{\clearpage\phantomsection
\addcontentsline{toc}{section}{Index}
\PrintIndex
}
\end{document}
-\endinput
-%%
-%% End of file `bibleref-manual.tex'.