12.68 text.fill - Text filling ¶

Module: text.fill ¶

This module provides procedures to fill given text within the specified width, inserting line breaks adequately. It is similar to fill-paragraph of Emacs.

Function: display-filled-text text :key port indent hanging width start-column lead-in ¶

{text.fill} Output text to port, while keeping the line width up to width as much as possible by inserting line breaks. If port is omitted, the current output port is used.

Two consecutive newlines mark (or, an empty line) a paragraph break. First, text is splitted into paragraphs, then each paragraph is filled. All other newlines are treated as whitespaces.

It has a few keyword arguments to control the formatting. The width argument specifies the entire width of the filled text. It tries to keep lines from overflowing the width, but if there’s an unbreakable chunk of text that’s wider than the given width, it lets the line oveflow. The hanging specifies the hanging indent width of the paragraph’s first line, and indent specifies the indent width of the rest of lines. They are included in width. Here’s the relations of these values:

  width
<------------------------------------------------------------------->
  hanging
<------>
         Lorem ipsum dolor sit amet, consectetur adipiscing elit,
   sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
   Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
   nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
   in reprehenderit in voluptate velit esse cillum dolore eu fugiat
   nulla pariatur. Excepteur sint occaecat cupidatat non proident,
   sunt in culpa qui officia deserunt mollit anim id est laborum.
<->
  indent

The arguments width, indent, and hanging must be nonnegative exact integers or #f, if given. When omitted or #f, width is assumed to be 65, indent to be 0, and hanging to be the same as indent.

If you call this procedure in the middle of the line (that is, some text is already written to port), the procedure takes the current column into account, as shown below:

  width
<--------------------------------------------------------------------->
             start column
                |   hanging
                v<---->
                        Lorem ipsum dolor sit amet, consectetur
          adipiscing elit, sed do eiusmod tempor incididunt ut labore
          et dolore magna aliqua.  Ut enim ad minim veniam, quis
          nostrud exercitation ullamco laboris nisi ut aliquip ex ea
          commodo consequat. Duis aute irure dolor in reprehenderit in
          voluptate velit esse cillum dolore eu fugiat nulla pariatur.
          Excepteur sint occaecat cupidatat non proident, sunt in culpa
          qui officia deserunt mollit anim id est laborum.
<-------->
   indent

The start-column keyword argument can override the port’s current column with the given nonnegative exact integer. It is only considered for the first paragraph; subsequent paragraphs are formatted as if start-column is zero.

The last line of the last paragraph is not terminated by a newline, allowing the caller to continue output in the same line.

The length of the line is computed by each character’s East Asian Width (see East asian width property). The actual display width depends on the fonts, but it gives a reasonable approximation.

Finally, if the lead-in argument is not #f, it must be a string that is output before any text and indentation is output. Then, if the column after lead-in is less than hanging minus one, text will be emitted on the smae line, starting from hanging column:

     hanging
<------------------>
THIS IS LEAD-IN.    Lorem ipsum dolor sit amet, consectetur
             adipiscing elit, sed do eiusmod tempor incididunt ut labore
             et dolore magna aliqua.
<----------->
    indent

If lead-in text is equal to or longer than the hanging, text is emitted from the next line.

     hanging
<------------------>
THIS IS LEAD-IN LONGER THAN HANGING.
                    Lorem ipsum dolor sit amet, consectetur
             adipiscing elit, sed do eiusmod tempor incididunt ut labore
             et dolore magna aliqua.
<----------->
    indent

Even if text contains more than one paragraph, lead-in is displayed only once, at the beginning.

This is handy when you display definition-list like document, e.g. command-line option description.

Function: text->filled-stree text :key indent hanging width start-column lead-in ¶

{text.fill} This is a low-level routine to construct a filled text used by display-filled-text. It returns a string tree (see text.tree - Lazy text construction). If you want to add more text around the filled paragraph, using this procedure can save constructing intermediate strings.

The meaning of the keywrd arguments are the same as display-filled-text, except that start-column is assumed to be 0 if omitted.