generate man page output file mappings automatically

[pve-docs.git] / scan-adoc-refs

#!/usr/bin/perl

use strict;
use warnings;
use IO::File;
use JSON;

use Data::Dumper;

my $environments = {
    default => 1,
    wiki => 1,
    manvolnum => 1,
    pvelogo => 0, # ignore
};

my $fileinfo = {
    outfile => {
	default => {
	    "pve-admin-guide.adoc" => "pve-admin-guide.html",
	    "datacenter.cfg.adoc" => "datacenter.cfg.5.html",
	    "ha-manager.adoc" => "chapter-ha-manager.html",
	    "pct.adoc" => "chapter-pct.html",
	    "pve-bibliography.adoc" => "chapter-pve-bibliography.html",
	    "pve-firewall.adoc" => "chapter-pve-firewall.html",
	    "pve-installation.adoc" => "chapter-pve-installation.html",
	    "pvecm.adoc" => "chapter-pvecm.html",
	    "pvesm.adoc" => "chapter-pvesm.html",
	    "pveum.adoc" => "chapter-pveum.html",
	    "qm.adoc" => "chapter-qm.html",
	    "sysadmin.adoc" => "chapter-sysadmin.html",
	    "vzdump.adoc" => "chapter-vzdump.html",
	    "pmxcfs.adoc" => "chapter-pmxcfs.html",
	    "pve-faq.adoc" => "chapter-pve-faq.html",
	},
    },
};

my $start_env = [];
foreach my $e (keys %$environments) {
    push @$start_env, $e if $environments->{$e};
}

my $env_stack = [$start_env];
my $env_name_stack = [];

sub reset_environment_stack {
    $env_stack = [$start_env];
    $env_name_stack = [];
}

sub push_environment {
    my ($env, $not) = @_;

    die "undefined environment '$env'\n" if !defined($environments->{$env});

    # FIXME: this seems wrong  (nested env?)?
    return if !$environments->{$env}; # do not track

    if ($not) {
	my $new_env = [];
	foreach my $e (@{$env_stack->[-1]}) {
	    if ($e ne $env) {
		push @$new_env, $e;
	    }
	}
	die "empty environment" if !scalar($new_env);
	push @$env_stack, $new_env;
    } else {
	push @$env_stack, [$env];
    }

    push @$env_name_stack, $env;
}

sub pop_environment {
    my ($env) = @_;

    die "undefined environment '$env'\n" if !defined($environments->{$env});

    return if !$environments->{$env}; # do not track

    pop @$env_stack;
    my $res = pop @$env_name_stack;

    die "environment missmatch ($res != $env)\n" if $res ne $env;
}

sub register_include {
    my ($filename, $include_filename, $env_list) = @_;

    return if $include_filename !~ m/\.adoc$/; # skip attributes.txt

    foreach my $e (@$env_list) {
	$fileinfo->{include}->{$e}->{$filename}->{$include_filename} = 1;
    }
}

sub register_blockid {
    my ($filename, $blockid, $reftext, $env_list) = @_;

    foreach my $e (@$env_list) {
	my $fn = $fileinfo->{blockid}->{$e}->{$blockid};
	die "blockid '$blockid' already defined in $fn"
	    if defined($fn);
	$fileinfo->{blockid}->{$e}->{$blockid} = $filename;
	$fileinfo->{reftext}->{$e}->{$blockid} = $reftext
	    if defined($reftext);
    }
}

sub register_title {
    my ($filename, $env, $doctype, $title, $blockid) = @_;

    # fixme: what about other macros?
    $title =~ s/\{pve\}/Proxmox VE/g;
    $title =~ s!http://\S+\[(.*?)\]!$1!g;

    # register document title (onyl once)
    if (!defined($fileinfo->{titles}->{$env}->{$filename})) {

	$fileinfo->{titles}->{$env}->{$filename} = $title;

	if (defined($doctype)) {
	    $fileinfo->{doctype}->{$env}->{$filename} = $doctype;
	} else {
	    die "unable to change title (no doctype)"
		if !defined($fileinfo->{doctype}->{$env}->{$filename});
	}

	if (defined($doctype) && ($env eq 'manvolnum') && ($doctype == 0)) {
	    if ($title =~ m/.*\(([1-8])\)\s*$/) {
		$fileinfo->{mansection}->{$env}->{$filename} = $1;
	    }
	}
    }

    if ($blockid) {
	die "internal error"
	    if !defined($fileinfo->{blockid}->{$env}->{$blockid});
	$fileinfo->{reftitle}->{$env}->{$blockid} = $title;
    }
}

sub scan_adoc_file {
    my ($filename) = @_;

    reset_environment_stack();

    # print "SCAN $filename\n";

    my $fh = IO::File->new("$filename", "r") or
	die "unable to open file '$filename' - $!\n";

    my $env_last_line = {};
    my $env_last_blockid = {};

    while (defined (my $line = <$fh>)) {
	if ($line =~ m/^if(n?)def::(\S+)\[(.*)\]\s*$/) {
	    my ($not, $env, $text) = ($1, $2, $3);
	    die "unsuported ifdef usage - implement me" if $text;
	    push_environment($env, $not);
	    next;
	} elsif ($line =~ m/^endif::(\S+)\[(.*)\]\s*$/) {
	    my ($env, $text) = ($1, $2);
	    die "unsuported ifdef usage - implement me" if $text;
	    pop_environment($env);
	    next;
	} elsif ($line =~ m/^include::(\S+)\[.*\]\s*$/) {
	    register_include($filename, $1, $env_stack->[-1]);
	    next;
	}

	# try to detect titles
	foreach my $e (@{$env_stack->[-1]}) {
	    if ($line =~ m/^=====+$/) {
		register_title($filename, $e, 0, $env_last_line->{$e},
			       $env_last_blockid->{$e});
	    } elsif ($line =~ m/^-----+$/) {
		register_title($filename, $e, 1, $env_last_line->{$e},
			       $env_last_blockid->{$e});
	    } elsif ($line =~ m/^~~~~~+$/) {
		register_title($filename, $e, 2, $env_last_line->{$e},
			       $env_last_blockid->{$e});
	    } elsif ($line =~ m/^\^\^\^\^\^+$/) {
		register_title($filename, $e, 3, $env_last_line->{$e},
			       $env_last_blockid->{$e});
	    } elsif ($line =~ m/^= +(\S.*?)( +=)?$/) {
		register_title($filename, $e, 0, $1, $env_last_blockid->{$e});
	    } elsif ($line =~ m/^== +(\S.*?)( +==)?$/) {
		register_title($filename, $e, 1, $1, $env_last_blockid->{$e});
	    } elsif ($line =~ m/^=== +(\S.*?)( +===)?$/) {
		register_title($filename, $e, 2, $1, $env_last_blockid->{$e});
	    } elsif ($line =~ m/^==== +(\S.*?)( +====)?$/) {
		register_title($filename, $e, 3, $1, $env_last_blockid->{$e});
	    }

	    $env_last_line->{$e} = $line;
	    chomp $env_last_line->{$e};
	}

	if ($line =~ m/^:(\S+?):\s*(.*\S)?\s*$/) {
	    my ($key, $value) = ($1, $2);
	    if ($key eq 'pve-toplevel') {

		foreach my $e (@{$env_stack->[-1]}) {
		    my $title = $fileinfo->{titles}->{$e}->{$filename};
		    die "not title for toplevel file '$filename' (env=$e)\n"
			if !defined($title);
		    $fileinfo->{toplevel}->{$e}->{$filename} = 1;
		}
	    } elsif ($key eq 'title') {
		foreach my $e (@{$env_stack->[-1]}) {
		    register_title($filename, $e, undef, $value);
		}
	    }
	}

	if ($line =~ m/^\[\[(.*)\]\]\s*$/) {
	    my $blockid = $1;
	    die "implement me" if $blockid =~m/,/;
	    my $reftext = '';
	    register_blockid($filename, $blockid, $reftext, $env_stack->[-1]);
	    foreach my $e (@{$env_stack->[-1]}) {
		$env_last_blockid->{$e} = $blockid;
	    }
	}

	if ($line =~ m/^\s*$/) {
	    foreach my $e (@{$env_stack->[-1]}) {
		delete $env_last_blockid->{$e};
	    }
	}

	# fixme: "anchor:"
	# bibliography anchors
	if ($line =~ m/\[\[\[([^\]]*)\]\]\]/) {
	    my $blockid = $1;
	    die "implement me" if $blockid =~m/,/;
	    register_blockid($filename, $blockid, "&#91;$blockid&#93;", $env_stack->[-1]);
	}
    }
}

my $scanned_files = {};
while (my $filename = shift) {
    next if $filename !~ m/\.adoc$/; # skip attributes.txt
    next if $scanned_files->{$filename};

    scan_adoc_file($filename);
    $scanned_files->{$filename} = 1;
}

sub resolve_link_target {
    my ($env, $filename) = @_;

    my $include_hash = $fileinfo->{include}->{$env};

    my $repeat = 1;

    while ($repeat) {
	$repeat = 0;
	foreach my $fn (keys %$include_hash) {
	    if ($include_hash->{$fn}->{$filename}) {
		next if ($fn eq 'pve-admin-guide.adoc') &&
		    $fileinfo->{outfile}->{$env}->{$filename};
		$filename = $fn;
		$repeat = 1;
		last;
	    }
	}
    }

    return $filename;
}


# try to generate output file mapping
foreach my $e (@$start_env) {
    my $toplevel_hash = $fileinfo->{toplevel}->{$e};
    foreach my $fn (sort keys %$toplevel_hash) {
	my $mansection = $fileinfo->{mansection}->{manvolnum}->{$fn};
	if ($e eq 'wiki') {
	    my $realfn = $fn;
	    $realfn =~ s/\.adoc$//;
	    if (defined($mansection) && ($mansection == 5)) {
		$realfn .= ".$mansection";
	    }
	    $realfn = "$realfn-plain.html";
	    $fileinfo->{outfile}->{$e}->{$fn} = $realfn;
	} elsif ($e eq 'manvolnum') {
	    my $realfn = $fn;
	    $realfn =~ s/\.adoc$//;
	    die "toplevel file '$fn' is marhes as manual page!" if !$mansection;
	    $realfn .= ".$mansection";
	    $fileinfo->{outfile}->{$e}->{$fn} = $realfn;
	}
    }
}

# now resolve blockids
foreach my $e (@$start_env) {
    my $blockid_hash = $fileinfo->{blockid}->{$e};
    foreach my $blockid (keys %$blockid_hash) {
	my $fn = resolve_link_target($e, $blockid_hash->{$blockid});
	if ($e eq 'wiki') {
	    my $title = $fileinfo->{titles}->{$e}->{$fn};
	    $title =~ s/\s/_/g;
	    die "found not title for '$fn' in env '$e'" if !$title;
	    $fileinfo->{blockid_target}->{$e}->{$blockid} = "link:/wiki/$title#$blockid";

	    # we do not produce wiki pages for all content
	    #my $realfn = $fileinfo->{outfile}->{$e}->{$fn};
	    #warn "no output file mapping for '$fn' ($e)\n" if !$realfn;

	} elsif ($e eq 'default') {
	    my $realfn = $fileinfo->{outfile}->{$e}->{$fn} ||
		die "no output file mapping for '$fn'\n";
	    $fileinfo->{blockid_target}->{$e}->{$blockid} = "link:/pve-docs/$realfn#$blockid";
	} elsif ($e eq 'manvolnum') {
	    # we do not produce manpages for all content
	    # my $realfn = $fileinfo->{outfile}->{$e}->{$fn} ||
	    # warn "no output file mapping for '$fn'\n";
	    $fileinfo->{blockid_target}->{$e}->{$blockid} = $fn;
	}
    }
}


print to_json($fileinfo, { pretty => 1,  canonical => 1 } );