diff options
Diffstat (limited to 'Master/texmf-dist/doc')
74 files changed, 16186 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/cweb-latex/CATALOG b/Master/texmf-dist/doc/latex/cweb-latex/CATALOG new file mode 100644 index 00000000000..4e8e259d023 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/CATALOG @@ -0,0 +1,12 @@ +Name: cweb +Version: 1.0 [29 Aug 95] +Problems-To: schrod@iti.informatik.th-darmstadt.de +Author: Joachim Schrod +Address: TU Darmstadt, Alexanderstr. 10, D-64283 Darmstadt, Germany. + No phone calls, please. + +Description: LaTeX CWEB: Use LaTeX2e markup for your CWEB programs. + The cweb class provides hierarchic document structure (with + real sections, subsections, etc.), and is highly configurable. + +Keywords: CWEB, Literate Programming, LaTeX diff --git a/Master/texmf-dist/doc/latex/cweb-latex/History b/Master/texmf-dist/doc/latex/cweb-latex/History new file mode 100644 index 00000000000..fba36fdefb6 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/History @@ -0,0 +1,91 @@ +cweb-sty/History 30 Nov 95 -*- Indented-Text -*- +--------------------------------------------------------------------------- + +PL1 30 Nov 95 + + Make it usable with LaTeX <1994/12/01>. + + +Version 1.1 20 Nov 95 + + Section numbers are properly reset when a higher-level section begins. + + Support for German, French, and Italian CWEB documents. + + Experimental version of cwebparts package, to input CWEB + programs in LaTeX documents. (No user documentation yet.) + + Chunk numbers in margin are more often aligned to the first + program line. Chunk marker (paragraph sign) doesn't have a + depth any more. + + Index doesn't produce an error with base classes report and + book any more. + + +Version 1.0 29 Aug 95 + + Updated to LaTeX2e, this is now a document class. + User configuration via cweb.cfg and keyword-value class options, + the base class of this document class may be configured. + Improved user manual, added more concept explanations. + + Realized hierarchic document structure. + Flat document structure is an option now. + + Suppression of change hints, unchanged sections, identifier + index, and reference list is supported. + + Moved Counter cwebSecNoEject to protected interface. + Chunk numbers of CWEAVE are used instead of self-computed ones. + Different document base sizes than 10pt may be used. + + +Version 0.4 10 Aug 93 + + Added cwebarray.sty to the official release. + Added cwebzw.sty as contributed option. + + Left shift operator (`<<') is now defined correctly. + CWEB macro and program part in one section works now. + Typed numbers now produce a subscript, as in the plain version. + + Cross references to section numbers do not output a period + after the section number any more. + + Updated user documentation. + + Start new page on main section only if @*2 or higher (configurable). + + +Version 0.3 17 Jun 93 + + CWEB 3.0 was released yesterday. Mentioned that in the doc. + + +Version 0.2 15 Jun 93 + + cweb is now a style, not an option. + + CWEAVE markup has changed in April '93. Documents and + implements the new and changed tags. + In particular, supports the group level construct of + starred sections, i.e., `@**', `@*1', etc. + + Handles @( foo @> constructs. + + The detection of `@.' entries is more robust now. + + Works with LaTeX versions prior to 1992, too. + + Allows an optional \con at the file end (was mandatory before). + Typesets identifier index or refinement list only when + they exist. + + Improved the documentation, both internal and user. + + +Version 0.1 09 Apr 93 + + First release, experimental alpha + still an option, not a style diff --git a/Master/texmf-dist/doc/latex/cweb-latex/INSTALL b/Master/texmf-dist/doc/latex/cweb-latex/INSTALL new file mode 100644 index 00000000000..da0c453681d --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/INSTALL @@ -0,0 +1,43 @@ +$Id: INSTALL,v 1.2 1995/11/30 15:41:27 schrod Exp $ +------------------------------------------------------------ + + +You're not on Unix? Jump ahead to `INSTALLATION BY HAND'. + + +INSTALLATION ON UNIX +==================== + +I have supplied a Makefile for your convenience. You have to edit it +to tell make where your TeX installation lives. + +Do you have a TDS-compliant installation? +(E.g., teTeX, highly recommended.) + + yes => Change the value of TEXMF to your TDS root directory. + no => Change even more variables (the ones below TEXMF). + Make sure all parent directories exist. + + +Type + make + +Everything should be installed now. + +If you have a TDS installation structure and make complains that the +LaTeX directory is not found, install LaTeX first. + + + +INSTALLATION BY HAND +==================== + +Copy *.cls, *.sty, and contrib/*.sty to some directory where LaTeX finds it. + The correct TDS directory name is tex/latex/cweb/, relative to the + TDS root. + +Copy *.dvi from the current directory to the directory +where you keep the documentation for your installed LaTeX styles. + What? You don't have such a directory? Shame on you. ;-) + The TDS proposes one of the following directory names: doc/latex/cweb/ + or doc/latex/styles/cweb/. I use the latter. diff --git a/Master/texmf-dist/doc/latex/cweb-latex/License b/Master/texmf-dist/doc/latex/cweb-latex/License new file mode 100644 index 00000000000..a43ea2126fb --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/License @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 675 Mass Ave, Cambridge, MA 02139, 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 + + Appendix: 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. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) 19yy <name of author> + + 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., 675 Mass Ave, Cambridge, MA 02139, 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) 19yy 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. + + <signature of Ty Coon>, 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/latex/cweb-latex/MANIFEST b/Master/texmf-dist/doc/latex/cweb-latex/MANIFEST new file mode 100644 index 00000000000..f6ae6a4dcc3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/MANIFEST @@ -0,0 +1,21 @@ +$Id: MANIFEST,v 1.5 1995/08/29 17:34:33 schrod Exp $ -*- Indented-Text -*- +---------------------------------------------------------------------- + +The following files are part of the cweb bundle: + + README -- general intro, what's this package for + CATALOG -- catalog information about this bundle + INSTALL -- installation instructions + + cweb.cls -- class macro file + keyvald.sty -- needed by cweb.cls + cwebarray.sty -- style option for ruled tables, needs array.sty + cweb-user.dvi -- typeset user manual + cweb-conf.dvi -- typeset description of internal interface + + History -- revision history of this package + MANIFEST -- this file + License -- GPL + Makefile -- will help you for installation on Unix + src/ -- subdirectory with my development area + Please read the file README in that directory. diff --git a/Master/texmf-dist/doc/latex/cweb-latex/README b/Master/texmf-dist/doc/latex/cweb-latex/README new file mode 100644 index 00000000000..348323fa78c --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/README @@ -0,0 +1,92 @@ +$Id: README,v 1.6 1995/11/21 00:41:49 schrod Exp $ +------------------------------------------------------------ + + +This is the distribution of LaTeX CWEB, a bundle that allows you to +use LaTeX as the documentation markup of your CWEB program. Your CWEB +programs may be LaTeX documents now -- with sections, subsections, +environments, figures, graphics inclusion, etc. + +You will want to use this bundle if you + + -- are a CWEB programmer and use LaTeX elsewhere, + -- haven't used CWEB up to now, because you wanted structured markup + (and you didn't want to develop it yourself), or + -- want an hierarchic document structure for CWEB programs. + +Included in the distribution is the full source and DVI files for your +convenience. + In addition, the distribution features a well known example: the +``Counting Words'' program distributed with CWEB. I recoded it to +LaTeX markup. You'll find both source and processed files in the +examples/ directory. + +Note that the style file is rather large because the comments are not +stripped yet. This will change in a future release. I'm still working +on this class, the next release will support inclusion of CWEB program +parts in other LaTeX documents. (Yes, I know that this was already +promised for this release. Look in src/ for a preliminary version, in +cwebparts.sty and cwebx.sty -- the end user documentation is missing +and it has lots of rough edges, but it works!) + If you have more wishes or if you have any other gripes about the +usage of this class, you should send them *now*, as you can still +influence the development. When I've finished the realization of the +inclusion, I'll freeze the code base and will concentrate on fixes for +reported problems. + +Anyhow, feedback is always appreciated, I'd like to know if you that +style. -- The more people tell me they use it, the more support I'll +put in future versions. + + +If you want to use this style file, you must use CWEB V3. (Current +release, as of $Date: 1995/11/21 00:41:49 $: 3.4.) You must also use a +more-or-less recent LaTeX2e, I cannot support LaTeX 2.09 any longer. +(`More-or-less recent' means: if I need a feature that was introduced +in the current LaTeX revision or in the previous one, I'll use it.) +Most probably you also need a big TeX to use the cweb class, but they +should be common by now anyhow. + + +MANIFEST features a list of files in this distribution. +For installation instructions, check the file INSTALL. +src/TODO explicates my development plans. + + +Reference anonymous ftp site: + ftp.th-darmstadt.de [130.83.47.112] + directory pub/programming/literate-programming/c.c++ + file cweb-sty-<version>.tar.gz + where <version> is the current version number + (a gzipped tar file) + +You'll also find a version of this bundle on CTAN in +macros/latex/contrib/supported/cweb/. + + +LEGALESE + +This is freely distributable 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 software 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 in +the file License along with this package; if not, write to the Free +Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + + +Share and enjoy, + + Joachim + +-- +=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= +Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de +Computer Science Department +Technical University of Darmstadt, Germany diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/Index b/Master/texmf-dist/doc/latex/cweb-latex/contrib/Index new file mode 100644 index 00000000000..bf7a308a667 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/Index @@ -0,0 +1,16 @@ +% $ITI: Index,v 1.2 1995/11/21 00:42:08 schrod Exp $ -*- Indented-Text -*- +%---------------------------------------------------------------------- + +The following files are contributed to LaTeX CWEB: + + cwbl-french - by Andreas Scherer <scherer@physik.rwth-aachen.de> + Support for French CWEB documents. + cwbl-italian - by Andreas Scherer <scherer@physik.rwth-aachen.de> + Support for Italian CWEB documents. + cwbl-deutsch - by Andreas Scherer <scherer@physik.rwth-aachen.de> + Another support for German CWEB documents, + different texts than the one in src/. + + cwebzw.sty - by Zden\v{e}k Wagner <wagner@csearn.bitnet> + Created for cweb.sty 1.8; + most probably doesn't run any more, moved to wagner/. diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-deutsch.sty b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-deutsch.sty new file mode 100644 index 00000000000..9192ad883b2 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-deutsch.sty @@ -0,0 +1,83 @@ +% $Id: dcweb.sty,v 1.3 1995/09/11 18:03:44 scherer Exp $ +% +% THIS IS A TEST! +% +% I have no idea how to write a style-conformant package, so bear with me. +% This `package' translates the `LaTeX CWEB' class to German. +% +% Andreas Scherer +% Rolandstra{\ss}e 16 +% 52070 Aachen, Germany +% +% 31. August 1995 +% +% $Log: dcweb.sty,v $ +% Revision 1.3 1995/09/11 18:03:44 scherer +% Following Joachim Schrod's advice, `chunk' means `Baustein'. +% +% Revision 1.2 1995/09/11 18:01:24 scherer +% Make this package usable with `german.sty'. +% +% Revision 1.1 1995/09/11 18:00:41 scherer +% Initial revision +% +\renewcommand{\CwebCRAlso}{\CwebCrossRef{Siehe auch den Baustein}} + % See also chunk +\renewcommand{\CwebCRsAlso}{\CwebCrossRef{Siehe auch die Bausteine}} + % See also chunks + +\renewcommand{\CwebCRCite} + {\CwebCrossRef{Dieser Programmteil wird zitiert im Baustein}} + % This code is cited in chunk +\renewcommand{\CwebCRsCite} + {\CwebCrossRef{Dieser Programmteil wird zitiert in den Bausteinen}} + % This code is cited in chunks + +\renewcommand{\CwebCRUse} + {\CwebCrossRef{Dieser Programmteil wird verwendet im Baustein}} + % This code is used in chunk +\renewcommand{\CwebCRsUse} + {\CwebCrossRef{Dieser Programmteil wird verwendet in den Bausteinen}} + % This code is used in chunks + +\renewcommand{\CwebCREt}{ und~} + % and~ +\renewcommand{\CwebCRsEt}{ und~} + % , and~ + +\renewcommand{\CwebCRChanged}{% + \CwebCrossRef{Die folgenden Bausteine sind vom Change-File + ver\"andert worden:}% + } + % The following chunks were changed by the change file: +\renewcommand{\CwebChangedListName}{Ver\"anderte Bausteine} + % Changed Chunks + +\renewcommand{\CwebRefListName}{Liste der Verfeinerungen} + % List of Refinements + +\renewcommand{\CwebXRCite}{\CwebCrossRef{Zitiert im Baustein}} + % Cited in chunk +\renewcommand{\CwebXRCites}{\CwebCrossRef{Zitiert in den Bausteinen}} + % Cited in chunks +\renewcommand{\CwebXRUse}{\CwebCrossRef{Verwendet im Baustein}} + % Used in chunk +\renewcommand{\CwebXRUses}{\CwebCrossRef{Verwendet in den Bausteinen}} + % Used in chunks + + +%% -js [07 Nov 95]: +%% Discarded code below, this problem has been repaired in the +%% cwebbase module. +%% +%% \makeatletter +%% \catcode`\_=\CatLetter +%% \def\CwebString#1{% +%% \hbox{\tt +%% \cweb@string_setup +%% \ifx\originalTeX\undefined\else\originalTeX\fi % for `german.sty' +%% #1\kern .05em +%% }% +%% } +%% \catcode`\_=\CatUsCode +%% \makeatother diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-french.sty b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-french.sty new file mode 100644 index 00000000000..6dd3f6203ed --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-french.sty @@ -0,0 +1,64 @@ +% $Id: fcweb.sty,v 1.2 1995/10/26 12:28:04 scherer Exp $ +% +% THIS IS A TEST! +% +% I have no idea how to write a style-conformant package, so bear with me. +% This `package' translates the `LaTeX CWEB' class to French. +% +% Andreas Scherer +% Rolandstra{\ss}e 16 +% 52070 Aachen, Germany +% +% 31. August 1995 +% +% $Log: fcweb.sty,v $ +% Revision 1.2 1995/10/26 12:28:04 scherer +% Some French corrections pointed out by <bronne@@montefiore.ulg.ac.be. +% Merci beaucoup ! +% +% Revision 1.1 1995/09/11 17:57:59 scherer +% Initial revision +% +\renewcommand{\CwebCRAlso}{\CwebCrossRef{Voir aussi le fragment}} + % See also chunk +\renewcommand{\CwebCRsAlso}{\CwebCrossRef{Voir aussi les fragments}} + % See also chunks + +\renewcommand{\CwebCRCite} + {\CwebCrossRef{Code cit\'e dans le fragment}} + % This code is cited in chunk +\renewcommand{\CwebCRsCite} + {\CwebCrossRef{Code cit\'e dans les fragments}} + % This code is cited in chunks + +\renewcommand{\CwebCRUse} + {\CwebCrossRef{Code utilis\'e dans le fragment}} + % This code is used in chunk +\renewcommand{\CwebCRsUse} + {\CwebCrossRef{Code utilis\'e dans les fragments}} + % This code is used in chunks + +\renewcommand{\CwebCREt}{ et~} + % and~ +\renewcommand{\CwebCRsEt}{ et~} + % , and~ + +\renewcommand{\CwebCRChanged}{% + \CwebCrossRef{Les fragments suivants ont \'et\'e modifi\'es dans + le fichier de changements\,:}% + } + % The following chunks were changed by the change file: +\renewcommand{\CwebChangedListName}{Fragments modifi\'es} + % Changed Chunks + +\renewcommand{\CwebRefListName}{Liste des fragments} + % List of refinements + +\renewcommand{\CwebXRCite}{\CwebCrossRef{Cit\'e dans le fragment}} + % Cited in chunk +\renewcommand{\CwebXRCites}{\CwebCrossRef{Cit\'e dans les fragments}} + % Cited in chunks +\renewcommand{\CwebXRUse}{\CwebCrossRef{Utilis\'e dans le fragment}} + % Used in chunk +\renewcommand{\CwebXRUses}{\CwebCrossRef{Utilis\'e dans les fragments}} + % Used in chunks diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-italian.sty b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-italian.sty new file mode 100644 index 00000000000..dc75642bff8 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cwbl-italian.sty @@ -0,0 +1,63 @@ +% $Id: icweb.sty,v 1.2 1995/09/28 09:20:01 scherer Exp $ +% +% THIS IS A TEST! +% +% I have no idea how to write a style-conformant package, so bear with me. +% This `package' translates the `LaTeX CWEB' class to Italian. +% +% Andreas Scherer +% Rolandstra{\ss}e 16 +% 52070 Aachen, Germany +% +% 31. August 1995 +% +% $Log: icweb.sty,v $ +% Revision 1.2 1995/09/28 09:20:01 scherer +% I must apologize for my poor Italian. Giuseppe Ghibò corrected this. +% +% Revision 1.1 1995/09/11 17:56:07 scherer +% Initial revision +% +\renewcommand{\CwebCRAlso}{\CwebCrossRef{Vedi anche chunk}} + % See also chunk +\renewcommand{\CwebCRsAlso}{\CwebCrossRef{Vedi anche chunk}} + % See also chunks + +\renewcommand{\CwebCRCite} + {\CwebCrossRef{Questo codice \`e citato nel chunk}} + % This code is cited in chunk +\renewcommand{\CwebCRsCite} + {\CwebCrossRef{Questo codice \`e citato nei chunk}} + % This code is cited in chunks + +\renewcommand{\CwebCRUse} + {\CwebCrossRef{Questo codice \`e usato nel chunk}} + % This code is used in chunk +\renewcommand{\CwebCRsUse} + {\CwebCrossRef{Questo codice \`e usato nei chunk}} + % This code is used in chunks + +\renewcommand{\CwebCREt}{ e~} + % and~ +\renewcommand{\CwebCRsEt}{ e~} + % , and~ + +\renewcommand{\CwebCRChanged}{% + \CwebCrossRef{I seguenti chunk sono stati modificati tramite + il change-file:}% + } + % The following chunks were changed by the change file: +\renewcommand{\CwebChangedListName}{Chunk modificati} + % Changed Chunks + +\renewcommand{\CwebRefListName}{Nomi dei chunk:} + % List of Refinements + +\renewcommand{\CwebXRCite}{\CwebCrossRef{Citato nel chunk}} + % Cited in chunk +\renewcommand{\CwebXRCites}{\CwebCrossRef{Citato nei chunk}} + % Cited in chunks +\renewcommand{\CwebXRUse}{\CwebCrossRef{Usato nel chunk}} + % Used in chunk +\renewcommand{\CwebXRUses}{\CwebCrossRef{Usato nei chunk}} + % Used in chunks diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/README.txt b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/README.txt new file mode 100644 index 00000000000..676de55038a --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/README.txt @@ -0,0 +1,131 @@ +Dear User: + +I present to you an evolution of the excellent CWEB class, originally by +Joachim Schrod. +The purpose of the new files is twofold: + +1.- To allow a file written using this class to be included in other +documents, as for instance as an appendix to some report. For this, +the file nodoc.tex may be of help. + +2.- To insert hyperlinks from the places where a chunk of code is +referenced to the chunk itself, including the indices that are produced at +the end of cweb document. The result makes it a lot more easy to follow +the code if it is typeset using PDFLaTeX, or is otherwise processed +to obtain a PDF or an HTML file, and makes no harm in the paper version +of the document. + +The installation is straightforward. Put the files cweb-hy.cls and +cwbasehy.tex where TeX can find them. Since cweb.cls was installed +under tex/latex/literate, may I suggest you put all these files under +tex/latex/liter-hy, all paths relative to your TEXMF hierarchy. + +1 The Class as a Package. + +For using the class as a normal package (with \usepackage{cweb-hy}), you +simply have to copy the file cweb-hy.cls with the name cweb-hy.sty, so +that it is found by LaTeX. + +How this works I can explain as follows. Suppose you have a file called +whatever.w such as + +-------------------------------------- +% Very simple CWEB +\documentclass[]{cweb-hy} +\usepackage[T1]{fontenc} +\usepackage{ae} +\begin{document} +\title{Whatever} +\author{Me} + +@* CWEB program. +This is your program. +@c +@<Header files@>@/ +@<Main program@> + +@ If we want to use the system resources, we must insert the definition +of the standard functions. + +@<Header...@>= +#include <stdio.h> + +@ The code makes whatever. + +@<Main...@>= +int +main(void) +{ +printf("Whatever\n"); +exit(0); +} +@ \end{document} +-------------------------------------- +And suppose further that you want to make a report including your +beautifully typeset program (with CWEB and TeX). +Well, with the CWEB class as it stands, you can't. However, with the very +simple changes I have implemented, you could say + +\documentclass{report} +\title{All my life's programs} +\author{Me} +\begin{document} +\part{Rationale} +Blah, Blah... + +\part{Programs} +\section{Makes Whatever} +\input{whatever} +\end{document} + +and the file whatever.tex will get just in with all your very skillful +code and clear documentation, everything typeset by TeX. The package +accepts almost all the options the class does, but I decided not to +include some auxiliary files with the cross-references in the former +case. For two reasons. I am unsure as to how to do it and it is a +bit overwhelming if you are in a large document to have these sections. +I guess it can be done, however, and I guess you may like it. Drop me a +mail in this case. + +You may now say to yourself, how is this going to work, if in my +file whatever.tex there is a \documentclass, etc. all forbidden in +a document's body? You have two choices. One is to delete all the +offending commands and \input the diminished file. Another is to use +nodoc.tex which I also provide. This nodoc.tex inhibits all offending +commands for a while ---long enough for LaTeX not noticing it---, +and restores the definitions just in time for you to have your dose of +error-messages if you dare putting a preamble macro in the wrong place. +For using it, simply add an \input{nodoc} at the very beginning of your +file, and you will then be allowed both to typeset your file with LaTeX +directly and to include it in other files, at the expense of a very +limited memory use. + +2. Making screen versions of your programs + +Programs are cumbersome to follow. With CWEB your programs get a +better structure, are better typeset and are more easy to understand. +They remain, however, hard to follow because you have to move paper to +and fro, looking for the referenced code. Using this new package, and +if the documentation file (the one obtained with cweave) is processed to +provide a screen version that can use hyperlinks (such as with PDFLaTeX, +xdvi, dvipdfm) with the help of the hyperref package, the screen version +you get has all the program chunks linked and referenced, so that when +one is used or cited, there is a link you can click on to get to the +adequate place. If you do not use the hyperref package no harm is done +and the changes take no effect. + +Enjoy yourself with this demonstration of my clumsy TeX programming, +and let me know if you experience any problems. Please write to Enrique +Meléndez <UEI0560130010@eurociber.es> in case of failure, being as +precise as you can with the error, possibly with a short example +that demonstrates the failure, and providing a workaround (in the best of +the worlds :-)) + +Regards, +Enrique Meléndez + +By the way, no responsibility is held. I did this for fun (among other +things) and it worked for me. it may not work for you or, if it works, +it may not perform exactly as you intended. If you write to me I can +try my best to solve your problem (and I probably will try), but I make no +formal promises. See the GNU public license for details. diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/cwbasehy.tex b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/cwbasehy.tex new file mode 100644 index 00000000000..1f7941323c5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/cwbasehy.tex @@ -0,0 +1,2239 @@ +% $StyleId: cwebbase.doc,v 1.4 1995/11/07 17:55:19 schrod Exp $ +%---------------------------------------------------------------------- +% Written by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>. +% Copyright conditions see below (GPL). + +% +% LaTeX macros cwebbase +% support for incorporation of CWEAVE markup in LaTeX documents +% +% [LaTeX in MAKEPROG] +% (history at end) + + + + +%%%% +%%%% +%%%% These TeX macros were documented with the documentation system +%%%% MAKEPROG and automatically converted to the current form. +%%%% If you have MAKEPROG available you may transform it back to +%%%% the original input: Remove every occurence of three percents +%%%% and one optional blank from the beginning of a line and remove +%%%% every line which starts with four percents. The following lex +%%%% program will do this: +%%%% +%%%% %% +%%%% +%%%% ^%%%\ ? ; +%%%% ^%%%%.*\n ; +%%%% +%%%% If you just want to print the documentation you may fetch +%%%% the archive print-makeprog.tar.Z from ftp.th-darmstadt.de (directory +%%%% pub/tex/latex). It contains *all* used styles -- but beware, they +%%%% may not be in a documented form... +%%%% +%%%% +%%% \documentclass{progltx} + +%%% \usepackage{cweb-doc} % document-specific markup +%%% \usepackage{fullpage} + + +%%% \RCS $StyleRevision: 1.4 $ +%%% \RCS $StyleDate: 1995/11/07 17:55:19 $ + + +%%% \begin{document} + + +%%% \title{Typesetting \cweave{} Output} +%%% \author{% % LaTeX does not discard unnecessary glue... +%%% Joachim Schrod% +%%% \thanks{% +%%% \protect\raggedright +%%% TU~Darmstadt, Computer Science Department, WG Systems Programming, +%%% Alexanderstr.~10, D-64283~Darmstadt, Germany. +%%% Email: \texttt{schrod@iti.informatik.th-darmstadt.de}.% +%%% }% +%%% } +%%% \date{% +%%% Revision \RCSStyleRevision\\ +%%% (as of \RCSStyleDate)% +%%% } + +%%% \maketitle + + +%%% % doesn't work with progltx yet +%%% %\tableofcontents + + + + +%%% \chap Introduction. + +%%% This code shall interpret and render the tag set output by \cweave{}. +%%% That's realized in this module as it's needed in multiple places -- +%%% when we want to use \LaTeX{} markup in \cweb{}, when we want to +%%% incorporate \cweb{} pieces in \LaTeX{} documents (as examples, or in +%%% textbooks), and when we want to incorporate whole \cweb{} documents in +%%% a \LaTeX{} document. (That's by far the most difficult task.) + +%%% As \cweb{} operates in modes, for obvious reasons our implementation +%%% is based on a finite state automaton (FSA). The whole tag set is +%%% separated into subsets that are valid in certain states. + +%%% The complete set of tags does not obey any name conventions, some tags +%%% are even in conflict with standard \LaTeX{} tags (e.g.\ |\\|). Most +%%% tags are used to render code pieces. With the introduction of states +%%% we can restrict the visibilities of these tags to those states where +%%% we typeset program parts. The needed functionality will be available +%%% in cseqs of our namespace, we'll map that to \cweave{}'s names in a +%%% group. + +%%% Then we have to implement the rendering of chunks and sections, that's +%%% (more or less) a straight-forward task. Actually, we only set up the +%%% basic code pieces, the integration of section divisions in the actual +%%% \LaTeX{} document is a task of higher-level code; that integration +%%% depends heavily on the type of document. That also implies that we +%%% won't implement front or back matter material (document markup, table +%%% of contents, index, list of refinements, etc.)\ in this module. + + +%%% \sect Let's identify this module. + +%%% \noindent The code below is explained in the implementation +%%% documentation of the \pkg{rcs} package. + +%%% \beginprog +\begingroup + \def\RCSFile#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesFile{#1}[\date\space\id\space #2]% + } + + \RCSFile{cwebbase.tex}{CWEAVE tags for LaTeX markup} + $StyleDate: 1995/11/07 17:55:19 $: 9999/00/00 \endRCS + $StyleRevision: 1.4 $: 0.0 \endRCS +\endgroup +%%% \endprog + + +%%% \sect This module is part of the supported \textsl{cweb-sty} bundle. +%%% Send bug reports, comments and repairs. + +%%% It assumes that the canonical setup of my modules has happened and can +%%% be used herein. (In particular, the underscore is a letter.) + + +%%% \sect This module reserves the namespace |cwbb|. It assumes that +%%% |\cweb_warning| is bound either to |\PackageWarningNoLine| or +%%% |\ClassWarningNoLine|, depending on the environment. + +%%% \beginprog +\ifx \cwbb@loaded\undefined + \def\cwbb@loaded{$StyleRevision: 1.4 $} +\else + \cweb_warning{cwebbase}% + {Some other package already uses namespace `cwbb'} +\fi +%%% \endprog + + +%%% \sect This is freely distributable 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 software is distributed in the hope that it will be useful, but +%%% \textbf{without any warranty}; without even the implied warranty of +%%% \textbf{merchantability} or \textbf{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 in +%%% the file |License| along with this package; if not, write to the Free +%%% Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA. + + +\ifx\hypertarget\undefined +\def\hypertarget#1#2{#2} +\def\hyperlink#1#2{#2} +\fi + + +%%% % ------------------------------------------------------------ +%%% % +%%% % subdocument: The interface between CWEAVE and TeX +%%% % + +%%% \input{cweave-spec} + +%%% % +%%% % ------------------------------------------------------------ + + + + +%%% \chap Interface of \pkg{cwebbase} module. + +%%% \pkg{cwebbase} implements most of \cweave{} tags. It sets up tons of +%%% redefinable cseqs, all of them start with |Cweb|. +%%% % +%%% \begin{fixme} +%%% How do I document them? We need a configuration document anyhow. Do +%%% I present here just a list of those cseqs realized in this module +%%% and refer to the config docs? Need to wait until I have it, then +%%% we'll see how the stuff here will be added. +%%% \end{fixme} + + +%%% \sect This module supports both hierarchic and flat section +%%% structuring. You have to bind |\cweb@structure| to 0 (hierarchic) or 1 +%%% (flat) before importing it, to show which structure is wanted. + + +%%% \sect This module supports suppression of different document parts. +%%% You have to define flags |@cweb@suppress@|\<foo>|@| with +%%% $\mbox{\<foo>} \in \{ |changehints|, |unchanged|, |format| \}$ to +%%% denote if suppression shall happen. + + +%%% \sect The counter |secnumdepth| must be~11 if chunks shall be +%%% numbered. That counter doesn't need to be set when this module is +%%% imported, it can be set locally during typesetting \cweb{} code. + +%%% The definitions for flat structure assume that |secnumdepth| is~11 +%%% during typesetting. + + +%%% \sect |\part|, |\chapter| (if available), and |\section| are used for +%%% \cweb{} section divisions (those with the lowest ranks). These +%%% commands will change the respective counters globally and will +%%% add toc lines and marks. You might want to prevent that by redefining +%%% |\addcontentsline| and |\mark|. + +%%% Table of contents macros are not defined for the section divisions +%%% introduced by this module. You must either prevent that they are +%%% written to the |AUX| file at all; or you must define them. +%%% % +%%% \begin{fixme} +%%% Add explanation of introduced section divisions. +%%% \end{fixme} + +%%% For flat structure, all section divisions are of type `|chunk|', like +%%% chunks. The section names start with `|\cwbbRank{|\<rank>|}|'. By +%%% default, |\cwbbRank| takes one argument and expands to the empty list +%%% -- this can be redefined for the table of contents. + + +%%% \sect The document end, as explained in the \cweave{} interface specs +%%% (chunk~\ref{spec:sec:docend}), is not implemented. That must be done +%%% by the user of this module -- if the back matter is to be processed at +%%% all. + + + + +%%% \chap Processing states. + +%%% We have to typeset five different categories of material: +%%% Documentation, program pieces---embedded within the documentation and +%%% as large chunks, \TeX{} material within program pieces (i.e., comments +%%% and refinement names), and cross reference information. Since we need +%%% a complete other environment for the program pieces than for the rest +%%% we design ``states'' where we switch to appropriately. +%%% % +%%% \begin{enumerate} + +%%% \item A chunk starts in the \textsl{documentation state}. + +%%% \item |\B| switches to \textsl{program state}. This can happen in +%%% documentation and program state. + +%%% \item While we process the argument of |\PB| we're in \textsl{restricted +%%% program state}; |\PB| may appear in documentation and in \TeX{} +%%% state. Since \TeX{} state can be switched on within restricted +%%% program state, |\PB| can appear within the argument of itself. + +%%% \item In the arguments of |\C|, |\SHC|, and |\X| we switch to +%%% \textsl{\TeX{} state}. All these cseqs appear only in (restricted) +%%% program state, their official names are actually different. I.e., only +%%% in (restricted) program state these cseq are bound to the meaning +%%% described here. + +%%% \item Cross reference information are attached to most chunks with +%%% refinements. This information is processed in \textsl{CR state}. +%%% After CR state material +%%% comes always the next chunk or the document end, i.e., material in +%%% documentation state. + +%%% \end{enumerate} +%%% % +%%% This FSA is illustrated by the diagram in figure~\ref{fig:fsa}. + +%%% \begin{figure} + +%%% \begin{center} +%%% \chardef\\=`\\ +%%% \input{cweb-fsa.latex} +%%% \end{center} + +%%% \caption{The processing state's FSA. The automaton starts and ends in +%%% the ``documentation'' state.} +%%% \label{fig:fsa} + +%%% \end{figure} + +%%% |\cwbb@documentation| will switch to documentation state, +%%% |\cwbb@program| to program state, |\cwbb@Rprogram| to restricted +%%% program state, |\cwbb@tex| to \TeX{} state, and |\cwbb@CR| to CR state. +%%% If we're already in a state, the switch to this state shall be a +%%% permissible null operation. + + +%%% \sect The basic difference between these states can be named with +%%% two parameters: (1)~The cseq bindings in effect and (2)~the layout +%%% parameters used for paragraph makeup. + +%%% In (restricted) program state and in CR state the text is output +%%% under the control of \cweave{}, and tagged by \cweave{}. The used +%%% tags are from a global namespace and should only be in effect during +%%% these states. We call this tag set the \textsl{\cweave{} bindings}. In the +%%% other two states the tags are largely defined by the user, the tag +%%% set is called the \textsl{user bindings}. The switch to another binding +%%% is always done locally, i.e., if we switch from documentation to +%%% restricted program state within a group we don't have to bother about +%%% the restauration of the user binding; it will be done automatically +%%% by \TeX{} at the end of the group. Nevertheless we must be able to +%%% switch from the \cweave{} bindings back to the user bindings which +%%% were in effect when we activated the \cweave{} bindings. This is +%%% needed for the \TeX{} state which is always activated within +%%% (restricted) program state. + +%%% The parameters for \textsl{program layout} are really special ones +%%% since they need to support the indentation which shows the program +%%% structure. These parameters are used in program and in \TeX{} state. +%%% The \textsl{document layout} parameters established by the user are +%%% used in the other three states. + +%%% The following table shall summarize this. $C$~denotes \cweave{} +%%% bindings, $U$~user bindings, $P$~program layout, and $D$~document +%%% layout. If an entry is empty, its value is not changed on entry in +%%% this state. +%%% % +%%% \begin{center} +%%% \DeleteShortVerb\| +%%% \begin{tabular}{r|c|c} +%%% \multicolumn1{c|}{\textsc{State}} & \textsc{Binding} & \textsc{Layout} \\[1pt] +%%% \hline +%%% documentation & $U$ & $D$ \\ +%%% program & $C$ & $P$ \\ +%%% restricted program & $C$ & \\ +%%% \TeX{} & $U$ & \\ +%%% CR & $C$ & $D$ \\ +%%% \end{tabular} +%%% \MakeShortVerb\| +%%% \end{center} + + +%%% \sect Since the user bindings and the document layout is defined +%%% initially, we don't have to do anything if it's requested. Only if we +%%% change it, i.e., within |\cwbb@cweave_bindings| and +%%% |\cwbb@program_layout|, we redefine |\cwbb@user_bindings| and +%%% |\cwbb@doc_layout|. If they are eventually executed, they shall +%%% rebind themselves back to |\relax|. This way we can switch to +%%% documentation state as often as we want. + +%%% \beginprog +\let\cwbb@user_bindings=\relax +\let\cwbb@doc_layout=\relax + +\def\cwbb@documentation{% + \cwbb@user_bindings + \cwbb@doc_layout + } +\def\cwbb@Rprogram{\cwbb@cweave_bindings} + +\def\cwbb@program{% + \cwbb@cweave_bindings + \cwbb@program_layout + } +\def\cwbb@tex{\cwbb@user_bindings} + +\def\cwbb@CR{% + \cwbb@cweave_bindings + \cwbb@doc_layout + } +%%% \endprog + + + + +%%% \chap Saving and restoring control sequences. + +%%% We have a lot of cseqs which are defined within the namespace of this +%%% module and which will be used with other names. This usage is in a +%%% controlled environment, namely neither in documentation nor in \TeX{} +%%% state. (I.e., the text processed is tagged by \cweave{}, not by humans; +%%% therefore we have a precise specification of the cseqs we have to +%%% accept.) We cannot work with groups where a cseq is just redefined +%%% and \TeX{} takes care for establishing the old binding again; when we +%%% switch from program state to \TeX{} state all the bindings which were +%%% in effect before the program state get active, i.e., in the +%%% documentation state, must be in effect again. We cannot simply +%%% consider the \TeX{} state as something parallel to program state, it +%%% must be a hierarchical relationship: In the program state values are +%%% set up which must be available after switching back from \TeX{} to +%%% program state. + +%%% We save the current binding of a cseq in another cseq, but only if +%%% there exists a binding currently. This is done to save valuable +%%% \TeX{} main memory. (Why don't all those people who talk about +%%% extending \TeX{} not just implement dynamic memory management for the +%%% existing \TeX{}? It would still be \TeX{} and would \emph{really} be +%%% a worthy activity. But not enough fun, I assume\,\dots) Actually, one +%%% can assume that nearly no cseq bindings must be saved at all---the +%%% used names are strange enough. The bindings of |\foo|, i.e., of the +%%% cseq with the name \fbox{\ttfamily foo}, is saved as the cseq with the +%%% name \fbox{\ttfamily cweb\char `\\ foo}, i.e., as +%%% |\csname cweb\string\foo \endcsname|. + + +%%% \sect The save process is not done statically, but by the macro +%%% |\cwbb@rebind| which interprets a list of tuples $({\it old\_name}, +%%% {\it new\_name})$, terminated by the tuple $(|\stop|, |\stop|)$. +%%% Eventually it constructs two new lists, |\cwbb@to_restore| with the +%%% cseqs which had a binding, and |\cwbb@undefined| with the names which +%%% didn't have one. + +%%% The saving is actually done by |\cwbb@save_binding|, |\cwbb@rebind| +%%% is responsible for the initialization, |\cwbb@do_rebind| for the +%%% effective rebinding and the tail recursion on the list. + +%%% \begin{fixme} +%%% We could pull the |\next| assignment in the |\else| branch out of +%%% the loop to get a better performance. Should measure if this is of +%%% interest. +%%% \end{fixme} + +%%% \beginprog +\newtoks\cwbb@undefined +\newtoks\cwbb@to_restore + +\def\cwbb@rebind{% + \cwbb@undefined{}% + \cwbb@to_restore{}% + \cwbb@do_rebind + } +\def\cwbb@do_rebind#1#2{% + \ifx #1\stop + \let\next\relax + \else + \cwbb@save_binding #2% + \let #2=#1% + \let\next\cwbb@do_rebind + \fi + \next + } +%%% \endprog + + +%%% \sect If the cseq to be saved is undefined, it may just be added to +%%% the ``undefined list.'' Otherwise its binding is saved and it's added +%%% to the ``to-be-restored list.'' + +%%% \TeX{}nical note: The cseq-name for the saved binding must be created +%%% before the |\let| is executed. + +%%% \beginprog +\def\cwbb@save_binding#1{% + \ifx #1\undefined + \cwbb@undefined \expandafter{\the\cwbb@undefined #1}% + \else + \expandafter\let \csname cweb\string#1\endcsname =#1% + \cwbb@to_restore \expandafter{\the\cwbb@to_restore #1}% + \fi + } +%%% \endprog + + +%%% \sect The restoration of rebound cseqs is a two-tied activity: All +%%% previously undefined cseqs must be made undefined again, and all saved +%%% cseqs must be restored. Actually, we don't need to reset the two token +%%% lists, but we do it to save space. + +%%% Both |\cwbb@undefine| and |\cwbb@restore_binding| iterate over a list +%%% of cseqs terminated by |\stop|. + +%%% \begin{fixme} +%%% And here the |\next| assignment could be prepended to the loop as +%%% well. +%%% \end{fixme} + +%%% \beginprog +\def\cwbb@restore_bindings{% + \expandafter\cwbb@undefine \the\cwbb@undefined \stop + \cwbb@undefined{}% + \expandafter\cwbb@restore_binding \the\cwbb@to_restore \stop + \cwbb@to_restore{}% + } + +\def\cwbb@undefine#1{% + \ifx #1\stop + \let\next\relax + \else + \let#1\undefined + \let\next\cwbb@undefine + \fi + \next + } +%%% \endprog + + +%%% \sect \TeX{}nical note: As in |\cwbb@save_binding|, the cseq-name for +%%% the saved binding must be created before the |\let|s are executed. + +%%% \begin{fixme} +%%% Another |\next| assignment. +%%% \end{fixme} + +%%% \beginprog +\def\cwbb@restore_binding#1{% + \ifx #1\stop + \let\next\relax + \else + \expandafter\let \expandafter#1\csname cweb\string#1\endcsname + \expandafter\let \csname cweb\string#1\endcsname \undefined + \let\next\cwbb@restore_binding + \fi + \next + } +%%% \endprog + + + + +%%% \chap Chunks. + +%%% All chunks are numbered subsequently. The chunk number is supplied as +%%% part of the markup. In addition, the `changed' tag |\*| may be +%%% appended to the chunk number. + +%%% By default, chunks have approximately two picas vertical space in +%%% front. + +%%% If we use an hierarchic structure, we output the chunk number at the +%%% refinement. (It's only needed to identify the refinement for cross +%%% references.) But chunks are important structural units and thus should +%%% be marked by typographic means that's more visible than the space +%%% mentioned above, we add a `chunk start marker'. + +%%% For a flat structure, we output the chunk number as the chunk start +%%% marker, that is the traditional \WEB{} layout. + +%%% In any case, the documentation part shall be run in after the chunk +%%% start marker. + +%%% \beginprog +\newskip\CwebChunkPreSkip + \CwebChunkPreSkip=2pc plus 1pc minus 6pt +%%% \endprog + + +%%% \sect In \LaTeX{}, structural divisions are best realized by +%%% |\@startsection|, we'll use it also for chunk starts. The chunk start +%%% marker is the section heading. For hierarchic structure, we use a +%%% traditional paragraph sign, used since medieval times to tag new text +%%% units. Our first test showed that the paragraph sign has typically an +%%% underlength, that doesn't look good at the start of a chunk. We raise +%%% the sign by its depth. + +%%% For flat structure, we don't have text as the section heading, +%%% but we have to cope for a deficiency of \LaTeX{}: It always leaves a +%%% quad after the section number (by the way, this is not mentioned in +%%% the documentation---you have to look in the macros to figure this +%%% out). So we use a backskip of $\rm -1\,em$ as the chunk start marker +%%% then. + +%%% Changed chunks are marked by a changeflag, by default a star lapping +%%% to the right. We need the information if that chunk is changed to +%%% decide if we shall output the changeflag. We demand from the chunk +%%% macros that they record that info in the flag |@cwbb_changed_chunk@|. + +%%% Each structural division must be categorized, it belongs to a +%%% \textsl{type}. This type determines also the name of the counter, the +%%% mark handling for this category, and how this section tag is +%%% represented in the table of contents. The type of chunks is `|chunk|' +%%% (trivial, isn't it?). + +%%% Furthermore, a structural division in \LaTeX{} has an associated +%%% \textsl{level}. That level is used to determine if that division get +%%% numbered in text or table of contents. For sections, we'll compute the +%%% level from the rank, it will not be larger than the rank.% +%%% \footnote{Check the next section for a more precise definition of +%%% `rank' and `level'.} +%%% Since the highest section rank is~10, we may use 11 as chunk level. + +%%% For flat structure, we output the number for all section headings, +%%% including chunks. For hierarchic structure we use the default maximum +%%% level as supplied by our document class (e.g., 3~for \cls{article}, +%%% and 2~for \cls{report} or \cls{book}). + +%%% As a last point, we have to care already for sections in flat +%%% structure. They will use the |chunk| category as well, we have to +%%% distinguish them in the table of contents. For that, we'll record the +%%% level in the text, it will get written to the table of contents. + +%%% \beginprog +\newif\if@cwbb_changed_chunk@ +\let\CwebChangeFlag=* +\if@cweb@suppress@changehints@ + \let\cwbb@change_flag=\relax +\else + \let\cwbb@change_flag=\CwebChangeFlag +\fi +\def\cwbb@lap_change_flag{\rlap{\cwbb@change_flag}} + +\ifcase \cweb@structure + %% hierarchic + \let\CwebChunkHeadingStyle\relax + \newbox\cweb@chunk_marker + \setbox\cweb@chunk_marker=\hbox{\P} % tradition from medivial times + \setbox\cweb@chunk_marker=\hbox{% + \raise\dp\cweb@chunk_marker \box\cweb@chunk_marker + } + \def\CwebChunkHeadingMarker{\copy\cweb@chunk_marker} + \def\CwebChunkHeading#1{% + \CwebChunkHeadingMarker + \if@cwbb_changed_chunk@ \cwbb@lap_change_flag \fi + } + \or + %% flat + \def\cwbbRank#1{} + \def\CwebChunkHeadingStyle{\bfseries} + \def\CwebChunkHeading#1{% + \protect\cwbbRank{#1}% + \kern -1em + \if@cwbb_changed_chunk@ \cwbb@lap_change_flag \fi + } +\fi +%%% \endprog + + +%%% \sect Chunks are tagged with |\M| and get passed the chunk number as +%%% argument. Before we evaluate |\@startsection|, we'll start the chunk. +%%% That's common code to be used by sections as well, as they also +%%% implicitely start a chunk. + +%%% Enrique Mel\'endez (\texttt{ema@csn.es}) introduced some code to insert +%%% hyperlinks. + +%%% \beginprog +\def\M#1{% + \cwbb@start_chunk{#1}% + \@startsection + {chunk}% % category, == counter etc. + {11}% % level + {\z@}% % no indentation for heading + {\CwebChunkPreSkip}% % skip above heading + {\m@ne em}% % run-in heading, 1em distance to text + {\normalfont\CwebChunkHeadingStyle}% % layout + {\CwebChunkHeading{11}}% % text, level might go to toc file + \hypertarget{_hypersect_#1}{}% + } +%%% \endprog + + +%%% \sect But let's first declare how a chunk number is represented. The +%%% principle rendering is controlled by |\thechunk|, namely, we get +%%% arabic numbers. This rendering is used both for creation of the +%%% section header (if in flat mode) and for cross references. I.e., +%%% |\ref| expands into it. + +%%% But for flat structure we need different expansions: In the section +%%% header a period shall be appended, a cross reference shall appear +%%% without such a period. We use two different macros: |\thechunk| +%%% creates the number with the period, |\cwbb@refchunk| only the number. +%%% The latter is used for a redefinition of |\@currentlabel|. Of course, +%%% for hierarchic structure, both are the same. + +%%% \beginprog +\newcounter{chunk} + +\def\cwbb@refchunk{\arabic{chunk}} + +\ifcase \cweb@structure + %% hierarchic + \let\thechunk=\cwbb@refchunk + \or + %% flat + \def\thechunk{\arabic{chunk}.} +\fi +%%% \endprog + + +%%% \sect Each chunk is started by |\cwbb@start_chunk|, which does the +%%% common actions. First of all, we switch to documentation state. + +%%% Then we store the chunk number in the |chunk| counter. That implies +%%% that the chunk start must not step this counter! We'll take care for +%%% that later by redefining |\refstepcounter|. The actual number is +%%% passed as the argument, including an optional |\*| used to denote +%%% changed chunks. We'll redefine that cseq to update the flag +%%% |@cwbb_changed_chunk@|. + +%%% Each chunk must be typeset with an open |\if| since it is finished by +%%% |\fi|. If we shall suppress the output of unchanged chunks, we have +%%% to use |\iffalse| if not |@cwbb_changed_chunk@|, otherwise |\iftrue|. +%%% The flag |@cwbb_print_chunk@| is set up to provide an appropriate +%%% test. + +%%% When we typeset a chunk, we evaluate |\cwbb@init_print_chunk|. For +%%% hierarchic structure, that cseq will be used to initialize the +%%% typesetting of the chunk number at program parts. + +%%% \beginprog +\if@cweb@suppress@unchanged@ + \def\if@cwbb_print_chunk@{\if@cwbb_changed_chunk@} + \@gobble\fi % close \if in case it's skipped +\else + \let\if@cwbb_print_chunk@=\iftrue + \@gobble\fi % same here +\fi + +\def\cwbb@start_chunk#1{% + \cwbb@documentation +% \hypertarget{_hypersect_#1}{}% + %%\hypertarget{_hyperchunk_#1}{}% + \begingroup + \def\*{\global\@cwbb_changed_chunk@true}% + \global\@cwbb_changed_chunk@false + \global \c@chunk #1\relax % might expand \* + \endgroup + \if@cwbb_print_chunk@ + \cwbb@init_print_chunk + } +%%% \endprog + + +%%% \sect |\@startsection| will step the section counter (i.e., |chunk|). +%%% Since we just assigned it in |\cwbb@start_chunk|, that would leave us +%%% with a counter that's one too high. And our output in cross references +%%% may be wrong, as a period is appended in flat structure. + +%%% That damage all comes from one macro, |\refstepcounter|; let's +%%% advice it to do the Right Thing for |chunk| counters. + +%%% \beginprog +\let\cwbb@refstepcounter=\refstepcounter + +\def\cwbb@string@chunk{chunk} +\def\refstepcounter#1{% + \def\@tempa{#1}% + \ifx \@tempa\cwbb@string@chunk + \protected@edef\@currentlabel{\cwbb@refchunk}% + \else + \cwbb@refstepcounter{#1}% + \fi + } +%%% \endprog + + + + +%%% \chap Sections. + +%%% Important sections are started on a new page, normal sections have the +%%% same space as chunks in front. The very first section does not +%%% automatically start on a new page since a title may be in front of it. + +%%% Each section division has a \textsl{rank}, that denotes the section +%%% depth as seen by \cweave{}. + +%%% For this depth we compute a \textsl{level}, used to denote the section +%%% depth for \LaTeX{}. This section depth is used to decide where +%%% numbering shall stop, or if that entry shall be presented in the table +%%% of contents, etc. + +%%% These two numbers are not the same, due to the support of document +%%% classes with chapters. + +%%% We consider a section as important if it's rank is smaller than~3, +%%% i.e., then we'll start a new page. This limit is controlled by the +%%% number |\CwebRankNoEject|. The rank is used as the section level +%%% and is therefore available to configure depth of typeset numbering and +%%% appearance in table of contents. + +%%% \beginprog +\def\CwebRankNoEject{3} +%%% \endprog + + +%%% \sect Sections are started with the macro |\N|. It's first parameter +%%% is the section's rank. The second parameter is the chunk number, the +%%% third the title of the section. This last parameter must be terminated +%%% by a dot. + +%%% Each section implicitly starts a chunk. As explained above, major +%%% sections may eject the page, and we add our actual section heading +%%% with |\CwebSection|. + +%%% We also tell the user that we have reached the next section by telling +%%% him about the current chunk number. The message is output after the +%%% section header is set, it shall be on the correct page. Since the +%%% token list to be output is expanded at shipout time, we must take care +%%% for the immediate expansion ourselves. + +%%% Enrique Mel\'endez (\texttt{ema@csn.es}) introduced some code to insert +%%% hyperlinks. +%%% \beginprog +\def\N#1#2#3.{% + \cwbb@start_chunk{#2}% + \CwebEjectSection{#1}% + \hypertarget{_hypersect_#2}{}% + \CwebSection{#1}{#3}% + \begingroup + \def\*{}% + \edef\tmp{*#2}% + \message \expandafter{\tmp}% + \endgroup + } +%%% \endprog + + +%%% \sect At the start of a section we usually eject the page if our rank +%%% is not too low. But if the user had a title above the first section, +%%% he won't want this page break. So we try to guess it. If we guess +%%% wrong, the user may either add |\newpage| himself or he may redefine +%%% |\CwebEjectSection| in a package. + +%%% \beginprog +\def\CwebEjectSection#1{% % #1 == rank + \gdef\CwebEjectSection##1{% + \relax + \ifnum ##1<\CwebRankNoEject\relax + \newpage + \fi + }% + } + +\if@titlepage + \CwebEjectSection{} +\fi +%%% \endprog + + +%%% \sect Now comes a heary piece. We have 11~section ranks, and need 11 +%%% different section categories, section counters, etc. For flat +%%% structure, they shall all do the same; for hierarchic structure, they +%%% shall be really different. + +%%% \noindent Let's have a look at the hierarchic structure first, it's +%%% more complex. +%%% % +%%% \begin{itemize} + +%%% \item We associate section rank~0 (that's `|@**|') with document +%%% parts, i.e., map it to |\part|. Many smaller programs won't use it. + +%%% \item If we are used in a class that has a bound cseq |\chapter|, we +%%% associate rank~1 (`|@*0|') with it and rank~2 (`|@*1|') with +%%% |\section|. Otherwise we associate rank~1 with |\section|. These +%%% tags (|\chapter| and/or |\section|) must be defined because many +%%% macros that want to create section divisions will use them. + +%%% \item All other section ranks are placed below |\section|. +%%% |\subsection| and other \LaTeX{} style markup is not supported. + +%%% For hierarchic structure, we identify these sections with category +%%% names `|section|$l$', where $l$ is the respective level, computed +%%% from the rank. Those section names do not exist yet, we have to +%%% create them. + +%%% \end{itemize} + +%%% Now we come to the point why we can't use the rank as the section +%%% level passed to \LaTeX{}: When we assume the level usage of \LaTeX{}'s +%%% standard classes, |\section| is \emph{always} on level~1, independent +%%% of the existence of |\chapter|. The latter is placed on level~0, its +%%% existence only influences the section level of |\part|, which is +%%% either $-1$ or~0. + +%%% This implies that |\subsection| in a standard class is always on +%%% level~2, but our equivalent section division is either `|@*0|' +%%% (rank~1) or `|@*1|' (rank~2). I.e., when we have chapters, we use a +%%% level that's one lower than the rank, otherwise we use the rank. + +%%% For flat structure, we use type |chunk|. This way we'll use the chunk +%%% numbers, they are already set up. + +%%% For flat structure, we will map all ranks to the same section markup. +%%% This markup will also be accessible by |\section| or |\chapter|. They +%%% will be declared to be on a level that is the same as the rank. + + +%%% \sect The printed representation of a section divison number is simply +%%% the presentation from the next upper level, a full stop, and an arabic +%%% section number. When we compute the name of the previous level we must +%%% pay attention to our first section division created this way. This +%%% division must be placed below |section|, without any following number. + +%%% Since registers are a valuable resource in \TeX{}, we have to take +%%% care not to allocate a superfluous one. + +%%% \beginprog +\def\toclevel@chunk{12} +\def\theHchunk{chunk.\arabic{chunk}} +\ifcase \cweb@structure + %% hierarchic + \newcounter{section2}[section] + \@namedef{thesection2}{\@nameuse{thesection}.\arabic{section2}} + \newcounter{section3}[section2] + \@namedef{thesection3}{\@nameuse{thesection2}.\arabic{section3}} + \newcounter{section4}[section3] + \@namedef{thesection4}{\@nameuse{thesection3}.\arabic{section4}} + \newcounter{section5}[section4] + \@namedef{thesection5}{\@nameuse{thesection4}.\arabic{section5}} + \newcounter{section6}[section5] + \@namedef{thesection6}{\@nameuse{thesection5}.\arabic{section6}} + \newcounter{section7}[section6] + \@namedef{thesection7}{\@nameuse{thesection6}.\arabic{section7}} + \newcounter{section8}[section7] + \@namedef{thesection8}{\@nameuse{thesection7}.\arabic{section8}} + \newcounter{section9}[section8] + \@namedef{thesection9}{\@nameuse{thesection8}.\arabic{section9}} +% + \@namedef{theHsection2}{\@nameuse{thesection}.\arabic{section2}} + \@namedef{theHsection3}{\@nameuse{thesection2}.\arabic{section3}} + \@namedef{theHsection4}{\@nameuse{thesection3}.\arabic{section4}} + \@namedef{theHsection5}{\@nameuse{thesection4}.\arabic{section5}} + \@namedef{theHsection6}{\@nameuse{thesection5}.\arabic{section6}} + \@namedef{theHsection7}{\@nameuse{thesection6}.\arabic{section7}} + \@namedef{theHsection8}{\@nameuse{thesection7}.\arabic{section8}} + \@namedef{theHsection9}{\@nameuse{thesection8}.\arabic{section9}} + \@namedef{toclevel@section2}{2} + \@namedef{toclevel@section3}{3} + \@namedef{toclevel@section4}{4} + \@namedef{toclevel@section5}{5} + \@namedef{toclevel@section6}{6} + \@namedef{toclevel@section7}{7} + \@namedef{toclevel@section8}{8} + \@namedef{toclevel@section9}{9} + \ifx \chapter\undefined + \newcounter{section10}[section9] + \@namedef{thesection10}{\@nameuse{thesection9}.\arabic{section10}} + \@namedef{theHsection10}{\@nameuse{theHsection9}.\arabic{section10}} + \@namedef{toclevel@section10}{10} + \else + \fi +\fi +%%% \endprog + + +%%% \sect Sections are typeset by |\CwebSection|; rank and title are the +%%% arguments. + +%%% For hierarchic structure, we select the proper cseq according to rank: +%%% |\part|, |\chapter| if this is a structure with chapters, |\section|, +%%% and |\cwbb@section{|\<rank>|}| for other ranks. For the last cseq we +%%% also have to supply the section category, it's `|section|$l$' where +%%% $l$ is the rank~$r$ if we don't have chapters, $r-1$ otherwise. + +%%% That category cannot be computed by |\cwbb@section| itself since we +%%% want to use that macro also for flat structure. But there all sections +%%% are basically chunks, we have to use the |chunk| category there. Since +%%% we want to differentiate them in the table of contents nevertheless, +%%% we record the current rank in the title. + +%%% \beginprog +\ifcase \cweb@structure + %% hierarchic + \ifcase\cweb@cls + \ifx \chapter\undefined + \def\CwebSection#1#2{% + \ifcase #1 + %% 0 + \let\next\part + \or %% 1 + \let\next\section + \else %% level = rank + \def\cwbb@sect_name{section#1}% + \def\next{\cwbb@section{#1}}% + \fi + \next{#2}% + } + \else + \def\CwebSection#1#2{% + \ifcase #1 + %% 0 + \let\next\part + \or %% 1 + \let\next\chapter + \or %% 2 + \let\next\section + \else %% level = rank - 1 + \count@=#1 \advance \count@\m@ne + \edef\cwbb@sect_name{section\number\count@}% + \edef\next{\noexpand\cwbb@section{\number\count@}}% + \fi + \next{#2}% + } + \fi + \or %% In case we are included from other classes + %% + \ifx \chapter\undefined + \def\CwebSection#1#2{% + \count@=#1 \advance \count@\@ne\advance \count@\@ne + \edef\cwbb@sect_name{section\number\count@}% + \edef\next{\noexpand\cwbb@section{\number\count@}}% + \next{#2}% + } + \else + \def\CwebSection#1#2{% + \ifcase #1 + %% 0 + \let\next\chapter + \or %% 1 + \let\next\section + \else %% level = rank + \def\cwbb@sect_name{section#1}% + \def\next{\cwbb@section{#1}}% + \fi + \next{#2}% + } + \fi + \fi + \or + %% flat + \def\CwebSection#1#2{% + \def\cwbb@sect_name{chunk}% + \cwbb@section{#1}{\protect\cwbbRank{#1}#2}% + } + \def\section{% + \def\cwbb@sect_name{chunk}% + \cwbb@section{1}% + } +\fi +%%% \endprog + + +%%% \sect We use the same layout for all minor sections. That layout can +%%% be changed by ammended by defining |\CwebSect|$r$|Hook| to redefine +%%% |\CwebSectPreSkip| and/or |\CwebSectLayout| locally. (Of couse, it may +%%% be redefined once globally, too.) These are the values to be used for +%%% arguments 4 and~5 of |\@startsection|, pay attention to the skip sign, +%%% telling about indentation of the first paragraph. And don't forget +%%% that the skip is only used for sections on ranks below +%%% |\CwebRankNoEject|, the others start on a new page anyhow. + +%%% The default definition sets the section title in bold and leaves the +%%% same space as before chunks. The first paragraph of the following +%%% documentation has no indentation. + +%%% Other layout changes (indentation for heading, etc.)\ must be made by +%%% redefining |\cwbb@section|. Or---email me, if you want to do it. Then +%%% I might be enclined to introduce further possibilities. + +%%% \beginprog +\newskip\CwebSectPreSkip + \CwebSectPreSkip = -\CwebChunkPreSkip +\def\CwebSectLayout{\normalfont\bfseries} + +\def\cwbb@section#1{% % #2 (next token) is title + \csname CwebSect#1Hook\endcsname % \relax if undefined + \expandafter\@startsection + \expandafter{\cwbb@sect_name}% % category; for counter, etc. + {#1}% % level is rank + \z@ % no indentation for heading + \CwebSectPreSkip % skip above, maybe no next par indent + \medskipamount % skip below heading + \CwebSectLayout + } +%%% \endprog + + + + +%%% \chap Marks. + +%%% \begin{fixme} +%%% Since I don't know yet how to handle marks I ignore most of them for +%%% the time being. + +%%% Have to change this later. +%%% \end{fixme} + +%%% \beginprog +\let\chunkmark\@gobble + +\count@=2 +\@whilenum \count@<11 \do { + \expandafter\let \csname section\number\count@ mark\endcsname \@gobble + \advance \count@ by 1 + } +%%% \endprog + + + + +%%% \chap Typesetting programs. + +%%% Program pieces come in two flavours: as argument of |\PB|, or as +%%% material after |\B|. In the former case we can use a group for the +%%% switch to the restricted program state, the group end will restore the +%%% previous state again. In the latter case we use |\B| for the switch to +%%% program state, the cross reference list or the next chunk will go to +%%% another state. Since we have to do more for the material after |\B|, +%%% we define this cseq later. + +%%% \beginprog +\def\PB#1{% + \begingroup + \cwbb@Rprogram + \leavevmode + #1% + \endgroup + } +%%% \endprog + + +%%% \sect Note, that |\Y| cannot just be |\smallskip|, as in Plain +%%% \cweb{}. We must assert that the current paragraph is ended before the +%%% vertical glue is inserted, and that's not done by the \LaTeX{} +%%% definition of |\smallskip|. In addition we add some negative penalty, +%%% here is a good place for a page break. As the penalty value we use +%%% half the chunk break penalty---of course a chunk start is an even +%%% better place for a page break\,\dots + +%%% It might be that |\Y| is the very first token in a chunk. Then the +%%% chunk start marker isn't set already since it is regarded as a run-in +%%% section heading. In that case we don't set the vertical skip but +%%% simply start the chunk with the program part. + +%%% \TeX{}nical note: The flag |@noskipsec| may be used to test if we're +%%% immediately after a run-in section heading. + +%%% \beginprog +\newcount\CwebProgPenalty + \CwebProgPenalty=\@secpenalty + \divide\CwebProgPenalty by 2 +\def\Y{% + \if@noskipsec + \else + \par + \penalty\CwebProgPenalty + \smallskip + \fi + } +%%% \endprog + + +%%% \sect Yep, let's unfold the ``official'' names of the cseqs used in +%%% program state. + +%%% If we turn on the \cweave{} bindings, they might be in effect already, +%%% we don't need to establish them again. We can test +%%% |\cwbb@user_bindings| for this case, it will be redefined then. + +%%% \beginprog +\def\cwbb@cweave_bindings{% + \ifx \cwbb@user_bindings\relax + \cwbb@rebind + % indentation and paragraph layout + \cwbb@incr_indent \1% + \cwbb@decr_indent \2% + \cwbb@expr_break \3% + \cwbb@backup \4% + \cwbb@opt_break \5% + \cwbb@break \6% + \cwbb@big_break \7% + \cwbb@noindent \8% + % C/C++ tokens + \CwebRel \?% + \CwebAddress \AND + \CwebComplement \CM + \CwebScope \DC + \CwebEquiv \E + \CwebGe \G + \CwebRightShift \GG + \CwebNe \I + \CwebAssign \K + \CwebLeftShift \LL + \CwebMod \MOD + \CwebNull \NULL + \CwebNot \R + \CwebBinOr \OR + \CwebMemberRef \PA + \CwebThis \this + \CwebOr \V + \CwebAnd \W + \CwebXor \XOR + \CwebLe \Z + \CwebPointer \MG + \CwebPointerMemberRef \MGA + \CwebDecr \MM + \CwebIncr \PP + % more tokens + \CwebId \\% + \CwebIdLetter \|% + \CwebRes \&% + \CwebString \.% %% ( ...Emacs... + \CwebStringBreak \)% + \CwebNumber \T + \CwebCombinedOp \MRL + % goes to TeX state + \CwebComment \C + \CwebCxxComment \SHC + \CwebRefName \X + % CWEB tokens + \CwebMacrosHere \ATH + \CwebDefine \D + \cwbb@format \F + \CwebIdCat \J + \CwebVerbString \vb + % cross reference tags + \cwbb@change_flag \*% + \CwebCRAlso \A + \CwebCRsAlso \As + \CwebCRCite \Q + \CwebCRsCite \Qs + \CwebCRUse \U + \CwebCRsUse \Us + \CwebCREt \ET + \CwebCRsEt \ETs + % finish the list + \stop\stop + \def\cwbb@user_bindings{% + \cwbb@restore_bindings + \let\cwbb@user_bindings\relax + }% + \fi + } +%%% \endprog + + +%%% \sect Since most of the \cweave{} bindings are simple and tedious +%%% coding, we'll have a look at the program layout next. Between two +%%% paragraphs there must not be any skip, the skip used in document +%%% layout is saved in |\cwbb@save@parskip|. A few other layout +%%% parameters from the document layout must be saved as well. + +%%% \beginprog +\newskip\cwbb@save@parskip +\newskip\cwbb@save@rightskip +\newcount\cwbb@save@sem_sfcode +\newcount\cwbb@save@pretolerance +\newcount\cwbb@save@hyphenpenalty +\newcount\cwbb@save@exhyphenpenalty + +\def\cwbb@save_doc_layout{% + \cwbb@save@parskip\parskip + \cwbb@save@rightskip\rightskip + \cwbb@save@sem_sfcode\sfcode`\; + \cwbb@save@pretolerance\pretolerance + \cwbb@save@hyphenpenalty\hyphenpenalty + \cwbb@save@exhyphenpenalty\exhyphenpenalty + } +\def\cwbb@restore_doc_layout{% + \parskip\cwbb@save@parskip + \rightskip\cwbb@save@rightskip + \sfcode`\;=\cwbb@save@sem_sfcode + \pretolerance\cwbb@save@pretolerance + \hyphenpenalty\cwbb@save@hyphenpenalty + \exhyphenpenalty\cwbb@save@exhyphenpenalty + } +%%% \endprog + + +%%% \sect When |\cwbb@program_layout| is called for the very first time +%%% we have to set up some variables. This cannot be done in advance +%%% since they depend on values which might be changed by the user in the +%%% preamble. This setup is done in |\cwbb@layout_init|. + +%%% If the program layout is already active, we must not switch it on +%%% another time. This can be tested by the current binding of +%%% |\cwbb@doc_layout|. + +%%% \beginprog +\def\cwbb@program_layout{% + \ifx \cwbb@doc_layout\relax + \cwbb@layout_init + \cwbb@save_doc_layout + \def\cwbb@doc_layout{% + \cwbb@restore_doc_layout + \let\cwbb@doc_layout\relax + }% + % set new values + \parskip\z@skip + \rightskip\z@ plus 100\p@ minus 10\p@ + \sfcode`\;=3000 + \pretolerance\@M + \hyphenpenalty 1000 % strings can be broken this way + \exhyphenpenalty\@M + \fi + } +%%% \endprog + + +%%% \sect The unit of the basic indentation is stored in +%%% |\CwebIndentUnit|. Continuation lines are indented two units further, +%%% i.e., the initial hanging indentation is 3~units. The current hanging +%%% indentation is kept in |\cwbb@indent|. + +%%% We need undiscardable items which can be used as backspaces, of one +%%% and two units, respectively. This is done best by boxes. The +%%% initialization of the boxes must be postponed until the user had the +%%% chance to change |\CwebIndentUnit|, it's done in the program state +%%% initialization. + +%%% \beginprog +\newdimen\CwebIndentUnit + \CwebIndentUnit=1em +\newdimen\cwbb@indent + +\newbox\cwbb@bak % backspace one unit +\newbox\cwbb@bakk % backspace two units + +\def\cwbb@layout_init{% + \global\setbox\cwbb@bak \hbox to -1\CwebIndentUnit{}% + \global\setbox\cwbb@bakk \hbox to -2\CwebIndentUnit{}% + \global\let\cwbb@layout_init\relax + } +%%% \endprog + + +%%% \sect Now we can formulate how to start typesetting program pieces: We +%%% switch to program state, set the initial indentation, and add the +%%% basic indentation of the first code line. Then we might add a marker +%%% to this program part; for hierarchic structure we want to typeset the +%%% chunk number in the margin of the chunk's program part. That's not +%%% really possible, 'though: definitions and format requests are also +%%% introduced with |\B|, so the chunk number will happen to be at the +%%% start of the definition part if one exists. + +%%% If the code line is the very first text to be typeset in this chunk, +%%% we don't add the basic indentation---we're already indented from the +%%% run-in chunk start marker. But we must not start our chunk with +%%% |\noindent|, the marker would be typeset in the left margin then. (I +%%% consider this as a \LaTeX{} error.) So we just emulate an empty +%%% documentation part, the marker is now set correctly. |\B| can test for +%%% this case: |@noskipsec| is still true then. + +%%% \beginprog +\def\B{% + \cwbb@program + \cwbb@indent 3\CwebIndentUnit \hangindent\cwbb@indent + \ifvmode + \if@noskipsec + \indent % add an empty documentation part + \else + \noindent \kern\CwebIndentUnit + \fi + \fi + \CwebNumberProgramPart + } +%%% \endprog + + +%%% \sect The chunk number shall be added at the first program part. We +%%% have a hook in the chunk start where we can set up +%%% |\CwebNumberProgramPart|. It will redefine itself at first call, to +%%% disable further output on more |\B| occurences in a chunk. + +%%% The chunk number should always be in the left margin. If it's in the +%%% right margin, there would be too much horizontal space between the +%%% code start and the actual number. (The first code line is typically +%%% not very long.) \LaTeX{} does not allow to select the margin for +%%% marginpars, therefore we have to typeset the marginal note `by hand'. +%%% As we know that we're in horizontal mode when we're called, |\vadjust| +%%% is used to create the note. The standard \LaTeX{} dimen register for +%%% the distance between marginal notes and text matter is used, of +%%% course. + +%%% Note that marginal notes may overwrite the chunk number. As it's very +%%% unlikely that somebody issues marginal notes in program mode (that's +%%% quite difficult and involves ingenious usage of the implementation of +%%% this macros), I won't care for that case. + +%%% \begin{fixme} +%%% The baseline of the marginal note shall be aligned to the baseline +%%% of the preceding line. That does not happen by default. Currently, I +%%% assume that the preceding line has a depth of appropriately the +%%% depth of a~`g'. Experiments showed that this gives good results for +%%% most \cweb{} documents. But nevertheless one should determine the +%%% exact depth of the preceding line, to know how much |box0| should be +%%% raised. If anybody knows how this can be done, please tell me. (I +%%% know about the route over the output routine, implementing an own +%%% marginal note category, but this seems too much effort.) +%%% \end{fixme} + +%%% For flat structure, we don't add any program part marker and we +%%% don't need to initialize it. + +%%% Enrique Mel\'endez (\texttt{ema@csn.es}) introduced some code to insert +%%% hyperlinks. +%%% \beginprog +\ifcase \cweb@structure + %% hierarchic + \def\cwbb@marginal_chunkno{% + \vadjust{% + \setbox\z@ \hbox to \z@{% + \hss \vphantom{g}% + \hypertarget{_hyperchunk_\thechunk}{% + \small \thechunk + }% + \hskip \marginparsep + }% + \vbox to \z@{% + \hsize\z@ + \vss + \noindent \raise \dp\z@ \box\z@ + }% + }% + } + \def\cwbb@init_print_chunk{% + \def\CwebNumberProgramPart{% + %\hypertarget{_hyperchunk_\thechunk}{% + \cwbb@marginal_chunkno%} + \let\CwebNumberProgramPart\relax + }% + } + \or + %% flat + \let\cwbb@init_print_chunk\relax + \let\CwebNumberProgramPart\relax +\fi +%%% \endprog + + +%%% \sect If a statement is finished, a new paragraph with the basic +%%% indentation has to be started. + +%%% An optional statement break is implemented by a low penalty which +%%% will be selected if the line has to be broken. We assume that the +%%% hanging indentation of the new line is already set correctly, and +%%% have to backup two units to get the basic indentation. It might be +%%% that the line break is not chosen by \TeX{}, we compensate the +%%% backspace for this case. This compensation is discarded at the start +%%% of a new line. + +%%% \beginprog +\def\cwbb@break{% % forced break, between statements + \ifmmode\else + \endgraf % in LaTeX it isn't sure what \par is really... + \noindent + \hangindent\cwbb@indent \kern\cwbb@indent + \copy\cwbb@bakk % go back to basic indentation + \ignorespaces + \fi + } +\def\cwbb@opt_break{% % optional break between statements + \hfil \penalty\m@ne + \hfilneg \kern .5em \kern 2\CwebIndentUnit % discarded on line break + \copy\cwbb@bakk + \ignorespaces + } +\def\cwbb@big_break{% % forced break and a little extra space + \Y + \cwbb@break + } +\def\cwbb@expr_break#1{% % break with penalty #1 * 10 + \hfil \penalty#10 + \hfilneg % discarded on line break + } +%%% \endprog + + +%%% \sect When we increment the indentation, we must not forget to set +%%% the hanging indentation immediately since |\cwbb@opt_break| relies on +%%% the new value. If a continuation line is needed it will also be +%%% indented one unit more, which is ok since it should be distinguishable +%%% from the next line. +%%% % +%%% \begin{fixme} +%%% Shouldn't the hanging indentation be set anew at the end of +%%% |\cwbb@decr_indent| as well? +%%% \end{fixme} + +%%% \beginprog +\def\cwbb@incr_indent{% + \global\advance\cwbb@indent\CwebIndentUnit + \hangindent\cwbb@indent + } +\def\cwbb@decr_indent{\global\advance\cwbb@indent -\CwebIndentUnit} +\def\cwbb@backup{\copy\cwbb@bak} +\def\cwbb@noindent{% % no indentation + \hskip -\cwbb@indent \hskip 2\CwebIndentUnit + } +%%% \endprog + + + + +%%% \chap Program (C or \C++) tokens. + +%%% Since the user might want to change the (somewhat unusual) way some +%%% of the operators are typeset, we supply names for them. + +%%% \beginprog +\let\CwebAnd=\land % logical and, && +\let\CwebEquiv=\equiv % equiv sign, for == +\let\CwebGe=\ge % greater or equal +\let\CwebLe=\le % less or equal +\let\CwebNe=\ne % unequal, != +\let\CwebNull=\Lambda % NULL pointer +\let\CwebNot=\lnot % logical not, ! +\let\CwebOr=\lor % logical or, || +\let\CwebXor=\oplus % bitwise exclusive or, ^ +%%% \endprog + + +%%% \sect Some symbols have to be shifted around, to save computation time +%%% we put them in boxes. + +%%% \begin{fixme} +%%% It's not sure if the following symbols still look good in other font +%%% families than Computer Modern. The movements might need to get +%%% adapted when more experience is available. They were chosen from +%%% Plain \cweb{}, where these were explicit movements measured in +%%% points. I changed the dimension to quads, to achieve at least the +%%% support for different sizes in the Computer Modern family. +%%% \end{fixme} + +%%% \TeX{}nical note: The pointer symbol must not be declared as a math +%%% symbol (e.g., with |\DeclareMathSymbol|). Then \TeX{} would insert an +%%% italic correction behind it, according to rule~17 from appendix~G. +%%% (Please send email if you know of an easy way to prevent that +%%% addition.) So I use the symbol as an accent, but then I have to supply +%%% a nucleus for this math list. That nucleus also determines the total +%%% width of this construct. As the vector accent has a width of +%%% approximately 5\,pt in |cmmi10|, I'm going to use 0.5\,em. (That +%%% heuristic is as good as any other I can think of.) + +%%% \beginprog +%% pointer to struct component (`->'), use symbol of \vec accent +\newbox\cwbb@pointer +\setbox\cwbb@pointer=\hbox{% + \kern -.2em + \lower .3em \hbox{$\vec{\kern .5em}$}% + \kern .1em + } + +\newbox\cwbb@decr % decrement, -- +\setbox\cwbb@decr=\hbox{% + \kern .05em + \raise .1em \hbox{$\scriptstyle {-}\kern -.1em{-}$}% + \kern .05em + } +\newbox\cwbb@incr % increment, ++ +\setbox\cwbb@incr=\hbox{% + \kern .05em + \raise .1em \hbox{$\scriptstyle {+}\kern -.1em{+}$}% + \kern .05em + } +%%% \endprog + + +%%% \sect Although the following symbols are typeset like an ``ordinary +%%% \C++ programmer'' would expect them, we provide own module names +%%% nevertheless. They can now be changed as well, i.e., orthogonality is +%%% enhanced. (And we can use |\cwbb@rebind| for assigning them to their +%%% names while we switch to program state\,\dots). + +%%% Note: The comment at |\CwebMod| says ``modulo/remainder'', as this is +%%% not defined by the C standard, i.e., implementation-dependent. + +%%% \beginprog +\mathchardef\CwebAddress="2026 % `&', as binary op +\let\CwebAssign== % assignment +\let\CwebBinOr=\mid % binary or +\def\CwebComplement{{\sim}} % `~', as ordinary symbol +\def\CwebDecr{\copy\cwbb@decr} % decrement +\def\CwebIncr{\copy\cwbb@incr} % increment +\let\CwebLeftShift=\ll % left shift, << +\def\CwebMod{\mathbin{\hbox{\footnotesize\rm\%}}} % modulo/remainder, % +\def\CwebMemberRef{\mathbin{.*}} % ptr to member (on object) +\def\CwebPointer{\copy\cwbb@pointer} +\def\CwebPointerMemberRef{\mathbin{\CwebPointer*}} % ptr to member (on ptr) +\def\CwebRel{\mathrel?} % relation operator +\let\CwebRightShift=\gg % right shift, >> +\def\CwebScope{\kern.1em{::}\kern.1em} % scope resolution + +\def\CwebThis{\CwebRes{this}} % reserved identifier `this' +%%% \endprog + + +%%% \sect The special identifier |\TeX| remains. In math mode it shall be +%%% the identifier, in other modes the usual logo. We use the definition +%%% supplied by DEK (or \textsc{Silvio Levy}?)\ from Plain \cweb{}. + +%%% \beginprog +\def\TeX{% + {% + \ifmmode\it\fi + \mbox{T\kern-.1667em\lower.424ex\hbox{E}\hskip-.125emX}% + }} +%%% \endprog + + +%%% \sect Some tokens don't have constant names, the name is supplied as +%%% the argument. + +%%% Identifiers are typeset in italics, reserved words and type names in +%%% boldface, and strings in typewriter. For an underscore in the bold +%%% words we use a line that's 50\,\% thicker as the usual line thickness. +%%% -- But what is the usual line thickness. As Knuth uses 0.4\,pt for a +%%% 10\,pt Computer Modern font, we'll use 0.06\,em for a CM font in an +%%% arbitrary size. If that line thickness is still OK for other fonts is +%%% doubtful, as it should fit to the stem width. (CM is a rather light +%%% font, after all.) But since there is no font dimension that gives a +%%% hint to an appropriate line thickness, it's our best try. + +%%% \beginprog +\def\CwebCombinedOp#1{\mathrel{\let\K==#1}} % e.g., += operator +\def\CwebId#1{\hbox{\it#1\/\kern.05em}} % identifier, more than one char +\def\CwebIdLetter#1{\hbox{$#1$}} % identifier, one letter +\def\CwebRes#1{% % reserverd words and type names + \hbox{\bf + \def\_{\kern.04em\vbox{\hrule width.3em height.06em}\kern.08em}% + #1\/\kern .05em + }% + } +%%% \endprog + + +%%% \sect In Plain \cweb{} strings are typeset in the font |cmtex10|, +%%% which is a typewriter font with extended ASCII characters. This font +%%% does not have the usual accents and can therefore not used for +%%% typesetting national characters. (Very often they are input in some +%%% 8-bit encoding, the respective character code is made active and is +%%% substituted by a cseq which expands to the correct glyph. Of course, +%%% there are better ways, but that's the reality we have to cope with.) +%%% Instead of this special font we use the standard typewriter font. +%%% This has the further advantage that |cmtex10| may not be introduced +%%% to NFSS\@. + +%%% \beginprog +\def\CwebString{% + \hbox \bgroup + \tt + \cwbb@string_setup + \cwbb@string + } +\def\cwbb@string#1{% + #1\kern .05em + \egroup + } +%%% \endprog + + +%%% \sect Within strings certain cseqs have a special meaning; this is +%%% introduced by |\cwbb@string_setup|. The cseqs within strings are +%%% mostly special \TeX{} characters that are to be typeset by cseqs with +%%% the same name. + +%%% But a problem remains: active characters. They will still expand, and +%%% will mess up the string visualization. This is a particular problem +%%% with |german.sty| where the double quote is active. (Of course, that's +%%% a problem -- I'm German. :--) When one typesets strings, a double +%%% quote shall be typeset as double quotes, and must not expand to the +%%% special meaning. Remember that double quotes happen to appear quite +%%% often in strings. As the string argument is already tokenized, one has +%%% to redefine the binding of $(\textit{\textup{symbol}}\ \textbf{.}\ +%%% |#\"|)$. + +%%% \begin{fixme} +%%% Perhaps one might use a loop over all characters except the braces, +%%% and set their catcode to other. That would give us enough security. + +%%% For now, we handle only the double quote. +%%% \end{fixme} + +%%% Every once in a while we have discretionary breaks in a string, +%%% denoted by |\CwebStringBreak|. This break is shown with the C +%%% convention of escaped newlines. + +%%% \beginprog +\def\cwbb@string_setup{% + \chardef\ =`\ % % <-- two spaces ! + \chardef\&=`\& + \chardef\\=`\\ + \chardef\^=`\^ + \chardef\_=`\_ + \chardef\{=`\{ + \chardef\}=`\} + \chardef\~=`\~ + \catcode`\"=\CatOther + } + +\def\CwebStringBreak{\discretionary{\hbox{\tt\char`\\}}{}{}} +%%% \endprog + + +%%% \sect Numbers are typeset in different ways. We use the definition of +%%% Plain \cweb{}. +%%% % +%%% \begin{fixme} +%%% Should add a specification of the possible input and an explanation +%%% of the macros below. In particular, that the closing brace after +%%% |\aftergroup| is used much later is probably not grokked by most +%%% \TeX{} programmers. +%%% \end{fixme} + +%%% \beginprog +\def\cwbb@oct{\hbox{$^\circ$\kern-.1em\it\aftergroup\?\aftergroup}} +\def\cwbb@hex{\hbox{$^{\scriptscriptstyle\#}$\tt\aftergroup}} + +\def\CwebNumber#1{% % octal, hex, or decimal constant + \hbox{% + $% + \def\?{\kern.2em}% + \def\$##1{\egroup\sb{\,\rm##1}\bgroup}% suffix to constant + \def\_{\cdot 10^{\aftergroup}}% power of ten (via dirty trick) + \let\~\cwbb@oct \let\^\cwbb@hex + {#1}% + $}% + } +%%% \endprog + + +%%% \sect Comments are typeset in \TeX{} state. We add a hook, the user +%%% shall be able to change the layout (e.g., he might want another font). +%%% % +%%% \begin{fixme} +%%% Currently \C++ comments are typeset like C comments. This is +%%% horrible in usual circumstances, i.e., when complete blocks of text +%%% are prefixed with |//|. We should simply catenate all these text and +%%% typeset it as one paragraph, each line prefixed by |//|. But then we +%%% have to implement an |\everyline| first, and since that's not so +%%% easy we postpone it\,\dots +%%% \end{fixme} +%%% % +%%% In front of a C comment there is an optional stmt break, with 2\,quad +%%% in front if the line is not broken and 1.5\,quad if the line is broken. + +%%% \beginprog +\def\CwebComment#1{% + \5% % 0.5em will be discarded on line break + \hskip 1.5em + $/\ast\,$% + {\cwbb@tex + \CwebCommentHook + #1% + }% + $\,\ast/$% + } +\let\CwebCommentHook\relax +\let\CwebCxxComment\CwebComment +%%% \endprog + + + + + +%%% \chap \cweb{} tokens. + +%%% We distinguish three categories of \cweb{} tokens: (1) Those which +%%% output constant text, (2) those which have attributes to be displayed +%%% in a special way, and (3) those which start a new structure element, +%%% namely |@d| and~|@f|. Let's consider them in this order. + + +%%% \sect \cweb{} tokens which expand in a constant string are the +%%% identifier catenation operator~(`|@&|') and the macro placement +%%% directive~(`|@h|'). + +%%% \beginprog +\def\CwebIdCat{\CwebString{@\&}} +\def\CwebMacrosHere{% + \begingroup + \def\CwebRefNumber##1{}% + \CwebRefName :Preprocessor definitions\X + \endgroup + } +%%% \endprog + + +%%% \sect Verbatim program strings, i.e., strings passed verbatim by +%%% \ctangle{}~(`|@=|') are typeset like normal strings, but within a box. +%%% We use 2\,pt as the separating distance, this is set locally. + +%%% \beginprog +\def\CwebVerbString#1{{\fboxsep\tw@\p@ \fbox{\CwebString{#1}}}} +%%% \endprog + + +%%% \sect The refinement names are typeset in angles, this has a long +%%% tradition. We burry the typesetting of the chunk number (which is +%%% the first parameter) in a macro call; the user may change this to +%%% achieve special effects. +%%% % +%%% \begin{fixme} +%%% One could think about handling special values of the chunk numbers +%%% differently. E.g., an empty argument is not typeset at all, a~0 +%%% triggers a marginal note about a missing definition, etc. +%%% \end{fixme} + +%%% A refinement name may be typeset both in math and horizontal mode. +%%% The name itself is typeset in horizontal mode, of course; for the +%%% angles we need math mode. Therefore we assert at the start of the +%%% macro that we're not in math mode any more. At the end we switch back +%%% to math mode if we've started in it. This conditional switch from and +%%% back to math mode is done by |\cwbb@toggle_text|. + +%%% \TeX{}nical note: If we're in math mode |\cwbb@toggle_text| must be +%%% defined globally, as it will turn off math mode and the definition +%%% would be un-made then. The second invocation of |\cwbb@toggle_text| +%%% would be undefined then. + +%%% A refinement may also consist of the file name the expansion of this +%%% refinement shall be written to. +%%% % +%%% \label{sec:refname-dot} +%%% % +%%% This file name is tagged with |\.|, it shall be typeset like a string. +%%% But the user shall be able to use the dot accent in the refinement +%%% name as well. We check if the text consists solely of the tag and its +%%% argument; in this case we substitute |\.| with |\CwebString|. +%%% Otherwise we leave it as it is. Then a refinement name may not +%%% consist of a single dot-accented expression---well, that's highly +%%% unlikely. (Nevertheless I'll document it in the user's manual\,\dots) + +%%% \begin{fixme} +%%% One should be able to use |\EnsureMath| here. But the refinement +%%% name must not be set in math mode and must not be set in an hbox; +%%% the latter would prevent line breaks. +%%% \end{fixme} +%%% Enrique Mel\'endez (\texttt{ema@csn.es}) added the macro |\cweb@num@lnk| +%%% include hyperlinks into the cross references. + +%%% \beginprog +\def\CwebRefName#1:#2\X{% + \ifmmode \gdef\cwbb@toggle_text{\null$\null}% + \else \let\cwbb@toggle_text\relax + \fi + \cwbb@toggle_text + $\langle\,${\cwbb@tex \cwbb@check_dot{#2}\CwebRefNumber{#1}}$\,\rangle$% + %} + \cwbb@toggle_text + } +\def\CwebRefNumber#1{% + {\reset@font \footnotesize \kern .5em\cweb@num@lnk#1, |}% + } +%%% \endprog + +%%% \sect This is the implementation of |\cweb@num@lnk|. It essentially +%%% processes the incoming list, takink care of whether one element of the +%%% list is processed with the macro |\[|. It borrows the phylosophy from +%%% |\check_dot| below in that we inhibit the behaviour of |\[| for a while, +%%% so that we can test its presence. Then we proeceed differently when it is +%%% present. I (\texttt{ema@csn.es}) have not a lot of experience in list +%%% processing in \LaTeX. I have done my best, using only two macros, the +%%% already named |\def\cweb@num@lnk| and a wrapper for it, +%%% |\def\cweb@@num@lnk|. I need the strange termination code (\texttt{|}). + +%%% \beginprog +\newif\if@lbracket@ +\def\hyper@i\[#1]{\hyperlink{_hyperchunk_#1}{\[#1]}} +\def\cweb@num@lnk #1, #2|{% + \begingroup + \def\[##1]{}% + \expandafter\def\expandafter\next\expandafter{#1}% + \ifx\next\empty + \global\@lbracket@true + \else + \global\@lbracket@false + \fi + \endgroup + \if@lbracket@% + \hyper@i#1% + \else + \hyperlink{_hyperchunk_#1}{#1}% + \fi + \@lbracket@false + \edef\next{#2}% + \ifx\next\empty + \else + { } % Yep, a space by itself. + \cweb@@num@lnk #2|% + \fi +} +\def\cweb@@num@lnk #1, |{\cweb@num@lnk#1, |} +%%% \endprog + + +%%% \sect The next macro, |\cwbb@check_dot| is a hassle to implement. We +%%% must check if it's argument consists solely of a `|\.|'~tag, together +%%% with the argument to this tag. Then the `|\.|'-argument shall be +%%% typeset like a string, |\.| itself must be ignored. + +%%% The check for |\.| must not evaluate the parameter. Especially |\PB| +%%% must not be evaluated within, it would lead to havoc with the +%%% redefinition of all bindings, etc. (At least that's the empirical +%%% result---it happened; although I don't know where the problems are. +%%% Anyhow, it wasn't in the specs of the rebinding process.) All other +%%% cseqs which shouldn't be used in moving arguments may cause problems +%%% here, too. Note that |\protect| is no solution here, the user often is +%%% not aware of the presence of \cweave{}-generated tags. As an example, +%%% consider the refinement \verb"@< local variables of |foo| @>|" which +%%% will lead to a call with the argument `|local variables of \PB{\\{foo}}|'. +%%% |\\| must not be evaluated here. + +%%% I use an approach where I hope that it will work---but to be honest, +%%% I'm not sure. I want to define a macro |\next| which shall have an +%%% empty expansion iff |#1| was a `|\.|'~tag with its argument. Empty +%%% refinement names are not allowed so we can assume that |#1| consists +%%% of at least one token. I evaluate the first token of |#1| before the +%%% |\def| is done. With an appropriate binding a |\.| will disappear, +%%% perhaps leaving an empty token list. I also take care that |\PB| is +%%% not evaluated then, by temporary rebinding it to |\relax|. Thereby I +%%% have taken care for all cseqs \cweave{} might have introduced at the +%%% very front of |#1|. Other cseqs are user-tags. If they cause +%%% problems, the user might circumstance them by adding |\protect|. + +%%% \beginprog +\def\cwbb@check_dot#1{% + \begingroup + \let\.\@gobble + \let\PB\relax + \expandafter\def \expandafter\next \expandafter{#1}% + \ifx \next\empty + \gdef\next##1{\CwebString}% + \else + \global\let\next\relax + \fi + \endgroup + \next #1% + } +%%% \endprog + + +%%% \sect \cweb{} macro definitions (done by~|@d|) and format directives are +%%% basically program text. When they are started we are already in +%%% program state, i.e., |\B| has appeared in front of it. But since we have +%%% an introductionary identifier (either |#define| or |format|) to set at +%%% the very front we increase the indentation by three units. + +%%% The output of format directives may be suppressed. Then we have to +%%% gather both identifiers that will appear after |\F|. Both of them +%%% consist of one group-token (a cseq and the identifier name), after +%%% each identifier one other token separates them. I.e., we have to +%%% gobble six group-tokens. As the very last token is |\par| if a format +%%% directive follows directly on another one, the definition must be +%%% long. + +%%% \TeX{}nical note: |\cwbb@format| must expand to |\CwebFormat|, not to +%%% its expansion. Otherwise a redefinition of |\CwebFormat| in a package +%%% would not be used. + +%%% \beginprog +\def\CwebDefine{\cwbb@macro{\#define}} +\def\CwebFormat{\cwbb@macro{format}} +\if@cweb@suppress@format@ + \long\def\cwbb@format#1#2#3#4#5#6{} +\else + \def\cwbb@format{\CwebFormat} +\fi + +\def\cwbb@macro#1{% + \global\advance\cwbb@indent \tw@\CwebIndentUnit + \cwbb@incr_indent + \CwebRes{#1 }% % <-- blank! + } +%%% \endprog + + + + +%%% \chap Refinement cross references and changes. + +%%% At the end of chunks with refinements, \cweave{} may output cross +%%% reference information: In which chunks additional definitions for +%%% this refinement are found, where this refinement is used, and where it +%%% is cited. This cross reference information is always introduced by a +%%% tag followed by a non-empty list of chunk numbers. Different tags +%%% are used for lists with only one element and for lists with more than +%%% one element, this way the introductionary text may be adapted. + +%%% Within a list of $n$~chunk numbers the first $n-1$~numbers are +%%% separated by commas with one following blank. The last two numbers +%%% are separated by |\ET| if~$n=2$, and by |\ETs| if~$n>2$. If a chunk +%%% is changed by the changefile, a changeflag~(`|\*|') is appended to +%%% its number. The list is eventually terminated by a full stop. + + +%%% \sect We separate the cross reference information by a smallskip from +%%% the refinement or from a previous cross reference information. The +%%% information itself is typeset in a smaller font, as it is auxilliary, +%%% inserted stuff. The number list has a hanging indentation of +%%% |\CwebNumberListHangindent|. But beware: This isn't a dimension +%%% register, it's a macro. This way one can use ems as dimensions. + +%%% The actual size change is represented by a macro. We will redefine it +%%% when we need an other size, e.g., in the lists at the end of the +%%% document. + +%%% We must assert that we're in CR state while we set a cross reference. + +%%% The first parameter of a cross reference information unit is the +%%% introductionary text, the second is the number list. The parameters +%%% must be evaluated in a group---local parameter changes therein must +%%% not influence the environment. + +%%% Enrique Mel\'endez (\texttt{ema@csn.es}) included some code to handle +%%% putting in hyperlinks. In the case of only one item, a single +%%% |\hyperlink| has been included. The processing of several +%%% cross-references is somewhat more difficult. This amounts to inhibiting +%%% the effect of |\ET| and |\ETs| so that the list can be processed +%%% properly, and calling the macro |\cweb@cr@lnk| to process it. The +%%% appropriate end-list conjunction will be added there. + +%%% \beginprog +\def\CwebNumberListHangindent{2em} +\let\CwebCRSize\footnotesize +\def\CwebCrossRef#1#2.{% + \par\smallskip + \cwbb@CR + \begingroup + \reset@font \CwebCRSize + \noindent \hangindent\CwebNumberListHangindent\relax + #1~\hyperlink{_hypersect_#2}{#2}.\par + %#1~\hyperlink{_hyperchunk_#2}{#2}.\par + \endgroup + } +\def\CwebCrossRefs#1#2.{% + \par\smallskip + \cwbb@CR + \begingroup + \reset@font \CwebCRSize + \noindent \hangindent\CwebNumberListHangindent\relax + \let\save@et\ET% + \let\save@ets\ETs + \def\ET{, }% + \let\ETs\ET% + \edef\@cr@lst{#2}% + \let\LastList@Conjunction\save@et + #1~\expandafter\cweb@cr@lnk\@cr@lst, ]\par + \endgroup + } +%%% \endprog + +%%% \sect The cross references are added here for the case of a list of them. +%%% We test whether we are at the last point of the list, and then add the +%%% adequate conjunction, which is updated in the macro |\cweb@@cr@lnk|, which +%%% takes care of the case of there being more than two elements. The +%%% processing of the list goes along the same lines as |\cweb@num@lnk|. + +%%% \beginprog +\def\cweb@cr@lnk #1, #2, #3]{% + \hyperlink{_hyperchunk_#1}{#1}% + \edef\next{#3}% + \ifx\next\empty + \LastList@Conjunction\hyperlink{_hyperchunk_#2}{#2}% + \else + , \hyperlink{_hyperchunk_#2}{#2}% + \cweb@@cr@lnk#3]% + \fi +} +\def\cweb@@cr@lnk #1, #2]{% + \let\LastList@Conjunction\save@ets + \edef\next{#2}% + \ifx\next\empty + \LastList@Conjunction\hyperlink{_hyperchunk_#1}{#1}% + \else + , \cweb@cr@lnk#1, #2]% + \fi +} +%%% \endprog + + +%%% \sect Well, let's define all introducing tags, which in fact start the +%%% cross reference information unit. The number list is gathered by +%%% |\CwebCrossRef|. + +%%% \beginprog +\def\CwebCRAlso{\CwebCrossRef{See also chunk}} +\def\CwebCRsAlso{\CwebCrossRefs{See also chunks}} + +\def\CwebCRCite{\CwebCrossRef{This code is cited in chunk}} +\def\CwebCRsCite{\CwebCrossRefs{This code is cited in chunks}} + +\def\CwebCRUse{\CwebCrossRef{This code is used in chunk}} +\def\CwebCRsUse{\CwebCrossRefs{This code is used in chunks}} + +\def\CwebCREt{ and~} +\def\CwebCRsEt{, and~} +%%% \endprog + + + + +%%% \chap Bells and whistles. + +%%% \begin{fixme} +%%% Just copied from Plain \cweb{}. It doesn't work +%%% anyhow---|\char"|\<xy> usually doesn't typeset the correct +%%% character. That's because this character is most probably an active +%%% character; at least that's typical for the way \TeX{} systems are +%%% used in Europe. I have to think about the implementation. +%%% \end{fixme} + +%%% \beginprog +\def\ATL{\par\noindent\bgroup\catcode`\_=12 \postATL} % print @l in limbo +\def\postATL#1 #2 {\bf letter \\{\uppercase{\char"#1}} + tangles as \tentex "#2"\egroup\par} +\def\noATL#1 #2 {} +\def\noatl{\let\ATL=\noATL} % suppress output from @l +%%% \endprog + + + +%%% \chap The end. + +%%% Well, after all we're finished with this module + +%%% \beginprog +\endinput +%%% \endprog + + +%%% +%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%% \vskip \PltxPreSectSkip + +%%% \rcsLogIntro{After the actual revision log of this module, we give an +%%% extract of log messages of the \cls{cweb} class. This module was +%%% extracted from revision~2.8 of that class, we present to you the +%%% log entries that concern the code of the new module.} + +%%% \begin{rcslog} +%%% $StyleLog: cwebbase.doc,v $ +%%% \Revision 1.4 1995/11/07 17:55:19 schrod +%%% \LaTeX{} \cweb{} should work at least with the last two \LaTeX{} +%%% versions; make it work with the previous-to-last one, version +%%% \mbox{$\langle$1994/12/01$\rangle$}. For that, one has to install the +%%% \mbox{$\langle$1995/06/01$\rangle$} (non-outer) definition of +%%% |\newif|, and |\hb@xt@| must not be used.\\ +%%% Problem reported by Laurent Desnogues +%%% \path|<laurent.desnogues@aiguemarine.unice.fr>| and somebody else (XXX +%%% -- add name). + +%%% \Revision 1.3 1995/11/07 14:13:12 schrod +%%% Reset section numbers when higher-level section begins.\\ +%%% Error reported by Bronne Louis \path|<bronne@montefiore.ulg.ac.be>|. + +%%% \Revision 1.2 1995/11/06 10:58:47 schrod +%%% Support active double quotes in strings. That happens when +%%% |german.sty| is used. Problems with other active characters may still +%%% appear. + +%%% \Revision 1.1 1995/09/12 23:02:22 schrod +%%% Moved all code that does the actual typesetting of \cweave{} tags and +%%% is therefore also needed for a |cweb| environment. It's now an own +%%% module named \pkg{cwebbase}. + +%%% Chunk markers and chunk marginal numbers don't hang below the +%%% baseline any more. + + +%%% \item[] \noindent\hrulefill\break +%%% \textbf{Extract of the revision log for |cweb.doc|:} + +%%% \vskip 2ex + +%%% \Revision 2.5 1995/08/29 02:07:26 schrod +%%% Discard dependencies on 10\,pt fonts. + +%%% Support suppression of format directives. + +%%% \Revision 2.4 1995/08/27 19:31:43 schrod +%%% Make configuration of change flag easier. + +%%% Put section title of changed chunks list in marks, and tell the user +%%% that it got typeset. + +%%% \Revision 2.3 1995/08/27 17:24:46 schrod +%%% Make usage of baseclass with chapters work. + +%%% \Revision 2.2 1995/08/27 13:26:22 schrod +%%% Add possibility to suppress change hints. + +%%% \Revision 2.1 1995/08/25 19:11:18 schrod +%%% Hierarchic structures are supported now, in addition to the flat +%%% structure of the beta-test version. One can choose with an option. For +%%% that step, the terminology was cleaned up, too: Chunks are not named +%%% sections any more. (That change involved reimplementation of almost +%%% all the structure and toc stuff.) + +%%% The chunk number supplied by \cweave{} is used now, not some computed +%%% number. Change flags are printed, too. + +%%% One can suppress output of unchanged sections. + +%%% \Revision 1.12 1993/08/10 14:15:43 schrod +%%% New page on main section only if group level $<$ |\cwebSecNoEject|. +%%% Default for the latter is 3. + +%%% \Revision 1.11 1993/08/10 11:21:07 schrod +%%% Reference to section number does not render a period after the +%%% number any more. + +%%% \Revision 1.10 1993/08/09 20:08:20 schrod +%%% |\cweb@cweave_bindings| is now a no-op if \cweave{} bindings are in +%%% effect already.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% \Revision 1.9 1993/08/09 18:05:28 schrod +%%% Left shift operator wasn't defined correctly.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% \Revision 1.6 1993/06/15 08:49:23 schrod +%%% |\cweb@check_dot| must not evaluate its argument in an |\edef|, this +%%% causes problems if a |\PB| is within. Now I try hard not to evaluate any +%%% tokens outside of my control. + +%%% Can use |\@defpar| for an empty line in |\cweb@has_entries|, don't +%%% need an own macro. + +%%% \Revision 1.4 1993/06/14 15:54:18 schrod +%%% Add FSA diagram about processing states. CR state is also switched +%%% to from \TeX{} state (that happens with |\ch| at the document end). + +%%% \Revision 1.3 1993/05/13 17:51:21 schrod +%%% Refinements may also be filenames (`|@(|'). Then the complete name +%%% consists of a |\.| macro call, which is handled now.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% Made the detection of `|@.|' index entries more robust. + +%%% \Revision 1.2 1993/05/12 18:28:59 schrod +%%% Adapted to recent changes of \cweave{} (of April 93): + +%%% Main sections have a group level, represented in the table of +%%% contents. This changed the complete implementation of section tags. + +%%% New C token cseqs: |\Z| and |\MRL|, implemented as |\CwebLe| and +%%% |\CwebCombinedOp|. + +%%% \Revision 1.1 1993/04/09 15:00:37 schrod +%%% Initial revision + +%%% \end{rcslog} + + + +%%% \end{document} + + +%%% +%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%% Local Variables: +%%% mode: LaTeX +%%% TeX-brace-indent-level: 4 +%%% indent-tabs-mode: t +%%% TeX-auto-untabify: nil +%%% TeX-auto-regexp-list: LaTeX-auto-regexp-list +%%% compile-command: "make cwebbase.tex" +%%% End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/cweb-hy.cls b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/cweb-hy.cls new file mode 100644 index 00000000000..e1ca54752ae --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/cweb-hy.cls @@ -0,0 +1,1538 @@ +% $StyleId: cweb.doc,v 3.6 1995/11/30 15:44:53 schrod Exp $ +%---------------------------------------------------------------------- +% Written by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>. +% Copyright conditions see below (GPL). +% Modified by Enrique Meléndez <ema@csn.es> to support hyperlinks and to allow +% it to be included in other classes documnts. + +% +% LaTeX class cweb +% support for LaTeX markup in CWEB sources +% +% [LaTeX in MAKEPROG] +% (history at end) + +% If you have received this style file without the user manual (in the +% file cweb-user.dvi or the respective LaTeX file), it's incomplete and +% near to useless. If it was given to you as something that you shall +% use as an author -- complain bitterly to your provider. You need the +% documentation and you have a right on it! (Below you can find info +% where to get the reference version.) + + + + +%%%% +%%%% +%%%% These TeX macros were documented with the documentation system +%%%% MAKEPROG and automatically converted to the current form. +%%%% If you have MAKEPROG available you may transform it back to +%%%% the original input: Remove every occurence of three percents +%%%% and one optional blank from the beginning of a line and remove +%%%% every line which starts with four percents. The following lex +%%%% program will do this: +%%%% +%%%% %% +%%%% +%%%% ^%%%\ ? ; +%%%% ^%%%%.*\n ; +%%%% +%%%% If you just want to print the documentation you may fetch +%%%% the archive print-makeprog.tar.Z from ftp.th-darmstadt.de (directory +%%%% pub/tex/latex). It contains *all* used styles -- but beware, they +%%%% may not be in a documented form... +%%%% +%%%% +%%% \documentclass{progltx} + +%%% \usepackage{cweb-doc} % document-specific markup +%%% \usepackage{fullpage} + + +%%% \RCS $StyleRevision: 3.6 $ +%%% \RCS $StyleDate: 1995/11/30 15:44:53 $ + + +%%% \begin{document} + + +%%% \title{The \texttt{cweb} Class\\ +%%% {\large (Implementation)}% +%%% } +%%% \author{% % LaTeX does not discard unnecessary glue... +%%% Joachim Schrod% +%%% \thanks{% +%%% \protect\raggedright +%%% TU~Darmstadt, Computer Science Department, WG Systems Programming, +%%% Alexanderstr.~10, D-64283~Darmstadt, Germany. +%%% Email: \texttt{jschrod@acm.org}% +%%% }% +%%% } +%%% \date{% +%%% Revision \RCSStyleRevision\\ +%%% (as of \RCSStyleDate)% +%%% } + +%%% \maketitle + + +%%% % doesn't work with progltx yet +%%% %\tableofcontents + + + +%%% % ------------------------------------------------------------ +%%% % +%%% % subdocument: The user interface of cweb.cls +%%% % + +%%% \input{cweb-user} + +%%% % +%%% % ------------------------------------------------------------ +%%% % +%%% % subdocument: The internal interface +%%% % + +%%% \input{cweb-conf} + +%%% % +%%% % ------------------------------------------------------------ + + + + +%%% \chap Implementation. + +%%% This implementation must typeset complete files output by \cweave{}. +%%% Large parts of this task are available from the module \pkg{cwebbase}. +%%% It remains mainly to implement document-level markup and front and +%%% back matter (table of contents, index, etc.) In particular, the back +%%% matter material is not trivial; its tags are behind |\end{document}|, +%%% we have to read carefully behind the end of our \cweb{} document to +%%% detect if we have to typeset them at all. + + +%%% \sect This module reserves the namespace |cweb|. + +%%% \beginprog +\ifx \cweb@loaded\undefined + \def\cweb@loaded{$StyleRevision: 3.6 $} +\else + \PackageWarningNoLine{cweb}% + {Some other package already uses namespace `cweb'} +\fi +%%% \endprog + + +%%% \sect Let's identify this class. + +%%% \noindent The code below is explained in the implementation +%%% documentation of the \pkg{rcs} package. + +%%% \beginprog +\begingroup + \def\RCSClass#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesClass{#1}[\date\space\id\space #2]% + } + + \RCSClass{cweb-inc}{LaTeX markup for CWEB sources} + $StyleDate: 1995/11/30 15:44:53 $: 9999/00/00 \endRCS + $StyleRevision: 3.6 $: 0.0 \endRCS +\endgroup +%%% \endprog + + +%%% \sect This module is from a supported bundle. Send bug reports, +%%% comments and repairs. + +%%% The reference version may be retrieved via anonymous ftp from +%%% |ftp.th-darmstadt.de| [130.83.47.112], directory +%%% |pub/programming/literate-programming/c.c++/|. It's +%%% placed there as a gzipped tar file. (The information on the IP~number +%%% is dated August~29,~1995. +%%% It might have changed, although this is very unlikely. Use +%%% your friendly nameserver.) + + +%%% \sect This is freely distributable 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 software is distributed in the hope that it will be useful, but +%%% \textbf{without any warranty}; without even the implied warranty of +%%% \textbf{merchantability} or \textbf{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 in +%%% the file |License| along with this package; if not, write to the Free +%%% Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA. + + +%%% \sect Before we start we declare some shorthands for category codes. +%%% By declaring the underscore~`(|_|)' as letter we can use it in our +%%% macros. (I agree with \textsc{D.~Knuth} that +%%% |\identifier_several_words_long| is more readable than +%%% |\IdentifierSeveralWordsLong| and in every case better than |\p@@@s|.) + +%%% As this is a \LaTeX{} style file the at sign is a letter anyhow; so +%%% we can use the ``private'' \LaTeX{} macros; and with the underscore we +%%% can make our own macros more readable. But as we have to restore this +%%% category code at the end of this macro file we store its former value +%%% in the control sequence |\CatUsCode|. This method is better than to +%%% use a group because not all macros have to be defined global this way. + +%%% Since somebody might use more styles from me, this cseqs might be +%%% defined already. + +%%% \beginprog +\ifx \CatEscape\undefined + \chardef\CatEscape=0 + \chardef\CatOpen=1 + \chardef\CatClose=2 + \chardef\CatIgnore=9 + \chardef\CatLetter=11 + \chardef\CatOther=12 + \chardef\CatActive=13 % is defined in Plain already + + \chardef\CatUsCode=\catcode`\_ +\fi + +\catcode`\_=\CatLetter % top level macro file +%%% \endprog + + + +%%% See if we are a class or a package. If |cweb| is a class, |section| is +%%% still undefined, as it will be defined when the base package is loaded +%%% later on. This allows us to define |cweb@cls| to be true and act +%%% under this condition.[ema@csn.es] +%%% \beginprog + +\ifx\section\undefined + \def\cweb@cls{0} +\else + \def\cweb@cls{1} +\fi +%%% \endprog + + +%%% \sect Problems over problems with different \LaTeX{} versions. I have +%%% decided that I will take the same stand as the \LaTeX{} team: I will +%%% only support the last two official \LaTeX{} versions, folks who run +%%% older software might need to upgrade. + +%%% The implementation will use `star'-forms of \LaTeX{}'s command +%%% definition macros. They were introduced with \LaTeX{} +%%% \mbox{$\langle$1994/12/01$\rangle$}. + +%%% Currently (as of 07 Nov 95), 1995/06/01 is the most recent version. +%%% I want to use a features introduced with that version: |\newif| is not +%%% outer any more. So I check here for the version and supply the new +%%% definition if necessary. + +%%% \beginprog +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +\@ifl@t@r \fmtversion{1995/06/01}{}% else + { + \@namedef{newif}#1{% + \count@\escapechar \escapechar\m@ne + \let#1\iffalse + \@if#1\iftrue + \@if#1\iffalse + \escapechar\count@ + } + \def\@if#1#2{% + \expandafter\def + \csname \expandafter\@gobbletwo\string#1% + \expandafter\@gobbletwo\string#2\endcsname {% + \let#1#2% + }% + } + } +%%% \endprog + + +%%% \chap Options. + +%%% Our options are of the ``keyword-value'' category. We realize them by +%%% the \pkg{keyvald} package, an enhancement of the \pkg{keyval} package +%%% from the Graphics bundle that supports defaulting for unknown keys. + +%%% \begin{fixme} +%%% Most of the code below should be extracted and moved to a +%%% \pkg{keyvalx} package (or a new version of \pkg{keyval}). In +%%% particular, support for package/class option processing, enumeration +%%% values, and set values for keyword options. +%%% \end{fixme} + +%%% |\ProcessKeyValOptions| may be used instead of |\ProcessOptions|, it +%%% takes the keyval set identifier as argument. At the end it evaluates +%%% and resets a hook. That hook may be used at option definition to +%%% define further dependencies. (E.g., enabling that option implies +%%% enabling an other option, too.) +%%% % +%%% \begin{fixme} +%%% Like |\ProcessOptions|, I define |\@curroptions|, since I don't know +%%% if that's needed later. The only place where it could been needed is +%%% in the check for unprocessed options. +%%% \end{fixme} + +%%% \beginprog +\RequirePackage{keyvald} + +\let\ProcessKeyValOptionsHook\empty +\providecommand*\ProcessKeyValOptions[1]{% + \edef\@curroptions{\@ptionlist{\@currname.\@currext}}% + \edef\next{\noexpand\setkeys{#1}{\@curroptions}}% + \next + \ProcessKeyValOptionsHook + \let\ProcessKeyValOptionsHook\empty + \AtEndOfPackage{\let\@unprocessedoptions\relax} + } +%%% \endprog + + +%%% \sect The enumeration option |structure| selects hierarchic~(0) or +%%% flat~(1) structure. The predefined value is `hierarchic', there is no +%%% default. The option value is bound to |\cweb@structure|. +%%% +%%% I make this behaviour conditional on whether |cweb| is a class or a +%%% package. [ema@csn.es] + +%%% \beginprog +\ifcase\cweb@cls +%%% \endprog + +%%% \beginprog +%% \define@key@enum{cweb}{structure}{hierarchic,flat}[hierarchic] +\@namedef{KV@cweb@structure@enum:hierarchic}{0 } % <-- space! +\@namedef{KV@cweb@structure@enum:flat}{1 } % <-- space! +\define@key{cweb}{structure}{% + \expandafter\let \expandafter\@tempa + \csname KV@cweb@structure@enum:#1\endcsname % \relax if undefined + \ifx \@tempa\relax + \PackageError{cweb}% + {% + Invalid value `#1' for option structure% + }{% +Possible valid values are `hierarchic' and `flat'.\MessageBreak +The predefined value is `hierarchic'.\MessageBreak +There's no default value, you have to specify one.% + }% + \else + \let\cweb@structure\@tempa + \fi + } +\setkeys{cweb}{structure=hierarchic} +%%% \endprog + +%%% Since usually this will be inserted in a `normal' LaTeX document, I +%%% stick to the hierarchic structure.[ema@csn.es] +%%% \beginprog +\or +\def\cweb@structure{0} +\fi +%%% \endprog + + +%%% \sect With the set option |suppress| one can select suppression of +%%% different document parts: |changehints| suppresses output of hints +%%% that a changefile was involved, |unchanged| output of unchanged +%%% chunks, |index| and |reflist| output of index and reference list, and +%%% |format| output of `|@f|' directives. + +%%% The predefined value is no suppression. There is no default value. +%%% % +%%% \begin{fixme} +%%% Shouldn't I supply a default value? `|{index,reflist}|'? +%%% \end{fixme} + +%%% Set options are represented by flags named +%%% |@cweb@|\<option>|@|\<value>|@|. + +%%% This options also receive a predetermined value for the `package' case +%%% [ema@csn.es] + + +%%% \beginprog +%% \define@key@set{cweb}{suppress}{changehints,unchanged,index,reflist,format} +\@for \@tempa :=changehints,unchanged,index,reflist,format\do {% + \expandafter\newif \csname if@cweb@suppress@\@tempa @\endcsname + \csname @cweb@suppress@\@tempa @false\endcsname + }% +%%% \endprog +%%% \beginprog +\ifcase \cweb@cls +%%% \endprog +%%% \beginprog +\define@key{cweb}{suppress}{% + \@for \@tempa :=#1\do {% + \expandafter\let \expandafter\@tempb + \csname @cweb@suppress@\@tempa @true\endcsname + %% \relax if undefined + \ifx \@tempb\relax + \PackageError{cweb}% + {% + Invalid value `#1' for set option suppress% + }{% +Possible valid values are `changehints', `unchanged',\MessageBreak +or a comma-separated list of these words enclosed in braces.\MessageBreak +Specified values are turned on, you can't turn them off.\MessageBreak +No value is on initially.\MessageBreak +There's no default value, you have to specify one.% + }% + \else + \@tempb + \fi + }% + } +\g@addto@macro\ProcessKeyValOptionsHook{% + \if@cweb@suppress@unchanged@ + \@cweb@suppress@changehints@true + \fi + } +%%% \endprog + +%%% For the package case, I select to suppress the Index, the List of +%%% Refinements and the change hints. [ema@csn.es] +%%% \beginprog, + \or + \@for \@tempa :=changehints,index,reflist\do {% + \csname @cweb@suppress@\@tempa @true\endcsname + }% + \@for \@tempa :=unchanged,format\do {% + \csname @cweb@suppress@\@tempa @false\endcsname + }% + \fi +%%% \endprog + + +%%% \sect The base document class may be specified by the option +%%% |baseclass|. + +%%% This class will not be loaded if we are a package.[ema@csn.es] +%%% \beginprog +\ifcase\cweb@cls +%%% \endprog +%%% \beginprog +\def\CwebBaseClass{article} +\define@key{cweb}{baseclass}[report]{\def\CwebBaseClass{#1}} +%%% \endprog + +%%% Nothing to do for packages.[ema@csn.es] +%%% \beginprog +\fi +%%% \endprog + + +%%% \sect Language-specific adaptions are stored in files +%%% \texttt{cwbl-{\it language}.sty}. They may be accessed as packages or +%%% by the |language| option that takes the \textit{language} as value. We +%%% have to require the respective package at the end of the class, then +%%% all cseqs with default names are defined and may be overwritten. + +%%% For some languages, we provide Babel-compatible option names, to ease +%%% the usage of global class options taken up by other packages (like +%%% \pkg{varioref}), too. + +%%% \beginprog +\def\cweb_set_language#1{% + \IfFileExists{cwbl-#1.sty}{% + %% true + \RequirePackage{cwbl-#1}% + }{% + %% false + \ClassError{cweb}{Language `#1' is unknown.}{% +Language definitions are stored in files `cwbl-<language>.sty'.\MessageBreak +I could not locate the file `cwbl-#1.sty'. If you didn't make a% +\MessageBreak +typo, please check if there is such a file in a directory searched\MessageBreak +by LaTeX.% + }% + }% + } + +\define@key{cweb}{language}{\AtEndOfClass{\cweb_set_language{#1}}} + +\define@key{cweb}{german}[]{\setkeys{cweb}{language=german}} +\define@key{cweb}{french}[]{\setkeys{cweb}{language=french}} +\define@key{cweb}{italian}[]{\setkeys{cweb}{language=italian}} +\define@key{cweb}{spanish}[]{\setkeys{cweb}{language=spanish}} +%%% \endprog + + + + +%%% \chap Configuration, inheritance, and aggregation. + +%%% This chapter sets up access to other modules, therefore we restore the +%%% original catcodes for the time being. + +%%% \beginprog +\catcode`\_=\CatUsCode +%%% \endprog + + +%%% \sect As usual, we provide the possibility to configure this class. + +%%% \beginprog +\InputIfFileExists{cweb.cfg}{% + \typeout{******************************************^^J% + *^^J% + * Using local configuration file cweb.cfg^^J% + *^^J% + ******************************************% + }% + }{} +%%% \endprog + + +%%% \sect Inherit article class. + +%%% \beginprog +\ifx \CwebBaseClass\undefined + \def\CwebBaseClass{article} +\fi +\define@key{cweb}*[]{\PassOptionsToClass{\KV@key}{\CwebBaseClass}} +\ProcessKeyValOptions{cweb} +%%% \endprog + +%%% The class will not be loaded if we are a package.[ema@csn.es] +%%% \beginprog +\ifcase\cweb@cls +\LoadClass{\CwebBaseClass} +%%% \endprog + +%%% Nothing to do for packages.[ema@csn.es] +%%% \beginprog +\fi +%%% \endprog + + +%%% \sect OK, now comes our own code; switch on again our lexical +%%% conventions. + +%%% \beginprog +\catcode`\_=\CatLetter +%%% \endprog + + + + +%%% \chap Typesetting \cweave{} output. + +%%% This task has been out-sourced to an other module, \pkg{cwebbase}. As +%%% mentioned at the start of the implementation, there remain mainly some +%%% bigger tasks, they will be implemented in further sections below. For +%%% the most part, the necessary preconditions are actually our class +%%% option definitions, we don't have to do anything. (Gosh, what a +%%% coincidence. :--) We need to tell \pkg{cwebbase}, that it should use +%%% class warnings on problems. + +%%% \beginprog +\let\cweb_warning=\ClassWarningNoLine +\input{cwbasehy} +%%% \endprog + + + +%%% \sect But there remain also some small things to be done right now: +%%% For flat structure, the counter |secnumdepth| must be set to~11, then +%%% we want to number chunks in the whole document. + +%%% \beginprog +\ifcase \cweb@structure + %% hierarchic + \or + %% flat + \setcounter{secnumdepth}{11} +\fi +%%% \endprog + + +%%% \sect \pkg{cwebbase} uses |\part|, |\chapter| (if bound), and +%%% |\section|. We have no use for any other section division that came +%%% from the base class, let's discard the standard ones. + +%%% Unless we are a package, in which case we don't know if there will be +%%% sections using them later. +%%% \beginprog +\ifcase\cweb@cls +%%% \endprog +%%% \beginprog +\let\subsection\undefined +\let\subsubsection\undefined +\let\paragraph\undefined +\let\subparagraph\undefined +%%% \endprog + +%%% Nothing to do for packages.[ema@csn.es] +%%% \beginprog +\or\fi +%%% \endprog + + + + +%%% \chap Table of contents. + +%%% The table of contents features only sections, chunks don't have +%%% titles, after all. Titles are indented proportionally to the rank, +%%% with an basic indentation of |\CwebTocIndent|. An entry on major +%%% ranks may be differentiated by layout instead of indentation, as it's +%%% done in standard \LaTeX{} classes, too. + +%%% The counter |\CwebTocIndentMaxLevel| constitutes an upper limit for a +%%% recognized indent (concerning indentation, that is). + +%%% \beginprog +\newdimen\CwebTocIndent + \CwebTocIndent=1.5em +\newcount\CwebTocIndentMaxLevel + \CwebTocIndentMaxLevel=6 % increase indentation if <= max level +%%% \endprog + + +%%% \sect For hierarchic structure, we can ignore chunk entries +%%% completely, but have to supply a bunch of definitions for entries of +%%% type `|section|$l$'. But for flat structure, sections are passed as +%%% chunks, too. Then the current rank is stored in the title, as +%%% |\cwbbRank{|$r$|}|. These differences are so large that we'll have +%%% to make a very large |\ifcase|, over many chunks in this macro source +%%% file. Let's start with the hierarchic stuff. + +%%% \beginprog +\ifcase \cweb@structure + %% hierarchic + \def\l@chunk#1#2{} +%%% \endprog + + +%%% \sect Let's assume that we're subclassed from one of \LaTeX{}'s +%%% standard classes; otherwise this stuff must be redefined, too. They +%%% indent |\section| entries always by the same amount (1.5\,em), our +%%% layout must fit to that. + +%%% If we have chapters, they are also indented by 1.5\,em and +%%% distinguished by layout. The first minor section starts on rank~3 and +%%% is placed on level~2, it should be indented larger. Let's simply add +%%% 1.5\,em for each rank, that makes 3\,em for sections of type +%%% |section2|. I.e., we use $f=l$ as a factor for our basic indentation. + +%%% If we don't have chapters, the first minor section starts on rank~2 +%%% and is placed also on level~2, it should be indented like sections +%%% (1.5\,em), as it will be in another layout. I.e., we use $f=l-1$ as +%%% the indentation factor. + +%%% The actual definitions are generated in a loop. `|\l@section|$l$' +%%% expands to `|\cweb@toc_entry{|$l$|}|'. The indentation will be +%%% computed within that macro. + +%%% \beginprog + \count@=2 + \@whilenum \count@<11 \do { + \expandafter\edef \csname l@section\number\count@\endcsname{% + \noexpand\cweb@toc_entry{\number\count@}% + } + \advance \count@ by 1 + } +%%% \endprog + + +%%% \sect A toc entry may be produced by |\@dottedtocline|. That cseq +%%% needs the level (to decide if that entry is produced after all), the +%%% entry indentation, the inner-entry indentation used for the number, +%%% entry text, and page number. + +%%% As explained above, we use an indentation of $f \cdot +%%% |\CwebTocIndent|$, if the level is not larger than +%%% |\CwebTocIndentMaxLevel|. Otherwise we use the indentation of that +%%% level. + +%%% Each entry is kind of an item with the number as the label. We need an +%%% inner-entry indentation to be used for subsequent lines within this +%%% entry. If a number is specified, it's tagged by |\numberline| in the +%%% entry text. With a proper local definition and a pro-forma evaluation +%%% of the text, we get at the width of the number (with a fitting space +%%% for separation to text) and can use that as the inner-entry +%%% indentation. + +%%% \beginprog + \def\cweb@toc_entry#1#2{% % #3 (page) will follow + %% \count@ == factor for basic indentation + %% min(#1,TocIndentMaxRank) - correct_level + \ifnum #1>\CwebTocIndentMaxLevel + \count@\CwebTocIndentMaxLevel + \else + \count@ #1 % <-- space! + \fi + \ifx \chapter\undefined + \advance \count@\m@ne + \fi + %% \dimen@ == inner-entry indentation + %% width of number & space, if existing + \begingroup + \global\dimen@ \z@ % assert value + \def\numberline##1{\settowidth{\global\dimen@}{##1\enskip}}% + \setbox\z@ \hbox{#2}% % evaluates \numberline if specified + \endgroup + \@dottedtocline + {#1}% % level + {\count@ \CwebTocIndent}% % basic indent + \dimen@ % num width + {#2}% % entry; page will follow + } +%%% \endprog + + +%%% \sect We're done with toc configuration for hierarchic structure, +%%% since entry definitions for |chapter| and |section| types exist +%%% already. Let's turn over to the flat structure. + +%%% \beginprog + \or + %% flat +%%% \endprog + + +%%% \sect The section rank determines how they are featured in the table. +%%% Titles on rank~0 are typeset boldface, other titles are dotted +%%% contents lines in roman. + +%%% The rank is specified within the title, i.e., in the +%%% first argument to |\l@chunk|, as an argument for the |\cwbbRank| tag. +%%% With an appropriate definition we might set |\count@| to the +%%% respective value. If it is not set, an explicite invocation of +%%% |\section| or |\addcontentsline| is responsible for this entry. Then +%%% we assume that the rank is~0. + +%%% \beginprog + \def\l@chunk#1{% % page will be processed later + \count@\@ne % default value of group level + \begingroup + \let\numberline\@gobble % width not known yet + \def\cwbbRank##1{\global\count@ ##1\relax}% + \setbox\z@ \hbox{#1}% + \endgroup + \ifnum \count@=\z@ + \let\next\cweb@bold_toc_line + \else + \let\next\cweb@normal_toc_line + \fi + \next{#1}% + } +%%% \endprog + + +%%% \sect A boldface line is typeset similar to the definition of +%%% |\@dottedtocline|, only with fewer parameters. It takes two +%%% parameters, the entry and the page number. + +%%% \beginprog + \def\cweb@bold_toc_line#1#2{% + \addpenalty{\@secpenalty}% + \addvspace{1em plus\p@}% + \begingroup + \noindent \bf + \hangindent\CwebTocIndent + \rightskip\@tocrmarg \parfillskip -\rightskip + \interlinepenalty\@M + \@tempdima\CwebTocIndent % for \numberline + #1\nobreak\hfill \hbox to\@pnumwidth{\hss #2}% + \par + \endgroup + } +%%% \endprog + + +%%% \sect A normal line uses |\@dottedtocline| like the hierarchic stuff. +%%% Rank~1 shall still be on the same level as the bold toc line, so we +%%% have to use $r-1$ as the proportional factor for |\CwebTocIndent|. + +%%% \beginprog + \def\cweb@normal_toc_line#1{% % page will be processed later + \edef\next{\noexpand\@dottedtocline{\the\count@}}% % toc entry level + \ifnum \count@>\CwebTocIndentMaxLevel + \count@ \CwebTocIndentMaxLevel + \fi + \advance\count@\m@ne % group level -= 1 + \next{\count@\CwebTocIndent}% % basic indent + \CwebTocIndent % numwidth + {#1}% % entry + } +%%% \endprog + + +%%% \sect The first argument of |\@dottedtocline| is used to specify a +%%% depth of the issued entry. All entries with a depth larger than +%%% |tocdepth| are discarded. We typeset all entries, our |tocdepth| +%%% value is the largest possible section level. + +%%% \beginprog + \setcounter{tocdepth}{10} +%%% \endprog + + +%%% \sect That's it. Close our distinction between hierarchic and flat +%%% structure. + +%%% \beginprog +\fi +%%% \endprog + + + + +%%% \chap The end of the document. + +%%% The end of a \cweave{} document is a rather complicated thing. It is +%%% described in detail in the \cweave{} interface specification, we repeat the +%%% most important points shortly. +%%% % +%%% \begin{itemize} + +%%% \item The user has issued an |\end{document}| tag in the documentation +%%% part of the last chunk. + +%%% This tag is therefore part of a chunk, the chunk end (i.e., the +%%% |\fi| cseq) does appear later in the document. Particularly, this +%%% means that at the accurence of this tag there is still an open |\if|. + +%%% \item Between the |\end{document}| and the |\fi| a lot of text may +%%% come which must be ignored. Within this text no |\fi| is allowed. + +%%% \item After the |\fi| the document may be finished by |\end|. +%%% (Then the |-x| option of \cweave{} was used.) + +%%% Or additional information about the whole document is added: An +%%% optional tag |\ch|, two mandatory tags |\inx\fin|, and another +%%% optional tag |\con|. + +%%% \end{itemize} + +%%% Btw, the last chunk is marked as changed if any changefile entry has +%%% been applied in the document. (In Plain \cweb{} that chunk is +%%% colloquially used as the introduction to the index, and that shall be +%%% printed always.) If we suppress unchanged chunks, the last +%%% chunk will therefore always be processed, independent if it was really +%%% changed or not. Yet another reason to use a whole chunk just for +%%% |\end{document}|. + +%%% We'll use a the following approach for the implementation of the +%%% iidentifier index and the refinement list (remember that we do not +%%% produce a table of contents): We will check if there is any of these +%%% two lists available. The available ones are typeset. Then we'll +%%% finish the document. This functionality will be bound to |\fin|. +%%% |\inx| will be simply a no-op. |\con| will never be reached, so we +%%% don't have to cope with it. + + +%%% \sect With the introduction of an end-document hook in \LaTeXe{}, one +%%% might have hoped that we can utilize that hook for our task. But this +%%% is not possible: We don't want to add some additional actions +%%% \emph{into} the end-document handling, we want to look ahead and issue +%%% lots of commands \emph{before} the end-document handling has happened. +%%% (If you know \TeX{} by heart, you may skip the rest of the explanation +%%% and go to the next chunk.) + +%%% As a macro language, \TeX{}'s cseqs take those tokens as arguments +%%% that are behind them in the token stream. The token stream is +%%% initially the document source, evaluation of a macro pushes its +%%% expansion (a token list) on front of the stream. I.e., the evaluation +%%% of |\end| will push the expansion on the token stream before +%%% |\enddocument| is even looked at. And |\enddocument| will also push +%%% its expansion before the hook is evaluated. + +%%% If we would allow |\enddocument| to push its expansion, all these +%%% tokens have to be evaluated after we have typeset the backmatter -- +%%% after all, we need a proper document end, don't we? One would need to +%%% skip over them, look at and eventually evaluate tokens that come +%%% behind (from the initial document stream, the document source), and +%%% then evaluate the skipped tokens. That's too hairy, we don't know +%%% exactly how many tokens to skip, this is probable to change in future +%%% \LaTeX{} revisions, etc. + +%%% The pushed tokens from |\end| don't pose so much problems. As +%%% |\enddocument| will terminate the document processing, they are not +%%% evaluated anyhow, we can just throw them away. And |\end| has changed +%%% only once in the last few years, so it seems to be a stable macro -- +%%% necessary as we need to know its expansion for propper skipping. + +%%% A very first consequence of the demand to process tokens after +%%% |\end{document}| is that we have to save the ``standard'' \LaTeX{} +%%% document termination, since we will execute that later. + +%%% \beginprog +\ifcase\cweb@cls +\let\cweb@save@enddocument=\enddocument +\or +\let\cweb@save@enddocument=\relax +\fi +%%% \endprog + + +%%% \sect When we encounter |\end{document}| we have to skip tokens +%%% until we reach a |\fi|. Then we establish the correct +%%% environment for the material behind. + +%%% The skip itself is actually a bit difficil, so we'll look at it more +%%% closely. |\enddocument| is executed within |\end|. As mentioned above, +%%% the original +%%% definition of |\enddocument| cheats, it terminates \LaTeX{} before +%%% the rest of |\end| is executed. |\end| first checks if we're in +%%% the correct current environment, then it establishs the end +%%% processing for paragraph building environments, closes the +%%% group---each environment is in its own group, executes the end +%%% processing established before, and it may ignore following white +%%% space. + +%%% The |document| pseudo-environment is different in that it isn't in a +%%% group. I.e., we have to open a group which can be closed by |\end| +%%% afterwards. The environment check will be done in this group. With +%%% |\aftergroup| we establish a macro which will skip the rest of the +%%% |\end| processing. This processing is not needed anyhow: |document| +%%% is no paragraph building environment and the following white space is +%%% ignored by ourselves. Since |document| is no paragraph building +%%% environment, the end processing described above is empty, i.e., not +%%% existant. Then come a few tokens which ignore the white space. One of +%%% these tokens is a |\fi|, so we have to skip them first separately. +%%% They are discarded by |\cweb@skip_end|, we can start to look +%%% for our |\fi| afterwards. + +%%% If |\end{document}| is the first (i.e., the only) text in this chunk +%%% we discard the chunk start marker. This is possible since it isn't set +%%% until now, it's in the |\everypar| token register. Of course, then we +%%% have to do the house keeping work stored in |\everypar| ourselves. + +%%% No need of this for packages. [ema@csn.es] +%%% \beginprog +\ifcase\cweb@cls +%%% \endprog + +%%% \beginprog +\def\enddocument{% + \if@noskipsec + \global\everypar{}% + \global\@noskipsecfalse + \global\@nobreakfalse + \global\clubpenalty\@clubpenalty + \fi + \begingroup + \aftergroup\cweb@skip_end + } +%%% \endprog + +%%% [ema@cwn.es] +%%% \beginprog +\fi +%%% \endprog + +%%% \sect Let's make sure that the expansion of |\end| is the one that we +%%% expect. Then we can define |\cweb@skip_end| appropriately, we have to +%%% skip 5~tokens. + +%%% \beginprog +\CheckCommand*\end[1]{% + \csname end#1\endcsname\@checkend{#1}% + \expandafter\endgroup\if@endpe\@doendpe\fi +% 1 2 3 4 5 + \if@ignore\@ignorefalse\ignorespaces\fi} +\def\cweb@skip_end#1#2#3#4{\cweb@check_fi} +%%% \endprog + + +%%% \sect |\cweb@check_fi| gets the next token, and invokes +%%% |\cweb@do_check_fi| who really checks it. If this token is |\fi| we +%%% can prepare to finish our document. Otherwise we have to check the +%%% next token. + +%%% Of course, first the token we have checked already must be discarded. +%%% Therefore we insert the followup action by |\afterassignment|. It's +%%% important that the assignment gets \emph{only} the next token, we +%%% have to supply both the equals sign and the optional blank which are +%%% allowed between the both arguments to |\let|. + +%%% \beginprog +\def\cweb@check_fi{% + \futurelet\next \cweb@do_check_fi + } +\def\cweb@do_check_fi{% + \ifx \next\fi + \afterassignment\cweb@finish + \else + \afterassignment\cweb@check_fi + \fi + \let\next= % <-- blank!! + } +%%% \endprog + + +%%% \sect When we found the |\fi|, we also discard it. But we're still +%%% within a chunk, i.e., there is an open |\if|. So we must supply the +%%% |\fi|. + +%%% \TeX{}nical note: |\next| is now equivalent to |\fi|. It must not be +%%% used within a loop where it denotes the tail recursion's action. I.e., +%%% code like +%%% % +%%% \begin{verbatim} +%%% \ifx \foo\bar +%%% \let\next\relax +%%% \else +%%% \let\next\continue +%%% \fi +%%% \next +%%% \end{verbatim} +%%% % +%%% will fail. This trap is closed by a redefinition of |\next|. + +%%% The output of all following lists may be suppressed by some option. +%%% That is tested at the place where the respective list shall be +%%% produced. + +%%% All following lists are typeset in CR state. + +%%% \beginprog +\def\cweb@finish{% + \fi + \let\next\relax + \let\ch\cweb@changed_list + \let\inx\relax + \let\fin\cweb@end_document + \let\end\cweb@save@enddocument + \cwbb@CR + } +%%% \endprog + +%%% But, if we are inside another document, we would not like to have all +%%% this. As they are disabled from the arguments, I will skip +%%% them.[ema@csn.es] + +%%% \beginprog +\ifcase\cweb@cls\or +\let\con\relax %<- Not sure! +\let\inx\relax +\let\fin\relax +\fi +%%% \endprog + +%%% \sect The following lists are started with unnumbered section +%%% divisions. They are either chapters or sections. + +%%% \beginprog +\ifx \chapter\undefined + \let\CwebListSectionDiv=\section +\else + \let\CwebListSectionDiv=\chapter +\fi +\def\CwebListSection{\CwebListSectionDiv*} +%%% \endprog + + +%%% \sect The list of changed chunks is a cross reference list, (nearly) +%%% like all others at the end of a chunk. The only difference is that +%%% we do not show changeflags any more---each chunk number in this list +%%% carries a change flag by definition. + +%%% \TeX{}nical note: The redefinition of |\*| is part of the second +%%% argument of |\CwebCrossRef|. It is \emph{not} a global redefinition. + +%%% \beginprog +\def\CwebCRChanged{% + \CwebCrossRef{The following chunks were changed by the change file:}% + } +\def\CwebChangedListName{Changed Chunks} + +\if@cweb@suppress@changehints@ + \def\cweb@changed_list#1.{} +\else + \def\cweb@changed_list{% + \CwebListSection{\CwebChangedListName}% + \@mkboth{\uppercase{\CwebChangedListName}}% + {\uppercase{\CwebChangedListName}}% + \message{\CwebChangedListName}% + \let\CwebCRSize\relax + \CwebCRChanged \let\*\relax + } +\fi +%%% \endprog + + +%%% \sect As outlined above, we want to check if there are any entries in +%%% the identifier index or the refinement list. The former is stored in +%%% the file |\jobname.idx|, the latter in the file |\jobname.scn|. + +%%% We write a macro |\cweb@if_file_not_empty| that's like |\IfFileExists|. + +%%% \beginprog +\def\cweb@end_document{% + \cweb@if_file_not_empty{\jobname.idx}{% + \if@cweb@suppress@index@ \else + \CwebIdIndex + \fi + }{}% + \cweb@if_file_not_empty{\jobname.scn}{% + \if@cweb@suppress@reflist@ \else + \CwebRefList + \fi + }{}% + \cweb@save@enddocument + } +%%% \endprog + + +%%% \sect The paragraph layout for both the index and the refinement list +%%% is much the same, it is taken from Plain \cweb{}: Each entry is a +%%% paragraph, nearly no skip between the paragraphs (just a bit to +%%% prevent underfull vboxes), no paragraph indentation, ragged right. +%%% Overfull hboxes in the lists don't make sense, so we prevent them. And +%%% we don't allow hyphenation. + +%%% \beginprog +\def\cweb@list_par_layout{% + \parskip \z@ plus .5\p@ + \parindent\z@ + \rightskip \z@ plus 2.5em + \tolerance\@M \hyphenpenalty\@M + } +%%% \endprog + + +%%% \sect We consider a file as ``not empty'' if (1)~the file exists, +%%% (2)~is not empty, and (3)~has a non-empty line at the very front. (In +%%% fact, an empty line at the front means that there should not be +%%% anything behind it---but we can't test this portably.) + +%%% |\cweb@if_file_not_empty| tests the property, it's parametrized by the +%%% file name and gets passed actions for the true and the false case. + +%%% We open the file first. Then we check if it doesn't exist or if it's +%%% empty, both conditions deliver true on |\ifeof|; in this case we +%%% pretend that there was an empty line. (The \LaTeX{} kernel already +%%% once provided a macro for an empty line, |\@defpar|, we repeat that +%%% definition here since it was discarded there.) Otherwise we read the +%%% first line. At this state, the emptiness of the first line is +%%% equivalent to the non-availability of entries, we can easily construct +%%% an appropriate macro call to set the flag. + +%%% \beginprog +\def\@defpar{\par} +\def\cweb@if_file_not_empty#1#2#3{% + \openin\@inputcheck #1\relax + \ifeof \@inputcheck + \let\next\@defpar + \else + \read\@inputcheck to \next + \fi + \closein\@inputcheck + \ifx \next\@defpar + \def\reserved@a{#3}% + \else + \def\reserved@a{#2}% + \fi + \reserved@a + } +%%% \endprog + + +%%% \sect The identifier index is available in the file |\jobname.idx|. +%%% The setup for the index is a mixture of the |theindex| environment of +%%% the \cls{article} class and DEK's index macros. It's typeset in two +%%% columns; the user may specify an introductionary text for the index +%%% by |\cwebIndexIntro|. If there is any introductionary text we add a +%%% medium skip below. + +%%% For the index, |\parfillskip| set in such a way that almost empty +%%% lines are avoided. + +%%% Before we read in this file, we have to bind the special cseqs used +%%% therein. + +%%% \begin{fixme} +%%% \LaTeX{} feature or bug? The optional argument of |\twocolumn| is +%%% typeset as a vbox, therefore the space at top of the section heading +%%% is not discarded at the top of a page. But we know that |\twocolumn| +%%% will start a page in any case, we must prevent the addition of this +%%% space. Looking in the source, we see that setting the flag +%%% |@nobreak| will prevent this addition, let's do that as a +%%% workaround. File a \LaTeX{} bug report? +%%% \end{fixme} + +%%% \begin{fixme} +%%% Surprise: If |@nobreak| is set \emph{and} if there are no index +%%% entries, |\twocolumn| will drop its optional argument. (That +%%% happened to be noticed when there was an error in +%%% |\cweb@if_file_not_empty|.) File a \LaTeX{} bug report? +%%% \end{fixme} + +%%% \begin{fixme} +%%% If |\CwebListSection| is a chapter tag of the standard classes, that +%%% macro will check if it's in twocolumn mode and will try to set +%%% itself at the top of the current page in full width, as it would +%%% have been given in an optional argument of |\twocolumn|. As the +%%% method that optional argument uses (a float) must not be nested, we +%%% must prevent this to happen. We set the |@twocolumn| flag to false, +%%% chapter macros will then think they're evaluated in a one-column +%%% document. It's debatable if that is a kludge or even \emph{the} +%%% solution -- after all, within the optional argument we aren't in +%%% twocolumn mode any more. File a \LaTeX{} bug report? +%%% \end{fixme} + +%%% \beginprog +\newtoks\cwebIndexIntro + \cwebIndexIntro={} +\def\CwebIdIndex{% + %% two column format + \columnseprule\z@ + \columnsep 35\p@ % value is from article.sty + %% introduction of index + \twocolumn[% + \cwbb@tex + \@nobreaktrue % don't add space in front of section + \@twocolumnfalse % \CwebListSection might be \chapter + \CwebListSection{\indexname}% + \edef\intro{\the\cwebIndexIntro}% % is a local def + \ifx \intro\empty + \else + \the\cwebIndexIntro\unskip + \par\medskip + \fi + ]% + \@mkboth{\uppercase{\indexname}}{\uppercase{\indexname}}% + \message{\indexname:}% % tell the user what we're doing + %% paragraph layout + \cweb@list_par_layout + \parfillskip \z@ plus .6\hsize + %% bindings + \let\I\CwebIndexEntry + \let\[\CwebIndexDeclared + \let\*\cwbb@change_flag + %% read the index + \CwebReadIndex + } +\def\CwebReadIndex{\@input{\jobname.idx}} +%%% \endprog + + +%%% \sect An index entry is typeset with the same hanging indentation like +%%% a cross reference list. + +%%% The entry is tagged with |\.|, if it was entered by the \cweb{} +%%% operator~`|@.|'. Then it shall be typeset as a string. But an indexed +%%% name may also want to use |\.| as an accent. This is the same +%%% situation as we had at the refinement names (in module +%%% \pkg{cwebbase}), where we introduced |\cwbb@check_dot| to handle this +%%% case. The same minor restriction as there holds here, a refinement +%%% name may not consist of a single dot-accented expression. (|@:|~helps +%%% in this singular case.) + +%%% Enrique Mel\'endez (\texttt{ema@csn.es})introduced come code to +%%% insert hyperlinks (with the macro |\cweb@num@lnk|). + +%%% \beginprog +\def\CwebIndexEntry#1, #2.{% + \par + \hangindent\CwebNumberListHangindent + \leavevmode + \cwbb@check_dot{#1}:\quad\cweb@num@lnk#2, |. + } +%%% \endprog + + +%%% \sect The chunks where identifiers are declared are noted with +%%% underlined numbers. We also must not forget the default declaration of +%%% |\9|, the tag for the user definable index layout. + +%%% \beginprog +\def\CwebIndexDeclared#1]{$\underline{#1}$} +\def\9#1{} +%%% \endprog + + +%%% \sect The list of the refinement names is available in the file +%%% |\jobname.scn|. The layout is taken from the plain version: ragged +%%% right, each entry is a paragraph, the different cross reference +%%% categories are separated by a quad. + +%%% We must initialize our whole paragraph layout, as the index might have +%%% been suppressed and no initialization has happened there then. If +%%% there was an index, it changed |\parfillskip| and |\*|, let's restore it. + +%%% Enrique Mel\'endez (\texttt{ema@csn.es})introduced come code to +%%% insert hyperlinks (also in the macro |\CwebCrossRefs|). + +%%% \beginprog +\def\CwebRefListName{List of Refinements} + +\def\CwebRefList{% + %% paragraph layout: like in index, but + \onecolumn + \cweb@list_par_layout + \parfillskip\@flushglue % must be reset before section heading + \CwebListSection{\CwebRefListName}% + \@mkboth{\uppercase{\CwebRefListName}}% + {\uppercase{\CwebRefListName}}% + \message{\CwebRefListName:}% + %% different bindings + \def\I{\par \hangindent\CwebNumberListHangindent}% + \def\CwebCrossRef##1##2.{\quad % + {\reset@font\footnotesize ##1~\hyperlink{_hyperchunk_##2}{##2}.}}% + \def\CwebCrossRefs##1##2.{\quad % + { \let\save@et\ET% + \let\save@ets\ETs + \def\ET{, }% + \let\ETs\ET% + \edef\@crlst{##2}% + \let\LastList@Conjunction\save@et + \reset@font\footnotesize ##1~% + \expandafter\cweb@cr@lnk\@crlst, ].}}% + \let\Q\CwebXRCite + \let\Qs\CwebXRCites + \let\U\CwebXRUse + \let\Us\CwebXRUses + \let\*\cwbb@change_flag + %% Read the list, allow configuration first. + \csname CwebRefListHook\endcsname + \CwebReadPPList + } +\def\CwebReadPPList{\@input{\jobname.scn}} +%%% \endprog + +%%% \sect Extra definitions for the sake of internationalization. + +%%% \beginprog +\def\CwebXRCite{\CwebCrossRef{Cited in chunk}} +\def\CwebXRCites{\CwebCrossRefs{Cited in chunks}} +\def\CwebXRUse{\CwebCrossRef{Used in chunk}} +\def\CwebXRUses{\CwebCrossRefs{Used in chunks}} +%%% \endprog + + + +%%% \chap The end. + +%%% Well, after all we're finished with this class. We must not forget to +%%% restore the underscore catcode. + +%%% \beginprog +\catcode`\_=\CatUsCode + +\endinput +%%% \endprog + + +%%% \sect I would like to thank those who helped me to improve this module. +%%% % In particular, XXX provided XXXsubstantial parts of the code. + +%%% \textsc{Michael M\"uller} and \textsc{Zden\v{e}k Wagner} did thorough +%%% checks that helped me to improve the alpha test version. + + +%%% +%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%% \vskip \PltxPreSectSkip + +%%% \begin{rcslog} +%%% $StyleLog: cweb.doc,v $ +%%% \Revision 3.6 1995/11/30 15:44:53 schrod +%%% Still didn't work with version \mbox{$\langle$1994/12/01$\rangle$}, +%%% the copy of |\newif| was not complete.\\ +%%% Problem reported by Michael Seel \path|<seel@mpi-sb.mpg.de>|. + +%%% \Revision 3.5 1995/11/20 22:34:18 schrod +%%% Add language support.\\ +%%% Triggered by Christian Kumpf \path|<smurf@igd.fhg.de>| and Andreas +%%% Scherer \path|<scherer@physik.rwth-aachen.de>|. + +%%% Use my `official' (ACM) email address. + +%%% \Revision 3.4 1995/11/07 17:55:18 schrod +%%% \LaTeX{} \cweb{} should work at least with the last two \LaTeX{} +%%% versions; make it work with the previous-to-last one, version +%%% \mbox{$\langle$1994/12/01$\rangle$}. For that, one has to install the +%%% \mbox{$\langle$1995/06/01$\rangle$} (non-outer) definition of +%%% |\newif|, and |\hb@xt@| must not be used.\\ +%%% Problem reported by Laurent Desnogues +%%% \path|<laurent.desnogues@aiguemarine.unice.fr>| and somebody else (XXX +%%% -- add name). + +%%% \Revision 3.3 1995/09/17 14:15:36 schrod +%%% Initialize list paragraph layout in refinement list, too. With the +%%% introduction of index suppression, the initialization -- located in +%%% the index code -- might have been skipped. + +%%% \Revision 3.2 1995/09/15 10:22:59 schrod +%%% The \cls{cweb} class needs at least \LaTeX{} version +%%% \mbox{$\langle$1994/12/01$\rangle$}.\\ +%%% Problem reported by John S. Robinson \path|jsrobin@umiacs.umd.edu|. + +%%% \Revision 3.1 1995/09/12 23:00:48 schrod +%%% Moved all code that does the actual typesetting of \cweave{} tags and +%%% is therefore also needed for a |cweb| environment. It's now an own +%%% module named \pkg{cwebbase}. + +%%% \Revision 2.8 1995/09/12 11:44:33 schrod +%%% Standard base classes with chapters (i.e., report \& book) produced an +%%% error at the start of the index: |\chapter| may not be called in the +%%% optional argument of |\twocolumn|. Add a workaround to |\twocolumn|.\\ +%%% Problem reported by Christopher Higgins \path|<C.Higgins@cit.gu.edu.au>|. + +%%% \Revision 2.7 1995/08/29 17:32:36 schrod +%%% Add hook for refinement list. + +%%% Allow internationalization of refinement list.\\ +%%% (Problem reported by Christian Kumpf \path|<kumpf@igd.fhg.de>|.) + +%%% Cweb bundle, version 1.0. + +%%% \Revision 2.6 1995/08/29 15:19:50 schrod +%%% Added (hint to non-existence of) description of the internal interface. + +%%% \Revision 2.5 1995/08/29 02:07:26 schrod +%%% Discard dependencies on 10\,pt fonts. + +%%% Support suppression of format directives. + +%%% \Revision 2.4 1995/08/27 19:31:43 schrod +%%% Discard superfluous space at the top of index. Spacing in refinement +%%% heading was wrong. Repair test on empty auxilliary files. Make +%%% section heading for index and refinement list divisions (more) +%%% configurable. Suppression of index and reference list is supported. + +%%% Make configuration of change flag easier. + +%%% Put section title of changed chunks list in marks, and tell the user +%%% that it got typeset. + +%%% \Revision 2.3 1995/08/27 17:24:46 schrod +%%% Make usage of baseclass with chapters work. + +%%% \Revision 2.2 1995/08/27 13:26:22 schrod +%%% Add possibility to suppress change hints. Suppression of unchanged +%%% chunks suppress change hints as well, they are meaningless as all +%%% printed chunks are changed by definition. + +%%% Realize dependencies in options by |\ProcessKeyValOptionsHook|. +%%% Illegal values for enumeration options don't alter the current value +%%% any more. + +%%% List of changed chunks is an unnumbered section now. + +%%% \Revision 2.1 1995/08/25 19:11:18 schrod +%%% Add keyword-value option style, with new \pkg{keyvald} package. + +%%% Hierarchic strucutures are supported now, in addition to the flat +%%% structure of the beta-test version. One can choose with an option. For +%%% that step, the terminology was cleaned up, too: Chunks are not named +%%% sections any more. (That change involved reimplementation of almost +%%% all the structure and toc stuff.) + +%%% The chunk number supplied by \cweave{} is used now, not some computed +%%% number. Change flags are printed, too. + +%%% One can suppress output of unchanged sections. + +%%% One can select the baseclass with an option. That may be used to use +%%% \cls{report} or \cls{book} to get chapter-style layout. Of course, +%%% using an arbitrary baseclass is dangerous, it must conform to the +%%% conventions of \LaTeX{} standard classes. + +%%% \Revision 1.13 1995/08/08 00:14:29 schrod +%%% Updated to \LaTeXe{}, the |cweb| style is now a document class. Used +%%% my standard templates for that, no changes in functionality. + +%%% \Revision 1.12 1993/08/10 14:15:43 schrod +%%% New page on main section only if group level $<$ |\cwebSecNoEject|. +%%% Default for the latter is 3. + +%%% Document that logos will not be defined in this style file. + +%%% Copy of plain macros for |\CwebNumber| does not work. Repaired the +%%% most important one (subscript must be accessed via |\sb|). +%%% Incompatibility to NFSS will be addressed later.\\ +%%% (Problems reported by Zden\v{e}k Wagner \path|<wagner@csearn.bitnet>|.) + +%%% \Revision 1.11 1993/08/10 11:21:07 schrod +%%% Reference to section number does not render a period after the +%%% number any more. + +%%% \Revision 1.10 1993/08/09 20:08:20 schrod +%%% |\cweb@cweave_bindings| is now a no-op if \cweave{} bindings are in +%%% effect already.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% \Revision 1.9 1993/08/09 18:05:28 schrod +%%% Left shift operator wasn't defined correctly.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% \Revision 1.8 1993/06/15 15:22:30 schrod +%%% \textbf{Version 0.2:} Moved from |pub/incoming| to official place, in +%%% Literate Programming Archive. + +%%% \Revision 1.7 1993/06/15 13:25:48 schrod +%%% First attempt to make it a style: |article| is imported. Warns the +%%% user if he tries to use |cweb| as a style option. + +%%% \Revision 1.6 1993/06/15 08:49:23 schrod +%%% |\cweb@check_dot| must not evaluate its argument in an |\edef|, this +%%% causes problems if a |\PB| is within. Now I try hard not to evaluate any +%%% tokens outside of my control. + +%%% Can use |\@defpar| for an empty line in |\cweb@has_entries|, don't +%%% need an own macro. + +%%% \Revision 1.5 1993/06/14 17:50:30 schrod +%%% Handle a missing |\con|: |\inx| and |\con| are now never looked at. +%%% Instead |\fin| checks for the existence of the lists and typeset them +%%% if there are entries available. + +%%% \Revision 1.4 1993/06/14 15:54:18 schrod +%%% Made it work with older versions of \LaTeX{}, too. The |\enddocument| +%%% implementation of cweb.sty depends on the |\end| implementation; check +%%% if the current implementation is one we know of (currently: 91-01-14 +%%% and 92-03-25).\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% Add FSA diagram about processing states. CR state is also switched +%%% to from \TeX{} state (that happens with |\ch| at the document end). + +%%% \Revision 1.3 1993/05/13 17:51:21 schrod +%%% Refinements may also be filenames (`|@(|'). Then the complete name +%%% consists of a |\.| macro call, which is handled now.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% Made the detection of `|@.|' index entries more robust. + +%%% \Revision 1.2 1993/05/12 18:28:59 schrod +%%% Adapted to recent changes of \cweave{} (of April 93): + +%%% Main sections have a group level, represented in the table of +%%% contents. This changed the complete implementation of section tags. + +%%% New C token cseqs: |\Z| and |\MRL|, implemented as |\CwebLe| and +%%% |\CwebCombinedOp|. + +%%% \Revision 1.1 1993/04/09 15:00:37 schrod +%%% Initial revision + +%%% \end{rcslog} + + + +%%% \end{document} + + +%%% +%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%% Local Variables: +%%% mode: LaTeX +%%% TeX-brace-indent-level: 4 +%%% indent-tabs-mode: t +%%% TeX-auto-untabify: nil +%%% TeX-auto-regexp-list: LaTeX-auto-regexp-list +%%% compile-command: "make cweb.cls" +%%% End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/nodoc.tex b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/nodoc.tex new file mode 100644 index 00000000000..fe9e4b8658a --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/cweb-hy/nodoc.tex @@ -0,0 +1,121 @@ +% File nodoc.tex +% By Enrique Mel\'endez, <UEI0560130010@eurociber.es> April, 14, 1999. +% Freely distributable under, f. i. GNU. +% I do this for fun, but if you use it, I would like no know how it performs +% Please, keep the author notice. +% Put \include nodoc.tex as the very first line of your documents. +% No responsibility. Usde this at your own risk. (That is, it may not work +% as you intended, but I never designed it to.) + + +\makeatletter +\ifx\section\undefined + \makeatother + \expandafter\endinput +\else + +% Things we suppress are `only preamble' +% documentclass +\let\n@documentclass\documentclass +\def\documentclass{\@ifnextchar[\@documentclass@{\@documentclass@[]}} +\def\@documentclass@[#1]#2{\relax} + +% usepackage +\let\n@usepackage\usepackage +\def\usepackage{\@ifnextchar[\@usepackage@{\@usepackage@[]}} +\def\@usepackage@[#1]#2{\relax} +% The following 4 should be allowed to change. I don't know how. +% author +\let\n@author\author +\def\author#1{\gdef \@author{#1}%\relax +} +% date +\let\n@date\date +\def\date#1{\relax} +% title +\let\n@title\title +\def\title#1{\gdef \@title{#1}%\relax +} +% maketitle +\let\n@maketitle\maketitle +\def\maketitle{% + \vskip 2em% + \begin{center}% + \let \footnote \thanks + {\LARGE \@title \par}% + \vskip 1.5em% + {\large + \lineskip .5em% + \begin{tabular}[t]{c}% + \@author + \end{tabular}\par}% + \vskip 1em% + {\large \@date}% + \end{center}% + \par + \vskip 1.5em + \global\let\@title\@empty + \global\let\@author\@empty + \global\let\title\relax + \global\let\author\relax +%\relax +} +\def\pagestyle#1{\relax} +\def\thispagestyle#1{\relax} +\renewenvironment{titlepage} + {% + \if@twocolumn + \@restonecoltrue\onecolumn + \else + \@restonecolfalse\newpage + \fi + \thispagestyle{empty}% + %\setcounter{page}\@ne + }% + {\if@restonecol\twocolumn \else \newpage \fi + %\if@twoside\else + %\setcounter{page}\@ne + %\fi + } +% tableofcontents +\let\n@tableofcontents\tableofcontents +\def\tableofcontents{\relax} +% The begindocument, where we rebind some of the above +\let\@document@=\document +\def\document{\endgroup\relax% +\let\document\@document@% +\let\documentclass\n@documentclass% +\let\usepackage\n@usepackage% +} +% The enddocument, where some more things are rebound +\let\@enddoc@=\enddocument +\def\enddocument{% +\let\tableofcontents\n@tableofcontents% +\let\maketitle\n@maketitle +\let\title\n@title +\let\author\n@author +\let\date\n@date +\let\enddocument\@enddoc@% +\begingroup} +\fi + +%% Borrowed from LaTeX general format. +\def\@ifnextchar#1#2#3{% + \let\reserved@d=#1% + \def\reserved@a{#2}\def\reserved@b{#3}% + \futurelet\@let@token\@ifnch} +\def\@ifnch{% + \ifx\@let@token\@sptoken + \let\reserved@c\@xifnch + \else + \ifx\@let@token\reserved@d + \let\reserved@c\reserved@a + \else + \let\reserved@c\reserved@b + \fi + \fi + \reserved@c} +\def\:{\let\@sptoken= } \: % this makes \@sptoken a space token +\def\:{\@xifnch} \expandafter\def\: {\futurelet\@let@token\@ifnch} + +\makeatother diff --git a/Master/texmf-dist/doc/latex/cweb-latex/contrib/wagner/cwebzw.sty b/Master/texmf-dist/doc/latex/cweb-latex/contrib/wagner/cwebzw.sty new file mode 100644 index 00000000000..cff2d7c254e --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/contrib/wagner/cwebzw.sty @@ -0,0 +1,323 @@ +%% $Id: cwebzw.sty,v 1.2 1993/08/10 14:14:33 schrod Exp $ +%%---------------------------------------------------------------------- +%% Changed by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de> +%% Original received by mail: +%% Date: Thu, 05 Aug 93 12:34:21 MDT +%% From: Zdenek Wagner <WAGNER@CSEARN.BITNET> + +%% This is file ``cwebzw.sty'' written by Z. Wagner as an extension and +%% correction of ``cweb.sty'' Revision 1.8 + +%% This file is self-documenting. If you process this file through LaTeX, +%% you will get the documentation. You can use MakeIndex to create an +%% index of macros used. In your cweb documents you can either use it as +%% is or you can remove all comment lines by your editor or the docstrip +%% utility (or a program of your own). + +%% See chapter ``Introduction'' for other remarks. + +\def\cwebzwrevision{1.8} % Do not remove this line! + +% You can remove the next two lines +\ifcat a\noexpand @\let\next\relax\else\def\next{% + \documentstyle[doc]{article}\MakePercentIgnore}\fi\next + +% \EnableCrossrefs +% \CodelineIndex +% \catcode`\_=12 +% \DoNotIndex{\cweb,\orig,\p} ^^A doc.sty cannot handle underscore +% \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ } +% \DoNotIndex{\@ne,\tw@,\bgroup,\egroup,\endinput,\end,\kern,\hbox,\vbox,\vtop} +% \DoNotIndex{\aftergroup,\arabic,\begin,\protect,\rm,\reset@font,\setbox} +% \DoNotIndex{\show,\typeout,\errhelp,\unskip,\unvbox,\wd,\input,\hskip} +% \DoNotIndex{\ifdim,\ifmmode,\ifnum,\long,\footnotesize,\newbox,\newpage} +% \DoNotIndex{\@ifnextchar,\@ifundefined,\@namedef} +% \DoNotIndex{\advance,\begingroup,\catcode,\closein,\closeout} +% \DoNotIndex{\day,\def,\edef,\else,\empty,\endgroup,\errmessage} +% \DoNotIndex{\expandafter,\fi,\futurelet,\gdef,\global,\if,\ifeof} +% \DoNotIndex{\ifx,\immediate,\let,\loop,\m@ne,\message,\month,\newcount} +% \DoNotIndex{\newif,\newlinechar,\newread,\newtoks,\newwrite} +% \DoNotIndex{\noexpand,\openin,\openout,\par,\read,\relax,\repeat} +% \DoNotIndex{\space,\the,\undefined,\write,\xdef,\year,\z@} +% \advance\textwidth by 40pt +% \def\pcws{{\tt cweb.sty}} +% \def\cws{\protect\pcws} +% \newbox\cwebincr +% \setbox\cwebincr=\hbox{^^A +% \kern .5pt +% \raise .1em\hbox{$\scriptstyle{+}\kern -.1em{+}$}^^A +% \kern .5pt} +% \def\Cpp{C\copy\cwebincr} +% \begin{document} +% \MakeShortVerb\| +% \title{Extension and correction of \cws\ revision~\cwebzwrevision} +% \author{Zden\v{e}k Wagner\\ +% $\langle$wagner@csearn.bitnet$\rangle$ or +% $\langle$wagner@earn.cvut.cz$\rangle$}\date{} +% \maketitle\vspace{3ex} + +% \tableofcontents\thispagestyle{empty}\newpage + +% \section{Introduction} +% The purpose of this file is to add new features to \cws\ and +% correct some bugs. When doing this we intended not to make a faintest +% change into \cws. Therefore some definitions may look strangely +% cumbersome. However, this file should be treated as a test of new +% features and bug fixes which should then be placed in the official +% distribution of \cws\ and in the ideal state this file will one day +% vanish at all. + +% {\bf Note by Joachim Schrod}:\quad I have incorporated most error +% repairs and some of the enhancements into \cws{} (Revision~1.12). To +% avoid problems, I deleted all the respective macros from this +% option. The rest that you see here will not be incorporated (at +% least not as-is) and is therefore provided as a contributed style +% option for those who like it. + + +% \section{Preliminaries} +% First we make sure that this file is not input twice. +% \begin{macrocode} +\@ifundefined{\cweb@egroup}{}{\endinput} +% \end{macrocode} + +% Throughout this file we will use tags defined in \cws. Therefore we +% begin the file with identifying itself and displaying the revision of +% \cws\ for which it is written. Afterwards we change catcode of +% underscore in order to have the same conditions as \cws. +% \begin{macrocode} +\typeout{Extension of cweb style, revision \cwebzwrevision} +\typeout{(if you have an older revision of cweb.sty, please upgrade)} +\catcode`\_=\CatLetter +% \end{macrocode} + +% \section{Extensions} +% \begin{macro}{\C++} +% \begin{macro}{\Cpp} +% \begin{macro}{\CPLUSPLUS/} +% The documentation of \cws\ says that |\C++| may now be used for \Cpp\ +% logo. However, |\C++| is not defined in \cws. The conservative users +% of {\tt ccwebmac.tex} designed by Hans--Hermann Bode might be +% accustomed to |\Cpp| while users of {\tt cwebmac.tex} from {\tt CWEB +% 3.0} might like |\CPLUSPLUS/|. Therefore we supply all three tags and +% moreover make them robust so that they can safely be used in moving +% arguments. +% \begin{macrocode} +\def\p_cpp{C\CwebIncr} +\def\C++{\protect\p_cpp} +\def\Cpp{\protect\p_cpp} +\def\CPLUSPLUS/{\protect\p_cpp} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} + +% \section{Improvements} +% \begin{macro}{\CwebScope} +% If your program contains description of member functions as +% |TListBox::|\-|handleEvent|, the documentation part may easily contain +% lots of overfull boxes. Therefore we try to allow the line break after +% the scope operator. We make the change only if it is not typeset in +% the math mode. The following solution is not perfect. The expression +% ``|::close|'' may be incorrectly split after the scope resolution +% operator. To make a robust macro we should probably fiddle with +% |\lastskip| and |\lastpenalty|. +% \begin{macrocode} +\def\CwebScope{\ifmmode \kern.1em::\kern.1em\else + \kern.1em::\hskip.1em\fi} +% \end{macrocode} +% \end{macro} + +% \subsection{Index appearance} +% When typesetting two or more columns it is more pleasant if the +% columns are balanced. This may easily be achieved with Frank +% Mittelbach's {\tt multicol.sty}. We try whether the style is +% available. +% \begin{macrocode} +\newif\ifhave@multicol +\openin\@ne multicol.sty +\ifeof\@ne \else \have@multicoltrue \fi +\closein\@ne \relax +% \end{macrocode} + +% If we found {\tt multicol.sty}, we use it. It might me nice to delay +% this until we know that the index is really requested. +% \begin{macrocode} +\ifhave@multicol \input{multicol.sty} \fi +% \end{macrocode} + +% \begin{macro}{\CwebIdIndex} +% \begin{macro}{\twocolumn} +% \begin{macro}{\onecolumn} +% We delay the redefinitions of the twocolumn format into the definition +% of |\CwebIdIndex|. If we made the changes globally, we could +% eventually break something in the user's code. + +% I dare say that I do not like the page break in between the index and +% the list of refinements so I do not put it into the redefinition of +% |\onecolumn|. Notice also that the new version of |\onecolumn| +% restores everything for the rare case it is needed somewhere later. +% \begin{macrocode} +\let\orig_CwebIdIndex=\CwebIdIndex +\let\orig_twocolumn=\twocolumn +\let\orig_onecolumn=\onecolumn + +\ifhave@multicol + \def\CwebIdIndex{% + \def\twocolumn{\newpage + \@ifnextchar[{\zw@twocol}{\begin{multicols}{2}}} + \long\def\zw@twocol[##1]{\setbox\cweb_tempbox=\vbox{##1}% + \begin{multicols}{2}[\unvbox\cweb_tempbox]} + \def\onecolumn{% + \let\onecolumn=\orig_onecolumn + \let\twocolumn=\orig_twocolumn} + \orig_CwebIdIndex\cweb@restore_end\end{multicols}} +\fi +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} + +% \begin{macro}{\cweb@restore_end} +% The index is processed after the user supplied |\end{document}| where +% the |\end| tag has unfortunately been redefined. We would always get a +% \LaTeX\ error informing us about unmatched |\begin| and |\end|. +% Therefore we prepare a macro which will be used inside a group to +% restore temporarily the original meaning of |\end|. +% \begin{macrocode} +\let\orig_end=\end +\def\cweb@restore_end{\let\end=\orig_end} +% \end{macrocode} +% \end{macro} + +% \section{Crazy inventions} +% As we can see from the documentation of \cws, it can handle two +% versions of \LaTeX. Older versions of \LaTeX\ are unlikely to be used +% and \LaTeX3 will handle |\end|'s in a different way so the following +% invention does not seem useful. I wrote it mainly as an exercise so +% that I could proudly say with the White Knight from Through the +% Looking Glass, ``It's my own invention.'' + +% \begin{macro}{\cweb@end_tokens} +% When skipping around the |\end{document}| we have to catch the tokens +% which are placed after |\endgroup|. For this purpose we establish a +% new token register. +% \begin{macrocode} +\newtoks\cweb@end_tokens +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\cweb@report_error} +% Before we start the job of catching tokens we prepare some macros. The +% first of them will display our error message. Though we hope that the +% catching algorithm will work with all \LaTeX's currently available, it +% may according to Murphy's Laws happen that someone's obsolete (or +% brand new) \LaTeX\ will break it. We do not want to bother the user +% with strange error messages. We therefore supply ours. The text is +% taken exactly from \cws. The macro will be issued from inside a group +% therefore we take no care about restoring the original definitions. +% \begin{macrocode} +\def\cweb@report_error{\let\orig_errmsg=\errmessage + \def\errmessage##1{% + \errhelp={^^J% +This style depends on an internal implementation detail of LaTeX.^^J% +Sad to note, this detail has changed; you cannot use the cweb style.^^J% +Please type "i\show\end" now. TeX will spit out a few lines of^^J% +definitions and ask again for input. Type "x" then, this will finish TeX.^^J +Then send the log file to the style's author, Joachim Schrod^^J% +(Email: schrod@iti.informatik.th-darmstadt.de). He will adapt cweb.sty^^J% +to the new LaTeX version.^^J} + \orig_errmsg{Sorry, you cannot use the cweb style with this LaTeX version}} +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\cweb@catch_tokens} +% We also prepare the macro which will catch the tokens. This is an +% incomplete assignment to the token register. Its function will be +% explained later. +% \begin{macrocode} +\def\cweb@catch_tokens{\cweb@end_tokens=\bgroup} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\cweb_3_env} +% \begin{macro}{\endcweb_3_env} +% For catching the tokens we will invoke a very special environment with +% the name |cweb_3_env|. \LaTeX\ would complain if the environment were +% undefined. Therefore we place to |\cweb_3_env| everything which is +% needed at the beginning of the catching job and similarly +% |\endcweb_3_env| will contain the trap for the tokens. Notice that we +% have to use |\@namedef| to define tags with such strange names. +% \begin{macrocode} +\@namedef{cweb_3_env}{\cweb@report_error} +\@namedef{endcweb_3_env}{\aftergroup\cweb@catch_tokens} +% \end{macrocode} +% \end{macro} +% \end{macro} + +% \begin{macro}{\cweb@skip_end} +% Now we can catch the tokens and define |\cweb@skip_end| accordingly. +% First we write it and then explain how it works. +% \begin{macrocode} +\begin{cweb_3_env} +{\egroup\end{cweb_3_env}} +\expandafter\def\expandafter\cweb@skip_end\the\cweb@end_tokens{\cweb@check_fi} +% \end{macrocode} +% When we start the environment, \LaTeX\ will invoke our error reporting +% macro. It is invoked inside a group as we have promised. The ending +% command will tell \TeX\ that |\cweb@catch_tokens| should be carried +% out after the end of group. When the group is closed (after some +% checks), the tokens which stem from the expansion of |\end| are not +% executed but stored in our token register. So we have to complete the +% assignment. You might have temptation to just append |\egroup| after +% the statement ending the environment. But beware! This will store +% |\egroup| as the next token in |\cweb@end_tokens|. It will also eat up +% the rest of the file. Fortunately we are redefining \cws\ so that the +% official tags will do the job. We could start catching tokens with +% |\bgroup| which is equivalent to \{ but we must put \} and nothing +% else at the end of the assignment. We solve it by inserting an empty +% group |{\egroup|. This is syntactically correct. In almost all +% contexts \} and |\egroup| are interchangeable. So when \TeX\ scans the +% text, it sees matched braces and when executing the macros it finds +% balanced groups. The definition of |\cweb@skip_end| is now +% straightforward. Isn't it a pretty nonsense code? +% \end{macro} + +% \section{Bug corrections} +% \begin{macro}{\egroup_} +% A funny (and instructive) bug invaded into the definition of +% |\CwebNumber|. This tag is defined in \cws\ where underscore is +% recatcoded to letter. Therefore, what would work in a usual \TeX\ +% context, does not work here. We correct it by defining |\egroup_| +% which will do the correct things. However, there is one more thing +% which should be mentioned. When using NFSS, |\rm| has no effect in the +% math mode. The easiest safe way for switching to roman alphabet from +% inside math is to use |\hbox|. Placing |\,| as done in \cws\ seems +% unpleasant to my eyes therefore I remove it. Please notice that the +% catcode of underscore is restored to the original value within the +% following definition. + +% {\bf Note from Joachim Schrod:}\quad This will not work any more +% since the bug with the underscore has been repaired (one shouldn't +% simply copy plain macros to \LaTeX{} code\,\dots). Nevertheless the +% problem with NFSS remains. But I'm not (yet?)\ convinced that the +% work-around presented here is the adequate solution. So the code is +% here for reference, but it will not be used. + +% \begin{macrocode} +\def\egroup_{\egroup\begingroup + \catcode`\_=\CatUsCode + \let\,=\relax + \def\rm{\reset@font\footnotesize}% + \cweb@egroup} + +\catcode`\_=\CatUsCode +\def\cweb@egroup#1{_{\hbox{#1}}\endgroup} +% \end{macrocode} +% \end{macro} + +% \PrintIndex +% \end{document} +\endinput + diff --git a/Master/texmf-dist/doc/latex/cweb-latex/cweb-conf.pdf b/Master/texmf-dist/doc/latex/cweb-latex/cweb-conf.pdf Binary files differnew file mode 100644 index 00000000000..0978e160863 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/cweb-conf.pdf diff --git a/Master/texmf-dist/doc/latex/cweb-latex/cweb-user.pdf b/Master/texmf-dist/doc/latex/cweb-latex/cweb-user.pdf Binary files differnew file mode 100644 index 00000000000..4e655f848b7 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/cweb-user.pdf diff --git a/Master/texmf-dist/doc/latex/cweb-latex/cwebbase.tex b/Master/texmf-dist/doc/latex/cweb-latex/cwebbase.tex new file mode 100644 index 00000000000..dff1d3494b9 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/cwebbase.tex @@ -0,0 +1,2080 @@ +% $StyleId: cwebbase.doc,v 1.4 1995/11/07 17:55:19 schrod Exp $ +%---------------------------------------------------------------------- +% Written by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>. +% Copyright conditions see below (GPL). + +% +% LaTeX macros cwebbase +% support for incorporation of CWEAVE markup in LaTeX documents +% +% [LaTeX in MAKEPROG] +% (history at end) + + + + +%%%% +%%%% +%%%% These TeX macros were documented with the documentation system +%%%% MAKEPROG and automatically converted to the current form. +%%%% If you have MAKEPROG available you may transform it back to +%%%% the original input: Remove every occurence of three percents +%%%% and one optional blank from the beginning of a line and remove +%%%% every line which starts with four percents. The following lex +%%%% program will do this: +%%%% +%%%% %% +%%%% +%%%% ^%%%\ ? ; +%%%% ^%%%%.*\n ; +%%%% +%%%% If you just want to print the documentation you may fetch +%%%% the archive print-makeprog.tar.Z from ftp.th-darmstadt.de (directory +%%%% pub/tex/latex). It contains *all* used styles -- but beware, they +%%%% may not be in a documented form... +%%%% +%%%% +%%% \documentclass{progltx} + +%%% \usepackage{cweb-doc} % document-specific markup +%%% \usepackage{fullpage} + + +%%% \RCS $StyleRevision: 1.4 $ +%%% \RCS $StyleDate: 1995/11/07 17:55:19 $ + + +%%% \begin{document} + + +%%% \title{Typesetting \cweave{} Output} +%%% \author{% % LaTeX does not discard unnecessary glue... +%%% Joachim Schrod% +%%% \thanks{% +%%% \protect\raggedright +%%% TU~Darmstadt, Computer Science Department, WG Systems Programming, +%%% Alexanderstr.~10, D-64283~Darmstadt, Germany. +%%% Email: \texttt{schrod@iti.informatik.th-darmstadt.de}.% +%%% }% +%%% } +%%% \date{% +%%% Revision \RCSStyleRevision\\ +%%% (as of \RCSStyleDate)% +%%% } + +%%% \maketitle + + +%%% % doesn't work with progltx yet +%%% %\tableofcontents + + + + +%%% \chap Introduction. + +%%% This code shall interpret and render the tag set output by \cweave{}. +%%% That's realized in this module as it's needed in multiple places -- +%%% when we want to use \LaTeX{} markup in \cweb{}, when we want to +%%% incorporate \cweb{} pieces in \LaTeX{} documents (as examples, or in +%%% textbooks), and when we want to incorporate whole \cweb{} documents in +%%% a \LaTeX{} document. (That's by far the most difficult task.) + +%%% As \cweb{} operates in modes, for obvious reasons our implementation +%%% is based on a finite state automaton (FSA). The whole tag set is +%%% separated into subsets that are valid in certain states. + +%%% The complete set of tags does not obey any name conventions, some tags +%%% are even in conflict with standard \LaTeX{} tags (e.g.\ |\\|). Most +%%% tags are used to render code pieces. With the introduction of states +%%% we can restrict the visibilities of these tags to those states where +%%% we typeset program parts. The needed functionality will be available +%%% in cseqs of our namespace, we'll map that to \cweave{}'s names in a +%%% group. + +%%% Then we have to implement the rendering of chunks and sections, that's +%%% (more or less) a straight-forward task. Actually, we only set up the +%%% basic code pieces, the integration of section divisions in the actual +%%% \LaTeX{} document is a task of higher-level code; that integration +%%% depends heavily on the type of document. That also implies that we +%%% won't implement front or back matter material (document markup, table +%%% of contents, index, list of refinements, etc.)\ in this module. + + +%%% \sect Let's identify this module. + +%%% \noindent The code below is explained in the implementation +%%% documentation of the \pkg{rcs} package. + +%%% \beginprog +\begingroup + \def\RCSFile#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesFile{#1}[\date\space\id\space #2]% + } + + \RCSFile{cwebbase.tex}{CWEAVE tags for LaTeX markup} + $StyleDate: 1995/11/07 17:55:19 $: 9999/00/00 \endRCS + $StyleRevision: 1.4 $: 0.0 \endRCS +\endgroup +%%% \endprog + + +%%% \sect This module is part of the supported \textsl{cweb-sty} bundle. +%%% Send bug reports, comments and repairs. + +%%% It assumes that the canonical setup of my modules has happened and can +%%% be used herein. (In particular, the underscore is a letter.) + + +%%% \sect This module reserves the namespace |cwbb|. It assumes that +%%% |\cweb_warning| is bound either to |\PackageWarningNoLine| or +%%% |\ClassWarningNoLine|, depending on the environment. + +%%% \beginprog +\ifx \cwbb@loaded\undefined + \def\cwbb@loaded{$StyleRevision: 1.4 $} +\else + \cweb_warning{cwebbase}% + {Some other package already uses namespace `cwbb'} +\fi +%%% \endprog + + +%%% \sect This is freely distributable 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 software is distributed in the hope that it will be useful, but +%%% \textbf{without any warranty}; without even the implied warranty of +%%% \textbf{merchantability} or \textbf{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 in +%%% the file |License| along with this package; if not, write to the Free +%%% Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA. + + + + +%%% % ------------------------------------------------------------ +%%% % +%%% % subdocument: The interface between CWEAVE and TeX +%%% % + +%%% \input{cweave-spec} + +%%% % +%%% % ------------------------------------------------------------ + + + + +%%% \chap Interface of \pkg{cwebbase} module. + +%%% \pkg{cwebbase} implements most of \cweave{} tags. It sets up tons of +%%% redefinable cseqs, all of them start with |Cweb|. +%%% % +%%% \begin{fixme} +%%% How do I document them? We need a configuration document anyhow. Do +%%% I present here just a list of those cseqs realized in this module +%%% and refer to the config docs? Need to wait until I have it, then +%%% we'll see how the stuff here will be added. +%%% \end{fixme} + + +%%% \sect This module supports both hierarchic and flat section +%%% structuring. You have to bind |\cweb@structure| to 0 (hierarchic) or 1 +%%% (flat) before importing it, to show which structure is wanted. + + +%%% \sect This module supports suppression of different document parts. +%%% You have to define flags |@cweb@suppress@|\<foo>|@| with +%%% $\mbox{\<foo>} \in \{ |changehints|, |unchanged|, |format| \}$ to +%%% denote if suppression shall happen. + + +%%% \sect The counter |secnumdepth| must be~11 if chunks shall be +%%% numbered. That counter doesn't need to be set when this module is +%%% imported, it can be set locally during typesetting \cweb{} code. + +%%% The definitions for flat structure assume that |secnumdepth| is~11 +%%% during typesetting. + + +%%% \sect |\part|, |\chapter| (if available), and |\section| are used for +%%% \cweb{} section divisions (those with the lowest ranks). These +%%% commands will change the respective counters globally and will +%%% add toc lines and marks. You might want to prevent that by redefining +%%% |\addcontentsline| and |\mark|. + +%%% Table of contents macros are not defined for the section divisions +%%% introduced by this module. You must either prevent that they are +%%% written to the |AUX| file at all; or you must define them. +%%% % +%%% \begin{fixme} +%%% Add explanation of introduced section divisions. +%%% \end{fixme} + +%%% For flat structure, all section divisions are of type `|chunk|', like +%%% chunks. The section names start with `|\cwbbRank{|\<rank>|}|'. By +%%% default, |\cwbbRank| takes one argument and expands to the empty list +%%% -- this can be redefined for the table of contents. + + +%%% \sect The document end, as explained in the \cweave{} interface specs +%%% (chunk~\ref{spec:sec:docend}), is not implemented. That must be done +%%% by the user of this module -- if the back matter is to be processed at +%%% all. + + + + +%%% \chap Processing states. + +%%% We have to typeset five different categories of material: +%%% Documentation, program pieces---embedded within the documentation and +%%% as large chunks, \TeX{} material within program pieces (i.e., comments +%%% and refinement names), and cross reference information. Since we need +%%% a complete other environment for the program pieces than for the rest +%%% we design ``states'' where we switch to appropriately. +%%% % +%%% \begin{enumerate} + +%%% \item A chunk starts in the \textsl{documentation state}. + +%%% \item |\B| switches to \textsl{program state}. This can happen in +%%% documentation and program state. + +%%% \item While we process the argument of |\PB| we're in \textsl{restricted +%%% program state}; |\PB| may appear in documentation and in \TeX{} +%%% state. Since \TeX{} state can be switched on within restricted +%%% program state, |\PB| can appear within the argument of itself. + +%%% \item In the arguments of |\C|, |\SHC|, and |\X| we switch to +%%% \textsl{\TeX{} state}. All these cseqs appear only in (restricted) +%%% program state, their official names are actually different. I.e., only +%%% in (restricted) program state these cseq are bound to the meaning +%%% described here. + +%%% \item Cross reference information are attached to most chunks with +%%% refinements. This information is processed in \textsl{CR state}. +%%% After CR state material +%%% comes always the next chunk or the document end, i.e., material in +%%% documentation state. + +%%% \end{enumerate} +%%% % +%%% This FSA is illustrated by the diagram in figure~\ref{fig:fsa}. + +%%% \begin{figure} + +%%% \begin{center} +%%% \chardef\\=`\\ +%%% \input{cweb-fsa.latex} +%%% \end{center} + +%%% \caption{The processing state's FSA. The automaton starts and ends in +%%% the ``documentation'' state.} +%%% \label{fig:fsa} + +%%% \end{figure} + +%%% |\cwbb@documentation| will switch to documentation state, +%%% |\cwbb@program| to program state, |\cwbb@Rprogram| to restricted +%%% program state, |\cwbb@tex| to \TeX{} state, and |\cwbb@CR| to CR state. +%%% If we're already in a state, the switch to this state shall be a +%%% permissible null operation. + + +%%% \sect The basic difference between these states can be named with +%%% two parameters: (1)~The cseq bindings in effect and (2)~the layout +%%% parameters used for paragraph makeup. + +%%% In (restricted) program state and in CR state the text is output +%%% under the control of \cweave{}, and tagged by \cweave{}. The used +%%% tags are from a global namespace and should only be in effect during +%%% these states. We call this tag set the \textsl{\cweave{} bindings}. In the +%%% other two states the tags are largely defined by the user, the tag +%%% set is called the \textsl{user bindings}. The switch to another binding +%%% is always done locally, i.e., if we switch from documentation to +%%% restricted program state within a group we don't have to bother about +%%% the restauration of the user binding; it will be done automatically +%%% by \TeX{} at the end of the group. Nevertheless we must be able to +%%% switch from the \cweave{} bindings back to the user bindings which +%%% were in effect when we activated the \cweave{} bindings. This is +%%% needed for the \TeX{} state which is always activated within +%%% (restricted) program state. + +%%% The parameters for \textsl{program layout} are really special ones +%%% since they need to support the indentation which shows the program +%%% structure. These parameters are used in program and in \TeX{} state. +%%% The \textsl{document layout} parameters established by the user are +%%% used in the other three states. + +%%% The following table shall summarize this. $C$~denotes \cweave{} +%%% bindings, $U$~user bindings, $P$~program layout, and $D$~document +%%% layout. If an entry is empty, its value is not changed on entry in +%%% this state. +%%% % +%%% \begin{center} +%%% \DeleteShortVerb\| +%%% \begin{tabular}{r|c|c} +%%% \multicolumn1{c|}{\textsc{State}} & \textsc{Binding} & \textsc{Layout} \\[1pt] +%%% \hline +%%% documentation & $U$ & $D$ \\ +%%% program & $C$ & $P$ \\ +%%% restricted program & $C$ & \\ +%%% \TeX{} & $U$ & \\ +%%% CR & $C$ & $D$ \\ +%%% \end{tabular} +%%% \MakeShortVerb\| +%%% \end{center} + + +%%% \sect Since the user bindings and the document layout is defined +%%% initially, we don't have to do anything if it's requested. Only if we +%%% change it, i.e., within |\cwbb@cweave_bindings| and +%%% |\cwbb@program_layout|, we redefine |\cwbb@user_bindings| and +%%% |\cwbb@doc_layout|. If they are eventually executed, they shall +%%% rebind themselves back to |\relax|. This way we can switch to +%%% documentation state as often as we want. + +%%% \beginprog +\let\cwbb@user_bindings=\relax +\let\cwbb@doc_layout=\relax + +\def\cwbb@documentation{% + \cwbb@user_bindings + \cwbb@doc_layout + } +\def\cwbb@Rprogram{\cwbb@cweave_bindings} + +\def\cwbb@program{% + \cwbb@cweave_bindings + \cwbb@program_layout + } +\def\cwbb@tex{\cwbb@user_bindings} + +\def\cwbb@CR{% + \cwbb@cweave_bindings + \cwbb@doc_layout + } +%%% \endprog + + + + +%%% \chap Saving and restoring control sequences. + +%%% We have a lot of cseqs which are defined within the namespace of this +%%% module and which will be used with other names. This usage is in a +%%% controlled environment, namely neither in documentation nor in \TeX{} +%%% state. (I.e., the text processed is tagged by \cweave{}, not by humans; +%%% therefore we have a precise specification of the cseqs we have to +%%% accept.) We cannot work with groups where a cseq is just redefined +%%% and \TeX{} takes care for establishing the old binding again; when we +%%% switch from program state to \TeX{} state all the bindings which were +%%% in effect before the program state get active, i.e., in the +%%% documentation state, must be in effect again. We cannot simply +%%% consider the \TeX{} state as something parallel to program state, it +%%% must be a hierarchical relationship: In the program state values are +%%% set up which must be available after switching back from \TeX{} to +%%% program state. + +%%% We save the current binding of a cseq in another cseq, but only if +%%% there exists a binding currently. This is done to save valuable +%%% \TeX{} main memory. (Why don't all those people who talk about +%%% extending \TeX{} not just implement dynamic memory management for the +%%% existing \TeX{}? It would still be \TeX{} and would \emph{really} be +%%% a worthy activity. But not enough fun, I assume\,\dots) Actually, one +%%% can assume that nearly no cseq bindings must be saved at all---the +%%% used names are strange enough. The bindings of |\foo|, i.e., of the +%%% cseq with the name \fbox{\ttfamily foo}, is saved as the cseq with the +%%% name \fbox{\ttfamily cweb\char `\\ foo}, i.e., as +%%% |\csname cweb\string\foo \endcsname|. + + +%%% \sect The save process is not done statically, but by the macro +%%% |\cwbb@rebind| which interprets a list of tuples $({\it old\_name}, +%%% {\it new\_name})$, terminated by the tuple $(|\stop|, |\stop|)$. +%%% Eventually it constructs two new lists, |\cwbb@to_restore| with the +%%% cseqs which had a binding, and |\cwbb@undefined| with the names which +%%% didn't have one. + +%%% The saving is actually done by |\cwbb@save_binding|, |\cwbb@rebind| +%%% is responsible for the initialization, |\cwbb@do_rebind| for the +%%% effective rebinding and the tail recursion on the list. + +%%% \begin{fixme} +%%% We could pull the |\next| assignment in the |\else| branch out of +%%% the loop to get a better performance. Should measure if this is of +%%% interest. +%%% \end{fixme} + +%%% \beginprog +\newtoks\cwbb@undefined +\newtoks\cwbb@to_restore + +\def\cwbb@rebind{% + \cwbb@undefined{}% + \cwbb@to_restore{}% + \cwbb@do_rebind + } +\def\cwbb@do_rebind#1#2{% + \ifx #1\stop + \let\next\relax + \else + \cwbb@save_binding #2% + \let #2=#1% + \let\next\cwbb@do_rebind + \fi + \next + } +%%% \endprog + + +%%% \sect If the cseq to be saved is undefined, it may just be added to +%%% the ``undefined list.'' Otherwise its binding is saved and it's added +%%% to the ``to-be-restored list.'' + +%%% \TeX{}nical note: The cseq-name for the saved binding must be created +%%% before the |\let| is executed. + +%%% \beginprog +\def\cwbb@save_binding#1{% + \ifx #1\undefined + \cwbb@undefined \expandafter{\the\cwbb@undefined #1}% + \else + \expandafter\let \csname cweb\string#1\endcsname =#1% + \cwbb@to_restore \expandafter{\the\cwbb@to_restore #1}% + \fi + } +%%% \endprog + + +%%% \sect The restoration of rebound cseqs is a two-tied activity: All +%%% previously undefined cseqs must be made undefined again, and all saved +%%% cseqs must be restored. Actually, we don't need to reset the two token +%%% lists, but we do it to save space. + +%%% Both |\cwbb@undefine| and |\cwbb@restore_binding| iterate over a list +%%% of cseqs terminated by |\stop|. + +%%% \begin{fixme} +%%% And here the |\next| assignment could be prepended to the loop as +%%% well. +%%% \end{fixme} + +%%% \beginprog +\def\cwbb@restore_bindings{% + \expandafter\cwbb@undefine \the\cwbb@undefined \stop + \cwbb@undefined{}% + \expandafter\cwbb@restore_binding \the\cwbb@to_restore \stop + \cwbb@to_restore{}% + } + +\def\cwbb@undefine#1{% + \ifx #1\stop + \let\next\relax + \else + \let#1\undefined + \let\next\cwbb@undefine + \fi + \next + } +%%% \endprog + + +%%% \sect \TeX{}nical note: As in |\cwbb@save_binding|, the cseq-name for +%%% the saved binding must be created before the |\let|s are executed. + +%%% \begin{fixme} +%%% Another |\next| assignment. +%%% \end{fixme} + +%%% \beginprog +\def\cwbb@restore_binding#1{% + \ifx #1\stop + \let\next\relax + \else + \expandafter\let \expandafter#1\csname cweb\string#1\endcsname + \expandafter\let \csname cweb\string#1\endcsname \undefined + \let\next\cwbb@restore_binding + \fi + \next + } +%%% \endprog + + + + +%%% \chap Chunks. + +%%% All chunks are numbered subsequently. The chunk number is supplied as +%%% part of the markup. In addition, the `changed' tag |\*| may be +%%% appended to the chunk number. + +%%% By default, chunks have approximately two picas vertical space in +%%% front. + +%%% If we use an hierarchic structure, we output the chunk number at the +%%% refinement. (It's only needed to identify the refinement for cross +%%% references.) But chunks are important structural units and thus should +%%% be marked by typographic means that's more visible than the space +%%% mentioned above, we add a `chunk start marker'. + +%%% For a flat structure, we output the chunk number as the chunk start +%%% marker, that is the traditional \WEB{} layout. + +%%% In any case, the documentation part shall be run in after the chunk +%%% start marker. + +%%% \beginprog +\newskip\CwebChunkPreSkip + \CwebChunkPreSkip=2pc plus 1pc minus 6pt +%%% \endprog + + +%%% \sect In \LaTeX{}, structural divisions are best realized by +%%% |\@startsection|, we'll use it also for chunk starts. The chunk start +%%% marker is the section heading. For hierarchic structure, we use a +%%% traditional paragraph sign, used since medieval times to tag new text +%%% units. Our first test showed that the paragraph sign has typically an +%%% underlength, that doesn't look good at the start of a chunk. We raise +%%% the sign by its depth. + +%%% For flat structure, we don't have text as the section heading, +%%% but we have to cope for a deficiency of \LaTeX{}: It always leaves a +%%% quad after the section number (by the way, this is not mentioned in +%%% the documentation---you have to look in the macros to figure this +%%% out). So we use a backskip of $\rm -1\,em$ as the chunk start marker +%%% then. + +%%% Changed chunks are marked by a changeflag, by default a star lapping +%%% to the right. We need the information if that chunk is changed to +%%% decide if we shall output the changeflag. We demand from the chunk +%%% macros that they record that info in the flag |@cwbb_changed_chunk@|. + +%%% Each structural division must be categorized, it belongs to a +%%% \textsl{type}. This type determines also the name of the counter, the +%%% mark handling for this category, and how this section tag is +%%% represented in the table of contents. The type of chunks is `|chunk|' +%%% (trivial, isn't it?). + +%%% Furthermore, a structural division in \LaTeX{} has an associated +%%% \textsl{level}. That level is used to determine if that division get +%%% numbered in text or table of contents. For sections, we'll compute the +%%% level from the rank, it will not be larger than the rank.% +%%% \footnote{Check the next section for a more precise definition of +%%% `rank' and `level'.} +%%% Since the highest section rank is~10, we may use 11 as chunk level. + +%%% For flat structure, we output the number for all section headings, +%%% including chunks. For hierarchic structure we use the default maximum +%%% level as supplied by our document class (e.g., 3~for \cls{article}, +%%% and 2~for \cls{report} or \cls{book}). + +%%% As a last point, we have to care already for sections in flat +%%% structure. They will use the |chunk| category as well, we have to +%%% distinguish them in the table of contents. For that, we'll record the +%%% level in the text, it will get written to the table of contents. + +%%% \beginprog +\newif\if@cwbb_changed_chunk@ +\let\CwebChangeFlag=* +\if@cweb@suppress@changehints@ + \let\cwbb@change_flag=\relax +\else + \let\cwbb@change_flag=\CwebChangeFlag +\fi +\def\cwbb@lap_change_flag{\rlap{\cwbb@change_flag}} + +\ifcase \cweb@structure + %% hierarchic + \let\CwebChunkHeadingStyle\relax + \newbox\cweb@chunk_marker + \setbox\cweb@chunk_marker=\hbox{\P} % tradition from medivial times + \setbox\cweb@chunk_marker=\hbox{% + \raise\dp\cweb@chunk_marker \box\cweb@chunk_marker + } + \def\CwebChunkHeadingMarker{\copy\cweb@chunk_marker} + \def\CwebChunkHeading#1{% + \CwebChunkHeadingMarker + \if@cwbb_changed_chunk@ \cwbb@lap_change_flag \fi + } + \or + %% flat + \def\cwbbRank#1{} + \def\CwebChunkHeadingStyle{\bfseries} + \def\CwebChunkHeading#1{% + \protect\cwbbRank{#1}% + \kern -1em + \if@cwbb_changed_chunk@ \cwbb@lap_change_flag \fi + } +\fi +%%% \endprog + + +%%% \sect Chunks are tagged with |\M| and get passed the chunk number as +%%% argument. Before we evaluate |\@startsection|, we'll start the chunk. +%%% That's common code to be used by sections as well, as they also +%%% implicitely start a chunk. + +%%% \beginprog +\def\M#1{% + \cwbb@start_chunk{#1}% + \@startsection + {chunk}% % category, == counter etc. + {11}% % level + {\z@}% % no indentation for heading + {\CwebChunkPreSkip}% % skip above heading + {\m@ne em}% % run-in heading, 1em distance to text + {\normalfont\CwebChunkHeadingStyle}% % layout + {\CwebChunkHeading{11}}% % text, level might go to toc file + } +%%% \endprog + + +%%% \sect But let's first declare how a chunk number is represented. The +%%% principle rendering is controlled by |\thechunk|, namely, we get +%%% arabic numbers. This rendering is used both for creation of the +%%% section header (if in flat mode) and for cross references. I.e., +%%% |\ref| expands into it. + +%%% But for flat structure we need different expansions: In the section +%%% header a period shall be appended, a cross reference shall appear +%%% without such a period. We use two different macros: |\thechunk| +%%% creates the number with the period, |\cwbb@refchunk| only the number. +%%% The latter is used for a redefinition of |\@currentlabel|. Of course, +%%% for hierarchic structure, both are the same. + +%%% \beginprog +\newcounter{chunk} + +\def\cwbb@refchunk{\arabic{chunk}} + +\ifcase \cweb@structure + %% hierarchic + \let\thechunk=\cwbb@refchunk + \or + %% flat + \def\thechunk{\arabic{chunk}.} +\fi +%%% \endprog + + +%%% \sect Each chunk is started by |\cwbb@start_chunk|, which does the +%%% common actions. First of all, we switch to documentation state. + +%%% Then we store the chunk number in the |chunk| counter. That implies +%%% that the chunk start must not step this counter! We'll take care for +%%% that later by redefining |\refstepcounter|. The actual number is +%%% passed as the argument, including an optional |\*| used to denote +%%% changed chunks. We'll redefine that cseq to update the flag +%%% |@cwbb_changed_chunk@|. + +%%% Each chunk must be typeset with an open |\if| since it is finished by +%%% |\fi|. If we shall suppress the output of unchanged chunks, we have +%%% to use |\iffalse| if not |@cwbb_changed_chunk@|, otherwise |\iftrue|. +%%% The flag |@cwbb_print_chunk@| is set up to provide an appropriate +%%% test. + +%%% When we typeset a chunk, we evaluate |\cwbb@init_print_chunk|. For +%%% hierarchic structure, that cseq will be used to initialize the +%%% typesetting of the chunk number at program parts. + +%%% \beginprog +\if@cweb@suppress@unchanged@ + \def\if@cwbb_print_chunk@{\if@cwbb_changed_chunk@} + \@gobble\fi % close \if in case it's skipped +\else + \let\if@cwbb_print_chunk@=\iftrue + \@gobble\fi % same here +\fi + +\def\cwbb@start_chunk#1{% + \cwbb@documentation + \begingroup + \def\*{\global\@cwbb_changed_chunk@true}% + \global\@cwbb_changed_chunk@false + \global \c@chunk #1\relax % might expand \* + \endgroup + \if@cwbb_print_chunk@ + \cwbb@init_print_chunk + } +%%% \endprog + + +%%% \sect |\@startsection| will step the section counter (i.e., |chunk|). +%%% Since we just assigned it in |\cwbb@start_chunk|, that would leave us +%%% with a counter that's one too high. And our output in cross references +%%% may be wrong, as a period is appended in flat structure. + +%%% That damage all comes from one macro, |\refstepcounter|; let's +%%% advice it to do the Right Thing for |chunk| counters. + +%%% \beginprog +\let\cwbb@refstepcounter=\refstepcounter + +\def\cwbb@string@chunk{chunk} +\def\refstepcounter#1{% + \def\@tempa{#1}% + \ifx \@tempa\cwbb@string@chunk + \protected@edef\@currentlabel{\cwbb@refchunk}% + \else + \cwbb@refstepcounter{#1}% + \fi + } +%%% \endprog + + + + +%%% \chap Sections. + +%%% Important sections are started on a new page, normal sections have the +%%% same space as chunks in front. The very first section does not +%%% automatically start on a new page since a title may be in front of it. + +%%% Each section division has a \textsl{rank}, that denotes the section +%%% depth as seen by \cweave{}. + +%%% For this depth we compute a \textsl{level}, used to denote the section +%%% depth for \LaTeX{}. This section depth is used to decide where +%%% numbering shall stop, or if that entry shall be presented in the table +%%% of contents, etc. + +%%% These two numbers are not the same, due to the support of document +%%% classes with chapters. + +%%% We consider a section as important if it's rank is smaller than~3, +%%% i.e., then we'll start a new page. This limit is controlled by the +%%% number |\CwebRankNoEject|. The rank is used as the section level +%%% and is therefore available to configure depth of typeset numbering and +%%% appearance in table of contents. + +%%% \beginprog +\def\CwebRankNoEject{3} +%%% \endprog + + +%%% \sect Sections are started with the macro |\N|. It's first parameter +%%% is the section's rank. The second parameter is the chunk number, the +%%% third the title of the section. This last parameter must be terminated +%%% by a dot. + +%%% Each section implicitly starts a chunk. As explained above, major +%%% sections may eject the page, and we add our actual section heading +%%% with |\CwebSection|. + +%%% We also tell the user that we have reached the next section by telling +%%% him about the current chunk number. The message is output after the +%%% section header is set, it shall be on the correct page. Since the +%%% token list to be output is expanded at shipout time, we must take care +%%% for the immediate expansion ourselves. + +%%% \beginprog +\def\N#1#2#3.{% + \cwbb@start_chunk{#2}% + \CwebEjectSection{#1}% + \CwebSection{#1}{#3}% + \begingroup + \def\*{}% + \edef\tmp{*#2}% + \message \expandafter{\tmp}% + \endgroup + } +%%% \endprog + + +%%% \sect At the start of a section we usually eject the page if our rank +%%% is not too low. But if the user had a title above the first section, +%%% he won't want this page break. So we try to guess it. If we guess +%%% wrong, the user may either add |\newpage| himself or he may redefine +%%% |\CwebEjectSection| in a package. + +%%% \beginprog +\def\CwebEjectSection#1{% % #1 == rank + \gdef\CwebEjectSection##1{% + \relax + \ifnum ##1<\CwebRankNoEject\relax + \newpage + \fi + }% + } + +\if@titlepage + \CwebEjectSection{} +\fi +%%% \endprog + + +%%% \sect Now comes a heary piece. We have 11~section ranks, and need 11 +%%% different section categories, section counters, etc. For flat +%%% structure, they shall all do the same; for hierarchic structure, they +%%% shall be really different. + +%%% \noindent Let's have a look at the hierarchic structure first, it's +%%% more complex. +%%% % +%%% \begin{itemize} + +%%% \item We associate section rank~0 (that's `|@**|') with document +%%% parts, i.e., map it to |\part|. Many smaller programs won't use it. + +%%% \item If we are used in a class that has a bound cseq |\chapter|, we +%%% associate rank~1 (`|@*0|') with it and rank~2 (`|@*1|') with +%%% |\section|. Otherwise we associate rank~1 with |\section|. These +%%% tags (|\chapter| and/or |\section|) must be defined because many +%%% macros that want to create section divisions will use them. + +%%% \item All other section ranks are placed below |\section|. +%%% |\subsection| and other \LaTeX{} style markup is not supported. + +%%% For hierarchic structure, we identify these sections with category +%%% names `|section|$l$', where $l$ is the respective level, computed +%%% from the rank. Those section names do not exist yet, we have to +%%% create them. + +%%% \end{itemize} + +%%% Now we come to the point why we can't use the rank as the section +%%% level passed to \LaTeX{}: When we assume the level usage of \LaTeX{}'s +%%% standard classes, |\section| is \emph{always} on level~1, independent +%%% of the existence of |\chapter|. The latter is placed on level~0, its +%%% existence only influences the section level of |\part|, which is +%%% either $-1$ or~0. + +%%% This implies that |\subsection| in a standard class is always on +%%% level~2, but our equivalent section division is either `|@*0|' +%%% (rank~1) or `|@*1|' (rank~2). I.e., when we have chapters, we use a +%%% level that's one lower than the rank, otherwise we use the rank. + +%%% For flat structure, we use type |chunk|. This way we'll use the chunk +%%% numbers, they are already set up. + +%%% For flat structure, we will map all ranks to the same section markup. +%%% This markup will also be accessible by |\section| or |\chapter|. They +%%% will be declared to be on a level that is the same as the rank. + + +%%% \sect The printed representation of a section divison number is simply +%%% the presentation from the next upper level, a full stop, and an arabic +%%% section number. When we compute the name of the previous level we must +%%% pay attention to our first section division created this way. This +%%% division must be placed below |section|, without any following number. + +%%% Since registers are a valuable resource in \TeX{}, we have to take +%%% care not to allocate a superfluous one. + +%%% \beginprog +\ifcase \cweb@structure + %% hierarchic + \newcounter{section2}[section] + \@namedef{thesection2}{\@nameuse{thesection}.\arabic{section2}} + \newcounter{section3}[section2] + \@namedef{thesection3}{\@nameuse{thesection2}.\arabic{section3}} + \newcounter{section4}[section3] + \@namedef{thesection4}{\@nameuse{thesection3}.\arabic{section4}} + \newcounter{section5}[section4] + \@namedef{thesection5}{\@nameuse{thesection4}.\arabic{section5}} + \newcounter{section6}[section5] + \@namedef{thesection6}{\@nameuse{thesection5}.\arabic{section6}} + \newcounter{section7}[section6] + \@namedef{thesection7}{\@nameuse{thesection6}.\arabic{section7}} + \newcounter{section8}[section7] + \@namedef{thesection8}{\@nameuse{thesection7}.\arabic{section8}} + \newcounter{section9}[section8] + \@namedef{thesection9}{\@nameuse{thesection8}.\arabic{section9}} + \ifx \chapter\undefined + \newcounter{section10}[section9] + \@namedef{thesection10}{\@nameuse{thesection9}.\arabic{section10}} + \fi +\fi +%%% \endprog + + +%%% \sect Sections are typeset by |\CwebSection|; rank and title are the +%%% arguments. + +%%% For hierarchic structure, we select the proper cseq according to rank: +%%% |\part|, |\chapter| if this is a structure with chapters, |\section|, +%%% and |\cwbb@section{|\<rank>|}| for other ranks. For the last cseq we +%%% also have to supply the section category, it's `|section|$l$' where +%%% $l$ is the rank~$r$ if we don't have chapters, $r-1$ otherwise. + +%%% That category cannot be computed by |\cwbb@section| itself since we +%%% want to use that macro also for flat structure. But there all sections +%%% are basically chunks, we have to use the |chunk| category there. Since +%%% we want to differentiate them in the table of contents nevertheless, +%%% we record the current rank in the title. + +%%% \beginprog +\ifcase \cweb@structure + %% hierarchic + \ifx \chapter\undefined + \def\CwebSection#1#2{% + \ifcase #1 + %% 0 + \let\next\part + \or %% 1 + \let\next\section + \else %% level = rank + \def\cwbb@sect_name{section#1}% + \def\next{\cwbb@section{#1}}% + \fi + \next{#2}% + } + \else + \def\CwebSection#1#2{% + \ifcase #1 + %% 0 + \let\next\part + \or %% 1 + \let\next\chapter + \or %% 2 + \let\next\section + \else %% level = rank - 1 + \count@=#1 \advance \count@\m@ne + \edef\cwbb@sect_name{section\number\count@}% + \edef\next{\noexpand\cwbb@section{\number\count@}}% + \fi + \next{#2}% + } + \fi + \or + %% flat + \def\CwebSection#1#2{% + \def\cwbb@sect_name{chunk}% + \cwbb@section{#1}{\protect\cwbbRank{#1}#2}% + } + \def\section{% + \def\cwbb@sect_name{chunk}% + \cwbb@section{1}% + } +\fi +%%% \endprog + + +%%% \sect We use the same layout for all minor sections. That layout can +%%% be changed by ammended by defining |\CwebSect|$r$|Hook| to redefine +%%% |\CwebSectPreSkip| and/or |\CwebSectLayout| locally. (Of couse, it may +%%% be redefined once globally, too.) These are the values to be used for +%%% arguments 4 and~5 of |\@startsection|, pay attention to the skip sign, +%%% telling about indentation of the first paragraph. And don't forget +%%% that the skip is only used for sections on ranks below +%%% |\CwebRankNoEject|, the others start on a new page anyhow. + +%%% The default definition sets the section title in bold and leaves the +%%% same space as before chunks. The first paragraph of the following +%%% documentation has no indentation. + +%%% Other layout changes (indentation for heading, etc.)\ must be made by +%%% redefining |\cwbb@section|. Or---email me, if you want to do it. Then +%%% I might be enclined to introduce further possibilities. + +%%% \beginprog +\newskip\CwebSectPreSkip + \CwebSectPreSkip = -\CwebChunkPreSkip +\def\CwebSectLayout{\normalfont\bfseries} + +\def\cwbb@section#1{% % #2 (next token) is title + \csname CwebSect#1Hook\endcsname % \relax if undefined + \expandafter\@startsection + \expandafter{\cwbb@sect_name}% % category; for counter, etc. + {#1}% % level is rank + \z@ % no indentation for heading + \CwebSectPreSkip % skip above, maybe no next par indent + \medskipamount % skip below heading + \CwebSectLayout + } +%%% \endprog + + + + +%%% \chap Marks. + +%%% \begin{fixme} +%%% Since I don't know yet how to handle marks I ignore most of them for +%%% the time being. + +%%% Have to change this later. +%%% \end{fixme} + +%%% \beginprog +\let\chunkmark\@gobble + +\count@=2 +\@whilenum \count@<11 \do { + \expandafter\let \csname section\number\count@ mark\endcsname \@gobble + \advance \count@ by 1 + } +%%% \endprog + + + + +%%% \chap Typesetting programs. + +%%% Program pieces come in two flavours: as argument of |\PB|, or as +%%% material after |\B|. In the former case we can use a group for the +%%% switch to the restricted program state, the group end will restore the +%%% previous state again. In the latter case we use |\B| for the switch to +%%% program state, the cross reference list or the next chunk will go to +%%% another state. Since we have to do more for the material after |\B|, +%%% we define this cseq later. + +%%% \beginprog +\def\PB#1{% + \begingroup + \cwbb@Rprogram + \leavevmode + #1% + \endgroup + } +%%% \endprog + + +%%% \sect Note, that |\Y| cannot just be |\smallskip|, as in Plain +%%% \cweb{}. We must assert that the current paragraph is ended before the +%%% vertical glue is inserted, and that's not done by the \LaTeX{} +%%% definition of |\smallskip|. In addition we add some negative penalty, +%%% here is a good place for a page break. As the penalty value we use +%%% half the chunk break penalty---of course a chunk start is an even +%%% better place for a page break\,\dots + +%%% It might be that |\Y| is the very first token in a chunk. Then the +%%% chunk start marker isn't set already since it is regarded as a run-in +%%% section heading. In that case we don't set the vertical skip but +%%% simply start the chunk with the program part. + +%%% \TeX{}nical note: The flag |@noskipsec| may be used to test if we're +%%% immediately after a run-in section heading. + +%%% \beginprog +\newcount\CwebProgPenalty + \CwebProgPenalty=\@secpenalty + \divide\CwebProgPenalty by 2 +\def\Y{% + \if@noskipsec + \else + \par + \penalty\CwebProgPenalty + \smallskip + \fi + } +%%% \endprog + + +%%% \sect Yep, let's unfold the ``official'' names of the cseqs used in +%%% program state. + +%%% If we turn on the \cweave{} bindings, they might be in effect already, +%%% we don't need to establish them again. We can test +%%% |\cwbb@user_bindings| for this case, it will be redefined then. + +%%% \beginprog +\def\cwbb@cweave_bindings{% + \ifx \cwbb@user_bindings\relax + \cwbb@rebind + % indentation and paragraph layout + \cwbb@incr_indent \1% + \cwbb@decr_indent \2% + \cwbb@expr_break \3% + \cwbb@backup \4% + \cwbb@opt_break \5% + \cwbb@break \6% + \cwbb@big_break \7% + \cwbb@noindent \8% + % C/C++ tokens + \CwebRel \?% + \CwebAddress \AND + \CwebComplement \CM + \CwebScope \DC + \CwebEquiv \E + \CwebGe \G + \CwebRightShift \GG + \CwebNe \I + \CwebAssign \K + \CwebLeftShift \LL + \CwebMod \MOD + \CwebNull \NULL + \CwebNot \R + \CwebBinOr \OR + \CwebMemberRef \PA + \CwebThis \this + \CwebOr \V + \CwebAnd \W + \CwebXor \XOR + \CwebLe \Z + \CwebPointer \MG + \CwebPointerMemberRef \MGA + \CwebDecr \MM + \CwebIncr \PP + % more tokens + \CwebId \\% + \CwebIdLetter \|% + \CwebRes \&% + \CwebString \.% %% ( ...Emacs... + \CwebStringBreak \)% + \CwebNumber \T + \CwebCombinedOp \MRL + % goes to TeX state + \CwebComment \C + \CwebCxxComment \SHC + \CwebRefName \X + % CWEB tokens + \CwebMacrosHere \ATH + \CwebDefine \D + \cwbb@format \F + \CwebIdCat \J + \CwebVerbString \vb + % cross reference tags + \cwbb@change_flag \*% + \CwebCRAlso \A + \CwebCRsAlso \As + \CwebCRCite \Q + \CwebCRsCite \Qs + \CwebCRUse \U + \CwebCRsUse \Us + \CwebCREt \ET + \CwebCRsEt \ETs + % finish the list + \stop\stop + \def\cwbb@user_bindings{% + \cwbb@restore_bindings + \let\cwbb@user_bindings\relax + }% + \fi + } +%%% \endprog + + +%%% \sect Since most of the \cweave{} bindings are simple and tedious +%%% coding, we'll have a look at the program layout next. Between two +%%% paragraphs there must not be any skip, the skip used in document +%%% layout is saved in |\cwbb@save@parskip|. A few other layout +%%% parameters from the document layout must be saved as well. + +%%% \beginprog +\newskip\cwbb@save@parskip +\newskip\cwbb@save@rightskip +\newcount\cwbb@save@sem_sfcode +\newcount\cwbb@save@pretolerance +\newcount\cwbb@save@hyphenpenalty +\newcount\cwbb@save@exhyphenpenalty + +\def\cwbb@save_doc_layout{% + \cwbb@save@parskip\parskip + \cwbb@save@rightskip\rightskip + \cwbb@save@sem_sfcode\sfcode`\; + \cwbb@save@pretolerance\pretolerance + \cwbb@save@hyphenpenalty\hyphenpenalty + \cwbb@save@exhyphenpenalty\exhyphenpenalty + } +\def\cwbb@restore_doc_layout{% + \parskip\cwbb@save@parskip + \rightskip\cwbb@save@rightskip + \sfcode`\;=\cwbb@save@sem_sfcode + \pretolerance\cwbb@save@pretolerance + \hyphenpenalty\cwbb@save@hyphenpenalty + \exhyphenpenalty\cwbb@save@exhyphenpenalty + } +%%% \endprog + + +%%% \sect When |\cwbb@program_layout| is called for the very first time +%%% we have to set up some variables. This cannot be done in advance +%%% since they depend on values which might be changed by the user in the +%%% preamble. This setup is done in |\cwbb@layout_init|. + +%%% If the program layout is already active, we must not switch it on +%%% another time. This can be tested by the current binding of +%%% |\cwbb@doc_layout|. + +%%% \beginprog +\def\cwbb@program_layout{% + \ifx \cwbb@doc_layout\relax + \cwbb@layout_init + \cwbb@save_doc_layout + \def\cwbb@doc_layout{% + \cwbb@restore_doc_layout + \let\cwbb@doc_layout\relax + }% + % set new values + \parskip\z@skip + \rightskip\z@ plus 100\p@ minus 10\p@ + \sfcode`\;=3000 + \pretolerance\@M + \hyphenpenalty 1000 % strings can be broken this way + \exhyphenpenalty\@M + \fi + } +%%% \endprog + + +%%% \sect The unit of the basic indentation is stored in +%%% |\CwebIndentUnit|. Continuation lines are indented two units further, +%%% i.e., the initial hanging indentation is 3~units. The current hanging +%%% indentation is kept in |\cwbb@indent|. + +%%% We need undiscardable items which can be used as backspaces, of one +%%% and two units, respectively. This is done best by boxes. The +%%% initialization of the boxes must be postponed until the user had the +%%% chance to change |\CwebIndentUnit|, it's done in the program state +%%% initialization. + +%%% \beginprog +\newdimen\CwebIndentUnit + \CwebIndentUnit=1em +\newdimen\cwbb@indent + +\newbox\cwbb@bak % backspace one unit +\newbox\cwbb@bakk % backspace two units + +\def\cwbb@layout_init{% + \global\setbox\cwbb@bak \hbox to -1\CwebIndentUnit{}% + \global\setbox\cwbb@bakk \hbox to -2\CwebIndentUnit{}% + \global\let\cwbb@layout_init\relax + } +%%% \endprog + + +%%% \sect Now we can formulate how to start typesetting program pieces: We +%%% switch to program state, set the initial indentation, and add the +%%% basic indentation of the first code line. Then we might add a marker +%%% to this program part; for hierarchic structure we want to typeset the +%%% chunk number in the margin of the chunk's program part. That's not +%%% really possible, 'though: definitions and format requests are also +%%% introduced with |\B|, so the chunk number will happen to be at the +%%% start of the definition part if one exists. + +%%% If the code line is the very first text to be typeset in this chunk, +%%% we don't add the basic indentation---we're already indented from the +%%% run-in chunk start marker. But we must not start our chunk with +%%% |\noindent|, the marker would be typeset in the left margin then. (I +%%% consider this as a \LaTeX{} error.) So we just emulate an empty +%%% documentation part, the marker is now set correctly. |\B| can test for +%%% this case: |@noskipsec| is still true then. + +%%% \beginprog +\def\B{% + \cwbb@program + \cwbb@indent 3\CwebIndentUnit \hangindent\cwbb@indent + \ifvmode + \if@noskipsec + \indent % add an empty documentation part + \else + \noindent \kern\CwebIndentUnit + \fi + \fi + \CwebNumberProgramPart + } +%%% \endprog + + +%%% \sect The chunk number shall be added at the first program part. We +%%% have a hook in the chunk start where we can set up +%%% |\CwebNumberProgramPart|. It will redefine itself at first call, to +%%% disable further output on more |\B| occurences in a chunk. + +%%% The chunk number should always be in the left margin. If it's in the +%%% right margin, there would be too much horizontal space between the +%%% code start and the actual number. (The first code line is typically +%%% not very long.) \LaTeX{} does not allow to select the margin for +%%% marginpars, therefore we have to typeset the marginal note `by hand'. +%%% As we know that we're in horizontal mode when we're called, |\vadjust| +%%% is used to create the note. The standard \LaTeX{} dimen register for +%%% the distance between marginal notes and text matter is used, of +%%% course. + +%%% Note that marginal notes may overwrite the chunk number. As it's very +%%% unlikely that somebody issues marginal notes in program mode (that's +%%% quite difficult and involves ingenious usage of the implementation of +%%% this macros), I won't care for that case. + +%%% \begin{fixme} +%%% The baseline of the marginal note shall be aligned to the baseline +%%% of the preceding line. That does not happen by default. Currently, I +%%% assume that the preceding line has a depth of appropriately the +%%% depth of a~`g'. Experiments showed that this gives good results for +%%% most \cweb{} documents. But nevertheless one should determine the +%%% exact depth of the preceding line, to know how much |box0| should be +%%% raised. If anybody knows how this can be done, please tell me. (I +%%% know about the route over the output routine, implementing an own +%%% marginal note category, but this seems too much effort.) +%%% \end{fixme} + +%%% For flat structure, we don't add any program part marker and we +%%% don't need to initialize it. + +%%% \beginprog +\ifcase \cweb@structure + %% hierarchic + \def\cwbb@marginal_chunkno{% + \vadjust{% + \setbox\z@ \hbox to \z@{% + \hss \vphantom{g}% + \small \thechunk + \hskip \marginparsep + }% + \vbox to \z@{% + \hsize\z@ + \vss + \noindent \raise \dp\z@ \box\z@ + }% + }% + } + \def\cwbb@init_print_chunk{% + \def\CwebNumberProgramPart{% + \cwbb@marginal_chunkno + \let\CwebNumberProgramPart\relax + }% + } + \or + %% flat + \let\cwbb@init_print_chunk\relax + \let\CwebNumberProgramPart\relax +\fi +%%% \endprog + + +%%% \sect If a statement is finished, a new paragraph with the basic +%%% indentation has to be started. + +%%% An optional statement break is implemented by a low penalty which +%%% will be selected if the line has to be broken. We assume that the +%%% hanging indentation of the new line is already set correctly, and +%%% have to backup two units to get the basic indentation. It might be +%%% that the line break is not chosen by \TeX{}, we compensate the +%%% backspace for this case. This compensation is discarded at the start +%%% of a new line. + +%%% \beginprog +\def\cwbb@break{% % forced break, between statements + \ifmmode\else + \endgraf % in LaTeX it isn't sure what \par is really... + \noindent + \hangindent\cwbb@indent \kern\cwbb@indent + \copy\cwbb@bakk % go back to basic indentation + \ignorespaces + \fi + } +\def\cwbb@opt_break{% % optional break between statements + \hfil \penalty\m@ne + \hfilneg \kern .5em \kern 2\CwebIndentUnit % discarded on line break + \copy\cwbb@bakk + \ignorespaces + } +\def\cwbb@big_break{% % forced break and a little extra space + \Y + \cwbb@break + } +\def\cwbb@expr_break#1{% % break with penalty #1 * 10 + \hfil \penalty#10 + \hfilneg % discarded on line break + } +%%% \endprog + + +%%% \sect When we increment the indentation, we must not forget to set +%%% the hanging indentation immediately since |\cwbb@opt_break| relies on +%%% the new value. If a continuation line is needed it will also be +%%% indented one unit more, which is ok since it should be distinguishable +%%% from the next line. +%%% % +%%% \begin{fixme} +%%% Shouldn't the hanging indentation be set anew at the end of +%%% |\cwbb@decr_indent| as well? +%%% \end{fixme} + +%%% \beginprog +\def\cwbb@incr_indent{% + \global\advance\cwbb@indent\CwebIndentUnit + \hangindent\cwbb@indent + } +\def\cwbb@decr_indent{\global\advance\cwbb@indent -\CwebIndentUnit} +\def\cwbb@backup{\copy\cwbb@bak} +\def\cwbb@noindent{% % no indentation + \hskip -\cwbb@indent \hskip 2\CwebIndentUnit + } +%%% \endprog + + + + +%%% \chap Program (C or \C++) tokens. + +%%% Since the user might want to change the (somewhat unusual) way some +%%% of the operators are typeset, we supply names for them. + +%%% \beginprog +\let\CwebAnd=\land % logical and, && +\let\CwebEquiv=\equiv % equiv sign, for == +\let\CwebGe=\ge % greater or equal +\let\CwebLe=\le % less or equal +\let\CwebNe=\ne % unequal, != +\let\CwebNull=\Lambda % NULL pointer +\let\CwebNot=\lnot % logical not, ! +\let\CwebOr=\lor % logical or, || +\let\CwebXor=\oplus % bitwise exclusive or, ^ +%%% \endprog + + +%%% \sect Some symbols have to be shifted around, to save computation time +%%% we put them in boxes. + +%%% \begin{fixme} +%%% It's not sure if the following symbols still look good in other font +%%% families than Computer Modern. The movements might need to get +%%% adapted when more experience is available. They were chosen from +%%% Plain \cweb{}, where these were explicit movements measured in +%%% points. I changed the dimension to quads, to achieve at least the +%%% support for different sizes in the Computer Modern family. +%%% \end{fixme} + +%%% \TeX{}nical note: The pointer symbol must not be declared as a math +%%% symbol (e.g., with |\DeclareMathSymbol|). Then \TeX{} would insert an +%%% italic correction behind it, according to rule~17 from appendix~G. +%%% (Please send email if you know of an easy way to prevent that +%%% addition.) So I use the symbol as an accent, but then I have to supply +%%% a nucleus for this math list. That nucleus also determines the total +%%% width of this construct. As the vector accent has a width of +%%% approximately 5\,pt in |cmmi10|, I'm going to use 0.5\,em. (That +%%% heuristic is as good as any other I can think of.) + +%%% \beginprog +%% pointer to struct component (`->'), use symbol of \vec accent +\newbox\cwbb@pointer +\setbox\cwbb@pointer=\hbox{% + \kern -.2em + \lower .3em \hbox{$\vec{\kern .5em}$}% + \kern .1em + } + +\newbox\cwbb@decr % decrement, -- +\setbox\cwbb@decr=\hbox{% + \kern .05em + \raise .1em \hbox{$\scriptstyle {-}\kern -.1em{-}$}% + \kern .05em + } +\newbox\cwbb@incr % increment, ++ +\setbox\cwbb@incr=\hbox{% + \kern .05em + \raise .1em \hbox{$\scriptstyle {+}\kern -.1em{+}$}% + \kern .05em + } +%%% \endprog + + +%%% \sect Although the following symbols are typeset like an ``ordinary +%%% \C++ programmer'' would expect them, we provide own module names +%%% nevertheless. They can now be changed as well, i.e., orthogonality is +%%% enhanced. (And we can use |\cwbb@rebind| for assigning them to their +%%% names while we switch to program state\,\dots). + +%%% Note: The comment at |\CwebMod| says ``modulo/remainder'', as this is +%%% not defined by the C standard, i.e., implementation-dependent. + +%%% \beginprog +\mathchardef\CwebAddress="2026 % `&', as binary op +\let\CwebAssign== % assignment +\let\CwebBinOr=\mid % binary or +\def\CwebComplement{{\sim}} % `~', as ordinary symbol +\def\CwebDecr{\copy\cwbb@decr} % decrement +\def\CwebIncr{\copy\cwbb@incr} % increment +\let\CwebLeftShift=\ll % left shift, << +\def\CwebMod{\mathbin{\hbox{\footnotesize\rm\%}}} % modulo/remainder, % +\def\CwebMemberRef{\mathbin{.*}} % ptr to member (on object) +\def\CwebPointer{\copy\cwbb@pointer} +\def\CwebPointerMemberRef{\mathbin{\CwebPointer*}} % ptr to member (on ptr) +\def\CwebRel{\mathrel?} % relation operator +\let\CwebRightShift=\gg % right shift, >> +\def\CwebScope{\kern.1em{::}\kern.1em} % scope resolution + +\def\CwebThis{\CwebRes{this}} % reserved identifier `this' +%%% \endprog + + +%%% \sect The special identifier |\TeX| remains. In math mode it shall be +%%% the identifier, in other modes the usual logo. We use the definition +%%% supplied by DEK (or \textsc{Silvio Levy}?)\ from Plain \cweb{}. + +%%% \beginprog +\def\TeX{% + {% + \ifmmode\it\fi + \mbox{T\kern-.1667em\lower.424ex\hbox{E}\hskip-.125emX}% + }} +%%% \endprog + + +%%% \sect Some tokens don't have constant names, the name is supplied as +%%% the argument. + +%%% Identifiers are typeset in italics, reserved words and type names in +%%% boldface, and strings in typewriter. For an underscore in the bold +%%% words we use a line that's 50\,\% thicker as the usual line thickness. +%%% -- But what is the usual line thickness. As Knuth uses 0.4\,pt for a +%%% 10\,pt Computer Modern font, we'll use 0.06\,em for a CM font in an +%%% arbitrary size. If that line thickness is still OK for other fonts is +%%% doubtful, as it should fit to the stem width. (CM is a rather light +%%% font, after all.) But since there is no font dimension that gives a +%%% hint to an appropriate line thickness, it's our best try. + +%%% \beginprog +\def\CwebCombinedOp#1{\mathrel{\let\K==#1}} % e.g., += operator +\def\CwebId#1{\hbox{\it#1\/\kern.05em}} % identifier, more than one char +\def\CwebIdLetter#1{\hbox{$#1$}} % identifier, one letter +\def\CwebRes#1{% % reserverd words and type names + \hbox{\bf + \def\_{\kern.04em\vbox{\hrule width.3em height.06em}\kern.08em}% + #1\/\kern .05em + }% + } +%%% \endprog + + +%%% \sect In Plain \cweb{} strings are typeset in the font |cmtex10|, +%%% which is a typewriter font with extended ASCII characters. This font +%%% does not have the usual accents and can therefore not used for +%%% typesetting national characters. (Very often they are input in some +%%% 8-bit encoding, the respective character code is made active and is +%%% substituted by a cseq which expands to the correct glyph. Of course, +%%% there are better ways, but that's the reality we have to cope with.) +%%% Instead of this special font we use the standard typewriter font. +%%% This has the further advantage that |cmtex10| may not be introduced +%%% to NFSS\@. + +%%% \beginprog +\def\CwebString{% + \hbox \bgroup + \tt + \cwbb@string_setup + \cwbb@string + } +\def\cwbb@string#1{% + #1\kern .05em + \egroup + } +%%% \endprog + + +%%% \sect Within strings certain cseqs have a special meaning; this is +%%% introduced by |\cwbb@string_setup|. The cseqs within strings are +%%% mostly special \TeX{} characters that are to be typeset by cseqs with +%%% the same name. + +%%% But a problem remains: active characters. They will still expand, and +%%% will mess up the string visualization. This is a particular problem +%%% with |german.sty| where the double quote is active. (Of course, that's +%%% a problem -- I'm German. :--) When one typesets strings, a double +%%% quote shall be typeset as double quotes, and must not expand to the +%%% special meaning. Remember that double quotes happen to appear quite +%%% often in strings. As the string argument is already tokenized, one has +%%% to redefine the binding of $(\textit{\textup{symbol}}\ \textbf{.}\ +%%% |#\"|)$. + +%%% \begin{fixme} +%%% Perhaps one might use a loop over all characters except the braces, +%%% and set their catcode to other. That would give us enough security. + +%%% For now, we handle only the double quote. +%%% \end{fixme} + +%%% Every once in a while we have discretionary breaks in a string, +%%% denoted by |\CwebStringBreak|. This break is shown with the C +%%% convention of escaped newlines. + +%%% \beginprog +\def\cwbb@string_setup{% + \chardef\ =`\ % % <-- two spaces ! + \chardef\&=`\& + \chardef\\=`\\ + \chardef\^=`\^ + \chardef\_=`\_ + \chardef\{=`\{ + \chardef\}=`\} + \chardef\~=`\~ + \catcode`\"=\CatOther + } + +\def\CwebStringBreak{\discretionary{\hbox{\tt\char`\\}}{}{}} +%%% \endprog + + +%%% \sect Numbers are typeset in different ways. We use the definition of +%%% Plain \cweb{}. +%%% % +%%% \begin{fixme} +%%% Should add a specification of the possible input and an explanation +%%% of the macros below. In particular, that the closing brace after +%%% |\aftergroup| is used much later is probably not grokked by most +%%% \TeX{} programmers. +%%% \end{fixme} + +%%% \beginprog +\def\cwbb@oct{\hbox{$^\circ$\kern-.1em\it\aftergroup\?\aftergroup}} +\def\cwbb@hex{\hbox{$^{\scriptscriptstyle\#}$\tt\aftergroup}} + +\def\CwebNumber#1{% % octal, hex, or decimal constant + \hbox{% + $% + \def\?{\kern.2em}% + \def\$##1{\egroup\sb{\,\rm##1}\bgroup}% suffix to constant + \def\_{\cdot 10^{\aftergroup}}% power of ten (via dirty trick) + \let\~\cwbb@oct \let\^\cwbb@hex + {#1}% + $}% + } +%%% \endprog + + +%%% \sect Comments are typeset in \TeX{} state. We add a hook, the user +%%% shall be able to change the layout (e.g., he might want another font). +%%% % +%%% \begin{fixme} +%%% Currently \C++ comments are typeset like C comments. This is +%%% horrible in usual circumstances, i.e., when complete blocks of text +%%% are prefixed with |//|. We should simply catenate all these text and +%%% typeset it as one paragraph, each line prefixed by |//|. But then we +%%% have to implement an |\everyline| first, and since that's not so +%%% easy we postpone it\,\dots +%%% \end{fixme} +%%% % +%%% In front of a C comment there is an optional stmt break, with 2\,quad +%%% in front if the line is not broken and 1.5\,quad if the line is broken. + +%%% \beginprog +\def\CwebComment#1{% + \5% % 0.5em will be discarded on line break + \hskip 1.5em + $/\ast\,$% + {\cwbb@tex + \CwebCommentHook + #1% + }% + $\,\ast/$% + } +\let\CwebCommentHook\relax +\let\CwebCxxComment\CwebComment +%%% \endprog + + + + + +%%% \chap \cweb{} tokens. + +%%% We distinguish three categories of \cweb{} tokens: (1) Those which +%%% output constant text, (2) those which have attributes to be displayed +%%% in a special way, and (3) those which start a new structure element, +%%% namely |@d| and~|@f|. Let's consider them in this order. + + +%%% \sect \cweb{} tokens which expand in a constant string are the +%%% identifier catenation operator~(`|@&|') and the macro placement +%%% directive~(`|@h|'). + +%%% \beginprog +\def\CwebIdCat{\CwebString{@\&}} +\def\CwebMacrosHere{% + \begingroup + \def\CwebRefNumber##1{}% + \CwebRefName :Preprocessor definitions\X + \endgroup + } +%%% \endprog + + +%%% \sect Verbatim program strings, i.e., strings passed verbatim by +%%% \ctangle{}~(`|@=|') are typeset like normal strings, but within a box. +%%% We use 2\,pt as the separating distance, this is set locally. + +%%% \beginprog +\def\CwebVerbString#1{{\fboxsep\tw@\p@ \fbox{\CwebString{#1}}}} +%%% \endprog + + +%%% \sect The refinement names are typeset in angles, this has a long +%%% tradition. We burry the typesetting of the chunk number (which is +%%% the first parameter) in a macro call; the user may change this to +%%% achieve special effects. +%%% % +%%% \begin{fixme} +%%% One could think about handling special values of the chunk numbers +%%% differently. E.g., an empty argument is not typeset at all, a~0 +%%% triggers a marginal note about a missing definition, etc. +%%% \end{fixme} + +%%% A refinement name may be typeset both in math and horizontal mode. +%%% The name itself is typeset in horizontal mode, of course; for the +%%% angles we need math mode. Therefore we assert at the start of the +%%% macro that we're not in math mode any more. At the end we switch back +%%% to math mode if we've started in it. This conditional switch from and +%%% back to math mode is done by |\cwbb@toggle_text|. + +%%% \TeX{}nical note: If we're in math mode |\cwbb@toggle_text| must be +%%% defined globally, as it will turn off math mode and the definition +%%% would be un-made then. The second invocation of |\cwbb@toggle_text| +%%% would be undefined then. + +%%% A refinement may also consist of the file name the expansion of this +%%% refinement shall be written to. +%%% % +%%% \label{sec:refname-dot} +%%% % +%%% This file name is tagged with |\.|, it shall be typeset like a string. +%%% But the user shall be able to use the dot accent in the refinement +%%% name as well. We check if the text consists solely of the tag and its +%%% argument; in this case we substitute |\.| with |\CwebString|. +%%% Otherwise we leave it as it is. Then a refinement name may not +%%% consist of a single dot-accented expression---well, that's highly +%%% unlikely. (Nevertheless I'll document it in the user's manual\,\dots) + +%%% \begin{fixme} +%%% One should be able to use |\EnsureMath| here. But the refinement +%%% name must not be set in math mode and must not be set in an hbox; +%%% the latter would prevent line breaks. +%%% \end{fixme} + +%%% \beginprog +\def\CwebRefName#1:#2\X{% + \ifmmode \gdef\cwbb@toggle_text{\null$\null}% + \else \let\cwbb@toggle_text\relax + \fi + \cwbb@toggle_text + $\langle\,${\cwbb@tex \cwbb@check_dot{#2}\CwebRefNumber{#1}}$\,\rangle$% + \cwbb@toggle_text + } +\def\CwebRefNumber#1{% + {\reset@font \footnotesize \kern .5em#1}% + } +%%% \endprog + + +%%% \sect The next macro, |\cwbb@check_dot| is a hassle to implement. We +%%% must check if it's argument consists solely of a `|\.|'~tag, together +%%% with the argument to this tag. Then the `|\.|'-argument shall be +%%% typeset like a string, |\.| itself must be ignored. + +%%% The check for |\.| must not evaluate the parameter. Especially |\PB| +%%% must not be evaluated within, it would lead to havoc with the +%%% redefinition of all bindings, etc. (At least that's the empirical +%%% result---it happened; although I don't know where the problems are. +%%% Anyhow, it wasn't in the specs of the rebinding process.) All other +%%% cseqs which shouldn't be used in moving arguments may cause problems +%%% here, too. Note that |\protect| is no solution here, the user often is +%%% not aware of the presence of \cweave{}-generated tags. As an example, +%%% consider the refinement \verb"@< local variables of |foo| @>|" which +%%% will lead to a call with the argument `|local variables of \PB{\\{foo}}|'. +%%% |\\| must not be evaluated here. + +%%% I use an approach where I hope that it will work---but to be honest, +%%% I'm not sure. I want to define a macro |\next| which shall have an +%%% empty expansion iff |#1| was a `|\.|'~tag with its argument. Empty +%%% refinement names are not allowed so we can assume that |#1| consists +%%% of at least one token. I evaluate the first token of |#1| before the +%%% |\def| is done. With an appropriate binding a |\.| will disappear, +%%% perhaps leaving an empty token list. I also take care that |\PB| is +%%% not evaluated then, by temporary rebinding it to |\relax|. Thereby I +%%% have taken care for all cseqs \cweave{} might have introduced at the +%%% very front of |#1|. Other cseqs are user-tags. If they cause +%%% problems, the user might circumstance them by adding |\protect|. + +%%% \beginprog +\def\cwbb@check_dot#1{% + \begingroup + \let\.\@gobble + \let\PB\relax + \expandafter\def \expandafter\next \expandafter{#1}% + \ifx \next\empty + \gdef\next##1{\CwebString}% + \else + \global\let\next\relax + \fi + \endgroup + \next #1% + } +%%% \endprog + + +%%% \sect \cweb{} macro definitions (done by~|@d|) and format directives are +%%% basically program text. When they are started we are already in +%%% program state, i.e., |\B| has appeared in front of it. But since we have +%%% an introductionary identifier (either |#define| or |format|) to set at +%%% the very front we increase the indentation by three units. + +%%% The output of format directives may be suppressed. Then we have to +%%% gather both identifiers that will appear after |\F|. Both of them +%%% consist of one group-token (a cseq and the identifier name), after +%%% each identifier one other token separates them. I.e., we have to +%%% gobble six group-tokens. As the very last token is |\par| if a format +%%% directive follows directly on another one, the definition must be +%%% long. + +%%% \TeX{}nical note: |\cwbb@format| must expand to |\CwebFormat|, not to +%%% its expansion. Otherwise a redefinition of |\CwebFormat| in a package +%%% would not be used. + +%%% \beginprog +\def\CwebDefine{\cwbb@macro{\#define}} +\def\CwebFormat{\cwbb@macro{format}} +\if@cweb@suppress@format@ + \long\def\cwbb@format#1#2#3#4#5#6{} +\else + \def\cwbb@format{\CwebFormat} +\fi + +\def\cwbb@macro#1{% + \global\advance\cwbb@indent \tw@\CwebIndentUnit + \cwbb@incr_indent + \CwebRes{#1 }% % <-- blank! + } +%%% \endprog + + + + +%%% \chap Refinement cross references and changes. + +%%% At the end of chunks with refinements, \cweave{} may output cross +%%% reference information: In which chunks additional definitions for +%%% this refinement are found, where this refinement is used, and where it +%%% is cited. This cross reference information is always introduced by a +%%% tag followed by a non-empty list of chunk numbers. Different tags +%%% are used for lists with only one element and for lists with more than +%%% one element, this way the introductionary text may be adapted. + +%%% Within a list of $n$~chunk numbers the first $n-1$~numbers are +%%% separated by commas with one following blank. The last two numbers +%%% are separated by |\ET| if~$n=2$, and by |\ETs| if~$n>2$. If a chunk +%%% is changed by the changefile, a changeflag~(`|\*|') is appended to +%%% its number. The list is eventually terminated by a full stop. + + +%%% \sect We separate the cross reference information by a smallskip from +%%% the refinement or from a previous cross reference information. The +%%% information itself is typeset in a smaller font, as it is auxilliary, +%%% inserted stuff. The number list has a hanging indentation of +%%% |\CwebNumberListHangindent|. But beware: This isn't a dimension +%%% register, it's a macro. This way one can use ems as dimensions. + +%%% The actual size change is represented by a macro. We will redefine it +%%% when we need an other size, e.g., in the lists at the end of the +%%% document. + +%%% We must assert that we're in CR state while we set a cross reference. + +%%% The first parameter of a cross reference information unit is the +%%% introductionary text, the second is the number list. The parameters +%%% must be evaluated in a group---local parameter changes therein must +%%% not influence the environment. + +%%% \beginprog +\def\CwebNumberListHangindent{2em} +\let\CwebCRSize\footnotesize +\def\CwebCrossRef#1#2.{% + \par\smallskip + \cwbb@CR + \begingroup + \reset@font \CwebCRSize + \noindent \hangindent\CwebNumberListHangindent\relax + #1~#2.\par + \endgroup + } +%%% \endprog + + +%%% \sect Well, let's define all introducing tags, which in fact start the +%%% cross reference information unit. The number list is gathered by +%%% |\CwebCrossRef|. + +%%% \beginprog +\def\CwebCRAlso{\CwebCrossRef{See also chunk}} +\def\CwebCRsAlso{\CwebCrossRef{See also chunks}} + +\def\CwebCRCite{\CwebCrossRef{This code is cited in chunk}} +\def\CwebCRsCite{\CwebCrossRef{This code is cited in chunks}} + +\def\CwebCRUse{\CwebCrossRef{This code is used in chunk}} +\def\CwebCRsUse{\CwebCrossRef{This code is used in chunks}} + +\def\CwebCREt{ and~} +\def\CwebCRsEt{, and~} +%%% \endprog + + + + +%%% \chap Bells and whistles. + +%%% \begin{fixme} +%%% Just copied from Plain \cweb{}. It doesn't work +%%% anyhow---|\char"|\<xy> usually doesn't typeset the correct +%%% character. That's because this character is most probably an active +%%% character; at least that's typical for the way \TeX{} systems are +%%% used in Europe. I have to think about the implementation. +%%% \end{fixme} + +%%% \beginprog +\def\ATL{\par\noindent\bgroup\catcode`\_=12 \postATL} % print @l in limbo +\def\postATL#1 #2 {\bf letter \\{\uppercase{\char"#1}} + tangles as \tentex "#2"\egroup\par} +\def\noATL#1 #2 {} +\def\noatl{\let\ATL=\noATL} % suppress output from @l +%%% \endprog + + + +%%% \chap The end. + +%%% Well, after all we're finished with this module + +%%% \beginprog +\endinput +%%% \endprog + + +%%% +%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +%%% \vskip \PltxPreSectSkip + +%%% \rcsLogIntro{After the actual revision log of this module, we give an +%%% extract of log messages of the \cls{cweb} class. This module was +%%% extracted from revision~2.8 of that class, we present to you the +%%% log entries that concern the code of the new module.} + +%%% \begin{rcslog} +%%% $StyleLog: cwebbase.doc,v $ +%%% \Revision 1.4 1995/11/07 17:55:19 schrod +%%% \LaTeX{} \cweb{} should work at least with the last two \LaTeX{} +%%% versions; make it work with the previous-to-last one, version +%%% \mbox{$\langle$1994/12/01$\rangle$}. For that, one has to install the +%%% \mbox{$\langle$1995/06/01$\rangle$} (non-outer) definition of +%%% |\newif|, and |\hb@xt@| must not be used.\\ +%%% Problem reported by Laurent Desnogues +%%% \path|<laurent.desnogues@aiguemarine.unice.fr>| and somebody else (XXX +%%% -- add name). + +%%% \Revision 1.3 1995/11/07 14:13:12 schrod +%%% Reset section numbers when higher-level section begins.\\ +%%% Error reported by Bronne Louis \path|<bronne@montefiore.ulg.ac.be>|. + +%%% \Revision 1.2 1995/11/06 10:58:47 schrod +%%% Support active double quotes in strings. That happens when +%%% |german.sty| is used. Problems with other active characters may still +%%% appear. + +%%% \Revision 1.1 1995/09/12 23:02:22 schrod +%%% Moved all code that does the actual typesetting of \cweave{} tags and +%%% is therefore also needed for a |cweb| environment. It's now an own +%%% module named \pkg{cwebbase}. + +%%% Chunk markers and chunk marginal numbers don't hang below the +%%% baseline any more. + + +%%% \item[] \noindent\hrulefill\break +%%% \textbf{Extract of the revision log for |cweb.doc|:} + +%%% \vskip 2ex + +%%% \Revision 2.5 1995/08/29 02:07:26 schrod +%%% Discard dependencies on 10\,pt fonts. + +%%% Support suppression of format directives. + +%%% \Revision 2.4 1995/08/27 19:31:43 schrod +%%% Make configuration of change flag easier. + +%%% Put section title of changed chunks list in marks, and tell the user +%%% that it got typeset. + +%%% \Revision 2.3 1995/08/27 17:24:46 schrod +%%% Make usage of baseclass with chapters work. + +%%% \Revision 2.2 1995/08/27 13:26:22 schrod +%%% Add possibility to suppress change hints. + +%%% \Revision 2.1 1995/08/25 19:11:18 schrod +%%% Hierarchic structures are supported now, in addition to the flat +%%% structure of the beta-test version. One can choose with an option. For +%%% that step, the terminology was cleaned up, too: Chunks are not named +%%% sections any more. (That change involved reimplementation of almost +%%% all the structure and toc stuff.) + +%%% The chunk number supplied by \cweave{} is used now, not some computed +%%% number. Change flags are printed, too. + +%%% One can suppress output of unchanged sections. + +%%% \Revision 1.12 1993/08/10 14:15:43 schrod +%%% New page on main section only if group level $<$ |\cwebSecNoEject|. +%%% Default for the latter is 3. + +%%% \Revision 1.11 1993/08/10 11:21:07 schrod +%%% Reference to section number does not render a period after the +%%% number any more. + +%%% \Revision 1.10 1993/08/09 20:08:20 schrod +%%% |\cweb@cweave_bindings| is now a no-op if \cweave{} bindings are in +%%% effect already.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% \Revision 1.9 1993/08/09 18:05:28 schrod +%%% Left shift operator wasn't defined correctly.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% \Revision 1.6 1993/06/15 08:49:23 schrod +%%% |\cweb@check_dot| must not evaluate its argument in an |\edef|, this +%%% causes problems if a |\PB| is within. Now I try hard not to evaluate any +%%% tokens outside of my control. + +%%% Can use |\@defpar| for an empty line in |\cweb@has_entries|, don't +%%% need an own macro. + +%%% \Revision 1.4 1993/06/14 15:54:18 schrod +%%% Add FSA diagram about processing states. CR state is also switched +%%% to from \TeX{} state (that happens with |\ch| at the document end). + +%%% \Revision 1.3 1993/05/13 17:51:21 schrod +%%% Refinements may also be filenames (`|@(|'). Then the complete name +%%% consists of a |\.| macro call, which is handled now.\\ +%%% (Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +%%% Made the detection of `|@.|' index entries more robust. + +%%% \Revision 1.2 1993/05/12 18:28:59 schrod +%%% Adapted to recent changes of \cweave{} (of April 93): + +%%% Main sections have a group level, represented in the table of +%%% contents. This changed the complete implementation of section tags. + +%%% New C token cseqs: |\Z| and |\MRL|, implemented as |\CwebLe| and +%%% |\CwebCombinedOp|. + +%%% \Revision 1.1 1993/04/09 15:00:37 schrod +%%% Initial revision + +%%% \end{rcslog} + + + +%%% \end{document} + + +%%% +%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%% Local Variables: +%%% mode: LaTeX +%%% TeX-brace-indent-level: 4 +%%% indent-tabs-mode: t +%%% TeX-auto-untabify: nil +%%% TeX-auto-regexp-list: LaTeX-auto-regexp-list +%%% compile-command: "make cwebbase.tex" +%%% End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/Makefile b/Master/texmf-dist/doc/latex/cweb-latex/examples/Makefile new file mode 100644 index 00000000000..e23e3056dbf --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/Makefile @@ -0,0 +1,29 @@ +# $Id: Makefile,v 1.5 1995/11/21 00:42:38 schrod Exp $ +#---------------------------------------------------------------------- + + +all:: wcltx.dvi + + +wcltx.dvi: wcltx.tex wcltx.bib ../cweb.cls + tex-it latex wcltx + rm -f wcltx.blg + +wcltx.tex: wcltx.w + cweave wcltx + + + AUX = *.aux *.bbl *.dvi *.idx *.log *.scn *.tex + +distrib:: + decomment-tex /usr/local/lib/texmf/tex/latex/misc/rcs.sty \ + 'from CTAN, directory macros/tex/latex/contrib/supported/rcs/.' \ + >rcs.sty + cp /usr/local/bin/tex-it . + $(MAKE) all + mkdir compare + mv $(AUX) compare + + +clean:: + /bin/rm -f $(AUX) diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.aux b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.aux new file mode 100644 index 00000000000..c602ac21793 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.aux @@ -0,0 +1,26 @@ +\relax +\citation{litprog:schrod:cweb} +\@writefile{toc}{\contentsline {section}{\numberline {1}An example of {\tt CWEB\/}{}}{1}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{1}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{1}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{2}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{2}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{2}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{3}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{3}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{3}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{3}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{4}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{4}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{4}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{4}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{4}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{5}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{5}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{5}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{5}} +\bibstyle{plain} +\bibdata{wcltx} +\bibcite{litprog:schrod:cweb}{1} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{6}} +\@writefile{toc}{\contentsline {chunk}{\copy \cweb@chunk_marker }{6}} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.bbl b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.bbl new file mode 100644 index 00000000000..1e95c84cced --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.bbl @@ -0,0 +1,8 @@ +\begin{thebibliography}{1} + +\bibitem{litprog:schrod:cweb} +Klaus Guntermann and Joachim Schrod. +\newblock {\WEB} adapted to {C}. +\newblock {\em TUGboat}, 7(3):134--137, 1986. + +\end{thebibliography} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.dvi b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.dvi Binary files differnew file mode 100644 index 00000000000..468bc34d4bf --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.dvi diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.idx b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.idx new file mode 100644 index 00000000000..dc79615c804 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.idx @@ -0,0 +1,40 @@ +\I\\{argc}, \[5], 7, 8. +\I\\{argv}, \[5], 7, 10, 17. +\I\\{buf\_end}, \[12], 13, 16. +\I\\{buf\_size}, \[12], 16. +\I\\{buffer}, \[12], 13, 16. +\I\.{BUFSIZ}, 12. +\I\|{c}, \[12]. +\I\.{cannot open file}, 10. +\I\\{cannot\_open\_file}, \[4], 10. +\I\\{char\_count}, \[12], 13, 16, 17, 18, \[20]. +\I\\{close}, 11. +\I\\{exit}, 5. +\I\\{fd}, \[9], 10, 11, 16. +\I\\{file\_count}, \[6], 7, 10, 17, 19. +\I\\{fprintf}, 10, 20. +\I\\{in\_word}, \[12], 13, 15. +\I{Joke}, 14. +\I\\{line\_count}, \[12], 13, 15, 17, 18, \[20]. +\I\\{main}, \[5], 14. +\I\.{OK}, \[4]. +\I\\{open}, 10. +\I\\{print\_count}, \[20]. +\I\\{printf}, 17, 19, 20. +\I\\{prog\_name}, \[4], 5, 10, 20. +\I\\{ptr}, \[12], 13, 15, 16. +\I\\{read}, 16. +\I\.{READ\_ONLY}, \[10]. +\I\\{status}, \[4], 5, 10, 20. +\I\\{stderr}, 3, 10, 20. +\I\\{stdin}, 9, 17. +\I\\{stdout}, 3. +\I\\{tot\_char\_count}, \[14], 18, 19. +\I\\{tot\_line\_count}, \[14], 18, 19. +\I\\{tot\_word\_count}, \[14], 18, 19. +\I\.{Usage: ...}, 20. +\I\\{usage\_error}, \[4], 20. +\I\\{wc\_print}, 17, 19, \[20]. +\I\\{which}, \[6], 7, 17, 19, \[20]. +\I\\{word\_count}, \[12], 13, 15, 17, 18, \[20]. + diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.log b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.log new file mode 100644 index 00000000000..a3f0d6136fd --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.log @@ -0,0 +1,114 @@ +This is TeX, Version 3.1415 (C version 6.1) (format=latex 95.7.29) 30 NOV 1995 16:52 +**wcltx +(wcltx.tex +LaTeX2e <1995/06/01> patch level 3 +Hyphenation patterns for english, german, loaded. +(/usr/local/lib/texmf/tex/generic/misc/cwebmac.tex) (../cweb.cls +Document Class: cweb 1995/11/30 v3.6 LaTeX markup for CWEB sources +(../keyvald.sty +Package: keyvald 1994/08/23 v1.08.1 key=value parser (DPC) w/ defaults (js) +) (/usr/local/lib/texmf/tex/latex/base/article.cls +Document Class: article 1995/06/26 v1.3g Standard LaTeX document class +(/usr/local/lib/texmf/tex/latex/base/size10.clo +File: size10.clo 1995/06/19 v1.3e Standard LaTeX file (size option) +) +\c@part=\count82 +\c@section=\count83 +\c@subsection=\count84 +\c@subsubsection=\count85 +\c@paragraph=\count86 +\c@subparagraph=\count87 +\c@figure=\count88 +\c@table=\count89 +\abovecaptionskip=\skip41 +\belowcaptionskip=\skip42 +\bibindent=\dimen102 +) (../cwebbase.tex +File: cwebbase.tex 1995/11/07 v1.4 CWEAVE tags for LaTeX markup +\cwbb@undefined=\toks15 +\cwbb@to_restore=\toks16 +\CwebChunkPreSkip=\skip43 +\cweb@chunk_marker=\box26 +LaTeX Font Info: Try loading font information for OMS+cmr on input line 598. + + +(/usr/local/lib/texmf/tex/latex/base/OMScmr.fd +File: OMScmr.fd 1995/04/22 v2.3f Standard LaTeX font definitions +) +LaTeX Font Info: Font shape `OMS/cmr/m/n' in size <10> not available +(Font) Font shape `OMS/cmsy/m/n' tried instead on input line 598. +\c@chunk=\count90 +\c@section2=\count91 +\c@section3=\count92 +\c@section4=\count93 +\c@section5=\count94 +\c@section6=\count95 +\c@section7=\count96 +\c@section8=\count97 +\c@section9=\count98 +\c@section10=\count99 +\CwebSectPreSkip=\skip44 +\CwebProgPenalty=\count100 +\cwbb@save@parskip=\skip45 +\cwbb@save@rightskip=\skip46 +\cwbb@save@sem_sfcode=\count101 +\cwbb@save@pretolerance=\count102 +\cwbb@save@hyphenpenalty=\count103 +\cwbb@save@exhyphenpenalty=\count104 +\CwebIndentUnit=\dimen103 +\cwbb@indent=\dimen104 +\cwbb@bak=\box27 +\cwbb@bakk=\box28 +\cwbb@pointer=\box29 +LaTeX Font Info: External font `cmex10' loaded for size +(Font) <7> on input line 1454. +LaTeX Font Info: External font `cmex10' loaded for size +(Font) <5> on input line 1454. +\cwbb@decr=\box30 +\cwbb@incr=\box31 +) +\CwebTocIndent=\dimen105 +\CwebTocIndentMaxLevel=\count105 +\cwebIndexIntro=\toks17 +) (rcs.sty +Package: rcs 1995/08/02 v2.9 typeset info from RCS fields +\rcsLogIntro=\toks18 +) (wcltx.aux) +LaTeX Font Info: Checking defaults for OML/cmm/m/it on input line 39. +LaTeX Font Info: ... okay on input line 39. +LaTeX Font Info: Checking defaults for T1/cmr/m/n on input line 39. +LaTeX Font Info: ... okay on input line 39. +LaTeX Font Info: Checking defaults for OT1/cmr/m/n on input line 39. +LaTeX Font Info: ... okay on input line 39. +LaTeX Font Info: Checking defaults for OMS/cmsy/m/n on input line 39. +LaTeX Font Info: ... okay on input line 39. +LaTeX Font Info: Checking defaults for OMX/cmex/m/n on input line 39. +LaTeX Font Info: ... okay on input line 39. +LaTeX Font Info: Checking defaults for U/cmr/m/n on input line 39. +LaTeX Font Info: ... okay on input line 39. +LaTeX Font Info: External font `cmex10' loaded for size +(Font) <8> on input line 47. +LaTeX Font Info: External font `cmex10' loaded for size +(Font) <6> on input line 47. +LaTeX Font Info: External font `cmex10' loaded for size +(Font) <12> on input line 51. + *1 +[1 + +] [2] [3] [4] [5] (wcltx.bbl [6]) [7] Index: (wcltx.idx) [8 + + +] +List of Refinements: (wcltx.scn) [9 + +] (wcltx.aux) ) +Here is how much of TeX's memory you used: + 709 strings out of 10921 + 7728 string characters out of 72294 + 56323 words of memory out of 262141 + 3583 multiletter control sequences out of 9500 + 8738 words of font info for 32 fonts, out of 100000 for 255 + 14 hyphenation exceptions out of 607 + 29i,8n,22p,172b,316s stack positions out of 300i,40n,60p,3000b,4000s + +Output written on wcltx.dvi (9 pages, 24308 bytes). diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.scn b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.scn new file mode 100644 index 00000000000..4b0fbe3d4a8 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.scn @@ -0,0 +1,32 @@ +\I\X11:Close file\X +\U8. +\I\X16:Fill \PB{\\{buffer}} if it is empty; \PB{\&{break}} at end of file\X +\U15. +\I\X20:Functions\X +\U2. +\I\X4, 14:Global variables\X +\U2. +\I\X3:Header files to include\X +\U2. +\I\X10:If a file is given, try to open \PB{${*}(\PP\\{argv})$}; \PB{% +\&{continue}} if unsuccessful\X +\U8. +\I\X13:Initialize pointers and counters\X +\U8. +\I\X19:Print the grand totals if there were multiple files\X +\U5. +\I\X8:Process all the files\X +\U5. +\I\X15:Scan file\X +\U8. +\I\X7:Set up option selection\X +\U5. +\I\X5:The main program\X +\U2. +\I\X18:Update grand totals\X +\U8. +\I\X6, 9, 12:Variables local to \PB{\\{main}}\X +\U5. +\I\X17:Write statistics for file\X +\U8. + diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.tex b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.tex new file mode 100644 index 00000000000..58a91af0247 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/compare/wcltx.tex @@ -0,0 +1,412 @@ +\input cwebmac +% $Id: wcltx.w,v 1.4 1995/08/29 17:27:57 schrod Exp $ +%------------------------------------------------------------ + +% +% wc: An example of CWEB by Silvio Levy and Donald E. Knuth +% +% [LaTeX] +% (history at end) + + +%% -js: +%% should rework it: ANSI C compliance, POSIX.2 compliant option +%% parsing with getopt(), including *all* required header files (ie, +%% POSIX.1 compliance), using POSIX return codes and types, etc. + + + +\documentclass{cweb} + +\usepackage{rcs} + + +% +% some tags for this document +% +\def\CEE/{C\spacefactor 1000 } +\def\cweb{{\tt CWEB\/}} +\def\SPARC{SPARC\-\kern.1em station} +\def\UNIX/{{\small UNIX\/}} +\def\wc{{\tt wc\/}} +\def\WEB{{\tt WEB\/}} + +\hfuzz=0.5pt + + + + +\begin{document} + + + +\title{Counting words} +\author{Silvio Levy\and Donald E. Knuth} +\begingroup +\def\thefootnote{\hbox{$^*$}} +\footnotetext[0]{\LaTeX{} markup by Joachim Schrod.} +\endgroup +\RCSdate $Date: 1995/08/29 17:27:57 $ + +\maketitle + +% not very interesting, only one starred section +% \tableofcontents + + + + +\N{1}{1}An example of \cweb{}. This example, based on a program by +Klaus Guntermann and Joachim Schrod~\cite{litprog:schrod:cweb} +presents the ``word count'' program from \UNIX/, rewritten in +\cweb{} to demonstrate literate programming in \CEE/.% +\footnote{% +Incidentally, Klaus Guntermann and Joachim Schrod are now +using this \cweb{} and have stopped the support for their version. +Joachim Schrod contributed the \LaTeX{} style used for the markup of +this document. +} +The level of detail in this document is intentionally high, for +didactic purposes; many of the things spelled out here don't need to +be explained in other programs. + +The purpose of \wc{} is to count lines, words, and/or characters in a +list of files. The number of lines in a file is the number of newline +characters it contains. The number of characters is the file length in bytes. +A ``word'' is a maximal sequence of consecutive characters other than +newline, space, or tab, containing at least one visible ASCII code. +(We assume that the standard ASCII code is in use.) + +\fi + +\M{2}Most \cweb{} programs share a common structure. It's probably a +good idea to state the overall structure explicitly at the outset, +even though the various parts could all be introduced in unnamed +sections of the code if we wanted to add them piecemeal. + +Here, then, is an overview of the file \texttt{wcltx.c} that is +defined by this \cweb{} program \texttt{wcltx.w}: + +\Y\B\X3:Header files to include\X\6 +\X4:Global variables\X\6 +\X20:Functions\X\6 +\X5:The main program\X\par +\fi + +\M{3}We must include the standard I/O definitions, since we want to send +formatted output to \PB{\\{stdout}} and \PB{\\{stderr}}. + +\Y\B\4\X3:Header files to include\X${}\E{}$\6 +\8\#\&{include} \.{<stdio.h>}\par +\U2.\fi + +\M{4} The \PB{\\{status}} variable will tell the operating system if the run +was +successful or not, and \PB{\\{prog\_name}} is used in case there's an error +message to +be printed. + +\Y\B\4\D$\.{OK}$ \5 +\T{0}\C{ \PB{\\{status}} code for successful run }\par +\B\4\D$\\{usage\_error}$ \5 +\T{1}\C{ \PB{\\{status}} code for improper syntax }\par +\B\4\D$\\{cannot\_open\_file}$ \5 +\T{2}\C{ \PB{\\{status}} code for file access error }\par +\Y\B\4\X4:Global variables\X${}\E{}$\6 +\&{int} \\{status}${}\K\.{OK}{}$;\C{ exit status of command, initially \PB{% +\.{OK}} }\6 +\&{char} ${}{*}\\{prog\_name}{}$;\C{ who we are }\par +\A14. +\U2.\fi + +\M{5}Now we come to the general layout of the \PB{\\{main}} function. + +\Y\B\4\X5:The main program\X${}\E{}$\6 +$\\{main}(\\{argc},\39\\{argv}){}$\1\1\6 +\&{int} \\{argc};\C{ the number of arguments on the \UNIX/ command line }\6 +\&{char} ${}{*}{*}\\{argv}{}$;\C{ the arguments themselves, an array of strings +}\2\2\6 +${}\{{}$\1\6 +\X6:Variables local to \PB{\\{main}}\X\6 +${}\\{prog\_name}\K\\{argv}[\T{0}];{}$\6 +\X7:Set up option selection\X;\6 +\X8:Process all the files\X;\6 +\X19:Print the grand totals if there were multiple files\X;\6 +\\{exit}(\\{status});\6 +\4${}\}{}$\2\par +\U2.\fi + +\M{6}If the first argument begins with a `\texttt{-}', the user is choosing +the desired counts and specifying the order in which they should be +displayed. Each selection is given by the initial character +(lines, words, or characters). For example, `\texttt{-cl}' would cause +just the number of characters and the number of lines to be printed, +in that order. + +We do not process this string now; we simply remember where it is. +It will be used to control the formatting at output time. + +\Y\B\4\X6:Variables local to \PB{\\{main}}\X${}\E{}$\6 +\&{int} \\{file\_count};\C{ how many files there are }\6 +\&{char} ${}{*}\\{which}{}$;\C{ which counts to print }\par +\As9\ET12. +\U5.\fi + +\M{7}\B\X7:Set up option selection\X${}\E{}$\6 +$\\{which}\K\.{"lwc"}{}$;\C{ if no option is given, print all three values }\6 +\&{if} ${}(\\{argc}>\T{1}\W{*}\\{argv}[\T{1}]\E\.{'-'}){}$\5 +${}\{{}$\1\6 +${}\\{which}\K\\{argv}[\T{1}]+\T{1};{}$\6 +${}\\{argc}\MM;{}$\6 +${}\\{argv}\PP;{}$\6 +\4${}\}{}$\2\6 +${}\\{file\_count}\K\\{argc}-\T{1}{}$;\par +\U5.\fi + +\M{8}Now we scan the remaining arguments and try to open a file, if +possible. The file is processed and its statistics are given. +We use a \PB{\&{do}}~\dots~\PB{\&{while}} loop because we should read from the +standard input if no file name is given. + +\Y\B\4\X8:Process all the files\X${}\E{}$\6 +$\\{argc}\MM;{}$\6 +\&{do}\5 +${}\{{}$\1\6 +\X10:If a file is given, try to open \PB{${*}(\PP\\{argv})$}; \PB{\&{continue}} +if unsuccessful\X;\6 +\X13:Initialize pointers and counters\X;\6 +\X15:Scan file\X;\6 +\X17:Write statistics for file\X;\6 +\X11:Close file\X;\6 +\X18:Update grand totals\X;\C{ even if there is only one file }\6 +\4${}\}{}$\5 +\2\5 +\&{while} ${}(\MM\\{argc}>\T{0}){}$;\par +\U5.\fi + +\M{9}Here's the code to open the file. A special trick allows us to +handle input from \PB{\\{stdin}} when no name is given. +Recall that the file descriptor to \PB{\\{stdin}} is~0; that's what we +use as the default initial value. + +\Y\B\4\X6:Variables local to \PB{\\{main}}\X${}\mathrel+\E{}$\6 +\&{int} \\{fd}${}\K\T{0}{}$;\C{ file descriptor, initialized to \PB{\\{stdin}} +}\par +\fi + +\M{10}\B\D$\.{READ\_ONLY}$ \5 +\T{0}\C{ read access code for system \PB{\\{open}} routine }\par +\Y\B\4\X10:If a file is given, try to open \PB{${*}(\PP\\{argv})$}; \PB{% +\&{continue}} if unsuccessful\X${}\E{}$\6 +\&{if} ${}(\\{file\_count}>\T{0}\W(\\{fd}\K\\{open}({*}(\PP\\{argv}),\39\.{READ% +\_ONLY}))<\T{0}){}$\5 +${}\{{}$\1\6 +${}\\{fprintf}(\\{stderr},\39\.{"\%s:\ cannot\ open\ fil}\)\.{e\ \%s\\n"},\39% +\\{prog\_name},\39{*}\\{argv});{}$\6 +${}\\{status}\MRL{{\OR}{\K}}\\{cannot\_open\_file};{}$\6 +${}\\{file\_count}\MM;{}$\6 +\&{continue};\6 +\4${}\}{}$\2\par +\U8.\fi + +\M{11}\B\X11:Close file\X${}\E{}$\6 +\\{close}(\\{fd});\par +\U8.\fi + +\M{12}We will do some homemade buffering in order to speed things up: +Characters +will be read into the \PB{\\{buffer}} array before we process them. +To do this we set up appropriate pointers and counters. + +\Y\B\4\D$\\{buf\_size}$ \5 +\.{BUFSIZ}\C{ \texttt{stdio.h}'s \PB{\.{BUFSIZ}} is chosen for efficiency }\par +\Y\B\4\X6:Variables local to \PB{\\{main}}\X${}\mathrel+\E{}$\6 +\&{char} \\{buffer}[\\{buf\_size}];\C{ we read the input into this array }\6 +\&{register} \&{char} ${}{*}\\{ptr}{}$;\C{ the first unprocessed character in % +\PB{\\{buffer}} }\6 +\&{register} \&{char} ${}{*}\\{buf\_end}{}$;\C{ the first unused position in % +\PB{\\{buffer}} }\6 +\&{register} \&{int} \|c;\C{ current character, or number of characters just +read }\6 +\&{int} \\{in\_word};\C{ are we within a word? }\6 +\&{long} \\{word\_count}${},{}$ \\{line\_count}${},{}$ \\{char\_count};\C{ +number of words, lines, and characters found in the file so far }\par +\fi + +\M{13}\B\X13:Initialize pointers and counters\X${}\E{}$\6 +$\\{ptr}\K\\{buf\_end}\K\\{buffer};{}$\6 +${}\\{line\_count}\K\\{word\_count}\K\\{char\_count}\K\T{0};{}$\6 +${}\\{in\_word}\K\T{0}{}$;\par +\U8.\fi + +\M{14}The grand totals must be initialized to zero at the beginning of the +program. If we made these variables local to \PB{\\{main}}, we would have to +do this initialization explicitly; however, \CEE/'s globals are automatically +zeroed. (Or rather, ``statically zeroed.'') (Get it?) +%% -js: The joke would be better if the vars would be static, which +%% they aren't in the C sense... + +\Y\B\4\X4:Global variables\X${}\mathrel+\E{}$\6 +\&{long} \\{tot\_word\_count}${},{}$ \\{tot\_line\_count}${},{}$ \\{tot\_char% +\_count};\C{ total number of words, lines, and chars }\par +\fi + +\M{15}The present section, which does the counting that is \wc{}'s \emph{raison +d'\^etre}, was actually one of the simplest to write. We look at each +character and change state if it begins or ends a word. + +\Y\B\4\X15:Scan file\X${}\E{}$\6 +\&{while} (\T{1})\5 +${}\{{}$\1\6 +\X16:Fill \PB{\\{buffer}} if it is empty; \PB{\&{break}} at end of file\X;\6 +${}\|c\K{*}\\{ptr}\PP;{}$\6 +\&{if} ${}(\|c>\.{'\ '}\W\|c<\T{\~177}){}$\5 +${}\{{}$\C{ visible ASCII codes }\1\6 +\&{if} ${}(\R\\{in\_word}){}$\5 +${}\{{}$\1\6 +${}\\{word\_count}\PP;{}$\6 +${}\\{in\_word}\K\T{1};{}$\6 +\4${}\}{}$\2\6 +\&{continue};\6 +\4${}\}{}$\2\6 +\&{if} ${}(\|c\E\.{'\\n'}){}$\1\5 +${}\\{line\_count}\PP;{}$\2\6 +\&{else} \&{if} ${}(\|c\I\.{'\ '}\W\|c\I\.{'\\t'}){}$\1\5 +\&{continue};\2\6 +${}\\{in\_word}\K\T{0}{}$;\C{ \PB{\|c} is newline, space, or tab }\6 +\4${}\}{}$\2\par +\U8.\fi + +\M{16}Buffered I/O allows us to count the number of characters almost for free. + +\Y\B\4\X16:Fill \PB{\\{buffer}} if it is empty; \PB{\&{break}} at end of file% +\X${}\E{}$\6 +\&{if} ${}(\\{ptr}\G\\{buf\_end}){}$\5 +${}\{{}$\1\6 +${}\\{ptr}\K\\{buffer};{}$\6 +${}\|c\K\\{read}(\\{fd},\39\\{ptr},\39\\{buf\_size});{}$\6 +\&{if} ${}(\|c\Z\T{0}){}$\1\5 +\&{break};\2\6 +${}\\{char\_count}\MRL{+{\K}}\|c;{}$\6 +${}\\{buf\_end}\K\\{buffer}+\|c;{}$\6 +\4${}\}{}$\2\par +\U15.\fi + +\M{17}It's convenient to output the statistics by defining a new function +\PB{\\{wc\_print}}; then the same function can be used for the totals. +Additionally we must decide here if we know the name of the file +we have processed or if it was just \PB{\\{stdin}}. + +\Y\B\4\X17:Write statistics for file\X${}\E{}$\6 +$\\{wc\_print}(\\{which},\39\\{char\_count},\39\\{word\_count},\39\\{line% +\_count});{}$\6 +\&{if} (\\{file\_count})\1\5 +${}\\{printf}(\.{"\ \%s\\n"},\39{*}\\{argv}){}$;\C{ not \PB{\\{stdin}} }\2\6 +\&{else}\1\5 +\\{printf}(\.{"\\n"});\C{ \PB{\\{stdin}} }\2\par +\U8.\fi + +\M{18}\B\X18:Update grand totals\X${}\E{}$\6 +$\\{tot\_line\_count}\MRL{+{\K}}\\{line\_count};{}$\6 +${}\\{tot\_word\_count}\MRL{+{\K}}\\{word\_count};{}$\6 +${}\\{tot\_char\_count}\MRL{+{\K}}\\{char\_count}{}$;\par +\U8.\fi + +\M{19}We might as well improve a bit on \UNIX/'s \wc{} by displaying the +number of files too. + +\Y\B\4\X19:Print the grand totals if there were multiple files\X${}\E{}$\6 +\&{if} ${}(\\{file\_count}>\T{1}){}$\5 +${}\{{}$\1\6 +${}\\{wc\_print}(\\{which},\39\\{tot\_char\_count},\39\\{tot\_word\_count},\39% +\\{tot\_line\_count});{}$\6 +${}\\{printf}(\.{"\ total\ in\ \%d\ files\\}\)\.{n"},\39\\{file\_count});{}$\6 +\4${}\}{}$\2\par +\U5.\fi + +\M{20}Here now is the function that prints the values according to the +specified options. The calling routine is supposed to supply a +newline. If an invalid option character is found we inform +the user about proper usage of the command. Counts are printed in +8-digit fields so that they will line up in columns. + +\Y\B\4\D$\\{print\_count}(\|n)$ \5 +$\\{printf}(\.{"\%8ld"},\39\|n{}$)\par +\Y\B\4\X20:Functions\X${}\E{}$\6 +$\\{wc\_print}(\\{which},\39\\{char\_count},\39\\{word\_count},\39\\{line% +\_count}){}$\1\1\6 +\&{char} ${}{*}\\{which}{}$;\C{ which counts to print }\6 +\&{long} \\{char\_count}${},{}$ \\{word\_count}${},{}$ \\{line\_count};\C{ +given totals }\2\2\6 +${}\{{}$\1\6 +\&{while} ${}({*}\\{which}){}$\1\6 +\&{switch} ${}({*}\\{which}\PP){}$\5 +${}\{{}$\1\6 +\4\&{case} \.{'l'}:\5 +\\{print\_count}(\\{line\_count});\6 +\&{break};\6 +\4\&{case} \.{'w'}:\5 +\\{print\_count}(\\{word\_count});\6 +\&{break};\6 +\4\&{case} \.{'c'}:\5 +\\{print\_count}(\\{char\_count});\6 +\&{break};\6 +\4\&{default}:\6 +\&{if} ${}((\\{status}\AND\\{usage\_error})\E\T{0}){}$\5 +${}\{{}$\1\6 +${}\\{fprintf}(\\{stderr},\39\.{"\\nUsage:\ \%s\ [-lwc]\ }\)\.{[filename\ ...]% +\\n"},\39\\{prog\_name});{}$\6 +${}\\{status}\MRL{{\OR}{\K}}\\{usage\_error};{}$\6 +\4${}\}{}$\2\6 +\4${}\}{}$\2\2\6 +\4${}\}{}$\2\par +\U2.\fi + +\M{21}Incidentally, a test of this program against the system \wc{} +command on a \SPARC\ showed that the ``official'' \wc{} was slightly +slower. Furthermore, although that \wc{} gave an appropriate error +message for the options `\texttt{-abc}', it made no complaints about the +options `\texttt{-labc}'! Dare we suggest that the system routine +might have been +better if its programmer had used a more literate approach? + + + +\bibliographystyle{plain} +\bibliography{wcltx} + + +\fi + +\M{22} + +\cwebIndexIntro{% +Here is a list of the identifiers used, and where they appear. +Underlined entries indicate the place of definition. Error messages +are also shown. +} + +\end{document} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% $Log: wcltx.w,v $ +% Revision 1.4 1995/08/29 17:27:57 schrod +% Recoded to LaTeX2e markup. +% +% Revision 1.3 1993/06/15 14:01:14 schrod +% Renamed document to wcltx, must change \bibliography tag, too. +% +% Revision 1.2 1993/06/15 13:35:12 schrod +% `cweb' is now a style, was an option formerly. +% +% Revision 1.1 1993/04/09 15:00:37 schrod +% Initial revision +% +\fi + + +\inx +\fin +\con diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/rcs.sty b/Master/texmf-dist/doc/latex/cweb-latex/examples/rcs.sty new file mode 100644 index 00000000000..e3cfaec72ec --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/rcs.sty @@ -0,0 +1,227 @@ +% This is a stripped version of rcs.sty, +% all comment lines and empty lines were discarded to save space. YOU +% ARE NOT ALLOWED to use this file for your own work. You may ONLY +% redistribute it as part of the complete distribution you received it. +% This file was created at Thu Nov 30 15:51:58 UTC 1995. + +% The original file may be retrieved +% from CTAN, directory macros/tex/latex/contrib/supported/rcs/.. + +% ====================================================================== + +\ifx \rcs@loaded\undefined + \def\rcs@loaded{$StyleRevision: 2.9 $} +\else + \PackageWarningNoLine{rcs}% + {Some other package already uses namespace `rcs'} +\fi +\begingroup + \def\RCSPackage#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesPackage{#1}[\date\space\id\space #2]% + } + \RCSPackage{rcs}{typeset info from RCS fields} + $StyleDate: 1995/08/02 12:09:07 $: 9999/00/00 \endRCS + $StyleRevision: 2.9 $: 0.0 \endRCS +\endgroup +\ifx \CatEscape\undefined + \chardef\CatEscape=0 + \chardef\CatOpen=1 + \chardef\CatClose=2 + \chardef\CatIgnore=9 + \chardef\CatLetter=11 + \chardef\CatOther=12 + \chardef\CatActive=13 + \chardef\CatUsCode=\catcode`\_ +\fi +\catcode`\_=\CatLetter % top level macro file +\def\RcsEmptyValue{} +\def\rcs_split_field #1: #2 :#3\end_value{% + \def\RCS_keyword{#1}% + \def\RCS_value{#2}% + \ifx \RCS_value\empty + \let\RCS_value\RcsEmptyValue + \fi + } +\def\RCS $#1${% + \rcs_split_field #1: {} :\end_value + \expandafter\let \csname RCS\rcs_raw_if_handle\RCS_keyword\endcsname + \RCS_value + \csname RcsHandle\RCS_keyword\endcsname + } +\def\rcs_raw_if_handle{% + \@ifundefined{RcsHandle\RCS_keyword}{}{Raw}% + } +\def\RcsHandleDate{% + \ifx \today\undefined + \expandafter\let \csname RCS\RCS_keyword\endcsname \RCS_value + \else + \ifx \RCS_value\RcsEmptyValue + \@namedef{RCS\RCS_keyword}{\today}% + \let\RCSTime\empty + \else + \expandafter\rcs_set_date \RCS_value\end_date + \fi + \fi + } +\def\rcs_set_date #1/#2/#3 #4\end_date{% + \begingroup + \day #3 % <-- space! + \month #2 % <-- space! + \year #1 % <-- space! + \expandafter\xdef \csname RCS\RCS_keyword\endcsname {\today}% + \endgroup + \def\RCSTime{#4}% + } +\newtoks\rcsLogIntro + \rcsLogIntro={} +\def\rcsAuthor#1#2{\@namedef{rcs_author:#1}{#2}} +\def\RCS_get_author#1{% + \@ifundefined{rcs_author:#1}{#1}{\@nameuse{rcs_author:#1}}% + } +\def\RcsLogStyle{% + \def\RcsLogHeading{\subsubsection*}% + \footnotesize + } +\def\rcs_log_hdr#1,v\end_value{% + \@rcs_empty_log@false + \RcsLogHeading{\RcsLogHeadingName #1}% + \the\rcsLogIntro + } +\def\rcs_empty_log_value{% + \global\@rcs_empty_log@true % that's most probably in a group! + \RcsUnknownFile % text for unknown file name + ,v% % assert calling env + } +\newif\if@rcs_empty_log@ +\def\RcsLogHeadingName{Revision Log for \tt} % file name in monospace +\def\RcsUnknownFile{\rm $\langle\,$Unknown file name$\,\rangle$} +\def\RcsEmptyLog{{\itshape No log entries available.}} +\def\RcsLogRevision#1#2#3#4{% + \item [Revision #1]% + (created at \RcsLogDate #2\endDate\space \RcsLogTime{#3} % <-- space! + by \RCS_get_author{#4})\\\relax + } +\def\RcsLogDate #1/#2/#3\endDate{% + \begingroup + \day #3 % <-- space! + \month #2 % <-- space! + \year #1 % <-- space! + \today + \endgroup + } +\def\RcsLogTime#1{\ignorespaces} +\def\rcs_settime{% + \def\RcsLogTime##1{[##1]}% + } +\def\rcslog{% + \@ifnextchar[% % ] (Emacs) + \rcslog_configure + {\rcslog_configure[]}% + } +\def\rcslog_configure[#1]{% + \let\Revision\rcslog_revision + \let\settime\rcs_settime + \RcsLogStyle + #1% + \afterassignment\rcslog_skipcr + \let\next + } +\def\rcslog_skipcr{% + \ifx \next $% + \def\next{\rcslog_field $}% + \else\ifx \next\par + \let\next\rcslog_field + \else + \PackageError{rcs}{Missing RCS Log field in environment}{% +The RCS Log field must be the very first text in the rcslog\MessageBreak +environment. I will discard the rest of your input line and try to\MessageBreak +recover then. If you think this won't work, exit now.\MessageBreak +Otherwise press <Return> and cross your fingers!} + \let\next\rcslog_discard_line + \fi\fi + \next + } +\def\rcslog_discard_line{% + \begingroup + \obeylines + \rcslog_gobble_line + } +\begingroup +\obeylines +\gdef\rcslog_gobble_line #1^^M{% + \endgroup% + \afterassignment\rcslog_skipcr% + \let\next% + } +\endgroup +\def\rcslog_field{% + \begingroup + \obeylines + \rcslog_get_field + } +\begingroup +\obeylines +\gdef\rcslog_get_field #1^^M{% + \endgroup% + \rcslog_set_field{#1}% + } +\endgroup +\def\rcslog_set_field#1{% + \let\RcsEmptyValue\rcs_empty_log_value + \RCS #1% + \expandafter\rcs_log_hdr \RCS_value\end_value + \list{}\RcsLogListStyle % empty label, layout configurable + \if@rcs_empty_log@ + \item []\RcsEmptyLog % supply missing item + \fi + } +\def\RcsLogListStyle{% + \global\@listdepth\z@ + \labelwidth\z@ % item label w/o fixed size + \itemindent -\leftmargin % move label before start of line + \advance\itemindent \labelsep % label was moved too much + \def\makelabel##1{\bf ##1}% % how to typeset labels + \parsep\z@skip % no space between pars in items + \listparindent 1em % <-- space! indent pars in items + }% +\let\endrcslog\endtrivlist +\def\rcslog_revision{% + \begingroup + \obeylines + \rcslog_get_revinfo + } +\begingroup +\obeylines +\gdef\rcslog_get_revinfo #1 #2 #3 #4^^M{% + \endgroup% + \RcsLogRevision{#1}{#2}{#3}{#4}% + } +\endgroup +\def\RCSdate $#1${% + \RCS $#1$% + \expandafter\date \expandafter{\csname RCS\RCS_keyword\endcsname}% + } +\def\RCSID{% + \@ifnextchar\bgroup + \rcsid_get_field + \rcs_id + } +\def\rcsid_get_field#1{\rcs_id #1} +\def\rcs_id $#1${% + \RCS $#1$% + \begingroup + \let\protect\noexpand + \xdef\@oddfoot{% + \reset@font + \protect\framebox[\textwidth]{\RCS_keyword: \RCS_value}% + }% + \endgroup + \global\let\@evenfoot\@oddfoot + } +\def\RCSdef $#1${% + \typeout{RCS field: $#1$}% + \RCS $#1$% + } +\catcode`\_=\CatUsCode +\endinput diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/tex-it b/Master/texmf-dist/doc/latex/cweb-latex/examples/tex-it new file mode 100644 index 00000000000..07a8e98ad31 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/tex-it @@ -0,0 +1,203 @@ +#!/bin/sh +# $ITI: tex-it,v 1.3 1995/06/14 10:49:12 schrod Exp $ +#---------------------------------------------------------------------- + +# +# tex-it --- transform a TeX document to a final DVI file +# +# (history at end) + + +# SYNOPSIS +# +# tex-it [-bi] tex-cmd file +# +# tex-it runs 'tex-cmd' on 'file' as often as necessary to produce a +# DVI file where all cross references are resolved. That convergence +# is reached by analyzing auxilliary files: +# -- If file.toc has changed, the table of contents is not up to date. +# -- If file.idx has changed, the index is not up to date. +# MakeIndex is assumed to be used for creating the index. +# -- If file.aux has changed, cross references are not up to date. +# -- If file.aux contains a "\bibdata" tag and if the set of +# "\citation" tags have changed, then BibTeX is run. +# +# No other auxilliary files are handled. No subdocuments (via +# "\include") are supported. +# +# 'tex-cmd' may be more than one word. +# +# +# OPTIONS +# `-b' skip test for BibTeX +# `-i' skip test for MakeIndex + +# NOTE: On HP-UX this script is not functional, you have to substitute +# /bin/sh by /bin/ksh in the first line. (/bin/sh doesn't have the +# getopts builtin.) + + +cmd=`basename $0` +usage() +{ + echo "usage: $cmd [-bi] tex-cmd file" >&2 + exit 1 +} + + +# Normalize and check arguments. + +do_bibtex=true +do_makeindex=true +while getopts 'bi' option + do case "$option" in + b) do_bibtex='' + ;; + i) do_makeindex='' + ;; + *) usage + ;; + esac + done + +shift `expr $OPTIND - 1` +test $# -gt 0 || usage + + +# Get file name (last argument), discard extension if necessary. + +file=`eval "echo \\$$#"` +file=`echo $file | sed 's/\.[^.]*//'` + + +# Create temporary directory for auxilliary files to compare. Discard +# that directory if the script is terminated. Note that trap handler +# for 0 is executed at the end of the trap handler for the other +# signals. + +tmp=/tmp/tex$$ +trap "/bin/rm -rf $tmp" 0 +trap "exit 4" 1 2 3 15 +mkdir $tmp + + +# ------------------------------------------------------------ +# +# Set up functions that save auxilliary information and check if they +# have changed. Save functions are called `save_<type>', check +# functions are called `check_<type>'. Check functions set $run_tex to +# "true" if TeX must be run anew. Check functions may run programs to +# create other auxilliary files. + + +# aux: table of contents & cross references +# +# We don't check for *.toc files. LaTeX stores the information in the +# AUX file anyhow, and plain-based macros typically produce the table +# of contents at the end of the document, when it's guaranteed to be +# OK. + +save_aux() +{ + if [ -f "$file.aux" ] + then cp "$file.aux" $tmp + else touch "$tmp/$file.aux" + fi +} + +check_aux() +{ + test -f "$file.aux" || return 0 + cmp -s "$file.aux" "$tmp/$file.aux" || run_tex=true +} + + +# bibtex: Citations + +save_bibtex() +{ + if [ -f "$file.aux" ] + then egrep '^\\(citation|bibdata)' "$file.aux" | + sort >"$tmp/$file.bib" + else touch "$tmp/$file.bib" + fi +} + + +check_bibtex() +{ + test "$do_bibtex" -a -f "$file.aux" || return 0 + egrep '^\\(citation|bibdata)' "$file.aux" | sort >$tmp/bib.new + if grep '^\\bibdata' $tmp/bib.new >/dev/null + then if cmp -s "$tmp/$file.bib" $tmp/bib.new + then : do nothing + else bibtex "$file" + run_tex=true + fi + fi +} + + +# idx: raw index data + +save_idx() +{ + if [ -f "$file.idx" ] + then cp "$file.idx" $tmp + else touch "$tmp/$file.idx" + fi +} + +check_idx() +{ + test "$do_makeindex" -a -f "$file.idx" || return 0 + if cmp -s "$file.idx" "$tmp/$file.idx" + then : do nothing + else makeindex "$file" + run_tex=true + fi +} + + +# Two functions that collect the functions above. + +save_aux_info() +{ + save_aux + save_bibtex + save_idx +} + +check_aux_info() +{ + check_aux + check_bibtex + check_idx +} + + +# Process the document by TeX. Determine if TeX must be run anew by +# the functions realized above. + +run_tex=true +while [ "$run_tex" ] + do save_aux_info + "$@" + run_tex='' + check_aux_info + done + + + +#====================================================================== +# +# $ITIlog: tex-it,v $ +# Revision 1.3 1995/06/14 10:49:12 schrod +# HP-UX /bin/sh doesn't grok getopts, use ksh instead. +# +# Revision 1.2 1995/04/19 14:31:06 schrod +# Support MakeIndex call, too. +# +# Revision 1.1 1995/03/14 17:07:26 schrod +# Added script to process a TeX document. +# diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/wcltx.bib b/Master/texmf-dist/doc/latex/cweb-latex/examples/wcltx.bib new file mode 100644 index 00000000000..007879df1f4 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/wcltx.bib @@ -0,0 +1,23 @@ +$Id: wcltx.bib,v 1.1 1993/04/09 15:36:52 schrod Exp $ +---------------------------------------------------------------------- + +% +% extracted from litprog.bib database +% + +@string{ tub = "TUGboat"} + +@article{litprog:schrod:cweb, + author = {Klaus Guntermann and Joachim Schrod}, + title = {{\WEB} adapted to {C}}, + journal = tub, + volume = 7, + number = 3, + month = {}, + year = 1986, + pages = {134-137}, + annote = {\js{} My {\small CWEB}, an adaption of Knuth's Pascal +\WEB{}, ie, written in \WEB{}. Created to write an IBM~/370 +assembler/emulater for undergrad CS courses. I was an graduate +student, Klaus was my supervisor then.} +} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/examples/wcltx.w b/Master/texmf-dist/doc/latex/cweb-latex/examples/wcltx.w new file mode 100644 index 00000000000..4b82bd04f65 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/examples/wcltx.w @@ -0,0 +1,327 @@ +% $Id: wcltx.w,v 1.4 1995/08/29 17:27:57 schrod Exp $ +%------------------------------------------------------------ + +% +% wc: An example of CWEB by Silvio Levy and Donald E. Knuth +% +% [LaTeX] +% (history at end) + + +%% -js: +%% should rework it: ANSI C compliance, POSIX.2 compliant option +%% parsing with getopt(), including *all* required header files (ie, +%% POSIX.1 compliance), using POSIX return codes and types, etc. + + + +\documentclass{cweb} + +\usepackage{rcs} + + +% +% some tags for this document +% +\def\CEE/{C\spacefactor 1000 } +\def\cweb{{\tt CWEB\/}} +\def\SPARC{SPARC\-\kern.1em station} +\def\UNIX/{{\small UNIX\/}} +\def\wc{{\tt wc\/}} +\def\WEB{{\tt WEB\/}} + +\hfuzz=0.5pt + + + + +\begin{document} + + + +\title{Counting words} +\author{Silvio Levy\and Donald E. Knuth} +\begingroup +\def\thefootnote{\hbox{$^*$}} +\footnotetext[0]{\LaTeX{} markup by Joachim Schrod.} +\endgroup +\RCSdate $Date: 1995/08/29 17:27:57 $ + +\maketitle + +% not very interesting, only one starred section +% \tableofcontents + + + +@* An example of \cweb{}. This example, based on a program by +Klaus Guntermann and Joachim Schrod~\cite{litprog:schrod:cweb} +presents the ``word count'' program from \UNIX/, rewritten in +\cweb{} to demonstrate literate programming in \CEE/.% + \footnote{% + Incidentally, Klaus Guntermann and Joachim Schrod are now +using this \cweb{} and have stopped the support for their version. +Joachim Schrod contributed the \LaTeX{} style used for the markup of +this document. + } +The level of detail in this document is intentionally high, for +didactic purposes; many of the things spelled out here don't need to +be explained in other programs. + +The purpose of \wc{} is to count lines, words, and/or characters in a +list of files. The number of lines in a file is the number of newline +characters it contains. The number of characters is the file length in bytes. +A ``word'' is a maximal sequence of consecutive characters other than +newline, space, or tab, containing at least one visible ASCII code. +(We assume that the standard ASCII code is in use.) + +@ Most \cweb{} programs share a common structure. It's probably a +good idea to state the overall structure explicitly at the outset, +even though the various parts could all be introduced in unnamed +sections of the code if we wanted to add them piecemeal. + +Here, then, is an overview of the file \texttt{wcltx.c} that is +defined by this \cweb{} program \texttt{wcltx.w}: + +@c +@<Header files to include@>@/ +@<Global variables@>@/ +@<Functions@>@/ +@<The main program@> + +@ We must include the standard I/O definitions, since we want to send +formatted output to |stdout| and |stderr|. + +@<Header files...@>= +#include <stdio.h> + +@ The |status| variable will tell the operating system if the run was +successful or not, and |prog_name| is used in case there's an error message to +be printed. + +@d OK 0 /* |status| code for successful run */ +@d usage_error 1 /* |status| code for improper syntax */ +@d cannot_open_file 2 /* |status| code for file access error */ + +@<Global variables@>= +int status=OK; /* exit status of command, initially |OK| */ +char *prog_name; /* who we are */ + +@ Now we come to the general layout of the |main| function. + +@<The main...@>= +main (argc,argv) + int argc; /* the number of arguments on the \UNIX/ command line */ + char **argv; /* the arguments themselves, an array of strings */ +{ + @<Variables local to |main|@>@; + prog_name=argv[0]; + @<Set up option selection@>; + @<Process all the files@>; + @<Print the grand totals if there were multiple files @>; + exit(status); +} + +@ If the first argument begins with a `\texttt{-}', the user is choosing +the desired counts and specifying the order in which they should be +displayed. Each selection is given by the initial character +(lines, words, or characters). For example, `\texttt{-cl}' would cause +just the number of characters and the number of lines to be printed, +in that order. + +We do not process this string now; we simply remember where it is. + It will be used to control the formatting at output time. + +@<Var...@>= +int file_count; /* how many files there are */ +char *which; /* which counts to print */ + +@ @<Set up o...@>= +which="lwc"; /* if no option is given, print all three values */ +if (argc>1 && *argv[1] == '-') { which=argv[1]+1; argc--; argv++; } +file_count=argc-1; + +@ Now we scan the remaining arguments and try to open a file, if +possible. The file is processed and its statistics are given. +We use a |do|~\dots~|while| loop because we should read from the +standard input if no file name is given. + +@<Process...@>= +argc--; +do@+{ + @<If a file is given, try to open |*(++argv)|; |continue| if unsuccessful@>; + @<Initialize pointers and counters@>; + @<Scan file@>; + @<Write statistics for file@>; + @<Close file@>; + @<Update grand totals@>; /* even if there is only one file */ +}@+while (--argc>0); + +@ Here's the code to open the file. A special trick allows us to +handle input from |stdin| when no name is given. +Recall that the file descriptor to |stdin| is~0; that's what we +use as the default initial value. + +@<Variabl...@>= +int fd=0; /* file descriptor, initialized to |stdin| */ + +@ @d READ_ONLY 0 /* read access code for system |open| routine */ + +@<If a file...@>= +if (file_count>0 && (fd=open(*(++argv),READ_ONLY))<0) { + fprintf (stderr, "%s: cannot open file %s\n", prog_name, *argv); +@.cannot open file@> + status|=cannot_open_file; + file_count--; + continue; +} + +@ @<Close file@>= +close(fd); + +@ We will do some homemade buffering in order to speed things up: Characters +will be read into the |buffer| array before we process them. +To do this we set up appropriate pointers and counters. + +@d buf_size BUFSIZ /* \texttt{stdio.h}'s |BUFSIZ| is chosen for efficiency */ + +@<Var...@>= +char buffer[buf_size]; /* we read the input into this array */ +register char *ptr; /* the first unprocessed character in |buffer| */ +register char *buf_end; /* the first unused position in |buffer| */ +register int c; /* current character, or number of characters just read */ +int in_word; /* are we within a word? */ +long word_count, line_count, char_count; /* number of words, lines, + and characters found in the file so far */ + +@ @<Init...@>= +ptr=buf_end=buffer; line_count=word_count=char_count=0; in_word=0; + +@ The grand totals must be initialized to zero at the beginning of the +program. If we made these variables local to |main|, we would have to +do this initialization explicitly; however, \CEE/'s globals are automatically +zeroed. (Or rather, ``statically zeroed.'') (Get it?) +@^Joke@> +%% -js: The joke would be better if the vars would be static, which +%% they aren't in the C sense... + +@<Global var...@>= +long tot_word_count, tot_line_count, tot_char_count; + /* total number of words, lines, and chars */ + +@ The present section, which does the counting that is \wc{}'s \emph{raison +d'\^etre}, was actually one of the simplest to write. We look at each +character and change state if it begins or ends a word. + +@<Scan...@>= +while (1) { + @<Fill |buffer| if it is empty; |break| at end of file@>; + c=*ptr++; + if (c>' ' && c<0177) { /* visible ASCII codes */ + if (!in_word) {word_count++; in_word=1;} + continue; + } + if (c=='\n') line_count++; + else if (c!=' ' && c!='\t') continue; + in_word=0; /* |c| is newline, space, or tab */ +} + +@ Buffered I/O allows us to count the number of characters almost for free. + +@<Fill |buff...@>= +if (ptr>=buf_end) { + ptr=buffer; c=read(fd,ptr,buf_size); + if (c<=0) break; + char_count+=c; buf_end=buffer+c; +} + +@ It's convenient to output the statistics by defining a new function +|wc_print|; then the same function can be used for the totals. +Additionally we must decide here if we know the name of the file +we have processed or if it was just |stdin|. + +@<Write...@>= +wc_print(which, char_count, word_count, line_count); +if (file_count) printf (" %s\n", *argv); /* not |stdin| */ +else printf ("\n"); /* |stdin| */ + +@ @<Upda...@>= +tot_line_count+=line_count; +tot_word_count+=word_count; +tot_char_count+=char_count; + +@ We might as well improve a bit on \UNIX/'s \wc{} by displaying the +number of files too. + +@<Print the...@>= +if (file_count>1) { + wc_print(which, tot_char_count, tot_word_count, tot_line_count); + printf(" total in %d files\n",file_count); +} + +@ Here now is the function that prints the values according to the +specified options. The calling routine is supposed to supply a +newline. If an invalid option character is found we inform +the user about proper usage of the command. Counts are printed in +8-digit fields so that they will line up in columns. + +@d print_count(n) printf("%8ld",n) + +@<Fun...@>= +wc_print(which, char_count, word_count, line_count) +char *which; /* which counts to print */ +long char_count, word_count, line_count; /* given totals */ +{ + while (*which) + switch (*which++) { + case 'l': print_count(line_count); break; + case 'w': print_count(word_count); break; + case 'c': print_count(char_count); break; + default: if ((status & usage_error)==0) { + fprintf (stderr, "\nUsage: %s [-lwc] [filename ...]\n", prog_name); +@.Usage: ...@> + status|=usage_error; + } + } +} + +@ Incidentally, a test of this program against the system \wc{} +command on a \SPARC\ showed that the ``official'' \wc{} was slightly +slower. Furthermore, although that \wc{} gave an appropriate error +message for the options `\texttt{-abc}', it made no complaints about the +options `\texttt{-labc}'! Dare we suggest that the system routine +might have been +better if its programmer had used a more literate approach? + + + +\bibliographystyle{plain} +\bibliography{wcltx} + + +@ + +\cwebIndexIntro{% + Here is a list of the identifiers used, and where they appear. +Underlined entries indicate the place of definition. Error messages +are also shown. + } + +\end{document} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% $Log: wcltx.w,v $ +% Revision 1.4 1995/08/29 17:27:57 schrod +% Recoded to LaTeX2e markup. +% +% Revision 1.3 1993/06/15 14:01:14 schrod +% Renamed document to wcltx, must change \bibliography tag, too. +% +% Revision 1.2 1993/06/15 13:35:12 schrod +% `cweb' is now a style, was an option formerly. +% +% Revision 1.1 1993/04/09 15:00:37 schrod +% Initial revision +% diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/Imakefile b/Master/texmf-dist/doc/latex/cweb-latex/src/Imakefile new file mode 100644 index 00000000000..64bd313b8f5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/Imakefile @@ -0,0 +1,106 @@ +XCOMM $Id: Imakefile,v 1.7 1995/11/21 00:41:31 schrod Exp $ +/* ---------------------------------------------------------------------- */ + +/* + * Imakefile for cweb bundle + * + * (history at end) + */ + + +/* needed modules */ +#include <TeX.imk> +#include <makeprog.imk> + +#include <install/TeX.imk> + +XCOMM ------------------------------------------------------------ +XCOMM continue in Imakefile + + +/* exported files */ + +MpDoc2TeXTarget(cwebbase,tex) +MpDoc2TeXTarget(cweb,cls) +MpDoc2TeXTarget(cwebparts,sty) + +TeXTarget(latex,cweb-user) +TeXTarget(latex,cweb-conf) + + +/* for some time, until it's moved to an own bundle */ + +AllTarget(keyvald.sty) + +keyvald.sty: keyvald.dtx + latex keyvald.ins + +clean:: + $(RM) keyvald.sty + + +/* installation */ + +#ifdef ITI_Site + DESTDIR = /archives/tex/Install +#endif + +InstallTeXLaTeX(cweb,cweb.cls cwebbase.tex cwebarray.sty keyvald.sty \ + cwebparts.sty cwbl-german.sty) +InstallTeXDoc(latex/styles/cweb,cweb-user.dvi) +InstallTeXDoc(latex/styles/cweb,cweb-conf.dvi) + + +/* internal documentation */ + +TeXFileTarget(latex,cweb,doc) +TeXFileTarget(latex,cwebbase,doc) +TeXFileTarget(latex,cwebparts,doc) +TeXTarget(latex,cweave-spec) + + +/* distribution */ + +distrib:: all cweb.dvi cwebbase.dvi cwebparts.dvi + mv cweb-*.dvi *.cls cwebbase.tex keyvald.sty .. + cp cwebarray.sty cwbl-german.sty .. + cp $(HOME)/Notes/README.latex.doc-src README + $(MAKE) realclean + +realclean:: clean + $(RM) Makefile + + + +/* ============================================================ + * + * $Log: Imakefile,v $ + * Revision 1.7 1995/11/21 00:41:31 schrod + * German language package. + * + * Revision 1.6 1995/09/17 14:21:25 schrod + * Add support for German CWEB documents. + * + * Revision 1.5 1995/09/16 17:00:18 schrod + * Extract cwebbase.tex from cweb.cls, add cwebparts.sty. + * + * Revision 1.4 1995/08/29 17:34:39 schrod + * LaTeX CWEB, version 1.0. + * + * Revision 1.3 1995/08/29 15:19:47 schrod + * Added (hint to non-existence of) description of the internal interface. + * + * Revision 1.2 1995/08/25 19:00:32 schrod + * Add enhanced version of keyval package, with ability to specify + * default action for unknown keyword options. + * + * Revision 1.1 1995/08/08 00:14:24 schrod + * Updated to \LaTeXe{}, the |cweb| style is now a document class. Used + * my standard templates for that, no changes in functionality. + * + + * ------------------------------------------------------------ + * Local Variables: + * mode: Indented-Text + * End: + */ diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/README b/Master/texmf-dist/doc/latex/cweb-latex/src/README new file mode 100644 index 00000000000..0e7a4836715 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/README @@ -0,0 +1,31 @@ +latex-style:src/README 29 Aug 95 +---------------------------------------------------------------------- + +Please note: This directory is part of the distribution primarily for your +information. It's not prepared to be usable by you, sorry. + +In particular, probably you won't have tools and style files I take +for granted during development. Please don't complain, either use the +supplied installable files (as listed in ../MANIFEST) or search & get +the missing files. I will neither stop adding this directory to the +distribution, nor will I add all missing files. + +On the one hand I won't restrict my own development environment by not +using available tools, on the other hand I'll want to make my source +available for those who have a similar environment to mine. + + +For your orientation: + + *.doc -- master file for TeX macro files + *.dvi -- typeset version of *.doc + *-user.tex -- user manual + *-conf.tex -- (optional) internal interface description + *.tex -- (optional) other documentation parts + *.{fig,latex} -- (optional) figures prepared with xfig + *.sty -- needed to process the above documents + + TODO -- (optional) personal notes for future revisions + Imakefile -- does not use MIT's Imake templates + style/ -- (optional) files for AUC-TeX + test/ -- test cases diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/TODO b/Master/texmf-dist/doc/latex/cweb-latex/src/TODO new file mode 100644 index 00000000000..82fddd2ee5c --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/TODO @@ -0,0 +1,168 @@ +% $Id: TODO,v 1.10 1995/11/30 15:44:51 schrod Exp $ +%---------------------------------------------------------------------- + + +---------------------------------------------------------------------- + +functionality [problem] + +In plain CWEB chunks are not split over pages, LaTeX CWEB does so. Add +an option that re-establishs the behaviour of plain CWEB. + +Problem reported by Denis B. R\"ogel <denis.roegel@loria.fr> + +---------------------------------------------------------------------- + +functionality [problem] + +User index would use with standard LaTeX markup (\index) would use +*.idx as raw index file. This file is used by CWEAVE as tagged index +file. + +Shall I redefine \makeindex? + +---------------------------------------------------------------------- + +functionality [proposal] + +Add support to create the illusion of more than one refinement in a +chunk. + +\cwebNoChunkIntro; see cwebx.sty. +Proposed by Christopher Higgins <C.Higgins@cit.gu.edu.au>. +Ack him for that. + +---------------------------------------------------------------------- + +functionality [proposal] + +Add support for CWEB code examples. + +For that code from cwebparts.doc must be moved to cwebbase.doc; see +cwebx.sty. That code has also several improvements over cwebparts.doc! +cwebparts.doc is needed later for typesetting sections, etc. Well, if +that can really be realized in a document/project independent way. +Don't know if I really need it. (Except as a user front end. But I +can also use cwebbase for that.) + +---------------------------------------------------------------------- + +functionality [proposal] + +Add support for HyperTeX. + +Proposed by Christopher Higgins <C.Higgins@cit.gu.edu.au>. + +---------------------------------------------------------------------- + +list headers [error] + +Use \chaptermark & \sectionmark, in \CwebListSection. + +Maybe discard \@mkboth from \CwebIdIndex, \CwebRefList, etc. It's +supposed to be changed by a pagestyle, but this doesn't happen with +fancyheadings anyhow -- and face it, fancyheadings is the method of +choice for head-/footline creation. + +The actual code was caused by stupid copying from LaTeX standard +classes; with the change it's possible to have other list heading +layout (add to toc, other marks, etc.) + +But check if I can use that in \CwebIdIndex: There \CwebListSection is +used in an \twocolumn optional arg, that will eventually trigger the +output routine and will be set as a float. Does marks correctly +migrate out of floats? + +---------------------------------------------------------------------- + +layout [error] + +In chunks without documentation, a refinement is too near to the chunk +marker. In addition, the distance is not independent of +\CwebIndentUnit, making it impossible to change the latter. + +NOTE: Might be a problem of \cwebNoChunk that should start a +paragraph. *When* will CWEAVE add `\4' after `\B'? Have to make tests +for that. How can I detect an empty documentation section? + +\B kind of repaired in cwebx.sty. + +---------------------------------------------------------------------- + +layout [error] + +Chunk numbers are not exactly aligned in all circumstances, see fixme +remark in cwebbase.doc. + +---------------------------------------------------------------------- + +interface [idea] + +Name all \cwbb@... macros used in other modules \Cwbb... (or even +\cwbb...). + +---------------------------------------------------------------------- + +markup [proposal] + +Support delimiting section titles by braces. + +Maybe one needs an option to turn that on. + +Supported by Peter Wainwright <prw-b@ugrad.cs.york.ac.uk>. + +---------------------------------------------------------------------- + +documentation [ack] + +Who sent the mail concerning \hb@xt@? Add to acks. Change log message +for it, too (cweb.doc: 3.4; cwebbase.doc: 1.4). + +---------------------------------------------------------------------- + +documentation [problem] + +cweb-conf.tex: + +Cseq name of chunk marker (paragraph symbol). +Ack Christopher Higgins \path|<c.higgins@cit.gu.edu.au>|. + +\CwebRankNoEject. (Implies explication of rank numbers. Should be +explicated in cwebbase.doc as well, btw.) +Ack Nicholas Urbanik \path|<nicku@iohk.com>| + +Support for another language must be stored in cwbl-*.sty. Check +cwbl-german.sty for the cseqs that must be redefined, list their +original English text for clarification. + +---------------------------------------------------------------------- + +distribution [problem] + +cweb.cls & cwebbase.tex is > 100KB now. Export it in uncommented form. + +---------------------------------------------------------------------- + +distribution [problem] + +It's better to collect stuff from contrib, and have each file that +shall be installed in top dir. + +This means a Makefile in contrib/; and changes in README, INSTALL, and +maybe even MANIFEST. + +---------------------------------------------------------------------- + +distribution [proposal] + +Add hint to TODO in README. Maybe point out that src/ sometimes holds +prereleases of future styles. + +---------------------------------------------------------------------- + +distribution [proposal] + +Install TODO in doc dir. The end user should see open problems and +plans, too. + +---------------------------------------------------------------------- diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cwbl-german.sty b/Master/texmf-dist/doc/latex/cweb-latex/src/cwbl-german.sty new file mode 100644 index 00000000000..68a7ce6c054 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cwbl-german.sty @@ -0,0 +1,109 @@ +% $Id: cwbl-german.sty,v 1.1 1995/09/17 14:21:25 schrod Exp $ +%---------------------------------------------------------------------- + +% +% LaTeX2e package cwbl-german +% adapt CWEB documents to language `german' +% +% [LaTeX2e] +% (history at end) + + +% Identification. The code below is explained in the implementation +% documentation of the rcs package. + +\begingroup + \def\RCSPackage#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesPackage{#1}[\date\space\id\space #2]% + } + + \RCSPackage{cwbl-german}{German CWEB documents} + $Date: 1995/09/17 14:21:25 $: 9999/00/00 \endRCS + $Revision: 1.1 $: 0.0 \endRCS +\endgroup + + +% +% What's this package for? +% +% XXX +% + + +% This class is supported. Send bug reports, comments and repairs. +% +% The reference version may be retrieved via anonymous ftp from +% |ftp.th-darmstadt.de| [130.83.47.112], directory |pub/tex/latex|. It's +% placed there as a gzipped tar file. (The information on the +% IP~number is dated 17 Sep 95. It might have changed, also +% this is very unlikely. Use your friendly nameserver.) + + +%%% ------------------------------------------------------------ + + +% at the end of chunks + +\def\CwebCRAlso{\CwebCrossRef{Siehe auch Baustein}} +\def\CwebCRsAlso{\CwebCrossRef{Siehe auch Bausteine}} + +\def\CwebCRCite{\CwebCrossRef{Dies wird zitiert im Baustein}} +\def\CwebCRsCite{\CwebCrossRef{Dies wird zitiert in den Bausteinen}} + +\def\CwebCRUse{\CwebCrossRef{Dies wird benutzt im Baustein}} +\def\CwebCRsUse{\CwebCrossRef{Dies wird benutzt in den Bausteinen}} + +\def\CwebCREt{ und~} +\def\CwebCRsEt{ und~} + + +% back matter + +\def\CwebCRChanged{% + \CwebCrossRef{% + Die folgenden Bausteine wurden durch ein Changefile ge\"andert:% + }% + } +\def\CwebChangedListName{Ge\"anderte Bausteine} + + +\def\CwebRefListName{Verzeichnis der Verfeinerungen} + +\def\CwebXRCite{\CwebCrossRef{Zitiert im Baustein}} +\def\CwebXRCites{\CwebCrossRef{Zitiert in den Bausteinen}} +\def\CwebXRUse{\CwebCrossRef{Benutzt im Baustein}} +\def\CwebXRUses{\CwebCrossRef{Benutzt in den Bausteinen}} + + +\def\CwebMacrosHere{% + \begingroup + \def\CwebRefNumber##1{}% + \CwebRefName :Pr\"aprozessor Definitionen\X + \endgroup + } + + + +\endinput + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% $Log: cwbl-german.sty,v $ +% Revision 1.1 1995/09/17 14:21:25 schrod +% Add support for German CWEB documents. +% + + + +%%%------------------------------------------------------------ + +% Local Variables: +% mode: LaTeX +% TeX-brace-indent-level: 4 +% TeX-parse-self: nil +% TeX-auto-save: nil +% TeX-master: t +% page-delimiter: "^%%%" +% End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex b/Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex new file mode 100644 index 00000000000..c1f5b4f07ff --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex @@ -0,0 +1,403 @@ +% $DocId: cweave-spec.tex,v 1.8 1995/09/12 22:56:02 schrod Exp $ +%------------------------------------------------------------ + +% +% specification of CWEAVE/TeX interface +% +% [LaTeX] +% (history at end) + + +% This file is either a subdocument of the style doc or a document on +% its own. In the former case it's a chapter, in the latter it's a +% ``normal'' LaTeX progltx document. +% If it's a subdocument, this file will be included after +% \begin{document}. We can detect this: \document redefines +% \documentclass to be \@twoclasseserror. Then we also have to define +% how this document is ended: Either by \endinput or by an additional +% revision log. +% Of course, this test works only if LaTeX 2e is used for processing. + +\expandafter\ifx \csname @twoclasseserror\endcsname \documentclass + + \let\endSubDocument=\endinput + + \chap The interface between \cweave{} and \TeX{}. + \label{sec:cweave-spec} + +\else + + \let\endSubDocument=\relax + + \documentclass{progltx} + + \usepackage{cweb-doc} % additional document-specific markup + \usepackage{a4-9} % Tschichold's A4 layout + + + \begin{document} + + \title{The Interface between \cweave{} and \TeX{}} + \author{Joachim Schrod% + \thanks{Email: \texttt{schrod@iti.informatik.th-darmstadt.de}}% + } + \RCSdate $DocDate: 1995/09/12 22:56:02 $ + + \maketitle + + \sect + +\fi + + + + +Here we present all tags output by \cweave{}% + \footnote{This information refers to \cweb{}~3.4. Differences to + other 3.x versions of \cweave{} are minor and can be ignored in + our context. See the revision log of the complete interface specs + document for more information.} +in an ordered fashion. First we look at those +tags which are part of the `protected interface,' i.e., they are +visible to a \cweb{} user, but he must not use them. Then we consider +the private tags, some are used in the documentation part, others +are needed to typeset program code, and there are a few tags for +typesetting special characters in strings. + + +\sect Some tags output by \cweave{} are part of the protected +interface even though they are not prefixed by |cweb|. We'll present +them in the order they'll arrive in the document instance. + +The following table specifies in the second column if this tag takes +arguments. If the entry is non-empty, it's either a number listing +just how many arguments are expected; then usual argument passing is +used. Or it displays the context required. + % +\begin{cseqtab} +|\ATL| & \verb*|#1 #2 | & \cweb{} operator: |@l| + && (how to output non-ASCII chars in \ctangle{}) + && \arg1 hex code of mapped character + && \arg2 string output by \ctangle{} +|\M| & 1 & \cweb{} structure tag: start of a chunk + && \arg1 chunk number +|\N| & |#1#2#3.| & \cweb{} structure tag: start of a section + && \arg1 section rank, $0 \le |#1| \le 10$ + && \arg2 chunk number + && \arg3 section title +|\PB| & 1 & restricted program mode material + && \arg1 program code +|\Y| & & between major pieces of a program part +|\B| & & start program material +|\fi| & & \cweb{} structure tag: end of a chunk +|\9| & 1 & index entry, user defined layout + && \arg1 text of index entry +\end{cseqtab} + +|\ATL| does only appear in front of the very first chunk. The +chunk number is an explicit \TeX{} number which might be followed +by a `changed flag' (see chunk~\ref{sec:text-tag.priv}). Note the +usage of |\fi|, ie, each chunk must open an according |\if|. |\PB| +might appear within its own argument (created by restricted program +mode material in a refinement name within restricted program mode). + +|\9| deserves a further explanation: It is expected, though not +defined, that it expands to an empty token list. The parameter will +be a sort key, actually; the real key to be typeset will appear +afterwards. So a \cweb{} user might index \TeX{} as +`|@:TeX}{\TeX@>|', the index will feature it in the ``T''~chunk, +not in the ``|\|''~chunk. + +With the exception of |\PB| the tags above will not appear in math mode. + + +\sect The following tags might appear to be public ones, but they +are, in fact, never used. That's because they will be placed after +the |\fi| which terminates the last chunk. Our problem is that we +have to produce the information which were produced by these tags in +the Plain macros. Namely the optional lists poses us the problems. We +must read behind the document end to gather the information which +lists to produce. + +%% This label is used in cweb.doc +\label{spec:sec:docend} + +We can depend on the following rules. + % +\begin{enumerate} + +\item If |\end| is found, there will be no other of these tags. + +\item |\ch| comes first, but is optional. + +\item |\inx\fin| come next, they are mandatory. + +\item |\con| is optional again; if it is found it's the very last +token to look at in this document. + +\end{enumerate} + % +\begin{fixme} + +Perhaps |\inx| should be defined as |\end{document}|, and both |\ch| +and |\inx| should be added to the protected interface. Then the user +may simply omit |\end{document}|. But we should take care of a +possible occurence anyhow. + +\end{fixme} + +Here are the tags mentioned in this chunk, and their respective +meaning in the Plain version: + % +\begin{cseqtab} +|\ch| & |#1.| & Note which chunks are changed + && \arg1 list of chunk numbers, like in |\U| and such. +|\inx| & & Create index +|\fin| & & Create the table of refinement names +|\con| & & Create the table of contents +|\end| & & output if index and all lists were suppressed +\end{cseqtab} + + + +\sect \label{sec:text-tag.priv} + Some tags appear only in special circumstances and may therefore be +considered as private tags. The largest part of them concern the tagging of +program code, we'll have a look at them later. First we present the +tags used in other areas. + +Lists of chunk numbers occurs on several places: At the chunk +start (where the list has actually only one element), within +refinement names, in the identifier index, and for cross reference +purposes. Cross references can be made at the end of a chunk, and +in the refinement name list at the very end. Everywhere where a +chunk number can occur it can be followed by a tag which shows that +this chunk was changed by the changefile. + % +\begin{cseqtab} +|\*| & & tag after chunk number: this chunk is changed. +\end{cseqtab} + +Within the identifier index we have also special tags. The identifiers +are tagged like in the program mode, ie, with |\\| and |\&|. Remember +that |\9|, listed above, appears also in the index. + % +\begin{cseqtab} +|\I| & \verb*|#1, | & start of an index entry + && \arg1 index entry +|\[| & |#1]| & underlined chunk number in index + && \arg1 chunk number +|\.| & 1 & |@.| index entry + && \arg1 index entry +\end{cseqtab} + +In the list of refinement names the entries are marked similar to +the index entries. But note that |\I| has no arg here. + % +\begin{cseqtab} +|\I| & & start of a new refinement name +\end{cseqtab} + + +\sect \label{sec:prog-tag} + OK, now we can have a look at the large amount of tags used +for tagging program code. First, we have those which represent +directly C or \C++ tokens. + % +\begin{cseqtab} +|\?| & & C operator: conditional expression +|\AND| & & C operator: logical and +|\CM| & & C operator: binary complement +|\DC| & & \C++ operator: scope resolution +|\E| & & C operator: equivalence + && and equivalence sign after refinement name on it's definition +|\G| & & C operator: greater or equal +|\GG| & & C operator: shift right +|\I| & & C operator: not equal +|\K| & & C operator: assignment +|\LL| & & C operator: shift left +|\MG| & & C operator: pointer to struct component +|\MGA| & & \C++ operator: pointer to pointer to member +|\MM| & & C operator: decrement +|\MOD| & & C operator: modulo (actually, remainder) +|\NULL| & & `quoted' identifier +|\OR| & & C operator: binary or +|\PA| & & \C++ operator: pointer to member +|\PP| & & C operator: increment +|\R| & & C operator: logical negation +|\this| & & `quoted' identifier +|\TeX| & & `customized' identifier +|\V| & & C operator: logical or +|\W| & & C operator: logical and +|\XOR| & & C operator: binary exclusive or +|\Z| & & C operator: less or equal +\end{cseqtab} + +Other tokens have variable parts, passed as arguments. + % +\begin{cseqtab} +|\.| & 1 & C string + && \arg1 string +|\)| & & discretionary break between string parts +|\&| & 1 & reserved identifier + && \arg1 identifier +|\\| & 1 & ``normal'' identifier with more than one chars + && \arg1 identifier +\verb"\|" & 1 & ``normal'' identifier with one char + && \arg1 character +|\C| & 1 & C comment + && \arg1 comment text +|\MRL| & 1 & C operator: combined binary operators + && \arg1 operators, |\K| must print as `$=$' +|\SHC| & 1 & \C++ comment + && \arg1 comment text +|\T| & 1 & numeric constants + && \arg1 constant +|\X| & |#1: #2\X| & refinement name + && \arg1 chunk number + && \arg2 refinement name +\end{cseqtab} + % +The refinement name (second argument of |\X|) may be a file name +tagged by `|\.|'. Then the name must be set like a C~string. + +\cweb{} itself introduces its own operators: + % +\begin{cseqtab} +|\ATH| & & |@h| (place the preprocessor definitions here) +|\D| & & |@d| (define macro) +|\F| & & |@f| (format identifier like another one) +|\J| & & |@&| (join) +|\vb| & 1 & |@=| (pass arg verbatim by \ctangle{}) + && \arg1 string +\end{cseqtab} + +And we have some tags used for cross referencing. Chunk +cross-referencing (actually, for program parts) is started with some +tag, then follows a list of chunk numbers. + % +\begingroup + \hfuzz=22pt % 21.76602pt too wide (with a4-9.sty) +\begin{cseqtab} +|\A| & & one add-on definition (``See also chunk'') +|\As| & & more than one add-on definition (``See also chunks'') +|\ET| & & separator between the last two numbers if there are only two +|\ETs| & & separator between the last two numbers if there are more than two +|\Q| & & the chunk where it is cited (``This code is cited in chunk'') +|\Qs| & & more than one chunk where it is cited (``This code is cited in chunk'') +|\U| & & used in one chunk (``This code is used in chunk'') +|\Us| & & used in more than one chunk (``This code is used in chunks'') +\end{cseqtab} +\endgroup + +Program code must be indented according to its structure. Each +``larger'' statement is typeset as one paragraph, usually only one +line long. The basic indentation of the next statement may be +incremented and decremented in given units. If a statement has to be +broken in more than one line nevertheless, a hanging indentation is +added to the basic indentation for the subsequent lines. One can mark +an `optional' statement start, ie, some kind of optional paragraph +start. If a line break must be inserted it should be inserted here and +no hanging indentation should be added to the basic indentation. + % +\begin{cseqtab} +|\1| & & future stmts indented one more unit +|\2| & & future stmts indented one less unit +|\3| & 1 & optional line break within a statement + && \arg1 digit, penalty for line break +|\4| & & backspace one indentation unit +|\5| & & optional line break or small space (between run-in statements) +|\6| & & line break +|\7| & & line break and additional vertical space +|\8| & & line is a preprocessor directive (must be issued at start of line) +\end{cseqtab} + + +\sect Some args are designated as strings above. Within these args the +following tags are used to represent special characters: + % +\begin{cseqtab} +\verb*|\ | & & space +|\&| & & ampersand +|\\| & & backslash +|\^| & & hat +|\_| & & underscore +|\{| & & left brace +|\}| & & right brace +|\~| & & tilde +\end{cseqtab} + + +\sect Last, we have tags which are used in their ``standard'' +\LaTeX{} meaning. We don't have much work with them: + % +\begin{cseqtab} +|\#| & & hash mark in program or in string +|\$| & & dollar +|\%| & & percent +|\{| & & block start (is set in math mode) +|\}| & & block end (is set in math mode) +|\,| & & thin space (like the \LaTeX{} default) +|\langle| & & left delimiter in include directives, or in templates +|\le| & & C operator: less or equal +|\ldots| & & Function protoypes: Variable number of arguments +|\rangle| & & right delimiter in include directives, or in templates +\end{cseqtab} + + + + +\endSubDocument + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\vskip \PltxPreSectSkip + +\begin{rcslog} +$DocLog: cweave-spec.tex,v $ +\Revision 1.8 1995/09/12 22:56:02 schrod +|cweave -x| doesn't output |\vfill| in front of |\end| any more. +Change noticed in \cweb{} 3.4. + +\Revision 1.7 1995/08/29 01:40:24 schrod +Checked the interface description for \cweb{}~3.4. + +\Revision 1.6 1995/08/25 19:09:57 schrod +Cleaned up terminology: Chunks are not named sections any more. +Explicate possible range of section ranks. + +\Revision 1.5 1995/08/08 00:14:26 schrod +Updated to \LaTeXe{}, the |cweb| style is now a document class. Used +my standard templates for that, no changes in functionality. + +\Revision 1.4 1993/06/17 15:09:28 schrod +\cweb{} 3.0 was released officially on June 16, 1993. Mentioned in +the documentation that this version is needed for the |cweb| style. + +\Revision 1.3 1993/06/14 17:50:14 schrod +Clarify the occurence pattern of the lists after the last section: +which are optional, the expected order, etc. + +Changed `cseq' to `tag'. On this level of abstraction (that's the +specification!), we're still not considering \TeX{}nical details. + +\Revision 1.2 1993/06/14 15:40:02 schrod +Adapted to April 93 changes to \cweave{}: |\N| has three parameters +(added group level), |\M| param is no data-tag any more, |\Z| and +|\MRL| are new. + +Added further explanation of |\9| and |\X|. + +Replaced `program part name' by `refinement name'. + +\Revision 1.1 1993/04/09 15:00:37 schrod +Initial revision + +\end{rcslog} + + + +\end{document} + +% LocalWords: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-conf.tex b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-conf.tex new file mode 100644 index 00000000000..86dd2ae04e4 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-conf.tex @@ -0,0 +1,103 @@ +% $DocId: cweb-conf.tex,v 2.1 1995/08/29 15:19:45 schrod Exp $ +%------------------------------------------------------------ + +% +% internal interface of cweb class +% +% [LaTeX] +% (history at end) + + +% This file is either a subdocument of the style doc or a document on +% its own. In the former case it's a chapter, in the latter it's a +% ``normal'' LaTeX progltx document. +% If it's a subdocument, this file will be included after +% \begin{document}. We can detect this: \document redefines +% \documentclass to be \@twoclasseserror. Then we also have to define +% how this document is ended: Either by \endinput or by an additional +% revision log. +% Of course, this test works only if LaTeX 2e is used for processing. + +\expandafter\ifx \csname @twoclasseserror\endcsname \documentclass + + \let\endSubDocument=\endinput + + \chap The internal interface. + +\else + + \let\endSubDocument=\relax + + \documentclass{progltx} + + \usepackage{cweb-doc} % additional document-specific markup + \usepackage{a4-9} % Tschichold's A4 layout + + \nofiles % no crossreferences used + + \begin{document} + + \title{The \texttt{cweb} Class\\ + {\large (Internal Interface)}% + } + \author{Joachim Schrod% + \thanks{Email: \texttt{schrod@iti.informatik.th-darmstadt.de}}% + } + + \RCS $DocDate: 1995/08/29 15:19:45 $ + \date{% + \RCSDocDate\\[3pt] % LaTeX Error: Paragraph terminated too early + (Revision \RCSStyleRevision{} of \texttt{cweb.cls})% + } + + \maketitle + + \sect + +\fi + + + + +This +% +\ifx \endSubDocument\relax + document +\else + section +\fi +% +shall describe the internal interface for \TeX{} programmers who want +to write packages or subclasses to enhance the \cls{cweb} class. In +particular, it shall describe all control sequences a programmer may +redefine to adapt this class to special needs. (There are an awful lot +of them, all cseqs that start with `|Cweb|'.) + +Due to time constraints this description has not been written yet. It +depends on the demand when it will be written. I.e., if \emph{you} are +a package/class writer and if you want to enhance the \cls{cweb} +class, send me email. Please mention the kind of enhancement you want +to do. I will then add information to this description as needed. + + + + +\endSubDocument + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\vskip \PltxPreSectSkip + +\begin{rcslog} +$DocLog: cweb-conf.tex,v $ +\Revision 2.1 1995/08/29 15:19:45 schrod +Added (hint to non-existence of) description of the internal interface. + +\end{rcslog} + + + +\end{document} + +% LocalWords: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-doc.sty b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-doc.sty new file mode 100644 index 00000000000..2859584f6cb --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-doc.sty @@ -0,0 +1,133 @@ +% $Id: cweb-doc.sty,v 1.3 1995/08/25 19:07:54 schrod Exp $ +%---------------------------------------------------------------------- + +% +% tags for the documentation of cweb class +% + + +\ProvidesPackage{cweb-doc} + + +% +% Used packages +% + +\begingroup + \let\begingroup=\endinput + \input{cweb.cls} % get style revision + \global\let\cweb@loaded=\cweb@loaded +\endgroup +\providecommand*\cweb@loaded{$StyleRevision$} % bootstrap + + + +% +% Configuration of RCS fields +% + +% keywords in style are prefixed by `Style', in documentation by `Doc'. +\let\RcsHandleStyleDate=\RcsHandleDate % transform StyleDate value +\let\RcsHandleDocDate=\RcsHandleDate % transform DocDate field + +% the revision of cweb.cls is needed by the documentation +\def\RcsEmptyValue{$\langle$unknown$\rangle$} +\expandafter\RCS \cweb@loaded % creates \RCSStyleRevision +\def\RcsEmptyValue{} + +% author name +\rcsAuthor{schrod}{Joachim Schrod} + + + +% +% new environments +% + +\font\manfnt=manfnt % with the dangerous bend sign +\chardef\bend="7F % I like the non-S curve ;-) +\newenvironment{fixme}{% + \trivlist + \hangindent 2em + \hangafter -2 + \item[\hbox to 0pt{\hss \manfnt \bend}]% + \ignorespaces + }{% + \endtrivlist + } + + +\newenvironment{cseqtab}{% + \quote + \obeycr + \tabular{lrl}% + \@gobblecr % eat following newline + }{% + \endtabular + \endquote + } + + +\newenvironment{options}{% + \list{}{% + \labelwidth\z@ + \itemindent -.5\leftmargin + \labelsep 1em + \def\makelabel##1{% + \hspace\labelsep + \normalfont\ttfamily ##1% + }% + }% + }{% + \endlist + } + + + +% +% new tags +% + +% logos +\def\cweb{\texttt{CWEB}} +\def\ctangle{\texttt{CTANGLE}} +\def\cweave{\texttt{CWEAVE}} + +% other +\renewcommand*\arg[1]{\textsl{Arg.~#1}:} % I don't use the arg operator + +\def\<#1>{\textit{#1}} % syntactic category + +\newcommand\cls[1]{\textsf{#1}} % LaTeX classes +\newcommand\pkg[1]{\textsf{#1}} % LaTeX packages + + +% +% change of LaTeX parameters, for layout etc. +% + +% underfull hboxes are not such a problem in program documentation + +\hbadness=4000 + + +% figure + +\def\textfraction{0.1} % must be at least 10% text on page +\def\topfraction{0.9} % rest may be top insertion +\def\floatpagefraction{0.8} % float pages only if the float is larger than 80% + + + + +\endinput + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Local Variables: +mode: LaTeX +TeX-brace-indent-level: 4 +indent-tabs-mode: t +TeX-auto-untabify: nil +End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.fig b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.fig new file mode 100644 index 00000000000..729c992d272 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.fig @@ -0,0 +1,78 @@ +#FIG 2.1 +80 2 +6 35 82 134 122 +1 1 0 1 -1 0 0 0 0.00000 1 0.000 83 100 47 18 83 100 130 119 +4 1 0 10 0 -1 0 0.00000 0 7 63 83 104 Documentation +-6 +6 35 152 134 192 +6 62 158 107 180 +4 1 0 10 0 -1 0 0.00000 0 7 43 83 167 Restricted +4 1 0 10 0 -1 0 0.00000 0 9 36 83 180 Program +-6 +1 1 0 1 -1 0 0 0 0.00000 1 0.000 83 170 47 18 83 170 130 189 +-6 +6 116 17 215 57 +6 140 23 188 48 +4 1 0 10 0 -1 0 0.00000 0 9 48 164 32 (CR) Cross +4 1 0 10 0 -1 0 0.00000 0 7 40 164 48 Reference +-6 +1 1 0 1 -1 0 0 0 0.00000 1 0.000 164 35 47 18 164 35 211 54 +-6 +6 203 152 302 192 +1 1 0 1 -1 0 0 0 0.00000 1 0.000 251 170 47 18 251 170 298 189 +4 1 0 10 0 -1 0 0.00000 2 7 21 251 174 \TeX +-6 +6 203 82 302 122 +1 1 0 1 -1 0 0 0 0.00000 1 0.000 251 100 47 18 251 100 298 119 +4 1 0 10 0 -1 0 0.00000 0 9 36 251 104 Program +-6 +6 257 122 299 143 +6 257 131 287 143 +4 0 5 10 0 -1 0 0.00000 2 10 30 257 143 \\SHC +-6 +4 0 5 10 0 -1 0 0.00000 2 10 42 257 132 \\C \\X +-6 +6 221 47 266 71 +4 0 5 10 0 -1 0 0.00000 2 10 42 223 57 \\A \\Q +4 0 5 10 0 -1 0 0.00000 2 8 18 235 69 \\U +-6 +2 1 0 1 -1 0 0 0 0.000 -1 1 0 + 0 0 1.000 4.000 8.000 + 254 119 254 152 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 1 0 + 0 0 1.000 4.000 8.000 + 245 83 208 46 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 1 0 + 0 0 1.000 4.000 8.000 + 119 41 89 81 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 1 0 + 0 0 1.000 4.000 8.000 + 101 83 125 51 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 1 0 + 0 0 1.000 4.000 8.000 + 131 174 203 174 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 0 1 + 0 0 1.000 4.000 8.000 + 131 164 203 164 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 0 1 + 0 0 1.000 4.000 8.000 + 89 119 89 152 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 1 0 + 0 0 1.000 4.000 8.000 + 131 95 203 95 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 0 1 + 0 0 1.000 4.000 8.000 + 131 105 203 105 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 1 0 + 0 0 1.000 4.000 8.000 + 74 119 74 152 9999 9999 +2 1 0 1 -1 0 0 0 0.000 -1 0 1 + 0 0 1.000 4.000 8.000 + 239 119 239 152 9999 9999 +4 2 5 10 0 -1 0 0.00000 2 10 24 72 136 \\PB +4 1 5 10 0 -1 0 0.00000 2 8 24 167 160 \\PB +4 1 5 10 0 -1 0 0.00000 2 8 18 166 92 \\B +4 1 5 10 0 -1 0 0.00000 2 8 42 166 117 \\M \\N +4 2 5 10 0 -1 0 0.00000 2 8 42 101 60 \\M \\N +4 0 5 10 0 -1 0 0.00000 2 8 24 113 76 \\ch +4 1 5 10 0 -1 0 0.00000 2 8 18 167 188 \\X diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.latex b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.latex new file mode 100644 index 00000000000..8f624ed30af --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.latex @@ -0,0 +1,62 @@ +\setlength{\unitlength}{0.012500in}% +% +\ifx \SetFigFont\undefined + \begingroup\makeatletter + % extract first six characters in \fmtname + \def\x#1#2#3#4#5#6#7\relax{\def\x{#1#2#3#4#5#6}}% + \expandafter\x\fmtname xxxxxx\relax \def\y{splain}% + \ifx\x\y % LaTeX or SliTeX? + \gdef\SetFigFont#1#2#3{% + \ifnum #1<17\tiny\else \ifnum #1<20\small\else + \ifnum #1<24\normalsize\else \ifnum #1<29\large\else + \ifnum #1<34\Large\else \ifnum #1<41\LARGE\else + \huge\fi\fi\fi\fi\fi\fi + \csname #3\endcsname}% + \else + \gdef\SetFigFont#1#2#3{\begingroup + \count@#1\relax \ifnum 25<\count@\count@25\fi + \def\x{\endgroup\@setsize\SetFigFont{#2pt}}% + \expandafter\x + \csname \romannumeral\the\count@ pt\expandafter\endcsname + \csname @\romannumeral\the\count@ pt\endcsname + \csname #3\endcsname}% + \fi + \endgroup +\fi +\begin{picture}(262,171)(37,651) +\put( 84,735){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{}Documentation}}} +\put( 84,672){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{}Restricted}}} +\put( 84,659){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{}Program}}} +\thinlines +\put( 84,669){\oval(94,36)} +\put(165,807){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{}(CR) Cross}}} +\put(165,791){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{}Reference}}} +\put(165,804){\oval(94,36)} +\put(252,669){\oval(94,36)} +\put(252,665){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{}\TeX}}} +\put(252,739){\oval(94,36)} +\put(252,735){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{}Program}}} +\put(258,696){\makebox(0,0)[lb]{\smash{\SetFigFont{10}{12.0}{tt}\\SHC}}} +\put(258,707){\makebox(0,0)[lb]{\smash{\SetFigFont{10}{12.0}{tt}\\C \\X}}} +\put(224,782){\makebox(0,0)[lb]{\smash{\SetFigFont{10}{12.0}{tt}\\A \\Q}}} +\put(236,770){\makebox(0,0)[lb]{\smash{\SetFigFont{10}{12.0}{tt}\\U}}} +\put(255,720){\vector( 0,-1){ 33}} +\put( 84,739){\oval(94,36)} +\put(246,756){\vector(-1, 1){ 37}} +\put(168,651){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{tt}\\X}}} +\put(120,798){\vector(-3,-4){ 30}} +\put(102,756){\vector( 3, 4){ 24}} +\put(132,665){\vector( 1, 0){ 72}} +\put(204,675){\vector(-1, 0){ 72}} +\put( 90,687){\vector( 0, 1){ 33}} +\put(132,744){\vector( 1, 0){ 72}} +\put(204,734){\vector(-1, 0){ 72}} +\put( 75,720){\vector( 0,-1){ 33}} +\put(240,687){\vector( 0, 1){ 33}} +\put( 73,703){\makebox(0,0)[rb]{\smash{\SetFigFont{10}{12.0}{tt}\\PB}}} +\put(168,679){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{tt}\\PB}}} +\put(167,747){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{tt}\\B}}} +\put(167,722){\makebox(0,0)[b]{\smash{\SetFigFont{10}{12.0}{tt}\\M \\N}}} +\put(102,779){\makebox(0,0)[rb]{\smash{\SetFigFont{10}{12.0}{tt}\\M \\N}}} +\put(114,763){\makebox(0,0)[lb]{\smash{\SetFigFont{10}{12.0}{tt}\\ch}}} +\end{picture} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.ltx b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.ltx new file mode 100644 index 00000000000..aa5cdce2f26 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-fsa.ltx @@ -0,0 +1,29 @@ +% $Id: cweb-fsa.ltx,v 1.2 1995/08/08 00:14:27 schrod Exp $ +%------------------------------------------------------------ + +% +% test of xfig created pictures +% +% [LaTeX] + + + + +\documentstyle{article} + + +\begin{document} + +\noindent Test of figure \texttt{cweb-fsa.latex}: Finite State +Automaton for different CWEB modi. + +\bigskip + +\begin{center} + \chardef\\=`\\ + \input{cweb-fsa.latex} +\end{center} + + + +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-user.tex b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-user.tex new file mode 100644 index 00000000000..2f21f53150c --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb-user.tex @@ -0,0 +1,779 @@ +% $DocId: cweb-user.tex,v 2.10 1995/11/20 22:34:16 schrod Exp $ +%------------------------------------------------------------ + +% +% user manual/requirement definition for cweb class +% +% [LaTeX] +% (history at end) + + +% This file is either a subdocument of the style doc or a document on +% its own. In the former case it's a chapter, in the latter it's a +% ``normal'' LaTeX progltx document. +% If it's a subdocument, this file will be included after +% \begin{document}. We can detect this: \document redefines +% \documentclass to be \@twoclasseserror. Then we also have to define +% how this document is ended: Either by \endinput or by an additional +% revision log. +% Of course, this test works only if LaTeX 2e is used for processing. + +\expandafter\ifx \csname @twoclasseserror\endcsname \documentclass + + \let\endSubDocument=\endinput + + \chap What's this class for?. + +\else + + \let\endSubDocument=\relax + + \documentclass{progltx} + + \usepackage{cweb-doc} % additional document-specific markup + \usepackage{a4-9} % Tschichold's A4 layout + + + \begin{document} + + \title{The \texttt{cweb} Class} + \author{Joachim Schrod% + \thanks{Email: \texttt{jschrod@acm.org}}% + } + + \RCS $DocDate: 1995/11/20 22:34:16 $ + \date{% + \RCSDocDate\\[3pt] % LaTeX Error: Paragraph terminated too early + (Revision \RCSStyleRevision{} of \texttt{cweb.cls})% + } + + \maketitle + + \sect + +\fi + +\cweb{} is a Literate Programming tool that enables you to combine +documentation and actual C or \C++ code in one document. The \cls{cweb} +class allows you to use \LaTeX{} for the documentation of your \cweb{} +programs. Now a \cweb{} document is like a usual \LaTeX{} +document---as you have probably written dozens before. With all the +features of \LaTeX{}, and with all the quirks of \LaTeX{}. + +Originally, \cweb{} was only usable with Plain \TeX{}, as \cweave{} +outputs \TeX{} code that looks as if it were Plain \TeX{}. Well, it +isn't---it's just not the normal \LaTeX{} markup. No change in +\cweave{} is necessary to use \LaTeX{}. + +For the sake of those \cweb{} programmers who have used the original +markup interface (i.e., the Plain \TeX{} macros) before, I'll +sometimes contrast the approach presented here with the original one. +Then I'll call the original interface ``Plain \cweb{}''. The new +interface is called ``\LaTeX{} \cweb{}''. + +If you never used \cweb{} before, you won't find enough information in +this manual. Please read the user manual of \cweb{} first, and then +come back again. I assume a working knowledge, and will only present +the new stuff introduced by this class. + + +\sect This bundle does \emph{not} support inclusion of \cweb{} code in +other (general) \LaTeX{} documents. This is not the task of the +\cls{cweb} class -- its task is the usage of \LaTeX{} for creation of +\cweb{} documents. + +Note also that you will not be able to \LaTeX{} your \cweb{} documents +(i.e., the program files) directly. You must still process them first +by \cweave{}, then you can use \LaTeX{} to process the resulting +\TeX{} file. + + +\sect You have to use \cweb{} version~3 and you need at least \LaTeX{} +version \mbox{$\langle$1994/12/01$\rangle$} (or any later one), this +class does not work with older versions. + + +\sect A \cweb{} document has two concurrent structures, a +\textsl{document structure} and a \textsl{program structure}. + +The basic building block of the document structure, the bricks that +build up our document, are called \textsl{chunks}. We use chunks to +present one point of our work to our reader, the presentation has both +informal (explanation) and formal parts (code). This is the essence of +Literate Programming, that we tell each point twice, once on an +abstract and once on a technical level. + +A chunk consists of three parts: (1)~the \textsl{documentation part}, +(2)~the \textsl{definition part}, and (3)~the \textsl{program part}. +Each of these parts can be empty. The documentation part is mostly +text with \LaTeX{} tags. In this text material from \textsl{restricted +program mode} can appear. The definition part consists of a series of +either \textsl{macro} or \textsl{format definitions}. The program part +is one piece of a refinement, identified by a name (see below). + +A chunk starts with `\verb*|@ |', and gets assigned a unique +identification, a number; we'll use that number to refer to that +chunk. In particular, the number is of interest when we want to refer +to the code part of the chunk, otherwise it's often regarded as +superfluous. + +\sect And we have higher-level structure elements as well. They combine a +sequence of chunks and a sequence of structure elements on a lower +level, both sequences may be empty. As usual in \LaTeX{}, we call +these elements \textsl{section divisions} or short \textsl{sections}. +We do not give them names +like `part,' `chapter,' `subsection,' etc., to denote their level; +most often we'll use level-numbers (sometimes called \textit{rank}) +instead. + +A section division starts with `|@*|' and is followed by a character, the rank +indicator. The highest rank is~`|@**|', you can think of it as an +equivalence to \LaTeX{}'s |\part|. (Often we don't use that rank in +smaller programs, as we don't use |\part| in smaller articles.) A +section on the next rank is started with~`\verb*|@* |' (synonym to +`|@*0|'), roughly equivalent to chapters. Then we'll use numbers to +mark the next ranks, from |@*1| to~|@*9| (sections to +sub$^{9}$sections). That's outrageous---I'll hope you'll never use +11~hierarchy levels in your documents, they would be unreadable. + +A section has a title, that title comes after the section start tag +and ends with a full stop. If you need periods in your title, enclose +them in braces. (That behavior can be changed if there's enough +interest. I can also make it possible to use braces to delimit the +section title, as in |\section|, etc. Send mail with your opinion.) + +As a matter of convenience, a section implicitly starts a chunk; +i.e., one does not need to use `\verb*|@ |' after the section title. +Of course, it doesn't hurt to use it either. + +\medskip + +The explanation might have been a bit too abstract, so let me make one +thing plain clear: You should \emph{never ever} use |\part|, +|\chapter|, |\section|, or any other \LaTeX{} sectioning command in +your \cweb{} documents. Use the sectioning commands of \cweb{}, i.e., +`|@*|\textit{rank}'. + + + +\sect The description above does not mean that the output is fixed to +the style you'll know from the \cls{book} or \cls{report} document +classes. Quite in contrary, the default layout is oriented along the +\cls{article} class. + +There is a very easy possibility to change that default layout: With +the option |baseclass| (see chunk~\ref{chunk:baseclass}) you can +specify the document class \cls{cweb} inherits from. If that document +class has chapters (like \cls{report} or \cls{book}), you'll get the +layout as you're used from these classes. + + +\sect In Plain \cweb{}, the term \textit{section} was used for +`chunk.' We abstain from that usage, as sections are used in \LaTeX{} +(and in almost all other documentation systems, for that matter) to +designate higher-level structure elements. We prefer to follow the +traditional usage of terms here, even if that means that we'll have to +confront Plain \cweb{} users with a slight shift in semantics. + +And you'll find the term \textit{starred section} in Plain \cweb{} and +might think these are our sections. Well, almost. There's a subtle, +but important difference between these starred sections and our +terminology: A starred section is just a chunk with a special +attribute (a title). That title will appear in a table of contents, +but that does not mean that the starred section is an element to +denote a structural \emph{hierarchy}. + +You won't find a section number like `1.5.2' in Plain \cweb{}, do you? +--- In \LaTeX{} \cweb{}, you've got the choice. You have the new +support of the hierarchical structure, or you may stay with Plain +\cweb{}'s (flat) structure. + + +\sect We still have one open point in our explanation of the +document's structure. As mentioned at the start, we've got two +concurrent structures, let's have a look at the program structure +finally. + +A \cweb{} program consists of a tree of \textsl{refinements}. A +refinement is a sequence of program parts with the same name, ordered +in appearance in the document. The root of the tree is the refinement +with the special name~|@c|. + +The complete program text is defined by the depth-first traversal +(DFS, i.e.\ infix-order) of the tree, the tool \ctangle{} extracts the +program text from a \cweb{} document. + + + + +\chap Markup for your document structure. + +Like every \LaTeX{} document, a \cweb{} document starts with a +document class specification; then comes the preamble, terminated by +the document start. This way we brought some structure in the \cweb{} +limbo, but this shouldn't be a problem for you. You must tag the end +of the document, as you do in other \LaTeX{} files. But here you must +take a bit more care: +% +\begin{quote} + \itshape + + Assert that the\/ |\end{document}| is in the documentation part of + a\/ chunk, neither in the definition nor in the program part. + +\end{quote} +% +If it would be in the program part, \cweave{} would readily process it +and \LaTeX{} would never see this tag. Nevertheless, if you make this +mistake, you will detect it early: \ctangle{} will copy this tag to +the C file as well, and your program will be erroneous\,\dots + +And there's another difference you'll have to take care of: Usually +you can put arbitrary text after the end of your document, \LaTeX{} +will not see it. Please note that both \ctangle{} and \cweave{} will +still see it---don't put a program part or even complete chunks there. +For technical reasons, there must not be any |\fi| token after the +document end, too. + + +\sect The resulting structure of your \cweb{} document is exemplified +in figure~\ref{fig:structure}. Note that |\end{document}| is placed +in a new, empty, chunk. This isn't necessary, you could write more +documentation there---but it's considered good style to use a sole +chunk for document finish. + +%% my little joke +\begin{figure} + +\setbox0=\vbox{\parindent=0pt \hsize=.85\textwidth +\begin{minipage}{\hsize} +\begin{verbatim} +\documentclass{cweb} + +\begin{document} + +\title{My Program, Doomed for the ACM Software Systems Award} +\author{Joe L. User} + +\maketitle + +\tableofcontents % if you want + + +@* A PSPACE solution for the Traveling Salesman. + +< insert your program here > + + + +@ +\end{document} +\end{verbatim} +\end{minipage} +} + +\begin{center} +\fboxsep=1em +\fbox{\box0} +\end{center} + +\caption{Exemplified \cweb{} document structure} +\label{fig:structure} +\end{figure} + + +\sect If you don't call \cweave{} with the |-x| option, an identifier +index and a list of all refinements is created at the end of the +document. You can specify an introductionary text for the index with +the tag |\cwebIndexIntro|, the introduction is the argument of this +tag. + + + + +\chap Configuration. + +You may configure the \cls{cweb} class in several ways, with class +options, redefinitions in the preamble, supplying additional +packages, and by subclassing it. + +At start of the processing, the file |cweb.cfg| is read if it exists. +That file may contain configuration code that shall apply to all your +\cweb{} documents. You can set the paper size there, etc. Please don't +set the default structure there (see +chunk~\ref{chunk:structure-option}), others would get different results +when they process your document. + + +\sect Options are specified with the new ``keyword$=$value''-scheme, +first introduced with the \pkg{graphicx} package. I.e., the options have a +set of possible values, you may choose one. For instance, the option +|structure| has the possible values |flat| and |hierarchic|. You tell +that you want a flat document structure by +% +\begin{quote} + |\documentclass[structure=flat]{cweb}| +\end{quote} +% +As usual, options are separated by commas. From the set of possible +option values, two ones are special: The \textsl{predefined value} and +the \textsl{default value}. The predefined value is the one that's +used when you don't specify the option at all. The default value is +used of you don't specify the value in the option; e.g., +% +\begin{quote} + |\documentclass[suppress]{cweb}| +\end{quote} +% +selects the default value of the option |suppress|. (Not that there is +one currently. :--) + +There is always a predefined value, a default value may not be there. +If a default value exists, it is always different from the predefined +one. The default value gives you an easy specification of an option +value that is expected to be common. If that value would be the +predefined one, you won't need to specify the option in the first +hand. + +The following options are available and explained below: +% +\begin{options} +\item[structure] Select the structure model used by the \cls{cweb} + class. +\item[suppress] Suppress output of different document parts. +\item[baseclass] Select the base document class. +\item[language] Select a language for inserted texts. +\end{options} + + +\sect \label{chunk:structure-option} + +We have two possibilities to output chunks and sections, either +as a flat or as a hierarchic structure. This configuration is selected +by the option |structure|, either through the value |flat| or +|hierarchic|. +% +\begin{options} + +\item[flat] The flat structure is the ``classic'' approach, + the way Plain \cweb{} renders its chunks. Then each chunk starts + with its number. The chunk numbers are output in boldface, followed + by a dot and a quad. + + Sections show chunk numbers as well (remember, they implicitly + start a chunk). ``Important'' sections are added to the table of + contents. + +\item[hierarchic] The hierarchic structure is the + ``modernistic'' (aka \LaTeX{}) approach, then we mark the start of a + chunk by a start sign. (By default, that's a paragraph sign, `\P'). + Chunk numbers are rendered in the margin of the program part. If + there's no program part, no chunk number will be rendered---after + all, they are only used for identification of program parts. + + Section numbers are hierarchic, like in other \LaTeX{} document + classes. + +\end{options} +% +The predefined value of |structure| is |hierarchic|. There doesn't +exist a default value. + + +\sect The option |suppress| allows to select suppression of different +document parts. You have different parts you can suppress. The value +of the |suppress| option is a comma-separated list of identifiers, +enclosed in braces. If you have only one thing you want to suppress, +you don't need to surround that identifier by braces. Possible +identifiers are: + +\begin{options} + +\item[changehints] suppress output of hints that a changefile was + used: The change flag (by default a star at the start of a chunk) + and the list of changed chunks at the end of the document. + +\item[unchanged] suppress output of chunks that are not changed by + a changefile. This value implies |changehints|---by definition all + printed chunks are changed, it doesn't make any sense to hint to + that fact in addition. + +\item[index] suppress the identifier index. + +\item[reflist] suppress the refinement list. + +\item[format] suppress output of `|@f|' directives. + +\end{options} + +The predefined value is the empty list, i.e., nothing is suppressed. +There is no default value since I don't know which parts are +suppressed most often. Send email with your demands, I'll add a +default if I see that there is one major application of this option. + + +\sect \label{chunk:baseclass} The option |baseclass| allows to select +the base document class used by the \cls{cweb} class. In particular, +if the base class has |\chapter| defined the layout of major section +divisions (`|@**|' and `\verb*|@* |') will be changed to be in a +chapter layout. + +The predefined value is |article|, the default value is |report|. + + +\sect The option |language| allows to adapt inserted texts to +different languages. E.g., with the option `|language=german|' German +texts are inserted for cross references, headings, etc. That option +will neither switch on language-specific hyphenation, nor will it +trigger any other processing -- that's the task of Babel or any other +\LaTeX{} language style. + +There is neither a predefined nor a default value. (Without the +|language| option, inserted texts are in English.) + +That option actually triggers the usage of a package +\pkg{cwbl-\textit{language}}. To see if a language is supported, you +have to look for respective files in the \LaTeX{} \cweb{} macro +directory.% + \footnote{That's |texmf/tex/latex/cweb|, on a TDS compliant + installation. Please beware that pseudo operating systems like DOS + cripple file names and shorten them to eight characters; if you + see a file |cwbl-ger.sty| you'll know that the option value + |german| is supported.} +Of course, the easiest way to check the availability is to try it +out -- you'll get a comprehensible error message if there is no +respective \cweb{} language package. In November 1995, |german|, +|french|, and |italian| were supported, more might have been added +later. + +\smallskip + +For compatibility with Babel, some other options (e.g., |german| or +|french|) are also supported as nicknames for +|language=|\textit{option}. If you use packages that make also use of +these options (e.g., \pkg{babel} or \pkg{varioref}), you'll probably +prefer them over |language| since they are picked up by those packages +as well. + + + + + +\chap Restrictions. + +The following restrictions will not be withdrawn as far as I can +see---except if somebody will send me a patch with changes. I tried to +sort the restrictions in order of severity. + + +\sect \emph{(Restrictions due to the design of \cweave{}.)} + +Please be aware that the vertical bar (`\verb"|"') is used by \cweb{} +to delimit small C code pieces in the documentation parts, and is +therefore processed (and mangled) by \cweave{}. \emph{You cannot use +it for \TeX{} any more.} + +In particular, you cannot specify rules for the |tabular| or the +|array| environment. Since you most certainly want to do so: You have +two choices left: +% +\begin{enumerate} + +\item Make sure you have the \pkg{array} package (by Frank Mittelbach and + David Carlisle, from the Tools bundle) installed. Then you may use + the package \pkg{cwebarray}, it defines `|I|' (that's an uppercase~`i') + as a specifier for rules. I.e., instead of + \verb"\begin{tabular}{l|l}" you have to write + |\begin{tabular}{lIl}|. Not the most elegant solution, but it + works\,\dots + +\item + Use `|^^7c|' instead of `\verb"|"'. I.e., instead of + \verb"\begin{tabular}{l|l}" you may write |\begin{tabular}{l^^7cl}|. + +\end{enumerate} +% +These two choices are compatible, you may use both in one document. +Needless to say, I consider the first alternative the better one. + + +\sect Neither a refinement name nor an index entry made by~|@^| may +consist of a \emph{single} dot-accented term. I.e., you must not +write `|@<\.O@>|', `|@^\.o@>|', or even `|@^\.{foolish}@>|'. Of +course you may write `|@^\.o, accent@>|' or `|@< Handle accent \.o @>|'. + + +\sect \emph{(Restriction due to the implementation of \LaTeX{}.)} + +One cannot use restricted C mode in moving arguments. Most notably, +this is disturbing in the section titles and in |\caption| +tags. Sorry, folks. + +(Basically, that's because the definition of |\addcontentsline|, etc., +in the \LaTeX{} kernel is brain damaged; it wants to expand its +argument. And I don't want to maintain redefinitions of such basic +macros.) + + +\sect \emph{(Restrictions due to \TeX{}.)} + +\C++ comments (i.e., from |//| to the end of the line) are typeset as C +comments. This is especially bad if they are used for a whole block of +comment lines, as it is quite common. Please put such comment blocks +in the documentation part. (An |\everyline| implementation would be +needed to lift that restriction, and that's impossible in general.) + + + + +\chap Details. + +The following tags are reserved and must neither be used nor redefined: + |\ATL|, + |\B|, + |\M|, + |\N|, + |\PB|, + and~|\Y|. + +|\9| is already explained in the \cweb{} user manual: It's a special +control sequence used for the index entries tagged with~`|@:|'. Its +default definition is setup in such a way that you can cheat +\cweave{} concerning the sort order of this entry: If you enter +`|@:sort}{print@>|' you will get an index entry ``print'' next to the +place where the index entry ``sort'' would be. But you're allowed to +change this default definition.% + \footnote{Remember: A package is a very good place to place such + redefinitions; your document should be concerned with contents, not + with appearance.} + +The names of all other control sequences defined by this +class---besides the common \LaTeX{} control sequences---start with +|cweb|, |Cweb|, or |cwbb|. Please don't define new control sequences starting +with this prefix. (The control sequences starting with |Cweb| may be +redefined in a package to change the appearance of the \cweb{} +document or the behavior in a controlled manner, check the +description of the internal interface for this possibility.) + + +\sect Plain \cweb{} users +should note that the macros from |cwebmac.tex| are not available any +more. E.g., you cannot use |\.| to typeset typewriter material; use +either |\texttt| or~|\verb|, as it fits the situation. On the other hand, +now you're able to use |\.| for the dot accent, you can define |\3| +for the `sharp~s', |\C++| for the \C++ logo,% + \footnote{I will not define any such logos in this class. A + package like \pkg{logos} with lots of name definitions is the + appropriate place for this.} +etc. + +Another detail for ex-plainies: The table of contents is produced by +the |\tableofcontents| tag (during the second \LaTeX{} run), not +automatically. But this is the standard \LaTeX{} behavior. + + + + +\chap Known Problems. +\label{sec:problems} + +There is a bunch of known bugs, problems, and ommisions. + +\bigbreak + +\noindent \textit{Bugs:} + % +\begin{itemize} + +\item The presentation of |@l| redefinitions is not proper. But it +wasn't in Plain \cweb{}, either. + +\end{itemize} + +\noindent \textit{Problems:} + % +\begin{itemize} + +\item You can't use |\index| and |\makeindex| as-is to create an + index. Add your entries instead to \cweave{}'s index using `|@^|', + `|@.|', or `|@:|'. That problem is caused by a clash in the usage of + the filename extension |idx| by \cweave{} and \LaTeX{}. The + \pkg{index} package by \textsc{David Jones} will help you to define + additional index categories (that use an other extension) if you + don't want to mix identifiers and your other index entries. + +\end{itemize} + +\noindent \textit{Ommisions} (``wouldn't it be nice, if''s): + % +\begin{itemize} + +\item The current chunk number and most section titles (below rank 1 + or~2, depending on the base class) are not available as a mark for + inclusion in a running head. + +\item Better integration of \pkg{rcs} package. That package is used to + support including information from the revision management system + RCS into the document. E.g., the revision log at the end of that + document was produced by that package. + +\end{itemize} + + +\sect I would like to thank those who helped me to improve this bundle. +% In particular, XXX provided XXXsubstantial parts of the code. + +\textsc{Michael M\"uller} and \textsc{Zden\v{e}k Wagner} did thorough +checks that helped me to improve the alpha test version. + +\textsc{Christian Kumpf} triggered the addition of language support +and pointed out where configuration could be made easier by supplying +more macros in the protected interface. \textsc{Andreas Scherer} +provided packages for French and Italian \cweb{} documents. + +\textsc{Laurent Desnogues}, +\textsc{Felix G\"artner}, +and +\textsc{John S. Robinson} +provided error and problem reports. +\textsc{Bronne Louis} pointed out the embarrassing error that section +numbers were not reset when a higher-level section began. + + + +\endSubDocument + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\newpage + +\begin{rcslog} +$DocLog: cweb-user.tex,v $ +\Revision 2.10 1995/11/20 22:34:16 schrod +Add language support.\\ +Triggered by Christian Kumpf \path|<smurf@igd.fhg.de>| and Andreas +Scherer \path|<scherer@physik.rwth-aachen.de>|. + +Use my `official' (ACM) email address. + +\Revision 2.9 1995/11/20 10:39:34 schrod + Explicate that one must not use |\section| etc., that one cannot +\LaTeX{} the \cweb{} program directly but must run \cweave{} first, +and that the \cls{cweb} class does not provide inclusion of \cweb{} +programs in other \LaTeX{} documents.\\ +Clarification triggered by Laurent Desnogues +\path|<laurent.desnogues@aiguemarine.unice.fr>|. + +\Revision 2.8 1995/09/15 10:22:58 schrod +The \cls{cweb} class needs at least \LaTeX{} version +\mbox{$\langle$1994/12/01$\rangle$}.\\ +Problem reported by John S. Robinson \path|jsrobin@umiacs.umd.edu|. + +\Revision 2.7 1995/09/12 22:58:38 schrod +|cwbb| is also a reserved namespace. + +Added acknowledgements. + +\Revision 2.6 1995/08/29 17:34:14 schrod + \LaTeX{} \cweb{}, version 1.0. + +\Revision 2.5 1995/08/29 02:07:28 schrod +Discard dependencies on 10\,pt fonts. + +Support suppression of format directives. + +\Revision 2.4 1995/08/27 19:31:11 schrod +Suppression of index and reference list is supported. + +Discard documentation on |\cwebSecNoEject|, that's part of the +protected interface. + +\Revision 2.3 1995/08/27 17:24:45 schrod +Make usage of baseclass with chapters work. + +\Revision 2.2 1995/08/27 13:25:59 schrod +Add possibility to suppress change hints. Suppression of unchanged +chunks suppress change hints as well, they are meaningless as all +printed chunks are changed by definition. + +Update problems section, they were partly resolved by the current +changes. Added hint to \pkg{index} package that resolves the problem +of extensions clashes with \MakeIndex{}. + +\Revision 2.1 1995/08/25 19:11:17 schrod +Add keyword-value option style, with new \pkg{keyvald} package. + +Hierarchic strucutures are supported now, in addition to the flat +structure of the beta-test version. One can choose with an option. For +that step, the terminology was cleaned up, too: Chunks are not named +sections any more. (That change involved reimplementation of almost +all the structure and toc stuff.) + +The chunk number supplied by \cweave{} is used now, not some computed +number. Change flags are printed, too. + +One can suppress output of unchanged sections. + +One can select the baseclass with an option. That may be used to use +\cls{report} or \cls{book} to get chapter-style layout. Of course, +using an arbitrary baseclass is dangerous, it must conform to the +conventions of \LaTeX{} standard classes. + +\Revision 1.10 1995/08/08 00:14:28 schrod +Updated to \LaTeXe{}, the |cweb| style is now a document class. Used +my standard templates for that, no changes in functionality. + +\Revision 1.9 1993/08/10 14:15:40 schrod +New page on main section only if group level $<$ |\cwebSecNoEject|. +Default for the latter is 3. + +Document that logos will not be defined in this style file. + +Copy of plain macros for |\CwebNumber| does not work. Repaired the +most important one (subscript must be accessed via |\sb|). +Incompatibility to NFSS will be addressed later.\\ +(Problems reported by Zden\v{e}k Wagner \path|<wagner@csearn.bitnet>|.) + +\Revision 1.8 1993/08/10 11:21:03 schrod +Reference to section number does not render a period after the +number any more. + +\Revision 1.7 1993/08/09 18:05:54 schrod +Mentioned that `\verb"|"' cannot be used for LaTeX purposes, in +particular, not for ruled tables. Described workarounds, one of them +is the new style option |cwebarray|.\\ +(Problem reported by Felix G\"artner +\path|<theedge@rbg.informatik.th-darmstadt.de>|.) + +\Revision 1.6 1993/06/17 16:10:06 schrod +`|cweb|' was still an option in the example. + +\Revision 1.5 1993/06/17 15:09:30 schrod +\cweb{} 3.0 was released officially on June 16, 1993. Mentioned in +the documentation that this version is needed for the |cweb| style. + +\Revision 1.4 1993/06/15 15:19:11 schrod +It's a style now, was an option formerly. + +\Revision 1.3 1993/06/14 15:40:42 schrod +Added section about restrictions (no restricted C mode material +in moving arguments, no single dot-accented term in an index entry). + +\Revision 1.2 1993/05/12 20:23:32 schrod +Adapted to recent changes of \cweave{} (of April 93): Main sections +have a group level, represented in the table of contents. + +Boxed the example, it was not legible formerly. + +\Revision 1.1 1993/04/09 15:00:37 schrod +Initial revision + +\end{rcslog} + + + +\end{document} + +% LocalWords: baseclass DFS PSPACE graphicx changehints changefile reflist idx +% LocalWords: cwebarray cwebmac plainies ommisions if''s rcs cwbb uller Zden diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweb.doc b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb.doc new file mode 100644 index 00000000000..8fb7a0a5582 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweb.doc @@ -0,0 +1,1396 @@ +% $StyleId: cweb.doc,v 3.6 1995/11/30 15:44:53 schrod Exp $ +%---------------------------------------------------------------------- +% Written by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>. +% Copyright conditions see below (GPL). + +% +% LaTeX class cweb +% support for LaTeX markup in CWEB sources +% +% [LaTeX in MAKEPROG] +% (history at end) + +% If you have received this style file without the user manual (in the +% file cweb-user.dvi or the respective LaTeX file), it's incomplete and +% near to useless. If it was given to you as something that you shall +% use as an author -- complain bitterly to your provider. You need the +% documentation and you have a right on it! (Below you can find info +% where to get the reference version.) + + + + +\documentclass{progltx} + +\usepackage{cweb-doc} % document-specific markup +\usepackage{fullpage} + + +\RCS $StyleRevision: 3.6 $ +\RCS $StyleDate: 1995/11/30 15:44:53 $ + + +\begin{document} + + +\title{The \texttt{cweb} Class\\ + {\large (Implementation)}% + } +\author{% % LaTeX does not discard unnecessary glue... + Joachim Schrod% + \thanks{% + \protect\raggedright + TU~Darmstadt, Computer Science Department, WG Systems Programming, + Alexanderstr.~10, D-64283~Darmstadt, Germany. + Email: \texttt{jschrod@acm.org}% + }% + } +\date{% + Revision \RCSStyleRevision\\ + (as of \RCSStyleDate)% + } + +\maketitle + + +% doesn't work with progltx yet +%\tableofcontents + + + +% ------------------------------------------------------------ +% +% subdocument: The user interface of cweb.cls +% + +\input{cweb-user} + +% +% ------------------------------------------------------------ +% +% subdocument: The internal interface +% + +\input{cweb-conf} + +% +% ------------------------------------------------------------ + + + + +\chap Implementation. + +This implementation must typeset complete files output by \cweave{}. +Large parts of this task are available from the module \pkg{cwebbase}. +It remains mainly to implement document-level markup and front and +back matter (table of contents, index, etc.) In particular, the back +matter material is not trivial; its tags are behind |\end{document}|, +we have to read carefully behind the end of our \cweb{} document to +detect if we have to typeset them at all. + + +\sect This module reserves the namespace |cweb|. + +\beginprog +\ifx \cweb@loaded\undefined + \def\cweb@loaded{$StyleRevision: 3.6 $} +\else + \PackageWarningNoLine{cweb}% + {Some other package already uses namespace `cweb'} +\fi +\endprog + + +\sect Let's identify this class. + +\noindent The code below is explained in the implementation +documentation of the \pkg{rcs} package. + +\beginprog +\begingroup + \def\RCSClass#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesClass{#1}[\date\space\id\space #2]% + } + + \RCSClass{cweb}{LaTeX markup for CWEB sources} + $StyleDate: 1995/11/30 15:44:53 $: 9999/00/00 \endRCS + $StyleRevision: 3.6 $: 0.0 \endRCS +\endgroup +\endprog + + +\sect This module is from a supported bundle. Send bug reports, +comments and repairs. + +The reference version may be retrieved via anonymous ftp from +|ftp.th-darmstadt.de| [130.83.47.112], directory +|pub/programming/literate-programming/c.c++/|. It's +placed there as a gzipped tar file. (The information on the IP~number +is dated August~29,~1995. +It might have changed, although this is very unlikely. Use +your friendly nameserver.) + + +\sect This is freely distributable 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 software is distributed in the hope that it will be useful, but +\textbf{without any warranty}; without even the implied warranty of +\textbf{merchantability} or \textbf{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 in +the file |License| along with this package; if not, write to the Free +Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA. + + +\sect Before we start we declare some shorthands for category codes. +By declaring the underscore~`(|_|)' as letter we can use it in our +macros. (I agree with \textsc{D.~Knuth} that +|\identifier_several_words_long| is more readable than +|\IdentifierSeveralWordsLong| and in every case better than |\p@@@s|.) + +As this is a \LaTeX{} style file the at sign is a letter anyhow; so +we can use the ``private'' \LaTeX{} macros; and with the underscore we +can make our own macros more readable. But as we have to restore this +category code at the end of this macro file we store its former value +in the control sequence |\CatUsCode|. This method is better than to +use a group because not all macros have to be defined global this way. + +Since somebody might use more styles from me, this cseqs might be +defined already. + +\beginprog +\ifx \CatEscape\undefined + \chardef\CatEscape=0 + \chardef\CatOpen=1 + \chardef\CatClose=2 + \chardef\CatIgnore=9 + \chardef\CatLetter=11 + \chardef\CatOther=12 + \chardef\CatActive=13 % is defined in Plain already + + \chardef\CatUsCode=\catcode`\_ +\fi + +\catcode`\_=\CatLetter % top level macro file +\endprog + + +\sect Problems over problems with different \LaTeX{} versions. I have +decided that I will take the same stand as the \LaTeX{} team: I will +only support the last two official \LaTeX{} versions, folks who run +older software might need to upgrade. + +The implementation will use `star'-forms of \LaTeX{}'s command +definition macros. They were introduced with \LaTeX{} +\mbox{$\langle$1994/12/01$\rangle$}. + +Currently (as of 07 Nov 95), 1995/06/01 is the most recent version. +I want to use a features introduced with that version: |\newif| is not +outer any more. So I check here for the version and supply the new +definition if necessary. + +\beginprog +\NeedsTeXFormat{LaTeX2e}[1994/12/01] +\@ifl@t@r \fmtversion{1995/06/01}{}% else + { + \@namedef{newif}#1{% + \count@\escapechar \escapechar\m@ne + \let#1\iffalse + \@if#1\iftrue + \@if#1\iffalse + \escapechar\count@ + } + \def\@if#1#2{% + \expandafter\def + \csname \expandafter\@gobbletwo\string#1% + \expandafter\@gobbletwo\string#2\endcsname {% + \let#1#2% + }% + } + } +\endprog + + + + +\chap Options. + +Our options are of the ``keyword-value'' category. We realize them by +the \pkg{keyvald} package, an enhancement of the \pkg{keyval} package +from the Graphics bundle that supports defaulting for unknown keys. + +\begin{fixme} + Most of the code below should be extracted and moved to a + \pkg{keyvalx} package (or a new version of \pkg{keyval}). In + particular, support for package/class option processing, enumeration + values, and set values for keyword options. +\end{fixme} + +|\ProcessKeyValOptions| may be used instead of |\ProcessOptions|, it +takes the keyval set identifier as argument. At the end it evaluates +and resets a hook. That hook may be used at option definition to +define further dependencies. (E.g., enabling that option implies +enabling an other option, too.) +% +\begin{fixme} + Like |\ProcessOptions|, I define |\@curroptions|, since I don't know + if that's needed later. The only place where it could been needed is + in the check for unprocessed options. +\end{fixme} + +\beginprog +\RequirePackage{keyvald} + +\let\ProcessKeyValOptionsHook\empty +\providecommand*\ProcessKeyValOptions[1]{% + \edef\@curroptions{\@ptionlist{\@currname.\@currext}}% + \edef\next{\noexpand\setkeys{#1}{\@curroptions}}% + \next + \ProcessKeyValOptionsHook + \let\ProcessKeyValOptionsHook\empty + } +\endprog + + +\sect The enumeration option |structure| selects hierarchic~(0) or +flat~(1) structure. The predefined value is `hierarchic', there is no +default. The option value is bound to |\cweb@structure|. + +\beginprog +%% \define@key@enum{cweb}{structure}{hierarchic,flat}[hierarchic] +\@namedef{KV@cweb@structure@enum:hierarchic}{0 } % <-- space! +\@namedef{KV@cweb@structure@enum:flat}{1 } % <-- space! +\define@key{cweb}{structure}{% + \expandafter\let \expandafter\@tempa + \csname KV@cweb@structure@enum:#1\endcsname % \relax if undefined + \ifx \@tempa\relax + \PackageError{cweb}% + {% + Invalid value `#1' for option structure% + }{% +Possible valid values are `hierarchic' and `flat'.\MessageBreak +The predefined value is `hierarchic'.\MessageBreak +There's no default value, you have to specify one.% + }% + \else + \let\cweb@structure\@tempa + \fi + } +\setkeys{cweb}{structure=hierarchic} +\endprog + + +\sect With the set option |suppress| one can select suppression of +different document parts: |changehints| suppresses output of hints +that a changefile was involved, |unchanged| output of unchanged +chunks, |index| and |reflist| output of index and reference list, and +|format| output of `|@f|' directives. + +The predefined value is no suppression. There is no default value. +% +\begin{fixme} + Shouldn't I supply a default value? `|{index,reflist}|'? +\end{fixme} + +Set options are represented by flags named +|@cweb@|\<option>|@|\<value>|@|. + +\beginprog +%% \define@key@set{cweb}{suppress}{changehints,unchanged,index,reflist,format} +\@for \@tempa :=changehints,unchanged,index,reflist,format\do {% + \expandafter\newif \csname if@cweb@suppress@\@tempa @\endcsname + \csname @cweb@suppress@\@tempa @false\endcsname + }% +\define@key{cweb}{suppress}{% + \@for \@tempa :=#1\do {% + \expandafter\let \expandafter\@tempb + \csname @cweb@suppress@\@tempa @true\endcsname + %% \relax if undefined + \ifx \@tempb\relax + \PackageError{cweb}% + {% + Invalid value `#1' for set option suppress% + }{% +Possible valid values are `changehints', `unchanged',\MessageBreak +or a comma-separated list of these words enclosed in braces.\MessageBreak +Specified values are turned on, you can't turn them off.\MessageBreak +No value is on initially.\MessageBreak +There's no default value, you have to specify one.% + }% + \else + \@tempb + \fi + }% + } + +\g@addto@macro\ProcessKeyValOptionsHook{% + \if@cweb@suppress@unchanged@ + \@cweb@suppress@changehints@true + \fi + } +\endprog + + +\sect The base document class may be specified by the option +|baseclass|. + +\beginprog +\def\CwebBaseClass{article} +\define@key{cweb}{baseclass}[report]{\def\CwebBaseClass{#1}} +\endprog + + +\sect Language-specific adaptions are stored in files +\texttt{cwbl-{\it language}.sty}. They may be accessed as packages or +by the |language| option that takes the \textit{language} as value. We +have to require the respective package at the end of the class, then +all cseqs with default names are defined and may be overwritten. + +For some languages, we provide Babel-compatible option names, to ease +the usage of global class options taken up by other packages (like +\pkg{varioref}), too. + +\beginprog +\def\cweb_set_language#1{% + \IfFileExists{cwbl-#1.sty}{% + %% true + \RequirePackage{cwbl-#1}% + }{% + %% false + \ClassError{cweb}{Language `#1' is unknown.}{% +Language definitions are stored in files `cwbl-<language>.sty'.\MessageBreak +I could not locate the file `cwbl-#1.sty'. If you didn't make a% +\MessageBreak +typo, please check if there is such a file in a directory searched\MessageBreak +by LaTeX.% + }% + }% + } + +\define@key{cweb}{language}{\AtEndOfClass{\cweb_set_language{#1}}} + +\define@key{cweb}{german}[]{\setkeys{cweb}{language=german}} +\define@key{cweb}{french}[]{\setkeys{cweb}{language=french}} +\define@key{cweb}{italian}[]{\setkeys{cweb}{language=italian}} +\endprog + + + + +\chap Configuration, inheritance, and aggregation. + +This chapter sets up access to other modules, therefore we restore the +original catcodes for the time being. + +\beginprog +\catcode`\_=\CatUsCode +\endprog + + +\sect As usual, we provide the possibility to configure this class. + +\beginprog +\InputIfFileExists{cweb.cfg}{% + \typeout{******************************************^^J% + *^^J% + * Using local configuration file cweb.cfg^^J% + *^^J% + ******************************************% + }% + }{} +\endprog + + +\sect Inherit article class. + +\beginprog +\ifx \CwebBaseClass\undefined + \def\CwebBaseClass{article} +\fi +\define@key{cweb}*[]{\PassOptionsToClass{\KV@key}{\CwebBaseClass}} +\ProcessKeyValOptions{cweb} +\LoadClass{\CwebBaseClass} +\endprog + + +\sect OK, now comes our own code; switch on again our lexical +conventions. + +\beginprog +\catcode`\_=\CatLetter +\endprog + + + + +\chap Typesetting \cweave{} output. + +This task has been out-sourced to an other module, \pkg{cwebbase}. As +mentioned at the start of the implementation, there remain mainly some +bigger tasks, they will be implemented in further sections below. For +the most part, the necessary preconditions are actually our class +option definitions, we don't have to do anything. (Gosh, what a +coincidence. :--) We need to tell \pkg{cwebbase}, that it should use +class warnings on problems. + +\beginprog +\let\cweb_warning=\ClassWarningNoLine +\input{cwebbase} +\endprog + + +\sect But there remain also some small things to be done right now: +For flat structure, the counter |secnumdepth| must be set to~11, then +we want to number chunks in the whole document. + +\beginprog +\ifcase \cweb@structure + %% hierarchic + \or + %% flat + \setcounter{secnumdepth}{11} +\fi +\endprog + + +\sect \pkg{cwebbase} uses |\part|, |\chapter| (if bound), and +|\section|. We have no use for any other section division that came +from the base class, let's discard the standard ones. + +\beginprog +\let\subsection\undefined +\let\subsubsection\undefined +\let\paragraph\undefined +\let\subparagraph\undefined +\endprog + + + + +\chap Table of contents. + +The table of contents features only sections, chunks don't have +titles, after all. Titles are indented proportionally to the rank, +with an basic indentation of |\CwebTocIndent|. An entry on major +ranks may be differentiated by layout instead of indentation, as it's +done in standard \LaTeX{} classes, too. + +The counter |\CwebTocIndentMaxLevel| constitutes an upper limit for a +recognized indent (concerning indentation, that is). + +\beginprog +\newdimen\CwebTocIndent + \CwebTocIndent=1.5em +\newcount\CwebTocIndentMaxLevel + \CwebTocIndentMaxLevel=6 % increase indentation if <= max level +\endprog + + +\sect For hierarchic structure, we can ignore chunk entries +completely, but have to supply a bunch of definitions for entries of +type `|section|$l$'. But for flat structure, sections are passed as +chunks, too. Then the current rank is stored in the title, as +|\cwbbRank{|$r$|}|. These differences are so large that we'll have +to make a very large |\ifcase|, over many chunks in this macro source +file. Let's start with the hierarchic stuff. + +\beginprog +\ifcase \cweb@structure + %% hierarchic + \def\l@chunk#1#2{} +\endprog + + +\sect Let's assume that we're subclassed from one of \LaTeX{}'s +standard classes; otherwise this stuff must be redefined, too. They +indent |\section| entries always by the same amount (1.5\,em), our +layout must fit to that. + +If we have chapters, they are also indented by 1.5\,em and +distinguished by layout. The first minor section starts on rank~3 and +is placed on level~2, it should be indented larger. Let's simply add +1.5\,em for each rank, that makes 3\,em for sections of type +|section2|. I.e., we use $f=l$ as a factor for our basic indentation. + +If we don't have chapters, the first minor section starts on rank~2 +and is placed also on level~2, it should be indented like sections +(1.5\,em), as it will be in another layout. I.e., we use $f=l-1$ as +the indentation factor. + +The actual definitions are generated in a loop. `|\l@section|$l$' +expands to `|\cweb@toc_entry{|$l$|}|'. The indentation will be +computed within that macro. + +\beginprog + \count@=2 + \@whilenum \count@<11 \do { + \expandafter\edef \csname l@section\number\count@\endcsname{% + \noexpand\cweb@toc_entry{\number\count@}% + } + \advance \count@ by 1 + } +\endprog + + +\sect A toc entry may be produced by |\@dottedtocline|. That cseq +needs the level (to decide if that entry is produced after all), the +entry indentation, the inner-entry indentation used for the number, +entry text, and page number. + +As explained above, we use an indentation of $f \cdot +|\CwebTocIndent|$, if the level is not larger than +|\CwebTocIndentMaxLevel|. Otherwise we use the indentation of that +level. + +Each entry is kind of an item with the number as the label. We need an +inner-entry indentation to be used for subsequent lines within this +entry. If a number is specified, it's tagged by |\numberline| in the +entry text. With a proper local definition and a pro-forma evaluation +of the text, we get at the width of the number (with a fitting space +for separation to text) and can use that as the inner-entry +indentation. + +\beginprog + \def\cweb@toc_entry#1#2{% % #3 (page) will follow + %% \count@ == factor for basic indentation + %% min(#1,TocIndentMaxRank) - correct_level + \ifnum #1>\CwebTocIndentMaxLevel + \count@\CwebTocIndentMaxLevel + \else + \count@ #1 % <-- space! + \fi + \ifx \chapter\undefined + \advance \count@\m@ne + \fi + %% \dimen@ == inner-entry indentation + %% width of number & space, if existing + \begingroup + \global\dimen@ \z@ % assert value + \def\numberline##1{\settowidth{\global\dimen@}{##1\enskip}}% + \setbox\z@ \hbox{#2}% % evaluates \numberline if specified + \endgroup + \@dottedtocline + {#1}% % level + {\count@ \CwebTocIndent}% % basic indent + \dimen@ % num width + {#2}% % entry; page will follow + } +\endprog + + +\sect We're done with toc configuration for hierarchic structure, +since entry definitions for |chapter| and |section| types exist +already. Let's turn over to the flat structure. + +\beginprog + \or + %% flat +\endprog + + +\sect The section rank determines how they are featured in the table. +Titles on rank~0 are typeset boldface, other titles are dotted +contents lines in roman. + +The rank is specified within the title, i.e., in the +first argument to |\l@chunk|, as an argument for the |\cwbbRank| tag. +With an appropriate definition we might set |\count@| to the +respective value. If it is not set, an explicite invocation of +|\section| or |\addcontentsline| is responsible for this entry. Then +we assume that the rank is~0. + +\beginprog + \def\l@chunk#1{% % page will be processed later + \count@\@ne % default value of group level + \begingroup + \let\numberline\@gobble % width not known yet + \def\cwbbRank##1{\global\count@ ##1\relax}% + \setbox\z@ \hbox{#1}% + \endgroup + \ifnum \count@=\z@ + \let\next\cweb@bold_toc_line + \else + \let\next\cweb@normal_toc_line + \fi + \next{#1}% + } +\endprog + + +\sect A boldface line is typeset similar to the definition of +|\@dottedtocline|, only with fewer parameters. It takes two +parameters, the entry and the page number. + +\beginprog + \def\cweb@bold_toc_line#1#2{% + \addpenalty{\@secpenalty}% + \addvspace{1em plus\p@}% + \begingroup + \noindent \bf + \hangindent\CwebTocIndent + \rightskip\@tocrmarg \parfillskip -\rightskip + \interlinepenalty\@M + \@tempdima\CwebTocIndent % for \numberline + #1\nobreak\hfill \hbox to\@pnumwidth{\hss #2}% + \par + \endgroup + } +\endprog + + +\sect A normal line uses |\@dottedtocline| like the hierarchic stuff. +Rank~1 shall still be on the same level as the bold toc line, so we +have to use $r-1$ as the proportional factor for |\CwebTocIndent|. + +\beginprog + \def\cweb@normal_toc_line#1{% % page will be processed later + \edef\next{\noexpand\@dottedtocline{\the\count@}}% % toc entry level + \ifnum \count@>\CwebTocIndentMaxLevel + \count@ \CwebTocIndentMaxLevel + \fi + \advance\count@\m@ne % group level -= 1 + \next{\count@\CwebTocIndent}% % basic indent + \CwebTocIndent % numwidth + {#1}% % entry + } +\endprog + + +\sect The first argument of |\@dottedtocline| is used to specify a +depth of the issued entry. All entries with a depth larger than +|tocdepth| are discarded. We typeset all entries, our |tocdepth| +value is the largest possible section level. + +\beginprog + \setcounter{tocdepth}{10} +\endprog + + +\sect That's it. Close our distinction between hierarchic and flat +structure. + +\beginprog +\fi +\endprog + + + + +\chap The end of the document. + +The end of a \cweave{} document is a rather complicated thing. It is +described in detail in the \cweave{} interface specification, we repeat the +most important points shortly. +% +\begin{itemize} + +\item The user has issued an |\end{document}| tag in the documentation +part of the last chunk. + +This tag is therefore part of a chunk, the chunk end (i.e., the +|\fi| cseq) does appear later in the document. Particularly, this +means that at the accurence of this tag there is still an open |\if|. + +\item Between the |\end{document}| and the |\fi| a lot of text may +come which must be ignored. Within this text no |\fi| is allowed. + +\item After the |\fi| the document may be finished by |\end|. +(Then the |-x| option of \cweave{} was used.) + +Or additional information about the whole document is added: An +optional tag |\ch|, two mandatory tags |\inx\fin|, and another +optional tag |\con|. + +\end{itemize} + +Btw, the last chunk is marked as changed if any changefile entry has +been applied in the document. (In Plain \cweb{} that chunk is +colloquially used as the introduction to the index, and that shall be +printed always.) If we suppress unchanged chunks, the last +chunk will therefore always be processed, independent if it was really +changed or not. Yet another reason to use a whole chunk just for +|\end{document}|. + +We'll use a the following approach for the implementation of the +iidentifier index and the refinement list (remember that we do not +produce a table of contents): We will check if there is any of these +two lists available. The available ones are typeset. Then we'll +finish the document. This functionality will be bound to |\fin|. +|\inx| will be simply a no-op. |\con| will never be reached, so we +don't have to cope with it. + + +\sect With the introduction of an end-document hook in \LaTeXe{}, one +might have hoped that we can utilize that hook for our task. But this +is not possible: We don't want to add some additional actions +\emph{into} the end-document handling, we want to look ahead and issue +lots of commands \emph{before} the end-document handling has happened. +(If you know \TeX{} by heart, you may skip the rest of the explanation +and go to the next chunk.) + +As a macro language, \TeX{}'s cseqs take those tokens as arguments +that are behind them in the token stream. The token stream is +initially the document source, evaluation of a macro pushes its +expansion (a token list) on front of the stream. I.e., the evaluation +of |\end| will push the expansion on the token stream before +|\enddocument| is even looked at. And |\enddocument| will also push +its expansion before the hook is evaluated. + +If we would allow |\enddocument| to push its expansion, all these +tokens have to be evaluated after we have typeset the backmatter -- +after all, we need a proper document end, don't we? One would need to +skip over them, look at and eventually evaluate tokens that come +behind (from the initial document stream, the document source), and +then evaluate the skipped tokens. That's too hairy, we don't know +exactly how many tokens to skip, this is probable to change in future +\LaTeX{} revisions, etc. + +The pushed tokens from |\end| don't pose so much problems. As +|\enddocument| will terminate the document processing, they are not +evaluated anyhow, we can just throw them away. And |\end| has changed +only once in the last few years, so it seems to be a stable macro -- +necessary as we need to know its expansion for propper skipping. + +A very first consequence of the demand to process tokens after +|\end{document}| is that we have to save the ``standard'' \LaTeX{} +document termination, since we will execute that later. + +\beginprog +\let\cweb@save@enddocument=\enddocument +\endprog + + +\sect When we encounter |\end{document}| we have to skip tokens +until we reach a |\fi|. Then we establish the correct +environment for the material behind. + +The skip itself is actually a bit difficil, so we'll look at it more +closely. |\enddocument| is executed within |\end|. As mentioned above, +the original +definition of |\enddocument| cheats, it terminates \LaTeX{} before +the rest of |\end| is executed. |\end| first checks if we're in +the correct current environment, then it establishs the end +processing for paragraph building environments, closes the +group---each environment is in its own group, executes the end +processing established before, and it may ignore following white +space. + +The |document| pseudo-environment is different in that it isn't in a +group. I.e., we have to open a group which can be closed by |\end| +afterwards. The environment check will be done in this group. With +|\aftergroup| we establish a macro which will skip the rest of the +|\end| processing. This processing is not needed anyhow: |document| +is no paragraph building environment and the following white space is +ignored by ourselves. Since |document| is no paragraph building +environment, the end processing described above is empty, i.e., not +existant. Then come a few tokens which ignore the white space. One of +these tokens is a |\fi|, so we have to skip them first separately. +They are discarded by |\cweb@skip_end|, we can start to look +for our |\fi| afterwards. + +If |\end{document}| is the first (i.e., the only) text in this chunk +we discard the chunk start marker. This is possible since it isn't set +until now, it's in the |\everypar| token register. Of course, then we +have to do the house keeping work stored in |\everypar| ourselves. + +\beginprog +\def\enddocument{% + \if@noskipsec + \global\everypar{}% + \global\@noskipsecfalse + \global\@nobreakfalse + \global\clubpenalty\@clubpenalty + \fi + \begingroup + \aftergroup\cweb@skip_end + } +\endprog + + +\sect Let's make sure that the expansion of |\end| is the one that we +expect. Then we can define |\cweb@skip_end| appropriately, we have to +skip 5~tokens. + +\beginprog +\CheckCommand*\end[1]{% + \csname end#1\endcsname\@checkend{#1}% + \expandafter\endgroup\if@endpe\@doendpe\fi +% 1 2 3 4 5 + \if@ignore\global\@ignorefalse\ignorespaces\fi} + +\def\cweb@skip_end#1#2#3#4#5{\cweb@check_fi} +\endprog + + +\sect |\cweb@check_fi| gets the next token, and invokes +|\cweb@do_check_fi| who really checks it. If this token is |\fi| we +can prepare to finish our document. Otherwise we have to check the +next token. + +Of course, first the token we have checked already must be discarded. +Therefore we insert the followup action by |\afterassignment|. It's +important that the assignment gets \emph{only} the next token, we +have to supply both the equals sign and the optional blank which are +allowed between the both arguments to |\let|. + +\beginprog +\def\cweb@check_fi{% + \futurelet\next \cweb@do_check_fi + } +\def\cweb@do_check_fi{% + \ifx \next\fi + \afterassignment\cweb@finish + \else + \afterassignment\cweb@check_fi + \fi + \let\next= % <-- blank!! + } +\endprog + + +\sect When we found the |\fi|, we also discard it. But we're still +within a chunk, i.e., there is an open |\if|. So we must supply the +|\fi|. + +\TeX{}nical note: |\next| is now equivalent to |\fi|. It must not be +used within a loop where it denotes the tail recursion's action. I.e., +code like + % +\begin{verbatim} + \ifx \foo\bar + \let\next\relax + \else + \let\next\continue + \fi + \next +\end{verbatim} + % +will fail. This trap is closed by a redefinition of |\next|. + +The output of all following lists may be suppressed by some option. +That is tested at the place where the respective list shall be +produced. + +All following lists are typeset in CR state. + +\beginprog +\def\cweb@finish{% + \fi + \let\next\relax + \let\ch\cweb@changed_list + \let\inx\relax + \let\fin\cweb@end_document + \let\end\cweb@save@enddocument + \cwbb@CR + } +\endprog + + +\sect The following lists are started with unnumbered section +divisions. They are either chapters or sections. + +\beginprog +\ifx \chapter\undefined + \let\CwebListSectionDiv=\section +\else + \let\CwebListSectionDiv=\chapter +\fi +\def\CwebListSection{\CwebListSectionDiv*} +\endprog + + +\sect The list of changed chunks is a cross reference list, (nearly) +like all others at the end of a chunk. The only difference is that +we do not show changeflags any more---each chunk number in this list +carries a change flag by definition. + +\TeX{}nical note: The redefinition of |\*| is part of the second +argument of |\CwebCrossRef|. It is \emph{not} a global redefinition. + +\beginprog +\def\CwebCRChanged{% + \CwebCrossRef{The following chunks were changed by the change file:}% + } +\def\CwebChangedListName{Changed Chunks} + +\if@cweb@suppress@changehints@ + \def\cweb@changed_list#1.{} +\else + \def\cweb@changed_list{% + \CwebListSection{\CwebChangedListName}% + \@mkboth{\uppercase{\CwebChangedListName}}% + {\uppercase{\CwebChangedListName}}% + \message{\CwebChangedListName}% + \let\CwebCRSize\relax + \CwebCRChanged \let\*\relax + } +\fi +\endprog + + +\sect As outlined above, we want to check if there are any entries in +the identifier index or the refinement list. The former is stored in +the file |\jobname.idx|, the latter in the file |\jobname.scn|. + +We write a macro |\cweb@if_file_not_empty| that's like |\IfFileExists|. + +\beginprog +\def\cweb@end_document{% + \cweb@if_file_not_empty{\jobname.idx}{% + \if@cweb@suppress@index@ \else + \CwebIdIndex + \fi + }{}% + \cweb@if_file_not_empty{\jobname.scn}{% + \if@cweb@suppress@reflist@ \else + \CwebRefList + \fi + }{}% + \cweb@save@enddocument + } +\endprog + + +\sect The paragraph layout for both the index and the refinement list +is much the same, it is taken from Plain \cweb{}: Each entry is a +paragraph, nearly no skip between the paragraphs (just a bit to +prevent underfull vboxes), no paragraph indentation, ragged right. +Overfull hboxes in the lists don't make sense, so we prevent them. And +we don't allow hyphenation. + +\beginprog +\def\cweb@list_par_layout{% + \parskip \z@ plus .5\p@ + \parindent\z@ + \rightskip \z@ plus 2.5em + \tolerance\@M \hyphenpenalty\@M + } +\endprog + + +\sect We consider a file as ``not empty'' if (1)~the file exists, +(2)~is not empty, and (3)~has a non-empty line at the very front. (In +fact, an empty line at the front means that there should not be +anything behind it---but we can't test this portably.) + +|\cweb@if_file_not_empty| tests the property, it's parametrized by the +file name and gets passed actions for the true and the false case. + +We open the file first. Then we check if it doesn't exist or if it's +empty, both conditions deliver true on |\ifeof|; in this case we +pretend that there was an empty line. (The \LaTeX{} kernel already +once provided a macro for an empty line, |\@defpar|, we repeat that +definition here since it was discarded there.) Otherwise we read the +first line. At this state, the emptiness of the first line is +equivalent to the non-availability of entries, we can easily construct +an appropriate macro call to set the flag. + +\beginprog +\def\@defpar{\par} +\def\cweb@if_file_not_empty#1#2#3{% + \openin\@inputcheck #1\relax + \ifeof \@inputcheck + \let\next\@defpar + \else + \read\@inputcheck to \next + \fi + \closein\@inputcheck + \ifx \next\@defpar + \def\reserved@a{#3}% + \else + \def\reserved@a{#2}% + \fi + \reserved@a + } +\endprog + + +\sect The identifier index is available in the file |\jobname.idx|. +The setup for the index is a mixture of the |theindex| environment of +the \cls{article} class and DEK's index macros. It's typeset in two +columns; the user may specify an introductionary text for the index +by |\cwebIndexIntro|. If there is any introductionary text we add a +medium skip below. + +For the index, |\parfillskip| set in such a way that almost empty +lines are avoided. + +Before we read in this file, we have to bind the special cseqs used +therein. + +\begin{fixme} + \LaTeX{} feature or bug? The optional argument of |\twocolumn| is + typeset as a vbox, therefore the space at top of the section heading + is not discarded at the top of a page. But we know that |\twocolumn| + will start a page in any case, we must prevent the addition of this + space. Looking in the source, we see that setting the flag + |@nobreak| will prevent this addition, let's do that as a + workaround. File a \LaTeX{} bug report? +\end{fixme} + +\begin{fixme} + Surprise: If |@nobreak| is set \emph{and} if there are no index + entries, |\twocolumn| will drop its optional argument. (That + happened to be noticed when there was an error in + |\cweb@if_file_not_empty|.) File a \LaTeX{} bug report? +\end{fixme} + +\begin{fixme} + If |\CwebListSection| is a chapter tag of the standard classes, that + macro will check if it's in twocolumn mode and will try to set + itself at the top of the current page in full width, as it would + have been given in an optional argument of |\twocolumn|. As the + method that optional argument uses (a float) must not be nested, we + must prevent this to happen. We set the |@twocolumn| flag to false, + chapter macros will then think they're evaluated in a one-column + document. It's debatable if that is a kludge or even \emph{the} + solution -- after all, within the optional argument we aren't in + twocolumn mode any more. File a \LaTeX{} bug report? +\end{fixme} + +\beginprog +\newtoks\cwebIndexIntro + \cwebIndexIntro={} +\def\CwebIdIndex{% + %% two column format + \columnseprule\z@ + \columnsep 35\p@ % value is from article.sty + %% introduction of index + \twocolumn[% + \cwbb@tex + \@nobreaktrue % don't add space in front of section + \@twocolumnfalse % \CwebListSection might be \chapter + \CwebListSection{\indexname}% + \edef\intro{\the\cwebIndexIntro}% % is a local def + \ifx \intro\empty + \else + \the\cwebIndexIntro\unskip + \par\medskip + \fi + ]% + \@mkboth{\uppercase{\indexname}}{\uppercase{\indexname}}% + \message{\indexname:}% % tell the user what we're doing + %% paragraph layout + \cweb@list_par_layout + \parfillskip \z@ plus .6\hsize + %% bindings + \let\I\CwebIndexEntry + \let\[\CwebIndexDeclared + \let\*\cwbb@change_flag + %% read the index + \CwebReadIndex + } +\def\CwebReadIndex{\@input{\jobname.idx}} +\endprog + + +\sect An index entry is typeset with the same hanging indentation like +a cross reference list. + +The entry is tagged with |\.|, if it was entered by the \cweb{} +operator~`|@.|'. Then it shall be typeset as a string. But an indexed +name may also want to use |\.| as an accent. This is the same +situation as we had at the refinement names (in module +\pkg{cwebbase}), where we introduced |\cwbb@check_dot| to handle this +case. The same minor restriction as there holds here, a refinement +name may not consist of a single dot-accented expression. (|@:|~helps +in this singular case.) + +\beginprog +\def\CwebIndexEntry#1, {% + \par + \hangindent\CwebNumberListHangindent + \leavevmode + \cwbb@check_dot{#1}:\quad + } +\endprog + + +\sect The chunks where identifiers are declared are noted with +underlined numbers. We also must not forget the default declaration of +|\9|, the tag for the user definable index layout. + +\beginprog +\def\CwebIndexDeclared#1]{$\underline{#1}$} +\def\9#1{} +\endprog + + +\sect The list of the refinement names is available in the file +|\jobname.scn|. The layout is taken from the plain version: ragged +right, each entry is a paragraph, the different cross reference +categories are separated by a quad. + +We must initialize our whole paragraph layout, as the index might have +been suppressed and no initialization has happened there then. If +there was an index, it changed |\parfillskip| and |\*|, let's restore it. + +\beginprog +\def\CwebRefListName{List of Refinements} + +\def\CwebRefList{% + %% paragraph layout: like in index, but + \onecolumn + \cweb@list_par_layout + \parfillskip\@flushglue % must be reset before section heading + \CwebListSection{\CwebRefListName}% + \@mkboth{\uppercase{\CwebRefListName}}% + {\uppercase{\CwebRefListName}}% + \message{\CwebRefListName:}% + %% different bindings + \def\I{\par \hangindent\CwebNumberListHangindent}% + \def\CwebCrossRef##1##2.{\quad {\reset@font\footnotesize ##1~##2.}}% + \let\Q\CwebXRCite + \let\Qs\CwebXRCites + \let\U\CwebXRUse + \let\Us\CwebXRUses + \let\*\cwbb@change_flag + %% Read the list, allow configuration first. + \csname CwebRefListHook\endcsname + \CwebReadPPList + } +\def\CwebReadPPList{\@input{\jobname.scn}} +\endprog + + +\sect Extra definitions for the sake of internationalization. + +\beginprog +\def\CwebXRCite{\CwebCrossRef{Cited in chunk}} +\def\CwebXRCites{\CwebCrossRef{Cited in chunks}} +\def\CwebXRUse{\CwebCrossRef{Used in chunk}} +\def\CwebXRUses{\CwebCrossRef{Used in chunks}} +\endprog + + + +\chap The end. + +Well, after all we're finished with this class. We must not forget to +restore the underscore catcode. + +\beginprog +\catcode`\_=\CatUsCode + +\endinput +\endprog + + +\sect I would like to thank those who helped me to improve this module. +% In particular, XXX provided XXXsubstantial parts of the code. + +\textsc{Michael M\"uller} and \textsc{Zden\v{e}k Wagner} did thorough +checks that helped me to improve the alpha test version. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\vskip \PltxPreSectSkip + +\begin{rcslog} +$StyleLog: cweb.doc,v $ +\Revision 3.6 1995/11/30 15:44:53 schrod +Still didn't work with version \mbox{$\langle$1994/12/01$\rangle$}, +the copy of |\newif| was not complete.\\ +Problem reported by Michael Seel \path|<seel@mpi-sb.mpg.de>|. + +\Revision 3.5 1995/11/20 22:34:18 schrod +Add language support.\\ +Triggered by Christian Kumpf \path|<smurf@igd.fhg.de>| and Andreas +Scherer \path|<scherer@physik.rwth-aachen.de>|. + +Use my `official' (ACM) email address. + +\Revision 3.4 1995/11/07 17:55:18 schrod + \LaTeX{} \cweb{} should work at least with the last two \LaTeX{} +versions; make it work with the previous-to-last one, version +\mbox{$\langle$1994/12/01$\rangle$}. For that, one has to install the +\mbox{$\langle$1995/06/01$\rangle$} (non-outer) definition of +|\newif|, and |\hb@xt@| must not be used.\\ +Problem reported by Laurent Desnogues +\path|<laurent.desnogues@aiguemarine.unice.fr>| and somebody else (XXX +-- add name). + +\Revision 3.3 1995/09/17 14:15:36 schrod +Initialize list paragraph layout in refinement list, too. With the +introduction of index suppression, the initialization -- located in +the index code -- might have been skipped. + +\Revision 3.2 1995/09/15 10:22:59 schrod +The \cls{cweb} class needs at least \LaTeX{} version +\mbox{$\langle$1994/12/01$\rangle$}.\\ +Problem reported by John S. Robinson \path|jsrobin@umiacs.umd.edu|. + +\Revision 3.1 1995/09/12 23:00:48 schrod +Moved all code that does the actual typesetting of \cweave{} tags and +is therefore also needed for a |cweb| environment. It's now an own +module named \pkg{cwebbase}. + +\Revision 2.8 1995/09/12 11:44:33 schrod +Standard base classes with chapters (i.e., report \& book) produced an +error at the start of the index: |\chapter| may not be called in the +optional argument of |\twocolumn|. Add a workaround to |\twocolumn|.\\ +Problem reported by Christopher Higgins \path|<C.Higgins@cit.gu.edu.au>|. + +\Revision 2.7 1995/08/29 17:32:36 schrod +Add hook for refinement list. + +Allow internationalization of refinement list.\\ +(Problem reported by Christian Kumpf \path|<kumpf@igd.fhg.de>|.) + +Cweb bundle, version 1.0. + +\Revision 2.6 1995/08/29 15:19:50 schrod +Added (hint to non-existence of) description of the internal interface. + +\Revision 2.5 1995/08/29 02:07:26 schrod +Discard dependencies on 10\,pt fonts. + +Support suppression of format directives. + +\Revision 2.4 1995/08/27 19:31:43 schrod +Discard superfluous space at the top of index. Spacing in refinement +heading was wrong. Repair test on empty auxilliary files. Make +section heading for index and refinement list divisions (more) +configurable. Suppression of index and reference list is supported. + +Make configuration of change flag easier. + +Put section title of changed chunks list in marks, and tell the user +that it got typeset. + +\Revision 2.3 1995/08/27 17:24:46 schrod +Make usage of baseclass with chapters work. + +\Revision 2.2 1995/08/27 13:26:22 schrod +Add possibility to suppress change hints. Suppression of unchanged +chunks suppress change hints as well, they are meaningless as all +printed chunks are changed by definition. + +Realize dependencies in options by |\ProcessKeyValOptionsHook|. +Illegal values for enumeration options don't alter the current value +any more. + +List of changed chunks is an unnumbered section now. + +\Revision 2.1 1995/08/25 19:11:18 schrod +Add keyword-value option style, with new \pkg{keyvald} package. + +Hierarchic strucutures are supported now, in addition to the flat +structure of the beta-test version. One can choose with an option. For +that step, the terminology was cleaned up, too: Chunks are not named +sections any more. (That change involved reimplementation of almost +all the structure and toc stuff.) + +The chunk number supplied by \cweave{} is used now, not some computed +number. Change flags are printed, too. + +One can suppress output of unchanged sections. + +One can select the baseclass with an option. That may be used to use +\cls{report} or \cls{book} to get chapter-style layout. Of course, +using an arbitrary baseclass is dangerous, it must conform to the +conventions of \LaTeX{} standard classes. + +\Revision 1.13 1995/08/08 00:14:29 schrod +Updated to \LaTeXe{}, the |cweb| style is now a document class. Used +my standard templates for that, no changes in functionality. + +\Revision 1.12 1993/08/10 14:15:43 schrod +New page on main section only if group level $<$ |\cwebSecNoEject|. +Default for the latter is 3. + +Document that logos will not be defined in this style file. + +Copy of plain macros for |\CwebNumber| does not work. Repaired the +most important one (subscript must be accessed via |\sb|). +Incompatibility to NFSS will be addressed later.\\ +(Problems reported by Zden\v{e}k Wagner \path|<wagner@csearn.bitnet>|.) + +\Revision 1.11 1993/08/10 11:21:07 schrod +Reference to section number does not render a period after the +number any more. + +\Revision 1.10 1993/08/09 20:08:20 schrod +|\cweb@cweave_bindings| is now a no-op if \cweave{} bindings are in +effect already.\\ +(Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +\Revision 1.9 1993/08/09 18:05:28 schrod +Left shift operator wasn't defined correctly.\\ +(Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +\Revision 1.8 1993/06/15 15:22:30 schrod +\textbf{Version 0.2:} Moved from |pub/incoming| to official place, in +Literate Programming Archive. + +\Revision 1.7 1993/06/15 13:25:48 schrod +First attempt to make it a style: |article| is imported. Warns the +user if he tries to use |cweb| as a style option. + +\Revision 1.6 1993/06/15 08:49:23 schrod +|\cweb@check_dot| must not evaluate its argument in an |\edef|, this +causes problems if a |\PB| is within. Now I try hard not to evaluate any +tokens outside of my control. + +Can use |\@defpar| for an empty line in |\cweb@has_entries|, don't +need an own macro. + +\Revision 1.5 1993/06/14 17:50:30 schrod +Handle a missing |\con|: |\inx| and |\con| are now never looked at. +Instead |\fin| checks for the existence of the lists and typeset them +if there are entries available. + +\Revision 1.4 1993/06/14 15:54:18 schrod +Made it work with older versions of \LaTeX{}, too. The |\enddocument| +implementation of cweb.sty depends on the |\end| implementation; check +if the current implementation is one we know of (currently: 91-01-14 +and 92-03-25).\\ +(Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +Add FSA diagram about processing states. CR state is also switched +to from \TeX{} state (that happens with |\ch| at the document end). + +\Revision 1.3 1993/05/13 17:51:21 schrod +Refinements may also be filenames (`|@(|'). Then the complete name +consists of a |\.| macro call, which is handled now.\\ +(Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +Made the detection of `|@.|' index entries more robust. + +\Revision 1.2 1993/05/12 18:28:59 schrod +Adapted to recent changes of \cweave{} (of April 93): + +Main sections have a group level, represented in the table of +contents. This changed the complete implementation of section tags. + +New C token cseqs: |\Z| and |\MRL|, implemented as |\CwebLe| and +|\CwebCombinedOp|. + +\Revision 1.1 1993/04/09 15:00:37 schrod +Initial revision + +\end{rcslog} + + + +\end{document} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Local Variables: +mode: LaTeX +TeX-brace-indent-level: 4 +indent-tabs-mode: t +TeX-auto-untabify: nil +TeX-auto-regexp-list: LaTeX-auto-regexp-list +compile-command: "make cweb.cls" +End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cwebarray.sty b/Master/texmf-dist/doc/latex/cweb-latex/src/cwebarray.sty new file mode 100644 index 00000000000..1eb73a0d48b --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cwebarray.sty @@ -0,0 +1,50 @@ +% $Id: cwebarray.sty,v 1.2 1995/08/08 00:14:31 schrod Exp $ +%---------------------------------------------------------------------- + +% +% LaTeX style option cwebarray +% depends on array style option +% +% [LaTeX] +% (history at end) + +\ProvidesPackage{cwebarray} + + +% +% What's this style option for? +% +% If you use CWEB, you cannot use vertical bars (`|') as rule specifiers in +% tables any more; CWEAVE processes them already. This style option +% defines `I' (that's an uppercase i) as a replacement for the +% vertical bar. +% +% I.e., write +% +% \begin{tabular}{lIl} +% +% instead of \begin{tabular}{l|l}. + +% This option won't work without the array style. + +\ifx \d@llarbegin\undefined + \RequirePackage{array} +\fi + +\newcolumntype{I}{|} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% $Log: cwebarray.sty,v $ +% Revision 1.2 1995/08/08 00:14:31 schrod +% Updated to \LaTeXe{}, the |cweb| style is now a document class. Used +% my standard templates for that, no changes in functionality. +% +% Revision 1.1 1993/08/09 18:05:55 schrod +% Mentioned that `|' cannot be used for LaTeX purposes, in +% particular, not for ruled tables. Described workarounds, one of them +% is the new style option cwebarray. +% [Reported by Felix G\"artner] +% diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cwebbase.doc b/Master/texmf-dist/doc/latex/cweb-latex/src/cwebbase.doc new file mode 100644 index 00000000000..280e53f82fc --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cwebbase.doc @@ -0,0 +1,2059 @@ +% $StyleId: cwebbase.doc,v 1.4 1995/11/07 17:55:19 schrod Exp $ +%---------------------------------------------------------------------- +% Written by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>. +% Copyright conditions see below (GPL). + +% +% LaTeX macros cwebbase +% support for incorporation of CWEAVE markup in LaTeX documents +% +% [LaTeX in MAKEPROG] +% (history at end) + + + + +\documentclass{progltx} + +\usepackage{cweb-doc} % document-specific markup +\usepackage{fullpage} + + +\RCS $StyleRevision: 1.4 $ +\RCS $StyleDate: 1995/11/07 17:55:19 $ + + +\begin{document} + + +\title{Typesetting \cweave{} Output} +\author{% % LaTeX does not discard unnecessary glue... + Joachim Schrod% + \thanks{% + \protect\raggedright + TU~Darmstadt, Computer Science Department, WG Systems Programming, + Alexanderstr.~10, D-64283~Darmstadt, Germany. + Email: \texttt{schrod@iti.informatik.th-darmstadt.de}.% + }% + } +\date{% + Revision \RCSStyleRevision\\ + (as of \RCSStyleDate)% + } + +\maketitle + + +% doesn't work with progltx yet +%\tableofcontents + + + + +\chap Introduction. + +This code shall interpret and render the tag set output by \cweave{}. +That's realized in this module as it's needed in multiple places -- +when we want to use \LaTeX{} markup in \cweb{}, when we want to +incorporate \cweb{} pieces in \LaTeX{} documents (as examples, or in +textbooks), and when we want to incorporate whole \cweb{} documents in +a \LaTeX{} document. (That's by far the most difficult task.) + +As \cweb{} operates in modes, for obvious reasons our implementation +is based on a finite state automaton (FSA). The whole tag set is +separated into subsets that are valid in certain states. + +The complete set of tags does not obey any name conventions, some tags +are even in conflict with standard \LaTeX{} tags (e.g.\ |\\|). Most +tags are used to render code pieces. With the introduction of states +we can restrict the visibilities of these tags to those states where +we typeset program parts. The needed functionality will be available +in cseqs of our namespace, we'll map that to \cweave{}'s names in a +group. + +Then we have to implement the rendering of chunks and sections, that's +(more or less) a straight-forward task. Actually, we only set up the +basic code pieces, the integration of section divisions in the actual +\LaTeX{} document is a task of higher-level code; that integration +depends heavily on the type of document. That also implies that we +won't implement front or back matter material (document markup, table +of contents, index, list of refinements, etc.)\ in this module. + + +\sect Let's identify this module. + +\noindent The code below is explained in the implementation +documentation of the \pkg{rcs} package. + +\beginprog +\begingroup + \def\RCSFile#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesFile{#1}[\date\space\id\space #2]% + } + + \RCSFile{cwebbase.tex}{CWEAVE tags for LaTeX markup} + $StyleDate: 1995/11/07 17:55:19 $: 9999/00/00 \endRCS + $StyleRevision: 1.4 $: 0.0 \endRCS +\endgroup +\endprog + + +\sect This module is part of the supported \textsl{cweb-sty} bundle. +Send bug reports, comments and repairs. + +It assumes that the canonical setup of my modules has happened and can +be used herein. (In particular, the underscore is a letter.) + + +\sect This module reserves the namespace |cwbb|. It assumes that +|\cweb_warning| is bound either to |\PackageWarningNoLine| or +|\ClassWarningNoLine|, depending on the environment. + +\beginprog +\ifx \cwbb@loaded\undefined + \def\cwbb@loaded{$StyleRevision: 1.4 $} +\else + \cweb_warning{cwebbase}% + {Some other package already uses namespace `cwbb'} +\fi +\endprog + + +\sect This is freely distributable 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 software is distributed in the hope that it will be useful, but +\textbf{without any warranty}; without even the implied warranty of +\textbf{merchantability} or \textbf{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 in +the file |License| along with this package; if not, write to the Free +Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA. + + + + +% ------------------------------------------------------------ +% +% subdocument: The interface between CWEAVE and TeX +% + +\input{cweave-spec} + +% +% ------------------------------------------------------------ + + + + +\chap Interface of \pkg{cwebbase} module. + +\pkg{cwebbase} implements most of \cweave{} tags. It sets up tons of +redefinable cseqs, all of them start with |Cweb|. +% +\begin{fixme} + How do I document them? We need a configuration document anyhow. Do + I present here just a list of those cseqs realized in this module + and refer to the config docs? Need to wait until I have it, then + we'll see how the stuff here will be added. +\end{fixme} + + +\sect This module supports both hierarchic and flat section +structuring. You have to bind |\cweb@structure| to 0 (hierarchic) or 1 +(flat) before importing it, to show which structure is wanted. + + +\sect This module supports suppression of different document parts. +You have to define flags |@cweb@suppress@|\<foo>|@| with +$\mbox{\<foo>} \in \{ |changehints|, |unchanged|, |format| \}$ to +denote if suppression shall happen. + + +\sect The counter |secnumdepth| must be~11 if chunks shall be +numbered. That counter doesn't need to be set when this module is +imported, it can be set locally during typesetting \cweb{} code. + +The definitions for flat structure assume that |secnumdepth| is~11 +during typesetting. + + +\sect |\part|, |\chapter| (if available), and |\section| are used for +\cweb{} section divisions (those with the lowest ranks). These +commands will change the respective counters globally and will +add toc lines and marks. You might want to prevent that by redefining +|\addcontentsline| and |\mark|. + +Table of contents macros are not defined for the section divisions +introduced by this module. You must either prevent that they are +written to the |AUX| file at all; or you must define them. +% +\begin{fixme} + Add explanation of introduced section divisions. +\end{fixme} + +For flat structure, all section divisions are of type `|chunk|', like +chunks. The section names start with `|\cwbbRank{|\<rank>|}|'. By +default, |\cwbbRank| takes one argument and expands to the empty list +-- this can be redefined for the table of contents. + + +\sect The document end, as explained in the \cweave{} interface specs +(chunk~\ref{spec:sec:docend}), is not implemented. That must be done +by the user of this module -- if the back matter is to be processed at +all. + + + + +\chap Processing states. + +We have to typeset five different categories of material: +Documentation, program pieces---embedded within the documentation and +as large chunks, \TeX{} material within program pieces (i.e., comments +and refinement names), and cross reference information. Since we need +a complete other environment for the program pieces than for the rest +we design ``states'' where we switch to appropriately. +% +\begin{enumerate} + +\item A chunk starts in the \textsl{documentation state}. + +\item |\B| switches to \textsl{program state}. This can happen in +documentation and program state. + +\item While we process the argument of |\PB| we're in \textsl{restricted +program state}; |\PB| may appear in documentation and in \TeX{} +state. Since \TeX{} state can be switched on within restricted +program state, |\PB| can appear within the argument of itself. + +\item In the arguments of |\C|, |\SHC|, and |\X| we switch to +\textsl{\TeX{} state}. All these cseqs appear only in (restricted) +program state, their official names are actually different. I.e., only +in (restricted) program state these cseq are bound to the meaning +described here. + +\item Cross reference information are attached to most chunks with +refinements. This information is processed in \textsl{CR state}. +After CR state material +comes always the next chunk or the document end, i.e., material in +documentation state. + +\end{enumerate} +% +This FSA is illustrated by the diagram in figure~\ref{fig:fsa}. + +\begin{figure} + +\begin{center} +\chardef\\=`\\ +\input{cweb-fsa.latex} +\end{center} + +\caption{The processing state's FSA. The automaton starts and ends in +the ``documentation'' state.} +\label{fig:fsa} + +\end{figure} + +|\cwbb@documentation| will switch to documentation state, +|\cwbb@program| to program state, |\cwbb@Rprogram| to restricted +program state, |\cwbb@tex| to \TeX{} state, and |\cwbb@CR| to CR state. +If we're already in a state, the switch to this state shall be a +permissible null operation. + + +\sect The basic difference between these states can be named with +two parameters: (1)~The cseq bindings in effect and (2)~the layout +parameters used for paragraph makeup. + +In (restricted) program state and in CR state the text is output +under the control of \cweave{}, and tagged by \cweave{}. The used +tags are from a global namespace and should only be in effect during +these states. We call this tag set the \textsl{\cweave{} bindings}. In the +other two states the tags are largely defined by the user, the tag +set is called the \textsl{user bindings}. The switch to another binding +is always done locally, i.e., if we switch from documentation to +restricted program state within a group we don't have to bother about +the restauration of the user binding; it will be done automatically +by \TeX{} at the end of the group. Nevertheless we must be able to +switch from the \cweave{} bindings back to the user bindings which +were in effect when we activated the \cweave{} bindings. This is +needed for the \TeX{} state which is always activated within +(restricted) program state. + +The parameters for \textsl{program layout} are really special ones +since they need to support the indentation which shows the program +structure. These parameters are used in program and in \TeX{} state. +The \textsl{document layout} parameters established by the user are +used in the other three states. + +The following table shall summarize this. $C$~denotes \cweave{} +bindings, $U$~user bindings, $P$~program layout, and $D$~document +layout. If an entry is empty, its value is not changed on entry in +this state. +% +\begin{center} + \DeleteShortVerb\| +\begin{tabular}{r|c|c} +\multicolumn1{c|}{\textsc{State}} & \textsc{Binding} & \textsc{Layout} \\[1pt] +\hline +documentation & $U$ & $D$ \\ +program & $C$ & $P$ \\ +restricted program & $C$ & \\ +\TeX{} & $U$ & \\ +CR & $C$ & $D$ \\ +\end{tabular} + \MakeShortVerb\| +\end{center} + + +\sect Since the user bindings and the document layout is defined +initially, we don't have to do anything if it's requested. Only if we +change it, i.e., within |\cwbb@cweave_bindings| and +|\cwbb@program_layout|, we redefine |\cwbb@user_bindings| and +|\cwbb@doc_layout|. If they are eventually executed, they shall +rebind themselves back to |\relax|. This way we can switch to +documentation state as often as we want. + +\beginprog +\let\cwbb@user_bindings=\relax +\let\cwbb@doc_layout=\relax + +\def\cwbb@documentation{% + \cwbb@user_bindings + \cwbb@doc_layout + } +\def\cwbb@Rprogram{\cwbb@cweave_bindings} + +\def\cwbb@program{% + \cwbb@cweave_bindings + \cwbb@program_layout + } +\def\cwbb@tex{\cwbb@user_bindings} + +\def\cwbb@CR{% + \cwbb@cweave_bindings + \cwbb@doc_layout + } +\endprog + + + + +\chap Saving and restoring control sequences. + +We have a lot of cseqs which are defined within the namespace of this +module and which will be used with other names. This usage is in a +controlled environment, namely neither in documentation nor in \TeX{} +state. (I.e., the text processed is tagged by \cweave{}, not by humans; +therefore we have a precise specification of the cseqs we have to +accept.) We cannot work with groups where a cseq is just redefined +and \TeX{} takes care for establishing the old binding again; when we +switch from program state to \TeX{} state all the bindings which were +in effect before the program state get active, i.e., in the +documentation state, must be in effect again. We cannot simply +consider the \TeX{} state as something parallel to program state, it +must be a hierarchical relationship: In the program state values are +set up which must be available after switching back from \TeX{} to +program state. + +We save the current binding of a cseq in another cseq, but only if +there exists a binding currently. This is done to save valuable +\TeX{} main memory. (Why don't all those people who talk about +extending \TeX{} not just implement dynamic memory management for the +existing \TeX{}? It would still be \TeX{} and would \emph{really} be +a worthy activity. But not enough fun, I assume\,\dots) Actually, one +can assume that nearly no cseq bindings must be saved at all---the +used names are strange enough. The bindings of |\foo|, i.e., of the +cseq with the name \fbox{\ttfamily foo}, is saved as the cseq with the +name \fbox{\ttfamily cweb\char `\\ foo}, i.e., as +|\csname cweb\string\foo \endcsname|. + + +\sect The save process is not done statically, but by the macro +|\cwbb@rebind| which interprets a list of tuples $({\it old\_name}, +{\it new\_name})$, terminated by the tuple $(|\stop|, |\stop|)$. +Eventually it constructs two new lists, |\cwbb@to_restore| with the +cseqs which had a binding, and |\cwbb@undefined| with the names which +didn't have one. + +The saving is actually done by |\cwbb@save_binding|, |\cwbb@rebind| +is responsible for the initialization, |\cwbb@do_rebind| for the +effective rebinding and the tail recursion on the list. + +\begin{fixme} + We could pull the |\next| assignment in the |\else| branch out of + the loop to get a better performance. Should measure if this is of + interest. +\end{fixme} + +\beginprog +\newtoks\cwbb@undefined +\newtoks\cwbb@to_restore + +\def\cwbb@rebind{% + \cwbb@undefined{}% + \cwbb@to_restore{}% + \cwbb@do_rebind + } +\def\cwbb@do_rebind#1#2{% + \ifx #1\stop + \let\next\relax + \else + \cwbb@save_binding #2% + \let #2=#1% + \let\next\cwbb@do_rebind + \fi + \next + } +\endprog + + +\sect If the cseq to be saved is undefined, it may just be added to +the ``undefined list.'' Otherwise its binding is saved and it's added +to the ``to-be-restored list.'' + +\TeX{}nical note: The cseq-name for the saved binding must be created +before the |\let| is executed. + +\beginprog +\def\cwbb@save_binding#1{% + \ifx #1\undefined + \cwbb@undefined \expandafter{\the\cwbb@undefined #1}% + \else + \expandafter\let \csname cweb\string#1\endcsname =#1% + \cwbb@to_restore \expandafter{\the\cwbb@to_restore #1}% + \fi + } +\endprog + + +\sect The restoration of rebound cseqs is a two-tied activity: All +previously undefined cseqs must be made undefined again, and all saved +cseqs must be restored. Actually, we don't need to reset the two token +lists, but we do it to save space. + +Both |\cwbb@undefine| and |\cwbb@restore_binding| iterate over a list +of cseqs terminated by |\stop|. + +\begin{fixme} + And here the |\next| assignment could be prepended to the loop as + well. +\end{fixme} + +\beginprog +\def\cwbb@restore_bindings{% + \expandafter\cwbb@undefine \the\cwbb@undefined \stop + \cwbb@undefined{}% + \expandafter\cwbb@restore_binding \the\cwbb@to_restore \stop + \cwbb@to_restore{}% + } + +\def\cwbb@undefine#1{% + \ifx #1\stop + \let\next\relax + \else + \let#1\undefined + \let\next\cwbb@undefine + \fi + \next + } +\endprog + + +\sect \TeX{}nical note: As in |\cwbb@save_binding|, the cseq-name for +the saved binding must be created before the |\let|s are executed. + +\begin{fixme} + Another |\next| assignment. +\end{fixme} + +\beginprog +\def\cwbb@restore_binding#1{% + \ifx #1\stop + \let\next\relax + \else + \expandafter\let \expandafter#1\csname cweb\string#1\endcsname + \expandafter\let \csname cweb\string#1\endcsname \undefined + \let\next\cwbb@restore_binding + \fi + \next + } +\endprog + + + + +\chap Chunks. + +All chunks are numbered subsequently. The chunk number is supplied as +part of the markup. In addition, the `changed' tag |\*| may be +appended to the chunk number. + +By default, chunks have approximately two picas vertical space in +front. + +If we use an hierarchic structure, we output the chunk number at the +refinement. (It's only needed to identify the refinement for cross +references.) But chunks are important structural units and thus should +be marked by typographic means that's more visible than the space +mentioned above, we add a `chunk start marker'. + +For a flat structure, we output the chunk number as the chunk start +marker, that is the traditional \WEB{} layout. + +In any case, the documentation part shall be run in after the chunk +start marker. + +\beginprog +\newskip\CwebChunkPreSkip + \CwebChunkPreSkip=2pc plus 1pc minus 6pt +\endprog + + +\sect In \LaTeX{}, structural divisions are best realized by +|\@startsection|, we'll use it also for chunk starts. The chunk start +marker is the section heading. For hierarchic structure, we use a +traditional paragraph sign, used since medieval times to tag new text +units. Our first test showed that the paragraph sign has typically an +underlength, that doesn't look good at the start of a chunk. We raise +the sign by its depth. + +For flat structure, we don't have text as the section heading, +but we have to cope for a deficiency of \LaTeX{}: It always leaves a +quad after the section number (by the way, this is not mentioned in +the documentation---you have to look in the macros to figure this +out). So we use a backskip of $\rm -1\,em$ as the chunk start marker +then. + +Changed chunks are marked by a changeflag, by default a star lapping +to the right. We need the information if that chunk is changed to +decide if we shall output the changeflag. We demand from the chunk +macros that they record that info in the flag |@cwbb_changed_chunk@|. + +Each structural division must be categorized, it belongs to a +\textsl{type}. This type determines also the name of the counter, the +mark handling for this category, and how this section tag is +represented in the table of contents. The type of chunks is `|chunk|' +(trivial, isn't it?). + +Furthermore, a structural division in \LaTeX{} has an associated +\textsl{level}. That level is used to determine if that division get +numbered in text or table of contents. For sections, we'll compute the +level from the rank, it will not be larger than the rank.% + \footnote{Check the next section for a more precise definition of + `rank' and `level'.} +Since the highest section rank is~10, we may use 11 as chunk level. + +For flat structure, we output the number for all section headings, +including chunks. For hierarchic structure we use the default maximum +level as supplied by our document class (e.g., 3~for \cls{article}, +and 2~for \cls{report} or \cls{book}). + +As a last point, we have to care already for sections in flat +structure. They will use the |chunk| category as well, we have to +distinguish them in the table of contents. For that, we'll record the +level in the text, it will get written to the table of contents. + +\beginprog +\newif\if@cwbb_changed_chunk@ +\let\CwebChangeFlag=* +\if@cweb@suppress@changehints@ + \let\cwbb@change_flag=\relax +\else + \let\cwbb@change_flag=\CwebChangeFlag +\fi +\def\cwbb@lap_change_flag{\rlap{\cwbb@change_flag}} + +\ifcase \cweb@structure + %% hierarchic + \let\CwebChunkHeadingStyle\relax + \newbox\cweb@chunk_marker + \setbox\cweb@chunk_marker=\hbox{\P} % tradition from medivial times + \setbox\cweb@chunk_marker=\hbox{% + \raise\dp\cweb@chunk_marker \box\cweb@chunk_marker + } + \def\CwebChunkHeadingMarker{\copy\cweb@chunk_marker} + \def\CwebChunkHeading#1{% + \CwebChunkHeadingMarker + \if@cwbb_changed_chunk@ \cwbb@lap_change_flag \fi + } + \or + %% flat + \def\cwbbRank#1{} + \def\CwebChunkHeadingStyle{\bfseries} + \def\CwebChunkHeading#1{% + \protect\cwbbRank{#1}% + \kern -1em + \if@cwbb_changed_chunk@ \cwbb@lap_change_flag \fi + } +\fi +\endprog + + +\sect Chunks are tagged with |\M| and get passed the chunk number as +argument. Before we evaluate |\@startsection|, we'll start the chunk. +That's common code to be used by sections as well, as they also +implicitely start a chunk. + +\beginprog +\def\M#1{% + \cwbb@start_chunk{#1}% + \@startsection + {chunk}% % category, == counter etc. + {11}% % level + {\z@}% % no indentation for heading + {\CwebChunkPreSkip}% % skip above heading + {\m@ne em}% % run-in heading, 1em distance to text + {\normalfont\CwebChunkHeadingStyle}% % layout + {\CwebChunkHeading{11}}% % text, level might go to toc file + } +\endprog + + +\sect But let's first declare how a chunk number is represented. The +principle rendering is controlled by |\thechunk|, namely, we get +arabic numbers. This rendering is used both for creation of the +section header (if in flat mode) and for cross references. I.e., +|\ref| expands into it. + +But for flat structure we need different expansions: In the section +header a period shall be appended, a cross reference shall appear +without such a period. We use two different macros: |\thechunk| +creates the number with the period, |\cwbb@refchunk| only the number. +The latter is used for a redefinition of |\@currentlabel|. Of course, +for hierarchic structure, both are the same. + +\beginprog +\newcounter{chunk} + +\def\cwbb@refchunk{\arabic{chunk}} + +\ifcase \cweb@structure + %% hierarchic + \let\thechunk=\cwbb@refchunk + \or + %% flat + \def\thechunk{\arabic{chunk}.} +\fi +\endprog + + +\sect Each chunk is started by |\cwbb@start_chunk|, which does the +common actions. First of all, we switch to documentation state. + +Then we store the chunk number in the |chunk| counter. That implies +that the chunk start must not step this counter! We'll take care for +that later by redefining |\refstepcounter|. The actual number is +passed as the argument, including an optional |\*| used to denote +changed chunks. We'll redefine that cseq to update the flag +|@cwbb_changed_chunk@|. + +Each chunk must be typeset with an open |\if| since it is finished by +|\fi|. If we shall suppress the output of unchanged chunks, we have +to use |\iffalse| if not |@cwbb_changed_chunk@|, otherwise |\iftrue|. +The flag |@cwbb_print_chunk@| is set up to provide an appropriate +test. + +When we typeset a chunk, we evaluate |\cwbb@init_print_chunk|. For +hierarchic structure, that cseq will be used to initialize the +typesetting of the chunk number at program parts. + +\beginprog +\if@cweb@suppress@unchanged@ + \def\if@cwbb_print_chunk@{\if@cwbb_changed_chunk@} + \@gobble\fi % close \if in case it's skipped +\else + \let\if@cwbb_print_chunk@=\iftrue + \@gobble\fi % same here +\fi + +\def\cwbb@start_chunk#1{% + \cwbb@documentation + \begingroup + \def\*{\global\@cwbb_changed_chunk@true}% + \global\@cwbb_changed_chunk@false + \global \c@chunk #1\relax % might expand \* + \endgroup + \if@cwbb_print_chunk@ + \cwbb@init_print_chunk + } +\endprog + + +\sect |\@startsection| will step the section counter (i.e., |chunk|). +Since we just assigned it in |\cwbb@start_chunk|, that would leave us +with a counter that's one too high. And our output in cross references +may be wrong, as a period is appended in flat structure. + +That damage all comes from one macro, |\refstepcounter|; let's +advice it to do the Right Thing for |chunk| counters. + +\beginprog +\let\cwbb@refstepcounter=\refstepcounter + +\def\cwbb@string@chunk{chunk} +\def\refstepcounter#1{% + \def\@tempa{#1}% + \ifx \@tempa\cwbb@string@chunk + \protected@edef\@currentlabel{\cwbb@refchunk}% + \else + \cwbb@refstepcounter{#1}% + \fi + } +\endprog + + + + +\chap Sections. + +Important sections are started on a new page, normal sections have the +same space as chunks in front. The very first section does not +automatically start on a new page since a title may be in front of it. + +Each section division has a \textsl{rank}, that denotes the section +depth as seen by \cweave{}. + +For this depth we compute a \textsl{level}, used to denote the section +depth for \LaTeX{}. This section depth is used to decide where +numbering shall stop, or if that entry shall be presented in the table +of contents, etc. + +These two numbers are not the same, due to the support of document +classes with chapters. + +We consider a section as important if it's rank is smaller than~3, +i.e., then we'll start a new page. This limit is controlled by the +number |\CwebRankNoEject|. The rank is used as the section level +and is therefore available to configure depth of typeset numbering and +appearance in table of contents. + +\beginprog +\def\CwebRankNoEject{3} +\endprog + + +\sect Sections are started with the macro |\N|. It's first parameter +is the section's rank. The second parameter is the chunk number, the +third the title of the section. This last parameter must be terminated +by a dot. + +Each section implicitly starts a chunk. As explained above, major +sections may eject the page, and we add our actual section heading +with |\CwebSection|. + +We also tell the user that we have reached the next section by telling +him about the current chunk number. The message is output after the +section header is set, it shall be on the correct page. Since the +token list to be output is expanded at shipout time, we must take care +for the immediate expansion ourselves. + +\beginprog +\def\N#1#2#3.{% + \cwbb@start_chunk{#2}% + \CwebEjectSection{#1}% + \CwebSection{#1}{#3}% + \begingroup + \def\*{}% + \edef\tmp{*#2}% + \message \expandafter{\tmp}% + \endgroup + } +\endprog + + +\sect At the start of a section we usually eject the page if our rank +is not too low. But if the user had a title above the first section, +he won't want this page break. So we try to guess it. If we guess +wrong, the user may either add |\newpage| himself or he may redefine +|\CwebEjectSection| in a package. + +\beginprog +\def\CwebEjectSection#1{% % #1 == rank + \gdef\CwebEjectSection##1{% + \relax + \ifnum ##1<\CwebRankNoEject\relax + \newpage + \fi + }% + } + +\if@titlepage + \CwebEjectSection{} +\fi +\endprog + + +\sect Now comes a heary piece. We have 11~section ranks, and need 11 +different section categories, section counters, etc. For flat +structure, they shall all do the same; for hierarchic structure, they +shall be really different. + +\noindent Let's have a look at the hierarchic structure first, it's +more complex. +% +\begin{itemize} + +\item We associate section rank~0 (that's `|@**|') with document + parts, i.e., map it to |\part|. Many smaller programs won't use it. + +\item If we are used in a class that has a bound cseq |\chapter|, we + associate rank~1 (`|@*0|') with it and rank~2 (`|@*1|') with + |\section|. Otherwise we associate rank~1 with |\section|. These + tags (|\chapter| and/or |\section|) must be defined because many + macros that want to create section divisions will use them. + +\item All other section ranks are placed below |\section|. + |\subsection| and other \LaTeX{} style markup is not supported. + + For hierarchic structure, we identify these sections with category + names `|section|$l$', where $l$ is the respective level, computed + from the rank. Those section names do not exist yet, we have to + create them. + +\end{itemize} + +Now we come to the point why we can't use the rank as the section +level passed to \LaTeX{}: When we assume the level usage of \LaTeX{}'s +standard classes, |\section| is \emph{always} on level~1, independent +of the existence of |\chapter|. The latter is placed on level~0, its +existence only influences the section level of |\part|, which is +either $-1$ or~0. + +This implies that |\subsection| in a standard class is always on +level~2, but our equivalent section division is either `|@*0|' +(rank~1) or `|@*1|' (rank~2). I.e., when we have chapters, we use a +level that's one lower than the rank, otherwise we use the rank. + +For flat structure, we use type |chunk|. This way we'll use the chunk +numbers, they are already set up. + +For flat structure, we will map all ranks to the same section markup. +This markup will also be accessible by |\section| or |\chapter|. They +will be declared to be on a level that is the same as the rank. + + +\sect The printed representation of a section divison number is simply +the presentation from the next upper level, a full stop, and an arabic +section number. When we compute the name of the previous level we must +pay attention to our first section division created this way. This +division must be placed below |section|, without any following number. + +Since registers are a valuable resource in \TeX{}, we have to take +care not to allocate a superfluous one. + +\beginprog +\ifcase \cweb@structure + %% hierarchic + \newcounter{section2}[section] + \@namedef{thesection2}{\@nameuse{thesection}.\arabic{section2}} + \newcounter{section3}[section2] + \@namedef{thesection3}{\@nameuse{thesection2}.\arabic{section3}} + \newcounter{section4}[section3] + \@namedef{thesection4}{\@nameuse{thesection3}.\arabic{section4}} + \newcounter{section5}[section4] + \@namedef{thesection5}{\@nameuse{thesection4}.\arabic{section5}} + \newcounter{section6}[section5] + \@namedef{thesection6}{\@nameuse{thesection5}.\arabic{section6}} + \newcounter{section7}[section6] + \@namedef{thesection7}{\@nameuse{thesection6}.\arabic{section7}} + \newcounter{section8}[section7] + \@namedef{thesection8}{\@nameuse{thesection7}.\arabic{section8}} + \newcounter{section9}[section8] + \@namedef{thesection9}{\@nameuse{thesection8}.\arabic{section9}} + \ifx \chapter\undefined + \newcounter{section10}[section9] + \@namedef{thesection10}{\@nameuse{thesection9}.\arabic{section10}} + \fi +\fi +\endprog + + +\sect Sections are typeset by |\CwebSection|; rank and title are the +arguments. + +For hierarchic structure, we select the proper cseq according to rank: +|\part|, |\chapter| if this is a structure with chapters, |\section|, +and |\cwbb@section{|\<rank>|}| for other ranks. For the last cseq we +also have to supply the section category, it's `|section|$l$' where +$l$ is the rank~$r$ if we don't have chapters, $r-1$ otherwise. + +That category cannot be computed by |\cwbb@section| itself since we +want to use that macro also for flat structure. But there all sections +are basically chunks, we have to use the |chunk| category there. Since +we want to differentiate them in the table of contents nevertheless, +we record the current rank in the title. + +\beginprog +\ifcase \cweb@structure + %% hierarchic + \ifx \chapter\undefined + \def\CwebSection#1#2{% + \ifcase #1 + %% 0 + \let\next\part + \or %% 1 + \let\next\section + \else %% level = rank + \def\cwbb@sect_name{section#1}% + \def\next{\cwbb@section{#1}}% + \fi + \next{#2}% + } + \else + \def\CwebSection#1#2{% + \ifcase #1 + %% 0 + \let\next\part + \or %% 1 + \let\next\chapter + \or %% 2 + \let\next\section + \else %% level = rank - 1 + \count@=#1 \advance \count@\m@ne + \edef\cwbb@sect_name{section\number\count@}% + \edef\next{\noexpand\cwbb@section{\number\count@}}% + \fi + \next{#2}% + } + \fi + \or + %% flat + \def\CwebSection#1#2{% + \def\cwbb@sect_name{chunk}% + \cwbb@section{#1}{\protect\cwbbRank{#1}#2}% + } + \def\section{% + \def\cwbb@sect_name{chunk}% + \cwbb@section{1}% + } +\fi +\endprog + + +\sect We use the same layout for all minor sections. That layout can +be changed by ammended by defining |\CwebSect|$r$|Hook| to redefine +|\CwebSectPreSkip| and/or |\CwebSectLayout| locally. (Of couse, it may +be redefined once globally, too.) These are the values to be used for +arguments 4 and~5 of |\@startsection|, pay attention to the skip sign, +telling about indentation of the first paragraph. And don't forget +that the skip is only used for sections on ranks below +|\CwebRankNoEject|, the others start on a new page anyhow. + +The default definition sets the section title in bold and leaves the +same space as before chunks. The first paragraph of the following +documentation has no indentation. + +Other layout changes (indentation for heading, etc.)\ must be made by +redefining |\cwbb@section|. Or---email me, if you want to do it. Then +I might be enclined to introduce further possibilities. + +\beginprog +\newskip\CwebSectPreSkip + \CwebSectPreSkip = -\CwebChunkPreSkip +\def\CwebSectLayout{\normalfont\bfseries} + +\def\cwbb@section#1{% % #2 (next token) is title + \csname CwebSect#1Hook\endcsname % \relax if undefined + \expandafter\@startsection + \expandafter{\cwbb@sect_name}% % category; for counter, etc. + {#1}% % level is rank + \z@ % no indentation for heading + \CwebSectPreSkip % skip above, maybe no next par indent + \medskipamount % skip below heading + \CwebSectLayout + } +\endprog + + + + +\chap Marks. + +\begin{fixme} + Since I don't know yet how to handle marks I ignore most of them for + the time being. + + Have to change this later. +\end{fixme} + +\beginprog +\let\chunkmark\@gobble + +\count@=2 +\@whilenum \count@<11 \do { + \expandafter\let \csname section\number\count@ mark\endcsname \@gobble + \advance \count@ by 1 + } +\endprog + + + + +\chap Typesetting programs. + +Program pieces come in two flavours: as argument of |\PB|, or as +material after |\B|. In the former case we can use a group for the +switch to the restricted program state, the group end will restore the +previous state again. In the latter case we use |\B| for the switch to +program state, the cross reference list or the next chunk will go to +another state. Since we have to do more for the material after |\B|, +we define this cseq later. + +\beginprog +\def\PB#1{% + \begingroup + \cwbb@Rprogram + \leavevmode + #1% + \endgroup + } +\endprog + + +\sect Note, that |\Y| cannot just be |\smallskip|, as in Plain +\cweb{}. We must assert that the current paragraph is ended before the +vertical glue is inserted, and that's not done by the \LaTeX{} +definition of |\smallskip|. In addition we add some negative penalty, +here is a good place for a page break. As the penalty value we use +half the chunk break penalty---of course a chunk start is an even +better place for a page break\,\dots + +It might be that |\Y| is the very first token in a chunk. Then the +chunk start marker isn't set already since it is regarded as a run-in +section heading. In that case we don't set the vertical skip but +simply start the chunk with the program part. + +\TeX{}nical note: The flag |@noskipsec| may be used to test if we're +immediately after a run-in section heading. + +\beginprog +\newcount\CwebProgPenalty + \CwebProgPenalty=\@secpenalty + \divide\CwebProgPenalty by 2 +\def\Y{% + \if@noskipsec + \else + \par + \penalty\CwebProgPenalty + \smallskip + \fi + } +\endprog + + +\sect Yep, let's unfold the ``official'' names of the cseqs used in +program state. + +If we turn on the \cweave{} bindings, they might be in effect already, +we don't need to establish them again. We can test +|\cwbb@user_bindings| for this case, it will be redefined then. + +\beginprog +\def\cwbb@cweave_bindings{% + \ifx \cwbb@user_bindings\relax + \cwbb@rebind + % indentation and paragraph layout + \cwbb@incr_indent \1% + \cwbb@decr_indent \2% + \cwbb@expr_break \3% + \cwbb@backup \4% + \cwbb@opt_break \5% + \cwbb@break \6% + \cwbb@big_break \7% + \cwbb@noindent \8% + % C/C++ tokens + \CwebRel \?% + \CwebAddress \AND + \CwebComplement \CM + \CwebScope \DC + \CwebEquiv \E + \CwebGe \G + \CwebRightShift \GG + \CwebNe \I + \CwebAssign \K + \CwebLeftShift \LL + \CwebMod \MOD + \CwebNull \NULL + \CwebNot \R + \CwebBinOr \OR + \CwebMemberRef \PA + \CwebThis \this + \CwebOr \V + \CwebAnd \W + \CwebXor \XOR + \CwebLe \Z + \CwebPointer \MG + \CwebPointerMemberRef \MGA + \CwebDecr \MM + \CwebIncr \PP + % more tokens + \CwebId \\% + \CwebIdLetter \|% + \CwebRes \&% + \CwebString \.% %% ( ...Emacs... + \CwebStringBreak \)% + \CwebNumber \T + \CwebCombinedOp \MRL + % goes to TeX state + \CwebComment \C + \CwebCxxComment \SHC + \CwebRefName \X + % CWEB tokens + \CwebMacrosHere \ATH + \CwebDefine \D + \cwbb@format \F + \CwebIdCat \J + \CwebVerbString \vb + % cross reference tags + \cwbb@change_flag \*% + \CwebCRAlso \A + \CwebCRsAlso \As + \CwebCRCite \Q + \CwebCRsCite \Qs + \CwebCRUse \U + \CwebCRsUse \Us + \CwebCREt \ET + \CwebCRsEt \ETs + % finish the list + \stop\stop + \def\cwbb@user_bindings{% + \cwbb@restore_bindings + \let\cwbb@user_bindings\relax + }% + \fi + } +\endprog + + +\sect Since most of the \cweave{} bindings are simple and tedious +coding, we'll have a look at the program layout next. Between two +paragraphs there must not be any skip, the skip used in document +layout is saved in |\cwbb@save@parskip|. A few other layout +parameters from the document layout must be saved as well. + +\beginprog +\newskip\cwbb@save@parskip +\newskip\cwbb@save@rightskip +\newcount\cwbb@save@sem_sfcode +\newcount\cwbb@save@pretolerance +\newcount\cwbb@save@hyphenpenalty +\newcount\cwbb@save@exhyphenpenalty + +\def\cwbb@save_doc_layout{% + \cwbb@save@parskip\parskip + \cwbb@save@rightskip\rightskip + \cwbb@save@sem_sfcode\sfcode`\; + \cwbb@save@pretolerance\pretolerance + \cwbb@save@hyphenpenalty\hyphenpenalty + \cwbb@save@exhyphenpenalty\exhyphenpenalty + } +\def\cwbb@restore_doc_layout{% + \parskip\cwbb@save@parskip + \rightskip\cwbb@save@rightskip + \sfcode`\;=\cwbb@save@sem_sfcode + \pretolerance\cwbb@save@pretolerance + \hyphenpenalty\cwbb@save@hyphenpenalty + \exhyphenpenalty\cwbb@save@exhyphenpenalty + } +\endprog + + +\sect When |\cwbb@program_layout| is called for the very first time +we have to set up some variables. This cannot be done in advance +since they depend on values which might be changed by the user in the +preamble. This setup is done in |\cwbb@layout_init|. + +If the program layout is already active, we must not switch it on +another time. This can be tested by the current binding of +|\cwbb@doc_layout|. + +\beginprog +\def\cwbb@program_layout{% + \ifx \cwbb@doc_layout\relax + \cwbb@layout_init + \cwbb@save_doc_layout + \def\cwbb@doc_layout{% + \cwbb@restore_doc_layout + \let\cwbb@doc_layout\relax + }% + % set new values + \parskip\z@skip + \rightskip\z@ plus 100\p@ minus 10\p@ + \sfcode`\;=3000 + \pretolerance\@M + \hyphenpenalty 1000 % strings can be broken this way + \exhyphenpenalty\@M + \fi + } +\endprog + + +\sect The unit of the basic indentation is stored in +|\CwebIndentUnit|. Continuation lines are indented two units further, +i.e., the initial hanging indentation is 3~units. The current hanging +indentation is kept in |\cwbb@indent|. + +We need undiscardable items which can be used as backspaces, of one +and two units, respectively. This is done best by boxes. The +initialization of the boxes must be postponed until the user had the +chance to change |\CwebIndentUnit|, it's done in the program state +initialization. + +\beginprog +\newdimen\CwebIndentUnit + \CwebIndentUnit=1em +\newdimen\cwbb@indent + +\newbox\cwbb@bak % backspace one unit +\newbox\cwbb@bakk % backspace two units + +\def\cwbb@layout_init{% + \global\setbox\cwbb@bak \hbox to -1\CwebIndentUnit{}% + \global\setbox\cwbb@bakk \hbox to -2\CwebIndentUnit{}% + \global\let\cwbb@layout_init\relax + } +\endprog + + +\sect Now we can formulate how to start typesetting program pieces: We +switch to program state, set the initial indentation, and add the +basic indentation of the first code line. Then we might add a marker +to this program part; for hierarchic structure we want to typeset the +chunk number in the margin of the chunk's program part. That's not +really possible, 'though: definitions and format requests are also +introduced with |\B|, so the chunk number will happen to be at the +start of the definition part if one exists. + +If the code line is the very first text to be typeset in this chunk, +we don't add the basic indentation---we're already indented from the +run-in chunk start marker. But we must not start our chunk with +|\noindent|, the marker would be typeset in the left margin then. (I +consider this as a \LaTeX{} error.) So we just emulate an empty +documentation part, the marker is now set correctly. |\B| can test for +this case: |@noskipsec| is still true then. + +\beginprog +\def\B{% + \cwbb@program + \cwbb@indent 3\CwebIndentUnit \hangindent\cwbb@indent + \ifvmode + \if@noskipsec + \indent % add an empty documentation part + \else + \noindent \kern\CwebIndentUnit + \fi + \fi + \CwebNumberProgramPart + } +\endprog + + +\sect The chunk number shall be added at the first program part. We +have a hook in the chunk start where we can set up +|\CwebNumberProgramPart|. It will redefine itself at first call, to +disable further output on more |\B| occurences in a chunk. + +The chunk number should always be in the left margin. If it's in the +right margin, there would be too much horizontal space between the +code start and the actual number. (The first code line is typically +not very long.) \LaTeX{} does not allow to select the margin for +marginpars, therefore we have to typeset the marginal note `by hand'. +As we know that we're in horizontal mode when we're called, |\vadjust| +is used to create the note. The standard \LaTeX{} dimen register for +the distance between marginal notes and text matter is used, of +course. + +Note that marginal notes may overwrite the chunk number. As it's very +unlikely that somebody issues marginal notes in program mode (that's +quite difficult and involves ingenious usage of the implementation of +this macros), I won't care for that case. + +\begin{fixme} + The baseline of the marginal note shall be aligned to the baseline + of the preceding line. That does not happen by default. Currently, I + assume that the preceding line has a depth of appropriately the + depth of a~`g'. Experiments showed that this gives good results for + most \cweb{} documents. But nevertheless one should determine the + exact depth of the preceding line, to know how much |box0| should be + raised. If anybody knows how this can be done, please tell me. (I + know about the route over the output routine, implementing an own + marginal note category, but this seems too much effort.) +\end{fixme} + +For flat structure, we don't add any program part marker and we +don't need to initialize it. + +\beginprog +\ifcase \cweb@structure + %% hierarchic + \def\cwbb@marginal_chunkno{% + \vadjust{% + \setbox\z@ \hbox to \z@{% + \hss \vphantom{g}% + \small \thechunk + \hskip \marginparsep + }% + \vbox to \z@{% + \hsize\z@ + \vss + \noindent \raise \dp\z@ \box\z@ + }% + }% + } + \def\cwbb@init_print_chunk{% + \def\CwebNumberProgramPart{% + \cwbb@marginal_chunkno + \let\CwebNumberProgramPart\relax + }% + } + \or + %% flat + \let\cwbb@init_print_chunk\relax + \let\CwebNumberProgramPart\relax +\fi +\endprog + + +\sect If a statement is finished, a new paragraph with the basic +indentation has to be started. + +An optional statement break is implemented by a low penalty which +will be selected if the line has to be broken. We assume that the +hanging indentation of the new line is already set correctly, and +have to backup two units to get the basic indentation. It might be +that the line break is not chosen by \TeX{}, we compensate the +backspace for this case. This compensation is discarded at the start +of a new line. + +\beginprog +\def\cwbb@break{% % forced break, between statements + \ifmmode\else + \endgraf % in LaTeX it isn't sure what \par is really... + \noindent + \hangindent\cwbb@indent \kern\cwbb@indent + \copy\cwbb@bakk % go back to basic indentation + \ignorespaces + \fi + } +\def\cwbb@opt_break{% % optional break between statements + \hfil \penalty\m@ne + \hfilneg \kern .5em \kern 2\CwebIndentUnit % discarded on line break + \copy\cwbb@bakk + \ignorespaces + } +\def\cwbb@big_break{% % forced break and a little extra space + \Y + \cwbb@break + } +\def\cwbb@expr_break#1{% % break with penalty #1 * 10 + \hfil \penalty#10 + \hfilneg % discarded on line break + } +\endprog + + +\sect When we increment the indentation, we must not forget to set +the hanging indentation immediately since |\cwbb@opt_break| relies on +the new value. If a continuation line is needed it will also be +indented one unit more, which is ok since it should be distinguishable +from the next line. +% +\begin{fixme} + Shouldn't the hanging indentation be set anew at the end of + |\cwbb@decr_indent| as well? +\end{fixme} + +\beginprog +\def\cwbb@incr_indent{% + \global\advance\cwbb@indent\CwebIndentUnit + \hangindent\cwbb@indent + } +\def\cwbb@decr_indent{\global\advance\cwbb@indent -\CwebIndentUnit} +\def\cwbb@backup{\copy\cwbb@bak} +\def\cwbb@noindent{% % no indentation + \hskip -\cwbb@indent \hskip 2\CwebIndentUnit + } +\endprog + + + + +\chap Program (C or \C++) tokens. + +Since the user might want to change the (somewhat unusual) way some +of the operators are typeset, we supply names for them. + +\beginprog +\let\CwebAnd=\land % logical and, && +\let\CwebEquiv=\equiv % equiv sign, for == +\let\CwebGe=\ge % greater or equal +\let\CwebLe=\le % less or equal +\let\CwebNe=\ne % unequal, != +\let\CwebNull=\Lambda % NULL pointer +\let\CwebNot=\lnot % logical not, ! +\let\CwebOr=\lor % logical or, || +\let\CwebXor=\oplus % bitwise exclusive or, ^ +\endprog + + +\sect Some symbols have to be shifted around, to save computation time +we put them in boxes. + +\begin{fixme} + It's not sure if the following symbols still look good in other font + families than Computer Modern. The movements might need to get + adapted when more experience is available. They were chosen from + Plain \cweb{}, where these were explicit movements measured in + points. I changed the dimension to quads, to achieve at least the + support for different sizes in the Computer Modern family. +\end{fixme} + +\TeX{}nical note: The pointer symbol must not be declared as a math +symbol (e.g., with |\DeclareMathSymbol|). Then \TeX{} would insert an +italic correction behind it, according to rule~17 from appendix~G. +(Please send email if you know of an easy way to prevent that +addition.) So I use the symbol as an accent, but then I have to supply +a nucleus for this math list. That nucleus also determines the total +width of this construct. As the vector accent has a width of +approximately 5\,pt in |cmmi10|, I'm going to use 0.5\,em. (That +heuristic is as good as any other I can think of.) + +\beginprog +%% pointer to struct component (`->'), use symbol of \vec accent +\newbox\cwbb@pointer +\setbox\cwbb@pointer=\hbox{% + \kern -.2em + \lower .3em \hbox{$\vec{\kern .5em}$}% + \kern .1em + } + +\newbox\cwbb@decr % decrement, -- +\setbox\cwbb@decr=\hbox{% + \kern .05em + \raise .1em \hbox{$\scriptstyle {-}\kern -.1em{-}$}% + \kern .05em + } +\newbox\cwbb@incr % increment, ++ +\setbox\cwbb@incr=\hbox{% + \kern .05em + \raise .1em \hbox{$\scriptstyle {+}\kern -.1em{+}$}% + \kern .05em + } +\endprog + + +\sect Although the following symbols are typeset like an ``ordinary +\C++ programmer'' would expect them, we provide own module names +nevertheless. They can now be changed as well, i.e., orthogonality is +enhanced. (And we can use |\cwbb@rebind| for assigning them to their +names while we switch to program state\,\dots). + +Note: The comment at |\CwebMod| says ``modulo/remainder'', as this is +not defined by the C standard, i.e., implementation-dependent. + +\beginprog +\mathchardef\CwebAddress="2026 % `&', as binary op +\let\CwebAssign== % assignment +\let\CwebBinOr=\mid % binary or +\def\CwebComplement{{\sim}} % `~', as ordinary symbol +\def\CwebDecr{\copy\cwbb@decr} % decrement +\def\CwebIncr{\copy\cwbb@incr} % increment +\let\CwebLeftShift=\ll % left shift, << +\def\CwebMod{\mathbin{\hbox{\footnotesize\rm\%}}} % modulo/remainder, % +\def\CwebMemberRef{\mathbin{.*}} % ptr to member (on object) +\def\CwebPointer{\copy\cwbb@pointer} +\def\CwebPointerMemberRef{\mathbin{\CwebPointer*}} % ptr to member (on ptr) +\def\CwebRel{\mathrel?} % relation operator +\let\CwebRightShift=\gg % right shift, >> +\def\CwebScope{\kern.1em{::}\kern.1em} % scope resolution + +\def\CwebThis{\CwebRes{this}} % reserved identifier `this' +\endprog + + +\sect The special identifier |\TeX| remains. In math mode it shall be +the identifier, in other modes the usual logo. We use the definition +supplied by DEK (or \textsc{Silvio Levy}?)\ from Plain \cweb{}. + +\beginprog +\def\TeX{% + {% + \ifmmode\it\fi + \mbox{T\kern-.1667em\lower.424ex\hbox{E}\hskip-.125emX}% + }} +\endprog + + +\sect Some tokens don't have constant names, the name is supplied as +the argument. + +Identifiers are typeset in italics, reserved words and type names in +boldface, and strings in typewriter. For an underscore in the bold +words we use a line that's 50\,\% thicker as the usual line thickness. +-- But what is the usual line thickness. As Knuth uses 0.4\,pt for a +10\,pt Computer Modern font, we'll use 0.06\,em for a CM font in an +arbitrary size. If that line thickness is still OK for other fonts is +doubtful, as it should fit to the stem width. (CM is a rather light +font, after all.) But since there is no font dimension that gives a +hint to an appropriate line thickness, it's our best try. + +\beginprog +\def\CwebCombinedOp#1{\mathrel{\let\K==#1}} % e.g., += operator +\def\CwebId#1{\hbox{\it#1\/\kern.05em}} % identifier, more than one char +\def\CwebIdLetter#1{\hbox{$#1$}} % identifier, one letter +\def\CwebRes#1{% % reserverd words and type names + \hbox{\bf + \def\_{\kern.04em\vbox{\hrule width.3em height.06em}\kern.08em}% + #1\/\kern .05em + }% + } +\endprog + + +\sect In Plain \cweb{} strings are typeset in the font |cmtex10|, +which is a typewriter font with extended ASCII characters. This font +does not have the usual accents and can therefore not used for +typesetting national characters. (Very often they are input in some +8-bit encoding, the respective character code is made active and is +substituted by a cseq which expands to the correct glyph. Of course, +there are better ways, but that's the reality we have to cope with.) +Instead of this special font we use the standard typewriter font. +This has the further advantage that |cmtex10| may not be introduced +to NFSS\@. + +\beginprog +\def\CwebString{% + \hbox \bgroup + \tt + \cwbb@string_setup + \cwbb@string + } +\def\cwbb@string#1{% + #1\kern .05em + \egroup + } +\endprog + + +\sect Within strings certain cseqs have a special meaning; this is +introduced by |\cwbb@string_setup|. The cseqs within strings are +mostly special \TeX{} characters that are to be typeset by cseqs with +the same name. + +But a problem remains: active characters. They will still expand, and +will mess up the string visualization. This is a particular problem +with |german.sty| where the double quote is active. (Of course, that's +a problem -- I'm German. :--) When one typesets strings, a double +quote shall be typeset as double quotes, and must not expand to the +special meaning. Remember that double quotes happen to appear quite +often in strings. As the string argument is already tokenized, one has +to redefine the binding of $(\textit{\textup{symbol}}\ \textbf{.}\ +|#\"|)$. + +\begin{fixme} + Perhaps one might use a loop over all characters except the braces, + and set their catcode to other. That would give us enough security. + + For now, we handle only the double quote. +\end{fixme} + +Every once in a while we have discretionary breaks in a string, +denoted by |\CwebStringBreak|. This break is shown with the C +convention of escaped newlines. + +\beginprog +\def\cwbb@string_setup{% + \chardef\ =`\ % % <-- two spaces ! + \chardef\&=`\& + \chardef\\=`\\ + \chardef\^=`\^ + \chardef\_=`\_ + \chardef\{=`\{ + \chardef\}=`\} + \chardef\~=`\~ + \catcode`\"=\CatOther + } + +\def\CwebStringBreak{\discretionary{\hbox{\tt\char`\\}}{}{}} +\endprog + + +\sect Numbers are typeset in different ways. We use the definition of +Plain \cweb{}. +% +\begin{fixme} + Should add a specification of the possible input and an explanation + of the macros below. In particular, that the closing brace after + |\aftergroup| is used much later is probably not grokked by most + \TeX{} programmers. +\end{fixme} + +\beginprog +\def\cwbb@oct{\hbox{$^\circ$\kern-.1em\it\aftergroup\?\aftergroup}} +\def\cwbb@hex{\hbox{$^{\scriptscriptstyle\#}$\tt\aftergroup}} + +\def\CwebNumber#1{% % octal, hex, or decimal constant + \hbox{% + $% + \def\?{\kern.2em}% + \def\$##1{\egroup\sb{\,\rm##1}\bgroup}% suffix to constant + \def\_{\cdot 10^{\aftergroup}}% power of ten (via dirty trick) + \let\~\cwbb@oct \let\^\cwbb@hex + {#1}% + $}% + } +\endprog + + +\sect Comments are typeset in \TeX{} state. We add a hook, the user +shall be able to change the layout (e.g., he might want another font). +% +\begin{fixme} + Currently \C++ comments are typeset like C comments. This is + horrible in usual circumstances, i.e., when complete blocks of text + are prefixed with |//|. We should simply catenate all these text and + typeset it as one paragraph, each line prefixed by |//|. But then we + have to implement an |\everyline| first, and since that's not so + easy we postpone it\,\dots +\end{fixme} +% +In front of a C comment there is an optional stmt break, with 2\,quad +in front if the line is not broken and 1.5\,quad if the line is broken. + +\beginprog +\def\CwebComment#1{% + \5% % 0.5em will be discarded on line break + \hskip 1.5em + $/\ast\,$% + {\cwbb@tex + \CwebCommentHook + #1% + }% + $\,\ast/$% + } +\let\CwebCommentHook\relax +\let\CwebCxxComment\CwebComment +\endprog + + + + + +\chap \cweb{} tokens. + +We distinguish three categories of \cweb{} tokens: (1) Those which +output constant text, (2) those which have attributes to be displayed +in a special way, and (3) those which start a new structure element, +namely |@d| and~|@f|. Let's consider them in this order. + + +\sect \cweb{} tokens which expand in a constant string are the +identifier catenation operator~(`|@&|') and the macro placement +directive~(`|@h|'). + +\beginprog +\def\CwebIdCat{\CwebString{@\&}} +\def\CwebMacrosHere{% + \begingroup + \def\CwebRefNumber##1{}% + \CwebRefName :Preprocessor definitions\X + \endgroup + } +\endprog + + +\sect Verbatim program strings, i.e., strings passed verbatim by +\ctangle{}~(`|@=|') are typeset like normal strings, but within a box. +We use 2\,pt as the separating distance, this is set locally. + +\beginprog +\def\CwebVerbString#1{{\fboxsep\tw@\p@ \fbox{\CwebString{#1}}}} +\endprog + + +\sect The refinement names are typeset in angles, this has a long +tradition. We burry the typesetting of the chunk number (which is +the first parameter) in a macro call; the user may change this to +achieve special effects. +% +\begin{fixme} + One could think about handling special values of the chunk numbers + differently. E.g., an empty argument is not typeset at all, a~0 + triggers a marginal note about a missing definition, etc. +\end{fixme} + +A refinement name may be typeset both in math and horizontal mode. +The name itself is typeset in horizontal mode, of course; for the +angles we need math mode. Therefore we assert at the start of the +macro that we're not in math mode any more. At the end we switch back +to math mode if we've started in it. This conditional switch from and +back to math mode is done by |\cwbb@toggle_text|. + +\TeX{}nical note: If we're in math mode |\cwbb@toggle_text| must be +defined globally, as it will turn off math mode and the definition +would be un-made then. The second invocation of |\cwbb@toggle_text| +would be undefined then. + +A refinement may also consist of the file name the expansion of this +refinement shall be written to. +% +\label{sec:refname-dot} +% +This file name is tagged with |\.|, it shall be typeset like a string. +But the user shall be able to use the dot accent in the refinement +name as well. We check if the text consists solely of the tag and its +argument; in this case we substitute |\.| with |\CwebString|. +Otherwise we leave it as it is. Then a refinement name may not +consist of a single dot-accented expression---well, that's highly +unlikely. (Nevertheless I'll document it in the user's manual\,\dots) + +\begin{fixme} + One should be able to use |\EnsureMath| here. But the refinement + name must not be set in math mode and must not be set in an hbox; + the latter would prevent line breaks. +\end{fixme} + +\beginprog +\def\CwebRefName#1:#2\X{% + \ifmmode \gdef\cwbb@toggle_text{\null$\null}% + \else \let\cwbb@toggle_text\relax + \fi + \cwbb@toggle_text + $\langle\,${\cwbb@tex \cwbb@check_dot{#2}\CwebRefNumber{#1}}$\,\rangle$% + \cwbb@toggle_text + } +\def\CwebRefNumber#1{% + {\reset@font \footnotesize \kern .5em#1}% + } +\endprog + + +\sect The next macro, |\cwbb@check_dot| is a hassle to implement. We +must check if it's argument consists solely of a `|\.|'~tag, together +with the argument to this tag. Then the `|\.|'-argument shall be +typeset like a string, |\.| itself must be ignored. + +The check for |\.| must not evaluate the parameter. Especially |\PB| +must not be evaluated within, it would lead to havoc with the +redefinition of all bindings, etc. (At least that's the empirical +result---it happened; although I don't know where the problems are. +Anyhow, it wasn't in the specs of the rebinding process.) All other +cseqs which shouldn't be used in moving arguments may cause problems +here, too. Note that |\protect| is no solution here, the user often is +not aware of the presence of \cweave{}-generated tags. As an example, +consider the refinement \verb"@< local variables of |foo| @>|" which +will lead to a call with the argument `|local variables of \PB{\\{foo}}|'. +|\\| must not be evaluated here. + +I use an approach where I hope that it will work---but to be honest, +I'm not sure. I want to define a macro |\next| which shall have an +empty expansion iff |#1| was a `|\.|'~tag with its argument. Empty +refinement names are not allowed so we can assume that |#1| consists +of at least one token. I evaluate the first token of |#1| before the +|\def| is done. With an appropriate binding a |\.| will disappear, +perhaps leaving an empty token list. I also take care that |\PB| is +not evaluated then, by temporary rebinding it to |\relax|. Thereby I +have taken care for all cseqs \cweave{} might have introduced at the +very front of |#1|. Other cseqs are user-tags. If they cause +problems, the user might circumstance them by adding |\protect|. + +\beginprog +\def\cwbb@check_dot#1{% + \begingroup + \let\.\@gobble + \let\PB\relax + \expandafter\def \expandafter\next \expandafter{#1}% + \ifx \next\empty + \gdef\next##1{\CwebString}% + \else + \global\let\next\relax + \fi + \endgroup + \next #1% + } +\endprog + + +\sect \cweb{} macro definitions (done by~|@d|) and format directives are +basically program text. When they are started we are already in +program state, i.e., |\B| has appeared in front of it. But since we have +an introductionary identifier (either |#define| or |format|) to set at +the very front we increase the indentation by three units. + +The output of format directives may be suppressed. Then we have to +gather both identifiers that will appear after |\F|. Both of them +consist of one group-token (a cseq and the identifier name), after +each identifier one other token separates them. I.e., we have to +gobble six group-tokens. As the very last token is |\par| if a format +directive follows directly on another one, the definition must be +long. + +\TeX{}nical note: |\cwbb@format| must expand to |\CwebFormat|, not to +its expansion. Otherwise a redefinition of |\CwebFormat| in a package +would not be used. + +\beginprog +\def\CwebDefine{\cwbb@macro{\#define}} +\def\CwebFormat{\cwbb@macro{format}} +\if@cweb@suppress@format@ + \long\def\cwbb@format#1#2#3#4#5#6{} +\else + \def\cwbb@format{\CwebFormat} +\fi + +\def\cwbb@macro#1{% + \global\advance\cwbb@indent \tw@\CwebIndentUnit + \cwbb@incr_indent + \CwebRes{#1 }% % <-- blank! + } +\endprog + + + + +\chap Refinement cross references and changes. + +At the end of chunks with refinements, \cweave{} may output cross +reference information: In which chunks additional definitions for +this refinement are found, where this refinement is used, and where it +is cited. This cross reference information is always introduced by a +tag followed by a non-empty list of chunk numbers. Different tags +are used for lists with only one element and for lists with more than +one element, this way the introductionary text may be adapted. + +Within a list of $n$~chunk numbers the first $n-1$~numbers are +separated by commas with one following blank. The last two numbers +are separated by |\ET| if~$n=2$, and by |\ETs| if~$n>2$. If a chunk +is changed by the changefile, a changeflag~(`|\*|') is appended to +its number. The list is eventually terminated by a full stop. + + +\sect We separate the cross reference information by a smallskip from +the refinement or from a previous cross reference information. The +information itself is typeset in a smaller font, as it is auxilliary, +inserted stuff. The number list has a hanging indentation of +|\CwebNumberListHangindent|. But beware: This isn't a dimension +register, it's a macro. This way one can use ems as dimensions. + +The actual size change is represented by a macro. We will redefine it +when we need an other size, e.g., in the lists at the end of the +document. + +We must assert that we're in CR state while we set a cross reference. + +The first parameter of a cross reference information unit is the +introductionary text, the second is the number list. The parameters +must be evaluated in a group---local parameter changes therein must +not influence the environment. + +\beginprog +\def\CwebNumberListHangindent{2em} +\let\CwebCRSize\footnotesize +\def\CwebCrossRef#1#2.{% + \par\smallskip + \cwbb@CR + \begingroup + \reset@font \CwebCRSize + \noindent \hangindent\CwebNumberListHangindent\relax + #1~#2.\par + \endgroup + } +\endprog + + +\sect Well, let's define all introducing tags, which in fact start the +cross reference information unit. The number list is gathered by +|\CwebCrossRef|. + +\beginprog +\def\CwebCRAlso{\CwebCrossRef{See also chunk}} +\def\CwebCRsAlso{\CwebCrossRef{See also chunks}} + +\def\CwebCRCite{\CwebCrossRef{This code is cited in chunk}} +\def\CwebCRsCite{\CwebCrossRef{This code is cited in chunks}} + +\def\CwebCRUse{\CwebCrossRef{This code is used in chunk}} +\def\CwebCRsUse{\CwebCrossRef{This code is used in chunks}} + +\def\CwebCREt{ and~} +\def\CwebCRsEt{, and~} +\endprog + + + + +\chap Bells and whistles. + +\begin{fixme} + Just copied from Plain \cweb{}. It doesn't work + anyhow---|\char"|\<xy> usually doesn't typeset the correct + character. That's because this character is most probably an active + character; at least that's typical for the way \TeX{} systems are + used in Europe. I have to think about the implementation. +\end{fixme} + +\beginprog +\def\ATL{\par\noindent\bgroup\catcode`\_=12 \postATL} % print @l in limbo +\def\postATL#1 #2 {\bf letter \\{\uppercase{\char"#1}} + tangles as \tentex "#2"\egroup\par} +\def\noATL#1 #2 {} +\def\noatl{\let\ATL=\noATL} % suppress output from @l +\endprog + + + +\chap The end. + +Well, after all we're finished with this module + +\beginprog +\endinput +\endprog + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\vskip \PltxPreSectSkip + +\rcsLogIntro{After the actual revision log of this module, we give an + extract of log messages of the \cls{cweb} class. This module was + extracted from revision~2.8 of that class, we present to you the + log entries that concern the code of the new module.} + +\begin{rcslog} +$StyleLog: cwebbase.doc,v $ +\Revision 1.4 1995/11/07 17:55:19 schrod + \LaTeX{} \cweb{} should work at least with the last two \LaTeX{} +versions; make it work with the previous-to-last one, version +\mbox{$\langle$1994/12/01$\rangle$}. For that, one has to install the +\mbox{$\langle$1995/06/01$\rangle$} (non-outer) definition of +|\newif|, and |\hb@xt@| must not be used.\\ +Problem reported by Laurent Desnogues +\path|<laurent.desnogues@aiguemarine.unice.fr>| and somebody else (XXX +-- add name). + +\Revision 1.3 1995/11/07 14:13:12 schrod +Reset section numbers when higher-level section begins.\\ +Error reported by Bronne Louis \path|<bronne@montefiore.ulg.ac.be>|. + +\Revision 1.2 1995/11/06 10:58:47 schrod + Support active double quotes in strings. That happens when +|german.sty| is used. Problems with other active characters may still +appear. + +\Revision 1.1 1995/09/12 23:02:22 schrod +Moved all code that does the actual typesetting of \cweave{} tags and +is therefore also needed for a |cweb| environment. It's now an own +module named \pkg{cwebbase}. + +Chunk markers and chunk marginal numbers don't hang below the +baseline any more. + + +\item[] \noindent\hrulefill\break + \textbf{Extract of the revision log for |cweb.doc|:} + + \vskip 2ex + +\Revision 2.5 1995/08/29 02:07:26 schrod +Discard dependencies on 10\,pt fonts. + +Support suppression of format directives. + +\Revision 2.4 1995/08/27 19:31:43 schrod +Make configuration of change flag easier. + +Put section title of changed chunks list in marks, and tell the user +that it got typeset. + +\Revision 2.3 1995/08/27 17:24:46 schrod +Make usage of baseclass with chapters work. + +\Revision 2.2 1995/08/27 13:26:22 schrod +Add possibility to suppress change hints. + +\Revision 2.1 1995/08/25 19:11:18 schrod +Hierarchic structures are supported now, in addition to the flat +structure of the beta-test version. One can choose with an option. For +that step, the terminology was cleaned up, too: Chunks are not named +sections any more. (That change involved reimplementation of almost +all the structure and toc stuff.) + +The chunk number supplied by \cweave{} is used now, not some computed +number. Change flags are printed, too. + +One can suppress output of unchanged sections. + +\Revision 1.12 1993/08/10 14:15:43 schrod +New page on main section only if group level $<$ |\cwebSecNoEject|. +Default for the latter is 3. + +\Revision 1.11 1993/08/10 11:21:07 schrod +Reference to section number does not render a period after the +number any more. + +\Revision 1.10 1993/08/09 20:08:20 schrod +|\cweb@cweave_bindings| is now a no-op if \cweave{} bindings are in +effect already.\\ +(Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +\Revision 1.9 1993/08/09 18:05:28 schrod +Left shift operator wasn't defined correctly.\\ +(Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +\Revision 1.6 1993/06/15 08:49:23 schrod +|\cweb@check_dot| must not evaluate its argument in an |\edef|, this +causes problems if a |\PB| is within. Now I try hard not to evaluate any +tokens outside of my control. + +Can use |\@defpar| for an empty line in |\cweb@has_entries|, don't +need an own macro. + +\Revision 1.4 1993/06/14 15:54:18 schrod +Add FSA diagram about processing states. CR state is also switched +to from \TeX{} state (that happens with |\ch| at the document end). + +\Revision 1.3 1993/05/13 17:51:21 schrod +Refinements may also be filenames (`|@(|'). Then the complete name +consists of a |\.| macro call, which is handled now.\\ +(Problem reported by Michael M\"uller \path|<mimu@mpi-sb.mpg.de>|.) + +Made the detection of `|@.|' index entries more robust. + +\Revision 1.2 1993/05/12 18:28:59 schrod +Adapted to recent changes of \cweave{} (of April 93): + +Main sections have a group level, represented in the table of +contents. This changed the complete implementation of section tags. + +New C token cseqs: |\Z| and |\MRL|, implemented as |\CwebLe| and +|\CwebCombinedOp|. + +\Revision 1.1 1993/04/09 15:00:37 schrod +Initial revision + +\end{rcslog} + + + +\end{document} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Local Variables: +mode: LaTeX +TeX-brace-indent-level: 4 +indent-tabs-mode: t +TeX-auto-untabify: nil +TeX-auto-regexp-list: LaTeX-auto-regexp-list +compile-command: "make cwebbase.tex" +End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cwebparts.doc b/Master/texmf-dist/doc/latex/cweb-latex/src/cwebparts.doc new file mode 100644 index 00000000000..3eec51882b1 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cwebparts.doc @@ -0,0 +1,452 @@ +% $StyleId: cwebparts.doc,v 1.1 1995/09/16 17:01:59 schrod Exp $ +%---------------------------------------------------------------------- +% Written by Joachim Schrod <schrod@iti.informatik.th-darmstadt.de>. +% Copyright conditions see below. + +% +% LaTeX package cwebparts +% include parts of CWEB programs in LaTeX documents +% +% [LaTeX in MAKEPROG] +% (history at end) + +%% FIXME: The user manual is not in cwebparts-user.tex. Most probably +%% I'll make one user manual for the whole bundle; due to the usage of +%% cwebbase class and package have lots in common. +%% +%% % If you have received this style file without the user manual (in the +%% % file cwebparts-user.tex or the respective DVI file), it's incomplete and +%% % near to useless. If it was given to you as something that you shall +%% % use as an author -- complain bitterly to your provider. You need the +%% % documentation and you have a right on it! (Below you can find info +%% % where to get the reference version.) + + + + +\documentclass{progltx} + +\usepackage{cweb-doc} % document-specific markup +\usepackage{fullpage} + + +\RCS $StyleRevision: 1.1 $ +\RCS $StyleDate: 1995/09/16 17:01:59 $ + + +\begin{document} + + +\title{The \texttt{cwebparts} Package\\ + {\large (Implementation)}% + } +\author{% % LaTeX does not discard unnecessary glue... + Joachim Schrod% + \thanks{% + \protect\raggedright + TU~Darmstadt, Computer Science Department, WG Systems Programming, + Alexanderstr.~10, D-64283~Darmstadt, Germany. + Email: \texttt{schrod@iti.informatik.th-darmstadt.de}.% + }% + } +\date{% + Revision \RCSStyleRevision\\ + (as of \RCSStyleDate)% + } + +\maketitle + + +% doesn't work with progltx yet +%\tableofcontents + + + +\chap What's this style for?. + +This style supports inclusion of \cweb{} program parts in \LaTeX{} +documents. For that it provides the environment |cweb| where \cweave{} +output may be stuffed in. + +A more versatile explanation is available in the user manual of the +\cweb{} bundle; this package is part of that bundle. +% +\begin{fixme} + Read: ``should be available'' -- there is no bundle user manual + (yet). |cweb-user.tex| will be enhanced after first testing of this + code. +\end{fixme} + + +\sect The internal interface is also not described in this source, +refer to the configuration documentation for this bundle. +% +\begin{fixme} + Even worse: I don't even have written the internal specs for the + \cls{cweb} class, not to speak of this package. +\end{fixme} + + + + +\chap Implementation. + +Most of the implementation is made available by the module +\pkg{cwebbase}. We have to supply macros it demands from a user, and +have to deliver the |cweb| environment. + + +\sect This module reserves the namespace |cweb|. (This implies that it +cannot be used with the \cls{cweb} class. But you don't want to do +that anyhow. :--) + +\beginprog +\ifx \cweb@loaded\undefined + \def\cweb@loaded{$StyleRevision: 1.1 $} +\else + \PackageWarningNoLine{cwebparts}% + {Some other package already uses namespace `cweb'} +\fi +\endprog + + +\sect Let's identify this package. + +\noindent The code below is explained in the implementation +documentation of the |rcs| package. + +\beginprog +\begingroup + \def\RCSPackage#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesPackage{#1}[\date\space\id\space #2]% + } + + \RCSPackage{cwebparts}{include CWEB program parts in LaTeX documents} + $StyleDate: 1995/09/16 17:01:59 $: 9999/00/00 \endRCS + $StyleRevision: 1.1 $: 0.0 \endRCS +\endgroup +\endprog + + +\sect This module is supported. Send bug reports, comments and +repairs. + +The reference version may be retrieved via anonymous ftp from +|ftp.th-darmstadt.de| [130.83.47.112], directory |pub/tex/latex|. It's +placed there as a gzipped tar file. (The information on the IP~number +is dated September~13,~1995. +It might have changed, although this is very unlikely. Use your +friendly nameserver.) + + +\sect This is freely distributable 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 software is distributed in the hope that it will be useful, but +\textbf{without any warranty}; without even the implied warranty of +\textbf{merchantability} or \textbf{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 in +the file |License| along with this package; if not, write to the Free +Software Foundation, Inc., 675~Mass Ave, Cambridge, MA~02139,~USA. + + +\sect Before we start we declare some shorthands for category codes. +By declaring the underscore~`(|_|)' as letter we can use it in our +macros. (I agree with \textsc{D.~Knuth} that +|\identifier_several_words_long| is more readable than +|\IdentifierSeveralWordsLong| and in every case better than |\p@@@s|.) + +As this is a \LaTeX{} style file the at sign is a letter anyhow; so +we can use the ``private'' \LaTeX{} macros; and with the underscore we +can make our own macros more readable. But as we have to restore this +category code at the end of this macro file we store its former value +in the control sequence |\CatUsCode|. This method is better than to +use a group because not all macros have to be defined global this way. + +Since somebody might use more styles from me, this cseqs might be +defined already. + +\beginprog +\ifx \CatEscape\undefined + \chardef\CatEscape=0 + \chardef\CatOpen=1 + \chardef\CatClose=2 + \chardef\CatIgnore=9 + \chardef\CatLetter=11 + \chardef\CatOther=12 + \chardef\CatActive=13 % is defined in Plain already + + \chardef\CatUsCode=\catcode`\_ +\fi + +\catcode`\_=\CatLetter % top level macro file +\endprog + + + + +\chap Typesetting \cweave{} output. + +The module \pkg{cwebbase} handles that. It demands some cseqs to be +defined before it may be imported. +% +\begin{fixme} + These cseqs should actually be implemented as package options. Have + to extract the \pkg{keyvalx} code from the \cls{cweb} class first. + Now I fix the usage I need for our Literate Programming book. +\end{fixme} + +\begin{fixme} + The options should not only be available as package options, but + also on a per environment base. We might to typeset one part with + flat and another one with hierarchic structure. Or we might to + suppress format directives only in some parts, while other parts + feature them. But this needs a change in \pkg{cwebbase}, there code + is \emph{defined} depending on the cseqs below. It must be evaluated + differently to support the stuff below. OTOH, this will cost + performance -- is it worth it? +\end{fixme} + +\beginprog +\def\cweb@structure{0 } % hierarchic structure +\let\if@cweb@suppress@changehints@=\iffalse % no suppression whatsoever +\let\if@cweb@suppress@unchanged@=\iffalse +\let\if@cweb@suppress@format@=\iffalse + +\input{cwebbase} +\endprog + + +\sect Now we can typeset pieces of \cweave{} output -- in principle. +If these pieces have sections in them, they'll write entries to the +|TOC| file. These entries will either mess up the structure of the +document's table of contents or lead to \TeX{} error messages. That's +because either toc entries for section types |part|, |chapter|, or +|section| are written (causing the conflict); or toc entries for +section types |chunk| and `|section|$i$' are written (being +undefined). + +The best way seems to stop the included source to add anything to the +table of contents or to do any mark processing. For that, we provide a +macro |\CwebNoLists| that will locally redefine the \LaTeX{} cseqs +that cause such actions to happen. That macro will be used at the +start of the environment. + +\beginprog +\def\CwebNoLists{% + \let\addtocontents\@gobbletwo + \let\mark\@gobble +%% \let\markboth\@gobbletwo +%% \let\markright\@gobble + } +\endprog + + +\sect Furthermore, section divisions should not start a new page. +% +\begin{fixme} + Currently, sections in the included parts are typeset exactly the + same way as they're typeset in the main document. That should be + different -- but how do I change it in a general way? +\end{fixme} + +\beginprog +\let\CwebEjectSection\@gobble +\endprog + + +\sect OK, what needs to be done for the environment? We need to save +and restore counters that are changed globally by section commands. + +\beginprog +\ifx \chapter\undefined + \let\cweb@save_c@chapter\@gobble + \let\c@chapter\@gobble +\else + \newcount\cweb@save_c@chapter +\fi +\newcount\cweb@save_c@part +\newcount\cweb@save_c@section + +\def\cweb@save_for_env{% + %% save values changed globally by cwebbase macros + \cweb@save_c@chapter\c@chapter + \cweb@save_c@part\c@part + \cweb@save_c@section\c@section + \let\cweb@save_thechapter\thechapter + \let\cweb@save_thesection\thesection + %% set up typesetting of CWEB source + \@nobreaktrue % don't add space from first chunk + } +\def\cweb@restore_env{% + \global\c@chapter\cweb@save_c@chapter + \global\c@part\cweb@save_c@part + \global\c@section\cweb@save_c@section + \global\let\thechapter\cweb@save_thechapter + \global\let\thesection\cweb@save_thesection + } +\endprog + + +\sect For the moment, we use list spacing around a |cweb| environment. +\LaTeX{} supplies the |trivlist| environment for such purposes. + +But the environment content itself must not be typeset in a list +context. Two problems exist: There must be at least one |\item|, it +will actually add the vertical space and must therefore not be +discarded. And list environments redefine |\par|, but the +\pkg{cwebbase} macros need a more `normal' definition. + +An item label is stored by |\item| in the |\everypar| register. The +label is only typeset if |@inlabel| is true. The flag |@newlist| tells +most other \LaTeX{} macros, that there was no item yet; typically +they'll add an empty paragraph if necessary. As the content will +start with a \LaTeX{} section division, or even with document markup, +we don't want that empty paragraph and should skip the empty item +label. (Often enough, due to the initialisation of |\everypar| in +|\@startsection|, it will be thrown away anyhow). So we establish its +postconditions, the next macro won't notice that the item hasn't been +set actually. + +\begin{fixme} + Experimentally, we reduce the skip in front of a chunk to 1\,pc, + otherwise the distance between two chunks is far too wide compared + to other vertical distances in the text around the included stuff. +\end{fixme} + +\beginprog +\def\CwebBeginEnvLayout{% + %% use spacing of list, but switch off list handling afterwards + \trivlist + \@inlabelfalse % don't go in horizontal mode + \item\relax + \global\@newlistfalse + \global\@inlabelfalse\the\everypar + \@setpar{\@@par}% + \CwebChunkPreSkip 1pc plus 6pt minus 3pt + } +\let\CwebEndEnvLayout=\endtrivlist +\endprog + + +\sect The environment gets trivial now. We supply a hook for a whole +document and also environment-specific ones (as an optional +environment argument). + +\beginprog +\newenvironment{cweb}[1][]% + {% + \CwebBeginEnvLayout + \cweb@save_for_env + \CwebNoLists + \csname CwebEnvHook\endcsname + #1 + }{% + \CwebEndEnvLayout + } +\endprog + + +\sect An a convenience tag to include a complete \cweave{} file. Since +we want to test the typesetting of our included \cweb{} program alone, +we allow but ignore most kinds of document markup. Many of them have +two arguments, one is optional. + +In the preambel, only |\documentclass| and |\usepackage| may appear. +Titlepage material is handled, table of contents is discarded. The +document environment does nothing, i.e., unlike the \cls{cweb} class, +material behind |\end{document}| is not ignored. + +An |\end| tag is inserted by \cweave{} and must be redefined, we don't +end an environment there. We'll open a group and will use that tag to +close it again, as we know that we'll have reached the end of our +\cweb{} file. Of course, |\end| must not be redefined during +processing the actual program source -- environments are valid there. +The redefinition is best be triggered by material inserted from +\cweave{} at the very end, e.g., from |\inx|. But |\inx| may not be +there (when \cweave{} is called with the `|-x|' option), we'll use +|\enddocument| to add a |\inx| tag for safety reason. If the user +didn't add an |\end{document}| to his file and used `|-x|', we're +going to loose. + +\TeX{}nical note: |\document| must not have the same binding as +|\relax|, as this would be interpreted as a non-existing environment +by \LaTeX{}. (That's due to the |\csname| lossage.) + +\TeX{}nical note: Evaluating |\inx| in |\enddocument| will not have +any effect, we're inside a group. That evaluation must be postponed +after the group has been closed. + +\beginprog +\newcommand\cweb@doc_markup_gobble[2][]{} +\newcommand*\cwebInput[1]{% + \begin{cweb} + [% + \begingroup + \let\documentclass\cweb@doc_markup_gobble + \let\usepackage\cweb@doc_markup_gobble + \let\title\@gobble + \let\author\@gobble + \let\date\@gobble + \let\maketitle\relax + \let\tableofcontents\relax + \let\document\empty + \def\inx{\let\end\endgroup}% + \let\fin\relax + \let\con\relax + \def\enddocument{\aftergroup\inx}% + ]% + \input{#1}% + \end{cweb}% + } +\endprog + + + + +\chap The end. + +Well, after all we're finished with this style. We must not forget to +restore the underscore catcode. + +\beginprog +\catcode`\_=\CatUsCode + +\endinput +\endprog + + +%\sect I would like to thank those who helped me to improve this style. +% In particular, XXX provided XXXsubstantial parts of the code. + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\begin{rcslog} +$StyleLog: cwebparts.doc,v $ +\Revision 1.1 1995/09/16 17:01:59 schrod +Add support for inclusion of \cweb{} files in \LaTeX{} documents. + +\end{rcslog} + + + +\end{document} + + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +Local Variables: +mode: LaTeX +TeX-brace-indent-level: 4 +indent-tabs-mode: t +TeX-auto-untabify: nil +TeX-auto-regexp-list: LaTeX-auto-regexp-list +compile-command: "make cwebparts.sty" +End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cwebx.sty b/Master/texmf-dist/doc/latex/cweb-latex/src/cwebx.sty new file mode 100644 index 00000000000..d20db59b171 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cwebx.sty @@ -0,0 +1,406 @@ +% $Id: cwebx.sty,v 3.1 1995/11/21 00:42:49 schrod Exp $ +%---------------------------------------------------------------------- + +% +% LaTeX2e package cwebx +% extra stuff for cweb bundle, to be added there sometimes +% +% [LaTeX2e] +% (history at end) + + +% Identification. The code below is explained in the implementation +% documentation of the rcs package. + +\begingroup + \def\RCSPackage#1#2 $#3: #4 #5\endRCS $#6: #7 #8\endRCS{% + \def\date{#4}\def\id{v#7}% + \ProvidesPackage{#1}[\date\space\id\space #2]% + } + + \RCSPackage{cwebx}{extra stuff for cweb bundle} + $Date: 1995/11/21 00:42:49 $: 9999/00/00 \endRCS + $Revision: 3.1 $: 0.0 \endRCS +\endgroup + + +% +% What's this package for? +% +% Additional macros for cweb.cls or cwebpart.sty, to be added there +% sometimes. +% + + +% requires that cweb base is loaded +\ifx \cwbb@loaded\undefined + \PackageError{cwebx}{cweb base is not loaded} + {This package requires the usage of either cweb.cls or + cwebparts.sty.} +\fi + + +% This style is supported. Send bug reports, comments and repairs. +% +% The reference version may be retrieved via anonymous ftp from +% |ftp.th-darmstadt.de| [130.83.47.112], directory |pub/tex/latex|. It's +% placed there as a gzipped tar file. (The information on the +% IP~number is dated 27 Sep 95. It might have changed, also +% this is very unlikely. Use your friendly nameserver.) + + + +\catcode`\_=\CatLetter + + + +%%% ====================================================================== + + +%% +%% Errors in cwebbase.doc +%% + + +% As \4 follows \B always, the \kern\CwebIndentUnit to neutralize that +% backspace must be made after run-in section, too. Between the chunk +% marker and the program code start is 1em then (inserted by LaTeX +% section start). + +% FIXME: \4 does _not_ follow \B all the time. Check when it is +% issued. The code below was introduced to repair a problem that gets +% visible if one uses \cwebNoChunk with an indentation unit of 2em, +% obviously I have to look for a better repair possibility. + +\CheckCommand*\B{% + \cwbb@program + \cwbb@indent 3\CwebIndentUnit \hangindent\cwbb@indent + \ifvmode + \if@noskipsec + \indent % add an empty documentation part + \else + \noindent \kern\CwebIndentUnit + \fi + \fi + \CwebNumberProgramPart + } + +\renewcommand\B{% + \cwbb@program + \cwbb@indent 3\CwebIndentUnit \hangindent\cwbb@indent + \ifvmode + \if@noskipsec + \indent % add an empty documentation part + \else + \noindent + \fi + \fi + \kern\CwebIndentUnit + \CwebNumberProgramPart + } + + +%%% ------------------------------------------------------------ + + +%% +%% Macros from cwebparts.doc, to be moved to cwebbase.doc. +%% + +% They are partly repaired and improved, where noted with `CHANGE'. + + +% \sect Now we can typeset pieces of \cweave{} output -- in principle. +% If these pieces have sections in them, they'll write entries to the +% |TOC| file. These entries will either mess up the structure of the +% document's table of contents or lead to \TeX{} error messages. That's +% because either toc entries for section types |part|, |chapter|, or +% |section| are written (causing the conflict); or toc entries for +% section types |chunk| and `|section|$i$' are written (being +% undefined). + +% The best way seems to stop the included source to add anything to the +% table of contents or to do any mark processing. For that, we provide a +% macro |\CwebNoLists| that will locally redefine the \LaTeX{} cseqs +% that cause such actions to happen. That macro will be used at the +% start of the environment. + +% CHANGE: Discard try code that redefines |\markboth| and |\markright|. + +% \beginprog +\def\CwebNoLists{% + \let\addtocontents\@gobbletwo + \let\mark\@gobble + } +% \endprog + + +% \sect Furthermore, section divisions should not start a new page. +% % +% \begin{fixme} +% Currently, sections in the included parts are typeset exactly the +% same way as they're typeset in the main document. That should be +% different -- but how do I change it in a general way? +% \end{fixme} +% +% CHANGE: Moved to Cweb environment. + + +% CHANGE: Improved question. +% +% \sect OK, what gets destroyed by the environment? We need to save +% and restore counters that are changed globally by section commands. + +% \beginprog +\ifx \chapter\undefined + \let\cweb@save_c@chapter\@gobble + \let\c@chapter\@gobble +\else + \newcount\cweb@save_c@chapter +\fi +\newcount\cweb@save_c@part +\newcount\cweb@save_c@section +\newcount\cweb@save_c@chunk + +\def\cweb@save_for_env{% + %% save values changed globally by cwebbase macros + \cweb@save_c@chapter\c@chapter + \cweb@save_c@part\c@part + \cweb@save_c@section\c@section + \cweb@save_c@chunk\c@chunk + \let\cweb@save_thechapter\thechapter + \let\cweb@save_thesection\thesection + %% set up typesetting of CWEB source + \@nobreaktrue % don't add space from first chunk + } +\def\cweb@restore_env{% + \global\c@chapter\cweb@save_c@chapter + \global\c@part\cweb@save_c@part + \global\c@section\cweb@save_c@section + \global\c@chunk\cweb@save_c@chunk + \global\let\thechapter\cweb@save_thechapter + \global\let\thesection\cweb@save_thesection + } +% \endprog + + +% \sect For the moment, we use list spacing around a |cweb| environment. +% \LaTeX{} supplies the |trivlist| environment for such purposes. + +% But the environment content itself must not be typeset in a list +% context. Two problems exist: There must be at least one |\item|, it +% will actually add the vertical space and must therefore not be +% discarded. And list environments redefine |\par|, but the +% \pkg{cwebbase} macros need a more `normal' definition. + +% An item label is stored by |\item| in the |\everypar| register. The +% label is only typeset if |@inlabel| is true. The flag |@newlist| tells +% most other \LaTeX{} macros, that there was no item yet; typically +% they'll add an empty paragraph if necessary. As the content will +% start with a \LaTeX{} section division, or even with document markup, +% we don't want that empty paragraph and should skip the empty item +% label. (Often enough, due to the initialisation of |\everypar| in +% |\@startsection|, it will be thrown away anyhow). So we establish its +% postconditions, the next macro won't notice that the item hasn't been +% set actually. + +% CHANGE: Added \CwebNoLists, as I consider it part of the env layout. + +% CHANGE: Added paragraph below. +% +% Furthermore, section divisions should not start a new page. +% % +% \begin{fixme} +% Currently, sections in the included parts are typeset exactly the +% same way as they're typeset in the main document. That should be +% different -- but how do I change it in a general way? +% \end{fixme} + +% \begin{fixme} +% Experimentally, we reduce the skip in front of a chunk to 1\,pc, +% otherwise the distance between two chunks is far too wide compared +% to other vertical distances in the text around the included stuff. +% \end{fixme} + +% \beginprog +\def\CwebBeginEnvLayout{% + %% use spacing of list, but switch off list handling afterwards + \trivlist + \@inlabelfalse % don't go in horizontal mode + \item\relax + \global\@newlistfalse + \global\@inlabelfalse\the\everypar + \@setpar{\@@par}% + %% now change cweb base layout, meant for classes + \CwebNoLists + \let\CwebEjectSection\@gobble + \CwebChunkPreSkip 1pc plus 6pt minus 3pt + } +\let\CwebEndEnvLayout=\endtrivlist +% \endprog + + +% \sect The environment gets trivial now. We supply a hook for a whole +% document and also environment-specific ones (as an optional +% environment argument). + +% CHANGE: Renamed to `Cweb'. Lusers should actually not call that env +% directly, it's too dangerous. + +% CHANGE: Added forgotten evaluation of \cweb@restore_env. + +% \beginprog +\newenvironment{Cweb}[1][]% + {% + \CwebBeginEnvLayout + \cweb@save_for_env + \csname CwebEnvHook\endcsname + #1 + }{% + \cweb@restore_env + \CwebEndEnvLayout + } +% \endprog + + +% CHANGE: Have to improve the introduction of |cwebInput|. Now it has +% an additional optional parameter, where instance specific cseqs may +% be passed (like the cweb env). + +% \sect An a convenience tag to include a complete \cweave{} file. Since +% we want to test the typesetting of our included \cweb{} program alone, +% we allow but ignore most kinds of document markup. Many of them have +% two arguments, one is optional. + +% In the preambel, only |\documentclass| and |\usepackage| may appear. +% Titlepage material is handled, table of contents is discarded. The +% document environment does nothing, i.e., unlike the \cls{cweb} class, +% material behind |\end{document}| is not ignored. + +% An |\end| tag is inserted by \cweave{} and must be redefined, we don't +% end an environment there. We'll open a group and will use that tag to +% close it again, as we know that we'll have reached the end of our +% \cweb{} file. Of course, |\end| must not be redefined during +% processing the actual program source -- environments are valid there. +% The redefinition is best be triggered by material inserted from +% \cweave{} at the very end, e.g., from |\inx|. But |\inx| may not be +% there (when \cweave{} is called with the `|-x|' option), we'll use +% |\enddocument| to add a |\inx| tag for safety reason. If the user +% didn't add an |\end{document}| to his file and used `|-x|', we're +% going to loose. + +% CHANGE: Added handling of empty chunk. (@noskipsec was set after the +% environment, what messed up later invocations of program code if +% used with \cwebCodeExample.) + +% \TeX{}nical note: |\document| must not have the same binding as +% |\relax|, as this would be interpreted as a non-existing environment +% by \LaTeX{}. (That's due to the |\csname| lossage.) + +% \TeX{}nical note: Evaluating |\inx| in |\enddocument| will not have +% any effect, we're inside a group. That evaluation must be postponed +% after the group has been closed. + +% \beginprog +\providecommand\cweb@doc_markup_gobble[2][]{} +\let\cwebInput\undefined +\newcommand*\cwebInput[2][]{% + \begin{Cweb} + [% + \begingroup + \let\documentclass\cweb@doc_markup_gobble + \let\usepackage\cweb@doc_markup_gobble + \let\title\@gobble + \let\author\@gobble + \let\date\@gobble + \let\maketitle\relax + \let\tableofcontents\relax + \let\document\empty + \def\inx{\let\end\endgroup}% + \let\fin\relax + \let\con\relax + \def\enddocument{% + \if@noskipsec % empty chunk + \global\@noskipsecfalse + \global\everypar{}% + \fi + \aftergroup\inx + }% + #1% + ]% + \input{#2}% + \end{Cweb}% + } +% \endprog + + +%%% ------------------------------------------------------------ + + +%% +%% New macros for cwebbase.doc. +%% + + +% For production of code examples in CWEB documents. It's expected +% that the document consists of only \emph{one} chunk that has no +% documentation. Just the code is of interest. Neither chunk markers, +% nor chunk numbers, nor refinement numbers are typeset. +% +% But one may change that with the optional parameter. + +\providecommand*\cwebCodeExample[2][]{% + \cwebInput[% + \def\CwebChunkHeading##1{\kern -1em}% + \let\cwbb@marginal_chunkno\relax + \let\CwebRefNumber\@gobble + \CwebChunkPreSkip\z@skip + #1% + ]{#2}% + } + + +% Often one has an explanation for more than one refinement. (E.g., +% when there's needed a definition and a declaration.) Then the +% documentation of the follow-up refinements shall consist solely of +% |\cwebNoChunk|. Then no chunk marker is set, and the refinement +% is typeset nearer to the previous refinement. Optically, we create +% one chunk with many refinements this way. + +% \TeX{}nical note: No chunk marker is created by redefining macro +% |\@svsechd| that creates header for run-in \LaTeX{} section. Every +% header is followed by 1\,em space, we have to annulate that skip. +% (The refinement shall start at the beginning of the line.) One must +% not use |\hskip| to backup, an |\unskip| comes after the header and +% would discard that skip. + +\providecommand\cwebNoChunk{% + \vskip -\lastskip \bigskip % discard LaTeX's inter-section skip + \def\@svsechd{\kern -1em}% + } + + + + +\catcode`\_=\CatUsCode +\endinput + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% $Log: cwebx.sty,v $ +% Revision 3.1 1995/11/21 00:42:49 schrod +% version 1.1 +% + + + +%%%------------------------------------------------------------ + +% Local Variables: +% mode: LaTeX +% TeX-brace-indent-level: 4 +% indent-tabs-mode: t +% TeX-auto-untabify: nil +% page-delimiter: "^%%%" +% End: diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/keyvald.dtx b/Master/texmf-dist/doc/latex/cweb-latex/src/keyvald.dtx new file mode 100644 index 00000000000..6873fde7110 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/keyvald.dtx @@ -0,0 +1,347 @@ +%% $ITI: keyvald.dtx,v 1.2 1995/08/25 19:00:31 schrod Exp $ +%%------------------------------------------------------------ +%% (history at end) +% +% \iffalse +%% File: keyvald.dtx; changed version of +%% File: keyval.dtx Copyright (C) 1993-1994 David Carlisle +% +%<*dtx> + \ProvidesFile{keyvald.dtx} +%</dtx> +%<*!plain> +%<package&!plain>\NeedsTeXFormat{LaTeX2e} +%<package&!plain>\ProvidesPackage{keyvald} +%<driver> \ProvidesFile{keyvald.drv} +% \fi +% \ProvidesFile{keyvald.dtx} + [1994/08/23 v1.08.1 key=value parser (DPC) w/ defaults (js)] +% +% \iffalse +%</!plain> +%<*driver> +\documentclass{ltxdoc} +\usepackage{keyvald} +\begin{document} + \DocInput{keyvald.dtx} +\end{document} +%</driver> +% \fi +% +% \GetFileInfo{keyvald.dtx} +% \title{The \textsf{keyvald} package\thanks{This file +% has version number \fileversion, last +% revised \filedate.}} +% \author{David Carlisle\\carlisle@cs.man.ac.uk +% \and +% changed by\\Joachim Schrod\\ +% \texttt{<schrod@iti.informatik.th-darmstadt.de>} +% } +% \date{\filedate} +% \maketitle +% +% \begin{abstract} +% A \LaTeX\ package implementing a system allowing the setting +% of parameters (or `named arguments' with a +% \meta{key}${}={}$\meta{value} syntax. +% +% Eg: |\foo[height=3in, shadow = true ]{bar}| +% \end{abstract} +% +% \CheckSum{110} +% +% \changes{v1.03} +% {1993/10/13}{Initial version} +% \changes{v1.04}{1993/11/15} +% {Upgrade after comments from Timothy van Zandt} +% \changes{v1.05}{1993/11/17} +% {Further small improvements} +% \changes{v1.06}{1994/02/01} +% {Update to LaTeX2e} +% \changes{v1.07}{1994/03/15} +% {New style ltxdoc} +% \changes{v1.08}{1994/09/12} +% {Improve docstrip handling} +% \changes{v1.08.1}{1995/08/23} +% {Default keys} +% +% +% This package implements a system of defining and using sets of +% parameters, which are set using the syntax \meta{key}=\meta{value}. +% +% For each keyword in such a set, there exists a function which is +% called whenever the parameter appears in a parameter list. For +% instance if the set |dpc| is to have the keyword |scale| then I +% would define.\\ +% | \define@key{dpc}{scale}{scale ({\tt\string#1})\\}|\\ +% The first argument of |\define@key| is the set of keywords being +% used, the second is the keyword, and the third is the function to +% call. This function will be given as |#1| the \meta{value} specified +% by the user. +% +% Normally it is an error to omit the `=\meta{value}' however if an +% optional \meta{value} is supplied when the keyword is defined, then +% just the keyword need be supplied.\\ +% |\define@key{dpc}{clip}[true]{...}|\\ +% For `|clip|' you can go `|clip = true|' or `|clip = false|' or +% just `|clip|', which is the same as `|clip = true|' +% +% To use these keywords, just call `|\setkeys|' with a comma +% separated list of settings, each of the form +% \meta{key}=\meta{value}, or just \meta{key}. Any white space around +% the `|=|' and `|,|' is ignored. +% +% As the \meta{key} is passed as a macro argument, if it consists +% entirely of a |{ }| group, the outer braces are stripped off. Thus +% |,key=foo,| and |key=,{foo},| are equivalent. This fact enables one to +% `hide' any commas or equals signs that must appear in the value. i.e.\ +% in |foo={1,2,3},bar=4|, |foo| gets the value |1,2,3|, the comma after +% |1| does not terminate the keyval pair, as it is `hidden' by the +% braces. +% +% Empty entries, with nothing between the commas, are silently ignored. +% This means that it is not an error to have a comma after the last +% term, or before the first. +% +% \section{Example} +% +% We may extend the examples above to give a `fake' graphics +% inclusion macro, with a syntax similar to that used in the psfig +% macros. +% +% \makeatletter +% \def\dpcgraphics{\@ifnextchar[\@dpcgraphics{\@dpcgraphics[]}} +% +% |\dpcgraphics| has one optional argument which is passed through +% |\setkeys|, and one mandatory argument, the filename. It actually +% just typesets its arguments, for demonstration. +% +% \def\@dpcgraphics[#1]#2{{\setkeys{dpc}{#1}INPUT: #2}}% +% +% \define@key{dpc}{scale}{scale ({\tt\string#1\relax})\\} +% \define@key{dpc}{height}{height ({\tt#1})\\} +% \define@key{dpc}{width}{width ({\tt#1})\\} +% \define@key{dpc}{bb}{bounding box ({\tt#1})\\} +% \define@key{dpc}{clip}[true]{clip ({\tt\string#1\relax})\\} +% \makeatother +% +% The declared keys are: |scale|, |height|, |width|, |bb|, +% and |clip|. Except for the last, they must all be given a value if +% used. +% +% Note how in the following, any white space arround |=| or |,| is +% ignored, as are the `empty' arguments caused by extra commas. Note +% also that each macro receives {\em exactly\/} the tokens that you +% specify as arguments, no premature expansion is done. +% +% \begin{verbatim} +% \def\dpcgraphics{\@ifnextchar[\@dpcgraphics{\@dpcgraphics[]}} +% \def\@dpcgraphics[#1]#2{{\setkeys{dpc}{#1}INPUT: #2}} +% +% \define@key{dpc}{scale}{scale ({\tt\string#1\relax})\\} +% \define@key{dpc}{clip}[true]{clip ({\tt\string#1\relax})\\} +% \end{verbatim} +% +% \begin{minipage}{.4\textwidth} +% \begin{verbatim} +% \def\scalemacro{9} +% \dpcgraphics +% [ height =4in, , +% width = 3in, +% scale = \scalemacro, +% bb = 20 20 300 400 , +% clip, +% ]{aaa} +% \end{verbatim} +% \end{minipage} +% \hfill +% \begin{minipage}{.4\textwidth} +% \def\scalemacro{9} +%\dpcgraphics +% [ height =4in, , +% width = 3in, +% scale = \scalemacro , +% bb = 20 20 300 400 , +% clip , +% ]{aaa} +% \end{minipage} +% +% +% \section{The Internal Interface} +% A declaration of the form:\\ +% |\define@key{family}{key}{...}|\\ +% Defines a macro |\KV@prefix@key| with one argument. When used in a +% keyval list, the macro receives the value as its argument. +% +% A declaration of the form:\\ +% |\define@key{family}{key}[default]{...}|\\ +% Defines a macro |\KV@family@key| as above, however it also defines the +% macro |\KV@family@key@default| as a macro with no arguments, and +% definition\\ +% |\KV@family@key{default}|. +% +% Thus if macros are defined using |\define@key|, the use of a key with +% no value \ldots|,foo,|\ldots\ is always equivalent to the use of the +% key with some value, \ldots|,foo=default,|\ldots. However a package +% writer may wish that the `default' behaviour for some key is not +% directly equivalent to using that key with a value. (In particular, as +% pointed out to me by Timothy Van Zandt, you may wish to omit error +% checking on the default value as you know it is correct.) In these +% cases one simply needs to define the two macros +% |\KV@|\meta{family}|@key| and |\KV@|\meta{family}|@key@default| +% directly using |\def| (or |\newcommand|). I do not supply a user +% interface for this type of definition, but it is supported in the +% sense that I will try to ensure that any future upgrades of this +% package do not break styles making use of these `low level' +% definitions. +% +% \StopEventually{} +% +% \section{The Macros} +% +% From version~1.05, all `internal' macros associated to keys have names +% of the form:\\ +% |\KV@|\meta{family}|@|\meta{key} or +% |\KV@|\meta{family}|@|\meta{key}|@|\meta{default} +% +% \begin{macrocode} +%<*package> +% \end{macrocode} +% +% \begin{macro}{\setkeys} +% The top level macro. |#2| should be a comma separated values of the +% form \meta{key} |=| \meta{value} or just simply \meta{key}. +% The macro associated with this key in the `family' |#1| is called with +% argument \meta{value}. The second form is only allowed if the key was +% declared with a default value. +% \begin{macrocode} +\def\setkeys#1#2{% +% \end{macrocode} +% Save the `family' for later. Then begin acting on the comma +% separated list. +% \begin{macrocode} + \def\KV@prefix{KV@#1@}% + \KV@do#2,\relax,} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\KV@do} +% Iterate down the list of comma separated argument pairs. +% \begin{macrocode} +\def\KV@do#1,{% + \ifx\relax#1\empty\else + \KV@split#1==\relax + \expandafter\KV@do\fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\KV@split} +% Split up the keyword and value, and call the appropriate command. +% This macro was slightly reorganised for version 1.04, after some +% suggestions from Timothy Van Zandt. +% \begin{macrocode} +\def\KV@split#1=#2=#3\relax{% + \KV@@sp@def\KV@key{#1}% + \ifx\KV@key\@empty\else + \expandafter\let\expandafter\@tempc + \csname\KV@prefix\KV@key\endcsname + \ifx \@tempc\relax + \expandafter\let \expandafter\@tempc + \csname\KV@prefix*\endcsname + \def\@tempa{*}% + \else + \let\@tempa\KV@key + \fi + \ifx\@tempc\relax + \KV@err{\KV@key\space undefined}% + \else + \ifx\@empty#3\@empty + \KV@default + \else + \KV@@sp@def\@tempb{#2}% + \expandafter\@tempc\expandafter{\@tempb}\relax + \fi + \fi + \fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\KV@default} +% Run the default code, or raise an error. +% \begin{macrocode} +\def\KV@default{% + \expandafter\let\expandafter\@tempb + \csname\KV@prefix\@tempa @default\endcsname + \ifx\@tempb\relax + \KV@err{No value specified for \KV@key}% + \else + \@tempb\relax + \fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\KV@err} +% Error messages. +% \begin{macrocode} +\def\KV@err#1{\PackageError{keyvald}{#1}{}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\KV@@sp@def} +% \begin{macro}{\KV@@sp@b} +% \begin{macro}{\KV@@sp@c} +% |\KV@@sp@def|\meta{cmd}\meta{token list} is like |\def|, except that +% a space token at the beginning or end of \meta{token list} is +% removed before making the assignment. \meta{token list} may not +% contain the token |\@nil|, unless it is within a brace group. +% The names of these commands were changed at version~1.05 to ensure +% that they do not clash with `internal' macros in a key family `sp'. +% +% The following three lines are equivalent to\\ +% |\def\KV@@sp@def#1#2{\KV@@sp@b#2\@nil\@nil~\@nil\relax#1}|\\ +% Where |~| is an explicit space token. +% \begin{macrocode} +\def\@tempa#1{% +\def\KV@@sp@def##1##2{\KV@@sp@b##2\@nil\@nil#1\@nil\relax##1}} +\@tempa{ } +\def\KV@@sp@b#1#2 \@nil{\KV@@sp@c#1#2} +\def\KV@@sp@c#1\@nil#2\relax#3{\def#3{#1}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% +% \begin{macro}{\define@key} +% Define the command associated to the key |#2| in the family |#1|. +% First looks for a default argument (the default value for the +% key) +% \begin{macrocode} +\def\define@key#1#2{% + \@ifnextchar[{\KV@def{#1}{#2}}{\@namedef{KV@#1@#2}####1}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\KV@def} +% Make the definitions of the command, and the default value. +% \begin{macrocode} +\def\KV@def#1#2[#3]{% + \@namedef{KV@#1@#2@default\expandafter}\expandafter + {\csname KV@#1@#2\endcsname{#3}}% + \@namedef{KV@#1@#2}##1} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</package> +% \end{macrocode} +% \Finale +% +\endinput + +%------------------------------------------------------------ +% +% $ITIlog: keyvald.dtx,v $ +% Revision 1.2 1995/08/25 19:00:31 schrod +% Add enhanced version of keyval package, with ability to specify +% default action for unknown keyword options. +% diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/keyvald.ins b/Master/texmf-dist/doc/latex/cweb-latex/src/keyvald.ins new file mode 100644 index 00000000000..0fe873fd74f --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/keyvald.ins @@ -0,0 +1,6 @@ +\def\batchfile{keyvald.ins} +\input docstrip + +\keepsilent + +\generateFile{keyvald.sty}{f}{\from{keyvald.dtx}{package}} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/style/cweb-doc.el b/Master/texmf-dist/doc/latex/cweb-latex/src/style/cweb-doc.el new file mode 100644 index 00000000000..eb801786499 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/style/cweb-doc.el @@ -0,0 +1,22 @@ +;; $Id: cweb-doc.el,v 1.1 1995/08/29 15:15:30 schrod Exp $ +;;---------------------------------------------------------------------- + +;;; +;;; AUC-TeX configuration for cweb-doc.sty +;;; + +(TeX-add-style-hook "cweb-doc" + (function + (lambda () + (TeX-add-symbols "cweb" "ctangle" "cweave" + '("arg" 1) + '("<" TeX-arg-free ">") + '("cls" 1) + '("pkg" 1) + ) + (LaTeX-add-environments "fixme" "cseqtab" + '("options" LaTeX-env-item) + ) + (setq LaTeX-item-list (cons '("options" . LaTeX-item-argument) + LaTeX-item-list)) + ))) diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/Imakefile b/Master/texmf-dist/doc/latex/cweb-latex/src/test/Imakefile new file mode 100644 index 00000000000..0d32d8301c3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/Imakefile @@ -0,0 +1,142 @@ +XCOMM $Id: Imakefile,v 1.9 1995/11/20 22:34:44 schrod Exp $ +/* ---------------------------------------------------------------------- */ + +/* + * Imakefile for test of cweb bundle + * + * (history at end) + */ + + +/* needed modules */ +#define idx NO_IDX_CLEAN /* don't delete *.idx on make clean */ +#include <TeX.imk> +#undef idx + +XCOMM ------------------------------------------------------------ +XCOMM continue in Imakefile + +.SUFFIXES: .tex .w + +.w.tex: @@\ + if [ -r $*.ch ] ; \ @@\ + then cweave $* $* ; \ @@\ + else cweave $* ; \ @@\ + fi + + +regression:: clean + $(MAKE) all + + +/* ============================================================ + * + * tests for cweb class & cwebarray package + */ + +TeXTarget(latex,minimal) /* minimal document */ +TeXTarget(latex,token) /* rendering of tokens */ +TeXTarget(latex,refname) /* refinement names, filename ref. */ +TeXTarget(latex,modes) /* cweb FSA */ +TeXTarget(latex,section) /* hierarchic document structure */ +TeXTarget(latex,flat) /* flat document structure */ +TeXTarget(latex,report) /* report as base class */ +TeXTarget(latex,nolists) /* nolists via CWEAVE option -x */ +TeXTarget(latex,newif) /* idiosyncrasy of old LateX version */ + +TeXTarget(latex,enddocbegin) /* skip stuff after \end{document} */ +TeXTarget(latex,vbar) /* ruled table [cwebarray] */ +TeXTarget(latex,titlepage) /* titlepage option */ + +TeXTarget(latex,language-german) /* language option german */ +TeXTarget(latex,german) /* babel-compatible option german */ + +TeXTarget(latex,change) /* changefile-related output */ +TeXTarget(latex,sup-changes) /* changefile-related suppression */ + +TeXTarget(latex,sup-lists) /* suppression of index & reflist */ +TeXTarget(latex,sup-format) /* suppression of format directives */ + +TeXTarget(latex '\nonstopmode \input',badend) /* unknown \end expansion */ +TeXTarget(latex '\nonstopmode \input',badopts) /* unknown & illegal options */ + + +/* + * Special (additional) rules for targets above + */ + +nolists.tex: nolists.w + cweave -x nolists + +change.tex: change.ch + +sup-changes.tex: sup-changes.w change.ch + cweave sup-changes change + + + +/* ============================================================ + * + * tests for packages + */ + +/* cwebparts */ + +TeXTarget(latex,parts) /* CWEB parts in LaTeX document */ + +parts.dvi: parts-code.tex + +parts-code.tex: parts-code.w + cweave -x parts-code + + + +/* ============================================================ + * + * Tests for stuff that is not strictly part of the cweb bundle. + */ + +TeXTarget(latex,keyvald) /* keyword-value options w/ defaults */ + + +realclean:: clean + rm -f *.idx *.scn *.tex + + + +/* ============================================================ + * + * $Log: Imakefile,v $ + * Revision 1.9 1995/11/20 22:34:44 schrod + * Test language support, actually for German. + * + * Revision 1.8 1995/11/07 18:28:52 schrod + * Add test newif, for old LaTeX version. + * + * Revision 1.7 1995/09/17 14:21:36 schrod + * Test package cwbl-german. + * + * Revision 1.6 1995/09/16 17:02:09 schrod + * Test cwebparts.sty. + * + * Revision 1.5 1995/09/12 22:32:21 schrod + * Add test case for output of CWEAVE with `-x' option. + * + * Revision 1.4 1995/08/29 15:22:14 schrod + * Add test of format directive suppression. + * + * Revision 1.3 1995/08/27 13:29:38 schrod + * Tests of options & changefile-related suppression. + * + * Revision 1.2 1995/08/25 19:12:39 schrod + * Test implementation of hierarchic and flat structure. + * + * Revision 1.1 1995/08/08 00:14:46 schrod + * Updated to \LaTeXe{}, the |cweb| style is now a document class. + * + + * ------------------------------------------------------------ + * Local Variables: + * mode: Indented-Text + * End: + */ diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/badend.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/badend.w new file mode 100644 index 00000000000..51060a65cfd --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/badend.w @@ -0,0 +1,21 @@ +% $Id: badend.w,v 1.3 1995/08/08 00:14:46 schrod Exp $ +%---------------------------------------------------------------------- + +% tests unknown \end macro +% assumes "h" and "x" user reaction +% note: produces no output! + +\makeatletter +\def\end#1{\csname end#1\endcsname\@@checkend{#1}% + \expandafter\endgroup \if@@endpe \@@doendpe \fi +\relax % <-- added + \if@@ignore \global\@@ignorefalse \ignorespaces\fi} +\makeatother + +\documentclass{cweb} + +\begin{document} + +@ Test + +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/badopts.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/badopts.w new file mode 100644 index 00000000000..5fff5f7add7 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/badopts.w @@ -0,0 +1,13 @@ +% $Id: badopts.w,v 1.1 1995/08/27 13:29:39 schrod Exp $ +%------------------------------------------------------------ + +% test bad options + +\documentclass[undef,structure,structure=chaos]{cweb} + +\begin{document} + +Text. + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/change.ch b/Master/texmf-dist/doc/latex/cweb-latex/src/test/change.ch new file mode 100644 index 00000000000..2796a280e68 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/change.ch @@ -0,0 +1,5 @@ +@x +change here +@y +did the change +@z diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/change.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/change.w new file mode 100644 index 00000000000..d787065b933 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/change.w @@ -0,0 +1,20 @@ +% $Id: change.w,v 1.4 1995/08/27 13:29:40 schrod Exp $ +%---------------------------------------------------------------------- + +% tests changefile output + +\documentclass{cweb} + +\begin{document} + +\title{Test for changefiles} +\author{Coogar} +\maketitle + +@ test + +@ +change here + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/enddocbegin.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/enddocbegin.w new file mode 100644 index 00000000000..64d77368e1f --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/enddocbegin.w @@ -0,0 +1,16 @@ +% $Id: enddocbegin.w,v 1.3 1995/08/08 00:14:47 schrod Exp $ +%---------------------------------------------------------------------- + +% tests skip of stuff after \end{document} + +\documentclass{cweb} + +\begin{document} + +@ Test. + +\end{document} + +\begin{itemize} +\item an item +\end{itemize} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/flat.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/flat.w new file mode 100644 index 00000000000..993193971f3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/flat.w @@ -0,0 +1,47 @@ +% $Id: flat.w,v 1.1 1995/08/25 19:12:40 schrod Exp $ +%---------------------------------------------------------------------- + +% tests section levels and references for flat structure documents. + +\documentclass[structure=flat]{cweb} + +\begin{document} + +\tableofcontents + +\newpage + +@** s title. +\label{main-sec} + +Some text. + +@* e title. + +Some text. +And some references: Part~\ref{main-sec} and section~\ref{normal-sec}. + +@*0 0 title. + +Some text. + +@*1 1 title. + +Some text. + +@*2 2 title. + +Some text. + +@ \label{normal-sec} +Doc. + +@d def foo +@f def int + +@c +for ( int i=1; i<10; i++ ) + @< do something @> + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/german.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/german.w new file mode 100644 index 00000000000..dd6f5d64bbe --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/german.w @@ -0,0 +1,33 @@ +% $Id: german.w,v 1.3 1995/11/20 22:34:44 schrod Exp $ +%---------------------------------------------------------------------- + +% tests german language support + + +% check if option after german works as well +\documentclass[german,suppress=index]{cweb} + +\usepackage{german} + +\begin{document} + +\title{Test der \texttt{german} Option} +\author{Puma} +\maketitle + +@ Aktives Anf\"uhrungszeichen im String. +@c +#include "foo.h" + +@ @( foo.h@>= +@< etwas |code| @>@; +@< mehr Code @> + +@ @< etwas ...@>= +for ( int i=1; i<10; i++ ) + @< mehr... @> + +@ @< mehr... @>= + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/language-german.ch b/Master/texmf-dist/doc/latex/cweb-latex/src/test/language-german.ch new file mode 100644 index 00000000000..1e41e64e1e3 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/language-german.ch @@ -0,0 +1,5 @@ +@x +@< mehr Code @> +@y +@< mehr -- ge\"anderter -- Code @> +@z diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/language-german.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/language-german.w new file mode 100644 index 00000000000..bd145c4f921 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/language-german.w @@ -0,0 +1,31 @@ +% $Id: language-german.w,v 1.1 1995/11/20 22:34:45 schrod Exp $ +%---------------------------------------------------------------------- + +% tests german language support + +\documentclass[language=german]{cweb} + +\usepackage{german} + +\begin{document} + +\title{Test der \texttt{language} Option} +\author{Puma} +\maketitle + +@ Aktives Anf\"uhrungszeichen im String. +@c +#include "foo.h" + +@ @( foo.h@>= +@< etwas |code| @>@; +@< mehr Code @> + +@ @< etwas ...@>= +for ( int i=1; i<10; i++ ) + @< mehr... @> + +@ @< mehr... @>= + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/minimal.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/minimal.w new file mode 100644 index 00000000000..fc0cdaa492a --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/minimal.w @@ -0,0 +1,12 @@ +% $Id: minimal.w,v 1.4 1995/08/25 19:12:41 schrod Exp $ +%---------------------------------------------------------------------- + +% tests minimal CWEB w/ LaTeX input file + +\documentclass{cweb} +\begin{document} + +Test. + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/modes.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/modes.w new file mode 100644 index 00000000000..48525ae38d5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/modes.w @@ -0,0 +1,16 @@ +% $Id: modes.w,v 1.3 1995/08/27 19:28:49 schrod Exp $ +%---------------------------------------------------------------------- + +\documentclass{cweb} + +\begin{document} + +@ program $\to$ program with documentation of |bar(i+1)|. + +@d foo bar +@< refinement @>= + stmt; + + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/newif.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/newif.w new file mode 100644 index 00000000000..53ae2775145 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/newif.w @@ -0,0 +1,39 @@ +% $Id: newif.w,v 1.1 1995/11/07 18:28:52 schrod Exp $ +%------------------------------------------------------------ + +% test that proper definition of \newif is established. + + +% First, restore problematic definition and pretend we're an old LaTeX. + +\makeatletter + +\outer\def\newif#1{\count@@\escapechar \escapechar\m@@ne + \expandafter\expandafter\expandafter + \edef\@@if#1{true}{\let\noexpand#1=\noexpand\iftrue}% + \expandafter\expandafter\expandafter + \edef\@@if#1{false}{\let\noexpand#1=\noexpand\iffalse}% + \@@if#1{false}\escapechar\count@@} % the condition starts out false + +\let\OldNewif=\newif + +\edef\fmtversion{1994/12/01} + +\makeatother + + +% Now, start the document and check if \newif got redefined. + +\documentclass{cweb} + +\begin{document} + +\ifx \OldNewif\newif + \errmessage{\string\newif\space was not redefined.} +\else + \message{\string\newif\space got redefined.} +\fi + +@ Test. + +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/nolists.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/nolists.w new file mode 100644 index 00000000000..190c22c3c21 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/nolists.w @@ -0,0 +1,16 @@ +% $Id: nolists.w,v 1.1 1995/09/12 22:32:22 schrod Exp $ +%------------------------------------------------------------ + +% test suppression of index & ref list + +\documentclass{cweb} + +\begin{document} + +@ We need something to add to the lists. + +@< refinement @>= +foo(bar); + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/parts-code.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/parts-code.w new file mode 100644 index 00000000000..ad24b1e2b29 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/parts-code.w @@ -0,0 +1,32 @@ +% $Id: parts-code.w,v 1.1 1995/09/16 17:02:10 schrod Exp $ +%------------------------------------------------------------ + +% test of `cwebparts' package: +% code parts to be included in a LaTeX document +% no sections + +\documentclass{cweb} + +\usepackage{rcs} + +\begin{document} + +\title{Believe it} +\author{Coogar} + +\maketitle + +@ Some explanation of the code below. It's very hairy, isn't it? + +@( foo.h@>= +@< some |code| @>@; +@< more code @> + +@ @< some ...@>= +for ( int i=1; i<10; i++ ) + @< more... @> + +@ @< more... @>= + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/parts.tex b/Master/texmf-dist/doc/latex/cweb-latex/src/test/parts.tex new file mode 100644 index 00000000000..252b2129918 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/parts.tex @@ -0,0 +1,47 @@ +% $Id: parts.tex,v 1.1 1995/09/16 17:02:10 schrod Exp $ +%---------------------------------------------------------------------- + +% +% test of inclusion of CWEB program parts +% +% [LaTeX] +% (history at end) + + + +\documentclass{article} + +\usepackage{cwebparts} + + +\begin{document} + + + +\title{Foobar Algorithm} +\author{Cougar} + +\maketitle + +\makeatletter + + +\section{C Implementation} + +Let's have a look at the implementation in C: + +\cwebInput{parts-code} + +\noindent Got it? + + + +\end{document} + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +$Log: parts.tex,v $ +Revision 1.1 1995/09/16 17:02:10 schrod + Test cwebparts.sty. + diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/refname.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/refname.w new file mode 100644 index 00000000000..e15fa990ddd --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/refname.w @@ -0,0 +1,21 @@ +% $Id: refname.w,v 1.3 1995/08/08 00:14:49 schrod Exp $ +%---------------------------------------------------------------------- + +% tests refinement names, incl. pseudo-refinements w/ file names + +\documentclass{cweb} + +\begin{document} + +@ @( foo.h@>= +@< some |code| @>@; +@< more code @> + +@ @< some ...@>= +for ( int i=1; i<10; i++ ) + @< more... @> + +@ @< more... @>= + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/report.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/report.w new file mode 100644 index 00000000000..15242e7908d --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/report.w @@ -0,0 +1,48 @@ +% $Id: report.w,v 1.1 1995/08/27 17:25:40 schrod Exp $ +%------------------------------------------------------------ + +% test baseclass option +% default is `report' + +\documentclass[baseclass]{cweb} + +\begin{document} + +\tableofcontents + +\newpage + +@** s title. +\label{main-sec} + +Some text. + +@* e title. + +Some text. +And some references: Part~\ref{main-sec} and section~\ref{normal-sec}. + +@*0 0 title. + +Some text. + +@*1 1 title. + +Some text. + +@*2 2 title. + +Some text. + +@ \label{normal-sec} +Doc. + +@d def foo +@f def int + +@c +for ( int i=1; i<10; i++ ) + @< do something @> + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/section.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/section.w new file mode 100644 index 00000000000..13159e2fc6a --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/section.w @@ -0,0 +1,55 @@ +% $Id: section.w,v 1.6 1995/11/07 14:14:25 schrod Exp $ +%---------------------------------------------------------------------- + +% tests section levels and references. + +\documentclass{cweb} + +\begin{document} + +\tableofcontents + +\newpage + +@** s title. +\label{main-sec} + +Some text. + +@* e title. + +Some text. +And some references: Part~\ref{main-sec} and section~\ref{normal-sec}. + +@*0 0 title. + +Some text. + +@*1 1 title. + +Some text. + +@*2 2 title. + +Some text. + +@*1 1 title. + +Reset counter. + +@*2 2 title. + +Some text. + +@ \label{normal-sec} +Doc. + +@d def foo +@f def int + +@c +for ( int i=1; i<10; i++ ) + @< do something @> + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-changes.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-changes.w new file mode 100644 index 00000000000..019dc8388e0 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-changes.w @@ -0,0 +1,20 @@ +% $Id: sup-changes.w,v 1.1 1995/08/27 13:29:40 schrod Exp $ +%---------------------------------------------------------------------- + +% tests suppress=unchanged + +\documentclass[suppress=unchanged]{cweb} + +\begin{document} + +\title{Test for suppression of unchanged chunks} +\author{Coogar} +\maketitle + +@ test + +@ +change here + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-format.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-format.w new file mode 100644 index 00000000000..eec493ff4fd --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-format.w @@ -0,0 +1,17 @@ +% $Id: sup-format.w,v 1.1 1995/08/29 15:22:17 schrod Exp $ +%------------------------------------------------------------ + +% test suppression of format directives + +\documentclass[suppress=format]{cweb} + +\begin{document} + +@ test +@f XmMainWindow int +@f foo int +@f bar i +XmMainWindow dir = XtCreateWidget("foobar"); + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-lists.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-lists.w new file mode 100644 index 00000000000..2049f361512 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/sup-lists.w @@ -0,0 +1,16 @@ +% $Id: sup-lists.w,v 1.1 1995/08/27 19:29:07 schrod Exp $ +%------------------------------------------------------------ + +% test suppression of index & ref list + +\documentclass[suppress={index,reflist}]{cweb} + +\begin{document} + +@ We need something to add to the lists. + +@< refinement @>= +foo(bar); + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/titlepage.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/titlepage.w new file mode 100644 index 00000000000..b8230cebeb2 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/titlepage.w @@ -0,0 +1,19 @@ +% $Id: titlepage.w,v 1.1 1995/08/27 13:29:41 schrod Exp $ +%------------------------------------------------------------ + +% test titlepage option +% test also forwarding of option to baseclass + +\documentclass[titlepage]{cweb} + +\begin{document} + +\title{Test title} +\author{Coogar} + +\maketitle + +Test text. + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/token.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/token.w new file mode 100644 index 00000000000..7765f1b9b37 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/token.w @@ -0,0 +1,29 @@ +% $Id: token.w,v 1.3 1995/08/29 15:21:08 schrod Exp $ +%---------------------------------------------------------------------- + +% tests: rendering of tokens + +\documentclass{cweb} + +\begin{document} + +@ +@c +a = 100L; +a = 100UL; + +@ shift operators: +@c +cout << "hello, world" << endl; +cin >> var; + +@ formatting that depend on font sizes in Plain \texttt{CWEB}: +@f foo_bar int +@c +foo++; bar--; +foo_bar obj; +obj->method(); + + +@ +\end{document} diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/test/vbar.w b/Master/texmf-dist/doc/latex/cweb-latex/src/test/vbar.w new file mode 100644 index 00000000000..144b2810b36 --- /dev/null +++ b/Master/texmf-dist/doc/latex/cweb-latex/src/test/vbar.w @@ -0,0 +1,30 @@ +% $Id: vbar.w,v 1.2 1995/08/08 00:14:51 schrod Exp $ +%---------------------------------------------------------------------- + +% tests ways to get ruled tables + +\documentclass{cweb} + +\usepackage{cwebarray} + +\begin{document} + +@ Test 1: + +\begin{tabular}{^^7cl^^7cl^^7c} +\hline +1st column & 2nd column\\ +\hline +\end{tabular} + + +@ Test 2: + +\begin{tabular}{IlIlI} +\hline +1st column & 2nd column\\ +\hline +\end{tabular} + + +\end{document} |