converts a document graph with pointing chains into a string representation
    of a brat *.ann file.

    Parameters
    ----------
    docgraph : DiscourseDocumentGraph
        a document graph which might contain pointing chains (e.g. coreference links)
    layer : str or None
        the name of the layer that contains the pointing chains (e.g. 'mmax' or 'pocores').
        If unspecified, all pointing chains in the document will be considered

    Returns
    -------
    ret_str : unicode
        the content of a brat *.ann file

def brat_output(docgraph, layer=None, show_relations=True):
    """
    converts a document graph with pointing chains into a string representation
    of a brat *.ann file.

    Parameters
    ----------
    docgraph : DiscourseDocumentGraph
        a document graph which might contain pointing chains (e.g. coreference links)
    layer : str or None
        the name of the layer that contains the pointing chains (e.g. 'mmax' or 'pocores').
        If unspecified, all pointing chains in the document will be considered

    Returns
    -------
    ret_str : unicode
        the content of a brat *.ann file
    """
    # we can't rely on the .ns attribute of a merged graph
    if layer:
        namespace = dg.layer2namespace(layer)
    else:
        namespace = docgraph.ns

    ret_str = u''
    pointing_chains = dg.get_pointing_chains(docgraph, layer=layer)

    # a token can be part of 1+ markable(s)
    first_token2markables = defaultdict(list)
    markable_dict = {}
    markable_index = 1

    for pointing_chain in pointing_chains:
        for markable in sorted(pointing_chain, key=dg.util.natural_sort_key):
            span_tokens = spanstring2tokens(docgraph, docgraph.node[markable][namespace+':span'])
            span_text = dg.tokens2text(docgraph, span_tokens)
            first_token2markables[span_tokens[0]].append(markable)
            markable_dict[markable] = (markable_index, span_text, len(span_text))
            markable_index += 1

    onset = 0
    for token_id in docgraph.tokens:
        tok_len = len(docgraph.get_token(token_id))
        if token_id in first_token2markables:
            for markable in first_token2markables[token_id]:
                mark_index, mark_text, mark_len = markable_dict[markable]
                ret_str += u"T{0}\tMarkable {1} {2}\t{3}\n".format(
                    mark_index, onset, onset+mark_len, mark_text)
        onset += tok_len+1

    if show_relations:
        relation = 1
        for pointing_chain in pointing_chains:
            last_to_first_mention = sorted(pointing_chain, key=dg.util.natural_sort_key, reverse=True)
            for i in xrange(0, len(pointing_chain)-1):
                chain_element = markable_dict[last_to_first_mention[i]][0]
                prev_chain_element = markable_dict[last_to_first_mention[i+1]][0]
                ret_str += u"R{0}\tCoreference Arg1:T{1} Arg2:T{2}\n".format(
                    relation, chain_element, prev_chain_element)
                relation += 1
    return ret_str