asciidoc-pve.in: implement commands to generate man pages
authorDietmar Maurer <dietmar@proxmox.com>
Tue, 11 Oct 2016 08:28:30 +0000 (10:28 +0200)
committerDietmar Maurer <dietmar@proxmox.com>
Tue, 11 Oct 2016 08:28:30 +0000 (10:28 +0200)
Makefile
asciidoc-pve.in
pve-doc-generator.mk

index 36a6377..37bebb8 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,5 @@
 DGDIR=.
+ASCIIDOC_PVE=./asciidoc-pve
 
 include ./pve-doc-generator.mk
 
@@ -213,11 +214,11 @@ all: index.html
 
 chapter-sysadmin.html sysadmin-plain.html: ${SYSADMIN_SOURCES}
 
-chapter-%.html: %.adoc ${PVE_COMMON_DOC_SOURCES}
-       asciidoc ${ADOC_STDARG} -a toc -o $@ $*.adoc
+chapter-%.html: %.adoc asciidoc-pve ${PVE_COMMON_DOC_SOURCES}
+       ./asciidoc-pve compile-chapter -o $@ $*.adoc
 
-%.1.html: %.adoc %.1-synopsis.adoc ${PVE_COMMON_DOC_SOURCES}
-       asciidoc ${ADOC_MAN1_HTML_ARGS} -o $@ $*.adoc
+%.1.html: %.adoc %.1-synopsis.adoc asciidoc-pve ${PVE_COMMON_DOC_SOURCES}
+       ./asciidoc-pve compile-man-html -o $@ $*.adoc
 
 pmxcfs.8.html: pmxcfs.adoc pmxcfs.8-cli.adoc ${PVE_COMMON_DOC_SOURCES}
        asciidoc ${ADOC_MAN8_HTML_ARGS} -o $@ pmxcfs.adoc
@@ -310,5 +311,5 @@ update: clean
        make all
 
 clean: 
-       rm -rf *.tmp.xml *.html *.pdf *.epub *.tmp *.1 *.5 *.8 *.deb *.changes build api-viewer/apidoc.js chapter-*.html *-plain.html chapter-*.html pve-admin-guide.chunked asciidoc-pve link-refs.json .asciidoc-pve-tmp_* pve-docs-mediawiki-import
+       rm -rf *.html *.pdf *.epub *.tmp *.1 *.5 *.8 *.deb *.changes build api-viewer/apidoc.js chapter-*.html *-plain.html chapter-*.html pve-admin-guide.chunked asciidoc-pve link-refs.json .asciidoc-pve-tmp_* pve-docs-mediawiki-import
        find . -name '*~' -exec rm {} ';'
index b578556..109b066 100644 (file)
@@ -30,6 +30,7 @@ if (-f "attributes.txt" && -f "pve-admin-guide.adoc") {
 
 my $prepared_files = {};
 
+my $man_target_html = 0;
 my $env_stack = [];
 my $env_skip = 0;
 
@@ -77,35 +78,84 @@ sub replace_wiki_xref {
 
     $text = $reftext if !length($text);
 
-    die "xref: no text for '$blockid'\n" if !$text;
+    die "xref: no text for wiki link '$blockid'\n" if !$text;
 
     return "$link\[$text\]";
 }
 
+sub replace_default_xref {
+    my ($blockid, $text) = @_;
+
+    my $link = $fileinfo->{blockid_target}->{default}->{$blockid};
+    my $reftext = $fileinfo->{reftext}->{default}->{$blockid};
+
+    die "unable to resolve chapter link (xref:$blockid)\n"
+       if !defined($link);
+
+    $text = $reftext if !length($text);
+
+    die "xref: no text for chapter link '$blockid'\n" if !$text;
+
+    return "$link\[$text\]";
+}
+
+sub replace_man_xref {
+    my ($blockid, $text) = @_;
+
+    my $link = $fileinfo->{blockid_target}->{manvolnum}->{$blockid};
+    my $reftext = $fileinfo->{reftext}->{manvolnum}->{$blockid};
+
+    die "unable to resolve man page link (xref:$blockid)\n"
+       if !defined($link);
+
+    $text = $reftext if !length($text);
+
+    die "xref: no text for man page link '$blockid'\n" if !$text;
+
+    my $section = $fileinfo->{mansection}->{manvolnum}->{$link};
+    die "link target is not a manual page" if !defined($section);
+
+
+    if (0 && $man_target_html) {
+       my $target = $link;
+       $target =~ s/\.adoc//;
+       $target .= ".$section";
+       return "link:${target}.html#${blockid}\[$text\]";
+    } else {
+       my $command = $link;
+       $command =~ s/\.adoc//;
+       return "\*${text}\* (man \*${command}\*($section))";
+    }
+}
+
 sub replace_xref {
     my ($env, $blockid, $text) = @_;
 
     if ($env eq 'wiki') {
        return replace_wiki_xref($blockid, $text);
+    } elsif ($env eq 'manvolnum') {
+       return replace_man_xref($blockid, $text);
+    } elsif ($env eq 'default') {
+       return replace_default_xref($blockid, $text);
     } else {
-       die "implement me";
+       die "internal error";
     }
 }
 
 sub prepare_adoc_file {
     my ($target_env, $filename, $attributes) = @_;
 
-    return if $prepared_files->{$filename};
+    return $prepared_files->{$filename} if defined($prepared_files->{$filename});
 
     print "PREPARE $filename\n";
 
-    $prepared_files->{$filename} = 1;
-
     my $dirname = dirname($filename);
     my $basename = basename($filename);
 
     my $outfilename = "$dirname/${tmpprefix}$basename";
 
+    $prepared_files->{$filename} = $outfilename;
+
     my $fh = IO::File->new("$filename", "r") or
        die "unable to open file '$filename' - $!\n";
 
@@ -113,6 +163,7 @@ sub prepare_adoc_file {
        die "unable to open temporary file '$outfilename'\n";
 
     while (defined (my $line = <$fh>)) {
+       chomp $line;
        if ($line =~ m/^if(n?)def::(\S+)\[(.*)\]\s*$/) {
            my ($not, $env, $text) = ($1, $2, $3);
            die "unsuported ifdef usage - implement me" if $text;
@@ -135,7 +186,9 @@ sub prepare_adoc_file {
            my ($fn, $rest) = ($1, $2);
            print "INCLUDE: $fn\n";
            my $new_fn = prepare_adoc_file($target_env, $fn, $attributes);
-           $line = "include::${new_fn}$rest\n";
+
+           print $outfh "include::${new_fn}$rest\n";
+           next;
        }
 
        # fix xrefs
@@ -143,7 +196,7 @@ sub prepare_adoc_file {
 
        $line =~ s/<<([^\s,\[\]]+)(?:,(.*?))?>>/replace_xref(${target_env},$1,$2)/ge;
 
-       print $outfh $line;
+       print $outfh $line . "\n";
     }
 
     return $outfilename;
@@ -165,21 +218,21 @@ sub compile_asciidoc {
     scalar(@ARGV) == 0 or
        die "too many arguments...\n";
 
-    if ($env eq 'wiki') {
-
-
-    } else {
+    defined($fileinfo->{titles}->{$env}) ||
        die "unknown environment '$env'";
-    }
 
     my $title = $fileinfo->{titles}->{$env}->{$infile} or
-       die "unable to get title for '$infile'\n";
+       die "unable to get title for '$infile'$env\n";
 
     print "compile: $title\n";
 
     my $leveloffset = 0;
 
-    my $doctype = $fileinfo->{doctype}->{$env}->{$infile} // 0;
+    my $doctype = $fileinfo->{doctype}->{$env}->{$infile};
+
+    die "unable to get document type for '$infile'\n"
+       if !defined($doctype);
+
     $leveloffset = - $doctype;
 
     my $date = `date`;
@@ -187,48 +240,108 @@ sub compile_asciidoc {
 
     my $attributes = {
        $env => undef,
-       icons => undef,
-       'data-uri' => undef,
-       date => $date,
        leveloffset => $leveloffset,
-       revnumber => $release,
     };
 
-    if (!($env eq 'wiki') || ($env ne 'manvolnum')) {
+    my $mansection = $fileinfo->{mansection}->{$env}->{$infile};
+
+    if ($env eq 'wiki') {
+    } elsif ($env eq 'manvolnum') {
+       die "undefined man section" if !defined($mansection);
+       $attributes->{manvolnum} = $mansection;
+    } elsif ($env eq 'default') {
+       die "$infile: wrong doctype\n" if $doctype != 0;
        $attributes->{toc} = undef;
     }
 
-    my $cmd = ['asciidoc', '-s'];
-
-    foreach my $key (keys %$attributes) {
-       my $value = $attributes->{$key};
-       if (defined($value)) {
-           push @$cmd, '-a', "$key=$value";
+    if (!defined($outfile)) {
+       $outfile = $infile;
+       $outfile =~ s/\.adoc$//;
+       if ($env eq 'manvolnum') {
+           if ($man_target_html) {
+               $outfile .= ".$mansection.html";
+           } else {
+               $outfile .= ".$mansection";
+           }
        } else {
-           push @$cmd, '-a', $key;
+           $outfile .= ".html";
        }
     }
 
-    push @$cmd, '--verbose' if $verbose;
+    if (($env eq 'manvolnum') && !$man_target_html) {
 
-    if (!defined($outfile)) {
-       $outfile = $infile;
-       $outfile =~ s/\.adoc$//;
-       $outfile .= ".html";
-    }
+       # asciidoc /etc/asciidoc/docbook-xsl/manpage.xsl skip REFERENCES
+       # section like footnotes, so we cannot use a2x.
+       # We use xmlto instead.
 
-    push @$cmd, '--out-file', $outfile;
+       my $cmd = ['asciidoc', '-dmanpage', '-bdocbook', '-a', 'docinfo1'];
 
-    my $new_infile = prepare_adoc_file($env, $infile, $attributes);
+       foreach my $key (keys %$attributes) {
+           my $value = $attributes->{$key};
+           if (defined($value)) {
+               push @$cmd, '-a', "$key=$value";
+           } else {
+               push @$cmd, '-a', $key;
+           }
+       }
 
-    push @$cmd, $new_infile;
+       push @$cmd, '--verbose' if $verbose;
 
-    print "RUN " . join(' ', @$cmd) . "\n";
+       my $tmpxmlfile = "${outfile}.xml.tmp";
 
-    system(@$cmd) == 0 or
-       die "aciidoc error";
-}
+       push @$cmd, '--out-file', $tmpxmlfile;
+
+       my $new_infile = prepare_adoc_file($env, $infile, $attributes);
+
+       push @$cmd, $new_infile;
+
+       print "RUN " . join(' ', @$cmd) . "\n";
+
+       system(@$cmd) == 0 or
+           die "aciidoc error";
+
+       $cmd = ['xmlto', 'man', $tmpxmlfile];
+
+       push @$cmd, '-v' if $verbose;
+
+       print "RUN " . join(' ', @$cmd) . "\n";
+
+       system(@$cmd) == 0 or
+           die "xmlto error";
+
+    } else {
 
+       $attributes->{icons} = undef;
+       $attributes->{'data-uri'} = undef;
+       $attributes->{revnumber} = $release;
+
+       my $cmd = ['asciidoc'];
+
+       push @$cmd, '-s' if $env eq 'wiki';
+
+       foreach my $key (keys %$attributes) {
+           my $value = $attributes->{$key};
+           if (defined($value)) {
+               push @$cmd, '-a', "$key=$value";
+           } else {
+               push @$cmd, '-a', $key;
+           }
+       }
+
+       push @$cmd, '--verbose' if $verbose;
+
+       push @$cmd, '--out-file', $outfile;
+
+       my $new_infile = prepare_adoc_file($env, $infile, $attributes);
+
+       push @$cmd, $new_infile;
+
+       print "RUN " . join(' ', @$cmd) . "\n";
+
+       system(@$cmd) == 0 or
+           die "aciidoc error";
+    }
+}
 
 if ($clicmd eq 'compile-wiki') {
 
@@ -239,6 +352,35 @@ if ($clicmd eq 'compile-wiki') {
 
     die $err if $err;
 
+} elsif ($clicmd eq 'compile-chapter') {
+
+    eval { compile_asciidoc('default'); };
+    my $err = $@;
+
+    cleanup();
+
+    die $err if $err;
+
+} elsif ($clicmd eq 'compile-man-html') {
+
+    $man_target_html = 1;
+
+    eval { compile_asciidoc('manvolnum'); };
+    my $err = $@;
+
+    cleanup();
+
+    die $err if $err;
+
+} elsif ($clicmd eq 'compile-man') {
+
+    eval { compile_asciidoc('manvolnum'); };
+    my $err = $@;
+
+    cleanup();
+
+    die $err if $err;
+
 } else {
 
     die "unknown command '$clicmd'\n";
index 4998074..a729d46 100644 (file)
@@ -3,6 +3,8 @@ DOCRELEASE=4.3
 
 DGDIR?=/usr/share/pve-doc-generator
 
+ASCIIDOC_PVE?=asciidoc-pve
+
 all:
 
 PVE_COMMON_DOC_SOURCES=                        \
@@ -173,107 +175,80 @@ ifneq (${DGDIR},.)
        mv $@.tmp $@
 endif
 
-# asciidoc /etc/asciidoc/docbook-xsl/manpage.xsl skip REFERENCES section
-# like footnotes, so we cannot use a2x. We use xmlto instead.
-#A2MAN_COMMON=a2x -v -k -a docinfo1 -a "manversion=Release ${DOCRELEASE}" -f manpage
-#A2MAN1=${A2MAN_COMMON} -a "manvolnum=1"
-#A2MAN5=${A2MAN_COMMON} -a "manvolnum=5"
-#A2MAN8=${A2MAN_COMMON} -a "manvolnum=8"
-
-A2MAN_COMMON=asciidoc -dmanpage -bdocbook -a docinfo1
-
-define A2MAN1
-${A2MAN_COMMON} -a "manvolnum=1" -o $1.tmp.xml $1.adoc
-xmlto -v man $1.tmp.xml
-@rm -f $1.tmp.xml
-endef
-
-define A2MAN5
-${A2MAN_COMMON} -a "manvolnum=5" -o $1.tmp.xml $1.adoc
-xmlto -v man $1.tmp.xml 
-@rm -f $1.tmp.xml
-endef
-
-define A2MAN8
-${A2MAN_COMMON} -a "manvolnum=8" -o $1.tmp.xml $1.adoc
-xmlto -v man $1.tmp.xml
-@rm -f $1.tmp.xml
-endef
-
-pve-firewall.8: ${PVE_FIREWALL_MAN8_SOURCES}
-       $(call A2MAN8,pve-firewall)
+pve-firewall.8: ${PVE_FIREWALL_MAN8_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pve-firewall.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pvesm.1: ${PVESM_MAN1_SOURCES}
-       $(call A2MAN1,pvesm)
+pvesm.1: ${PVESM_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pvesm.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pveceph.1: ${PVECEPH_MAN1_SOURCES}
-       $(call A2MAN1,pveceph)
+pveceph.1: ${PVECEPH_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pveceph.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pct.1: ${PCT_MAN1_SOURCES}
-       $(call A2MAN1,pct)
+pct.1: ${PCT_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pct.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-vzdump.1: ${VZDUMP_MAN1_SOURCES}
-       $(call A2MAN1,vzdump)
+vzdump.1: ${VZDUMP_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ vzdump.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pvesubscription.1: ${PVESUBSCRIPTION_MAN1_SOURCES}
-       $(call A2MAN1,pvesubscription)
+pvesubscription.1: ${PVESUBSCRIPTION_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pvesubscription.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-qm.1: ${QM_MAN1_SOURCES}
-       $(call A2MAN1,qm)
+qm.1: ${QM_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ qm.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-qmrestore.1: ${QMRESTORE_MAN1_SOURCES}
-       $(call A2MAN1,qmrestore)
+qmrestore.1: ${QMRESTORE_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ qmrestore.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pvecm.1: ${PVECM_MAN1_SOURCES}
-       $(call A2MAN1,pvecm)
+pvecm.1: ${PVECM_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pvecm.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pveum.1: ${PVEUM_MAN1_SOURCES}
-       $(call A2MAN1,pveum)
+pveum.1: ${PVEUM_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pveum.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pveam.1: ${PVEAM_MAN1_SOURCES}
-       $(call A2MAN1,pveam)
+pveam.1: ${PVEAM_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pveam.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-ha-manager.1: ${HA_MANAGER_MAN1_SOURCES}
-       $(call A2MAN1,ha-manager)
+ha-manager.1: ${HA_MANAGER_MAN1_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ ha-manager.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pve-ha-crm.8: ${PVE_HA_CRM_MAN8_SOURCES}
-       $(call A2MAN8,pve-ha-crm)
+pve-ha-crm.8: ${PVE_HA_CRM_MAN8_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pve-ha-crm.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pve-ha-lrm.8: ${PVE_HA_LRM_MAN8_SOURCES}
-       $(call A2MAN8,pve-ha-lrm)
+pve-ha-lrm.8: ${PVE_HA_LRM_MAN8_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pve-ha-lrm.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pvestatd.8: ${PVESTATD_MAN8_SOURCES}
-       $(call A2MAN8,pvestatd)
+pvestatd.8: ${PVESTATD_MAN8_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pvestatd.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pvedaemon.8: ${PVEDAEMON_MAN8_SOURCES}
-       $(call A2MAN8,pvedaemon)
+pvedaemon.8: ${PVEDAEMON_MAN8_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pvedaemon.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pveproxy.8: ${PVEPROXY_MAN8_SOURCES}
-       $(call A2MAN8,pveproxy)
+pveproxy.8: ${PVEPROXY_MAN8_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pveproxy.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-spiceproxy.8: ${SPICEPROXY_MAN8_SOURCES}
-       $(call A2MAN8,spiceproxy)
+spiceproxy.8: ${SPICEPROXY_MAN8_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ spiceproxy.adoc
        test -n "$${NOVIEW}" || man -l $@
 
-pmxcfs.8: ${PMXCFS_MAN8_SOURCES}
-       $(call A2MAN8,pmxcfs)
+pmxcfs.8: ${PMXCFS_MAN8_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ pmxcfs.adoc
        test -n "$${NOVIEW}" || man -l $@
 
 qm.conf.5: ${QM_CONF_MAN5_SOURCES}
@@ -282,8 +257,8 @@ pct.conf.5: ${PCT_CONF_MAN5_SOURCES}
 
 datacenter.cfg.5: ${DATACENTER_CONF_MAN5_SOURCES}
 
-%.5: %.adoc %.5-opts.adoc ${PVE_COMMON_DOC_SOURCES}
-       $(call A2MAN5,$*)
+%.5: %.adoc %.5-opts.adoc ${PVE_COMMON_DOC_SOURCES} ${ASCIIDOC_PVE}
+       ${ASCIIDOC_PVE} compile-man -o $@ $*.adoc
        test -n "$${NOVIEW}" || man -l $@
 
 .PHONY: cleanup-docgen