From f9ba1f4431124f48769a2666d5d9ec921345ca71 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 9 Jan 2006 00:43:17 +0000 Subject: doc 2 git-svn-id: svn://tug.org/texlive/trunk@78 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/eplain/base/AUTHORS | 12 + Master/texmf-dist/doc/eplain/base/COPYING | 340 ++ Master/texmf-dist/doc/eplain/base/ChangeLog | 1750 +++++++ Master/texmf-dist/doc/eplain/base/INSTALL | 51 + Master/texmf-dist/doc/eplain/base/Makefile | 97 + Master/texmf-dist/doc/eplain/base/NEWS | 87 + Master/texmf-dist/doc/eplain/base/PROJECTS | 18 + Master/texmf-dist/doc/eplain/base/README | 50 + Master/texmf-dist/doc/eplain/base/arrow.texi | 781 +++ Master/texmf-dist/doc/eplain/base/btxdoc.bib | 90 + Master/texmf-dist/doc/eplain/base/btxdoc.tex | 1117 ++++ Master/texmf-dist/doc/eplain/base/csindex.texi | 6 + Master/texmf-dist/doc/eplain/base/eplain.html | 6644 ++++++++++++++++++++++++ Master/texmf-dist/doc/eplain/base/eplain.pdf | Bin 0 -> 670226 bytes Master/texmf-dist/doc/eplain/base/eplain.texi | 228 + Master/texmf-dist/doc/eplain/base/hlink.texi | 1860 +++++++ Master/texmf-dist/doc/eplain/base/index.texi | 7 + Master/texmf-dist/doc/eplain/base/install.texi | 65 + Master/texmf-dist/doc/eplain/base/intro.texi | 71 + Master/texmf-dist/doc/eplain/base/invoke.texi | 144 + Master/texmf-dist/doc/eplain/base/progdef.texi | 768 +++ Master/texmf-dist/doc/eplain/base/userdef.texi | 2538 +++++++++ 22 files changed, 16724 insertions(+) create mode 100644 Master/texmf-dist/doc/eplain/base/AUTHORS create mode 100644 Master/texmf-dist/doc/eplain/base/COPYING create mode 100644 Master/texmf-dist/doc/eplain/base/ChangeLog create mode 100644 Master/texmf-dist/doc/eplain/base/INSTALL create mode 100644 Master/texmf-dist/doc/eplain/base/Makefile create mode 100644 Master/texmf-dist/doc/eplain/base/NEWS create mode 100644 Master/texmf-dist/doc/eplain/base/PROJECTS create mode 100644 Master/texmf-dist/doc/eplain/base/README create mode 100644 Master/texmf-dist/doc/eplain/base/arrow.texi create mode 100644 Master/texmf-dist/doc/eplain/base/btxdoc.bib create mode 100644 Master/texmf-dist/doc/eplain/base/btxdoc.tex create mode 100644 Master/texmf-dist/doc/eplain/base/csindex.texi create mode 100644 Master/texmf-dist/doc/eplain/base/eplain.html create mode 100644 Master/texmf-dist/doc/eplain/base/eplain.pdf create mode 100644 Master/texmf-dist/doc/eplain/base/eplain.texi create mode 100644 Master/texmf-dist/doc/eplain/base/hlink.texi create mode 100644 Master/texmf-dist/doc/eplain/base/index.texi create mode 100644 Master/texmf-dist/doc/eplain/base/install.texi create mode 100644 Master/texmf-dist/doc/eplain/base/intro.texi create mode 100644 Master/texmf-dist/doc/eplain/base/invoke.texi create mode 100644 Master/texmf-dist/doc/eplain/base/progdef.texi create mode 100644 Master/texmf-dist/doc/eplain/base/userdef.texi (limited to 'Master/texmf-dist/doc/eplain') diff --git a/Master/texmf-dist/doc/eplain/base/AUTHORS b/Master/texmf-dist/doc/eplain/base/AUTHORS new file mode 100644 index 00000000000..b44969727ac --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/AUTHORS @@ -0,0 +1,12 @@ +Eplain was originally written mostly by Karl Berry. Some ideas were +suggested by Paul Abrahams, who also wrote a few of the macros. Other +macros are based on ones in The TeXbook. + +David Guichard and Adam Lewenberg improved the multicolumn macros. +Stepan Kasal has contributed several patches. +Oleg Katsitadze added the hyperlink capabilities to Eplain. +Oren Patashnik has worked tirelessly on improving the BibTeX macros. +Heiko Oberdiek wrote ifpdf.sty. +Steven Smith wrote the commutative diagram macros. +Philip Taylor wrote path.sty starting from an initial macro by Nelson Beebe. +Nelson also collected the texnames.sty which Eplain incorporates. diff --git a/Master/texmf-dist/doc/eplain/base/COPYING b/Master/texmf-dist/doc/eplain/base/COPYING new file mode 100644 index 00000000000..3912109b5cd --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/COPYING @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) year name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/Master/texmf-dist/doc/eplain/base/ChangeLog b/Master/texmf-dist/doc/eplain/base/ChangeLog new file mode 100644 index 00000000000..8b875392f07 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/ChangeLog @@ -0,0 +1,1750 @@ +2005-09-20 Oleg Katsitadze + + * doc/eplain.texi, doc/hlink.texi: New documentation for hyperlinks. + + * doc/userdef.texi: + Added references to implicit hyperlink subsections. Punctuation + corrections by Karl Berry. + + * doc/progdef.texi (Page list and page range parsers): New section. + + * test/example.eps: New file (from PSfrag). + + * test/dvipdfm.tex, test/hlcite.tex, test/hlfoot.tex, test/hlidx.tex, test/hlink.tex, test/pdftex.tex, test/usepackage.tex: + Updated to the changes. + + * NEWS: Updated for the upcoming release 3.0. + + * eplain.tex, xeplain.tex: + Added color support for hyperlinks. Completely reworked hyperlink + option setting (added \hl[dest]{type,opts}). Renamed `uri' link + types to `url'. + +2005-09-19 Karl Berry + + * AUTHORS: alphabetize + +2005-09-15 Oleg Katsitadze + + * doc/userdef.texi (Environment for loading packages): + Changed @emph{preamble} to @dfn{preamble}. + + * doc/intro.texi, doc/userdef.texi: + Replaced a bunch of @w{foo bar} with foo@tie{}bar. + +2005-09-11 Oleg Katsitadze + + * test/cite.tex, test/xampl.tex: Removed \mbox definitions. + +2005-09-07 Karl Berry + + * doc/invoke.texi: pxref in parens + +2005-09-07 Oleg Katsitadze + + * doc/invoke.texi: + Added ifpdf.sty and path.sty to the list of incorporated files. + Added reference to texi2dvi. + + * doc/userdef.texi (Citations): (Indexing): Added references to texi2dvi. + +2005-09-03 Karl Berry + + * doc/invoke.texi: missing punct + +2005-08-30 Oleg Katsitadze + + * doc/userdef.texi: + Changed paths on CTAN hosts to actual links on www.ctan.org + (Packages known to work): Added reference to \begin{picture} and + \end{picture} + + * doc/intro.texi: + Changed La@TeX{} to @LaTeX{}. Updated mailing list addresses. + + * doc/arrow.texi: Changed La@TeX{} to @LaTeX{}. + + * doc/eplain.texi, doc/userdef.texi (Equation references): + Added doc on referring to empty labels. (Loading LaTeX packages): + New section. + + * test/usepackage.tex: New file. + + * eplain.tex, xeplain.tex: Added \@inmatherr needed by autopict.sty + +2005-08-29 Oleg Katsitadze + + * eplain.tex, xeplain.tex: Added support for LaTeX packages. + +2005-08-25 Oleg Katsitadze + + * doc/progdef.texi (Category codes): Corrections to the new doc + on \makeat{letter,other} (thanks to Karl Berry, as always). + + * doc/progdef.texi, doc/eplain.info, doc/eplain.pdf (Category codes): + Added doc on \makeatletter and \makeatother. + + * xeplain.tex: Added \makeatletter and \makeatother. + +2005-08-23 Oleg Katsitadze + + * doc/eplain.info, doc/eplain.pdf, doc/progdef.texi (Auxiliary files): + Added doc on optional arg to \testfileexistence. (User-defined + environments): Removed spurious indentation. + +2005-08-21 Oleg Katsitadze + + * README: Added description of util dir. + + * doc/eplain.info, doc/eplain.pdf, doc/userdef.texi (Page + references): Updated. (Modifying index entries): Updated. + (Customizing indexing): Added docs on customizing see entries and + on trimsee. + + * util/trimsee: Added --help and -v|--version options. + + * xeplain.tex, eplain.tex: Added italics correction to + \indexsee[also] (thanks to Dan Luecking ), + downcased See. + +2005-08-20 Oleg Katsitadze + + * Makefile: Added util and scripts. + + * util/idxuniq, util/trimsee: New file. + +2005-08-19 Karl Berry + + * btxmac.tex: simplify license to be like plain.tex + +2005-08-18 Oleg Katsitadze + + * doc/eplain.pdf, doc/eplain.info, doc/eplain.texi, doc/userdef.texi (Equation references): + Made into section. (Checking for pdfTeX...): New section (documents ifpdf.sty). + +2005-08-17 Oleg Katsitadze + + * Makefile, doc/Makefile: Rearranged. + + * manifest, tarchive: Removed (Makefile now does the packaging). + + * MANIFESTO: Removed. + +2005-08-15 Oleg Katsitadze + + * eplain.tex, xeplain.tex: Got rid of the homegrown \ifpdf. + + * xeplain.tex, AUTHORS, eplain.tex, manifest, merge: + Added ifpdf.sty to Eplain. + + * ifpdf.sty: New file. + + * manifest: Removed intermediate doc/eplain.??s and multiple info + files. + +2005-08-15 Oleg Katsitadze , Karl Berry + + * README: Updated; authorship info moved to AUTHORS. + +2005-08-15 Oleg Katsitadze + + * doc/Makefile (distclean): Do not delete eplain.pdf (it is now + part of distro). (maintainer-clean): Delete eplain.pdf. + + * doc/eplain.kys, doc/eplain.pgs, doc/eplain.tps, doc/eplain.vrs: + Removed. + + * AUTHORS: New file. + +2005-08-15 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2005-08-15 Oleg Katsitadze + + * manifest: Removed doc/*.t2p files (we don't use tex2page anymore). + + * doc/eplain.t2p, doc/btxdoc.t2p, doc/texinfo.t2p: Removed (we + don't use tex2page anymore). + + * manifest: Include .mst file(s) from test/ in tarball. + + * test/dvipdfm.tex, test/hlcite.tex, test/hlfoot.tex, test/hlidx.mst, test/hlidx.tex, test/hlink.tex, test/pdftex.tex: + New test files for hyperlinks. + + * btxmac.tex: Changes required to support hyperlinks in bibliography. + + * xeplain.tex: Added hyperlink support. + +2005-08-14 Karl Berry + + * doc/.cvsignore, doc/eplain.info: clean + + * doc/Makefile: eplain only + + * doc/arrow.texi, doc/eplain.pdf, doc/eplain.texi, doc/gpl.texi, doc/index.texi, doc/install.texi, doc/intro.texi, doc/invoke.texi, doc/progdef.texi, doc/userdef.texi: + make most of the manual public domain + +2005-08-14 Oleg Katsitadze + + * doc/userdef.texi (Indexing): dropped reference to ftp.math.utah.edu + +2005-08-13 Oleg Katsitadze + + * doc/eplain.texi Removed pagesize specifications. (@menu): + Corrected nodes, added detailed node listing for Indexing. + + * doc/userdef.texi (Indexing): Updated stale link to MakeIndex on + ftp.math.utah.edu (@menu): Changed tabs to spaces in Indexing + node. (Indexing): changed references to MakeIndex from @xref to + @url + + * doc/Makefile (../INSTALL): Adjusted sed command to the new + output from makeinfo (old one resulted in empty ../INSTALL). + + * ChangeLog: Merged with doc/ChangeLog (old doc entries at the bottom). + + * doc/ChangeLog: Removed (merged with ChangeLog). + +2005-08-13 Karl Berry + + * doc/texinfo.tex: update from texinfo + + * doc/progdef.texi: typo + + * doc/.cvsignore, doc/eplain.cps, doc/eplain.fns, doc/eplain.info-1, doc/eplain.info-2, doc/eplain.info-3, doc/eplain.info-4, doc/texinfo.tex: + omit intermediate files and delete old info files from repository + +2005-08-13 Oleg Katsitadze + + * arrow.tex, xeplain.tex: Header update. + + * COPYING: Added GPL v.2 for arrow.tex + + * ChangeLog, MANIFESTO, Makefile, NEWS, PROJECTS, README, add-date, add-version, fix-checksum, merge, tarchive, test/allref.tex, test/boxes.tex, test/boxit.tex, test/catcode.tex, test/center.tex, test/cite.bib, test/cite.tex, test/citeall.tex, test/citealph.tex, test/citeapa.tex, test/citebegin.tex, test/citecust.tex, test/citenote.tex, test/citex.tex, test/colfootn.tex, test/colrule.tex, test/column.tex, test/column2.tex, test/column3.tex, test/commdiags.tex, test/contents.tex, test/displine.tex, test/double.tex, test/double2.tex, test/ecommdiag.tex, test/emergncy.tex, test/env.tex, test/eqdef.tex, test/eqref.tex, test/filexist.tex, test/flynn.tex, test/footnote.tex, test/frac.tex, test/gcol.tex, test/ian.tex, test/index.tex, test/jan.tex, test/justify.tex, test/knuth.bib, test/label.tex, test/latexcite.tex, test/liang.tex, test/list.tex, test/listing.tex, test/logo.tex, test/loop.tex, test/loopnext.tex, test/mag.tex, test/makecol.tex, test/margin.tex, test/matrix.tex, test/mdisplay.tex, test/names.tex, test/noarrow.tex, test/nobib.tex, test/nonouter.tex, test/optional.tex, test/outer.tex, test/page.tex, test/path.tex, test/pcol.tex, test/psfont.map, test/rex.tex, test/rule.tex, test/sidx.tex, test/subdef.tex, test/tenenb.tex, test/tenenb2.tex, test/test.tex, test/time.tex, test/truemarg.tex, test/uscore.bib, test/uscore.tex, test/verb2.tex, test/verbatim.tex, test/vlach.tex, test/whitespc.tex, test/xampl.tex, test/xref.tex: + Added "public domain" note. + + * test/nagflm.tex, test/nhm.style, test/nhm.tex, test/tables.tex: + Removed (non-public domain/outdated). + +2005-08-12 Karl Berry + + * xeplain.tex: header updates + +2005-08-12 Oleg Katsitadze + + * Makefile (pdf): New target. + (html): No need for eplain.html, use html instead. + (info): Bug correction, there is no info dir. + (btxdoc): New target. + + * 00Description: Removed. + +2005-08-12 Karl Berry + + * CVSROOT/checkoutlist, CVSROOT/commitinfo, CVSROOT/config, CVSROOT/cvswrappers, CVSROOT/editinfo, CVSROOT/loginfo, CVSROOT/modules, CVSROOT/notify, CVSROOT/rcsinfo, CVSROOT/taginfo, CVSROOT/verifymsg: + remove dup CVSROOT + +2005-08-12 Stepan Kasal + + * xeplain.tex (^^L): Remove the redefinition. + (\@setuplisting): Fix the def in the case that ^^L is not + active. + + * xeplain.tex (\readcontentsfile): Do not open toc file for + writing, to allow multiple contents + +2005-08-06 Oleg Katsitadze + + * Imported sources into CVS on sarovar.org + (http://sarovar.org/projects/eplain) + +2004-09-05 + + * Version 2.8.4 + +2004-08-31 Oleg Katsitadze + + * xeplain.tex: \indexproofunbox: add \nointerlineskip + + * xeplain.tex: \@idxwrite: Add \allowhyphens when under + \indexproofing, otherwise `infinitesimal' in + \sidx{Infinitesimal}infinitesimal won't be hyphenated. + +2004-08-31 Stepan Kasal + + * xeplain.tex: \def\endcolumns{\singlecolumn} instead of \let... + + * xeplain.tex: \makecolumns. Correct calculation of + items-per-column + +2004-07-26 Stepan Kasal , Karl Berry + + * Version 2.8.3 + * README: Fix URL + +2004-07-26 Stepan Kasal + + * xeplain.tex (\printitem): Add \nobreak before \vskip-\parskip and + (implicit) \vskip\parskip, so that a page break cannot appear + here, between the indexing \write at the start of the item. + +2004-02-28 + + * Version 2.8.2 + * Updated texnames.sty, version 1.10 + +2003-12-27 Stepan Kasal + + * xeplain.tex (\@column): Make sure there is enough space before + we start columned output. + (\@col@minlines, \@ejectpartialpenalty): New constants. + (\@columnhsize): Removed. + (\@setuplisting, \@endcolumns): Use \break instead of \eject, + when we are sure TeX is in vertical mode. + +Tue Jul 15 xx:xx:xx 2003 Dorai Sitaram + + * \setpropertyglobal, from + Oleg Katsitadze + +Mon Jan 30 xx:xx:xx 2001 Dorai Sitaram + + * packaged for CTAN + +Sat Nov 11 20:00:00 2000 Dorai Sitaram + + * Version 2.8.1 + + * \leftdisplays was not allowing pagebreaks + inside \eqalignno. Bug reported by Ludger Hentschel + . Fixed by + Donald Arsenau . + + * doc/btxdoc.bib included alongside doc/btxdoc.tex + +Sat Sep 2 13:20:00 2000 Dorai Sitaram + + * Version 2.8 + +Sun May 7 09:40:00 2000 Dorai Sitaram + + * Fixed problem where Eplain's redefinition of \iterate + was causing nameclash of \next in a TeXdraw macro. + Suggested by TeXdraw author Peter Kabal + . + +Sat Apr 9 00:17:00 2000 Adam Lewenberg + + * xeplain.tex: Fixed problem introduced when double column uneven + bug was `fixed'. + +Sun Apr 25 22:30:00 1999 Adam Lewenberg + + * doc/progdef.texi: Added a section on user-defined environments + to progdef.texi and fixed a few typos in documentation. Suggested + by Paul Abrahams. + +Thu May 14 11:30:00 1998 Adam Lewenberg + + * xeplain.tex: Changed \columnfill after suggestion of + Helmut Jarausch . + +Wed Dec 5 09:10:00 1997 Adam Lewenberg + + * Version 2.7. + + * xeplain.tex: Added the control sequence \gutterbox as a hook + to add arbitrary vertical material between columns in + multi-column mode. + +Wed Mar 26 07:17:00 1997 Adam Lewenberg + + * xeplain.tex: Moved an \obeywhitespace to the end of the + definition of \verbatim to remove spurious space. + Suggested by Dorai Sitaram. + +Wed Jan 28 08:00:00 1997 Adam Lewenberg + + * xeplain.tex: Added \def\@emptymarkA{\@emptymarkB} so that + \ifempty\undefined is false. Suggested by Stanislav Brabec. + +Sat Oct 5 18:11:00 1996 Adam Lewenberg + + * xeplain.tex: Changed a line in the definition of \@fineqdefn + to remove a \noexpand which seemed to be causing a problem + with \eqdef. + +Tue Sep 24 10:25:00 1996 Adam Lewenberg + + * xeplain.tex: Added some code to multiple columns so that + when switching from multi- to single-columns the last line or + so does not get lost. Let's hope it works; added a \newif. + +Wed Apr 1 10:11:00 1996 Adam Lewenberg + + * arrow.tex: changed \smash to \smash@@ (a synonym for plain's + smash) so that arrow.tex works with amstex. + + * xeplain.tex: Put a test at the start so that eplain.tex is loaded + only once. + + * xeplain.tex: changed -1in to -1truein in margin macros; + Macros affected: + \@finishtopmargin + \@finishleftmargin + \@computebottommargin + \@computerightmargin + \indexsetmargins. + Also, initialize \paperheight to 11truein and \paperwidth to + 8.5truein when \mag is not 1000. + + These changes forced a redefinition of \magnification in the event + that \magnification is called AFTER eplain.tex is \input (in + particular, when \magnification is used with an eplain .fmt). + + * xeplain.tex: changed {toc} to {#1} in the definition of + \readcontentsfile to allow more general use. + + * merge: the merge script improperly replaced "xeplain" by "eplain" + in too many places. + +Mon Nov 13 14:14:28 1995 Karl Berry + + * btxmac.tex: Update for Oren's new 0.99k. + +Tue Mar 14 11:36:55 1995 Karl Berry + + * xeplain.tex: Doc fix. + +Sat Apr 30 05:58:31 1994 Karl Berry (karl@cs.umb.edu) + + * Version 2.6. + + * xeplain.tex (toc commands): Rewrite to allow general toc's. + + * xeplain.tex: Include indexing commands. + +Sun Apr 24 14:59:59 1994 Kathy Hargreaves (karl@cs.umb.edu) + + * xeplain.tex (\eqalignno): put \hfil back in (from plain) front of + first \@align, so lhs will be right justified. + +Fri Apr 15 17:46:39 1994 Karl Berry (karl@ra.cs.umb.edu) + + * merge: Split arrow into pre- and post-catcode changes. + * xeplain.tex: Read both parts. + +Wed Mar 30 14:34:52 1994 Karl Berry (karl@ra.cs.umb.edu) + + * xeplain.tex: Globally replace \dimen0 with \dimen@, why not. + +Wed Mar 30 13:19:59 1994 Karl Berry (karl@cs.umb.edu) + + * Version 2.5. + + * xeplain.tex (\@makeverbatimdoubleescape): New macro from + dorai@cs.rice.edu. + (\verbatimescapechar): Call it. + +Mon Mar 28 11:09:03 1994 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\@maybewarnref): Call \ref at the end. + +Tue Mar 22 10:48:01 1994 Karl Berry (karl@cs.umb.edu) + + * Version 2.4. + +Tue Mar 15 12:01:57 1994 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\@maybewarnref): New macro. + (\ref): Define to that initially. + (\eplainref): Name the real definition this. + +Sat Mar 12 15:32:32 1994 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\@columnsplit): Omit doing the looping; it causes + strange column splits on my index tests. + +Tue Mar 8 10:59:31 1994 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\@columns): Correct for one too many gutters. + +Sat Mar 5 15:16:47 1994 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\@numcolumns): Remove \newcount in favor of a \chardef. + (\columnfill): New macro. + +Thu Mar 3 14:31:16 1994 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\@oldandcode, \@plainnew{if,dimen}): New control + sequences, so we can read arrow.tex conditionally a la bibtex. + + * xeplain.tex (\@oldatcatcode): Rename to \@eplainoldatcode, so + btxmac and arrow's redefinitions don't affect us. + +Sat May 22 11:24:31 1993 Karl Berry (karl@cs.umb.edu) + + * Makefile.in (dist): Run gzip -9. + +Sun Apr 11 15:19:18 1993 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\@eqdefn): \@definelabel after the \definexref. + + * xeplain.tex (\xrlabel): Append an `x' after the _. + +Mon Mar 15 08:42:49 1993 Karl Berry (karl@cs.umb.edu) + + * btxmac.tex (\@readbblfile): Let our default \end be \@gobble. + + * btxmac.tex (\@readbblfile): Don't define \begin and \end if + \begin is already defined. + + * btxmac.tex (\@onecitation): Call \@printcitelabel. + (\@printcitelabel): New macro. + +Mon Mar 1 06:26:46 1993 Karl Berry (karl@cs.umb.edu) + + * Version 2.3. + +Tue Feb 23 16:52:49 1993 Karl Berry (karl@cs.umb.edu) + + * Makefile.in (dist): Copy info files to my local info directory. + +Sun Feb 21 11:07:38 1993 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\definexref, \ref, etc.): New macros. + (\@eqdefn, \writeitemxref, \xrdef): Use \definexref. + + * xeplain.tex (\{set,get}property): New macros from generic. + + * xeplain.tex (\tokstostring): This is no longer defined. + +Sat Feb 20 08:07:12 1993 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\hook{append,prepend,action,actiononce,run}): New + macros. + + * xeplain.tex (\expandifdefined): Remove. + + * Makefile (default): Change default to `eplain.tex'. + + * xeplain.tex (\toks@ii): New definition. + +Fri Feb 5 08:07:21 1993 Karl Berry (karl@cs.umb.edu) + + * Makefile (dist, eplain.tex): Pass version explicitly. + +Sun Jan 17 14:08:14 1993 Karl Berry (karl@cs.umb.edu) + + * Makefile (dist): Copy add-version. + +Sun Dec 27 17:00:59 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\csn, \ece): New macros. + +Fri Dec 18 10:11:33 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\expandifdefined): New macro. + +Sun Nov 22 12:03:13 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\ifempty, \@@ifempty): Restore from an old btxmac, + as some people were using them. + +Wed Nov 18 11:15:16 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex: Doc fix. + +Thu Nov 12 17:52:24 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\if@leftdisplays): New conditional. + (\{left,centered}displays): Set it and test it appropriately. + + * xeplain.tex (\displaysetup): Rename to \leftdisplaysetup. + + * xeplain.tex (\centereddisplays): Don't set \displaysetup to + \relax, just go back to the \previouseverydisplay. + +Wed Nov 11 07:08:18 1992 Karl Berry (karl@cs.umb.edu) + + * Version 2.2. + +Mon Nov 9 09:50:43 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\{,end}orderedlist): Synonyms for \{,end}numberedlist. + +Fri Nov 6 15:19:03 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\@removebox): Don't use \lastbox unless we're in + horizontal mode. + ( ): \let to `\ ', instead of \def. + +Mon Oct 19 09:10:56 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\boxit): Define to be \long. + +Fri Oct 9 10:19:05 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex (\everylist): New toks register. + (\beginlist): Expand it. + +Thu Oct 8 17:42:33 1992 Karl Berry (karl@cs.umb.edu) + + * Makefile (topfiles): Add `NEWS'. + + * xeplain.tex (\footnoterulewidth): Define as 2in, not 2true in. + Why did Knuth do this? + +Fri Oct 2 11:48:26 1992 Karl Berry (karl@cs.umb.edu) + + * xeplain.tex: doc fix. + +Sat Sep 19 17:32:44 1992 Karl Berry (karl@hayley) + + * xeplain.tex (\xrlabel): set the catcode of _ to 8 before the + definition, to protect ourselves. (From adam@symcom.math.uiuc.edu) + +Tue Aug 25 12:06:50 1992 Karl Berry (karl@hayley) + + * xeplain.tex: save and restore the catcode of @ as we do with + btxmac.tex. + +Tue Aug 11 07:54:52 1992 Karl Berry (karl@hayley) + + * xeplain.tex (\fmtversion): use `23 April 1964' style instead of + Unix-y timestamp style. + +Sat Aug 8 12:04:29 1992 Karl Berry (karl@hayley) + + * Makefile (eplain.tex): depend on Makefile. + +Fri Aug 7 14:43:22 1992 Karl Berry (karl@Prometheus) + + * xeplain.tex (\displayhook): remove this \newtoks. + (\leftdisplays): don't insert it into \everydisplay. + +Fri Jul 31 17:00:23 1992 Karl Berry (karl@hayley) + + * Makefile (topfiles): use *.sty, not just texnames.sty. + +Sat Jul 25 17:23:10 1992 Karl Berry (karl@hayley) + + * path.sty: new version (with Phil's blessing). Changes recorded + in the file itself. + +Fri Jun 19 09:17:04 1992 Karl Berry (karl@hayley) + + * xeplain.tex (\@lefteqalignnonoalign): use \parindent=0pt instead + of \noindent to lose the indentation. + +Thu Jun 11 09:13:14 1992 Karl Berry (karl@hayley) + + * arrow.tex: new version from Steven, changes only the license. + +Fri May 29 08:46:35 1992 Karl Berry (karl@hayley) + + * Makefile (dist): include add-date. + + * merge: include path.sty. + * xeplain.tex: leave marker. + * Makefile (eplain.tex): depend on path.sty. + +Mon May 25 11:16:15 1992 Karl Berry (karl@hayley) + + * xeplain.tex (\writenumberedtocentry): only expand the ``number'' + once, via \expandafter and \the\toks. + +Thu May 21 09:11:05 1992 Karl Berry (karl@hayley) + + * xeplain.tex (\verbatim, \endverbatim): do not begin and end with + \par. + +Sat May 16 11:26:19 1992 Karl Berry (karl@hayley) + + * xeplain.tex (\makeblankbox): assign to \errhelp before the + \errmessage. + +Sat May 9 06:42:57 1992 Karl Berry (karl@hayley) + + * xeplain.tex (\writenumberedtocentry): \edef the extra number, so + \the gets expanded. + +Wed May 6 15:46:52 1992 Karl Berry (karl@hayley) + + * Makefile (realclean): separate from distclean, and remove INSTALL. + +Tue May 5 11:25:44 1992 Karl Berry (karl@hayley) + + * Makefile (install): install eplain.tex. + +Tue Apr 28 08:28:29 1992 Karl Berry (karl@hayley) + + * Makefile (distclean): new target. + +Sun Apr 19 08:18:22 1992 Karl Berry (karl@hayley) + + * xeplain.tex (\expandonce): new macro from generic. + + * xeplain.tex (\@setuplisting): set \parskip = 0pt. + + * xeplain.tex (\@setuplisting): use `\listingfont' instead of \tt. + (\listingfont): new macro. + +Thu Apr 9 09:27:25 1992 Karl Berry (karl@hayley) + + * Makefile: use $(MAKE) to do submakes. + +Tue Mar 31 14:10:45 1992 Karl Berry (karl at hayley) + + * xeplain.tex (\boxit): use \ehrule and \evrule. + +Wed Mar 25 09:27:51 1992 Karl Berry (karl at hayley) + + * Version 2.1. + + * xeplain.tex (^^I): don't do \tt while defining this, as we might + not have any fonts yet. + +Sun Mar 15 06:58:33 1992 Karl Berry (karl at hayley) + + * Makefile: general cleanup. + + * btxmac.tex: version 0.99j, from Oren. + +Thu Mar 5 13:53:06 1992 Karl Berry (karl at claude.cs.umb.edu) + + * Version 2.0. + + * New btxmac.tex from Oren. + + * doc/eplain.texinfo: replace GPL. + +Mon Feb 17 14:19:27 1992 Karl Berry (karl at hayley) + + * btxmac.tex (\newcommand): use \@getoptionalarg. + (\@continuenewcommand): rewrite accordingly. + (\@newcommandwithargs): delete. + (\bibitem, \@bibitem): likewise. + + * btxmac.tex (\biblabelprint): use \p{re,ost}biblabelcontents + instead of hardwiring the \hss. + (\@readbblfile): in \@alphabibitem and \@numberedbibitem, define + the appropriate one to \hss to do the justification. + + * btxmac.tex (\@readauxfile): improve comments. + + * btxmac.tex (\biblabelprint): \kern\biblabelextrahang, instead of + \enspace. + (\@readbblfile): change comment at \biblabelextrahang. + +Fri Feb 7 08:11:07 1992 Karl Berry (karl at hayley) + + * eplain.texinfo (Cross-references): bring the list of valid chars + in references up-to-date. + +Wed Feb 5 12:05:09 1992 Karl Berry (karl at hayley) + + * xeplain.tex: remove spurious spaces from ends of definitions. + + * xeplain.tex: marker for arrow.tex. + * merge: include arrow.tex in eplain.tex. + * arrow.tex: new file. + +Mon Jan 27 06:22:43 1992 Karl Berry (karl at hayley) + + * xeplain.tex (*printmarker): use \listmarkerspace instead of + \enspace. + * eplain.texinfo (List formatting): document this. + + * xeplain.tex (\linenumberedlisting, \printlistinglineno): new + macros, from FABROADI@CUGSBVM.BITNET. + * eplain.texinfo (Verbatim listing): document them. + + * eplain.texinfo (Verbatim listing): document it. + * xeplain.tex (\verbatim): new macro, mostly from + beebe@math.utah.edu, to do inline verbatim mode. + + * eplain.texinfo (Footnotes): say that the space above the rule + and below the text is \skip\footins. + + * xeplain.tex (\center, \flush{left,right}): define with \gdef; + remove the \globaldefs = 1. + + * eplain.texinfo (Logos): add some more. + * xeplain.tex: include texnames.sty. + +Thu Jan 23 08:35:43 1992 Karl Berry (karl at hayley) + + * xeplain.tex (\writenumberedtocentry): \sanitize the section + number (arg#3), in case it happens to have weird control + sequences in it (e.g., if it's an author's name instead of a + number). + +Wed Jan 15 10:52:32 1992 Karl Berry (karl at hayley) + + * eplain.texinfo (Citations): document \bblfilebasename. + + * eplain.texinfo (Contents): document this. + * xeplain.tex (\readtocfile, \opentocfile): use \tocfilebasename. + (\tocfilebasename): defaults to \jobname. + +Fri Dec 27 11:07:41 1991 Karl Berry (karl at Prometheus) + + * btxmac.tex (\@getoptionalarg): set \@optionalnext to \relax + before using it as the arg to \@futurenonspacelet. + +Sat Dec 7 07:23:14 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\eqnofontfam): remove this. What was I thinking of? + +Fri Dec 6 12:57:16 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\eqnofontfam): change from \mit to \rm. + (\eqprint): enclose the font change in a group. + + * xeplain.tex (\displaysetup): subtract \leftskip from + \displaywidth (on the umpteenth alternation here); also, don't + \hskip by \displaywidth after advancing by the extra parameters. + Instead, use a temporary. (Otherwise, we would \hskip by too much.) + +Mon Nov 18 06:57:33 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\eqprint): call \eqnofontfam first. + (\eqnofontfam): define to be \mit. + + * xeplain.tex (\leftdisplays): decrease \hsize, so \noalign in + \eqalignno doesn't produce an overfull box. + (\eqalignno in \redefinealignmentdisplays): set \noalign to a new + definition. + (\@primitivenoalign): new synonym. + (\@lefteqalignnonoalign): new macro. + + * btxmac.tex (\bibliography): do \nobreak before reading the bbl file. + +Mon Oct 28 10:01:39 1991 Karl Berry (karl at hayley) + + * btxmac.tex (\@readbblfile): correct test for \@itemnum being + defined. + + * xeplain.tex (\@eateol): if there's text on the line with the + justify command, do the right thing. + * eplain.texinfo (Justification): document these changes. + + * xeplain.tex (\@finjustifyreturn): new macro to test for two + ^^M's in justified environments. If we find this, insert + \blanklineskipamount glue. + (\beforejustify): set up ^^M to call this; set up \@eateol. + (\flushleft, \flushright, \center): define \@eolaction instead of + defining ^^M directly; ditto for \@eateol. + +Sun Oct 6 12:02:46 1991 Karl Berry (karl at hayley) + + * btxmac.tex (\@readbblfile): don't define \@itemnum if it's + already defined. + +Fri Oct 4 14:34:58 1991 Karl Berry (karl at hayley) + + * btxmac.tex (\bblfilebasename): new macro, defaults to \jobname. + (\bibliography, \@readbblfile): use it. + +Sat Sep 28 11:46:10 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\unorderedprintmarker): new macro. + (\unorderedlist): set \printmarker to it. + (\writeitemxref): new macro, the xref-defining part from \@finli. + + * xeplain.tex (\leftdisplays): don't save and restore \eqalign, + since we don't change it in \@redefinealignmentdisplays. + +Fri Sep 27 09:45:17 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\displaysetup): no, take \leftskip into account + after all. What's going on? + +Tue Sep 24 07:10:23 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\displaysetup): don't advance \displayindent by + \leftskip, since TeX already does. + + * btxmac.tex (\nexttoken): rename to \@nexttoken. + +Fri Sep 20 10:45:23 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\displaysetup): don't subtract \leftskip when computing + \displaywidth; TeX already does that. + + * xeplain.tex (\@finli): don't call \xrlabel on the arg to + \definexref; advance \itemromannumeral. + +Thu Sep 19 16:12:14 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\xrefn): remove spurious braces from warning. + + * eplain.texinfo (Lists): document this. + * xeplain.tex (\{print,}itemromannumeral): new macros. + (\numberedmarker): use roman numerals for depth 3. + +Tue Sep 17 06:30:25 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\xrefn): remove calls to \tokstostring; \csname + works just as well. + * btxmac.tex (\@readauxfile): don't call \@setletters; only reset @. + (\@tokstostring): remove. + (\@cite...): remove calls to \@tokstostring + + * xeplain.tex (\@finli): define the item cross-reference label, as + well as write it out; no, don't, the value might be a page number. + + * xeplain.tex (\xrlabel): remove assignments, so it becomes + expandable. (This means control sequences are no longer allowed + in labels.) Change callers. + +Mon Sep 16 15:17:09 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\eqdefn): don't call \eqconstruct if we're given an + optional argument. + +Sun Sep 15 17:19:33 1991 Karl Berry (karl at hayley) + + * eplain.texinfo (Lists): document this. + * xeplain.tex (\beginlist): set \itemnumber=1; remove from \...list. + (\li): remove from the \...list macros and only + define once; allow an optional arg as a cross-reference label. + (\item{number,letter}out): rename to \print...; change caller. + (\printmarker): new macro to output the actual item marker. + +Sat Sep 14 15:55:39 1991 Karl Berry (karl at hayley) + + * btxmac.tex (\@getoptionalarg): use \@futurenonspacelet. + (\@futurenonspacelet): move from xeplain.tex. + * eplain.texinfo (Macro arguments): document this. + +Mon Sep 9 10:25:51 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\@redefinealignmentdisplays): add another \hfil + outside math mode to the template for \displaylines. + +Sun Sep 8 06:31:50 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\eqdef): call \eqconstruct here. + (\eq@eqdefn): not here. + + * eplain.texinfo: document all this. + + * xeplain.tex (\beginlist): do the \abovelistskip first. + + * xeplain.tex (\{v,h}penalty): new macros. + + * xeplain.tex (\{above,below}listskipamount, + \interitemskipamount): rename from ...skip. + (\{above,below}listpenalty, \interitempenalty): new count + registers. + (\{above,below}listskip, \interitemskip): macros which skip by the + register and include the \...penalty. + +Sat Sep 7 07:29:12 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\gtracingoff, \gloggingall): new macros. + * eplain.texinfo (Diagnostics): document them. + +Fri Sep 6 13:40:11 1991 Karl Berry (karl at hayley) + + * eplain.texinfo (Diagnostics): new command \tracingoff. + * xeplain.tex (\tracingoff): define it. + +Thu Sep 5 10:19:49 1991 Karl Berry (karl at hayley) + + * eplain.texinfo (Tables): replace reference to INRSTeX, which + seems not to exist, with one to ruled.tex, available on ymir. + +Sun Sep 1 14:53:38 1991 Karl Berry (karl at hayley) + + * xeplain.tex: change header comment. + +Thu Aug 29 16:01:43 1991 Karl Berry (karl at hayley) + + * eplain.texinfo (Formatting equation references): document + \eqconstruct. + * eplain.texinfo (Macro arguments): document \identity. + + * xeplain.tex (\identity): new definition. + (\eqconstruct): new macro \let = \identity. + (\@eqdefn): call \eqconstruct to produce the final cross-reference + text. + + * eplain.texinfo (Index): rename to `Concept index'. + + * eplain.texinfo (Top): include version number. + +Sat Aug 24 07:09:23 1991 Karl Berry (karl at hayley) + + * Makefile (dist): make a doc subdirectory in the distribution. + (dos): don't distribute all the test files. + + * Makefile (install): install the info files. + (infodir): new variable. + +Fri Aug 23 11:48:40 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\eqsubdefn): expand \@currenteqlabel before + defining it. + + * xeplain.tex (\xrlabel): use 95 instead of `\_, so \edef doesn't + break quite so badly. + +Thu Aug 22 14:42:45 1991 Karl Berry (karl at ra.cs.umb.edu) + + * xeplain.tex (\@eqdef): new command for both \eqdef and \eqsubdef + to call. + (\eqrefn): new command to do what \eqref does, except omits the + call to \eqprint. + (\eqref): call \eqrefn. + (\eqdefn): allow an optional argument to specify the text of the + label, instead of always using numbers. + (\@currenteqlabel): defined by \eqdefn to be the last defined + label. + (\eqsubdefn): use \eqrefn of \@currenteqlabel to define the text + for the subequation label. + (\@eqdef): use \eqref to generate the printed material, instead of + writing the numbers. + + * xeplain.tex (\xrlabel): remove grouping; use \count@ to save + \escapechar instead. Also, use \temp instead of \tts. + (\xrdef, \@eqdefn): remove grouping. + + * btxmac.tex (\cite): do \printcitestart before \@nocite. + + * merge: don't use /bin/date. + +Fri Aug 16 08:06:26 1991 Karl Berry (karl at hayley) + + * eplain.texinfo: fix node pointers. + +Wed Aug 14 14:53:10 1991 Karl Berry (karl at hayley) + + * Makefile (etex.fmt): rm -f etex.aux before creating it. + (merge): assume fix-checksum is in PATH. + +Mon Aug 12 19:42:07 1991 Karl Berry (karl at hayley) + + * eplain.texinfo (Formatting displays): remove the stuff about + \generaldisplay, since that's gone. + + * xeplain.tex (\eqsubdefn): new macro to define subequations. + (\eqsubdef): its companion. + (\eqsubreftext): macro to produce the text of such a reference. + (\@eqdefn): new subroutine for \eqsubdefn and \eqdefn. + (\subeqnumber): new count register. + * eplain.texinfo (Subequation references): new subsection to + describe all this. + +Mon Aug 5 07:08:55 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\eattoken): use a private control sequence for + eating, to avoid conflicts. + (\@eattoken): \let = \relax. + +Sat Jul 20 06:39:48 1991 Karl Berry (karl at hayley) + + * eplain.texinfo (Copying): replace with version 2 of the GPL. + + * eplain.texinfo (Local variables): remove this, since it's + standard now. + +Mon Jul 8 05:46:57 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\leftdisplays): new implementation. + + * xeplain.tex (\eattoken): new macro. + * eplain.texinfo (Macro arguments): document it. + +Sun Jun 23 11:13:42 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\ifundefined): new macro. + + * xeplain.tex (\blackbox): add \relax at the end. + + * xeplain.tex (\BibTeX): use \TeX. + (\MF): use \rm instead of \tenrm. + + * merge: automatically figure out the date, and version, and loop + on the checksum. + * xeplain.tex (\fmtversion): don't include real version numbers, + dates, or the checksum. + + * xeplain.tex (\environment): define \@groupname with \edef + instead of \def. + +Sat Jun 22 08:23:05 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\@isolatedendenvironmenthelp): improve this message. + +Fri May 31 06:19:40 1991 Karl Berry (karl at hayley) + + * eplain.texinfo: do @finalout, to prevent overfull boxes. + +Sun May 19 07:01:12 1991 Karl Berry (karl at hayley) + + * citecust.tex: define the \scriptfont for \ttfam, so that + undefined references work properly (found by + jxp@ccadfa.cc.adfa.oz.au). + +Wed May 15 06:52:20 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\writetocentry): pass in an empty arg to + \writenumberedtocentry, not \empty, so the \ifx works right + (found by Paul). + +Wed May 8 17:04:32 1991 Karl Berry (karl at hayley) + + * Makefile (dos): put texinfo.tex in the DOS distribution. + +Tue May 7 12:19:24 1991 Karl Berry (karl at ra.cs.umb.edu) + + * xeplain.tex (\xrefwarningfalse): forgot a \ in front of the \let + (found by Paul). + +Mon May 6 11:01:07 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\AMS): new macro from \AMSTeX. + (\AMSTeX): use it. + (\AMSLaTeX): new macro. + * eplain.texinfo (logos): document \AMSLaTeX. + + * xeplain.tex (\today): new macro. + * eplain.texinfo (Time of day): document it. + +Fri Apr 26 08:29:08 1991 Karl Berry (karl at hayley) + + * Makefile (dos): rename INSTALL, remove ORIG. + + * Version 1.9. + + * Makefile (clean): remove the .??O files that texi2dvi creates. + (eplain.dvi): use texi2dvi. + + * Makefile (dist): create the file `INSTALL' after making the info + files. + + * eplain.texinfo (Installation): bring up to date. + * README: likewise. + + * btxmac.tex: final (for now) version. + +Mon Apr 22 09:53:53 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\@writeeqdef, \@writexrdef): we don't need a + \percentchar at the end of the lines we write anymore, since + btxmac.tex does \endlinechar = -1 before reading the aux file. + + * allref.tex: new test file to test all kinds of reference + simultaneously. + +Mon Apr 15 09:15:51 1991 Karl Berry (karl at hayley) + + * eplain.texinfo (Installation): describe \noauxfile. + + * xeplain.tex (\singlecolumn): document (somewhat) better. + + * btxmac.tex: new version from Oren. + +Sun Apr 7 14:54:05 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\boxit, \boxitspace): new macros from the TeXbook. + * eplain.texinfo (Boxes): document it. + + * xeplain.tex (\hidevrule): remove a spurious space. + + * xeplain.tex (\lbracechar, \rbracechar): new definitions. + * eplain.texinfo (Category codes): document them. + +Fri Mar 29 17:13:46 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\makecolumns): set the \hsize inside each entry. + (\currentcolumn): new register. + + * xeplain.tex (\hidehrule, \hidevrule): comment these; remove a + group from \hidevrule. + +Tue Mar 26 12:20:35 1991 Karl Berry (karl at ra.cs.umb.edu) + + * xeplain.tex (\linenumber): \let = \@linenumber. + +Mon Mar 25 05:52:27 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\writenumberedtocentry): don't test #3 with an + \ifx; define it in a control sequence first. + +Mon Mar 11 08:56:43 1991 Karl Berry (karl at hayley) + + * Version 1.8. + + * xeplain.tex (\environment, \endenvironment): don't ignore spaces + at the end. + + * xeplain.tex (\@undefinedmessage): don't define it if it's + already defined. + + * xeplain.tex (\everyjob): expand the old \everyjob. + +Fri Mar 8 08:03:50 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\writenumberedtocentry): \ignorespaces after the + \fi, not before (found by abrahams@mts.cc.wayne.edu). + +Tue Mar 5 08:33:16 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\makeblankbox): give an error message if \box0 is + void. + (\@makeblankboxhelp): new control sequence with help for the error + message. + +Mon Mar 4 07:10:10 1991 Karl Berry (karl at hayley) + + * btxmac.tex (\linenumber): define this, and use it in the + undefined citation message. + * xeplain.tex: use \linenumber in the undefined messages. + + * xeplain.tex: change all \undefined's to \@undefined's. + +Sun Mar 3 07:43:11 1991 Karl Berry (karl at hayley) + + * xeplain.tex: put the BibTeX definitions in a token register; + expand it if \nobibtex is undefined. + +Fri Mar 1 16:00:38 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\@redefinealignmentdisplays): Make \displaylines + redefine \eqprint, so the equation number still comes out on the + right. + + * Makefile (etex.fmt): cp /dev/null onto etex.aux, don't just + touch it. + + * xeplain.tex (\if@nobibtex): remove this; just test + \ifx\nobibtex\@undefined instead. + + * btxmac.tex (\@innernewdimen): define this. + (\if@notfirstcitation, \biblabelwidth, \biblabelextrahang, + \@numparams): define using \@inner..., since we include all of + btxmac.tex in an \if ... \fi construction in eplain.tex now. + +Wed Feb 27 08:02:24 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\@ddisplaytest): this time really remove the + trailing spaces; I didn't test it properly before. + + * eplain.texinfo (Justification): remark that setting the + linespacing values inside \center et al. is useless. + +Sat Feb 23 08:42:12 1991 Karl Berry (karl at hayley) + + * xeplain.toc (\opentocfile): make the \@tocfileopenedtrue be + \global (from Paul). + + * xeplain.tex (\fullmonthname): new macro. + * eplain.texinfo (Time of day): document it. + +Fri Feb 22 15:11:14 1991 Karl Berry (karl at hayley) + + * eqref.tex: say that the output of the \displaylines test should + look bad. + + * xeplain.tex (\@displaytest, \@ldisplaytest): use \noexpand on + the argument, to prevent obscure errors (that might never + actually occur, I'm not sure). + + * xeplain.tex (\@ddisplaytest): remove trailing spaces and/or + surrounding braces from the argument to \eqdef (from + jxp@ccadfa.cc.adfa.oz.au). + (\@removetrailingspaces): new macro. + +Sat Feb 2 09:25:30 1991 Karl Berry (karl at hayley) + + * fileexist.tex: new file to test the various possibilities. + + * btxmac.tex (\@testfileexistence): allow an optional argument + specifying the root name of the file. + (\@finishtestfileexistence): new macro. + + * merge: merge all of btxmac into eplain.tex. + * xeplain.tex: rearrange slightly to accommodate this. + +Fri Jan 25 11:34:09 1991 Karl Berry (karl at hayley) + + * Version 1.7 (released for ASI only). + + * Makefile (dist): automatically include btxdoc.tex and + texinfo.tex in the distribution. + + * Makefile (etex.fmt): don't print all the stupid \font... lines. + + * contents.tex: make a subsection include \cos, to test the + non-expansion. + * xeplain.tex (\sanitize, \gobblemeaning): new macros from a + TUGboat article by Ron Whitney. + (\writenumberedtocentry, \writetocentry): do not expand the text + of the heading. + * eplain.texinfo (Contents): say that the title text is not + expanded. + +Thu Jan 3 09:07:05 1991 Karl Berry (karl at hayley) + + * xeplain.tex (\beginlist): don't set \parskip = 0pt, in case + \parindent is zero. + (\printitem): do \vskip-\parskip, so we don't get extra space if + \parskip is nonzero. + + * list.tex: test a multiple-paragraph list item with \parindent=0 + and \parskip nonzero. + +Mon Dec 17 12:57:41 1990 Karl Berry (karl at hayley) + + * xeplain.tex (` ' in \obeywhitespace): define to be `\ ' using + \def instead of \let, to allow redefinition. + +Wed Dec 12 14:34:28 1990 Karl Berry (karl at aten) + + * Version 1.6. + + * eplain.texinfo (Formatting bibliographies): \biblabelextrahang + and \parskip must be set inside \bblhook. + + * Makefile (etex.fmt): make sure etex.aux exists. + +Mon Dec 10 16:09:30 1990 Karl Berry (karl at aten) + + * eplain.texinfo (Formatting bibliographies): describe + \biblabelextrahang and \bblsc. + + * xref.tex: don't unconditionally input eplain.tex. + + * xeplain.tex: don't set \@citewarningtrue after all; that makes + it so we always warn about labels. + * btxmac.tex (\@readauxfile): set \@citewarningtrue if there was + an aux file, so that we get warned about undefined references + when we make a format file. + + * xeplain.tex: remove misplaced comment. + +Sun Dec 9 07:52:52 1990 Karl Berry (karl at hayley) + + * xeplain.tex (\blanklineskipamount, \@finishobeyedreturn): new + definitions to generalize the handling of blank lines in + \obeywhitespace. + * eplain.texinfo (Obeying spaces): document this. + + * xeplain.tex (\obeywhitespace): use `\ ' instead of + `\alwaysspace', and remove the latter. + * eplain.texinfo (Obeying spaces): remove reference to \alwaysspace. + + * xeplain.tex: set \@citewarningtrue after reading the stuff from + btxmac, so that we get undefined label messages when we use a + format file. + +Sat Dec 1 07:44:52 1990 Karl Berry (karl at hayley) + + * eplain.texinfo (Installation): refer to `\fmtversion', not + `\eplainversion'. + + * btxmac.tex (\@getoptionalarg): new macro. + * xeplain.tex (\getoptionalarg): \let = to above. + * eplain.texinfo (Macro arguments): document it. + + * xeplain.tex (\futurenonspacelet): new macro from the TeXbook. + * eplain.texinfo: document it. + + * btxmac.tex (\@setletters): only check characters with codes + below 128 if we are the old TeX. + + * xeplain.tex (\@ddisplaytest): omit extra braces around the call + to \eqdef. + (\eqdef, \eqdefn): ignore following spaces. + + * xeplain.tex (\@undefinedmessage): change wording slightly. + +Fri Nov 30 10:51:02 1990 Karl Berry (karl at hayley) + + * eplain.texinfo (Installation): describe \eplain. + + * eplain.texinfo (Citations): use @file instead of @t, and make + editorial changes. + +Wed Nov 28 06:57:24 1990 Karl Berry (karl at hayley) + + * eplain.texinfo (Cross-references): escapes are catcode 0, not 1. + Also, don't put a \ in the invalid example. + + * eplain.texinfo (Allocation macros): use `proclaim' in the + example, not `innerproclaim'. + + * xeplain.tex (\alwaysspace): use \font instead of \the\font. + + * xeplain.tex (^^I): use \fontdimen2\font, instead of \tt, since + \tt might not be a font selector. + + * Makefile (etex.fmt): remove etex.aux. + + * xeplain.tex (\displayhook): new token register expanded at + \everydisplay time. + * eplain.texinfo (displays): document this. + +Tue Nov 27 08:24:41 1990 Karl Berry (karl at hayley) + + * xeplain.tex (\eqdef): make \eqno = \relax if we are inner. + * eplain.texinfo (Equation references): \eqdefn doesn't produce + anything. + + * eqref.tex: test \eqdef inside \displaylines. + + * xeplain.tex (\eplain): define to be `t'. + +Sun Nov 25 09:30:46 1990 Karl Berry (karl at hayley) + + * xeplain.tex (\eqref, \xrefn): no, that's not enough. Use + \if@citewarning here, so the \if's and \fi's match properly. + * eplain.texinfo (Citations): document \xrefwarningtrue. + (Cross-references): ditto. + + * xeplain.tex (\ifxrefwarning): define to be \if@citewarning, so + changes to the latter are reflected in the former. + +Sat Nov 24 08:21:35 1990 Karl Berry (karl at hayley) + + * xeplain.tex: say that we have two version numbers now in the + header comment. + +Thu Nov 22 10:48:35 1990 Karl Berry (karl at hayley) + + * eplain.texinfo (Equation references): \eqdef can be used in an + \eqalignno now, so \eqdefn is useful in even fewer sitations. + +Thu Nov 15 10:28:13 1990 Karl Berry (karl at hayley) + + * Version 1.5. + + * merge: remove comments from xeplain.tex as well as btxmac.tex, + and fix the checksum and filename in the final eplain.tex. + + * xeplain.tex (\if@fileexists, ...): \let = \relax, in case the + file is being read twice. + + * Makefile (etex.fmt): new rule. + +Wed Nov 14 19:02:28 1990 Karl Berry (karl at aten) + + * eplain.texinfo (Iterations): fix syntax error in example (from + bsuggs@hac2arpa.hac.com). + +Mon Nov 12 10:34:37 1990 Karl Berry (karl at hayley) + + * etex.tex: mention that plain should be loaded. + * eplain.texinfo (Installation): mention etex.tex. + + * xeplain.tex (\ifnobibtex): set to true if \nobibtex is defined. + * eplain.texinfo (Installation): describe this. + + * btxmac.tex: new version incorporating my changes from Oren. + \@citewarning has to be defined in the non-bibtex specific part. + +Sat Nov 10 08:49:07 1990 Karl Berry (karl at hayley) + + * xeplain.tex (\xrlabel): explain how _ works. + +Wed Oct 31 06:24:56 1990 Karl Berry (karl at hayley) + + * merge: make eplain.tex readonly after creating it. + +Tue Oct 30 07:52:07 1990 Karl Berry (karl at hayley) + + * eplain.texinfo: `eplain' changed to `Eplain' throughout; a few + other typos corrected. + + * btxmac.tex (\@innerdef): new macro to give an inner definition + to an outer control sequence. + (\@innernewcount, \@innernewdimen, \@innernewif, + \@innernewwrite): use it to define these macros. + * xeplain.tex: make \innernewcount et al. synonyms for the above, + and also make inner versions of all the other plain TeX macros. + * eplain.texinfo (Allocation macros): new section to document this. + + * xeplain.tex: rename \@xrlabel to \xrlabel. + * eplain.texinfo (Converting to characters): document \xrlabel. + +Sun Oct 28 08:35:20 1990 Karl Berry (karl at hayley) + + * eplain.texinfo (Cross-references): explain which characters are + valid. + + * btxmac.tex (\@setletters): change all characters with category + code 12 into category code 11, instead of writing a list. + (Also change _.) + (@setmoreletters): remove. + + * btxmac.tex (\@resetnumerals): also change the category codes of + ', `, and ". + +Sat Oct 27 09:46:54 1990 Karl Berry (karl at hayley) + + * eplain.tex becomes xeplain.tex; a shell script `merge' puts + definitions from btxmac.tex that are used in the rest of eplain + into xeplain, creating eplain.tex. Also, a new conditional, + \ifnobibtex, determines whether we read btxmac.tex or not. + (Being able to not read btxmac suggested by Paul.) + +Sun Oct 21 14:03:31 1990 Karl Berry (karl at hayley) + + * eplain.texinfo (Cross-references): users should use + \@setmoreletters, not redefine \@setletters. + +Wed Oct 17 07:14:26 1990 Karl Berry (karl at hayley) + + * eplain.tex (\eqdef): don't do \eqno if we're inner. + +Sat Oct 13 07:28:11 1990 Karl Berry (karl at hayley) + + * eplain.tex (\leftdisplayindent): new \dimen parameter + (suggested by wiawkph@dutrun.tudelft.nl). + (\leftdisplays): use it. + * eplain.texinfo (Displays): document it. + + * eplain.tex (\@ddisplaytest): new macro to find an \eqdef in a + display. + (displaysetup): call it. + +Fri Oct 12 06:27:52 1990 Karl Berry (karl at hayley) + + * eplain.texinfo: describe @menu entries. + + * eplain.tex (\topmargin, et al.): new macros. + * eplain.texinfo (Margins): new section to document them. + +Thu Oct 11 06:30:54 1990 Karl Berry (karl at hayley) + + * xref.tex: forgot \xref in front of {label2}. + +Tue Oct 9 06:48:08 1990 Karl Berry (karl at hayley) + + * eplain.tex (\xrdef): use \@xrlabel, not \xrlabel. + +Tue Sep 25 17:55:32 1990 Karl Berry (karl at hayley) + + * eplain.tex (\TeX): new macro, adds \null to plain's definition. + +Fri Sep 14 13:54:01 1990 Karl Berry (karl at hayley) + + * eplain.tex (\writenumberedtocentry): expand the third parameter + now, instead of at the time of the \write. + * eplain.texinfo (Contents): document this. + +Thu Sep 13 08:09:25 1990 Karl Berry (karl at hayley) + + * eplain.texinfo (Citations, Formatting citations, Formatting + bibliographies): emendations from Oren Patashnik + . + + * eplain.tex (\footnoterule): new macro from plain TeX, + generalized to arbitrary dimensions. + (\vfootnote): advance \splittopskip by \interfootnoteskip, so that + split footnotes have the right amount of space at the top. + * footnote.tex: test the new dimension parameters. + * eplain.texinfo (Footnotes): document all this. + +Fri Sep 7 06:38:49 1990 Karl Berry (karl at hayley) + + * Version 1.4. + +2005-08-13 Oleg Katsitadze + + * doc/ChangeLog, doc/Makefile: Added "public domain" note. + +2005-08-12 Karl Berry + + * doc/userdef.texi, doc/eplain.info, doc/eplain.texi: wording + +2005-08-12 Oleg Katsitadze + + * doc/Makefile (doc): Added btxdoc prerequisite. + (pdf): New target. + (btxdoc): New target. + (eplain.html): No need for it, html is good enough. + (distclean): Brought up-to-date with the changes. + + * doc/userdef.texi (Contents): \readtocfile does not wipe out toc + file any more, to allow multiple contents + +Sun Apr 25 22:30:00 1999 Adam Lewenberg + + * doc/progdef.texi: Added a section on user-defined environments + to progdef.texi and fixed a few typos in documentation. Suggested + by Paul Abrahams. + +Sun Dec 7 18:29:00 1997 Adam Lewenberg + + * doc/eplain.texi: Force line length of documentation to be 6.5 inches + by adding a @changepagesizes command. + +Fri Dec 5 09:10:00 1997 Adam Lewenberg + + * doc/userdef.texi: Added \gutterbox explanation to multicolumn + section. + +Sun Jun 2 09:30:00 1996 Adam Lewenberg (adam@math.uiuc.edu) + + * doc/userdef.texi: added a missing word in section on path + command. + +Mon Apr 8 12:00:00 1996 Adam Lewenberg (adam@math.uiuc.edu) + + * doc/userdef.texi: changed dimensions in section on margins from in to + true in. + +Thu Jul 28 15:41:40 1994 Karl Berry (karl@cs.umb.edu) + + * doc/userdef.texi: \{above,below}doublecolumnskip => + \{above,below}columnskip. From wiawkph@dutrun2.tudelft.nl. + +Sat Apr 30 17:51:52 1994 Karl Berry (karl@cs.umb.edu) + + * Version 2.6. + + * doc/userdef.tex (Indexing): New section. + (Contents): Describe new generic contents commands. + +Sun Apr 17 10:06:50 1994 Karl Berry (karl@ra.cs.umb.edu) + + * doc/progdef.texi (Converting to characters): Remove spurious period. + * doc/userdef.tex (Verbatim listing, Cross-references): Fix other typos. + * doc/invoke.texi: Rewrite \nobibtex section. + From adam@symcom.math.uiuc.edu. + +Wed Mar 30 14:27:21 1994 Karl Berry (karl@cs.umb.edu) + + * Version 2.5. + + * doc/userdef.texi (Verbatim listing): Document \makeverbatimescapechar. + +Tue Mar 22 10:48:01 1994 Karl Berry (karl@cs.umb.edu) + + * Version 2.4. + +Thu Mar 3 17:47:55 1994 Karl Berry (karl@cs.umb.edu) + + * doc/invoke.texi (Invoking Eplain): Document \noarrow. + + * doc/userdef.texi (Formatting bibliographies): Index extra space + between the items. + +Sun Apr 11 15:44:58 1993 Karl Berry (karl@cs.umb.edu) + + * doc/userdef.texi (Equation references): Document empty equation labels. + +Sun Apr 4 13:21:12 1993 Karl Berry (karl@cs.umb.edu) + + * doc/install.texi: Include information for emtex. + + * doc/Makefile (TEX): Be sure .. is in TEXINPUTS. + + * doc/Makefile (distclean): Remove empty .??s files. + +Mon Mar 1 06:26:51 1993 Karl Berry (karl@cs.umb.edu) + + * Version 2.3. + +Fri Dec 18 10:14:25 1992 Karl Berry (karl@cs.umb.edu) + + * doc/progdef.texi: Document \expandifdefined. + +Thu Nov 12 17:53:07 1992 Karl Berry (karl@cs.umb.edu) + + * doc/userdef.texi (Formatting displays): \displaysetup is now + \leftdisplaysetup. + +Wed Nov 11 07:08:12 1992 Karl Berry (karl@cs.umb.edu) + + * Version 2.2. + +Mon Nov 9 09:59:24 1992 Karl Berry (karl@cs.umb.edu) + + * doc/Makefile (dist): Make the Info and index files after inserting + the new version number. + +Thu Oct 22 10:46:28 1992 Karl Berry (karl@cs.umb.edu) + + * update.el (make-backup-files): Set to nil. + +Tue Aug 18 15:55:15 1992 Karl Berry (karl@hayley) + + * doc/Makefile (INSTALL): `Node: Installation' does not begin a line. + +Fri Jul 31 19:18:12 1992 Karl Berry (karl@hayley) + + * doc/userdef.texi (Verbatim): \verbatim doesn't work in macro definitions. + +Fri Jul 17 09:55:10 1992 Karl Berry (karl@hayley) + + * doc/userdef.texi (Tables): update info for ruled.tex (from + mathew@bach.crhc.uiuc.edu). + +Fri May 29 09:35:59 1992 Karl Berry (karl@hayley) + + * doc/userdef.texi (Paths): new section. + +Thu May 21 09:08:18 1992 Karl Berry (karl@hayley) + + * doc/userdef.texi (Verbatim listing): had the example wrong. + +Tue May 12 15:28:04 1992 Karl Berry (karl@hayley) + + * doc/userdef.texi (Cross-references): had sense of valid xref + catcodes inverted. + +Thu May 7 08:08:24 1992 Karl Berry (karl@hayley) + + * doc/Makefile (dist): link the .texi files. + +Wed May 6 15:41:24 1992 Karl Berry (karl@hayley) + + * doc/eplain.texi: add an `@paragraphindent'. + +Tue May 5 11:05:43 1992 Karl Berry (karl@hayley) + + * doc/Makefile (install): use a loop to install the multiple info + files. + (eplain.info): depend on *.texi. + * doc/*.texi: split up eplain.texinfo. + +Tue Apr 28 08:23:30 1992 Karl Berry (karl@hayley) + + * doc/Makefile (prefix, infodir, INSTALL_DATA): add definitions. + (distclean): new target. + (dist): put INSTALL in the distribution. + +Sun Apr 19 08:17:43 1992 Karl Berry (karl@hayley) + + * doc/eplain.texinfo (\expandonce): new subsection. + (\futurenonspacelet): change to a subsection. + (\ifundefined): might as well document this here, also. + (Expansion): new section. + + * doc/eplain.texinfo (Verbatim listing): document \listingfont. + + * doc/Makefile (eplain.dvi): tex eplain.texinfo, not eplain.cps. + +Tue Mar 31 14:12:03 1992 Karl Berry (karl at hayley) + + * doc/eplain.texinfo (Boxes): document \boxit using \e[hv]rule. + +Wed Mar 25 09:22:29 1992 Karl Berry (karl at hayley) + + * Version 2.1. + + * doc/eplain.texinfo: add section on patents and copyrights. + +Sun Mar 15 08:22:56 1992 Karl Berry (karl at hayley) + + * doc/Makefile: new file. + + +This file is public domain. diff --git a/Master/texmf-dist/doc/eplain/base/INSTALL b/Master/texmf-dist/doc/eplain/base/INSTALL new file mode 100644 index 00000000000..3a514ae606b --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/INSTALL @@ -0,0 +1,51 @@ +Installation +************ + +The simplest way to install Eplain is simply to install the file +`eplain.tex' in a directory where TeX will find it. What that +directory is obviously depends on your operating system and TeX +installation. I personally install `eplain.tex' in a directory +`/usr/local/lib/texmf/tex/plain'. + + If you want, you can also create a format (`.fmt') file for Eplain, +which will eliminate the time spent reading the macro source file with +`\input'. You do this by issuing a sequence of Unix commands something +like this: + + prompt$ touch eplain.aux + prompt$ initex + This is TeX, ... + **&plain eplain + (eplain.tex) + *\dump + ... MESSAGES ... + +You must make sure that `eplain.aux' exists _before_ you run `initex'; +otherwise, warning messages about undefined labels will never be issued. + + You then have to install the resulting `eplain.fmt' in some system +directory or set an environment variable to tell TeX how to find it. I +install the format files in `/usr/local/lib/texmf/ini'; the environment +variable for the Web2C port of TeX to Unix is `TEXFORMATS'. + + Some implementations of TeX (including Web2C) use the name by which +TeX is invoked to determine what format to read. For them, you should +make a link to the `virtex' program named `etex', and then install the +format file with the name `etex.fmt'. This lets users invoke TeX as +`etex' and get the format file read automatically, without having to +say `&eplain'. + + For convenience, the file `etex.tex' in the distribution directory +does `\input eplain' and then `\dump', so that if you replace `eplain' +with `etex' in the example above, the format file will end up with the +right name. + + The `install' target in the `Makefile' does all this properly for +Unix systems and Web2C. You may have to change the pathnames. + + Under emtex, `eaj@acpub.duke.edu' says that + + tex386 -i ^&plain eplain \dump + +produces a format file. + diff --git a/Master/texmf-dist/doc/eplain/base/Makefile b/Master/texmf-dist/doc/eplain/base/Makefile new file mode 100644 index 00000000000..6ff999f6a73 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/Makefile @@ -0,0 +1,97 @@ +# Makefile for Eplain. This file is public domain. + +VERSION = 3.0 +SOURCES = arrow.tex btxmac.tex ifpdf.sty path.sty texnames.sty xeplain.tex +SUPPORT = add-date add-version AUTHORS ChangeLog COPYING etex.tex fix-checksum \ + INSTALL Makefile merge NEWS PROJECTS README +MANUALS = $(patsubst %,doc/%,Makefile *.texi btxdoc.bib btxdoc.tex texinfo.tex) +TESTS = $(patsubst %,test/%,*.tex *.bib *.map *.mst *.eps) +UTILS = util/idxuniq util/trimsee + +DIST_FILES = eplain.tex doc/eplain.info $(SOURCES) $(SUPPORT) $(MANUALS) \ + $(TESTS) $(UTILS) +DIST_NAME = eplain-$(VERSION) + +TAR_FLAGS = +GZIP_FLAGS = + + +.PHONY: default alldoc doc dvi pdf html info btxdoc dist +.PHONY: clean mostlyclean distclean maintainer-clean +.DELETE_ON_ERROR: + + +default: eplain.tex + +eplain.tex: merge $(SOURCES) + version=$(VERSION) ./merge + +etex.fmt: eplain.tex + rm -f etex.aux + cp /dev/null etex.aux + initex \&plain etex | grep -v '^\\font' + + +alldoc: + cd doc && make + +doc: + cd doc && make doc + +dvi: + cd doc && make dvi + +pdf: + cd doc && make pdf + +html: + cd doc && make html + +info doc/eplain.info: + cd doc && make info + +btxdoc: + cd doc && make btxdoc + +INSTALL: + cd doc && make ../INSTALL + + +dist: $(DIST_FILES) + @rm -rf $(DIST_NAME) + @echo D $(DIST_NAME) + @mkdir $(DIST_NAME) + @for file in $(DIST_FILES); do \ + echo A $(DIST_NAME)/$$file; \ + cp --parents $$file $(DIST_NAME); \ + done + @echo C $(DIST_NAME).tar.gz + @tar -c $(TAR_FLAGS) $(DIST_NAME) | gzip $(GZIP_FLAGS) > $(DIST_NAME).tar.gz + @rm -rf $(DIST_NAME) + + +define clean-cmds +rm -rf $(DIST_NAME) etex.aux etex.log +endef + +define distclean-cmds +$(clean-cmds) +rm -f etex.fmt $(DIST_NAME).tar.gz +endef + +define maintainer-clean-cmds +$(distclean-cmds) +rm -f eplain.tex +endef + +clean mostlyclean: + $(clean-cmds) + cd doc && make $@ + +distclean: + $(distclean-cmds) + cd doc && make distclean + +maintainer-clean: + $(maintainer-clean-cmds) + cd doc && make maintainer-clean diff --git a/Master/texmf-dist/doc/eplain/base/NEWS b/Master/texmf-dist/doc/eplain/base/NEWS new file mode 100644 index 00000000000..2b7f9364d7c --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/NEWS @@ -0,0 +1,87 @@ +This file records noteworthy changes. This file is public domain. + +3.0 (20 September 2005) +* Eplain now hosted at Sarovar: http://sarovar.org/projects/eplain/ +* Support for hyperlinks! +* Support for (a few) LaTeX packages, notably graphicx and color. +* Incorporated ifpdf.sty into eplain.tex [2005-08-15]. +* Many improvements of double-column macros by Stepan Kasal. +* ConTeXt compatibility; do not wipe out toc file unnecessarily to + allow multiple contents. [2005-08-12]. +* Avoid pagebreak at the xref \write before a list item. [2004-07-26] +* When under \indexproofing, allow hyphenation of indexed words and + avoid shift of page body. [2004-08-31] +* New documentation for the hyperlinks and the LaTeX package support, + many improvements of the old docs. + +2.8 (2 September 2000) +* Added a section on user-defined environments to progdef.texi and + fixed a few typos in documentation. Suggested by Paul Abrahams + [25 April 1999] +* Added a fix to a buggy double-column macro that Adam Lewenberg + introduced when attempting to fix the balancing macros. + [9 April 2000] + +2.7 (14 January 1998) +* Added the control sequence \gutterbox as a hook to add arbitrary + vertical material between columns in multi-column mode. [5 December 1997] +* Removed spurious space in \verbatim macro. [26 March 1997] +* Added some code to the multiple columns section so that when + switching from multi- to single-columns lines are not lost. + [22 September 1996]. +* Changed \smash to \smash@@ in arrow.tex to allow arrow.tex to work with + amstex. [2 March 1996]. +* Changed all dimension values in margin setting macros to 'true'; redefined + \magnification so that this works. + +2.6 (2 May 1994) +* Indexing support (in conjunction with MakeIndex). +* Generalization of .toc files for lists of figures/tables, etc. +* \commdiag and other arrow macros work again. +* \eqalignno right-justifies the first column in \leftdisplays, as in + non-leftdisplays. + +2.5 (31 March 1994) +* Do not ignore first \ref command. +* Make \verbatim (and the || feature) work again (thanks to Dorai Sitaram). + +2.4 (16 March 1994) +* \catcode of @ properly restored (reported by adam@symcom.math.uiuc.edu). +* `| ' in \verbatim argument documented (also reported by adam). +* | not hardwired as the \verbatim escape character (thanks to + dorai@cs.rice.edu). +* Defining \noarrow before eplain.tex is read omits arrow macros + (suggested by Rex Shudde <0024P@NAVPGS.BITNET> and + murray@macadam.mpce.mq.edu.au.) +* Double column macros revamped (thanks to guichard@fermat.whitman.edu) so + \singlecolumn can be invoked on the same page as \doublecolumns. + 3- and 4-column typesetting also supported. + Column ejects also supported (sort of). +* \parskip set to zero before each footnote (but not for the footnote text). +* \ref and \cite conflicts with amstex described in manual. + +2.3 (1 March 1993) + +* New macros for arbitrary cross-references. +* \iterate is redefined to allow \else in loops. +* texnames.sty uses \spacefactor1000 instead of an empty hbox to handle + \TeX at the end of a sentence. +* New macros for hooks and properties. +* \centereddisplays and \leftdisplays can be repeated, and called in any + order. +* New macros \csn and \ece to do common expansion things. + +2.2 (11 November 1992) +* New \toks register \everylist, expanded at the start of every list. +* \footnoterulewidth defined as 2in, not 2true in, thus allowing the use + of \mag after reading eplain.tex. The `2true in' was Knuth's, but I + don't know why he did it. +* \obeywhitespace works inside a \vbox. +* \boxit is \long, and uses \ehrule and \evrule. +* \writenumberedtocentry expands the chapter number, so `\the + ' can be used. +* \verbatim doesn't begin and end with \par, so it can be used in the + middle of a paragraph. +* \pathafterhook added to \path in path.sty, so macros can execute + cleanup actions. +* The \path command and friends are documented in the manual. diff --git a/Master/texmf-dist/doc/eplain/base/PROJECTS b/Master/texmf-dist/doc/eplain/base/PROJECTS new file mode 100644 index 00000000000..d24baf64c58 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/PROJECTS @@ -0,0 +1,18 @@ +This file is public domain. + +How about list processing macros like those in ``Tex in Practice''? + +In TUGboat volume 11 number 3, Amy Hendrickson gives some modified +routines for \newcount that do work inside groups. Perhaps they should +be included. + +FABROADI@CUGSBVM.BITNET suggests that the verbatim macros be extended to +allow things like: + \verbatim{first line + second line + third line} +to optionally have line numbers. + +Generalize toc files to other kinds of generated listings (e.g., figures). + +Define a spec for \ifempty and write a robust macro to implement it. diff --git a/Master/texmf-dist/doc/eplain/base/README b/Master/texmf-dist/doc/eplain/base/README new file mode 100644 index 00000000000..9ec64791292 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/README @@ -0,0 +1,50 @@ +(This file is public domain.) + +This file describes the Eplain (expanded or extended plain, take your +pick) distribution. The current version number is at the beginning and +end of eplain.tex, among other places. + +See INSTALL for installation and basic usage hints. + +eplain.tex is the macros. This file is generated (by the Unix shell +script merge) from xeplain.tex, btxmac.tex, arrow.tex, and other files. +Unless you are hacking the macros, you should have no need to regenerate +the file; just use the one that's provided. If you do regenerate it, +you will need a date program which understands the %B format (GNU date does). + +doc/eplain.texi and other .texi files in the doc directory describe the +features currently provided. If you think of additional features that +would be useful, or extensions to existing ones, see email below. + +doc/eplain.info is the Info file resulting from doc/eplain.texi and +other .texi files in the doc directory, which GNU Emacs and GNU Info +can read. You'll need makeinfo, from the GNU Texinfo distribution, to +process it, if you happen to need to. Here is the line I added to the +dir file, in the top-level Emacs info directory: + * Eplain: (eplain). Expansions to plain TeX. +See http://www.gnu.org/software/texinfo for more information about Texinfo. + +The files in the test subdirectory are of course for testing of various +features, but also provide some examples of usage. + +The util subdirectory contains some useful scripts to help with "see" +and "see also" index entries, and making index entries with +hyperlinks. + +You can get the current development sources for Eplain via CVS from +sarovar, http://sarovar.org/projects/eplain. + +Most of these macros, like most of the manual, are in the public domain. +The exceptions are the commutative diagram macros (the file arrow.tex) +and the documentation for them (the file doc/arrow.texi). Both of +arrow.tex and doc/arrow.texi are under the GNU General Public +License (see the file headers for details). + +Eplain was developed as part of the book TeX for the Impatient, +published by Addison-Wesley in 1990. It is now freely available, from +http://tug.org/ftp/tex/impatient, with a free French translation. + +Eplain is currently maintained by Oleg Katsitadze. + +email: bug-eplain@tug.org +www: http://www.tug.org/eplain diff --git a/Master/texmf-dist/doc/eplain/base/arrow.texi b/Master/texmf-dist/doc/eplain/base/arrow.texi new file mode 100644 index 00000000000..c5d4786cef3 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/arrow.texi @@ -0,0 +1,781 @@ +@c arrow.texi - documentation for Eplain's commutative diagrams. +@c Copyright (C) 1991, 1992 Steven Smith. +@c This is part of the Eplain manual. +@c +@c This file is free software; you can redistribute it and/or modify +@c it under the terms of the GNU General Public License as published by +@c the Free Software Foundation; either version 2, or (at your option) +@c any later version. +@c +@c This file is distributed in the hope that it will be useful, +@c but WITHOUT ANY WARRANTY; without even the implied warranty of +@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +@c GNU General Public License for more details. +@c +@c You should have received a copy of the GNU General Public License +@c along with this file; if not, write to the Free Software +@c Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +@c 02110-1301, USA. + +@comment \input texinfo +@comment setfilename arrow.info +@comment settitle Arrow Theoretic Diagrams + +@c Input arrow macros without altering texinfo's \catcodes. +@c Use the arrow macros in an `@iftex @tex ... @end iftex' environment. + +@iftex +@catcode`@$=3 @catcode`@%=14 @catcode`@&=4 @catcode`@#=6 +@catcode`@^=7 @catcode`@_=8 +@catcode`@"=@other @catcode`@<=@other @catcode`@>=@other +@catcode`@\=0 +\catcode`\@=\other +\input arrow +\catcode`\@=0 +@catcode`@\=@active +@catcode`@$=@other @catcode`@%=@other @catcode`@&=@other @catcode`@#=@other +@catcode`@^=@active @catcode`@_=@active +@catcode`@"=@active @catcode`@<=@active @catcode`@>=@active +@end iftex + + +@node Arrow theoretic diagrams +@chapter Arrow theoretic diagrams + +This chapter describes definitions for producing commutative diagrams. + +Steven Smith wrote this documentation (and the macros). + +@menu +* Slanted lines and vectors:: +* Commutative diagrams:: +@end menu + +@node Slanted lines and vectors +@section Slanted lines and vectors + +The macros @code{\drawline} +@findex drawline +and @code{\drawvector} +@findex drawvector +provide the capability found in @LaTeX{}'s +@cindex @LaTeX{} +@cindex picture mode +picture mode to draw slanted lines and vectors of certain directions. +Both of these macros take three arguments: two integer arguments to +specify the direction of the line or vector, and one argument to specify +its length. For example, @samp{\drawvector(-4,1)@{60pt@}} produces the +vector +@iftex +@tex +$$\vbox{\hbox{\drawvector(-4,1){60pt}}\smallskip + \hbox{$\mathop{\hbox to60pt{\leftarrowfill\hskip-5pt\rightarrowfill}} + \limits_{{\fam0 60\,pt}}$}}$$ +@end tex +@end iftex +@ifinfo + +@center (A vector in the 2d quadrant of length 60 pt appears here.) + +@end ifinfo +@cindex lines +@cindex vectors +which lies in the 2d quadrant, has a slope of minus 1/4, and a width of +60 pt. + +Note that if an @code{\hbox} is placed around @code{\drawline} or +@code{\drawvector}, then the width of the @code{\hbox} will be the +positive dimension specified in the third argument, except when a +vertical line or vector is specified, e.g., +@code{\drawline(0,1)@{1in@}}, which has zero width. If the specified +direction lies in the 1st or 2d quadrant (e.g., @code{(1,1)} or +@code{(-2,3)}), then the @code{\hbox} will have positive height and zero +depth. Conversely, if the specified direction lies in the 3d or 4th +quadrant (e.g., @code{(-1,-1)} or @code{(2,-3)}), then the @code{\hbox} +will have positive depth and zero height. + +There are a finite number of directions that can be specified. For +@code{\drawline}, the absolute value of each integer defining the +direction must be less than or equal to six, i.e., @code{(7,-1)} is +incorrect, but @code{(6,-1)} is acceptable. For @code{\drawvector}, the +absolute value of each integer must be less than or equal to four. +Furthermore, the two integers cannot have common divisors; therefore, if +a line with slope 2 is desired, say @code{(2,1)} instead of +@code{(4,2)}. Also, specify @code{(1,0)} instead of, say, @code{(3,0)} +for horizontal lines and likewise for vertical lines. + +Finally, these macros depend upon the @LaTeX{} font @code{line10}. If +your site doesn't have this font, ask your system administrator to get +it. Future enhancements will include macros to draw dotted lines and +dotted vectors of various directions. + + +@node Commutative diagrams +@section Commutative diagrams + +@cindex commutative diagrams + +The primitive commands @code{\drawline} and @code{\drawvector} can be +used to typeset arrow theoretic diagrams. This section describes (1) +macros to facilitate typesetting arrows and morphisms, and (2) macros to +facilitate the construction of commutative diagrams. All macros +described in this section must be used in math mode. + +@menu +* Arrows and morphisms:: +* Construction of commutative diagrams:: +* Commutative diagram parameters:: +@end menu + +@node Arrows and morphisms +@subsection Arrows and morphisms +@cindex arrows +@cindex morphisms + +The macros @code{\mapright} and @code{\mapleft} produce right and left +@findex mapright +@findex mapleft +pointing arrows, respectively. Use superscript (@code{^}) to place a +morphism above the arrow, e.g., @samp{\mapright^\alpha}; use subscript +(@code{_}) to place a morphism below the arrow, e.g., +@samp{\mapright_@{\tilde l@}}. Superscripts and subscripts may be used +simulataneously, e.g., @samp{\mapright^\pi_@{\rm epimor.@}}. + +Similarly, the macros @code{\mapup} and @code{\mapdown} produce up and +@findex mapup +@findex mapdown +down pointing arrows, respectively. Use @code{\rt} +@findex rt +to place a morphism to the right of the arrow, e.g., @samp{\mapup\rt@{\rm +id@}}; use @code{\lft} +@findex lft +to place a morphism to the left of the arrow, e.g., @samp{\mapup\lft\omega}. +@code{\lft} and @code{\rt} may be used simultaneously, e.g., +@samp{\mapdown\lft\pi\rt@{\rm monomor.@}}. + +Slanted arrows are produced by the macro @code{\arrow}, which takes +@findex arrow +a direction argument (e.g., @samp{\arrow(3,-4)}). Use @code{\rt} and +@code{\lft} to place morphisms to the right and left, respectively, of +the arrow. A slanted line (no arrowhead) is produced with the macro +@code{\sline}, +@findex sline +whose syntax is identical to that of @code{\arrow}. + +The length of these macros is predefined by the default @TeX{} +dimensions @code{\harrowlength}, +@findex harrowlength +for horizontal arrows (or lines), +@code{\varrowlength}, +@findex varrowlength +for vertical arrows (or lines), and +@code{\sarrowlength}, +@findex sarrowlength +for slanted arrows (or lines). To change any of these dimensions, say, +e.g., @samp{\harrowlength=40pt}. As with all other @TeX{} dimensions, +the change may be as global or as local as you like. Furthermore, the +placement of morphisms on the arrows is controlled by the dimensions +@code{\hmorphposn}, +@findex hmorphposn +@code{\vmorphposn}, +@findex vmorphposn +and @code{\morphdist}. +@findex morphdist +The first two dimensions control the horizontal and vertical position of +the morphism from its default position; the latter dimension controls +the distance of the morphism from the arrow. If you have more than one +morphism per arrow (i.e., a @code{^}/@code{_} or @code{\lft}/@code{\rt} +construction), use the parameters +@code{\hmorphposnup}, +@findex hmorphposnup +@code{\hmorphposndn}, +@findex hmorphposndn +@code{\vmorphposnup}, +@findex vmorphposnup +@code{\vmorphposndn}, +@findex vmorphposndn +@code{\hmorphposnrt}, +@findex hmorphposnrt +@code{\hmorphposnlft}, +@findex hmorphposnlft +@code{\vmorphposnrt}, +@findex vmorphposnrt +and @code{\vmorphposnlft}. +@findex vmorphposnlft +The default values of all these dimensions are provided in the section +on parameters that follows below. + +There is a family of macros to produce horizontal lines, arrows, and +adjoint arrows. The following macros produce horizontal maps and have +the same syntax as @code{\mapright}: + +@table @code + +@item \mapright +@findex mapright +@code{$X\mapright Y$} +@iftex +@tex +$\equiv$ $\harrowlength=20ptX\mapright Y$. +@end tex +@end iftex +@ifinfo += (a right arrow). +@end ifinfo + +@item \mapleft +@findex mapleft +@code{$X\mapleft Y$} +@iftex +@tex +$\equiv$ $\harrowlength=20ptX\mapleft Y$. +@end tex +@end iftex +@ifinfo += (a left arrow). +@end ifinfo + +@item \hline +@findex hline +@code{$X\hline Y$} +@iftex +@tex +$\equiv$ $\harrowlength=20ptX\hline Y$. +@end tex +@end iftex +@ifinfo += (horizontal line) +@end ifinfo + +@ignore +@item \dothline +@findex dothline +(dotted horizontal line) {@bf Unimplemented.} +@end ignore + +@item \bimapright +@findex bimapright +@code{$X\bimapright Y$} +@iftex +@tex +$\equiv$ $\harrowlength=20ptX\bimapright Y$. +@end tex +@end iftex +@ifinfo += (two right arrows). +@end ifinfo + +@item \bimapleft +@findex bimapleft +@code{$X\bimapleft Y$} +@iftex +@tex +$\equiv$ $\harrowlength=20ptX\bimapleft Y$. +@end tex +@end iftex +@ifinfo += (two left arrows) +@end ifinfo + +@item \adjmapright +@findex adjmapright +@code{$X\adjmapright Y$} +@iftex +@tex +$\equiv$ $\harrowlength=20ptX\adjmapright Y$. +@end tex +@end iftex +@ifinfo += (two adjoint arrows; left over right) +@end ifinfo + +@item \adjmapleft +@findex adjmapleft +@code{$X\adjmapleft Y$} +@iftex +@tex +$\equiv$ $\harrowlength=20ptX\adjmapleft Y$. +@end tex +@end iftex +@ifinfo += (two adjoint arrows; right over left) +@end ifinfo + +@item \bihline +@findex bihline +@code{$X\bihline Y$} +@iftex +@tex +$\equiv$ $\harrowlength=20ptX\bihline Y$. +@end tex +@end iftex +@ifinfo += (two horizontal lines) +@end ifinfo +@end table + +There is also a family of macros to produce vertical lines, arrows, and +adjoint arrows. The following macros produce vertical maps and have +the same syntax as @code{\mapdown}: + +@table @code + +@item \mapdown +@findex mapdown +(a down arrow) + +@item \mapup +@findex mapup +(an up arrow) + +@item \vline +@findex vline +(vertical line) + +@ignore +@item \dotvline +@findex dotvline +(dotted vertical line) {@bf Unimplemented.} +@end ignore + +@item \bimapdown +@findex bimapdown +(two down arrows) + +@item \bimapup +@findex bimapup +(two up arrows) + +@item \adjmapdown +@findex adjmapdown +(two adjoint arrows; down then up) + +@item \adjmapup +@findex adjmapup +(two adjoint arrows; up then down) + +@item \bivline +@findex bivline +(two vertical lines) +@end table + +Finally, there is a family of macros to produce slanted lines, arrows, +and adjoint arrows. The following macros produce slanted maps and have +the same syntax as @code{\arrow}: + +@table @code + +@item \arrow +@findex arrow +(a slanted arrow) + +@item \sline +@findex sline +(a slanted line) + +@item \biarrow +@findex biarrow +(two straight arrows) + +@item \adjarrow +@findex adjarrow +(two adjoint arrows) + +@item \bisline +@findex bisline +(two straight lines) + +@end table + +The width between double arrows is controlled by the parameter +@code{\channelwidth}. +@findex channelwidth +The parameters @code{\hchannel} and @code{\vchannel}, if nonzero, +override @code{\channelwidth} by controlling the horizontal and vertical +shifting from the first arrow to the second. + +There are no adornments on these arrows to distinguish inclusions from +epimorphisms from monomorphisms. Many texts, such as Lang's book +@cite{Algebra}, use as a tasteful alternative the symbol `inc' (in roman) next +to an arrow to denote inclusion. +@cindex Lang, Serge + +Future enhancements will include a mechanism to draw curved arrows +found in, e.g., the Snake Lemma, by employing a version of the +@code{\path} macros of Appendix D of @cite{The @TeX{}book}. +@cindex Snake Lemma + + +@node Construction of commutative diagrams +@subsection Construction of commutative diagrams + +There are two approaches to the construction of commutative diagrams +described here. The first approach, and the simplest, treats +commutative diagrams like fancy matrices, as Knuth does in Exercise +18.46 of @cite{The @TeX{}book}. This case is covered by the macro +@code{\commdiag}, +@findex commdiag +which is an altered version of the Plain @TeX{} macro @code{\matrix}. +@findex matrix +An example suffices to demonstrate this macro. The following +commutative diagram (illustrating the covering homotopy property; Bott +and Tu, @cite{Differential Forms in Algebraic Topology}) +@cindex Bott, Raoul +@cindex Tu, Loring W. +@cindex covering homotopy property +@iftex +@tex +$$\commdiag{Y&\mapright^f&E\cr \mapdown&\arrow(3,2)\lft{f_t}&\mapdown\cr +Y\times I&\mapright^{\bar f_t}&X}$$ +@end tex +@end iftex +@ifinfo + +@center (A commutative diagram appears here in the printed output.) + +@end ifinfo +is produced with the code + +@example +$$\commdiag@{Y&\mapright^f&E\cr \mapdown&\arrow(3,2)\lft@{f_t@}&\mapdown\cr +Y\times I&\mapright^@{\bar f_t@}&X@}$$ +@end example + +Of course, the parameters may be changed to produce a different effect. +The following commutative diagram (illustrating the universal mapping +property; Warner, @cite{Foundations of Differentiable Manifolds and Lie +Groups}) +@cindex Warner, Frank W. +@cindex universal mapping property +@iftex +@tex +$$\varrowlength=20pt +\commdiag{V\otimes W\cr \mapup\lft\phi&\arrow(3,-1)\rt{\tilde l}\cr +V\times W&\mapright^l&U\cr}$$ +@end tex +@end iftex +@ifinfo + +@center (A commutative diagram appears here in the printed output.) + +@end ifinfo +is produced with the code + +@example +$$\varrowlength=20pt +\commdiag@{V\otimes W\cr \mapup\lft\phi&\arrow(3,-1)\rt@{\tilde l@}\cr +V\times W&\mapright^l&U\cr@}$$ +@end example + +A diagram containing isosceles triangles is achieved by placing the apex +of the triangle in the center column, as shown in the example +(illustrating all constant minimal realizations of a linear system; +Brockett, @cite{Finite Dimensional Linear Systems}) +@cindex Brockett, Roger W. +@cindex minimal realizations +@cindex linear systems theory +@iftex +@tex +$$\sarrowlength=.42\harrowlength +\commdiag{&R^m\cr &\arrow(-1,-1)\lft{\fam6 B}\quad \arrow(1,-1)\rt{\fam6 G}\cr +R^n&\mapright^{\fam6 P}&R^n\cr +\mapdown\lft{e^{{\fam6 A}t}}&&\mapdown\rt{e^{{\fam6 F}t}}\cr +R^n&\mapright^{\fam6 P}&R^n\cr +&\arrow(1,-1)\lft{\fam6 C}\quad \arrow(-1,-1)\rt{\fam6 H}\cr +&R^q\cr}$$ +@end tex +@end iftex +@ifinfo + +@center (A commutative diagram appears here in the printed output.) + +@end ifinfo +which is produced with the code + +@example +$$\sarrowlength=.42\harrowlength +\commdiag@{&R^m\cr &\arrow(-1,-1)\lft@{\bf B@}\quad \arrow(1,-1)\rt@{\bf G@}\cr +R^n&\mapright^@{\bf P@}&R^n\cr +\mapdown\lft@{e^@{@{\bf A@}t@}@}&&\mapdown\rt@{e^@{@{\bf F@}t@}@}\cr +R^n&\mapright^@{\bf P@}&R^n\cr +&\arrow(1,-1)\lft@{\bf C@}\quad \arrow(-1,-1)\rt@{\bf H@}\cr +&R^q\cr@}$$ +@end example + +Other commutative diagram examples appear in the file +@code{commdiags.tex}, which is distributed with this package. + +In these examples the arrow lengths and line slopes were carefully +chosen to blend with each other. In the first example, the default +settings for the arrow lengths are used, but a direction for the arrow +must be chosen. The ratio of the default horizontal and vertical arrow +lengths is approximately the golden mean +@cindex golden mean +@iftex +@tex +$\gamma=1.618\ldots$; +@end tex +@end iftex +@ifinfo +gamma=1.618...; +@end ifinfo +@cindex golden mean +the arrow direction closest to this mean is @code{(3,2)}. In the second +example, a slope of +@iftex +@tex +$-1/3$ +@end tex +@end iftex +@ifinfo +-1/3 +@end ifinfo +is desired and the default horizontal arrow length is 60 pt; therefore, +choose a vertical arrow length of 20 pt. You may affect the interline +glue settings of @code{\commdiag} by redefining the macro +@code{\commdiagbaselines}. +@findex commdiagbaselines +(cf@. Exercise 18.46 of @cite{The @TeX{}book} and the section on +parameters below.) + +The width, height, and depth of all morphisms are hidden so that the +morphisms' size do not affect arrow positions. This can cause a large +morphism at the top or bottom of a diagram to impinge upon the text +surrounding the diagram. To overcome this problem, use @TeX{}'s +@code{\noalign} primitive to insert a @code{\vskip} immediately above or +below the offending line, e.g., +@samp{$$\commdiag@{\noalign@{\vskip6pt@}X&\mapright^\int&Y\cr ...@}}. + +The macro @code{\commdiag} is too simple to be used for more complicated +diagrams, which may have intersecting or overlapping arrows. A second +approach, borrowed from Francis Borceux's @cite{Diagram} macros for +@LaTeX{}, treats the commutative diagram like a grid of identically +shaped boxes. To compose the commutative diagram, first draw an equally +spaced grid, e.g., +@cindex grid +@cindex Borceux, Francis +@cindex Diagram, macros for LaTeX +@iftex +@tex +$$\def\grid{\cdot&\cdot&\cdot&\cdot&\cdot&\cdot\cr} +\matrix{\grid\grid\grid\grid}$$ +@end tex +@end iftex +@ifinfo + +@center . . . . . . +@center . . . . . . +@center . . . . . . +@center . . . . . . + +@end ifinfo +on a piece of scratch paper. Then draw each element (vertices and +arrows) of the commutative diagram on this grid, centered at each +grid point. Finally, use the macro @code{\gridcommdiag} +@findex gridcommdiag +to implement your design as a @TeX{} alignment. For example, the cubic +diagram +@cindex cube +@iftex +@tex +$$\harrowlength=48pt \varrowlength=48pt \sarrowlength=20pt +\def\cross#1#2{\setbox0=\hbox{$#1$}% + \hbox to\wd0{\hss\hbox{$#2$}\hss}\llap{\unhbox0}} +\gridcommdiag{&&B&&\mapright^b&&D\cr +&\arrow(1,1)\lft a&&&&\arrow(1,1)\lft d\cr +A&&\cross{\hmorphposn=12pt\mapright^c}{\vmorphposn=-12pt\mapdown\lft f} +&&C&&\mapdown\rt h\cr\cr +\mapdown\lft e&&F&&\cross{\hmorphposn=-12pt\mapright_j} +{\vmorphposn=12pt\mapdown\rt g}&&H\cr +&\arrow(1,1)\lft i&&&&\arrow(1,1)\rt l\cr +E&&\mapright_k&&G\cr}$$ +@end tex +@end iftex +@ifinfo + +@center (A commutative diagram appears here.) + +@end ifinfo +that appears in Francis Borceux's documentation can be implemented on +a 7 by 7 grid, and is achieved with the code + +@example +$$\harrowlength=48pt \varrowlength=48pt \sarrowlength=20pt +\def\cross#1#2@{\setbox0=\hbox@{$#1$@}% + \hbox to\wd0@{\hss\hbox@{$#2$@}\hss@}\llap@{\unhbox0@}@} +\gridcommdiag@{&&B&&\mapright^b&&D\cr +&\arrow(1,1)\lft a&&&&\arrow(1,1)\lft d\cr +A&&\cross@{\hmorphposn=12pt\mapright^c@}@{\vmorphposn=-12pt\mapdown\lft f@} +&&C&&\mapdown\rt h\cr\cr +\mapdown\lft e&&F&&\cross@{\hmorphposn=-12pt\mapright_j@} +@{\vmorphposn=12pt\mapdown\rt g@}&&H\cr +&\arrow(1,1)\lft i&&&&\arrow(1,1)\rt l\cr +E&&\mapright_k&&G\cr@}$$ +@end example + +The dimensions @code{\hgrid} and @code{\vgrid} +@findex hgrid +@findex vgrid +control the horizontal and vertical spacing of the grid used by +@code{\gridcommdiag}. The default setting for both of these dimensions +is 15 pt. Note that in the example of the cube the arrow lengths must +be adjusted so that the arrows overlap into neighboring boxes by the +desired amount. Hence, the @code{\gridcommdiag} method, albeit more +powerful, is less automatic than the simpler @code{\commdiag} method. +Furthermore, the ad hoc macro @code{\cross} is introduced to allow the +effect of overlapping arrows. Finally, note that the positions of four +of the morphisms are adjusted by setting @code{\hmorphposn} and +@code{\vmorphposn}. + +One is not restricted to a square grid. For example, the proof of +Zassenhaus's Butterfly Lemma can be illustrated by the diagram (appearing +in Lang's book @cite{Algebra}) +@cindex Zassenhaus, Hans +@cindex Lang, Serge +@cindex Butterfly Lemma +@iftex +@tex +$$\hgrid=16pt \vgrid=8pt \sarrowlength=32pt +\def\cross#1#2{\setbox0=\hbox{$#1$}% + \hbox to\wd0{\hss\hbox{$#2$}\hss}\llap{\unhbox0}} +\def\l#1{\llap{$#1$\hskip.5em}} +\def\r#1{\rlap{\hskip.5em$#1$}} +\gridcommdiag{&&U&&&&V\cr &&\bullet&&&&\bullet\cr +&&\sarrowlength=16pt\sline(0,1)&&&&\sarrowlength=16pt\sline(0,1)\cr +&&\l{u(U\cap V)}\bullet&&&&\bullet\r{(U\cap V)v}\cr +&&&\sline(2,-1)&&\sline(2,1)\cr +&&\cross{=}{\sline(0,1)}&&\bullet&&\cross{=}{\sline(0,1)}\cr\cr +&&\l{^{\textstyle u(U\cap v)}}\bullet&&\cross{=}{\sline(0,1)}&& + \bullet\r{^{\textstyle(u\cap V)v}}\cr +&\sline(2,1)&&\sline(2,-1)&&\sline(2,1)&&\sline(2,-1)\cr +\l{u}\bullet&&&&\bullet&&&&\bullet\r{v}\cr +&\sline(2,-1)&&\sline(2,1)&&\sline(2,-1)&&\sline(2,1)\cr +&&\bullet&&&&\bullet\cr &&u\cap V&&&&U\cap v\cr}$$ +@end tex +@end iftex +@ifinfo + +@center (A commutative diagram appears here.) + +@end ifinfo +This diagram may be implemented on a 9 by 12 grid with an aspect ratio +of 1/2, and is set with the code + +@example +$$\hgrid=16pt \vgrid=8pt \sarrowlength=32pt +\def\cross#1#2@{\setbox0=\hbox@{$#1$@}% + \hbox to\wd0@{\hss\hbox@{$#2$@}\hss@}\llap@{\unhbox0@}@} +\def\l#1@{\llap@{$#1$\hskip.5em@}@} +\def\r#1@{\rlap@{\hskip.5em$#1$@}@} +\gridcommdiag@{&&U&&&&V\cr &&\bullet&&&&\bullet\cr +&&\sarrowlength=16pt\sline(0,1)&&&&\sarrowlength=16pt\sline(0,1)\cr +&&\l@{u(U\cap V)@}\bullet&&&&\bullet\r@{(U\cap V)v@}\cr +&&&\sline(2,-1)&&\sline(2,1)\cr +&&\cross@{=@}@{\sline(0,1)@}&&\bullet&&\cross@{=@}@{\sline(0,1)@}\cr\cr +&&\l@{^@{\textstyle u(U\cap v)@}@}\bullet&&\cross@{=@}@{\sline(0,1)@}&& + \bullet\r@{^@{\textstyle(u\cap V)v@}@}\cr +&\sline(2,1)&&\sline(2,-1)&&\sline(2,1)&&\sline(2,-1)\cr +\l@{u@}\bullet&&&&\bullet&&&&\bullet\r@{v@}\cr +&\sline(2,-1)&&\sline(2,1)&&\sline(2,-1)&&\sline(2,1)\cr +&&\bullet&&&&\bullet\cr &&u\cap V&&&&U\cap v\cr@}$$ +@end example + +Again, the construction of this diagram requires careful choices for the +arrow lengths and is facilitated by the introduction of the ad hoc +macros @code{\cross}, @code{\r}, and @code{\l}. Note also that +superscripts were used to adjust the position of the vertices +@iftex +@tex +$u(U\cap v)$ and $(u\cap V)v$. +@end tex +@end iftex +@ifinfo +u(U intersection v) and (u intersection V)v. +@end ifinfo +Many diagrams may be typeset with the predefined macros that appear +here; however, ingenuity is often required to handle special cases. + +@node Commutative diagram parameters +@subsection Commutative diagram parameters + +The following is a list describing the parameters used in the +commutative diagram macros. These dimensions may be changed globally or +locally. + +@table @code +@item \harrowlength +@findex harrowlength +(Default: 60 pt) The length of right or left arrows. + +@item \varrowlength +@findex varrowlength +(Default: 0.618@code{\harrowlength}) The length of up or down +arrows. + +@item \sarrowlength +@findex sarrowlength +(Default: 60 pt) The horizontal length of slanted arrows. + +@item \hmorphposn +@findex hmorphposn +(Default: 0 pt) The horizontal position of the morphism with +respect to its default position. There are also the dimensions +@code{\hmorphposnup}, +@findex hmorphposnup +@code{\hmorphposndn}, +@findex hmorphposndn +@code{\hmorphposnrt}, +@findex hmorphposnrt +and @code{\hmorphposnlft} +@findex hmorphposnlft +for @code{^}/@code{_} or @code{\lft}/@code{\rt} constructions. + +@item \vmorphposn +@findex vmorphposn +(Default: 0 pt) The vertical position of the morphism with +respect to its default position. There are also the dimensions +@code{\vmorphposnup}, +@findex vmorphposnup +@code{\vmorphposndn}, +@findex vmorphposndn +@code{\vmorphposnrt}, +@findex vmorphposnrt +and @code{\vmorphposnlft} +@findex vmorphposnlft +for @code{^}/@code{_} or @code{\lft}/@code{\rt} constructions. + +@item \morphdist +@findex morphdist +(Default: 4 pt) The distance of morphisms from slanted lines +or arrows. + +@item \channelwidth +@findex channelwidth +(Default: 3 pt) The distance between double lines or arrows. + +@item \hchannel, \vchannel +@findex hchannel +@findex vchannel +(Defaults: 0 pt) Overrides @code{\channelwidth}. The +horizontal and vertical shifts between double lines or arrows. + +@item \commdiagbaselines +@findex commdiagbaselines +(Default: @code{\baselineskip=15pt +\lineskip=3pt +\lineskiplimit=3pt }) +The parameters used by @code{\commdiag} for setting interline glue. + +@item \hgrid +@findex hgrid +(Default: 15 pt) The horizontal spacing of the grid used by +@code{\gridcommdiag}. + +@item \vgrid +@findex vgrid +(Default: 15 pt) The vertical spacing of the grid used by +@code{\gridcommdiag}. + +@end table + +@comment bye diff --git a/Master/texmf-dist/doc/eplain/base/btxdoc.bib b/Master/texmf-dist/doc/eplain/base/btxdoc.bib new file mode 100644 index 00000000000..4eaf3eddc56 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/btxdoc.bib @@ -0,0 +1,90 @@ +Copyright (C) 1988, all rights reserved. + +@COMMENT(You may put a comment in a `comment' command, + the way you would with SCRIBE.) + +Or you may dispense with the command and simply give the comment, +as long as it's not within an entry. + +If you really want to put a comment inside an entry, simply +make up a never-to-be-used field. + +@FAKE-ENTRY + {fake-database-key, + never-to-be-used-field = "Even if this were a real entry, + I could still have a comment inside an entry + by making up a fake field" + } + +@string (SCRIBE-NOTE = {Chapter twelve and appendices E8 through E10 deal + with bibliographies}) + +The next entry shows some of the syntactically legal things that +those with the inclination may use.@ + +MaNuAl (scribe, + TITLE="Scribe Document Production System + + + User Manual", + ORGANIZATION = {Unilogic,}#" Ltd"# {. + }, + ADDRESS = "Pittsburgh", + MONTH +=aPR + ,YEAR=1984, + note = scribe-note, +) May the inclination not be with you. + + +@MISC{prime-number-theorem, + author = "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin", + note = "A strong form of the prime number theorem, 19th century" } + +@INBOOK{chicago, + title = "The Chicago Manual of Style", + publisher = "University of Chicago Press", + edition = "Thirteenth", + year = 1982, + pages = "400--401", + key = "Chicago" } + +@BOOK{texbook, + author = "Donald E. Knuth", + title= "The {{\TeX}book}", + publisher = "Addison-Wesley", + year = 1984 } + +@BOOK{latex, + author = "Leslie Lamport", + title = "{\LaTeX \rm:} {A} Document Preparation System", + publisher = "Addison-Wesley", + year = 1986 } + +@UNPUBLISHED{btxdoc, + author = "Oren Patashnik", + title = "{{\BibTeX ing}}", + note = "Documentation for general {\BibTeX} users", + month = "8~" # feb, + year = 1988 } + +@UNPUBLISHED{btxhak, + author = "Oren Patashnik", + title = "Designing {\BibTeX} Styles", + note = "The part of \BibTeX's documentation + that's not meant for general users", + month = "8~" # feb, + year = 1988 } + +@BOOK{strunk-and-white, + author = "Strunk, Jr., William and E. B. White", + title = "The Elements of Style", + publisher = "Macmillan", + edition = "Third", + year = 1979 } + +@BOOK{van-leunen, + title = "A Handbook for Scholars", + author = "Mary-Claire van Leunen", + publisher = "Knopf", + year = 1979 } diff --git a/Master/texmf-dist/doc/eplain/base/btxdoc.tex b/Master/texmf-dist/doc/eplain/base/btxdoc.tex new file mode 100644 index 00000000000..52723e08b69 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/btxdoc.tex @@ -0,0 +1,1117 @@ +% Copyright (C) 1988, all rights reserved. + +\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em + T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}} + +\title{B\kern-.05em{\large I}\kern-.025em{\large B}\kern-.08em\TeX ing} +\author{Oren Patashnik} +\date{February 8, 1988} + +\documentstyle{article} +\begin{document} + +\maketitle + +\section{Overview} + +[This document will be expanded when \BibTeX\ version 1.00 comes out. +Please report typos, omissions, inaccuracies, +and especially unclear explanations +to me ({\tt patashnik@SCORE.STANFORD.EDU}). +Suggestions for improvements are wanted and welcome.] + +This documentation, for \BibTeX\ version 0.99b, +is meant for general \BibTeX\ users; +bibliography-style designers should read this document +and then read ``Designing \BibTeX\ Styles''~\cite{btxhak}, +which is meant for just them. + +This document has three parts: +Section~\ref{differences} +describes the differences between versions 0.98i and 0.99b +of \BibTeX\ and between the corresponding versions of the standard styles; +Section~\ref{latex-appendix} +updates Appendix~B.2 of the \LaTeX\ book~\cite{latex}; +and Section~\ref{odds-and-ends} +gives some general and specific tips +that aren't documented elsewhere. +It's assumed throughout that you're familiar with +the relevant sections of the \LaTeX\ book. + +This documentation also serves as sample input to help +\BibTeX\ implementors get it running. +For most documents, this one included, you produce the reference list by: +running \LaTeX\ on the document (to produce the {\tt aux} file(s)), +then running \BibTeX\ (to produce the {\tt bbl} file), +then \LaTeX\ twice more (first to find the information in the {\tt bbl} file +and then to get the forward references correct). +In very rare circumstances you may need an extra \BibTeX/\LaTeX\ run. + +\BibTeX\ version 0.99b should be used with \LaTeX\ version 2.09, +for which the closed bibliography format is the default; +to get the open format, use the optional document style {\tt openbib} +(in an open format there's a line break between major blocks of a +reference-list entry; in a closed format the blocks run together).] + +Note: \BibTeX\ 0.99b is not compatible with the old style files; +nor is \BibTeX\ 0.98i compatible with the new ones +(the new \BibTeX, however, is compatible with old database files). + +Note for implementors: \BibTeX\ provides logical-area names +\hbox{\tt TEXINPUTS:} for bibliography-style files and +\hbox{\tt TEXBIB:} for database files it can't otherwise find. + + +\section{Changes} +\label{differences} + +This section describes the differences between +\BibTeX\ versions 0.98i and 0.99b, and also between +the corresponding standard styles. +There were a lot of differences; +there will be a lot fewer between 0.99 and 1.00. + + +\subsection{New \BibTeX\ features} +\label{features} + +The following list explains \BibTeX's new features and how to use them. +\begin{enumerate} + +\item +With the single command `\hbox{\verb|\nocite{*}|}' +you can now include in the reference list +every entry in the database files, without having to explicitly +\verb|\cite| or \hbox{\verb|\nocite|} each entry. +Giving this command, in essence, +\hbox{\verb|\nocite|}s +all the enties in the database, in database order, +at the very spot in your document +where you give the command. + +\item +\label{concat} +You can now have as a field value (or an {\tt @STRING} definition) +the concatenation of several strings. +For example if you've defined +\begin{verbatim} + @STRING( WGA = " World Gnus Almanac" ) +\end{verbatim} +then it's easy to produce nearly-identical +{\tt title} fields for different entries: +\begin{verbatim} + @BOOK(almanac-66, + title = 1966 # WGA, + . . . + @BOOK(almanac-67, + title = 1967 # WGA, +\end{verbatim} +and so on. Or, you could have a field like +\begin{verbatim} + month = "1~" # jan, +\end{verbatim} +which would come out something like +`\hbox{\verb|1~January|}' or `\hbox{\verb|1~Jan.|}' in the {\tt bbl} file, +depending on how your bibliography style defines +the {\tt jan} abbreviation. +You may concatenate as many strings as you like +(except that there's a limit to the overall length +of the resulting field); +just be sure to put the concatenation character `{\tt\#}'$\!$, +surrounded by optional spaces or newlines, +between each successive pair of strings. + +\item +\BibTeX\ has a new cross-referencing feature, +explained by an example. +Suppose you say \hbox{\verb|\cite{no-gnats}|} in your document, +and suppose you have these two entries in your database file: +\begin{verbatim} + @INPROCEEDINGS(no-gnats, + crossref = "gg-proceedings", + author = "Rocky Gneisser", + title = "No Gnats Are Taken for Granite", + pages = "133-139") + . . . + @PROCEEDINGS(gg-proceedings, + editor = "Gerald Ford and Jimmy Carter", + title = "The Gnats and Gnus 1988 Proceedings", + booktitle = "The Gnats and Gnus 1988 Proceedings") +\end{verbatim} +Two things happen. +First, the special \hbox{\tt crossref} field tells \BibTeX\ +that the \hbox{\tt no-gnats} entry should inherit +any fields it's missing from +the entry it cross references, \hbox{\tt gg-proceedings}. +In this case it in inherits the two fields +\hbox{\tt editor} and \hbox{\tt booktitle}. +Note that, in the standard styles at least, +the \hbox{\tt booktitle} field is irrelevant +for the \hbox{\tt PROCEEDINGS} entry type. +The \hbox{\tt booktitle} field appears here +in the \hbox{\tt gg-proceedings} entry +only so that the entries that cross reference it +may inherit the field. +No matter how many papers from this meeting exist in the database, +this \hbox{\tt booktitle} field need only appear once. + +The second thing that happens: +\BibTeX\ automatically puts the entry \hbox{\tt gg-proceedings} +into the reference list if it's cross +referenced by two or more entries that you +\verb|\cite| or \hbox{\verb|\nocite|}, +even if you don't \verb|\cite| or \hbox{\verb|\nocite|} +the \hbox{\tt gg-proceedings} entry itself. +So \hbox{\tt gg-proceedings} will automatically appear +on the reference list if one other entry +besides \hbox{\tt no-gnats} cross references it. + +To guarantee that this scheme works, however, +a cross-referenced entry must occur later in the database files +than every entry that cross-references it. +Thus, putting all cross-referenced entries at the end makes sense. +(Moreover, you may not reliably nest cross references; +that is, a cross-referenced entry may +not itself reliably cross reference an entry. +This is almost certainly not something you'd +want to do, though.) + +One final note: +This cross-referencing feature is completely unrelated +to the old \BibTeX's cross referencing, +which is still allowed. +Thus, having a field like +\begin{verbatim} + note = "Jones \cite{jones-proof} improves the result" +\end{verbatim} +is not affected by the new feature. + +\item +\BibTeX\ now handles accented characters. +For example if you have an entry with the two fields +\begin{verbatim} + author = "Kurt G{\"o}del", + year = 1931, +\end{verbatim} +and if you're using the \hbox{\tt alpha} bibliography style, +then \BibTeX\ will construct the label +\hbox{[G{\"o}d31]} for this entry, which is what you'd want. +To get this feature to work you must place the entire accented +character in braces; +in this case either \hbox{\verb|{\"o}|} +or \hbox{\verb|{\"{o}}|} will do. +Furthermore these braces must not themselves be +enclosed in braces (other than the ones that might delimit +the entire field or the entire entry); +and there must be a backslash +as the very first character inside the braces. +Thus neither \hbox{\verb|{G{\"{o}}del}|} +nor \hbox{\verb|{G\"{o}del}|} will work for this example. + +This feature handles all the accented characters and +all but the nonbackslashed foreign symbols found in Tables +3.1 and~3.2 of the \LaTeX\ book. +This feature behaves similarly for ``accents'' you might define; +we'll see an example shortly. +For the purposes of counting letters in labels, +\BibTeX\ considers everything contained inside the braces +as a single letter. + +\item +\BibTeX\ also handles hyphenated names. +For example if you have an entry with +\begin{verbatim} + author = "Jean-Paul Sartre", +\end{verbatim} +and if you're using the \hbox{\tt abbrv} style, +then the result is `J.-P. Sartre'$\!$. + +\item +\label{preamble} +There's now an \hbox{\verb|@PREAMBLE|} command +for the database files. +This command's syntax is just like \hbox{\verb|@STRING|}'s, +except that there is no name or equals-sign, just the string. +Here's an example: +\begin{verbatim} + @PREAMBLE{ "\newcommand{\noopsort}[1]{} " + # "\newcommand{\singleletter}[1]{#1} " } +\end{verbatim} +(note the use of concatenation here, too). +The standard styles output whatever information you give this command +(\LaTeX\ macros most likely) directly to the {\tt bbl} file. +We'll look at one possible use of this command, +based on the \hbox{\verb|\noopsort|} command just defined. + +The issue here is sorting (alphabetizing). +\BibTeX\ does a pretty good job, +but occasionally weird circumstances conspire to confuse \BibTeX: +Suppose that you have entries in your database for +the two books in a two-volume set by the same author, +and that you'd like volume~1 to appear +just before volume~2 in your reference list. +Further suppose that there's now a second edition of volume~1, +which came out in 1973, say, +but that there's still just one edition of volume~2, +which came out in 1971. +Since the {\tt plain} standard style +sorts by author and then year, +it will place volume~2 first +(because its edition came out two years earlier) +unless you help \BibTeX. +You can do this by using the {\tt year} fields below +for the two volumes: +\begin{verbatim} + year = "{\noopsort{a}}1973" + . . . + year = "{\noopsort{b}}1971" +\end{verbatim} +According to the definition of \hbox{\verb|\noopsort|}, +\LaTeX\ will print nothing but the true year for these fields. +But \BibTeX\ will be perfectly happy pretending that +\hbox{\verb|\noopsort|} specifies some fancy accent +that's supposed to adorn the `a' and the~`b'; +thus when \BibTeX\ sorts it will pretend that +`a1973' and `b1971' are the real years, +and since `a' comes before~`b'$\!$, it will place volume~1 before volume~2, +just what you wanted. +By the way, if this author has any other works included +in your database, you'd probably want to use instead something like +\hbox{\verb|{\noopsort{1968a}}1973|} and +\hbox{\verb|{\noopsort{1968b}}1971|}, +so that these two books would come out in a reasonable spot +relative to the author's other works +(this assumes that 1968 results in a reasonable spot, +say because that's when the first edition of volume~1 appeared). + +There is a limit to the number of \hbox{\verb|@PREAMBLE|} commands +you may use, but you'll never exceed this limit if +you restrict yourself to one per database file; +this is not a serious restriction, +given the concatenation feature (item~\ref{concat}). + +\item +\BibTeX's sorting algorithm is now stable. +This means that if two entries have identical sort keys, +those two entries will appear in citation order. +(The bibliography styles construct these sort keys---% +usually the author information followed by the year and the title.) + +\item +\BibTeX\ no longer does case conversion for file names; +this will make \BibTeX\ easier to install on Unix systems, for example. + +\item +It's now easier to add code for processing a +command-line {\tt aux}-file name. + +\end{enumerate} + + +\subsection{Changes to the standard styles} + +This section describes changes to the standard styles +({\tt plain}, {\tt unsrt}, {\tt alpha}, {\tt abbrv}) +that affect ordinary users. +Changes that affect style designers appear in +the document ``Designing \BibTeX\ Styles''~\cite{btxhak}. +\begin{enumerate} + +\item +In general, sorting is now by ``author''$\!$, then year, then title---% +the old versions didn't use the year field. +(The {\tt alpha} style, however, sorts first by label, +then ``author''$\!$, year, and title.) +The quotes around author mean that some entry types +might use something besides the author, like the editor or organization. + +\item +Many unnecessary ties (\verb|~|) have been removed. +\LaTeX\ thus will produce slightly fewer +`\hbox{\tt Underfull} \verb|\hbox|' messages +when it's formatting the reference list. + +\item +Emphasizing (\hbox{\verb|{\em ...}|}) +has replaced italicizing (\hbox{\verb|{\it ...}|}). +This will almost never result in a difference +between the old output and the new. + +\item +The {\tt alpha} style now uses a superscripted~`$^{+}$' instead of a~`*' +to represent names omitted in constructing the label. +If you really liked it the way it was, however, +or if you want to omit the character entirely, +you don't have to modify the style file---% +you can override the~`$^{+}$' by +redefining the \hbox{\verb|\etalchar|} command +that the {\tt alpha} style writes onto the {\tt bbl} file +(just preceding the \hbox{\verb|\thebibliography|} environment); +use \LaTeX's \hbox{\verb|\renewcommand|} inside +a database \hbox{\tt @PREAMBLE} command, +described in the previous subsection's item~\ref{preamble}. + +\item +The {\tt abbrv} style now uses `Mar.' and `Sept.'\ +for those months rather than `March' and `Sep.' + +\item +The standard styles use \BibTeX's new cross-referencing feature +by giving a \verb|\cite| of the cross-referenced entry and by +omitting from the cross-referencing entry +(most of the) information that appears +in the cross-referenced entry. +These styles do this when +a titled thing (the cross-referencing entry) +is part of a larger titled thing (the cross-referenced entry). +There are five such situations: +when (1)~an \hbox{\tt INPROCEEDINGS} +(or \hbox{\tt CONFERENCE}, which is the same) +cross references a \hbox{\tt PROCEEDINGS}; +when (2)~a {\tt BOOK}, (3)~an \hbox{\tt INBOOK}, +or (4)~an \hbox{\tt INCOLLECTION} +cross references a {\tt BOOK} +(in these cases, the cross-referencing entry is a single +volume in a multi-volume work); +and when (5)~an \hbox{\tt ARTICLE} +cross references an \hbox{\tt ARTICLE} +(in this case, the cross-referenced entry is really a journal, +but there's no \hbox{\tt JOURNAL} entry type; +this will result in warning messages about +an empty \hbox{\tt author} and \hbox{\tt title} for the journal---% +you should just ignore these warnings). + +\item +The \hbox{\tt MASTERSTHESIS} and \hbox{\tt PHDTHESIS} +entry types now take an optional {\tt type} field. +For example you can get the standard styles to +call your reference a `Ph.D.\ dissertation' +instead of the default `PhD thesis' by including a +\begin{verbatim} + type = "{Ph.D.} dissertation" +\end{verbatim} +in your database entry. + +\item +Similarly, the \hbox{\tt INBOOK} and \hbox{\tt INCOLLECTION} +entry types now take an optional {\tt type} field, +allowing `section~1.2' instead of the default `chapter~1.2'$\!$. +You get this by putting +\begin{verbatim} + chapter = "1.2", + type = "Section" +\end{verbatim} +in your database entry. + +\item +The \hbox{\tt BOOKLET}, \hbox{\tt MASTERSTHESIS}, +and \hbox{\tt TECHREPORT} entry types now format +their \hbox{\tt title} fields as if they were +\hbox{\tt ARTICLE} \hbox{\tt title}s +rather than \hbox{\tt BOOK} \hbox{\tt title}s. + +\item +The \hbox{\tt PROCEEDINGS} and \hbox{\tt INPROCEEDINGS} +entry types now use the \hbox{\tt address} field +to tell where a conference was held, +rather than to give the address +of the publisher or organization. +If you want to include the +publisher's or organization's address, +put it in the \hbox{\tt publisher} +or \hbox{\tt organization} field. + +\item +The \hbox{\tt BOOK}, \hbox{\tt INBOOK}, \hbox{\tt INCOLLECTION}, +and \hbox{\tt PROCEEDINGS} entry types now allow either +\hbox{\tt volume} or \hbox{\tt number} (but not both), +rather than just \hbox{\tt volume}. + +\item +The \hbox{\tt INCOLLECTION} entry type now allows +a \hbox{\tt series} and an \hbox{\tt edition} field. + +\item +The \hbox{\tt INPROCEEDINGS} and \hbox{\tt PROCEEDINGS} +entry types now allow either a \hbox{\tt volume} or \hbox{\tt number}, +and also a \hbox{\tt series} field. + +\item +The \hbox{\tt UNPUBLISHED} entry type now outputs, +in one block, the \hbox{\tt note} field +followed by the date information. + +\item +The \hbox{\tt MANUAL} entry type now prints out +the \hbox{\tt organization} in the first block +if the \hbox{\tt author} field is empty. + +\item +The {\tt MISC} entry type now issues a warning +if all the optional fields are empty +(that is, if the entire entry is empty). + +\end{enumerate} + + +\section{The Entries} +\label{latex-appendix} + +This section is simply a corrected version of +Appendix~B.2 of the \LaTeX\ book~\cite{latex}, +\copyright~1986, by Addison-Wesley. +The basic scheme is the same, only a few details have changed. + + +\subsection{Entry Types} + +When entering a reference in the database, the first thing to decide +is what type of entry it is. No fixed classification scheme can be +complete, but \BibTeX\ provides enough entry types to handle almost +any reference reasonably well. + +References to different types of publications contain different +information; a reference to a journal article might include the volume +and number of the journal, which is usually not meaningful for a book. +Therefore, database entries of different types have different fields. +For each entry type, the fields are divided into three classes: +\begin{description} + +\item[required] +Omitting the field will produce a warning message +and, rarely, a badly formatted bibliography entry. +If the required information is not meaningful, +you are using the wrong entry type. +However, if the required information is meaningful +but, say, already included is some other field, +simply ignore the warning. + +\item[optional] +The field's information will be used if present, +but can be omitted without causing any formatting problems. +You should include the optional field if it will help the reader. + +\item[ignored] +The field is ignored. +\BibTeX\ ignores any field that is not required or optional, so you can include +any fields you want in a \hbox{\tt bib} file entry. It's a good idea +to put all relevant information about +a reference in its \hbox{\tt bib} file entry---even information that +may never appear in the bibliography. For example, if you want to +keep an abstract of a paper in a computer file, put it in an \hbox{\tt +abstract} field in the paper's \hbox{\tt bib} file entry. The +\hbox{\tt bib} file is likely to be as good a place as any for the +abstract, and it is possible to design a bibliography style for +printing selected abstracts. +Note: Misspelling a field name will +result in its being ignored, +so watch out for typos +(especially for optional fields, +since \BibTeX\ won't warn you when those are missing). + +\end{description} + +The following are the standard entry types, along with their required +and optional fields, that are used by the standard bibliography styles. +The fields within each class (required or optional) +are listed in order of occurrence in the output, +except that a few entry types may perturb the order slightly, +depending on what fields are missing. +These entry types are similar to those adapted by Brian Reid +from the classification scheme of van~Leunen~\cite{van-leunen} +for use in the {\em Scribe\/} system. +The meanings of the individual fields are explained in the next section. +Some nonstandard bibliography styles may ignore some optional fields +in creating the reference. +Remember that, when used in the \hbox{\tt bib} +file, the entry-type name is preceded by an \hbox{\tt @} character. + +\begin{description} +\sloppy + +\item[article\hfill] An article from a journal or magazine. +Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt journal}, +\hbox{\tt year}. +Optional fields: \hbox{\tt volume}, \hbox{\tt number}, +\hbox{\tt pages}, \hbox{\tt month}, \hbox{\tt note}. + +\item[book\hfill] A book with an explicit publisher. +Required fields: \hbox{\tt author} or \hbox{\tt editor}, +\hbox{\tt title}, \hbox{\tt publisher}, \hbox{\tt year}. +Optional fields: \hbox{\tt volume} or \hbox{\tt number}, \hbox{\tt series}, +\hbox{\tt address}, \hbox{\tt edition}, \hbox{\tt month}, +\hbox{\tt note}. + +\item[booklet\hfill] A work that is printed and bound, +but without a named publisher or sponsoring institution. +Required field: \hbox{\tt title}. +Optional fields: \hbox{\tt author}, \hbox{\tt howpublished}, +\hbox{\tt address}, \hbox{\tt month}, \hbox{\tt year}, \hbox{\tt note}. + +\item[conference\hfill] The same as {\tt INPROCEEDINGS}, +included for {\em Scribe\/} compatibility. + +\item[inbook\hfill] A part of a book, +which may be a chapter (or section or whatever) and/or a range of pages. +Required fields: \hbox{\tt author} or \hbox{\tt editor}, \hbox{\tt title}, +\hbox{\tt chapter} and/or \hbox{\tt pages}, \hbox{\tt publisher}, +\hbox{\tt year}. +Optional fields: \hbox{\tt volume} or \hbox{\tt number}, \hbox{\tt series}, +\hbox{\tt type}, \hbox{\tt address}, +\hbox{\tt edition}, \hbox{\tt month}, \hbox{\tt note}. + +\item[incollection\hfill] A part of a book having its own title. +Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt booktitle}, +\hbox{\tt publisher}, \hbox{\tt year}. +Optional fields: \hbox{\tt editor}, \hbox{\tt volume} or \hbox{\tt number}, +\hbox{\tt series}, \hbox{\tt type}, \hbox{\tt chapter}, \hbox{\tt pages}, +\hbox{\tt address}, \hbox{\tt edition}, \hbox{\tt month}, \hbox{\tt note}. + +\item[inproceedings\hfill] An article in a conference proceedings. +Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt booktitle}, +\hbox{\tt year}. +Optional fields: \hbox{\tt editor}, \hbox{\tt volume} or \hbox{\tt number}, +\hbox{\tt series}, \hbox{\tt pages}, \hbox{\tt address}, \hbox{\tt month}, +\hbox{\tt organization}, \hbox{\tt publisher}, \hbox{\tt note}. + +\item[manual\hfill] Technical documentation. Required field: \hbox{\tt title}. +Optional fields: \hbox{\tt author}, \hbox{\tt organization}, +\hbox{\tt address}, \hbox{\tt edition}, \hbox{\tt month}, \hbox{\tt year}, +\hbox{\tt note}. + +\item[mastersthesis\hfill] A Master's thesis. +Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt school}, +\hbox{\tt year}. +Optional fields: \hbox{\tt type}, \hbox{\tt address}, \hbox{\tt month}, +\hbox{\tt note}. + +\item[misc\hfill] Use this type when nothing else fits. +Required fields: none. +Optional fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt howpublished}, +\hbox{\tt month}, \hbox{\tt year}, \hbox{\tt note}. + +\item[phdthesis\hfill] A PhD thesis. +Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt school}, +\hbox{\tt year}. +Optional fields: \hbox{\tt type}, \hbox{\tt address}, \hbox{\tt month}, +\hbox{\tt note}. + +\item[proceedings\hfill] The proceedings of a conference. +Required fields: \hbox{\tt title}, \hbox{\tt year}. +Optional fields: \hbox{\tt editor}, \hbox{\tt volume} or \hbox{\tt number}, +\hbox{\tt series}, \hbox{\tt address}, \hbox{\tt month}, +\hbox{\tt organization}, \hbox{\tt publisher}, \hbox{\tt note}. + + +\item[techreport\hfill] A report published by a school or other institution, +usually numbered within a series. +Required fields: \hbox{\tt author}, +\hbox{\tt title}, \hbox{\tt institution}, \hbox{\tt year}. +Optional fields: \hbox{\tt type}, \hbox{\tt number}, \hbox{\tt address}, +\hbox{\tt month}, \hbox{\tt note}. + +\item[unpublished\hfill] A document having an author and title, +but not formally published. +Required fields: \hbox{\tt author}, \hbox{\tt title}, \hbox{\tt note}. +Optional fields: \hbox{\tt month}, \hbox{\tt year}. + +\end{description} + +In addition to the fields listed above, each entry type also has an +optional \hbox{\tt key} field, used in some styles +for alphabetizing, for cross referencing, +or for forming a \hbox{\verb|\bibitem|} label. +You should include a \hbox{\tt key} field for any entry whose +``author'' information is missing; +the ``author'' information is usually the \hbox{\tt author} field, +but for some entry types it can be the \hbox{\tt editor} +or even the \hbox{\tt organization} field +(Section~\ref{odds-and-ends} describes this in more detail). +Do not confuse the \hbox{\tt key} field with the key that appears in the +\hbox{\verb|\cite|} command and at the beginning of the database entry; +this field is named ``key'' only for compatibility with {\it Scribe}. + + +\subsection{Fields} + +Below is a description of all fields +recognized by the standard bibliography styles. +An entry can also contain other fields, which are ignored by those styles. +\begin{description} + +\item[address\hfill] +Usually the address of the \hbox{\tt publisher} or other type +of institution. +For major publishing houses, +van~Leunen recommends omitting the information entirely. +For small publishers, on the other hand, you can help the +reader by giving the complete address. + +\item[annote\hfill] +An annotation. +It is not used by the standard bibliography styles, +but may be used by others that produce an annotated bibliography. + +\item[author\hfill] +The name(s) of the author(s), +in the format described in the \LaTeX\ book. + +\item[booktitle\hfill] +Title of a book, part of which is being cited. +See the \LaTeX\ book for how to type titles. +For book entries, use the \hbox{\tt title} field instead. + +\item[chapter\hfill] +A chapter (or section or whatever) number. + +\item[crossref\hfill] +The database key of the entry being cross referenced. + +\item[edition\hfill] +The edition of a book---for example, ``Second''$\!$. +This should be an ordinal, and +should have the first letter capitalized, as shown here; +the standard styles convert to lower case when necessary. + +\item[editor\hfill] +Name(s) of editor(s), typed as indicated in the \LaTeX\ book. +If there is also an \hbox{\tt author} field, then +the \hbox{\tt editor} field gives the editor of the book or collection +in which the reference appears. + +\item[howpublished\hfill] +How something strange has been published. +The first word should be capitalized. + +\item[institution\hfill] +The sponsoring institution of a technical report. + +\item[journal\hfill] +A journal name. +Abbreviations are provided for many journals; see the {\it Local Guide}. + +\item[key\hfill] +Used for alphabetizing, cross referencing, and creating a label when +the ``author'' information +(described in Section~\ref{odds-and-ends}) is missing. +This field should not be confused with the key that appears in the +\hbox{\verb|\cite|} command and at the beginning of the database entry. + +\item[month\hfill] +The month in which the work was +published or, for an unpublished work, in which it was written. +You should use the standard three-letter abbreviation, +as described in Appendix B.1.3 of the \LaTeX\ book. + +\item[note\hfill] +Any additional information that can help the reader. +The first word should be capitalized. + +\item[number\hfill] +The number of a journal, magazine, technical report, +or of a work in a series. +An issue of a journal or magazine is usually +identified by its volume and number; +the organization that issues a +technical report usually gives it a number; +and sometimes books are given numbers in a named series. + +\item[organization\hfill] +The organization that sponsors a conference or that publishes a \hbox{manual}. + +\item[pages\hfill] +One or more page numbers or range of numbers, +such as \hbox{\tt 42--111} or \hbox{\tt 7,41,73--97} or \hbox{\tt 43+} +(the `{\tt +}' in this last example indicates pages following +that don't form a simple range). +To make it easier to maintain {\em Scribe\/}-compatible databases, +the standard styles convert a single dash (as in \hbox{\tt 7-33}) +to the double dash used in \TeX\ to denote number ranges +(as in \hbox{\tt 7--33}). + +\item[publisher\hfill] +The publisher's name. + +\item[school\hfill] +The name of the school where a thesis was written. + +\item[series\hfill] +The name of a series or set of books. +When citing an entire book, the the \hbox{\tt title} field +gives its title and an optional \hbox{\tt series} field gives the +name of a series or multi-volume set +in which the book is published. + +\item[title\hfill] +The work's title, typed as explained in the \LaTeX\ book. + +\item[type\hfill] +The type of a technical report---for example, +``Research Note''$\!$. + +\item[volume\hfill] +The volume of a journal or multivolume book. + +\item[year\hfill] +The year of publication or, for +an unpublished work, the year it was written. +Generally it should consist of four numerals, such as {\tt 1984}, +although the standard styles can handle any {\tt year} whose +last four nonpunctuation characters are numerals, +such as `\hbox{(about 1984)}'$\!$. + +\end{description} + + +\section{Helpful Hints} +\label{odds-and-ends} + +This section gives some random tips +that aren't documented elsewhere, +at least not in this detail. +They are, roughly, in order +of least esoteric to most. +First, however, a brief spiel. + +I understand that there's often little choice in choosing +a bibliography style---journal~$X$ says you must use style~$Y$ +and that's that. +If you have a choice, however, I strongly recommend that you +choose something like the {\tt plain} standard style. +Such a style, van~Leunen~\cite{van-leunen} argues convincingly, +encourages better writing than the alternatives---% +more concrete, more vivid. + +{\em The Chicago Manual of Style\/}~\cite{chicago}, +on the other hand, +espouse the author-date system, +in which the citation might appear in the text as `(Jones, 1986)'$\!$. +I argue that this system, +besides cluttering up the +text with information that may or may not be relevant, +encourages the passive voice and vague writing. +Furthermore the strongest arguments for +using the author-date system---like ``it's the most practical''---% +fall flat on their face with the advent +of computer-typesetting technology. +For instance the {\em Chicago Manual\/} contains, +right in the middle of page~401, this anachronism: +``The chief disadvantage of [a style like {\tt plain}] is that additions +or deletions cannot be made after the manuscript is typed without changing +numbers in both text references and list.'' +\LaTeX, obviously, sidesteps the disadvantage. + +Finally, the logical deficiencies of the author-date style +are quite evident once you've written a program to implement it. +For example, in a large bibliography, +using the standard alphabetizing scheme, +the entry for `(Aho et~al., 1983b)' +might be half a page later than the one for `(Aho et~al., 1983a)'$\!$. +Fixing this problem results in even worse ones. +What a mess. +(I have, unfortunately, programmed such a style, +and if you're saddled with an unenlightened publisher +or if you don't buy my propaganda, +it's available from the Rochester style collection.) + +Ok, so the spiel wasn't very brief; +but it made me feel better, +and now my blood pressure is back to normal. +Here are the tips for using \BibTeX\ +with the standard styles +(although many of them hold for nonstandard styles, too). +\begin{enumerate} + +\item +With \BibTeX's style-designing language +you can program general database manipulations, +in addition to bibliography styles. +For example it's a fairly easy task for someone familiar with the language +to produce a database-key/author index of all the entries in a database. +Consult the {\em Local Guide\/} to see +what tools are available on your system. + +\item +The standard style's thirteen entry types +do reasonably well at formatting most entries, +but no scheme with just thirteen formats +can do everything perfectly. +Thus, you should feel free to be creative +in how you use these entry types +(but if you have to be too creative, +there's a good chance you're using the wrong entry type). + +\item +Don't take the field names too seriously. +Sometimes, for instance, you might have to include +the publisher's address along with the publisher's name +in the \hbox{\tt publisher} field, +rather than putting it in the \hbox{\tt address} field. +Or sometimes, difficult entries work best when you +make judicious use of the {\tt note} field. + +\item +Don't take the warning messages too seriously. +Sometimes, for instance, the year appears in the title, +as in {\em The 1966 World Gnus Almanac}. +In this case it's best to omit the {\tt year} field +and to ignore \BibTeX's warning message. + +\item +If you have too many names to list in an +\hbox{\tt author} or \hbox{\tt editor} field, +you can end the list with ``and others''; +the standard styles appropriately append an ``et~al.'' + +\item +In general, if you want to keep \BibTeX\ from changing +something to lower case, you enclose it in braces. +You might not get the effect you want, however, +if the very first character after the left brace is a backslash. +The ``special characters'' item later in this section explains. + +\item +For {\em Scribe\/} compatibility, the database files +allow an \hbox{\tt @COMMENT} command; it's not really +needed because \BibTeX\ allows in the database files +any comment that's not within an entry. +If you want to comment out an entry, +simply remove the `{\tt @}' character preceding the entry type. + +\item +The standard styles have journal abbreviations that are +computer-science oriented; +these are in the style files primarily for the example. +If you have a different set of journal abbreviations, +it's sensible to put them in \hbox{\tt @STRING} commands +in their own database file and to list this database file +as an argument to \LaTeX's \hbox{\verb|\bibliography|} command +(but you should list this argument before the ones that +specify real database entries). + +\item +It's best to use the three-letter abbreviations for the month, +rather than spelling out the month yourself. +This lets the bibliography style be consistent. +And if you want to include information for the day of the month, +the {\tt month} field is usually the best place. +For example +\begin{verbatim} + month = jul # "~4," +\end{verbatim} +will probably produce just what you want. + +\item +If you're using the \hbox{\tt unsrt} style +(references are listed in order of citation) +along with the \hbox{\verb|\nocite{*}|} feature +(all entries in the database are included), +the placement of the \hbox{\verb|\nocite{*}|} command +within your document file will determine the reference order. +According to the rule given in Section~\ref{features}: +If the command is placed at the beginning of the document, +the entries will be listed in exactly the order +they occur in the database; +if it's placed at the end, +the entries that you explicitly +\hbox{\verb|\cite|} or \hbox{\verb|\nocite|} +will occur in citation order, +and the remaining database entries will be in database order. + +\item +For theses, van Leunen recommends not giving +the school's department after the name of the degree, +since schools, not departments, issue degrees. +If you really think that giving the department information +will help the reader find the thesis, +put that information in the \hbox{\tt address} field. + +\item +The \hbox{\tt MASTERSTHESIS} and \hbox{\tt PHDTHESIS} entry types +are so named for {\em Scribe\/} compatibility; +\hbox{\tt MINORTHESIS} and \hbox{\tt MAJORTHESIS} +probably would have been better names. +Keep this in mind when trying to classify +a non-U.S.\ thesis. + +\item +Here's yet another suggestion for what to do when an author's +name appears slightly differently in two publications. +Suppose, for example, two journals articles use these fields. +\begin{verbatim} + author = "Donald E. Knuth" + . . . + author = "D. E. Knuth" +\end{verbatim} +There are two possibilities. +You could (1)~simply leave them as is, +or (2)~assuming you know for sure that +these authors are one and the same person, +you could list both in the form that the author prefers +(say, `Donald~E.\ Knuth'). +In the first case, the entries might be alphabetized incorrectly, +and in the second, the slightly altered name might +foul up somebody's electronic library search. +But there's a third possibility, which is the one I prefer. +You could convert the second journal's field to +\begin{verbatim} + author = "D[onald] E. Knuth" +\end{verbatim} +This avoids the pitfalls of the previous two solutions, +since \BibTeX\ alphabetizes this as if the brackets weren't there, +and since the brackets clue the reader in that a full first name +was missing from the original. +Of course it introduces another pitfall---`D[onald]~E.\ Knuth' looks ugly---% +but in this case I think the increase in accuracy outweighs +the loss in aesthetics. + +\item +\LaTeX's comment character `{\tt\%}' is not a comment character +in the database files. + +\item +Here's a more complete description of +the ``author'' information referred to in previous sections. +For most entry types the ``author'' information +is simply the \hbox{\tt author} field. +However: +For the \hbox{\tt BOOK} and \hbox{\tt INBOOK} entry types +it's the \hbox{\tt author} field, but if there's no author +then it's the \hbox{\tt editor} field; +for the \hbox{\tt MANUAL} entry type +it's the \hbox{\tt author} field, but if there's no author +then it's the \hbox{\tt organization} field; +and for the \hbox{\tt PROCEEDINGS} entry type +it's the \hbox{\tt editor} field, but if there's no editor +then it's the \hbox{\tt organization} field. + +\item +When creating a label, +the \hbox{\tt alpha} style uses the ``author'' information described above, +but with a slight change---% +for the \hbox{\tt MANUAL} and \hbox{\tt PROCEEDINGS} entry types, +the {\tt key} field takes precedence over the \hbox{\tt organization} field. +Here's a situation where this is useful. +\begin{verbatim} + organization = "The Association for Computing Machinery", + key = "ACM" +\end{verbatim} +Without the {\tt key} field, the \hbox{\tt alpha} style +would make a label from the first three letters of information +in the \hbox{\tt organization} field; +\hbox{\tt alpha} knows to strip off the `\hbox{\tt The }'$\!$, +but it would still form a label like `\hbox{[Ass86]}'$\!$, +which, however intriguing, is uninformative. +Including the {\tt key} field, as above, +would yield the better label `\hbox{[ACM86]}'$\!$. + +You won't always need the {\tt key} field to override the +\hbox{\tt organization}, though: +With +\begin{verbatim} + organization = "Unilogic, Ltd.", +\end{verbatim} +for instance, the \hbox{\tt alpha} style would +form the perfectly reasonable label `\hbox{[Uni86]}'$\!$. + +\item +Section~\ref{features} discusses accented characters. +To \BibTeX, an accented character is really a special case +of a ``special character''$\!$, +which consists of everything from a left brace at the top-most level, +immediately followed by a backslash, +up through the matching right brace. +For example in the field +\begin{verbatim} + author = "\AA{ke} {Jos{\'{e}} {\'{E}douard} G{\"o}del" +\end{verbatim} +there are just two special characters, +`\hbox{\verb|{\'{E}douard}|}' and `\hbox{\verb|{\"o}|}' +(the same would be true if the pair of double quotes +delimiting the field were braces instead). +In general, \BibTeX\ will not do any processing +of a \TeX\ or \LaTeX\ control sequence inside a special character, +but it {\em will\/} process other characters. +Thus a style that converts all titles to lower case +would convert +\begin{verbatim} + The {\TeX BOOK\NOOP} Experience +\end{verbatim} +to +\begin{verbatim} + The {\TeX book\NOOP} experience +\end{verbatim} +(the `{\tt The}' is still capitalized +because it's the first word of the title). + +This special-character scheme is useful for handling accented characters, +for getting \BibTeX's alphabetizing to do what you want, +and, since \BibTeX\ counts an entire special character as just one letter, +for stuffing extra characters inside labels. +The file \hbox{\tt XAMPL.BIB} distributed with \BibTeX\ +gives examples of all three uses. + +\item +This final item of the section describes \BibTeX's names +(which appear in the \hbox{\tt author} or \hbox{\tt editor} field) +in slightly more detail than what +appears in Appendix~B of the \LaTeX\ book. +In what follows, a ``name'' corresponds to a person. +(Recall that you separate multiple names in a single field +with the word ``and''$\!$, surrounded by spaces, +and not enclosed in braces. +This item concerns itself with the structure of a single name.) + +Each name consists of four parts: First, von, Last, and~Jr; +each part consists of a (possibly empty) list of name-tokens. +The Last part will be nonempty if any part is, +so if there's just one token, it's always a Last token. + +Recall that Per Brinch~Hansen's name should be typed +\begin{verbatim} + "Brinch Hansen, Per" +\end{verbatim} +The First part of his name has the single token ``Per''; +the Last part has two tokens, ``Brinch'' and ``Hansen''; +and the von and Jr parts are empty. +If you had typed +\begin{verbatim} + "Per Brinch Hansen" +\end{verbatim} +instead, \BibTeX\ would (erroneously) think ``Brinch'' were a First-part token, +just as ``Paul'' is a First-part token in ``John~Paul Jones''$\!$, +so this erroneous form would have two First tokens and one Last token. + +Here's another example: +\begin{verbatim} + "Charles Louis Xavier Joseph de la Vall{\'e}e Poussin" +\end{verbatim} +This name has four tokens in the First part, two in the von, and +two in the Last. +Here \BibTeX\ knows where one part ends and the other begins because +the tokens in the von part begin with lower-case letters. + +In general, it's a von token if the first letter at brace-level~0 +is in lower case. +Since technically everything +in a ``special character'' is at brace-level~0, +you can trick \BibTeX\ into thinking that +a token is or is not a von token by prepending a dummy +special character whose first letter past the \TeX\ control sequence +is in the desired case, upper or lower. + +To summarize, \BibTeX\ allows three possible forms for the name: +\begin{verbatim} + "First von Last" + "von Last, First" + "von Last, Jr, First" +\end{verbatim} +You may almost always use the first form; +you shouldn't if either there's a Jr part, +or the Last part has multiple tokens but there's no von part. + +\end{enumerate} + +\bibliography{btxdoc} +\bibliographystyle{plain} +\end{document} diff --git a/Master/texmf-dist/doc/eplain/base/csindex.texi b/Master/texmf-dist/doc/eplain/base/csindex.texi new file mode 100644 index 00000000000..f80b7058979 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/csindex.texi @@ -0,0 +1,6 @@ +@c Public domain. + +@node Macro index +@unnumbered Macro index + +@printindex fn diff --git a/Master/texmf-dist/doc/eplain/base/eplain.html b/Master/texmf-dist/doc/eplain/base/eplain.html new file mode 100644 index 00000000000..638a3492141 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/eplain.html @@ -0,0 +1,6644 @@ + + +Expanded Plain TeX + + + + + + + + + + +

Expanded Plain TeX

+
+

+ +Next: , +Up: (dir) + +
+ +

Eplain

+ +

This manual documents the Eplain macros, version 3.0, +September 2005. Eplain provides functionality for plain TeX that +is intended to be useful regardless of how your document is actually +formatted. + +

Most of this manual is in the public domain, like most of the Eplain +code. It was mostly written by Karl Berry, starting in 1989. Steven +Smith wrote the documentation for the commutative diagram macros; this +chapter is under the GNU General Public License. Oleg Katsitadze and +Adam Lewenberg have made additions and corrections. + +

+

--- The Detailed Node Listing --- + +

User definitions + +

+ +

Citations + +

+ +

Displays + +

+ +

Lists + +

+ +

Cross-references + +

+ +

Equation references + +

+ +

Indexing + +

+ +

Indexing terms + +

+ +

Hyperlinks + +

+ +

Implicit hyperlinks + +

+ +

Index hyperlinks + +

+ +

Hyperlink drivers + +

+ +

Hyperlink drivers pdftex and dvipdfm:: + +

+ +

Setting hyperlink types and options + +

+ +

Turning hyperlinks on/off + +

+ +

Arrow theoretic diagrams + +

+ +

Commutative diagrams + +

+ +

Programming definitions + +

+ +

Expansion + +

+ + + +
+

+ +Next: , +Previous: Top, +Up: Top + +
+ +

1 Introduction

+ +

+The Eplain macro package expands on and extends the definitions in +plain TeX. This manual describes the definitions that you, as either +an author or a macro writer, might like to use. It doesn't discuss the +implementation; see comments in the source code (xeplain.tex) for +that. + +

Eplain is not intended to provide “generic” typesetting capabilities, as +do LaTeX (written by Leslie Lamport) +or Texinfo +(written by Richard Stallman and others). +Instead, it provides definitions that are intended to be useful +regardless of the high-level commands that you use when you actually +prepare your manuscript. + +

For example, Eplain does not have a command \section, which +would format section headings in an “appropriate” way, such as +LaTeX's \section. The philosophy of Eplain is +that some people will always need or want to go beyond the macro +designer's idea of “appropriate”. Such canned macros are +fine—as long as you are willing to accept the resulting output. If +you don't like the results, or if you are trying to match a different +format, you are out of luck. + +

On the other hand, almost everyone would like capabilities such as +cross-referencing by labels, so that you don't have to put actual page +numbers in the manuscript. The author of Eplain +is not aware of any generally available macro packages that (1) do +not force their typographic style on an author, and yet (2) provide +such capabilities. + +

Besides such generic macros as cross-referencing, Eplain +contains another set of definitions: ones that change the conventions of +plain TeX's output. For example, math displays in TeX are, by +default, centered. If you want your displays to come out +left-justified, you have to plow through The TeXbook to find +some way to do it, and then adapt the code to your own needs. Eplain +tries to take care of the messy details of such things, while still +leaving the detailed appearance of the output up to you. + +

Finally, numerous definitions turned out to be useful as Eplain was +developed. They are also documented in this manual, on the chance that +people writing other macros will be able to use them. + +

You can send bug reports or suggestions to +tex-eplain@tug.org. The current version number of Eplain is +defined as the macro \fmtversion +at the end of the source file eplain.tex. When corresponding, +please refer to it. + +

To get on this mailing list yourself, email +tex-eplain-request@tug.org with a message whose body contains +a line +

     subscribe you@your.preferred.address
+
+ +
+

+ +Next: , +Previous: Introduction, +Up: Top + +
+ +

2 Installation

+ +

The simplest way to install Eplain is simply to install the file +eplain.tex in a directory where TeX will find it. What that +directory is obviously depends on your operating system and TeX +installation. I personally install eplain.tex in +a directory /usr/local/lib/texmf/tex/plain. + +

If you want, you can also create a format (.fmt) +file for Eplain, which will eliminate the time spent reading the macro +source file with \input. You do this by issuing a sequence of +Unix commands something like this: + +

     prompt$ touch eplain.aux
+     prompt$ initex
+     This is TeX, ...
+     **&plain eplain
+     (eplain.tex)
+     *\dump
+     ... messages ...
+
+

You must make sure that eplain.aux exists before you +run initex; otherwise, warning messages about undefined labels +will never be issued. + +

You then have to install the resulting eplain.fmt in some system +directory or set an environment variable to tell TeX how to find it. +I install the format files in /usr/local/lib/texmf/ini; the +environment variable for the Web2C port of TeX to Unix is +TEXFORMATS. + +

Some implementations of TeX (including Web2C) use the name by which +TeX is invoked to determine what format to read. For them, you +should make a link to the virtex program named etex, and +then install the format file with the name etex.fmt. This lets +users invoke TeX as etex and get the format file read +automatically, without having to say `&eplain'. + +

For convenience, the file etex.tex in the distribution directory +does \input eplain and then \dump, so that if you replace +`eplain' with `etex' in the example above, the format file +will end up with the right name. + +

The install target in the Makefile does all this properly +for Unix systems and Web2C. You may have to change the pathnames. + +

Under emtex, `eaj@acpub.duke.edu' says that + +

     tex386 -i ^&plain eplain \dump
+
+

produces a format file. + + +

+

+ +Next: , +Previous: Installation, +Up: Top + +
+ +

3 Invoking Eplain

+ +

The simplest way to use Eplain is simply to put: + +

     \input eplain
+
+

at the beginning of your input file. The macro file is small +enough that reading it does not take an unbearably long time—at least on +contemporary machines. + +

In addition, if a format (.fmt) +file has been created for Eplain (see the previous section), you can +eliminate the time spent reading the macro source file. You do this +by responding &eplain to TeX's `**' prompt. For +example: + +

     initex
+     This is TeX, ...
+     **&eplain myfile
+
+

Depending on the implementation of TeX which you are using, you might +also be able to invoke TeX as eplain and have the format file +automatically read. + +

If you write something which you will be distributing to others, you +won't know if the Eplain format will be loaded already. If it is, then +doing \input eplain will waste time; if it isn't, then you must +load it. To solve this, Eplain defines the control sequence +\eplain +to be the letter t (a convention borrowed from Lisp; it doesn't +actually matter what the definition is, only that the definition +exists). Therefore, you can do the following: +

     \ifx\eplain\undefined \input eplain \fi
+
+

where \undefined must never acquire a definition. + +

Eplain consists of several source files: +

+
xeplain.tex
most of the macros; + +
arrow.tex
commutative diagram macros (see Arrow theoretic diagrams), written by +Steven Smith; + +
btxmac.tex
bibliography-related macros (see Citations); + +
ifpdf.sty
sets the switch \ifpdf, which can be used to +detect pdfTeX in PDF mode (see Checking for PDF output), written +by Heiko Oberdiek; + +
path.sty
macro for allowing line breaks at punctuation characters within long +pathnames, electronic mail addresses, etc., (see Paths), written +by Philip Taylor; + +
texnames.sty
abbreviations for various TeX-related names (see Logos), edited +by Nelson Beebe. + +
+ +

The file eplain.tex is all of these files merged +together, with comments removed. + +

All of these files except xeplain.tex can be input individually, +if all you want are the definitions in that file. + +

Also, since the bibliography macros are fairly extensive, you might not +want to load them, to conserve TeX's memory. Therefore, if the +control sequence \nobibtex +is defined, then the bibliography definitions are skipped. You must set +\nobibtex before eplain.tex is read, naturally. For +example, you could start your input file like this: + +

     \let\nobibtex = t
+     \input eplain
+
+

By default, \nobibtex is undefined, and so the bibliography +definitions are made. + +

Likewise, define \noarrow if you don't want to include the +commutative diagram macros from arrow.tex, perhaps because you +already have conflicting ones. + +

If you don't want to read or write an aux file at all, for any +kind of cross-referencing, define \noauxfile +before reading eplain.tex. This also turns off all warnings +about undefined labels. + +

Eplain conflicts with AMSTeX (to be precise, with amsppt.sty): +the macros \cite and \ref are defined by both. + +

If you want to use AMSTeX's \cite, the solution is to define +\nobibtex before reading Eplain, as described above. + +

If you have amsppt.sty loaded and use \ref, Eplain writes +a warning on your terminal. If you want to use the AMSTeX +\ref, do \let\ref = \amsref after reading Eplain. +To avoid the warning, do \let\ref = \eplainref after reading +Eplain and before using \ref. + +

Sometimes you may need to run TeX more then once on your +.tex file in order to produce and typeset indexes, resolve +undefined cross-references and/or citations. The shell script +texi2dvi from the Texinfo documentation system (see +http://www.gnu.org/software/texinfo/) can automate this process: +it runs BibTeX, MakeIndex and TeX as many times as needed to +complete the compilation process. You will need to set the +LATEX environment variable to `tex'. For example, in a +Bourne-compatible shell, the following command will do all the work: + +

     prompt$ LATEX=tex texi2dvi file.tex
+
+

(Despite the name, texi2dvi can also produce +.pdf files; just set `LATEX=pdftex'.) See the output from +the command texi2dvi --help for invoking information and a +full list of options. + + +

+

+ +Next: , +Previous: Invoking Eplain, +Up: Top + +
+ +

4 User definitions

+ +

This chapter describes definitions that are meant to be used directly +in a document. When appropriate, ways to change the default +formatting are described in subsections. + +

+ +
+

+ +Next: , +Up: User definitions + +
+ +

4.1 Diagnostics

+ +

Plain TeX provides the \tracingall command, to turn on the +maximum amount of tracing possible in TeX. The (usually voluminous) +output from \tracingall goes both on the terminal and into the +transcript file. +It is sometimes easier to have the output go only to the transcript +file, so you can peruse it at your leisure and not obscure other output +to the terminal. So, Eplain provides the command \loggingall. +(For some reason, this command is available in Metafont, but not in +TeX.) + +

It is also sometimes useful to see the complete contents of boxes. +\tracingboxes does this. (It doesn't affect whether or not the +contents +are shown on the terminal.) + +

You can turn off all tracing with \tracingoff. + +You can also turn logging on and off globally, so you don't have to +worry about whether or not you're inside a group at the time of command. +These variants are named \gloggingall +and \gtracingall. + +Finally, if you write your own help messages (see \newhelp +in The TeXbook), you want a convenient way to break lines in +them. This is what TeX's \newlinechar parameter is for; +however, plain TeX doesn't set \newlinechar. Therefore, +Eplain defines it to be the character ^^J. + +

For example, one of Eplain's own error messages is defined as follows: +

     \newhelp\envhelp{Perhaps you forgot to end the previous^^J%
+        environment? I'm finishing off the current group,^^J%
+        hoping that will fix it.}%
+
+
+

+ +Next: , +Previous: Diagnostics, +Up: User definitions + +
+ +

4.2 Rules

+ +

The default dimensions of rules are defined in chapter 21 of the +The TeXbook. To sum up what is given there, the “thickness” +of rules is +0.4pt by default. Eplain defines three parameters that let you change +this dimension: \hruledefaultheight, \hruledefaultdepth, +and \vruledefaultwidth. By default, they are defined as +The TeXbook describes. + +

But it would be wrong to redefine \hrule and \vrule. For +one thing, some macros in plain TeX depend on the default dimensions +being used; for another, rules are used quite heavily, and the +performance impact of making it a macro can be noticeable. Therefore, +to take advantage of the default rule parameters, you must use +\ehrule +and \evrule. + + +

+

+ +Next: , +Previous: Rules, +Up: User definitions + +
+ +

4.3 Citations

+ +

Bibliographies are part of almost every technical document. To handle +them easily, you need two things: a program to do the tedious +formatting, and a way to cite references by labels, rather than by +numbers. The BibTeX program, written by Oren Patashnik, takes care +of the first item; the citation commands in LaTeX, written to be used +with BibTeX, take care of the second. Therefore, +Eplain adopts the use of BibTeX, and virtually the same interface as +LaTeX. + +

The general idea is that you put citation commands in the text of your +document, and commands saying where the bibliography data is. When you +run TeX, these commands produce output on the file with the same root +name as your document (by default) and the extension .aux. +BibTeX reads this file. You should put the bibliography data in a +file or files with the extension .bib. BibTeX writes out a +file with the same root +name as your document and extension .bbl. Eplain reads this file +the next time you run your document through TeX. (It takes +multiple passes to get everything straight, because usually after seeing +your bibliography typeset, you want to make changes in the .bib +file, which means you have to run BibTeX again, which means you have +to run TeX again...) An annotated example of the whole process is +given below. + +

If your document has more than one bibliography—for example, if it +is a collection of papers—you can tell Eplain to use a different root +name for the .bbl file by defining the control sequence +\bblfilebasename. +The default definition is simply \jobname. + +

See the document BibTeXing (whose text is in the file +btxdoc.tex, which should be in the Eplain distribution you got) +for information on how to write your .bib files. Both the +BibTeX and the Eplain distributions contain several examples, also. + +

The \cite +command produces a citation in the text of your document. The exact +printed form the citation will take is under your control; +see Formatting citations. \cite takes one +required argument, a comma-separated list of cross-reference labels +(see Cross-references, for exactly what characters are allowed in +such labels). Warning: spaces in this list are taken as part of the +following label name, which is probably not what you expect. +The \cite command also produces a command +in the .aux file that tells BibTeX to retrieve the given reference(s) +from the .bib file. \cite also takes one optional argument, +which you specify within square brackets, as in LaTeX. This text is +simply typeset after the citations. (See the example below.) + +

Eplain can create hypertext links for citations pointing to the relevant +bibliography entries; see Citation hyperlinks. + +

Another command, \nocite, +puts the given reference(s) into the bibliography, but produces nothing +in the text. + +

The \bibliography +command is next. It serves two purposes: producing the typeset +bibliography, and telling BibTeX the root names of the .bib +files. Therefore, the argument to \bibliography is a comma +separated list of the .bib files (without the `.bib'). Again, +spaces in this list are significant. + +

You tell BibTeX the particular style in which you want your +bibliography typeset with one more command: +\bibliographystyle. +The argument to this is a single filename style, which tells +BibTeX to look for a file style.bst. +See the document Designing BibTeX styles (whose text is in the +btxhak.tex) for information on how to write your own styles. + +

Eplain automatically reads the citations from the .aux file when +your job starts. + +

If you don't want to see the messages about undefined citations, you +can say \xrefwarningfalse before making any citations. +Eplain automatically does this if the .aux file does not exist. +You can restore the default by saying \xrefwarningtrue. + +

Here is a TeX input file that illustrates the various commands. + +

     \input eplain                    % Reads the .aux file.
+     Two citations to Knuthian works:
+       \cite[note]{surreal,concrete-math}.
+     \beginsection{References.}\par   % Title for the bibliography.
+     \bibliography{knuth}             % Use knuth.bib for the labels.
+     \bibliographystyle{plain}        % Number the references.
+     \end                             % End of the document.
+
+

+If we suppose that this file was named citex.tex and that the +bibliography data is in knuth.bib (as the \bibliography +command says), the following commands do what's required. (`$ ' +represents the shell prompt.) + +

     $ tex citex       (produces undefined citation messages)
+     $ bibtex citex    (read knuth.bib and citex.aux, write citex.bbl)
+     $ tex citex       (read citex.bbl, still have undefined citations)
+     $ tex citex       (one more time, to resolve the references)
+
+

(The texi2dvi program can help you automate this +process, see Invoking Eplain.) + +

The output looks something like (because we used the plain +bibliography style): + +

+Two citations to Knuthian works: [2,1 note]. + +

References + +

[1] Ronald L. Graham, Donald E. Knuth, and Oren Patashnik. Concrete +Mathematics. Addison-Wesley, Reading, Massachusetts, 1989. + +

[2] Donald E. Knuth. Surreal Numbers. Addison-Wesley, Reading, +Massachusetts, 1974. +

+ +

See the BibTeX documentation for information on how to write the +bibliography databases, and the bibliography styles that are available. +(If you want your references printed with names, as in [Knu74], instead +of numbered, the bibliography style is alpha.) + + +

+ +
+

+ +Next: , +Up: Citations + +
+ +

4.3.1 Formatting citations

+ +

+You may wish to change Eplain's formatting of citations; i.e., the +result of your \cite commands. By default, the citation labels +are printed one after another, separated by commas and enclosed in +brackets, using the main text font. Some formats require other styles, +such as superscripted labels. You can accomodate such formats by +redefining the following macros. + +

+
\printcitestart
\printcitefinish
Eplain expands these macros at the begining and end of the list of +citations for each \cite command. By default, they produce a +`[' and `]', respectively. + +
\printbetweencitations
If a \cite command has multiple citations, as in +\cite{acp,texbook}, Eplain expands this macro in between each +pair of citations. By default, it produces a comma followed by a space. + +
\printcitenote
This macro takes one argument, which is the optional note to the +\cite command. If the \cite command had no note, this +macro isn't used. Otherwise, it should print the note. By default, the +note is preceded with a comma and a space. +
+ +

Here is an example, showing you could produce citations as +superscripted labels, with the optional notes in parentheses. + +

     \def\printcitestart{\unskip $^\bgroup}
+     \def\printbetweencitations{,}
+     \def\printcitefinish{\egroup$}
+     \def\printcitenote#1{\hbox{\sevenrm\space (#1)}}
+
+
+

+ +Previous: Formatting citations, +Up: Citations + +
+ +

4.3.2 Formatting bibliographies

+ +

+You may wish to change Eplain's formatting of the bibliography, +especially with respect to the fonts that are used. Therefore, Eplain +provides the following control sequences: + +

+
\biblabelwidth
This control sequence represents a \dimen register, and its value +is the width of the widest label in the bibliography. Although it is +unlikely you will ever want to redefine it, you might want +to use it if you redefine \biblabelprint, below. + +
\biblabelprint
This macro takes one argument, the label to print. By default, the +label is put in a box of width \biblabelwidth, and is followed by +an enspace. When you want to change the spacing around the labels, this +is the right macro to redefine. + +
\biblabelcontents
This macro also takes one argument, the label to print. By default, the +label is printed using the font \bblrm (below), and enclosed in +brackets. When you want to change the appearance of the label, but not +the spacing around it, this is the right macro to redefine. + +
\bblrm
The default font used for printing the bibliography. + +
\bblem
The font used for printing the titles and other “emphasized” material. + +
\bblsc
In some styles, authors' names are printed in a caps-and-small-caps +font. In those cases, this font is used. + +
\bblnewblock
This is invoked between each of the parts of a bibliography entry. The +default is to leave some extra space between the parts; you could +redefine it to start each part on a new line (for example). A part is +simply a main element of the entry; for example, the author is a part. +(It was LaTeX that introduced the (misleading, as far as I am +concerned) term `block' for this.) + +
\biblabelextraspace
Bibliography entries are typeset with a hanging indentation of +\biblabelwidth plus this. The default is .5em, where the +em width is taken from the \bblrm font. If you want to change +this, you should do it inside \bblhook. + +
\bblhook
This is expanded before reading the .bbl file. By +default, it does nothing. You could, for example, define it to set the +bibliography fonts, or produce the heading for the references. Two +spacing parameters must be changed inside \bblhook: +\parskip, which produces extra space between the items; and +\biblabelextraspace, which is described above. +(By the way, \hookappend won't work with \bblhook, despite +the names. Just use \def.) + +
+ +

If you are really desperate, you can also hand-edit the .bbl file +that BibTeX produces to do anything you wish. + +

+

+ +Next: , +Previous: Citations, +Up: User definitions + +
+ +

4.4 Displays

+ +

+By default, TeX centers displayed material. (Displayed material is +just whatever you put between $$'s—it's not necessarily +mathematics.) Many layouts would be better served if the displayed +material was left-justified. Therefore, Eplain provides the command +\leftdisplays, +which indents displayed material by \parindent plus +\leftskip, plus \leftdisplayindent. + +You can go back to centering displays with \centereddisplays. +(It is usually poor typography to have both centered and left-justified +displays in a single publication, though.) + +

\leftdisplays also changes the plain TeX commands that deal +with alignments inside math displays, +\displaylines, +\eqalignno, +and \leqalignno, +to produce left-justified text. You can still override this formatting +by inserting \hfill glue, as explained in The TeXbook. + +

+ +
+

+ +Up: Displays + +
+ +

4.4.1 Formatting displays

+ +

If you want some other kind of formatting, you can write a definition +of your own, analogous to \leftdisplays. You need only make sure +that \leftdisplaysetup +is called at the beginning of every display (presumably by invoking it +in TeX's \everydisplay parameter), and to define +\generaldisplay. + +\leftdisplays expands the old value of \everydisplay +before calling \leftdisplaysetup, so that any changes you have made +to it won't be lost. That old token list as available as the value of +the token register \previouseverydisplay. + + +

+

+ +Next: , +Previous: Displays, +Up: User definitions + +
+ +

4.5 Time of day

+ +

+TeX provides the day, month, and year as numeric quantities (unless +your TeX implementation is woefully deficient). Eplain provides some +control sequences to make them a little more friendly to humans. + +

\monthname +produces the name of the current month, abbreviated to three letters. + +

\fullmonthname +produces the name of the current month, unabbreviated (in English). + +

\timestring +produces the current time, as in `1:14 p.m.' + +

\timestamp +produces the current date and time, as in `23 Apr 64 1:14 p.m.'. +(Except the spacing is slightly different.) + +

\today +produces the current date, as in `23 April 1964'. + +

+

+ +Next: , +Previous: Time of day, +Up: User definitions + +
+ +

4.6 Lists

+ +

+Many documents require lists of items, either numbered or simply +enumerated. Plain TeX defines one macro to help with creating lists, +\item, but that is insufficient in many cases. Therefore, +Eplain provides two pairs of commands: + +

+
\numberedlist ... \endnumberedlist
\orderedlist ... \endorderedlist
These commands (they are synonyms) produce a list with the items +numbered sequentially, starting from one. A nested \numberedlist +labels the items with lowercase letters, starting with `a'. Another +nested \numberedlist labels the items with roman numerals. Yet +more deeply nested numbered lists label items with `*'. + +
\unorderedlist ... \endunorderedlist
This produces a list with the items labelled with small black boxes +(“square bullets”). A nested \unorderedlist labels items with +em-dashes. Doubly (and deeper) nested unordered lists label items with +`*'s. + +
+ +

The two kinds of lists can be nested within each other, as well. + +

In both kinds of lists, you begin an item with \li. +An item may continue for several paragraphs. Each item starts a +paragraph. + +

You can give \li an optional argument, a cross-reference label. +It's defined to be the “marker” for the current item. This is useful +if the list items are numbered. You can produce the value of the label +with \xrefn. See Cross-references. + +

Eplain can create hypertext links for the markers produced by +\xrefn pointing to the relevant list item; see List hyperlinks. + +

You can also say \listcompact +right after \numberedlist or \unorderedlist. The items in +the list will then not have any extra space between them +(see Formatting lists). You might want to do this if the items in +this particular list are short. + +

Here is an example: +

     \numberedlist\listcompact
+     \li The first item.
+     \li The second item.
+     
+     The second paragraph of the second item.
+     \endnumberedlist
+
+ + +
+

+ +Up: Lists + +
+ +

4.6.1 Formatting lists

+ +

+Several registers define the spacing associated with lists. It is +likely that their default values won't suit your particular layout. + +

+
\abovelistskipamount, \belowlistskipamount
The vertical glue inserted before and after every list, respectively. + +
\interitemskipamount
The vertical glue inserted before each item except the first. +\listcompact resets this to zero, as mentioned above. + +
\listleftindent, \listrightindent
\listrightindent is the amount of space by which the list is +indented on the right; i.e., it is added to \rightskip. +\listleftindent is the amount of space, relative to +\parindent, by which the list is indented on the left. Why treat +the two parameters differently? Because (a) it is more useful to +make the list indentation depend on the paragraph indentation; +(b) footnotes aren't formatted right if \parindent is reset +to zero. + +
+ +

The three vertical glues are inserted by macros, and preceded by +penalties: \abovelistskip +does \vpenalty\abovelistpenalty +and then \vskip\abovelistskip. \belowlistskip +and \interitemskip +are analogous. + +

In addition, the macro \listmarkerspace +is called to separate the item label from the item text. This is set to +\enspace by default. + +

If you want to change the labels on the items, you can redefine these +macros: +\numberedmarker +or \unorderedmarker. +The following registers might be useful if you do: + +

+
\numberedlistdepth, \unorderedlistdepth
These keep track of the depth of nesting of the two kinds of lists. + +
\itemnumber, \itemletter
These keep track of the number of items that have been seen in the current +numbered list. They are both integer registers. The difference is that +\itemnumber starts at one, and \itemletter starts at 97, +i.e., lowercase `a'. + +
+ +

You can also redefine the control sequences that are used internally, +if you want to do something radically different: \beginlist +is invoked to begin both kinds of lists; \printitem +is invoked to print the label (and space following the label) for each +item; and \endlist +is invoked to end both kinds of +lists. + + +

+

+ +Next: , +Previous: Lists, +Up: User definitions + +
+ +

4.7 Verbatim listing

+ +

It is sometimes useful to include a file verbatim in your document; +for example, part of a computer program. The \listing +command is given one argument, a filename, and produces the contents of +that file in your document. \listing expands \listingfont +to set the current font. The default value of \listingfont +is \tt. + +

You can take arbitrary actions before reading the file by defining the macro +\setuplistinghook. +This is expanded just before the file is input. + +

If you want to have line numbers on the output, you can say +\let\setuplistinghook = \linenumberedlisting. +The line numbers are stored in the count register \lineno while +the file is being read. You can redefine the macro +\printlistinglineno to change how they are printed. + +

You can produce in-line verbatim text in your document with \verbatim. +End the text with |endverbatim. If you need a `|' in the text, +double it. If the first character of the verbatim text is a space, use +| . (| will work elsewhere in the argument, too, but +isn't necessary.) + +

For example: + +

     \verbatim| ||\#%&!|endverbatim
+
+

produces |\#%&!. + +

Line breaks and spaces in the verbatim text are preserved. + +

You can change the verbatim escape character from the default `|' +with \verbatimescapechar char; for example, this changes +it to `@'. + +

     \verbatimescapechar \@
+
+

The backslash is not necessary in some cases, but is in +others, depending on the catcode of the character. The argument to +\verbatimescapechar is used as \catcode `char, so +the exact rules follow that for \catcode. + +

Because \verbatim must change the category code of special +characters, calling inside a macro definition of your own does not work +properly. For example: + +

     \def\mymacro{\verbatim &#%|endverbatim}% Doesn't work!
+
+

To accomplish this, you must change the category codes yourself before +making the macro definition. Perhaps \uncatcodespecials will +help you (see Category codes). + +

+

+ +Next: , +Previous: Verbatim listing, +Up: User definitions + +
+ +

4.8 Contents

+ +

+Producing a table of contents that is both useful and aesthetic is one +of the most difficult design problems in any work. Naturally, Eplain +does not pretend to solve the design problem. Collecting the raw data +for a table of contents, however, is much the same across documents. +Eplain uses an auxiliary file with extension .toc +(and the same root name as your document) to save the information. + +

To write an entry for the table of contents, you say +\writetocentry{part}{text}, +where part is the type of part this entry is, e.g., +`chapter', and text is the text of the title. +\writetocentry puts an entry into the .toc file that looks +like \tocpartentry{text}{page number}. The +text is written unexpanded. + +

A related command, \writenumberedtocentry, takes one additional +argument, the first token of which is expanded at the point of the +\writenumberedtocentry, but the rest of the argument is not +expanded. The usual application is when the parts of the document are +numbered. On the other hand, the one-level expansion allows you to use +the argument for other things as well (author's names in a proceedings, +say), and not have accents or other control sequences expanded. The +downside is that if you want full expansion of the third +argument, you don't get it—you must expand it yourself, before you +call \writenumberedtocentry. + +

For example: + +

     \writenumberedtocentry{chapter}{A $\sin$ wave}{\the\chapno}
+     \writetocentry{section}{A section title}
+
+

Supposing \the\chapno expanded to `3' and that the +\write's occurred on pages eight and nine, respectively, the +above writes the following to the .toc file: + +

     \tocchapterentry{A $\sin$ wave}{3}{8}
+     \tocsectionentry{A section title}{9}
+
+

You read the .toc file with the command \readtocfile. +Naturally, whatever \toc... entry commands that were written +to the file must be defined when \readtocfile is invoked. Eplain +has minimal definitions for \tocchapterentry, +\tocsectionentry, and \tocsubsectionentry, just to prevent +undefined control sequence errors in common cases. They aren't suitable +for anything but preliminary proofs. + +

Each of \writetocentry and \writenumberedtocentry opens +the .toc file for writing, thereby deleting the information from the +previous run. You should therefore arrange that \readtocfile be +called before the first call to a \writetoc... macro. +\readtocfile does not itself delete the information +from the .toc file, so that you can call it several times, +e.g., to create both a short +and normal table of contents. (To produce this in particular, define +\tocsectionentry to produce nothing while you are reading +.toc file for a short table of contents (see Macro arguments).) + +

On the other hand, if you don't want to rewrite the .toc file at +all, perhaps because you are only running TeX on part of your +manuscript, you can set \rewritetocfilefalse. + +By default, the .toc file has the root \jobname. If your +document has more than one contents—for example, if it is a collection +of papers, some of which have their own contents—you can tell Eplain +to use a different root name by defining the control sequence +\tocfilebasename. + +In addition to the usual table of contents, you may want to have a list +of figures, list of tables, or other such contents-like list. You can do +this with \definecontentsfile{abbrev}. All of the +above commands are actually a special case that Eplain predefines with + +

     \definecontentsfile{toc}
+
+

The abbrev is used both for the file extension and in +the control sequence names. + +

+

+ + +Next: , +Previous: Contents, +Up: User definitions + +
+ +

4.9 Cross-references

+ +

It is often useful to refer the reader to other parts of your document; +but putting literal page, section, equation, or whatever numbers in the +text is certainly a bad thing. + +

Eplain therefore provides commands for symbolic cross-references. It +uses an auxiliary file with extension .aux +(and the same root name as your document) to keep track of the +information. Therefore, it takes two passes to get the cross-references +right—one to write them out, and one to read them in. Eplain +automatically reads the .aux file at the first reference; after +reading it, Eplain reopens it for writing. + +

You can control whether or not Eplain warns you about undefined +labels. See Citations. + +

Labels in Eplain's cross-reference commands can use characters of +category code eleven (letter), twelve (other), ten (space), three (math +shift), four (alignment tab), seven (superscript), or eight (subscript). +For example, `(a1 $&^_' is a valid label (assuming the category +codes of plain TeX), but `%#\{' has no valid characters. + +

You can also do symbolic cross-references for bibliographic citations +and list items. See Citations, and Lists. + +

Eplain can create hypertext links for the cross-references; +see Cross-reference hyperlinks. + +

+ +
+

+ +Next: , +Up: Cross-references + +
+ +

4.9.1 Defining generic references

+ +

+Eplain provides the command \definexref for general +cross-references. It takes three arguments: the name of the label (see +section above for valid label names), the value of the label (which can +be anything), and the “class” of the reference—whether it's a +section, or theorem, or what. For example: + +

     \definexref{sec-intro}{3.1}{section}
+
+

Of course, the label value is usually generated by another +macro using TeX count registers or some such. + +

\definexref doesn't actually define label; instead, it +writes out the definition to the .aux file, where Eplain will read +it on the next TeX run. + +

The class argument is used by the \ref and \refs +commands. See the next section. + +

+

+ +Previous: Defining generic references, +Up: Cross-references + +
+ +

4.9.2 Using generic references

+ +

+To retrieve the value of the label defined via \definexref (see +the previous section), Eplain provides the following macros: + + + +

\refn{label}

\xrefn{label}
\refn and \xrefn (they are synonyms) produce the bare +definition of label. If label isn't defined, issue a +warning, and produce label itself instead, in typewriter. (The +warning isn't given if \xrefwarningfalse.) + +
\ref{label}
Given the class c for label (see the description of +\definexref in the previous section), expand the control sequence +\c word (if it's defined) followed by a tie. Then call +\refn on label. (Example below.) + +


\refs{label}
Like \ref, but append the letter `s' to the +\...word. + +
+ +

The purpose of the \...word macro is to produce the word +`Section' or `Figure' or whatever that usually precedes the actual +reference number. + +

Here is an example: + +

     \def\sectionword{Section}
+     \definexref{sec-intro}{3.1}{section}
+     \definexref{sec-next}{3.2}{section}
+     See \refs{sec-intro} and \refn{sec-next} ...
+
+

This produces `See Sections 3.1 and 3.2 ...' + +

+

+ +Next: , +Previous: Cross-references, +Up: User definitions + +
+ +

4.10 Page references

+ +

Eplain provides two commands for handling references to page numbers, +one for definition and one for use. + +

+
\xrdef{label}
Define label to be the current page number. This produces no +printed output, and ignores following spaces. + +
\xref{label}
Produce the text `p. pageno', which is the usual form for +cross-references. The pageno is actually label's +definition; if label isn't defined, the text of the label itself +is printed. The `p. ' prefix is defined by \xrefpageword. +Its default definition is p.\thinspace. + +
+ +

Eplain can create hypertext links for the page references; see Page reference hyperlinks. + +

+

+ +Next: , +Previous: Page references, +Up: User definitions + +
+ +

4.11 Equation references

+ +

Instead of referring to pages, it's most useful if equation labels +refer to equation numbers. Therefore, Eplain reserves a \count +register, \eqnumber, +for the current equation number, and increments it at each +numbered equation. + +

Here are the commands to define equation labels and then refer to them: + +

+
\eqdef{label}
This defines label to be the current value of \eqnumber, +and, if the current context is not inner, then produces a \eqno +command. (The condition makes it possible to use \eqdef in an +\eqalignno construction, for example.) The text of the equation +number is produced using \eqprint. See Formatting equation references. + +

If label is empty, you still get an equation number (although +naturally you can't reliably refer to it). This is useful if you want +to put numbers on all equations in your document, and you don't want to +think up unique labels. + +

To refer to the last equation with the empty label, you just use the +empty label in one of the equation reference macros (see below). This +can be handy when you want to refer to an equation shortly after its +definition, say, in the sentence following the displayed equation, and +do not intend to refer to the equation later. But use this trick with +extreme caution: if later you change the text and insert another +empty definition between the original definition and the reference, +the reference will start to refer to the new empty-labeled equation. + +

\eqdefn{label}
This is like \eqdef, except it always omits the \eqno +command. It can therefore be used in places where \eqdef can't; +for example, in a non-displayed equation. The text of the equation +number is not produced, so you can also use it in the (admittedly +unusual) circumstance when you want to define an equation label but not +print that label. + +
\eqref{label}
This produces a formatted reference to label. If label is +undefined (perhaps because it is a forward reference), it just produces +the text of the label itself. Otherwise, it calls \eqprint. + +
\eqrefn{label}
This produces the cross-reference text for label. That is, it +is like \eqref, except it doesn't call \eqprint. + +
+ +

Equation labels can contain the same characters that are valid in +general cross-references. + +

Eplain can create hypertext links for the equation references; +see Equation reference hyperlinks. + +

+ +
+

+ +Next: , +Up: Equation references + +
+ +

4.11.1 Formatting equation references

+ +

Both defining an equation label and referring to it should usually +produce output. This output is produced with the \eqprint macro, +which takes one argument, the equation number being defined or referred +to. By default, this just produces `(number)', where +number is the equation number. To produce the equation number in +a different font, or with different surrounding symbols, or whatever, +you can redefine \eqprint. +For example, the following definition would print all equation numbers +in italics. (The extra braces define a group, to keep the font change +from affecting surrounding text.) + +

     \def\eqprint#1{{\it (#1)}}
+
+

In addition to changing the formatting of equation numbers, you might +to add more structure to the equation number; for example, you might +want to include the chapter number, to get equation numbers like +`(1.2)'. To achieve this, you redefine \eqconstruct. +For example: + +

     \def\eqconstruct#1{\the\chapternumber.#1}
+
+

(If you are keeping the chapter number in a count register named +\chapternumber, naturally.) + +

The reason for having both \eqconstruct and \eqprint may +not be immediately apparent. The difference is that \eqconstruct +affects the text that cross-reference label is defined to be, while +\eqprint affects only what is typeset on the page. The example +just below might help. + +

Usually, you want equation labels to refer to equation numbers. But +sometimes you might want a more complicated text. For example, you +might have an equation `(1)', and then have a variation several pages +later which you want to refer to as `(1*)'. + +

Therefore, Eplain allows you to give an optional argument (i.e., +arbitrary text in square brackets) before the cross-reference label to +\eqdef. Then, when you refer to the equation, that text is produced. +Here's how to get the example just mentioned: + +

     $$...\eqdef{a-eq}$$
+     ...
+     $$...\eqdef[\eqrefn{a-eq}*]{a-eq-var}$$
+     In \eqref{a-eq-var}, we expand on \eqref{a-eq}, ...
+
+

We use \eqrefn in the cross-reference text, not +\eqref, so that \eqprint is called only once. + +

+

+ +Previous: Formatting equation references, +Up: Equation references + +
+ +

4.11.2 Subequation references

+ +

Eplain also provides for one level of substructure for equations. That +is, you might want to define a related group of equations with numbers +like `2.1' and `2.2', and then be able to refer to the group as a whole: +“... in the system of equations (2)...”. + +

The commands to do this are \eqsubdef and +\eqsubdefn. +They take one label argument like their counterparts above, +and generally behave in the same way. The difference is in how they +construct the equation number: instead of using just \eqnumber, +they also use another counter, \subeqnumber. +This counter is advanced by one at every \eqsubdef or +\eqsubdefn, and reset to zero at every \eqdef or +\eqdefn. + +

You use \eqref to refer to subequations as well as main +equations. + +

To put the two together to construct the text that the label will +produce, they use a macro \eqsubreftext. +This macros takes two arguments, the “main” equation number (which, +because the equation label can be defined as arbitrary text, as +described in the previous section, might be anything at all) and the +“sub” equation number (which is always just a number). Eplain's +default definition just puts a period between them: +

     \def\eqsubreftext#1#2{#1.#2}%
+
+

You can redefine \eqsubreftext to print however you +like. For example, this definition makes the labels print as `2a', +`2b', and so on. +

     \newcount\subref
+     \def\eqsubreftext#1#2{%
+       \subref = #2           % The space stops a <number>.
+       \advance\subref by 96  % `a' is character code 97.
+       #1\char\subref
+     }
+
+

Sadly, we must define a new count register, \subref, +instead of using the scratch count register \count255, because +`#1' might include other macro calls which use \count255. + +

+

+ +Next: , +Previous: Equation references, +Up: User definitions + +
+ +

4.12 Indexing

+ +

+Eplain provides support for generating raw material for an index, and +for typesetting a sorted index. A separate program must do the actual +collection and sorting of terms, because TeX itself has no support +for sorting. + +

Eplain can create hypertext links pointing from the index to the index +terms; see Index hyperlinks. + +

Eplain's indexing commands were designed to work with the program +MakeIndex, available from CTAN hosts in +tex-archive/indexing/makeindex; MakeIndex is also commonly +included in prepackaged TeX distributions. It is beyond the scope of +this manual to explain how to run MakeIndex, and all of its many +options. See http://www.ctan.org/tex-archive/indexing/makeindex/ + +

The basic strategy for indexing works like this: + +

    + +

  1. For a document foo.tex, Eplain's indexing commands (e.g., +\idx; see the section `Indexing terms' below) write the raw index +material to foo.idx. + +

  2. MakeIndex reads foo.idx, collects and sorts the index, and +writes the result to foo.ind. + +
  3. Eplain reads and typesets foo.ind on a subsequent run of +TeX. See the section `Typesetting an index' below. + +
+ +

The texi2dvi program can help you automate this +process, see Invoking Eplain. + +

If your document needs more than one index, each must have its own +file. Therefore, Eplain provides the command \defineindex, which +takes an argument that is a single letter, which replaces `i' in +the filenames and in the indexing command names described below. For +example, + +

     \defineindex{m}
+
+

defines the command \mdx to write to the file +foo.mdx. Eplain simply does \defineindex{i} to define +the default commands. + +

+ +
+

+ +Next: , +Up: Indexing + +
+ +

4.12.1 Indexing terms

+ +

+Indexing commands in Eplain come in pairs: one command that only +writes the index entry to the `.idx' file (see above section), and +one that also typesets the term being indexed. The former always starts +with `s' (for “silent”). In either case, the name always includes +`Idx', where I is the index letter, also described +above. Eplain defines the index `i' itself, so that's what we'll +use in the names below. + +

The silent form of the commands take a subterm as a trailing optional +argument. For example, \sidx{truth}[definition of] on page 75 +makes an index entry that will eventually be typeset (by default) as + +

     truth
+       definition of, 75
+
+

Also, the silent commands ignore trailing spaces. The non-silent ones do not. + +

+ +
+

+ +Next: , +Up: Indexing terms + +
+ +
4.12.1.1 Indexing commands
+ +

Here are the commands. + +

    +
  • \sidx{term}[subterm] makes an index entry for +term, optionally with subterm subterm. +\idx{term} also produces term as output. Example: + + 
              \sidx{truth}[beauty of]
+          The beauty of truth is \idx{death}.
+
    +

    Subterms at the second and further levels can also be +specified in subterm, using the +\idxsubentryseparator character to separate +them. This character is by default `!'. + +

  • \sidxname{First M.}{von Last}[subterm] +makes an index +entry for `von Last, First M.'. You can change the +`, ' by redefining \idxnameseparator. +\idxname{First M.}{von Last} also produces First M. von +Last as output. (These commands are useful special cases of \idx +and \sidx.) Example: + + 
              \sidxname{Richard}{Stark}
+          \idxname{Donald}{Westlake} has written many kinds of novels, under
+          almost as many names.
+
    +
  • \sidxmarked\cs{term}[subterm] makes an index +entry for term[subterm], but term will be put +in the index as \cs{term}, but still sorted as just +term. \idxmarked\cs{term} also typesets +\cs{term}. This provides for the usual ways of changing +the typesetting of index entries. Example: + + 
              \def\article#1{``#1''}
+          \sidxmarked\article{Miss Elsa and Aunt Sophie}
+          Peter Drucker's \idxmarked\article{The Polanyis} is a remarkable
+          essay about a remarkable family.
+
    +
  • \sidxsubmarked{term}\cs{subterm} makes an index +entry for term, subterm as usual, but also puts subterm in +the index as \cs{term}. +\idxsubmarked{term}\cs{subterm} also typesets +term \cs{subterm}, in the unlikely event that your +syntax is convoluted enough to make this useful. Example: + + 
              \def\title#1{{\sl #1}}
+          \sidxsubmarked{Anderson, Laurie}\title{Strange Angels}
+          The \idxsubmarked{Anderson}\title{Carmen} is a strange twist.
+
    +
+ +

The commands above rely on MakeIndex's feature for separating sorting of +an index entry's from its typesetting. You can use this directly by +specifying an index entry as sort@typeset. For +example: + +

     \sidx{Ap-weight@$A_\pi$-weight}
+
+

will sort as Ap-weight, but print with the proper math. +The @ here is MakeIndex's default character for this purpose. +See http://www.ctan.org/tex-archive/indexing/makeindex/. To make an index +entry with an @ in it, you have to escape it with a backslash; +Eplain provides no macros for doing this. + +

After any index command, Eplain runs +\hookaction{afterindexterm}. Because the index commands always +add a whatsit item to the current list, you may wish to preserve a +penalty or space past the new item. For example, given a conditional +\if@aftersctnhead set true when you're at a section heading, you +could do: + +

     \hookaction{afterindexterm}{\if@aftersctnhead \nobreak \fi}
+
+
+

+ +Next: , +Previous: Indexing commands, +Up: Indexing terms + +
+ +
4.12.1.2 Modifying index entries
+ +

+All the index commands described in the previous section take an initial +optional argument before the index term, which modify the index entry's +meaning in various ways. You can specify only one of the following in +any given command, except that begin and end can be +specified together with pagemarkup=cs (separate them with +a comma without a following space, like this: +[begin,pagemarkup=defn]). + +

These work via MakeIndex's “encapsulation” feature. See Customizing indexing, if you're not using the default characters for the +MakeIndex operators. The other optional argument (specifying a subterm) +is independent of these. + +

Here are the possibilities: + +

+
begin
end
These mark an index entry as the beginning or end of a range. The index +entries must match exactly for MakeIndex to recognize them. +Example: + + 
          \sidx[begin]{future}[Cohen, Leonard]
+          ...
+          \sidx[end]{future}[Cohen, Leonard]
+
+

will typeset as something like + + 

          future,
+            Cohen, Leonard, 65–94
+
+
see
This marks an index entry as pointing to another; the real index term is +an additional (non-optional) argument to the command. Thus you can +anticipate a term readers may wish to look up, yet which you have +decided not to index. Example: + + 
          \sidx[see]{analysis}[archetypal]{archetypal criticism}
+
+

becomes + + 

          analysis,
+            archetypal, see archetypal criticism
+
+
seealso
Similar to see (the previous item), but also allows for normal +index entries of the referencing term. Example: + + 
          \sidx[seealso]{archetypal criticism}[elements of]{dichotomies}
+
+

becomes + + 

          archetypal criticism,
+            elements of, 75, 97, 114, see also dichotomies
+
+

(Aside for the academically curious: The archetypally critical book I +took these dichotomous examples from is Laurence Berman's The +Musical Image, which I happened to co-design and typeset.) + +

pagemarkup=cs
This puts \cs before the page number in the typeset index, +thus allowing you to underline definitive entries, italicize examples, +and the like. You do not precede the control sequence cs +with a backslash. (That just leads to expansive difficulties.) Naturally +it is up to you to define the control sequences you want to use. Example: + + 
          \def\defn#1{{\sl #1}}
+          \sidx[pagemarkeup=defn]{indexing}
+
+

becomes something like + + 

          indexing, \defn{75}
+
+
+ +
+

+ +Previous: Modifying index entries, +Up: Indexing terms + +
+ +
4.12.1.3 Proofing index terms
+ +

+As you are reading through a manuscript, it is helpful to see what terms +have been indexed, so you can add others, catch miscellaneous errors, +etc. (Speaking from bitter experience, I can say it is extremely +error-prone to leave all indexing to the end of the writing, since it +involves adding many TeX commands to the source files.) + +

So Eplain puts index terms in the margin of each page, if you +set \indexproofingtrue. It is false by default. The terms +are typeset by the macro \indexproofterm, which takes a single +argument, the term to be typeset. Eplain's definition of +\indexproofterm just puts it into an \hbox, first doing +\indexprooffont, which Eplain defines to select the font +cmtt8. With this definition long terms run off the page, but +since this is just for proofreading anyway, it seems acceptable. + +

On the other hand, we certainly don't want the index term to run into +the text of the page, so Eplain uses the right-hand side of the page +rather than the left-hand page (assuming a language read left to right +here). So \ifodd\pageno, Eplain kerns by \outsidemargin, +otherwise by \insidemargin. If those macros are undefined, +\indexsetmargins defines them to be one inch plus \hoffset. + +

To get the proofing index entries on the proper page, Eplain defines a new +insertion class \@indexproof. To unbox any index proofing +material, Eplain redefines \makeheadline to call +\indexproofunbox before the original \makeheadline. Thus, +if you have your own output routine, that redefines or doesn't use +\makeheadline, it's up to you to call \indexproofunbox at +the appropriate time. + +

+

+ +Next: , +Previous: Indexing terms, +Up: Indexing + +
+ +

4.12.2 Typesetting an index

+ +

+The command \readindexfile{i} reads and typesets the +.ind file that MakeIndex outputs (from the .idx file which +the indexing commands in the previous sections write). Eplain defines a +number of commands that support the default MakeIndex output. + +

More precisely, \readindexfile reads +\indexfilebasename.index-letternd, where the +index-letter is the argument. \indexfilebasename is +\jobname by default, but if you have different indexes in +different parts of a book, you may wish to change it, just as with +bibliographies (see Citations). + +

MakeIndex was designed to work with LaTeX; therefore, by default the +.ind file starts with \begin{theindex} and ends with +\end{theindex}. If no \begin has been defined, Eplain +defines one to ignore its argument and set up for typesetting the index +(see below), and also defines a \end to ignore its argument. (In +a group, naturally, since there is a primitive \end). + +

Eplain calls \indexfonts, sets \parindent = 0pt, and does +\doublecolumns (see Multiple columns) at the +\begin{theindex}. \indexfonts does nothing by default; +it's just there for you to override. (Indexes are usually typeset in +smaller type than the main text.) + +

It ends the setup with \hookrun{beginindex}, so you can +override anything you like in that hook (see Hooks). For example: + +

     \hookaction{beginindex}{\triplecolumns}
+
+

MakeIndex turns each main index entry into an \item, subentries +into \subitem, and subsubentries into \subsubitem. By +default, the first line of main entries are not indented, and subentries +are indented 1em per level. Main entries are preceded by a \vskip +of \aboveitemskipamount, 0pt plus2pt by default. Page +breaks are encouraged before main entries (\penalty -100), but +prohibited afterwards—Eplain has no provision for “continued” +index entries. + +

All levels do the following: + +

+

     \hangindent = 1em
+     \raggedright
+     \hyphenpenalty = 10000
+
+

Each entry ends with \hookrun{indexitem}, so you can change any +of this. For example, to increase the allowable rag: + +

     \hookaction{indexitem}{\advance\rightskip by 2em}
+
+

Finally, MakeIndex outputs \indexspace between each group of +entries in the .ind file. Eplain makes this equivalent to +\bigbreak. + +

+

+ +Previous: Typesetting an index, +Up: Indexing + +
+ +

4.12.3 Customizing indexing

+ +

+By default, MakeIndex outputs `, ' after each term in the index. To +change this, you can add the following to your MakeIndex style +(.ist) file: + +

     delim_0 "\\afterindexterm "
+     delim_1 "\\afterindexterm "
+     delim_2 "\\afterindexterm "
+
+

Eplain makes \afterindexterm equivalent to +\quad. + +

You can also change the keywords Eplain recognizes (see Modifying index entries): + +

+
\idxrangebeginword
`begin' + +
\idxrangeendword
`end' + +
\idxseecmdword
`see' + +
\idxseealsocmdword
`seealso' + +
+ +

You can also change the magic characters Eplain puts into the +.idx file, in case you've changed them in the .ist file: + +

+
\idxsubentryseparator
`!' + +
\idxencapoperator
`|' + +
\idxbeginrangemark
`(' + +
\idxendrangemark
`)' + +
+ +

There is no macro for the actual (`@' by default) +character, because it's impossible to make it expand properly. + +

You can change the (imaginary) page number that “see also” +entries sort as by redefining \idxmaxpagenum. This is 99999 by +default, which is one digit too many for old versions of MakeIndex. + +

The words output by Eplain for “see” and “see also” index entries +are defined by \indexseeword and \indexseealsowords +respectively. You can change the typeface used for these words by +redefining \seevariant. And finally, the macros +\indexsee and \indexseealso actually produce the “see +...” entries, so you can redefine them if you want something +entirely different. If you do redefine them, make them take two +parameters, the term being referenced and the \idxmaxpagenum +(the latter should normally be ignored). See the example below. + +

Unfortunately, it is impossible to reliably control the commas +produced by MakeIndex in front of “see ...” entries in the +.ind file, either at MakeIndex level or at Eplain level. +However, the +sed script named trimsee +distributed with Eplain in the test directory can be used to +filter out these commas from the output of MakeIndex. For example, +suppose you want the following style for your “see ...” entries: + +

     analysis,
+       archetypal (see archetypal criticism)
+     archetypal criticism,
+       elements of, 75, 97, 114 (see also dichotomies)
+
+

You would need to redefine these macros in your TeX +file: + +

     \def\indexsee#1#2{({\seevariant \indexseeword\/ }#1)}
+     \def\indexseealso#1#2{({\seevariant \indexseealsowords\/ }#1)}
+
+

and then filter out the commas in front of the “see ...” +entries by running the following command to produce the .ind +file (assuming the name of the .idx file is myfile.idx +and the trimsee script is placed in the current directory): + +

     prompt$ cat myfile.idx | makeindex | ./trimsee > myfile.ind
+
+

By default, trimsee uses default page list separators and +default “see ...” command names. If you set up MakeIndex to use +different page list separator or change the names of \indexsee +and \indexseealso commands, it is possible to adjust the +trimsee script through its command line options, which are the +following: + +

+
-i is
Use is as a regular expression matching separator before “see +...” commands in the input (default: `, \+'). + +
-o os
Use os as a separator to replace is before “see ...” +commands (default: ` '). + +
-s see
Use see as a regular expression matching “see ...” +commands (default: `\\indexsee'). + +
-h
--help
Print a usage message. + +
-v
--version
Print version. +
+ +

trimsee reads input from the standard input, and directs its +output to the standard output. + +

+

+ +Next: , +Previous: Indexing, +Up: User definitions + +
+ +

4.13 Justification

+ +

Eplain defines three commands to conveniently justify multiple +lines of text: \flushright, \flushleft, and +\center. + +They all work in the same way; let's take \center as the +example. To start centering lines, you say \center inside a +group; to stop, you end the group. Between the two commands, each +end-of-line in the input file also starts a new line in the output file. + +

The entire block of text is broken into paragraphs at blank lines, +so all the TeX paragraph-shaping parameters apply in the usual way. +This is convenient, but it implies something else that isn't so +convenient: changes to any linespacing parameters, such as +\baselineskip, will have no effect on the paragraph in +which they are changed. TeX does not handle linespacing changes +within a paragraph (because it doesn't know where the line breaks are +until the end of the paragraph). + +

The space between paragraphs is by default one blank line's worth. +You can adjust this space by assigning to \blanklineskipamount; +this (vertical) glue is inserted after each blank line. + +

Here is an example: +

     {\center First line.
+     
+        Second line, with a blank line before.
+     }
+
+

This produces: + +

First line.
+
+
Second line, with a blank line before.
+ +

You may wish to use the justification macros inside of your own +macros. Just be sure to put them in a group. For example, here is how +a title macro might be defined: + +

     \def\title{\begingroup\titlefont\center}
+     \def\endtitle{\endgroup}
+
+
+

+ +Next: , +Previous: Justification, +Up: User definitions + +
+ +

4.14 Tables

+ +

Eplain provides a single command, \makecolumns, +to make generating one particular kind of table easier. More ambitious +macro packages might be helpful to you for more difficult applications. +The files ruled.tex and TXSruled.tex, available from +`lifshitz.ph.utexas.edu' in texis/tables, is the only one I +know of. + +

Many tables are homogenous, i.e., all the entries are semantically the +same. The arrangement into columns is to save space on the page, not +to encode different meanings. In this kind of the table, it is useful to +have the column breaks chosen automatically, so that you can add or +delete entries without worrying about the column breaks. + +

\makecolumns takes two arguments: the number of entries in the +table, and the number of columns to break them into. As you can see +from the example below, the first argument is delimited by a slash, and +the second by a colon and a space (or end-of-line). The entries for the +table then follow, one per line (not including the line with the +\makecolumns command itself). + +

\parindent defines the space to the left of the +table. \hsize defines the width of the table. +So you can adjust the position of the table on the page by assignments +to these parameters, probably inside a group. + +

You can also control the penalty at a page break before the +\makecolumns by setting the parameter +\abovecolumnspenalty. +Usually, the table is preceded by some explanatory text. You wouldn't +want a page break to occur after the text and before the table, so +Eplain sets it to 10000. But if the table produced by +\makecolumns is standing on its own, \abovecolumnspenalty +should be decreased. + +

If you happen to give \makecolumns a smaller number of entries +than you really have, some text beyond the (intended) end of the table +will be incorporated into the table, probably producing an error +message, or at least some strange looking entries. And if you give +\makecolumns a larger number of entries than you really have, +some of the entries will be typeset as straight text, probably also +looking somewhat out of place. + +

Here is an example: +

     % Arrange 6 entries into 2 columns:
+     \makecolumns 6/2: % This line doesn't have an entry.
+     one
+     two
+     three
+     four
+     five
+     six
+     Text after the table.
+
+

This produces `one', `two', and `three' in the first column, and +`four', `five', and `six' in the second. + +

+

+ +Next: , +Previous: Tables, +Up: User definitions + +
+ +

4.15 Margins

+ +

TeX's primitives describe the type area in terms of an offset from +the upper left corner, and the width and height of the type. Some +people prefer to think in terms of the margins at the top, bottom, +left, and right of the page, and most composition systems other than +TeX conceive of the page laid out in this way. Therefore, Eplain +provides commands to directly assign and increment the margins. + +

+
\topmargin = dimen
\bottommargin = dimen
\leftmargin = dimen
\rightmargin = dimen
These commands set the specified margin to the dimen given. +The = and the spaces around it are optional. The control +sequences here are not TeX registers, despite appearances; +therefore, commands like \showthe\topmargin will not do what you +expect. + +
\advancetopmargin by dimen
\advancebottommargin by dimen
\advanceleftmargin by dimen
\advancerightmargin by dimen
These commands change the specified margin by the dimen given. +
+ +

Regardless of whether you use the assignment or the advance commands, +Eplain always changes the type area in response, not the other margins. +For example, when TeX starts, the left and right margins are both one +inch. If you then say \leftmargin = 2in, the right margin will +remain at one inch, and the width of the lines (i.e., \hsize) +will decrease by one inch. + +

When you use any of these commands, Eplain computes the old value of +the particular margin, by how much you want to change it, and then +resets the values of TeX's primitive parameters to correspond. +Unfortunately, Eplain cannot compute the right or bottom margin without +help: you must tell it the full width and height of the final output +page. It defines two new parameters for this: + +

+
\paperheight
The height of the output page; default is 11truein. + +
\paperwidth
The width of the output page; default is 8.5truein. +
+ +

If your output page has different dimensions than this, you must +reassign to these parameters, as in + +

     \paperheight = 11truein
+     \paperwidth = 17truein
+
+
+

+ +Next: , +Previous: Margins, +Up: User definitions + +
+ +

4.16 Multiple columns

+ +

Eplain provides for double, triple, and quadruple column output: say +\doublecolumns, +\triplecolumns, +or \quadcolumns, +and from that point on, the manuscript will be +set in columns. To go back to one column, say +\singlecolumn. + +You may need to invoke \singlecolumn to balance the columns +on the last page of output. + +

To do a “column eject”, i.e., move to the top of the next column, do +\columnfill. This does not actually force an eject, however: it +merely inserts a kern of size \@normalvsize minus +\pagetotal (\@normalvsize being the usual height of the +page; to implement multicolumns, Eplain multiplies \vsize itself +by the number of columns). In most circumstances, a column break will be +forced after this kern (during the column splitting operation when the +whole page is output), as desired. + +

The columns are separated by the value of the dimen parameter +\gutter. Default value is two picas. +If you want to add vertical material between the columns, use +\gutterbox. For example, to put a vertical line between columns, +define +\gutterbox as +

     \def\gutterbox{\vbox to \dimen0{\vfil\hbox{\vrule height\dimen0}\vfil}}%
+
+

The dimension counter +\dimen0 +contains the height of the column. + +

All the \...columns macros insert the value of the glue parameter +\abovecolumnskip +before the multicolumn text, and the value of the glue parameter +\belowcolumnskip +after it. The default value for both of these parameters is +\bigskipamount, i.e., one linespace in plain TeX. + +

The macros take into account only the insertion classes +defined by plain TeX; namely, footnotes and \topinserts. If +you have additional insertion classes, you will need to change +the implementation. + +

Also, Eplain makes insertions the full page width. There is no +provision for column-width insertions. + +

+

+ +Next: , +Previous: Multiple columns, +Up: User definitions + +
+ +

4.17 Footnotes

+ +

The most common reference mark for footnotes is a raised number, +incremented on each footnote. The \numberedfootnote +macro provides this. It takes one argument, the footnote text. + +

If your document uses only numbered footnotes, you could make typing +\numberedfootnote more convenient with a command such as: + +

     \let\footnote = \numberedfootnote
+
+

After doing this, you can type your footnotes as +\footnote{footnote text}, instead of as +\numberedfootnote{footnote text}. + +

Eplain keeps the current footnote number in the count register +\footnotenumber. So, to reset the footnote number to zero, +as you might want to do at, for example, the beginning of a chapter, you +could say \footnotenumber=0. + +

Plain TeX separates the footnote marker from the footnote text by +an en space (it uses the \textindent macro). In Eplain, you can +change this space by setting the dimension register +\footnotemarkseparation. +The default is still an en. + +

You can produce a space between footenotes by setting the glue +register \interfootnoteskip. +The default is zero. + +

\parskip is also set to zero by default before the beginning of +each footnote (but not for the text of the footnote). + +

You can also control footnote formatting in a more general way: +Eplain expands the token register \everyfootnote +before a footnote is typeset, but after the default values for all the +parameters have been established. For example, if you want your +footnotes to be printed in seven-point type, indented by one inch, you +could say: +

     \everyfootnote = {\sevenrm \leftskip = 1in}
+
+

By default, an \hrule is typeset above each group of footnotes +on a page. You can control the dimensions of this rule by setting +the dimension registers \footnoterulewidth +and \footnoteruleheight. +The space between the rule and the first footnote on the page is +determined by the dimension register \belowfootnoterulespace. +If you don't want any rule at all, set \footenoteruleheight=0pt, +and, most likely, \belowfootnoterulespace=0pt. The defaults for +these parameters typeset the rule in the same way as plain TeX: the +rule is 0.4 points high, 2 true inches wide, with 2.6 points below it. + +

The space above the rule and below the text on the page is controlled +by the glue register \skip\footins. The default is a plain TeX +\bigskip. + +

Eplain can create hypertext links for the footnote marks; see Footnote hyperlinks. + +

+

+ +Next: , +Previous: Footnotes, +Up: User definitions + +
+ +

4.18 Fractions

+ +

Exercise 11.6 of The TeXbook describes a macro \frac +for setting fractions, but \frac never made it into plain TeX. +So Eplain includes it. + +

\frac typesets the numerator and denominator in +\scriptfont0, slightly raised and lowered. The numerator and +denominator are separated by a slash. The denominator must be enclosed +in braces if it's more than one token long, but the numerator need not +be. (This is a consequence of \frac taking delimited arguments; +see page 203 of The TeXbook for an explanation of +delimited macro arguments.) + +

For example, \frac 23/{64} turns `23/64' into +. + +

+

+ +Next: , +Previous: Fractions, +Up: User definitions + +
+ +

4.19 Paths

+ +

+When you typeset long pathnames, electronic mail addresses, or other +such “computer” names, you would like TeX to break lines at +punctuation characters within the name, rather than trying to find +hyphenation points within the words. For example, it would be better to +break the email address letters@alpha.gnu.ai.mit.edu at the +`@' or a `.', rather than at the hyphenation points in +`letters' and `alpha'. + +

If you use the \path macro to typeset the names, TeX will find +these good breakpoints. The argument to \path is delimited by +any character other other than `\' which does not appear in the +name itself. +`|' is often a good choice, as in: +

     \path|letters@alpha.gnu.ai.mit.edu|
+
+

You can control the exact set of characters at which breakpoints will be +allowed by calling \discretionaries. This takes the same sort of +delimited argument; any character in the argument will henceforth be a valid +breakpoint within \path. The default set is essentially all the +punctuation characters: +

     \discretionaries |~!@$%^&*()_+`-=#{}[]:";'<>,.?\/|
+
+

If for some reason you absolutely must use \ as the delimiter +character for \path, you can set +\specialpathdelimiterstrue. (Other delimiter characters can +still be used.) TeX then processes the \path argument +about four times more slowly. + +

The \path macro comes from path.sty, written by Nelson +Beebe and Philip Taylor and available at +http://www.ctan.org/tex-archive/macros/latex/contrib/misc/path.sty. + +

+

+ +Next: , +Previous: Paths, +Up: User definitions + +
+ +

4.20 Logos

+ +

+Eplain redefines the \TeX +macro of plain TeX to end with \null, so that the proper +spacing is produced when \TeX is used at the end of a sentence. +The other ...TeX macros listed here do this, also. + +

Eplain defines +\AMSTeX, +\BibTeX +\AMSLaTeX, +\LAMSTeX, +\LaTeX +\MF, +and \SLiTeX +to produce their respective logos. (Sorry, the logos are not shown +here.) Some spelling variants of these are also supported. + +

All these macros come from texnames.sty, compiled by Nelson +Beebe and available at +http://www.ctan.org/tex-archive/info/biblio/texnames.sty. + +

+

+ +Next: , +Previous: Logos, +Up: User definitions + +
+ +

4.21 Boxes

+ +

The solid rectangle that Eplain uses as a marker in unordered lists +(see Lists) is available by itself: just say \blackbox. + +You can create black boxes of arbitrary size with \hrule or +\vrule. + +

You can also get unfilled rectangles with \makeblankbox. +This takes two explicit arguments: the height and depth of the rules that +define the top and bottom of the rectangle. (The two arguments are +added to get the width of the left and right borders, so that the +thickness of the border is the same on all four sides.) It also uses, +as implicit arguments, the dimensions of \box0 to define the +dimensions of the rectangle it produces. (The contents of \box0 +are ignored.) + +

Here is an example. This small raised open box is suitable for +putting next to numbers in, e.g., a table of contents. + +

     \def\openbox{%
+       \ht0 = 1.75pt \dp0 = 1.75pt \wd0 = 3.5pt
+       \raise 2.75pt \makeblankbox{.2pt}{.2pt}
+     }
+
+

Finally, you can put a box around arbitrary text with \boxit. +This takes one argument, which must itself be a (TeX) box, and puts a +printed box around it, separated by \boxitspace +white space (3 points by default) on all four sides. For example: + +

     \boxit{\hbox{This text is boxed.}}
+
+

The reason that the argument must be a box is that when the text is +more than one line long, TeX cannot figure out the line length for +itself. Eplain does set \parindent to zero inside \boxit, +since it is very unlikely you would want indentation there. (If you do, +you can always reset it yourself.) + +

\boxit uses \ehrule and \evrule so that you can +easily adjust the thicknesses of the box rules. See Rules. + +

+

+ +Next: , +Previous: Boxes, +Up: User definitions + +
+ +

4.22 Checking for PDF output

+ +

pdfTeX is a TeX variant that can output both .dvi and +.pdf (Adobe's Portable Document Format) files (see +http://www.ctan.org/tex-archive/systems/pdftex/). You might +sometimes want to know whether the target format is .pdf or +.dvi. The \ifpdf +switch can be used to detect pdfTeX in PDF mode: + +

     \ifpdf
+        This text is produced when pdfTeX is in PDF mode.
+     \else
+        This text is produced when pdfTeX is in DVI mode,
+        or when some program other than pdfTeX is used.
+     \fi
+
+

Keep in mind that \ifpdf is set based on the value of the +\pdfoutput +primitive of pdfTeX at the time Eplain is loaded. If you change +the value of \pdfoutput after you load Eplain, \ifpdf +will not reflect the change. + +

Eplain defines \ifpdf by incorporating Heiko Oberdiek's +ifpdf.sty, which is available at +http://www.ctan.org/tex-archive/macros/latex/contrib/oberdiek/ifpdf.sty. + +

+

+ +Previous: Checking for PDF output, +Up: User definitions + +
+ +

4.23 Loading LaTeX packages

+ +

Eplain provides a limited support for loading LaTeX packages +(.sty files—not .cls). This will mostly work for +packages which were designed with plain TeX compatibility in mind, +which means that most LaTeX packages cannot be loaded. The +packages which are known to work are listed below (see Packages known to work). If you discover a working package which is not in +the list, please report it to the Eplain mailing list +(see Introduction). + +

To set up a pseudo-LaTeX environment for the packages, Eplain uses +miniltx.tex +(http://www.ctan.org/tex-archive/macros/plain/graphics/miniltx.tex) +from the LaTeX graphics collection, written by David Carlisle and +Sebastian Rahtz (the collection is available at +http://www.ctan.org/tex-archive/macros/latex/required/graphics/). +Eplain extends miniltx.tex to provide some additional features, +e.g., support for package options. + +

+ +
+

+ + +Next: , +Up: Loading LaTeX packages + +
+ +

4.23.1 The \usepackage command

+ +

\usepackage loads a LaTeX package. Its syntax is similar to +that of LaTeX's \usepackage command: + +

     \usepackage[options]{packages}[version]
+
+

where options is a comma-separated list of package +options, packages is a comma-separated list of packages to load +(without the .sty suffix), and version is a package +version number given as a date in the format `YYYY/MM/DD'. If an +older version of the package is found, a warning is issued. If +several packages are loaded within a single \usepackage +command, the options will be applied to each of the packages. +As usual, parameters in square brackets are optional and can be +omitted (together with the square brackets). + +

For example: + +

     \usepackage[foo,bar]{pack1,pack2}[2005/08/29]
+
+

will load packages `pack1' and `pack2', each with +the options `foo' and `bar', and will check that each of the +packages are dated 2005/08/29 or newer. + +

+

+ +Next: , +Previous: The \usepackage command, +Up: Loading LaTeX packages + +
+ +

4.23.2 Environment for loading packages

+ +

Some packages request that certain commands are executed after all +packages have been loaded. In LaTeX, this means that the commands +are executed at the beginning of the document, after the so-called +preamble. Neither plain TeX nor Eplain have any kind of +preamble; therefore, Eplain requires that all packages be loaded inside +a \beginpackages...\endpackages block, for example: + +

     \beginpackages
+       \usepackage[foo,bar]{pack1}
+       \usepackage{pack2}
+     \endpackages
+
+

This requirement enables Eplain to execute the “delayed” +commands at the end of the \beginpackages...\endpackages block. + +

For the same reason, it is advisable to specify only one such block +per document, just like there is only one preamble in LaTeX. + +

+

+ +Next: , +Previous: Environment for loading packages, +Up: Loading LaTeX packages + +
+ +

4.23.3 Packages known to work

+ +

The following table lists packages that had been tested and are known +to work with Eplain, and locations where you can find manuals for +these packages. Some of the short descriptions of the packages were +taken from the documentation for those packages. + +

+
autopict (`2001/06/04 v1.1j Picture mode autoload file')
http://tug.org/eplain/ltpictur.pdf + +

This is the LaTeX “picture mode”, started by +\begin{picture} and ended by \end{picture} (in +LaTeX, this package is not explicitly loaded since it is part of +the LaTeX kernel). It provides commands to draw simple figures +inside your document without resorting to any external tools. + +

color (`1999/02/16 v1.0i Standard LaTeX Color (DPC)')
graphics (`2001/07/07 v1.0n Standard LaTeX Graphics (DPC,SPQR)')
graphicx (`1999/02/16 v1.0f Enhanced LaTeX Graphics (DPC,SPQR)')
http://www.ctan.org/tex-archive/macros/latex/required/graphics/grfguide.pdf + +

These packages are from the LaTeX graphics collection. They +provide commands for changing text/page colors, text rotation and +scaling, and much more. + +

psfrag (`1998/04/11 v3.04 PSfrag (MCG)')
http://www.ctan.org/tex-archive/macros/latex/contrib/psfrag/pfgguide.pdf + +

PSfrag allows the user to precisely overlay Encapsulated PostScript +(EPS) files with arbitrary (La)TeX constructions. In order to +accomplish this, the user places a simple text “tag” in the graphics +file, as a “position marker” of sorts. Then, using simple +(La)TeX commands, the user instructs PSfrag to remove that tag from +the figure, and replace it with a properly sized, aligned, and rotated +(La)TeX equation. + +

url (`2005/06/27 ver 3.2 Verb mode for urls, etc.')
http://www.ctan.org/tex-archive/macros/latex/contrib/misc/url.sty + +

This package provides a form of \verbatim that allows +line breaks at certain characters or combinations of characters, +accepts reconfiguration, and can usually be used in the argument to +another command. It is intended for email addresses, hypertext links, +directories/paths, etc., which normally have no spaces. + +

Eplain can create hypertext links with the \url command; +see URL hyperlinks. +

+ +
+

+ +Previous: Packages known to work, +Up: Loading LaTeX packages + +
+ +

4.23.4 Packages known not to work

+ +

The following packages are known not to work with Eplain: + +

+
pict2e (`2005/07/15 v0.2r Improved picture commands (HjG,RN)')
http://www.ctan.org/tex-archive/macros/latex/contrib/pict2e/ + +
xcolor (`2005/06/06 v2.03 LaTeX color extensions (UK)')
http://www.ctan.org/tex-archive/macros/latex/contrib/xcolor/ +
+ + +
+

+ +Next: , +Previous: User definitions, +Up: Top + +
+ +

5 Hyperlinks

+ +

This chapter describes the support which Eplain provides for hypertext +links (hyperlinks for short). Hyperlinks can be created +implicitly by the cross-reference, indexing and other macros in +Eplain. Macros for constructing explicit hyperlinks are also +provided. + +

+ +
+

+ +Next: , +Up: Hyperlinks + +
+ +

5.1 Introduction to hyperlinks

+ +

The original TeX engine has no built-in support for hyperlinks. +Many of the present-day file formats with hyperlinking capabilities +did not even exist at the time TeX was written. However, TeX's +\special primitive can be used to instruct TeX to write +special directives into its .dvi output file. These directives +are not interpreted by TeX in any way; they are intended for programs +which process the .dvi files produced by TeX, be it printing +or converting to other formats, such as +.ps or .pdf. + +

Another approach is to extend the original TeX engine with the +ability to generate one of the hyperlinking formats; TeX's set of +primitives can be extended to include hyperlink commands. This is the +approach used by the pdfTeX engine, which is capable of producing +.pdf files directly from the TeX source, skipping the +.dvi generation and processing step. + +

It turns out that the sets of commands for different formats are mostly +not interchangeable, as each of the file formats has its own quirks and +capabilities. And this is where Eplain hyperlink drivers come +into play. + +

In order for Eplain to generate proper commands, Eplain has to know +two things: which engine or .dvi processor you are using, and +the set of commands it understands. + +

The knowledge about the commands that the various processors +understand is programmed into Eplain's hyperlink drivers. Eplain +provides two drivers, pdftex and dvipdfm, named after +the programs which process the hyperlink commands, +pdfTeX and +dvipdfm. Therefore, Eplain can only produce hyperlink commands for one +of these two programs—except that the extended dvipdfmx program +can be used as well as the original dvipdfm, since they are +compatible. + +

To tell Eplain which .dvi processor or extended TeX engine you +are using, use the command +\enablehyperlinks. + +

For example: + +

     \enablehyperlinks
+
+

instructs Eplain to attempt to automatically detect which +driver to use, as follows: if it detects pdfTeX in PDF mode, it +loads the pdftex driver. If it does not detect pdfTeX in +PDF mode, the dvipdfm driver is loaded. The detection is based +on the +\ifpdf switch (see Checking for PDF output). + +

If necessary, you can explicitly specify the driver name: + +

     \enablehyperlinks[pdftex]
+
+

will start producing hyperlinks under the assumption that +you are using pdfTeX. + +

Eplain does not produce any hyperlinks until you explicitly enable +them with \enablehyperlinks. For one thing, this keeps Eplain +backward-compatible with previous releases without hyperlink support. +For another, you may be using a program other than pdfTeX or +dvipdfm, which does not understand their hyperlink commands. + +

Concepts and Terminology

+ +

In general, hyperlinks work as follows. You mark some place in your +document as a hyperlink destination, associating a hyperlink +label with that destination. Next, somewhere within your document, +you create a hyperlink, using a label to identify the destination you +want this link to point to. A hyperlink is a region in the document +(which can take many forms, for example, text or a picture); when a +user clicks on that region, they will be taken to a place in the +document marked by the corresponding destination. The following two +sections (Explicit hyperlinks, and Implicit hyperlinks) +describe the macros you can use to define destinations and create +links pointing to those destinations. + +

In the rest of this chapter, we will often need to refer to links and +destinations jointly, in which case we will use the term +hyperlinks. We will use the terms links and +destinations in cases when we need to refer specifically to +links or destinations. + +

Hyperlink drivers provide several kinds of links and destinations. We +will refer to them as link types and destination types. + +

For example, one of the destination types that the pdftex +driver provides is the `xyz' type; when the user follows a link +pointing to an `xyz' destination, the exact location marked by +that destination is displayed. Another destination type provided by +the pdftex driver is the `fit' type; when the user follows +a link pointing to a `fit' destination, the page containing that +destination is zoomed to fit into the window in which the document is +displayed. + +

Similarly, drivers support various link types. For example, with the +pdftex driver, the usual link type used to refer to +destinations in the current document is called `name'. You can +also create a link pointing to another local document (by using the +`filename' link type) or to a URL (by using the `url' link +type). + +

In addition, each hyperlink driver supports a number of destination and +link options. By setting these options you can customize +hyperlink parameters (e.g., the thickness of the border drawn around a +hyperlink) or pass information to hyperlinks (for example, file name of +a document, for a link pointing to a destination in another document). + +

See Hyperlink drivers, for the description of hyperlink types and +options supported by the drivers. See Setting hyperlink types and options, for the information on how to set hyperlink options. + +

+

+ +Next: , +Previous: Introduction to hyperlinks, +Up: Hyperlinks + +
+ +

5.2 Explicit hyperlinks

+ +

Explicit hyperlinks are created by you, in the source of your +document. The simplest command is \hldest, which marks the +current position in your document as a destination: + +

     \hldest{type}{options}{label}
+
+

Here type is one of the destination types supported by +the hyperlink driver (see Hyperlink drivers), options is a +comma-separated list of option assignments, and label is the +hyperlink label to associate with this destination. This label will +identify the destination when creating links pointing to this +destination. For example, with the pdftex driver, the command + +

     \hldest{xyz}{zoom=2000}{index}
+
+

creates a destination of type `xyz' (“the current +position”), sets the magnification ratio for this destination to be +200%, and associates the label index with the destination. + +

Another command, \hlstart, paired with \hlend, turns all +intervening material into a link: + +

     \hlstart{type}{options}{label} ... \hlend
+
+

Here type, options and label have the same +meaning as for \hldest. Continuing the previous example, + +

     \hlstart{name}{bstyle=U,bwidth=2}{index} Index\hlend
+
+

typesets the word `Index' as a link with underline border of +width 2 PostScript points, pointing to the named destination +index defined in the previous example. (The other options, like +highlight mode and border color, are determined by the defaults, +see Setting default types and options). + +

Both \hldest and \hlstart ignore following spaces. + +

Both \hldest and \hlstart expand the first token of +options once, so you can save a list of options in a macro and +pass it for the options. For example: + +

     \def\linkopts{bstyle=U,bwidth=2}
+     \hlstart{name}{\linkopts}{index}Index\hlend
+
+

is functionally equivalent to the previous example. + +

+

+ +Next: , +Previous: Explicit hyperlinks, +Up: Hyperlinks + +
+ +

5.3 Implicit hyperlinks

+ +

Implicit hyperlinks are hyperlinks created implicitly by various +Eplain macros, such as the macros for citations, cross-references, +indexing, etc. + +

All such macros are divided into link groups and +destination groups (or linkgroups and destgroups for +short) so that parameters can be set individually for each group. For +example, all equation macros which define a destination are assigned +to the `eq' destgroup; equation macros which create a link are +assigned to the `eq' linkgroup. By setting parameters for the `eq' +linkgroup (destgroup), you can uniformly customize all links +(destinations) related to equation references, without interfering +with settings for the other groups. + +

See Setting hyperlink types and options, for information on how to +set parameters for a group. + +

Here is the list of the linkgroups: + +

     cite, ref, xref, eq, idx, foot, footback, url.
+
+

And here are the destgroups: + +

     bib, li, definexref, xrdef, eq, idx, foot, footback.
+
+

The following subsections describe each of the linkgroups and destgroups +and the hyperlink support provided. + +

+ +
+

+ +Next: , +Up: Implicit hyperlinks + +
+ +

5.3.1 URL hyperlinks: url

+ +

The `url' linkgroup covers the +\url command from the LaTeX package +url (see Packages known to work), as well as any new +\url-like commands you define. The type for this linkgroup is +set to `url' by the drivers which support this link type. +`url' links use the parameter to the \url command as the URL +to point to. + +

You may be using the \url command to typeset something other than +a URL, e.g., a path, for which you do not want a link to be created; in +that case, you can disable the `url' linkgroup with the command +\hloff[url] (see Turning hyperlinks on/off for a group). + +

+

+ +Next: , +Previous: URL hyperlinks, +Up: Implicit hyperlinks + +
+ +

5.3.2 Citation hyperlinks: cite, bib

+ +

The `cite' linkgroup includes only the \cite command +(see Citations). \cite turns each of the references in the +list into a link pointing to the respective bibliography entry +produced by the \bibliography command. + +

The `bib' destgroup includes the macros related to the +\bibliography command (see Citations). \bibliography +inputs a .bbl file, which contains a list of bibliography +entries. For each of the entries, a destination is defined. + +

Both commands use the citation label as the hyperlink label. + +

+

+ +Next: , +Previous: Citation hyperlinks, +Up: Implicit hyperlinks + +
+ +

5.3.3 List hyperlinks: li

+ +

The `li' destgroup consists of the \li command (see Lists), +which defines a destination if you supply the optional argument +(cross-reference label). This label is also used as the hyperlink +label. + +

+

+ + +Next: , +Previous: List hyperlinks, +Up: Implicit hyperlinks + +
+ +

5.3.4 Cross-reference hyperlinks: definexref, ref

+ +

The `definexref' destgroup is for the \definexref command +(see Defining generic references). \definexref defines a +destination using the cross-reference label (the first argument) as the +hyperlink label. + +

The `ref' linkgroup includes \refn and \xrefn (they are +synonyms), \ref, and \refs (see Using generic references). + +

\refn turns the cross-reference it produces into a link, using +the cross-reference label as the hyperlink label. If an optional +argument is present, it is tied by +\reftie to the reference and become part of the link. + +

\ref works similarly to \refn. It takes an optional +argument, which is treated the same way as the optional argument to +\refn. In addition, \ref can produce a “class word”. +Both the optional argument and the class word become part of the link, +when present. The cross-reference is tied by +\reftie to the preceding word. The optional argument is +separated from the class word by +\refspace. + +

Unlike \ref, \refs does not take an optional argument and +does not make the class word part of the link, which is appropriate for +its intended use. + +

+

+ +Next: , +Previous: Cross-reference hyperlinks, +Up: Implicit hyperlinks + +
+ +

5.3.5 Page reference hyperlinks: xrdef, xref

+ +

The `xrdef' destgroup is for \xrdef (see Page references). +\xrdef defines a destination using cross-reference label as the +hyperlink label. + +

The `xref' linkgroup includes the \xref command (see Page references). \xref turns its optional argument (followed by +\refspace), \xrefpageword and the cross-reference (page +number) into a link, using the cross-reference label as the hyperlink +label. + +

+

+ +Next: , +Previous: Page reference hyperlinks, +Up: Implicit hyperlinks + +
+ +

5.3.6 Equation reference hyperlinks: eq

+ +

All commands that define equation labels are part of the `eq' destgroup. +These are \eqdef, \eqdefn, \eqsubdef and +\eqsubdefn (see Equation references). All these commands use +the equation label as the hyperlink label. However, if the equation +label is empty, they make up a (hopefully) unique hyperlink label for +the destination. This label will be used for the link when you refer to +this empty-labeled equation with one of the equation reference macros. + +

The command \phantomeqlabel is called to generate hyperlink +labels for the empty-labeled equations. By default, it produces the +labels in the format `PHEQnumber', where number comes +from the count register \phantomeqnumber; this count register is +incremented at every empty-labeled equation definition. + +

The commands \eqref and \eqrefn (see Equation references) form the `eq' linkgroup. These commands take an optional +argument, which, when present, is tied with \reftie to the +equation reference and becomes part of the link. The equation label is +used for the hyperlink label; if the label is empty, the link is for the +label generated for the last empty-labeled equation. + +

+

+ +Next: , +Previous: Equation reference hyperlinks, +Up: Implicit hyperlinks + +
+ +

5.3.7 Index hyperlinks: idx

+ +

All indexing commands (\idx, \idxname, \idxmarked, +\idxsubmarked and their silent equivalents, see Indexing commands) form the `idx' destgroup. The `idx' linkgroup consists of +the macros which are used to typeset the index when you say +\readindexfile{index-letter} (see Typesetting an index). + +

To create the links in index entries, Eplain uses MakeIndex's +“encapsulation” feature. When you use an indexing macro to mark an +index term, Eplain writes out a line to the +.idx file of the following general form: + +

     \indexentry{entry|pagemarkup}{pageno}
+
+

where entry is the index entry (converted into the +internal format that MakeIndex understands), cs is the markup +command you specified with the pagemarkup=cs optional +argument to the indexing commands (see Modifying index entries), +and pageno is the page number on which the term appeared. When +processing the .idx file, MakeIndex makes the page number an +argument to the page markup command (“encapsulates” the page +number), so the page number in the +.ind file appears as \cs{pageno}. Eplain +internally replaces the cs command name with its own command, +which, in addition to calling the original \cs +encapsulator, turns the page number into a link. + +

Eplain provides two approaches to linking page numbers in the index to +locations of index terms in the text. + +

+ +
+

+ +Next: , +Up: Index hyperlinks + +
+ +
5.3.7.1 Exact destinations for index terms
+ +

In this approach, each command that marks an index term defines a unique +destination and passes its label on to the .idx file as part of +the \indexentry command. The \indexentry line that Eplain +writes to the .idx file becomes + +

     \indexentry{entry|hlidx{label}{cs}}{pageno}
+
+

where \hlidx is the command that is defined by Eplain +to take three arguments: a hyperlink label (label), a name of +page number encapsulator (cs) and a page number (pageno). +In the .ind file that MakeIndex will generate, the page number +will now appear as + +

     \hlidx{label}{cs}{pageno}
+
+

The result of this command is +\cs{pageno}, wrapped up into a link pointing to +label destination. + +

The hyperlink labels for the index terms are generated by the +\hlidxlabel command, by default in the format +`IDXnumber', where number is the value of the count +register +\hlidxlabelnumber. This count register is incremented at each +index term. + +

The advantage of this approach, as compared to the second approach +described below, is that links in the index point to exact locations of +the indexed terms on the page. The disadvantage of this approach is +that MakeIndex will regard all index entries as distinct, because +each one contains a (unique) hyperlink label. This disadvantage can be +partially overcome by the script +idxuniq distributed with Eplain in the util directory. +This script filters out \indexentry lines differing only in the +hyperlink label but identical otherwise. You should process the +.idx with this script before passing it on to MakeIndex. For +example: + +

     prompt$ ./idxuniq file.idx | makeindex > file.ind
+
+

Still, this solution is not ideal, as the page-range formation +ability of MakeIndex will not work, and there will be problems of +apparently identical index entries clashing (e.g., when a range-end +entry appears on the same page as another entry with the same +definition; idxuniq will not filter out the second entry). + +

+

+ +Next: , +Previous: Exact destinations for index terms, +Up: Index hyperlinks + +
+ +
5.3.7.2 Page destinations for index terms
+ +

In the second approach, Eplain does not write out any destination labels +for the index terms. Instead, Eplain writes out a wrapper for page +number encapsulator which can parse the page number and generate a link +pointing to the page on which the term appeared. On top of each +page containing an index term, Eplain defines a destination with label +produced by +\hlidxpagelabel. The \hlidxpagelabel command takes a +single argument (page number number) and by default produces the +label in the format `IDXPGnumber'. + +

With this approach, the \indexentry line which Eplain writes to +the .idx file looks like this: + +

     \indexentry{entry|hlidxpage{cs}}{pageno}
+
+

where \hlidxpage is the command that is defined by Eplain +to take two arguments: a name of page number encapsulator (cs) +and a page number (pageno). In the .ind file that +MakeIndex will generate, the page number will appear as + +

     \hlidxpage{cs}{pageno}
+
+

The advantage of this approach is that all features of MakeIndex are +intact. The drawback is that links in the index do not point to exact +locations of indexed terms on a page, but to the top of a page on +which the term appears. + +

Another disadvantage is that this approach depends on the page range and +page list separators which MakeIndex was configured to output. +\hlidxpage must be able to parse the first page number in a page +range like `1--4'. In addition, page list parsing is needed +because MakeIndex combines two consecutive page numbers in one call to +the page number encapsulator, so \hlidxpage can be passed, e.g., +`1, 2' for the pageno. In this last case, \hlidxpage +splits the two page numbers, applies \cs to each of them, +and makes each of the page numbers a link to the appropriate page. Note +that this will alter typesetting slightly, because now the page list +separator (a comma followed by a space, by default) is not typeset using +the page number encapsulator (\cs). + +

Eplain's defaults for the page list and page number delimiters are the +same as those in MakeIndex, a comma followed by a space (`, ') and +two dashes (`--'), respectively. If you customize MakeIndex to use +different delimiters, you must not forget to let Eplain know about them +with the commands + +

     \setidxpagelistdelimiter{list-delim}
+     \setidxpagerangedelimiter{page-delim}
+
+

(see Page list and page range parsers). + +

+

+ +Next: , +Previous: Page destinations for index terms, +Up: Index hyperlinks + +
+ +
5.3.7.3 Choosing destination placement
+ +

The approach that Eplain should use for the index terms can be +selected in the +\enablehyperlinks command. The optional argument it accepts is +a comma-separated list of options. The +idxexact option selects the first approach, +idxpage the second, and +idxnone disables hyperlink support for the index terms +altogether, in case you want to stop Eplain from writing its link +wrappers into the .idx file. The default is idxpage. + +

For example: + +

     \enablehyperlinks[idxexact]
+
+

selects the first approach (“exact index links”). + +

+

+ +Next: , +Previous: Choosing destination placement, +Up: Index hyperlinks + +
+ +
5.3.7.4 Index page list and page range parsers
+ +

The macros that Eplain uses to parse page lists and page ranges, +\idxparselist and \idxparserange, can sometimes be useful +when defining page number encapsulators. See Page list and page range parsers, for the description of these commands and an example of their +usage. + +

+

+ +Previous: Index page list and page range parsers, +Up: Index hyperlinks + +
+ +
5.3.7.5 Hyperlinks in see and see also entries
+ +

There is no automatic support for hyperlinks with “see” and “see +also” index entries, as there is not enough information to trace the +parameters of +\indexsee and +\indexseealso to corresponding index entries. But if desired, +this can be implemented with \hldest and \hlstart +(see Explicit hyperlinks); for example: + +

     \sidx{semantic theory of truth@%
+           \leavevmode\hldest{}{}{idx:theo truth}semantic theory of truth}
+     ...
+     \sidx[seealso]{truth}[definition of]%
+           {\hlstart{}{}{idx:theo truth}semantic theory of truth\hlend}
+
+
+

+ +Next: , +Previous: Index hyperlinks, +Up: Implicit hyperlinks + +
+ +

5.3.8 Footnote hyperlinks: foot, footback

+ +

The `foot' link and destination groups include the +\numberedfootnote and +\footnote macros (see Footnotes). The `footback' groups +include the same macros, but control parameters for links and +destinations created inside the footnote to point back to the footnote +mark within the text body. + +

The macros use hyperlink labels generated by +\hlfootlabel and +\hlfootbacklabel. The default formats for the labels are +`FOOTnumber' and `FOOTBnumber', respectively, +where number is the value of the count register +\hlfootlabelnumber. This register is incremented at every +footnote. + +

+

+ +Previous: Footnote hyperlinks, +Up: Implicit hyperlinks + +
+ +

5.3.9 Contents hyperlinks

+ +

There is currently no special support for hyperlinks in the table of +contents (see Contents), but implementing them with the +\hldest and \hlstart ... \hlend commands +(see Explicit hyperlinks) should be possible. + +

+

+ +Next: , +Previous: Implicit hyperlinks, +Up: Hyperlinks + +
+ +

5.4 Hyperlink drivers

+ +

This section describes the hyperlink drivers: the types of hyperlinks +they support, and the options they accept. During the first reading, +you may only want to skim through this section. + +

Some of the descriptions below come from Portable Document Format +Reference Manual Version 1.3, March 11, 1999. + +

+ +
+

+ +Next: , +Up: Hyperlink drivers + +
+ +

5.4.1 Options supported by all drivers

+ +

This subsection describes the destination and link options which are +supported by all hyperlink drivers. + +

Destination options supported by all drivers
+ +

+

+
raise
Specifies how much to raise destinations above the baseline. When set +to zero or empty, destinations are placed at the baseline. + +

It is usually convenient to set this option to some variable parameter, +so that the height to which destinations are raised is automatically +adjusted according to the current context. For example, setting it to +\normalbaselineskip (or some fraction of it, like +1.7\normalbaselineskip) makes the setting appropriate for +different point sizes, in case your document uses more than one. + +

The default setting is \normalbaselineskip. Initially, the +destgroups do not define this option, so they fall back on the default, +except for the `eq' destgroup, for which this option is set to +1.7\normalbaselineskip, +to accommodate the usual cases of large operators in displayed math. + +

Example: \hldestopts[eq]{raise=2.5\normalbaselineskip} +

+ +
Link options supported by all drivers
+ +

+

+
colormodel
color
These two options define the color to be used for rendering the link +text. The colors are used only when a \color command is defined, +e.g., by loading the LaTeX `color' package (see Packages known to work). The \color command is called as +\color[colormodel]{color}, where colormodel +and color are the definitions of the colormodel and +color options, respectively. However, if colormodel is +empty, the optional argument to \color is omitted; and if +color is empty, the \color command is omitted altogether. +The default setting is colormodel=cmyk and +color=0.28,1,1,0.35. + +

When specifying colors with several components delimited by commas +(e.g., RGB and CMYK colors in the LaTeX `color' package), it is not +possible to specify the components directly in the option list of +\hlopts, because comma is the option list delimiter. With the +`color' package, it is possible to specify such colors by defining a +custom color with \definecolor and using the new color name with +an empty colormodel (see examples below). + +

Examples: + 

          \hlopts{colormodel=,color=blue}% predefined color
+          \definecolor{mycolor}{rgb}{.3,.8,.95}
+          \hlopts{colormodel=,color=mycolor}% custom color
+          \hlopts{colormodel=gray,color=.4}
+
+
+ +
+

+ +Next: , +Previous: Options supported by all drivers, +Up: Hyperlink drivers + +
+ +

5.4.2 Hyperlink drivers pdftex and dvipdfm

+ +

This subsection describes link and destination types and options +supported by the pdftex and dvipdfm drivers. Many of the +hyperlink types and options are common to both drivers, so we describe +them together. + +

+ +
+

+ +Next: , +Up: Hyperlink drivers pdftex and dvipdfm + +
+ +
5.4.2.1 Destination types for pdftex and dvipdfm
+ +

+

+
xyz
“Current position”. The option +zoom specifies magnification to use (zero or empty means leave +magnification unchanged, which is the default). This is the default +type. + +

For dvipdfm: the options +left and +top specify position coordinates to use (empty options mean +current position coordinate, which is the default). + +

Example: \hldest{xyz}{zoom=2000}{dest123} + +

fit
Fit the page to the window. + +

Example: \hldest{fit}{}{dest123} + +

fith
Fit the width of the page to the window. + +

For dvipdfm: the +top option specifies vertical position (default is empty, meaning +current position). + +

Example: \hldest{fith}{}{dest123} + +

fitv
Fit the height of the page to the window. + +

For dvipdfm: The option +left specifies horizontal position (default is empty, meaning +current position). + +

Example: \hldest{fitv}{}{dest123} + +

fitb
Fit the page's bounding box to the window. + +

Example: \hldest{fitb}{}{dest123} + +

fitbh
Fit the width of the page's bounding box to the window. + +

For dvipdfm: the option +top specifies vertical position (default is empty, meaning +current position). + +

Example: \hldest{fitbh}{}{dest123} + +

fitbv
Fit the height of the page's bounding box to the window. + +

For dvipdfm: the option +left specifies horizontal position (default is empty, meaning +current position). + +

Example: \hldest{fitbv}{}{dest123} + +

fitr
For pdftex: fit the rectangle specified by the options +width, +height and +depth (as a TeX rule specification) in the window. For +dimensions set to empty, the corresponding value of the parent box is +used (these are the defaults). + +

For dvipdfm: fit the rectangle specified by the options +left, +bottom, +right and +top (in +PostScript points, 72 points per inch) in the window. For +dimensions set to empty, current position coordinate is substituted +(these are the defaults). + +

Example for pdftex: + + 

          \hldest{fitr}{width=\hsize,height=.5\vsize,depth=0pt}{dest123}
+
+

Example for dvipdfm: + + 

          \hldest{fitr}{left=72,bottom=72,right=720,top=360}{dest123}
+
+
raw
The destination specification (in the form of a pdfTeX command or a +dvipdfm \special) is taken from the command sequence +\cs, where cs is the value of the +cmd option. In the definition of \cs, use +\@hllabel to refer to the hyperlink label. This option is +intended to be used with destgroups (see Setting hyperlink types and options), as it does not make sense to use it in a direct call to +\hldest—you can just call the raw command. + +

Example for pdftex: + + 

          \makeatletter
+          \def\mydest{\pdfdest name{\@hllabel} xyz}
+          \hldesttype{raw}
+          \hldestopts{cmd=mydest}
+          \resetatcatcode
+
+

Example for dvipdfm: + + 

          \makeatletter
+          \def\mydest{\special{pdf: dest (\@hllabel)
+                                    [@thispage /XYZ @xpos @ypos 0]}}
+          \hldesttype{raw}
+          \hldestopts{cmd=mydest}
+          \resetatcatcode
+
+
+ +
+

+ +Next: , +Previous: Destination types for pdftex and dvipdfm, +Up: Hyperlink drivers pdftex and dvipdfm + +
+ +
5.4.2.2 Destination options for pdftex and dvipdfm
+ +

With respect to the destination options, the pdftex and +dvipdfm differ in the way the fit rectangle is specified +(relative coordinates for pdftex, absolute coordinates for +dvipdfm). + +

Common destination options
+ +
+
cmd
Name of the macro (without the leading `\') containing a +pdfTeX command or a dvipdfm \special for the raw +destination. + +

For an example of usage, see Destination types for pdftex and dvipdfm, description of the raw destination. + +

zoom
Magnification ratio times 1000 (like TeX's scale factor). +Zero or empty means leave magnification unchanged, which is the +default. + +

Example: \hldest{xyz}{zoom=2000}{dest123} +

+ +
pdftex-specific destination options
+ +

The dimension options below must be specified as a TeX rule +specification. When set to empty, the corresponding value +of the parent box is used (this is the default for all dimension +options). + +

+
depth
Depth of the fit rectangle for the fitr destination. + +
height
Height of the fit rectangle for the fitr destination. + +
width
Width of the fit rectangle for the fitr destination. + +

Example: + + 

          \hldest{fitr}{width=\hsize,height=.5\vsize,depth=0pt}{dest123}
+
+
+ +
dvipdfm-specific destination options
+ +

The dimension options below must be specified in +PostScript points (72 points per inch), as a number without the +`bp' unit name. When set to empty, the current position +coordinate is used (this is the default for all dimension options). + +

+
bottom
Bottom position coordinate of a box specification for the various +destination types. + +
left
Left position coordinate of a box specification for the various +destination types. + +
right
Right position coordinate of a box specification for the various +destination types. + +
top
Top position coordinate of a box specification for the various +destination types. + +

Example: + + 

          \hldest{fitr}{left=72,bottom=72,right=720,top=360}{dest123}
+
+
+ +
+

+ +Next: , +Previous: Destination options for pdftex and dvipdfm, +Up: Hyperlink drivers pdftex and dvipdfm + +
+ +
5.4.2.3 Link types for pdftex and dvipdfm
+ +

Link types are the same for the pdftex and dvipdfm +drivers, except that the pdftex driver provides one additional +link type num (link to a numbered destination). dvipdfm does not +support numbered destinations, therefore it does not have this link +type. Note that all destinations created by Eplain hyperlink macros are +named destinations; to define a numbered destination, you have to use +low-level pdfTeX commands. + +

Common link types
+ +
+
name
Go to a “named destination”. The label is the destination name. +All destinations created with \hldest are named destinations. +This is the default type. + +

Example: \hlstart{name}{}{dest123}Link to dest123\hlend + +

page
Go to a page. The label is the page number (counting from 1). +Page fitting is specified by the +pagefit option. + +

Example: + + 

          \hlstart{page}{pagefit=/FitH 600}{123}Link to page~123\hlend
+
+
filename
Go to a named destination in another file. The label is the +destination name. The file name is specified by the +file option. Page fitting is specified by the +pagefit option. The +newwin option specifies whether the destination document is +opened in the same window or in a new window. + +

Example: + 

          \hlstart{filename}{file=book.pdf,newwin=1}{dest123}
+            Link to dest123 in file `book.pdf'\hlend
+
+
filepage
Go to a page in another file. The label is the page number (counting +from 1). The file name is specified by the +file option. Page fitting is specified by the +pagefit option. The +newwin option specifies whether the destination document is +opened in the same window or in a new window. + +

Example: + 

          \hlstart{filepage}{file=book.pdf,newwin=,%
+                             pagefit=/FitR 50 100 300 500}{1}
+            Link to page~1 in file `book.pdf'\hlend
+
+
url
Go to a URL. The label is the URL. + +

Example: \hlstart{url}{}{http://tug.org/eplain/}Eplain home\hlend + +

raw
The link specification (in the form of a pdfTeX command or a dvipdfm +\special primitive) is taken from the command sequence +\cs, where cs is the value of the +cmd option. This option is intended to be used with linkgroups +(see Setting hyperlink types and options), as it does not make sense +to use it in a direct call to +\hlstart—you can just call the raw command. + +

Example for pdftex: + + 

          % Redirect all \url links to the first page
+          \def\mycmd{\pdfstartlink goto page 1 {/Fit}}
+          \hltype[url]{raw}
+          \hlopts[url]{cmd=mycmd}
+
+

Example for dvipdfm: + + 

          % Redirect all \url links to the first page
+          \def\mycmd{\special{pdf: beginann <</Type/Annot /Subtype/Link
+                                              /Dest[0 /Fit]>>}}
+          \hltype[url]{raw}
+          \hlopts[url]{cmd=mycmd}
+
+
+ +
pdftex-specific link types
+ +
+
num
Go to a “numbered destination”. The label is the destination +number. + +

Example: \hlstart{num}{}{123}Link to 123\hlend +

+ +
+

+ +Previous: Link types for pdftex and dvipdfm, +Up: Hyperlink drivers pdftex and dvipdfm + +
+ +
5.4.2.4 Link options for pdftex and dvipdfm
+ +

Link options are mostly the same for the pdftex and +dvipdfm drivers. The pdftex driver has additional +options to specify link dimensions. + +

Common link options
+ +
+
bcolor
Border color. An array of three numbers in the range 0 to 1, +representing a color in DeviceRGB. + +

Example: \hlstart{name}{bcolor=.1 .5 1}{dest123}Link\hlend + +

bdash
Array of numbers representing on and off stroke lengths for drawing +dashes. + +

Example: \hlstart{name}{bstyle=D,bdash=2 4}{dest123}Link\hlend + +

bstyle
Link border style: + +
+
S
The border is drawn as a solid line. + +
D
The border is drawn with a dashed line (the dash pattern is specified +by the +bdash option). + +
B
The border is drawn in a beveled style. + +
I
The border is drawn in an inset style. + +
U
The border is drawn as a line on the bottom of the link rectangle. +
+ +

The default is `S'. + +

Example: \hlstart{name}{bstyle=D,bdash=2 4}{dest123}Link\hlend + +

bwidth
Border width in +PostScript points (72 points per inch). The default is 1. + +

Example: \hlstart{name}{bwidth=2}{dest123}Link\hlend + +

cmd
Name of the macro (without the leading `\') containing a +pdfTeX command or a dvipdfm \special for the raw link. + +

For an example of usage, see Link types for pdftex and dvipdfm, +description of the raw link. + +

file
File name for the filename and filepage link types. + +

For an example of usage, see Link types for pdftex and dvipdfm, +description of the filename and filepage links. + +

hlight
Link border highlight modes: + +
+
I
The rectangle specified by the bounding box of the link is inverted. + +
N
No highlighting is done. + +
O
The border of the link is inverted. + +
P
The region underneath the bounding box of the link is drawn inset into +the page. +
+ +

The default is `I'. + +

Example: \hlstart{name}{bstyle=S,hlight=O}{dest123}Link\hlend + +

newwin
For the filename and filepage links, specifies whether the destination document is +opened in the same window or in a new window. The settings are: + +
+
0
Open in the same window. +
non-0
Open in a new window. +
empty
Behavior according to the viewer settings. +
+ +

The default is empty. + +

For an example of usage, see Link types for pdftex and dvipdfm, +description of the filename and filepage links. + +

pagefit
For the page and filepage links, specifies how the page +must be fitted to the window. pagefit specification is written +to the PDF file as is, so it must conform to the PDF standard. + +

For an example of usage, see Link types for pdftex and dvipdfm, +description of the page and filepage links. +

+ +
pdftex-specific link options
+ +

The dimension options below must be specified as a TeX rule +specification. When set to empty, the corresponding value +of the parent box is used (this is the default for all dimension +options). + +

+
depth
Depth of the link. + +
height
Height of the link. + +
width
Width of the link. + +

Example: + + 

          \hlstart{name}{width=5in,height=20pc,depth=0pt}{dest123}
+            Link\hlend
+
+
+ +
+

+ +Previous: Hyperlink drivers pdftex and dvipdfm, +Up: Hyperlink drivers + +
+ +

5.4.3 Hyperlink driver nolinks

+ +

Select this driver to suppress all hyperlinks in your document. + +

Selecting this driver is quite different from not selecting any driver +at all, or from selecting some driver and then turning hyperlinks off +for the entire document with +\hloff and +\hldestoff (see Turning hyperlinks on/off). + +

The purpose of \hldestoff and \hloff is to mark (parts) of +your document where hyperlinks should never appear. (Imagine you want +to prevent a cross-referencing macro from generating a link at a certain +spot in your document.) + +

If instead you have prepared a document with hyperlinks and just want to +compile a version without them, it is better to select the driver +nolinks. This ensures that spacing and page-breaking are the +same as what you were getting with hyperlinks enabled. + +

The reason for this is that hyperlinks are produced by the +\special primitives or low-level hyperlink commands. Each such +command is placed inside a +whatsit (an internal TeX object), which may introduce +legitimate breakpoints at places where none would exist without the +whatsits. The macros \hldestoff and \hloff disable the +hyperlink macros completely, so that no whatsits are produced. + +

In contrast, the nolinks driver does not completely disable +hyperlink macros. Instead, it defines them to merely write to the log +file (what gets written is unimportant). This also produces +whatsits, thus imitating the whatsits from the hyperlink commands. +(This trick was borrowed from the +LaTeX `color' package.) + +

Another reason for using nolinks is that in horizontal mode +\hldest places destinations inside boxes of zero width, height, +and depth. When you say \hldestoff, \hldest will omit +both destination definitions and these boxes. The missing boxes can +again cause the typesetting to be inconsistent with that with +destinations enabled. Here again, the nolinks driver helps by +defining \hldest to produce the empty boxes. + +

+

+ +Next: , +Previous: Hyperlink drivers, +Up: Hyperlinks + +
+ +

5.5 Setting hyperlink types and options

+ +

You can define default types for links and destinations, which will be +used when you do not specify a type in +\hlstart or +\hldest. Similarly, you can define default values for the +options; the default value for an option is used when you do not set the +option in the argument to \hlstart or \hldest. + +

The parameters for implicit links and destinations can be customized by +setting the “group” types and options. When not set, the defaults are +used. + +

All these settings are local to the current (TeX) group, so if +you want to set an option temporarily, you can do so inside a +\begingroup...\endgroup block; when the group ends, the +previous settings are restored. + +

+ +
+

+ +Next: , +Up: Setting hyperlink types and options + +
+ +

5.5.1 Setting default types and options

+ +

The default types for links and destinations can be set with the +following commands: + +

     \hltype{type}
+     \hldesttype{type}
+
+

where type is one of the +link/destination types supported by the selected hyperlink driver +(see Hyperlink drivers). + +

Default values for the options can be set with the following commands: + +

     \hlopts{options}
+     \hldestopts{options}
+
+

where options is a comma-separated list of option +assignments in the format `option=value'. Again, what options +are allowed depends on the selected hyperlink driver. + +

+

+ +Next: , +Previous: Setting default types and options, +Up: Setting hyperlink types and options + +
+ +

5.5.2 Setting group types

+ +

When called with an optional argument, as in + +

     \hltype[groups]{type}
+     \hldesttype[groups]{type}
+
+

where groups is a comma-separated list of groups, +\hltype and \hldesttype set the type for each group from +groups to type. The default type is used for all groups +with an empty type (this is the initial setting for all groups, except +that the type for the `url' linkgroup is set to `url' by the +drivers which support this link type). + +

There are two special “groups” which can be used inside the +groups list. An empty group sets the default type. This allows +to set the default type and group types in one command, for example: + +

     \hltype[eq,]{type}
+
+

sets the link type for the `eq' linkgroup and the +default link type to type. + +

Another special group is a star (`*') group, which signifies all +defined groups. For example, the command + +

     \hldesttype[*,]{type}
+
+

sets the destination type to type for each group, +as well as the default destination type. + +

+

+ +Previous: Setting group types, +Up: Setting hyperlink types and options + +
+ +

5.5.3 Setting group options

+ +

Option values for each group are stored as a list of option +assignments. This list does not have to contain every supported +option. Values for options missing from this list are taken from the +default option values. + +

To manipulate the list of option values for the groups, you use the +\hlopts and \hldestopts commands with an optional +argument: + +

     \hlopts[groups]{options}
+     \hldestopts[groups]{options}
+     \hlopts![groups]{options}
+     \hldestopts![groups]{options}
+
+

where groups is a comma-separated list of groups and +options is a comma-separated list of option assignments. The +two special “groups”, the empty group and the star (`*') +group, have the same meaning as for \hltype and +\hldesttype. +When used without the exclamation mark, \hlopts and +\hldestopts preserve the current list of options for the groups, +and only update the options listed in options. If you add the +exclamation mark, the current list of options for each group in +groups is discarded and the new list is set to options. + +

The “overriding” nature of the `!' is appropriate when you give +a complete specification of the options for a group, e.g., at the +beginning of your document. On the other hand, when you want to +adjust some option(s) and leave others intact, you should use the +macros without the `!'. + +

For example, with displayed mathematical formulas, you often need to +adjust the `raise' option for the +`eq' destgroup, because the formulas often contain large parentheses and +brackets. But when doing so, you want to leave the other settings +unchanged. To achieve this, call \hldestopts without the +`!', for example: + +

     $$\hldestopts[eq]{raise=2.5\normalbaselineskip}
+     ...
+     $$
+
+

The display commands (`$$') implicitly put the entire +formula inside a (TeX) group (\begingroup...\endgroup), so +you do not need to isolate the setting of the `raise' option—it +will be restored after the closing `$$'. + +

Initially, Eplain sets the option lists for almost all groups to empty, +so that the groups fall back on the default values for all options. The +one exception to this rule is the `eq' destgroup, whose initial option +list contains one setting: + +

     raise=1.7\normalbaselineskip
+
+

This setting usually accommodates the large operators, which often +appear in displayed math. + +

+

+ + +Previous: Setting hyperlink types and options, +Up: Hyperlinks + +
+ +

5.6 Turning hyperlinks on/off

+ +

Links and/or destinations can be turned on or off globally by disabling +the low-level commands, or for each group individually. + +

All these settings are local to the current (TeX) group, so if you +want to enable or disable links/destinations temporarily, you can do so +inside a \begingroup...\endgroup block; when the group ends, the +previous settings are restored. + +

+ +
+

+ + +Next: , +Up: Turning hyperlinks on/off + +
+ +

5.6.1 Turning low-level commands on/off

+ +

The low-level commands \hlstart, \hlend and +\hldest can be turned on/off with the following commands: + +

     \hldeston
+     \hldestoff
+     \hlon
+     \hloff
+
+

See Hyperlink driver nolinks, for the implications of using +these commands to disable hyperlinks for the entire document. + +

+

+ + +Previous: Turning low-level commands on/off, +Up: Turning hyperlinks on/off + +
+ +

5.6.2 Turning hyperlinks on/off for a group

+ +

If you want to disable links/destinations produced by certain groups, +you can give a list of the groups as an optional argument to these +commands: + +

     \hldeston[groups]
+     \hldestoff[groups]
+     \hlon[groups]
+     \hloff[groups]
+
+

where groups is the list of linkgroups/destgroups. This +list can contain two special groups. The empty group switches the +low-level commands (see Turning low-level commands on/off), and the +star (`*') group operates on all defined groups. + +

Note that turning off the low-level commands disables all hyperlinks +globally, including groups which have them enabled. Turning off certain +linkgroups/destgroups records the fact that the macros in the group +should not produce links/destinations. To illustrate the distinction, +assume that all links are on; after the following sequence of commands: + +

     \hloff
+     \hloff[eq]
+     \hlon
+
+

all links are on except for the `eq' linkgroup. + + + + + + + + + + + + + + + + + + + + + +

+

+ +Next: , +Previous: Hyperlinks, +Up: Top + +
+ +

6 Arrow theoretic diagrams

+ +

This chapter describes definitions for producing commutative diagrams. + +

Steven Smith wrote this documentation (and the macros). + +

+ +
+

+ +Next: , +Up: Arrow theoretic diagrams + +
+ +

6.1 Slanted lines and vectors

+ +

The macros \drawline +and \drawvector +provide the capability found in LaTeX's +picture mode to draw slanted lines and vectors of certain directions. +Both of these macros take three arguments: two integer arguments to +specify the direction of the line or vector, and one argument to specify +its length. For example, `\drawvector(-4,1){60pt}' produces the +vector +which lies in the 2d quadrant, has a slope of minus 1/4, and a width of +60 pt. + +

Note that if an \hbox is placed around \drawline or +\drawvector, then the width of the \hbox will be the +positive dimension specified in the third argument, except when a +vertical line or vector is specified, e.g., +\drawline(0,1){1in}, which has zero width. If the specified +direction lies in the 1st or 2d quadrant (e.g., (1,1) or +(-2,3)), then the \hbox will have positive height and zero +depth. Conversely, if the specified direction lies in the 3d or 4th +quadrant (e.g., (-1,-1) or (2,-3)), then the \hbox +will have positive depth and zero height. + +

There are a finite number of directions that can be specified. For +\drawline, the absolute value of each integer defining the +direction must be less than or equal to six, i.e., (7,-1) is +incorrect, but (6,-1) is acceptable. For \drawvector, the +absolute value of each integer must be less than or equal to four. +Furthermore, the two integers cannot have common divisors; therefore, if +a line with slope 2 is desired, say (2,1) instead of +(4,2). Also, specify (1,0) instead of, say, (3,0) +for horizontal lines and likewise for vertical lines. + +

Finally, these macros depend upon the LaTeX font line10. If +your site doesn't have this font, ask your system administrator to get +it. Future enhancements will include macros to draw dotted lines and +dotted vectors of various directions. + +

+

+ +Previous: Slanted lines and vectors, +Up: Arrow theoretic diagrams + +
+ +

6.2 Commutative diagrams

+ +

+The primitive commands \drawline and \drawvector can be +used to typeset arrow theoretic diagrams. This section describes (1) +macros to facilitate typesetting arrows and morphisms, and (2) macros to +facilitate the construction of commutative diagrams. All macros +described in this section must be used in math mode. + +

+ +
+

+ +Next: , +Up: Commutative diagrams + +
+ +

6.2.1 Arrows and morphisms

+ +

+The macros \mapright and \mapleft produce right and left +pointing arrows, respectively. Use superscript (^) to place a +morphism above the arrow, e.g., `\mapright^\alpha'; use subscript +(_) to place a morphism below the arrow, e.g., +`\mapright_{\tilde l}'. Superscripts and subscripts may be used +simulataneously, e.g., `\mapright^\pi_{\rm epimor.}'. + +

Similarly, the macros \mapup and \mapdown produce up and +down pointing arrows, respectively. Use \rt +to place a morphism to the right of the arrow, e.g., `\mapup\rt{\rm +id}'; use \lft +to place a morphism to the left of the arrow, e.g., `\mapup\lft\omega'. +\lft and \rt may be used simultaneously, e.g., +`\mapdown\lft\pi\rt{\rm monomor.}'. + +

Slanted arrows are produced by the macro \arrow, which takes +a direction argument (e.g., `\arrow(3,-4)'). Use \rt and +\lft to place morphisms to the right and left, respectively, of +the arrow. A slanted line (no arrowhead) is produced with the macro +\sline, +whose syntax is identical to that of \arrow. + +

The length of these macros is predefined by the default TeX +dimensions \harrowlength, +for horizontal arrows (or lines), +\varrowlength, +for vertical arrows (or lines), and +\sarrowlength, +for slanted arrows (or lines). To change any of these dimensions, say, +e.g., `\harrowlength=40pt'. As with all other TeX dimensions, +the change may be as global or as local as you like. Furthermore, the +placement of morphisms on the arrows is controlled by the dimensions +\hmorphposn, +\vmorphposn, +and \morphdist. +The first two dimensions control the horizontal and vertical position of +the morphism from its default position; the latter dimension controls +the distance of the morphism from the arrow. If you have more than one +morphism per arrow (i.e., a ^/_ or \lft/\rt +construction), use the parameters +\hmorphposnup, +\hmorphposndn, +\vmorphposnup, +\vmorphposndn, +\hmorphposnrt, +\hmorphposnlft, +\vmorphposnrt, +and \vmorphposnlft. +The default values of all these dimensions are provided in the section +on parameters that follows below. + +

There is a family of macros to produce horizontal lines, arrows, and +adjoint arrows. The following macros produce horizontal maps and have +the same syntax as \mapright: + +

+
\mapright
$X\mapright Y$ + +
\mapleft
$X\mapleft Y$ + +
\hline
$X\hline Y$ + +
\bimapright
$X\bimapright Y$ + +
\bimapleft
$X\bimapleft Y$ + +
\adjmapright
$X\adjmapright Y$ + +
\adjmapleft
$X\adjmapleft Y$ + +
\bihline
$X\bihline Y$ +
+ +

There is also a family of macros to produce vertical lines, arrows, and +adjoint arrows. The following macros produce vertical maps and have +the same syntax as \mapdown: + +

+
\mapdown
(a down arrow) + +
\mapup
(an up arrow) + +
\vline
(vertical line) + +
\bimapdown
(two down arrows) + +
\bimapup
(two up arrows) + +
\adjmapdown
(two adjoint arrows; down then up) + +
\adjmapup
(two adjoint arrows; up then down) + +
\bivline
(two vertical lines) +
+ +

Finally, there is a family of macros to produce slanted lines, arrows, +and adjoint arrows. The following macros produce slanted maps and have +the same syntax as \arrow: + +

+
\arrow
(a slanted arrow) + +
\sline
(a slanted line) + +
\biarrow
(two straight arrows) + +
\adjarrow
(two adjoint arrows) + +
\bisline
(two straight lines) + +
+ +

The width between double arrows is controlled by the parameter +\channelwidth. +The parameters \hchannel and \vchannel, if nonzero, +override \channelwidth by controlling the horizontal and vertical +shifting from the first arrow to the second. + +

There are no adornments on these arrows to distinguish inclusions from +epimorphisms from monomorphisms. Many texts, such as Lang's book +Algebra, use as a tasteful alternative the symbol `inc' (in roman) next +to an arrow to denote inclusion. + +Future enhancements will include a mechanism to draw curved arrows +found in, e.g., the Snake Lemma, by employing a version of the +\path macros of Appendix D of The TeXbook. + + +

+

+ +Next: , +Previous: Arrows and morphisms, +Up: Commutative diagrams + +
+ +

6.2.2 Construction of commutative diagrams

+ +

There are two approaches to the construction of commutative diagrams +described here. The first approach, and the simplest, treats +commutative diagrams like fancy matrices, as Knuth does in Exercise +18.46 of The TeXbook. This case is covered by the macro +\commdiag, +which is an altered version of the Plain TeX macro \matrix. +An example suffices to demonstrate this macro. The following +commutative diagram (illustrating the covering homotopy property; Bott +and Tu, Differential Forms in Algebraic Topology) +is produced with the code + +

     $$\commdiag{Y&\mapright^f&E\cr \mapdown&\arrow(3,2)\lft{f_t}&\mapdown\cr
+     Y\times I&\mapright^{\bar f_t}&X}$$
+
+

Of course, the parameters may be changed to produce a different effect. +The following commutative diagram (illustrating the universal mapping +property; Warner, Foundations of Differentiable Manifolds and Lie +Groups) +is produced with the code + +

     $$\varrowlength=20pt
+     \commdiag{V\otimes W\cr \mapup\lft\phi&\arrow(3,-1)\rt{\tilde l}\cr
+     V\times W&\mapright^l&U\cr}$$
+
+

A diagram containing isosceles triangles is achieved by placing the apex +of the triangle in the center column, as shown in the example +(illustrating all constant minimal realizations of a linear system; +Brockett, Finite Dimensional Linear Systems) +which is produced with the code + +

     $$\sarrowlength=.42\harrowlength
+     \commdiag{&R^m\cr &\arrow(-1,-1)\lft{\bf B}\quad \arrow(1,-1)\rt{\bf G}\cr
+     R^n&\mapright^{\bf P}&R^n\cr
+     \mapdown\lft{e^{{\bf A}t}}&&\mapdown\rt{e^{{\bf F}t}}\cr
+     R^n&\mapright^{\bf P}&R^n\cr
+     &\arrow(1,-1)\lft{\bf C}\quad \arrow(-1,-1)\rt{\bf H}\cr
+     &R^q\cr}$$
+
+

Other commutative diagram examples appear in the file +commdiags.tex, which is distributed with this package. + +

In these examples the arrow lengths and line slopes were carefully +chosen to blend with each other. In the first example, the default +settings for the arrow lengths are used, but a direction for the arrow +must be chosen. The ratio of the default horizontal and vertical arrow +lengths is approximately the golden mean +the arrow direction closest to this mean is (3,2). In the second +example, a slope of +is desired and the default horizontal arrow length is 60 pt; therefore, +choose a vertical arrow length of 20 pt. You may affect the interline +glue settings of \commdiag by redefining the macro +\commdiagbaselines. +(cf. Exercise 18.46 of The TeXbook and the section on +parameters below.) + +

The width, height, and depth of all morphisms are hidden so that the +morphisms' size do not affect arrow positions. This can cause a large +morphism at the top or bottom of a diagram to impinge upon the text +surrounding the diagram. To overcome this problem, use TeX's +\noalign primitive to insert a \vskip immediately above or +below the offending line, e.g., +`$$\commdiag{\noalign{\vskip6pt}X&\mapright^\int&Y\cr ...}'. + +

The macro \commdiag is too simple to be used for more complicated +diagrams, which may have intersecting or overlapping arrows. A second +approach, borrowed from Francis Borceux's Diagram macros for +LaTeX, treats the commutative diagram like a grid of identically +shaped boxes. To compose the commutative diagram, first draw an equally +spaced grid, e.g., +on a piece of scratch paper. Then draw each element (vertices and +arrows) of the commutative diagram on this grid, centered at each +grid point. Finally, use the macro \gridcommdiag +to implement your design as a TeX alignment. For example, the cubic +diagram +that appears in Francis Borceux's documentation can be implemented on +a 7 by 7 grid, and is achieved with the code + +

     $$\harrowlength=48pt \varrowlength=48pt \sarrowlength=20pt
+     \def\cross#1#2{\setbox0=\hbox{$#1$}%
+       \hbox to\wd0{\hss\hbox{$#2$}\hss}\llap{\unhbox0}}
+     \gridcommdiag{&&B&&\mapright^b&&D\cr
+     &\arrow(1,1)\lft a&&&&\arrow(1,1)\lft d\cr
+     A&&\cross{\hmorphposn=12pt\mapright^c}{\vmorphposn=-12pt\mapdown\lft f}
+     &&C&&\mapdown\rt h\cr\cr
+     \mapdown\lft e&&F&&\cross{\hmorphposn=-12pt\mapright_j}
+     {\vmorphposn=12pt\mapdown\rt g}&&H\cr
+     &\arrow(1,1)\lft i&&&&\arrow(1,1)\rt l\cr
+     E&&\mapright_k&&G\cr}$$
+
+

The dimensions \hgrid and \vgrid +control the horizontal and vertical spacing of the grid used by +\gridcommdiag. The default setting for both of these dimensions +is 15 pt. Note that in the example of the cube the arrow lengths must +be adjusted so that the arrows overlap into neighboring boxes by the +desired amount. Hence, the \gridcommdiag method, albeit more +powerful, is less automatic than the simpler \commdiag method. +Furthermore, the ad hoc macro \cross is introduced to allow the +effect of overlapping arrows. Finally, note that the positions of four +of the morphisms are adjusted by setting \hmorphposn and +\vmorphposn. + +

One is not restricted to a square grid. For example, the proof of +Zassenhaus's Butterfly Lemma can be illustrated by the diagram (appearing +in Lang's book Algebra) +This diagram may be implemented on a 9 by 12 grid with an aspect ratio +of 1/2, and is set with the code + +

     $$\hgrid=16pt \vgrid=8pt \sarrowlength=32pt
+     \def\cross#1#2{\setbox0=\hbox{$#1$}%
+       \hbox to\wd0{\hss\hbox{$#2$}\hss}\llap{\unhbox0}}
+     \def\l#1{\llap{$#1$\hskip.5em}}
+     \def\r#1{\rlap{\hskip.5em$#1$}}
+     \gridcommdiag{&&U&&&&V\cr &&\bullet&&&&\bullet\cr
+     &&\sarrowlength=16pt\sline(0,1)&&&&\sarrowlength=16pt\sline(0,1)\cr
+     &&\l{u(U\cap V)}\bullet&&&&\bullet\r{(U\cap V)v}\cr
+     &&&\sline(2,-1)&&\sline(2,1)\cr
+     &&\cross{=}{\sline(0,1)}&&\bullet&&\cross{=}{\sline(0,1)}\cr\cr
+     &&\l{^{\textstyle u(U\cap v)}}\bullet&&\cross{=}{\sline(0,1)}&&
+      \bullet\r{^{\textstyle(u\cap V)v}}\cr
+     &\sline(2,1)&&\sline(2,-1)&&\sline(2,1)&&\sline(2,-1)\cr
+     \l{u}\bullet&&&&\bullet&&&&\bullet\r{v}\cr
+     &\sline(2,-1)&&\sline(2,1)&&\sline(2,-1)&&\sline(2,1)\cr
+     &&\bullet&&&&\bullet\cr &&u\cap V&&&&U\cap v\cr}$$
+
+

Again, the construction of this diagram requires careful choices for the +arrow lengths and is facilitated by the introduction of the ad hoc +macros \cross, \r, and \l. Note also that +superscripts were used to adjust the position of the vertices +Many diagrams may be typeset with the predefined macros that appear +here; however, ingenuity is often required to handle special cases. + +

+

+ +Previous: Construction of commutative diagrams, +Up: Commutative diagrams + +
+ +

6.2.3 Commutative diagram parameters

+ +

The following is a list describing the parameters used in the +commutative diagram macros. These dimensions may be changed globally or +locally. + +

+
\harrowlength
(Default: 60 pt) The length of right or left arrows. + +
\varrowlength
(Default: 0.618\harrowlength) The length of up or down +arrows. + +
\sarrowlength
(Default: 60 pt) The horizontal length of slanted arrows. + +
\hmorphposn
(Default: 0 pt) The horizontal position of the morphism with +respect to its default position. There are also the dimensions +\hmorphposnup, +\hmorphposndn, +\hmorphposnrt, +and \hmorphposnlft +for ^/_ or \lft/\rt constructions. + +
\vmorphposn
(Default: 0 pt) The vertical position of the morphism with +respect to its default position. There are also the dimensions +\vmorphposnup, +\vmorphposndn, +\vmorphposnrt, +and \vmorphposnlft +for ^/_ or \lft/\rt constructions. + +
\morphdist
(Default: 4 pt) The distance of morphisms from slanted lines +or arrows. + +
\channelwidth
(Default: 3 pt) The distance between double lines or arrows. + +
\hchannel, \vchannel
(Defaults: 0 pt) Overrides \channelwidth. The +horizontal and vertical shifts between double lines or arrows. + +
\commdiagbaselines
(Default: \baselineskip=15pt +\lineskip=3pt +\lineskiplimit=3pt ) +The parameters used by \commdiag for setting interline glue. + +
\hgrid
(Default: 15 pt) The horizontal spacing of the grid used by +\gridcommdiag. + +
\vgrid
(Default: 15 pt) The vertical spacing of the grid used by +\gridcommdiag. + +
+ + + +
+

+ +Next: , +Previous: Arrow theoretic diagrams, +Up: Top + +
+ +

7 Programming definitions

+ +

The definitions in this section are only likely to be useful when you +are writing nontrivial macros, not when writing a document. + +

+ +
+

+ +Next: , +Up: Programming definitions + +
+ +

7.1 Category codes

+ +

+Plain TeX defines \active (as the number 13) for use in +changing category codes. Although the author of The TeXbook +has “intentionally kept the category codes numeric”, two other +categories are commonly used: letters (category code 11) and others +(12). Therefore, Eplain defines \letter and +\other. + +Sometimes it is cleaner to make a character active without actually +writing a \catcode command. The \makeactive command takes +a character as an argument to make active (and ignores following +spaces). For example, here are two commands which both make \ +active: + +

     \makeactive`\\   \makeactive92
+
+

Sometimes you might want to temporarily change the category code of +the `@' character to \letter, so that you can use or define +macros which are normally inaccessible to the user. For such +situations, Eplain provides the \makeatletter +command. It sets the category code of `@' to \letter (11) and +defines +\resetatcatcode +to restore the category code to whatever it was before the call to +\makeatletter. For example: + +

     \makeatletter
+     \def\@hidden@macro{This macro cannot normally be
+                        called / redefined by the user}
+     \resetatcatcode
+
+

There is also \makeatother +which works similarly but sets the category code of `@' to +\other (12). + +

Usually, when you give a definition to an active character, you have +to do so inside a group where you temporarily make the character active, +and then give it a global definition (cf. the definition of +\obeyspaces in The TeXbook). +This is inconvenient if you are writing a long macro, or if the +character already has a global definition you do not wish to transcend. +Eplain provides \letreturn, which defines the usual end-of-line +character to be the argument. For example: + +

     \def\mymacro{... \letreturn\myreturn ... }
+     \mymacro hello
+     there
+
+

The end-of-line between `hello' and `there' causes +\myreturn to be expanded. + +

The TeXbook describes \uncatcodespecials, +which makes all characters which are normally “special” into “other” +characters, but the definition never made it into plain TeX. +Eplain therefore defines it. + +

Finally, \percentchar +expands into a literal `%' character. This is useful when you +\write TeX output to a file, and want to avoid spurious +spaces. For example, Eplain writes a \percentchar after the +definition of cross-references. The macros \lbracechar +and \rbracechar +expand similarly. + +

+

+ +Next: , +Previous: Category codes, +Up: Programming definitions + +
+ +

7.2 Allocation macros

+ +

+Plain TeX provides macros that allocate registers of each primitive +type in TeX, to prevent different sets of macros from using the same +register for two different things. The macros are all named starting +with `new', +e.g., \newcount allocates a new “count” +(integer) register. Such allocations are usually needed only at the top +level of some macro definition file; therefore, plain TeX makes the +allocation registers \outer, +to help find errors. (The error this helps to find is a missing right +brace in some macro definition.) + +

Sometimes, however, it is useful to allocate a register as part of +some macro. An outer control sequence cannot be used as part of a macro +definition (or in a few other contexts: the parameter text of a +definition, an argument to a definition, the preamble of an alignment, +or in conditional text that is being skipped). Therefore, Eplain +defines “inner” versions of all the allocation macros, named with the +prefix `inner': +\innernewbox, +\innernewcount, +\innernewdimen, +\innernewfam, +\innernewhelp, +\innernewif, +\innernewinsert, +\innernewlanguage, +\innernewread,
+\innernewskip, +\innernewtoks, +\innernewwrite. + +You can also define non-outer versions of other macros in the same way +that Eplain defines the above. The basic macro is called +\innerdef: + +

     \innerdef \innername {outername}
+
+

The first argument (\innername) to \innerdef is the +control sequence that you want to define. Any previous definition of +\innername is replaced. The second argument +(outername) is the characters in the name of the outer +control sequence. (You can't use the actual control sequence name, +since it's outer!) + +

If the outer control sequence is named \cs, and you want to +define innercs as the inner one, you can use +\innerinnerdef, +which is just an abbreviation for a call to \innerdef. For +example, these two calls are equivalent: + +

     \innerdef\innerproclaim{proclaim}
+     \innerinnerdef{proclaim}
+
+
+

+ +Next: , +Previous: Allocation macros, +Up: Programming definitions + +
+ +

7.3 Iteration

+ +

+You can iterate through a comma-separated list of items with +\for. +Here is an example: + +

     \for\name:=karl,kathy\do{%
+        \message{\name}%
+     }%
+
+

This writes `karl' and `kathy' to the terminal. Spaces +before or after the commas in the list, or after the :=, are +not ignored. + +

\for expands the iterated values fully (with \edef), so +this is equivalent to the above: + +

     \def\namelist{karl,kathy}%
+     \for\name:=\namelist\do ...
+
+
+

+ +Next: , +Previous: Iteration, +Up: Programming definitions + +
+ +

7.4 Macro arguments

+ +

It is occasionally useful to redefine a macro that takes arguments to +do nothing. Eplain defines \gobble, +\gobbletwo, +and \gobblethree to swallow one, two, and three arguments, +respectively. + +

For example, if you want to produce a “short” table of +contents—one that includes only chapters, say—the easiest thing to +do is read the entire .toc file (see Contents), and just +ignore the commands that produce section or subsection entries. To be +specific: + +

     \let\tocchapterentry = \shorttocchapter
+     \let\tocsectionentry = \gobbletwo
+     \let\tocsubsectionentry = \gobbletwo
+     \readtocfile
+
+

(Of course, this assumes you only have chapters, sections, and +subsections in your document.) + +

In addition, Eplain defines \eattoken +to swallow the single following token, using \let. Thus, +\gobble followed by `{...}' ignores the entire +brace-enclosed text. \eattoken followed by the same ignores only +the opening left brace. + +

Eplain defines a macro \identity +which takes one argument and expands to that argument. This may be +useful if you want to provide a function for the user to redefine, but +don't need to do anything by default. (For example, the default +definition of \eqconstruct (see Formatting equation references) is \identity.) + +

You may also want to read an optional argument. The established +convention is that optional arguments are put in square brackets, so +that is the syntax Eplain recognizes. Eplain ignores space tokens +before an optional argument, via \futurenonspacelet. + +

You test for an optional argument by using \@getoptionalarg. + +It takes one argument, a control sequence to expand after reading the +argument, if present. If an optional argument is present, the control +sequence \@optionalarg expands to it; otherwise, +\@optionalarg is \empty. You must therefore have the +category code of @ set to 11 (letter). Here is an example: + +

     \catcode`@=\letter
+     \def\cmd{\@getoptionalarg\finishcmd}
+     \def\finishcmd{%
+       \ifx\@optionalarg\empty
+         % No optional argument present.
+       \else
+         % One was present.
+       \fi
+     }
+
+

If an optional argument contains another optional argument, the inner +one will need to be enclosed in braces, so TeX does not mistake the +end of the first for the end of the second. + +

+

+ +Next: , +Previous: Macro arguments, +Up: Programming definitions + +
+ +

7.5 Converting to characters

+ +

Eplain defines \xrlabel +to produce control sequence names for cross-reference labels, et al. +This macro expands to its argument with an `_' appended. (It does +this because the usual use of \xrlabel is to generate a control +sequence name, and we naturally want to avoid conflicts between control +sequence names.) + +

Because \xrlabel is fully expandable, to make a control +sequence name out of the result you need only do +

     \csname \xrlabel{label}\endcsname
+
+

The \csname primitive makes a control sequence name out +of any sequence of character tokens, regardless of category code. +Labels can therefore include any characters except for `\', +`{', `}', and `#', all of which are used in macro +definitions themselves. + +

\sanitize takes a control sequence as an argument and converts +the expansion of the control sequence into a list of character tokens. +This is the behavior you want when writing information like chapter +titles to an output file. For example, here is part of the definition +of \writenumberedtocentry; #2 is the title that the user +has given. + +

     ...
+     \def\temp{#2}%
+     ...
+       \write\tocfile{%
+         ...
+         \sanitize\temp
+         ...
+       }%
+
+
+

+ +Next: , +Previous: Converting to characters, +Up: Programming definitions + +
+ +

7.6 Expansion

+ +

This section describes some miscellanous macros for expansion, etc. + +

+ +
+

+ + +Next: , +Up: Expansion + +
+ +

7.6.1 \csn and \ece

+ +

\csn{name} simply abbreviates \csname name +\endcsname, thus saving some typing. The extra level of expansion +does take some time, though, so I don't recommend it for an inner loop. + +

\ece{token}{name} abbreviates + +

     \expandafter token \csname name \endcsname
+
+

For example, + +

     \def\fontabbrevdef#1#2{\ece\def{@#1font}{#2}}
+     \fontabbrevdef{normal}{ptmr}
+
+

defines a control sequence \@normalfont to expand to +ptmr. + +

+

+ + +Next: , +Previous: \csn and \ece, +Up: Expansion + +
+ +

7.6.2 \edefappend

+ +

\edefappend is a way of adding on to an existing definition. It +takes two arguments: the first is the control sequence name, the second +the new tokens to append to the definition. The second argument is +fully expanded (in the \edef that redefines the control sequence). + +

For example: + +

     \def\foo{abc}
+     \def\bar{xyz}
+     \edefappend\foo{\bar karl}
+
+

results in \foo being defined as `abcxyzkarl'. + +

+

+ +Next: , +Previous: \edefappend, +Up: Expansion + +
+ +

7.6.3 Hooks

+ +

A hook is simply a name for a group of actions which is executed +in certain places—presumably when it is most useful to allow +customization or modification. TeX already provides many builtin +hooks; for example, the \every ... token lists are all +examples of hooks. + +

Eplain provides several macros for adding actions to hooks. They all +take two arguments: the name of the hook and the new actions. + + + +

hookaction name actions
hookappend name actions

hookprepend name actions
Each of these adds actions to the hook name. (Any +previously-defined actions are retained.) name is not a control +sequence, but rather the characters of the name. + +


hookactiononce name \cs
\hookactiononce adds cs to name, like the macros +above, but first it adds + + 
          \global\let \cs \relax
+
+

to the definition of \cs. (This implies \cs must +be a true expandable macro, not a control sequence \let to a +primitive or some other such thing.) Thus, \cs is expanded the +next time the hook name is run, but it will disappear after that. + +

The \global is useful because \hookactiononce is most +useful when the grouping structure of the TeX code could be anything. +Neither this nor the other hook macros do global assignments to the hook +variable itself, so TeX's usual grouping rules apply. +

+ +

The companion macro to defining hook actions is \hookrun, for +running them. This takes a single argument, the name of the hook. If +no actions for the hook are defined, no error ensues. + +

Here is a skeleton of general \begin and \end macros that +run hooks, and a couple of calls to define actions. The use of +\hookprepend for the begin action and \hookappend for the +end action ensures that the actions are executed in proper sequence with +other actions (as long as the other actions use \hookprepend and +\hookappend also). + +

     \def\begin#1{ ... \hookrun{begin} ... }
+     \def\end#1{ ... \hookrun{end} ... }
+     \hookprepend{begin}\start_underline
+     \hookappend{end}\finish_underline
+
+
+

+ +Next: , +Previous: Hooks, +Up: Expansion + +
+ +

7.6.4 Properties

+ +

A property is a name/value pair associated with another symbol, +traditionally called an atom. Both atom and property names are +control sequence names. + +

Eplain provides two macros for dealing with property lists: +\setproperty and \getproperty. + + + +

\setproperty atom propname value
\setproperty defines the property property on the atom +atom to be value. atom and propname can be +anything acceptable to \csname. value can be anything. + +


\getproperty atom propname
\getproperty expands to the value stored for propname on +atom. If propname is undefined, it expands to nothing +(i.e., \empty). + +
+ +

The idea of properties originated in Lisp (I believe). There, the +implementation truly does associate properties with atoms. In TeX, +where we have no builtin support for properties, the association is only +conceptual. + +

The following example typesets `xyz'. + +

     \setproperty{a}{pr}{xyz}
+     \getproperty{a}{pr}
+
+
+

+ + +Next: , +Previous: Properties, +Up: Expansion + +
+ +

7.6.5 \expandonce

+ +

\expandonce is defined as \expandafter\noexpand. Thus, +\expandonce token expands token once, instead of to +TeX primitives. This is most useful in an \edef. + +

For example, the following defines \temp to be \foo, not +`abc'. + +

     \def\foo{abc}
+     \def\bar{\foo}
+     \edef\temp{\expandonce\bar}
+
+
+

+ + +Next: , +Previous: \expandonce, +Up: Expansion + +
+ +

7.6.6 \ifundefined

+ +

\ifundefined{cs} t \else f \fi expands the +t text if the control sequence \cs is undefined or +has been \let to \relax, and the f text otherwise. + +

Since \ifundefined is not a primitive conditional, it cannot be +used in places where TeX might skip tokens “at high speed”, e.g., +within another conditional—TeX can't match up the \if's and +\fi's. + +

This macro was taken directly from The TeXbook, page 308. + +

+

+ + +Previous: \ifundefined, +Up: Expansion + +
+ +

7.6.7 \futurenonspacelet

+ +

The \futurelet primitive allows you to look at the next token +from the input. Sometimes, though, you want to look ahead ignoring any +spaces. This is what \futurenonspacelet does. It is otherwise +the same as \futurelet: you give it two control sequences as +arguments, and it assigns the next nonspace token to the first, and then +expands the second. For example: + +

     \futurenonspacelet\temp\finishup
+     \def\finishup{\ifx\temp ...}
+
+
+

+ +Next: , +Previous: Expansion, +Up: Programming definitions + +
+ +

7.7 Obeying spaces

+ +

+\obeywhitespace makes both end-of-lines and space characters in +the input be respected in the output. Unlike plain TeX's +\obeyspaces, even spaces at the beginnings of lines turn into +blank space. + +

By default, the size of the space that is produced by a space +character is the natural space of the current font, i.e., +what \ produces. + +

Ordinarily, a blank line in the input produces as much blank vertical +space as a line of text would occupy. You can adjust this by assigning +to the parameter \blanklineskipamount: +if you set this negative, the space produced by a blank line will be +smaller; if positive, larger. + +

Tabs are not affected by this routine. In particular, if tabs occur +at the beginning of a line, they will disappear. (If you are trying to +make TeX do the “right thing” with tabs, don't. Use a utility +program like expand instead.) + + +

+

+ +Next: , +Previous: Obeying spaces, +Up: Programming definitions + +
+ +

7.8 Writing out numbers

+ +

\numbername +produces the written-out form of its argument, i.e., `zero' through +`ten' for the numbers 0–10, and numerals for all others. + +

+

+ + +Next: , +Previous: Writing out numbers, +Up: Programming definitions + +
+ +

7.9 Mode-specific penalties

+ +

TeX's built-in \penalty command simply appends to the +current list, no matter what kind of list it is. You might intend a +particular penalty to always be a “vertical” penalty, however, i.e., +appended to a vertical list. Therefore, Eplain provides +\vpenalty +and \hpenalty +which first leave the other mode and then do \penalty. + +

More precisely, \vpenalty inserts \par if the current +mode is horizontal, and \hpenalty inserts \leavevmode if +the current mode is vertical. (Thus, \vpenalty cannot be used in +math mode.) + +

+

+ +Next: , +Previous: Mode-specific penalties, +Up: Programming definitions + +
+ +

7.10 Auxiliary files

+ +

It is common to write some information out to a file to be used on a +subsequent run. But when it is time to read the file again, you only +want to do so if the file actually exists. \testfileexistence +is given an argument which is appended to \jobname, +and sets the conditional \iffileexists +appropriately. For example: + +

     \testfileexistence{toc}%
+     \iffileexists
+        \input \jobname.toc
+     \fi
+
+

\testfileexistence takes an optional parameter; when +given, it will override \jobname for the root part of the file +name. For example, if you want to test for the file +answers.aux, you can do this with the following: + +

     \testfileexistence[answers]{aux}%
+     \iffileexists
+        \input answers.aux
+     \fi
+
+
+

+ + +Next: , +Previous: Auxiliary files, +Up: Programming definitions + +
+ +

7.11 User-defined environments

+ +

Plain TeX does not provide “named” block structures, only the anonymous +\begingroup and \endgroup pair. The disadvantage of this +is that when there are several such groups and one is mismatched, it can +be difficult to find the error. Eplain provides a named block structure +so that if you forget an \environment or an +\endenvironment, you will (probably) get an error message about +it. + +

For example: + +

     \def\itpar{
+       \environment{@italicpar}
+       \it\par
+     }
+     \def\enditpar{
+       \par
+       \endenvironment{@italicpar}%
+     }
+
+

which could then be used to set italicized paragraphs: +

     \itpar
+     If I reprehend anything in this world, it is the use of my oracular
+     tongue, and a nice derangement of epitaphs!
+     \enditpar
+
+

The above sort of environment allows nesting. But environments +shouldn't always be allowed to nest. Put the control sequence +\checkenv at the beginning of a macro that is going to define an +environment that should not be nested. + +

+

+ +Previous: User-defined environments, +Up: Programming definitions + +
+ +

7.12 Page list and page range parsers

+ +

The macros which Eplain uses to parse the page lists and ranges in the +index, \idxparselist and \idxparserange (see Page destinations for index terms), are sometimes useful when defining page +number encapsulators. They take one argument, text to parse. When a +page list (range) is not present, they set \idxpagei to be +\empty; when a list (range) is detected, they set +\idxpagei and \idxpageii to the first and the second page +numbers, respectively. + +

Eplain's defaults for the page list and page range delimiters are the +same as those in MakeIndex, a comma followed by a space (`, ') and +two dashes (`--'), respectively. If you customize MakeIndex to use +different delimiters, you must not forget to let Eplain know about them +with the commands + +

     \setidxpagelistdelimiter{list-delim}
+     \setidxpagerangedelimiter{page-delim}
+
+

These commands save the list-delim and +page-delim delimiters in +\idxpagelistdelimiter and \idxpagerangedelimiter, +respectively. + +

For example, you may want to define a page number markup command which +italicizes and properly underlines page ranges by underlining only the +page numbers and not the delimiter: + +

+

     \def\ituline#1{%
+       {\it
+       \idxparserange{#1}%
+       \ifx\idxpagei\empty
+         % The argument is a single page number.
+         \underbar{#1}%
+       \else
+         % The argument is a page range.
+         \underbar{\idxpagei}\idxpagerangedelimiter\underbar{\idxpageii}%
+       \fi}%
+     }
+
+

Note that the \ituline macro is not aware of page +lists. This is not needed if you use hyperlinks in the index, because +\hlidx and \hlidxpage will break up the page lists before +calling the user's page encapsulator (see Page destinations for index terms), so \ituline will never see the lists. If, however, you +need to design a macro which also takes care of the lists, you can +extend \ituline with an additional call to \idxparselist. + + +

+

+ +Next: , +Previous: Programming definitions, +Up: Top + +
+ +

Macro index

+ + + +
+

+ +Previous: Macro index, +Up: Top + +
+ +

Concept index

+ + + + +
+

Table of Contents

+ +
+ + + diff --git a/Master/texmf-dist/doc/eplain/base/eplain.pdf b/Master/texmf-dist/doc/eplain/base/eplain.pdf new file mode 100644 index 00000000000..099777a3115 Binary files /dev/null and b/Master/texmf-dist/doc/eplain/base/eplain.pdf differ diff --git a/Master/texmf-dist/doc/eplain/base/eplain.texi b/Master/texmf-dist/doc/eplain/base/eplain.texi new file mode 100644 index 00000000000..4b54e8160ea --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/eplain.texi @@ -0,0 +1,228 @@ +\input texinfo +@setfilename eplain.info +@settitle Expanded Plain @TeX{} + +@set UPDATED September 2005 +@set VERSION 3.0 + +@copying +This manual documents the Eplain macros, version @value{VERSION}, +@value{UPDATED}. Eplain provides functionality for plain @TeX{} that +is intended to be useful regardless of how your document is actually +formatted. + +Most of this manual is in the public domain, like most of the Eplain +code. It was mostly written by Karl Berry, starting in 1989. Steven +Smith wrote the documentation for the commutative diagram macros; this +chapter is under the GNU General Public License. Oleg Katsitadze and +Adam Lewenberg have made additions and corrections. +@end copying + +@dircategory Texinfo documentation system +@direntry +* Eplain: (eplain). Expanding on plain Tex. +@end direntry + +@titlepage +@title Expanded Plain @TeX{} +@subtitle @value{UPDATED} +@subtitle @value{VERSION} +@author Karl Berry +@author Steven Smith +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@headings double + +@c We use the program index for file extensions. (We want them to come out +@c in typewriter, but saying `@cindex @t{.aux} file', say, doesn't work.) +@synindex pg fn + + +@ifnottex +@node Top +@top Eplain + +@insertcopying +@end ifnottex + +@menu +* Introduction:: Eplain's purpose and philosophy. +* Installation:: Installing Eplain. +* Invoking Eplain:: Using Eplain from a TeX file. +* User definitions:: Macros to be used in a document. +* Hyperlinks:: Producing documents with hyperlinks. +* Arrow theoretic diagrams:: Macros for commutative diagrams. +* Programming definitions:: Macros to be used in writing other macros. +* Macro index:: Entries for TeX and Eplain control sequences. +* Concept index:: General index. + + --- The Detailed Node Listing --- + +User definitions + +* Diagnostics:: Tracing information. +* Rules:: Changing the default rule dimensions. +* Citations:: Using BibTeX and Eplain to make bibliographies. +* Displays:: Changing the formatting of math displays. +* Time of day:: Producing the time of day. +* Lists:: Producing numbered and unordered lists. +* Verbatim listing:: Producing text just as it appears. +* Contents:: Making a table of contents. +* Cross-references:: Symbolically referring to pages or equations. +* Page references:: Symbolic references to page numbers. +* Equation references:: Symbolic references to equation numbers. +* Indexing:: Creating and typesetting indexes. +* Justification:: Left- or right-justification, or centering. +* Tables:: Producing ordered tables. +* Margins:: Changing the margins directly. +* Multiple columns:: Getting output in two columns. +* Footnotes:: Autonumbered footnotes; changing formatting. +* Fractions:: A better way to produce fractions in text. +* Paths:: Allowing line breaks in pathnames. +* Logos:: Various logos. +* Boxes:: Producing filled or open rectangles. +* Checking for PDF output:: Checking for pdfTeX in PDF mode. + +Citations + +* Formatting citations:: Changing the way citations are printed. +* Formatting bibliographies:: Changing the way bibliographies are printed. + +Displays + +* Formatting displays:: General formatting of displays. + +Lists + +* Formatting lists:: Changing how the lists look. + +Cross-references + +* Defining generic references:: +* Using generic references:: + +Equation references + +* Formatting equation references:: +* Subequation references:: + +Indexing + +* Indexing terms:: Specifying what to index. +* Typesetting an index:: Printing the sorted output. +* Customizing indexing:: Creating commands and specifying extra actions. + +Indexing terms + +* Indexing commands:: Making index entries. +* Modifying index entries:: Ranges, see/see also, page number typesetting. +* Proofing index terms:: Noting index entries in the margins. + +Hyperlinks + +* Introduction to hyperlinks:: +* Explicit hyperlinks:: +* Implicit hyperlinks:: +* Hyperlink drivers:: +* Setting hyperlink types and options:: +* Turning hyperlinks on/off:: + +Implicit hyperlinks + +* URL hyperlinks:: url +* Citation hyperlinks:: cite, bib +* List hyperlinks:: li +* Cross-reference hyperlinks:: definexref, ref +* Page reference hyperlinks:: xrdef, xref +* Equation reference hyperlinks:: eq +* Index hyperlinks:: idx +* Footnote hyperlinks:: foot, footback +* Contents hyperlinks:: + +Index hyperlinks + +* Exact destinations for index terms:: +* Page destinations for index terms:: +* Choosing destination placement:: +* Index page list and page range parsers:: +* Hyperlinks in see and see also entries:: + +Hyperlink drivers + +* Options supported by all drivers:: +* Hyperlink drivers pdftex and dvipdfm:: +* Hyperlink driver nolinks:: + +Hyperlink drivers pdftex and dvipdfm:: + +* Destination types for pdftex and dvipdfm:: +* Destination options for pdftex and dvipdfm:: +* Link types for pdftex and dvipdfm:: +* Link options for pdftex and dvipdfm:: + +Setting hyperlink types and options + +* Setting default types and options:: +* Setting group types:: +* Setting group options:: + +Turning hyperlinks on/off + +* Turning low-level commands on/off:: +* Turning hyperlinks on/off for a group:: + +Arrow theoretic diagrams + +* Slanted lines and vectors:: +* Commutative diagrams:: + +Commutative diagrams + +* Arrows and morphisms:: +* Construction of commutative diagrams:: +* Commutative diagram parameters:: + +Programming definitions + +* Category codes:: Changing category codes. +* Allocation macros:: Non-outer versions of \newcount et al. +* Iteration:: Doing `for' loops in TeX. +* Macro arguments:: Reading and ignoring them. +* Converting to characters:: Normalizing control sequences and spaces. +* Expansion:: Controlling expansion. +* Obeying spaces:: Making whitespace count anywhere. +* Writing out numbers:: Making `1' into `one'. +* Mode-specific penalties:: +* Auxiliary files:: Testing for their existence. +* User-defined environments:: User-defined environments. +* Page list and page range parsers:: + +Expansion + +* \csn and \ece:: +* \edefappend:: +* Hooks:: Manipulating and executing named actions. +* Properties:: Associating information with a csname. +* \expandonce:: +* \ifundefined:: +* \futurenonspacelet:: + +@end menu + +@include intro.texi +@include install.texi +@include invoke.texi +@include userdef.texi +@include hlink.texi +@include arrow.texi +@include progdef.texi +@include csindex.texi +@include index.texi + + +@contents + +@bye diff --git a/Master/texmf-dist/doc/eplain/base/hlink.texi b/Master/texmf-dist/doc/eplain/base/hlink.texi new file mode 100644 index 00000000000..083bfa99fac --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/hlink.texi @@ -0,0 +1,1860 @@ +@c This is part of the Eplain manual. Public domain. + +@node Hyperlinks +@chapter Hyperlinks + +@cindex links, hypertext +@cindex hypertext links +This chapter describes the support which Eplain provides for hypertext +links (@dfn{hyperlinks} for short). Hyperlinks can be created +implicitly by the cross-reference, indexing and other macros in +Eplain. Macros for constructing explicit hyperlinks are also +provided. + +@menu +* Introduction to hyperlinks:: +* Explicit hyperlinks:: +* Implicit hyperlinks:: +* Hyperlink drivers:: +* Setting hyperlink types and options:: +* Turning hyperlinks on/off:: +@end menu + + +@node Introduction to hyperlinks +@section Introduction to hyperlinks + +@cindex hyperlink drivers +@cindex drivers, hyperlink +The original @TeX{} engine has no built-in support for hyperlinks. +Many of the present-day file formats with hyperlinking capabilities +did not even exist at the time @TeX{} was written. However, @TeX{}'s +@findex special +@code{\special} primitive can be used to instruct @TeX{} to write +special directives into its @file{.dvi} output file. These directives +are not interpreted by @TeX{} in any way; they are intended for programs +which process the @file{.dvi} files produced by @TeX{}, be it printing +or converting to other formats, such as +@pindex .ps @r{files} +@pindex .pdf @r{files} +@file{.ps} or @file{.pdf}. + +Another approach is to extend the original @TeX{} engine with the +ability to generate one of the hyperlinking formats; @TeX{}'s set of +primitives can be extended to include hyperlink commands. This is the +approach used by the pdf@TeX{} engine, which is capable of producing +@file{.pdf} files directly from the @TeX{} source, skipping the +@file{.dvi} generation and processing step. + +It turns out that the sets of commands for different formats are mostly +not interchangeable, as each of the file formats has its own quirks and +capabilities. And this is where Eplain @dfn{hyperlink drivers} come +into play. + +In order for Eplain to generate proper commands, Eplain has to know +two things: which engine or @file{.dvi} processor you are using, and +the set of commands it understands. + +The knowledge about the commands that the various processors +understand is programmed into Eplain's hyperlink drivers. Eplain +provides two drivers, @code{pdftex} and @code{dvipdfm}, named after +the programs which process the hyperlink commands, +@pindex pdftex +pdf@TeX{} and +@pindex dvipdfm +dvipdfm. Therefore, Eplain can only produce hyperlink commands for one +of these two programs---except that the extended @code{dvipdfmx} program +can be used as well as the original @code{dvipdfm}, since they are +compatible. + +To tell Eplain which @file{.dvi} processor or extended @TeX{} engine you +are using, use the command +@findex enablehyperlinks +@code{\enablehyperlinks}. + +For example: + +@example +\enablehyperlinks +@end example + +@noindent instructs Eplain to attempt to automatically detect which +driver to use, as follows: if it detects pdf@TeX{} in PDF mode, it +loads the @code{pdftex} driver. If it does not detect pdf@TeX{} in +PDF mode, the @code{dvipdfm} driver is loaded. The detection is based +on the +@findex ifpdf +@code{\ifpdf} switch (@pxref{Checking for PDF output}). + +If necessary, you can explicitly specify the driver name: + +@example +\enablehyperlinks[pdftex] +@end example + +@noindent will start producing hyperlinks under the assumption that +you are using pdf@TeX{}. + +Eplain does not produce any hyperlinks until you explicitly enable +them with @code{\enablehyperlinks}. For one thing, this keeps Eplain +backward-compatible with previous releases without hyperlink support. +For another, you may be using a program other than pdf@TeX{} or +@code{dvipdfm}, which does not understand their hyperlink commands. + +@subheading Concepts and Terminology + +In general, hyperlinks work as follows. You mark some place in your +document as a hyperlink destination, associating a @dfn{hyperlink +label} with that destination. Next, somewhere within your document, +you create a hyperlink, using a label to identify the destination you +want this link to point to. A hyperlink is a region in the document +(which can take many forms, for example, text or a picture); when a +user clicks on that region, they will be taken to a place in the +document marked by the corresponding destination. The following two +sections (@ref{Explicit hyperlinks}, and @ref{Implicit hyperlinks}) +describe the macros you can use to define destinations and create +links pointing to those destinations. + +In the rest of this chapter, we will often need to refer to links and +destinations jointly, in which case we will use the term +@dfn{hyperlinks}. We will use the terms @dfn{links} and +@dfn{destinations} in cases when we need to refer specifically to +links or destinations. + +@cindex link type +@cindex destination type +@cindex type, link and destination +Hyperlink drivers provide several kinds of links and destinations. We +will refer to them as @dfn{link types} and @dfn{destination types}. + +For example, one of the destination types that the @code{pdftex} +driver provides is the @samp{xyz} type; when the user follows a link +pointing to an @samp{xyz} destination, the exact location marked by +that destination is displayed. Another destination type provided by +the @code{pdftex} driver is the @samp{fit} type; when the user follows +a link pointing to a @samp{fit} destination, the page containing that +destination is zoomed to fit into the window in which the document is +displayed. + +Similarly, drivers support various link types. For example, with the +@code{pdftex} driver, the usual link type used to refer to +destinations in the current document is called @samp{name}. You can +also create a link pointing to another local document (by using the +@samp{filename} link type) or to a URL (by using the @samp{url} link +type). + +@cindex link options +@cindex destination options +@cindex options, link and destination +In addition, each hyperlink driver supports a number of destination and +link @dfn{options}. By setting these options you can customize +hyperlink parameters (e.g., the thickness of the border drawn around a +hyperlink) or pass information to hyperlinks (for example, file name of +a document, for a link pointing to a destination in another document). + +@xref{Hyperlink drivers}, for the description of hyperlink types and +options supported by the drivers. @xref{Setting hyperlink types and +options}, for the information on how to set hyperlink options. + + +@node Explicit hyperlinks +@section Explicit hyperlinks + +@cindex explicit hyperlinks +@cindex hyperlinks, explicit +@findex hldest +Explicit hyperlinks are created by you, in the source of your +document. The simplest command is @code{\hldest}, which marks the +current position in your document as a destination: + +@example +\hldest@{@var{type}@}@{@var{options}@}@{@var{label}@} +@end example + +@noindent Here @var{type} is one of the destination types supported by +the hyperlink driver (@pxref{Hyperlink drivers}), @var{options} is a +comma-separated list of option assignments, and @var{label} is the +hyperlink label to associate with this destination. This label will +identify the destination when creating links pointing to this +destination. For example, with the @code{pdftex} driver, the command + +@example +\hldest@{xyz@}@{zoom=2000@}@{index@} +@end example + +@noindent creates a destination of type @samp{xyz} (``the current +position''), sets the magnification ratio for this destination to be +200%, and associates the label @code{index} with the destination. + +@findex hlstart +@findex hlend +Another command, @code{\hlstart}, paired with @code{\hlend}, turns all +intervening material into a link: + +@example +\hlstart@{@var{type}@}@{@var{options}@}@{@var{label}@} @dots{} \hlend +@end example + +@noindent Here @var{type}, @var{options} and @var{label} have the same +meaning as for @code{\hldest}. Continuing the previous example, + +@example +\hlstart@{name@}@{bstyle=U,bwidth=2@}@{index@} Index\hlend +@end example + +@noindent typesets the word `Index' as a link with underline border of +width@tie{}2@tie{}PostScript points, pointing to the named destination +@code{index} defined in the previous example. (The other options, like +highlight mode and border color, are determined by the defaults, +@pxref{Setting default types and options}). + +Both @code{\hldest} and @code{\hlstart} ignore following spaces. + +Both @code{\hldest} and @code{\hlstart} expand the first token of +@var{options} once, so you can save a list of options in a macro and +pass it for the @var{options}. For example: + +@example +\def\linkopts@{bstyle=U,bwidth=2@} +\hlstart@{name@}@{\linkopts@}@{index@}Index\hlend +@end example + +@noindent is functionally equivalent to the previous example. + + +@node Implicit hyperlinks +@section Implicit hyperlinks + +@cindex implicit hyperlinks +@cindex hyperlinks, implicit +@dfn{Implicit hyperlinks} are hyperlinks created implicitly by various +Eplain macros, such as the macros for citations, cross-references, +indexing, etc. + +@cindex link group +@cindex linkgroup +@cindex group, link +@cindex destination group +@cindex destgroup +@cindex group, destination +All such macros are divided into @dfn{link groups} and +@dfn{destination groups} (or @dfn{linkgroups} and @dfn{destgroups} for +short) so that parameters can be set individually for each group. For +example, all equation macros which define a destination are assigned +to the `eq' destgroup; equation macros which create a link are +assigned to the `eq' linkgroup. By setting parameters for the `eq' +linkgroup (destgroup), you can uniformly customize all links +(destinations) related to equation references, without interfering +with settings for the other groups. + +@xref{Setting hyperlink types and options}, for information on how to +set parameters for a group. + +Here is the list of the linkgroups: + +@display +cite, ref, xref, eq, idx, foot, footback, url. +@end display + +And here are the destgroups: + +@display +bib, li, definexref, xrdef, eq, idx, foot, footback. +@end display + +The following subsections describe each of the linkgroups and destgroups +and the hyperlink support provided. + +@menu +* URL hyperlinks:: url +* Citation hyperlinks:: cite, bib +* List hyperlinks:: li +* Cross-reference hyperlinks:: definexref, ref +* Page reference hyperlinks:: xrdef, xref +* Equation reference hyperlinks:: eq +* Index hyperlinks:: idx +* Footnote hyperlinks:: foot, footback +* Contents hyperlinks:: +@end menu + + +@node URL hyperlinks +@subsection URL hyperlinks: url + +@cindex URL hyperlink +@cindex hyperlinks, URL +@cindex group `url' +@cindex linkgroup `url' +The `url' linkgroup covers the +@findex url @r{(hyperlinks)} +@code{\url} command from the @LaTeX{} package +@pindex url.sty +@file{url} (@pxref{Packages known to work}), as well as any new +@code{\url}-like commands you define. The type for this linkgroup is +set to @samp{url} by the drivers which support this link type. +@samp{url} links use the parameter to the @code{\url} command as the URL +to point to. + +You may be using the @code{\url} command to typeset something other than +a URL, e.g., a path, for which you do not want a link to be created; in +that case, you can disable the `url' linkgroup with the command +@code{\hloff[url]} (@pxref{Turning hyperlinks on/off for a group}). + + +@node Citation hyperlinks +@subsection Citation hyperlinks: cite, bib + +@cindex citations, hyperlinks +@cindex hyperlinks, citations +@cindex group `cite' +@cindex linkgroup `cite' +@findex cite @r{(hyperlinks)} +The `cite' linkgroup includes only the @code{\cite} command +(@pxref{Citations}). @code{\cite} turns each of the references in the +list into a link pointing to the respective bibliography entry +produced by the @code{\bibliography} command. + +@cindex bibliography, hyperlinks +@cindex hyperlinks, bibliography +@cindex group `bib' +@cindex destgroup `bib' +@findex bibliography @r{(hyperlinks)} +The `bib' destgroup includes the macros related to the +@code{\bibliography} command (@pxref{Citations}). @code{\bibliography} +inputs a @file{.bbl} file, which contains a list of bibliography +entries. For each of the entries, a destination is defined. + +Both commands use the citation label as the hyperlink label. + + +@node List hyperlinks +@subsection List hyperlinks: li + +@cindex lists, hyperlinks +@cindex hyperlinks, lists +@findex li @r{(hyperlinks)} +@cindex group `li' +@cindex destgroup `li' +The `li' destgroup consists of the @code{\li} command (@pxref{Lists}), +which defines a destination if you supply the optional argument +(cross-reference label). This label is also used as the hyperlink +label. + + +@node Cross-reference hyperlinks +@subsection Cross-reference hyperlinks: definexref, ref + +@findex definexref @r{(hyperlinks)} +@cindex cross-references, hyperlinks +@cindex hyperlinks, cross-references +@cindex group `definexref' +@cindex destgroup `definexref' +The `definexref' destgroup is for the @code{\definexref} command +(@pxref{Defining generic references}). @code{\definexref} defines a +destination using the cross-reference label (the first argument) as the +hyperlink label. + +@cindex group `ref' +@cindex linkgroup `ref' +The `ref' linkgroup includes @code{\refn} and @code{\xrefn} (they are +synonyms), @code{\ref}, and @code{\refs} (@pxref{Using generic +references}). + +@findex refn @r{(hyperlinks)} +@findex xrefn @r{(hyperlinks)} +@code{\refn} turns the cross-reference it produces into a link, using +the cross-reference label as the hyperlink label. If an optional +argument is present, it is tied by +@findex reftie +@code{\reftie} to the reference and become part of the link. + +@findex ref @r{(hyperlinks)} +@code{\ref} works similarly to @code{\refn}. It takes an optional +argument, which is treated the same way as the optional argument to +@code{\refn}. In addition, @code{\ref} can produce a ``class word''. +Both the optional argument and the class word become part of the link, +when present. The cross-reference is tied by +@findex reftie +@code{\reftie} to the preceding word. The optional argument is +separated from the class word by +@findex refspace +@code{\refspace}. + +@findex refs @r{(hyperlinks)} +Unlike @code{\ref}, @code{\refs} does not take an optional argument and +does not make the class word part of the link, which is appropriate for +its intended use. + + +@node Page reference hyperlinks +@subsection Page reference hyperlinks: xrdef, xref + +@findex xrdef @r{(hyperlinks)} +@cindex page reference hyperlink +@cindex hyperlinks, page references +@cindex group `xrdef' +@cindex destgroup `xrdef' +The `xrdef' destgroup is for @code{\xrdef} (@pxref{Page references}). +@code{\xrdef} defines a destination using cross-reference label as the +hyperlink label. + +@findex xref @r{(hyperlinks)} +@findex refspace +@findex xrefpageword +@cindex group `xref' +@cindex linkgroup `xref' +The `xref' linkgroup includes the @code{\xref} command (@pxref{Page +references}). @code{\xref} turns its optional argument (followed by +@code{\refspace}), @code{\xrefpageword} and the cross-reference (page +number) into a link, using the cross-reference label as the hyperlink +label. + + +@node Equation reference hyperlinks +@subsection Equation reference hyperlinks: eq + +@findex eqdef @r{(hyperlinks)} +@findex eqdefn @r{(hyperlinks)} +@findex eqsubdef @r{(hyperlinks)} +@findex eqsubdefn @r{(hyperlinks)} +@cindex equations, hyperlinks +@cindex hyperlinks, equations +@cindex group `eq' +@cindex destgroup `eq' +All commands that define equation labels are part of the `eq' destgroup. +These are @code{\eqdef}, @code{\eqdefn}, @code{\eqsubdef} and +@code{\eqsubdefn} (@pxref{Equation references}). All these commands use +the equation label as the hyperlink label. However, if the equation +label is empty, they make up a (hopefully) unique hyperlink label for +the destination. This label will be used for the link when you refer to +this empty-labeled equation with one of the equation reference macros. + +@findex phantomeqlabel +@findex phantomeqnumber +The command @code{\phantomeqlabel} is called to generate hyperlink +labels for the empty-labeled equations. By default, it produces the +labels in the format @samp{PHEQ@var{number}}, where @var{number} comes +from the count register @code{\phantomeqnumber}; this count register is +incremented at every empty-labeled equation definition. + +@findex eqref +@findex eqrefn +@findex reftie +@cindex group `eq' +@cindex linkgroup `eq' +The commands @code{\eqref} and @code{\eqrefn} (@pxref{Equation +references}) form the `eq' linkgroup. These commands take an optional +argument, which, when present, is tied with @code{\reftie} to the +equation reference and becomes part of the link. The equation label is +used for the hyperlink label; if the label is empty, the link is for the +label generated for the last empty-labeled equation. + + +@node Index hyperlinks +@subsection Index hyperlinks: idx + +@findex idx @r{(hyperlinks)} +@findex idxname @r{(hyperlinks)} +@findex idxmarked @r{(hyperlinks)} +@findex idxsubmarked @r{(hyperlinks)} +@cindex index hyperlink +@cindex hyperlinks, index +@cindex group `idx' +@cindex linkgroup `idx' +@cindex destgroup `idx' +All indexing commands (@code{\idx}, @code{\idxname}, @code{\idxmarked}, +@code{\idxsubmarked} and their silent equivalents, @pxref{Indexing +commands}) form the `idx' destgroup. The `idx' linkgroup consists of +the macros which are used to typeset the index when you say +@findex readindexfile @r{(hyperlinks)} +@code{\readindexfile@{@var{index-letter}@}} (@pxref{Typesetting an +index}). + +@pindex makeindex +To create the links in index entries, Eplain uses MakeIndex's +``encapsulation'' feature. When you use an indexing macro to mark an +index term, Eplain writes out a line to the +@pindex .idx @r{files} +@file{.idx} file of the following general form: + +@example +\indexentry@{@var{entry}|@var{pagemarkup}@}@{@var{pageno}@} +@end example + +@noindent where @var{entry} is the index entry (converted into the +internal format that MakeIndex understands), @var{cs} is the markup +command you specified with the @code{pagemarkup=@var{cs}} optional +argument to the indexing commands (@pxref{Modifying index entries}), +and @var{pageno} is the page number on which the term appeared. When +processing the @file{.idx} file, MakeIndex makes the page number an +argument to the page markup command (``encapsulates'' the page +number), so the page number in the +@pindex .ind @r{files} +@file{.ind} file appears as @code{\@var{cs}@{@var{pageno}@}}. Eplain +internally replaces the @var{cs} command name with its own command, +which, in addition to calling the original @code{\@var{cs}} +encapsulator, turns the page number into a link. + +Eplain provides two approaches to linking page numbers in the index to +locations of index terms in the text. + +@menu +* Exact destinations for index terms:: +* Page destinations for index terms:: +* Choosing destination placement:: +* Index page list and page range parsers:: +* Hyperlinks in see and see also entries:: +@end menu + + +@node Exact destinations for index terms +@subsubsection Exact destinations for index terms + +In this approach, each command that marks an index term defines a unique +destination and passes its label on to the @file{.idx} file as part of +the @code{\indexentry} command. The @code{\indexentry} line that Eplain +writes to the @file{.idx} file becomes + +@example +\indexentry@{@var{entry}|hlidx@{@var{label}@}@{@var{cs}@}@}@{@var{pageno@}} +@end example + +@findex hlidx +@noindent where @code{\hlidx} is the command that is defined by Eplain +to take three arguments: a hyperlink label (@var{label}), a name of +page number encapsulator (@var{cs}) and a page number (@var{pageno}). +In the @file{.ind} file that MakeIndex will generate, the page number +will now appear as + +@example +\hlidx@{@var{label}@}@{@var{cs}@}@{@var{pageno}@} +@end example + +@noindent The result of this command is +@code{\@var{cs}@{@var{pageno}@}}, wrapped up into a link pointing to +@var{label} destination. + +The hyperlink labels for the index terms are generated by the +@findex hlidxlabel +@code{\hlidxlabel} command, by default in the format +@samp{IDX@var{number}}, where @var{number} is the value of the count +register +@findex hlidxlabelnumber +@code{\hlidxlabelnumber}. This count register is incremented at each +index term. + +@cindex exact index hyperlinks +@cindex index, exact hyperlinks +@cindex hyperlinks, index, exact +The advantage of this approach, as compared to the second approach +described below, is that links in the index point to exact locations of +the indexed terms on the page. The disadvantage of this approach is +that MakeIndex will regard @emph{all} index entries as distinct, because +each one contains a (unique) hyperlink label. This disadvantage can be +partially overcome by the script +@pindex idxuniq +@cindex filtering index entries with hyperlinks +@cindex hyperlinks, filtering index entries +@file{idxuniq} distributed with Eplain in the @file{util} directory. +This script filters out @code{\indexentry} lines differing only in the +hyperlink label but identical otherwise. You should process the +@file{.idx} with this script before passing it on to MakeIndex. For +example: + +@example +prompt$ ./idxuniq file.idx | makeindex > file.ind +@end example + +@noindent Still, this solution is not ideal, as the page-range formation +ability of MakeIndex will not work, and there will be problems of +apparently identical index entries clashing (e.g., when a range-end +entry appears on the same page as another entry with the same +definition; @file{idxuniq} will not filter out the second entry). + + +@node Page destinations for index terms +@subsubsection Page destinations for index terms + +In the second approach, Eplain does not write out any destination labels +for the index terms. Instead, Eplain writes out a wrapper for page +number encapsulator which can parse the page number and generate a link +pointing to the @emph{page} on which the term appeared. On top of each +page containing an index term, Eplain defines a destination with label +produced by +@findex hlidxpagelabel +@code{\hlidxpagelabel}. The @code{\hlidxpagelabel} command takes a +single argument (page number @var{number}) and by default produces the +label in the format @samp{IDXPG@var{number}}. + +With this approach, the @code{\indexentry} line which Eplain writes to +the @code{.idx} file looks like this: + +@example +\indexentry@{@var{entry}|hlidxpage@{@var{cs}@}@}@{@var{pageno@}} +@end example + +@findex hlidxpage +@noindent where @code{\hlidxpage} is the command that is defined by Eplain +to take two arguments: a name of page number encapsulator (@var{cs}) +and a page number (@var{pageno}). In the @file{.ind} file that +MakeIndex will generate, the page number will appear as + +@example +\hlidxpage@{@var{cs}@}@{@var{pageno}@} +@end example + +The advantage of this approach is that all features of MakeIndex are +intact. The drawback is that links in the index do not point to exact +locations of indexed terms on a page, but to the top of a page on +which the term appears. + +@cindex index, parsing page numbers +@cindex page range, parsing +@cindex page list, parsing +@cindex parsing page numbers +Another disadvantage is that this approach depends on the page range and +page list separators which MakeIndex was configured to output. +@code{\hlidxpage} must be able to parse the first page number in a page +range like @samp{1--4}. In addition, page list parsing is needed +because MakeIndex combines two consecutive page numbers in one call to +the page number encapsulator, so @code{\hlidxpage} can be passed, e.g., +@samp{1, 2} for the @var{pageno}. In this last case, @code{\hlidxpage} +splits the two page numbers, applies @code{\@var{cs}} to each of them, +and makes each of the page numbers a link to the appropriate page. Note +that this will alter typesetting slightly, because now the page list +separator (a comma followed by a space, by default) is not typeset using +the page number encapsulator (@code{\@var{cs}}). + +Eplain's defaults for the page list and page number delimiters are the +same as those in MakeIndex, a comma followed by a space (@samp{, }) and +two dashes (@samp{--}), respectively. If you customize MakeIndex to use +different delimiters, you must not forget to let Eplain know about them +with the commands + +@example +\setidxpagelistdelimiter@{@var{list-delim}@} +\setidxpagerangedelimiter@{@var{page-delim}@} +@end example + +@noindent (@pxref{Page list and page range parsers}). + + +@node Choosing destination placement +@subsubsection Choosing destination placement + +@cindex index, placement of destinations +@cindex index, destination placement +@cindex index, selecting destination placement +@cindex index, choosing destination placement +@cindex hyperlinks, index destination placement +The approach that Eplain should use for the index terms can be +selected in the +@findex enablehyperlinks +@code{\enablehyperlinks} command. The optional argument it accepts is +a comma-separated list of options. The +@findex idxexact +@code{idxexact} option selects the first approach, +@findex idxpage +@code{idxpage} the second, and +@findex idxnone +@code{idxnone} disables hyperlink support for the index terms +altogether, in case you want to stop Eplain from writing its link +wrappers into the @file{.idx} file. The default is @code{idxpage}. + +For example: + +@example +\enablehyperlinks[idxexact] +@end example + +@noindent selects the first approach (``exact index links''). + + +@node Index page list and page range parsers +@subsubsection Index page list and page range parsers + +The macros that Eplain uses to parse page lists and page ranges, +@code{\idxparselist} and @code{\idxparserange}, can sometimes be useful +when defining page number encapsulators. @xref{Page list and page range +parsers}, for the description of these commands and an example of their +usage. + + +@node Hyperlinks in see and see also entries +@subsubsection Hyperlinks in see and see also entries + +@cindex hyperlinks, see and see also index entries +@cindex index, hyperlinks in see and see also entries +@cindex see also index entries and hyperlinks +@cindex see, and index entries, hyperlinks +There is no automatic support for hyperlinks with ``see'' and ``see +also'' index entries, as there is not enough information to trace the +parameters of +@findex indexsee +@code{\indexsee} and +@findex indexseealso +@code{\indexseealso} to corresponding index entries. But if desired, +this can be implemented with @code{\hldest} and @code{\hlstart} +(@pxref{Explicit hyperlinks}); for example: + +@example +\sidx@{semantic theory of truth@@% + \leavevmode\hldest@{@}@{@}@{idx:theo truth@}semantic theory of truth@} +@dots{} +\sidx[seealso]@{truth@}[definition of]% + @{\hlstart@{@}@{@}@{idx:theo truth@}semantic theory of truth\hlend@} +@end example + + +@node Footnote hyperlinks +@subsection Footnote hyperlinks: foot, footback + +@cindex footnotes, hyperlinks +@cindex hyperlinks, footnotes +@cindex group `foot' +@cindex group `footback' +@cindex linkgroup `foot' +@cindex linkgroup `footback' +@cindex destgroup `foot' +@cindex destgroup `footback' +The `foot' link and destination groups include the +@findex numberedfootnote @r{(hyperlinks)} +@code{\numberedfootnote} and +@findex footnote @r{(hyperlinks)} +@code{\footnote} macros (@pxref{Footnotes}). The `footback' groups +include the same macros, but control parameters for links and +destinations created inside the footnote to point back to the footnote +mark within the text body. + +The macros use hyperlink labels generated by +@findex hlfootlabel +@code{\hlfootlabel} and +@findex hlfootbacklabel +@code{\hlfootbacklabel}. The default formats for the labels are +@samp{FOOT@var{number}} and @samp{FOOTB@var{number}}, respectively, +where @var{number} is the value of the count register +@findex hlfootlabelnumber +@code{\hlfootlabelnumber}. This register is incremented at every +footnote. + + +@node Contents hyperlinks +@subsection Contents hyperlinks + +@cindex table of contents, hyperlinks +@cindex contents, hyperlinks +@cindex hyperlinks, table of contents +There is currently no special support for hyperlinks in the table of +contents (@pxref{Contents}), but implementing them with the +@code{\hldest} and @code{\hlstart @dots{} \hlend} commands +(@pxref{Explicit hyperlinks}) should be possible. + + +@node Hyperlink drivers +@section Hyperlink drivers + +This section describes the hyperlink drivers: the types of hyperlinks +they support, and the options they accept. During the first reading, +you may only want to skim through this section. + +Some of the descriptions below come from @cite{Portable Document Format +Reference Manual Version@tie{}1.3}, March@tie{}11, 1999. + +@menu +* Options supported by all drivers:: +* Hyperlink drivers pdftex and dvipdfm:: +* Hyperlink driver nolinks:: +@end menu + + +@node Options supported by all drivers +@subsection Options supported by all drivers + +@cindex hyperlink options, common +This subsection describes the destination and link options which are +supported by all hyperlink drivers. + + +@subsubheading Destination options supported by all drivers + +@cindex destination options, common +@cindex options, destination, common +@table @code +@item raise +@findex raise @r{(hyperlink option)} +@cindex raising hyperlink destinations +@cindex hyperlink destination, raising +@cindex destinations, raising +Specifies how much to raise destinations above the baseline. When set +to zero or empty, destinations are placed at the baseline. + +It is usually convenient to set this option to some variable parameter, +so that the height to which destinations are raised is automatically +adjusted according to the current context. For example, setting it to +@findex normalbaselineskip +@code{\normalbaselineskip} (or some fraction of it, like +@code{1.7\normalbaselineskip}) makes the setting appropriate for +different point sizes, in case your document uses more than one. + +The default setting is @code{\normalbaselineskip}. Initially, the +destgroups do not define this option, so they fall back on the default, +except for the `eq' destgroup, for which this option is set to +@code{1.7\normalbaselineskip}, +@cindex mathematics displays, hyperlinks +@cindex displayed math and hyperlinks +@cindex large operators and hyperlinks +@cindex hyperlinks, large operators +@cindex destinations, large operators +to accommodate the usual cases of large operators in displayed math. + +Example: @code{\hldestopts[eq]@{raise=2.5\normalbaselineskip@}} +@end table + + +@subsubheading Link options supported by all drivers +@cindex link options, common +@cindex options, link, common + +@table @code +@item colormodel +@itemx color +@findex colormodel @r{(hyperlink option)} +@findex color @r{(hyperlink option)} +@cindex color, hyperlinks +These two options define the color to be used for rendering the link +text. The colors are used only when a @code{\color} command is defined, +e.g., by loading the @LaTeX{} `color' package (@pxref{Packages known to +work}). The @code{\color} command is called as +@code{\color[@var{colormodel}]@{@var{color}@}}, where @var{colormodel} +and @var{color} are the definitions of the @code{colormodel} and +@code{color} options, respectively. However, if @var{colormodel} is +empty, the optional argument to @code{\color} is omitted; and if +@var{color} is empty, the @code{\color} command is omitted altogether. +The default setting is @code{@var{colormodel}=cmyk} and +@code{@var{color}=0.28,1,1,0.35}. + +When specifying colors with several components delimited by commas +(e.g., RGB and CMYK colors in the @LaTeX{} `color' package), it is not +possible to specify the components directly in the option list of +@code{\hlopts}, because comma is the option list delimiter. With the +`color' package, it is possible to specify such colors by defining a +custom color with @code{\definecolor} and using the new color name with +an empty @var{colormodel} (see examples below). + +Examples: +@example +\hlopts@{colormodel=,color=blue@}% predefined color +\definecolor@{mycolor@}@{rgb@}@{.3,.8,.95@} +\hlopts@{colormodel=,color=mycolor@}% custom color +\hlopts@{colormodel=gray,color=.4@} +@end example +@end table + + +@node Hyperlink drivers pdftex and dvipdfm +@subsection Hyperlink drivers @code{pdftex} and @code{dvipdfm} + +@cindex @code{pdftex}, hyperlink driver +@cindex @code{dvipdfm}, hyperlink driver +@cindex driver @code{pdftex} +@cindex driver @code{dvipdfm} +@cindex hyperlink driver @code{pdftex} +@cindex hyperlink driver @code{dvipdfm} +This subsection describes link and destination types and options +supported by the @code{pdftex} and @code{dvipdfm} drivers. Many of the +hyperlink types and options are common to both drivers, so we describe +them together. + +@menu +* Destination types for pdftex and dvipdfm:: +* Destination options for pdftex and dvipdfm:: +* Link types for pdftex and dvipdfm:: +* Link options for pdftex and dvipdfm:: +@end menu + + +@node Destination types for pdftex and dvipdfm +@subsubsection Destination types for @code{pdftex} and @code{dvipdfm} + +@cindex destination types, @code{pdftex} +@cindex destination types, @code{dvipdfm} +@cindex types, destination, @code{pdftex} +@cindex types, destination, @code{dvipdfm} +@cindex @code{pdftex}, destination types +@cindex @code{dvipdfm}, destination types +@table @code +@item xyz +@findex xyz @r{(destination type)} +``Current position''. The option +@findex zoom @r{(destination option)} +@code{zoom} specifies magnification to use (zero or empty means leave +magnification unchanged, which is the default). This is the default +type. + +For @code{dvipdfm}: the options +@findex left @r{(destination option)} +@code{left} and +@findex top @r{(destination option)} +@code{top} specify position coordinates to use (empty options mean +current position coordinate, which is the default). + +Example: @code{\hldest@{xyz@}@{zoom=2000@}@{dest123@}} + +@item fit +@findex fit @r{(destination type)} +Fit the page to the window. + +Example: @code{\hldest@{fit@}@{@}@{dest123@}} + +@item fith +@findex fith @r{(destination type)} +Fit the width of the page to the window. + +For @code{dvipdfm}: the +@findex top @r{(destination option)} +@code{top} option specifies vertical position (default is empty, meaning +current position). + +Example: @code{\hldest@{fith@}@{@}@{dest123@}} + +@item fitv +@findex fitv @r{(destination type)} +Fit the height of the page to the window. + +For @code{dvipdfm}: The option +@findex left @r{(destination option)} +@code{left} specifies horizontal position (default is empty, meaning +current position). + +Example: @code{\hldest@{fitv@}@{@}@{dest123@}} + +@item fitb +@findex fitb @r{(destination type)} +Fit the page's bounding box to the window. + +Example: @code{\hldest@{fitb@}@{@}@{dest123@}} + +@item fitbh +@findex fitbh @r{(destination type)} +Fit the width of the page's bounding box to the window. + +For @code{dvipdfm}: the option +@findex top @r{(destination option)} +@code{top} specifies vertical position (default is empty, meaning +current position). + +Example: @code{\hldest@{fitbh@}@{@}@{dest123@}} + +@item fitbv +@findex fitbv @r{(destination type)} +Fit the height of the page's bounding box to the window. + +For @code{dvipdfm}: the option +@findex left @r{(destination option)} +@code{left} specifies horizontal position (default is empty, meaning +current position). + +Example: @code{\hldest@{fitbv@}@{@}@{dest123@}} + +@item fitr +@findex fitr @r{(destination type)} +For @code{pdftex}: fit the rectangle specified by the options +@findex width @r{(destination option)} +@code{width}, +@findex height @r{(destination option)} +@code{height} and +@findex depth @r{(destination option)} +@code{depth} (as a @TeX{} rule specification) in the window. For +dimensions set to empty, the corresponding value of the parent box is +used (these are the defaults). + +For @code{dvipdfm}: fit the rectangle specified by the options +@findex left @r{(destination option)} +@code{left}, +@findex bottom @r{(destination option)} +@code{bottom}, +@findex right @r{(destination option)} +@code{right} and +@findex top @r{(destination option)} +@code{top} (in +@cindex PostScript point +PostScript points, 72@tie{}points per inch) in the window. For +dimensions set to empty, current position coordinate is substituted +(these are the defaults). + +Example for @code{pdftex}: + +@example +\hldest@{fitr@}@{width=\hsize,height=.5\vsize,depth=0pt@}@{dest123@} +@end example + +Example for @code{dvipdfm}: + +@example +\hldest@{fitr@}@{left=72,bottom=72,right=720,top=360@}@{dest123@} +@end example + +@item raw +@findex raw @r{(destination type)} +The destination specification (in the form of a pdf@TeX{} command or a +dvipdfm @code{\special}) is taken from the command sequence +@code{\@var{cs}}, where @var{cs} is the value of the +@findex cmd @r{(destination option)} +@code{cmd} option. In the definition of @code{\@var{cs}}, use +@findex @@hllabel +@code{\@@hllabel} to refer to the hyperlink label. This option is +intended to be used with destgroups (@pxref{Setting hyperlink types and +options}), as it does not make sense to use it in a direct call to +@findex hldest +@code{\hldest}---you can just call the raw command. + +Example for @code{pdftex}: + +@example +\makeatletter +\def\mydest@{\pdfdest name@{\@@hllabel@} xyz@} +\hldesttype@{raw@} +\hldestopts@{cmd=mydest@} +\resetatcatcode +@end example + +Example for @code{dvipdfm}: + +@example +\makeatletter +\def\mydest@{\special@{pdf: dest (\@@hllabel) + [@@thispage /XYZ @@xpos @@ypos 0]@}@} +\hldesttype@{raw@} +\hldestopts@{cmd=mydest@} +\resetatcatcode +@end example +@end table + + +@node Destination options for pdftex and dvipdfm +@subsubsection Destination options for @code{pdftex} and @code{dvipdfm} + +@cindex destination options, @code{pdftex} +@cindex destination options, @code{dvipdfm} +@cindex options, destination, @code{pdftex} +@cindex options, destination, @code{dvipdfm} +@cindex @code{pdftex}, destination options +@cindex @code{dvipdfm}, destination options +With respect to the destination options, the @code{pdftex} and +@code{dvipdfm} differ in the way the fit rectangle is specified +(relative coordinates for @code{pdftex}, absolute coordinates for +@code{dvipdfm}). + + +@subsubheading Common destination options + +@table @code +@item cmd +@findex cmd @r{(destination option)} +Name of the macro (without the leading @samp{\}) containing a +pdf@TeX{} command or a dvipdfm @code{\special} for the @code{raw} +destination. + +For an example of usage, @pxref{Destination types for pdftex and +dvipdfm}, description of the @code{raw} destination. + +@item zoom +@findex zoom @r{(destination option)} +@cindex destinations, magnification +@cindex hyperlink destination, magnification +@cindex magnification, hyperlink destination +@cindex zooming, hyperlink destination +Magnification ratio times 1000 (like @TeX{}'s scale factor). +Zero or empty means leave magnification unchanged, which is the +default. + +Example: @code{\hldest@{xyz@}@{zoom=2000@}@{dest123@}} +@end table + + +@subsubheading @code{pdftex}-specific destination options + +The dimension options below must be specified as a @TeX{} rule +specification. When set to empty, the corresponding value +of the parent box is used (this is the default for all dimension +options). + +@table @code +@item depth +@findex depth @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Depth of the fit rectangle for the @code{fitr} destination. + +@item height +@findex height @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Height of the fit rectangle for the @code{fitr} destination. + +@item width +@findex width @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Width of the fit rectangle for the @code{fitr} destination. + +Example: + +@example +\hldest@{fitr@}@{width=\hsize,height=.5\vsize,depth=0pt@}@{dest123@} +@end example +@end table + + +@subsubheading @code{dvipdfm}-specific destination options + +The dimension options below must be specified in +@cindex PostScript point +PostScript points (72@tie{}points per inch), as a number without the +@samp{bp} unit name. When set to empty, the current position +coordinate is used (this is the default for all dimension options). + +@table @code +@item bottom +@findex bottom @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Bottom position coordinate of a box specification for the various +destination types. + +@item left +@findex left @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Left position coordinate of a box specification for the various +destination types. + +@item right +@findex right @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Right position coordinate of a box specification for the various +destination types. + +@item top +@findex top @r{(destination option)} +@cindex destinations, dimensions +@cindex hyperlink destination, dimensions +@cindex dimensions, hyperlink destination +Top position coordinate of a box specification for the various +destination types. + +Example: + +@example +\hldest@{fitr@}@{left=72,bottom=72,right=720,top=360@}@{dest123@} +@end example +@end table + + +@node Link types for pdftex and dvipdfm +@subsubsection Link types for @code{pdftex} and @code{dvipdfm} + +@cindex link types, @code{pdftex} +@cindex link types, @code{dvipdfm} +@cindex types, link, @code{pdftex} +@cindex types, link, @code{dvipdfm} +@cindex @code{pdftex}, link types +@cindex @code{dvipdfm}, link types +Link types are the same for the @code{pdftex} and @code{dvipdfm} +drivers, except that the @code{pdftex} driver provides one additional +link type @code{num} (link to a numbered destination). dvipdfm does not +support numbered destinations, therefore it does not have this link +type. Note that all destinations created by Eplain hyperlink macros are +named destinations; to define a numbered destination, you have to use +low-level pdf@TeX{} commands. + + +@subsubheading Common link types + +@table @code +@item name +@findex name @r{(hyperlink type)} +@cindex named destination +@cindex destinations, named +@cindex hyperlink destination, named +Go to a ``named destination''. The label is the destination name. +All destinations created with @code{\hldest} are named destinations. +This is the default type. + +Example: @code{\hlstart@{name@}@{@}@{dest123@}Link to dest123\hlend} + +@item page +@findex page @r{(hyperlink type)} +@cindex page destination +@cindex destinations, page +@cindex hyperlink destination, page +Go to a page. The label is the page number (counting from@tie{}1). +Page fitting is specified by the +@findex pagefit @r{(hyperlink option)} +@code{pagefit} option. + +Example: + +@example +\hlstart@{page@}@{pagefit=/FitH 600@}@{123@}Link to page~123\hlend +@end example + +@item filename +@findex filename @r{(hyperlink type)} +@cindex file, hyperlink to +@cindex destinations, in another file +@cindex hyperlinks, to another file +Go to a named destination in another file. The label is the +destination name. The file name is specified by the +@findex file @r{(hyperlink option)} +@code{file} option. Page fitting is specified by the +@findex pagefit @r{(hyperlink option)} +@code{pagefit} option. The +@findex newwin @r{(hyperlink option)} +@code{newwin} option specifies whether the destination document is +opened in the same window or in a new window. + +Example: +@example +\hlstart@{filename@}@{file=book.pdf,newwin=1@}@{dest123@} + Link to dest123 in file `book.pdf'\hlend +@end example + +@item filepage +@findex filepage @r{(hyperlink type)} +@cindex file, hyperlink to +@cindex destinations, in another file +@cindex hyperlinks, to another file +Go to a page in another file. The label is the page number (counting +from@tie{}1). The file name is specified by the +@findex file @r{(hyperlink option)} +@code{file} option. Page fitting is specified by the +@findex pagefit @r{(hyperlink option)} +@code{pagefit} option. The +@findex newwin @r{(hyperlink option)} +@code{newwin} option specifies whether the destination document is +opened in the same window or in a new window. + +Example: +@example +\hlstart@{filepage@}@{file=book.pdf,newwin=,% + pagefit=/FitR 50 100 300 500@}@{1@} + Link to page~1 in file `book.pdf'\hlend +@end example + +@item url +@findex url @r{(hyperlink type)} +@cindex URL hyperlink +@cindex destinations, URL +@cindex hyperlinks, URL +Go to a URL. The label is the URL. + +Example: @code{\hlstart@{url@}@{@}@{http://tug.org/eplain/@}Eplain home\hlend} + +@item raw +@findex raw @r{(hyperlink type)} +The link specification (in the form of a pdf@TeX{} command or a dvipdfm +@code{\special} primitive) is taken from the command sequence +@code{\@var{cs}}, where @var{cs} is the value of the +@findex cmd @r{(hyperlink option)} +@code{cmd} option. This option is intended to be used with linkgroups +(@pxref{Setting hyperlink types and options}), as it does not make sense +to use it in a direct call to +@findex hlstart +@code{\hlstart}---you can just call the raw command. + +Example for @code{pdftex}: + +@example +% Redirect all \url links to the first page +\def\mycmd@{\pdfstartlink goto page 1 @{/Fit@}@} +\hltype[url]@{raw@} +\hlopts[url]@{cmd=mycmd@} +@end example + +Example for @code{dvipdfm}: + +@example +% Redirect all \url links to the first page +\def\mycmd@{\special@{pdf: beginann <>@}@} +\hltype[url]@{raw@} +\hlopts[url]@{cmd=mycmd@} +@end example +@end table + +@subsubheading @code{pdftex}-specific link types + +@table @code +@item num +@findex num @r{(hyperlink type)} +@cindex numbered destination +@cindex destinations, numbered +@cindex hyperlink destination, numbered +Go to a ``numbered destination''. The label is the destination +number. + +Example: @code{\hlstart@{num@}@{@}@{123@}Link to 123\hlend} +@end table + + +@node Link options for pdftex and dvipdfm +@subsubsection Link options for @code{pdftex} and @code{dvipdfm} + +@cindex link options, @code{pdftex} +@cindex link options, @code{dvipdfm} +@cindex options, link, @code{pdftex} +@cindex options, link, @code{dvipdfm} +@cindex @code{pdftex}, link options +@cindex @code{dvipdfm}, link options +Link options are mostly the same for the @code{pdftex} and +@code{dvipdfm} drivers. The @code{pdftex} driver has additional +options to specify link dimensions. + + +@subsubheading Common link options + +@table @code +@item bcolor +@findex bcolor @r{(hyperlink option)} +@cindex hyperlink border color +@cindex border color, hyperlink +@cindex color, hyperlink border +Border color. An array of three numbers in the range 0 to 1, +representing a color in DeviceRGB@. + +Example: @code{\hlstart@{name@}@{bcolor=.1 .5 1@}@{dest123@}Link\hlend} + +@item bdash +@findex bdash @r{(hyperlink option)} +@cindex dashed hyperlink border +@cindex hyperlinks, border style +@cindex border style, hyperlink +Array of numbers representing on and off stroke lengths for drawing +dashes. + +Example: @code{\hlstart@{name@}@{bstyle=D,bdash=2 4@}@{dest123@}Link\hlend} + +@item bstyle +@findex bstyle @r{(hyperlink option)} +@cindex solid hyperlink border +@cindex dashed hyperlink border +@cindex beveled hyperlink border +@cindex inset hyperlink border +@cindex underline hyperlink border +@cindex hyperlinks, border style +@cindex style, hyperlink border +@cindex border style, hyperlink +Link border style: + +@table @code +@item S +The border is drawn as a solid line. + +@item D +The border is drawn with a dashed line (the dash pattern is specified +by the +@findex bdash @r{(hyperlink option)} +@code{bdash} option). + +@item B +The border is drawn in a beveled style. + +@item I +The border is drawn in an inset style. + +@item U +The border is drawn as a line on the bottom of the link rectangle. +@end table + +The default is @samp{S}. + +Example: @code{\hlstart@{name@}@{bstyle=D,bdash=2 4@}@{dest123@}Link\hlend} + +@item bwidth +@findex bwidth @r{(hyperlink option)} +@cindex width, hyperlink border +@cindex hyperlinks, border width +@cindex border width, hyperlink +Border width in +@cindex PostScript point +PostScript points (72@tie{}points per inch). The default is@tie{}1. + +Example: @code{\hlstart@{name@}@{bwidth=2@}@{dest123@}Link\hlend} + +@item cmd +@findex cmd @r{(hyperlink option)} +Name of the macro (without the leading @samp{\}) containing a +pdf@TeX{} command or a dvipdfm @code{\special} for the @code{raw} link. + +For an example of usage, @pxref{Link types for pdftex and dvipdfm}, +description of the @code{raw} link. + +@item file +@findex file @r{(hyperlink option)} +File name for the @code{filename} and @code{filepage} link types. + +For an example of usage, @pxref{Link types for pdftex and dvipdfm}, +description of the @code{filename} and @code{filepage} links. + +@item hlight +@findex hlight @r{(hyperlink option)} +@cindex hyperlinks, highlight mode +@cindex highlight modes, hyperlink +Link border highlight modes: + +@table @code +@item I +The rectangle specified by the bounding box of the link is inverted. + +@item N +No highlighting is done. + +@item O +The border of the link is inverted. + +@item P +The region underneath the bounding box of the link is drawn inset into +the page. +@end table + +The default is @samp{I}. + +Example: @code{\hlstart@{name@}@{bstyle=S,hlight=O@}@{dest123@}Link\hlend} + +@item newwin +@findex newwin @r{(hyperlink option)} +@cindex hyperlinks, opening in a new window +@cindex new window, opening hyperlink in +For the @code{filename} and @code{filepage} links, specifies whether the destination document is +opened in the same window or in a new window. The settings are: + +@table @code +@item 0 +Open in the same window. +@item @r{non-}0 +Open in a new window. +@item @r{empty} +Behavior according to the viewer settings. +@end table + +The default is empty. + +For an example of usage, @pxref{Link types for pdftex and dvipdfm}, +description of the @code{filename} and @code{filepage} links. + +@item pagefit +@findex pagefit @r{(hyperlink option)} +For the @code{page} and @code{filepage links}, specifies how the page +must be fitted to the window. @code{pagefit} specification is written +to the PDF file as is, so it must conform to the PDF standard. + +For an example of usage, @pxref{Link types for pdftex and dvipdfm}, +description of the @code{page} and @code{filepage} links. +@end table + + +@subsubheading @code{pdftex}-specific link options + +The dimension options below must be specified as a @TeX{} rule +specification. When set to empty, the corresponding value +of the parent box is used (this is the default for all dimension +options). + +@table @code +@item depth +@findex depth @r{(hyperlink option)} +@cindex hyperlink dimensions +@cindex dimensions, hyperlink +Depth of the link. + +@item height +@findex height @r{(hyperlink option)} +@cindex hyperlink dimensions +@cindex dimensions, hyperlink +Height of the link. + +@item width +@findex width @r{(hyperlink option)} +@cindex hyperlink dimensions +@cindex dimensions, hyperlink +Width of the link. + +Example: + +@example +\hlstart@{name@}@{width=5in,height=20pc,depth=0pt@}@{dest123@} + Link\hlend +@end example +@end table + + +@node Hyperlink driver nolinks +@subsection Hyperlink driver @code{nolinks} + +@cindex @code{nolinks}, hyperlink driver +@cindex driver @code{nolinks} +@cindex hyperlink driver @code{nolinks} +@cindex omitting hyperlinks +@cindex disabling hyperlinks +@cindex hyperlinks, disabling +@cindex destinations, disabling +@cindex spacing, preserving with hyperlinks +@cindex hyperlinks, preserving spacing +@cindex page-breaking, preserving with hyperlinks +@cindex hyperlinks, preserving page-breaking +Select this driver to suppress all hyperlinks in your document. + +Selecting this driver is quite different from not selecting any driver +at all, or from selecting some driver and then turning hyperlinks off +for the entire document with +@findex hloff +@code{\hloff} and +@findex hldestoff +@code{\hldestoff} (@pxref{Turning hyperlinks on/off}). + +The purpose of @code{\hldestoff} and @code{\hloff} is to mark (parts) of +your document where hyperlinks should never appear. (Imagine you want +to prevent a cross-referencing macro from generating a link at a certain +spot in your document.) + +If instead you have prepared a document with hyperlinks and just want to +compile a version without them, it is better to select the driver +@code{nolinks}. This ensures that spacing and page-breaking are the +same as what you were getting with hyperlinks enabled. + +The reason for this is that hyperlinks are produced by the +@code{\special} primitives or low-level hyperlink commands. Each such +command is placed inside a +@cindex whatsits, made by hyperlinks +@dfn{whatsit} (an internal @TeX{} object), which may introduce +legitimate breakpoints at places where none would exist without the +whatsits. The macros @code{\hldestoff} and @code{\hloff} disable the +hyperlink macros completely, so that no whatsits are produced. + +In contrast, the @code{nolinks} driver does not completely disable +hyperlink macros. Instead, it defines them to merely write to the log +file (what gets written is unimportant). This also produces +whatsits, thus imitating the whatsits from the hyperlink commands. +(This trick was borrowed from the +@pindex color.sty +@cindex graphics collection, @LaTeX{} +@cindex @LaTeX{} graphics collection +@LaTeX{} `color' package.) + +Another reason for using @code{nolinks} is that in horizontal mode +@code{\hldest} places destinations inside boxes of zero width, height, +and depth. When you say @code{\hldestoff}, @code{\hldest} will omit +both destination definitions and these boxes. The missing boxes can +again cause the typesetting to be inconsistent with that with +destinations enabled. Here again, the @code{nolinks} driver helps by +defining @code{\hldest} to produce the empty boxes. + + +@node Setting hyperlink types and options +@section Setting hyperlink types and options + +@cindex default hyperlink type +@cindex default hyperlink options +@cindex hyperlinks, default type +@cindex hyperlinks, default options +@cindex destinations, default type +@cindex destinations, default options +You can define default types for links and destinations, which will be +used when you do not specify a type in +@findex hlstart +@code{\hlstart} or +@findex hldest +@code{\hldest}. Similarly, you can define default values for the +options; the default value for an option is used when you do not set the +option in the argument to @code{\hlstart} or @code{\hldest}. + +@cindex group, type hyperlink +@cindex group, options hyperlink +@cindex hyperlinks, group type +@cindex hyperlinks, group options +@cindex link, group type +@cindex link, group options +@cindex linkgroup, type +@cindex linkgroup, options +@cindex destinations, group type +@cindex destinations, group options +@cindex destgroup, type +@cindex destgroup, options +The parameters for implicit links and destinations can be customized by +setting the ``group'' types and options. When not set, the defaults are +used. + +All these settings are local to the current (@TeX{}) group, so if +you want to set an option temporarily, you can do so inside a +@code{\begingroup@dots{}\endgroup} block; when the group ends, the +previous settings are restored. + +@menu +* Setting default types and options:: +* Setting group types:: +* Setting group options:: +@end menu + + +@node Setting default types and options +@subsection Setting default types and options + +@findex hltype +@findex hldesttype +The default types for links and destinations can be set with the +following commands: + +@example +\hltype@{@var{type}@} +\hldesttype@{@var{type}@} +@end example + +@noindent where @var{type} is one of the +link/destination types supported by the selected hyperlink driver +(@pxref{Hyperlink drivers}). + +@findex hlopts +@findex hldestopts +Default values for the options can be set with the following commands: + +@example +\hlopts@{@var{options}@} +\hldestopts@{@var{options}@} +@end example + +@noindent where @var{options} is a comma-separated list of option +assignments in the format @samp{@var{option}=@var{value}}. Again, what options +are allowed depends on the selected hyperlink driver. + + +@node Setting group types +@subsection Setting group types + +@findex hltype +@findex hldesttype +@cindex group, type hyperlink +@cindex hyperlinks, group type +@cindex link, group type +@cindex linkgroup, type +@cindex destinations, group type +@cindex destgroup, type +When called with an optional argument, as in + +@example +\hltype[@var{groups}]@{@var{type}@} +\hldesttype[@var{groups}]@{@var{type}@} +@end example + +@noindent where @var{groups} is a comma-separated list of groups, +@code{\hltype} and @code{\hldesttype} set the type for each group from +@var{groups} to @var{type}. The default type is used for all groups +with an empty type (this is the initial setting for all groups, except +that the type for the `url' linkgroup is set to @samp{url} by the +drivers which support this link type). + +@cindex group `' (empty) +@cindex default hyperlink type +@cindex default hyperlink options +@cindex hyperlinks, default type +@cindex hyperlinks, default options +@cindex destinations, default type +@cindex destinations, default options +There are two special ``groups'' which can be used inside the +@var{groups} list. An empty group sets the default type. This allows +to set the default type and group types in one command, for example: + +@example +\hltype[eq,]@{@var{type}@} +@end example + +@noindent sets the link type for the `eq' linkgroup and the +default link type to @var{type}. + +@cindex group `*' +@cindex groups, specifying all +@cindex all groups, specifying +Another special group is a star (@samp{*}) group, which signifies all +defined groups. For example, the command + +@example +\hldesttype[*,]@{@var{type}@} +@end example + +@noindent sets the destination type to @var{type} for each group, +as well as the default destination type. + + +@node Setting group options +@subsection Setting group options + +@cindex group, options hyperlink +@cindex hyperlinks, group options +@cindex link, group options +@cindex linkgroup, options +@cindex destinations, group options +@cindex destgroup, options +Option values for each group are stored as a list of option +assignments. This list does not have to contain every supported +option. Values for options missing from this list are taken from the +default option values. + +@findex hlopts +@findex hldestopts +To manipulate the list of option values for the groups, you use the +@code{\hlopts} and @code{\hldestopts} commands with an optional +argument: + +@example +\hlopts[@var{groups}]@{@var{options}@} +\hldestopts[@var{groups}]@{@var{options}@} +\hlopts![@var{groups}]@{@var{options}@} +\hldestopts![@var{groups}]@{@var{options}@} +@end example + +@noindent where @var{groups} is a comma-separated list of groups and +@var{options} is a comma-separated list of option assignments. The +two special ``groups'', the empty group and the star (@samp{*}) +group, have the same meaning as for @code{\hltype} and +@code{\hldesttype}. +@cindex group, preserving option list +@cindex hyperlink group, preserving option list +@cindex option list, preserving for group +When used without the exclamation mark, @code{\hlopts} and +@code{\hldestopts} preserve the current list of options for the groups, +and only update the options listed in @var{options}. If you add the +exclamation mark, the current list of options for each group in +@var{groups} is discarded and the new list is set to @var{options}. + +The ``overriding'' nature of the @samp{!} is appropriate when you give +a complete specification of the options for a group, e.g., at the +beginning of your document. On the other hand, when you want to +adjust some option(s) and leave others intact, you should use the +macros without the @samp{!}. + +@findex raise @r{(hyperlink option)} +@cindex mathematics displays, hyperlinks +@cindex displayed math and hyperlinks +@cindex large operators and hyperlinks +@cindex hyperlinks, large operators +@cindex destinations, large operators +@cindex raising hyperlink destinations +For example, with displayed mathematical formulas, you often need to +adjust the @samp{raise} option for the +@cindex group `eq' +@cindex linkgroup `eq' +`eq' destgroup, because the formulas often contain large parentheses and +brackets. But when doing so, you want to leave the other settings +unchanged. To achieve this, call @code{\hldestopts} without the +@samp{!}, for example: + +@example +$$\hldestopts[eq]@{raise=2.5\normalbaselineskip@} +@dots{} +$$ +@end example + +@noindent The display commands (@samp{$$}) implicitly put the entire +formula inside a (@TeX{}) group (@code{\begingroup@dots{}\endgroup}), so +you do not need to isolate the setting of the @samp{raise} option---it +will be restored after the closing @samp{$$}. + +@cindex option list, group +@cindex group option list +@cindex hyperlinks, group option list +Initially, Eplain sets the option lists for almost all groups to empty, +so that the groups fall back on the default values for all options. The +one exception to this rule is the `eq' destgroup, whose initial option +list contains one setting: + +@example +raise=1.7\normalbaselineskip +@end example + +@noindent This setting usually accommodates the large operators, which often +appear in displayed math. + + +@node Turning hyperlinks on/off +@section Turning hyperlinks on/off + +@cindex omitting hyperlinks +@cindex disabling hyperlinks +@cindex hyperlinks, disabling +@cindex destinations, disabling +Links and/or destinations can be turned on or off globally by disabling +the low-level commands, or for each group individually. + +All these settings are local to the current (@TeX{}) group, so if you +want to enable or disable links/destinations temporarily, you can do so +inside a @code{\begingroup@dots{}\endgroup} block; when the group ends, the +previous settings are restored. + +@menu +* Turning low-level commands on/off:: +* Turning hyperlinks on/off for a group:: +@end menu + + +@node Turning low-level commands on/off +@subsection Turning low-level commands on/off + +@findex hldeston +@findex hldestoff +@findex hlon +@findex hloff +The low-level commands @code{\hlstart}, @code{\hlend} and +@code{\hldest} can be turned on/off with the following commands: + +@example +\hldeston +\hldestoff +\hlon +\hloff +@end example + +@noindent @xref{Hyperlink driver nolinks}, for the implications of using +these commands to disable hyperlinks for the entire document. + + +@node Turning hyperlinks on/off for a group +@subsection Turning hyperlinks on/off for a group + +@cindex group, disabling hyperlinks +@cindex hyperlink group, disabling hyperlinks +If you want to disable links/destinations produced by certain groups, +you can give a list of the groups as an optional argument to these +commands: + +@example +\hldeston[@var{groups}] +\hldestoff[@var{groups}] +\hlon[@var{groups}] +\hloff[@var{groups}] +@end example + +@noindent where @var{groups} is the list of linkgroups/destgroups. This +list can contain two special groups. The empty group switches the +low-level commands (@pxref{Turning low-level commands on/off}), and the +star (@samp{*}) group operates on all defined groups. + +Note that turning off the low-level commands disables all hyperlinks +globally, including groups which have them enabled. Turning off certain +linkgroups/destgroups records the fact that the macros in the group +should not produce links/destinations. To illustrate the distinction, +assume that all links are on; after the following sequence of commands: + +@example +\hloff +\hloff[eq] +\hlon +@end example + +@noindent all links are on except for the `eq' linkgroup. diff --git a/Master/texmf-dist/doc/eplain/base/index.texi b/Master/texmf-dist/doc/eplain/base/index.texi new file mode 100644 index 00000000000..7543633094d --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/index.texi @@ -0,0 +1,7 @@ +@c Public domain. + +@c makeinfo complains about bad links if we make them implicit. Strange. +@node Concept index, , Macro index, Top +@unnumbered Concept index + +@printindex cp diff --git a/Master/texmf-dist/doc/eplain/base/install.texi b/Master/texmf-dist/doc/eplain/base/install.texi new file mode 100644 index 00000000000..10cc42057ef --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/install.texi @@ -0,0 +1,65 @@ +@c This is part of the Eplain manual. Public domain. + +@node Installation +@chapter Installation + +@cindex Eplain, installing +@ @cindex installation +The simplest way to install Eplain is simply to install the file +@file{eplain.tex} in a directory where @TeX{} will find it. What that +directory is obviously depends on your operating system and @TeX{} +installation. I personally install @file{eplain.tex} in +a directory @file{/usr/local/lib/texmf/tex/plain}. + +If you want, you can also create a format (@file{.fmt}) +@pindex .fmt @r{file} +@cindex format file +file for Eplain, which will eliminate the time spent reading the macro +source file with @code{\input}. You do this by issuing a sequence of +Unix commands something like this: + +@example +prompt$ touch eplain.aux +prompt$ initex +This is TeX, ... +**&plain eplain +(eplain.tex) +*\dump +... @var{messages} ... +@end example + +@pindex eplain.aux +@cindex undefined labels, warnings about +@noindent You must make sure that @file{eplain.aux} exists @emph{before} you +run @file{initex}; otherwise, warning messages about undefined labels +will never be issued. + +You then have to install the resulting @file{eplain.fmt} in some system +directory or set an environment variable to tell @TeX{} how to find it. +I install the format files in @file{/usr/local/lib/texmf/ini}; the +environment variable for the Web2C port of @TeX{} to Unix is +@code{TEXFORMATS}. + +Some implementations of @TeX{} (including Web2C) use the name by which +@TeX{} is invoked to determine what format to read. For them, you +should make a link to the @file{virtex} program named @file{etex}, and +then install the format file with the name @file{etex.fmt}. This lets +users invoke @TeX{} as @file{etex} and get the format file read +automatically, without having to say @samp{&eplain}. + +For convenience, the file @file{etex.tex} in the distribution directory +does @code{\input eplain} and then @code{\dump}, so that if you replace +@samp{eplain} with @samp{etex} in the example above, the format file +will end up with the right name. + +The @code{install} target in the @file{Makefile} does all this properly +for Unix systems and Web2C. You may have to change the pathnames. + +@cindex emtex, installation under +Under emtex, @samp{eaj@@acpub.duke.edu} says that + +@example +tex386 -i ^&plain eplain \dump +@end example + +@noindent produces a format file. diff --git a/Master/texmf-dist/doc/eplain/base/intro.texi b/Master/texmf-dist/doc/eplain/base/intro.texi new file mode 100644 index 00000000000..00ccc5ad313 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/intro.texi @@ -0,0 +1,71 @@ +@c This is part of the Eplain manual. Public domain. + +@node Introduction +@chapter Introduction + +@cindex Eplain, purpose of + +@pindex xeplain.tex +The @dfn{Eplain} macro package expands on and extends the definitions in +plain @TeX{}. This manual describes the definitions that you, as either +an author or a macro writer, might like to use. It doesn't discuss the +implementation; see comments in the source code (@file{xeplain.tex}) for +that. + +Eplain is not intended to provide ``generic'' typesetting capabilities, as +do @LaTeX{} (written by Leslie Lamport) +@cindex @LaTeX{} +@cindex Lamport, Leslie +or Texinfo +@cindex Texinfo +(written by Richard Stallman and others). +@cindex Stallman, Richard +@cindex rms +Instead, it provides definitions that are intended to be useful +regardless of the high-level commands that you use when you actually +prepare your manuscript. + +For example, Eplain does not have a command @code{\section}, which +would format section headings in an ``appropriate'' way, such as +@LaTeX{}'s @code{\section}. The philosophy of Eplain is +that some people will always need or want to go beyond the macro +designer's idea of ``appropriate''. Such canned macros are +fine---as long as you are willing to accept the resulting output. If +you don't like the results, or if you are trying to match a different +format, you are out of luck. + +On the other hand, almost everyone would like capabilities such as +cross-referencing by labels, so that you don't have to put actual page +numbers in the manuscript. The author of Eplain +@cindex Berry, Karl +is not aware of any generally available macro packages that (1)@tie{}do +not force their typographic style on an author, and yet (2)@tie{}provide +such capabilities. + +Besides such generic macros as cross-referencing, Eplain +contains another set of definitions: ones that change the conventions of +plain @TeX{}'s output. For example, math displays in @TeX{} are, by +default, centered. If you want your displays to come out +left-justified, you have to plow through @cite{The @TeX{}book} to find +some way to do it, and then adapt the code to your own needs. Eplain +tries to take care of the messy details of such things, while still +leaving the detailed appearance of the output up to you. + +Finally, numerous definitions turned out to be useful as Eplain was +developed. They are also documented in this manual, on the chance that +people writing other macros will be able to use them. + +You can send bug reports or suggestions to +@email{tex-eplain@@tug.org}. The current version number of Eplain is +defined as the macro @code{\fmtversion} +@cindex version number +@findex fmtversion +at the end of the source file @file{eplain.tex}. When corresponding, +please refer to it. + +To get on this mailing list yourself, email +@email{tex-eplain-request@@tug.org} with a message whose body contains +a line +@example +subscribe @var{you@@your.preferred.address} +@end example diff --git a/Master/texmf-dist/doc/eplain/base/invoke.texi b/Master/texmf-dist/doc/eplain/base/invoke.texi new file mode 100644 index 00000000000..b412c64a57b --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/invoke.texi @@ -0,0 +1,144 @@ +@c This is part of the Eplain manual. Public domain. + +@node Invoking Eplain +@chapter Invoking Eplain + +@cindex Eplain, invoking +The simplest way to use Eplain is simply to put: + +@example +\input eplain +@end example + +@noindent at the beginning of your input file. The macro file is small +enough that reading it does not take an unbearably long time---at least on +contemporary machines. + +In addition, if a format (@file{.fmt}) +@pindex .fmt @r{file} +file has been created for Eplain (see the previous section), you can +eliminate the time spent reading the macro source file. You do this +by responding @code{&eplain} to @TeX{}'s @samp{**} prompt. For +example: + +@example +initex +This is TeX, ... +**&eplain myfile +@end example + +Depending on the implementation of @TeX{} which you are using, you might +also be able to invoke @TeX{} as @file{eplain} and have the format file +automatically read. + +If you write something which you will be distributing to others, you +won't know if the Eplain format will be loaded already. If it is, then +doing @code{\input eplain} will waste time; if it isn't, then you must +load it. To solve this, Eplain defines the control sequence +@code{\eplain} +@findex eplain +to be the letter @code{t} (a convention borrowed from Lisp; it doesn't +actually matter what the definition is, only that the definition +exists). Therefore, you can do the following: +@example +\ifx\eplain\undefined \input eplain \fi +@end example +@noindent where @code{\undefined} must never acquire a definition. + +Eplain consists of several source files: +@table @file +@item xeplain.tex +most of the macros; + +@item arrow.tex +commutative diagram macros (@pxref{Arrow theoretic diagrams}), written by +Steven Smith; + +@item btxmac.tex +bibliography-related macros (@pxref{Citations}); + +@item ifpdf.sty +sets the switch @code{\ifpdf}, which can be used to +detect pdf@TeX{} in PDF mode (@pxref{Checking for PDF output}), written +by Heiko Oberdiek; + +@item path.sty +macro for allowing line breaks at punctuation characters within long +pathnames, electronic mail addresses, etc., (@pxref{Paths}), written +by Philip Taylor; + +@item texnames.sty +abbreviations for various @TeX{}-related names (@pxref{Logos}), edited +by Nelson Beebe. + +@end table + +@noindent The file @file{eplain.tex} is all of these files merged +together, with comments removed. + +All of these files except @file{xeplain.tex} can be input individually, +if all you want are the definitions in that file. + +Also, since the bibliography macros are fairly extensive, you might not +want to load them, to conserve @TeX{}'s memory. Therefore, if the +control sequence @code{\nobibtex} +@findex nobibtex +is defined, then the bibliography definitions are skipped. You must set +@code{\nobibtex} before @file{eplain.tex} is read, naturally. For +example, you could start your input file like this: + +@example +\let\nobibtex = t +\input eplain +@end example + +By default, @code{\nobibtex} is undefined, and so the bibliography +definitions @emph{are} made. + +@findex noarrow +Likewise, define @code{\noarrow} if you don't want to include the +commutative diagram macros from @file{arrow.tex}, perhaps because you +already have conflicting ones. + +If you don't want to read or write an @file{aux} file at all, for any +kind of cross-referencing, define @code{\noauxfile} +@findex noauxfile +before reading @file{eplain.tex}. This also turns off all warnings +about undefined labels. + +@pindex amsppt.sty +@cindex AMS@TeX{} conflicts +Eplain conflicts with AMS@TeX{} (to be precise, with @file{amsppt.sty}): +the macros @code{\cite} and @code{\ref} are defined by both. + +If you want to use AMS@TeX{}'s @code{\cite}, the solution is to define +@code{\nobibtex} before reading Eplain, as described above. + +If you have @file{amsppt.sty} loaded and use @code{\ref}, Eplain writes +a warning on your terminal. If you want to use the AMS@TeX{} +@code{\ref}, do @code{\let\ref = \amsref} after reading Eplain. +To avoid the warning, do @code{\let\ref = \eplainref} after reading +Eplain and before using @code{\ref}. + +@pindex texi2dvi +@pindex bibtex +@pindex makeindex +Sometimes you may need to run @TeX{} more then once on your +@file{.tex} file in order to produce and typeset indexes, resolve +undefined cross-references and/or citations. The shell script +@command{texi2dvi} from the Texinfo documentation system (see +@url{http://www.gnu.org/software/texinfo/}) can automate this process: +it runs Bib@TeX{}, MakeIndex and @TeX{} as many times as needed to +complete the compilation process. You will need to set the +@env{LATEX} environment variable to @samp{tex}. For example, in a +Bourne-compatible shell, the following command will do all the work: + +@example +prompt$ LATEX=tex texi2dvi file.tex +@end example + +@pindex pdftex +@noindent (Despite the name, @command{texi2dvi} can also produce +@file{.pdf} files; just set @samp{LATEX=pdftex}.) See the output from +the command @command{texi2dvi --help} for invoking information and a +full list of options. diff --git a/Master/texmf-dist/doc/eplain/base/progdef.texi b/Master/texmf-dist/doc/eplain/base/progdef.texi new file mode 100644 index 00000000000..4169f151730 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/progdef.texi @@ -0,0 +1,768 @@ +@c This is part of the Eplain manual. Public domain. + +@node Programming definitions +@chapter Programming definitions + +The definitions in this section are only likely to be useful when you +are writing nontrivial macros, not when writing a document. + +@menu +* Category codes:: Changing category codes. +* Allocation macros:: Non-outer versions of \newcount et al. +* Iteration:: Doing `for' loops in TeX. +* Macro arguments:: Reading and ignoring them. +* Converting to characters:: Normalizing control sequences and spaces. +* Expansion:: Controlling expansion. +* Obeying spaces:: Making whitespace count anywhere. +* Writing out numbers:: Making `1' into `one'. +* Mode-specific penalties:: +* Auxiliary files:: Testing for their existence. +* User-defined environments:: User-defined environments. +* Page list and page range parsers:: +@end menu + + +@node Category codes +@section Category codes + +@cindex category codes + +Plain @TeX{} defines @code{\active} (as the number 13) for use in +changing category codes. Although the author of @cite{The @TeX{}book} +@cindex Knuth, Donald Ervin +has ``intentionally kept the category codes numeric'', two other +categories are commonly used: letters (category code 11) and others +(12). Therefore, Eplain defines @code{\letter} and +@code{\other}. +@findex letter +@findex other + +Sometimes it is cleaner to make a character active without actually +@cindex active characters +writing a @code{\catcode} command. The @code{\makeactive} command takes +@findex catcode +@findex makeactive +a character as an argument to make active (and ignores following +spaces). For example, here are two commands which both make @kbd{\} +active: +@cindex backslash character + +@example +\makeactive`\\ \makeactive92 +@end example + +@cindex user-inaccessible macros +@cindex inaccessible macros +Sometimes you might want to temporarily change the category code of +the `@@' character to @code{\letter}, so that you can use or define +macros which are normally inaccessible to the user. For such +situations, Eplain provides the @code{\makeatletter} +@findex makeatletter +command. It sets the category code of `@@' to @code{\letter} (11) and +defines +@code{\resetatcatcode} +@findex resetatcatcode +to restore the category code to whatever it was before the call to +@code{\makeatletter}. For example: + +@example +\makeatletter +\def\@@hidden@@macro@{This macro cannot normally be + called / redefined by the user@} +\resetatcatcode +@end example + +@noindent There is also @code{\makeatother} +@findex makeatother +which works similarly but sets the category code of `@@' to +@code{\other} (12). + +Usually, when you give a definition to an active character, you have +to do so inside a group where you temporarily make the character active, +and then give it a global definition (cf.@: the definition of +@code{\obeyspaces} in @cite{The @TeX{}book}). +@cindex definitions, global +This is inconvenient if you are writing a long macro, or if the +character already has a global definition you do not wish to transcend. +Eplain provides @code{\letreturn}, which defines the usual end-of-line +@findex letreturn +@cindex return character +character to be the argument. For example: + +@example +\def\mymacro@{@dots{} \letreturn\myreturn @dots{} @} +\mymacro hello +there +@end example + +@noindent The end-of-line between @samp{hello} and @samp{there} causes +@code{\myreturn} to be expanded. + +@cite{The @TeX{}book} describes @code{\uncatcodespecials}, +@findex uncatcodespecials +which makes all characters which are normally ``special'' into ``other'' +characters, but the definition never made it into plain @TeX{}. +Eplain therefore defines it. + +Finally, @code{\percentchar} +@findex percentchar +expands into a literal `%' character. This is useful when you +@code{\write} @TeX{} output to a file, and want to avoid spurious +spaces. For example, Eplain writes a @code{\percentchar} after the +definition of cross-references. The macros @code{\lbracechar} +@findex lbracechar +and @code{\rbracechar} +@findex rbracechar +expand similarly. + + +@node Allocation macros +@section Allocation macros + +@cindex allocation macros +@cindex register allocation + +Plain @TeX{} provides macros that allocate registers of each primitive +type in @TeX{}, to prevent different sets of macros from using the same +register for two different things. The macros are all named starting +with @samp{new}, +@findex new@dots{} +e.g., @code{\newcount} allocates a new ``count'' +(integer) register. Such allocations are usually needed only at the top +level of some macro definition file; therefore, plain @TeX{} makes the +allocation registers @code{\outer}, +@findex outer +to help find errors. (The error this helps to find is a missing right +brace in some macro definition.) + +Sometimes, however, it is useful to allocate a register as part of +some macro. An outer control sequence cannot be used as part of a macro +definition (or in a few other contexts: the parameter text of a +definition, an argument to a definition, the preamble of an alignment, +or in conditional text that is being skipped). Therefore, Eplain +defines ``inner'' versions of all the allocation macros, named with the +prefix @samp{inner}: +@code{\innernewbox}, +@findex innernewbox +@code{\innernewcount}, +@findex innernewcount +@code{\innernewdimen}, +@findex innernewdimen +@code{\innernewfam}, +@findex innernewfam +@code{\innernewhelp}, +@findex innernewhelp +@code{\innernewif}, +@findex innernewif +@code{\innernewinsert}, +@findex innernewinsert +@code{\innernewlanguage}, +@findex innernewlanguage +@code{\innernewread},@* +@findex innernewread +@code{\innernewskip}, +@findex innernewskip +@code{\innernewtoks}, +@findex innernewtoks +@code{\innernewwrite}. +@findex innernewwrite + +You can also define non-outer versions of other macros in the same way +that Eplain defines the above. The basic macro is called +@code{\innerdef}: +@findex innerdef + +@example +\innerdef @var{\innername} @{@var{outername}@} +@end example + +The first argument (@var{\innername}) to @code{\innerdef} is the +control sequence that you want to define. Any previous definition of +@var{\innername} is replaced. The second argument +(@var{outername}) is the @emph{characters} in the name of the outer +control sequence. (You can't use the actual control sequence name, +since it's outer!) + +If the outer control sequence is named @var{\cs}, and you want to +define @code{inner@var{cs}} as the inner one, you can use +@code{\innerinnerdef}, +@findex innerinnerdef +which is just an abbreviation for a call to @code{\innerdef}. For +example, these two calls are equivalent: + +@example +\innerdef\innerproclaim@{proclaim@} +\innerinnerdef@{proclaim@} +@end example + + +@node Iteration +@section Iteration + +@cindex iteration +@cindex for loops + +You can iterate through a comma-separated list of items with +@code{\for}. +@findex for +Here is an example: + +@example +\for\name:=karl,kathy\do@{% + \message@{\name@}% +@}% +@end example + +This writes @samp{karl} and @samp{kathy} to the terminal. Spaces +before or after the commas in the list, or after the @code{:=}, are +@emph{not} ignored. + +@code{\for} expands the iterated values fully (with @code{\edef}), so +this is equivalent to the above: + +@example +\def\namelist@{karl,kathy@}% +\for\name:=\namelist\do @dots{} +@end example + + +@node Macro arguments +@section Macro arguments + +@cindex arguments, ignoring +@cindex ignoring arguments +@cindex gobbling arguments +It is occasionally useful to redefine a macro that takes arguments to +do nothing. Eplain defines @code{\gobble}, +@findex gobble +@code{\gobbletwo}, +@findex gobbletwo +and @code{\gobblethree} to swallow one, two, and three arguments, +respectively. + +For example, if you want to produce a ``short'' table of +@cindex table of contents, short +contents---one that includes only chapters, say---the easiest thing to +do is read the entire @code{.toc} file (@pxref{Contents}), and just +ignore the commands that produce section or subsection entries. To be +specific: + +@example +\let\tocchapterentry = \shorttocchapter +\let\tocsectionentry = \gobbletwo +\let\tocsubsectionentry = \gobbletwo +\readtocfile +@end example +@noindent (Of course, this assumes you only have chapters, sections, and +subsections in your document.) + +In addition, Eplain defines @code{\eattoken} +@findex eattoken +to swallow the single following token, using @code{\let}. Thus, +@code{\gobble} followed by @samp{@{@dots{}@}} ignores the entire +brace-enclosed text. @code{\eattoken} followed by the same ignores only +the opening left brace. + +Eplain defines a macro @code{\identity} +@findex identity +which takes one argument and expands to that argument. This may be +useful if you want to provide a function for the user to redefine, but +don't need to do anything by default. (For example, the default +definition of @code{\eqconstruct} (@pxref{Formatting equation +references}) is @code{\identity}.) + +You may also want to read an optional argument. The established +convention is that optional arguments are put in square brackets, so +that is the syntax Eplain recognizes. Eplain ignores space tokens +before an optional argument, via @code{\futurenonspacelet}. + +You test for an optional argument by using @code{\@@getoptionalarg}. +@c this confuses texinfo.tex: findex @@getoptionalarg +It takes one argument, a control sequence to expand after reading the +argument, if present. If an optional argument is present, the control +sequence @code{\@@optionalarg} expands to it; otherwise, +@code{\@@optionalarg} is @code{\empty}. You must therefore have the +category code of @kbd{@@} set to 11 (letter). Here is an example: + +@example +\catcode`@@=\letter +\def\cmd@{\@@getoptionalarg\finishcmd@} +\def\finishcmd@{% + \ifx\@@optionalarg\empty + % @r{No optional argument present.} + \else + % @r{One was present.} + \fi +@} +@end example + +If an optional argument contains another optional argument, the inner +one will need to be enclosed in braces, so @TeX{} does not mistake the +end of the first for the end of the second. + + +@node Converting to characters +@section Converting to characters + +@cindex characters, converting to +Eplain defines @code{\xrlabel} +@findex xrlabel +to produce control sequence names for cross-reference labels, et al. +This macro expands to its argument with an @samp{_} appended. (It does +this because the usual use of @code{\xrlabel} is to generate a control +sequence name, and we naturally want to avoid conflicts between control +sequence names.) + +Because @code{\xrlabel} is fully expandable, to make a control +sequence name out of the result you need only do +@example +@code{\csname \xrlabel@{@var{label}@}\endcsname} +@end example + +@noindent The @code{\csname} primitive makes a control sequence name out +of any sequence of character tokens, regardless of category code. +Labels can therefore include any characters except for @samp{\}, +@samp{@{}, @samp{@}}, and @samp{#}, all of which are used in macro +definitions themselves. + +@findex sanitize +@code{\sanitize} takes a control sequence as an argument and converts +the expansion of the control sequence into a list of character tokens. +This is the behavior you want when writing information like chapter +titles to an output file. For example, here is part of the definition +of @code{\writenumberedtocentry}; @code{#2} is the title that the user +has given. + +@example +@dots{} +\def\temp@{#2@}% +@dots{} + \write\tocfile@{% + @dots{} + \sanitize\temp + @dots{} + @}% +@end example + + +@node Expansion +@section Expansion + +This section describes some miscellanous macros for expansion, etc. + +@menu +* \csn and \ece:: Abbreviations for \csname expansions. +* \edefappend:: +* Hooks:: Manipulating and executing named actions. +* Properties:: Associating information with a csname. +* \expandonce:: +* \ifundefined:: +* \futurenonspacelet:: +@end menu + + +@node \csn and \ece +@subsection @code{\csn} and @code{\ece} + +@findex csn +@code{\csn}@{@var{name}@} simply abbreviates @code{\csname} @var{name} +@code{\endcsname}, thus saving some typing. The extra level of expansion +does take some time, though, so I don't recommend it for an inner loop. + +@findex ece +@code{\ece}@{@var{token}@}@{@var{name}@} abbreviates + +@example +\expandafter @var{token} \csname @var{name} \endcsname +@end example + +@noindent For example, + +@example +\def\fontabbrevdef#1#2@{\ece\def@{@@#1font@}@{#2@}@} +\fontabbrevdef@{normal@}@{ptmr@} +@end example + +@noindent defines a control sequence @code{\@@normalfont} to expand to +@code{ptmr}. + + +@node \edefappend +@subsection @code{\edefappend} + +@findex edefappend +@code{\edefappend} is a way of adding on to an existing definition. It +takes two arguments: the first is the control sequence name, the second +the new tokens to append to the definition. The second argument is +fully expanded (in the @code{\edef} that redefines the control sequence). + +For example: + +@example +\def\foo@{abc@} +\def\bar@{xyz@} +\edefappend\foo@{\bar karl@} +@end example + +@noindent results in @code{\foo} being defined as @samp{abcxyzkarl}. + + +@node Hooks +@subsection Hooks + +@cindex hooks +A @dfn{hook} is simply a name for a group of actions which is executed +in certain places---presumably when it is most useful to allow +customization or modification. @TeX{} already provides many builtin +hooks; for example, the @code{\every @dots{}} token lists are all +examples of hooks. + +Eplain provides several macros for adding actions to hooks. They all +take two arguments: the name of the hook and the new actions. + +@table @code + +@findex hookaction +@itemx hookaction @var{name} @var{actions} +@findex hookappend +@itemx hookappend @var{name} @var{actions} +@findex hookprepend +@item hookprepend @var{name} @var{actions} +Each of these adds @var{actions} to the hook @var{name}. (Any +previously-defined actions are retained.) @var{name} is not a control +sequence, but rather the characters of the name. + +@findex hookactiononce +@item hookactiononce @var{name} @code{\@var{cs}} +@code{\hookactiononce} adds @var{cs} to @var{name}, like the macros +above, but first it adds + +@example +\global\let @var{\cs} \relax +@end example + +@noindent to the definition of @var{\cs}. (This implies @var{\cs} must +be a true expandable macro, not a control sequence @code{\let} to a +primitive or some other such thing.) Thus, @var{\cs} is expanded the +next time the hook @var{name} is run, but it will disappear after that. + +The @code{\global} is useful because @code{\hookactiononce} is most +useful when the grouping structure of the @TeX{} code could be anything. +Neither this nor the other hook macros do global assignments to the hook +variable itself, so @TeX{}'s usual grouping rules apply. +@end table + +@findex hookrun +The companion macro to defining hook actions is @code{\hookrun}, for +running them. This takes a single argument, the name of the hook. If +no actions for the hook are defined, no error ensues. + +Here is a skeleton of general @code{\begin} and @code{\end} macros that +run hooks, and a couple of calls to define actions. The use of +@code{\hookprepend} for the begin action and @code{\hookappend} for the +end action ensures that the actions are executed in proper sequence with +other actions (as long as the other actions use @code{\hookprepend} and +@code{\hookappend} also). + +@example +\def\begin#1@{ @dots{} \hookrun@{begin@} @dots{} @} +\def\end#1@{ @dots{} \hookrun@{end@} @dots{} @} +\hookprepend@{begin@}\start_underline +\hookappend@{end@}\finish_underline +@end example + + +@node Properties +@subsection Properties + +@cindex properties +@cindex atom +A @dfn{property} is a name/value pair associated with another symbol, +traditionally called an @dfn{atom}. Both atom and property names are +control sequence names. + +Eplain provides two macros for dealing with property lists: +@code{\setproperty} and @code{\getproperty}. + +@table @code + +@findex setproperty +@item \setproperty @var{atom} @var{propname} @var{value} +@code{\setproperty} defines the property @var{property} on the atom +@var{atom} to be @var{value}. @var{atom} and @var{propname} can be +anything acceptable to @code{\csname}. @var{value} can be anything. + +@findex getproperty +@item \getproperty @var{atom} @var{propname} +@code{\getproperty} expands to the value stored for @var{propname} on +@var{atom}. If @var{propname} is undefined, it expands to nothing +(i.e., @code{\empty}). + +@end table + +The idea of properties originated in Lisp (I believe). There, the +implementation truly does associate properties with atoms. In @TeX{}, +where we have no builtin support for properties, the association is only +conceptual. + +The following example typesets @samp{xyz}. + +@example +\setproperty@{a@}@{pr@}@{xyz@} +\getproperty@{a@}@{pr@} +@end example + + +@node \expandonce +@subsection @code{\expandonce} + +@cindex expansion, one-level +@findex expandonce +@code{\expandonce} is defined as @code{\expandafter\noexpand}. Thus, +@code{\expandonce @var{token}} expands @var{token} once, instead of to +@TeX{} primitives. This is most useful in an @code{\edef}. + +For example, the following defines @code{\temp} to be @code{\foo}, not +@samp{abc}. + +@example +\def\foo@{abc@} +\def\bar@{\foo@} +\edef\temp@{\expandonce\bar@} +@end example + + +@node \ifundefined +@subsection @code{\ifundefined} + +@findex ifundefined +@code{\ifundefined@{@var{cs}@} @var{t} \else @var{f} \fi} expands the +@var{t} text if the control sequence @code{\@var{cs}} is undefined or +has been @code{\let} to @code{\relax}, and the @var{f} text otherwise. + +@cindex skipping tokens +@cindex undefined control sequence, checking for +Since @code{\ifundefined} is not a primitive conditional, it cannot be +used in places where @TeX{} might skip tokens ``at high speed'', e.g., +within another conditional---@TeX{} can't match up the @code{\if}'s and +@code{\fi}'s. + +This macro was taken directly from @cite{The @TeX{}book}, page 308. + + +@node \futurenonspacelet +@subsection @code{\futurenonspacelet} + +@cindex lookahead without spaces +@cindex spaces, ignoring +@findex futurenonspacelet +The @code{\futurelet} primitive allows you to look at the next token +from the input. Sometimes, though, you want to look ahead ignoring any +spaces. This is what @code{\futurenonspacelet} does. It is otherwise +the same as @code{\futurelet}: you give it two control sequences as +arguments, and it assigns the next nonspace token to the first, and then +expands the second. For example: + +@example +\futurenonspacelet\temp\finishup +\def\finishup@{\ifx\temp @dots{}@} +@end example + + +@node Obeying spaces +@section Obeying spaces + +@cindex whitespace +@cindex spaces, obeying +@cindex newlines, obeying +@findex obeywhitespace + +@code{\obeywhitespace} makes both end-of-lines and space characters in +the input be respected in the output. Unlike plain @TeX{}'s +@code{\obeyspaces}, even spaces at the beginnings of lines turn into +blank space. + +By default, the size of the space that is produced by a space +character is the natural space of the current font, i.e., +what @code{\ } produces. + +Ordinarily, a blank line in the input produces as much blank vertical +space as a line of text would occupy. You can adjust this by assigning +to the parameter @code{\blanklineskipamount}: +@findex blanklineskipamount @r{in obeyed text} +if you set this negative, the space produced by a blank line will be +smaller; if positive, larger. + +Tabs are not affected by this routine. In particular, if tabs occur +at the beginning of a line, they will disappear. (If you are trying to +make @TeX{} do the ``right thing'' with tabs, don't. Use a utility +program like @i{expand} instead.) +@cindex tabs + + +@node Writing out numbers +@section Writing out numbers + +@cindex numbers, written form of + @code{\numbername} +@findex numbername +produces the written-out form of its argument, i.e., `zero' through +`ten' for the numbers 0--10, and numerals for all others. + + +@node Mode-specific penalties +@section Mode-specific penalties + +@TeX{}'s built-in @code{\penalty} command simply appends to the +current list, no matter what kind of list it is. You might intend a +particular penalty to always be a ``vertical'' penalty, however, i.e., +appended to a vertical list. Therefore, Eplain provides +@code{\vpenalty} +@findex vpenalty +and @code{\hpenalty} +which first leave the other mode and then do @code{\penalty}. + +More precisely, @code{\vpenalty} inserts @code{\par} if the current +mode is horizontal, and @code{\hpenalty} inserts @code{\leavevmode} if +the current mode is vertical. (Thus, @code{\vpenalty} cannot be used in +math mode.) + + +@node Auxiliary files +@section Auxiliary files + +@cindex axuiliary files, existence of +It is common to write some information out to a file to be used on a +subsequent run. But when it is time to read the file again, you only +want to do so if the file actually exists. @code{\testfileexistence} +@findex testfileexistence +is given an argument which is appended to @code{\jobname}, +@findex jobname +and sets the conditional @code{\iffileexists} +@findex iffileexists +@findex fileexists @r{(conditional)} +appropriately. For example: + +@example +\testfileexistence@{toc@}% +\iffileexists + \input \jobname.toc +\fi +@end example + +@code{\testfileexistence} takes an optional parameter; when +given, it will override @code{\jobname} for the root part of the file +name. For example, if you want to test for the file +@file{answers.aux}, you can do this with the following: + +@example +\testfileexistence[answers]@{aux@}% +\iffileexists + \input answers.aux +\fi +@end example + + +@node User-defined environments +@section User-defined environments + +@cindex environments, user-defined +Plain @TeX{} does not provide ``named'' block structures, only the anonymous +@code{\begingroup} and @code{\endgroup} pair. The disadvantage of this +is that when there are several such groups and one is mismatched, it can +be difficult to find the error. Eplain provides a named block structure +so that if you forget an @code{\environment} or an +@code{\endenvironment}, you will (probably) get an error message about +it. + +For example: + +@example +\def\itpar@{ + \environment@{@@italicpar@} + \it\par +@} +\def\enditpar@{ + \par + \endenvironment@{@@italicpar@}% +@} +@end example +@noindent which could then be used to set italicized paragraphs: +@example +\itpar +If I reprehend anything in this world, it is the use of my oracular +tongue, and a nice derangement of epitaphs! +\enditpar +@end example + +The above sort of environment allows nesting. But environments +shouldn't always be allowed to nest. Put the control sequence +@code{\checkenv} at the beginning of a macro that is going to define an +environment that should not be nested. + + +@node Page list and page range parsers +@section Page list and page range parsers + +@findex idxparselist +@findex idxparserange +@findex idxpagei +@findex idxpageii +The macros which Eplain uses to parse the page lists and ranges in the +index, @code{\idxparselist} and @code{\idxparserange} (@pxref{Page +destinations for index terms}), are sometimes useful when defining page +number encapsulators. They take one argument, text to parse. When a +page list (range) is not present, they set @code{\idxpagei} to be +@code{\empty}; when a list (range) is detected, they set +@code{\idxpagei} and @code{\idxpageii} to the first and the second page +numbers, respectively. + +@findex setidxpagelistdelimiter +@findex setidxpagerangedelimiter +Eplain's defaults for the page list and page range delimiters are the +same as those in MakeIndex, a comma followed by a space (@samp{, }) and +two dashes (@samp{--}), respectively. If you customize MakeIndex to use +different delimiters, you must not forget to let Eplain know about them +with the commands + +@example +\setidxpagelistdelimiter@{@var{list-delim}@} +\setidxpagerangedelimiter@{@var{page-delim}@} +@end example + +@noindent These commands save the @var{list-delim} and +@var{page-delim} delimiters in +@findex idxpagelistdelimiter +@findex idxpagerangedelimiter +@code{\idxpagelistdelimiter} and @code{\idxpagerangedelimiter}, +respectively. + +@cindex underlining page numbers in index +@cindex index, underlining page numbers +@findex ituline +For example, you may want to define a page number markup command which +italicizes and properly underlines page ranges by underlining only the +page numbers and not the delimiter: + +@findex idxpagerangedelimiter +@example +\def\ituline#1@{% + @{\it + \idxparserange@{#1@}% + \ifx\idxpagei\empty + % The argument is a single page number. + \underbar@{#1@}% + \else + % The argument is a page range. + \underbar@{\idxpagei@}\idxpagerangedelimiter\underbar@{\idxpageii@}% + \fi@}% +@} +@end example + +@noindent Note that the @code{\ituline} macro is not aware of page +lists. This is not needed if you use hyperlinks in the index, because +@code{\hlidx} and @code{\hlidxpage} will break up the page lists before +calling the user's page encapsulator (@pxref{Page destinations for index +terms}), so @code{\ituline} will never see the lists. If, however, you +need to design a macro which also takes care of the lists, you can +extend @code{\ituline} with an additional call to @code{\idxparselist}. diff --git a/Master/texmf-dist/doc/eplain/base/userdef.texi b/Master/texmf-dist/doc/eplain/base/userdef.texi new file mode 100644 index 00000000000..dfc5fcc4497 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/base/userdef.texi @@ -0,0 +1,2538 @@ +@c This is part of the Eplain manual. Public domain. + +@node User definitions +@chapter User definitions + +This chapter describes definitions that are meant to be used directly +in a document. When appropriate, ways to change the default +formatting are described in subsections. + +@menu +* Diagnostics:: Tracing information. +* Rules:: Changing the default rule dimensions. +* Citations:: Using BibTeX and Eplain to make bibliographies. +* Displays:: Changing the formatting of math displays. +* Time of day:: Producing the time of day. +* Lists:: Producing numbered and unordered lists. +* Verbatim listing:: Producing text just as it appears. +* Contents:: Making a table of contents. +* Cross-references:: Symbolic references to equations, figures, etc. +* Page references:: Symbolic references to page numbers. +* Equation references:: Symbolic references to equation numbers. +* Indexing:: Creating and typesetting indexes. +* Justification:: Ragged left, ragged right, centered. +* Tables:: Producing ordered tables. +* Margins:: Changing the margins directly. +* Multiple columns:: Getting output in two columns. +* Footnotes:: Autonumbered footnotes; changing formatting. +* Fractions:: A better way to produce fractions in text. +* Paths:: Allowing line breaks in pathnames. +* Logos:: Various logos. +* Boxes:: Producing filled or open rectangles. +* Checking for PDF output:: Checking for pdfTeX in PDF mode. +* Loading LaTeX packages:: Support for LaTeX packages under plain TeX. +@end menu + + +@node Diagnostics +@section Diagnostics + +@cindex diagnostics +@cindex tracing +Plain @TeX{} provides the @code{\tracingall} command, to turn on the +maximum amount of tracing possible in @TeX{}. The (usually voluminous) +output from @code{\tracingall} goes both on the terminal and into the +transcript file. +@findex tracingall +It is sometimes easier to have the output go only to the transcript +file, so you can peruse it at your leisure and not obscure other output +to the terminal. So, Eplain provides the command @code{\loggingall}. +@findex loggingall +(For some reason, this command is available in Metafont, but not in +@TeX{}.) + +It is also sometimes useful to see the complete contents of boxes. +@code{\tracingboxes} does this. (It doesn't affect whether or not the +contents +@findex tracingboxes +are shown on the terminal.) + +You can turn off all tracing with @code{\tracingoff}. +@findex tracingoff + +You can also turn logging on and off globally, so you don't have to +worry about whether or not you're inside a group at the time of command. +These variants are named @code{\gloggingall} +@findex gloggingall +and @code{\gtracingall}. +@findex gtracingall + +Finally, if you write your own help messages (see @code{\newhelp} +@cindex help messages +@cindex error messages +in @cite{The @TeX{}book}), you want a convenient way to break lines in +them. This is what @TeX{}'s @code{\newlinechar} parameter is for; +@cindex newlinechar +however, plain @TeX{} doesn't set @code{\newlinechar}. Therefore, +Eplain defines it to be the character @code{^^J}. + +For example, one of Eplain's own error messages is defined as follows: +@example +\newhelp\envhelp@{Perhaps you forgot to end the previous^^J% + environment? I'm finishing off the current group,^^J% + hoping that will fix it.@}% +@end example + + +@node Rules +@section Rules + +The default dimensions of rules are defined in chapter@tie{}21 of the +@cite{The @TeX{}book}. To sum up what is given there, the ``thickness'' +of rules is +@cindex rule thickness +0.4pt by default. Eplain defines three parameters that let you change +this dimension: @code{\hruledefaultheight}, @code{\hruledefaultdepth}, +@findex hruledefaultheight +@findex hruledefaultdepth +and @code{\vruledefaultwidth}. By default, they are defined as +@findex vruledefaultwidth +@cite{The @TeX{}book} describes. + +But it would be wrong to redefine @code{\hrule} and @code{\vrule}. For +one thing, some macros in plain @TeX{} depend on the default dimensions +being used; for another, rules are used quite heavily, and the +performance impact of making it a macro can be noticeable. Therefore, +to take advantage of the default rule parameters, you must use +@code{\ehrule} +@findex ehrule +and @code{\evrule}. +@findex evrule + + +@node Citations +@section Citations + +@cindex citations +@cindex bibliographies +Bibliographies are part of almost every technical document. To handle +them easily, you need two things: a program to do the tedious +formatting, and a way to cite references by labels, rather than by +numbers. The Bib@TeX{} program, written by Oren Patashnik, takes care +@cindex Bib@TeX{} +@cindex Patashnik, Oren +of the first item; the citation commands in @LaTeX{}, written to be used +@cindex @LaTeX{} +with Bib@TeX{}, take care of the second. Therefore, +Eplain adopts the use of Bib@TeX{}, and virtually the same interface as +@LaTeX{}. + +The general idea is that you put citation commands in the text of your +document, and commands saying where the bibliography data is. When you +run @TeX{}, these commands produce output on the file with the same root +name as your document (by default) and the extension @file{.aux}. +@pindex .aux @r{file} +@findex jobname +Bib@TeX{} reads this file. You should put the bibliography data in a +file or files with the extension @file{.bib}. Bib@TeX{} writes out a +file with the same root +@pindex .bib @r{file} +name as your document and extension @file{.bbl}. Eplain reads this file +@pindex .bbl @r{file} +the next time you run your document through @TeX{}. (It takes +multiple passes to get everything straight, because usually after seeing +your bibliography typeset, you want to make changes in the @file{.bib} +file, which means you have to run Bib@TeX{} again, which means you have +to run @TeX{} again@dots{}) An annotated example of the whole process is +given below. + +If your document has more than one bibliography---for example, if it +is a collection of papers---you can tell Eplain to use a different root +name for the @file{.bbl} file by defining the control sequence +@code{\bblfilebasename}. +@findex bblfilebasename +The default definition is simply @code{\jobname}. + +See the document @cite{Bib@TeX{}ing} (whose text is in the file +@file{btxdoc.tex}, which should be in the Eplain distribution you got) +for information on how to write your @t{.bib} files. Both the +Bib@TeX{} and the Eplain distributions contain several examples, also. + +The @code{\cite} +@findex cite +command produces a citation in the text of your document. The exact +printed form the citation will take is under your control; +@pxref{Formatting citations}. @code{\cite} takes one +required argument, a comma-separated list of cross-reference labels +(@pxref{Cross-references}, for exactly what characters are allowed in +such labels). Warning: spaces in this list are taken as part of the +following label name, which is probably not what you expect. +@cindex citations, undefined +The @code{\cite} command also produces a command +in the @t{.aux} file that tells Bib@TeX{} to retrieve the given reference(s) +from the @t{.bib} file. @code{\cite} also takes one optional argument, +which you specify within square brackets, as in @LaTeX{}. This text is +simply typeset after the citations. (See the example below.) + +Eplain can create hypertext links for citations pointing to the relevant +bibliography entries; @pxref{Citation hyperlinks}. + +Another command, @code{\nocite}, +@findex nocite +puts the given reference(s) into the bibliography, but produces nothing +in the text. + +The @code{\bibliography} +@findex bibliography +command is next. It serves two purposes: producing the typeset +bibliography, and telling Bib@TeX{} the root names of the @t{.bib} +files. Therefore, the argument to @code{\bibliography} is a comma +separated list of the @t{.bib} files (without the @samp{.bib}). Again, +spaces in this list are significant. + +You tell Bib@TeX{} the particular style in which you want your +bibliography typeset with one more command: +@code{\bibliographystyle}. +@findex bibliographystyle +The argument to this is a single filename @var{style}, which tells +Bib@TeX{} to look for a file @var{style}@t{.bst}. +@pindex .bst @r{files} +See the document @cite{Designing Bib@TeX{} styles} (whose text is in the +@file{btxhak.tex}) for information on how to write your own styles. + +Eplain automatically reads the citations from the @t{.aux} file when +your job starts. + +If you don't want to see the messages about undefined citations, you +can say @code{\xrefwarningfalse} before making any citations. +@findex xrefwarningfalse +Eplain automatically does this if the @t{.aux} file does not exist. +You can restore the default by saying @code{\xrefwarningtrue}. + +Here is a @TeX{} input file that illustrates the various commands. + +@example +\input eplain % Reads the .aux file. +Two citations to Knuthian works: + \cite[note]@{surreal,concrete-math@}. +\beginsection@{References.@}\par % Title for the bibliography. +\bibliography@{knuth@} % Use knuth.bib for the labels. +\bibliographystyle@{plain@} % Number the references. +\end % End of the document. +@end example +@cindex Knuth, Donald Ervin +@cindex Graham, Ronald L. +@cindex numbered references +@cindex references, numbered + +If we suppose that this file was named @file{citex.tex} and that the +bibliography data is in @file{knuth.bib} (as the @code{\bibliography} +command says), the following commands do what's required. (@samp{$ } +represents the shell prompt.) + +@example +$ tex citex (produces undefined citation messages) +$ bibtex citex (read knuth.bib and citex.aux, write citex.bbl) +$ tex citex (read citex.bbl, still have undefined citations) +$ tex citex (one more time, to resolve the references) +@end example + +@pindex texi2dvi +@noindent (The @command{texi2dvi} program can help you automate this +process, @pxref{Invoking Eplain}.) + +The output looks something like (because we used the @t{plain} +bibliography style): + +@quotation +Two citations to Knuthian works: [2,1 note]. + +@b{References} +@tex +@frenchspacing +@end tex + +[1] Ronald L. Graham, Donald E. Knuth, and Oren Patashnik. @i{Concrete +Mathematics}. Addison-Wesley, Reading, Massachusetts, 1989. + +[2] Donald E. Knuth. @i{Surreal Numbers}. Addison-Wesley, Reading, +Massachusetts, 1974. +@end quotation + +See the Bib@TeX{} documentation for information on how to write the +bibliography databases, and the bibliography styles that are available. +(If you want your references printed with names, as in [Knu74], instead +of numbered, the bibliography style is @code{alpha}.) +@cindex alphanumeric references +@cindex references, alphanumeric + +@menu +* Formatting citations:: Changing the way citations are printed. +* Formatting bibliographies:: Changing the way bibliographies are printed. +@end menu + + +@node Formatting citations +@subsection Formatting citations + +@cindex citations, formatting + +You may wish to change Eplain's formatting of citations; i.e., the +result of your @code{\cite} commands. By default, the citation labels +are printed one after another, separated by commas and enclosed in +brackets, using the main text font. Some formats require other styles, +such as superscripted labels. You can accomodate such formats by +redefining the following macros. + +@table @code +@itemx \printcitestart +@item \printcitefinish +@findex printcitestart +@findex printcitefinish +Eplain expands these macros at the begining and end of the list of +citations for each @code{\cite} command. By default, they produce a +@samp{[} and @samp{]}, respectively. + +@item \printbetweencitations +@findex printbetweencitations +If a @code{\cite} command has multiple citations, as in +@code{\cite@{acp,texbook@}}, Eplain expands this macro in between each +pair of citations. By default, it produces a comma followed by a space. + +@item \printcitenote +@findex printcitenote +This macro takes one argument, which is the optional note to the +@code{\cite} command. If the @code{\cite} command had no note, this +macro isn't used. Otherwise, it should print the note. By default, the +note is preceded with a comma and a space. +@end table + + +Here is an example, showing you could produce citations as +superscripted labels, with the optional notes in parentheses. + +@example +\def\printcitestart@{\unskip $^\bgroup@} +\def\printbetweencitations@{,@} +\def\printcitefinish@{\egroup$@} +\def\printcitenote#1@{\hbox@{\sevenrm\space (#1)@}@} +@end example + + +@node Formatting bibliographies +@subsection Formatting bibliographies + +@cindex bibliography, formatting the + +You may wish to change Eplain's formatting of the bibliography, +especially with respect to the fonts that are used. Therefore, Eplain +provides the following control sequences: + +@table @code + +@item \biblabelwidth +@findex biblabelwidth +This control sequence represents a @code{\dimen} register, and its value +is the width of the widest label in the bibliography. Although it is +unlikely you will ever want to redefine it, you might want +to use it if you redefine @code{\biblabelprint}, below. + +@item \biblabelprint +@findex biblabelprint +This macro takes one argument, the label to print. By default, the +label is put in a box of width @code{\biblabelwidth}, and is followed by +an enspace. When you want to change the spacing around the labels, this +is the right macro to redefine. + +@item \biblabelcontents +@findex biblabelcontents +This macro also takes one argument, the label to print. By default, the +label is printed using the font @code{\bblrm} (below), and enclosed in +brackets. When you want to change the appearance of the label, but not +the spacing around it, this is the right macro to redefine. + +@item \bblrm +@findex bblrm +@cindex bibliography fonts +The default font used for printing the bibliography. + +@item \bblem +@findex bblem +The font used for printing the titles and other ``emphasized'' material. + +@item \bblsc +@findex bblsc +In some styles, authors' names are printed in a caps-and-small-caps +font. In those cases, this font is used. + +@item \bblnewblock +@findex bblnewblock +This is invoked between each of the parts of a bibliography entry. The +default is to leave some extra space between the parts; you could +redefine it to start each part on a new line (for example). A part is +simply a main element of the entry; for example, the author is a part. +(It was @LaTeX{} that introduced the (misleading, as far as I am +concerned) term `block' for this.) + +@item \biblabelextraspace +@findex biblabelextraspace +Bibliography entries are typeset with a hanging indentation of +@code{\biblabelwidth} plus this. The default is @code{.5em}, where the +em width is taken from the @code{\bblrm} font. If you want to change +this, you should do it inside @code{\bblhook}. + +@item \bblhook +@findex bblhook +@cindex bibliography items, extra space between +This is expanded before reading the @t{.bbl} file. By +default, it does nothing. You could, for example, define it to set the +bibliography fonts, or produce the heading for the references. Two +spacing parameters must be changed inside @code{\bblhook}: +@code{\parskip}, which produces extra space between the items; and +@code{\biblabelextraspace}, which is described above. +(By the way, @code{\hookappend} won't work with @code{\bblhook}, despite +the names. Just use @code{\def}.) + +@end table + +If you are really desperate, you can also hand-edit the @t{.bbl} file +that Bib@TeX{} produces to do anything you wish. + + +@node Displays +@section Displays + +@cindex displays, left-justifying +@cindex mathematics displays, formatting +@cindex left-justification of displays + +By default, @TeX{} centers displayed material. (Displayed material is +just whatever you put between @code{$$}'s---it's not necessarily +mathematics.) Many layouts would be better served if the displayed +material was left-justified. Therefore, Eplain provides the command +@code{\leftdisplays}, +@findex leftdisplays +which indents displayed material by @code{\parindent} plus +@code{\leftskip}, plus @code{\leftdisplayindent}. +@findex leftdisplayindent + +You can go back to centering displays with @code{\centereddisplays}. +@findex centereddisplays +(It is usually poor typography to have both centered and left-justified +displays in a single publication, though.) + +@code{\leftdisplays} also changes the plain @TeX{} commands that deal +with alignments inside math displays, +@code{\displaylines}, +@findex displaylines +@code{\eqalignno}, +@findex eqalignno +and @code{\leqalignno}, +@findex leqalignno +to produce left-justified text. You can still override this formatting +by inserting @code{\hfill} glue, as explained in @cite{The @TeX{}book}. + +@menu +* Formatting displays:: General formatting of displays. +@end menu + + +@node Formatting displays +@subsection Formatting displays + +If you want some other kind of formatting, you can write a definition +of your own, analogous to @code{\leftdisplays}. You need only make sure +that @code{\leftdisplaysetup} +@findex leftdisplaysetup +is called at the beginning of every display (presumably by invoking it +in @TeX{}'s @code{\everydisplay} parameter), and to define +@code{\generaldisplay}. +@findex generaldisplay + +@code{\leftdisplays} expands the old value of @code{\everydisplay} +before calling @code{\leftdisplaysetup}, so that any changes you have made +to it won't be lost. That old token list as available as the value of +the token register @code{\previouseverydisplay}. +@findex previouseverydisplay + + +@node Time of day +@section Time of day + +@cindex time of day +@cindex date + +@TeX{} provides the day, month, and year as numeric quantities (unless +your @TeX{} implementation is woefully deficient). Eplain provides some +control sequences to make them a little more friendly to humans. + +@code{\monthname} +@findex monthname +produces the name of the current month, abbreviated to three letters. + +@code{\fullmonthname} +@findex fullmonthname +produces the name of the current month, unabbreviated (in English). + +@code{\timestring} +@findex timestring +produces the current time, as in `1:14 p.m.' + +@code{\timestamp} +@findex timestamp +produces the current date and time, as in `23 Apr 64 1:14 p.m.'. +(Except the spacing is slightly different.) + +@code{\today} +@findex today +produces the current date, as in `23 April 1964'. + + +@node Lists +@section Lists + +@cindex lists +@cindex numbered lists +@cindex ordered list +@cindex unordered lists + +Many documents require lists of items, either numbered or simply +enumerated. Plain @TeX{} defines one macro to help with creating lists, +@code{\item}, but that is insufficient in many cases. Therefore, +Eplain provides two pairs of commands: + +@table @code + +@itemx \numberedlist @dots{} \endnumberedlist +@item \orderedlist @dots{} \endorderedlist +@findex numberedlist +@findex endnumberedlist +@findex orderedlist +@findex endorderedlist +These commands (they are synonyms) produce a list with the items +numbered sequentially, starting from one. A nested @code{\numberedlist} +labels the items with lowercase letters, starting with `a'. Another +nested @code{\numberedlist} labels the items with roman numerals. Yet +more deeply nested numbered lists label items with @samp{*}. + +@item \unorderedlist @dots{} \endunorderedlist +@findex unorderedlist +@findex endunorderedlist +This produces a list with the items labelled with small black boxes +(``square bullets''). A nested @code{\unorderedlist} labels items with +em-dashes. Doubly (and deeper) nested unordered lists label items with +`*'s. + +@end table + +The two kinds of lists can be nested within each other, as well. + +In both kinds of lists, you begin an item with @code{\li}. +@findex li +An item may continue for several paragraphs. Each item starts a +paragraph. + +You can give @code{\li} an optional argument, a cross-reference label. +It's defined to be the ``marker'' for the current item. This is useful +if the list items are numbered. You can produce the value of the label +with @code{\xrefn}. @xref{Cross-references}. + +Eplain can create hypertext links for the markers produced by +@code{\xrefn} pointing to the relevant list item; @pxref{List +hyperlinks}. + +You can also say @code{\listcompact} +@findex listcompact +right after @code{\numberedlist} or @code{\unorderedlist}. The items in +the list will then not have any extra space between them +(@pxref{Formatting lists}). You might want to do this if the items in +this particular list are short. + +Here is an example: +@example +\numberedlist\listcompact +\li The first item. +\li The second item. + +The second paragraph of the second item. +\endnumberedlist +@end example + +@menu +* Formatting lists:: Changing how the lists look. +@end menu + + +@node Formatting lists +@subsection Formatting lists + +@cindex lists, formatting + +Several registers define the spacing associated with lists. It is +likely that their default values won't suit your particular layout. + +@table @code +@item \abovelistskipamount, \belowlistskipamount +@findex abovelistskipamount +@findex belowlistskipamount +The vertical glue inserted before and after every list, respectively. + +@item \interitemskipamount +@findex interitemskipamount +The vertical glue inserted before each item except the first. +@code{\listcompact} resets this to zero, as mentioned above. + +@item \listleftindent, \listrightindent +@findex listleftindent +@findex listrightindent +@code{\listrightindent} is the amount of space by which the list is +indented on the right; i.e., it is added to @code{\rightskip}. +@code{\listleftindent} is the amount of space, @emph{relative to} +@code{\parindent}, by which the list is indented on the left. Why treat +the two parameters differently? Because (a)@tie{}it is more useful to +make the list indentation depend on the paragraph indentation; +(b)@tie{}footnotes aren't formatted right if @code{\parindent} is reset +to zero. + +@end table + +The three vertical glues are inserted by macros, and preceded by +penalties: @code{\abovelistskip} +@findex abovelistskip +does @code{\vpenalty\abovelistpenalty} +@findex abovelistpenalty +and then @code{\vskip\abovelistskip}. @code{\belowlistskip} +@findex belowlistskip +and @code{\interitemskip} +@findex interitemskip +are analogous. + +In addition, the macro @code{\listmarkerspace} +@findex listmarkerspace +is called to separate the item label from the item text. This is set to +@code{\enspace} by default. + +If you want to change the labels on the items, you can redefine these +macros: +@code{\numberedmarker} +@findex numberedmarker +or @code{\unorderedmarker}. +@findex unorderedmarker +The following registers might be useful if you do: + +@table @code +@item \numberedlistdepth, \unorderedlistdepth +@findex numberedlistdepth +@findex unorderedlistdepth +These keep track of the depth of nesting of the two kinds of lists. + +@item \itemnumber, \itemletter +@findex itemnumber +@findex itemletter +These keep track of the number of items that have been seen in the current +numbered list. They are both integer registers. The difference is that +@code{\itemnumber} starts at one, and @code{\itemletter} starts at 97, +i.e., lowercase `a'. + +@end table + +You can also redefine the control sequences that are used internally, +if you want to do something radically different: @code{\beginlist} +@findex beginlist +is invoked to begin both kinds of lists; @code{\printitem} +@findex printitem +is invoked to print the label (and space following the label) for each +item; and @code{\endlist} +@findex endlist +is invoked to end both kinds of +lists. +@cindex item labels, changing +@cindex labels on items, changing + + +@node Verbatim listing +@section Verbatim listing + +@cindex verbatim listing +@cindex listing files +@cindex files, verbatim listing of +It is sometimes useful to include a file verbatim in your document; +for example, part of a computer program. The @code{\listing} +@findex listing +command is given one argument, a filename, and produces the contents of +that file in your document. @code{\listing} expands @code{\listingfont} +to set the current font. The default value of @code{\listingfont} +@findex listingfont +is @code{\tt}. + +You can take arbitrary actions before reading the file by defining the macro +@code{\setuplistinghook}. +@findex setuplistinghook +This is expanded just before the file is input. + +If you want to have line numbers on the output, you can say +@code{\let\setuplistinghook = \linenumberedlisting}. +@findex linenumberedlisting +The line numbers are stored in the count register @code{\lineno} while +the file is being read. You can redefine the macro +@code{\printlistinglineno} to change how they are printed. + +You can produce in-line verbatim text in your document with @code{\verbatim}. +@findex verbatim +End the text with @code{|endverbatim}. If you need a @samp{|} in the text, +double it. If the first character of the verbatim text is a space, use +@code{| }. (@code{| } will work elsewhere in the argument, too, but +isn't necessary.) + +For example: + +@example +\verbatim| ||\#%&!|endverbatim +@end example + +@noindent produces @code{ |\#%&!}. + +Line breaks and spaces in the verbatim text are preserved. + +@findex verbatimescapechar +@cindex escape character, changing verbatim +You can change the verbatim escape character from the default @samp{|} +with @code{\verbatimescapechar @var{char}}; for example, this changes +it to @samp{@@}. + +@example +\verbatimescapechar \@@ +@end example + +@noindent The backslash is not necessary in some cases, but is in +others, depending on the catcode of the character. The argument to +@code{\verbatimescapechar} is used as @code{\catcode `@var{char}}, so +the exact rules follow that for @code{\catcode}. + +Because @code{\verbatim} must change the category code of special +characters, calling inside a macro definition of your own does not work +properly. For example: + +@example +\def\mymacro@{\verbatim &#%|endverbatim@}% Doesn't work! +@end example + +To accomplish this, you must change the category codes yourself before +making the macro definition. Perhaps @code{\uncatcodespecials} will +help you (@pxref{Category codes}). + + +@node Contents +@section Contents + +@cindex table of contents +@cindex contents + +Producing a table of contents that is both useful and aesthetic is one +of the most difficult design problems in any work. Naturally, Eplain +does not pretend to solve the design problem. Collecting the raw data +for a table of contents, however, is much the same across documents. +Eplain uses an auxiliary file with extension @file{.toc} +@pindex .toc @r{file} +(and the same root name as your document) to save the information. + +To write an entry for the table of contents, you say +@code{\writetocentry@{@var{part}@}@{@var{text}@}}, +@findex writetocentry +where @var{part} is the type of part this entry is, e.g., +@samp{chapter}, and @var{text} is the text of the title. +@code{\writetocentry} puts an entry into the @t{.toc} file that looks +@findex toc@dots{}entry +like @code{\toc@var{part}entry@{@var{text}@}@{@var{page number}@}}. The +@var{text} is written unexpanded. + +@findex writenumberedtocentry +A related command, @code{\writenumberedtocentry}, takes one additional +argument, the first token of which is expanded at the point of the +@code{\writenumberedtocentry}, but the rest of the argument is not +expanded. The usual application is when the parts of the document are +numbered. On the other hand, the one-level expansion allows you to use +the argument for other things as well (author's names in a proceedings, +say), and not have accents or other control sequences expanded. The +downside is that if you @emph{want} full expansion of the third +argument, you don't get it---you must expand it yourself, before you +call @code{\writenumberedtocentry}. + +For example: + +@example +\writenumberedtocentry@{chapter@}@{A $\sin$ wave@}@{\the\chapno@} +\writetocentry@{section@}@{A section title@} +@end example + +@noindent Supposing @code{\the\chapno} expanded to @samp{3} and that the +@code{\write}'s occurred on pages eight and nine, respectively, the +above writes the following to the @t{.toc} file: + +@example +\tocchapterentry@{A $\sin$ wave@}@{3@}@{8@} +\tocsectionentry@{A section title@}@{9@} +@end example + +@findex readtocfile +You read the @t{.toc} file with the command @code{\readtocfile}. +Naturally, whatever @code{\toc@dots{} entry} commands that were written +to the file must be defined when @code{\readtocfile} is invoked. Eplain +has minimal definitions for @code{\tocchapterentry}, +@code{\tocsectionentry}, and @code{\tocsubsectionentry}, just to prevent +undefined control sequence errors in common cases. They aren't suitable +for anything but preliminary proofs. + +Each of @code{\writetocentry} and @code{\writenumberedtocentry} opens +the @t{.toc} file for writing, thereby deleting the information from the +previous run. You should therefore arrange that @code{\readtocfile} be +called @emph{before} the first call to a @code{\writetoc@dots{}} macro. +@code{\readtocfile} does not itself delete the information +from the @t{.toc} file, so that you can call it several times, +e.g., to create both a short +@cindex table of contents, short +and normal table of contents. (To produce this in particular, define +@code{\tocsectionentry} to produce nothing while you are reading +@t{.toc} file for a short table of contents (@pxref{Macro arguments}).) + +On the other hand, if you don't want to rewrite the @t{.toc} file at +all, perhaps because you are only running @TeX{} on part of your +manuscript, you can set @code{\rewritetocfilefalse}. +@findex ifrewritetocfile +@findex rewritetocfile @r{(conditional)} + +By default, the @file{.toc} file has the root @code{\jobname}. If your +document has more than one contents---for example, if it is a collection +of papers, some of which have their own contents---you can tell Eplain +to use a different root name by defining the control sequence +@code{\tocfilebasename}. +@findex tocfilebasename + +@cindex list of figures +@cindex list of tables +@findex definecontentsfile +In addition to the usual table of contents, you may want to have a list +of figures, list of tables, or other such contents-like list. You can do +this with @code{\definecontentsfile@{@var{abbrev}@}}. All of the +above commands are actually a special case that Eplain predefines with + +@example +\definecontentsfile@{toc@} +@end example + +@noindent The @var{abbrev} is used both for the file extension and in +the control sequence names. + + + +@node Cross-references +@section Cross-references + +@cindex cross-references +It is often useful to refer the reader to other parts of your document; +but putting literal page, section, equation, or whatever numbers in the +text is certainly a bad thing. + +Eplain therefore provides commands for symbolic cross-references. It +uses an auxiliary file with extension @t{.aux} +@pindex .aux @r{file} +(and the same root name as your document) to keep track of the +information. Therefore, it takes two passes to get the cross-references +right---one to write them out, and one to read them in. Eplain +automatically reads the @t{.aux} file at the first reference; after +reading it, Eplain reopens it for writing. + +You can control whether or not Eplain warns you about undefined +labels. @xref{Citations}. + +@cindex labels, characters valid in +Labels in Eplain's cross-reference commands can use characters of +category code eleven (letter), twelve (other), ten (space), three (math +shift), four (alignment tab), seven (superscript), or eight (subscript). +For example, @samp{(a1 $&^_} is a valid label (assuming the category +codes of plain @TeX{}), but @samp{%#\@{} has no valid characters. + +You can also do symbolic cross-references for bibliographic citations +and list items. @xref{Citations}, and @ref{Lists}. + +Eplain can create hypertext links for the cross-references; +@pxref{Cross-reference hyperlinks}. + +@menu +* Defining generic references:: +* Using generic references:: +@end menu + + +@node Defining generic references +@subsection Defining generic references + +@cindex defining general references +@cindex references, defining general +@cindex cross-references, defining general + +@findex definexref +Eplain provides the command @code{\definexref} for general +cross-references. It takes three arguments: the name of the label (see +section above for valid label names), the value of the label (which can +be anything), and the ``class'' of the reference---whether it's a +section, or theorem, or what. For example: + +@example +\definexref@{sec-intro@}@{3.1@}@{section@} +@end example + +@noindent Of course, the label value is usually generated by another +macro using @TeX{} count registers or some such. + +@code{\definexref} doesn't actually define @var{label}; instead, it +writes out the definition to the @t{.aux} file, where Eplain will read +it on the next @TeX{} run. + +The @var{class} argument is used by the @code{\ref} and @code{\refs} +commands. See the next section. + + +@node Using generic references +@subsection Using generic references + +@cindex defining general references +@cindex references, defining general +@cindex cross-references, defining general + +To retrieve the value of the label defined via @code{\definexref} (see +the previous section), Eplain provides the following macros: + +@table @code + +@findex refn +@itemx \refn@{@var{label}@} +@findex xrefn +@item \xrefn@{@var{label}@} +@code{\refn} and @code{\xrefn} (they are synonyms) produce the bare +definition of @var{label}. If @var{label} isn't defined, issue a +warning, and produce @var{label} itself instead, in typewriter. (The +warning isn't given if @code{\xrefwarningfalse}.) +@findex xrefwarning @r{conditional} + +@findex ref +@item \ref@{@var{label}@} +Given the class @var{c} for @var{label} (see the description of +@code{\definexref} in the previous section), expand the control sequence +@code{\@var{c} word} (if it's defined) followed by a tie. Then call +@code{\refn} on @var{label}. (Example below.) + +@findex refs +@item \refs@{@var{label}@} +Like @code{\ref}, but append the letter @samp{s} to the +@code{\@dots{}word}. + +@end table + +The purpose of the @code{\@dots{}word} macro is to produce the word +`Section' or `Figure' or whatever that usually precedes the actual +reference number. + +Here is an example: + +@example +\def\sectionword@{Section@} +\definexref@{sec-intro@}@{3.1@}@{section@} +\definexref@{sec-next@}@{3.2@}@{section@} +See \refs@{sec-intro@} and \refn@{sec-next@} @dots{} +@end example + +@noindent This produces `See Sections 3.1 and 3.2 @dots{}' + + +@node Page references +@section Page references + +Eplain provides two commands for handling references to page numbers, +one for definition and one for use. + +@table @code + +@item \xrdef@{@var{label}@} +@findex xrdef +Define @var{label} to be the current page number. This produces no +printed output, and ignores following spaces. + +@item \xref@{@var{label}@} +@findex xref +Produce the text `p.@tie{}@var{pageno}', which is the usual form for +cross-references. The @var{pageno} is actually @var{label}'s +definition; if @var{label} isn't defined, the text of the label itself +is printed. The `p.@tie{}' prefix is defined by @code{\xrefpageword}. +@findex xrefpageword +Its default definition is @code{p.\thinspace}. + +@end table + +Eplain can create hypertext links for the page references; @pxref{Page +reference hyperlinks}. + + +@node Equation references +@section Equation references + +@cindex equations, references to +@cindex equations, numbering +Instead of referring to pages, it's most useful if equation labels +refer to equation numbers. Therefore, Eplain reserves a @code{\count} +register, @code{\eqnumber}, +@findex eqnumber +for the current equation number, and increments it at each +numbered equation. + +Here are the commands to define equation labels and then refer to them: + +@table @code + +@item \eqdef@{@var{label}@} +@findex eqdef +This defines @var{label} to be the current value of @code{\eqnumber}, +and, if the current context is not inner, then produces a @code{\eqno} +command. (The condition makes it possible to use @code{\eqdef} in an +@code{\eqalignno} construction, for example.) The text of the equation +number is produced using @code{\eqprint}. @xref{Formatting equation +references}. + +@cindex empty equation labels +@cindex labels, empty equation +@cindex equations, giving numbers to all +If @var{label} is empty, you still get an equation number (although +naturally you can't reliably refer to it). This is useful if you want +to put numbers on all equations in your document, and you don't want to +think up unique labels. + +@cindex empty equation labels, referring to +@cindex labels, empty equation, referring to +To refer to the last equation with the empty label, you just use the +empty label in one of the equation reference macros (see below). This +can be handy when you want to refer to an equation shortly after its +definition, say, in the sentence following the displayed equation, and +do not intend to refer to the equation later. But use this trick with +extreme caution: if later you change the text and insert another +empty definition between the original definition and the reference, +the reference will start to refer to the new empty-labeled equation. + +@item \eqdefn@{@var{label}@} +@findex eqdefn +This is like @code{\eqdef}, except it always omits the @code{\eqno} +command. It can therefore be used in places where @code{\eqdef} can't; +for example, in a non-displayed equation. The text of the equation +number is not produced, so you can also use it in the (admittedly +unusual) circumstance when you want to define an equation label but not +print that label. + +@item \eqref@{@var{label}@} +@findex eqref +This produces a formatted reference to @var{label}. If @var{label} is +undefined (perhaps because it is a forward reference), it just produces +the text of the label itself. Otherwise, it calls @code{\eqprint}. + +@item \eqrefn@{@var{label}@} +@findex eqrefn +This produces the cross-reference text for @var{label}. That is, it +is like @code{\eqref}, except it doesn't call @code{\eqprint}. + +@end table + +@cindex equation labels, characters valid in +Equation labels can contain the same characters that are valid in +general cross-references. + +Eplain can create hypertext links for the equation references; +@pxref{Equation reference hyperlinks}. + + +@menu +* Formatting equation references:: +* Subequation references:: +@end menu + + +@node Formatting equation references +@subsection Formatting equation references + +@cindex equation numbers, formatting of +Both defining an equation label and referring to it should usually +produce output. This output is produced with the @code{\eqprint} macro, +which takes one argument, the equation number being defined or referred +to. By default, this just produces @samp{(@var{number})}, where +@var{number} is the equation number. To produce the equation number in +a different font, or with different surrounding symbols, or whatever, +you can redefine @code{\eqprint}. +@findex eqprint +For example, the following definition would print all equation numbers +in italics. (The extra braces define a group, to keep the font change +from affecting surrounding text.) + +@example +\def\eqprint#1@{@{\it (#1)@}@} +@end example + +In addition to changing the formatting of equation numbers, you might +to add more structure to the equation number; for example, you might +want to include the chapter number, to get equation numbers like +`(1.2)'. To achieve this, you redefine @code{\eqconstruct}. +@findex eqconstruct +For example: + +@example +\def\eqconstruct#1@{\the\chapternumber.#1@} +@end example + +@noindent +(If you are keeping the chapter number in a count register named +@code{\chapternumber}, naturally.) + +The reason for having both @code{\eqconstruct} and @code{\eqprint} may +not be immediately apparent. The difference is that @code{\eqconstruct} +affects the text that cross-reference label is defined to be, while +@code{\eqprint} affects only what is typeset on the page. The example +just below might help. + +Usually, you want equation labels to refer to equation numbers. But +sometimes you might want a more complicated text. For example, you +might have an equation `(1)', and then have a variation several pages +later which you want to refer to as `(1*)'. + +Therefore, Eplain allows you to give an optional argument (i.e., +arbitrary text in square brackets) before the cross-reference label to +\eqdef. Then, when you refer to the equation, that text is produced. +Here's how to get the example just mentioned: + +@example +$$@dots{}\eqdef@{a-eq@}$$ +@dots{} +$$@dots{}\eqdef[\eqrefn@{a-eq@}*]@{a-eq-var@}$$ +In \eqref@{a-eq-var@}, we expand on \eqref@{a-eq@}, @dots{} +@end example + +We use @code{\eqrefn} in the cross-reference text, not +@code{\eqref}, so that @code{\eqprint} is called only once. + + +@node Subequation references +@subsection Subequation references + +@cindex equations, groups of +@cindex subequations, referring to +Eplain also provides for one level of substructure for equations. That +is, you might want to define a related group of equations with numbers +like `2.1' and `2.2', and then be able to refer to the group as a whole: +``@dots{} in the system of equations (2)@dots{}''. + +The commands to do this are @code{\eqsubdef} and +@findex eqsubdef +@code{\eqsubdefn}. +@findex eqsubdefn +They take one @var{label} argument like their counterparts above, +and generally behave in the same way. The difference is in how they +construct the equation number: instead of using just @code{\eqnumber}, +they also use another counter, @code{\subeqnumber}. +@findex subeqnumber +This counter is advanced by one at every @code{\eqsubdef} or +@code{\eqsubdefn}, and reset to zero at every @code{\eqdef} or +@code{\eqdefn}. + +You use @code{\eqref} to refer to subequations as well as main +equations. + +To put the two together to construct the text that the label will +produce, they use a macro @code{\eqsubreftext}. +@findex eqsubreftext +This macros takes two arguments, the ``main'' equation number (which, +because the equation label can be defined as arbitrary text, as +described in the previous section, might be anything at all) and the +``sub'' equation number (which is always just a number). Eplain's +default definition just puts a period between them: +@example +\def\eqsubreftext#1#2@{#1.#2@}% +@end example + +@noindent You can redefine @code{\eqsubreftext} to print however you +like. For example, this definition makes the labels print as `2a', +`2b', and so on. +@example +\newcount\subref +\def\eqsubreftext#1#2@{% + \subref = #2 % The space stops a . + \advance\subref by 96 % `a' is character code 97. + #1\char\subref +@} +@end example + +@noindent Sadly, we must define a new count register, @code{\subref}, +instead of using the scratch count register @code{\count255}, because +@samp{#1} might include other macro calls which use @code{\count255}. + + +@node Indexing +@section Indexing + +@cindex indexing +@cindex sorting an index + +Eplain provides support for generating raw material for an index, and +for typesetting a sorted index. A separate program must do the actual +collection and sorting of terms, because @TeX{} itself has no support +for sorting. + +Eplain can create hypertext links pointing from the index to the index +terms; @pxref{Index hyperlinks}. + +@cindex URL for MakeIndex +@pindex makeindex +Eplain's indexing commands were designed to work with the program +MakeIndex, available from CTAN hosts in +@file{tex-archive/indexing/makeindex}; MakeIndex is also commonly +included in prepackaged @TeX{} distributions. It is beyond the scope of +this manual to explain how to run MakeIndex, and all of its many +options. See @url{http://www.ctan.org/tex-archive/indexing/makeindex/} + +The basic strategy for indexing works like this: + +@enumerate + +@pindex .idx @r{files} +@item For a document @file{foo.tex}, Eplain's indexing commands (e.g., +@code{\idx}; see the section `Indexing terms' below) write the raw index +material to @file{foo.idx}. + +@pindex .ind @r{files} +@item MakeIndex reads @file{foo.idx}, collects and sorts the index, and +writes the result to @file{foo.ind}. + +@item Eplain reads and typesets @file{foo.ind} on a subsequent run of +@TeX{}. See the section `Typesetting an index' below. + +@end enumerate + +@pindex texi2dvi +@noindent The @command{texi2dvi} program can help you automate this +process, @pxref{Invoking Eplain}. + +@cindex multiple indexes +@cindex indexes, multiple +@findex defineindex +If your document needs more than one index, each must have its own +file. Therefore, Eplain provides the command @code{\defineindex}, which +takes an argument that is a single letter, which replaces @samp{i} in +the filenames and in the indexing command names described below. For +example, + +@example +\defineindex@{m@} +@end example + +@noindent defines the command @code{\mdx} to write to the file +@file{foo.mdx}. Eplain simply does @code{\defineindex@{i@}} to define +the default commands. + +@menu +* Indexing terms:: Specifying what to index. +* Typesetting an index:: Printing the sorted output. +* Customizing indexing:: Creating commands and specifying extra actions. +@end menu + + +@node Indexing terms +@subsection Indexing terms + +@cindex indexing terms +@cindex silent indexing + +Indexing commands in Eplain come in pairs: one command that only +writes the index entry to the @samp{.idx} file (see above section), and +one that also typesets the term being indexed. The former always starts +with @samp{s} (for ``silent''). In either case, the name always includes +@samp{@var{I}dx}, where @var{I} is the index letter, also described +above. Eplain defines the index @samp{i} itself, so that's what we'll +use in the names below. + +@cindex subterm in indexing +The silent form of the commands take a subterm as a trailing optional +argument. For example, @code{\sidx@{truth@}[definition of]} on page 75 +makes an index entry that will eventually be typeset (by default) as + +@display +truth + definition of, 75 +@end display + +@cindex trailing spaces and indexing commands +@cindex spaces, trailing and indexing commands +@cindex indexing and trailing spaces +Also, the silent commands ignore trailing spaces. The non-silent ones do not. + +@menu +* Indexing commands:: Making index entries. +* Modifying index entries:: Ranges, see/see also, page number typesetting. +* Proofing index terms:: Noting index entries in the margins. +@end menu + + +@node Indexing commands +@subsubsection Indexing commands + +@cindex indexing commands +Here are the commands. + +@itemize @bullet + +@item +@findex sidx +@findex idx +@code{\sidx@{@var{term}@}[@var{subterm}]} makes an index entry for +@var{term}, optionally with subterm @var{subterm}. +@code{\idx@{@var{term}@}} also produces @var{term} as output. Example: + +@example +\sidx@{truth@}[beauty of] +The beauty of truth is \idx@{death@}. +@end example + +Subterms at the second and further levels can also be +specified in @var{subterm}, using the +@code{\idxsubentryseparator} character to separate +them. This character is by default @samp{!}. + +@item +@findex sidxname +@findex idxnameseparator +@findex idxname +@code{\sidxname@{@var{First M.}@}@{@var{von Last}@}[@var{subterm}]} +makes an index +entry for @samp{@var{von Last}, @var{First M.}}. You can change the +@samp{, } by redefining @code{\idxnameseparator}. +@code{\idxname@{@var{First M.}@}@{@var{von Last}@}} also produces @var{First M. von +Last} as output. (These commands are useful special cases of @code{\idx} +and @code{\sidx}.) Example: + +@example +\sidxname@{Richard@}@{Stark@} +\idxname@{Donald@}@{Westlake@} has written many kinds of novels, under +almost as many names. +@end example + +@item +@findex sidxmarked +@findex idxmarked +@code{\sidxmarked\@var{cs}@{@var{term}@}[@var{subterm}]} makes an index +entry for @code{@var{term}[@var{subterm}]}, but @var{term} will be put +in the index as @code{\@var{cs}@{term@}}, but still sorted as just +@var{term}. @code{\idxmarked\@var{cs}@{@var{term}@}} also typesets +@code{\@var{cs}@{term@}}. This provides for the usual ways of changing +the typesetting of index entries. Example: + +@example +\def\article#1@{``#1''@} +\sidxmarked\article@{Miss Elsa and Aunt Sophie@} +Peter Drucker's \idxmarked\article@{The Polanyis@} is a remarkable +essay about a remarkable family. +@end example + +@item +@findex idxsubmarked +@findex sidxsubmarked +@code{\sidxsubmarked@{@var{term}@}\@var{cs}@{subterm@}} makes an index +entry for @var{term}, @var{subterm} as usual, but also puts @var{subterm} in +the index as @code{\@var{cs}@{term@}}. +@code{\idxsubmarked@{@var{term}@}\@var{cs}@{subterm@}} also typesets +@code{@var{term} \@var{cs}@{subterm@}}, in the unlikely event that your +syntax is convoluted enough to make this useful. Example: + +@example +\def\title#1@{@{\sl #1@}@} +\sidxsubmarked@{Anderson, Laurie@}\title@{Strange Angels@} +The \idxsubmarked@{Anderson@}\title@{Carmen@} is a strange twist. +@end example + +@end itemize + +@cindex index entry general sorting +@cindex sorting of index entries +The commands above rely on MakeIndex's feature for separating sorting of +an index entry's from its typesetting. You can use this directly by +specifying an index entry as @code{@var{sort}@@@var{typeset}}. For +example: + +@example +\sidx@{Ap-weight@@$A_\pi$-weight@} +@end example + +@noindent will sort as @code{Ap-weight}, but print with the proper math. +The @code{@@} here is MakeIndex's default character for this purpose. +See @url{http://www.ctan.org/tex-archive/indexing/makeindex/}. To make an index +entry with an @code{@@} in it, you have to escape it with a backslash; +Eplain provides no macros for doing this. + +@findex afterindexterm @r{hook} +@cindex whatsits made by index entries +After any index command, Eplain runs +@code{\hookaction@{afterindexterm@}}. Because the index commands always +add a whatsit item to the current list, you may wish to preserve a +penalty or space past the new item. For example, given a conditional +@code{\if@@aftersctnhead} set true when you're at a section heading, you +could do: + +@example +\hookaction@{afterindexterm@}@{\if@@aftersctnhead \nobreak \fi@} +@end example + + +@node Modifying index entries +@subsubsection Modifying index entries + +@cindex modifying index entries' page numbers +@cindex index entries' page numbers, modifying + +All the index commands described in the previous section take an initial +optional argument before the index term, which modify the index entry's +meaning in various ways. You can specify only one of the following in +any given command, except that @code{begin} and @code{end} can be +specified together with @code{pagemarkup=@var{cs}} (separate them with +a comma without a following space, like this: +@code{[begin,pagemarkup=defn]}). + +These work via MakeIndex's ``encapsulation'' feature. @xref{Customizing +indexing}, if you're not using the default characters for the +MakeIndex operators. The other optional argument (specifying a subterm) +is independent of these. + +Here are the possibilities: + +@table @code + +@item begin +@itemx end +@findex begin @r{for index entries} +@findex end @r{for index entries} +@cindex index entries and ranges +@cindex ranges and index entry +These mark an index entry as the beginning or end of a range. The index +entries must match exactly for MakeIndex to recognize them. +Example: + +@example +\sidx[begin]@{future@}[Cohen, Leonard] +@dots{} +\sidx[end]@{future@}[Cohen, Leonard] +@end example + +@noindent will typeset as something like + +@display +future, + Cohen, Leonard, 65--94 +@end display + +@item see +@findex see @r{for index entries} +@cindex see, and index entries +@cindex cross-referencing index entries +@cindex index entries, and cross-referencing +This marks an index entry as pointing to another; the real index term is +an additional (non-optional) argument to the command. Thus you can +anticipate a term readers may wish to look up, yet which you have +decided not to index. Example: + +@example +\sidx[see]@{analysis@}[archetypal]@{archetypal criticism@} +@end example + +@noindent becomes + +@display +analysis, + archetypal, @i{see} archetypal criticism +@end display + +@item seealso +@findex seealso @r{for index entries} +Similar to @code{see} (the previous item), but also allows for normal +index entries of the referencing term. Example: + +@example +\sidx[seealso]@{archetypal criticism@}[elements of]@{dichotomies@} +@end example + +@noindent becomes + +@display +archetypal criticism, + elements of, 75, 97, 114, @i{see also} dichotomies +@end display + +(Aside for the academically curious: The archetypally critical book I +took these dichotomous examples from is Laurence Berman's @cite{The +Musical Image}, which I happened to co-design and typeset.) + +@item pagemarkup=@var{cs} +This puts @code{\@var{cs}} before the page number in the typeset index, +thus allowing you to underline definitive entries, italicize examples, +and the like. You do @emph{not} precede the control sequence @var{cs} +with a backslash. (That just leads to expansive difficulties.) Naturally +it is up to you to define the control sequences you want to use. Example: + +@example +\def\defn#1@{@{\sl #1@}@} +\sidx[pagemarkeup=defn]@{indexing@} +@end example + +@noindent becomes something like + +@example +indexing, @code{\defn@{75@}} +@end example + +@end table + + +@node Proofing index terms +@subsubsection Proofing index terms + +@cindex proofing index terms +@cindex index terms, proofing +@cindex margins, index terms in + +As you are reading through a manuscript, it is helpful to see what terms +have been indexed, so you can add others, catch miscellaneous errors, +etc. (Speaking from bitter experience, I can say it is extremely +error-prone to leave all indexing to the end of the writing, since it +involves adding many @TeX{} commands to the source files.) + +@findex indexproofterm +@findex indexprooffont +@pindex cmtt8 +So Eplain puts index terms in the margin of each page, if you +set @code{\indexproofingtrue}. It is @code{false} by default. The terms +are typeset by the macro @code{\indexproofterm}, which takes a single +argument, the term to be typeset. Eplain's definition of +@code{\indexproofterm} just puts it into an @code{\hbox}, first doing +@code{\indexprooffont}, which Eplain defines to select the font +@code{cmtt8}. With this definition long terms run off the page, but +since this is just for proofreading anyway, it seems acceptable. + +@findex pageno +@findex insidemargin +@findex hoffset +@findex outsidemargin +@findex indexsetmargins +On the other hand, we certainly don't want the index term to run into +the text of the page, so Eplain uses the right-hand side of the page +rather than the left-hand page (assuming a language read left to right +here). So @code{\ifodd\pageno}, Eplain kerns by @code{\outsidemargin}, +otherwise by @code{\insidemargin}. If those macros are undefined, +@code{\indexsetmargins} defines them to be one inch plus @code{\hoffset}. + +@findex @@indexproof @r{insertion class} +@findex indexproofunbox +@findex makeheadline +@cindex output routine and index proofing +To get the proofing index entries on the proper page, Eplain defines a new +insertion class @code{\@@indexproof}. To unbox any index proofing +material, Eplain redefines @code{\makeheadline} to call +@code{\indexproofunbox} before the original @code{\makeheadline}. Thus, +if you have your own output routine, that redefines or doesn't use +@code{\makeheadline}, it's up to you to call @code{\indexproofunbox} at +the appropriate time. + + +@node Typesetting an index +@subsection Typesetting an index + +@cindex typesetting an index +@cindex index typesetting +@findex readindexfile + +The command @code{\readindexfile@{i@}} reads and typesets the +@file{.ind} file that MakeIndex outputs (from the @file{.idx} file which +the indexing commands in the previous sections write). Eplain defines a +number of commands that support the default MakeIndex output. + +@findex indexfilebasename +@findex jobname +More precisely, @code{\readindexfile} reads +@code{\indexfilebasename.@var{index-letter}nd}, where the +@var{index-letter} is the argument. @code{\indexfilebasename} is +@code{\jobname} by default, but if you have different indexes in +different parts of a book, you may wish to change it, just as with +bibliographies (@pxref{Citations}). + +@findex begin@{theindex@} +@findex end@{theindex@} +MakeIndex was designed to work with @LaTeX{}; therefore, by default the +@file{.ind} file starts with @code{\begin@{theindex@}} and ends with +@code{\end@{theindex@}}. If no @code{\begin} has been defined, Eplain +defines one to ignore its argument and set up for typesetting the index +(see below), and also defines a @code{\end} to ignore its argument. (In +a group, naturally, since there is a primitive @code{\end}). + +@findex parindent @r{in indexes} +@cindex index fonts +@findex indexfonts +@cindex double columns in indexes +Eplain calls @code{\indexfonts}, sets @code{\parindent = 0pt}, and does +@code{\doublecolumns} (@pxref{Multiple columns}) at the +@code{\begin@{theindex@}}. @code{\indexfonts} does nothing by default; +it's just there for you to override. (Indexes are usually typeset in +smaller type than the main text.) + +@findex beginindex @r{hook} +It ends the setup with @code{\hookrun@{beginindex@}}, so you can +override anything you like in that hook (@pxref{Hooks}). For example: + +@example +\hookaction@{beginindex@}@{\triplecolumns@} +@end example + +@findex item @r{in indexes} +@findex subitem @r{in indexes} +@findex subsubitem @r{in indexes} +@cindex index entry formatting +@cindex formatting index entries +@cindex space above index entries +@cindex continued index entries +@cindex index entry continuations +MakeIndex turns each main index entry into an @code{\item}, subentries +into @code{\subitem}, and subsubentries into @code{\subsubitem}. By +default, the first line of main entries are not indented, and subentries +are indented 1em per level. Main entries are preceded by a @code{\vskip} +of @code{\aboveitemskipamount}, @code{0pt plus2pt} by default. Page +breaks are encouraged before main entries (@code{\penalty -100}), but +prohibited afterwards---Eplain has no provision for ``continued'' +index entries. + +All levels do the following: + +@findex hangindent @r{for index entries} +@findex raggedright @r{for index entries} +@findex hyphenpenalty @r{for index entries} +@example +\hangindent = 1em +\raggedright +\hyphenpenalty = 10000 +@end example + +@findex indexitem @r{hook} +Each entry ends with @code{\hookrun@{indexitem@}}, so you can change any +of this. For example, to increase the allowable rag: + +@example +\hookaction@{indexitem@}@{\advance\rightskip by 2em@} +@end example + +@findex indexspace +@cindex index groupings +Finally, MakeIndex outputs @code{\indexspace} between each group of +entries in the @file{.ind} file. Eplain makes this equivalent to +@code{\bigbreak}. + + +@node Customizing indexing +@subsection Customizing indexing + +@cindex customizing indexing + +@findex afterindexterm +@cindex commas after index terms +@cindex after index terms +By default, MakeIndex outputs @samp{, } after each term in the index. To +change this, you can add the following to your MakeIndex style +(@file{.ist}) file: + +@example +delim_0 "\\afterindexterm " +delim_1 "\\afterindexterm " +delim_2 "\\afterindexterm " +@end example + +@noindent Eplain makes @code{\afterindexterm} equivalent to +@code{\quad}. + +You can also change the keywords Eplain recognizes (@pxref{Modifying +index entries}): + +@table @code + +@item \idxrangebeginword +@findex idxrangebeginword +`begin' + +@item \idxrangeendword +@findex idxrangeendword +`end' + +@item \idxseecmdword +@findex idxseecmdword +`see' + +@item \idxseealsocmdword +@findex idxseealsocmdword +`seealso' + +@end table + +You can also change the magic characters Eplain puts into the +@file{.idx} file, in case you've changed them in the @code{.ist} file: + +@table @code + +@item \idxsubentryseparator +@findex idxsubentryseparator +@samp{!} + +@item \idxencapoperator +@findex idxencapoperator +@samp{|} + +@item \idxbeginrangemark +@findex idxbeginrangemark +@samp{(} + +@item \idxendrangemark +@findex idxendrangemark +@samp{)} + +@end table + +There is no macro for the @code{actual} (@samp{@@} by default) +character, because it's impossible to make it expand properly. + +@findex idxpagenum +@cindex see also index entries and sorting +You can change the (imaginary) page number that ``see also'' +entries sort as by redefining @code{\idxmaxpagenum}. This is 99999 by +default, which is one digit too many for old versions of MakeIndex. + +@findex indexseeword +@findex indexseealsowords +@findex seevariant +@findex indexsee +@findex indexseealso +The words output by Eplain for ``see'' and ``see also'' index entries +are defined by @code{\indexseeword} and @code{\indexseealsowords} +respectively. You can change the typeface used for these words by +redefining @code{\seevariant}. And finally, the macros +@code{\indexsee} and @code{\indexseealso} actually produce the ``see +@dots{}'' entries, so you can redefine them if you want something +entirely different. If you do redefine them, make them take two +parameters, the term being referenced and the @code{\idxmaxpagenum} +(the latter should normally be ignored). See the example below. + +@findex see @r{for index entries} +@cindex see, and index entries +@cindex cross-referencing index entries +@cindex index entries, and cross-referencing +@cindex commas in cross-referencing index entries +Unfortunately, it is impossible to reliably control the commas +produced by MakeIndex in front of ``see @dots{}'' entries in the +@file{.ind} file, either at MakeIndex level or at Eplain level. +However, the +@pindex sed +@command{sed} script named @command{trimsee} +@pindex trimsee +distributed with Eplain in the @file{test} directory can be used to +filter out these commas from the output of MakeIndex. For example, +suppose you want the following style for your ``see @dots{}'' entries: + +@display +analysis, + archetypal (@i{see} archetypal criticism) +archetypal criticism, + elements of, 75, 97, 114 (@i{see also} dichotomies) +@end display + +@noindent You would need to redefine these macros in your @TeX{} +file: + +@example +\def\indexsee#1#2@{(@{\seevariant \indexseeword\/ @}#1)@} +\def\indexseealso#1#2@{(@{\seevariant \indexseealsowords\/ @}#1)@} +@end example + +@noindent and then filter out the commas in front of the ``see @dots{}'' +entries by running the following command to produce the @file{.ind} +file (assuming the name of the @file{.idx} file is @file{myfile.idx} +and the @file{trimsee} script is placed in the current directory): + +@example +prompt$ cat myfile.idx | makeindex | ./trimsee > myfile.ind +@end example + +By default, @file{trimsee} uses default page list separators and +default ``see @dots{}'' command names. If you set up MakeIndex to use +different page list separator or change the names of @code{\indexsee} +and @code{\indexseealso} commands, it is possible to adjust the +@file{trimsee} script through its command line options, which are the +following: + +@table @option +@item -i @var{is} +Use @var{is} as a regular expression matching separator before ``see +@dots{}'' commands in the input (default: @samp{, \+}). + +@item -o @var{os} +Use @var{os} as a separator to replace @var{is} before ``see @dots{}'' +commands (default: @samp{ }). + +@item -s @var{see} +Use @var{see} as a regular expression matching ``see @dots{}'' +commands (default: @samp{\\indexsee}). + +@item -h +@itemx --help +Print a usage message. + +@item -v +@itemx --version +Print version. +@end table + +@file{trimsee} reads input from the standard input, and directs its +output to the standard output. + + +@node Justification +@section Justification + +@cindex centering +@cindex left-justification +@cindex right-justification +@cindex justification +Eplain defines three commands to conveniently justify multiple +lines of text: @code{\flushright}, @code{\flushleft}, and +@code{\center}. +@findex flushright +@findex flushleft +@findex center + +They all work in the same way; let's take @code{\center} as the +example. To start centering lines, you say @code{\center} inside a +group; to stop, you end the group. Between the two commands, each +end-of-line in the input file also starts a new line in the output file. + +The entire block of text is broken into paragraphs at blank lines, +so all the @TeX{} paragraph-shaping parameters apply in the usual way. +This is convenient, but it implies something else that isn't so +convenient: changes to any linespacing parameters, such as +@code{\baselineskip}, will have @emph{no effect} on the paragraph in +which they are changed. @TeX{} does not handle linespacing changes +within a paragraph (because it doesn't know where the line breaks are +until the end of the paragraph). + +The space between paragraphs is by default one blank line's worth. +You can adjust this space by assigning to @code{\blanklineskipamount}; +@findex blanklineskipamount @r{in justified text} +this (vertical) glue is inserted after each blank line. + +Here is an example: +@example +@{\center First line. + + Second line, with a blank line before. +@} +@end example + +This produces: + +@center First line. +@center +@center Second line, with a blank line before. + +You may wish to use the justification macros inside of your own +macros. Just be sure to put them in a group. For example, here is how +a title macro might be defined: + +@example +\def\title@{\begingroup\titlefont\center@} +\def\endtitle@{\endgroup@} +@end example + + +@node Tables +@section Tables + +@cindex tables +@cindex alignments +Eplain provides a single command, @code{\makecolumns}, +@findex makecolumns +to make generating one particular kind of table easier. More ambitious +macro packages might be helpful to you for more difficult applications. +The files @file{ruled.tex} and @file{TXSruled.tex}, available from +@samp{lifshitz.ph.utexas.edu} in @file{texis/tables}, is the only one I +know of. + +Many tables are homogenous, i.e., all the entries are semantically the +same. The arrangement into columns is to save space on the page, not +to encode different meanings. In this kind of the table, it is useful to +have the column breaks chosen automatically, so that you can add or +delete entries without worrying about the column breaks. + +@code{\makecolumns} takes two arguments: the number of entries in the +table, and the number of columns to break them into. As you can see +from the example below, the first argument is delimited by a slash, and +the second by a colon and a space (or end-of-line). The entries for the +table then follow, one per line (not including the line with the +@code{\makecolumns} command itself). + +@code{\parindent} defines the space to the left of the +table. @code{\hsize} defines the width of the table. +So you can adjust the position of the table on the page by assignments +to these parameters, probably inside a group. + +You can also control the penalty at a page break before the +@code{\makecolumns} by setting the parameter +@code{\abovecolumnspenalty}. +@findex abovecolumnspenalty +Usually, the table is preceded by some explanatory text. You wouldn't +want a page break to occur after the text and before the table, so +Eplain sets it to @code{10000}. But if the table produced by +@code{\makecolumns} is standing on its own, @code{\abovecolumnspenalty} +should be decreased. + +If you happen to give @code{\makecolumns} a smaller number of entries +than you really have, some text beyond the (intended) end of the table +will be incorporated into the table, probably producing an error +message, or at least some strange looking entries. And if you give +@code{\makecolumns} a larger number of entries than you really have, +some of the entries will be typeset as straight text, probably also +looking somewhat out of place. + +Here is an example: +@example +% Arrange 6 entries into 2 columns: +\makecolumns 6/2: % This line doesn't have an entry. +one +two +three +four +five +six +Text after the table. +@end example + +This produces `one', `two', and `three' in the first column, and +`four', `five', and `six' in the second. + + +@node Margins +@section Margins + +@cindex margins, changing +@TeX{}'s primitives describe the type area in terms of an offset from +the upper left corner, and the width and height of the type. Some +people prefer to think in terms of the @dfn{margins} at the top, bottom, +left, and right of the page, and most composition systems other than +@TeX{} conceive of the page laid out in this way. Therefore, Eplain +provides commands to directly assign and increment the margins. + +@table @code +@itemx \topmargin = @var{dimen} +@itemx \bottommargin = @var{dimen} +@itemx \leftmargin = @var{dimen} +@item \rightmargin = @var{dimen} +@findex topmargin +@findex bottommargin +@findex leftmargin +@findex rightmargin +These commands set the specified margin to the @var{dimen} given. +The @code{=} and the spaces around it are optional. The control +sequences here are not @TeX{} registers, despite appearances; +therefore, commands like @code{\showthe\topmargin} will not do what you +expect. + +@itemx \advancetopmargin by @var{dimen} +@itemx \advancebottommargin by @var{dimen} +@itemx \advanceleftmargin by @var{dimen} +@item \advancerightmargin by @var{dimen} +@findex advancetopmargin +@findex advancebottommargin +@findex advanceleftmargin +@findex advancerightmargin +These commands change the specified margin by the @var{dimen} given. +@end table + +Regardless of whether you use the assignment or the advance commands, +Eplain always changes the type area in response, not the other margins. +For example, when @TeX{} starts, the left and right margins are both one +inch. If you then say @code{\leftmargin = 2in}, the right margin will +remain at one inch, and the width of the lines (i.e., @code{\hsize}) +@findex hsize +will decrease by one inch. + +When you use any of these commands, Eplain computes the old value of +the particular margin, by how much you want to change it, and then +resets the values of @TeX{}'s primitive parameters to correspond. +Unfortunately, Eplain cannot compute the right or bottom margin without +help: you must tell it the full width and height of the final output +page. It defines two new parameters for this: + +@table @code +@item \paperheight +@findex paperheight +The height of the output page; default is 11truein. + +@item \paperwidth +@findex paperwidth +The width of the output page; default is 8.5truein. +@end table + +If your output page has different dimensions than this, you must +reassign to these parameters, as in + +@example +\paperheight = 11truein +\paperwidth = 17truein +@end example + + +@node Multiple columns +@section Multiple columns + +@cindex double column output +@cindex triple column output +@cindex quadruple column output +@cindex multiple column output +Eplain provides for double, triple, and quadruple column output: say +@code{\doublecolumns}, +@findex doublecolumns +@code{\triplecolumns}, +@findex triplecolumns +or @code{\quadcolumns}, +@findex quadcolumns +and from that point on, the manuscript will be +set in columns. To go back to one column, say +@code{\singlecolumn}. +@findex singlecolumn + +@cindex column balancing with @code{\singlecolumn} +@cindex balancing of columns with @code{\singlecolumn} +You may need to invoke @code{\singlecolumn} to balance the columns +on the last page of output. + +@findex columnfill +@cindex column eject +@cindex eject in multicolumns +@findex pagetotal +To do a ``column eject'', i.e., move to the top of the next column, do +@code{\columnfill}. This does not actually force an eject, however: it +merely inserts a kern of size @code{\@@normalvsize} minus +@code{\pagetotal} (@code{\@@normalvsize} being the usual height of the +page; to implement multicolumns, Eplain multiplies @code{\vsize} itself +by the number of columns). In most circumstances, a column break will be +forced after this kern (during the column splitting operation when the +whole page is output), as desired. + +@findex gutter +The columns are separated by the value of the dimen parameter +@code{\gutter}. Default value is two picas. +@findex gutterbox +If you want to add vertical material between the columns, use +@code{\gutterbox}. For example, to put a vertical line between columns, +define +@code{\gutterbox} as +@example +\def\gutterbox@{\vbox to \dimen0@{\vfil\hbox@{\vrule height\dimen0@}\vfil@}@}% +@end example +The dimension counter +@code{\dimen0} +contains the height of the column. + +All the @code{\@dots{}columns} macros insert the value of the glue parameter +@code{\abovecolumnskip} +@findex abovecolumnskip +before the multicolumn text, and the value of the glue parameter +@code{\belowcolumnskip} +@findex belowcolumnskip +after it. The default value for both of these parameters is +@code{\bigskipamount}, i.e., one linespace in plain @TeX{}. + +The macros take into account only the insertion classes +@cindex insertion classes +defined by plain @TeX{}; namely, footnotes and @code{\topinsert}s. If +you have additional insertion classes, you will need to change +the implementation. + +Also, Eplain makes insertions the full page width. There is no +provision for column-width insertions. + + +@node Footnotes +@section Footnotes + +@cindex footnotes, numbered +The most common reference mark for footnotes is a raised number, +incremented on each footnote. The @code{\numberedfootnote} +@findex numberedfootnote +macro provides this. It takes one argument, the footnote text. + +If your document uses only numbered footnotes, you could make typing +@code{\numberedfootnote} more convenient with a command such as: + +@example +\let\footnote = \numberedfootnote +@end example + +After doing this, you can type your footnotes as +@code{\footnote@{@var{footnote text}@}}, instead of as +@code{\numberedfootnote@{@var{footnote text}@}}. + +Eplain keeps the current footnote number in the count register +@code{\footnotenumber}. So, to reset the footnote number to zero, +as you might want to do at, for example, the beginning of a chapter, you +could say @code{\footnotenumber=0}. + +Plain @TeX{} separates the footnote marker from the footnote text by +an en space (it uses the @code{\textindent} macro). In Eplain, you can +change this space by setting the dimension register +@code{\footnotemarkseparation}. +@findex footnotemarkseparation +The default is still an en. + +You can produce a space between footenotes by setting the glue +register @code{\interfootnoteskip}. +@findex interfootnoteskip +The default is zero. + +@code{\parskip} is also set to zero by default before the beginning of +each footnote (but not for the text of the footnote). + +You can also control footnote formatting in a more general way: +Eplain expands the token register @code{\everyfootnote} +@findex everyfootnote +before a footnote is typeset, but after the default values for all the +parameters have been established. For example, if you want your +footnotes to be printed in seven-point type, indented by one inch, you +could say: +@example +\everyfootnote = @{\sevenrm \leftskip = 1in@} +@end example + +By default, an @code{\hrule} is typeset above each group of footnotes +on a page. You can control the dimensions of this rule by setting +the dimension registers @code{\footnoterulewidth} +@findex footnoterulewidth +and @code{\footnoteruleheight}. +@findex footnoteruleheight +The space between the rule and the first footnote on the page is +determined by the dimension register @code{\belowfootnoterulespace}. +@findex belowfootnoterulespace +If you don't want any rule at all, set @code{\footenoteruleheight=0pt}, +and, most likely, @code{\belowfootnoterulespace=0pt}. The defaults for +these parameters typeset the rule in the same way as plain @TeX{}: the +rule is 0.4 points high, 2 true inches wide, with 2.6 points below it. + +The space above the rule and below the text on the page is controlled +by the glue register @code{\skip\footins}. The default is a plain @TeX{} +@code{\bigskip}. + +Eplain can create hypertext links for the footnote marks; @pxref{Footnote +hyperlinks}. + + + +@node Fractions +@section Fractions + +@cindex fractions +Exercise 11.6 of @cite{The @TeX{}book} describes a macro @code{\frac} +@findex frac +for setting fractions, but @code{\frac} never made it into plain @TeX{}. +So Eplain includes it. + +@code{\frac} typesets the numerator and denominator in +@code{\scriptfont0}, slightly raised and lowered. The numerator and +denominator are separated by a slash. The denominator must be enclosed +in braces if it's more than one token long, but the numerator need not +be. (This is a consequence of @code{\frac} taking delimited arguments; +see page@tie{}203 of @cite{The @TeX{}book} for an explanation of +delimited macro arguments.) + +For example, @code{\frac 23/@{64@}} turns `23/64' into +@tex +\leavevmode + \kern-.1em \raise .5ex \hbox{\the\scriptfont0 23}@comment + \kern-.1em $/$@comment + \kern-.15em \lower .25ex \hbox{\the\scriptfont0 64}@comment +@end tex +@ifinfo +23/64 (you can't see the difference in the Info file)@comment +@end ifinfo +. + + +@node Paths +@section Paths + +@cindex pathnames, breaking +@cindex filenames, breaking +@cindex electronic mail addresses, breaking + +When you typeset long pathnames, electronic mail addresses, or other +such ``computer'' names, you would like @TeX{} to break lines at +punctuation characters within the name, rather than trying to find +hyphenation points within the words. For example, it would be better to +break the email address @code{letters@@alpha.gnu.ai.mit.edu} at the +@samp{@@} or a @samp{.}, rather than at the hyphenation points in +@samp{letters} and @samp{alpha}. + +@findex path +If you use the @code{\path} macro to typeset the names, @TeX{} will find +these good breakpoints. The argument to @code{\path} is delimited by +any character other other than @samp{\} which does not appear in the +name itself. +@samp{|} is often a good choice, as in: +@example +\path|letters@@alpha.gnu.ai.mit.edu| +@end example + +@findex discretionaries +You can control the exact set of characters at which breakpoints will be +allowed by calling @code{\discretionaries}. This takes the same sort of +delimited argument; any character in the argument will henceforth be a valid +breakpoint within @code{\path}. The default set is essentially all the +punctuation characters: +@example +\discretionaries |~!@@$%^&*()_+`-=#@{@}[]:";'<>,.?\/| +@end example + +@findex specialpathdelimiters @r{(conditional)} +If for some reason you absolutely must use @code{\} as the delimiter +character for @code{\path}, you can set +@code{\specialpathdelimiterstrue}. (Other delimiter characters can +still be used.) @TeX{} then processes the @code{\path} argument +about four times more slowly. + +@cindex URL for @file{path.sty} +The @code{\path} macro comes from @file{path.sty}, written by Nelson +Beebe and Philip Taylor and available at +@url{http://www.ctan.org/tex-archive/macros/latex/contrib/misc/path.sty}. + + +@node Logos +@section Logos + +@cindex logos +@cindex names, of @TeX{} variants + +Eplain redefines the @code{\TeX} +@findex TeX +macro of plain @TeX{} to end with @code{\null}, so that the proper +spacing is produced when @code{\TeX} is used at the end of a sentence. +The other @dots{}@TeX{} macros listed here do this, also. + +Eplain defines +@code{\AMSTeX}, +@cindex AMS@TeX{} +@findex AMSTeX +@code{\BibTeX} +@cindex Bib@TeX{} +@findex BibTeX +@code{\AMSLaTeX}, +@cindex AMS@LaTeX{} +@findex AMSLaTeX +@code{\LAMSTeX}, +@cindex LAMS@TeX{} +@findex LAMSTeX +@code{\LaTeX} +@cindex @LaTeX{} +@findex LaTeX +@code{\MF}, +@cindex Metafont +@findex MF +and @code{\SLiTeX} +@cindex SLi@TeX{} +@findex SLiTeX +to produce their respective logos. (Sorry, the logos are not shown +here.) Some spelling variants of these are also supported. + +@cindex URL for @file{texnames.sty} +All these macros come from @file{texnames.sty}, compiled by Nelson +Beebe and available at +@url{http://www.ctan.org/tex-archive/info/biblio/texnames.sty}. + + +@node Boxes +@section Boxes + +@cindex black boxes +@cindex rectangles +The solid rectangle that Eplain uses as a marker in unordered lists +(@pxref{Lists}) is available by itself: just say @code{\blackbox}. +@findex blackbox + +You can create black boxes of arbitrary size with @code{\hrule} or +@code{\vrule}. + +@cindex open boxes +@cindex boxes, open +You can also get unfilled rectangles with @code{\makeblankbox}. +@findex makeblankbox +This takes two explicit arguments: the height and depth of the rules that +define the top and bottom of the rectangle. (The two arguments are +added to get the width of the left and right borders, so that the +thickness of the border is the same on all four sides.) It also uses, +as implicit arguments, the dimensions of @code{\box0} to define the +dimensions of the rectangle it produces. (The contents of @code{\box0} +are ignored.) + +Here is an example. This small raised open box is suitable for +putting next to numbers in, e.g., a table of contents. + +@example +\def\openbox@{% + \ht0 = 1.75pt \dp0 = 1.75pt \wd0 = 3.5pt + \raise 2.75pt \makeblankbox@{.2pt@}@{.2pt@} +@} +@end example + +Finally, you can put a box around arbitrary text with @code{\boxit}. +@findex boxit +This takes one argument, which must itself be a (@TeX{}) box, and puts a +printed box around it, separated by @code{\boxitspace} +@findex boxitspace +white space (3 points by default) on all four sides. For example: + +@example +\boxit@{\hbox@{This text is boxed.@}@} +@end example + +The reason that the argument must be a box is that when the text is +more than one line long, @TeX{} cannot figure out the line length for +itself. Eplain does set @code{\parindent} to zero inside @code{\boxit}, +since it is very unlikely you would want indentation there. (If you do, +you can always reset it yourself.) + +@code{\boxit} uses @code{\ehrule} and @code{\evrule} so that you can +easily adjust the thicknesses of the box rules. @xref{Rules}. + + +@node Checking for PDF output +@section Checking for PDF output + +@cindex URL for pdf@TeX{} +@cindex PDF output +@pindex pdftex +@pindex .pdf @r{files} +pdf@TeX{} is a @TeX{} variant that can output both @file{.dvi} and +@file{.pdf} (Adobe's Portable Document Format) files (see +@url{http://www.ctan.org/tex-archive/systems/pdftex/}). You might +sometimes want to know whether the target format is @file{.pdf} or +@file{.dvi}. The @code{\ifpdf} +@findex ifpdf +switch can be used to detect pdf@TeX{} in PDF mode: + +@example +\ifpdf + This text is produced when pdfTeX is in PDF mode. +\else + This text is produced when pdfTeX is in DVI mode, + or when some program other than pdfTeX is used. +\fi +@end example + +Keep in mind that @code{\ifpdf} is set based on the value of the +@code{\pdfoutput} +@findex pdfoutput +primitive of pdf@TeX{} at the time Eplain is loaded. If you change +the value of @code{\pdfoutput} after you load Eplain, @code{\ifpdf} +will not reflect the change. + +@cindex URL for @file{ifpdf.sty} +@cindex Oberdiek, Heiko +Eplain defines @code{\ifpdf} by incorporating Heiko Oberdiek's +@file{ifpdf.sty}, which is available at +@url{http://www.ctan.org/tex-archive/macros/latex/contrib/oberdiek/ifpdf.sty}. + + +@node Loading LaTeX packages +@section Loading @LaTeX{} packages + +@cindex @LaTeX{} packages +@cindex packages, @LaTeX{} +@pindex .sty @r{files} +@pindex .cls @r{files} +Eplain provides a limited support for loading @LaTeX{} packages +(@file{.sty} files---not @file{.cls}). This will mostly work for +packages which were designed with plain @TeX{} compatibility in mind, +which means that most @LaTeX{} packages cannot be loaded. The +packages which are known to work are listed below (@pxref{Packages +known to work}). If you discover a working package which is not in +the list, please report it to the Eplain mailing list +(@pxref{Introduction}). + +@cindex graphics collection, @LaTeX{} +@cindex @LaTeX{} graphics collection +@pindex miniltx.tex +@cindex Carlisle, David +@cindex Rahtz, Sebastian +To set up a pseudo-@LaTeX{} environment for the packages, Eplain uses +@file{miniltx.tex} +(@url{http://www.ctan.org/tex-archive/macros/plain/graphics/miniltx.tex}) +from the @LaTeX{} graphics collection, written by David Carlisle and +Sebastian Rahtz (the collection is available at +@url{http://www.ctan.org/tex-archive/macros/latex/required/graphics/}). +Eplain extends @file{miniltx.tex} to provide some additional features, +e.g., support for package options. + + +@menu +* The \usepackage command:: Command to load packages. +* Environment for loading packages:: Environment for the \usepackage commands. +* Packages known to work:: Supported packages. +* Packages known not to work:: Packages known not to work with Eplain. +@end menu + +@node The \usepackage command +@subsection The @code{\usepackage} command + +@findex usepackage +@code{\usepackage} loads a @LaTeX{} package. Its syntax is similar to +that of @LaTeX{}'s @code{\usepackage} command: + +@example +\usepackage[@var{options}]@{@var{packages}@}[@var{version}] +@end example + +@noindent where @var{options} is a comma-separated list of package +options, @var{packages} is a comma-separated list of packages to load +(without the @file{.sty} suffix), and @var{version} is a package +version number given as a date in the format @samp{YYYY/MM/DD}. If an +older version of the package is found, a warning is issued. If +several packages are loaded within a single @code{\usepackage} +command, the @var{options} will be applied to each of the packages. +As usual, parameters in square brackets are optional and can be +omitted (together with the square brackets). + +For example: + +@example +\usepackage[foo,bar]@{pack1,pack2@}[2005/08/29] +@end example + +@noindent will load packages @samp{pack1} and @samp{pack2}, each with +the options @samp{foo} and @samp{bar}, and will check that each of the +packages are dated 2005/08/29 or newer. + + +@node Environment for loading packages +@subsection Environment for loading packages + +@findex beginpackages +@findex endpackages +Some packages request that certain commands are executed after all +packages have been loaded. In @LaTeX{}, this means that the commands +are executed at the beginning of the document, after the so-called +@dfn{preamble}. Neither plain @TeX{} nor Eplain have any kind of +preamble; therefore, Eplain requires that all packages be loaded inside +a @code{\beginpackages...\endpackages} block, for example: + +@example +\beginpackages + \usepackage[foo,bar]@{pack1@} + \usepackage@{pack2@} +\endpackages +@end example + +@noindent This requirement enables Eplain to execute the ``delayed'' +commands at the end of the @code{\beginpackages...\endpackages} block. + +For the same reason, it is advisable to specify only one such block +per document, just like there is only one preamble in @LaTeX{}. + + +@node Packages known to work +@subsection Packages known to work + +@cindex @LaTeX{} packages +@cindex packages, @LaTeX{} +The following table lists packages that had been tested and are known +to work with Eplain, and locations where you can find manuals for +these packages. Some of the short descriptions of the packages were +taken from the documentation for those packages. + +@table @asis +@item autopict (@samp{2001/06/04 v1.1j Picture mode autoload file}) +@pindex autopict.sty +@url{http://tug.org/eplain/ltpictur.pdf} + +@cindex picture mode +@findex begin@{picture@} +@findex end@{picture@} +This is the @LaTeX{} ``picture mode'', started by +@code{\begin@{picture@}} and ended by @code{\end@{picture@}} (in +@LaTeX{}, this package is not explicitly loaded since it is part of +the @LaTeX{} kernel). It provides commands to draw simple figures +inside your document without resorting to any external tools. + +@item color (@samp{1999/02/16 v1.0i Standard LaTeX Color (DPC)}) +@pindex color.sty +@itemx graphics (@samp{2001/07/07 v1.0n Standard LaTeX Graphics (DPC,SPQR)}) +@pindex graphics.sty +@itemx graphicx (@samp{1999/02/16 v1.0f Enhanced LaTeX Graphics (DPC,SPQR)}) +@pindex graphicx.sty +@url{http://www.ctan.org/tex-archive/macros/latex/required/graphics/grfguide.pdf} + +@cindex graphics collection, @LaTeX{} +@cindex @LaTeX{} graphics collection +@cindex color +@cindex rotation +@cindex scaling +These packages are from the @LaTeX{} graphics collection. They +provide commands for changing text/page colors, text rotation and +scaling, and much more. + +@item psfrag (@samp{1998/04/11 v3.04 PSfrag (MCG)}) +@pindex psfrag.sty +@url{http://www.ctan.org/tex-archive/macros/latex/contrib/psfrag/pfgguide.pdf} + +@cindex Encapsulated PostScript +@cindex EPS +@pindex .eps @r{files} +PSfrag allows the user to precisely overlay Encapsulated PostScript +(EPS) files with arbitrary (La)@TeX{} constructions. In order to +accomplish this, the user places a simple text ``tag'' in the graphics +file, as a ``position marker'' of sorts. Then, using simple +(La)@TeX{} commands, the user instructs PSfrag to remove that tag from +the figure, and replace it with a properly sized, aligned, and rotated +(La)@TeX{} equation. + +@item url (@samp{2005/06/27 ver 3.2 Verb mode for urls, etc.}) +@pindex url.sty +@url{http://www.ctan.org/tex-archive/macros/latex/contrib/misc/url.sty} + +@cindex pathnames, breaking +@cindex filenames, breaking +@cindex electronic mail addresses, breaking +This package provides a form of @code{\verbatim} that allows +line breaks at certain characters or combinations of characters, +accepts reconfiguration, and can usually be used in the argument to +another command. It is intended for email addresses, hypertext links, +directories/paths, etc., which normally have no spaces. + +Eplain can create hypertext links with the @code{\url} command; +@pxref{URL hyperlinks}. +@end table + + +@node Packages known not to work +@subsection Packages known not to work + +@cindex @LaTeX{} packages +@cindex packages, @LaTeX{} +The following packages are known not to work with Eplain: + +@table @asis +@item pict2e (@samp{2005/07/15 v0.2r Improved picture commands (HjG,RN)}) +@pindex pict2e.sty +@url{http://www.ctan.org/tex-archive/macros/latex/contrib/pict2e/} + +@item xcolor (@samp{2005/06/06 v2.03 LaTeX color extensions (UK)}) +@pindex xcolor.sty +@url{http://www.ctan.org/tex-archive/macros/latex/contrib/xcolor/} +@end table -- cgit v1.2.3