docs: def advReplace(document, search, replace, bs=3):
      """
      Replace all occurences of string with a different string, return updated
      document
  
      This is a modified version of python-docx.replace() that takes into
      account blocks of <bs> elements at a time. The replace element can also
      be a string or an xml etree element.
  
      What it does:
      It searches the entire document body for text blocks.
      Then scan thos text blocks for replace.
      Since the text to search could be spawned across multiple text blocks,
      we need to adopt some sort of algorithm to handle this situation.
      The smaller matching group of blocks (up to bs) is then adopted.
      If the matching group has more than one block, blocks other than first
      are cleared and all the replacement text is put on first block.
  
      Examples:
      original text blocks : [ 'Hel', 'lo,', ' world!' ]
      search / replace: 'Hello,' / 'Hi!'
      output blocks : [ 'Hi!', '', ' world!' ]
  
      original text blocks : [ 'Hel', 'lo,', ' world!' ]
      search / replace: 'Hello, world' / 'Hi!'
      output blocks : [ 'Hi!!', '', '' ]
  
      original text blocks : [ 'Hel', 'lo,', ' world!' ]
      search / replace: 'Hel' / 'Hal'
      output blocks : [ 'Hal', 'lo,', ' world!' ]
  
      @param instance  document: The original document
      @param str       search: The text to search for (regexp)
      @param mixed     replace: The replacement text or lxml.etree element to
                           append, or a list of etree elements
      @param int       bs: See above
  
      @return instance The document with replacement applied
  
      """
      # Enables debug output
      DEBUG = False
  
      newdocument = document
  
      # Compile the search regexp
      searchre = re.compile(search)
  
      # Will match against searchels. Searchels is a list that contains last
      # n text elements found in the document. 1 < n < bs
      searchels = []
  
      for element in newdocument.iter():
          if element.tag == '{%s}t' % nsprefixes['w']:  # t (text) elements
              if element.text:
                  # Add this element to searchels
                  searchels.append(element)
                  if len(searchels) > bs:
                      # Is searchels is too long, remove first elements
                      searchels.pop(0)
  
                  # Search all combinations, of searchels, starting from
                  # smaller up to bigger ones
                  # l = search lenght
                  # s = search start
                  # e = element IDs to merge
                  found = False
                  for l in range(1, len(searchels)+1):
                      if found:
                          break
                      #print "slen:", l
                      for s in range(len(searchels)):
                          if found:
                              break
                          if s+l <= len(searchels):
                              e = range(s, s+l)
                              #print "elems:", e
                              txtsearch = ''
                              for k in e:
                                  txtsearch += searchels[k].text
  
                              # Searcs for the text in the whole txtsearch
                              match = searchre.search(txtsearch)
                              if match:
                                  found = True
  
                                  # I've found something :)
                                  if DEBUG:
                                      log.debug("Found element!")
                                      log.debug("Search regexp: %s",
                                                searchre.pattern)
                                      log.debug("Requested replacement: %s",
                                                replace)
                                      log.debug("Matched text: %s", txtsearch)
                                      log.debug("Matched text (splitted): %s",
                                                map(lambda i: i.text, searchels))
                                      log.debug("Matched at position: %s",
                                                match.start())
                                      log.debug("matched in elements: %s", e)
                                      if isinstance(replace, etree._Element):
                                          log.debug("Will replace with XML CODE")
                                      elif isinstance(replace(list, tuple)):
                                          log.debug("Will replace with LIST OF"
                                                    " ELEMENTS")
                                      else:
                                          log.debug("Will replace with:",
                                                    re.sub(search, replace,
                                                           txtsearch))
  
                                  curlen = 0
                                  replaced = False
                                  for i in e:
                                      curlen += len(searchels[i].text)
                                      if curlen > match.start() and not replaced:
                                          # The match occurred in THIS element.
                                          # Puth in the whole replaced text
                                          if isinstance(replace, etree._Element):
                                              # Convert to a list and process
                                              # it later
                                              replace = [replace]
                                          if isinstance(replace, (list, tuple)):
                                              # I'm replacing with a list of
                                              # etree elements
                                              # clear the text in the tag and
                                              # append the element after the
                                              # parent paragraph
                                              # (because t elements cannot have
                                              # childs)
                                              p = findTypeParent(
                                                  searchels[i],
                                                  '{%s}p' % nsprefixes['w'])
                                              searchels[i].text = re.sub(
                                                  search, '', txtsearch)
                                              insindex = p.getparent().index(p)+1
                                              for r in replace:
                                                  p.getparent().insert(
                                                      insindex, r)
                                                  insindex += 1
                                          else:
                                              # Replacing with pure text
                                              searchels[i].text = re.sub(
                                                  search, replace, txtsearch)
                                          replaced = True
                                          log.debug(
                                              "Replacing in element #: %s", i)
                                      else:
                                          # Clears the other text elements
                                          searchels[i].text = ''
      return newdocument