docs: def identify_journals(line, kb_journals):
      """Attempt to identify all periodical titles in a reference line.
         Titles will be identified, their information (location in line,
         length in line, and non-standardised version) will be recorded,
         and they will be replaced in the working line by underscores.
         @param line: (string) - the working reference line.
         @param periodical_title_search_kb: (dictionary) - contains the
          regexp patterns used to search for a non-standard TITLE in the
          working reference line. Keyed by the TITLE string itself.
         @param periodical_title_search_keys: (list) - contains the non-
          standard periodical TITLEs to be searched for in the line. This
          list of titles has already been ordered and is used to force
          the order of searching.
         @return: (tuple) containing 4 elements:
                          + (dictionary) - the lengths of all titles
                                           matched at each given index
                                           within the line.
                          + (dictionary) - the text actually matched for
                                           each title at each given
                                           index within the line.
                          + (string)     - the working line, with the
                                           titles removed from it and
                                           replaced by underscores.
                          + (dictionary) - the totals for each bad-title
                                           found in the line.
      """
      periodical_title_search_kb = kb_journals[0]
      periodical_title_search_keys = kb_journals[2]
  
      title_matches = {}            # the text matched at the given line
      # location (i.e. the title itself)
      titles_count = {}             # sum totals of each 'bad title found in
      # line.
  
      # Begin searching:
      for title in periodical_title_search_keys:
          # search for all instances of the current periodical title
          # in the line:
          # for each matched periodical title:
          for title_match in periodical_title_search_kb[title].finditer(line):
  
              if title not in titles_count:
                  # Add this title into the titles_count dictionary:
                  titles_count[title] = 1
              else:
                  # Add 1 to the count for the given title:
                  titles_count[title] += 1
  
              # record the details of this title match:
              # record the match length:
              title_matches[title_match.start()] = title
  
              len_to_replace = len(title)
  
              # replace the matched title text in the line it n * '_',
              # where n is the length of the matched title:
              line = u"".join((line[:title_match.start()],
                               u"_" * len_to_replace,
                               line[title_match.start() + len_to_replace:]))
  
      # return recorded information about matched periodical titles,
      # along with the newly changed working line:
      return title_matches, line, titles_count