* [PATCH for-4.6 1/5] docs: Move misc README's into docs/misc/
2015-08-26 9:09 [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Andrew Cooper
@ 2015-08-26 9:09 ` Andrew Cooper
2015-08-26 9:09 ` [PATCH for-4.6 2/5] docs: Move xentop.1 to docs/man/xentop.pod.1 Andrew Cooper
` (4 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Andrew Cooper @ 2015-08-26 9:09 UTC (permalink / raw)
To: Xen-devel; +Cc: Andrew Cooper, Ian Jackson, Ian Campbell, Wei Liu
To live with the other documentation.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
stubdom/README => docs/misc/stubdom.txt | 0
tools/xenmon/README => docs/misc/xenmon.txt | 0
stubdom/Makefile | 6 +-----
tools/xenmon/Makefile | 2 --
4 files changed, 1 insertion(+), 7 deletions(-)
rename stubdom/README => docs/misc/stubdom.txt (100%)
rename tools/xenmon/README => docs/misc/xenmon.txt (100%)
diff --git a/stubdom/README b/docs/misc/stubdom.txt
similarity index 100%
rename from stubdom/README
rename to docs/misc/stubdom.txt
diff --git a/tools/xenmon/README b/docs/misc/xenmon.txt
similarity index 100%
rename from tools/xenmon/README
rename to docs/misc/xenmon.txt
diff --git a/stubdom/Makefile b/stubdom/Makefile
index faa7c21..e1359cf 100644
--- a/stubdom/Makefile
+++ b/stubdom/Makefile
@@ -463,15 +463,11 @@ xenstore-stubdom: mini-os-$(XEN_TARGET_ARCH)-xenstore libxc xenstore
#########
ifeq ($(STUBDOM_SUPPORTED),1)
-install: $(STUBDOMPATH) install-readme $(STUBDOM_INSTALL)
+install: $(STUBDOMPATH) $(STUBDOM_INSTALL)
else
install: $(STUBDOMPATH)
endif
-install-readme:
- $(INSTALL_DIR) $(DESTDIR)$(docdir)
- $(INSTALL_DATA) README $(DESTDIR)$(docdir)/README.stubdom
-
install-ioemu: ioemu-stubdom
$(INSTALL_DIR) "$(DESTDIR)$(LIBEXEC_BIN)"
$(INSTALL_PROG) stubdom-dm "$(DESTDIR)$(LIBEXEC_BIN)"
diff --git a/tools/xenmon/Makefile b/tools/xenmon/Makefile
index 5095682..20ea100 100644
--- a/tools/xenmon/Makefile
+++ b/tools/xenmon/Makefile
@@ -31,8 +31,6 @@ install: build
$(INSTALL_PROG) xenbaked $(DESTDIR)$(sbindir)/xenbaked
$(INSTALL_PROG) xentrace_setmask $(DESTDIR)$(sbindir)/xentrace_setmask
$(INSTALL_PROG) xenmon.py $(DESTDIR)$(sbindir)/xenmon.py
- $(INSTALL_DIR) $(DESTDIR)$(docdir)
- $(INSTALL_DATA) README $(DESTDIR)$(docdir)/README.xenmon
.PHONY: clean
clean:
--
1.7.10.4
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH for-4.6 2/5] docs: Move xentop.1 to docs/man/xentop.pod.1
2015-08-26 9:09 [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Andrew Cooper
2015-08-26 9:09 ` [PATCH for-4.6 1/5] docs: Move misc README's into docs/misc/ Andrew Cooper
@ 2015-08-26 9:09 ` Andrew Cooper
2015-08-26 9:09 ` [PATCH for-4.6 3/5] docs: Move xentrace_format.1 to docs/man/xentrace_format.pod.1 Andrew Cooper
` (3 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Andrew Cooper @ 2015-08-26 9:09 UTC (permalink / raw)
To: Xen-devel; +Cc: Andrew Cooper, Ian Jackson, Ian Campbell, Wei Liu
And transform to POD to match our other manpages.
The content is identical, although the layout differs slightly with
certain indentation.
In addition, adjust the MAN{1,5}SRC-y `find` runes to be more general.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
docs/Makefile | 6 +--
docs/man/xentop.pod.1 | 111 +++++++++++++++++++++++++++++++++++++++++
tools/xenstat/xentop/Makefile | 4 +-
tools/xenstat/xentop/xentop.1 | 103 --------------------------------------
4 files changed, 114 insertions(+), 110 deletions(-)
create mode 100644 docs/man/xentop.pod.1
delete mode 100644 tools/xenstat/xentop/xentop.1
diff --git a/docs/Makefile b/docs/Makefile
index 272292c..ef3340c 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -7,10 +7,8 @@ VERSION := $(shell $(MAKE) -C $(XEN_ROOT)/xen --no-print-directory xenversion)
DOC_ARCHES := arm x86_32 x86_64
# Documentation sources to build
-MAN1SRC-y += $(sort $(shell find man -name 'xl*.pod.1' -print))
-MAN1SRC-y += $(sort $(shell find man -name 'xenstore*.pod.1' -print))
-
-MAN5SRC-y := $(sort $(shell find man -name 'xl*.pod.5' -print))
+MAN1SRC-y := $(sort $(shell find man/ -name '*.pod.1' -print))
+MAN5SRC-y := $(sort $(shell find man/ -name '*.pod.5' -print))
MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
diff --git a/docs/man/xentop.pod.1 b/docs/man/xentop.pod.1
new file mode 100644
index 0000000..1d0eb50
--- /dev/null
+++ b/docs/man/xentop.pod.1
@@ -0,0 +1,111 @@
+=head1 NAME
+
+xentop - displays real-time information about a Xen system and domains
+
+=head1 SYNOPSIS
+
+B<xentop> [B<-h>] [B<-V>] [B<-d>SECONDS] [B<-n>] [B<-r>] [B<-v>] [B<-f>]
+[B<-b>] [B<-i>ITERATIONS]
+
+=head1 DESCRIPTION
+
+B<xentop> displays information about the Xen system and domains, in a
+continually-updating manner. Command-line options and interactive commands
+can change the detail and format of the information displayed by B<xentop>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h>, B<--help>
+
+display help and exit
+
+=item B<-V>, B<--version>
+
+output version information and exit
+
+=item B<-d>, B<--delay>=I<SECONDS>
+
+seconds between updates (default 3)
+
+=item B<-n>, B<--networks>
+
+output network information
+
+=item B<-x>, B<--vbds>
+
+output vbd block device data
+
+=item B<-r>, B<--repeat-header>
+
+repeat table header before each domain
+
+=item B<-v>, B<--vcpus>
+
+output VCPU data
+
+=item B<-f>, B<--full-name>
+
+output the full domain name (not truncated)
+
+=item B<-b>, B<--batch>
+
+output data in batch mode (to stdout)
+
+=item B<-i>, B<--iterations>=I<ITERATIONS>
+
+maximum number of iterations xentop should produce before ending
+
+=back
+
+=head1 INTERACTIVE COMMANDS
+
+All interactive commands are case-insensitive.
+
+=over 4
+
+=item B<D>
+
+set delay between updates
+
+=item B<N>
+
+toggle display of network information
+
+=item B<Q>, B<Esc>
+
+quit
+
+=item B<R>
+
+toggle table header before each domain
+
+=item B<S>
+
+cycle sort order
+
+=item B<V>
+
+toggle display of VCPU information
+
+=item B<Arrows>
+
+scroll domain display
+
+=back
+
+=head1 AUTHORS
+
+Written by Judy Fischbach, David Hendricks, and Josh Triplett
+
+=head1 REPORTING BUGS
+
+Report bugs to <xen-devel@lists.xen.org>.
+
+=head1 COPYRIGHT
+
+Copyright 2005 International Business Machines Corp
+
+This is free software; see the source for copying conditions. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
diff --git a/tools/xenstat/xentop/Makefile b/tools/xenstat/xentop/Makefile
index e67c9ab..1cc393f 100644
--- a/tools/xenstat/xentop/Makefile
+++ b/tools/xenstat/xentop/Makefile
@@ -30,11 +30,9 @@ LDFLAGS += $(APPEND_LDFLAGS)
all: xentop
.PHONY: install
-install: xentop xentop.1
+install: xentop
$(INSTALL_DIR) $(DESTDIR)$(sbindir)
$(INSTALL_PROG) xentop $(DESTDIR)$(sbindir)/xentop
- $(INSTALL_DIR) $(DESTDIR)$(MAN1DIR)
- $(INSTALL_DATA) xentop.1 $(DESTDIR)$(MAN1DIR)/xentop.1
endif
diff --git a/tools/xenstat/xentop/xentop.1 b/tools/xenstat/xentop/xentop.1
deleted file mode 100644
index 82c000e..0000000
--- a/tools/xenstat/xentop/xentop.1
+++ /dev/null
@@ -1,103 +0,0 @@
-.\" Copyright (C) International Business Machines Corp., 2005
-.\" Author: Josh Triplett <josh@kernel.org>
-.\"
-.\" This program is free software; you can redistribute it and/or modify
-.\" it under the terms of the GNU General Public License as published by
-.\" the Free Software Foundation; under version 2 of the License.
-.\"
-.\" This program is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program; If not, see <http://www.gnu.org/licenses/>.
-.TH xentop 1 "August 2005"
-.SH NAME
-\fBxentop\fR \- displays real-time information about a Xen system and domains
-
-.SH SYNOPSIS
-.B xentop
-[\fB\-h\fR]
-[\fB\-V\fR]
-[\fB\-d\fRSECONDS]
-[\fB\-n\fR]
-[\fB\-r\fR]
-[\fB\-v\fR]
-[\fB\-f\fR]
-[\fB\-b\fR]
-[\fB\-i\fRITERATIONS]
-
-.SH DESCRIPTION
-\fBxentop\fR displays information about the Xen system and domains, in a
-continually-updating manner. Command-line options and interactive commands
-can change the detail and format of the information displayed by \fBxentop\fR.
-
-.SH OPTIONS
-.TP
-\fB\-h\fR, \fB\-\-help\fR
-display help and exit
-.TP
-\fB\-V\fR, \fB\-\-version\fR
-output version information and exit
-.TP
-\fB\-d\fR, \fB\-\-delay\fR=\fISECONDS\fR
-seconds between updates (default 3)
-.TP
-\fB\-n\fR, \fB\-\-networks\fR
-output network information
-.TP
-\fB\-x\fR, \fB\-\-vbds\fR
-output vbd block device data
-.TP
-\fB\-r\fR, \fB\-\-repeat\-header\fR
-repeat table header before each domain
-.TP
-\fB\-v\fR, \fB\-\-vcpus\fR
-output VCPU data
-.TP
-\fB\-f\fR, \fB\-\-full\-name\fR
-output the full domain name (not truncated)
-.TP
-\fB\-b\fR, \fB\-\-batch\fR
-output data in batch mode (to stdout)
-.TP
-\fB\-i\fR, \fB\-\-iterations\fR=\fIITERATIONS\fR
-maximum number of iterations xentop should produce before ending
-
-
-.SH "INTERACTIVE COMMANDS"
-All interactive commands are case-insensitive.
-.TP
-.B D
-set delay between updates
-.TP
-.B N
-toggle display of network information
-.TP
-.B Q, Esc
-quit
-.TP
-.B R
-toggle table header before each domain
-.TP
-.B S
-cycle sort order
-.TP
-.B V
-toggle display of VCPU information
-.TP
-.B Arrows
-scroll domain display
-
-.SH AUTHORS
-Written by Judy Fischbach, David Hendricks, and Josh Triplett
-
-.SH "REPORTING BUGS"
-Report bugs to <xen-devel@lists.xen.org>.
-
-.SH COPYRIGHT
-Copyright \(co 2005 International Business Machines Corp
-.br
-This is free software; see the source for copying conditions. There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
--
1.7.10.4
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH for-4.6 3/5] docs: Move xentrace_format.1 to docs/man/xentrace_format.pod.1
2015-08-26 9:09 [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Andrew Cooper
2015-08-26 9:09 ` [PATCH for-4.6 1/5] docs: Move misc README's into docs/misc/ Andrew Cooper
2015-08-26 9:09 ` [PATCH for-4.6 2/5] docs: Move xentop.1 to docs/man/xentop.pod.1 Andrew Cooper
@ 2015-08-26 9:09 ` Andrew Cooper
2015-08-26 9:09 ` [PATCH for-4.6 4/5] docs: Support for generating man(8) pages Andrew Cooper
` (2 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Andrew Cooper @ 2015-08-26 9:09 UTC (permalink / raw)
To: Xen-devel; +Cc: Andrew Cooper, Ian Jackson, Ian Campbell, Wei Liu
And transform to POD to match our other manpages.
The content is identical (other than one correction), although the
layout differs slightly with certain indentation.
As a correction, remove the reference to xentrace_cpusplit(1) which was
removed in c/s 9b9ca98b6ab16, more than 10 years ago!
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
.../man/xentrace_format.pod.1 | 46 ++++++++++----------
tools/xentrace/Makefile | 3 --
2 files changed, 24 insertions(+), 25 deletions(-)
rename tools/xentrace/xentrace_format.1 => docs/man/xentrace_format.pod.1 (55%)
diff --git a/tools/xentrace/xentrace_format.1 b/docs/man/xentrace_format.pod.1
similarity index 55%
rename from tools/xentrace/xentrace_format.1
rename to docs/man/xentrace_format.pod.1
index 374ec6d..e05479a 100644
--- a/tools/xentrace/xentrace_format.1
+++ b/docs/man/xentrace_format.pod.1
@@ -1,20 +1,20 @@
-.TH XENTRACE_FORMAT 1 "11 May 2004" "Xen domain 0 utils"
-.SH NAME
-xentrace_format \- pretty-print Xen trace data
-.SH SYNOPSIS
-.B xentrace_format
-[
-.I DEFS-FILE
-]
-.SH DESCRIPTION
-.B xentrace_format
-parses trace data in \fBxentrace\fP binary format from standard input
-and reformats it according to the rules in a file of definitions
-(\fIDEFS-FILE\fP), printing to standard output.
-
-The rules in \fIDEFS-FILE\fP should have the format shown below:
-
-\fIevent_id\fP \fIwhitespace\fP \fIformat\fP
+=head1 NAME
+
+xentrace_format - pretty-print Xen trace data
+
+=head1 SYNOPSIS
+
+B<xentrace_format> [ I<DEFS-FILE> ]
+
+=head1 DESCRIPTION
+
+B<xentrace_format> parses trace data in B<xentrace> binary format from
+standard input and reformats it according to the rules in a file of
+definitions (I<DEFS-FILE>), printing to standard output.
+
+The rules in I<DEFS-FILE> should have the format shown below:
+
+I<event_id> I<whitespace> I<format>
Each rule should start on a new line.
@@ -34,11 +34,13 @@ in the file tools/xentrace/formats in the Xen source tree.
Depending on your system and the rate at which trace data is produced,
this script may not be able to keep up with the output of
-\fBxentrace\fP if it is piped directly. In these circumstances you
-should have \fBxentrace\fP output to a file for processing off-line.
+B<xentrace> if it is piped directly. In these circumstances you
+should have B<xentrace> output to a file for processing off-line.
+
+=head1 AUTHOR
-.SH AUTHOR
Mark A. Williamson <mark.a.williamson@intel.com>
-.SH "SEE ALSO"
-xentrace(8), xentrace_cpusplit(1)
+=head1 SEE ALSO
+
+xentrace(8)
diff --git a/tools/xentrace/Makefile b/tools/xentrace/Makefile
index 2f57bda..41caccb 100644
--- a/tools/xentrace/Makefile
+++ b/tools/xentrace/Makefile
@@ -11,7 +11,6 @@ BIN = $(BIN-y)
SBIN = xentrace xentrace_setsize
LIBBIN = xenctx
SCRIPTS = xentrace_format
-MAN1 = $(wildcard *.1)
MAN8 = $(wildcard *.8)
.PHONY: all
@@ -25,7 +24,6 @@ install: build
$(INSTALL_DIR) $(DESTDIR)$(bindir)
$(INSTALL_DIR) $(DESTDIR)$(sbindir)
[ -z "$(LIBBIN)" ] || $(INSTALL_DIR) $(DESTDIR)$(LIBEXEC_BIN)
- $(INSTALL_DIR) $(DESTDIR)$(MAN1DIR)
$(INSTALL_DIR) $(DESTDIR)$(MAN8DIR)
ifneq ($(BIN),)
$(INSTALL_PROG) $(BIN) $(DESTDIR)$(bindir)
@@ -33,7 +31,6 @@ endif
$(INSTALL_PROG) $(SBIN) $(DESTDIR)$(sbindir)
$(INSTALL_PYTHON_PROG) $(SCRIPTS) $(DESTDIR)$(bindir)
[ -z "$(LIBBIN)" ] || $(INSTALL_PROG) $(LIBBIN) $(DESTDIR)$(LIBEXEC_BIN)
- $(INSTALL_DATA) $(MAN1) $(DESTDIR)$(MAN1DIR)
$(INSTALL_DATA) $(MAN8) $(DESTDIR)$(MAN8DIR)
.PHONY: clean
--
1.7.10.4
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH for-4.6 4/5] docs: Support for generating man(8) pages
2015-08-26 9:09 [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Andrew Cooper
` (2 preceding siblings ...)
2015-08-26 9:09 ` [PATCH for-4.6 3/5] docs: Move xentrace_format.1 to docs/man/xentrace_format.pod.1 Andrew Cooper
@ 2015-08-26 9:09 ` Andrew Cooper
2015-08-26 9:09 ` [PATCH for-4.6 5/5] docs: Move xentrace.8 to docs/man/xentrace.pod.8 Andrew Cooper
2015-08-26 14:54 ` [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Wei Liu
5 siblings, 0 replies; 10+ messages in thread
From: Andrew Cooper @ 2015-08-26 9:09 UTC (permalink / raw)
To: Xen-devel; +Cc: Andrew Cooper, Ian Jackson, Ian Campbell, Wei Liu
The manpage rules are very repetative, because of the section number being
present in the filenames.
Instead of adding another set of 3 rules, switch to using a metarule to
automate the repetative action. New rules for different manpage sections can
be added simply by extending the $(foreach)
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
.gitignore | 1 +
docs/Makefile | 91 ++++++++++++++++++++++++++-------------------------------
2 files changed, 43 insertions(+), 49 deletions(-)
diff --git a/.gitignore b/.gitignore
index dafa3c4..9ead7c4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,6 +43,7 @@ dist/*
docs/html/
docs/man1/
docs/man5/
+docs/man8/
docs/pdf/
docs/txt/
extras/mini-os
diff --git a/docs/Makefile b/docs/Makefile
index ef3340c..3d77913 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -9,6 +9,7 @@ DOC_ARCHES := arm x86_32 x86_64
# Documentation sources to build
MAN1SRC-y := $(sort $(shell find man/ -name '*.pod.1' -print))
MAN5SRC-y := $(sort $(shell find man/ -name '*.pod.5' -print))
+MAN8SRC-y := $(sort $(shell find man/ -name '*.pod.8' -print))
MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
@@ -19,17 +20,20 @@ PANDOCSRC-y := $(sort $(shell find specs -name '*.pandoc' -print))
# Documentation targets
DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y))
+DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y))
DOC_HTML := $(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \
$(patsubst man/%.pod.1,html/man/%.1.html,$(MAN1SRC-y)) \
$(patsubst man/%.pod.5,html/man/%.5.html,$(MAN5SRC-y)) \
+ $(patsubst man/%.pod.8,html/man/%.8.html,$(MAN8SRC-y)) \
$(patsubst %.txt,html/%.txt,$(TXTSRC-y)) \
$(patsubst %,html/hypercall/%/index.html,$(DOC_ARCHES))
DOC_TXT := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
$(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \
$(patsubst man/%.pod.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
- $(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y))
+ $(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
+ $(patsubst man/%.pod.8,txt/man/%.8.txt,$(MAN8SRC-y))
DOC_PDF := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
@@ -55,7 +59,7 @@ else
endif
.PHONY: man-pages
-man-pages: $(DOC_MAN1) $(DOC_MAN5)
+man-pages: $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN8)
.PHONY: pdf
pdf: $(DOC_PDF)
@@ -75,6 +79,42 @@ distclean: clean
autom4te.cache
# Top level install targets
+
+# Metarules for generating manpages. Run with $(1) substitued for section
+define GENERATE_MANPAGE_RULES
+
+# Real manpages
+man$(1)/%.$(1): man/%.pod.$(1) Makefile
+ifneq ($(POD2MAN),)
+ @$(INSTALL_DIR) $$(@D)
+ $(POD2MAN) --release=$(VERSION) --name=$$* -s $(1) -c "Xen" $$< $$@
+else
+ @echo "pod2man not installed; skipping $$@"
+endif
+
+# HTML manpages
+html/man/%.$(1).html: man/%.pod.$(1) Makefile
+ifneq ($(POD2HTML),)
+ @$(INSTALL_DIR) $$(@D)
+ $(POD2HTML) --infile=$$< --outfile=$$@
+else
+ @echo "pod2html not installed; skipping $$@"
+endif
+
+# Text manpages
+txt/man/%.$(1).txt: man/%.pod.$(1) Makefile
+ifneq ($(POD2TEXT),)
+ @$(INSTALL_DIR) $$(@D)
+ $(POD2TEXT) $$< $$@
+else
+ @echo "pod2text not installed; skipping $$@"
+endif
+
+endef
+
+# Generate manpage rules for each section
+$(foreach i,1 5 8,$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
+
.PHONY: install-man-pages
install-man-pages: man-pages
$(INSTALL_DIR) $(DESTDIR)$(mandir)
@@ -90,22 +130,6 @@ install-html: html txt figs
install: install-man-pages install-html
# Individual file build targets
-man1/%.1: man/%.pod.1 Makefile
-ifneq ($(POD2MAN),)
- @$(INSTALL_DIR) $(@D)
- $(POD2MAN) --release=$(VERSION) --name=$* -s 1 -c "Xen" $< $@
-else
- @echo "pod2man not installed; skipping $@"
-endif
-
-man5/%.5: man/%.pod.5 Makefile
-ifneq ($(POD2MAN),)
- @$(INSTALL_DIR) $(@D)
- $(POD2MAN) --release=$(VERSION) --name=$* -s 5 -c "Xen" $< $@
-else
- @echo "pod2man not installed; skipping $@"
-endif
-
html/index.html: $(DOC_HTML) $(CURDIR)/gen-html-index INDEX
$(PERL) -w -- $(CURDIR)/gen-html-index -i INDEX html $(DOC_HTML)
@@ -121,21 +145,6 @@ html/%.txt: %.txt
@$(INSTALL_DIR) $(@D)
$(INSTALL_DATA) $< $@
-html/man/%.1.html: man/%.pod.1 Makefile
-ifneq ($(POD2HTML),)
- @$(INSTALL_DIR) $(@D)
- $(POD2HTML) --infile=$< --outfile=$@
-else
- @echo "pod2html not installed; skipping $@"
-endif
-
-html/man/%.5.html: man/%.pod.5 Makefile
-ifneq ($(POD2HTML),)
- @$(INSTALL_DIR) $(@D)
- $(POD2HTML) --infile=$< --outfile=$@
-else
- @echo "pod2html not installed; skipping $@"
-endif
# For non-x86 arches exclude the subarch whole x86 arch.
$(foreach i,$(filter-out x86_32 x86_64,$(DOC_ARCHES)),html/hypercall/$(i)/index.html): EXTRA_EXCLUDE := -X arch-x86
@@ -160,22 +169,6 @@ txt/%.txt: %.markdown
@$(INSTALL_DIR) $(@D)
$(INSTALL_DATA) $< $@
-txt/man/%.1.txt: man/%.pod.1 Makefile
-ifneq ($(POD2TEXT),)
- @$(INSTALL_DIR) $(@D)
- $(POD2TEXT) $< $@
-else
- @echo "pod2text not installed; skipping $@"
-endif
-
-txt/man/%.5.txt: man/%.pod.5 Makefile
-ifneq ($(POD2TEXT),)
- @$(INSTALL_DIR) $(@D)
- $(POD2TEXT) $< $@
-else
- @echo "pod2text not installed; skipping $@"
-endif
-
pdf/%.pdf: %.markdown
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $(@D)
--
1.7.10.4
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH for-4.6 5/5] docs: Move xentrace.8 to docs/man/xentrace.pod.8
2015-08-26 9:09 [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Andrew Cooper
` (3 preceding siblings ...)
2015-08-26 9:09 ` [PATCH for-4.6 4/5] docs: Support for generating man(8) pages Andrew Cooper
@ 2015-08-26 9:09 ` Andrew Cooper
2015-08-26 14:54 ` [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Wei Liu
5 siblings, 0 replies; 10+ messages in thread
From: Andrew Cooper @ 2015-08-26 9:09 UTC (permalink / raw)
To: Xen-devel; +Cc: Andrew Cooper, Ian Jackson, Ian Campbell, Wei Liu
And transform to POD to match our other manpages.
The content is identical, although the formatting was altered slightly
to conform to more usual manpage layout.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
.../xentrace/xentrace.8 => docs/man/xentrace.pod.8 | 160 ++++++++++----------
tools/xentrace/Makefile | 3 -
2 files changed, 81 insertions(+), 82 deletions(-)
rename tools/xentrace/xentrace.8 => docs/man/xentrace.pod.8 (63%)
diff --git a/tools/xentrace/xentrace.8 b/docs/man/xentrace.pod.8
similarity index 63%
rename from tools/xentrace/xentrace.8
rename to docs/man/xentrace.pod.8
index 7b3172b..69aef05 100644
--- a/tools/xentrace/xentrace.8
+++ b/docs/man/xentrace.pod.8
@@ -1,92 +1,93 @@
-.TH XENTRACE 8 "22 February 2007" "Xen domain 0 utils"
-.SH NAME
-xentrace \- capture Xen trace buffer data
-.SH SYNOPSIS
-.B xentrace
-[
-.I OPTIONS
-] [
-.I FILE
-]
-.SH DESCRIPTION
-.B xentrace
-is used to capture trace buffer data from Xen. The data is
+=head1 NAME
+
+xentrace - capture Xen trace buffer data
+
+=head1 SYNOPSIS
+
+B<xentrace> [ I<OPTIONS> ] [ I<FILE> ]
+
+=head1 DESCRIPTION
+
+B<xentrace> is used to capture trace buffer data from Xen. The data is
output in the following binary format (host endian):
-.PP
+
CPU(uint) TSC(u64) EVENT(u32) D1 D2 D3 D4 D5 (all u32)
-.PP
+
Where CPU is the processor number, TSC is the record's timestamp
(the value of the CPU cycle counter), EVENT is the event ID and
D1...D5 are the trace data.
Data is dumped onto the standard output (which must not be a TTY) or a
-\fIFILE\fP specified on the command line.
+I<FILE> specified on the command line.
The output should be parsed using the tool xentrace_format, which can
produce human-readable output in ASCII format.
-.SS Options
-.TP
-.B -t, --log-thresh=l
-set the threshold number, l, of new records required to trigger a write of
+=head1 OPTIONS
+
+=over 4
+
+=item B<-t> I<l>, B<--log-thresh>=I<l>
+
+set the threshold number, I<l>, of new records required to trigger a write of
all new records to the output
-.TP
-.B -s, --poll-sleep=p
-set the time, p, (in milliseconds) to sleep between polling the buffers
+
+=item B<-s> I<p>, B<--poll-sleep>=I<p>
+
+set the time, I<p>, (in milliseconds) to sleep between polling the buffers
for new data.
-.TP
-.B -c, --cpu-mask=[\fIc\fP|\fICPU-LIST\fP|\fIall\fP]
+
+=item B<-c> [I<c>|I<CPU-LIST>|I<all>], B<--cpu-mask>=[I<c>|I<CPU-LIST>|I<all>]
+
This can be: a hex value (of the form 0xNNNN...), or a set of cpu
-ranges as described below, or the string \fIall\fP. Hex values are limited
+ranges as described below, or the string I<all>. Hex values are limited
to 32 bits. If not specified, the cpu-mask as set during bootup will be
-constructed. If using the \fICPU-LIST\fP it expects decimal numbers, which
+constructed. If using the I<CPU-LIST> it expects decimal numbers, which
may be specified as follows:
-.RS 4
-.ie n .IP """0-3""" 4
-.el .IP "``0-3''" 4
-.IX Item "0-3"
-Trace only on CPUs 0 through 3
-.ie n .IP """0,2,5-7""" 4
-.el .IP "``0,2,5-7''" 4
-.IX Item "0,2,5-7"
-Trace only on CPUs 0, 2, and 5 through 7.
-.ie n .IP """-3""" 4
-.el .IP "``-3''" 4
-.IX Item "-3"
-Trace only on CPUs 0 through 3
-.ie n .IP """-3,7""" 4
-.el .IP "``-3,7''" 4
-.IX Item "-3,7"
-Trace only on CPUs 0 through 3 and 7
-.ie n .IP """3-""" 4
-.el .IP "``3-''" 4
-.IX Item "-3-"
-Trace only on CPUs 3 up to maximum numbers of CPUs the host has.
-.RE
-.Sp
-
-If using \fIall\fP it will use all of the CPUs the host has.
-.TP
-.B -e, --evt-mask=e
+ "0-3"
+ Trace only on CPUs 0 through 3
+
+ "0,2,5-7"
+ Trace only on CPUs 0, 2, and 5 through 7
+
+ "-3"
+ Trace only on CPUs 0 through 3
+
+ "-3,7"
+ Trace only on CPUs 0 through 3 and 7
+
+ "3-"
+ Trace only on CPUs 3 up to maximum numbers of CPUs the host has
+
+If using I<all> it will use all of the CPUs the host has.
+
+=item B<-e> I<mask>, B<--evt-mask>=I<mask>
+
set event capture mask. If not specified the TRC_ALL will be used.
-.TP
-.B -?, --help
+
+=item B<-?>, B<--help>
+
Give this help list
-.TP
-.B --usage
+
+=item B<--usage>
+
Give a short usage message
-.TP
-.B -V, --version
+
+=item B<-V>, B<--version>
+
Print program version
-.SS Event Classes (Masks)
+=back
+
+=head2 Event Classes (Masks)
+
The following event classes (masks) can be used to filter the events being
gathered by xentrace:
-.PP
- \fIID\fP \fIDescription\fP
-.PP
+
+ ID Description
+
0x0001f000 TRC_GEN
0x0002f000 TRC_SCHED
0x0004f000 TRC_DOM0OP
@@ -95,22 +96,23 @@ gathered by xentrace:
0xfffff000 TRC_ALL
-.SS Event Subclasses (More Masks)
+=head2 Event Subclasses (More Masks)
+
The following event subclasses (masks) can also be used to filter the events being
gathered by xentrace:
-.PP
- \fIID\fP \fIDescription\fP
-.PP
+
+ ID Description
+
0x00081000 TRC_HVM_ENTRYEXIT
0x00082000 TRC_HVM_HANDLER
-.SS Events
-.B xentrace
-collects the following events from the trace buffer:
-.PP
- \fIID\fP \fIDescription\fP
-.PP
+=head2 Events
+
+B<xentrace> collects the following events from the trace buffer:
+
+ ID Description
+
0x0001f001 TRC_LOST_RECORDS
0x0002f001 TRC_SCHED_DOM_ADD
0x0002f002 TRC_SCHED_DOM_REM
@@ -145,8 +147,8 @@ collects the following events from the trace buffer:
0x0008200D TRC_HVM_MSR_WRITE
0x0008200E TRC_HVM_CPUID
0x0008200F TRC_HVM_INTR
- 0x00082010 TRC_HVM_NMI
- 0x00082011 TRC_HVM_SMI
+ 0x00082010 TRC_HVM_NMI
+ 0x00082011 TRC_HVM_SMI
0x00082012 TRC_HVM_VMMCALL
0x00082013 TRC_HVM_HLT
0x00082014 TRC_HVM_INVLPG
@@ -155,10 +157,10 @@ collects the following events from the trace buffer:
0x0010f002 TRC_MEM_PAGE_GRANT_UNMAP
0x0010f003 TRC_MEM_PAGE_GRANT_TRANSFER
-.PP
+=head1 AUTHOR
-.SH AUTHOR
Mark A. Williamson <mark.a.williamson@intel.com>
-.SH "SEE ALSO"
+=head1 SEE ALSO
+
xentrace_format(1)
diff --git a/tools/xentrace/Makefile b/tools/xentrace/Makefile
index 41caccb..6c13cd1 100644
--- a/tools/xentrace/Makefile
+++ b/tools/xentrace/Makefile
@@ -11,7 +11,6 @@ BIN = $(BIN-y)
SBIN = xentrace xentrace_setsize
LIBBIN = xenctx
SCRIPTS = xentrace_format
-MAN8 = $(wildcard *.8)
.PHONY: all
all: build
@@ -24,14 +23,12 @@ install: build
$(INSTALL_DIR) $(DESTDIR)$(bindir)
$(INSTALL_DIR) $(DESTDIR)$(sbindir)
[ -z "$(LIBBIN)" ] || $(INSTALL_DIR) $(DESTDIR)$(LIBEXEC_BIN)
- $(INSTALL_DIR) $(DESTDIR)$(MAN8DIR)
ifneq ($(BIN),)
$(INSTALL_PROG) $(BIN) $(DESTDIR)$(bindir)
endif
$(INSTALL_PROG) $(SBIN) $(DESTDIR)$(sbindir)
$(INSTALL_PYTHON_PROG) $(SCRIPTS) $(DESTDIR)$(bindir)
[ -z "$(LIBBIN)" ] || $(INSTALL_PROG) $(LIBBIN) $(DESTDIR)$(LIBEXEC_BIN)
- $(INSTALL_DATA) $(MAN8) $(DESTDIR)$(MAN8DIR)
.PHONY: clean
clean:
--
1.7.10.4
^ permalink raw reply related [flat|nested] 10+ messages in thread* Re: [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree
2015-08-26 9:09 [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Andrew Cooper
` (4 preceding siblings ...)
2015-08-26 9:09 ` [PATCH for-4.6 5/5] docs: Move xentrace.8 to docs/man/xentrace.pod.8 Andrew Cooper
@ 2015-08-26 14:54 ` Wei Liu
2015-08-27 18:15 ` Ian Jackson
5 siblings, 1 reply; 10+ messages in thread
From: Wei Liu @ 2015-08-26 14:54 UTC (permalink / raw)
To: Andrew Cooper; +Cc: Wei Liu, Russ Pavlicek, Xen-devel
On Wed, Aug 26, 2015 at 10:09:46AM +0100, Andrew Cooper wrote:
> After this series, I don't believe there are any docs remaining out of
> the docs/ subtree.
>
> The three manpages moved have been converted from ?roff to POD to match
> all our other manpages
>
> Andrew Cooper (5):
> docs: Move misc README's into docs/misc/
> docs: Move xentop.1 to docs/man/xentop.pod.1
> docs: Move xentrace_format.1 to docs/man/xentrace_format.pod.1
> docs: Support for generating man(8) pages
> docs: Move xentrace.8 to docs/man/xentrace.pod.8
>
Whole series:
Acked-by: Wei Liu <wei.liu2@citrix.com>
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree
2015-08-26 14:54 ` [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree Wei Liu
@ 2015-08-27 18:15 ` Ian Jackson
2015-08-27 19:13 ` [DOCSDAY PATCH for-4.6] docs: Fix installation of man8 pages Andrew Cooper
0 siblings, 1 reply; 10+ messages in thread
From: Ian Jackson @ 2015-08-27 18:15 UTC (permalink / raw)
To: Wei Liu; +Cc: Andrew Cooper, Russ Pavlicek, Xen-devel
Wei Liu writes ("Re: [Xen-devel] [DOCS DAY] [PATCH for-4.6 0/5] Cleanup of docs spread throughout the tree"):
> On Wed, Aug 26, 2015 at 10:09:46AM +0100, Andrew Cooper wrote:
> Whole series:
>
> Acked-by: Wei Liu <wei.liu2@citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
Thanks,
Ian.
^ permalink raw reply [flat|nested] 10+ messages in thread* [DOCSDAY PATCH for-4.6] docs: Fix installation of man8 pages
2015-08-27 18:15 ` Ian Jackson
@ 2015-08-27 19:13 ` Andrew Cooper
2015-08-28 9:50 ` Ian Jackson
0 siblings, 1 reply; 10+ messages in thread
From: Andrew Cooper @ 2015-08-27 19:13 UTC (permalink / raw)
To: Xen-devel; +Cc: Andrew Cooper, Ian Jackson, Ian Campbell, Wei Liu
c/s a430436 "docs: Support for generating man(8) pages" accidentally
failed to update to the install and clean rules for man8 pages, meaning
that c/s 7b21214 "docs: Move xentrace.8 to docs/man/xentrace.pod.8"
caused a packaging regression when it came to xentop.8
To avoid similar bugs in the future, move the generation of the build,
install and clean rules into the manpage metarule.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
CC: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Wei Liu <wei.liu2@citrix.com>
---
docs/Makefile | 35 +++++++++++++++++++++++------------
1 file changed, 23 insertions(+), 12 deletions(-)
diff --git a/docs/Makefile b/docs/Makefile
index 3d77913..d25e6c7 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -58,20 +58,15 @@ else
@echo "fig2dev (transfig) not installed; skipping figs."
endif
-.PHONY: man-pages
-man-pages: $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN8)
-
.PHONY: pdf
pdf: $(DOC_PDF)
.PHONY: clean
-clean:
+clean: clean-man-pages
$(MAKE) -C figs clean
rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~
rm -rf *.ilg *.log *.ind *.toc *.bak *.tmp core
rm -rf html txt pdf
- rm -rf man5
- rm -rf man1
.PHONY: distclean
distclean: clean
@@ -80,6 +75,8 @@ distclean: clean
# Top level install targets
+.PHONY: man-pages install-man-pages clean-man-pages
+
# Metarules for generating manpages. Run with $(1) substitued for section
define GENERATE_MANPAGE_RULES
@@ -110,17 +107,31 @@ else
@echo "pod2text not installed; skipping $$@"
endif
+# Build
+.PHONY: man$(1)-pages
+man$(1)-pages: $$(DOC_MAN$(1))
+
+# Install
+.PHONY: install-man$(1)-pages
+install-man$(1)-pages: man$(1)-pages
+ $(INSTALL_DIR) $(DESTDIR)$(mandir)
+ cp -r man$(1) $(DESTDIR)$(mandir)
+
+# Clean
+.PHONY: clean-man$(1)-pages
+clean-man$(1)-pages:
+ rm -rf man$(1)
+
+# Link buld/install/clean to toplevel rules
+man-pages: man$(1)-pages
+install-man-pages: install-man$(1)-pages
+clean-man-pages: clean-man$(1)-pages
+
endef
# Generate manpage rules for each section
$(foreach i,1 5 8,$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
-.PHONY: install-man-pages
-install-man-pages: man-pages
- $(INSTALL_DIR) $(DESTDIR)$(mandir)
- cp -R man1 $(DESTDIR)$(mandir)
- cp -R man5 $(DESTDIR)$(mandir)
-
.PHONY: install-html
install-html: html txt figs
$(INSTALL_DIR) $(DESTDIR)$(docdir)
--
1.7.10.4
^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [DOCSDAY PATCH for-4.6] docs: Fix installation of man8 pages
2015-08-27 19:13 ` [DOCSDAY PATCH for-4.6] docs: Fix installation of man8 pages Andrew Cooper
@ 2015-08-28 9:50 ` Ian Jackson
0 siblings, 0 replies; 10+ messages in thread
From: Ian Jackson @ 2015-08-28 9:50 UTC (permalink / raw)
To: Andrew Cooper; +Cc: Wei Liu, Ian Campbell, Xen-devel
Andrew Cooper writes ("[DOCSDAY PATCH for-4.6] docs: Fix installation of man8 pages"):
> c/s a430436 "docs: Support for generating man(8) pages" accidentally
> failed to update to the install and clean rules for man8 pages, meaning
> that c/s 7b21214 "docs: Move xentrace.8 to docs/man/xentrace.pod.8"
> caused a packaging regression when it came to xentop.8
>
> To avoid similar bugs in the future, move the generation of the build,
> install and clean rules into the manpage metarule.
>
> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
(Wei gave his release-ack on irc)
^ permalink raw reply [flat|nested] 10+ messages in thread