sbr/execprog.c: Fix the return value
[mmh] / man / ap.man8
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH AP %manext8% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 ap \- parse addresses 822-style
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B %libdir%/ap
11 .RB [ \-form
12 .IR formatfile ]
13 .RB [ \-normalize " | " \-nonormalize ]
14 .RB [ \-Version ]
15 .RB [ \-help ]
16 .I addrs
17 \&...
18 .ad
19 .SH DESCRIPTION
20 .B Ap
21 is a program that parses addresses according to the ARPA
22 Internet standard.  It also understands many non\-standard formats.
23 It is useful for seeing how
24 .B nmh
25 will interpret an address.
26 .PP
27 The
28 .B ap
29 program treats each argument as one or more addresses, and
30 prints those addresses out in the official 822\-format.  Hence, it is
31 usually best to enclose each argument in double\-quotes for the shell.
32 .PP
33 To override the output format used by
34 .BR ap ,
35 the
36 .B \-form
37 .I file
38 switch is used.  This permits individual fields of
39 the address to be extracted with ease.
40 The
41 .I file
42 is either the name of a format file or it may be
43 a format string directly, if prepended with an equal sign `='.
44 See
45 .BR mh\-format (5)
46 for the details.
47 .PP
48 In addition to the standard escapes,
49 .B ap
50 also recognizes the following additional escape:
51 .PP
52 .RS 5
53 .nf
54 .ta \w'Escape  'u +\w'Returns  'u
55 .I "Escape      Returns Description
56 error   string  A diagnostic if the parse failed
57 .RE
58 .fi
59 .PP
60 If the
61 .B \-normalize
62 switch is given,
63 .B ap
64 will try to track down
65 the official hostname of the address.
66 .PP
67 Here is the default format string used by
68 .BR ap :
69 .PP
70 .RS 5
71 .nf
72 %<{error}%{error}: %{text}%|%(putstr(proper{text}))%>
73 .fi
74 .RE
75 .PP
76 which says that if an error was detected, print the error, a `:', and
77 the address in error.  Otherwise, output the 822\-proper format of
78 the address.
79
80 .SH FILES
81 .fc ^ ~
82 .nf
83 .ta \w'%etcdir%/ExtraBigFileName  'u
84 ^$HOME/.mmh/profile~^The user profile
85 .fi
86
87 .SH "PROFILE COMPONENTS"
88 None
89
90 .SH "SEE ALSO"
91 dp(8),
92 .I "Standard for the Format of ARPA Internet Text Messages"
93 (RFC\-822)
94
95 .SH DEFAULTS
96 .nf
97 .RB ` \-form "' defaults as described above"
98 .RB ` \-normalize '
99 .fi
100
101 .SH CONTEXT
102 None