Debian Codegraph @

upstream/debian-trixie/man7/groff_me.7

raw
1 '\" t
2 .TH groff_me 7 "3 June 2025" "groff 1.23.0"
3 .SH Name
4 groff_me \- \(lqme\(rq macro package for formatting
5 .I roff
6 documents
7 .
8 .
9 .\" ====================================================================
10 .\" Legal Terms
11 .\" ====================================================================
12 .\"
13 .\" Copyright (C) 1980, 1993
14 .\" The Regents of the University of California. All rights reserved.
15 .\"
16 .\" Redistribution and use in source and binary forms, with or without
17 .\" modification, are permitted provided that the following conditions
18 .\" are met:
19 .\" 1. Redistributions of source code must retain the above copyright
20 .\" notice, this list of conditions and the following disclaimer.
21 .\" 2. Redistributions in binary form must reproduce the above copyright
22 .\" notice, this list of conditions and the following disclaimer in
23 .\" the documentation and/or other materials provided with the
24 .\" distribution.
25 .\" 3. [Deleted. See
26 .\" ftp://ftp.cs.berkeley.edu/pub/4bsd/README.Impt.License.Change]
27 .\" 4. Neither the name of the University nor the names of its
28 .\" contributors may be used to endorse or promote products derived
29 .\" from this software without specific prior written permission.
30 .\"
31 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS IS"
32 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
33 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
34 .\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
35 .\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
36 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
37 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
38 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
39 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
40 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
41 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
42 .\" SUCH DAMAGE.
43 .\"
44 .\" @(#)me.7 8.1 (Berkeley) 06/05/93
45 .\"
46 .\" Modified for groff by [email protected]
47 .\" Changed to use TBL and eliminate low-level troff hackery by ESR
48 .\" (this enables it to be lifted to structural markup).
49 .
50 .
51 .\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
52 .do nr *groff_groff_me_7_man_C \n[.cp]
53 .cp 0
54 .
55 .\" Define fallback for groff 1.23's MR macro if the system lacks it.
56 .nr do-fallback 0
57 .if !\n(.f .nr do-fallback 1 \" mandoc
58 .if \n(.g .if !d MR .nr do-fallback 1 \" older groff
59 .if !\n(.g .nr do-fallback 1 \" non-groff *roff
60 .if \n[do-fallback] \{\
61 . de MR
62 . ie \\n(.$=1 \
63 . I \%\\$1
64 . el \
65 . IR \%\\$1 (\\$2)\\$3
66 . .
67 .\}
68 .rr do-fallback
69 .
70 .
71 .\" ====================================================================
72 .SH Synopsis
73 .\" ====================================================================
74 .
75 .SY "groff \-me"
76 .RI [ option\~ .\|.\|.\&]
77 .RI [ file\~ .\|.\|.]
78 .
79 .SY "groff \-m me"
80 .RI [ option\~ .\|.\|.\&]
81 .RI [ file\~ .\|.\|.]
82 .YS
83 .
84 .
85 .\" ====================================================================
86 .SH Description
87 .\" ====================================================================
88 .
89 The GNU implementation of the
90 .I me
91 macro package is part of the
92 .I groff
93 document formatting system.
94 .
95 The
96 .I me
97 package of macro definitions for the
98 .I roff
99 language provides a convenient facility for preparing technical papers
100 in various formats.
101 .
102 This version is based on the
103 .I me
104 distributed with 4.4BSD and can be used with the GNU
105 .I troff
106 formatter as well as those descended from AT&T
107 .IR troff .
108 .
109 .
110 .P
111 Some formatter requests affect page layout unpredictably when used in
112 conjunction with this package;
113 however,
114 the following may be used with impunity after the first call to a
115 paragraphing macro like
116 .B lp
117 or
118 .BR pp .
119 .
120 Some arguments are optional;
121 see
122 .MR groff 7
123 for details,
124 particularly of requests whose argument list is designated with an
125 ellipsis.
126 .
127 An asterisk
128 .B *
129 marks
130 .I groff
131 extensions.
132 .
133 .
134 .P
135 .TS
136 Lb1 Li L.
137 ad c set text adjustment mode to \fIc
138 af r f assign format \fIf\fP to register \fIr
139 am m e append to macro \fIm\fP until \fIe\fP called
140 as s t append rest of line \fIt\fP to string \fIs
141 bp n begin new page numbered \fIn
142 br \& break output line
143 ce n center next \fIn\fP output lines
144 cp n en-/disable AT&T \fItroff\fP compatibility mode\fB*
145 de m e define macro \fIm\fP until \fIe\fP called
146 do t interpret input \fIt\fP with compatibility mode off\fB*
147 ds s t define rest of line \fIt\fP as string \fIs
148 el t interpret \fIt\fP if corresponding \fBie\fP false
149 fc c d set field delimiter \fIc\fP and padding glyph \fId
150 fi \& enable filling
151 hc c set hyphenation character to \fIc
152 hy m set automatic hyphenation mode to \fIm
153 ie p t as \fBif\fP, but enable interpretation of later \fBel
154 if p t if condition \fIp\/\fP, interpret rest of line \fIt
155 in h set indentation to distance \fIh\fP
156 lc c set leader repetition glyph to \fIc
157 ls n set line spacing to \fIn
158 mc c h set (right) margin glyph to \fIc\fP at distance \fIh
159 mk r mark vertical position in register \fIr\fP
160 na \& disable adjustment of text
161 ne v need vertical space of distance \fIv
162 nf \& disable filling
163 nh \& disable automatic hyphenation
164 nr r n i assign register \fIr\fP value \fIn\fP with \
165 auto-increment \fIi
166 ns \& begin no-space mode
167 pl v set page length to \fIv
168 pn n set next page number to \fIn
169 po h set page offset to \fIh
170 rj n right-align next \fIn\fP output lines\fB*
171 rm m remove macro, string, or request \fIm
172 rn m n rename macro, string, or request \fIm\fP to \fIn
173 rr r remove register \fIr
174 rs \& resume spacing (end no-space mode)
175 rt v return to vertical position set by \fBmk\fP, or \fIv
176 so f source (interpolate) input file \fIf
177 sp n insert \fIn\fP lines of vertical space
178 ta \fR.\|.\|. set tab stops
179 tc c set tab repetition glyph to \fIc
180 ti h set temporary indentation (next line only) to \fIh
181 tl \fR.\|.\|. output three-part title
182 tr \fR.\|.\|. translate characters
183 ul n underline next \fIn\fP output lines
184 .TE
185 .
186 .
187 .P
188 Except on title pages
189 (produced by calling
190 .BR tp ),
191 .I me
192 suppresses the output of vertical space at the tops of pages
193 (after the output of any page header);
194 the
195 .B sp
196 request will thus not work there.
197 .
198 You can instead call
199 .B bl
200 or enclose the desired spacing request in a diversion,
201 for instance by calling
202 .B (b
203 and
204 .BR )b .
205 .
206 .I me
207 also intercepts the
208 .B ll
209 request;
210 see the
211 .RI \[lq] me
212 Reference Manual\[rq]
213 for details.
214 .
215 .
216 .\" ====================================================================
217 .SS "Name space"
218 .\" ====================================================================
219 .
220 Objects in
221 .I me
222 follow a rigid naming convention.
223 .
224 To avoid conflict,
225 any user-defined register,
226 string,
227 or macro
228 names should be single numerals or uppercase letters,
229 or any longer sequence of letters and numerals
230 with at least one uppercase letter.
231 .
232 (For portability between BSD and
233 .I groff
234 .IR me ,
235 limit names to
236 two characters,
237 and avoid the name
238 .B [
239 (left square bracket).)
240 .
241 The names employed
242 by any preprocessors in use
243 should also not be repurposed.
244 .
245 .
246 .\" ====================================================================
247 .SS Macros
248 .\" ====================================================================
249 .
250 .ne 2v \" Keep at least the first entry together with the heading.
251 .TS
252 Lb L.
253 $0 post-section heading hook
254 $1 pre-section depth 1 hook
255 $2 pre-section depth 2 hook
256 $3 pre-section depth 3 hook
257 $4 pre-section depth 4 hook
258 $5 pre-section depth 5 hook
259 $6 pre-section depth 6 hook
260 $C post-chapter title hook
261 $H page/column heading hook
262 $c output chapter number and title
263 $f output footer
264 $h output header
265 $p output section heading
266 $s output footnote area separator
267 (b begin block
268 (c begin centered block
269 (d begin delayed text
270 (f begin footnote
271 (l begin list
272 (q begin long quotation
273 (x begin index entry
274 (z begin floating keep
275 )b end block
276 )c end centered block
277 )d end delayed text
278 )f end footnote
279 )l end list
280 )q end long quotation
281 )x end index entry
282 )z end floating keep
283 ++ set document segment type
284 +c begin chapter
285 1c end multi-column layout
286 2c begin multi-column layout
287 EN end \fI\%eqn\fP equation
288 EQ begin \fI\%eqn\fP equation
289 GE end \fI\%grn\fP picture with drawing position at bottom
290 GF end \fI\%grn\fP picture with drawing position at top
291 GS start \fI\%grn\fP picture
292 IE end \fIideal\fP picture with drawing position at bottom
293 IF end \fIideal\fP picture with drawing position at top
294 IS start \fIideal\fP picture
295 PE end \fI\%pic\fP picture with drawing position at bottom
296 PF end \fI\%pic\fP picture with drawing position at top
297 PS start \fI\%pic\fP picture
298 TE end \fI\%tbl\fP table
299 TH end heading for multi-page \fI\%tbl\fP table
300 TS start \fI\%tbl\fP table
301 b embolden argument
302 ba set base indentation
303 bc begin new column
304 bi embolden and italicize argument
305 bx box argument
306 ef set even-numbered page footer
307 eh set even-numbered page header
308 ep end page
309 fo set footer
310 he set header
311 hl draw horizontal line
312 hx suppress next page's headers/footers
313 i italicize argument
314 ip begin indented paragraph
315 ld reset localization and date registers and strings\fB*
316 ll set line length
317 lp begin fully left-aligned paragraph
318 np begin numbered paragraph
319 of set odd-numbered page footer
320 oh set odd-numbered page header
321 pd output delayed text
322 pp begin first-line indented paragraph
323 q quote argument
324 r set argument in roman
325 re reset tab stops
326 sh begin numbered section
327 sm set argument at smaller type size
328 sx change section depth
329 sz set type size and vertical spacing
330 tp begin title page
331 u underline argument
332 uh begin unnumbered section
333 xl set line length (local)
334 xp output index
335 .TE
336 .
337 .
338 .P
339 Some macros are provided for \(lqold\(rq
340 .MR roff 1
341 compatibility.
342 .
343 The
344 .RI \(lq me
345 Reference Manual\(rq
346 describes alternatives for modern documents.
347 .
348 .
349 .P
350 .ne 2v \" Keep at least the first entry together with the heading.
351 .TS
352 Lb L.
353 ar use Arabic numerals for page numbers
354 bl insert space (even at page top; cf.\& \fBsp\fP)
355 ix set indentation without break
356 m1 set page top to header distance
357 m2 set header to text distance
358 m3 set text to footer distance
359 m4 set footer to page bottom distance
360 n1 begin output line numbering
361 n2 end or alter output line numbering
362 pa begin page
363 ro use Roman numerals for page numbers
364 sk skip next page
365 .TE
366 .
367 .
368 .\" ====================================================================
369 .SS Registers
370 .\" ====================================================================
371 .
372 .ne 2v \" Keep at least the first entry together with the heading.
373 .TS
374 Lb L.
375 $0 section depth
376 $1 first section number component
377 $2 second section number component
378 $3 third section number component
379 $4 fourth section number component
380 $5 fifth section number component
381 $6 sixth section number component
382 $c current column number
383 $d delayed text number
384 $f footnote number
385 $i paragraph base indentation
386 $l column width
387 $m number of available columns
388 $p numbered paragraph number
389 $s column spacing (indentation)
390 bi display (block) indentation
391 bm distance from text area to page bottom
392 bs display (block) pre/post space
393 bt block threshold for keeps
394 ch current chapter number
395 df display font
396 dv vertical spacing of displayed text (as percentage)\fB*
397 es equation pre/post space
398 ff footnote font
399 fi footnote indentation (first line only)
400 fm footer margin
401 fp footnote type size in points
402 fs footnote prespace
403 fu footnote undent (right indentation)
404 hm header margin
405 ii indented paragraph indentation
406 no line numbering offset\fB*
407 pf paragraph font
408 pi paragraph indentation
409 po page offset
410 pp paragraph type size in points
411 ps paragraph prespace
412 qi long quotation left/right indentation
413 qp long quotation type size in points
414 qs long quotation pre/post space
415 sf section title font
416 si section indentation per level of depth
417 so additional section title offset
418 sp section title type size in points
419 ss section prespace
420 sx super/subscript line height increase\fB*
421 tf title font
422 tm distance from page top to text area
423 tp title type size in points
424 tv vertical spacing of text (as percentage)\fB*
425 xs index entry prespace
426 xu index undent (right indentation)
427 y2 year of the century\fB*
428 y4 year\fB*
429 yr year minus 1900
430 zs floating keep pre/post space
431 .TE
432 .
433 .
434 .\" ====================================================================
435 .SS Strings
436 .\" ====================================================================
437 .
438 .ne 2v \" Keep at least the first entry together with the heading.
439 .TS
440 Lb L.
441 # delayed text marker
442 $n concatenated section number
443 * footnote marker
444 \- em dash
445 < begin subscripting
446 > end subscripting
447 dw weekday name
448 lq left double quotation mark
449 mo month name
450 rq right double quotation mark
451 td date
452 wa term for \(lqappendix\(rq used by \fB.$c*
453 wc term for \(lqchapter\(rq used by \fB.$c*
454 { begin superscripting
455 } end superscripting
456 .TE
457 .
458 .
459 .\" ====================================================================
460 .SH Files
461 .\" ====================================================================
462 .
463 .TP
464 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/e.tmac
465 implements the package.
466 .
467 .
468 .TP
469 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/refer\-me.tmac
470 implements
471 .MR \%refer 1
472 support for
473 .IR me .
474 .
475 .
476 .TP
477 .I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/me.tmac
478 is a wrapper enabling the package to be loaded with
479 .RB \[lq] "groff \-m me" \[rq].
480 .
481 .
482 .\" ====================================================================
483 .SH Notes
484 .\" ====================================================================
485 .
486 Early
487 .I roff
488 macro packages often limited their names to a single letter,
489 which followed the formatter's
490 .B m
491 flag letter,
492 resulting in
493 .IR mm ,
494 .IR ms ,
495 .IR mv ,
496 .IR mn ,
497 and so on.
498 .
499 .\" 'When I started writing the -me macros it began as something in my
500 .\" private tree (I don't remember what I called it). Then some other
501 .\" folks on the INGRES project wanted to use it, but our system admin
502 .\" at the time didn't want to dicker with the system namespace at the
503 .\" behest of a mere undergraduate, so he didn't like anything that was
504 .\" actually descriptive lest people think it was "official". He
505 .\" finally consented to "-meric" (which I always hated), since it was
506 .\" obviously non-official. By the time my macros became popular around
507 .\" Berkeley it got shortened to "-me", much to my relief.
508 .\"
509 .\" Of course, if AT&T had been willing to let Berkeley have -ms then
510 .\" most likely -me would never have happened at all. Without a macro
511 .\" package, nroff/troff is basically unusable; -me stepped into the
512 .\" vacuum.' -- Eric Allman
513 .\"
514 .\" https://minnie.tuhs.org/pipermail/tuhs/2018-November/017033.html
515 .
516 The \(lqe\(rq in \(lqme\(rq stands for \(lqEric P.\& Allman\(rq,
517 who wrote the macro package and the original technical papers
518 documenting it while an undergraduate at the University of California.
519 .
520 .
521 .\" ====================================================================
522 .SH "See also"
523 .\" ====================================================================
524 .
525 .
526 Two manuals are available in source and rendered form.
527 .
528 On your system,
529 they may be compressed and/or available in additional formats.
530 .
531 .
532 .br
533 .ne 3v
534 .TP
535 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/meintro.me
536 .TQ
537 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/meintro.ps
538 is
539 \[lq]Writing Papers with
540 .I Groff
541 Using
542 .RI \- me \[rq],
543 by Eric P.\& Allman,
544 adapted for
545 .I groff
546 by James Clark.
547 .
548 .
549 .br
550 .ne 4v
551 .TP
552 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/meref.me
553 .TQ
554 .I /usr/\:\%share/\:\%doc/\:\%groff\-base/meref.ps
555 is the
556 .RI \[lq] me
557 Reference Manual\[rq],
558 by Eric P.\& Allman,
559 adapted for
560 .I groff
561 by James Clark and G.\& Branden Robinson.
562 .
563 .
564 .P
565 .IR "Groff: The GNU Implementation of troff" ,
566 by Trent A.\& Fisher and Werner Lemberg,
567 is the primary
568 .I groff
569 manual.
570 .
571 You can browse it interactively with \[lq]info groff\[rq].
572 .
573 .
574 .P
575 For preprocessors supported by
576 .IR me ,
577 see
578 .MR \%eqn 1 ,
579 .MR \%grn 1 ,
580 .MR \%pic 1 ,
581 .MR \%refer 1 ,
582 and
583 .MR \%tbl 1 .
584 .
585 .
586 .P
587 .MR groff 1 ,
588 .MR \%troff 1 ,
589 .MR groff 7
590 .
591 .
592 .\" Restore compatibility mode (for, e.g., Solaris 10/11).
593 .cp \n[*groff_groff_me_7_man_C]
594 .do rr *groff_groff_me_7_man_C
595 .
596 .
597 .\" Local Variables:
598 .\" fill-column: 72
599 .\" mode: nroff
600 .\" End:
601 .\" vim: set filetype=groff textwidth=72: