5
0
mirror of git://git.proxmox.com/git/pve-docs.git synced 2025-03-22 02:50:06 +03:00

asciidoc-pve.in: implement commands to generate man pages

This commit is contained in:
Dietmar Maurer 2016-10-11 10:28:30 +02:00
parent 404a158e1b
commit c38115e910
3 changed files with 230 additions and 112 deletions

View File

@ -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 {} ';'

View 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,49 +240,109 @@ 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";
} else {
push @$cmd, '-a', $key;
}
}
push @$cmd, '--verbose' if $verbose;
if (!defined($outfile)) {
$outfile = $infile;
$outfile =~ s/\.adoc$//;
$outfile .= ".html";
if ($env eq 'manvolnum') {
if ($man_target_html) {
$outfile .= ".$mansection.html";
} else {
$outfile .= ".$mansection";
}
} else {
$outfile .= ".html";
}
}
push @$cmd, '--out-file', $outfile;
if (($env eq 'manvolnum') && !$man_target_html) {
my $new_infile = prepare_adoc_file($env, $infile, $attributes);
# asciidoc /etc/asciidoc/docbook-xsl/manpage.xsl skip REFERENCES
# section like footnotes, so we cannot use a2x.
# We use xmlto instead.
push @$cmd, $new_infile;
my $cmd = ['asciidoc', '-dmanpage', '-bdocbook', '-a', 'docinfo1'];
print "RUN " . join(' ', @$cmd) . "\n";
foreach my $key (keys %$attributes) {
my $value = $attributes->{$key};
if (defined($value)) {
push @$cmd, '-a', "$key=$value";
} else {
push @$cmd, '-a', $key;
}
}
system(@$cmd) == 0 or
die "aciidoc error";
push @$cmd, '--verbose' if $verbose;
my $tmpxmlfile = "${outfile}.xml.tmp";
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') {
eval { compile_asciidoc('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";

View 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