docs: def parse_tagged_reference_line(line_marker,
                                  line,
                                  identified_dois,
                                  identified_urls):
      """ Given a single tagged reference line, convert it to its MARC-XML representation.
          Try to find all tags and extract their contents and their types into corresponding
          dictionary elements. Append each dictionary tag representation onto a list, which
          is given to 'build_formatted_xml_citation()' where the correct xml output will be generated.
  
          This method is dumb, with very few heuristics. It simply looks for tags, and makes dictionaries
          from the data it finds in a tagged reference line.
  
          @param line_marker: (string) The line marker for this single reference line (e.g. [19])
          @param line: (string) The tagged reference line.
          @param identified_dois: (list) a list of dois which were found in this line. The ordering of
          dois corresponds to the ordering of tags in the line, reading from left to right.
          @param identified_urls: (list) a list of urls which were found in this line. The ordering of
          urls corresponds to the ordering of tags in the line, reading from left to right.
          @param which format to use for references,
          roughly "<title> <volume> <page>" or "<title>,<volume>,<page>"
          @return xml_line: (string) the MARC-XML representation of the tagged reference line
          @return count_*: (integer) the number of * (pieces of info) found in the reference line.
      """
      count_misc = count_title = count_reportnum = count_url = count_doi = count_auth_group = 0
      processed_line = line
      cur_misc_txt = u""
  
      tag_match = re_tagged_citation.search(processed_line)
  
      # contains a list of dictionary entries of previously cited items
      citation_elements = []
      # the last tag element found when working from left-to-right across the
      # line
      identified_citation_element = None
  
      while tag_match is not None:
          # While there are tags inside this reference line...
          tag_match_start = tag_match.start()
          tag_match_end = tag_match.end()
          tag_type = tag_match.group(1)
          cur_misc_txt += processed_line[0:tag_match_start]
  
          # Catches both standard titles, and ibid's
          if tag_type.find("JOURNAL") != -1:
              # This tag is an identified journal TITLE. It should be followed
              # by VOLUME, YEAR and PAGE tags.
  
              # See if the found title has been tagged as an ibid:
              # <cds.JOURNALibid>
              if tag_match.group('ibid'):
                  is_ibid = True
                  closing_tag_length = len(
                      CFG_REFEXTRACT_MARKER_CLOSING_TITLE_IBID)
                  idx_closing_tag = processed_line.find(CFG_REFEXTRACT_MARKER_CLOSING_TITLE_IBID,
                                                        tag_match_end)
              else:
                  is_ibid = False
                  closing_tag_length = len(CFG_REFEXTRACT_MARKER_CLOSING_TITLE)
                  # extract the title from the line:
                  idx_closing_tag = processed_line.find(CFG_REFEXTRACT_MARKER_CLOSING_TITLE,
                                                        tag_match_end)
  
              if idx_closing_tag == -1:
                  # no closing TITLE tag found - get rid of the solitary tag
                  processed_line = processed_line[tag_match_end:]
                  identified_citation_element = None
              else:
  
                  # Closing tag was found:
                  # The title text to be used in the marked-up citation:
                  title_text = processed_line[tag_match_end:idx_closing_tag]
  
                  # Now trim this matched title and its tags from the start of
                  # the line:
                  processed_line = processed_line[
                      idx_closing_tag + closing_tag_length:]
  
                  numeration_match = re_recognised_numeration_for_title_plus_series.search(
                      processed_line)
                  if numeration_match:
                      # recognised numeration immediately after the title -
                      # extract it:
                      reference_volume = numeration_match.group('vol')
                      reference_year = numeration_match.group('yr') or ''
                      reference_page = numeration_match.group('pg')
  
                      # This is used on two accounts:
                      # 1. To get the series char from the title, if no series was found with the numeration
                      # 2. To always remove any series character from the title match text
                      # series_from_title = re_series_from_title.search(title_text)
                      #
                      if numeration_match.group('series'):
                          reference_volume = numeration_match.group(
                              'series') + reference_volume
  
                      # Skip past the matched numeration in the working line:
                      processed_line = processed_line[numeration_match.end():]
  
                      # 'id_ibid' saves whether THIS TITLE is an ibid or not. (True or False)
                      # 'extra_ibids' are there to hold ibid's without the word 'ibid', which
                      # come directly after this title
                      # i.e., they are recognised using title numeration instead
                      # of ibid notation
                      identified_citation_element = {'type': "JOURNAL",
                                                     'misc_txt': cur_misc_txt,
                                                     'title': title_text,
                                                     'volume': reference_volume,
                                                     'year': reference_year,
                                                     'page': reference_page,
                                                     'is_ibid': is_ibid,
                                                     'extra_ibids': []
                                                     }
                      count_title += 1
                      cur_misc_txt = u""
  
                      # Try to find IBID's after this title, on top of previously found titles that were
                      # denoted with the word 'IBID'. (i.e. look for IBID's without the word 'IBID' by
                      # looking at extra numeration after this title)
  
                      numeration_match = re_numeration_no_ibid_txt.match(
                          processed_line)
                      while numeration_match is not None:
  
                          reference_volume = numeration_match.group('vol')
                          reference_year = numeration_match.group('yr')
                          reference_page = numeration_match.group('pg')
  
                          if numeration_match.group('series'):
                              reference_volume = numeration_match.group(
                                  'series') + reference_volume
  
                          # Skip past the matched numeration in the working line:
                          processed_line = processed_line[
                              numeration_match.end():]
  
                          # Takes the just found title text
                          identified_citation_element['extra_ibids'].append(
                              {'type': "JOURNAL",
                               'misc_txt': "",
                               'title': title_text,
                               'volume': reference_volume,
                               'year': reference_year,
                               'page': reference_page,
                               })
                          # Increment the stats counters:
                          count_title += 1
  
                          title_text = ""
                          reference_volume = ""
                          reference_year = ""
                          reference_page = ""
                          numeration_match = re_numeration_no_ibid_txt.match(
                              processed_line)
                  else:
                      # No numeration was recognised after the title. Add the
                      # title into a MISC item instead:
                      cur_misc_txt += "%s" % title_text
                      identified_citation_element = None
  
          elif tag_type == "REPORTNUMBER":
  
              # This tag is an identified institutional report number:
  
              # extract the institutional report-number from the line:
              idx_closing_tag = processed_line.find(CFG_REFEXTRACT_MARKER_CLOSING_REPORT_NUM,
                                                    tag_match_end)
              # Sanity check - did we find a closing report-number tag?
              if idx_closing_tag == -1:
                  # no closing </cds.REPORTNUMBER> tag found - strip the opening tag and move past this
                  # recognised reportnumber as it is unreliable:
                  processed_line = processed_line[tag_match_end:]
                  identified_citation_element = None
              else:
                  # closing tag was found
                  report_num = processed_line[tag_match_end:idx_closing_tag]
                  # now trim this matched institutional report-number
                  # and its tags from the start of the line:
                  ending_tag_pos = idx_closing_tag \
                      + len(CFG_REFEXTRACT_MARKER_CLOSING_REPORT_NUM)
                  processed_line = processed_line[ending_tag_pos:]
  
                  identified_citation_element = {'type': "REPORTNUMBER",
                                                 'misc_txt': cur_misc_txt,
                                                 'report_num': report_num}
                  count_reportnum += 1
                  cur_misc_txt = u""
  
          elif tag_type == "URL":
              # This tag is an identified URL:
  
              # From the "identified_urls" list, get this URL and its
              # description string:
              url_string = identified_urls[0][0]
              url_desc = identified_urls[0][1]
  
              # Now move past this "<cds.URL />"tag in the line:
              processed_line = processed_line[tag_match_end:]
  
              # Delete the information for this URL from the start of the list
              # of identified URLs:
              identified_urls[0:1] = []
  
              # Save the current misc text
              identified_citation_element = {
                  'type': "URL",
                  'misc_txt': "%s" % cur_misc_txt,
                  'url_string': "%s" % url_string,
                  'url_desc': "%s" % url_desc
              }
  
              count_url += 1
              cur_misc_txt = u""
  
          elif tag_type == "DOI":
              # This tag is an identified DOI:
  
              # From the "identified_dois" list, get this DOI and its
              # description string:
              doi_string = identified_dois[0]
  
              # Now move past this "<cds.CDS />"tag in the line:
              processed_line = processed_line[tag_match_end:]
  
              # Remove DOI from the list of DOI strings
              identified_dois[0:1] = []
  
              # SAVE the current misc text
              identified_citation_element = {
                  'type': "DOI",
                  'misc_txt': "%s" % cur_misc_txt,
                  'doi_string': "%s" % doi_string
              }
  
              # Increment the stats counters:
              count_doi += 1
              cur_misc_txt = u""
  
          elif tag_type.find("AUTH") != -1:
              # This tag is an identified Author:
  
              auth_type = ""
              # extract the title from the line:
              if tag_type.find("stnd") != -1:
                  auth_type = "stnd"
                  idx_closing_tag_nearest = processed_line.find(
                      CFG_REFEXTRACT_MARKER_CLOSING_AUTHOR_STND, tag_match_end)
              elif tag_type.find("etal") != -1:
                  auth_type = "etal"
                  idx_closing_tag_nearest = processed_line.find(
                      CFG_REFEXTRACT_MARKER_CLOSING_AUTHOR_ETAL, tag_match_end)
              elif tag_type.find("incl") != -1:
                  auth_type = "incl"
                  idx_closing_tag_nearest = processed_line.find(
                      CFG_REFEXTRACT_MARKER_CLOSING_AUTHOR_INCL, tag_match_end)
  
              if idx_closing_tag_nearest == -1:
                  # no closing </cds.AUTH****> tag found - strip the opening tag
                  # and move past it
                  processed_line = processed_line[tag_match_end:]
                  identified_citation_element = None
              else:
                  auth_txt = processed_line[
                      tag_match_end:idx_closing_tag_nearest]
                  # Now move past the ending tag in the line:
                  processed_line = processed_line[
                      idx_closing_tag_nearest + len("</cds.AUTHxxxx>"):]
                  # SAVE the current misc text
                  identified_citation_element = {
                      'type': "AUTH",
                      'misc_txt': "%s" % cur_misc_txt,
                      'auth_txt': "%s" % auth_txt,
                      'auth_type': "%s" % auth_type
                  }
  
                  # Increment the stats counters:
                  count_auth_group += 1
                  cur_misc_txt = u""
  
          # These following tags may be found separately;
          # They are usually found when a "JOURNAL" tag is hit
          # (ONLY immediately afterwards, however)
          # Sitting by themselves means they do not have
          # an associated TITLE tag, and should be MISC
          elif tag_type == "SER":
              # This tag is a SERIES tag; Since it was not preceeded by a TITLE
              # tag, it is useless - strip the tag and put it into miscellaneous:
              (cur_misc_txt, processed_line) = \
                  convert_unusable_tag_to_misc(processed_line, cur_misc_txt,
                                               tag_match_end,
                                               CFG_REFEXTRACT_MARKER_CLOSING_SERIES)
              identified_citation_element = None
  
          elif tag_type == "VOL":
              # This tag is a VOLUME tag; Since it was not preceeded by a TITLE
              # tag, it is useless - strip the tag and put it into miscellaneous:
              (cur_misc_txt, processed_line) = \
                  convert_unusable_tag_to_misc(processed_line, cur_misc_txt,
                                               tag_match_end,
                                               CFG_REFEXTRACT_MARKER_CLOSING_VOLUME)
              identified_citation_element = None
  
          elif tag_type == "YR":
              # This tag is a YEAR tag; Since it's not preceeded by TITLE and
              # VOLUME tags, it is useless - strip the tag and put the contents
              # into miscellaneous:
              (cur_misc_txt, processed_line) = \
                  convert_unusable_tag_to_misc(processed_line, cur_misc_txt,
                                               tag_match_end,
                                               CFG_REFEXTRACT_MARKER_CLOSING_YEAR)
              identified_citation_element = None
  
          elif tag_type == "PG":
              # This tag is a PAGE tag; Since it's not preceeded by TITLE,
              # VOLUME and YEAR tags, it is useless - strip the tag and put the
              # contents into miscellaneous:
              (cur_misc_txt, processed_line) = \
                  convert_unusable_tag_to_misc(processed_line, cur_misc_txt,
                                               tag_match_end,
                                               CFG_REFEXTRACT_MARKER_CLOSING_PAGE)
              identified_citation_element = None
  
          elif tag_type == "QUOTED":
              identified_citation_element, processed_line, cur_misc_txt = \
                  map_tag_to_subfield(tag_type,
                                      processed_line[tag_match_end:],
                                      cur_misc_txt,
                                      'title')
  
          elif tag_type == "ISBN":
              identified_citation_element, processed_line, cur_misc_txt = \
                  map_tag_to_subfield(tag_type,
                                      processed_line[tag_match_end:],
                                      cur_misc_txt,
                                      tag_type)
  
          elif tag_type == "PUBLISHER":
              identified_citation_element, processed_line, cur_misc_txt = \
                  map_tag_to_subfield(tag_type,
                                      processed_line[tag_match_end:],
                                      cur_misc_txt,
                                      'publisher')
  
          elif tag_type == "COLLABORATION":
              identified_citation_element, processed_line, cur_misc_txt = \
                  map_tag_to_subfield(tag_type,
                                      processed_line[tag_match_end:],
                                      cur_misc_txt,
                                      'collaboration')
  
          if identified_citation_element:
              # Append the found tagged data and current misc text
              citation_elements.append(identified_citation_element)
              identified_citation_element = None
  
          # Look for the next tag in the processed line:
          tag_match = re_tagged_citation.search(processed_line)
  
      # place any remaining miscellaneous text into the
      # appropriate MARC XML fields:
      cur_misc_txt += processed_line
  
      # This MISC element will hold the entire citation in the event
      # that no tags were found.
      if len(cur_misc_txt.strip(" .;,")) > 0:
          # Increment the stats counters:
          count_misc += 1
          identified_citation_element = {
              'type': "MISC",
              'misc_txt': cur_misc_txt,
          }
          citation_elements.append(identified_citation_element)
  
      return (citation_elements, line_marker, {
          'misc': count_misc,
          'title': count_title,
          'reportnum': count_reportnum,
          'url': count_url,
          'doi': count_doi,
          'auth_group': count_auth_group
      })