This file is indexed.

/usr/share/doc/libbobcat4-dev/man/ofoldstreambuf.3.html is in libbobcat-dev 4.08.02-2build1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
<!DOCTYPE html><html><head>
<meta charset="UTF-8">
<title>FBB::OFoldStreambuf(3bobcat)</title>
<style type="text/css">
    figure {text-align: center;}
    img {vertical-align: center;}
    .XXfc {margin-left:auto;margin-right:auto;}
    .XXtc {text-align: center;}
    .XXtl {text-align: left;}
    .XXtr {text-align: right;}
    .XXvt {vertical-align: top;}
    .XXvb {vertical-align: bottom;}
</style>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr/>
<h1 id="title">FBB::OFoldStreambuf(3bobcat)</h1>
<h2 id="author">Fold long lines<br/>(libbobcat-dev_4.08.02-x.tar.gz)</h2>
<h2 id="date">2005-2017</h2>


<p>
<h2 >NAME</h2>FBB::OFoldStreambuf - Folds long lines written to ostream
<p>
<h2 >SYNOPSIS</h2>
    <strong >#include &lt;bobcat/ofoldstreambuf&gt;</strong><br/>
    Linking option: <em >-lbobcat</em> 
<p>
<h2 >DESCRIPTION</h2>
    <strong >FBB::OFoldStreambuf</strong> is a specialization of <em >FBB::OFilterStreambuf</em>
folding long lines written to an <em >std::ostream</em> object. The
<em >OFoldStreambuf</em> writes the (folded) lines to a second <em >ostream</em> (the
<em >destination stream</em> which is either used by or opened by the
<em >OFoldStreambuf</em> object).
<p>
Internally the <em >OFoldStreambuf</em> defines its actions using a little
finite state automation distinguishing three states (INDENT, WS and NON_WS)
and three character categories (<em >\n</em>, other white space characters (space),
and non-space characters). The nine combinations resulting from these two sets
are discussed below.
<p>
<em >OFoldStreambuf</em> objects will never fold lines in the middle of series
of non-blank characters (called a `word' below) but will always break a line
at a white space character. The resulting lines will always appear to the
right of a configurable left margin and to the left of a configurable right
margin. There is a somewhat pathological exception to this: if a word is too
long to fit in between the margins then the word will exceed the right hand
margin. 
<p>
The indentation used for the left margins is configurable to either blanks
(the default) or tabs. When tabs are used the width of a tab character is
configurable, using a default of 8 positions in the destination stream.
<p>
What follows is a description of the <em >Finite State Automaton</em> (FSA)
defining what happens when various character types appear at its three
states. The phrase `... is written' means that the described information is
written to the <em >ostream</em> used or opened by the <em >OFoldStreambuf</em>
object. <em >OFoldStreambuf</em>'s initial state is <em >INDENT</em>:
<p>
<table>


<tr >
<td > State</td><td > char.</td><td > description</td>
 
</tr>

<tr><td colspan=3><hr/></td></tr>


<tr >
<td > INDENT</td><td > \n</td><td > a new line character is written</td>
 
</tr>


<tr >
<td > </td><td > space</td><td > the indentation is set;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > the space character is added to the indentation;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > next state: WS</td>
 
</tr>


<tr >
<td > </td><td > non-ws</td><td > the character is added to the currently stored word;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > next state: NON_WS</td>
 
</tr>

<tr><td colspan=3><hr/></td></tr>


<tr >
<td > WS</td><td > \n</td><td > a new line character is written;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > stored white-space is erased;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > next state: INDENT</td>
 
</tr>


<tr >
<td > </td><td > space</td><td > white space character is added to the currently</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > stored space characters;</td>
 
</tr>


<tr >
<td > </td><td > non-ws</td><td > the character is added to the currently stored word;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > next state: NON_WS</td>
 
</tr>

<tr><td colspan=3><hr/></td></tr>


<tr >
<td > NON_WS</td><td > \n</td><td > stored white space and word are written;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > a new line is written;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > next state: INDENT</td>
 
</tr>


<tr >
<td > </td><td > space</td><td > stored white space and word are written;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > white space character is added to the currently</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > stored space characters;</td>
 
</tr>

                
<tr >
<td > </td><td > </td><td > next state: WS</td>
 
</tr>


<tr >
<td > </td><td > non-ws</td><td > the character is added to the currently stored word;</td>
 
</tr>

<tr><td colspan=3><hr/></td></tr>


</table>
<p>
<h2 >NAMESPACE</h2>
    <strong >FBB</strong><br/>
    All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong >FBB</strong>.
<p>
<h2 >INHERITS FROM</h2>
    FBB::OFilterStreambuf
<p>
<h2 >ENUMERATION</h2>
    The enumeration <em >TabsOrBlanks</em> is used to select tabs or blanks when
writing the indentation. The default is blanks. When tabs are selected the
display width of tabs characters can be configured as well (using the default
of 8 positions for each tab-character). The enumeration has two values:
    <ul>
    <li> <strong >BLANKS</strong>:<br/>
        The default, indicating that the left margin is specified and written
as a number of blanks;
    <li> <strong >TABS</strong>:<br/>
        Indicating that the left margin is specified and written as a number
of tab-characters.
    </ul>
<p>
The enumeration <em >TrailingBlanks</em> is used to configure the
<em >OFoldStreambuf</em> object with respect to any trailing blanks that may appear
on the final line. These trailing blanks can appear on the final line it it is 
not properly terminated with a newline character but instead ends in white
space. By default these white space characters are ignored, but they may be
kept as well. The enumeration has two values:
    <ul>
    <li> <strong >IGNORE_TRAILING_BLANKS</strong>:<br/>
        This indicates that trailing blanks appearing at the final line if it
is not terminated by a newline should not be written to the destination
<em >std::ostream</em>. This is the default used by <em >OFoldStreambuf</em> objects.
    <li> <strong >KEEP_TRAILING_BLANKS</strong>:<br/>
        This indicates that trailing blanks at the final line if it is not
terminated by a newline should be written to the destination <em >std::ostream</em>
    </ul>
<p>
<h2 >CONSTRUCTORS</h2>
    <ul>
    <li> <strong >OFoldStreambuf(size_t leftIndent = 0, size_t rightMargin = 80,
                    TabsOrBlanks tob = BLANKS,
                    TrailingBlanks tb = IGNORE_TRAILING_BLANKS)</strong>:<br/>
        This constructor initializes an <em >OFoldStreambuf</em> object but does not
associate it with a destination stream. It can also be used as the default
constructor. 
<p>
<li> <strong >OFoldStreambuf(char const *fname,
                   size_t leftIndent = 0, size_t rightMargin = 80,
                    TabsOrBlanks tob = BLANKS,
                   TrailingBlanks tb = IGNORE_TRAILING_BLANKS)</strong>:<br/>
    This constructor initializes an <em >OFoldStreambuf</em> object and opens (using
<em >std::ios::out</em>) the destination stream using the name specified as its
<em >fname</em> argument. 
<p>
<li> <strong >OFoldStreambuf(std::ostream &amp;stream,
                   size_t leftIndent = 0, size_t rightMargin = 80,
                    TabsOrBlanks tob = BLANKS,
                   TrailingBlanks tb = IGNORE_TRAILING_BLANKS)</strong>:<br/>
    This constructor initializes an <em >OFoldStreambuf</em> object and uses as its
destination stream the <em >std::ostream stream</em>.
    </ul>
<p>
The destructor writes any buffered information to the destination stream
and will then flush the destination stream.
<p>
<h2 >MEMBER FUNCTIONS</h2>
     All members of <strong >FBB::OFilterStreambuf</strong>, in particular its <em >out()</em> and
<em >open()</em> members are available, as <strong >FBB::OFoldStreambuf</strong> inherits from
this class.
    <ul>
    <li> <strong >void setMargins(size_t leftMargin, size_t rightMargin)</strong>:<br/>
        This member can be used to modify the left- and right folding
margins. Note that the left margin may also be modified using the <em >FBB::lm</em>
and <em >FBB::mlm</em> manipulators.
<p>
<li> <strong >void setTrailingBlanks(TrailingBlanks tb)</strong>:<br/>
        This member can be used to modify the currently used
<em >TrailingBlanks</em> parameter.
<p>
<li> <strong >void useBlanks()</strong>:<br/>
        This member can be used to select blanks  to be used when inserting
left margins.
<p>
<li> <strong >void useTabs(size_t tabWidth = 8)</strong>:<br/>
        This member can be used to select tab-characters to be used when
inserting left margins. The second parameter is used to specify the display
width of a tab-character.
    </ul>
<p>
<h2 >STATIC MEMBER FUNCTIONS</h2>
<p>
<ul>
    <li> <strong >size_t leftMargin(std::ostreambuf const *buffer)</strong>:<br/>
        This member returns the current left margin setting of the
<em >OFoldStreambuf</em> object passed to it as its argument. The member defines a
<em >std::streambuf</em> parameter which is down cast to an <em >OFoldStreambuf</em> and
an <em >FBB::Exception</em> exception is thrown if that cast fails.
    <li> <strong >size_t rightMargin(std::ostreambuf const *buffer)</strong>:<br/>
        This member returns the current right margin setting of the
<em >OFoldStreambuf</em> object passed to it as its argument. The member's parameter
is down cast in the same way as <em >leftMargin()</em>'s argument: an <em >FBB::Exception</em>
exception is thrown if that cast fails.
    </ul>
<p>
<h2 >PROTECTED MEMBER FUNCTION</h2>
<p>
The member listed in this section implements the tasks of the comparably
named virtual function in the class's private interface. This separates the
redefinable interface from the user-interface. The class <strong >OFoldStreambuf</strong>
can, in accordance with Liskov's Substitution Principle, be used as a
<em >std:streambuf</em>; but it also offers a facility for classes deriving from
<strong >OFoldStreambuf</strong>. This facility is listed here.
    <ul>
    <li> <strong >int pSync()</strong>:<br/>
        The contents of the <strong >OFoldStreambuf</strong>'s internal buffer is flushed.
    </ul>
<p>
<h2 >EXAMPLE</h2>
        <pre>

    #include &lt;iostream&gt;
    #include &lt;ostream&gt;
    #include &lt;string&gt;
    #include &lt;bobcat/ofoldstreambuf&gt;
    
    using namespace std;
    using namespace FBB;
    
    int main()
    {
        OFoldStreambuf fb(cout, 4, 40);
        ostream out(&amp;fb);

        out &lt;&lt; lm(4);

        string line;
        while (getline(cin, line))
            out &lt;&lt; line &lt;&lt; '\n';
    
        return 0;
    }
        
</pre>

<p>
<h2 >FILES</h2>
    <em >bobcat/ofoldstreambuf</em> - defines the class interface
<p>
<h2 >SEE ALSO</h2>
    <strong >bobcat</strong>(7),  <strong >lm</strong>(3bobcat), <strong >mlm</strong>(3bobcat),
    <strong >ofilterstreambuf</strong>(3bobcat), <strong >ofoldstream</strong>(3bobcat)
<p>
<h2 >BUGS</h2>
    None Reported.
<p>

<h2 >DISTRIBUTION FILES</h2>
    <ul>
    <li> <em >bobcat_4.08.02-x.dsc</em>: detached signature;
    <li> <em >bobcat_4.08.02-x.tar.gz</em>: source archive;
    <li> <em >bobcat_4.08.02-x_i386.changes</em>: change log;
    <li> <em >libbobcat1_4.08.02-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em >libbobcat1-dev_4.08.02-x_*.deb</em>: debian package holding the
            libraries, headers and manual pages;
    <li> <em >http://sourceforge.net/projects/bobcat</em>: public archive location;
    </ul>
<p>
<h2 >BOBCAT</h2>
    Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2 >COPYRIGHT</h2>
    This is free software, distributed under the terms of the 
    GNU General Public License (GPL).
<p>
<h2 >AUTHOR</h2>
    Frank B. Brokken (<strong >f.b.brokken@rug.nl</strong>).
<p>
</body>
</html>