docs: def put_it_together(cur_image, caption, context, extracted_image_data,
                      line_index, lines):
      """Put it together.
  
      Takes the current image(s) and caption(s) and assembles them into
      something useful in the extracted_image_data list.
  
      :param: cur_image (string || list): the image currently being dealt with,
          or the list of images, in the case of subimages
      :param: caption (string || list): the caption or captions currently in
          scope
      :param: extracted_image_data ([(string, string), (string, string), ...]):
          a list of tuples of images matched to captions from this document.
      :param: line_index (int): the index where we are in the lines (for
          searchback and searchforward purposes)
      :param: lines ([string, string, ...]): the lines in the TeX
  
      :return: (cur_image, caption, extracted_image_data): the same arguments it
          was sent, processed appropriately
      """
      if type(cur_image) == list:
          if cur_image[MAIN_CAPTION_OR_IMAGE] == 'ERROR':
              cur_image[MAIN_CAPTION_OR_IMAGE] = ''
          for image in cur_image[SUB_CAPTION_OR_IMAGE]:
              if image == 'ERROR':
                  cur_image[SUB_CAPTION_OR_IMAGE].remove(image)
  
      if cur_image != '' and caption != '':
  
          if type(cur_image) == list and type(caption) == list:
  
              if cur_image[MAIN_CAPTION_OR_IMAGE] != '' and\
                      caption[MAIN_CAPTION_OR_IMAGE] != '':
                  extracted_image_data.append(
                      (cur_image[MAIN_CAPTION_OR_IMAGE],
                       caption[MAIN_CAPTION_OR_IMAGE],
                       context))
              if type(cur_image[MAIN_CAPTION_OR_IMAGE]) == list:
                  # why is the main image a list?
                  # it's a good idea to attach the main caption to other
                  # things, but the main image can only be used once
                  cur_image[MAIN_CAPTION_OR_IMAGE] = ''
  
              if type(cur_image[SUB_CAPTION_OR_IMAGE]) == list:
                  if type(caption[SUB_CAPTION_OR_IMAGE]) == list:
                      for index in \
                              range(len(cur_image[SUB_CAPTION_OR_IMAGE])):
                          if index < len(caption[SUB_CAPTION_OR_IMAGE]):
                              long_caption = \
                                  caption[MAIN_CAPTION_OR_IMAGE] + ' : ' + \
                                  caption[SUB_CAPTION_OR_IMAGE][index]
                          else:
                              long_caption = \
                                  caption[MAIN_CAPTION_OR_IMAGE] + ' : ' + \
                                  'Caption not extracted'
                          extracted_image_data.append(
                              (cur_image[SUB_CAPTION_OR_IMAGE][index],
                               long_caption, context))
  
                  else:
                      long_caption = caption[MAIN_CAPTION_OR_IMAGE] + \
                          ' : ' + caption[SUB_CAPTION_OR_IMAGE]
                      for sub_image in cur_image[SUB_CAPTION_OR_IMAGE]:
                          extracted_image_data.append(
                              (sub_image, long_caption, context))
  
              else:
                  if type(caption[SUB_CAPTION_OR_IMAGE]) == list:
                      long_caption = caption[MAIN_CAPTION_OR_IMAGE]
                      for sub_cap in caption[SUB_CAPTION_OR_IMAGE]:
                          long_caption = long_caption + ' : ' + sub_cap
                      extracted_image_data.append(
                          (cur_image[SUB_CAPTION_OR_IMAGE], long_caption,
                           context))
                  else:
                      # wtf are they lists for?
                      extracted_image_data.append(
                          (cur_image[SUB_CAPTION_OR_IMAGE],
                           caption[SUB_CAPTION_OR_IMAGE], context))
  
          elif type(cur_image) == list:
              if cur_image[MAIN_CAPTION_OR_IMAGE] != '':
                  extracted_image_data.append(
                      (cur_image[MAIN_CAPTION_OR_IMAGE], caption, context))
              if type(cur_image[SUB_CAPTION_OR_IMAGE]) == list:
                  for image in cur_image[SUB_CAPTION_OR_IMAGE]:
                      extracted_image_data.append((image, caption, context))
              else:
                  extracted_image_data.append(
                      (cur_image[SUB_CAPTION_OR_IMAGE], caption, context))
  
          elif type(caption) == list:
              if caption[MAIN_CAPTION_OR_IMAGE] != '':
                  extracted_image_data.append(
                      (cur_image, caption[MAIN_CAPTION_OR_IMAGE], context))
              if type(caption[SUB_CAPTION_OR_IMAGE]) == list:
                  # multiple caps for one image:
                  long_caption = caption[MAIN_CAPTION_OR_IMAGE]
                  for subcap in caption[SUB_CAPTION_OR_IMAGE]:
                      if long_caption != '':
                          long_caption += ' : '
                      long_caption += subcap
                  extracted_image_data.append((cur_image, long_caption, context))
              else:
                  extracted_image_data.append(
                      (cur_image, caption[SUB_CAPTION_OR_IMAGE]. context))
  
          else:
              extracted_image_data.append((cur_image, caption, context))
  
      elif cur_image != '' and caption == '':
          # we may have missed the caption somewhere.
          REASONABLE_SEARCHBACK = 25
          REASONABLE_SEARCHFORWARD = 5
          curly_no_tag_preceding = '(?<!\\w){'
  
          for searchback in range(REASONABLE_SEARCHBACK):
              if line_index - searchback < 0:
                  continue
  
              back_line = lines[line_index - searchback]
              m = re.search(curly_no_tag_preceding, back_line)
              if m:
                  open_curly = m.start()
                  open_curly, open_curly_line, close_curly, \
                      close_curly_line = find_open_and_close_braces(
                          line_index - searchback, open_curly, '{', lines)
  
                  cap_begin = open_curly + 1
  
                  caption = assemble_caption(open_curly_line, cap_begin,
                                             close_curly_line, close_curly,
                                             lines)
  
                  if type(cur_image) == list:
                      extracted_image_data.append(
                          (cur_image[MAIN_CAPTION_OR_IMAGE], caption, context))
                      for sub_img in cur_image[SUB_CAPTION_OR_IMAGE]:
                          extracted_image_data.append(
                              (sub_img, caption, context))
                  else:
                      extracted_image_data.append((cur_image, caption, context))
                      break
  
          if caption == '':
              for searchforward in range(REASONABLE_SEARCHFORWARD):
                  if line_index + searchforward >= len(lines):
                      break
  
                  fwd_line = lines[line_index + searchforward]
                  m = re.search(curly_no_tag_preceding, fwd_line)
  
                  if m:
                      open_curly = m.start()
                      open_curly, open_curly_line, close_curly,\
                          close_curly_line = find_open_and_close_braces(
                              line_index + searchforward, open_curly, '{', lines)
  
                      cap_begin = open_curly + 1
  
                      caption = assemble_caption(open_curly_line,
                                                 cap_begin, close_curly_line,
                                                 close_curly, lines)
  
                      if type(cur_image) == list:
                          extracted_image_data.append(
                              (cur_image[MAIN_CAPTION_OR_IMAGE],
                               caption, context))
                          for sub_img in cur_image[SUB_CAPTION_OR_IMAGE]:
                              extracted_image_data.append(
                                  (sub_img, caption, context))
                      else:
                          extracted_image_data.append(
                              (cur_image, caption, context))
                      break
  
          if caption == '':
              if type(cur_image) == list:
                  extracted_image_data.append(
                      (cur_image[MAIN_CAPTION_OR_IMAGE], 'No caption found',
                       context))
                  for sub_img in cur_image[SUB_CAPTION_OR_IMAGE]:
                      extracted_image_data.append(
                          (sub_img, 'No caption', context))
              else:
                  extracted_image_data.append(
                      (cur_image, 'No caption found', context))
  
      elif caption != '' and cur_image == '':
          if type(caption) == list:
              long_caption = caption[MAIN_CAPTION_OR_IMAGE]
              for subcap in caption[SUB_CAPTION_OR_IMAGE]:
                  long_caption = long_caption + ': ' + subcap
          else:
              long_caption = caption
          extracted_image_data.append(('', 'noimg' + long_caption, context))
  
      # if we're leaving the figure, no sense keeping the data
      cur_image = ''
      caption = ''
  
      return cur_image, caption, extracted_image_data