1 10/17/81 Documentation macros
2
3 A set of compose documentation macros is available for general use.
4 These macros may be a useful tool for users doing online documentation.
5 The macros do such things as page formatting, generation of page
6 headers and footers, font selection for section and paragraph titles,
7 spacing, and generating a Table of Contents - all automatically.
8
9 Each macro is 'called' by inserting one line in a compin segment. The
10 desired result is produced when the segment is composed. Type "help
11 compose" for information on compose as compose knowledge is necessary
12 in order to use these macros effectively. The macros follow current
13 Honeywell standards and specific Multics documentation format rules.
14
15
16 WARNING:
17 These macros are dynamic and are changed from time to time to provide
18 new features and to take advantage of new features in compose. Users
19 who make copies in order to obtain their own format are warned to check
20 each macro installation with compare_ascii to discover necessary
21 updates to their private copies.
22
23 This info segment briefly describes the actions of the various macros
24 and lists the macros according to function general purpose figure and
25 table addenda or miscellaneous. More detailed information on a
26 specific macro can be found in the info segment for that macro e.g.
27 if you want information on preface type "help preface.compin".
28
29
30 Macro Actions:
31 1. provide standard spacing around paragraph titles e.g 2 spaces
32 above and 1 below for standard size page; see init.compin.info for
33 more information
34 2. generate proper formatting of section and paragraph title, based on
35 the following Honeywell standard:
36 Level 0: typed - full caps, centered, new page
37 photoset - 18 pt Century Schoolbook Bold Italic,
38 initial caps, flush right, new page
39 Level 1: typed - full caps, underlined, flush left
40 photoset - 10 pt Helvetica Bold Roman, full caps,
41 flush left
42 Level 2: typed - initial caps, underlined, flush left
43 photoset - 10 pt Helvetica Bold Italic, full caps,
44 flush left
45 Level 3: typed - full caps, flush left
46 photoset - 10 pt Helvetica Roman, full caps,
47 flush left
48 Level 4: typed - initial caps, flush left
49 photoset - 10 pt Helvetica Medium Italic,
50 initial caps, flush left
51
52
53 3. assure sufficient space on current page for new paragraph title and
54 related text
55 4. generate Table of Contents automatically, based on heading level
56 macros used
57 5. generate page footers
58 6. generate page headers for command or subroutine descriptions
59 identified as 'module' text in macros; see l1h.compin.info for more
60 information on modules
61 7. generate table header and figure caption titles with proper spacing
62 between title and item
63 8. keep a table counter and a figure counter so the number in the title
64 is incremented automatically and user can make references without
65 knowing the actual number of the table or figure
66
67
68 9. generate a list of Tables and a list of Illustrations for the Table
69 of Contents segments automatically, based on the table and figure
70 macros used
71 10.generate dot pages for addenda e.g. pages 2.1 and 2.2 between
72 existing pages 2 and 3; see dot_page.compin.info for further
73 information
74 11.show command arguments and control arguments, and subsystem
75 requests, using 10pt Helvetica Medium for literal fields and 10pt
76 Helvetica Bold Italic for variable fields.
77
78
79 Title splitting:
80 All titles can be made to break at points of the users choice by
81 inserting exclamation points !^? where the breaks are to occur. The
82 exclamation points are removed from Table of Contents entries and do
83 not affect the splitting of such entries. If no exclamation points are
84 used, the titles will be split according the current line measure.
85
86
87 General purpose macros:
88 init, init_mpm, init_plm
89 initialize macro environment one of these should be used before
90 any other macros are used i.e. easiest to have an 'init' macro
91 as the first line in each segment in which the user wants to use
92 other macros
93 l0h
94 generate section heading; initialize Table of Contents for new
95 section
96 l1h, l2h, l3h, l4h
97 generate paragraph headings including 'module' page headers; see
98 l1h.compin.info for more information; generate Table of Contents
99 entries
100 l1hbox, l2hbox, l3hbox, l4hbox
101 generate 'box' page headers as for 'module' text above
102
103
104 l0exact, l2exact, l2exact, l3exact, l4exact
105 l0toc, l1toc, l2toc, l3toc, l4toc
106 generate section and paragraph headings that contain special
107 strings i.e. strings that are exceptions to the font selection
108 rules above; generate Table of Contents entries that contain
109 special strings
110 l0setup, l1setup, l2setup, l3setup, l4setup
111 generate page headers and footers so module segments can be output
112 properly without beginning on first page only needed for 'module'
113 text; see l1h.compin.info for more information on modules
114 toc_on
115 turn on Table of Contents generation
116 active_function
117 place a title reading "SYNTAX AS AN ACTIVE FUNCTION" and show an
118 active function syntax line.
119
120
121 argument
122 show the syntax of a command argument.
123 argument_list
124 place a title reading "ARGUMENTS".
125 bullet
126 place a bullet hanging left by one indentation level.
127 command
128 place a title reading "SYNTAX AS A COMMAND" and show a command
129 syntax line.
130 controlargument
131 show the syntax of a control argument.
132 controlargument_list
133 place a title reading "CONTROL ARGUMENTS".
134 example, example_off
135 control the generation of an example terminal session contained in
136 a ruled box.
137
138
139 example_line_number
140 place a local reference line number hanging left by one
141 indentation level and advance the count of such line numbers.
142 examples
143 place a title reading "EXAMPLES".
144 message
145 show a system output message in ASCII.
146 module
147 begin a new level 2 section for a new program module.
148 par
149 begin new paragraph with first line indented one indentation
150 level.
151 par_flush
152 begin new paragraph with first line flush to left margin.
153
154
155 par_hanging
156 begin new paragraph with first line hanging to the left by one
157 indentation level.
158 request_list
159 place a title reading "REQUESTS".
160 request
161 show a subsystem request syntax line.
162 slug_off
163 cancel any existing page header particularly box headers.
164
165
166 Figure and table macros:
167 fig_on, tab_on
168 turn on list of Illustrations/Tables generation
169 fig, tab
170 reset 'dot' number counter, advance figure/table counter, generate
171 centered Figure caption/Tableheader, generate list of
172 Illustrations/Tables entry.
173 dot_fig, dot_tab
174 create or advance 'dot' number figure/table counter, generate
175 centered Figure caption/Table header, generate list of
176 Illustrations/Tables entry.
177
178
179 fig_index, tab_index
180 advance figure/table counter, generate List of
181 Illustrations/Tables entry
182 dot_fig_index, dot_tab_index
183 advance 'dot' number figure/table counter, generate List of
184 Illustrations/Tables entry
185 fig_get_no, tab_get_no
186 reference a figure/table other than the current one
187 dot_fig_get_no, dot_tab_get_no
188 reference a 'dot' number figure/table other than the current one
189
190
191 Addenda macros:
192 dot_page, dot_page_off
193 begin/end a set of addendum pages with page numbers of the form
194 <page_count>.<addendum_page_count> e.g. 3.1 or
195 <section_number>-<page_count>.<addendum_page_count> e.g. 5-3.1
196
197
198 collating, coll_page, coll_cont
199 generate collating instruction pages, including special footers
200 Collating pages consist of instructions for removing and adding
201 pages in addendum.
202
203
204 Miscellaneous macros:
205 preface, pf, pf_cont
206 generate preface pages, including special footers
207 l1mh, l2mh, l3mh, l4mh
208 generate midpage paragraph titles for 'module' text; generate
209 Table of Contents entry
210 l1mhbox, l2mhbox, l3mhbox, l4mhbox
211 generate midpage 'box' paragraph titles and page headers as for
212 'module' text above
213
214
215 l0setup, l1setup, l2setup, l3setup, l4setup
216 perform all environment and 'side effect' processing as for the
217 equivalent level header macro above, but DO NOT emit title lines
218 or Table of Contents entries.
219 index_line.toc
220 generates a Table of Contents entry for the cross reference index
221
222
223 Special words:
224 There are many special words used thoughout the macros. Anyone writing
225 variations of these macros or separate macros that will be used with
226 the documentation macros must be aware of these special words.
227
228 User interface words:
229 add_date draft_date
230 add_letter section
231 draft style
232
233
234 Macro entryname words:
235 break_title fig_get_no
236 coll_cont fig_header
237 coll_page fig_index
238 collating fig_on
239 conditional_bar_3 index_line.toc
240 conditional_bar_4 init
241 conditional_bar_5 init_module_layout
242 conditional_bar_6 init_mpm
243 conditional_bar_7 init_plm
244 conditional_bar_8 init_prose_layout
245 conditional_bar_9 l0exact
246 conditional_space_1 l0h
247 conditional_space_2 l0setup
248 conditional_space_3 l0toc
249 conditional_space_4 l1exact
250 conditional_space_5 l1h
251 dot_page l1hbox
252 dot_page_off l1mh
253 exact_output l1mhbox
254 fig l1setup
255
256
257 l1toc l4toc
258 l2exact macro_util
259 l2h mpm_module_layout
260 l2hbox mpm_prose_layout
261 l2mh output
262 l2mhbox pf
263 l2setup pf_cont
264 l2toc plm_module_layout
265 l3exact plm_prose_layout
266 l3h preface
267 l3hbox setbox
268 l3mh split_title
269 l3mhbox tab
270 l3setup tab_get_no
271 l3toc tab_header
272 l4exact tab_index
273 l4h tab_on
274 l4hbox toc
275 l4mh toc_header
276 l4mhbox toc_on
277 l4setup
278
279
280 Internal words:
281 In this list "*" can take on any numeric value.
282 ADD_DATE LAYOUT
283 ADD_LETTER LENGTH
284 BLANK LEVEL
285 BOX_LENGTH LEVEL_FILL
286 BOX_LINE LEVEL_SIZE
287 BOX_WORD* LSN
288 BREAKER MACRO_INIT
289 COLON_INDEX MARK
290 DOCUMENT_TYPE MH
291 DOT_PAGE MHBOX
292 DotAddLetter MPM_SPACE
293 ENTRY NEXT_FIG_NO
294 FIGING NEXT_FIG_TITLE
295 FIGURE_COUNT NEXT_TAB_NO
296 FIGURE_IN_TOC NEXT_TAB_TITLE
297 FIGURE_SECTION ORDER_NUMBER
298 FONT PAGENO_SET
299 HALF PAGE_TAB
300
301
302 PART_LENGTH add_date
303 SECTION add_letter
304 SECTION_INDENT draft
305 SECTION_IN_TOC draft_date
306 SECTION_MARK figure
307 TABING figure_title
308 TABLE_COUNT figure_title*
309 TABLE_IN_TOC figure_title*L
310 TABLE_SECTION figure_titleI
311 TEXT_TYPE figure_titleL
312 THIS_FRONT figure_titleN
313 TITLE section
314 TITLE* style
315 TITLE1 table
316 TITLEI table_title
317 TITLEN table_title*
318 TOCING table_title*L
319 TOC_ENTRY table_titleI
320 TOC_PAGE_WIDTH table_titleL
321 TOC_REF table_titleN
322
323 END