[ovs-dev] [PATCH v2 15/21] nroff: Add support for 'diagram' XML element for protocol headers.

[Alex Wang]

On Tue, Jul 28, 2015 at 8:44 AM, Ben Pfaff <blp at nicira.com> wrote:

> This will be used in documentation for an upcoming change, to document
> how Geneve OVN options are encoded.
>
> The code in this change is from a series (not yet submitted) that makes
> much more extensive use of it for documenting protocol headers.
>
> Signed-off-by: Ben Pfaff <blp at nicira.com>
> ---
>  python/build/nroff.py | 98
> +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 98 insertions(+)
>
> diff --git a/python/build/nroff.py b/python/build/nroff.py
> index 6d22d46..778ce0f 100644
> --- a/python/build/nroff.py
> +++ b/python/build/nroff.py
> @@ -105,6 +105,102 @@ def pre_to_nroff(nodes, para, font):
>      s += '.fi\n'
>      return s
>
> +def diagram_header_to_nroff(header_node):
> +    header_fields = []
> +    i = 0
> +    for node in header_node.childNodes:
> +        if node.nodeType == node.ELEMENT_NODE and node.tagName == 'bits':
> +            name = node.attributes['name'].nodeValue
> +            width = node.attributes['width'].nodeValue
> +            above = node.getAttribute('above')
> +            below = node.getAttribute('below')
> +            fill = node.getAttribute('fill')
> +            header_fields += [{"name": name,
> +                              "tag": "B%d" % i,
> +                              "width": width,
> +                              "above": above,
> +                              "below": below,
> +                              "fill": fill}]
> +            i += 1
> +        elif node.nodeType == node.COMMENT_NODE:
> +            pass
> +        elif node.nodeType == node.TEXT_NODE and node.data.isspace():
> +            pass
> +        else:
> +            fatal("unknown node %s in diagram <header> element" % node)
> +
> +    pic_s = ""
> +    for f in header_fields:
> +        pic_s += "  %s: box \"%s\" width %s" % (f['tag'], f['name'],
> f['width'])
> +        if f['fill'] == 'yes':
> +            pic_s += " fill"
> +        pic_s += '\n'
> +    for f in header_fields:
> +        pic_s += "  \"%s\" at %s.n above\n" % (f['above'], f['tag'])
> +        pic_s += "  \"%s\" at %s.s below\n" % (f['below'], f['tag'])
> +    name = header_node.getAttribute('name')
> +    if name == "":
> +        visible = " invis"
> +    else:
> +        visible = ""
> +    pic_s += "line <->%s \"%s\" above " % (visible, name)
> +    pic_s += "from %s.nw + (0,textht) " % header_fields[0]['tag']
> +    pic_s += "to %s.ne + (0,textht)\n" % header_fields[-1]['tag']
> +
> +    text_s = ""
> +    for f in header_fields:
> +        text_s += """.IP \\(bu
> +%s bits""" % (f['above'])
> +        if f['name']:
> +            text_s += ": %s" % f['name']
> +        if f['below']:
> +            text_s += " (%s)" % f['below']
> +        text_s += "\n"
> +    return pic_s, text_s
> +
> +def diagram_to_nroff(nodes, para):
> +    pic_s = ''
> +    text_s = ''
> +    move = False
> +    for node in nodes:
> +        if node.nodeType == node.ELEMENT_NODE and node.tagName ==
> 'header':
> +            if move:
> +                pic_s += "move .1\n"
> +                text_s += ".sp\n"
> +            pic_header, text_header = diagram_header_to_nroff(node)
> +            pic_s += "[\n" + pic_header + "]\n"
> +            text_s += text_header
> +            move = True
> +        elif node.nodeType == node.ELEMENT_NODE and node.tagName ==
> 'nospace':
> +            move = False
> +        elif node.nodeType == node.ELEMENT_NODE and node.tagName ==
> 'dots':
> +            pic_s += "move .1\n"
> +            pic_s += '". . ." ljust\n'
> +            text_s += ".sp\n"
> +        elif node.nodeType == node.COMMENT_NODE:
> +            pass
> +        elif node.nodeType == node.TEXT_NODE and node.data.isspace():
> +            pass
> +        else:
> +            fatal("unknown node %s in diagram <header> element" % node)
> +    return para + """
> +.\\" check if in troff mode (TTY)
> +.if t \{
> +.PS
> +boxht = .2
> +textht = 1/6
> +fillval = .2
> +""" + pic_s + """\
> +.PE
> +\\}
> +.\\" check if in nroff mode:
> +.if n \{
> +.RS
> +""" + text_s + """\
> +.RE
> +\\}"""
> +    return s
> +
>


Really curious what's the protocol (reference) of writing this
(xml->manpage)?

Also, is the 'return s' redundant?

Thanks,
Alex Wang,

 def block_xml_to_nroff(nodes, para='.PP'):
>      s = ''
>      for node in nodes:
> @@ -176,6 +272,8 @@ def block_xml_to_nroff(nodes, para='.PP'):
>                  else:
>                      font = r'\fB'
>                  s += pre_to_nroff(node.childNodes, para, font)
> +            elif node.tagName == 'diagram':
> +                s += diagram_to_nroff(node.childNodes, para)
>              else:
>                  s += inline_xml_to_nroff(node, r'\fR')
>          elif node.nodeType == node.COMMENT_NODE:
> --
> 2.1.3
>
> _______________________________________________
> dev mailing list
> dev at openvswitch.org
> http://openvswitch.org/mailman/listinfo/dev
>