PARAMETERS

Number of initial blanks required to suppress
indenting. Use 0 to indent all.

const char *no_format_chars

Character in colum one which suppress
indenting. Use NULL or "" to disregard.

Bool keep_indentation

If TRUE, indentation is maintained. A change in
indent forces a new line, and justification
continues at the new indent.

Possible values for a

Bool

are as follows:

FALSE
,

TRUE

int extra_indent

Extra indent for justified lines. If positive, all
justified lines are indented this amount above what
they would be otherwise. Lines for which indentation is
disabled through no_format_indent or no_format_chars
are not affected.

char *out_str

Output buffer. Should be size max_len or more.

long max_len

Size of output buffer.

DESCRIPTION

This is a simple left_justify routine. More comprehensive code can be found
as part of the program "par". One day, I may even incorperate this (or other
formating) code into the KJB library.
The input string parameter is written reformatted to the output string
parameter. The rerortting strips returns and re-adds them so that if the
output string is printed it will be justified.
The parameters no_format_indent and no_format_chars can be used for some
control over when formatting occurs indenting. If no_format_indent is
greater than 0, any line which has that many blanks (or more) followed by
non-blanks, will be left alone, except that the lines will be wrapped to fit
in width if the line is too long. Similarly, any line whose first no-white
space is a character in the string no_format_chars will be left alone,
except that they wil also be wrapped, and if wrapped, the specific character
which supressed the formatting will be added as the first character of the
new line. Finally, if formatting is suppressed due to no_format_indent, and
the line wraps, and the first character would be one of the no_format_chars,
then an extra space is inserted.
The boolean parameter keep_indentation maintains the indent level of the
input. When the indent level of the input changes, then a new line is
forced, and the indentation is reset. This behaviour is often what is
required.
If the the paramter extra_indent is positive, then that number of blanks is
added to the begining of each formated line. This is in addition to the
indent which is set by the input if keep_indentation is used. Thus in this
case, the indent structure of the input is maintained, but the exact indent
is more.

RETURNS

NO_ERROR is returned on success. If the length of the output buffer as
specified by the parameter max_len is not large enough to hold the
result, then left_justify returns TRUNCATED. The output is null
terminated, and is truncated.

DISCLAIMER

This software is not adequatedly tested. It is recomended that
results are checked independantly where appropriate.