From d318611dd6f23fcfedd50e9b9e24620b102ba96a Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:44:05 +0200 Subject: Adding upstream version 1.23.0. Signed-off-by: Daniel Baumann --- contrib/mom/momdoc/definitions.html | 995 ++++++++++++++++++++++++++++++++++++ 1 file changed, 995 insertions(+) create mode 100644 contrib/mom/momdoc/definitions.html (limited to 'contrib/mom/momdoc/definitions.html') diff --git a/contrib/mom/momdoc/definitions.html b/contrib/mom/momdoc/definitions.html new file mode 100644 index 0000000..b85a089 --- /dev/null +++ b/contrib/mom/momdoc/definitions.html @@ -0,0 +1,995 @@ + + + + + + + + + Mom -- Definitions and Terms + + + + + + + +
+ + + + + + + +
Back to Table of ContentsNext: Using mom
+ +

Definitions of terms used in this manual

+ +

+I use a number of typesetting-specific and groff-specific terms +throughout this documentation, as well as a few terms that apply +to mom herself. To make life easier, I’ll explain +them here. Refer back to this section should you encounter a word +or concept you’re not familiar with. +

+ +
+ +
+ + + + + +
Typesetting terms
+ Ascender
+ Baseline
+ Ballot box
+ Bullet
+ Cap-height
+ Descender
+ Discretionary hyphen
+ Drop cap
+ Em/en
+ Family
+ Figure space/Digit space
+ Fixed width font
+ Fixed width space
+ Font
+ Force justify
+ Justify/justification
+ Gutter
+ Kerning
+ Kern Units
+ Lead/leading
+ Leaders
+ Ligature
+ Picas/Points
+ Point Size
+ Quad
+ Rag
+ Shape
+ Solid/set solid
+ Track kerning/Line kerning
+ Unbreakable space
+ Weight
+ Word space
+ x-height
+
+
+ +
+ + + + + +
Groff terms
+ Alias
+ Arguments
+ Comment lines
+ Control Lines
+ Filled lines
+ Inline escapes
+ Input line
+ Macros
+ Machine units
+ Numeric argument
+ Output line
+ Primitives
+ Pre-processor
+ String Argument
+ Unit of measure
+ Zero-width character
+
+
+ +
+ + + + + +
Mom terms
+ Baseline grid
+ Blockquote
+ Control macro
+ Docheader
+ Epigraph
+ Float
+ Footer
+ Head
+ Header
+ Linebreak
+ Paragraph head
+ PDF link
+ PDF outline
+ Quote
+ Running text
+ Toggle
+
+
+ +

Typesetting terms

+
+
Ascender
+
+ The portion of a letter that extends above the bowl. For + example, the letters a, c, and e have no ascenders. The letters + b, d, and h do. +
+ +
Baseline
+
+ The imaginary line on which the bottoms of capital letters and + the bowls of lower case letters rest. +
+ +
Ballot box
+
+ An unfilled square, usually + cap-height + in size, typically placed beside items in a checklist. +
+ +
Bullet
+
+ A small, filled circle typically found beside items or points in + a list. +
+ +
Cap-height
+
+ The height of the tallest capital letter in a given + font + at the current + point size. +
+ +
Descender
+
+ The portion of a letter that extends beneath the + baseline + (j, q, y are letters with descenders). +
+ +
Discretionary hyphen
+
+ A symbol inserted between two syllables of a word that indicates + to a typesetting program the valid hyphenation points in the + word. Normally, if hyphenation is turned on, groff knows where + to hyphenate words. However, hyphenation being what it is + (in English, at any rate), groff doesn’t always get it right. + Discretionary hyphens make sure it does. In the event that the + word doesn’t need to be hyphenated at all, groff leaves them + alone. In groff, the discretionary hyphen is entered with + \% (i.e. a backslash followed by the percent sign). +
+ +
Drop cap
+
+ A large, usually upper-case letter that introduces the first + paragraph of a document or section thereof. The top of the + drop cap usually lines up with the top of the first line of the + paragraph, and typically “drops” several lines lower. + Text adjacent to the drop cap is indented to the right of the + letter until the bottom of the drop cap is reached, at which + point text reverts to the left margin. +
+ +
Em/en
+
+ An em is a relative measurement equal to the width of the + letter M at a given + point size + in a given + font. + Since most Ms are designed square, an em is usually (but + sometimes erroneously) considered to be the same size as the + current point size (i.e., if the point size of the type is 12, + one em equals 12 points). An en is equal to the width of a + letter N (historically 2/3 of an em, although groff treats an en + as 1/2 of an em). Typically, ems and ens are used to measure + indents, or to define the length of dashes (long hyphens). +
+ +
Family
+
+ The collective name by which a collection of + fonts + are known, e.g. Helvetica, Times Roman, Garamond. +
+ +
Figure space/Digit space
+
+ A + fixed width space + that has the width of one digit. Used for aligning numerals in, + say, columns or numbered lists. In groff, the figure space is + entered with \0 (i.e. a backslash followed by a zero) +
+ +
Fixed-width font
+
+ A family or font in which every character occupies exactly the + same amount of horizontal space on the line. Courier is the + best-known, if not the most elegant, fixed-width font. +
+ +
Fixed width space
+
+ Equal to + word space, + but does not expand or contract when text is + justified. + In groff, fixed width space is entered with + \<space> (i.e. a backslash followed by a space) +
+ +
Font
+
+ The specific + weight + and + shape + of type within a + family, + e.g. light, medium, bold (which are weights), and roman, italic, + condensed (which are shapes). By default, groff knows of four + fonts within its default set of families: R (medium roman), I + (medium italic), B (bold roman) and BI (bold italic). + Mom considerably extends this very basic list. +
+ +
Force justify
+
+ Sometimes, in + justified + text, a line needs to be broken short of the right margin. + Force justifying means telling a typesetting program (like + groff) that you want the line broken early AND that you want the + line’s word spacing stretched to force the line flush with the + right margin. +
+ +
Gutter
+
+ The vertical whitespace separating columns of type. +
+ +
Justify/justification
+
+ Lines of type are justified when they’re flush at both the left + and right margins. Justification is the act of making both + margins flush. Some people use the terms "left justified" and + "right justified" to mean type where only the left (or right) + margins align. I don’t. See + quad. +
+ +
Kerning
+
+ Moving pairs of letters closer together to remove excess + whitespace between them. In the days before phototypesetting, + type was set from small, rectangular blocks of wood or metal, + each block having exactly one letter. Because the edge of + each block determined the edge of each letter, certain letter + combinations (TA, for example) didn’t fit together well and had + to be mortised by hand to bring them visually closer. Modern + typesetting systems usually take care of kerning automatically, + but they’re far from perfect. Professional typesetters still + devote a lot of time to fitting letters and punctuation together + properly. +
+ +
Kern Units
+
+ A relative distance, which, by default, is equal to 1/36 of the + current + point size. + Used between individual letters for + kerning. + Different typesetting systems use different values (1/54 is + popular), and sometimes call kern units by a different name. + It is possible to change the default size of the kern unit with the + KERN_UNIT + macro. +
+ +
Lead/leading
+
+ The distance from the + baseline + of one line of type to the line of type immediately beneath + it. Pronounced "ledding." Also called line spacing. Usually + measured in + points. + +

+ In case you’re interested... In previous centuries, + lines of type were separated by thin strips of—you guessed + it—lead. Lines of type that had no lead between them were said + to be “set solid.” Once you began separating them with + strips of lead, they were said to be “leaded”, and the + spacing was expressed in terms of the number of + points + of lead. For this reason, “leading” and “line + spacing” aren’t, historically speaking, synonymous. + If type was set 10 on 12, for example, the leading was 2 + points, not 12. Nowadays, however, the two terms are used + interchangeably to mean the distance from baseline to baseline. +

+ +
+ +
Leaders
+
+ Single characters used to fill lines, usually to their end. So + called because they “lead” the eye from one element + of the page to another. For example, in the following (brief) + Table of Contents, the periods (dots) are leaders. + + + Foreword............... 2 + Chapter 1.............. 5 + Chapter 2.............. 38 + Chapter 3.............. 60 + +
+ +
Ligature
+
+ Ligatures are letters joined together to form a single + character. The commonest are fi, fl, ff, ffi and ffl. Others + are ae and oe. Occasionally, one sees an st ligature, but this + is archaic and quite rare. +
+ +
Picas/Points
+
+ There are twelve points in a pica, and six picas in an inch + (hence 72 points to the inch). In the same way that gem-dealers + have always used their own system of measurement for weight + (carats), typographers have always used their own system of + measurement for type. +
+ +
Point Size
+
+ The nominal size of type, measured in + points + from the bottom of the longest + descender + to the top of the highest + ascender. + In reality, type is always fractionally smaller than its point + size. +
+ +
Quad
+
+ When only one margin of type is flush, lines of type are quadded + in the direction of the flush margin. Therefore, quad left + means the left margin is flush, the right isn’t. Quad right + means the right margin is flush, the left isn’t. Quad centre + means neither the left nor the right margin is flush; rather, + lines of type are quadded on both sides so that type appears + centred on the page. +
+ +
Rag
+
+ Describes a margin that isn’t flush. Rag right means the right + margin isn’t flush. Rag left means the left margin isn’t flush. + The expression "flush left/rag right" is sometimes used to + describe type that is + quadded + left. +
+ +
Shape
+
+ The degree of slant and/or the width of characters. + (Technically speaking, this is not a proper typesetting term; + however, it may help clarify some concepts presented in these + documents.) + +

+ Some typical shapes are: +

+ +
    +
  • Roman, which has no slant, and has letterforms of + average width
    • +
  • Italic, which is slanted, and has letterforms + of average width
    • +
  • Condensed, which has no slant, but has + letterforms narrower than the average represented by Roman
    • +
  • Condensed Italic, which is slanted, with letterforms narrower + than average
    • +
+ +

+ The term + font, + as it is used in these documents, refers to a combination of + weight + and shape. +

+ +
+ +
Solid/set solid
+
+ When no + lead + is added between lines of type (i.e., the + point size + and linespacing are the same), the lines are said to be “set + solid.” +
+ +
Track kerning/Line kerning
+
+ Sometimes, it’s advantageous to increase or decrease the amount + of space between every letter in a line by an equal (usually + small) amount, in order to fit more (or fewer) characters on the + line. The correct term is letter spacing, but track kerning and + line kerning (and sometimes, just "kerning") have come to mean + the same thing. +
+ +
Unbreakable space
+
+ Equal to + word space, + however words separated by an unbreakable space will always be + kept together on the same line. Expands and contracts like word + space. Useful for proper names, which one should, whenever + possible, avoid splitting onto two lines. In groff, unbreakable + space is entered with \~ (i.e. a backslash followed by a + tilde) +
+ +
Weight
+
+ The thickness of the strokes of letterforms. Medium and Book + have average thicknesses and are the weights used for most + of the text in books, magazines, newspapers, etc. Light has + strokes slightly thinner than Medium or Book, but is still + acceptable for most text. Semibold, Bold, Heavy and Black all + have strokes of increasing thickness, making them suitable for + headings and the like. +
+ +
Word space
+
+ The amount of whitespace between words. When text is + justified, + word space expands or contracts to make the margins flush. +
+ +
x-height
+
+ The height of a lower case letter x in a given font at a given + point size. Generally used to mean the average height of the + bowl of lower case letters. +
+
+ +

Groff terms

+ +
+
Alias
+
+ A + macro + invoked by a name different from its “official” + name. For example, the official name of the macro to change + family + is FAMILY. Its alias is FAM. + Aliases may be created for any macro (via the + ALIAS + macro) provided the alias uses a name not already taken by the + mom macros or one of the groff + primitives. + For a complete list of words or names you must not use, see the + list of reserved words. +
+ +
Arguments
+
+ Parameters or information needed by a + macro + to do its job. For example, in the macro + + + .PT_SIZE 12 + + + 12 is the argument. In the macro + + + .QUAD LEFT + + + LEFT is the argument. Arguments are separated from + macros by spaces. Some macros require several arguments; each + is separated by a space. +
+ +
Comment Lines
+
+ Input lines + introduced with the comment character \# (i.e. a + backslash followed by the pound sign). When processing output, + groff silently ignores everything on a line that begins with the + comment character. +
+ +
Control Lines
+
+ Instructions to groff that appear on a line by themselves, which + means that “control lines” are either + macros + or groff + primitives. + Control lines begin with a period or, occasionally, an apostrophe. +
+ +
Filled lines/fill mode
+
+ Automatic + justification + or + quadding. + In fill mode, the ends of lines as they appear in your text + editor are ignored. Instead, words from adjoining + input lines + are added one at a time to the output line until no more words + fit. Then, depending whether text is to be + justified + or + quadded + (left, right, or centre), and depending on whether automatic + hyphenation is turned on, groff attempts to hyphenate the last + word, or, barring that, spreads and breaks the line (when + justification is turned on) or breaks and quads the line (when + quadding is turned on). + +

+ Nofill mode (non-filled text) means that groff respects the ends + of lines exactly as they appear in your text editor. +

+ +
+ +
Inline escapes
+
+ Instructions issued to groff that appear as part of an + input line + (as opposed to + macros, + which must appear on a line by themselves). Inline escapes are + always introduced by the backslash character. For example, + + + A line of text with the word T\*[BU 2]oronto in it + + + contains the inline escape \*[BU 2] (which means + “move the letter ‘o’ 2 + kern units + closer to the letter ‘T’”). + +

+ Mom’s inline escapes always take the form + \*[<ESCAPE>], where ESCAPE is + composed of capital letters, sometimes followed immediately by a + digit, sometimes followed by a space and a + numeric argument. + Groff’s escapes begin with the backslash + character but typically have no star and are in lower case. For + example, the mom escapes to move forward 6 + points on a line are either + + + \*[FP6]  or  \*[FWD 6p] + + + while the groff escape for the same thing is + + + \h’6p’ + +

+ +
+ +
Input line
+
+ A line of text as it appears in your text editor. +
+ +
Macros
+
+ Instructions embedded in a document that determine how groff + processes the text for output. mom’s macros + always begin with a period, on a line by themselves, and must + be typed in capital letters. Typically, macros contain complex + commands issued to groff—behind the scenes—via + groff + primitives. +
+ +
Machine units
+
+ A machine unit is 1/1000 of a + point + when the groff device is ps. (“ps” means + “PostScript”—the default device for + which groff prepares output, and the device for which + mom was originally designed.) +
+ +
Numeric argument
+
+ An + argument + that has the form of a digit. Numeric arguments can be built + out of arithmetic expressions using +, -, *, and / for plus, + minus, times, and divided-by respectively. If a numeric + argument requires a + unit of measure, + a unit of measure must be appended to every digit in + the argument. For example: + + + .ALD 1i-1v + + +
+

+ IMPORTANT: groff does not + respect the order of operations, but rather evaluates + arithmetic expressions from left to right. Parentheses must + be used to circumvent this peculiarity. Not to worry, though. + The likelihood of more than just the occasional plus or minus + sign when using mom’s macros is slim. +

+
+
+ +
Output line
+
+ A line of text as it appears in output copy. +
+ +
Pre-processor
+
+ Pre-processors are used by groff to generate tables + (tbl), diagrams (pic), graphs + (grap), and equations (eqn). + These pre-processors are fully supported by mom. In addition, + the “refer” pre-processor is used to generate + bibliographies and lists of cited works. The PDF_IMAGE macro, + which allows insertion of graphics into a document, is not + strictly a pre-processor but behaves similarly to tbl, pic, and + eqn. +
+ +
Primitives
+
+ The lowercase instructions, introduced with a period, that groff + uses as its native command language, and out of which macros + are built. The majority of groff’s primitive requests are two + letters long. +
+ +
String Argument
+
+ Technically, any + argument + that is not numeric. In this documentation, string argument + means an argument that requires the user to input text. For + example, in the + macro + + + .TITLE "My Pulitzer Novel" + + + "My Pulitzer Novel" is a string argument. + +

+ Because string arguments must be enclosed by double-quotes, you + can’t use double-quotes as part of the string argument. If you + need double-quotes to be part of a string argument, use the + inline escapes + \(lq and \(rq (leftquote and + rightquote respectively) in place of the double-quote character + ("). +

+ +
+ +
Unit of measure
+
+ The single letter after a + numeric argument + that tells mom what measurement scale the + argument should use. Common valid units are: + + + i (inches) + p (points) + P (Picas) + c (centimetres) + m (ems) + n (ens) + u (machine units) + v (the current leading [line space]) + + +

+ Units of measure must come immediately after the numeric + argument (i.e. with no space between the argument and the unit + of measure), like this: + + + .ALD 2v + .LL 39P + .IL 1i + + + The above example advances 2 line spaces and sets the line + length to 39 picas with a left indent of 1 inch. +

+ +
+

+ IMPORTANT: + Most mom macros that set the size or measure of something must + be given a unit of measure since most of the macros do not have + default units of measure. There are a couple of exceptions, + the most notable of which are PT_SIZE and + LS. Both use + points + as the default unit of measure, which means you don’t have to + append “p” to their argument. +

+
+ +

+ You can enter decimal values for any unit of measure. Different + units may be combined by adding them together (e.g. 1.5i+2m, + which gives a measure of 1-1/2 inches plus 2 ems). +

+ +
+

+ Note: + a pica is composed of 12 points, therefore 12.5 picas is 12 + picas and 6 points, not 12 picas and 5 points. If you want 12 + picas and 5 points, you have to enter the measure as 12P+5p. +

+
+ +
+ +
Zero-width character
+
+ The + inline escape + that allows you to print a literal period, apostrophe and, if + output lines + are + filled, + a space that falls at the beginning of an + input line. + It looks like this: + + + \& (i.e. a backslash followed by an ampersand) + + + Normally, groff interprets a period (or an apostrophe) at the + beginning of an input line as meaning that what follows is a + control line. + In fill modes, groff treats a space at the beginning of an input + line as meaning “start a new line and put a space at the + beginning of it.” If you want groff to interpret periods + and apostrophes at the beginning of input lines literally (i.e. + to print them), or spaces at the beginning of input lines as just + garden variety word spaces, you must start the line with the + zero-width character. +
+
+ +

Mom terms

+
+
Baseline grid
+
+ Virtual guide lines spaced according to the + leading + established for running text. Adherence to the grid ensures that + text fills the page completely to the bottom margin. Uncorrected + deviations from the grid result in bottom margins that fall short. +
+ +
Control macro
+
+ Macros used in + document processing + to control/alter the appearance of document elements (e.g. + headings, quotes, footnotes, + headers, + etc.). +
+ +
Document header/docheader
+
+ Document information (title, subtitle, author, etc) output at + the top of page one. +
+ +
Epigraph
+
+ A short, usually cited passage that appears at the beginning of + a chapter, story, or other document. +
+ +
Float
+
+ A float is material intended to be kept together as a block. + Floated material that fits on a page in position is output on that + page. Floats that do not fit in position are deferred to the top + of the next page. +
+ + +
+ Document information (frequently author and title) output in + the bottom margin of pages after page one. Not to be + confused with footnotes, which are considered part of + running text. +
+ + +
+ The title used to identify a section of a document. Headings + are hierarchic, corresponding to the notion of head, subhead, + subsubhead, etc. +
+ + +
+ Document information (frequently author and title) output in the + top margin of pages after page one. + +
+

+ Note: In terms of content and style, + headers and + footers + are the same; they differ only in their placement on the page. + In most places in this documentation, references to the content + or style of headers applies equally to footers. +

+
+ +
+ +
Linebreak/author linebreak
+
+ A gap in the vertical flow of + running text, + frequently set off by typographic symbols such as asterisks or + daggers. Used to indicate a shift in the content of a document + (e.g. a scene change in a short story). Also commonly called a + scene break or a section break. +
+ +
Paragraph head
+
+ A heading joined to the body of a paragraph. +
+ + +
+ A portion of text that, when clicked on in a PDF viewer, + navigates to a bookmarked location in a document, generally but not + exclusively a heading. PDF links are usually coloured to make + them stand out from the surrounding text. +
+ +
PDF outline
+
+ The hierarchically-arranged navigation outline provided by most PDF + viewers (e.g. Okular, Evince), typically in a panel to the left of + the document window, and usually labelled “Contents”. +
+ +
Quote
+
+ A quote, to mom, is a line-for-line setting + of quoted material (e.g. poetry, song lyrics, or a snippet of + programming code). You don’t have to use + BR + with quotes. +
+ +
Running text
+
+ In a document formatted with mom, running + text means text that forms the body of the document, including + elements such as headings. + Docheaders, + headers, + footers + and page numbers are not part of running text. +
+ +
Toggle
+
+ A macro or tag that, when invoked without an argument, begins + something or turns a feature on, and, when invoked with ANY + argument, ends something or turns a feature off. See + Example 3 + of the section + How to read macro arguments. +
+
+ +
+ + + + + + + + +
Back to Table of ContentsTopNext: Using mom
+ +
+ +

+ + + -- cgit v1.2.3