Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Manpage generation improvements #248

Merged
merged 5 commits into from
Jan 8, 2021
Merged

Manpage generation improvements #248

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5883be1
Limit scope of generated (3) manpages to MMDB_
paravoid Jan 7, 2021
d67743c
Remove Pandoc version from manpages
paravoid Dec 27, 2017
e623f71
Add lowdown as an alternative Markdown->man translator
paravoid Jan 8, 2021
9e76848
Disable "smarty" filters from manpage generation
paravoid Jan 8, 2021
76c3d94
Pass pandoc a more-compatible Markdown flavor
paravoid Jan 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 30 additions & 13 deletions dev-bin/make-man-pages.pl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,28 +14,40 @@
sub main {
my $target = shift || "$Bin/..";

my $pandoc = which('pandoc')
or die
"\n You must install pandoc in order to generate the man pages.\n\n";
my @translators = qw ( pandoc lowdown );
my $translator;
foreach my $p ( @translators ) {
if (defined which($p)) {
$translator = $p;
last;
}
}
unless ( defined $translator ) {
die
"\n You must install one of " . join(', ', @translators) .
" in order to generate the man pages.\n\n";
}

_make_man( $target, 'libmaxminddb', 3 );
_make_man( $translator, $target, 'libmaxminddb', 3 );
_make_lib_man_links($target);

_make_man( $target, 'mmdblookup', 1 );
_make_man( $translator, $target, 'mmdblookup', 1 );
}

sub _make_man {
my $target = shift;
my $name = shift;
my $section = shift;
my $translator = shift;
my $target = shift;
my $name = shift;
my $section = shift;

my $man_dir = "$target/man/man$section";
mkpath($man_dir);

my $tempdir = tempdir( CLEANUP => 1 );

my $markdown = <<"EOF";
% $name($section)
title: $name
section: $section

EOF
$markdown .= read_file("$Bin/../doc/$name.md");
Expand All @@ -44,16 +56,20 @@ sub _make_man {
write_file( $tempfile, $markdown );

my $man_file = "$man_dir/$name.$section";
system( qw( pandoc -s -t man ), $tempfile, '-o', $man_file );

_fix_indentation($man_file);
if ( $translator eq 'pandoc' ) {
system( qw( pandoc -s -f markdown_mmd+backtick_code_blocks -t man ), $tempfile, '-o', $man_file );
_pandoc_postprocess($man_file);
} elsif ( $translator eq 'lowdown' ) {
system( qw( lowdown --out-no-smarty -s -Tman ), $tempfile, '-o', $man_file );
}
}

sub _make_lib_man_links {
my $target = shift;

my $header = read_file("$Bin/../include/maxminddb.h");
for my $proto ( $header =~ /^ *extern.+?(\w+)\(/gsm ) {
for my $proto ( $header =~ /^ *extern.+?(MMDB_\w+)\(/gsm ) {
open my $fh, '>', "$target/man/man3/$proto.3";
print {$fh} ".so man3/libmaxminddb.3\n";
close $fh;
Expand All @@ -62,12 +78,13 @@ sub _make_lib_man_links {

# AFAICT there's no way to control the indentation depth for code blocks with
# Pandoc.
sub _fix_indentation {
sub _pandoc_postprocess {
my $file = shift;

edit_file(
sub {
s/^\.IP\n\.nf/.IP "" 4\n.nf/gm;
s/(Automatically generated by Pandoc)(.+)$/$1/m;
},
$file
);
Expand Down