diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/bibleref/bibleref-manual.tex | 245 |
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'. |