X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=ovsdb%2Fovsdb-doc.in;h=aa4fae2e6c26ac1d25246ddb407c5f05711b2fe4;hb=2c57a420432de88b8a6f9ee54642c3841577ad7b;hp=17eca52e76b07a3084d31c1c9d169f6c6bd9d737;hpb=5d943800c1681d572411f9883e45dfb9a9e33909;p=sliver-openvswitch.git diff --git a/ovsdb/ovsdb-doc.in b/ovsdb/ovsdb-doc.in index 17eca52e7..aa4fae2e6 100755 --- a/ovsdb/ovsdb-doc.in +++ b/ovsdb/ovsdb-doc.in @@ -16,9 +16,9 @@ argv0 = sys.argv[0] def textToNroff(s, font=r'\fR'): def escape(match): c = match.group(0) - if c == '-': - if font == r'\fB': - return r'\-' + if c.startswith('-'): + if c != '-' or font == r'\fB': + return '\\' + c else: return '-' if c == '\\': @@ -31,7 +31,7 @@ def textToNroff(s, font=r'\fR'): raise error.Error("bad escape") # Escape - \ " ' as needed by nroff. - s = re.sub('([-"\'\\\\])', escape, s) + s = re.sub('(-[0-9]|[-"\'\\\\])', escape, s) if s.startswith('.'): s = '\\' + s return s @@ -59,7 +59,7 @@ def inlineXmlToNroff(node, font): elif node.hasAttribute('group'): s += node.attributes['group'].nodeValue else: - raise error.Error("'ref' lacks column and table attributes") + raise error.Error("'ref' lacks required attributes: %s" % node.attributes.keys()) return s + font elif node.tagName == 'var': s = r'\fI' @@ -125,6 +125,15 @@ def blockXmlToNroff(nodes, para='.PP'): s += "\n" s += para + "\n" s += blockXmlToNroff(node.childNodes, para) + elif node.tagName in ('h1', 'h2', 'h3'): + if s != "": + if not s.endswith("\n"): + s += "\n" + nroffTag = {'h1': 'SH', 'h2': 'SS', 'h3': 'ST'}[node.tagName] + s += ".%s " % nroffTag + for child_node in node.childNodes: + s += inlineXmlToNroff(child_node, r'\fR') + s += "\n" else: s += inlineXmlToNroff(node, r'\fR') else: @@ -135,19 +144,14 @@ def blockXmlToNroff(nodes, para='.PP'): def typeAndConstraintsToNroff(column): type = column.type.toEnglish(escapeNroffLiteral) - constraints = column.type.constraintsToEnglish(escapeNroffLiteral) + constraints = column.type.constraintsToEnglish(escapeNroffLiteral, + textToNroff) if constraints: type += ", " + constraints if column.unique: type += " (must be unique within table)" return type -def columnToNroff(columnName, column, node): - type = typeAndConstraintsToNroff(column) - s = '.IP "\\fB%s\\fR: %s"\n' % (columnName, type) - s += blockXmlToNroff(node.childNodes, '.IP') + "\n" - return s - def columnGroupToNroff(table, groupXml): introNodes = [] columnNodes = [] @@ -156,6 +160,10 @@ def columnGroupToNroff(table, groupXml): and node.tagName in ('column', 'group')): columnNodes += [node] else: + if (columnNodes + and not (node.nodeType == node.TEXT_NODE + and node.data.isspace())): + raise error.Error("text follows or inside : %s" % node) introNodes += [node] summary = [] @@ -163,10 +171,50 @@ def columnGroupToNroff(table, groupXml): body = '' for node in columnNodes: if node.tagName == 'column': - columnName = node.attributes['name'].nodeValue - column = table.columns[columnName] - body += columnToNroff(columnName, column, node) - summary += [('column', columnName, column)] + name = node.attributes['name'].nodeValue + column = table.columns[name] + if node.hasAttribute('key'): + key = node.attributes['key'].nodeValue + if node.hasAttribute('type'): + type_string = node.attributes['type'].nodeValue + type_json = ovs.json.from_string(str(type_string)) + if type(type_json) in (str, unicode): + raise error.Error("%s %s:%s has invalid 'type': %s" + % (table.name, name, key, type_json)) + type_ = ovs.db.types.BaseType.from_json(type_json) + else: + type_ = column.type.value + + nameNroff = "%s : %s" % (name, key) + + if column.type.value: + typeNroff = "optional %s" % column.type.value.toEnglish( + escapeNroffLiteral) + if (column.type.value.type == ovs.db.types.StringType and + type_.type == ovs.db.types.BooleanType): + # This is a little more explicit and helpful than + # "containing a boolean" + typeNroff += r", either \fBtrue\fR or \fBfalse\fR" + else: + if type_.type != column.type.value.type: + type_english = type_.toEnglish() + if type_english[0] in 'aeiou': + typeNroff += ", containing an %s" % type_english + else: + typeNroff += ", containing a %s" % type_english + constraints = ( + type_.constraintsToEnglish(escapeNroffLiteral, + textToNroff)) + if constraints: + typeNroff += ", %s" % constraints + else: + typeNroff = "none" + else: + nameNroff = name + typeNroff = typeAndConstraintsToNroff(column) + body += '.IP "\\fB%s\\fR: %s"\n' % (nameNroff, typeNroff) + body += blockXmlToNroff(node.childNodes, '.IP') + "\n" + summary += [('column', nameNroff, typeNroff)] elif node.tagName == 'group': title = node.attributes["title"].nodeValue subSummary, subIntro, subBody = columnGroupToNroff(table, node) @@ -181,19 +229,11 @@ def tableSummaryToNroff(summary, level=0): s = "" for type, name, arg in summary: if type == 'column': - - s += "%s\\fB%s\\fR\tT{\n%s\nT}\n" % ( - r'\ \ ' * level, name, typeAndConstraintsToNroff(arg)) + s += ".TQ %.2fin\n\\fB%s\\fR\n%s\n" % (3 - level * .25, name, arg) else: - if s != "": - s += "_\n" - s += """.T& -li | s -l | l. -%s%s -_ -""" % (r'\ \ ' * level, name) + s += ".TQ .25in\n\\fI%s:\\fR\n.RS .25in\n" % name s += tableSummaryToNroff(arg, level + 1) + s += ".RE\n" return s def tableToNroff(schema, tableXml): @@ -201,24 +241,13 @@ def tableToNroff(schema, tableXml): table = schema.tables[tableName] s = """.bp -.SS "%s Table" +.SH "%s TABLE" """ % tableName summary, intro, body = columnGroupToNroff(table, tableXml) s += intro - - s += r""" -.sp -.ce 1 -\fB%s\fR Table Columns: -.TS -center box; -l | l. -Column Type -= -""" % tableName + s += '.SS "Summary:\n' s += tableSummaryToNroff(summary) - s += ".TE\n" - + s += '.SS "Details:\n' s += body return s @@ -233,16 +262,15 @@ def docsToNroff(schemaFile, xmlFile, erFile, title=None): if title == None: title = schema.name - # Putting '\" pt as the first line tells "man" that the manpage - # needs to be preprocessed by "pic" and "tbl". - s = r''''\" pt -.TH %s 5 "%s" "Open vSwitch" "Open vSwitch Manual" + # Putting '\" p as the first line tells "man" that the manpage + # needs to be preprocessed by "pic". + s = r''''\" p +.TH @VERSION@ 5 "%s" "Open vSwitch" "Open vSwitch Manual" .\" -*- nroff -*- .de TQ . br . ns -. TP -\\$1 +. TP "\\$1" .. .de ST . PP @@ -250,9 +278,10 @@ def docsToNroff(schemaFile, xmlFile, erFile, title=None): . I "\\$1" . RE .. -''' % (title, d.strftime("%B %Y")) - - s += '.SH "%s DATABASE"\n' % schema.name +.SH NAME +%s \- %s database schema +.PP +''' % (title, textToNroff(title), schema.name) tables = "" introNodes = [] @@ -273,26 +302,28 @@ def docsToNroff(schemaFile, xmlFile, erFile, title=None): introNodes += [dbNode] s += blockXmlToNroff(introNodes) + "\n" - tableSummary = r""" -.sp -.ce 1 -\fB%s\fR Database Tables: -.TS -center box; -l | l -lb | l. -Table Purpose -= + + s += r""" +.SH "TABLE SUMMARY" +.PP +The following list summarizes the purpose of each of the tables in the +\fB%s\fR database. Each table is described in more detail on a later +page. +.IP "Table" 1in +Purpose """ % schema.name for name, title in summary: - tableSummary += "%s\t%s\n" % (name, textToNroff(title)) - tableSummary += '.TE\n' - s += tableSummary + s += r""" +.TQ 1in +\fB%s\fR +%s +""" % (name, textToNroff(title)) if erFile: s += """ -.if !'\*[.T]'ascii' \{ -.sp 1 +.\\" check if in troff mode (TTY) +.if t \{ +.bp .SH "TABLE RELATIONSHIPS" .PP The following diagram shows the relationship among tables in the