.lf 1 - .lf 1 ./abnff.0 .\" Description: abnff man page .\" $Id: ~|^` @(#)abnff.0 0.19 2005/05/20 02:30:21 copyright 2001, 2002, 2003, 2004, 2005 Bruce Lilly $ .\" common man macros to V7, V10, DWB2 (unique ones omitted, differences noted) .\" .TH n c x V7,10 begin page n of chapter c; x is extra commentary .\" .TH t s c n DWB2 beg. pg. t of sect. s; c=extra comment, n=new man. name .\" c appears at bottom center of page, n at top center .\" .SH text subhead .\" .SS text sub-subhead .\" .B text make text bold .\" .I text make text italic .\" .SM text make text 1 point smaller than default .\" .RI a b concatenate and alternate Roman, Italic fonts <=6 args .\" .IR .RB .BR .IB .BI similar to .RI .\" .PP new paragraph .\" .HP in hanging paragraph with indent in .\" .TP in indented paragraph with hanging tag (on next line) .\" .IP t in indented paragraph with hanging tag t (arg 1) .\" .RS in increase relative indent by in .\" .RE k return to kth relative indent level (1-based) .\" .DT default tab settings .\" .PD v inter-paragraph spacing v (default 0.4v troff, 1v nroff) .\" \*R registered symbol (Reg.) .\" \*S change to default type size .\" prevent hyphenation of function names, etc. .lf 1 ./abnff.hw .lf 26 ./abnff.0 .lg 0 .\" avoid groff's butt-ugly ligatures .ds ]W \" no 7th Edition designation .TH abnff 1 "release 0.19" .\" .DS .DE for -man ############################################## .lf 1 ./keepmacro.s .\" .DS .DE for -man ############################################## .\" @(#) keepmacro.s 0.58.0.0 2004/04/25 19:14:21 Bruce Lilly extracted 2004/07/26 02:05:35 .nr dD 0 \" not in keep .de DS \" keep (display) start .ie \\n(dD .tm WARNING: \\n(.F line \\n(.c: nested .DS .el \{.nr dD 1 \" in keep .nr dI \\n(IN \" current indent .nr dL \\n(LL \" current line length .if !\\n(dL .nr dL 6.5i \" make sure line length is not zero (default is 6.5i) .br \" finish current output .ev 1 \" set new environment for keep .in \\n(dIu \" set environment indent .ll \\n(dLu \" and line length same as page .di dC\} \" divert content into diversion dC .. .de DE \" keep (display) end .ie !\\n(dD .tm WARNING: \\n(.F line \\n(.c: .DE without .DS .el \{.br .di \" end keep diversion .ev \" pop keep environment .nr dH \\n(dn \" diversion height .nr dD 0 \" not in keep 'ne \\n(dHu \" break page if diversion won't fit on current page .ev 2 \" new environment for interpolation .in 0i \" zero indent for interpolating formatted diversion .ll \\n(dLu \" line length same as page .nf \" no fill mode for interpolating formatted content 'dC \" interpolate diverted content .br \" finish output .rm dC \" finished with diverted content .ev\} \" pop interpolation environment .. .\" ########################### end of keep macros ########################### .lf 31 ./abnff.0 .\" .TS [H], .TH [N] (redefinition), .TE for tables with -man ####### .lf 1 ./tblmacro.s .\" .TS [H], .TH [N] (redefinition), .TE for tables with -man ####### .\" @(#) tblmacro.s 1.5.0.0 2005/03/11 21:50:57 Bruce Lilly extracted 2005/03/11 21:53:59 .rm TS xH rH T& TE .de TS \" table start .rn TH tH \" move title heading out of way for table heading .rn xH TH \" table heading in effect for .TH .sp \\n(PDu \" inter-paragraph space (paragraph distance) .nr tI \\n(IN \" current indent .nr tL \\n(LL \" current line length .if !\\n(tL .nr tL 6.5i \" make sure line length is not zero (default is 6.5i) .if x\\$1xHx .wh 1i rH \" 1i page trap after new page header .ev 1 \" set new environment for table; avoid gtbl polluting page environment .in \\n(tIu \" set environment indent .ll \\n(tLu \" and line length same as page .ie x\\$1xHx \{'ne 5v .nr tH 1 \" .TS H .if \\n(dD .tm WARNING: \\n(.F line \\n(.c: .TS H within .DS .di hT\} \" divert heading into diversion hT .el .nr tH 0 \" not .TS H .. .de xH \" becomes TH for tables .br .di \" end diversion hT .nr tH 0 \" finished .TH .ev 2 \" new environment for interpolating formatted header .in 0i \" zero indent for interpolating formatted diversion .ll \\n(tLu \" line length same as page .nf \" no fill mode for interpolating formatted header .ie x\\$1xNx .if !\\n(tN .hT \" interpolate header if .TH N and 1st table on page .el .hT \" or if no N arg .br .ev \" pop environment .nr iT 1 \" in table (with header) .. .de rH \" repeat header via page trap .if \\n(iT \{.ev 2 \" do nothing if not in table .nr tN 0 \" no tables yet on new page .in 0i \" zero indent for interpolating formatted diversion .ev \" pop environment .ch rH 99i \" avoid retriggering page trap .ev 2 \" push environment back .sp |1i \" ensure correct position .nf \" no fill mode for interpolating formatted header .hT \" interpolate table header .ev \" pop environment .br .ch rH 1i \" restore page trap .\} \" pop environment .. .de TE \" table end .if \\n(tH \{.tm WARNING: \\n(.F line \\n(.c: .TS H without .TH .di\} .rn TH xH \" hide table heading macro .rn tH TH \" restore title heading macro for .TH .rm hT \" finished with diverted heading .nr iT 0 \" not in table .nr tN 1 \" at least 1 table output on this page .ev \" pop table environment .sp \\n(PDu \" inter-paragraph space (paragraph distance) .. .\" ########################### end of table macros ########################### .lf 33 ./abnff.0 .SH NAME \" 1 line name \- explanatory text .B abnff \- parse and nicely format ABNF .SH SYNOPSIS .PP .B abnff [files] .SH DESCRIPTION .PP .B Abnff is a preprocessor for parsing and formatting ABNF as used in RFCs and Internet Drafts. ABNF is described in RFC 2234. .PP .B Abnff implements a grammar which differs from the one in RFC 2234: .PP 1. comments which are not a continuation of a rule must not have whitespace before the semicolon (this is necessary to remove an ambiguity in the RFC 2234 grammar). .PP 2. ABNF lines parsed by .B abnff are not required to have an old\-fashioned teletype "carriage return" character preceding the newline character marking the end of a line (ABNF found in RFCs and Internet\-Drafts does not use a CR). .PP This software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative. .PP ABNF input is contained between lines beginning with .AS and .AE. The .AS line may contain two numeric arguments specifying the indent and line length in characters. Because .B abnff is a preprocessor, the numeric arguments must be specified directly; one cannot refer to troff registers or use troff width escapes, etc. .PP The .AS line can also take any combination of several one\-character alphabetic option flags: .TS H c0 cw(6.6i). Flag Description _ .TH .T& c l. c T{ canonicalize case of character literals; type (letter after '%') is lower\-case, hexadecimal digit letters are upper\-case. Rulename references use the same case as the defining ABNF line. T} d T{ omit display wrappers around output rules, instead separating rules with an empty line. This may be useful if the entire ABNF is placed within a display wrapper. T} g T{ group concatenated elements in parentheses if in an alternation expression T} i T{ implicit definition of core ABNF rules (suppres warnings about lack of definitions) T} n T{ normalize repetition specifications: 0*1foo becomes [foo], M[foo bar] becomes *M(foo bar), etc. T} s T{ Combine adjacent quoted strings into a single quoted string where possible T} t T{ topologically sort rules in a ruleset so that productions are defined before use T} r T{ reverse the sense of topological sorting; use precedes definition (ineffective if the t flag is not specified) T} .TE .PP Within a ruleset delimited by .AS and .AE lines, .B abnff recognizes a .BC line, which causes the immediately following rule in the ruleset to be formatted with a block comment. That is, the rule definition and comment text are placed side-by-side with running comment text. The height of definition ABNF and comment text is approximately balanced by .BR abnff . .PP Comment lines in troff style are also permitted within ABNF; they are echoed to output before all formatted ABNF rules. .SH EXAMPLE .PP The following example demonstrates formatting of some ABNF: .DS .ft CW .ps 8 .vs 9 .nf \&.AS 3 72 c g n r s t script-list = Script *( [ CFWS] "," [CFWS ] SCRIPT ) content-script = "Content-Script" ":" [CFWS] script-list [CFWS] CRLF CFWS = comment / FWS CRLF = %X0d.0a FWS = 000*([CRLF] WSP) \&.BC script = 4*00004ALPHA ; script tag per ISO 15924:2004; ; script tags are case-insensitive protocol elements \&.AE .fi .ft .ps .vs .DE .PP which is processed by .B abnff to produce: .DS .ft CW .ps 8 .vs 9 .nf \&.DS L content-script = "Content-Script:" [CFWS] script-list [CFWS] CRLF \&.DE \&.DS L script-list = script *([CFWS] "," [CFWS] script) \&.DE \&.DS L script = 4ALPHA ; script tag per ISO 15924:2004; script tags ; are case-insensitive protocol elements \&.DE \&.DS L CFWS = comment / FWS \&.DE \&.DS L FWS = *([CRLF] WSP) \&.DE \&.DS L CRLF = %x0D.0A \&.DE .fi .ft .ps .vs .DE .PP which in turn is processed by the rfc macros to produce output which looks like: .DS L .nf .ft CW .ps 8 .vs 9 content-script = "Content-Script:" [CFWS] script-list [CFWS] CRLF .fi .ft .ps .vs .DE .sp .DS L .nf .ft CW .ps 8 .vs 9 script-list = script *([CFWS] "," [CFWS] script) .fi .ft .ps .vs .DE .sp .DS L .nf .ft CW .ps 8 .vs 9 script = 4ALPHA ; script tag per ISO 15924:2004; script tags ; are case-insensitive protocol elements .fi .ft .ps .vs .DE .sp .DS L .nf .ft CW .ps 8 .vs 9 CFWS = comment / FWS .fi .ft .ps .vs .DE .sp .DS L .nf .ft CW .ps 8 .vs 9 FWS = *([CRLF] WSP) .fi .ft .ps .vs .DE .sp .DS L .nf .ft CW .ps 8 .vs 9 CRLF = %x0D.0A .fi .ft .ps .vs .DE .SH RETURN VALUE .B Abnff returns zero unless a serious error occurs. .SH BUGS and CAVEATS .PP Comment\-only ruleset lines have no associated rulename, therefore cannot be topologically sorted. If a ruleset contains comment\-only lines, has undefined rulenames, and topological sorting is specified, comment\-only lines may appear in strange places. .SH DIAGNOSTICS .PP .B Abnff emits warning and error messages on the standard error stream. It indicates errors if the input specification is faulty in a way that precludes sensible parsing; less serious issues result in warnings. Warnings include multiply\-defined rules, rules which are defined but not referenced, rulenames which are referenced but are undefined, constructs which map to empty input (e.g. a zero repetition count), and cycles in definitions. .SH SEE ALSO RFC 2234 .SH AUTHOR Bruce Lilly