%++++++++
% Copyright:    (C) 2008-2015 UDS/CNRS
% License:       GNU General Public License
%.IDENTIFICATION reformat.tex
%.PURPOSE        Man page of "reformat"
%.AUTHOR         Francois Ochsenbein
%.VERSION   1.0  21-Feb-1995
%.VERSION   1.5  21-May-1996
%.VERSION   1.6  13-Apr-1999
%----------

\def\pgm{{\bf reformat}\ }
\begin{manpage} {1}{reformat}{rearrange a text without cutting words}
	{May-2008}{Edition}
\def\pfile{{\em file}}
\syntax{ \pgm  [{\bf--c$|$--d$|$--f$|$--j}] {\bf--p} 
	[{\bf --[b}{\em sep\_list}]
	[{\bf --[w$|$W]} {\em width}] 
	[{\bf --[i$|$I]} {\em indentation}] 
	[{\em file...}] }

\mansec{ Description }
The \pgm command takes a text from {\em file}, or the standard
input, and re-arranges the text within {\em width} bytes,
and unlike the {\bf fold}(1) program
without cutting the words. Lines breaks are also generated
for lines {\em having a punctuation character in the leftmost byte}, 
or when the
amount of indentation on the input text is larger than usual.
\pgm may also add a constant indentation specified by
the {\bf--i} option.

With the {\bf--I} option, the leftmost {\em indent} bytes of each line are 
considered as an {\em identifier}, for which these bytes are reserved;
in other terms, these left bytes contain either the {\em identifier},
repeated with the {\bf--f} (fill) option, or blanks.

Note that the number of consecutive blanks is generally {\em not} kept,
except with the {\bf--c} or {\bf--d} option.

\mansec{Options}

\option{--b} asks to break lines when one of the chars in the
	list is immediately followed by a newline.
	The list of these characters, in the case of a {\bf--b} option
	without a list, is composed of the 2 characters {\bf:} (colon)
	and {\bf)} (right parenthesis)

\option{--c} is the {\em continuation only} option:
	only continuation lines from input lines larger than {\em width}
	are indented. 
	Note that, with this option, the number of consecutive blanks
	is not changed.

\option{--d} is the {\em definition} option, assuming a set of
	{\em definition word} followed by an {\em explanation}:
	lines starting by non-blanks are {\em not} indented
	(i.e. left-flushed), and are followed by enough blanks
	to fill the indentation; all lines starting by one or
	more blanks are assumed to be a continuation of the
	{\em explanation}.
	Note that, with this option, the number of consecutive blanks
	is not changed.

\option{--f}
	is similar to {\bf--d} (left-justified lines are kept left-justified),
	but the leftmost {\em I} bytes are repeated on each continuation line
	instead of being blank.

\option{--i {\em indentation}}
	\pgm starts each line with {\em indentation} blanks.
	Its default value is zero (no indentation)

\option{--I {\em indentation}}
	assumes that the leftmost {\em indentation} bytes are reserved
	for an {\em identifier}. 

\option{--j}
	asks to {\em justify} the text, i.e. insert blanks to adjust
	both left and right margins.

\option{--p}
	assumes input items made of {\em paragraphs}, i.e. full paragraphs
	are reformatted.

\option{--w {\em width}}
	defines the width of the text.
	Its default value is 80. The maximal length of each line 
	(linesize) is {\em width}+{\em indentation}

\option{--W {\em width}}
	defines the maximal length of each line (linesize).

\mansec{Returned Status}
The \pgm command returns 0 in case of success, and
non-zero when bad options or unreadable files are found.

\mansec{Examples}
\begin{enumerate}
\item	
The following text
\begin{verbatim}
Hello, here is a text that I would like to reformat.
   Effectively, the indented lines mean "starting a new paragraph"; 
but, caution, I've a list:
=> here is an item (the first)
=> this is also an item
   but not this
\end{verbatim}

gives with {\pgm \bf -i4 -w60} the following result:
\begin{verbatim}
    Hello, here is a text that I would like to reformat.
    Effectively, the indented lines mean "starting a new
    paragraph"; but, caution, I've a list:
    => here is an item (the first)
    => this is also an item but not this
\end{verbatim}

\item	The following text
\begin{verbatim}
WGA J0043.3-2638 Since being selected for the DXRBS sample, 
WGA J0043.3-2638 this source was observed by Cristiani et al.
WGA J0100.1-3337 The single emission line, which we classify as Mg II at 
WGA J0100.1-3337 z=0.875, is clearly broad (FWHM=2900km/s), 
WGA J0100.1-3337 but its equivalent width is close to 10A.
\end{verbatim}

gives with {\pgm \bf -I17 -W50} the following result:
\begin{verbatim}
WGA J0043.3-2638 Since being selected for the
                 DXRBS sample, this source was
                 observed by Cristiani et al.
WGA J0100.1-3337 The single emission line, which
                 we classify as Mg II at z=0.875,
                 is clearly broad (FWHM=2900km/s),
                 but its equivalent width is close
                 to 10A.
\end{verbatim}

\end{enumerate}


\seealso{acut(1) fold(1)}
\end{manpage}
