summaryrefslogtreecommitdiff
path: root/common/doc
diff options
context:
space:
mode:
authorNicolas Schodet2012-03-29 08:21:35 +0200
committerNicolas Schodet2012-04-11 11:16:06 +0200
commit207457e6d1ce7f895d0d27d944338fa24e34489d (patch)
treefe4d2c58b772904e7495f6a4f2b799726382d448 /common/doc
parent74f86c9bc410d490035887509f5c39c2e81e24dd (diff)
common/doc/template: add glossary generation
Diffstat (limited to 'common/doc')
-rw-r--r--common/doc/template/doc.mk10
-rw-r--r--common/doc/template/glossary/glossary35
-rwxr-xr-xcommon/doc/template/glossary/make_glossary98
3 files changed, 141 insertions, 2 deletions
diff --git a/common/doc/template/doc.mk b/common/doc/template/doc.mk
index 9729972573..93cbff28d5 100644
--- a/common/doc/template/doc.mk
+++ b/common/doc/template/doc.mk
@@ -1,5 +1,7 @@
TEMPLATE_DIR := $(BASE)/common/doc/template
HEADERS := header.rst
+GEN_HEADERS := $(if $(GLOSSARY),glossary.rst)
+GLOSSARIES := $(TEMPLATE_DIR)/glossary/glossary
.PHONY: all pdf html clean
@@ -9,7 +11,7 @@ HEADERS := header.rst
html: $(DOCS:%=%.html)
pdf: $(DOCS:%=%.pdf)
-RST_DEPS += $(HEADERS) $(DEPS)
+RST_DEPS += $(HEADERS) $(GEN_HEADERS) $(DEPS)
# Prevent make to remove our intermediary files, HTML still points to them.
.SECONDARY: $(DEPS)
@@ -30,8 +32,12 @@ RST_DEPS += $(HEADERS) $(DEPS)
$(HEADERS):
test -f $@ || ln -s $(TEMPLATE_DIR)/mstar/$@
+glossary.rst: $(DOCS:%=%.rst) $(GLOSSARIES)
+ $(TEMPLATE_DIR)/glossary/make_glossary $(GLOSSARIES:%=-b%) \
+ $(DOCS:%=%.rst) -t Glossary > $@
+
clean:
- rm -f $(EXTRA_CLEAN_FILES)
+ rm -f $(EXTRA_CLEAN_FILES) $(GEN_HEADERS)
rm -f $(DOCS:%=%.html) $(DOCS:%=%.pdf) $(DOCS:%=%.tex) \
$(DOCS:%=%.aux) $(DOCS:%=%.log) $(DOCS:%=%.out) \
$(DOCS:%=%.toc)
diff --git a/common/doc/template/glossary/glossary b/common/doc/template/glossary/glossary
new file mode 100644
index 0000000000..e163121fd7
--- /dev/null
+++ b/common/doc/template/glossary/glossary
@@ -0,0 +1,35 @@
+AES Advanced Encryption Standard
+CATV Cable Analog TV
+CE Channel estimation
+DHCP Dynamic Host Configuration Protocol
+DPW Device PassWord
+EoC Ethernet over Coax
+FTP File Transfer Protocol
+GPIO General Purpose Input/Output
+HTTP Hyper Text Transfer Protocol
+IGMP Internet Group Management Protocol
+IP Internet Protocol
+MAC Medium Access Control
+MIB Management Information Base
+MME Management Message
+MTU Maximum Transmit Unit
+NVRAM Non Volatile RAM
+OEM Original Equipment Manufacturer
+OID Object Identifier
+PLC Power Line Communication
+RF Radio Frequency
+Rx Receive
+QoS Quality of Service
+SARFT State Administration of
+ Radio, Film, and Television
+SNMP Simple Network Management Protocol
+SNR Signal-to-noise Ratio
+SSH Secure Shell
+STP Spanning Tree Protocol
+TDMA Time Division Multiple Access
+TEI Terminal Equipment Identifier
+TOS Type Of Service
+Tx Transmit
+VID VLAN Identifier
+VLAN Virtual Local Area Network
+WL White List
diff --git a/common/doc/template/glossary/make_glossary b/common/doc/template/glossary/make_glossary
new file mode 100755
index 0000000000..28f357572d
--- /dev/null
+++ b/common/doc/template/glossary/make_glossary
@@ -0,0 +1,98 @@
+#!/usr/bin/python
+"""Read document and output a glossary of every known terms."""
+import optparse
+import re
+import textwrap
+
+base_re = re.compile (r'^(\w*)(\s{2,})(.*)$')
+word_re = re.compile (r'\w+')
+
+def read_base (fname):
+ """Read glossary base file."""
+ last = None
+ last_indent = None
+ glossary = dict ()
+ with open (fname) as f:
+ for n, l in enumerate (f):
+ l = l.rstrip ()
+ m = base_re.match (l)
+ if not m:
+ raise RuntimeError ("%s:%d: bad format"
+ % (fname, n + 1))
+ key, space, value = m.groups ()
+ if key:
+ if key in glossary:
+ raise RuntimeError ("%s:%d: duplicated entry"
+ % (fname, n + 1))
+ glossary[key] = value
+ last, last_indent = key, len (key + space)
+ else:
+ # Continuation line.
+ if last is None or len (space) != last_indent:
+ raise RuntimeError ("%s:%d: bad continuation line"
+ % (fname, n + 1))
+ glossary[last] += ' ' + value
+ return glossary
+
+def make_glossary (base, fname):
+ """Read every word in document and lookup in base."""
+ glossary = dict ()
+ with open (fname) as f:
+ doc = f.read ()
+ for m in word_re.finditer (doc):
+ word = m.group (0)
+ if word in base and word not in glossary:
+ glossary[word] = base[word]
+ return glossary
+
+def output_rst (glossary, textwidth = 78, title = None):
+ """Output glossary in reStructuredText format."""
+ if title:
+ print title
+ print '=' * len (title)
+ print
+ max_key = len (max (glossary.iterkeys (), key = len))
+ value_width = textwidth - 1 - max_key
+ max_value = min (len (max (glossary.itervalues (), key = len)),
+ value_width)
+ print '=' * max_key, '=' * max_value
+ print '%-*s %s' % (max_key, "Term", "Definition")
+ print '=' * max_key, '=' * max_value
+ join_indent = '\n' + ' ' * max_key + ' '
+ for k in sorted (glossary):
+ print '%-*s' % (max_key, k),
+ print join_indent.join (textwrap.wrap (glossary[k], value_width))
+ print '=' * max_key, '=' * max_value
+
+if __name__ == '__main__':
+ op = optparse.OptionParser (usage = '%prog [options] document...',
+ description = __doc__)
+ op.add_option ('-b', '--base', metavar = 'FILE', action = 'append',
+ help = "read glossary base from given FILE, can be used several"
+ " times")
+ op.add_option ('-a', '--all', action = 'store_true',
+ help = "dump all glossary entry, do not read document")
+ op.add_option ('-w', '--textwidth', metavar = 'N', type = 'int',
+ default = 78,
+ help = "wrap at column N (default: %default)")
+ op.add_option ('-t', '--title', metavar = 'TEXT',
+ help = "use TEXT as title")
+ options, args = op.parse_args ()
+ if not options.base:
+ op.error ("no base given")
+ if not options.all and not args:
+ op.error ("no enough arguments")
+ if options.all and args:
+ op.error ("too much arguments")
+
+ base = dict ()
+ for bname in options.base:
+ base.update (read_base (bname))
+ if options.all:
+ glossary = base
+ else:
+ glossary = dict ()
+ for doc in args:
+ glossary.update (make_glossary (base, doc))
+ if glossary:
+ output_rst (glossary, options.textwidth, options.title)