Patchwork [4,of,8,v2] docchecker: introduce a way to check for poor markup

login
register
mail settings
Submitter timeless@mozdev.org
Date Jan. 12, 2016, 7:09 a.m.
Message ID <8f88193588b30473ef73.1452582585@waste.org>
Download mbox | patch
Permalink /patch/12683/
State Superseded
Commit ed86fb2a41879a8158539dfb500ad9682f802649
Headers show

Comments

timeless@mozdev.org - Jan. 12, 2016, 7:09 a.m.
# HG changeset patch
# User timeless <timeless@mozdev.org>
# Date 1452109634 0
#      Wed Jan 06 19:47:14 2016 +0000
# Node ID 8f88193588b30473ef73f1946a73e962ac93209a
# Parent  cc83327a6baebe9e42f7c8c54c2c878947fd9be2
docchecker: introduce a way to check for poor markup

Specifically, :hg:`foo 'bar baz'` when rendered by `hg help`
results in:

  'hg foo 'bar baz''

... which is hard to read.

We encourage :hg:`foo "bar baz"` instead.

Patch

diff --git a/doc/docchecker b/doc/docchecker
new file mode 100755
--- /dev/null
+++ b/doc/docchecker
@@ -0,0 +1,50 @@ 
+#!/usr/bin/env python
+#
+# docchecker - look for problematic markup
+#
+# Copyright 2016 timeless <timeless@mozdev.org> and others
+#
+# This software may be used and distributed according to the terms of the
+# GNU General Public License version 2 or any later version.
+import sys
+import re
+
+leadingline = re.compile(r'(^\s*)(\S.*)$')
+hg_backtick = re.compile(r""":hg:`[^`]*'[^`]*`""")
+
+def check(line):
+  if hg_backtick.search(line):
+    print(line)
+    print("""warning: please avoid nesting ' in :hg:`...`""")
+
+def work(file):
+  (llead, lline) = ('', '')
+
+  for line in file:
+    # this section unwraps lines
+    match = leadingline.match(line)
+    if not match:
+      check(lline)
+      (llead, lline) = ('', '')
+      continue
+
+    lead, line = match.group(1), match.group(2)
+    if (lead == llead):
+      if (lline != ''):
+        lline += ' ' + line
+      else:
+        lline = line
+    else:
+      check(lline)
+      (llead, lline) = (lead, line)
+  check(lline)
+
+def main():
+  for f in sys.argv[1:]:
+    try:
+      with open(f) as file:
+        work(file)
+    except:
+      print("failed to process %s" % f)
+
+main()