Annotation of embedaddon/rsync/md2man, revision 1.1
1.1 ! misho 1: #!/usr/bin/env python3
! 2:
! 3: # This script takes a manpage written in markdown and turns it into an html web
! 4: # page and a nroff man page. The input file must have the name of the program
! 5: # and the section in this format: NAME.NUM.md. The output files are written
! 6: # into the current directory named NAME.NUM.html and NAME.NUM. The input
! 7: # format has one extra extension: if a numbered list starts at 0, it is turned
! 8: # into a description list. The dl's dt tag is taken from the contents of the
! 9: # first tag inside the li, which is usually a p, code, or strong tag. The
! 10: # cmarkgfm or commonmark lib is used to transforms the input file into html.
! 11: # The html.parser is used as a state machine that both tweaks the html and
! 12: # outputs the nroff data based on the html tags.
! 13: #
! 14: # Copyright (C) 2020 Wayne Davison
! 15: #
! 16: # This program is freely redistributable.
! 17:
! 18: import sys, os, re, argparse, subprocess, time
! 19: from html.parser import HTMLParser
! 20:
! 21: CONSUMES_TXT = set('h1 h2 p li pre'.split())
! 22:
! 23: HTML_START = """\
! 24: <html><head>
! 25: <title>%s</title>
! 26: <link href="https://fonts.googleapis.com/css2?family=Roboto&family=Roboto+Mono&display=swap" rel="stylesheet">
! 27: <style>
! 28: body {
! 29: max-width: 50em;
! 30: margin: auto;
! 31: }
! 32: body, b, strong, u {
! 33: font-family: 'Roboto', sans-serif;
! 34: }
! 35: code {
! 36: font-family: 'Roboto Mono', monospace;
! 37: font-weight: bold;
! 38: white-space: pre;
! 39: }
! 40: pre code {
! 41: display: block;
! 42: font-weight: normal;
! 43: }
! 44: blockquote pre code {
! 45: background: #f1f1f1;
! 46: }
! 47: dd p:first-of-type {
! 48: margin-block-start: 0em;
! 49: }
! 50: </style>
! 51: </head><body>
! 52: """
! 53:
! 54: HTML_END = """\
! 55: <div style="float: right"><p><i>%s</i></p></div>
! 56: </body></html>
! 57: """
! 58:
! 59: MAN_START = r"""
! 60: .TH "%s" "%s" "%s" "%s" "User Commands"
! 61: """.lstrip()
! 62:
! 63: MAN_END = """\
! 64: """
! 65:
! 66: NORM_FONT = ('\1', r"\fP")
! 67: BOLD_FONT = ('\2', r"\fB")
! 68: UNDR_FONT = ('\3', r"\fI")
! 69: NBR_DASH = ('\4', r"\-")
! 70: NBR_SPACE = ('\xa0', r"\ ")
! 71:
! 72: md_parser = None
! 73:
! 74: def main():
! 75: fi = re.match(r'^(?P<fn>(?P<srcdir>.+/)?(?P<name>(?P<prog>[^/]+)\.(?P<sect>\d+))\.md)$', args.mdfile)
! 76: if not fi:
! 77: die('Failed to parse NAME.NUM.md out of input file:', args.mdfile)
! 78: fi = argparse.Namespace(**fi.groupdict())
! 79:
! 80: if not fi.srcdir:
! 81: fi.srcdir = './'
! 82:
! 83: fi.title = fi.prog + '(' + fi.sect + ') man page'
! 84: fi.mtime = 0
! 85:
! 86: git_dir = fi.srcdir + '.git'
! 87: if os.path.lexists(git_dir):
! 88: fi.mtime = int(subprocess.check_output(['git', '--git-dir', git_dir, 'log', '-1', '--format=%at']))
! 89:
! 90: env_subs = { 'prefix': os.environ.get('RSYNC_OVERRIDE_PREFIX', None) }
! 91:
! 92: if args.test:
! 93: env_subs['VERSION'] = '1.0.0'
! 94: env_subs['libdir'] = '/usr'
! 95: else:
! 96: for fn in (fi.srcdir + 'version.h', 'Makefile'):
! 97: try:
! 98: st = os.lstat(fn)
! 99: except:
! 100: die('Failed to find', fi.srcdir + fn)
! 101: if not fi.mtime:
! 102: fi.mtime = st.st_mtime
! 103:
! 104: with open(fi.srcdir + 'version.h', 'r', encoding='utf-8') as fh:
! 105: txt = fh.read()
! 106: m = re.search(r'"(.+?)"', txt)
! 107: env_subs['VERSION'] = m.group(1)
! 108:
! 109: with open('Makefile', 'r', encoding='utf-8') as fh:
! 110: for line in fh:
! 111: m = re.match(r'^(\w+)=(.+)', line)
! 112: if not m:
! 113: continue
! 114: var, val = (m.group(1), m.group(2))
! 115: if var == 'prefix' and env_subs[var] is not None:
! 116: continue
! 117: while re.search(r'\$\{', val):
! 118: val = re.sub(r'\$\{(\w+)\}', lambda m: env_subs[m.group(1)], val)
! 119: env_subs[var] = val
! 120: if var == 'srcdir':
! 121: break
! 122:
! 123: with open(fi.fn, 'r', encoding='utf-8') as fh:
! 124: txt = fh.read()
! 125:
! 126: txt = re.sub(r'@VERSION@', env_subs['VERSION'], txt)
! 127: txt = re.sub(r'@LIBDIR@', env_subs['libdir'], txt)
! 128:
! 129: fi.html_in = md_parser(txt)
! 130: txt = None
! 131:
! 132: fi.date = time.strftime('%d %b %Y', time.localtime(fi.mtime))
! 133: fi.man_headings = (fi.prog, fi.sect, fi.date, fi.prog + ' ' + env_subs['VERSION'])
! 134:
! 135: HtmlToManPage(fi)
! 136:
! 137: if args.test:
! 138: print("The test was successful.")
! 139: return
! 140:
! 141: for fn, txt in ((fi.name + '.html', fi.html_out), (fi.name, fi.man_out)):
! 142: print("Wrote:", fn)
! 143: with open(fn, 'w', encoding='utf-8') as fh:
! 144: fh.write(txt)
! 145:
! 146:
! 147: def html_via_commonmark(txt):
! 148: return commonmark.HtmlRenderer().render(commonmark.Parser().parse(txt))
! 149:
! 150:
! 151: class HtmlToManPage(HTMLParser):
! 152: def __init__(self, fi):
! 153: HTMLParser.__init__(self, convert_charrefs=True)
! 154:
! 155: st = self.state = argparse.Namespace(
! 156: list_state = [ ],
! 157: p_macro = ".P\n",
! 158: at_first_tag_in_li = False,
! 159: at_first_tag_in_dd = False,
! 160: dt_from = None,
! 161: in_pre = False,
! 162: in_code = False,
! 163: html_out = [ HTML_START % fi.title ],
! 164: man_out = [ MAN_START % fi.man_headings ],
! 165: txt = '',
! 166: )
! 167:
! 168: self.feed(fi.html_in)
! 169: fi.html_in = None
! 170:
! 171: st.html_out.append(HTML_END % fi.date)
! 172: st.man_out.append(MAN_END)
! 173:
! 174: fi.html_out = ''.join(st.html_out)
! 175: st.html_out = None
! 176:
! 177: fi.man_out = ''.join(st.man_out)
! 178: st.man_out = None
! 179:
! 180:
! 181: def handle_starttag(self, tag, attrs_list):
! 182: st = self.state
! 183: if args.debug:
! 184: self.output_debug('START', (tag, attrs_list))
! 185: if st.at_first_tag_in_li:
! 186: if st.list_state[-1] == 'dl':
! 187: st.dt_from = tag
! 188: if tag == 'p':
! 189: tag = 'dt'
! 190: else:
! 191: st.html_out.append('<dt>')
! 192: elif tag == 'p':
! 193: st.at_first_tag_in_dd = True # Kluge to suppress a .P at the start of an li.
! 194: st.at_first_tag_in_li = False
! 195: if tag == 'p':
! 196: if not st.at_first_tag_in_dd:
! 197: st.man_out.append(st.p_macro)
! 198: elif tag == 'li':
! 199: st.at_first_tag_in_li = True
! 200: lstate = st.list_state[-1]
! 201: if lstate == 'dl':
! 202: return
! 203: if lstate == 'o':
! 204: st.man_out.append(".IP o\n")
! 205: else:
! 206: st.man_out.append(".IP " + str(lstate) + ".\n")
! 207: st.list_state[-1] += 1
! 208: elif tag == 'blockquote':
! 209: st.man_out.append(".RS 4\n")
! 210: elif tag == 'pre':
! 211: st.in_pre = True
! 212: st.man_out.append(st.p_macro + ".nf\n")
! 213: elif tag == 'code' and not st.in_pre:
! 214: st.in_code = True
! 215: st.txt += BOLD_FONT[0]
! 216: elif tag == 'strong' or tag == 'b':
! 217: st.txt += BOLD_FONT[0]
! 218: elif tag == 'em' or tag == 'i':
! 219: tag = 'u' # Change it into underline to be more like the man page
! 220: st.txt += UNDR_FONT[0]
! 221: elif tag == 'ol':
! 222: start = 1
! 223: for var, val in attrs_list:
! 224: if var == 'start':
! 225: start = int(val) # We only support integers.
! 226: break
! 227: if st.list_state:
! 228: st.man_out.append(".RS\n")
! 229: if start == 0:
! 230: tag = 'dl'
! 231: attrs_list = [ ]
! 232: st.list_state.append('dl')
! 233: else:
! 234: st.list_state.append(start)
! 235: st.man_out.append(st.p_macro)
! 236: st.p_macro = ".IP\n"
! 237: elif tag == 'ul':
! 238: st.man_out.append(st.p_macro)
! 239: if st.list_state:
! 240: st.man_out.append(".RS\n")
! 241: st.p_macro = ".IP\n"
! 242: st.list_state.append('o')
! 243: st.html_out.append('<' + tag + ''.join(' ' + var + '="' + htmlify(val) + '"' for var, val in attrs_list) + '>')
! 244: st.at_first_tag_in_dd = False
! 245:
! 246:
! 247: def handle_endtag(self, tag):
! 248: st = self.state
! 249: if args.debug:
! 250: self.output_debug('END', (tag,))
! 251: if tag in CONSUMES_TXT or st.dt_from == tag:
! 252: txt = st.txt.strip()
! 253: st.txt = ''
! 254: else:
! 255: txt = None
! 256: add_to_txt = None
! 257: if tag == 'h1':
! 258: st.man_out.append(st.p_macro + '.SH "' + manify(txt) + '"\n')
! 259: elif tag == 'h2':
! 260: st.man_out.append(st.p_macro + '.SS "' + manify(txt) + '"\n')
! 261: elif tag == 'p':
! 262: if st.dt_from == 'p':
! 263: tag = 'dt'
! 264: st.man_out.append('.IP "' + manify(txt) + '"\n')
! 265: st.dt_from = None
! 266: elif txt != '':
! 267: st.man_out.append(manify(txt) + "\n")
! 268: elif tag == 'li':
! 269: if st.list_state[-1] == 'dl':
! 270: if st.at_first_tag_in_li:
! 271: die("Invalid 0. -> td translation")
! 272: tag = 'dd'
! 273: if txt != '':
! 274: st.man_out.append(manify(txt) + "\n")
! 275: st.at_first_tag_in_li = False
! 276: elif tag == 'blockquote':
! 277: st.man_out.append(".RE\n")
! 278: elif tag == 'pre':
! 279: st.in_pre = False
! 280: st.man_out.append(manify(txt) + "\n.fi\n")
! 281: elif (tag == 'code' and not st.in_pre):
! 282: st.in_code = False
! 283: add_to_txt = NORM_FONT[0]
! 284: elif tag == 'strong' or tag == 'b':
! 285: add_to_txt = NORM_FONT[0]
! 286: elif tag == 'em' or tag == 'i':
! 287: tag = 'u' # Change it into underline to be more like the man page
! 288: add_to_txt = NORM_FONT[0]
! 289: elif tag == 'ol' or tag == 'ul':
! 290: if st.list_state.pop() == 'dl':
! 291: tag = 'dl'
! 292: if st.list_state:
! 293: st.man_out.append(".RE\n")
! 294: else:
! 295: st.p_macro = ".P\n"
! 296: st.at_first_tag_in_dd = False
! 297: st.html_out.append('</' + tag + '>')
! 298: if add_to_txt:
! 299: if txt is None:
! 300: st.txt += add_to_txt
! 301: else:
! 302: txt += add_to_txt
! 303: if st.dt_from == tag:
! 304: st.man_out.append('.IP "' + manify(txt) + '"\n')
! 305: st.html_out.append('</dt><dd>')
! 306: st.at_first_tag_in_dd = True
! 307: st.dt_from = None
! 308: elif tag == 'dt':
! 309: st.html_out.append('<dd>')
! 310: st.at_first_tag_in_dd = True
! 311:
! 312:
! 313: def handle_data(self, txt):
! 314: st = self.state
! 315: if args.debug:
! 316: self.output_debug('DATA', (txt,))
! 317: if st.in_pre:
! 318: html = htmlify(txt)
! 319: else:
! 320: txt = re.sub(r'\s--(\s)', NBR_SPACE[0] + r'--\1', txt).replace('--', NBR_DASH[0]*2)
! 321: txt = re.sub(r'(^|\W)-', r'\1' + NBR_DASH[0], txt)
! 322: html = htmlify(txt)
! 323: if st.in_code:
! 324: txt = re.sub(r'\s', NBR_SPACE[0], txt)
! 325: html = html.replace(NBR_DASH[0], '-').replace(NBR_SPACE[0], ' ') # <code> is non-breaking in CSS
! 326: st.html_out.append(html.replace(NBR_SPACE[0], ' ').replace(NBR_DASH[0], '-⁠'))
! 327: st.txt += txt
! 328:
! 329:
! 330: def output_debug(self, event, extra):
! 331: import pprint
! 332: st = self.state
! 333: if args.debug < 2:
! 334: st = argparse.Namespace(**vars(st))
! 335: if len(st.html_out) > 2:
! 336: st.html_out = ['...'] + st.html_out[-2:]
! 337: if len(st.man_out) > 2:
! 338: st.man_out = ['...'] + st.man_out[-2:]
! 339: print(event, extra)
! 340: pprint.PrettyPrinter(indent=2).pprint(vars(st))
! 341:
! 342:
! 343: def manify(txt):
! 344: return re.sub(r"^(['.])", r'\&\1', txt.replace('\\', '\\\\')
! 345: .replace(NBR_SPACE[0], NBR_SPACE[1])
! 346: .replace(NBR_DASH[0], NBR_DASH[1])
! 347: .replace(NORM_FONT[0], NORM_FONT[1])
! 348: .replace(BOLD_FONT[0], BOLD_FONT[1])
! 349: .replace(UNDR_FONT[0], UNDR_FONT[1]), flags=re.M)
! 350:
! 351:
! 352: def htmlify(txt):
! 353: return txt.replace('&', '&').replace('<', '<').replace('>', '>').replace('"', '"')
! 354:
! 355:
! 356: def warn(*msg):
! 357: print(*msg, file=sys.stderr)
! 358:
! 359:
! 360: def die(*msg):
! 361: warn(*msg)
! 362: sys.exit(1)
! 363:
! 364:
! 365: if __name__ == '__main__':
! 366: parser = argparse.ArgumentParser(description='Transform a NAME.NUM.md markdown file into a NAME.NUM.html web page & a NAME.NUM man page.', add_help=False)
! 367: parser.add_argument('--test', action='store_true', help='Test if we can parse the input w/o updating any files.')
! 368: parser.add_argument('--debug', '-D', action='count', default=0, help='Output copious info on the html parsing. Repeat for even more.')
! 369: parser.add_argument("--help", "-h", action="help", help="Output this help message and exit.")
! 370: parser.add_argument('mdfile', help="The NAME.NUM.md file to parse.")
! 371: args = parser.parse_args()
! 372:
! 373: try:
! 374: import cmarkgfm
! 375: md_parser = cmarkgfm.markdown_to_html
! 376: except:
! 377: try:
! 378: import commonmark
! 379: md_parser = html_via_commonmark
! 380: except:
! 381: die("Failed to find cmarkgfm or commonmark for python3.")
! 382:
! 383: main()
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to md2man CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / rsync