diff options
Diffstat (limited to 'man1p/fold.1p')
| -rw-r--r-- | man1p/fold.1p | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/man1p/fold.1p b/man1p/fold.1p new file mode 100644 index 000000000..888061ec8 --- /dev/null +++ b/man1p/fold.1p @@ -0,0 +1,225 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FOLD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" fold +.SH NAME +fold \- filter for folding lines +.SH SYNOPSIS +.LP +\fBfold\fP \fB[\fP\fB-bs\fP\fB][\fP\fB-w\fP \fIwidth\fP\fB][\fP\fIfile\fP\fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIfold\fP utility is a filter that shall fold lines from its +input files, breaking the lines to have a maximum of +\fIwidth\fP column positions (or bytes, if the \fB-b\fP option is +specified). Lines shall be broken by the insertion of a +<newline> such that each output line (referred to later in this section +as a \fIsegment\fP) is the maximum width possible +that does not exceed the specified number of column positions (or +bytes). A line shall not be broken in the middle of a character. +The behavior is undefined if \fIwidth\fP is less than the number of +columns any single character in the input would occupy. +.LP +If the <carriage-return>s, <backspace>s, or <tab>s are encountered +in the input, and the \fB-b\fP option is +not specified, they shall be treated specially: +.TP 7 +<backspace> +The current count of line width shall be decremented by one, although +the count never shall become negative. The \fIfold\fP +utility shall not insert a <newline> immediately before or after any +<backspace>. +.TP 7 +<carriage-return> +.sp +The current count of line width shall be set to zero. The \fIfold\fP +utility shall not insert a <newline> immediately before +or after any <carriage-return>. +.TP 7 +<tab> +Each <tab> encountered shall advance the column position pointer to +the next tab stop. Tab stops shall be at each column +position \fIn\fP such that \fIn\fP modulo 8 equals 1. +.sp +.SH OPTIONS +.LP +The \fIfold\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-b\fP +Count \fIwidth\fP in bytes rather than column positions. +.TP 7 +\fB-s\fP +If a segment of a line contains a <blank> within the first \fIwidth\fP +column positions (or bytes), break the line after +the last such <blank> meeting the width constraints. If there is no +<blank> meeting the requirements, the \fB-s\fP +option shall have no effect for that output segment of the input line. +.TP 7 +\fB-w\ \fP \fIwidth\fP +Specify the maximum line length, in column positions (or bytes if +\fB-b\fP is specified). The results are unspecified if +\fIwidth\fP is not a positive decimal number. The default value shall +be 80. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file to be folded. If no \fIfile\fP operands +are specified, the standard input shall be used. +.sp +.SH STDIN +.LP +The standard input shall be used only if no \fIfile\fP operands are +specified. See the INPUT FILES section. +.SH INPUT FILES +.LP +If the \fB-b\fP option is specified, the input files shall be text +files except that the lines are not limited to {LINE_MAX} +bytes in length. If the \fB-b\fP option is not specified, the input +files shall be text files. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIfold\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files), and +for the determination of the width in column positions each +character would occupy on a constant-width font output device. +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be a file containing a sequence of characters +whose order shall be preserved from the input files, +possibly with inserted <newline>s. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +All input files were processed successfully. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The \fIcut\fP and \fIfold\fP utilities can be used to create text +files out of files with +arbitrary line lengths. The \fIcut\fP utility should be used when +the number of lines (or +records) needs to remain constant. The \fIfold\fP utility should be +used when the contents of long lines need to be kept +contiguous. +.LP +The \fIfold\fP utility is frequently used to send text files to printers +that truncate, rather than fold, lines wider than the +printer is able to print (usually 80 or 132 column positions). +.SH EXAMPLES +.LP +An example invocation that submits a file of possibly long lines to +the printer (under the assumption that the user knows the +line width of the printer to be assigned by \fIlp\fP): +.sp +.RS +.nf + +\fBfold -w 132 bigfile | lp +\fP +.fi +.RE +.SH RATIONALE +.LP +Although terminal input in canonical processing mode requires the +erase character (frequently set to <backspace>) to erase +the previous character (not byte or column position), terminal output +is not buffered and is extremely difficult, if not +impossible, to parse correctly; the interpretation depends entirely +on the physical device that actually displays/prints/stores the +output. In all known internationalized implementations, the utilities +producing output for mixed column-width output assume that a +<backspace> backs up one column position and outputs enough <backspace>s +to return to the start of the character when +<backspace> is used to provide local line motions to support underlining +and emboldening operations. Since \fIfold\fP +without the \fB-b\fP option is dealing with these same constraints, +<backspace> is always treated as backing up one column +position rather than backing up one character. +.LP +Historical versions of the \fIfold\fP utility assumed 1 byte was one +character and occupied one column position when written +out. This is no longer always true. Since the most common usage of +\fIfold\fP is believed to be folding long lines for output to +limited-length output devices, this capability was preserved as the +default case. The \fB-b\fP option was added so that +applications could \fIfold\fP files with arbitrary length lines into +text files that could then be processed by the standard +utilities. Note that although the width for the \fB-b\fP option is +in bytes, a line is never split in the middle of a character. +(It is unspecified what happens if a width is specified that is too +small to hold a single character found in the input followed by +a <newline>.) +.LP +The tab stops are hardcoded to be every eighth column to meet historical +practice. No new method of specifying other tab stops +was invented. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIcut\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |