This file is indexed.

/usr/lib/python2.7/dist-packages/mercurial/minirst.py is in mercurial-common 3.7.3-1ubuntu1.

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
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
# minirst.py - minimal reStructuredText parser
#
# Copyright 2009, 2010 Matt Mackall <mpm@selenic.com> and others
#
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.

"""simplified reStructuredText parser.

This parser knows just enough about reStructuredText to parse the
Mercurial docstrings.

It cheats in a major way: nested blocks are not really nested. They
are just indented blocks that look like they are nested. This relies
on the user to keep the right indentation for the blocks.

Remember to update https://mercurial-scm.org/wiki/HelpStyleGuide
when adding support for new constructs.
"""

from __future__ import absolute_import

import cgi
import re

from .i18n import _
from . import (
    encoding,
    util,
)

def section(s):
    return "%s\n%s\n\n" % (s, "\"" * encoding.colwidth(s))

def subsection(s):
    return "%s\n%s\n\n" % (s, '=' * encoding.colwidth(s))

def subsubsection(s):
    return "%s\n%s\n\n" % (s, "-" * encoding.colwidth(s))

def subsubsubsection(s):
    return "%s\n%s\n\n" % (s, "." * encoding.colwidth(s))

def replace(text, substs):
    '''
    Apply a list of (find, replace) pairs to a text.

    >>> replace("foo bar", [('f', 'F'), ('b', 'B')])
    'Foo Bar'
    >>> encoding.encoding = 'latin1'
    >>> replace('\\x81\\\\', [('\\\\', '/')])
    '\\x81/'
    >>> encoding.encoding = 'shiftjis'
    >>> replace('\\x81\\\\', [('\\\\', '/')])
    '\\x81\\\\'
    '''

    # some character encodings (cp932 for Japanese, at least) use
    # ASCII characters other than control/alphabet/digit as a part of
    # multi-bytes characters, so direct replacing with such characters
    # on strings in local encoding causes invalid byte sequences.
    utext = text.decode(encoding.encoding)
    for f, t in substs:
        utext = utext.replace(f.decode("ascii"), t.decode("ascii"))
    return utext.encode(encoding.encoding)

_blockre = re.compile(r"\n(?:\s*\n)+")

def findblocks(text):
    """Find continuous blocks of lines in text.

    Returns a list of dictionaries representing the blocks. Each block
    has an 'indent' field and a 'lines' field.
    """
    blocks = []
    for b in _blockre.split(text.lstrip('\n').rstrip()):
        lines = b.splitlines()
        if lines:
            indent = min((len(l) - len(l.lstrip())) for l in lines)
            lines = [l[indent:] for l in lines]
            blocks.append({'indent': indent, 'lines': lines})
    return blocks

def findliteralblocks(blocks):
    """Finds literal blocks and adds a 'type' field to the blocks.

    Literal blocks are given the type 'literal', all other blocks are
    given type the 'paragraph'.
    """
    i = 0
    while i < len(blocks):
        # Searching for a block that looks like this:
        #
        # +------------------------------+
        # | paragraph                    |
        # | (ends with "::")             |
        # +------------------------------+
        #    +---------------------------+
        #    | indented literal block    |
        #    +---------------------------+
        blocks[i]['type'] = 'paragraph'
        if blocks[i]['lines'][-1].endswith('::') and i + 1 < len(blocks):
            indent = blocks[i]['indent']
            adjustment = blocks[i + 1]['indent'] - indent

            if blocks[i]['lines'] == ['::']:
                # Expanded form: remove block
                del blocks[i]
                i -= 1
            elif blocks[i]['lines'][-1].endswith(' ::'):
                # Partially minimized form: remove space and both
                # colons.
                blocks[i]['lines'][-1] = blocks[i]['lines'][-1][:-3]
            elif len(blocks[i]['lines']) == 1 and \
                 blocks[i]['lines'][0].lstrip(' ').startswith('.. ') and \
                 blocks[i]['lines'][0].find(' ', 3) == -1:
                # directive on its own line, not a literal block
                i += 1
                continue
            else:
                # Fully minimized form: remove just one colon.
                blocks[i]['lines'][-1] = blocks[i]['lines'][-1][:-1]

            # List items are formatted with a hanging indent. We must
            # correct for this here while we still have the original
            # information on the indentation of the subsequent literal
            # blocks available.
            m = _bulletre.match(blocks[i]['lines'][0])
            if m:
                indent += m.end()
                adjustment -= m.end()

            # Mark the following indented blocks.
            while i + 1 < len(blocks) and blocks[i + 1]['indent'] > indent:
                blocks[i + 1]['type'] = 'literal'
                blocks[i + 1]['indent'] -= adjustment
                i += 1
        i += 1
    return blocks

_bulletre = re.compile(r'(-|[0-9A-Za-z]+\.|\(?[0-9A-Za-z]+\)|\|) ')
_optionre = re.compile(r'^(-([a-zA-Z0-9]), )?(--[a-z0-9-]+)'
                       r'((.*)  +)(.*)$')
_fieldre = re.compile(r':(?![: ])([^:]*)(?<! ):[ ]+(.*)')
_definitionre = re.compile(r'[^ ]')
_tablere = re.compile(r'(=+\s+)*=+')

def splitparagraphs(blocks):
    """Split paragraphs into lists."""
    # Tuples with (list type, item regexp, single line items?). Order
    # matters: definition lists has the least specific regexp and must
    # come last.
    listtypes = [('bullet', _bulletre, True),
                 ('option', _optionre, True),
                 ('field', _fieldre, True),
                 ('definition', _definitionre, False)]

    def match(lines, i, itemre, singleline):
        """Does itemre match an item at line i?

        A list item can be followed by an indented line or another list
        item (but only if singleline is True).
        """
        line1 = lines[i]
        line2 = i + 1 < len(lines) and lines[i + 1] or ''
        if not itemre.match(line1):
            return False
        if singleline:
            return line2 == '' or line2[0] == ' ' or itemre.match(line2)
        else:
            return line2.startswith(' ')

    i = 0
    while i < len(blocks):
        if blocks[i]['type'] == 'paragraph':
            lines = blocks[i]['lines']
            for type, itemre, singleline in listtypes:
                if match(lines, 0, itemre, singleline):
                    items = []
                    for j, line in enumerate(lines):
                        if match(lines, j, itemre, singleline):
                            items.append({'type': type, 'lines': [],
                                          'indent': blocks[i]['indent']})
                        items[-1]['lines'].append(line)
                    blocks[i:i + 1] = items
                    break
        i += 1
    return blocks

_fieldwidth = 14

def updatefieldlists(blocks):
    """Find key for field lists."""
    i = 0
    while i < len(blocks):
        if blocks[i]['type'] != 'field':
            i += 1
            continue

        j = i
        while j < len(blocks) and blocks[j]['type'] == 'field':
            m = _fieldre.match(blocks[j]['lines'][0])
            key, rest = m.groups()
            blocks[j]['lines'][0] = rest
            blocks[j]['key'] = key
            j += 1

        i = j + 1

    return blocks

def updateoptionlists(blocks):
    i = 0
    while i < len(blocks):
        if blocks[i]['type'] != 'option':
            i += 1
            continue

        optstrwidth = 0
        j = i
        while j < len(blocks) and blocks[j]['type'] == 'option':
            m = _optionre.match(blocks[j]['lines'][0])

            shortoption = m.group(2)
            group3 = m.group(3)
            longoption = group3[2:].strip()
            desc = m.group(6).strip()
            longoptionarg = m.group(5).strip()
            blocks[j]['lines'][0] = desc

            noshortop = ''
            if not shortoption:
                noshortop = '   '

            opt = "%s%s" %   (shortoption and "-%s " % shortoption or '',
                            ("%s--%s %s") % (noshortop, longoption,
                                             longoptionarg))
            opt = opt.rstrip()
            blocks[j]['optstr'] = opt
            optstrwidth = max(optstrwidth, encoding.colwidth(opt))
            j += 1

        for block in blocks[i:j]:
            block['optstrwidth'] = optstrwidth
        i = j + 1
    return blocks

def prunecontainers(blocks, keep):
    """Prune unwanted containers.

    The blocks must have a 'type' field, i.e., they should have been
    run through findliteralblocks first.
    """
    pruned = []
    i = 0
    while i + 1 < len(blocks):
        # Searching for a block that looks like this:
        #
        # +-------+---------------------------+
        # | ".. container ::" type            |
        # +---+                               |
        #     | blocks                        |
        #     +-------------------------------+
        if (blocks[i]['type'] == 'paragraph' and
            blocks[i]['lines'][0].startswith('.. container::')):
            indent = blocks[i]['indent']
            adjustment = blocks[i + 1]['indent'] - indent
            containertype = blocks[i]['lines'][0][15:]
            prune = True
            for c in keep:
                if c in containertype.split('.'):
                    prune = False
            if prune:
                pruned.append(containertype)

            # Always delete "..container:: type" block
            del blocks[i]
            j = i
            i -= 1
            while j < len(blocks) and blocks[j]['indent'] > indent:
                if prune:
                    del blocks[j]
                else:
                    blocks[j]['indent'] -= adjustment
                    j += 1
        i += 1
    return blocks, pruned

_sectionre = re.compile(r"""^([-=`:.'"~^_*+#])\1+$""")

def findtables(blocks):
    '''Find simple tables

       Only simple one-line table elements are supported
    '''

    for block in blocks:
        # Searching for a block that looks like this:
        #
        # === ==== ===
        #  A    B   C
        # === ==== ===  <- optional
        #  1    2   3
        #  x    y   z
        # === ==== ===
        if (block['type'] == 'paragraph' and
            len(block['lines']) > 2 and
            _tablere.match(block['lines'][0]) and
            block['lines'][0] == block['lines'][-1]):
            block['type'] = 'table'
            block['header'] = False
            div = block['lines'][0]

            # column markers are ASCII so we can calculate column
            # position in bytes
            columns = [x for x in xrange(len(div))
                       if div[x] == '=' and (x == 0 or div[x - 1] == ' ')]
            rows = []
            for l in block['lines'][1:-1]:
                if l == div:
                    block['header'] = True
                    continue
                row = []
                # we measure columns not in bytes or characters but in
                # colwidth which makes things tricky
                pos = columns[0] # leading whitespace is bytes
                for n, start in enumerate(columns):
                    if n + 1 < len(columns):
                        width = columns[n + 1] - start
                        v = encoding.getcols(l, pos, width) # gather columns
                        pos += len(v) # calculate byte position of end
                        row.append(v.strip())
                    else:
                        row.append(l[pos:].strip())
                rows.append(row)

            block['table'] = rows

    return blocks

def findsections(blocks):
    """Finds sections.

    The blocks must have a 'type' field, i.e., they should have been
    run through findliteralblocks first.
    """
    for block in blocks:
        # Searching for a block that looks like this:
        #
        # +------------------------------+
        # | Section title                |
        # | -------------                |
        # +------------------------------+
        if (block['type'] == 'paragraph' and
            len(block['lines']) == 2 and
            encoding.colwidth(block['lines'][0]) == len(block['lines'][1]) and
            _sectionre.match(block['lines'][1])):
            block['underline'] = block['lines'][1][0]
            block['type'] = 'section'
            del block['lines'][1]
    return blocks

def inlineliterals(blocks):
    substs = [('``', '"')]
    for b in blocks:
        if b['type'] in ('paragraph', 'section'):
            b['lines'] = [replace(l, substs) for l in b['lines']]
    return blocks

def hgrole(blocks):
    substs = [(':hg:`', "'hg "), ('`', "'")]
    for b in blocks:
        if b['type'] in ('paragraph', 'section'):
            # Turn :hg:`command` into "hg command". This also works
            # when there is a line break in the command and relies on
            # the fact that we have no stray back-quotes in the input
            # (run the blocks through inlineliterals first).
            b['lines'] = [replace(l, substs) for l in b['lines']]
    return blocks

def addmargins(blocks):
    """Adds empty blocks for vertical spacing.

    This groups bullets, options, and definitions together with no vertical
    space between them, and adds an empty block between all other blocks.
    """
    i = 1
    while i < len(blocks):
        if (blocks[i]['type'] == blocks[i - 1]['type'] and
            blocks[i]['type'] in ('bullet', 'option', 'field')):
            i += 1
        elif not blocks[i - 1]['lines']:
            # no lines in previous block, do not separate
            i += 1
        else:
            blocks.insert(i, {'lines': [''], 'indent': 0, 'type': 'margin'})
            i += 2
    return blocks

def prunecomments(blocks):
    """Remove comments."""
    i = 0
    while i < len(blocks):
        b = blocks[i]
        if b['type'] == 'paragraph' and (b['lines'][0].startswith('.. ') or
                                         b['lines'] == ['..']):
            del blocks[i]
            if i < len(blocks) and blocks[i]['type'] == 'margin':
                del blocks[i]
        else:
            i += 1
    return blocks

_admonitionre = re.compile(r"\.\. (admonition|attention|caution|danger|"
                           r"error|hint|important|note|tip|warning)::",
                           flags=re.IGNORECASE)

def findadmonitions(blocks):
    """
    Makes the type of the block an admonition block if
    the first line is an admonition directive
    """
    i = 0
    while i < len(blocks):
        m = _admonitionre.match(blocks[i]['lines'][0])
        if m:
            blocks[i]['type'] = 'admonition'
            admonitiontitle = blocks[i]['lines'][0][3:m.end() - 2].lower()

            firstline = blocks[i]['lines'][0][m.end() + 1:]
            if firstline:
                blocks[i]['lines'].insert(1, '   ' + firstline)

            blocks[i]['admonitiontitle'] = admonitiontitle
            del blocks[i]['lines'][0]
        i = i + 1
    return blocks

_admonitiontitles = {'attention': _('Attention:'),
                     'caution': _('Caution:'),
                     'danger': _('!Danger!')  ,
                     'error': _('Error:'),
                     'hint': _('Hint:'),
                     'important': _('Important:'),
                     'note': _('Note:'),
                     'tip': _('Tip:'),
                     'warning': _('Warning!')}

def formatoption(block, width):
    desc = ' '.join(map(str.strip, block['lines']))
    colwidth = encoding.colwidth(block['optstr'])
    usablewidth = width - 1
    hanging = block['optstrwidth']
    initindent = '%s%s  ' % (block['optstr'], ' ' * ((hanging - colwidth)))
    hangindent = ' ' * (encoding.colwidth(initindent) + 1)
    return ' %s\n' % (util.wrap(desc, usablewidth,
                                           initindent=initindent,
                                           hangindent=hangindent))

def formatblock(block, width):
    """Format a block according to width."""
    if width <= 0:
        width = 78
    indent = ' ' * block['indent']
    if block['type'] == 'admonition':
        admonition = _admonitiontitles[block['admonitiontitle']]
        if not block['lines']:
            return indent + admonition + '\n'
        hang = len(block['lines'][-1]) - len(block['lines'][-1].lstrip())

        defindent = indent + hang * ' '
        text = ' '.join(map(str.strip, block['lines']))
        return '%s\n%s\n' % (indent + admonition,
                             util.wrap(text, width=width,
                                       initindent=defindent,
                                       hangindent=defindent))
    if block['type'] == 'margin':
        return '\n'
    if block['type'] == 'literal':
        indent += '  '
        return indent + ('\n' + indent).join(block['lines']) + '\n'
    if block['type'] == 'section':
        underline = encoding.colwidth(block['lines'][0]) * block['underline']
        return "%s%s\n%s%s\n" % (indent, block['lines'][0],indent, underline)
    if block['type'] == 'table':
        table = block['table']
        # compute column widths
        widths = [max([encoding.colwidth(e) for e in c]) for c in zip(*table)]
        text = ''
        span = sum(widths) + len(widths) - 1
        indent = ' ' * block['indent']
        hang = ' ' * (len(indent) + span - widths[-1])

        for row in table:
            l = []
            for w, v in zip(widths, row):
                pad = ' ' * (w - encoding.colwidth(v))
                l.append(v + pad)
            l = ' '.join(l)
            l = util.wrap(l, width=width, initindent=indent, hangindent=hang)
            if not text and block['header']:
                text = l + '\n' + indent + '-' * (min(width, span)) + '\n'
            else:
                text += l + "\n"
        return text
    if block['type'] == 'definition':
        term = indent + block['lines'][0]
        hang = len(block['lines'][-1]) - len(block['lines'][-1].lstrip())
        defindent = indent + hang * ' '
        text = ' '.join(map(str.strip, block['lines'][1:]))
        return '%s\n%s\n' % (term, util.wrap(text, width=width,
                                             initindent=defindent,
                                             hangindent=defindent))
    subindent = indent
    if block['type'] == 'bullet':
        if block['lines'][0].startswith('| '):
            # Remove bullet for line blocks and add no extra
            # indentation.
            block['lines'][0] = block['lines'][0][2:]
        else:
            m = _bulletre.match(block['lines'][0])
            subindent = indent + m.end() * ' '
    elif block['type'] == 'field':
        key = block['key']
        subindent = indent + _fieldwidth * ' '
        if len(key) + 2 > _fieldwidth:
            # key too large, use full line width
            key = key.ljust(width)
        else:
            # key fits within field width
            key = key.ljust(_fieldwidth)
        block['lines'][0] = key + block['lines'][0]
    elif block['type'] == 'option':
        return formatoption(block, width)

    text = ' '.join(map(str.strip, block['lines']))
    return util.wrap(text, width=width,
                     initindent=indent,
                     hangindent=subindent) + '\n'

def formathtml(blocks):
    """Format RST blocks as HTML"""

    out = []
    headernest = ''
    listnest = []

    def escape(s):
        return cgi.escape(s, True)

    def openlist(start, level):
        if not listnest or listnest[-1][0] != start:
            listnest.append((start, level))
            out.append('<%s>\n' % start)

    blocks = [b for b in blocks if b['type'] != 'margin']

    for pos, b in enumerate(blocks):
        btype = b['type']
        level = b['indent']
        lines = b['lines']

        if btype == 'admonition':
            admonition = escape(_admonitiontitles[b['admonitiontitle']])
            text = escape(' '.join(map(str.strip, lines)))
            out.append('<p>\n<b>%s</b> %s\n</p>\n' % (admonition, text))
        elif btype == 'paragraph':
            out.append('<p>\n%s\n</p>\n' % escape('\n'.join(lines)))
        elif btype == 'margin':
            pass
        elif btype == 'literal':
            out.append('<pre>\n%s\n</pre>\n' % escape('\n'.join(lines)))
        elif btype == 'section':
            i = b['underline']
            if i not in headernest:
                headernest += i
            level = headernest.index(i) + 1
            out.append('<h%d>%s</h%d>\n' % (level, escape(lines[0]), level))
        elif btype == 'table':
            table = b['table']
            out.append('<table>\n')
            for row in table:
                out.append('<tr>')
                for v in row:
                    out.append('<td>')
                    out.append(escape(v))
                    out.append('</td>')
                    out.append('\n')
                out.pop()
                out.append('</tr>\n')
            out.append('</table>\n')
        elif btype == 'definition':
            openlist('dl', level)
            term = escape(lines[0])
            text = escape(' '.join(map(str.strip, lines[1:])))
            out.append(' <dt>%s\n <dd>%s\n' % (term, text))
        elif btype == 'bullet':
            bullet, head = lines[0].split(' ', 1)
            if bullet == '-':
                openlist('ul', level)
            else:
                openlist('ol', level)
            out.append(' <li> %s\n' % escape(' '.join([head] + lines[1:])))
        elif btype == 'field':
            openlist('dl', level)
            key = escape(b['key'])
            text = escape(' '.join(map(str.strip, lines)))
            out.append(' <dt>%s\n <dd>%s\n' % (key, text))
        elif btype == 'option':
            openlist('dl', level)
            opt = escape(b['optstr'])
            desc = escape(' '.join(map(str.strip, lines)))
            out.append(' <dt>%s\n <dd>%s\n' % (opt, desc))

        # close lists if indent level of next block is lower
        if listnest:
            start, level = listnest[-1]
            if pos == len(blocks) - 1:
                out.append('</%s>\n' % start)
                listnest.pop()
            else:
                nb = blocks[pos + 1]
                ni = nb['indent']
                if (ni < level or
                    (ni == level and
                     nb['type'] not in 'definition bullet field option')):
                    out.append('</%s>\n' % start)
                    listnest.pop()

    return ''.join(out)

def parse(text, indent=0, keep=None):
    """Parse text into a list of blocks"""
    pruned = []
    blocks = findblocks(text)
    for b in blocks:
        b['indent'] += indent
    blocks = findliteralblocks(blocks)
    blocks = findtables(blocks)
    blocks, pruned = prunecontainers(blocks, keep or [])
    blocks = findsections(blocks)
    blocks = inlineliterals(blocks)
    blocks = hgrole(blocks)
    blocks = splitparagraphs(blocks)
    blocks = updatefieldlists(blocks)
    blocks = updateoptionlists(blocks)
    blocks = findadmonitions(blocks)
    blocks = addmargins(blocks)
    blocks = prunecomments(blocks)
    return blocks, pruned

def formatblocks(blocks, width):
    text = ''.join(formatblock(b, width) for b in blocks)
    return text

def format(text, width=80, indent=0, keep=None, style='plain', section=None):
    """Parse and format the text according to width."""
    blocks, pruned = parse(text, indent, keep or [])
    parents = []
    if section:
        sections = getsections(blocks)
        blocks = []
        i = 0
        lastparents = []
        synthetic = []
        collapse = True
        while i < len(sections):
            name, nest, b = sections[i]
            del parents[nest:]
            parents.append(i)
            if name == section:
                if lastparents != parents:
                    llen = len(lastparents)
                    plen = len(parents)
                    if llen and llen != plen:
                        collapse = False
                    s = []
                    for j in xrange(3, plen - 1):
                        parent = parents[j]
                        if (j >= llen or
                            lastparents[j] != parent):
                            s.append(len(blocks))
                            sec = sections[parent][2]
                            blocks.append(sec[0])
                            blocks.append(sec[-1])
                    if s:
                        synthetic.append(s)

                lastparents = parents[:]
                blocks.extend(b)

                ## Also show all subnested sections
                while i + 1 < len(sections) and sections[i + 1][1] > nest:
                    i += 1
                    blocks.extend(sections[i][2])
            i += 1
        if collapse:
            synthetic.reverse()
            for s in synthetic:
                path = [blocks[i]['lines'][0] for i in s]
                real = s[-1] + 2
                realline = blocks[real]['lines']
                realline[0] = ('"%s"' %
                               '.'.join(path + [realline[0]]).replace('"', ''))
                del blocks[s[0]:real]

    if style == 'html':
        text = formathtml(blocks)
    else:
        text = ''.join(formatblock(b, width) for b in blocks)
    if keep is None:
        return text
    else:
        return text, pruned

def getsections(blocks):
    '''return a list of (section name, nesting level, blocks) tuples'''
    nest = ""
    level = 0
    secs = []

    def getname(b):
        if b['type'] == 'field':
            x = b['key']
        else:
            x = b['lines'][0]
        x = x.lower().strip('"')
        if '(' in x:
            x = x.split('(')[0]
        return x

    for b in blocks:
        if b['type'] == 'section':
            i = b['underline']
            if i not in nest:
                nest += i
            level = nest.index(i) + 1
            nest = nest[:level]
            secs.append((getname(b), level, [b]))
        elif b['type'] in ('definition', 'field'):
            i = ' '
            if i not in nest:
                nest += i
            level = nest.index(i) + 1
            nest = nest[:level]
            for i in range(1, len(secs) + 1):
                sec = secs[-i]
                if sec[1] < level:
                    break
                siblings = [a for a in sec[2] if a['type'] == 'definition']
                if siblings:
                    siblingindent = siblings[-1]['indent']
                    indent = b['indent']
                    if siblingindent < indent:
                        level += 1
                        break
                    elif siblingindent == indent:
                        level = sec[1]
                        break
            secs.append((getname(b), level, [b]))
        else:
            if not secs:
                # add an initial empty section
                secs = [('', 0, [])]
            if b['type'] != 'margin':
                pointer = 1
                bindent = b['indent']
                while pointer < len(secs):
                    section = secs[-pointer][2][0]
                    if section['type'] != 'margin':
                        sindent = section['indent']
                        if len(section['lines']) > 1:
                            sindent += len(section['lines'][1]) - \
                              len(section['lines'][1].lstrip(' '))
                        if bindent >= sindent:
                            break
                    pointer += 1
                if pointer > 1:
                    blevel = secs[-pointer][1]
                    if section['type'] != b['type']:
                        blevel += 1
                    secs.append(('', blevel, []))
            secs[-1][2].append(b)
    return secs

def decorateblocks(blocks, width):
    '''generate a list of (section name, line text) pairs for search'''
    lines = []
    for s in getsections(blocks):
        section = s[0]
        text = formatblocks(s[2], width)
        lines.append([(section, l) for l in text.splitlines(True)])
    return lines

def maketable(data, indent=0, header=False):
    '''Generate an RST table for the given table data as a list of lines'''

    widths = [max(encoding.colwidth(e) for e in c) for c in zip(*data)]
    indent = ' ' * indent
    div = indent + ' '.join('=' * w for w in widths) + '\n'

    out = [div]
    for row in data:
        l = []
        for w, v in zip(widths, row):
            if '\n' in v:
                # only remove line breaks and indentation, long lines are
                # handled by the next tool
                v = ' '.join(e.lstrip() for e in v.split('\n'))
            pad = ' ' * (w - encoding.colwidth(v))
            l.append(v + pad)
        out.append(indent + ' '.join(l) + "\n")
    if header and len(data) > 1:
        out.insert(2, div)
    out.append(div)
    return out