From c38115e9105dd81e86e1ce3f75184c3292de116a Mon Sep 17 00:00:00 2001 From: Dietmar Maurer Date: Tue, 11 Oct 2016 10:28:30 +0200 Subject: [PATCH] asciidoc-pve.in: implement commands to generate man pages --- Makefile | 11 ++- asciidoc-pve.in | 220 +++++++++++++++++++++++++++++++++++-------- pve-doc-generator.mk | 109 +++++++++------------ 3 files changed, 229 insertions(+), 111 deletions(-) diff --git a/Makefile b/Makefile index 36a6377..37bebb8 100644 --- 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 {} ';' diff --git a/asciidoc-pve.in b/asciidoc-pve.in index b578556..109b066 100644 --- a/asciidoc-pve.in +++ b/asciidoc-pve.in @@ -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"; diff --git a/pve-doc-generator.mk b/pve-doc-generator.mk index 4998074..a729d46 100644 --- a/pve-doc-generator.mk +++ b/pve-doc-generator.mk @@ -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 -- 2.39.2