DOCSLIB.ORG

The Doc and Shortvrb Packages∗

Total Page：16

File Type：pdf, Size：1020Kb

Download full-text PDF Read full-text
The Doc and Shortvrb Packages∗ The doc and shortvrb Packages∗ Frank Mittelbachy June 15, 2021 This file is maintained byA theLTEX Project team. Bug reports can be opened (category latex) at https://latex-project.org/bugs.html. Abstract This package contains the definitions that are necessary to format the documentation of package files. The package was developed in Mainz in cooperation with the Royal Military College of Science. This is an update which documents various changes and new features in doc and integrates the features of newdoc. Contents 1 Introduction3 2.10 Changing the default val- 1.1 Using the doc package..4 ues of style parameters.. 10 2.11 Short input of verbatim 2 The User Interface4 text pieces......... 10 2.1 The driver file.......4 2.12 Additional bells and 2.2 General conventions...5 whistles.......... 10 2.3 Describing the usage of 2.13 Basic usage summary.. 13 new macros........6 2.14 Acknowledgements.... 14 2.4 Describing the definition of new macros.......6 3 The Description of Macros 14 2.5 Formatting the margins.6 3.1 Options supported by doc 15 2.6 Using a special escape 3.2 Macros surrounding the character.........7 ‘definition parts'..... 15 2.7 Cross-referencing all 3.3 Macros for the `docu- macros used........7 mentation parts'..... 22 2.8 Producing the actual in- 3.4 Formatting the margin.. 27 dex entries.........8 3.5 Creating index entries by 2.9 Setting the index entries.9 scanning `macrocode'... 27 ∗This file has version number v2.1n dated 2021/05/28. yFurther commentary added at Royal Military College of Science by B. Hamilton Kelly; English translation of parts of the original German commentary provided by Andrew Mills; fairly substantial additions, particularly from newdoc, and documentation of post-v1.5q features added at v1.7a by Dave Love (SERC Daresbury Lab). Extraction of shortvrb package added by Joachim Schrod (TU Darmstadt). 1 3.6 Macros for scanning 3.12 Providing a checksum macro names....... 29 and character table.... 50 3.7 The index exclude list.. 33 3.13 Attaching line numbers 3.8 Macros for generating in- to code lines........ 52 dex entries......... 35 3.14 Layout Parameters for 3.9 Redefining the index en- documenting package files 53 vironment......... 38 3.10 Dealing with the change 3.15 Changing the \catcode history........... 42 of %............ 54 3.11 Bells and whistles..... 45 3.16 GetFileInfo........ 54 Preface to version 1.7 This version of doc.dtx documents Checksum/character table support changes which have occurred since the for ensuring the integrity of dis- last published version [5] but which have tributions is added; been present in distributed versions of becomes ; doc.sty for some time. It also inte- \printindex \PrintIndex grates the (undocumented) features of multicol.sty is no longer necessary the distributed newdoc.sty. to use doc or print the docu- The following changes and additions mentation (although it is recom- have been made to the user interface mended); since the published version [5]. See §2 for more details. `Docstrip' modules are recognised and formatted specially. Driver mechanism \DocInput is now used in the driver file to input As well as adding some completely possibly multiple independent doc new stuff, the opportunity has been files and doc no longer has to be taken to add some commentary to the the last package. \IndexListing code formerly in newdoc.sty and that is replaced by \IndexInput; added after version 1.5k of doc.sty. Since (as noted in the sections con- Indexing is controlled by \PageIndex cerned) this commentary wasn't writ- and \CodelineIndex, one of ten by Frank Mittelbach but the code which must be specified to pro- was, it is probably not true in this case duce an index|there is no longer that \if the code and comments disagree a \makeindex in the default both are probably wrong"! \DocstyleParms; The macro environment now takes Bugs as argument the macro name with There are some known bugs in this ver- the backslash; sion: Verbatim text Newlines are now for- • The \DoNotIndex command bidden inside \verb and com- doesn't work for some single char- mands \MakeShortVerb and acter commands most noticeable \DeleteShortVerb are provided \%. for verbatim shorthand; • The `General changes' glossary \par can now be used in \DoNotIndex; entry would come out after macro 2 names with a leading ! and possi- Wish list bly a leading "; • Hooks to allow \DescribeMacro • If you have an old version of make- and \DescribeEnv to write out index long \changes entries will to a special file information about come out strangely and you may the package's `exported' defini- find the section header amalga- tions which they describe. This mated with the first changes en- could subsequently be included in try. Try to get an up-to-date one the docstripped .sty file in a (see p.9); suitable form for use by smart editors in command completion, • Because the accompanying make- spelling checking etc., based on index style files support the in- the packages used in a document. consistent attribute specifications This would need agreement on a of older and newer versions make- `suitable form'. index always complains about three `unknown specifier’s when • Indexing of the modules used in sorting the index and changes en- docstrip's %< directives. I'm not tries. sure how to index directives con- • If \MakeShortVerb and taining module combinations; \DeleteShortVerb are used with single character arguments, e.g., • Writing out bibliographic infor- mation about the package; {|} instead of {\|} chaos may happen. • Allow turning off use of the spe- (Some `features' are documented be- cial font for, say, the next guarded low.) block. 1 Introduction The TEX macros which are described tion was born with the development of here allow definitions and documenta- the TEX program; it was crystallized tion to be held in one and the same file. in Pascal with the Web system. The This has the advantage that normally advantages of this method are plain to very complicated instructions are made see (it's easy to make comparisons [2]). simpler to understand by comments in- Since this development, systems similar side the definition. In addition to this, to Web have been developed for other updates are easier and only one source programming languages. But for one file needs to be changed. On the other of the most complicated programming hand, because of this, the package files languages (TEX) the documentation has are considerably longer: thus TEX takes however been neglected. The TEX world longer to load them. If this is a prob- seems to be divided between:| lem, there is an easy remedy: one needs only to run the docstrip.tex program • a couple of \wizards", who pro- that removes nearly all lines that begin duce many lines of completely un- with a percent sign. readable code “off the cuff", and The idea of integrated documenta- • many users who are amazed that 3 it works just how they want it to ing point, but because from this start- do. Or rather, who despair that ing point it was the quickest to develop.2 certain macros refuse to do what As a result of this design decision, I had is expected of them. to move away from the concept of mod- I do not think that the Web sys- ularization; this was certainly a step tem is the reference work; on the con- backward. trary, it is a prototype which suffices I would be happy if this article could for the development of programs within spark off discussion overE T X docu- mentation. I can only advise anyone the TEX world. It is sufficient, but not totally sufficient.1 As a result who thinks that they can cope with- of Web, new programming perspec- out documentation to \Stop Time" un- tives have been demonstrated; unfortu- til he or she completely understands the nately, though, they haven't been de- AMS-TEX source code. veloped further for other programming languages. 1.1 Using the doc package The method of documentation of TEX macros which I have introduced Just like any other package, invoke it by here should also only be taken as a first requesting it with a \usepackage com- sketch. It is designed explicitly to run mand in the preamble. Doc's use of under LATEX alone. Not because I was of \reversemarginpars may make it in- the opinion that this was the best start- compatible with some classes. 2 The User Interface 2.1 The driver file If one is going to document a set of macros with the doc package one has to prepare a special driver file which produces the formatted document. This driver file has the following characteristics: \documentclass[hoptionsi]{hdocument-classi} \usepackage{doc} hpreamblei \begin{document} hspecial input commandsi \end{document} The hdocument-classi might be any document class, I normally use article. In the hpreamblei one should place declarations which manipulate the behavior of the doc package like \DisableCrossrefs or \OnlyDescription. \DocInput Finally the hspecial input commandsi part should contain one or more \IndexInput \DocInputhfile namei and/or \IndexInputhfile namei commands. The \DocInput command is used for files prepared for the doc package whereas \IndexInput can be used for all kinds of macro files. See page 11 for more details of \IndexInput. Multiple \DocInputs can be used with a number of included files 1I know that this will be seen differently by a few people, but this product should notbe seen as the finished product, at least as far as applications concerningE T X are concerned. The long-standing debate over `multiple change files’ shows this well.
Load more

Recommended publications
  • The Microsoft Office Open XML Formats New File Formats for “Office 12”
    The Microsoft Office Open XML Formats New File Formats for “Office 12” White Paper Published: June 2005 For the latest information, please see http://www.microsoft.com/office/wave12 Contents Introduction ...............................................................................................................................1 From .doc to .docx: a brief history of the Office file formats.................................................1 Benefits of the Microsoft Office Open XML Formats ................................................................2 Integration with Business Data .............................................................................................2 Openness and Transparency ...............................................................................................4 Robustness...........................................................................................................................7 Description of the Microsoft Office Open XML Format .............................................................9 Document Parts....................................................................................................................9 Microsoft Office Open XML Format specifications ...............................................................9 Compatibility with new file formats........................................................................................9 For more information ..............................................................................................................10
    [Show full text]
  • Background Information History, Licensing, and File Formats Copyright This Document Is Copyright © 2008 by Its Contributors As Listed in the Section Titled Authors
    Getting Started Guide Appendix B Background Information History, licensing, and file formats Copyright This document is Copyright © 2008 by its contributors as listed in the section titled Authors. You may distribute it and/or modify it under the terms of either the GNU General Public License, version 3 or later, or the Creative Commons Attribution License, version 3.0 or later. All trademarks within this guide belong to their legitimate owners. Authors Jean Hollis Weber Feedback Please direct any comments or suggestions about this document to: [email protected] Acknowledgments This Appendix includes material written by Richard Barnes and others for Chapter 1 of Getting Started with OpenOffice.org 2.x. Publication date and software version Published 13 October 2008. Based on OpenOffice.org 3.0. You can download an editable version of this document from http://oooauthors.org/en/authors/userguide3/published/ Contents Introduction...........................................................................................4 A short history of OpenOffice.org..........................................................4 The OpenOffice.org community.............................................................4 How is OpenOffice.org licensed?...........................................................5 What is “open source”?..........................................................................5 What is OpenDocument?........................................................................6 File formats OOo can open.....................................................................6
    [Show full text]
  • Sharing Files with Microsoft Office Users
    Sharing Files with Microsoft Office Users Title: Sharing Files with Microsoft Office Users: Version: 1.0 First edition: November 2004 Contents Overview.........................................................................................................................................iv Copyright and trademark information........................................................................................iv Feedback.................................................................................................................................... iv Acknowledgments......................................................................................................................iv Modifications and updates......................................................................................................... iv File formats...................................................................................................................................... 1 Bulk conversion............................................................................................................................... 1 Opening files....................................................................................................................................2 Opening text format files.............................................................................................................2 Opening spreadsheets..................................................................................................................2 Opening presentations.................................................................................................................2
    [Show full text]
  • Document Conversion Technical Manual Version: 10.3.0
    Kofax Communication Server KCS Document Conversion Technical Manual Version: 10.3.0 Date: 2019-12-13 © 2019 Kofax. All rights reserved. Kofax is a trademark of Kofax, Inc., registered in the U.S. and/or other countries. All other trademarks are the property of their respective owners. No part of this publication may be reproduced, stored, or transmitted in any form without the prior written permission of Kofax. Table of Contents Chapter 1: Preface...................................................................................................................................... 7 Purpose...............................................................................................................................................7 Third Party Licenses................................................................................................................7 Usage..................................................................................................................................................7 Feature Comparison (Links Versus TWS)......................................................................................... 8 Conversion Tools................................................................................................................................ 8 Imgio.......................................................................................................................................10 File Formats......................................................................................................................................10
    [Show full text]
  • Microsoft Office Word 2003 Rich Text Format (RTF) Specification White Paper Published: April 2004 Table of Contents
    Microsoft Office Word 2003 Rich Text Format (RTF) Specification White Paper Published: April 2004 Table of Contents Introduction......................................................................................................................................1 RTF Syntax.......................................................................................................................................2 Conventions of an RTF Reader.............................................................................................................4 Formal Syntax...................................................................................................................................5 Contents of an RTF File.......................................................................................................................6 Header.........................................................................................................................................6 Document Area............................................................................................................................29 East ASIAN Support........................................................................................................................142 Escaped Expressions...................................................................................................................142 Character Set.............................................................................................................................143 Character Mapping......................................................................................................................143
    [Show full text]
  • Microsoft Exchange 2007 Journaling Guide
    Microsoft Exchange 2007 Journaling Guide Digital Archives Updated on 12/9/2010 Document Information Microsoft Exchange 2007 Journaling Guide Published August, 2008 Iron Mountain Support Information U.S. 1.800.888.2774 [email protected] Copyright © 2008 Iron Mountain Incorporated. All Rights Reserved. Trademarks Iron Mountain and the design of the mountain are registered trademarks of Iron Mountain Incorporated. All other trademarks and registered trademarks are the property of their respective owners. Entities under license agreement: Please consult the Iron Mountain & Affiliates Copyright Notices by Country. Confidentiality CONFIDENTIAL AND PROPRIETARY INFORMATION OF IRON MOUNTAIN. The information set forth herein represents the confidential and proprietary information of Iron Mountain. Such information shall only be used for the express purpose authorized by Iron Mountain and shall not be published, communicated, disclosed or divulged to any person, firm, corporation or legal entity, directly or indirectly, or to any third person without the prior written consent of Iron Mountain. Disclaimer While Iron Mountain has made every effort to ensure the accuracy and completeness of this document, it assumes no responsibility for the consequences to users of any errors that may be contained herein. The information in this document is subject to change without notice and should not be considered a commitment by Iron Mountain. Iron Mountain Incorporated 745 Atlantic Avenue Boston, MA 02111 +1.800.934.0956 www.ironmountain.com/digital
    [Show full text]
  • Rastermaster® for Java™ V20.2 Programmer's Guide
    RasterMaster® for Java™ v20.2 Programmer’s Guide RasterMaster® is the industry’s leading document/image conversion and imaging library for Java. It is continually enhanced with new functionality and formats and was developed by Snowbound’s experts who have nearly a hundred years of combined imaging expertise. It provides High-Speed File Conversion as well as Extensive Format Support. This guide is designed to provide developers with a high-level overview of RasterMaster’s functionality and capabilities, including conceptual information as well as code samples. For the full API reference, please see the Javadocs included with your build or visit docs.snowbound.com/rastermaster/latest/java/rastermaster-api/. IMPORTANT NOTICE: The online version of this manual contains information on the latest updates to RasterMaster. To find the most recent version of this manual, please visit the online version at www.rastermaster.com or download the most recent version from our website at www.snowbound.com/support/manuals.html. Copyright Information While Snowbound® Software believes the information included in this publication is correct as of the publication date, information in this document is subject to change without notice. UNLESS EXPRESSLY SET FORTH IN A WRITTEN AGREEMENT SIGNED BY AN AUTHORIZED REPRESENTATIVE OF SNOWBOUND SOFTWARE CORPORATION MAKES NO WARRANTY OR REPRESENTATION OF ANY KIND WITH RESPECT TO THE INFORMATION CONTAINED HEREIN, INCLUDING WARRANTY OF MERCHANTABILITY AND FITNESS FOR A PURPOSE, NON-INFRINGEMENT, OR THOSE WHICH MAY BE IMPLIED THROUGH COURSE OF DEALING OR CUSTOM OF TRADE. WITHOUT LIMITING THE FOREGOING, CUSTOMER UNDERSTANDS THAT SNOWBOUND DOES NOT WARRANT THAT CUSTOMER’S OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, THAT ALL DEFECTS IN THE SOFTWARE WILL BE CORRECTED, OR THAT THE RESULTS OF THE SOFTWARE WILL BE ERROR-FREE.
    [Show full text]
  • Office File Formats Overview
    Office File Formats Overview Tom Jebo Sr Escalation Engineer Agenda • Microsoft Office Supported Formats • Open Specifications File Format Documents and Resources • Benefits of broadly-adopted standards • Microsoft Office Extensibility • OOXML Format Overview Microsoft Office 2016 File Format Support • Office Open XML (.docx, .xlsx, .pptx) • Microsoft Office Binary Formats (.doc, .xls, .ppt) (legacy) • OpenDocument Format (.odt, .ods, .odp) • Portable Document Format (.pdf) • Open XML Paper Specification (.xps) Microsoft File Formats Documents and Resources File Format Related Documents • Documentation Intro & Reference Binary Formats Standards • https://msdn.microsoft.com/en- [MS-OFFDI] [MS-DOC] [MS-DOCX] us/library/gg134029.aspx [MS-OFCGLOS] [MS-XLS] [MS-XLSX] [MS-OFREF] [MS-XLSB] [MS-PPTX] • [MS-OFFDI] start here [MS-OSHARED] [MS-PPT] [MS-OE376] • Standards implementation notes [MS-OFFCRYPTO] [MS-OI29500] • File format documentation Macros [MS-OODF] OneNote [MS-OFFMACRO] [MS-OODF2] • SharePoint & Exchange/Outlook client-server protocols [MS-ONE] [MS-OFFMACRO2] [MS-OODF3] • Windows client and server protocols [MS-ONESTORE] [MS-OVBA] [MS-ODRAWXML] • .NET Framework Office Drawing/Graphics Other • XAML Customization [MS-CTDOC] [MS-ODRAW] [MS-DSEXPORT] • Support [MS-CTXLS] [MS-OGRAPH] [MS-ODCFF] [MS-CUSTOMUI] [MS-OFORMS] • [email protected] [MS-CUSTOMUI2] [MS-WORDLFF] • MSDN Open Specifications forums [MS-OWEMXML] Outlook [MS-XLDM] [MS-PST] [MS-3DMDTP] Reviewing Binary Formats • CFB – [MS-CFB] storages and streams Binary Formats • Drawing
    [Show full text]
  • How to Create Accessible Documents in Microsoft Office (Word, Powerpoint Or Excel) Or Google Doc
    How to Create Accessible Documents in Microsoft Office (Word, PowerPoint or Excel) or Google Doc Microsoft Word application is commonly used among individuals with and without disabilities, and it has accessibility features. The following part provides information to guide you to build accessible documents in Microsoft Word. Those steps are applicable in other Microsoft Office (PowerPoint or Excel) and Google Doc as well. The major components include use of Font, ​ ​ Headings, Lists, Meaningful Hyperlinks, Alternate Text for Images, Table, and Document ​ ​ ​ ​ ​ ​ ​ ​ ​ ​ Language Identification. ​ ❖ Use Sans Serif Fonts ​ ➢ Sans serif fonts (Helvetica, Arial, Verdana, Calibri, Comic Sans, and Geneva) are easier to read by digital, for learners with dyslexia ➢ Serif fonts (i.e., Times New Roman) are easier to read in print ➢ Suggest the use of an 11- or 12-point font size ❖ Use Headings to Organize the Document Instead of Manual Formatting ​ ​ ➢ Point your mouse to Home tab ➢ Find and click on Styles ➢ Use the built-in Heading styles, such as “Heading 1” (as the main heading) and “Heading 2” (as subheadings) ➢ The default, light blue, can be hard to read and is not accessible. Use the right mouse button to click on Heading 1, select Modify, and change the color of the heading from blue to black ➢ Change the default font from Calibri to any other san serif font, select a different size, or select bold; the American Federation for the Blind suggests, “Use bold. Avoid using italics or all capital letters.” ➢ Form an outline with headings ➢ With additional levels of headings within the document’s outline, use “Heading 3”, “Heading 4”, etc.
    [Show full text]
  • File Formatsformats
    FILEFILE FORMATSFORMATS Summary records created or formatted electronically are Rapid changes in technology mean that file formats covered under the act. can become obsolete quickly and cause problems for Proprietary, Non-proprietary, Open your records management strategy. A long-term view Standard and Open Source File Formats and careful planning can overcome this risk and ◆ ensure that you can meet your legal and operational Proprietary formats. Proprietary file formats are requirements. controlled and supported by just one software developer. Microsoft Word (.DOC) format is an Legally, your records must be trustworthy, complete, example. accessible, admissible in court, and durable for as ◆ Non-proprietary formats. These formats are long as your approved records retention schedules supported by more than one developer and can require. For example, you can convert a record to be accessed with different software systems. For another, more durable format (e.g., from a nearly example, eXtensible Markup Language (XML) is obsolete software program to a text file). That copy, becoming an increasingly popular non-proprietary as long as it is created in a trustworthy manner, is format. legally acceptable. ◆ Open Source formats. In general, open source The software in which a file is created usually has a refers to any program whose source code is made default format, often indicated by a file name suffix available for use or modification as users or other (e.g., *.PDF for portable document format). Most developers see fit. Open source software may be software allows authors to select from a variety of developed, modified and distributed by formats when they save a file (e.g., document independent software companies for profit.
    [Show full text]
  • An Introduction to R Notes on R: a Programming Environment for Data Analysis and Graphics Version 4.1.1 (2021-08-10)
    An Introduction to R Notes on R: A Programming Environment for Data Analysis and Graphics Version 4.1.1 (2021-08-10) W. N. Venables, D. M. Smith and the R Core Team This manual is for R, version 4.1.1 (2021-08-10). Copyright c 1990 W. N. Venables Copyright c 1992 W. N. Venables & D. M. Smith Copyright c 1997 R. Gentleman & R. Ihaka Copyright c 1997, 1998 M. Maechler Copyright c 1999{2021 R Core Team Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into an- other language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the R Core Team. i Table of Contents Preface :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 1 1 Introduction and preliminaries :::::::::::::::::::::::::::::::: 2 1.1 The R environment :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 2 1.2 Related software and documentation ::::::::::::::::::::::::::::::::::::::::::::::: 2 1.3 R and statistics :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 2 1.4 R and the window system ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    [Show full text]
  • Openoffice.Org User Guide for Version 2.X
    OpenOffice.org User Guide for Version 2.x [OpenOffice.org User Guide for 2.x] [0.2] First edition: [2005-04-11] First English edition: [2005-04-11] Copyright and trademark information The contents of this Documentation are subject to the Public Documentation License, Version 1.0 (the "License"); you may only use this Documentation if you comply with the terms of this License. A copy of the License is available at: http://www.openoffice.org/licenses/PDL.rtf. The Original Documentation is ªOpenOffice.org User Guide for Version 2.xº. Contributor(s): G. Roderick Singleton. Portions created by G. Roderick Singleton are Copyright © 2005, 2006. All Rights Reserved. All trademarks within this guide belong to legitimate owners. [Note: a copy of the PDL is included in this template and is also available at: http://www.openoffice.org/licenses/PDL.rtf.] Feedback Please direct any comments or suggestions about this document to: [email protected] Acknowledgements I wish to recognize the Technical Writers of Sun Microsystems for the fine model they have provided for organizing this document. I also wish to thank Erwin Tenhumberg for his blog, Mary Ellen Dawley for her indexing effort, Ross Johnson for his editing/correctionsand manitoban for the docking text in chapter 2. Modifications and updates Version Date Description of Change [0.9] [2005-11-11] [grs: 9th draft issued for comment ± switched to master doc, stewart©s amendments and added a chapter on XML usage (flat file)] [0.10] [2005-11-11] [grs: 10th draft issued for comment ± fix page numbering [0.11] [2006-01-31] [grs:11th draft issued for comment ± updated index [0.12a] [2006-02-20] [rj: 12th draft issued for comment ± corrections for 2.0 to replace 1.1.x references [0.13] [2006-02-21] [grs 13th draft issued for comment ± integrated Ross Johnson©s changes and edited for consistent grammar.
    [Show full text]