aboutsummaryrefslogtreecommitdiffstats
path: root/doc/pod2adoc.py
diff options
context:
space:
mode:
Diffstat (limited to 'doc/pod2adoc.py')
-rwxr-xr-xdoc/pod2adoc.py210
1 files changed, 0 insertions, 210 deletions
diff --git a/doc/pod2adoc.py b/doc/pod2adoc.py
deleted file mode 100755
index 8da7362506..0000000000
--- a/doc/pod2adoc.py
+++ /dev/null
@@ -1,210 +0,0 @@
-#!/usr/bin/env python3
-
-import os
-import re
-import sys
-
-from enum import Enum
-
-# To do:
-# - Fix COUNT(field)filter man output.
-
-class PodState(Enum):
- PRE = 1
- HEAD = 2
- SYNOPSIS = 3
- ITEM_BODY = 4
- AUTHOR = 5
-
-skip_commands = ('=back', '=begin', '=encoding', '=end', '=over')
-
-man4_files = ('extcap', 'wireshark-filter')
-
-tcpdump_manurls = {
- 'pcap': 'https://www.tcpdump.org/manpages/pcap.3pcap.html',
- 'pcap-filter': 'https://www.tcpdump.org/manpages/pcap-filter.7.html',
- 'tcpdump': 'https://www.tcpdump.org/manpages/tcpdump.1.html',
-}
-
-def xlate_markup(podline, inline_nobreak=True):
- # Replace < and > in two steps, here and at the end
- podline = podline.replace('E<lt>', '{lt}')
- podline = podline.replace('E<gt>', '{gt}')
- # TShark escapes quotes
- podline = podline.replace('E<34>', '"')
- # Italic, files, bold, and code
- podline = re.sub(r'[IF]<([^>]+)>', r'__\1__', podline)
- podline = re.sub(r'B<([^>]+)>', r'*\1*', podline)
- podline = re.sub(r'C<([^>]+)>', r'`\1`', podline)
- # AsciiDoctor figures out URL links on its own.
- podline = re.sub(r'L<([^>]+)>', r'\1', podline)
- # S< ... > inserts <span style="white-space: nowrap;"> ... </span>
- # XXX Handle multiline nowraps?
- nobr_re = re.search(r'S<([^>]+)>', podline)
- if nobr_re:
- text = nobr_re.group(1).strip()
- if inline_nobreak:
- if '#' in text:
- text = f'++{text}++'
- # Use .nowrap in paragraphs instead of manarg so that we don't trigger
- # "can't break line" warnings in nroff.
- podline = re.sub(r'S<[^>]+>', f'[.nowrap]#{text}#', podline)
- else:
- podline = re.sub(r'S<([^>]+)>', r'\1', text)
- podline = podline.replace('{lt}', '<')
- podline = podline.replace('{gt}', '>')
- if not podline.endswith('\n'):
- podline += '\n'
- return(podline)
-
-def pod2adoc(podfile):
- if not podfile.endswith('.pod'):
- sys.stderr.write(f"{podfile} doesn't have a .pod extension")
- return
- manpage_name = os.path.basename(podfile).split('.')[-2]
- mansect = 1
- adoc_fname = os.path.join(os.path.dirname(podfile), f'{manpage_name}.adoc')
-
- if manpage_name in man4_files:
- mansect = 4
-
- print(f'Processing {manpage_name}')
-
- state = PodState.PRE
-
- with open(podfile, 'r') as podf:
- adoc_body = f'''\
-= {manpage_name}({mansect})
-:doctype: manpage
-include::../docbook/attributes.adoc[]
-:stylesheet: ws.css
-:linkcss:
-:copycss: ../docbook/{{stylesheet}}
-
-'''
- linenum = 0
- for podline in podf:
- if state == PodState.AUTHOR:
- author = re.sub(r'\s+', ' ', podline.strip())
- if author == '' or author.isspace():
- state = PodState.PRE
- adoc_body += f'{author}\n'
- continue
-
- # Assume that command line synopses start with
- # B<command>
- # S< ... >
- if podline == f'B<{manpage_name}>\n':
- adoc_body += '[manarg]\n'
- state = PodState.SYNOPSIS
-
- podline = xlate_markup(podline, state != PodState.SYNOPSIS)
- linenum += 1
-
- if re.search('[BCEFLISXZ]<', podline):
- podline = xlate_markup(f'{podline} {next(podf)}', state != PodState.SYNOPSIS)
- sys.stderr.write(f'{manpage_name}: joined partial markup on line {linenum}\n')
- linenum += 1
-
- head = re.match('=head([12]) *(.*)', podline)
- if head:
- if state == PodState.ITEM_BODY:
- adoc_body += '--\n\n'
-
- adoc_body += f'={"=" * int(head.group(1))} {head.group(2)}\n'
- state = PodState.HEAD
- continue
-
- # Continued unordered and ordered list items
- item = re.match(r'=item\s*(\*|\d+\.)\s*$', podline)
- if item:
- adoc_body += f'{item.group(1)} '
- continue
-
- # Inline unordered and ordered list items
- item = re.match(r'=item\s*([-\*]\s+.*|\d+\.\s+.*)\s*$', podline)
- if item:
- adoc_body += f'{item.group(1)}'
- continue
-
- # Other list items
- item = re.match('=item\s*(.*)\s*', podline)
- if item:
- dl_term = item.group(1)
- # Menu items
- menu = dl_term.split(':')
- if len(menu) > 1 and re.match('[A-Z][a-z]+$', menu[0]):
- dl_term = f'menu:{menu[0]}[{",".join(menu[1:])}]'
-
- if state == PodState.ITEM_BODY:
- adoc_body += '--\n\n'
-
- adoc_body += f'''\
-{dl_term}::
-+
---'''
- state = PodState.ITEM_BODY
- continue
-
- if podline.startswith(skip_commands):
- continue
-
- if podline.startswith('='):
- sys.stderr.write(f'{manpage_name}: unhandled header on line {linenum}\n')
- sys.exit(1)
-
- if re.search('[BCEFLISXZ]<', podline):
- sys.stderr.write(f'{manpage_name}: unhandled partial markup on line {linenum}\n')
- sys.stderr.write(podline)
- sys.exit(1)
-
- # Author / contributor block.
- if podline.startswith((' Original Author', ' Contributors')):
- if not next(podf).startswith(' --------'):
- sys.stderr.write(f'{manpage_name}: unexpected author or contributor markup on line {linenum}\n')
- sys.exit(1)
-
- linenum += 1
- adoc_body += f'''\
-.{podline.strip()}
-[%hardbreaks]
-'''
- state = PodState.AUTHOR
- continue
-
- for man_re in re.finditer(r'\b([\w-]+)\(\d\)', podline):
- linkfile = man_re.group(1)
- if os.path.isfile(os.path.join(os.path.dirname(podfile), linkfile + '.pod')):
- podline = re.sub(fr'\b{linkfile}\(', f'xref:{linkfile}.html[{linkfile}](', podline)
- elif linkfile in tcpdump_manurls:
- podline = re.sub(fr'\b{linkfile}\(', f'xref:{tcpdump_manurls[linkfile]}[{linkfile}](', podline)
-
- # Single line manual fixups
- if podline.startswith('*lua_script*__num__:__argument__'):
- podline = re.sub('^\*lua_script\*', '**lua_script**', podline)
-
- if '(__field__)__filter__*' in podline:
- podline = re.sub(r'^\*([A-Z/]+)(\(__field__\)__filter__)(\*)', r'**\1**', podline)
-
- if podline.startswith('*FRAMES | BYTES[()__filter__]*'):
- podline = podline.replace('*FRAMES | BYTES[()__filter__]*', '**FRAMES | BYTES**[()__filter__]')
-
- if state != PodState.PRE:
- adoc_body += podline
-
- # Clean up our empty lines.
- adoc_body = re.sub('\n\n+', '\n\n', adoc_body)
-
- # Clean up our item blocks.
- adoc_body = re.sub('\n+--\n\n', '\n--\n\n', adoc_body)
-
- # Body-wide manual fixups
- adoc_body = adoc_body.replace('[<=Jelly Bean]', '[++<=++Jelly Bean]')
-
-
- with open(adoc_fname, 'w') as adocf:
- adocf.write(f'{adoc_body}')
-
-if __name__ == '__main__':
- for podfile in sys.argv[1:]:
- pod2adoc(podfile)
generated by cgit v1.2.3 (git 2.25.1) at 2024-09-21 18:24:41 +0000