10/17/81 Documentation macros A set of compose documentation macros is available for general use. These macros may be a useful tool for users doing online documentation. The macros do such things as page formatting, generation of page headers and footers, font selection for section and paragraph titles, spacing, and generating a Table of Contents - all automatically. Each macro is 'called' by inserting one line in a compin segment. The desired result is produced when the segment is composed. (Type "help compose" for information on compose as compose knowledge is necessary in order to use these macros effectively.) The macros follow current Honeywell standards and specific Multics documentation format rules. WARNING: These macros are dynamic and are changed from time to time to provide new features and to take advantage of new features in compose. Users who make copies in order to obtain their own format are warned to check each macro installation (with compare_ascii) to discover necessary updates to their private copies. This info segment briefly describes the actions of the various macros and lists the macros according to function (general purpose, figure and table, addenda, or miscellaneous). More detailed information on a specific macro can be found in the info segment for that macro (e.g., if you want information on preface, type "help preface.compin"). Macro Actions: 1. provide standard spacing around paragraph titles (e.g, 2 spaces above and 1 below for standard size page; see init.compin.info for more information) 2. generate proper formatting of section and paragraph title, based on the following Honeywell standard: Level 0: typed - full caps, centered, new page photoset - 18 pt Century Schoolbook Bold Italic, initial caps, flush right, new page Level 1: typed - full caps, underlined, flush left photoset - 10 pt Helvetica Bold Roman, full caps, flush left Level 2: typed - initial caps, underlined, flush left photoset - 10 pt Helvetica Bold Italic, full caps, flush left Level 3: typed - full caps, flush left photoset - 10 pt Helvetica Roman, full caps, flush left Level 4: typed - initial caps, flush left photoset - 10 pt Helvetica Medium Italic, initial caps, flush left 3. assure sufficient space on current page for new paragraph title and related text 4. generate Table of Contents automatically, based on heading level macros used 5. generate page footers 6. generate page headers for command or subroutine descriptions (identified as 'module' text in macros; see l1h.compin.info for more information on modules) 7. generate table header and figure caption titles with proper spacing between title and item 8. keep a table counter and a figure counter so the number in the title is incremented automatically and user can make references without knowing the actual number of the table or figure 9. generate a list of Tables and a list of Illustrations for the Table of Contents segments automatically, based on the table and figure macros used 10.generate dot pages for addenda (e.g., pages 2.1 and 2.2 between existing pages 2 and 3; see dot_page.compin.info for further information) 11.show command arguments and control arguments, and subsystem requests, using 10pt Helvetica Medium for literal fields and 10pt Helvetica Bold Italic for variable fields. Title splitting: All titles can be made to break at points of the users choice by inserting exclamation points (!) where the breaks are to occur. The exclamation points are removed from Table of Contents entries and do not affect the splitting of such entries. If no exclamation points are used, the titles will be split according the current line measure. General purpose macros: init, init_mpm, init_plm initialize macro environment (one of these should be used before any other macros are used, i.e., easiest to have an 'init' macro as the first line in each segment in which the user wants to use other macros) l0h generate section heading; initialize Table of Contents for new section l1h, l2h, l3h, l4h generate paragraph headings (including 'module' page headers; see l1h.compin.info for more information); generate Table of Contents entries l1hbox, l2hbox, l3hbox, l4hbox generate 'box' page headers as for 'module' text above l0exact, l2exact, l2exact, l3exact, l4exact l0toc, l1toc, l2toc, l3toc, l4toc generate section and paragraph headings that contain special strings (i.e., strings that are exceptions to the font selection rules above); generate Table of Contents entries that contain special strings l0setup, l1setup, l2setup, l3setup, l4setup generate page headers and footers so module segments can be output properly without beginning on first page (only needed for 'module' text; see l1h.compin.info for more information on modules) toc_on turn on Table of Contents generation active_function place a title reading "SYNTAX AS AN ACTIVE FUNCTION" and show an active function syntax line. argument show the syntax of a command argument. argument_list place a title reading "ARGUMENTS". bullet place a bullet hanging left by one indentation level. command place a title reading "SYNTAX AS A COMMAND" and show a command syntax line. controlargument show the syntax of a control argument. controlargument_list place a title reading "CONTROL ARGUMENTS". example, example_off control the generation of an example terminal session contained in a ruled box. example_line_number place a local reference line number hanging left by one indentation level and advance the count of such line numbers. examples place a title reading "EXAMPLES". message show a system output message in ASCII. module begin a new level 2 section for a new program module. par begin new paragraph with first line indented one indentation level. par_flush begin new paragraph with first line flush to left margin. par_hanging begin new paragraph with first line hanging to the left by one indentation level. request_list place a title reading "REQUESTS". request show a subsystem request syntax line. slug_off cancel any existing page header (particularly, box headers). Figure and table macros: fig_on, tab_on turn on list of Illustrations/Tables generation fig, tab reset 'dot' number counter, advance figure/table counter, generate centered Figure caption/Tableheader, generate list of Illustrations/Tables entry. dot_fig, dot_tab create or advance 'dot' number figure/table counter, generate centered Figure caption/Table header, generate list of Illustrations/Tables entry. fig_index, tab_index advance figure/table counter, generate List of Illustrations/Tables entry dot_fig_index, dot_tab_index advance 'dot' number figure/table counter, generate List of Illustrations/Tables entry fig_get_no, tab_get_no reference a figure/table other than the current one dot_fig_get_no, dot_tab_get_no reference a 'dot' number figure/table other than the current one Addenda macros: dot_page, dot_page_off begin/end a set of addendum pages with page numbers of the form . (e.g., 3.1) or -. (e.g., 5-3.1) collating, coll_page, coll_cont generate collating instruction page(s), including special footers (Collating pages consist of instructions for removing and adding pages in addendum.) Miscellaneous macros: preface, pf, pf_cont generate preface page(s), including special footers l1mh, l2mh, l3mh, l4mh generate midpage paragraph titles for 'module' text; generate Table of Contents entry l1mhbox, l2mhbox, l3mhbox, l4mhbox generate midpage 'box' paragraph titles and page headers as for 'module' text above l0setup, l1setup, l2setup, l3setup, l4setup perform all environment and 'side effect' processing as for the equivalent level header macro above, but DO NOT emit title lines or Table of Contents entries. index_line.toc generates a Table of Contents entry for the cross reference index Special words: There are many special words used thoughout the macros. Anyone writing variations of these macros or separate macros that will be used with the documentation macros must be aware of these special words. User interface words: add_date draft_date add_letter section draft style Macro entryname words: break_title fig_get_no coll_cont fig_header coll_page fig_index collating fig_on conditional_bar_3 index_line.toc conditional_bar_4 init conditional_bar_5 init_module_layout conditional_bar_6 init_mpm conditional_bar_7 init_plm conditional_bar_8 init_prose_layout conditional_bar_9 l0exact conditional_space_1 l0h conditional_space_2 l0setup conditional_space_3 l0toc conditional_space_4 l1exact conditional_space_5 l1h dot_page l1hbox dot_page_off l1mh exact_output l1mhbox fig l1setup l1toc l4toc l2exact macro_util l2h mpm_module_layout l2hbox mpm_prose_layout l2mh output l2mhbox pf l2setup pf_cont l2toc plm_module_layout l3exact plm_prose_layout l3h preface l3hbox setbox l3mh split_title l3mhbox tab l3setup tab_get_no l3toc tab_header l4exact tab_index l4h tab_on l4hbox toc l4mh toc_header l4mhbox toc_on l4setup Internal words: (In this list, "*" can take on any numeric value.) ADD_DATE LAYOUT ADD_LETTER LENGTH BLANK LEVEL BOX_LENGTH LEVEL_FILL BOX_LINE LEVEL_SIZE BOX_WORD* LSN BREAKER MACRO_INIT COLON_INDEX MARK DOCUMENT_TYPE MH DOT_PAGE MHBOX DotAddLetter MPM_SPACE ENTRY NEXT_FIG_NO FIGING NEXT_FIG_TITLE FIGURE_COUNT NEXT_TAB_NO FIGURE_IN_TOC NEXT_TAB_TITLE FIGURE_SECTION ORDER_NUMBER FONT PAGENO_SET HALF PAGE_TAB PART_LENGTH add_date SECTION add_letter SECTION_INDENT draft SECTION_IN_TOC draft_date SECTION_MARK figure TABING figure_title TABLE_COUNT figure_title* TABLE_IN_TOC figure_title*L TABLE_SECTION figure_titleI TEXT_TYPE figure_titleL THIS_FRONT figure_titleN TITLE section TITLE* style TITLE1 table TITLEI table_title TITLEN table_title* TOCING table_title*L TOC_ENTRY table_titleI TOC_PAGE_WIDTH table_titleL TOC_REF table_titleN (END) ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved