From 7ff51640e2fd3e968488d312879dee70458f2926 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 8 Dec 2006 00:25:19 +0000 Subject: eplain 3.1 (5dec06) git-svn-id: svn://tug.org/texlive/trunk@2630 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/eplain/AUTHORS | 12 + Master/texmf-dist/doc/eplain/COPYING | 340 + Master/texmf-dist/doc/eplain/ChangeLog | 2268 +++++++ Master/texmf-dist/doc/eplain/INSTALL | 46 + Master/texmf-dist/doc/eplain/NEWS | 141 + Master/texmf-dist/doc/eplain/PROJECTS | 18 + Master/texmf-dist/doc/eplain/README | 50 + 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 670226 -> 0 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 -------- Master/texmf-dist/doc/eplain/demo/Makefile | 41 + Master/texmf-dist/doc/eplain/demo/lscommnt.tex | 47 + Master/texmf-dist/doc/eplain/demo/xhyper.tex | 190 + Master/texmf-dist/doc/eplain/doc/eplain.html | 8078 ++++++++++++++++++++++++ Master/texmf-dist/doc/eplain/doc/eplain.info | 7863 +++++++++++++++++++++++ Master/texmf-dist/doc/eplain/doc/eplain.pdf | Bin 0 -> 895977 bytes Master/texmf-dist/doc/eplain/doc/lscommnt.jpg | Bin 0 -> 68549 bytes Master/texmf-dist/doc/eplain/doc/xhyper.jpg | Bin 0 -> 14118 bytes Master/texmf-dist/doc/eplain/util/idxuniq | 37 + Master/texmf-dist/doc/eplain/util/trimsee | 106 + 39 files changed, 19237 insertions(+), 16724 deletions(-) create mode 100644 Master/texmf-dist/doc/eplain/AUTHORS create mode 100644 Master/texmf-dist/doc/eplain/COPYING create mode 100644 Master/texmf-dist/doc/eplain/ChangeLog create mode 100644 Master/texmf-dist/doc/eplain/INSTALL create mode 100644 Master/texmf-dist/doc/eplain/NEWS create mode 100644 Master/texmf-dist/doc/eplain/PROJECTS create mode 100644 Master/texmf-dist/doc/eplain/README delete mode 100644 Master/texmf-dist/doc/eplain/base/AUTHORS delete mode 100644 Master/texmf-dist/doc/eplain/base/COPYING delete mode 100644 Master/texmf-dist/doc/eplain/base/ChangeLog delete mode 100644 Master/texmf-dist/doc/eplain/base/INSTALL delete mode 100644 Master/texmf-dist/doc/eplain/base/Makefile delete mode 100644 Master/texmf-dist/doc/eplain/base/NEWS delete mode 100644 Master/texmf-dist/doc/eplain/base/PROJECTS delete mode 100644 Master/texmf-dist/doc/eplain/base/README delete mode 100644 Master/texmf-dist/doc/eplain/base/arrow.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/btxdoc.bib delete mode 100644 Master/texmf-dist/doc/eplain/base/btxdoc.tex delete mode 100644 Master/texmf-dist/doc/eplain/base/csindex.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/eplain.html delete mode 100644 Master/texmf-dist/doc/eplain/base/eplain.pdf delete mode 100644 Master/texmf-dist/doc/eplain/base/eplain.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/hlink.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/index.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/install.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/intro.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/invoke.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/progdef.texi delete mode 100644 Master/texmf-dist/doc/eplain/base/userdef.texi create mode 100644 Master/texmf-dist/doc/eplain/demo/Makefile create mode 100644 Master/texmf-dist/doc/eplain/demo/lscommnt.tex create mode 100644 Master/texmf-dist/doc/eplain/demo/xhyper.tex create mode 100644 Master/texmf-dist/doc/eplain/doc/eplain.html create mode 100644 Master/texmf-dist/doc/eplain/doc/eplain.info create mode 100644 Master/texmf-dist/doc/eplain/doc/eplain.pdf create mode 100644 Master/texmf-dist/doc/eplain/doc/lscommnt.jpg create mode 100644 Master/texmf-dist/doc/eplain/doc/xhyper.jpg create mode 100644 Master/texmf-dist/doc/eplain/util/idxuniq create mode 100644 Master/texmf-dist/doc/eplain/util/trimsee (limited to 'Master/texmf-dist/doc/eplain') diff --git a/Master/texmf-dist/doc/eplain/AUTHORS b/Master/texmf-dist/doc/eplain/AUTHORS new file mode 100644 index 00000000000..391c66f94a3 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/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 and pdfcrop.pl. +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/COPYING b/Master/texmf-dist/doc/eplain/COPYING new file mode 100644 index 00000000000..3912109b5cd --- /dev/null +++ b/Master/texmf-dist/doc/eplain/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/ChangeLog b/Master/texmf-dist/doc/eplain/ChangeLog new file mode 100644 index 00000000000..d11f45da276 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/ChangeLog @@ -0,0 +1,2268 @@ +2006-12-03 Oleg Katsitadze + + * Makefile, doc/eplain.info, doc/eplain.pdf, doc/eplain.texi, eplain.tex: + Version 3.1. + + * doc/intro.texi: Added link to the TUGboat article. + + * NEWS: Reduced news for 3.1 a bit (it was way too long). + + * doc/hlink.texi, doc/invoke.texi, doc/progdef.texi, doc/userdef.texi: + Formatting (mostly empty lines around @example's, @noindent's + afterwards). + +2006-12-01 Oleg Katsitadze + + * Makefile, README.TDS: + Removed texmf/ prefix from the TDS dirs in the distro. + + * doc/eplain.texi, doc/progdef.texi (Iteration): Updated node comment. + + * Makefile: Put scripts in the doc/ within the distro. + + * doc/userdef.texi (Customizing indexing): + trimsee is in util/, not test/. + + * NEWS: News for the upcoming Eplain 3.1. + +2006-11-29 Oleg Katsitadze + + * xeplain.tex (idxargopen, idxargclose): Removed obsolete comment. + + * doc/userdef.texi: Added index terms for verbatim text in TOC + and index. (Writing the .toc file): Better rationale for + \writenumberedtocline. + + * doc/progdef.texi (Iteration): + Documented \loop (with the \else extension). + + * doc/userdef.texi (Packages known to work): Added soul.sty. + +2006-11-28 Oleg Katsitadze + + * doc/userdef.texi (Packages known not to work): Added hyperref.sty. + + * doc/demo.texi, doc/hlink.texi, doc/install.texi, doc/intro.texi, doc/userdef.texi, doc/invoke.texi: + Added breaks (@/) to @url's. + + * doc/eplain.texi, doc/userdef.texi (Index entries with special characters): + New node. + + * test/for.tex: New file. + + * doc/progdef.texi (Iteration): Documented \For. Correction + about expanding the first token of item list, not the entire + list. + + * xeplain.tex (For): Modified to ignore _all_ leading spaces of + the items, not just the first space. + + * test/href.tex: Added a "weird chars" test. + + * doc/hlink.texi, doc/invoke.texi, doc/userdef.texi: + Added a bunch of @acronym's. + + * doc/hlink.texi (Explicit hyperlinks): Note on special chars in + the label argument. + + * doc/eplain.texi, doc/hlink.texi (General hyperlinks): New node. + + * doc/progdef.texi (\ifinteger and \isinteger): Minor correction. + +2006-11-09 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-10-05 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-10-04 Oleg Katsitadze + + * doc/hlink.texi (Link types for hypertex, Link types for pdftex + and dvipdfm): Moved url link types toward beginnings of the + subsections. + + * doc/progdef.texi: Minor correction. + + * test/usepackage.tex: Test for LaTeX package reloading. + + * eplain.tex, xeplain.tex (\usepkg@load@pkg): When reloading + LaTeX packages, warn and skip reloading, instead of giving an + error. + + * test/href.tex: New file. + + * doc/invoke.texi: Removed the note on touch'ing the .aux file + before running texi2dvi, texi2dvi can deal with this since + revision 1.90. (BTW, the problem was not with cross-references + but with citations.) + +2006-09-30 Oleg Katsitadze + + * doc/eplain.texi: Updated the master menu. + + * doc/invoke.texi: Note on touch'ing the .aux file before running + texi2dvi. + + * doc/userdef.texi (Contents): Split into subsections. Documented + \writenumberedtocline. Documented integer @var{part} arguments. + + * doc/progdef.texi (\ifinteger and \isinteger): New subsection. + +2006-09-27 Oleg Katsitadze + + * doc/eplain.texi: Added nodes for "Loading LaTeX packages" to + the master menu. + + * doc/userdef.texi (Verbatim listing): Documented + \nolastlinelisting and C-l (form feed). + +2006-09-25 Oleg Katsitadze + + * eplain.tex, xeplain.tex (xrdef): Bug fix--\ignorespaces from + \definexref was masked off by \endgroup's. + + * test/xkvtest.tex: New file. + +2006-08-27 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-08-08 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-07-15 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-06-19 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-06-02 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-05-29 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-05-07 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-05-07 Oleg Katsitadze + + * eplain.tex, test/contents.tex, xeplain.tex (writenumberedcontentsline): + New macro. + +2006-05-05 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-05-02 Oleg Katsitadze + + * eplain.tex, test/indexvrb.tex, xeplain.tex: Simplified + embedding `{' and `}' into index terms by managing catcodes of + \idxargopen and \idxargclose internally. Allow \verbatim inside + arguments of \indexsee and \indexseealso by reading their + arguments verbatim and then \scantokens'ing. + + * doc/demo.texi, doc/eplain.info, doc/eplain.pdf, doc/eplain.texi, doc/hlink.texi, doc/userdef.texi: + Added the lscommnt.tex demo, tweaked some index terms. + + * doc/progdef.texi (Category codes): \makeactive`\\ -> \makeactive\\. + + * doc/userdef.texi (Packages known to work): Added warnings about + supp-mis.tex and \pagecolor (pdftex.def). + +2006-05-01 Oleg Katsitadze + + * eplain.ini: New file (used by TeX Live to generate .fmt file). + + * Makefile: Generate TDS-compliant distro. Added PDF and HTML to + the distro. + (eplain.tex): Updated location of mkdist-merge. + + * doc/Makefile: Updated location of pdfcrop.pl. Use `-quality + 75' option to convert to reduce image sizes. Added lscommnt demo. + (eplain/index.html): Copy images to eplain/ instead of symlinking. + (clean, mostlyclean): Don't delete JPEG images, they are in the + distro. + (distclean): Don't delete PDF and HTML, they are in the distro. + + * README.TDS: New file (README at the top of the distro tarball). + + * add-date, add-version, fix-checksum, merge, pdfcrop.pl, util/mkdist-add-date, util/mkdist-add-version, util/mkdist-fix-checksum, util/mkdist-merge, util/pdfcrop.pl: + Moved the support scripts to util/. + + * demo/Makefile, demo/lscommnt.pdf, demo/lscommnt.tex: + New demo (listings with highlighted comments). + + * test/dvipdfm.tex, test/epstopdf.tex, test/hlcite.tex, test/hlfoot.tex, test/hlidx.mst, test/hlidx.tex, test/hlink.tex, test/hypertex.tex, test/indexvrb.tex, test/pdftex.tex, test/soultest.tex, test/xrefwarn.tex: + Added `public domain' header. + +2006-04-30 Oleg Katsitadze + + * test/listing.tex: Added test for the \nolastlinelisting hook. + * xeplain.tex (nolastlinelisting): New listing hook to omit the + last (empty) line of the file. + + * xeplain.tex (@removebox): Preserve \box0 and use it instead of + the constructed \box2, since the latter does not preserve the + effect of a possible \hbox to 0pt (produced by, e.g., \llap). + + * test/contents.tex: Test for integer PARTs (\tocentry). + * xeplain.tex (ifinteger,isinteger): New macros. + (writenumberedcontentsentry): When PART argument is an integer, + write \tocentry{PART}... to the .toc file. + + * test/indexvrb.tex: New file. + * xeplain.tex: Indexing macros now read TERM and SUBTERM + arguments verbatim, to allow catcode changes within the + arguments. + +2006-04-23 Oleg Katsitadze + + * xeplain.tex (hlidx, hlidxpage): Do not rely on a CS with the + empty name to be undefined, instead check PAGEENCAP parameter + explicitly. + +2006-04-19 Oleg Katsitadze + + * xeplain.tex (@@href): Got rid of \@hrefhash, made \hlhash + equivalent to \@hrefhash. + +2006-04-17 Oleg Katsitadze + + * xeplain.tex (hldriver@pdftex, hldriver@dvipdfm): + Removed spurious spaces in \special's. + +2006-04-13 Oleg Katsitadze + + * eplain.tex, xeplain.tex (href): New macro. + +2006-04-12 Oleg Katsitadze + + * xeplain.tex (hl@getparam): Allow special chars (like # and ~) + in the LABEL argument (for URLs). + + * doc/hlink.texi: Wrapped some long option lists. + + * xeplain.tex: New \For loop, use it in hyperlink macros instead + of \for. + +2006-04-09 Oleg Katsitadze + + * doc/hlink.texi: Index terms. + +2006-04-09 Karl Berry + + * doc/hlink.texi: xref for \hldest. + +2006-03-30 Oleg Katsitadze + + * doc/hlink.texi (URL hyperlinks: url): Note on automatic link + coloring. + +2006-03-26 Oleg Katsitadze + + * test/hlidx.tex: Minor formatting. + + * xeplain.tex: Don't use xrefs for defining index page anchors, + to avoid messages about redefined xref labels. + + * test/hlfoot.tex: Select `pdftex' driver by default. + * test/dvipdfm.tex: Update: `dvipdfm' now is not the default driver. + + * xeplain.tex: Made all user-visible \hl* macros report errors + until hyperlinks are enabled. + + * eplain.tex, xeplain.tex (@fineqrefn): + Bugfix: \hlend -> \hlend@impl{eq}. + + * test/xrefwarn.tex: New file. + * xeplain.tex: Added warnings about multiply defined xref labels + (from Tomas Penicka ). + +2006-03-25 Oleg Katsitadze + + * doc/userdef.texi (Environment for loading packages): + More details on \eplaininput. + * doc/userdef.texi (Packages known to work): \ttfamily. + * xeplain.tex: Correct definition of \ttfamily. + + * doc/userdef.texi (Packages known to work): epstopdf.sty. + * test/epstopdf.tex: New file. + + * demo/Makefile (xhyper.pdf): Added prerequisites. + (maintainer-clean): New rule. + * demo/xhyper.tex: graphics.sty -> graphicx.sty. + + * doc/hlink.texi, doc/userdef.texi: + References to the `Demo files' section. + + * doc/hlink.texi, test/hlfoot.tex, xeplain.tex: + Footnote hyperlinks are now off by default. + + * doc/hlink.texi (URL hyperlinks: url): Older url.sty's do not work. + + * doc/userdef.texi (Environment for loading packages): + \eplaininput, \packageinput + * xeplain.tex (\beginpackages): \eplain@input -> \eplaininput. + + * doc/userdef.texi (Packages known to work): + Older versions of url.sty not working in plain TeX. + +2006-03-22 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-03-15 Oleg Katsitadze + + * doc/userdef.texi: Parenthesized the @pxref refs. + + * doc/userdef.texi: Punctuation. + + * doc/eplain.texi, doc/hlink.texi: Added doc on the hypertex driver. + + * test/hypertex.tex: New file. + + * xeplain.tex: + More defs for LaTeX: the `draft' option to graphic{s,x}.sty; and + warnings from epstopdf.sty when graphics.sty is not loaded. + + * xeplain.tex: + Bugfix: the `nolinks' driver now redefines \hl@setparam so that + the macros \hldesttype, \hldestopts, \hltype and \hlopts avoid + error messages about "unknown" options and types. + + * xeplain.tex: Added hypertex driver. + +2006-03-14 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-02-24 Oleg Katsitadze + + * test/soultest.tex: New file. + +2006-02-14 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-01-27 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2006-01-13 Karl Berry + + * doc/.cvsignore: . + + * doc/eplain.texi, ChangeLog, doc/Makefile, doc/eplain.info, doc/eplain.pdf: + move contents + +2006-01-12 Karl Berry + + * doc/eplain.texi: move @contents to front; also include + @shortcontents. + * doc/Makefile (eplain/index.html): don't try to create links if + they already exist. + * doc/.cvsignore: ignore links, etc. + And upload to lulu ... + +2006-01-06 Oleg Katsitadze + + * doc/progdef.texi (\ifempty): New subsection. + +2006-01-05 Oleg Katsitadze + + * doc/intro.texi: Reference to David Walden's article. + + * INSTALL, doc/install.texi: Removed info on etex.fmt and emtex. + Updated recommended installation locations. + + * doc/eplain.texi: Added variable index (for environment vars in + install.texi) and redirected program and variable indices into + concept index. + + * Makefile: Removed etex.tex. + * etex.tex: Removed. + + * xeplain.tex: Improved hyperlink messages. + + * doc/Makefile: Use texi2dvi --pdf instead of texi2pdf. + + * xeplain.tex (beginpackages): Save and restore \input to avoid + redefinition by miniltx.tex and packages (\packageinput stores the + redefinition). + + * test/usepackage.tex: Added \enablehyperlinks (this test depends + on hyperlinks being enabled). Added test for \urldef from + url.sty. + + * xeplain.tex: Added \protected@edef for \urldef from url.sty. + (hldriver@nolinks): The label argument to \hlstart and \hldest + must be passed to \write-1 _fully expanded_, otherwise macros that + the label uses may become redefined/undefined by the time the page + is shipped out and the \write is executed (this resulted in URLs + defined with \urldef to fail under the nolinks driver). + (@generalref): Use \@generalref@class instead of \temp, since + \@generalrefoptarg can possibly trash \temp. + +2005-12-26 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2005-12-23 Oleg Katsitadze + + * doc/userdef.texi: Changed location of ltpictur.pdf. + +2005-12-21 Oleg Katsitadze + + * demo/.cvsignore, demo/ctan_lion_350x350.png, demo/xhyper.pdf: + Image for the xhyper.tex demo and the output. + + * doc/Makefile: + Added rules for creating JPG images from the demos (for the html + docs). + +2005-12-20 Oleg Katsitadze + + * doc/userdef.texi (Contents): Tell that \writetocentry reads + \tocfilebasename only once. + (Tables): Corrected stale link to lifshitz.ph.utexas.edu. + (Packages known to work): Added link to Klaus Hoeppner's article + on LaTeX graphics. + + * demo/xhyper.tex: + Input ../eplain instead of eplain, in case Eplain is not (yet) + properly installed. + + * doc/Makefile: + Added _FLAG variables for each program used. Split targets like + `pdf eplain.pdf' and made pdf depend on eplain.pdf, etc. (otherwise + `make pdf' always rebuilds eplain.pdf). Added rules and dependencies + for the demo file images. + (ps): New target. + + * Makefile: + Added demo subdir. Changed all calls to Make to use $(MAKE). + (ps): New target. + + * pdfcrop.pl, demo/Makefile, doc/demo.texi: New files. + + * AUTHORS: Added pdfcrop.pl. + + * demo/xhyper.tex (Top comment): + \, only works in math mode in plain TeX (unlike in tugboat + format). + + * doc/hlink.texi (URL hyperlinks): + Showed how to have colored links instead of boxed links. + (Footnote hyperlinks): Showed how to turn off footnote hyperlinks. + (Hyperlink driver nolinks): Showed the proper way to + \enablehyperlinks for the dual links/nolinks output. + (Setting default types and options): Example of how to turn off + boxes for the links. + + * doc/eplain.texi: Changed the title. Included demo.texi. + +2005-12-14 Oleg Katsitadze + + * demo/xhyper.tex: New file. + +2005-10-11 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2005-10-09 Karl Berry + + * doc/texinfo.tex: update from texinfo + +2005-09-25 Oleg Katsitadze + + * Makefile, doc/Makefile: Remove intermediate files from the + tarball. NOTE: It was agreed not to include aux, toc, and index + files into the tarball, because if the user compiles the manual + with the command `tex eplain.texi' for a different paper size + (specified, e.g., in texinfo.cnf), then the references, TOC and + indexes will be off without the user knowing about it. + +2005-09-23 Oleg Katsitadze + + * Makefile: + Added intermediate files (aux, toc, ??, ??s) to MANUALS so that + they are included in the tarball (later reverted, see above). + + * doc/Makefile: + (clean): Leave intermediate files (aux, toc, ??, ??s) in tarballs + so users can easily compile docs (later reverted, see above). + (distclean): Remove eplain.html. + (maintainer-clean): Remove the intermediate files. + (html): Build also --no-split doc. + + * Version 3.0 (released 2005-09-20) + + * Makefile: Added test/*.eps to the list of test files. + +2005-09-20 Oleg Katsitadze + + * eplain.tex, Makefile, NEWS, doc/eplain.info, doc/eplain.pdf, doc/eplain.texi: + Version number update. + + * doc/Makefile (info): Added --no-split option. + + * 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/INSTALL b/Master/texmf-dist/doc/eplain/INSTALL new file mode 100644 index 00000000000..dcd705281b6 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/INSTALL @@ -0,0 +1,46 @@ +Installation +************ + +Your TeX installation should already contain a version of Eplain +(`eplain.tex') in its main `texmf' tree (usually under +`/usr/share/texmf/tex/eplain/' on Unix systems). To install a newer +version of Eplain, put the new `eplain.tex' (included in Eplain +distributions) in the `tex/eplain/' subdirectory of your local `texmf' +tree. The newer version you install in the local tree should override +the older one in the main tree. + + The location of the local `texmf' tree obviously depends on your +operating system and TeX installation. On Unix systems the usual +location is `/usr/local/share/texmf/'. If you don't have write +permissions for `/usr/local/share/texmf/', many installations read the +`texmf' tree in the user's home directory; `eplain.tex' then should go +under `~/texmf/tex/eplain/'. For more information about TeX directory +structure, please see +`http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds'. + + If you prefer to install `eplain.tex' in a non-standard place, set +an environment variable (`TEXINPUTS' for the Web2C port of TeX to Unix) +to tell TeX how to find it. + + 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 your local +`texmf' tree or set an environment variable to tell TeX how to find it. +For the Web2C port of TeX to Unix, format files are usually installed +under `/usr/local/share/texmf/web2c/' or `/var/lib/texmf/web2c/'; the +environment variable is `TEXFORMATS'. + diff --git a/Master/texmf-dist/doc/eplain/NEWS b/Master/texmf-dist/doc/eplain/NEWS new file mode 100644 index 00000000000..ac08de2a900 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/NEWS @@ -0,0 +1,141 @@ +This file records noteworthy changes. This file is public domain. + +3.1 (3 December 2006) + +General: +* Rearranged the distro to comply with TDS. +* Distro now includes PDF, HTML and INFO versions of the manual. +* Removed etex.tex. + +LaTeX packages under Eplain: +* When reloading LaTeX packages, warn and skip reloading, instead of + giving an error. Suggested by Dan Luecking. +* The primitive \input is now restored after loading LaTeX packages. +* Added more "LaTeX" defs needed by: the `draft' option to + graphic{s,x}.sty; warnings from epstopdf.sty when graphics.sty is + not loaded. + +Hyperlinks: +* Added the `hypertex' driver, and made it the default driver. +* Made footnote hyperlinks off by default. +* Added the \href macro. Suggested by Dorai Sitaram. +* LABEL argument of the hyperlink macros now allow special characters + like # and ~ (useful for URLs). Suggested by Dorai Sitaram. +* Fixed a hyperlink-related bug in equation macros. +* Fixed a bug in the `nolinks' driver. +* Added \writenumberedtocline macro, which is \writenumberedtocentry + with permuted parameters. Suggested by Dorai Sitaram. +* Hyperlink macros now ignore leading spaces in option lists. +* All hyperlink macros now report errors until links are enabled. + +Cross-references, TOC and indexing: +* Added warnings about multiply defined xref labels. Suggested by + Tomas Penicka. +* Fixed \definexref to (once again) ignore following spaces. +* Indexing macros now read TERM, SUBTERM and SEE... arguments + verbatim, to allow special characters and catcode changes. + Suggested by Dorai Sitaram. +* Extended the TOC macros: when given an integer for the type of a + TOC entry, they write \tocentry{NUM}... to the .toc file. Suggested + by Dorai Sitaram. + +Programming defs: +* Added \ifinteger and \isinteger macros. +* Added \For loop which strips off leading spaces from items. + +Manual: +* Added demo subdir with demo files, and added new chapter `Demo + files' to the manual. +* Documented \ifempty, the extended \loop macro, and the new macros. +* Many small improvements and additions to the manual. + +Other: +* Added new \nolastlinelisting listing hook which omits the last + (empty) line of the file. + + +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/PROJECTS b/Master/texmf-dist/doc/eplain/PROJECTS new file mode 100644 index 00000000000..d24baf64c58 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/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/README b/Master/texmf-dist/doc/eplain/README new file mode 100644 index 00000000000..9ec64791292 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/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/AUTHORS b/Master/texmf-dist/doc/eplain/base/AUTHORS deleted file mode 100644 index b44969727ac..00000000000 --- a/Master/texmf-dist/doc/eplain/base/AUTHORS +++ /dev/null @@ -1,12 +0,0 @@ -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 deleted file mode 100644 index 3912109b5cd..00000000000 --- a/Master/texmf-dist/doc/eplain/base/COPYING +++ /dev/null @@ -1,340 +0,0 @@ - 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 deleted file mode 100644 index 8b875392f07..00000000000 --- a/Master/texmf-dist/doc/eplain/base/ChangeLog +++ /dev/null @@ -1,1750 +0,0 @@ -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 deleted file mode 100644 index 3a514ae606b..00000000000 --- a/Master/texmf-dist/doc/eplain/base/INSTALL +++ /dev/null @@ -1,51 +0,0 @@ -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 deleted file mode 100644 index 6ff999f6a73..00000000000 --- a/Master/texmf-dist/doc/eplain/base/Makefile +++ /dev/null @@ -1,97 +0,0 @@ -# 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 deleted file mode 100644 index 2b7f9364d7c..00000000000 --- a/Master/texmf-dist/doc/eplain/base/NEWS +++ /dev/null @@ -1,87 +0,0 @@ -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 deleted file mode 100644 index d24baf64c58..00000000000 --- a/Master/texmf-dist/doc/eplain/base/PROJECTS +++ /dev/null @@ -1,18 +0,0 @@ -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 deleted file mode 100644 index 9ec64791292..00000000000 --- a/Master/texmf-dist/doc/eplain/base/README +++ /dev/null @@ -1,50 +0,0 @@ -(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 deleted file mode 100644 index c5d4786cef3..00000000000 --- a/Master/texmf-dist/doc/eplain/base/arrow.texi +++ /dev/null @@ -1,781 +0,0 @@ -@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 deleted file mode 100644 index 4eaf3eddc56..00000000000 --- a/Master/texmf-dist/doc/eplain/base/btxdoc.bib +++ /dev/null @@ -1,90 +0,0 @@ -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 deleted file mode 100644 index 52723e08b69..00000000000 --- a/Master/texmf-dist/doc/eplain/base/btxdoc.tex +++ /dev/null @@ -1,1117 +0,0 @@ -% 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 deleted file mode 100644 index f80b7058979..00000000000 --- a/Master/texmf-dist/doc/eplain/base/csindex.texi +++ /dev/null @@ -1,6 +0,0 @@ -@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 deleted file mode 100644 index 638a3492141..00000000000 --- a/Master/texmf-dist/doc/eplain/base/eplain.html +++ /dev/null @@ -1,6644 +0,0 @@ - - -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. - -

- - - -

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. - -

- - - -

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. - -

- -

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. - -

- - - -

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. - -

- -

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. - -

- -

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. -

- - - -

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 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. - -

- - - -

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. - -

- -

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. - -

- -

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. - -

- -

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. - -

- -

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. - -

- - - -
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). - -

- -
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). - -

- -
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”). - -

- -
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. - -

- -
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. - -

- -

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. - -

- - - -

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}
-     
-
- - - -

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. - -

- - - -
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
-     
-
- - - -
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}
-     
-
- - - -
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 -

- - - -
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
-     
-
- - - -

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. - -

- - - -

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. - -

- -

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. - -

- -

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. - -

- - - -

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. - -

- -

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). - -

- - - -

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. - -

- -

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. - -

- - - -

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. - - -

- -

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. - -

- -

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. - -

- - - -

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
-         ...
-       }%
-
- - -

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.) - - -

- -

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.) - -

- -

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
-
- - -

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. - -

- -

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 deleted file mode 100644 index 099777a3115..00000000000 Binary files a/Master/texmf-dist/doc/eplain/base/eplain.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/eplain/base/eplain.texi b/Master/texmf-dist/doc/eplain/base/eplain.texi deleted file mode 100644 index 4b54e8160ea..00000000000 --- a/Master/texmf-dist/doc/eplain/base/eplain.texi +++ /dev/null @@ -1,228 +0,0 @@ -\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 deleted file mode 100644 index 083bfa99fac..00000000000 --- a/Master/texmf-dist/doc/eplain/base/hlink.texi +++ /dev/null @@ -1,1860 +0,0 @@ -@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 deleted file mode 100644 index 7543633094d..00000000000 --- a/Master/texmf-dist/doc/eplain/base/index.texi +++ /dev/null @@ -1,7 +0,0 @@ -@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 deleted file mode 100644 index 10cc42057ef..00000000000 --- a/Master/texmf-dist/doc/eplain/base/install.texi +++ /dev/null @@ -1,65 +0,0 @@ -@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 deleted file mode 100644 index 00ccc5ad313..00000000000 --- a/Master/texmf-dist/doc/eplain/base/intro.texi +++ /dev/null @@ -1,71 +0,0 @@ -@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 deleted file mode 100644 index b412c64a57b..00000000000 --- a/Master/texmf-dist/doc/eplain/base/invoke.texi +++ /dev/null @@ -1,144 +0,0 @@ -@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 deleted file mode 100644 index 4169f151730..00000000000 --- a/Master/texmf-dist/doc/eplain/base/progdef.texi +++ /dev/null @@ -1,768 +0,0 @@ -@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 deleted file mode 100644 index dfc5fcc4497..00000000000 --- a/Master/texmf-dist/doc/eplain/base/userdef.texi +++ /dev/null @@ -1,2538 +0,0 @@ -@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 diff --git a/Master/texmf-dist/doc/eplain/demo/Makefile b/Master/texmf-dist/doc/eplain/demo/Makefile new file mode 100644 index 00000000000..45ba215c7aa --- /dev/null +++ b/Master/texmf-dist/doc/eplain/demo/Makefile @@ -0,0 +1,41 @@ +# Makefile for the Eplain demos. This file is public domain. + +PDFTEX = pdftex +DVIPDFM = dvipdfmx +TEXI2PDF = texi2dvi --pdf + + +.PHONY: all pdftex dvipdfm dvips mostlyclean clean distclean maintainer-clean + + +all: pdftex dvipdfm dvips + +# +# Documents which have to be processed with pdfTeX. +# +pdftex: xhyper.pdf lscommnt.pdf + +xhyper.pdf: xhyper.tex ctan_lion_350x350.png + PDFLATEX=$(PDFTEX) $(TEXI2PDF) xhyper.tex + +lscommnt.pdf: lscommnt.tex + PDFLATEX=$(PDFTEX) $(TEXI2PDF) lscommnt.tex + +# +# Documents which have to be processed with dvipdfm(x). +# +dvipdfm: + +# +# Documents which have to be processed with dvips. +# +dvips: + + +clean mostlyclean: + rm -f xhyper.{aux,log} lscommnt.log + +distclean: clean + rm -f xhyper.pdf lscommnt.pdf + +maintainer-clean: distclean diff --git a/Master/texmf-dist/doc/eplain/demo/lscommnt.tex b/Master/texmf-dist/doc/eplain/demo/lscommnt.tex new file mode 100644 index 00000000000..26d3ec76164 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/demo/lscommnt.tex @@ -0,0 +1,47 @@ +% (This file is public domain.) +% Demonstrate how Eplain can be used to include a TeX source file +% verbatim, typesetting comments in colored italic typewriter type. + +% Load Eplain and LaTeX's color.sty package. +\input eplain +\beginpackages \usepackage{color} \endpackages +\nopagenumbers % Disable page numbers. +\font\commentfont = cmitt10 % Font for the comments (italic \tt). +% We'll define some `protected' macros with `@' in their names. +\makeatletter +% Define an equivalent of Eplain's \letreturn, to be able to assign +% various actions to the (active) percent character. +\begingroup \makeactive\% + \gdef\letpercent{\let%} +\endgroup +% The listing hook to be called in \setuplistinghook, see below. It +% makes `%' active and assigns it a `start comment' action. +\def\hlightcommentslisting{\makeactive\% \letpercent\start@comment}% +% This is what `%' is aliased to before a comment is started. +\def\start@comment{% + \leavevmode % Needed in the very first line of the input to process + % the new par (possibly inserting line number) before we + % kick in with the color and stuff. + \begingroup % Isolate color and font changes and the redefinitions. + \commentfont + \color[cmyk]{0.28,1,1,0.35}% + \percentchar % Produce the actual `%' and + \letpercent\percentchar % make all following `%'s do the same. + \letreturn\end@comment % Call \end@comment at end-of-line. +} +% \end@comment (alias for ^^M inside a comment) will end the comment +% started by \start@comment. We make ^^M active temporarily so that +% the active version of ^^M gets "frozen" into \end@comment. +\begingroup \makeactive\^^M % Avoid ^^M's from here on. + \gdef\end@comment{\endgroup ^^M}% +\endgroup +\resetatcatcode % Make `@' again inaccessible for use in macro names. + +% Define \setuplistinghook to setup comments highlighting, line +% numbering and omitting the last (empty) line of input. +\def\setuplistinghook{\hlightcommentslisting \linenumberedlisting + \nolastlinelisting} +% Isn't this fun? This file typesets itself, with the extra bonus of +% the pretty-printed comments and numbered source lines! +\listing{lscommnt} +\bye diff --git a/Master/texmf-dist/doc/eplain/demo/xhyper.tex b/Master/texmf-dist/doc/eplain/demo/xhyper.tex new file mode 100644 index 00000000000..54742cb50b5 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/demo/xhyper.tex @@ -0,0 +1,190 @@ +% (This file is public domain.) +% +% This file demonstrates the following features of Eplain: +% +% - explicit and implicit hyperlinks; +% - symbolic cross-references; +% - inserting external graphics using |\includegraphics| from +% the \LaTeX\ package |graphicx.sty|. +% - rotating text using |\rotatebox| from |graphicx.sty|. +% +% The compiled demo can be downloaded from +% +% http://tug.org/eplain/demo +% +% In order to compile this file yourself, you will need the CTAN lion +% drawing by Duane Bibby from +% +% ftp://tug.ctan.org/ftpmaint/CTAN_lion/ctan_lion_350x350.png +% +% (thanks, |www.ctan.org|). Place the image file in the same +% directory with this file, and change to that directory. Now, to +% produce a PDF, run twice the command +% +% pdftex xhyper.tex +% +% During the first run, Eplain will write the information about the +% cross-references into |xhyper.aux|, and during the second run this +% information will be read by Eplain to typeset the references. +% +% Demo case: +% +% Suppose you are using pdf\TeX, have a figure you want to insert +% scaled to $200\,pt$ horizontally, and you want this figure to +% completely fill the PDF viewer's window whenever the reader +% selects a link pointing to this figure. Additionally, you want to +% typeset some text as live hyperlinks, clicking on which will start +% a Web browser and open a URL. + +\input eplain + +% Load \LaTeX\ packages. +\beginpackages + % |url.sty| provides the |\url| command which we will use to typeset + % a URL. We request that |url.sty| be the version from June~27, + % 2005, or later, because earlier versions had problems interacting + % with plain \TeX. + \usepackage{url}[2005/06/27] + % |color.sty| provides support for colored text; all hyperlinks are + % automatically colored by Eplain when this package is loaded. We give + % the |dvipsnames| option because we want to use named colors from the + % |dvips| graphics driver. + \usepackage[dvipsnames]{color} + % Finally, we load |graphicx.sty|, for the macros |\includegraphics| + % and |\rotatebox|. + \usepackage{graphicx} +\endpackages + +% Remember that hyperlinks are off by default. Therefore, we need to +% enable them. +\enablehyperlinks + +% Customize some hyperlink options. First, we set border width to~$0$ +% for all links to get rid of the default boxes around links (we +% prefer colored links over the boxed links). Next, we say that all +% links created by the |url| hyperlink group (which means the |\url| +% command from |url.sty|) must be colored using the named color +% |BlueViolet|. +\hlopts{bwidth=0} +\hlopts[url]{colormodel=named,color=BlueViolet} + +% Inhibit page numbering (we have only one page). +\nopagenumbers + +% Define a class word for the cross-reference class |figure|. This +% word, when defined, will be automatically prepended by Eplain to the +% reference created by |\ref| (read on to see its use). +\def\figureword{fig.} + +% Allocate a count register for the figure's number, and a box +% register which we'll use to measure dimensions of the image. +\newcount\fignumber +\newbox\imgbox + +% Now comes the fun part--constructing the figure for the image of the +% \CTAN\ lion. We define a macro +% +% \fig{LABEL}{FILENAME}{CAPTION}{WIDTH} +% +% which creates a figure using LABEL for the cross-reference and +% hyperlink label, reading the image from file FILENAME, using CAPTION +% to name the figure, and WIDTH to scale the image horizontally. +\def\fig#1#2#3#4{% + % Leave some space above the figure. This will also ensure that we + % are in the vertical mode before we produce a |\vbox|. + \medskip + % Advance the figure number. |\global| ensures that the change to + % the count register is global, even when |\fig| is buried inside a + % group. + \global\advance\fignumber by 1 + % We use |\includegraphics| (from |graphicx.sty|) to load the image, + % scaled to the specified width, into our ``measuring'' box + % |\imgbox|. + \setbox\imgbox = \hbox{\includegraphics[width=#4]{#2}}% + % To make the demo even more exciting, let's put the figure's + % caption to the left of the image into the |\indent| space of the + % new paragraph, and rotate the caption~$90^\circ$. + \textindent{% + \rotatebox{90}{F{\sc IGURE}~\the\fignumber. #3}% + }% + % Continue the paragraph by constructing a |\vbox| with the image of + % the lion. We use |\definexref| to define the cross-reference + % label. + \vbox{% + % In addition to the cross-reference label, |\definexref| will + % create a hyperlink destination with the same label. Therefore, + % we customize this destination to do what we need. We say that + % destination type for the hyperlink group |definexref| (to which + % |\definexref| belongs) should be |fitr|. This destination type + % will magnify the rectangle specified by the options |width|, + % |height| and |depth| to the PDF viewer's window. Therefore, we + % set those options accordingly with |\hldestopts| (notice the use + % of |depth| instead of |height|---we will want the rectangle to + % extend {\it downward}, to cover the image which will come + % next). Notice that these settings will be isolated within the + % current group (i.e., the |\vbox| we're constructing). + \hldesttype[definexref]{fitr}% + \hldestopts[definexref]{width=\wd\imgbox,height=0pt,depth=\ht\imgbox}% + % We define a symbolic label so that we can later refer + % to the figure with |\ref|. The command |\definexref| does + % exactly that. The last argument to |\definexref| specifies + % class of the label, which determines the word used by |\ref| in + % front of the reference text (remember that we've defined + % |\figureword| above). + \definexref{#1}{\the\fignumber}{figure}% + % Finally, produce the image which we've been stashing in the box + % register |\imgbox|. + \box\imgbox + }% + \medskip +} + +% Create the figure. +\fig{CTANlion}{ctan_lion_350x350}{Lion in the archives}{200pt} + +% Finished with the fun part, we can relax and typeset some +% hyperlinks. The easiest way to do that is to use the |\ref| +% cross-reference command. We can even pass an optional argument +% (|the lion in|), which will be placed before the class word (|fig.|) +% and become part of the link (to make sure the reader does not have +% to aim too hard). +Show me \ref[the lion in]{CTANlion}. + +% If you are the restless kind, here's another way to create a +% hyperlink to the image: we create a link explicitly by using +% |\hlstart ... \hlend|. We don't specify the link type, therefore +% the default type |name| will be used (these are ``named links'', +% i.e., links pointing to destinations identified by labels). In the +% options argument, we specify that the border of the link should be +% inverted when the user clicks the link (|hlight=O|), and also set +% special color for this link, overriding the default dark-red. The +% label for the destination is the same as the cross-reference label, +% |CTANlion|. +Show me +\hlstart{}{hlight=O,colormodel=named,color=OliveGreen}{CTANlion} + the CTAN lion\hlend. + +% Let's now point somewhere outside our document. Eplain homepage is +% a good target. In the similar spirit, let's consider two +% approaches. The easy one is to use the |\url| command from +% |url.sty|. Remember that we have customized the color of |url| +% hyperlinks, so this one will show up with a different color than the +% default dark-red. +Take me to \url{http://tug.org/eplain}. + +% The second approach is to create an explicit URL link. We specify +% yet another border highlighting mode, |P|, which means that the +% region underneath the bounding box of the link will be drawn inset +% into the page. Also, let's set the color of the hyperlink to an RGB +% color |0.4,0.1,0.4|. Since we cannot use commas to separate the +% color elements inside the options parameter to |\hlstart| (commas +% there separate options), we have to first create a user-defined +% color with |\definecolor| from |color.sty|, and use that in +% |\hlstart|. +\definecolor{mycolor}{rgb}{0.4,0.1,0.4} + +Take me to +\hlstart{url}{hlight=P,colormodel=,color=mycolor}{http://tug.org/eplain} + Eplain homepage\hlend. + +\bye diff --git a/Master/texmf-dist/doc/eplain/doc/eplain.html b/Master/texmf-dist/doc/eplain/doc/eplain.html new file mode 100644 index 00000000000..968582fd698 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/doc/eplain.html @@ -0,0 +1,8078 @@ + + +Eplain: Expanded Plain TeX + + + + + + + + + + +

Eplain: Expanded Plain TeX

+ + + + +
+

Table of Contents

+ +
+ +
+


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

Eplain

+ +

This manual documents the Eplain macros, version 3.1, +December 2006. 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. Adam Lewenberg has +made additions and corrections. Oleg Katsitadze has helped with writing +the section on LaTeX packages and the chapter on hyperlinks. + +

+

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

User definitions + +

+ +

Citations + +

+ +

Displays + +

+ +

Lists + +

+ +

Contents + +

+ +

Cross-references + +

+ +

Equation references + +

+ +

Indexing + +

+ +

Indexing terms + +

+ +

Loading LaTeX packages + +

+ +

Hyperlinks + +

+ +

Implicit hyperlinks + +

+ +

Index hyperlinks + +

+ +

Hyperlink drivers + +

+ +

Hyperlink driver hypertex:: + +

+ +

Hyperlink drivers pdftex and dvipdfm:: + +

+ +

Setting hyperlink types and options + +

+ +

Turning hyperlinks on/off + +

+ +

Arrow theoretic diagrams + +

+ +

Commutative diagrams + +

+ +

Programming definitions + +

+ +

Expansion + +

+ +

Demo files + +

+ + + +
+


+ +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
+
+

or visit http://tug.org/mailman/listinfo/tex-eplain. + +

David Walden had reported his experience with Eplain as a new user. +The article is available online at +http://tug.org/pracjourn/2005-4/walden. An introductory +article (written for +TUGboat) is also available online at +http://tug.org/eplain/misc/tb84katsi.pdf. + + +

+


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

2 Installation

+ +

Your TeX installation should already contain a version of Eplain +(eplain.tex) in its main texmf tree (usually under +/usr/share/texmf/tex/eplain/ on Unix systems). To install a +newer version of Eplain, put the new eplain.tex (included in +Eplain distributions) in the tex/eplain/ subdirectory of your +local texmf tree. The newer version you install in the local +tree should override the older one in the main tree. + +

The location of the local texmf tree obviously depends on your +operating system and TeX installation. On Unix systems the usual +location is /usr/local/share/texmf/. If you don't have write +permissions for /usr/local/share/texmf/, many installations read +the texmf tree in the user's home directory; eplain.tex +then should go under ~/texmf/tex/eplain/. For more information +about TeX directory structure, please see +http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds. + +

If you prefer to install eplain.tex in a non-standard place, set +an environment variable (TEXINPUTS for the Web2C port of TeX +to Unix) to tell TeX how to find it. + +

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 your local +texmf tree or set an environment variable to tell TeX how to +find it. For the Web2C port of TeX to Unix, format files are usually +installed under /usr/local/share/texmf/web2c/ or +/var/lib/texmf/web2c/; the environment variable is +TEXFORMATS. + + +

+


+ +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. + +

Normally, the \listing command will add a final empty line at +the end of the output, even if the file does not end in a newline. To +suppress this final line, you can say +\let\setuplistinghook = \nolastlinelisting. +This also works with line numbers (say +\def\setuplistinghook{\linenumberedlisting \nolastlinelisting}), +but only if \printlistinglineno +consists exclusively of boxes at the top level (i.e., any +\kerns or glue should be wrapped up in a box). + +

You can use the form feed control character (ASCII +code 12, typed as CTRL-L) in the file to force a page break +in the output. + +

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. + +

+ +
+


+ + +Next: , +Up: Contents + +
+ +

4.8.1 Writing the .toc file

+ +

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} +(unless part is an integer, see below). 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}
+
+

A variation on \writenumberedtocentry is +\writenumberedtocline, differing only in the order of the +parameters it takes and writes for the \tocpartentry +control sequences. To continue the previous example: + +

     \writenumberedtocline{chapter}{\the\chapno}{A $\sin$ wave}
+
+

writes the following to the .toc file: + +

     \tocchapterentry{3}{A $\sin$ wave}{8}
+
+

Such ordering of the parameters allows the +\tocpartentry macros to typeset the text of the entry +without actually reading it as an argument. This is required for +entries which need to change character catcodes, e.g., to produce +verbatim text (see Verbatim listing). + +

Each of \writetocentry, \writenumberedtocentry and +\writenumberedtocline processes a numeric part argument +specially. If you pass part expanding to an integer, these +macros write into the .toc file an entry that starts with +\tocentry{part}. Thus, you can define a single +\tocentry macro which formats all entries for a table of +contents. To continue the previous examples: + +

     \writenumberedtocentry{1}{A $\sin$ wave}{\the\chapno}
+     \writenumberedtocline{1}{\the\chapno}{A $\sin$ wave}
+     \writetocentry{2}{A section title}
+
+

writes the following to the .toc file: + +

     \tocentry{1}{A $\sin$ wave}{3}{8}
+     \tocentry{1}{3}{A $\sin$ wave}{8}
+     \tocentry{2}{A section title}{9}
+
+ + +

4.8.2 Reading the .toc file

+ +

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, \writenumberedtocentry and +\writenumberedtocline 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. + + +

+


+ + +Next: , +Previous: Reading the .toc file, +Up: Contents + +
+ +

4.8.3 Changing the .toc file's root name

+ +

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. + +Note that \writetocentry, \writenumberedtocentry and +\writenumberedtocline will +open the contents file for writing only at the first call, using the +value of \tocfilebasename at that time. Changing the value of +\tocfilebasename afterwards will not affect which file gets +written, although it will affect which file gets read by +\readcontentsfile. In case you need to write several contents +files from a single TeX job, use \definecontentsfile +(see Alternative contents files). + +

+


+ +Previous: Changing the .toc file's root name, +Up: Contents + +
+ +

4.8.4 Alternative contents files

+ +

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). + +

+ + + +

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). + +

+ + + +

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 want +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. + +

+ +

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}
+
+ + +
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}
+     
+
+ +
+


+ +Next: , +Previous: Modifying index entries, +Up: Indexing terms + +
+ +
4.12.1.3 Index entries with special characters
+ +

+Indexing terms with special characters can become quite cumbersome +because you have to keep both TeX and MakeIndex happy at the same +time. For example, while `!' has no special meaning for TeX, +it is a subentry separator for MakeIndex, therefore you'd have to +escape occurrences of literal `!' in index terms. Things get +even more interesting with characters which are special in both TeX +and MakeIndex. + +

This in turn has some implications for the non-silent forms of the +indexing commands (see Indexing terms), since TeX and MakeIndex +use different conventions for escaping characters. For example, this +will not typeset the exclamation point correctly within the text, +while it will come out right inside the index, after MakeIndex strips +the quoting character (`"'): + +

     \idx{"!}
+
+

This would have to be rewritten using the silent command: + +

     !\sidx{"!}
+
+

In general, it is a good idea to eschew the non-silent +commands whenever index term contains anything unusual. + +

To understand this keep in mind that indexing commands read the terms +verbatim so that the terms can embed almost any character, and that's +what gets written into the .idx file. The non-silent forms +then typeset the term by rescanning the verbatim copy, therefore for +the non-silent commands the term, besides being a valid MakeIndex +input, must also represent a valid TeX input. The silent commands +don't have this restriction—their terms only need to become valid +TeX input after MakeIndex processes the .idx file and +writes the .ind file. This is what makes the non-silent +commands less powerful and more troublesome when dealing with special +characters. + +

Here's an example showing that terms for the silent commands can +contain almost any character: + +

     \sidx[see]{comments}[with %@with \verbatim %"|endverbatim]
+       {commenting with \verbatim %"|endverbatim}
+
+

We didn't have to escape `%' in the sort string for +MakeIndex, while we had to put it inside the verbatim environment +(see Verbatim listing) in the part which MakeIndex will pass back +to TeX. Also, we had to escape the `|' character because it +is special for MakeIndex. If you have trouble understanding the +reasons for the different types of escaping used, it is best to +examine the .idx and .ind files resulting from +processing the above input. + +

As was mentioned, index terms can embed “almost any character”, so +now we'll describe the exceptions. + +

The following characters are reset to their usual meanings because +they are not useful verbatim: multiple consequent spaces are +converted into a single space; ASCII tab characters are +treated as spaces; ASCII return is treated as end-of-line +(this means, among other things, that long terms can be broken across +several lines). + +

You have to be careful with the begin- and end-group characters +(`{' and `}' by default). If they are matched, you don't +have to do anything special. For example: + +

     \sidx {braces {, }@braces
+       \verbatim {"|endverbatim, \verbatim }"|endverbatim}
+
+

However, if they are not matched you have two problems on +hand. The first one is TeX—you have to instruct TeX to use +something else as begin- and/or end-group characters. Eplain provides +an easy way to do this: just define +\idxargopen and/or +\idxargclose to the begin- and end-group characters you are +going to use with indexing macros, and use braces inside index terms +without any restrictions. Here's an example: + +

     \def\idxargopen{`\<}
+     \def\idxargclose{`\>}
+     \sidx <left brace "{@left brace \verbatim "{"|endverbatim>
+
+

In this example we've also dealt with the second +problem—braces are MakeIndex's grouping characters as well (by +default), so we have escaped unmatched braces with `"'. + +

And the final note: if you need a subentry containing brackets +(`[' and `]'), avoid the optional argument of \sidx +and friends, and use instead MakeIndex's subentry separator to create +the subentry with the brackets in it: + +

     \sidx{entry!subentry with a bracket [}
+
+ + +
4.12.1.4 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 contained in trimsee +distributed with Eplain in the util 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 +http://www.ctan.org/tex-archive/macros/texsis, 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. + +

+ + + +

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. + +

+ +

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. + +

Some packages (and the pseudo-LaTeX environment, miniltx.tex) +redefine TeX's primitive \input to be a macro. Non-primitive +\input is probably not what the user expects under +plain TeX. Therefore, at the beginning of the +\beginpackages...\endpackages block Eplain saves the meaning of +\input as +\eplaininput and restores the original \input at the end +of the block. This usually means that the primitive \input is +restored, unless you (or some other macro package you've loaded +directly) have redefined it before calling \beginpackages. In +case you need to access the package-provided \input, Eplain saves +it as \packageinput. + +

Sometimes you may encounter packages which make conflicting +redefinitions of \input. Common symptoms are TeX spewing +incomprehensible error messages or hanging in a loop at a call to +\input. This sometimes can be cured by restoring \input +to \eplaininput before loading each package. For example: + +

     \beginpackages
+       \usepackage{pack1}
+       \let\input\eplaininput
+       \usepackage{pack2}
+     \endpackages
+
+ + +

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/misc/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. + +

Warning 1: If you encounter problems loading one of +these packages under pdfTeX (more specifically, when pdfTeX +reads supp-mis.tex), the cause may be an outdated +supp-mis.tex (part of ConTeXt, a typesetting system for +TeX) installed on your system. The problem was fixed in +supp-mis.tex version 2004.10.26. You can obtain +up-to-date versions of supp-mis.tex and the accompanying +supp-pdf.tex from +http://www.ctan.org/tex-archive/macros/pdftex/graphics. +To convince TeX to use the new files, you have the following +options in the decreasing order of preference: + +

    +
  1. put the new files in the same directory with your document; + +
  2. overwrite the outdated files installed by your TeX distribution; + +
  3. install the new supp-mis.tex and supp-pdf.tex files in +the relevant subdirectory of your local texmf tree (for info on +TeX directory structure see +http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds); + +
  4. upgrade your ConTeXt installation. +
+ +

Note that option 1 is the safest but provides the fix +only for your current document. Options 2 and 3 will +usually suffice for Eplain but may break ConTeXt. Option 4 is +the most general but is more complicated than the first three. Be +sure to backup any files you overwrite. Also keep in mind that +upgrading your TeX distribution may overwrite files you install in +the system texmf tree.
End of warning 1. + +

Warning 2: If you encounter problems using the +\pagecolor command from the color.sty package under +pdfTeX, the cause may be an outdated pdfTeX color and graphics +driver pdftex.def. The problem was fixed in pdftex.def +version 0.03p. You can obtain an up-to-date version from +http://www.ctan.org/tex-archive/graphics/pdftex/pdftex.def.
+End of warning 2. + +

The graphics/graphicx packages have the option +draft which instructs \includegraphics not to include the +graphics but instead typeset a box with the dimensions of the graphics +and the name of the graphics file in typewriter type at the center of +the box. These packages expect the LaTeX-provided command +\ttfamily to switch to the typewrite type. This command is not +defined by miniltx.tex, therefore Eplain defines it and makes it +equivalent to plain TeX's +\tt. + +

See Hyperlinks (xhyper.tex), for the demonstration of text rotation and +graphics inclusion using the graphicx package, and using the +color package to colorize hypertext links. + +

Klaus Höppner has written a nice introduction to the LaTeX graphics +packages and different graphics formats. You can download it from +

          http://www.tug.org/pracjourn/2005-3/hoeppner
+     
+
epstopdf (`2001/02/04 v1.1 Conversion with epstopdf on the fly (HO)')
http://www.ctan.org/tex-archive/macros/latex/contrib/oberdiek + +

This package does on-the-fly conversion of Encapsulated PostScript +(EPS) graphics into Portable Document Format (PDF) +graphics for inclusion with the \includegraphics command from +the graphics/graphicx packages, so that you do not have +to explicitly call the epstopdf script. + +

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. + +

soul (`2003/11/17 v2.4 letterspacing/underlining (mf)')
http://www.ctan.org/tex-archive/macros/latex/contrib/soul + +

This package provides hyphenatable letterspacing (spacing out), +underlining, and some derivatives. The package is optimized for +LaTeX, but works with plain TeX—you don't actually need to +load it with the \usepackage command, just say \input +soul.sty. If you intend to use the highlighting macros of +soul, don't forget to load the color package. + +

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). + +

Be sure to get a version dated at least 2005/06/27, as older versions +have problems in plain TeX. +

+ + + +

4.23.4 Packages known not to work

+ +

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

+
hyperref
http://www.ctan.org/tex-archive/macros/latex/contrib/hyperref + +

This package depends heavily on LaTeX, so that it is mostly +unusable outside of LaTeX. Eplain provides its own macros for +creating hyperlinks, see Hyperlinks. + +

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 +(a.k.a. hypertext links). +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 three drivers: hypertex (implementation of the +HyperTeX standard, see http://arxiv.org/hypertex), and +pdftex and dvipdfm (named after the programs which +process the hyperlink commands, +pdfTeX and +dvipdfm). Therefore, Eplain can only produce HyperTeX commands and +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 hypertex 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 or +the HyperTeX 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 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). + +

The label argument of both \hldest and \hlstart +can contain special characters (such as `#', `%', `&', +`~', etc.) without any escaping. This is especially important +for URL links supported by some drivers (see Hyperlink drivers). + +

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. + +

See Hyperlinks (xhyper.tex), for a demonstration of the usage of +explicit hyperlinks. + +

+


+ +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: + +

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

And here are the destgroups: + +

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

See Hyperlinks (xhyper.tex), for a demonstration of the usage of +implicit hyperlinks. + +

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

+ +
+


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

5.3.1 General hyperlinks: hrefint, hrefext

+ +

\href{url}{text} typesets text as a link +to url. It basically does what the explicit hyperlink macros do +(see Explicit hyperlinks), but is more convenient (at the expense +of flexibility). + +

If url starts with `#', the rest of url is assumed to +be a local hyperlink destination name (destination within the same +document). Parameters for these links can be set by customizing the +`hrefint' linkgroup. For example: + +

     See \href{#intro}{Introduction}
+
+

will make `Introduction' into an internal link, which might +have been created, e.g., with \xrdef{intro}. + +

If url does not start with `#', it is assumed to be a +URL link. Parameters for these links can be set by +customizing the +`hrefext' linkgroup. The special characters (such as `#' and +`~') in the URL don't need to be escaped. For example: + +

     \href{http://tug.org/eplain/doc/eplain.html#Hyperlinks}{Hyperlinks
+     in Eplain}
+
+

See URL hyperlinks, for another way to create +URL hyperlinks. + +

The text argument of \href can contain verbatim text +(see Verbatim listing) or other macros which manipulate character +catcodes. For example: + +

     \href{#WeirdChars}{The weird chars \verbatim #&%$~|endverbatim}
+
+

\href does not currently handle other link types, such as +`file:' and +`run:' links. + +

+


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

5.3.2 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). + +

By default, URL (and other types of) links are boxed, so +that they are visually marked even if you do not load the LaTeX +`color' package (see Loading LaTeX packages) and therefore link text +is not colored. You can see the effect by compiling the following code +snippet (be sure to get a modern url.sty, older versions do not +work in plain TeX; see Packages known to work): + +

     \input eplain
+     \beginpackages
+       \usepackage{url}
+     \endpackages
+     
+     \enablehyperlinks
+     
+     \url{http://foo/bar}
+     \bye
+
+

If the hyperlink driver you use supports the link option bwidth +(see Hyperlink drivers), you can produce colored links with no +border around them. Try this: + +

     \input eplain
+     \beginpackages
+       \usepackage{url}
+       \usepackage{color}
+     \endpackages
+     
+     \enablehyperlinks
+     \hlopts{bwidth=0}
+     
+     \url{http://foo/bar}
+     \bye
+
+

The command \hlopts{bwidth=0} sets border width to +zero as the default for all links, and loading the color package +automatically colors links using the default color (see Options supported by all drivers). If you want the border width setting to +apply to URL links only, say \hlopts[url]{bwidth=0} +(see Setting hyperlink types and options). + +

+


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

5.3.3 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. + +

+ +

5.3.4 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.5 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. + +

+ +

5.3.6 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. + +

+ +

5.3.7 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. + +

+ +

5.3.8 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. + +

+ + + +
5.3.8.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). + +

+ +
5.3.8.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). + +

+ +
5.3.8.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”). + +

+ +
5.3.8.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. + +

+ +
5.3.8.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.9 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. + +

Generally, footnote hyperlinks are not of much use, because the +footnotes are usually placed on the same page as the footnote mark. +Therefore, footnote hyperlinks are disabled by default. Here is how you +can turn them on selectively, without affecting the other kinds of +hyperlinks (see Turning hyperlinks on/off for a group): + +

     \hldeston[foot,footback]
+     \hlon[foot,footback]
+
+
+


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

5.3.10 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. + +

+ +

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. + +

+ + + +

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}
+     
+
+ + + +

5.4.2 Hyperlink driver hypertex

+ +

HyperTeX is a standard for inclusion of hyperlink information in +TeX (and LaTeX) documents (see http://arxiv.org/hypertex). +This standard defines a set of hyperlink tags implemented as +\special commands written into the DVI file. The +major advantage of such standard is that a single .dvi file +containing HyperTeX commands can be viewed by any +HyperTeX-enabled viewer (e.g., any more or less modern version of +xdvi) or converted to other file formats (e.g., PDF) +by any HyperTeX-enabled DVI converter (e.g., +dvipdfmx or +dvips with +Ghostscript's +ps2pdf script). + +

The downside to the standard is that it is by design “the common +factor” of other formats supporting hyperlinks, so many features of a +particular file format cannot be supported by HyperTeX. Therefore, +if you need to use special features of a particular format, HyperTeX +is not a good choice. For the PDF file format, Eplain +provides the pdftex and dvipdfm drivers which provide +fine control over the PDF options (see Hyperlink drivers pdftex and dvipdfm). + +

For more information on programs which support the HyperTeX standard, +please see + +

     http://arxiv.org/hypertex
+     http://www.tug.org/tex-archive/support/hypertex/hypertex
+
+

For convenience, we list a few HyperTeX-enabled converters: + + + +

dvips
Note that you need to pass the -z option to dvips to +tell it to preserve the information about the hyperlinks. To generate a +.pdf file with hyperlinks, you can use the +ps2pdf script of +Ghostscript. For example, if foo.tex is a TeX file using +HyperTeX commands, then + +
          prompt$ tex foo.tex
+          prompt$ dvips -z foo.dvi -o
+          prompt$ ps2pdf foo.ps
+     
+

will produce foo.pdf with hyperlinks. + +

dvipdfm
dvipdfmx
No special command line arguments are required, these programs +automatically detect the HyperTeX commands. + +
+ +

One more note is in place: support for the HyperTeX commands varies +from one previewer/converter to another, so you might need to experiment +to see if what you need is supported by the program(s) you intend to +use. For example, dvips(k) as of version 5.92b converts all +internal hyperlinks into page links pointing to a page containing the +destination, so that “exact” linking to destinations is not possible +(this was confirmed to be a bug and most probably has already been fixed +in later versions of dvips(k)); dvipdfm as of version 0.13.2c and +dvipdfmx as of version 20040411 do not correctly parse links to +external local files, and produce a URL link instead of a +file link. + +

+ + + +
5.4.2.1 Destination types for hypertex
+ +

+

+
xyz
“Current position”. This is the default type. + +

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

raw
The destination specification (in the form of a HyperTeX +\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 in a direct call to +\hldest—you can just call the raw command. + +

Example: + +

          \makeatletter
+          \def\mydest{\special{html:<a name="\@hllabel">}%
+                      \special{html:</a>}}
+          \resetatcatcode
+          \indent\hldest{raw}{cmd=mydest}{SpecialDest}
+            Special destination.
+     
+
+ + + +
5.4.2.2 Destination options for hypertex
+ +

+

+
cmd
Name of the macro (without the leading `\') containing a +HyperTeX \special for the raw destination. + +

See Destination types for hypertex, the description of the raw +destination, for an example. +

+ + + +
5.4.2.3 Link types for hypertex
+ +

+

+
name
Go to a “named destination”. The label is the destination name. All +destinations in HyperTeX are named destinations. This is the default +type. + +

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

url
Go to a URL. The label is the URL. + +

Example: + +

          \hlstart{url}{}{http://tug.org/eplain/}Eplain home\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. The file name extension can be specified separately +by the +ext option. The idea is to set the ext option globally at +the beginning of the document to avoid hard-coding the extension +together with the file name within each link—HyperTeX is not +restricted to any single output format, it can be DVI, +PDF, possibly other formats. + +

Example: + +

          \hlopts{ext=.pdf}
+          \hlstart{filename}{file=book}{dest123}
+            Link to dest123 in file `book.pdf'\hlend
+     
+
raw
The link specification (in the form of a HyperTeX \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. Use the predefined +command +\hlhash to insert the # characters. This option is +intended to be used with linkgroups (see Setting hyperlink types and options), as it does not make sense in a direct call to +\hlstart—you can just call the raw command. + +

Example: + +

          \makeatletter
+          \def\mylink{\special{html:<a href="\hlhash\@hllabel">}}
+          \resetatcatcode
+          \hlstart{raw}{cmd=mylink}{SpecialDest}
+            Link to the special destination.\hlend
+     
+
+ + + +
5.4.2.4 Link options for hypertex
+ +

+

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

See Link types for hypertex, the description of the raw link, +for an example. + +

file
File name for the filename link type. See also the ext +option. + +

See Link types for hypertex, the description of the filename +link, for an example. + +

ext
File name extension for the filename link type. The idea is to +set the ext option globally at the beginning of the document to +avoid hard-coding the extension together with the file name within each +link—HyperTeX is not restricted to any single output format, it can +be DVI, PDF, possibly other formats. + +

See Link types for hypertex, the description of the filename +link, for an example. +

+ + + +

5.4.3 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. + +

+ + + +
5.4.3.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 in a direct call to +\hldest—you can just call the raw command. + +

Example for pdftex: + +

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

Example for dvipdfm: + +

          \makeatletter
+          \def\mydest{\special{pdf: dest (\@hllabel)
+                                    [@thispage /XYZ @xpos @ypos 0]}}
+          \resetatcatcode
+          \hldesttype{raw}
+          \hldestopts{cmd=mydest}
+     
+
+ + + +
5.4.3.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. + +

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

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}
+     
+
+ + + +
5.4.3.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 +(see Explicit hyperlinks). This is the default type. + +

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

url
Go to a URL. The label is the URL. + +

Example: \hlstart{url}{}{http://tug.org/eplain/}Eplain home\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
+     
+
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. In the definition of \cs, use +\@hllabel to refer to the hyperlink label. This option is +intended to be used with linkgroups (see Setting hyperlink types and options), as it does not make sense 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 +

+ + + +
5.4.3.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. + +

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

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

See Link types for pdftex and dvipdfm, the descriptions of the +filename and filepage links, for an example. + +

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. + +

See Link types for pdftex and dvipdfm, the descriptions of the +filename and filepage links, for an example. + +

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. + +

See Link types for pdftex and dvipdfm, the descriptions of the +page and filepage links, for an example. +

+ +
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
+     
+
+ + + +

5.4.4 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. + +

So, if you are planning to produce versions of your PDF +document both with and without hyperlinks, here is the recommended way +to enable the hyperlinks under pdfTeX: + +

+

     \ifpdf
+       \enablehyperlinks
+     \else
+       \enablehyperlinks[nolinks]%
+     \fi
+
+
+


+ +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. + +

+ + + +

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. + +

Many people regard the default boxed links as not aesthetic and +intruding on page layout. The reason why boxed links are the default is +that the links are not colored until you load the LaTeX +`color' package (see Loading LaTeX packages) or use other means to +define the \color command; therefore, not producing any kind of +link border may result in the links not being marked in any way. +However, when the links are actually colored, there is no need to +produce the link boxes anymore; to avoid the boxes, you can set the +default border width to zero (if the driver you use supports the link +option bwidth; see Hyperlink drivers): + +

     \hlopts{bwidth=0}
+
+ + +

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. + +

+ +

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. + +

+ + + +

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. + +

+ +

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). + +

+ + + +

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. + +

+ +

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. + +

+ + + +

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. + + +

+ +

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. + +

+ +

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. + +

+ + + +

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. To strip leading spaces off the items, use +\For: + +

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

Note that trailing spaces are still not ignored. + +

Both \for and \For expand the first token of the item +list fully, so this is equivalent to the above: + +

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

However, this won't work, either with \for or with +\For: + +

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

because \for and \For expand the first +token after := which is space, not \namelist. + +

Eplain provides another kind of loops, which is an extension of plain +TeX's +\loop. If you say: + +

+

     \loop
+       loop-text
+     \if condition
+       if-text
+     \repeat
+
+

then loop-text will be repeated as long as condition +is satisfied (\if can be any of the TeX's conditional +commands, without the matching \fi). Eplain extends this with +the optional else clause: + +

     \loop
+       loop-text
+     \if condition
+       if-text
+     \else
+       else-text
+     \repeat
+
+

Here, loop-text will be repeated as long as +condition is not satisfied. This extension is from +Victor Eijkhout's +TeX by Topic (page 104). + +

+


+ +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
+         ...
+       }%
+
+ + +

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. + +

+


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

7.6.7 \ifempty

+ +

\ifempty{arg} t \else f \fi expands the +t text if arg is the empty string, and the f text +otherwise. This macro is useful when you need to test for empty +arguments to your macros, for example: + +

     \def\foo#1{\ifempty{#1} t \else f \fi}
+
+

Since \ifempty 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. + +

Note that the following code + +

     \def\empty{}
+     \ifempty\empty\message{empty}\else\message{not empty}\fi
+
+

will produce the message `not empty'. + +

+


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

7.6.8 \ifinteger and \isinteger

+ +

\ifinteger{arg} t \else f \fi expands the +t text if arg is an integer, and the f text +otherwise. This macro can detect positive and negative integers. + +

Since \ifinteger 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. For such situations Eplain provides +\isinteger, which can be used as follows: + +

     \if\isinteger{arg} t \else f \fi
+
+

Although \ifinteger and \isinteger work well +with regular input, they are not bullet-proof. For example, the +following code + +

     \ifinteger{12_ab}integer\else not integer\fi
+
+

will expand to `ab_integer' (and thus would not +even compile outside math mode). + +

These macros come from TeX Frequently Asked Question +(http://www.tex.ac.uk/cgi-bin/texfaq2html). + +

+


+ + +Previous: \ifinteger and \isinteger, +Up: Expansion + +
+ +

7.6.9 \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.) + + +

+ +

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.) + +

+ +

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
+
+ + +

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. + +

+ +

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 + +
+ +

8 Demo files

+ +

This chapter contains listings of source files, along with the output +they produce (where appropriate), which illustrate various aspects of +Eplain. The files can be found in the demo subdirectory of +Eplain distribution. These demos, both the sources and the compiled PDF +and PS files, are also available from http://tug.org/eplain/demo. + +

+ + + +

8.1 Hyperlinks (xhyper.tex)

+ +
xhyper.jpg
+ +

+ + + + + + + + + +

% (This file is public domain.)
+%
+% This file demonstrates the following features of Eplain:
+%
+%   - explicit and implicit hyperlinks;
+%   - symbolic cross-references;
+%   - inserting external graphics using |\includegraphics| from
+%     the \LaTeX\ package |graphicx.sty|.
+%   - rotating text using |\rotatebox| from |graphicx.sty|.
+%
+% The compiled demo can be downloaded from
+%
+%   http://tug.org/eplain/demo
+%
+% In order to compile this file yourself, you will need the CTAN lion
+% drawing by Duane Bibby from
+%
+%   ftp://tug.ctan.org/ftpmaint/CTAN_lion/ctan_lion_350x350.png
+%
+% (thanks, |www.ctan.org|).  Place the image file in the same
+% directory with this file, and change to that directory.  Now, to
+% produce a PDF, run twice the command
+%
+%   pdftex xhyper.tex
+%
+% During the first run, Eplain will write the information about the
+% cross-references into |xhyper.aux|, and during the second run this
+% information will be read by Eplain to typeset the references.
+%
+% Demo case:
+%
+%   Suppose you are using pdf\TeX, have a figure you want to insert
+%   scaled to $200\,pt$ horizontally, and you want this figure to
+%   completely fill the PDF viewer's window whenever the reader
+%   selects a link pointing to this figure.  Additionally, you want to
+%   typeset some text as live hyperlinks, clicking on which will start
+%   a Web browser and open a URL.
+
+\input eplain
+
+% Load \LaTeX\ packages.
+\beginpackages
+  % |url.sty| provides the |\url| command which we will use to typeset
+  % a URL.  We request that |url.sty| be the version from June~27,
+  % 2005, or later, because earlier versions had problems interacting
+  % with plain \TeX.
+  \usepackage{url}[2005/06/27]
+  % |color.sty| provides support for colored text; all hyperlinks are
+  % automatically colored by Eplain when this package is loaded.  We give
+  % the |dvipsnames| option because we want to use named colors from the
+  % |dvips| graphics driver.
+  \usepackage[dvipsnames]{color}
+  % Finally, we load |graphicx.sty|, for the macros |\includegraphics|
+  % and |\rotatebox|.
+  \usepackage{graphicx}
+\endpackages
+
+% Remember that hyperlinks are off by default.  Therefore, we need to
+% enable them.
+\enablehyperlinks
+
+% Customize some hyperlink options.  First, we set border width to~$0$
+% for all links to get rid of the default boxes around links (we
+% prefer colored links over the boxed links). Next, we say that all
+% links created by the |url| hyperlink group (which means the |\url|
+% command from |url.sty|) must be colored using the named color
+% |BlueViolet|.
+\hlopts{bwidth=0}
+\hlopts[url]{colormodel=named,color=BlueViolet}
+
+% Inhibit page numbering (we have only one page).
+\nopagenumbers
+
+% Define a class word for the cross-reference class |figure|.  This
+% word, when defined, will be automatically prepended by Eplain to the
+% reference created by |\ref| (read on to see its use).
+\def\figureword{fig.}
+
+% Allocate a count register for the figure's number, and a box
+% register which we'll use to measure dimensions of the image.
+\newcount\fignumber
+\newbox\imgbox
+
+% Now comes the fun part--constructing the figure for the image of the
+% \CTAN\ lion.  We define a macro
+%
+%   \fig{LABEL}{FILENAME}{CAPTION}{WIDTH}
+%
+% which creates a figure using LABEL for the cross-reference and
+% hyperlink label, reading the image from file FILENAME, using CAPTION
+% to name the figure, and WIDTH to scale the image horizontally.
+\def\fig#1#2#3#4{%
+  % Leave some space above the figure.  This will also ensure that we
+  % are in the vertical mode before we produce a |\vbox|.
+  \medskip
+  % Advance the figure number.  |\global| ensures that the change to
+  % the count register is global, even when |\fig| is buried inside a
+  % group.
+  \global\advance\fignumber by 1
+  % We use |\includegraphics| (from |graphicx.sty|) to load the image,
+  % scaled to the specified width, into our ``measuring'' box
+  % |\imgbox|.
+  \setbox\imgbox = \hbox{\includegraphics[width=#4]{#2}}%
+  % To make the demo even more exciting, let's put the figure's
+  % caption to the left of the image into the |\indent| space of the
+  % new paragraph, and rotate the caption~$90^\circ$.
+  \textindent{%
+    \rotatebox{90}{F{\sc IGURE}~\the\fignumber.  #3}%
+  }%
+  % Continue the paragraph by constructing a |\vbox| with the image of
+  % the lion.  We use |\definexref| to define the cross-reference
+  % label.
+  \vbox{%
+    % In addition to the cross-reference label, |\definexref| will
+    % create a hyperlink destination with the same label.  Therefore,
+    % we customize this destination to do what we need.  We say that
+    % destination type for the hyperlink group |definexref| (to which
+    % |\definexref| belongs) should be |fitr|.  This destination type
+    % will magnify the rectangle specified by the options |width|,
+    % |height| and |depth| to the PDF viewer's window.  Therefore, we
+    % set those options accordingly with |\hldestopts| (notice the use
+    % of |depth| instead of |height|---we will want the rectangle to
+    % extend {\it downward}, to cover the image which will come
+    % next).  Notice that these settings will be isolated within the
+    % current group (i.e., the |\vbox| we're constructing).
+    \hldesttype[definexref]{fitr}%
+    \hldestopts[definexref]{width=\wd\imgbox,height=0pt,depth=\ht\imgbox}%
+    % We define a symbolic label so that we can later refer
+    % to the figure with |\ref|.  The command |\definexref| does
+    % exactly that.  The last argument to |\definexref| specifies
+    % class of the label, which determines the word used by |\ref| in
+    % front of the reference text (remember that we've defined
+    % |\figureword| above).
+    \definexref{#1}{\the\fignumber}{figure}%
+    % Finally, produce the image which we've been stashing in the box
+    % register |\imgbox|.
+    \box\imgbox
+  }%
+  \medskip
+}
+
+% Create the figure.
+\fig{CTANlion}{ctan_lion_350x350}{Lion in the archives}{200pt}
+
+% Finished with the fun part, we can relax and typeset some
+% hyperlinks.  The easiest way to do that is to use the |\ref|
+% cross-reference command.  We can even pass an optional argument
+% (|the lion in|), which will be placed before the class word (|fig.|)
+% and become part of the link (to make sure the reader does not have
+% to aim too hard).
+Show me \ref[the lion in]{CTANlion}.
+
+% If you are the restless kind, here's another way to create a
+% hyperlink to the image:  we create a link explicitly by using
+% |\hlstart ... \hlend|.  We don't specify the link type, therefore
+% the default type |name| will be used (these are ``named links'',
+% i.e., links pointing to destinations identified by labels).  In the
+% options argument, we specify that the border of the link should be
+% inverted when the user clicks the link (|hlight=O|), and also set
+% special color for this link, overriding the default dark-red.  The
+% label for the destination is the same as the cross-reference label,
+% |CTANlion|.
+Show me
+\hlstart{}{hlight=O,colormodel=named,color=OliveGreen}{CTANlion}
+  the CTAN lion\hlend.
+
+% Let's now point somewhere outside our document.  Eplain homepage is
+% a good target.  In the similar spirit, let's consider two
+% approaches.  The easy one is to use the |\url| command from
+% |url.sty|.  Remember that we have customized the color of |url|
+% hyperlinks, so this one will show up with a different color than the
+% default dark-red.
+Take me to \url{http://tug.org/eplain}.
+
+% The second approach is to create an explicit URL link.  We specify
+% yet another border highlighting mode, |P|, which means that the
+% region underneath the bounding box of the link will be drawn inset
+% into the page.  Also, let's set the color of the hyperlink to an RGB
+% color |0.4,0.1,0.4|.  Since we cannot use commas to separate the
+% color elements inside the options parameter to |\hlstart| (commas
+% there separate options), we have to first create a user-defined
+% color with |\definecolor| from |color.sty|, and use that in
+% |\hlstart|.
+\definecolor{mycolor}{rgb}{0.4,0.1,0.4}
+
+Take me to
+\hlstart{url}{hlight=P,colormodel=,color=mycolor}{http://tug.org/eplain}
+  Eplain homepage\hlend.
+
+\bye
+
+ +
+


+ + +Previous: Hyperlinks (xhyper.tex), +Up: Demo files + +
+ +

8.2 Highlighting TeX comments in listings (lscommnt.tex)

+ +
lscommnt.jpg
+ +

+ + + +

% (This file is public domain.)
+% Demonstrate how Eplain can be used to include a TeX source file
+% verbatim, typesetting comments in colored italic typewriter type.
+
+% Load Eplain and LaTeX's color.sty package.
+\input eplain
+\beginpackages \usepackage{color} \endpackages
+\nopagenumbers % Disable page numbers.
+\font\commentfont = cmitt10 % Font for the comments (italic \tt).
+% We'll define some `protected' macros with `@' in their names.
+\makeatletter
+% Define an equivalent of Eplain's \letreturn, to be able to assign
+% various actions to the (active) percent character.
+\begingroup \makeactive\%
+  \gdef\letpercent{\let%}
+\endgroup
+% The listing hook to be called in \setuplistinghook, see below.  It
+% makes `%' active and assigns it a `start comment' action.
+\def\hlightcommentslisting{\makeactive\% \letpercent\start@comment}%
+% This is what `%' is aliased to before a comment is started.
+\def\start@comment{%
+  \leavevmode % Needed in the very first line of the input to process
+              % the new par (possibly inserting line number) before we
+              % kick in with the color and stuff.
+  \begingroup % Isolate color and font changes and the redefinitions.
+    \commentfont
+    \color[cmyk]{0.28,1,1,0.35}%
+    \percentchar            % Produce the actual `%' and
+    \letpercent\percentchar % make all following `%'s do the same.
+    \letreturn\end@comment  % Call \end@comment at end-of-line.
+}
+% \end@comment (alias for ^^M inside a comment) will end the comment
+% started by \start@comment.  We make ^^M active temporarily so that
+% the active version of ^^M gets "frozen" into \end@comment.
+\begingroup \makeactive\^^M % Avoid ^^M's from here on.
+  \gdef\end@comment{\endgroup ^^M}%
+\endgroup
+\resetatcatcode % Make `@' again inaccessible for use in macro names.
+
+% Define \setuplistinghook to setup comments highlighting, line
+% numbering and omitting the last (empty) line of input.
+\def\setuplistinghook{\hlightcommentslisting \linenumberedlisting
+                      \nolastlinelisting}
+% Isn't this fun?  This file typesets itself, with the extra bonus of
+% the pretty-printed comments and numbered source lines!
+\listing{lscommnt}
+\bye
+
+ + +
+


+ +Next: , +Previous: Demo files, +Up: Top + +
+ +

Macro index

+ + + +
+


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

Concept index

+ + + + + diff --git a/Master/texmf-dist/doc/eplain/doc/eplain.info b/Master/texmf-dist/doc/eplain/doc/eplain.info new file mode 100644 index 00000000000..aa7dd6bbd4e --- /dev/null +++ b/Master/texmf-dist/doc/eplain/doc/eplain.info @@ -0,0 +1,7863 @@ +This is eplain.info, produced by makeinfo version 4.8 from eplain.texi. + + This manual documents the Eplain macros, version 3.1, December 2006. +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. Adam Lewenberg has +made additions and corrections. Oleg Katsitadze has helped with writing +the section on LaTeX packages and the chapter on hyperlinks. + +INFO-DIR-SECTION Texinfo documentation system +START-INFO-DIR-ENTRY +* Eplain: (eplain). Expanding on plain Tex. +END-INFO-DIR-ENTRY + + +File: eplain.info, Node: Top, Next: Introduction, Up: (dir) + +Eplain +****** + +This manual documents the Eplain macros, version 3.1, December 2006. +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. Adam Lewenberg has +made additions and corrections. Oleg Katsitadze has helped with writing +the section on LaTeX packages and the chapter on hyperlinks. + +* 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. +* Demo files:: Sample documents demonstrating Eplain. +* 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. +* Loading LaTeX packages:: Support for LaTeX packages under plain TeX. + +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. + +Contents + +* Writing the .toc file:: +* Reading the .toc file:: +* Changing the .toc file's root name:: +* Alternative contents files:: + +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. +* Index entries with special characters:: +* Proofing index terms:: Noting index entries in the margins. + +Loading LaTeX packages + +* 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. + +Hyperlinks + +* Introduction to hyperlinks:: +* Explicit hyperlinks:: +* Implicit hyperlinks:: +* Hyperlink drivers:: +* Setting hyperlink types and options:: +* Turning hyperlinks on/off:: + +Implicit hyperlinks + +* General hyperlinks:: hrefint, hrefext +* 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 driver hypertex:: +* Hyperlink drivers pdftex and dvipdfm:: +* Hyperlink driver nolinks:: + +Hyperlink driver hypertex:: + +* Destination types for hypertex:: +* Destination options for hypertex:: +* Link types for hypertex:: +* Link options for hypertex:: + +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' and `while' 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:: +* \ifempty:: +* \ifinteger and \isinteger:: +* \futurenonspacelet:: + +Demo files + +* Hyperlinks (xhyper.tex):: +* Highlighting TeX comments in listings (lscommnt.tex):: + + +File: eplain.info, Node: Introduction, Next: Installation, Prev: 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 . +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 + with a message whose body contains a line + + subscribe YOU@YOUR.PREFERRED.ADDRESS + +or visit `http://tug.org/mailman/listinfo/tex-eplain'. + + David Walden had reported his experience with Eplain as a new user. +The article is available online at +`http://tug.org/pracjourn/2005-4/walden'. An introductory article +(written for TUGboat) is also available online at +`http://tug.org/eplain/misc/tb84katsi.pdf'. + + +File: eplain.info, Node: Installation, Next: Invoking Eplain, Prev: Introduction, Up: Top + +2 Installation +************** + +Your TeX installation should already contain a version of Eplain +(`eplain.tex') in its main `texmf' tree (usually under +`/usr/share/texmf/tex/eplain/' on Unix systems). To install a newer +version of Eplain, put the new `eplain.tex' (included in Eplain +distributions) in the `tex/eplain/' subdirectory of your local `texmf' +tree. The newer version you install in the local tree should override +the older one in the main tree. + + The location of the local `texmf' tree obviously depends on your +operating system and TeX installation. On Unix systems the usual +location is `/usr/local/share/texmf/'. If you don't have write +permissions for `/usr/local/share/texmf/', many installations read the +`texmf' tree in the user's home directory; `eplain.tex' then should go +under `~/texmf/tex/eplain/'. For more information about TeX directory +structure, please see +`http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds'. + + If you prefer to install `eplain.tex' in a non-standard place, set +an environment variable (`TEXINPUTS' for the Web2C port of TeX to Unix) +to tell TeX how to find it. + + 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 your local +`texmf' tree or set an environment variable to tell TeX how to find it. +For the Web2C port of TeX to Unix, format files are usually installed +under `/usr/local/share/texmf/web2c/' or `/var/lib/texmf/web2c/'; the +environment variable is `TEXFORMATS'. + + +File: eplain.info, Node: Invoking Eplain, Next: User definitions, Prev: 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 (*note Arrow theoretic diagrams::), + written by Steven Smith; + +`btxmac.tex' + bibliography-related macros (*note Citations::); + +`ifpdf.sty' + sets the switch `\ifpdf', which can be used to detect pdfTeX in + PDF mode (*note 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., (*note Paths::), + written by Philip Taylor; + +`texnames.sty' + abbreviations for various TeX-related names (*note 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. + + +File: eplain.info, Node: User definitions, Next: Hyperlinks, Prev: 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. + +* 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. + + +File: eplain.info, Node: Diagnostics, Next: Rules, 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.}% + + +File: eplain.info, Node: Rules, Next: Citations, Prev: 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'. + + +File: eplain.info, Node: Citations, Next: Displays, Prev: 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 (*note Formatting citations::). `\cite' takes one required +argument, a comma-separated list of cross-reference labels (*note +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 (*note 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 (*note +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'.) + +* Menu: + +* Formatting citations:: Changing the way citations are printed. +* Formatting bibliographies:: Changing the way bibliographies are printed. + + +File: eplain.info, Node: Formatting citations, Next: Formatting bibliographies, 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)}} + + +File: eplain.info, Node: Formatting bibliographies, Prev: 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. + + +File: eplain.info, Node: Displays, Next: Time of day, Prev: 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'. + +* Menu: + +* Formatting displays:: General formatting of displays. + + +File: eplain.info, Node: Formatting displays, 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'. + + +File: eplain.info, Node: Time of day, Next: Lists, Prev: 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'. + + +File: eplain.info, Node: Lists, Next: Verbatim listing, Prev: 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'. *Note Cross-references::. + + Eplain can create hypertext links for the markers produced by +`\xrefn' pointing to the relevant list item (*note 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 (*note 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 + +* Menu: + +* Formatting lists:: Changing how the lists look. + + +File: eplain.info, Node: Formatting lists, 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. + + +File: eplain.info, Node: Verbatim listing, Next: Contents, Prev: 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. + + Normally, the `\listing' command will add a final empty line at the +end of the output, even if the file does not end in a newline. To +suppress this final line, you can say `\let\setuplistinghook = +\nolastlinelisting'. This also works with line numbers (say +`\def\setuplistinghook{\linenumberedlisting \nolastlinelisting}'), but +only if `\printlistinglineno' consists exclusively of boxes at the top +level (i.e., any `\kern's or glue should be wrapped up in a box). + + You can use the form feed control character (ASCII code 12, typed as +`CTRL-L') in the file to force a page break in the output. + + 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 (*note Category codes::). + + +File: eplain.info, Node: Contents, Next: Cross-references, Prev: 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. + +* Menu: + +* Writing the .toc file:: +* Reading the .toc file:: +* Changing the .toc file's root name:: +* Alternative contents files:: + + +File: eplain.info, Node: Writing the .toc file, Next: Reading the .toc file, Up: Contents + +4.8.1 Writing the .toc file +--------------------------- + +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}' (unless PART is an integer, see +below). 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} + + A variation on `\writenumberedtocentry' is `\writenumberedtocline', +differing only in the order of the parameters it takes and writes for +the `\tocPARTentry' control sequences. To continue the previous +example: + + \writenumberedtocline{chapter}{\the\chapno}{A $\sin$ wave} + +writes the following to the .toc file: + + \tocchapterentry{3}{A $\sin$ wave}{8} + +Such ordering of the parameters allows the `\tocPARTentry' macros to +typeset the text of the entry without actually reading it as an +argument. This is required for entries which need to change character +catcodes, e.g., to produce verbatim text (*note Verbatim listing::). + + Each of `\writetocentry', `\writenumberedtocentry' and +`\writenumberedtocline' processes a numeric PART argument specially. +If you pass PART expanding to an integer, these macros write into the +.toc file an entry that starts with `\tocentry{PART}'. Thus, you can +define a single `\tocentry' macro which formats all entries for a table +of contents. To continue the previous examples: + + \writenumberedtocentry{1}{A $\sin$ wave}{\the\chapno} + \writenumberedtocline{1}{\the\chapno}{A $\sin$ wave} + \writetocentry{2}{A section title} + +writes the following to the .toc file: + + \tocentry{1}{A $\sin$ wave}{3}{8} + \tocentry{1}{3}{A $\sin$ wave}{8} + \tocentry{2}{A section title}{9} + + +File: eplain.info, Node: Reading the .toc file, Next: Changing the .toc file's root name, Prev: Writing the .toc file, Up: Contents + +4.8.2 Reading the .toc file +--------------------------- + +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', `\writenumberedtocentry' and +`\writenumberedtocline' 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 (*note 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'. + + +File: eplain.info, Node: Changing the .toc file's root name, Next: Alternative contents files, Prev: Reading the .toc file, Up: Contents + +4.8.3 Changing the .toc file's root name +---------------------------------------- + +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'. + + Note that `\writetocentry', `\writenumberedtocentry' and +`\writenumberedtocline' will open the contents file for writing only at +the first call, using the value of `\tocfilebasename' at that time. +Changing the value of `\tocfilebasename' afterwards will not affect +which file gets _written_, although it will affect which file gets +_read_ by `\readcontentsfile'. In case you need to write several +contents files from a single TeX job, use `\definecontentsfile' (*note +Alternative contents files::). + + +File: eplain.info, Node: Alternative contents files, Prev: Changing the .toc file's root name, Up: Contents + +4.8.4 Alternative contents files +-------------------------------- + +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. + + +File: eplain.info, Node: Cross-references, Next: Page references, Prev: 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. *Note 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. *Note Citations::, and *Note Lists::. + + Eplain can create hypertext links for the cross-references (*note +Cross-reference hyperlinks::). + +* Menu: + +* Defining generic references:: +* Using generic references:: + + +File: eplain.info, Node: Defining generic references, Next: Using generic references, 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. + + +File: eplain.info, Node: Using generic references, Prev: 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 ...' + + +File: eplain.info, Node: Page references, Next: Equation references, Prev: 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 (*note +Page reference hyperlinks::). + + +File: eplain.info, Node: Equation references, Next: Indexing, Prev: 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'. *Note 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 (*note +Equation reference hyperlinks::). + +* Menu: + +* Formatting equation references:: +* Subequation references:: + + +File: eplain.info, Node: Formatting equation references, Next: Subequation references, 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 want 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. + + +File: eplain.info, Node: Subequation references, Prev: 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 . + \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'. + + +File: eplain.info, Node: Indexing, Next: Justification, Prev: 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 (*note 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 (*note +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. + +* Menu: + +* Indexing terms:: Specifying what to index. +* Typesetting an index:: Printing the sorted output. +* Customizing indexing:: Creating commands and specifying extra actions. + + +File: eplain.info, Node: Indexing terms, Next: Typesetting an index, 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. + +* Menu: + +* Indexing commands:: Making index entries. +* Modifying index entries:: Ranges, see/see also, page number typesetting. +* Index entries with special characters:: +* Proofing index terms:: Noting index entries in the margins. + + +File: eplain.info, Node: Indexing commands, Next: Modifying index entries, 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} + + +File: eplain.info, Node: Modifying index entries, Next: Index entries with special characters, Prev: 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. *Note +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}' + + + +File: eplain.info, Node: Index entries with special characters, Next: Proofing index terms, Prev: Modifying index entries, Up: Indexing terms + +4.12.1.3 Index entries with special characters +.............................................. + +Indexing terms with special characters can become quite cumbersome +because you have to keep both TeX and MakeIndex happy at the same time. +For example, while `!' has no special meaning for TeX, it is a +subentry separator for MakeIndex, therefore you'd have to escape +occurrences of literal `!' in index terms. Things get even more +interesting with characters which are special in both TeX and MakeIndex. + + This in turn has some implications for the non-silent forms of the +indexing commands (*note Indexing terms::), since TeX and MakeIndex use +different conventions for escaping characters. For example, this will +not typeset the exclamation point correctly within the text, while it +will come out right inside the index, after MakeIndex strips the +quoting character (`"'): + + \idx{"!} + +This would have to be rewritten using the silent command: + + !\sidx{"!} + +In general, it is a good idea to eschew the non-silent commands +whenever index term contains anything unusual. + + To understand this keep in mind that indexing commands read the terms +verbatim so that the terms can embed almost any character, and that's +what gets written into the `.idx' file. The non-silent forms then +typeset the term by rescanning the verbatim copy, therefore for the +non-silent commands the term, besides being a valid MakeIndex input, +must also represent a valid TeX input. The silent commands don't have +this restriction--their terms only need to become valid TeX input +_after_ MakeIndex processes the `.idx' file and writes the `.ind' file. +This is what makes the non-silent commands less powerful and more +troublesome when dealing with special characters. + + Here's an example showing that terms for the silent commands can +contain almost any character: + + \sidx[see]{comments}[with %@with \verbatim %"|endverbatim] + {commenting with \verbatim %"|endverbatim} + +We didn't have to escape `%' in the sort string for MakeIndex, while we +had to put it inside the verbatim environment (*note Verbatim +listing::) in the part which MakeIndex will pass back to TeX. Also, we +had to escape the `|' character because it is special for MakeIndex. +If you have trouble understanding the reasons for the different types +of escaping used, it is best to examine the `.idx' and `.ind' files +resulting from processing the above input. + + As was mentioned, index terms can embed "almost any character", so +now we'll describe the exceptions. + + The following characters are reset to their usual meanings because +they are not useful verbatim: multiple consequent spaces are converted +into a single space; ASCII tab characters are treated as spaces; ASCII +return is treated as end-of-line (this means, among other things, that +long terms can be broken across several lines). + + You have to be careful with the begin- and end-group characters (`{' +and `}' by default). If they are matched, you don't have to do +anything special. For example: + + \sidx {braces {, }@braces + \verbatim {"|endverbatim, \verbatim }"|endverbatim} + +However, if they are not matched you have two problems on hand. The +first one is TeX--you have to instruct TeX to use something else as +begin- and/or end-group characters. Eplain provides an easy way to do +this: just define `\idxargopen' and/or `\idxargclose' to the begin- +and end-group characters you are going to use with indexing macros, and +use braces inside index terms without any restrictions. Here's an +example: + + \def\idxargopen{`\<} + \def\idxargclose{`\>} + \sidx + +In this example we've also dealt with the second problem--braces are +MakeIndex's grouping characters as well (by default), so we have +escaped unmatched braces with `"'. + + And the final note: if you need a subentry containing brackets (`[' +and `]'), avoid the optional argument of `\sidx' and friends, and use +instead MakeIndex's subentry separator to create the subentry with the +brackets in it: + + \sidx{entry!subentry with a bracket [} + + +File: eplain.info, Node: Proofing index terms, Prev: Index entries with special characters, Up: Indexing terms + +4.12.1.4 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. + + +File: eplain.info, Node: Typesetting an index, Next: Customizing indexing, Prev: 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 (*note 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' (*note 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 (*note 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'. + + +File: eplain.info, Node: Customizing indexing, Prev: 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 (*note 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 contained in `trimsee' distributed with Eplain in the `util' +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. + + +File: eplain.info, Node: Justification, Next: Tables, Prev: 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} + + +File: eplain.info, Node: Tables, Next: Margins, Prev: 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 +`http://www.ctan.org/tex-archive/macros/texsis', 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. + + +File: eplain.info, Node: Margins, Next: Multiple columns, Prev: 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 + + +File: eplain.info, Node: Multiple columns, Next: Footnotes, Prev: 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 `\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. + + +File: eplain.info, Node: Footnotes, Next: Fractions, Prev: 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 (*note +Footnote hyperlinks::). + + +File: eplain.info, Node: Fractions, Next: Paths, Prev: 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 23/64 (you can't see +the difference in the Info file). + + +File: eplain.info, Node: Paths, Next: Logos, Prev: 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'. + + +File: eplain.info, Node: Logos, Next: Boxes, Prev: 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'. + + +File: eplain.info, Node: Boxes, Next: Checking for PDF output, Prev: Logos, Up: User definitions + +4.21 Boxes +========== + +The solid rectangle that Eplain uses as a marker in unordered lists +(*note 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. *Note Rules::. + + +File: eplain.info, Node: Checking for PDF output, Next: Loading LaTeX packages, Prev: 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'. + + +File: eplain.info, Node: Loading LaTeX packages, Prev: 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 (*note Packages known to work::). If you discover a +working package which is not in the list, please report it to the +Eplain mailing list (*note 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. + +* 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. + + +File: eplain.info, Node: The \usepackage command, Next: Environment for loading packages, 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. + + +File: eplain.info, Node: Environment for loading packages, Next: Packages known to work, Prev: 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. + + Some packages (and the pseudo-LaTeX environment, `miniltx.tex') +redefine TeX's primitive `\input' to be a macro. Non-primitive +`\input' is probably not what the user expects under plain TeX. +Therefore, at the beginning of the `\beginpackages...\endpackages' +block Eplain saves the meaning of `\input' as `\eplaininput' and +restores the original `\input' at the end of the block. This usually +means that the primitive `\input' is restored, unless you (or some +other macro package you've loaded directly) have redefined it before +calling `\beginpackages'. In case you need to access the +package-provided `\input', Eplain saves it as `\packageinput'. + + Sometimes you may encounter packages which make conflicting +redefinitions of `\input'. Common symptoms are TeX spewing +incomprehensible error messages or hanging in a loop at a call to +`\input'. This sometimes can be cured by restoring `\input' to +`\eplaininput' before loading each package. For example: + + \beginpackages + \usepackage{pack1} + \let\input\eplaininput + \usepackage{pack2} + \endpackages + + +File: eplain.info, Node: Packages known to work, Next: Packages known not to work, Prev: 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/misc/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. + + *Warning 1:* If you encounter problems loading one of these + packages under pdfTeX (more specifically, when pdfTeX reads + `supp-mis.tex'), the cause may be an outdated `supp-mis.tex' (part + of ConTeXt, a typesetting system for TeX) installed on your + system. The problem was fixed in `supp-mis.tex' + version 2004.10.26. You can obtain up-to-date versions of + `supp-mis.tex' and the accompanying `supp-pdf.tex' from + `http://www.ctan.org/tex-archive/macros/pdftex/graphics'. To + convince TeX to use the new files, you have the following options + in the decreasing order of preference: + + 1. put the new files in the same directory with your document; + + 2. overwrite the outdated files installed by your TeX + distribution; + + 3. install the new `supp-mis.tex' and `supp-pdf.tex' files in + the relevant subdirectory of your local `texmf' tree (for + info on TeX directory structure see + `http://www.tex.ac.uk/cgi-bin/texfaq2html?label=tds'); + + 4. upgrade your ConTeXt installation. + + Note that option 1 is the safest but provides the fix only for + your current document. Options 2 and 3 will usually suffice for + Eplain but may break ConTeXt. Option 4 is the most general but is + more complicated than the first three. Be sure to backup any + files you overwrite. Also keep in mind that upgrading your TeX + distribution may overwrite files you install in the system `texmf' + tree. + *End of warning 1.* + + *Warning 2:* If you encounter problems using the `\pagecolor' + command from the `color.sty' package under pdfTeX, the cause may + be an outdated pdfTeX color and graphics driver `pdftex.def'. The + problem was fixed in `pdftex.def' version 0.03p. You can obtain + an up-to-date version from + `http://www.ctan.org/tex-archive/graphics/pdftex/pdftex.def'. + *End of warning 2.* + + The `graphics'/`graphicx' packages have the option `draft' which + instructs `\includegraphics' not to include the graphics but + instead typeset a box with the dimensions of the graphics and the + name of the graphics file in typewriter type at the center of the + box. These packages expect the LaTeX-provided command `\ttfamily' + to switch to the typewrite type. This command is not defined by + `miniltx.tex', therefore Eplain defines it and makes it equivalent + to plain TeX's `\tt'. + + *Note Hyperlinks (xhyper.tex)::, for the demonstration of text + rotation and graphics inclusion using the `graphicx' package, and + using the `color' package to colorize hypertext links. + + Klaus Ho"ppner has written a nice introduction to the LaTeX + graphics packages and different graphics formats. You can + download it from + `http://www.tug.org/pracjourn/2005-3/hoeppner' + +epstopdf (`2001/02/04 v1.1 Conversion with epstopdf on the fly (HO)') + `http://www.ctan.org/tex-archive/macros/latex/contrib/oberdiek' + + This package does on-the-fly conversion of Encapsulated PostScript + (EPS) graphics into Portable Document Format (PDF) graphics for + inclusion with the `\includegraphics' command from the + `graphics'/`graphicx' packages, so that you do not have to + explicitly call the `epstopdf' script. + +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. + +soul (`2003/11/17 v2.4 letterspacing/underlining (mf)') + `http://www.ctan.org/tex-archive/macros/latex/contrib/soul' + + This package provides hyphenatable letterspacing (spacing out), + underlining, and some derivatives. The package is optimized for + LaTeX, but works with plain TeX--you don't actually need to load + it with the `\usepackage' command, just say `\input soul.sty'. If + you intend to use the highlighting macros of `soul', don't forget + to load the `color' package. + +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 (*note + URL hyperlinks::). + + Be sure to get a version dated at least 2005/06/27, as older + versions have problems in plain TeX. + + +File: eplain.info, Node: Packages known not to work, Prev: 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: + +hyperref + `http://www.ctan.org/tex-archive/macros/latex/contrib/hyperref' + + This package depends heavily on LaTeX, so that it is mostly + unusable outside of LaTeX. Eplain provides its own macros for + creating hyperlinks, see *Note Hyperlinks::. + +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' + + +File: eplain.info, Node: Hyperlinks, Next: Arrow theoretic diagrams, Prev: 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. + +* Menu: + +* Introduction to hyperlinks:: +* Explicit hyperlinks:: +* Implicit hyperlinks:: +* Hyperlink drivers:: +* Setting hyperlink types and options:: +* Turning hyperlinks on/off:: + + +File: eplain.info, Node: Introduction to hyperlinks, Next: Explicit hyperlinks, Up: Hyperlinks + +5.1 Introduction to hyperlinks +============================== + +The original TeX engine has no built-in support for hyperlinks (a.k.a. +hypertext links). 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 three drivers: `hypertex' (implementation of the HyperTeX +standard, see `http://arxiv.org/hypertex'), and `pdftex' and `dvipdfm' +(named after the programs which process the hyperlink commands, pdfTeX +and dvipdfm). Therefore, Eplain can only produce HyperTeX commands and +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 +`hypertex' driver is loaded. The detection is based on the `\ifpdf' +switch (*note 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 or the HyperTeX +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 +(*Note Explicit hyperlinks::, and *Note 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). + + *Note Hyperlink drivers::, for the description of hyperlink types and +options supported by the drivers. *Note Setting hyperlink types and +options::, for the information on how to set hyperlink options. + + +File: eplain.info, Node: Explicit hyperlinks, Next: Implicit hyperlinks, Prev: 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 (*note 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, *note Setting +default types and options::). + + The LABEL argument of both `\hldest' and `\hlstart' can contain +special characters (such as `#', `%', `&', `~', etc.) without any +escaping. This is especially important for URL links supported by some +drivers (*note Hyperlink drivers::). + + 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. + + *Note Hyperlinks (xhyper.tex)::, for a demonstration of the usage of +explicit hyperlinks. + + +File: eplain.info, Node: Implicit hyperlinks, Next: Hyperlink drivers, Prev: 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. + + *Note Setting hyperlink types and options::, for information on how +to set parameters for a group. + + Here is the list of the linkgroups: + + hrefint, hrefext, url, cite, ref, xref, eq, idx, foot, footback. + + And here are the destgroups: + + bib, li, definexref, xrdef, eq, idx, foot, footback. + + *Note Hyperlinks (xhyper.tex)::, for a demonstration of the usage of +implicit hyperlinks. + + The following subsections describe each of the linkgroups and +destgroups and the hyperlink support provided. + +* Menu: + +* General hyperlinks:: hrefint, hrefext +* 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:: + + +File: eplain.info, Node: General hyperlinks, Next: URL hyperlinks, Up: Implicit hyperlinks + +5.3.1 General hyperlinks: hrefint, hrefext +------------------------------------------- + +`\href{URL}{TEXT}' typesets TEXT as a link to URL. It basically does +what the explicit hyperlink macros do (*note Explicit hyperlinks::), +but is more convenient (at the expense of flexibility). + + If URL starts with `#', the rest of URL is assumed to be a local +hyperlink destination name (destination within the same document). +Parameters for these links can be set by customizing the `hrefint' +linkgroup. For example: + + See \href{#intro}{Introduction} + +will make `Introduction' into an internal link, which might have been +created, e.g., with `\xrdef{intro}'. + + If URL does not start with `#', it is assumed to be a URL link. +Parameters for these links can be set by customizing the `hrefext' +linkgroup. The special characters (such as `#' and `~') in the URL +don't need to be escaped. For example: + + \href{http://tug.org/eplain/doc/eplain.html#Hyperlinks}{Hyperlinks + in Eplain} + +*Note URL hyperlinks::, for another way to create URL hyperlinks. + + The TEXT argument of `\href' can contain verbatim text (*note +Verbatim listing::) or other macros which manipulate character +catcodes. For example: + + \href{#WeirdChars}{The weird chars \verbatim #&%$~|endverbatim} + + `\href' does not currently handle other link types, such as `file:' +and `run:' links. + + +File: eplain.info, Node: URL hyperlinks, Next: Citation hyperlinks, Prev: General hyperlinks, Up: Implicit hyperlinks + +5.3.2 URL hyperlinks: url +-------------------------- + +The `url' linkgroup covers the `\url' command from the LaTeX package `url' +(*note 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]' (*note Turning hyperlinks on/off for a group::). + + By default, URL (and other types of) links are boxed, so that they +are visually marked even if you do not load the LaTeX `color' package +(*note Loading LaTeX packages::) and therefore link text is not +colored. You can see the effect by compiling the following code +snippet (be sure to get a modern `url.sty', older versions do not work +in plain TeX; *note Packages known to work::): + + \input eplain + \beginpackages + \usepackage{url} + \endpackages + + \enablehyperlinks + + \url{http://foo/bar} + \bye + + If the hyperlink driver you use supports the link option `bwidth' +(*note Hyperlink drivers::), you can produce colored links with no +border around them. Try this: + + \input eplain + \beginpackages + \usepackage{url} + \usepackage{color} + \endpackages + + \enablehyperlinks + \hlopts{bwidth=0} + + \url{http://foo/bar} + \bye + +The command `\hlopts{bwidth=0}' sets border width to zero as the +default for all links, and loading the `color' package automatically +colors links using the default color (*note Options supported by all +drivers::). If you want the border width setting to apply to URL links +only, say `\hlopts[url]{bwidth=0}' (*note Setting hyperlink types and +options::). + + +File: eplain.info, Node: Citation hyperlinks, Next: List hyperlinks, Prev: URL hyperlinks, Up: Implicit hyperlinks + +5.3.3 Citation hyperlinks: cite, bib +------------------------------------- + +The `cite' linkgroup includes only the `\cite' command (*note +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 (*note 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. + + +File: eplain.info, Node: List hyperlinks, Next: Cross-reference hyperlinks, Prev: Citation hyperlinks, Up: Implicit hyperlinks + +5.3.4 List hyperlinks: li +-------------------------- + +The `li' destgroup consists of the `\li' command (*note Lists::), which +defines a destination if you supply the optional argument +(cross-reference label). This label is also used as the hyperlink +label. + + +File: eplain.info, Node: Cross-reference hyperlinks, Next: Page reference hyperlinks, Prev: List hyperlinks, Up: Implicit hyperlinks + +5.3.5 Cross-reference hyperlinks: definexref, ref +-------------------------------------------------- + +The `definexref' destgroup is for the `\definexref' command (*note +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' (*note 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. + + +File: eplain.info, Node: Page reference hyperlinks, Next: Equation reference hyperlinks, Prev: Cross-reference hyperlinks, Up: Implicit hyperlinks + +5.3.6 Page reference hyperlinks: xrdef, xref +--------------------------------------------- + +The `xrdef' destgroup is for `\xrdef' (*note Page references::). +`\xrdef' defines a destination using cross-reference label as the +hyperlink label. + + The `xref' linkgroup includes the `\xref' command (*note 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. + + +File: eplain.info, Node: Equation reference hyperlinks, Next: Index hyperlinks, Prev: Page reference hyperlinks, Up: Implicit hyperlinks + +5.3.7 Equation reference hyperlinks: eq +---------------------------------------- + +All commands that define equation labels are part of the `eq' destgroup. +These are `\eqdef', `\eqdefn', `\eqsubdef' and `\eqsubdefn' (*note +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' (*note 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. + + +File: eplain.info, Node: Index hyperlinks, Next: Footnote hyperlinks, Prev: Equation reference hyperlinks, Up: Implicit hyperlinks + +5.3.8 Index hyperlinks: idx +---------------------------- + +All indexing commands (`\idx', `\idxname', `\idxmarked', +`\idxsubmarked' and their silent equivalents, *note 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}' +(*note 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 (*note +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. + +* 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:: + + +File: eplain.info, Node: Exact destinations for index terms, Next: Page destinations for index terms, Up: Index hyperlinks + +5.3.8.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). + + +File: eplain.info, Node: Page destinations for index terms, Next: Choosing destination placement, Prev: Exact destinations for index terms, Up: Index hyperlinks + +5.3.8.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} + +(*note Page list and page range parsers::). + + +File: eplain.info, Node: Choosing destination placement, Next: Index page list and page range parsers, Prev: Page destinations for index terms, Up: Index hyperlinks + +5.3.8.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"). + + +File: eplain.info, Node: Index page list and page range parsers, Next: Hyperlinks in see and see also entries, Prev: Choosing destination placement, Up: Index hyperlinks + +5.3.8.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. *Note Page list and page range +parsers::, for the description of these commands and an example of their +usage. + + +File: eplain.info, Node: Hyperlinks in see and see also entries, Prev: Index page list and page range parsers, Up: Index hyperlinks + +5.3.8.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' (*note 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} + + +File: eplain.info, Node: Footnote hyperlinks, Next: Contents hyperlinks, Prev: Index hyperlinks, Up: Implicit hyperlinks + +5.3.9 Footnote hyperlinks: foot, footback +------------------------------------------ + +The `foot' link and destination groups include the `\numberedfootnote' +and `\footnote' macros (*note 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. + + Generally, footnote hyperlinks are not of much use, because the +footnotes are usually placed on the same page as the footnote mark. +Therefore, footnote hyperlinks are disabled by default. Here is how you +can turn them on selectively, without affecting the other kinds of +hyperlinks (*note Turning hyperlinks on/off for a group::): + + \hldeston[foot,footback] + \hlon[foot,footback] + + +File: eplain.info, Node: Contents hyperlinks, Prev: Footnote hyperlinks, Up: Implicit hyperlinks + +5.3.10 Contents hyperlinks +-------------------------- + +There is currently no special support for hyperlinks in the table of +contents (*note Contents::), but implementing them with the `\hldest' +and `\hlstart ... \hlend' commands (*note Explicit hyperlinks::) should +be possible. + + +File: eplain.info, Node: Hyperlink drivers, Next: Setting hyperlink types and options, Prev: 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. + +* Menu: + +* Options supported by all drivers:: +* Hyperlink driver hypertex:: +* Hyperlink drivers pdftex and dvipdfm:: +* Hyperlink driver nolinks:: + + +File: eplain.info, Node: Options supported by all drivers, Next: Hyperlink driver hypertex, 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 (*note + 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} + + +File: eplain.info, Node: Hyperlink driver hypertex, Next: Hyperlink drivers pdftex and dvipdfm, Prev: Options supported by all drivers, Up: Hyperlink drivers + +5.4.2 Hyperlink driver `hypertex' +--------------------------------- + +HyperTeX is a standard for inclusion of hyperlink information in TeX +(and LaTeX) documents (see `http://arxiv.org/hypertex'). This standard +defines a set of hyperlink tags implemented as `\special' commands +written into the DVI file. The major advantage of such standard is +that a single `.dvi' file containing HyperTeX commands can be viewed by +any HyperTeX-enabled viewer (e.g., any more or less modern version of `xdvi') +or converted to other file formats (e.g., PDF) by any HyperTeX-enabled +DVI converter (e.g., `dvipdfmx' or `dvips' with Ghostscript's `ps2pdf' +script). + + The downside to the standard is that it is by design "the common +factor" of other formats supporting hyperlinks, so many features of a +particular file format cannot be supported by HyperTeX. Therefore, if +you need to use special features of a particular format, HyperTeX is +not a good choice. For the PDF file format, Eplain provides the +`pdftex' and `dvipdfm' drivers which provide fine control over the PDF +options (*note Hyperlink drivers pdftex and dvipdfm::). + + For more information on programs which support the HyperTeX standard, +please see + + `http://arxiv.org/hypertex' + `http://www.tug.org/tex-archive/support/hypertex/hypertex' + +For convenience, we list a few HyperTeX-enabled converters: + +`dvips' + Note that you need to pass the `-z' option to `dvips' to tell it + to preserve the information about the hyperlinks. To generate a + `.pdf' file with hyperlinks, you can use the `ps2pdf' script of Ghostscript. + For example, if `foo.tex' is a TeX file using HyperTeX commands, + then + + prompt$ tex foo.tex + prompt$ dvips -z foo.dvi -o + prompt$ ps2pdf foo.ps + + will produce `foo.pdf' with hyperlinks. + +`dvipdfm' +`dvipdfmx' + No special command line arguments are required, these programs + automatically detect the HyperTeX commands. + + + One more note is in place: support for the HyperTeX commands varies +from one previewer/converter to another, so you might need to experiment +to see if what you need is supported by the program(s) you intend to +use. For example, dvips(k) as of version 5.92b converts all internal +hyperlinks into page links pointing to a page containing the +destination, so that "exact" linking to destinations is not possible +(this was confirmed to be a bug and most probably has already been fixed +in later versions of dvips(k)); dvipdfm as of version 0.13.2c and +dvipdfmx as of version 20040411 do not correctly parse links to +external local files, and produce a URL link instead of a file link. + +* Menu: + +* Destination types for hypertex:: +* Destination options for hypertex:: +* Link types for hypertex:: +* Link options for hypertex:: + + +File: eplain.info, Node: Destination types for hypertex, Next: Destination options for hypertex, Up: Hyperlink driver hypertex + +5.4.2.1 Destination types for `hypertex' +........................................ + +`xyz' + "Current position". This is the default type. + + Example: `\hldest{xyz}{}{dest123}' + +`raw' + The destination specification (in the form of a HyperTeX + `\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 (*note Setting hyperlink types and + options::), as it does not make sense in a direct call to `\hldest'--you + can just call the raw command. + + Example: + + \makeatletter + \def\mydest{\special{html:}% + \special{html:}} + \resetatcatcode + \indent\hldest{raw}{cmd=mydest}{SpecialDest} + Special destination. + + + +File: eplain.info, Node: Destination options for hypertex, Next: Link types for hypertex, Prev: Destination types for hypertex, Up: Hyperlink driver hypertex + +5.4.2.2 Destination options for `hypertex' +.......................................... + +`cmd' + Name of the macro (without the leading `\') containing a HyperTeX + `\special' for the `raw' destination. + + *Note Destination types for hypertex::, the description of the + `raw' destination, for an example. + + +File: eplain.info, Node: Link types for hypertex, Next: Link options for hypertex, Prev: Destination options for hypertex, Up: Hyperlink driver hypertex + +5.4.2.3 Link types for `hypertex' +................................. + +`name' + Go to a "named destination". The label is the destination name. + All destinations in HyperTeX are named destinations. This is the + default type. + + Example: `\hlstart{name}{}{dest123}Link to dest123\hlend' + +`url' + Go to a URL. The label is the URL. + + Example: + + `\hlstart{url}{}{http://tug.org/eplain/}Eplain home\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. The file name extension can be specified separately by the `ext' + option. The idea is to set the `ext' option globally at the + beginning of the document to avoid hard-coding the extension + together with the file name within each link--HyperTeX is not + restricted to any single output format, it can be DVI, PDF, + possibly other formats. + + Example: + + \hlopts{ext=.pdf} + \hlstart{filename}{file=book}{dest123} + Link to dest123 in file `book.pdf'\hlend + +`raw' + The link specification (in the form of a HyperTeX `\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. Use the predefined command `\hlhash' to + insert the `#' characters. This option is intended to be used + with linkgroups (*note Setting hyperlink types and options::), as + it does not make sense in a direct call to `\hlstart'--you can + just call the raw command. + + Example: + + \makeatletter + \def\mylink{\special{html:}} + \resetatcatcode + \hlstart{raw}{cmd=mylink}{SpecialDest} + Link to the special destination.\hlend + + + +File: eplain.info, Node: Link options for hypertex, Prev: Link types for hypertex, Up: Hyperlink driver hypertex + +5.4.2.4 Link options for `hypertex' +................................... + +`cmd' + Name of the macro (without the leading `\') containing a HyperTeX + `\special' for the `raw' link. + + *Note Link types for hypertex::, the description of the `raw' link, + for an example. + +`file' + File name for the `filename' link type. See also the `ext' option. + + *Note Link types for hypertex::, the description of the `filename' + link, for an example. + +`ext' + File name extension for the `filename' link type. The idea is to + set the `ext' option globally at the beginning of the document to + avoid hard-coding the extension together with the file name within + each link--HyperTeX is not restricted to any single output format, + it can be DVI, PDF, possibly other formats. + + *Note Link types for hypertex::, the description of the `filename' + link, for an example. + + +File: eplain.info, Node: Hyperlink drivers pdftex and dvipdfm, Next: Hyperlink driver nolinks, Prev: Hyperlink driver hypertex, Up: Hyperlink drivers + +5.4.3 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. + +* 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:: + + +File: eplain.info, Node: Destination types for pdftex and dvipdfm, Next: Destination options for pdftex and dvipdfm, Up: Hyperlink drivers pdftex and dvipdfm + +5.4.3.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 (*note Setting + hyperlink types and options::), as it does not make sense in a + direct call to `\hldest'--you can just call the raw command. + + Example for `pdftex': + + \makeatletter + \def\mydest{\pdfdest name{\@hllabel} xyz} + \resetatcatcode + \hldesttype{raw} + \hldestopts{cmd=mydest} + + Example for `dvipdfm': + + \makeatletter + \def\mydest{\special{pdf: dest (\@hllabel) + [@thispage /XYZ @xpos @ypos 0]}} + \resetatcatcode + \hldesttype{raw} + \hldestopts{cmd=mydest} + + +File: eplain.info, Node: Destination options for pdftex and dvipdfm, Next: Link types for pdftex and dvipdfm, Prev: Destination types for pdftex and dvipdfm, Up: Hyperlink drivers pdftex and dvipdfm + +5.4.3.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. + + *Note Destination types for pdftex and dvipdfm::, the description + of the `raw' destination, for an example. + +`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} + + +File: eplain.info, Node: Link types for pdftex and dvipdfm, Next: Link options for pdftex and dvipdfm, Prev: Destination options for pdftex and dvipdfm, Up: Hyperlink drivers pdftex and dvipdfm + +5.4.3.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 + (*note Explicit hyperlinks::). This is the default type. + + Example: `\hlstart{name}{}{dest123}Link to dest123\hlend' + +`url' + Go to a URL. The label is the URL. + + Example: `\hlstart{url}{}{http://tug.org/eplain/}Eplain + home\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 + +`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. In the + definition of `\CS', use `\@hllabel' to refer to the hyperlink + label. This option is intended to be used with linkgroups (*note + Setting hyperlink types and options::), as it does not make sense + 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 <>}} + \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' + + +File: eplain.info, Node: Link options for pdftex and dvipdfm, Prev: Link types for pdftex and dvipdfm, Up: Hyperlink drivers pdftex and dvipdfm + +5.4.3.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. + + *Note Link types for pdftex and dvipdfm::, the description of the + `raw' link, for an example. + +`file' + File name for the `filename' and `filepage' link types. + + *Note Link types for pdftex and dvipdfm::, the descriptions of the + `filename' and `filepage' links, for an example. + +`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. + + *Note Link types for pdftex and dvipdfm::, the descriptions of the + `filename' and `filepage' links, for an example. + +`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. + + *Note Link types for pdftex and dvipdfm::, the descriptions of the + `page' and `filepage' links, for an example. + +`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 + + +File: eplain.info, Node: Hyperlink driver nolinks, Prev: Hyperlink drivers pdftex and dvipdfm, Up: Hyperlink drivers + +5.4.4 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' +(*note 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. + + So, if you are planning to produce versions of your PDF document +both with and without hyperlinks, here is the recommended way to enable +the hyperlinks under pdfTeX: + + \ifpdf + \enablehyperlinks + \else + \enablehyperlinks[nolinks]% + \fi + + +File: eplain.info, Node: Setting hyperlink types and options, Next: Turning hyperlinks on/off, Prev: 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. + +* Menu: + +* Setting default types and options:: +* Setting group types:: +* Setting group options:: + + +File: eplain.info, Node: Setting default types and options, Next: Setting group types, 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 (*note 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. + + Many people regard the default boxed links as not aesthetic and +intruding on page layout. The reason why boxed links are the default is +that the links are not colored until you load the LaTeX `color' package +(*note Loading LaTeX packages::) or use other means to define the +`\color' command; therefore, not producing any kind of link border may +result in the links not being marked in any way. However, when the +links are actually colored, there is no need to produce the link boxes +anymore; to avoid the boxes, you can set the default border width to +zero (if the driver you use supports the link option `bwidth'; *note +Hyperlink drivers::): + + \hlopts{bwidth=0} + + +File: eplain.info, Node: Setting group types, Next: Setting group options, Prev: 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. + + +File: eplain.info, Node: Setting group options, Prev: 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. + + +File: eplain.info, Node: Turning hyperlinks on/off, Prev: 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. + +* Menu: + +* Turning low-level commands on/off:: +* Turning hyperlinks on/off for a group:: + + +File: eplain.info, Node: Turning low-level commands on/off, Next: Turning hyperlinks on/off for a group, 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 + +*Note Hyperlink driver nolinks::, for the implications of using these +commands to disable hyperlinks for the entire document. + + +File: eplain.info, Node: Turning hyperlinks on/off for a group, Prev: 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 (*note 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. + + +File: eplain.info, Node: Arrow theoretic diagrams, Next: Programming definitions, Prev: Hyperlinks, Up: Top + +6 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:: + + +File: eplain.info, Node: Slanted lines and vectors, Next: Commutative diagrams, 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 + + (A vector in the 2d quadrant of length 60 pt appears here.) + + 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. + + +File: eplain.info, Node: Commutative diagrams, Prev: 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. + +* Menu: + +* Arrows and morphisms:: +* Construction of commutative diagrams:: +* Commutative diagram parameters:: + + +File: eplain.info, Node: Arrows and morphisms, Next: Construction of commutative diagrams, 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$' = (a right arrow). + +`\mapleft' + `$X\mapleft Y$' = (a left arrow). + +`\hline' + `$X\hline Y$' = (horizontal line) + +`\bimapright' + `$X\bimapright Y$' = (two right arrows). + +`\bimapleft' + `$X\bimapleft Y$' = (two left arrows) + +`\adjmapright' + `$X\adjmapright Y$' = (two adjoint arrows; left over right) + +`\adjmapleft' + `$X\adjmapleft Y$' = (two adjoint arrows; right over left) + +`\bihline' + `$X\bihline Y$' = (two horizontal lines) + + 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'. + + +File: eplain.info, Node: Construction of commutative diagrams, Next: Commutative diagram parameters, Prev: 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') + + (A commutative diagram appears here in the printed output.) + + 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') + + (A commutative diagram appears here in the printed output.) + + 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') + + (A commutative diagram appears here in the printed output.) + + 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 gamma=1.618...; the arrow +direction closest to this mean is `(3,2)'. In the second example, a +slope of -1/3 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 + + (A commutative diagram appears here.) + + 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') + + (A commutative diagram appears here.) + + 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 u(U intersection v) and (u +intersection V)v. Many diagrams may be typeset with the predefined +macros that appear here; however, ingenuity is often required to handle +special cases. + + +File: eplain.info, Node: Commutative diagram parameters, Prev: 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'. + + + +File: eplain.info, Node: Programming definitions, Next: Demo files, Prev: 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. + +* Menu: + +* Category codes:: Changing category codes. +* Allocation macros:: Non-outer versions of \newcount et al. +* Iteration:: Doing `for' and `while' 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:: + + +File: eplain.info, Node: Category codes, Next: Allocation macros, 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. + + +File: eplain.info, Node: Allocation macros, Next: Iteration, Prev: 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} + + +File: eplain.info, Node: Iteration, Next: Macro arguments, Prev: 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. To strip +leading spaces off the items, use `\For': + + \For\name:= + karl, + kathy\do{% + \message{\name}% + }% + +Note that trailing spaces are still _not_ ignored. + + Both `\for' and `\For' expand the first token of the item list +fully, so this is equivalent to the above: + + \def\namelist{karl,kathy}% + \for\name:=\namelist\do ... + +However, this won't work, either with `\for' or with `\For': + + \def\namelist{karl,kathy}% + \For\name:= \namelist\do ... + +because `\for' and `\For' expand the first token after `:=' which is +space, not `\namelist'. + + Eplain provides another kind of loops, which is an extension of plain +TeX's `\loop'. If you say: + + \loop + LOOP-TEXT + \if CONDITION + IF-TEXT + \repeat + +then LOOP-TEXT will be repeated as long as CONDITION is satisfied +(`\if' can be any of the TeX's conditional commands, without the +matching `\fi'). Eplain extends this with the optional else clause: + + \loop + LOOP-TEXT + \if CONDITION + IF-TEXT + \else + ELSE-TEXT + \repeat + +Here, LOOP-TEXT will be repeated as long as CONDITION is _not_ +satisfied. This extension is from Victor Eijkhout's TeX by Topic +(page 104). + + +File: eplain.info, Node: Macro arguments, Next: Converting to characters, Prev: 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 (*note 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' (*note +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. + + +File: eplain.info, Node: Converting to characters, Next: Expansion, Prev: 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 + ... + }% + + +File: eplain.info, Node: Expansion, Next: Obeying spaces, Prev: Converting to characters, Up: Programming definitions + +7.6 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:: +* \ifempty:: +* \ifinteger and \isinteger:: +* \futurenonspacelet:: + + +File: eplain.info, Node: \csn and \ece, Next: \edefappend, 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'. + + +File: eplain.info, Node: \edefappend, Next: Hooks, Prev: \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'. + + +File: eplain.info, Node: Hooks, Next: Properties, Prev: \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 + + +File: eplain.info, Node: Properties, Next: \expandonce, Prev: 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} + + +File: eplain.info, Node: \expandonce, Next: \ifundefined, Prev: 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} + + +File: eplain.info, Node: \ifundefined, Next: \ifempty, Prev: \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. + + +File: eplain.info, Node: \ifempty, Next: \ifinteger and \isinteger, Prev: \ifundefined, Up: Expansion + +7.6.7 `\ifempty' +---------------- + +`\ifempty{ARG} T \else F \fi' expands the T text if ARG is the empty +string, and the F text otherwise. This macro is useful when you need +to test for empty arguments to your macros, for example: + + \def\foo#1{\ifempty{#1} T \else F \fi} + + Since `\ifempty' 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. + + Note that the following code + + \def\empty{} + \ifempty\empty\message{empty}\else\message{not empty}\fi + +will produce the message `not empty'. + + +File: eplain.info, Node: \ifinteger and \isinteger, Next: \futurenonspacelet, Prev: \ifempty, Up: Expansion + +7.6.8 `\ifinteger' and `\isinteger' +----------------------------------- + +`\ifinteger{ARG} T \else F \fi' expands the T text if ARG is an +integer, and the F text otherwise. This macro can detect positive and +negative integers. + + Since `\ifinteger' 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. For +such situations Eplain provides `\isinteger', which can be used as +follows: + + \if\isinteger{ARG} T \else F \fi + + Although `\ifinteger' and `\isinteger' work well with regular input, +they are not bullet-proof. For example, the following code + + \ifinteger{12_ab}integer\else not integer\fi + +will expand to `ab_integer' (and thus would not even compile outside +math mode). + + These macros come from TeX Frequently Asked Question +(`http://www.tex.ac.uk/cgi-bin/texfaq2html'). + + +File: eplain.info, Node: \futurenonspacelet, Prev: \ifinteger and \isinteger, Up: Expansion + +7.6.9 `\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 ...} + + +File: eplain.info, Node: Obeying spaces, Next: Writing out numbers, Prev: 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.) + + +File: eplain.info, Node: Writing out numbers, Next: Mode-specific penalties, Prev: 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. + + +File: eplain.info, Node: Mode-specific penalties, Next: Auxiliary files, Prev: 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.) + + +File: eplain.info, Node: Auxiliary files, Next: User-defined environments, Prev: 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 + + +File: eplain.info, Node: User-defined environments, Next: Page list and page range parsers, Prev: 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. + + +File: eplain.info, Node: Page list and page range parsers, Prev: 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' (*note 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 (*note 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'. + + +File: eplain.info, Node: Demo files, Next: Macro index, Prev: Programming definitions, Up: Top + +8 Demo files +************ + +This chapter contains listings of source files, along with the output +they produce (where appropriate), which illustrate various aspects of +Eplain. The files can be found in the `demo' subdirectory of Eplain +distribution. These demos, both the sources and the compiled PDF and +PS files, are also available from `http://tug.org/eplain/demo'. + +* Menu: + +* Hyperlinks (xhyper.tex):: +* Highlighting TeX comments in listings (lscommnt.tex):: + + +File: eplain.info, Node: Hyperlinks (xhyper.tex), Next: Highlighting TeX comments in listings (lscommnt.tex), Up: Demo files + +8.1 Hyperlinks (`xhyper.tex') +============================= + +% (This file is public domain.) +% +% This file demonstrates the following features of Eplain: +% +% - explicit and implicit hyperlinks; +% - symbolic cross-references; +% - inserting external graphics using |\includegraphics| from +% the \LaTeX\ package |graphicx.sty|. +% - rotating text using |\rotatebox| from |graphicx.sty|. +% +% The compiled demo can be downloaded from +% +% http://tug.org/eplain/demo +% +% In order to compile this file yourself, you will need the CTAN lion +% drawing by Duane Bibby from +% +% ftp://tug.ctan.org/ftpmaint/CTAN_lion/ctan_lion_350x350.png +% +% (thanks, |www.ctan.org|). Place the image file in the same +% directory with this file, and change to that directory. Now, to +% produce a PDF, run twice the command +% +% pdftex xhyper.tex +% +% During the first run, Eplain will write the information about the +% cross-references into |xhyper.aux|, and during the second run this +% information will be read by Eplain to typeset the references. +% +% Demo case: +% +% Suppose you are using pdf\TeX, have a figure you want to insert +% scaled to $200\,pt$ horizontally, and you want this figure to +% completely fill the PDF viewer's window whenever the reader +% selects a link pointing to this figure. Additionally, you want to +% typeset some text as live hyperlinks, clicking on which will start +% a Web browser and open a URL. + +\input eplain + +% Load \LaTeX\ packages. +\beginpackages + % |url.sty| provides the |\url| command which we will use to typeset + % a URL. We request that |url.sty| be the version from June~27, + % 2005, or later, because earlier versions had problems interacting + % with plain \TeX. + \usepackage{url}[2005/06/27] + % |color.sty| provides support for colored text; all hyperlinks are + % automatically colored by Eplain when this package is loaded. We give + % the |dvipsnames| option because we want to use named colors from the + % |dvips| graphics driver. + \usepackage[dvipsnames]{color} + % Finally, we load |graphicx.sty|, for the macros |\includegraphics| + % and |\rotatebox|. + \usepackage{graphicx} +\endpackages + +% Remember that hyperlinks are off by default. Therefore, we need to +% enable them. +\enablehyperlinks + +% Customize some hyperlink options. First, we set border width to~$0$ +% for all links to get rid of the default boxes around links (we +% prefer colored links over the boxed links). Next, we say that all +% links created by the |url| hyperlink group (which means the |\url| +% command from |url.sty|) must be colored using the named color +% |BlueViolet|. +\hlopts{bwidth=0} +\hlopts[url]{colormodel=named,color=BlueViolet} + +% Inhibit page numbering (we have only one page). +\nopagenumbers + +% Define a class word for the cross-reference class |figure|. This +% word, when defined, will be automatically prepended by Eplain to the +% reference created by |\ref| (read on to see its use). +\def\figureword{fig.} + +% Allocate a count register for the figure's number, and a box +% register which we'll use to measure dimensions of the image. +\newcount\fignumber +\newbox\imgbox + +% Now comes the fun part--constructing the figure for the image of the +% \CTAN\ lion. We define a macro +% +% \fig{LABEL}{FILENAME}{CAPTION}{WIDTH} +% +% which creates a figure using LABEL for the cross-reference and +% hyperlink label, reading the image from file FILENAME, using CAPTION +% to name the figure, and WIDTH to scale the image horizontally. +\def\fig#1#2#3#4{% + % Leave some space above the figure. This will also ensure that we + % are in the vertical mode before we produce a |\vbox|. + \medskip + % Advance the figure number. |\global| ensures that the change to + % the count register is global, even when |\fig| is buried inside a + % group. + \global\advance\fignumber by 1 + % We use |\includegraphics| (from |graphicx.sty|) to load the image, + % scaled to the specified width, into our ``measuring'' box + % |\imgbox|. + \setbox\imgbox = \hbox{\includegraphics[width=#4]{#2}}% + % To make the demo even more exciting, let's put the figure's + % caption to the left of the image into the |\indent| space of the + % new paragraph, and rotate the caption~$90^\circ$. + \textindent{% + \rotatebox{90}{F{\sc IGURE}~\the\fignumber. #3}% + }% + % Continue the paragraph by constructing a |\vbox| with the image of + % the lion. We use |\definexref| to define the cross-reference + % label. + \vbox{% + % In addition to the cross-reference label, |\definexref| will + % create a hyperlink destination with the same label. Therefore, + % we customize this destination to do what we need. We say that + % destination type for the hyperlink group |definexref| (to which + % |\definexref| belongs) should be |fitr|. This destination type + % will magnify the rectangle specified by the options |width|, + % |height| and |depth| to the PDF viewer's window. Therefore, we + % set those options accordingly with |\hldestopts| (notice the use + % of |depth| instead of |height|---we will want the rectangle to + % extend {\it downward}, to cover the image which will come + % next). Notice that these settings will be isolated within the + % current group (i.e., the |\vbox| we're constructing). + \hldesttype[definexref]{fitr}% + \hldestopts[definexref]{width=\wd\imgbox,height=0pt,depth=\ht\imgbox}% + % We define a symbolic label so that we can later refer + % to the figure with |\ref|. The command |\definexref| does + % exactly that. The last argument to |\definexref| specifies + % class of the label, which determines the word used by |\ref| in + % front of the reference text (remember that we've defined + % |\figureword| above). + \definexref{#1}{\the\fignumber}{figure}% + % Finally, produce the image which we've been stashing in the box + % register |\imgbox|. + \box\imgbox + }% + \medskip +} + +% Create the figure. +\fig{CTANlion}{ctan_lion_350x350}{Lion in the archives}{200pt} + +% Finished with the fun part, we can relax and typeset some +% hyperlinks. The easiest way to do that is to use the |\ref| +% cross-reference command. We can even pass an optional argument +% (|the lion in|), which will be placed before the class word (|fig.|) +% and become part of the link (to make sure the reader does not have +% to aim too hard). +Show me \ref[the lion in]{CTANlion}. + +% If you are the restless kind, here's another way to create a +% hyperlink to the image: we create a link explicitly by using +% |\hlstart ... \hlend|. We don't specify the link type, therefore +% the default type |name| will be used (these are ``named links'', +% i.e., links pointing to destinations identified by labels). In the +% options argument, we specify that the border of the link should be +% inverted when the user clicks the link (|hlight=O|), and also set +% special color for this link, overriding the default dark-red. The +% label for the destination is the same as the cross-reference label, +% |CTANlion|. +Show me +\hlstart{}{hlight=O,colormodel=named,color=OliveGreen}{CTANlion} + the CTAN lion\hlend. + +% Let's now point somewhere outside our document. Eplain homepage is +% a good target. In the similar spirit, let's consider two +% approaches. The easy one is to use the |\url| command from +% |url.sty|. Remember that we have customized the color of |url| +% hyperlinks, so this one will show up with a different color than the +% default dark-red. +Take me to \url{http://tug.org/eplain}. + +% The second approach is to create an explicit URL link. We specify +% yet another border highlighting mode, |P|, which means that the +% region underneath the bounding box of the link will be drawn inset +% into the page. Also, let's set the color of the hyperlink to an RGB +% color |0.4,0.1,0.4|. Since we cannot use commas to separate the +% color elements inside the options parameter to |\hlstart| (commas +% there separate options), we have to first create a user-defined +% color with |\definecolor| from |color.sty|, and use that in +% |\hlstart|. +\definecolor{mycolor}{rgb}{0.4,0.1,0.4} + +Take me to +\hlstart{url}{hlight=P,colormodel=,color=mycolor}{http://tug.org/eplain} + Eplain homepage\hlend. + +\bye + + +File: eplain.info, Node: Highlighting TeX comments in listings (lscommnt.tex), Prev: Hyperlinks (xhyper.tex), Up: Demo files + +8.2 Highlighting TeX comments in listings (`lscommnt.tex') +========================================================== + +% (This file is public domain.) +% Demonstrate how Eplain can be used to include a TeX source file +% verbatim, typesetting comments in colored italic typewriter type. + +% Load Eplain and LaTeX's color.sty package. +\input eplain +\beginpackages \usepackage{color} \endpackages +\nopagenumbers % Disable page numbers. +\font\commentfont = cmitt10 % Font for the comments (italic \tt). +% We'll define some `protected' macros with `@' in their names. +\makeatletter +% Define an equivalent of Eplain's \letreturn, to be able to assign +% various actions to the (active) percent character. +\begingroup \makeactive\% + \gdef\letpercent{\let%} +\endgroup +% The listing hook to be called in \setuplistinghook, see below. It +% makes `%' active and assigns it a `start comment' action. +\def\hlightcommentslisting{\makeactive\% \letpercent\start@comment}% +% This is what `%' is aliased to before a comment is started. +\def\start@comment{% + \leavevmode % Needed in the very first line of the input to process + % the new par (possibly inserting line number) before we + % kick in with the color and stuff. + \begingroup % Isolate color and font changes and the redefinitions. + \commentfont + \color[cmyk]{0.28,1,1,0.35}% + \percentchar % Produce the actual `%' and + \letpercent\percentchar % make all following `%'s do the same. + \letreturn\end@comment % Call \end@comment at end-of-line. +} +% \end@comment (alias for ^^M inside a comment) will end the comment +% started by \start@comment. We make ^^M active temporarily so that +% the active version of ^^M gets "frozen" into \end@comment. +\begingroup \makeactive\^^M % Avoid ^^M's from here on. + \gdef\end@comment{\endgroup ^^M}% +\endgroup +\resetatcatcode % Make `@' again inaccessible for use in macro names. + +% Define \setuplistinghook to setup comments highlighting, line +% numbering and omitting the last (empty) line of input. +\def\setuplistinghook{\hlightcommentslisting \linenumberedlisting + \nolastlinelisting} +% Isn't this fun? This file typesets itself, with the extra bonus of +% the pretty-printed comments and numbered source lines! +\listing{lscommnt} +\bye + + +File: eplain.info, Node: Macro index, Next: Concept index, Prev: Demo files, Up: Top + +Macro index +*********** + +[index] +* Menu: + +* @hllabel <1>: Link types for pdftex and dvipdfm. + (line 68) +* @hllabel <2>: Destination types for pdftex and dvipdfm. + (line 84) +* @hllabel <3>: Link types for hypertex. + (line 39) +* @hllabel: Destination types for hypertex. + (line 14) +* @indexproof insertion class: Proofing index terms. + (line 28) +* abovecolumnskip: Multiple columns. (line 33) +* abovecolumnspenalty: Tables. (line 32) +* abovelistpenalty: Formatting lists. (line 29) +* abovelistskip: Formatting lists. (line 29) +* abovelistskipamount: Formatting lists. (line 10) +* adjarrow: Arrows and morphisms. + (line 112) +* adjmapdown: Arrows and morphisms. + (line 90) +* adjmapleft: Arrows and morphisms. + (line 65) +* adjmapright: Arrows and morphisms. + (line 62) +* adjmapup: Arrows and morphisms. + (line 93) +* advancebottommargin: Margins. (line 28) +* advanceleftmargin: Margins. (line 28) +* advancerightmargin: Margins. (line 28) +* advancetopmargin: Margins. (line 28) +* afterindexterm: Customizing indexing. + (line 6) +* afterindexterm hook: Indexing commands. (line 63) +* AMSLaTeX: Logos. (line 10) +* AMSTeX: Logos. (line 10) +* arrow: Arrows and morphisms. + (line 20) +* bblem: Formatting bibliographies. + (line 33) +* bblfilebasename: Citations. (line 30) +* bblhook: Formatting bibliographies. + (line 55) +* bblnewblock: Formatting bibliographies. + (line 41) +* bblrm: Formatting bibliographies. + (line 30) +* bblsc: Formatting bibliographies. + (line 37) +* bcolor (hyperlink option): Link options for pdftex and dvipdfm. + (line 14) +* bdash (hyperlink option): Link options for pdftex and dvipdfm. + (line 20) +* begin for index entries: Modifying index entries. + (line 22) +* beginindex hook: Typesetting an index. + (line 30) +* beginlist: Formatting lists. (line 51) +* beginpackages: Environment for loading packages. + (line 6) +* begin{picture}: Packages known to work. + (line 14) +* begin{theindex}: Typesetting an index. + (line 17) +* belowcolumnskip: Multiple columns. (line 34) +* belowfootnoterulespace: Footnotes. (line 46) +* belowlistskip: Formatting lists. (line 30) +* belowlistskipamount: Formatting lists. (line 10) +* biarrow: Arrows and morphisms. + (line 109) +* biblabelcontents: Formatting bibliographies. + (line 23) +* biblabelextraspace: Formatting bibliographies. + (line 49) +* biblabelprint: Formatting bibliographies. + (line 17) +* biblabelwidth: Formatting bibliographies. + (line 11) +* bibliography: Citations. (line 56) +* bibliography (hyperlinks): Citation hyperlinks. (line 11) +* bibliographystyle: Citations. (line 63) +* BibTeX: Logos. (line 10) +* bihline: Arrows and morphisms. + (line 68) +* bimapdown: Arrows and morphisms. + (line 84) +* bimapleft: Arrows and morphisms. + (line 59) +* bimapright: Arrows and morphisms. + (line 56) +* bimapup: Arrows and morphisms. + (line 87) +* bisline: Arrows and morphisms. + (line 115) +* bivline: Arrows and morphisms. + (line 96) +* blackbox: Boxes. (line 7) +* blanklineskipamount in justified text: Justification. (line 24) +* blanklineskipamount in obeyed text: Obeying spaces. (line 16) +* bottom (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 56) +* bottom (destination option): Destination types for pdftex and dvipdfm. + (line 65) +* bottommargin: Margins. (line 18) +* boxit: Boxes. (line 29) +* boxitspace: Boxes. (line 31) +* bstyle (hyperlink option): Link options for pdftex and dvipdfm. + (line 26) +* bwidth (hyperlink option): Link options for pdftex and dvipdfm. + (line 50) +* catcode: Category codes. (line 13) +* center: Justification. (line 7) +* centereddisplays: Displays. (line 13) +* channelwidth <1>: Commutative diagram parameters. + (line 36) +* channelwidth: Arrows and morphisms. + (line 119) +* cite: Citations. (line 37) +* cite (hyperlinks): Citation hyperlinks. (line 6) +* cmd (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 14) +* cmd (destination option) <2>: Destination types for pdftex and dvipdfm. + (line 83) +* cmd (destination option) <3>: Destination options for hypertex. + (line 7) +* cmd (destination option): Destination types for hypertex. + (line 14) +* cmd (hyperlink option) <1>: Link options for pdftex and dvipdfm. + (line 56) +* cmd (hyperlink option) <2>: Link types for pdftex and dvipdfm. + (line 67) +* cmd (hyperlink option) <3>: Link options for hypertex. + (line 7) +* cmd (hyperlink option): Link types for hypertex. + (line 38) +* color (hyperlink option): Options supported by all drivers. + (line 37) +* colormodel (hyperlink option): Options supported by all drivers. + (line 37) +* columnfill: Multiple columns. (line 14) +* commdiag: Construction of commutative diagrams. + (line 9) +* commdiagbaselines <1>: Commutative diagram parameters. + (line 43) +* commdiagbaselines: Construction of commutative diagrams. + (line 64) +* csn: \csn and \ece. (line 6) +* definecolor: Hyperlinks (xhyper.tex). + (line 6) +* definecontentsfile: Alternative contents files. + (line 6) +* defineindex: Indexing. (line 37) +* definexref <1>: Hyperlinks (xhyper.tex). + (line 6) +* definexref: Defining generic references. + (line 6) +* definexref (hyperlinks): Cross-reference hyperlinks. + (line 6) +* depth (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 34) +* depth (destination option): Destination types for pdftex and dvipdfm. + (line 61) +* depth (hyperlink option): Link options for pdftex and dvipdfm. + (line 124) +* discretionaries: Paths. (line 20) +* displaylines: Displays. (line 18) +* doublecolumns: Multiple columns. (line 7) +* drawline: Slanted lines and vectors. + (line 6) +* drawvector: Slanted lines and vectors. + (line 6) +* dvipdfm (hyperlink driver): Hyperlink drivers pdftex and dvipdfm. + (line 6) +* eattoken: Macro arguments. (line 23) +* ece: \csn and \ece. (line 10) +* edefappend: \edefappend. (line 6) +* ehrule: Rules. (line 17) +* enablehyperlinks <1>: Hyperlink driver nolinks. + (line 48) +* enablehyperlinks <2>: Choosing destination placement. + (line 7) +* enablehyperlinks: Introduction to hyperlinks. + (line 42) +* end for index entries: Modifying index entries. + (line 22) +* endlist: Formatting lists. (line 53) +* endnumberedlist: Lists. (line 14) +* endorderedlist: Lists. (line 14) +* endpackages: Environment for loading packages. + (line 6) +* endunorderedlist: Lists. (line 22) +* end{picture}: Packages known to work. + (line 14) +* end{theindex}: Typesetting an index. + (line 17) +* eplain: Invoking Eplain. (line 30) +* eplaininput: Environment for loading packages. + (line 28) +* eqalignno: Displays. (line 18) +* eqconstruct: Formatting equation references. + (line 21) +* eqdef: Equation references. (line 15) +* eqdef (hyperlinks): Equation reference hyperlinks. + (line 6) +* eqdefn: Equation references. (line 38) +* eqdefn (hyperlinks): Equation reference hyperlinks. + (line 6) +* eqnumber: Equation references. (line 8) +* eqprint: Formatting equation references. + (line 12) +* eqref <1>: Equation reference hyperlinks. + (line 20) +* eqref: Equation references. (line 46) +* eqrefn <1>: Equation reference hyperlinks. + (line 20) +* eqrefn: Equation references. (line 52) +* eqsubdef: Subequation references. + (line 11) +* eqsubdef (hyperlinks): Equation reference hyperlinks. + (line 6) +* eqsubdefn: Subequation references. + (line 11) +* eqsubdefn (hyperlinks): Equation reference hyperlinks. + (line 6) +* eqsubreftext: Subequation references. + (line 22) +* everyfootnote: Footnotes. (line 35) +* evrule: Rules. (line 18) +* expandonce: \expandonce. (line 6) +* ext (hyperlink option) <1>: Link options for hypertex. + (line 20) +* ext (hyperlink option): Link types for hypertex. + (line 23) +* file (hyperlink option) <1>: Link options for pdftex and dvipdfm. + (line 63) +* file (hyperlink option) <2>: Link types for pdftex and dvipdfm. + (line 41) +* file (hyperlink option) <3>: Link options for hypertex. + (line 14) +* file (hyperlink option): Link types for hypertex. + (line 22) +* fileexists (conditional): Auxiliary files. (line 10) +* filename (hyperlink type) <1>: Link types for pdftex and dvipdfm. + (line 40) +* filename (hyperlink type): Link types for hypertex. + (line 21) +* filepage (hyperlink type): Link types for pdftex and dvipdfm. + (line 52) +* fit (destination type): Destination types for pdftex and dvipdfm. + (line 18) +* fitb (destination type): Destination types for pdftex and dvipdfm. + (line 39) +* fitbh (destination type): Destination types for pdftex and dvipdfm. + (line 44) +* fitbv (destination type): Destination types for pdftex and dvipdfm. + (line 52) +* fith (destination type): Destination types for pdftex and dvipdfm. + (line 23) +* fitr (destination type): Destination types for pdftex and dvipdfm. + (line 60) +* fitv (destination type): Destination types for pdftex and dvipdfm. + (line 31) +* flushleft: Justification. (line 7) +* flushright: Justification. (line 7) +* fmtversion: Introduction. (line 47) +* footnote (hyperlinks): Footnote hyperlinks. (line 7) +* footnotemarkseparation: Footnotes. (line 25) +* footnoteruleheight: Footnotes. (line 44) +* footnoterulewidth: Footnotes. (line 44) +* For: Iteration. (line 15) +* for: Iteration. (line 6) +* frac: Fractions. (line 6) +* fullmonthname: Time of day. (line 13) +* futurenonspacelet: \futurenonspacelet. (line 6) +* generaldisplay: Formatting displays. (line 10) +* getproperty: Properties. (line 18) +* gloggingall: Diagnostics. (line 23) +* gobble: Macro arguments. (line 7) +* gobbletwo: Macro arguments. (line 7) +* gridcommdiag: Construction of commutative diagrams. + (line 89) +* gtracingall: Diagnostics. (line 23) +* gutter: Multiple columns. (line 23) +* gutterbox: Multiple columns. (line 24) +* hangindent for index entries: Typesetting an index. + (line 45) +* harrowlength <1>: Commutative diagram parameters. + (line 11) +* harrowlength: Arrows and morphisms. + (line 27) +* hchannel: Commutative diagram parameters. + (line 39) +* height (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 37) +* height (destination option): Destination types for pdftex and dvipdfm. + (line 60) +* height (hyperlink option): Link options for pdftex and dvipdfm. + (line 127) +* hgrid <1>: Commutative diagram parameters. + (line 47) +* hgrid: Construction of commutative diagrams. + (line 109) +* hldest <1>: Setting hyperlink types and options. + (line 7) +* hldest <2>: Destination types for pdftex and dvipdfm. + (line 87) +* hldest <3>: Destination types for hypertex. + (line 17) +* hldest: Explicit hyperlinks. (line 6) +* hldestoff <1>: Turning low-level commands on/off. + (line 6) +* hldestoff: Hyperlink driver nolinks. + (line 10) +* hldeston: Turning low-level commands on/off. + (line 6) +* hldestopts <1>: Hyperlinks (xhyper.tex). + (line 6) +* hldestopts <2>: Setting group options. + (line 11) +* hldestopts: Setting default types and options. + (line 15) +* hldesttype <1>: Hyperlinks (xhyper.tex). + (line 6) +* hldesttype <2>: Setting group types. (line 6) +* hldesttype: Setting default types and options. + (line 6) +* hlend <1>: Hyperlinks (xhyper.tex). + (line 6) +* hlend: Explicit hyperlinks. (line 25) +* hlfootbacklabel: Footnote hyperlinks. (line 12) +* hlfootlabel: Footnote hyperlinks. (line 12) +* hlfootlabelnumber: Footnote hyperlinks. (line 14) +* hlhash: Link types for hypertex. + (line 40) +* hlidx: Exact destinations for index terms. + (line 13) +* hlidxlabel: Exact destinations for index terms. + (line 23) +* hlidxlabelnumber: Exact destinations for index terms. + (line 25) +* hlidxpage: Page destinations for index terms. + (line 20) +* hlidxpagelabel: Page destinations for index terms. + (line 11) +* hlight (hyperlink option): Link options for pdftex and dvipdfm. + (line 69) +* hlightcommentslisting: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* hline: Arrows and morphisms. + (line 53) +* hloff <1>: Turning low-level commands on/off. + (line 6) +* hloff: Hyperlink driver nolinks. + (line 10) +* hlon: Turning low-level commands on/off. + (line 6) +* hlopts <1>: Hyperlinks (xhyper.tex). + (line 6) +* hlopts <2>: Setting group options. + (line 11) +* hlopts: Setting default types and options. + (line 15) +* hlstart <1>: Hyperlinks (xhyper.tex). + (line 6) +* hlstart <2>: Setting hyperlink types and options. + (line 7) +* hlstart <3>: Link types for pdftex and dvipdfm. + (line 71) +* hlstart <4>: Link types for hypertex. + (line 43) +* hlstart: Explicit hyperlinks. (line 25) +* hltype <1>: Setting group types. (line 6) +* hltype: Setting default types and options. + (line 6) +* hmorphposn <1>: Commutative diagram parameters. + (line 20) +* hmorphposn: Arrows and morphisms. + (line 33) +* hmorphposndn <1>: Commutative diagram parameters. + (line 22) +* hmorphposndn: Arrows and morphisms. + (line 38) +* hmorphposnlft <1>: Commutative diagram parameters. + (line 23) +* hmorphposnlft: Arrows and morphisms. + (line 38) +* hmorphposnrt <1>: Commutative diagram parameters. + (line 22) +* hmorphposnrt: Arrows and morphisms. + (line 38) +* hmorphposnup <1>: Commutative diagram parameters. + (line 22) +* hmorphposnup: Arrows and morphisms. + (line 38) +* hoffset: Proofing index terms. + (line 21) +* hookaction: Hooks. (line 15) +* hookactiononce: Hooks. (line 23) +* hookappend: Hooks. (line 16) +* hookprepend: Hooks. (line 17) +* hookrun: Hooks. (line 39) +* href: General hyperlinks. (line 6) +* hruledefaultdepth: Rules. (line 9) +* hruledefaultheight: Rules. (line 9) +* hsize: Margins. (line 34) +* hypertex (hyperlink driver): Hyperlink driver hypertex. + (line 6) +* hyphenpenalty for index entries: Typesetting an index. + (line 45) +* identity: Macro arguments. (line 28) +* idx: Indexing commands. (line 8) +* idx (hyperlinks): Index hyperlinks. (line 6) +* idxargclose: Index entries with special characters. + (line 73) +* idxargopen: Index entries with special characters. + (line 73) +* idxbeginrangemark: Customizing indexing. + (line 42) +* idxencapoperator: Customizing indexing. + (line 39) +* idxendrangemark: Customizing indexing. + (line 45) +* idxexact: Choosing destination placement. + (line 8) +* idxmarked: Indexing commands. (line 29) +* idxmarked (hyperlinks): Index hyperlinks. (line 6) +* idxname: Indexing commands. (line 19) +* idxname (hyperlinks): Index hyperlinks. (line 6) +* idxnameseparator: Indexing commands. (line 19) +* idxnone: Choosing destination placement. + (line 9) +* idxpage: Choosing destination placement. + (line 9) +* idxpagei: Page list and page range parsers. + (line 6) +* idxpageii: Page list and page range parsers. + (line 6) +* idxpagelistdelimiter: Page list and page range parsers. + (line 23) +* idxpagenum: Customizing indexing. + (line 51) +* idxpagerangedelimiter: Page list and page range parsers. + (line 23) +* idxparselist: Page list and page range parsers. + (line 6) +* idxparserange: Page list and page range parsers. + (line 6) +* idxrangebeginword: Customizing indexing. + (line 20) +* idxrangeendword: Customizing indexing. + (line 23) +* idxseealsocmdword: Customizing indexing. + (line 29) +* idxseecmdword: Customizing indexing. + (line 26) +* idxsubentryseparator: Customizing indexing. + (line 36) +* idxsubmarked: Indexing commands. (line 40) +* idxsubmarked (hyperlinks): Index hyperlinks. (line 6) +* ifempty: \ifempty. (line 6) +* iffileexists: Auxiliary files. (line 10) +* ifinteger: \ifinteger and \isinteger. + (line 6) +* ifpdf <1>: Introduction to hyperlinks. + (line 51) +* ifpdf: Checking for PDF output. + (line 10) +* ifrewritetocfile: Reading the .toc file. + (line 26) +* ifundefined: \ifundefined. (line 6) +* includegraphics: Hyperlinks (xhyper.tex). + (line 6) +* indexfilebasename: Typesetting an index. + (line 11) +* indexfonts: Typesetting an index. + (line 24) +* indexitem hook: Typesetting an index. + (line 49) +* indexprooffont: Proofing index terms. + (line 12) +* indexproofterm: Proofing index terms. + (line 12) +* indexproofunbox: Proofing index terms. + (line 28) +* indexsee <1>: Hyperlinks in see and see also entries. + (line 8) +* indexsee: Customizing indexing. + (line 55) +* indexseealso <1>: Hyperlinks in see and see also entries. + (line 8) +* indexseealso: Customizing indexing. + (line 55) +* indexseealsowords: Customizing indexing. + (line 55) +* indexseeword: Customizing indexing. + (line 55) +* indexsetmargins: Proofing index terms. + (line 21) +* indexspace: Typesetting an index. + (line 54) +* innerdef: Allocation macros. (line 26) +* innerinnerdef: Allocation macros. (line 37) +* innernewbox: Allocation macros. (line 21) +* innernewcount: Allocation macros. (line 21) +* innernewdimen: Allocation macros. (line 21) +* innernewfam: Allocation macros. (line 21) +* innernewhelp: Allocation macros. (line 21) +* innernewif: Allocation macros. (line 21) +* innernewinsert: Allocation macros. (line 21) +* innernewlanguage: Allocation macros. (line 21) +* innernewread: Allocation macros. (line 22) +* innernewskip: Allocation macros. (line 22) +* innernewtoks: Allocation macros. (line 22) +* innernewwrite: Allocation macros. (line 22) +* input: Environment for loading packages. + (line 24) +* insidemargin: Proofing index terms. + (line 21) +* interfootnoteskip: Footnotes. (line 29) +* interitemskip: Formatting lists. (line 30) +* interitemskipamount: Formatting lists. (line 14) +* isinteger: \ifinteger and \isinteger. + (line 13) +* item in indexes: Typesetting an index. + (line 35) +* itemletter: Formatting lists. (line 44) +* itemnumber: Formatting lists. (line 44) +* ituline: Page list and page range parsers. + (line 26) +* jobname <1>: Auxiliary files. (line 9) +* jobname <2>: Typesetting an index. + (line 11) +* jobname: Citations. (line 17) +* LAMSTeX: Logos. (line 10) +* LaTeX: Logos. (line 10) +* lbracechar: Category codes. (line 59) +* left (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 60) +* left (destination option): Destination types for pdftex and dvipdfm. + (line 11) +* leftdisplayindent: Displays. (line 11) +* leftdisplays: Displays. (line 10) +* leftdisplaysetup: Formatting displays. (line 8) +* leftmargin: Margins. (line 18) +* leqalignno: Displays. (line 19) +* letreturn: Category codes. (line 41) +* letter: Category codes. (line 10) +* lft: Arrows and morphisms. + (line 15) +* li: Lists. (line 30) +* li (hyperlinks): List hyperlinks. (line 6) +* linenumberedlisting <1>: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* linenumberedlisting: Verbatim listing. (line 17) +* listcompact: Lists. (line 41) +* listing <1>: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* listing: Verbatim listing. (line 7) +* listingfont: Verbatim listing. (line 10) +* listleftindent: Formatting lists. (line 18) +* listmarkerspace: Formatting lists. (line 33) +* listrightindent: Formatting lists. (line 18) +* loggingall: Diagnostics. (line 12) +* loop: Iteration. (line 40) +* makeactive: Category codes. (line 13) +* makeatletter: Category codes. (line 22) +* makeatother: Category codes. (line 32) +* makeblankbox: Boxes. (line 12) +* makecolumns: Tables. (line 6) +* makeheadline: Proofing index terms. + (line 28) +* mapdown: Arrows and morphisms. + (line 13) +* mapleft: Arrows and morphisms. + (line 6) +* mapright: Arrows and morphisms. + (line 6) +* mapup: Arrows and morphisms. + (line 13) +* matrix: Construction of commutative diagrams. + (line 10) +* MF: Logos. (line 10) +* monthname: Time of day. (line 10) +* morphdist <1>: Commutative diagram parameters. + (line 32) +* morphdist: Arrows and morphisms. + (line 33) +* name (hyperlink type) <1>: Link types for pdftex and dvipdfm. + (line 18) +* name (hyperlink type): Link types for hypertex. + (line 7) +* new...: Allocation macros. (line 9) +* newwin (hyperlink option) <1>: Link options for pdftex and dvipdfm. + (line 90) +* newwin (hyperlink option): Link types for pdftex and dvipdfm. + (line 42) +* noarrow: Invoking Eplain. (line 84) +* noauxfile: Invoking Eplain. (line 89) +* nobibtex: Invoking Eplain. (line 73) +* nocite: Citations. (line 53) +* nolastlinelisting <1>: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* nolastlinelisting: Verbatim listing. (line 25) +* nolinks (hyperlink driver): Hyperlink driver nolinks. + (line 6) +* normalbaselineskip: Options supported by all drivers. + (line 19) +* num (hyperlink type): Link types for pdftex and dvipdfm. + (line 92) +* numberedfootnote: Footnotes. (line 7) +* numberedfootnote (hyperlinks): Footnote hyperlinks. (line 6) +* numberedlist: Lists. (line 14) +* numberedlistdepth: Formatting lists. (line 41) +* numberedmarker: Formatting lists. (line 37) +* numbername: Writing out numbers. (line 6) +* obeywhitespace: Obeying spaces. (line 6) +* orderedlist: Lists. (line 14) +* other: Category codes. (line 10) +* outer: Allocation macros. (line 12) +* outsidemargin: Proofing index terms. + (line 21) +* page (hyperlink type): Link types for pdftex and dvipdfm. + (line 31) +* pagefit (hyperlink option) <1>: Link options for pdftex and dvipdfm. + (line 109) +* pagefit (hyperlink option): Link types for pdftex and dvipdfm. + (line 32) +* pageno: Proofing index terms. + (line 21) +* pagetotal: Multiple columns. (line 14) +* paperheight: Margins. (line 45) +* paperwidth: Margins. (line 48) +* parindent in indexes: Typesetting an index. + (line 24) +* path: Paths. (line 13) +* pdfoutput: Checking for PDF output. + (line 20) +* pdftex (hyperlink driver): Hyperlink drivers pdftex and dvipdfm. + (line 6) +* percentchar: Category codes. (line 56) +* phantomeqlabel: Equation reference hyperlinks. + (line 14) +* phantomeqnumber: Equation reference hyperlinks. + (line 14) +* previouseverydisplay: Formatting displays. (line 15) +* printbetweencitations: Formatting citations. + (line 21) +* printcitefinish: Formatting citations. + (line 16) +* printcitenote: Formatting citations. + (line 27) +* printcitestart: Formatting citations. + (line 16) +* printitem: Formatting lists. (line 52) +* printlistinglineno: Verbatim listing. (line 19) +* quadcolumns: Multiple columns. (line 7) +* raggedright for index entries: Typesetting an index. + (line 45) +* raise (hyperlink option) <1>: Setting group options. + (line 34) +* raise (hyperlink option): Options supported by all drivers. + (line 13) +* raw (destination type) <1>: Destination types for pdftex and dvipdfm. + (line 81) +* raw (destination type): Destination types for hypertex. + (line 12) +* raw (hyperlink type) <1>: Link types for pdftex and dvipdfm. + (line 65) +* raw (hyperlink type): Link types for hypertex. + (line 37) +* rbracechar: Category codes. (line 60) +* readindexfile: Typesetting an index. + (line 6) +* readindexfile (hyperlinks): Index hyperlinks. (line 9) +* readtocfile: Reading the .toc file. + (line 6) +* ref <1>: Hyperlinks (xhyper.tex). + (line 6) +* ref: Using generic references. + (line 17) +* ref (hyperlinks): Cross-reference hyperlinks. + (line 19) +* refn: Using generic references. + (line 9) +* refn (hyperlinks): Cross-reference hyperlinks. + (line 14) +* refs: Using generic references. + (line 23) +* refs (hyperlinks): Cross-reference hyperlinks. + (line 26) +* refspace <1>: Page reference hyperlinks. + (line 10) +* refspace: Cross-reference hyperlinks. + (line 24) +* reftie <1>: Equation reference hyperlinks. + (line 20) +* reftie: Cross-reference hyperlinks. + (line 16) +* repeat: Iteration. (line 42) +* resetatcatcode: Category codes. (line 23) +* rewritetocfile (conditional): Reading the .toc file. + (line 26) +* right (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 64) +* right (destination option): Destination types for pdftex and dvipdfm. + (line 65) +* rightmargin: Margins. (line 18) +* rotatebox: Hyperlinks (xhyper.tex). + (line 6) +* rt: Arrows and morphisms. + (line 14) +* sanitize: Converting to characters. + (line 22) +* sarrowlength <1>: Commutative diagram parameters. + (line 17) +* sarrowlength: Arrows and morphisms. + (line 28) +* see for index entries <1>: Customizing indexing. + (line 64) +* see for index entries: Modifying index entries. + (line 36) +* seealso for index entries: Modifying index entries. + (line 49) +* seevariant: Customizing indexing. + (line 55) +* setidxpagelistdelimiter: Page list and page range parsers. + (line 14) +* setidxpagerangedelimiter: Page list and page range parsers. + (line 14) +* setproperty: Properties. (line 13) +* setuplistinghook <1>: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* setuplistinghook: Verbatim listing. (line 13) +* sidx: Indexing commands. (line 8) +* sidxmarked: Indexing commands. (line 29) +* sidxname: Indexing commands. (line 19) +* sidxsubmarked: Indexing commands. (line 40) +* singlecolumn: Multiple columns. (line 9) +* sline: Arrows and morphisms. + (line 23) +* SLiTeX: Logos. (line 11) +* special: Introduction to hyperlinks. + (line 9) +* specialpathdelimiters (conditional): Paths. (line 28) +* subeqnumber: Subequation references. + (line 15) +* subitem in indexes: Typesetting an index. + (line 35) +* subsubitem in indexes: Typesetting an index. + (line 35) +* testfileexistence: Auxiliary files. (line 8) +* TeX: Logos. (line 6) +* timestamp: Time of day. (line 18) +* timestring: Time of day. (line 16) +* toc...entry: Writing the .toc file. + (line 9) +* tocfilebasename: Changing the .toc file's root name. + (line 10) +* today: Time of day. (line 21) +* top (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 68) +* top (destination option): Destination types for pdftex and dvipdfm. + (line 11) +* topmargin: Margins. (line 18) +* tracingall: Diagnostics. (line 9) +* tracingboxes: Diagnostics. (line 17) +* tracingoff: Diagnostics. (line 19) +* triplecolumns: Multiple columns. (line 7) +* tt: Packages known to work. + (line 76) +* ttfamily: Packages known to work. + (line 73) +* uncatcodespecials: Category codes. (line 51) +* unorderedlist: Lists. (line 22) +* unorderedlistdepth: Formatting lists. (line 41) +* unorderedmarker: Formatting lists. (line 37) +* url: Hyperlinks (xhyper.tex). + (line 6) +* url (hyperlink type) <1>: Link types for pdftex and dvipdfm. + (line 25) +* url (hyperlink type): Link types for hypertex. + (line 14) +* url (hyperlinks): URL hyperlinks. (line 6) +* usepackage: The \usepackage command. + (line 6) +* varrowlength <1>: Commutative diagram parameters. + (line 14) +* varrowlength: Arrows and morphisms. + (line 28) +* vchannel: Commutative diagram parameters. + (line 39) +* verbatim: Verbatim listing. (line 34) +* verbatimescapechar: Verbatim listing. (line 47) +* vgrid <1>: Commutative diagram parameters. + (line 51) +* vgrid: Construction of commutative diagrams. + (line 109) +* vline: Arrows and morphisms. + (line 81) +* vmorphposn <1>: Commutative diagram parameters. + (line 26) +* vmorphposn: Arrows and morphisms. + (line 33) +* vmorphposndn <1>: Commutative diagram parameters. + (line 28) +* vmorphposndn: Arrows and morphisms. + (line 38) +* vmorphposnlft <1>: Commutative diagram parameters. + (line 29) +* vmorphposnlft: Arrows and morphisms. + (line 39) +* vmorphposnrt <1>: Commutative diagram parameters. + (line 28) +* vmorphposnrt: Arrows and morphisms. + (line 38) +* vmorphposnup <1>: Commutative diagram parameters. + (line 28) +* vmorphposnup: Arrows and morphisms. + (line 38) +* vpenalty: Mode-specific penalties. + (line 9) +* vruledefaultwidth: Rules. (line 10) +* width (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 40) +* width (destination option): Destination types for pdftex and dvipdfm. + (line 60) +* width (hyperlink option): Link options for pdftex and dvipdfm. + (line 130) +* writenumberedtocentry: Writing the .toc file. + (line 13) +* writenumberedtocline: Writing the .toc file. + (line 36) +* writetocentry: Writing the .toc file. + (line 7) +* xrdef: Page references. (line 10) +* xrdef (hyperlinks): Page reference hyperlinks. + (line 6) +* xref: Page references. (line 14) +* xref (hyperlinks): Page reference hyperlinks. + (line 10) +* xrefn: Using generic references. + (line 10) +* xrefn (hyperlinks): Cross-reference hyperlinks. + (line 14) +* xrefpageword <1>: Page reference hyperlinks. + (line 10) +* xrefpageword: Page references. (line 17) +* xrefwarning conditional: Using generic references. + (line 15) +* xrefwarningfalse: Citations. (line 73) +* xrlabel: Converting to characters. + (line 6) +* xyz (destination type) <1>: Destination types for pdftex and dvipdfm. + (line 7) +* xyz (destination type): Destination types for hypertex. + (line 7) +* zoom (destination option) <1>: Destination options for pdftex and dvipdfm. + (line 21) +* zoom (destination option): Destination types for pdftex and dvipdfm. + (line 7) + + +File: eplain.info, Node: Concept index, Prev: Macro index, Up: Top + +Concept index +************* + +[index] +* Menu: + +* .aux file <1>: Cross-references. (line 11) +* .aux file: Citations. (line 17) +* .bbl file: Citations. (line 20) +* .bib file: Citations. (line 20) +* .bst files: Citations. (line 65) +* .cls files: Loading LaTeX packages. + (line 6) +* .eps files: Packages known to work. + (line 90) +* .fmt file <1>: Invoking Eplain. (line 14) +* .fmt file: Installation. (line 27) +* .idx files <1>: Index hyperlinks. (line 14) +* .idx files: Indexing. (line 23) +* .ind files <1>: Index hyperlinks. (line 25) +* .ind files: Indexing. (line 27) +* .pdf files <1>: Introduction to hyperlinks. + (line 13) +* .pdf files <2>: Packages known to work. + (line 90) +* .pdf files: Checking for PDF output. + (line 6) +* .ps files: Introduction to hyperlinks. + (line 13) +* .sty files: Loading LaTeX packages. + (line 6) +* .toc file: Contents. (line 10) +* active characters: Category codes. (line 12) +* after index terms: Customizing indexing. + (line 6) +* alignments: Tables. (line 6) +* all groups, specifying: Setting group types. (line 26) +* allocation macros: Allocation macros. (line 6) +* alphanumeric references: Citations. (line 116) +* AMSLaTeX: Logos. (line 10) +* amsppt.sty: Invoking Eplain. (line 92) +* AMSTeX: Logos. (line 10) +* AMSTeX conflicts: Invoking Eplain. (line 92) +* arguments, ignoring: Macro arguments. (line 6) +* arrows: Arrows and morphisms. + (line 6) +* atom: Properties. (line 6) +* autopict.sty: Packages known to work. + (line 12) +* avoiding boxed links <1>: Setting default types and options. + (line 25) +* avoiding boxed links: URL hyperlinks. (line 17) +* axuiliary files, existence of: Auxiliary files. (line 6) +* backslash character: Category codes. (line 15) +* balancing of columns with \singlecolumn: Multiple columns. (line 11) +* Berry, Karl: Introduction. (line 28) +* beveled hyperlink border: Link options for pdftex and dvipdfm. + (line 26) +* bibliographies: Citations. (line 6) +* bibliography fonts: Formatting bibliographies. + (line 30) +* bibliography items, extra space between: Formatting bibliographies. + (line 55) +* bibliography, formatting the: Formatting bibliographies. + (line 6) +* bibliography, hyperlinks: Citation hyperlinks. (line 11) +* BibTeX <1>: Logos. (line 10) +* BibTeX: Citations. (line 9) +* bibtex: Invoking Eplain. (line 103) +* black boxes: Boxes. (line 6) +* Borceux, Francis: Construction of commutative diagrams. + (line 80) +* border color, hyperlink: Link options for pdftex and dvipdfm. + (line 14) +* border style, hyperlink: Link options for pdftex and dvipdfm. + (line 20) +* border width, hyperlink: Link options for pdftex and dvipdfm. + (line 50) +* Bott, Raoul: Construction of commutative diagrams. + (line 13) +* boxed links, avoiding <1>: Setting default types and options. + (line 25) +* boxed links, avoiding: URL hyperlinks. (line 17) +* boxes, open: Boxes. (line 12) +* braces, inside index entries: Index entries with special characters. + (line 63) +* brackets, inside index entries: Index entries with special characters. + (line 86) +* Brockett, Roger W.: Construction of commutative diagrams. + (line 38) +* Butterfly Lemma: Construction of commutative diagrams. + (line 122) +* Carlisle, David: Loading LaTeX packages. + (line 14) +* category codes: Category codes. (line 6) +* centering: Justification. (line 6) +* characters, converting to: Converting to characters. + (line 6) +* citations: Citations. (line 6) +* citations, formatting: Formatting citations. + (line 6) +* citations, hyperlinks: Citation hyperlinks. (line 6) +* citations, undefined: Citations. (line 43) +* cmtt8: Proofing index terms. + (line 12) +* color: Packages known to work. + (line 25) +* color, demo: Hyperlinks (xhyper.tex). + (line 6) +* color, hyperlink border: Link options for pdftex and dvipdfm. + (line 14) +* color, hyperlinks <1>: Setting default types and options. + (line 25) +* color, hyperlinks <2>: Options supported by all drivers. + (line 37) +* color, hyperlinks: URL hyperlinks. (line 17) +* color, problems with pdfTeX: Packages known to work. + (line 29) +* color.sty <1>: Hyperlinks (xhyper.tex). + (line 6) +* color.sty <2>: Setting default types and options. + (line 27) +* color.sty <3>: Hyperlink driver nolinks. + (line 34) +* color.sty <4>: URL hyperlinks. (line 18) +* color.sty: Packages known to work. + (line 21) +* colored links <1>: Setting default types and options. + (line 25) +* colored links <2>: Options supported by all drivers. + (line 37) +* colored links: URL hyperlinks. (line 17) +* column balancing with \singlecolumn: Multiple columns. (line 11) +* column eject: Multiple columns. (line 14) +* commas after index terms: Customizing indexing. + (line 6) +* commas in cross-referencing index entries: Customizing indexing. + (line 64) +* comments, highlighting in listings: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* commutative diagrams: Commutative diagrams. + (line 6) +* contents: Contents. (line 6) +* contents, and verbatim text: Writing the .toc file. + (line 50) +* contents, hyperlinks: Contents hyperlinks. (line 6) +* ConTeXt: Packages known to work. + (line 29) +* continued index entries: Typesetting an index. + (line 35) +* covering homotopy property: Construction of commutative diagrams. + (line 13) +* cross-references: Cross-references. (line 6) +* cross-references, defining general <1>: Using generic references. + (line 6) +* cross-references, defining general: Defining generic references. + (line 6) +* cross-references, demo: Hyperlinks (xhyper.tex). + (line 6) +* cross-references, hyperlinks: Cross-reference hyperlinks. + (line 6) +* cross-referencing index entries <1>: Customizing indexing. + (line 64) +* cross-referencing index entries: Modifying index entries. + (line 36) +* CTRL-L, and verbatim listing: Verbatim listing. (line 30) +* cube: Construction of commutative diagrams. + (line 90) +* customizing indexing: Customizing indexing. + (line 6) +* dashed hyperlink border: Link options for pdftex and dvipdfm. + (line 20) +* date: Time of day. (line 6) +* default hyperlink options <1>: Setting group types. (line 17) +* default hyperlink options: Setting hyperlink types and options. + (line 6) +* default hyperlink type <1>: Setting group types. (line 17) +* default hyperlink type: Setting hyperlink types and options. + (line 6) +* defining general references <1>: Using generic references. + (line 6) +* defining general references: Defining generic references. + (line 6) +* definitions, global: Category codes. (line 38) +* demo files: Demo files. (line 6) +* destgroup: Implicit hyperlinks. (line 10) +* destgroup `bib': Citation hyperlinks. (line 11) +* destgroup `definexref': Cross-reference hyperlinks. + (line 6) +* destgroup `eq': Equation reference hyperlinks. + (line 6) +* destgroup `foot': Footnote hyperlinks. (line 6) +* destgroup `footback': Footnote hyperlinks. (line 6) +* destgroup `idx': Index hyperlinks. (line 6) +* destgroup `li': List hyperlinks. (line 6) +* destgroup `xrdef': Page reference hyperlinks. + (line 6) +* destgroup options <1>: Setting group options. + (line 6) +* destgroup options: Setting hyperlink types and options. + (line 12) +* destgroup options, demo: Hyperlinks (xhyper.tex). + (line 6) +* destgroup type <1>: Setting group types. (line 6) +* destgroup type: Setting hyperlink types and options. + (line 12) +* destgroup type, demo: Hyperlinks (xhyper.tex). + (line 6) +* destination group: Implicit hyperlinks. (line 10) +* destination options: Introduction to hyperlinks. + (line 105) +* destination options, common: Options supported by all drivers. + (line 12) +* destination options, dvipdfm: Destination options for pdftex and dvipdfm. + (line 6) +* destination options, hypertex: Destination options for hypertex. + (line 6) +* destination options, pdftex: Destination options for pdftex and dvipdfm. + (line 6) +* destination type: Introduction to hyperlinks. + (line 88) +* destination types, dvipdfm: Destination types for pdftex and dvipdfm. + (line 6) +* destination types, hypertex: Destination types for hypertex. + (line 6) +* destination types, pdftex: Destination types for pdftex and dvipdfm. + (line 6) +* destinations, default options <1>: Setting group types. (line 17) +* destinations, default options: Setting hyperlink types and options. + (line 6) +* destinations, default type <1>: Setting group types. (line 17) +* destinations, default type: Setting hyperlink types and options. + (line 6) +* destinations, dimensions: Destination options for pdftex and dvipdfm. + (line 34) +* destinations, disabling <1>: Turning hyperlinks on/off. + (line 6) +* destinations, disabling: Hyperlink driver nolinks. + (line 6) +* destinations, group options <1>: Setting group options. + (line 6) +* destinations, group options: Setting hyperlink types and options. + (line 12) +* destinations, group options, demo: Hyperlinks (xhyper.tex). + (line 6) +* destinations, group type <1>: Setting group types. (line 6) +* destinations, group type: Setting hyperlink types and options. + (line 12) +* destinations, group type, demo: Hyperlinks (xhyper.tex). + (line 6) +* destinations, in another file <1>: Link types for pdftex and dvipdfm. + (line 40) +* destinations, in another file: Link types for hypertex. + (line 21) +* destinations, large operators <1>: Setting group options. + (line 34) +* destinations, large operators: Options supported by all drivers. + (line 27) +* destinations, magnification: Destination options for pdftex and dvipdfm. + (line 21) +* destinations, named <1>: Link types for pdftex and dvipdfm. + (line 18) +* destinations, named: Link types for hypertex. + (line 7) +* destinations, numbered: Link types for pdftex and dvipdfm. + (line 92) +* destinations, page: Link types for pdftex and dvipdfm. + (line 31) +* destinations, raising: Options supported by all drivers. + (line 13) +* destinations, URL <1>: Link types for pdftex and dvipdfm. + (line 25) +* destinations, URL: Link types for hypertex. + (line 14) +* detecting numbers: \ifinteger and \isinteger. + (line 6) +* diagnostics: Diagnostics. (line 6) +* Diagram, macros for LaTeX: Construction of commutative diagrams. + (line 80) +* dimensions, hyperlink: Link options for pdftex and dvipdfm. + (line 124) +* dimensions, hyperlink destination: Destination options for pdftex and dvipdfm. + (line 34) +* disabling hyperlinks <1>: Turning hyperlinks on/off. + (line 6) +* disabling hyperlinks: Hyperlink driver nolinks. + (line 6) +* displayed math and hyperlinks <1>: Setting group options. + (line 34) +* displayed math and hyperlinks: Options supported by all drivers. + (line 27) +* displays, left-justifying: Displays. (line 6) +* do...while loops: Iteration. (line 6) +* double column output: Multiple columns. (line 6) +* double columns in indexes: Typesetting an index. + (line 24) +* draft, option for graphics.sty: Packages known to work. + (line 69) +* driver dvipdfm: Hyperlink drivers pdftex and dvipdfm. + (line 6) +* driver hypertex: Hyperlink driver hypertex. + (line 6) +* driver nolinks: Hyperlink driver nolinks. + (line 6) +* driver pdftex: Hyperlink drivers pdftex and dvipdfm. + (line 6) +* drivers, hyperlink: Introduction to hyperlinks. + (line 6) +* dvipdfm <1>: Hyperlink driver hypertex. + (line 13) +* dvipdfm: Introduction to hyperlinks. + (line 36) +* dvipdfm, destination options: Destination options for pdftex and dvipdfm. + (line 6) +* dvipdfm, destination types: Destination types for pdftex and dvipdfm. + (line 6) +* dvipdfm, hyperlink driver: Hyperlink drivers pdftex and dvipdfm. + (line 6) +* dvipdfm, link options: Link options for pdftex and dvipdfm. + (line 6) +* dvipdfm, link types: Link types for pdftex and dvipdfm. + (line 6) +* dvips: Hyperlink driver hypertex. + (line 13) +* Eijkhout, Victor: Iteration. (line 61) +* eject in multicolumns: Multiple columns. (line 14) +* electronic mail addresses, breaking <1>: Packages known to work. + (line 120) +* electronic mail addresses, breaking: Paths. (line 6) +* empty argument, checking for: \ifempty. (line 6) +* empty equation labels: Equation references. (line 22) +* empty equation labels, referring to: Equation references. (line 27) +* empty string, checking for: \ifempty. (line 6) +* Encapsulated PostScript: Packages known to work. + (line 90) +* environments, user-defined: User-defined environments. + (line 6) +* Eplain, installing: Installation. (line 6) +* Eplain, invoking: Invoking Eplain. (line 6) +* Eplain, purpose of: Introduction. (line 6) +* Eplain, upgrading: Installation. (line 6) +* eplain.aux: Installation. (line 40) +* eplain.fmt: Installation. (line 27) +* EPS: Packages known to work. + (line 90) +* epstopdf: Packages known to work. + (line 90) +* epstopdf.sty: Packages known to work. + (line 88) +* equation labels, characters valid in: Equation references. (line 56) +* equation numbers, formatting of: Formatting equation references. + (line 6) +* equations, giving numbers to all: Equation references. (line 22) +* equations, groups of: Subequation references. + (line 6) +* equations, hyperlinks: Equation reference hyperlinks. + (line 6) +* equations, numbering: Equation references. (line 6) +* equations, references to: Equation references. (line 6) +* error messages: Diagnostics. (line 25) +* error on \input: Environment for loading packages. + (line 35) +* escape character, changing verbatim: Verbatim listing. (line 47) +* exact index hyperlinks: Exact destinations for index terms. + (line 28) +* expansion, one-level: \expandonce. (line 6) +* explicit hyperlinks: Explicit hyperlinks. (line 6) +* explicit hyperlinks, demo: Hyperlinks (xhyper.tex). + (line 6) +* file, hyperlink to <1>: Link types for pdftex and dvipdfm. + (line 40) +* file, hyperlink to: Link types for hypertex. + (line 21) +* file: links: General hyperlinks. (line 36) +* filenames, breaking <1>: Packages known to work. + (line 120) +* filenames, breaking: Paths. (line 6) +* files, verbatim listing of: Verbatim listing. (line 6) +* files, verbatim listing of, demo: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* filtering index entries with hyperlinks: Exact destinations for index terms. + (line 33) +* footnotes, hyperlinks: Footnote hyperlinks. (line 6) +* footnotes, numbered: Footnotes. (line 6) +* for loops: Iteration. (line 6) +* form feed character, and verbatim listing: Verbatim listing. + (line 30) +* format file: Installation. (line 27) +* formatting index entries: Typesetting an index. + (line 35) +* fractions: Fractions. (line 6) +* Ghostscript: Hyperlink driver hypertex. + (line 13) +* gobbling arguments: Macro arguments. (line 6) +* golden mean: Construction of commutative diagrams. + (line 59) +* Graham, Ronald L.: Citations. (line 86) +* graphics collection, LaTeX <1>: Hyperlink driver nolinks. + (line 34) +* graphics collection, LaTeX <2>: Packages known to work. + (line 25) +* graphics collection, LaTeX: Loading LaTeX packages. + (line 14) +* graphics collection, LaTeX, demo: Hyperlinks (xhyper.tex). + (line 6) +* graphics, omitting typesetting of: Packages known to work. + (line 69) +* graphics, problems with pdfTeX: Packages known to work. + (line 29) +* graphics.sty: Packages known to work. + (line 22) +* graphicx.sty <1>: Hyperlinks (xhyper.tex). + (line 6) +* graphicx.sty: Packages known to work. + (line 23) +* grid: Construction of commutative diagrams. + (line 80) +* group `' (empty): Setting group types. (line 17) +* group `*': Setting group types. (line 26) +* group `bib': Citation hyperlinks. (line 11) +* group `cite': Citation hyperlinks. (line 6) +* group `definexref': Cross-reference hyperlinks. + (line 6) +* group `eq' <1>: Setting group options. + (line 35) +* group `eq': Equation reference hyperlinks. + (line 6) +* group `foot': Footnote hyperlinks. (line 6) +* group `footback': Footnote hyperlinks. (line 6) +* group `hrefext': General hyperlinks. (line 21) +* group `hrefint': General hyperlinks. (line 12) +* group `idx': Index hyperlinks. (line 6) +* group `li': List hyperlinks. (line 6) +* group `ref': Cross-reference hyperlinks. + (line 11) +* group `url': URL hyperlinks. (line 6) +* group `xrdef': Page reference hyperlinks. + (line 6) +* group `xref': Page reference hyperlinks. + (line 10) +* group option list: Setting group options. + (line 49) +* group options, hyperlink <1>: Setting group options. + (line 6) +* group options, hyperlink: Setting hyperlink types and options. + (line 12) +* group options, hyperlink, demo: Hyperlinks (xhyper.tex). + (line 6) +* group type, hyperlink <1>: Setting group types. (line 6) +* group type, hyperlink: Setting hyperlink types and options. + (line 12) +* group type, hyperlink, demo: Hyperlinks (xhyper.tex). + (line 6) +* group, destination: Implicit hyperlinks. (line 10) +* group, disabling hyperlinks: Turning hyperlinks on/off for a group. + (line 6) +* group, link: Implicit hyperlinks. (line 10) +* group, preserving option list: Setting group options. + (line 22) +* groups, specifying all: Setting group types. (line 26) +* hanging on \input: Environment for loading packages. + (line 35) +* help messages: Diagnostics. (line 25) +* highlight modes, hyperlink: Link options for pdftex and dvipdfm. + (line 69) +* highlighting: Packages known to work. + (line 110) +* highlighting, in listings: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* Ho"ppner, Klaus: Packages known to work. + (line 82) +* hooks: Hooks. (line 6) +* hyperlink border color: Link options for pdftex and dvipdfm. + (line 14) +* hyperlink color <1>: Setting default types and options. + (line 25) +* hyperlink color <2>: Options supported by all drivers. + (line 37) +* hyperlink color: URL hyperlinks. (line 17) +* hyperlink destination, dimensions: Destination options for pdftex and dvipdfm. + (line 34) +* hyperlink destination, magnification: Destination options for pdftex and dvipdfm. + (line 21) +* hyperlink destination, named <1>: Link types for pdftex and dvipdfm. + (line 18) +* hyperlink destination, named: Link types for hypertex. + (line 7) +* hyperlink destination, numbered: Link types for pdftex and dvipdfm. + (line 92) +* hyperlink destination, page: Link types for pdftex and dvipdfm. + (line 31) +* hyperlink destination, raising: Options supported by all drivers. + (line 13) +* hyperlink dimensions: Link options for pdftex and dvipdfm. + (line 124) +* hyperlink driver dvipdfm: Hyperlink drivers pdftex and dvipdfm. + (line 6) +* hyperlink driver hypertex: Hyperlink driver hypertex. + (line 6) +* hyperlink driver nolinks: Hyperlink driver nolinks. + (line 6) +* hyperlink driver pdftex: Hyperlink drivers pdftex and dvipdfm. + (line 6) +* hyperlink drivers: Introduction to hyperlinks. + (line 6) +* hyperlink group, disabling hyperlinks: Turning hyperlinks on/off for a group. + (line 6) +* hyperlink group, preserving option list: Setting group options. + (line 22) +* hyperlink options, common: Options supported by all drivers. + (line 6) +* hyperlinks, bibliography: Citation hyperlinks. (line 11) +* hyperlinks, border style: Link options for pdftex and dvipdfm. + (line 20) +* hyperlinks, border width: Link options for pdftex and dvipdfm. + (line 50) +* hyperlinks, citations: Citation hyperlinks. (line 6) +* hyperlinks, cross-references: Cross-reference hyperlinks. + (line 6) +* hyperlinks, default options <1>: Setting group types. (line 17) +* hyperlinks, default options: Setting hyperlink types and options. + (line 6) +* hyperlinks, default type <1>: Setting group types. (line 17) +* hyperlinks, default type: Setting hyperlink types and options. + (line 6) +* hyperlinks, demo: Hyperlinks (xhyper.tex). + (line 6) +* hyperlinks, disabling <1>: Turning hyperlinks on/off. + (line 6) +* hyperlinks, disabling: Hyperlink driver nolinks. + (line 6) +* hyperlinks, equations: Equation reference hyperlinks. + (line 6) +* hyperlinks, explicit: Explicit hyperlinks. (line 6) +* hyperlinks, explicit, demo: Hyperlinks (xhyper.tex). + (line 6) +* hyperlinks, filtering index entries: Exact destinations for index terms. + (line 33) +* hyperlinks, footnotes: Footnote hyperlinks. (line 6) +* hyperlinks, group option list: Setting group options. + (line 49) +* hyperlinks, group options <1>: Setting group options. + (line 6) +* hyperlinks, group options: Setting hyperlink types and options. + (line 12) +* hyperlinks, group options, demo: Hyperlinks (xhyper.tex). + (line 6) +* hyperlinks, group type <1>: Setting group types. (line 6) +* hyperlinks, group type: Setting hyperlink types and options. + (line 12) +* hyperlinks, highlight mode: Link options for pdftex and dvipdfm. + (line 69) +* hyperlinks, implicit: Implicit hyperlinks. (line 6) +* hyperlinks, implicit, demo: Hyperlinks (xhyper.tex). + (line 6) +* hyperlinks, index: Index hyperlinks. (line 6) +* hyperlinks, index destination placement: Choosing destination placement. + (line 6) +* hyperlinks, index, exact: Exact destinations for index terms. + (line 28) +* hyperlinks, large operators <1>: Setting group options. + (line 34) +* hyperlinks, large operators: Options supported by all drivers. + (line 27) +* hyperlinks, lists: List hyperlinks. (line 6) +* hyperlinks, opening in a new window: Link options for pdftex and dvipdfm. + (line 90) +* hyperlinks, page references: Page reference hyperlinks. + (line 6) +* hyperlinks, preserving page-breaking: Hyperlink driver nolinks. + (line 6) +* hyperlinks, preserving spacing: Hyperlink driver nolinks. + (line 6) +* hyperlinks, see and see also index entries: Hyperlinks in see and see also entries. + (line 6) +* hyperlinks, table of contents: Contents hyperlinks. (line 6) +* hyperlinks, to another file <1>: Link types for pdftex and dvipdfm. + (line 40) +* hyperlinks, to another file: Link types for hypertex. + (line 21) +* hyperlinks, URL <1>: Link types for pdftex and dvipdfm. + (line 25) +* hyperlinks, URL <2>: Link types for hypertex. + (line 14) +* hyperlinks, URL <3>: URL hyperlinks. (line 6) +* hyperlinks, URL: General hyperlinks. (line 20) +* hyperref.sty: Packages known not to work. + (line 9) +* hypertex, destination options: Destination options for hypertex. + (line 6) +* hypertex, destination types: Destination types for hypertex. + (line 6) +* hypertex, hyperlink driver: Hyperlink driver hypertex. + (line 6) +* hypertex, link options: Link options for hypertex. + (line 6) +* hypertex, link types: Link types for hypertex. + (line 6) +* hypertext links: Hyperlinks. (line 6) +* identifying numbers: \ifinteger and \isinteger. + (line 6) +* idxuniq: Exact destinations for index terms. + (line 33) +* ignoring arguments: Macro arguments. (line 6) +* implicit hyperlinks: Implicit hyperlinks. (line 6) +* implicit hyperlinks, demo: Hyperlinks (xhyper.tex). + (line 6) +* inaccessible macros: Category codes. (line 19) +* index entries and ranges: Modifying index entries. + (line 22) +* index entries containing braces: Index entries with special characters. + (line 63) +* index entries containing brackets: Index entries with special characters. + (line 86) +* index entries with special characters: Index entries with special characters. + (line 6) +* index entries' page numbers, modifying: Modifying index entries. + (line 6) +* index entries, and cross-referencing <1>: Customizing indexing. + (line 64) +* index entries, and cross-referencing: Modifying index entries. + (line 36) +* index entries, proofing: Proofing index terms. + (line 6) +* index entries, with verbatim text: Index entries with special characters. + (line 40) +* index entry continuations: Typesetting an index. + (line 35) +* index entry formatting: Typesetting an index. + (line 35) +* index entry general sorting: Indexing commands. (line 51) +* index fonts: Typesetting an index. + (line 24) +* index groupings: Typesetting an index. + (line 54) +* index hyperlink: Index hyperlinks. (line 6) +* index typesetting: Typesetting an index. + (line 6) +* index, and verbatim text: Index entries with special characters. + (line 40) +* index, choosing destination placement: Choosing destination placement. + (line 6) +* index, destination placement: Choosing destination placement. + (line 6) +* index, exact hyperlinks: Exact destinations for index terms. + (line 28) +* index, hyperlinks in see and see also entries: Hyperlinks in see and see also entries. + (line 6) +* index, parsing page numbers: Page destinations for index terms. + (line 32) +* index, placement of destinations: Choosing destination placement. + (line 6) +* index, selecting destination placement: Choosing destination placement. + (line 6) +* index, underlining page numbers: Page list and page range parsers. + (line 26) +* indexes, multiple: Indexing. (line 37) +* indexing: Indexing. (line 6) +* indexing and trailing spaces: Indexing terms. (line 20) +* indexing commands: Indexing commands. (line 6) +* indexing terms: Indexing terms. (line 6) +* insertion classes: Multiple columns. (line 38) +* inset hyperlink border: Link options for pdftex and dvipdfm. + (line 26) +* installation: Installation. (line 6) +* integers, detecting: \ifinteger and \isinteger. + (line 6) +* item labels, changing: Formatting lists. (line 54) +* iteration: Iteration. (line 6) +* justification: Justification. (line 6) +* Knuth, Donald Ervin <1>: Category codes. (line 7) +* Knuth, Donald Ervin: Citations. (line 86) +* labels on items, changing: Formatting lists. (line 54) +* labels, characters valid in: Cross-references. (line 20) +* labels, empty equation: Equation references. (line 22) +* labels, empty equation, referring to: Equation references. (line 27) +* Lamport, Leslie: Introduction. (line 13) +* LAMSTeX: Logos. (line 10) +* Lang, Serge <1>: Construction of commutative diagrams. + (line 122) +* Lang, Serge: Arrows and morphisms. + (line 126) +* large operators and hyperlinks <1>: Setting group options. + (line 34) +* large operators and hyperlinks: Options supported by all drivers. + (line 27) +* LaTeX <1>: Slanted lines and vectors. + (line 7) +* LaTeX <2>: Logos. (line 10) +* LaTeX <3>: Citations. (line 10) +* LaTeX: Introduction. (line 13) +* LaTeX graphics collection <1>: Hyperlink driver nolinks. + (line 34) +* LaTeX graphics collection <2>: Packages known to work. + (line 25) +* LaTeX graphics collection: Loading LaTeX packages. + (line 14) +* LaTeX graphics collection, demo: Hyperlinks (xhyper.tex). + (line 6) +* LaTeX packages <1>: Packages known not to work. + (line 6) +* LaTeX packages <2>: Packages known to work. + (line 6) +* LaTeX packages: Loading LaTeX packages. + (line 6) +* LaTeX packages, restoring \input: Environment for loading packages. + (line 24) +* left-justification: Justification. (line 6) +* left-justification of displays: Displays. (line 6) +* letterspacing: Packages known to work. + (line 110) +* linear systems theory: Construction of commutative diagrams. + (line 38) +* lines: Slanted lines and vectors. + (line 15) +* link group: Implicit hyperlinks. (line 10) +* link options: Introduction to hyperlinks. + (line 105) +* link options, common: Options supported by all drivers. + (line 35) +* link options, dvipdfm: Link options for pdftex and dvipdfm. + (line 6) +* link options, hypertex: Link options for hypertex. + (line 6) +* link options, pdftex: Link options for pdftex and dvipdfm. + (line 6) +* link type: Introduction to hyperlinks. + (line 88) +* link types, dvipdfm: Link types for pdftex and dvipdfm. + (line 6) +* link types, hypertex: Link types for hypertex. + (line 6) +* link types, pdftex: Link types for pdftex and dvipdfm. + (line 6) +* link, group options <1>: Setting group options. + (line 6) +* link, group options: Setting hyperlink types and options. + (line 12) +* link, group options, demo: Hyperlinks (xhyper.tex). + (line 6) +* link, group type <1>: Setting group types. (line 6) +* link, group type: Setting hyperlink types and options. + (line 12) +* linkgroup: Implicit hyperlinks. (line 10) +* linkgroup `cite': Citation hyperlinks. (line 6) +* linkgroup `eq' <1>: Setting group options. + (line 35) +* linkgroup `eq': Equation reference hyperlinks. + (line 20) +* linkgroup `foot': Footnote hyperlinks. (line 6) +* linkgroup `footback': Footnote hyperlinks. (line 6) +* linkgroup `hrefext': General hyperlinks. (line 21) +* linkgroup `hrefint': General hyperlinks. (line 12) +* linkgroup `idx': Index hyperlinks. (line 6) +* linkgroup `ref': Cross-reference hyperlinks. + (line 11) +* linkgroup `url': URL hyperlinks. (line 6) +* linkgroup `xref': Page reference hyperlinks. + (line 10) +* linkgroup options <1>: Setting group options. + (line 6) +* linkgroup options: Setting hyperlink types and options. + (line 12) +* linkgroup options, demo: Hyperlinks (xhyper.tex). + (line 6) +* linkgroup type <1>: Setting group types. (line 6) +* linkgroup type: Setting hyperlink types and options. + (line 12) +* links, hypertext: Hyperlinks. (line 6) +* list of figures: Alternative contents files. + (line 6) +* list of tables: Alternative contents files. + (line 6) +* listing files: Verbatim listing. (line 6) +* listing files, demo: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* lists: Lists. (line 6) +* lists, formatting: Formatting lists. (line 6) +* lists, hyperlinks: List hyperlinks. (line 6) +* logos: Logos. (line 6) +* lookahead without spaces: \futurenonspacelet. (line 6) +* loops: Iteration. (line 6) +* lscommnt.tex: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* magnification, hyperlink destination: Destination options for pdftex and dvipdfm. + (line 21) +* makeindex <1>: Index hyperlinks. (line 12) +* makeindex <2>: Indexing. (line 14) +* makeindex: Invoking Eplain. (line 103) +* margins, changing: Margins. (line 6) +* margins, index terms in: Proofing index terms. + (line 6) +* mathematics displays, formatting: Displays. (line 6) +* mathematics displays, hyperlinks <1>: Setting group options. + (line 34) +* mathematics displays, hyperlinks: Options supported by all drivers. + (line 27) +* Metafont: Logos. (line 10) +* miniltx.tex: Loading LaTeX packages. + (line 14) +* minimal realizations: Construction of commutative diagrams. + (line 38) +* modifying index entries' page numbers: Modifying index entries. + (line 6) +* morphisms: Arrows and morphisms. + (line 6) +* multiple column output: Multiple columns. (line 6) +* multiple indexes: Indexing. (line 37) +* named destination <1>: Link types for pdftex and dvipdfm. + (line 18) +* named destination: Link types for hypertex. + (line 7) +* names, of TeX variants: Logos. (line 6) +* new window, opening hyperlink in: Link options for pdftex and dvipdfm. + (line 90) +* newlinechar: Diagnostics. (line 27) +* newlines, obeying: Obeying spaces. (line 6) +* nolinks, hyperlink driver: Hyperlink driver nolinks. + (line 6) +* numbered destination: Link types for pdftex and dvipdfm. + (line 92) +* numbered lists: Lists. (line 6) +* numbered references: Citations. (line 86) +* numbers, detecting: \ifinteger and \isinteger. + (line 6) +* numbers, written form of: Writing out numbers. (line 6) +* Oberdiek, Heiko: Checking for PDF output. + (line 24) +* omitting hyperlinks <1>: Turning hyperlinks on/off. + (line 6) +* omitting hyperlinks: Hyperlink driver nolinks. + (line 6) +* omitting typesetting of graphics: Packages known to work. + (line 69) +* open boxes: Boxes. (line 12) +* option list, group: Setting group options. + (line 49) +* option list, preserving for group: Setting group options. + (line 22) +* options, destination, common: Options supported by all drivers. + (line 12) +* options, destination, dvipdfm: Destination options for pdftex and dvipdfm. + (line 6) +* options, destination, hypertex: Destination options for hypertex. + (line 6) +* options, destination, pdftex: Destination options for pdftex and dvipdfm. + (line 6) +* options, link and destination: Introduction to hyperlinks. + (line 105) +* options, link, common: Options supported by all drivers. + (line 35) +* options, link, dvipdfm: Link options for pdftex and dvipdfm. + (line 6) +* options, link, hypertex: Link options for hypertex. + (line 6) +* options, link, pdftex: Link options for pdftex and dvipdfm. + (line 6) +* ordered list: Lists. (line 6) +* output routine and index proofing: Proofing index terms. + (line 28) +* overstriking: Packages known to work. + (line 110) +* packages, LaTeX <1>: Packages known not to work. + (line 6) +* packages, LaTeX <2>: Packages known to work. + (line 6) +* packages, LaTeX: Loading LaTeX packages. + (line 6) +* page destination: Link types for pdftex and dvipdfm. + (line 31) +* page list, parsing: Page destinations for index terms. + (line 32) +* page range, parsing: Page destinations for index terms. + (line 32) +* page reference hyperlink: Page reference hyperlinks. + (line 6) +* page-breaking, preserving with hyperlinks: Hyperlink driver nolinks. + (line 6) +* parsing page numbers: Page destinations for index terms. + (line 32) +* Patashnik, Oren: Citations. (line 9) +* pathnames, breaking <1>: Packages known to work. + (line 120) +* pathnames, breaking: Paths. (line 6) +* PDF: Packages known to work. + (line 90) +* PDF output: Checking for PDF output. + (line 6) +* pdftex <1>: Introduction to hyperlinks. + (line 35) +* pdftex <2>: Checking for PDF output. + (line 6) +* pdftex: Invoking Eplain. (line 115) +* pdftex, destination options: Destination options for pdftex and dvipdfm. + (line 6) +* pdftex, destination types: Destination types for pdftex and dvipdfm. + (line 6) +* pdftex, hyperlink driver: Hyperlink drivers pdftex and dvipdfm. + (line 6) +* pdftex, link options: Link options for pdftex and dvipdfm. + (line 6) +* pdftex, link types: Link types for pdftex and dvipdfm. + (line 6) +* pdfTeX, problems using color and graphics: Packages known to work. + (line 29) +* pdfTeX, problems with supp-mis.tex: Packages known to work. + (line 29) +* pict2e.sty: Packages known not to work. + (line 16) +* picture mode <1>: Slanted lines and vectors. + (line 7) +* picture mode: Packages known to work. + (line 14) +* Portable Document Format: Packages known to work. + (line 90) +* PostScript point <1>: Link options for pdftex and dvipdfm. + (line 50) +* PostScript point <2>: Destination options for pdftex and dvipdfm. + (line 50) +* PostScript point: Destination types for pdftex and dvipdfm. + (line 66) +* proofing index terms: Proofing index terms. + (line 6) +* properties: Properties. (line 6) +* ps2pdf: Hyperlink driver hypertex. + (line 13) +* psfrag.sty: Packages known to work. + (line 97) +* quadruple column output: Multiple columns. (line 6) +* Rahtz, Sebastian: Loading LaTeX packages. + (line 14) +* raising hyperlink destinations <1>: Setting group options. + (line 34) +* raising hyperlink destinations: Options supported by all drivers. + (line 13) +* ranges and index entry: Modifying index entries. + (line 22) +* recognizing numbers: \ifinteger and \isinteger. + (line 6) +* rectangles: Boxes. (line 6) +* references, alphanumeric: Citations. (line 116) +* references, defining general <1>: Using generic references. + (line 6) +* references, defining general: Defining generic references. + (line 6) +* references, numbered: Citations. (line 86) +* register allocation: Allocation macros. (line 6) +* restoring \input, LaTeX packages: Environment for loading packages. + (line 24) +* return character: Category codes. (line 41) +* right-justification: Justification. (line 6) +* rms: Introduction. (line 14) +* rotation: Packages known to work. + (line 25) +* rotation, demo: Hyperlinks (xhyper.tex). + (line 6) +* rule thickness: Rules. (line 7) +* run: links: General hyperlinks. (line 37) +* scaling: Packages known to work. + (line 25) +* scaling, demo: Hyperlinks (xhyper.tex). + (line 6) +* sed: Customizing indexing. + (line 66) +* see also index entries and hyperlinks: Hyperlinks in see and see also entries. + (line 6) +* see also index entries and sorting: Customizing indexing. + (line 51) +* see, and index entries <1>: Customizing indexing. + (line 64) +* see, and index entries: Modifying index entries. + (line 36) +* see, and index entries, hyperlinks: Hyperlinks in see and see also entries. + (line 6) +* silent indexing: Indexing terms. (line 6) +* skipping tokens <1>: \ifempty. (line 12) +* skipping tokens: \ifundefined. (line 10) +* SLiTeX: Logos. (line 11) +* Snake Lemma: Arrows and morphisms. + (line 130) +* solid hyperlink border: Link options for pdftex and dvipdfm. + (line 26) +* sorting an index: Indexing. (line 6) +* sorting of index entries: Indexing commands. (line 51) +* soul.sty: Packages known to work. + (line 108) +* space above index entries: Typesetting an index. + (line 35) +* spaces, ignoring: \futurenonspacelet. (line 6) +* spaces, obeying: Obeying spaces. (line 6) +* spaces, trailing and indexing commands: Indexing terms. (line 20) +* spacing out: Packages known to work. + (line 110) +* spacing, preserving with hyperlinks: Hyperlink driver nolinks. + (line 6) +* special characters, in index entries: Index entries with special characters. + (line 6) +* special characters, in table of contents: Writing the .toc file. + (line 50) +* Stallman, Richard: Introduction. (line 14) +* striking out: Packages known to work. + (line 110) +* style, hyperlink border: Link options for pdftex and dvipdfm. + (line 26) +* subequations, referring to: Subequation references. + (line 6) +* subterm in indexing: Indexing terms. (line 13) +* supp-mis.tex, problems with pdfTeX: Packages known to work. + (line 29) +* supp-pdf.tex: Packages known to work. + (line 29) +* table of contents: Contents. (line 6) +* table of contents, and verbatim text: Writing the .toc file. + (line 50) +* table of contents, hyperlinks: Contents hyperlinks. (line 6) +* table of contents, short <1>: Macro arguments. (line 10) +* table of contents, short: Reading the .toc file. + (line 19) +* tables: Tables. (line 6) +* tabs: Obeying spaces. (line 22) +* TeX by Topic: Iteration. (line 61) +* TeX Frequently Asked Question: \ifinteger and \isinteger. + (line 26) +* TEXFORMATS: Installation. (line 43) +* texi2dvi <1>: Indexing. (line 34) +* texi2dvi <2>: Citations. (line 97) +* texi2dvi: Invoking Eplain. (line 103) +* Texinfo: Introduction. (line 13) +* TEXINPUTS: Installation. (line 23) +* time of day: Time of day. (line 6) +* toc files, writing several: Changing the .toc file's root name. + (line 12) +* tracing: Diagnostics. (line 6) +* trailing spaces and indexing commands: Indexing terms. (line 20) +* trimsee: Customizing indexing. + (line 67) +* triple column output: Multiple columns. (line 6) +* Tu, Loring W.: Construction of commutative diagrams. + (line 13) +* TUGboat: Introduction. (line 60) +* type, link and destination: Introduction to hyperlinks. + (line 88) +* types, destination, dvipdfm: Destination types for pdftex and dvipdfm. + (line 6) +* types, destination, hypertex: Destination types for hypertex. + (line 6) +* types, destination, pdftex: Destination types for pdftex and dvipdfm. + (line 6) +* types, link, dvipdfm: Link types for pdftex and dvipdfm. + (line 6) +* types, link, hypertex: Link types for hypertex. + (line 6) +* types, link, pdftex: Link types for pdftex and dvipdfm. + (line 6) +* typesetting an index: Typesetting an index. + (line 6) +* undefined control sequence, checking for: \ifundefined. (line 10) +* undefined labels, warnings about: Installation. (line 40) +* underline hyperlink border: Link options for pdftex and dvipdfm. + (line 26) +* underlining: Packages known to work. + (line 110) +* underlining page numbers in index: Page list and page range parsers. + (line 26) +* universal mapping property: Construction of commutative diagrams. + (line 25) +* unordered lists: Lists. (line 6) +* upgrading: Installation. (line 6) +* URL for ifpdf.sty: Checking for PDF output. + (line 24) +* URL for MakeIndex: Indexing. (line 14) +* URL for path.sty: Paths. (line 33) +* URL for pdfTeX: Checking for PDF output. + (line 6) +* URL for texnames.sty: Logos. (line 14) +* URL hyperlink <1>: Link types for pdftex and dvipdfm. + (line 25) +* URL hyperlink <2>: Link types for hypertex. + (line 14) +* URL hyperlink <3>: URL hyperlinks. (line 6) +* URL hyperlink: General hyperlinks. (line 20) +* url.sty <1>: Hyperlinks (xhyper.tex). + (line 6) +* url.sty <2>: URL hyperlinks. (line 6) +* url.sty: Packages known to work. + (line 118) +* user-inaccessible macros: Category codes. (line 19) +* vectors: Slanted lines and vectors. + (line 15) +* verbatim listing: Verbatim listing. (line 6) +* verbatim listing, demo: Highlighting TeX comments in listings (lscommnt.tex). + (line 6) +* verbatim text, in index: Index entries with special characters. + (line 40) +* verbatim text, in table of contents: Writing the .toc file. + (line 50) +* version number: Introduction. (line 47) +* Walden, David: Introduction. (line 57) +* Warner, Frank W.: Construction of commutative diagrams. + (line 25) +* whatsits made by hyperlinks: Hyperlink driver nolinks. + (line 25) +* whatsits made by index entries: Indexing commands. (line 63) +* while loops: Iteration. (line 6) +* whitespace: Obeying spaces. (line 6) +* width, hyperlink border: Link options for pdftex and dvipdfm. + (line 50) +* writing several toc files: Changing the .toc file's root name. + (line 12) +* xcolor.sty: Packages known not to work. + (line 19) +* xdvi: Hyperlink driver hypertex. + (line 11) +* xeplain.tex: Introduction. (line 6) +* xhyper.tex: Hyperlinks (xhyper.tex). + (line 6) +* Zassenhaus, Hans: Construction of commutative diagrams. + (line 122) +* zooming, hyperlink destination: Destination options for pdftex and dvipdfm. + (line 21) + + + +Tag Table: +Node: Top824 +Node: Introduction8097 +Node: Installation11064 +Node: Invoking Eplain13116 +Node: User definitions17568 +Node: Diagnostics19395 +Node: Rules20965 +Node: Citations21798 +Node: Formatting citations27641 +Node: Formatting bibliographies29187 +Node: Displays32016 +Node: Formatting displays33063 +Node: Time of day33735 +Node: Lists34496 +Node: Formatting lists36655 +Node: Verbatim listing38951 +Node: Contents41680 +Node: Writing the .toc file42351 +Node: Reading the .toc file45219 +Node: Changing the .toc file's root name46629 +Node: Alternative contents files47649 +Node: Cross-references48214 +Node: Defining generic references49699 +Node: Using generic references50577 +Node: Page references51868 +Node: Equation references52692 +Node: Formatting equation references55445 +Node: Subequation references57745 +Node: Indexing59668 +Node: Indexing terms61671 +Node: Indexing commands62784 +Node: Modifying index entries65812 +Node: Index entries with special characters68529 +Node: Proofing index terms72788 +Node: Typesetting an index74601 +Node: Customizing indexing77068 +Node: Justification80775 +Node: Tables82454 +Node: Margins85009 +Node: Multiple columns87170 +Node: Footnotes89154 +Node: Fractions91741 +Node: Paths92528 +Node: Logos94135 +Node: Boxes94822 +Node: Checking for PDF output96620 +Node: Loading LaTeX packages97711 +Node: The \usepackage command99059 +Node: Environment for loading packages100149 +Node: Packages known to work102216 +Node: Packages known not to work108621 +Node: Hyperlinks109383 +Node: Introduction to hyperlinks109966 +Node: Explicit hyperlinks115522 +Node: Implicit hyperlinks117812 +Node: General hyperlinks119634 +Node: URL hyperlinks121102 +Node: Citation hyperlinks123131 +Node: List hyperlinks123863 +Node: Cross-reference hyperlinks124257 +Node: Page reference hyperlinks125637 +Node: Equation reference hyperlinks126301 +Node: Index hyperlinks127699 +Node: Exact destinations for index terms129463 +Node: Page destinations for index terms131639 +Node: Choosing destination placement134267 +Node: Index page list and page range parsers135059 +Node: Hyperlinks in see and see also entries135612 +Node: Footnote hyperlinks136411 +Node: Contents hyperlinks137609 +Node: Hyperlink drivers137992 +Node: Options supported by all drivers138627 +Node: Hyperlink driver hypertex141431 +Node: Destination types for hypertex144383 +Node: Destination options for hypertex145422 +Node: Link types for hypertex145904 +Node: Link options for hypertex147925 +Node: Hyperlink drivers pdftex and dvipdfm148949 +Node: Destination types for pdftex and dvipdfm149595 +Node: Destination options for pdftex and dvipdfm153094 +Node: Link types for pdftex and dvipdfm155549 +Node: Link options for pdftex and dvipdfm159088 +Node: Hyperlink driver nolinks162727 +Node: Setting hyperlink types and options165139 +Node: Setting default types and options166141 +Node: Setting group types167570 +Node: Setting group options168763 +Node: Turning hyperlinks on/off171253 +Node: Turning low-level commands on/off171891 +Node: Turning hyperlinks on/off for a group172404 +Node: Arrow theoretic diagrams173561 +Node: Slanted lines and vectors173928 +Node: Commutative diagrams176010 +Node: Arrows and morphisms176609 +Node: Construction of commutative diagrams181087 +Node: Commutative diagram parameters188279 +Node: Programming definitions190098 +Node: Category codes191099 +Node: Allocation macros193709 +Node: Iteration195857 +Node: Macro arguments197516 +Node: Converting to characters200015 +Node: Expansion201407 +Node: \csn and \ece201970 +Node: \edefappend202536 +Node: Hooks203085 +Node: Properties205271 +Node: \expandonce206356 +Node: \ifundefined206805 +Node: \ifempty207369 +Node: \ifinteger and \isinteger208112 +Node: \futurenonspacelet209150 +Node: Obeying spaces209749 +Node: Writing out numbers210780 +Node: Mode-specific penalties211103 +Node: Auxiliary files211835 +Node: User-defined environments212758 +Node: Page list and page range parsers213973 +Node: Demo files216110 +Node: Hyperlinks (xhyper.tex)216678 +Node: Highlighting TeX comments in listings (lscommnt.tex)224997 +Node: Macro index227421 +Node: Concept index289457 + +End Tag Table diff --git a/Master/texmf-dist/doc/eplain/doc/eplain.pdf b/Master/texmf-dist/doc/eplain/doc/eplain.pdf new file mode 100644 index 00000000000..206298f2393 Binary files /dev/null and b/Master/texmf-dist/doc/eplain/doc/eplain.pdf differ diff --git a/Master/texmf-dist/doc/eplain/doc/lscommnt.jpg b/Master/texmf-dist/doc/eplain/doc/lscommnt.jpg new file mode 100644 index 00000000000..6f40a9ac8b7 Binary files /dev/null and b/Master/texmf-dist/doc/eplain/doc/lscommnt.jpg differ diff --git a/Master/texmf-dist/doc/eplain/doc/xhyper.jpg b/Master/texmf-dist/doc/eplain/doc/xhyper.jpg new file mode 100644 index 00000000000..60c5abf18e2 Binary files /dev/null and b/Master/texmf-dist/doc/eplain/doc/xhyper.jpg differ diff --git a/Master/texmf-dist/doc/eplain/util/idxuniq b/Master/texmf-dist/doc/eplain/util/idxuniq new file mode 100644 index 00000000000..6ee7d225f5c --- /dev/null +++ b/Master/texmf-dist/doc/eplain/util/idxuniq @@ -0,0 +1,37 @@ +#!/usr/bin/awk -f + +# (This file is public domain.) + +# This script filters input lines (which are expected to be a list of +# `\indexentry' lines for MakeIndex) eliminating matching lines. The comparison +# is done without regard to hyperlink label names (in the form `IDX*', where `*' +# stands for a non-negative integer). + +# This has to be done to avoid terms which differ only in hyperlink label names +# embedded into them, because MakeIndex will treat these otherwise identical +# terms as distinct, listing more than once a page number for equivalent terms +# on the same page. + +# `stripped' array is indexed by `\indexentry' lines stripped off the hyperlink +# label name. For each term, we use its stripped version as a key into the +# `stripped' array to increment its element. This records the fact that we have +# seen the term with such key. Also, we add the (full) `\indexentry' line to +# the `terms' array, but only if we have not yet seen a term with such key. + +# The idea was borrowed from Edition 3 of `GAWK: Effective AWK Programming: A +# User's Guide for GNU Awk', which contains the following credit: + +# histsort.awk --- compact a shell history file +# Thanks to Byron Rakitzis for the general idea + +{ + temp = $0 + sub (/{IDX[[:digit:]]+}/, "", temp) + if (stripped[temp]++ == 0) + terms[++count] = $0 +} + +END { + for (i = 1; i <= count; i++) + print terms[i] +} diff --git a/Master/texmf-dist/doc/eplain/util/trimsee b/Master/texmf-dist/doc/eplain/util/trimsee new file mode 100644 index 00000000000..8af5ebe6434 --- /dev/null +++ b/Master/texmf-dist/doc/eplain/util/trimsee @@ -0,0 +1,106 @@ +#!/bin/sh + +# (This file is public domain.) + +help () +{ + cat <&2 + exit 1 + fi +} + +VERSION='0.1' + +DEFAULT_SEE='\\indexsee' +DEFAULT_IS=', \+' +DEFAULT_OS=' ' + +SEE=$DEFAULT_SEE +IS=$DEFAULT_IS +OS=$DEFAULT_OS + +while [ $# != 0 ] +do + case "$1" in + -i) + check_missing_arg $# "$1" + IS=$2 + shift + ;; + -o) + check_missing_arg $# "$1" + OS=$2 + shift + ;; + -s) + check_missing_arg $# "$1" + SEE=$2 + shift + ;; + -h | --help) + help + exit 0 + ;; + -v | --version) + echo "trimsee version $VERSION" + exit 0 + ;; + *) + echo "Unknown option '$1'" 1>&2 + exit 1 + ;; + esac + shift +done + + +# The idea is to implement line output delayed by one line. When we +# read next line, we check if it starts with a see/see also entry, and +# if it does, we remove the comma at the end of the previous line +# before printing it. We keep previous lines in the hold buffer. + +sed -n ' + +# Remove all commas in front of see/see also inside each line. +s/'"$IS$SEE/$OS$SEE"'/g + +# If this line does not start with see/see also, we will print the +# previous line intact. NOTE: There are two characters inside the +# brackets: a space and a tab. +/^[ ]*'"$SEE"'/! { x; b PRINT; } + +# This line starts with see/see also, so remove comma at the end of +# the previous line before we print it. +x +s/'"$IS"'$/'"$OS"'/ + +# Print the previous line. +:PRINT +1! p + +# At the end of the input, print the last line. +$ { x; p; } + +' -- cgit v1.2.3