Some of the docs/misc documents will need to go in man 7 section,
prepare docs/Makefile for it.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
Some of the docs/misc documents are written in markdown language.
As an effort to cleanup man pages these documents will be converted into
man pages. To avoid some more conversion, add rules to the docs/Makefile
to generate man pages out of markdown files as well as pod ones.
However, pandoc doesn't know how to convert man pages links. Thus the
man links in markdown pages won't work.
Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
Multi-target non-pattern rules and Multi-target pattern rules behave rather
differently. From `Pattern Intro':
Pattern rules may have more than one target. Unlike normal rules, this does
not act as many different rules with the same prerequisites and commands.
If a pattern rule has multiple targets, `make' knows that the rule's
commands are responsible for making all of the targets. The commands are
executed only once to make all the targets.
The intended use of the multi-target pattern rules was to avoid repeating the
identical recipe multiple times. The issue can be demonstrated with the
generation of documentation from pandoc source.
./xen.git$ touch docs/features/template.pandoc
./xen.git$ make -C docs/
# Regenerates html/features/template.html
./xen.git$ make -C docs/
# Regenerates txt/features/template.txt
./xen.git$ make -C docs/
# Regenerates pdf/features/template.pdf
To work around this, there need to be three distinct rules, so the execution
of one recipe doesn't short ciruit the others. To avoid copy&paste
duplication, introduce a metarule, and evalute it for each document target.
As $(PANDOC) is used to generate documentation from different source types,
the metarule can be extended to also encompas the rule to create pdfs from
markdown.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Release-acked-by: Wei Liu <wei.liu2@citrix.com>
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>
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>
Acked-by: Wei Liu <wei.liu2@citrix.com>
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>
Acked-by: Wei Liu <wei.liu2@citrix.com>
A find option was forgotten in commit 6592bf60be
"docs: Look for documentation in sub-directories" resulting to get some
docs duplicated and other missing.
Signed-off-by: Julien Grall <julien.grall@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
The ARM documentation is living in a specific folder under misc. Until
now, it was skipped during building.
In order to avoid missing future directory, use find to look for a
specific file pattern through all the directory.
Note the we already use find in other Makefile.
Signed-off-by: Julien Grall <julien.grall@citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
For top-level targets which use more than a single program to produce content
(txt already, pdf once pandoc is supported), these current checks are
unsuitable.
By moving the the install checks to the rules which actually use the programs,
it is now possible to build a subset of a top-level target depending on the
installed programs.
As a bonus, it removes the need to recurse for txt, man-pages and pdf targets.
A side effect of this is that every individual source which cannot be
generated will have a specific message logged, giving the file and program.
As such, these message are updated to consistently report the target file
which was not generated.
Finally, update "ifdef foo" to "ifneq($(foo),)" to be more resilient to errors
caused by having foo defined as an empty string.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
Otherwise an incremental build will fail to overwrite the destination
files.
Signed-off-by: Jan Beulich <jbeulich@suse.com>
Reviewed-by: Andrew Cooper <andrew.cooper3@citrix.com>
These were added by 7dbfc2f8b0 "docs: Honour --{en, dis}able-xend when
building docs" between v1 and the (eventually committed) v2 of 9e8672f1c3
"tools: remove xend and associated python modules" and were missed when
rebasing for v2.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Tested-by: Olaf Hering <olaf@aepfle.de>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Split the current install target into two subtargets, install-man-pages and
install-html, with the main install target depending on both.
This helps packagers who want the man pages to put in appropriate rpms/debs,
but don't want to build the html developer docs.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
If a user has specified --disable-xend, they wont want the manpages either.
Propagating this parameters requires reorganising the way in which the
makefile chooses which documents to build.
There is now a split of {MAN1,MAN5,MARKDOWN,TXT}SRC-y to select which
documentation to build, which is separate from the patsubst section which
generates appropriate paths to trigger the later rules.
The manpages are quite easy to split between xend, xl and xenstore, and have
been. Items from misc/ are much harder and been left.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Campbell <Ian.Campbell@citrix.com>
CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
[ ijc -- reran autogen.sh as requested. ]
This was broken by 118104e5eaf2 "docs: Build docs for ARM as well as x86_64".
Move docs to hypercall/ARCH instead of hypercall-ARCH.
Support mulitple levels of subdirectories in gen-html-index tool.
This removes the need for a symlink hypercall->hypercall-x86_64 since there is
now a proper index at hypercall/index.html.
Update INDEX to human readable names for the architecture specific hypercalls.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Also do x86_32 (which is still relevant since it is "compat mode").
Install as hypercall-$ARCH but keep the hypercall path around as a symlink to
the x86_64 version so links (e.g. to http://xenbits.xen.org/docs/ keep working.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
doc: buildsystem fixes
- use correct pathes (make gmake dist-docs from toplevel directory work)
- configure detects perl as tools/configure does
Signed-off-by: Christoph Egger <chegger@amazon.de>
Reviewed-by: Matthew Wilson <msw@amazon.de>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
[ ijc -- reran autogen.sh ]
cp -d is a GNU extension, and only useful for links, which don't seem
to exist in the directories being copied, so just remove said flag.
Signed-off-by: Patrick Welche <prlw1@cam.ac.uk>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
It is sometimes hard to discover all the optional tools that should be
on a system to build all available Xen documentation. By checking for
documentation generation tools at ./configure time and displaying a
warning, Xen packagers will more easily learn about new optional build
dependencies, like markdown, when they are introduced.
Based on a patch by Matt Wilson. Changed to use a separate
docs/configure which is called from the top-level in the same manner
as stubdoms.
Rerun autogen.sh and "git add docs/configure" after applying this patch.
Signed-off-by: Matt Wilson <msw@amazon.com>
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Matt Wilson <msw@amazon.com>
(For the change to introduce docs/configure)
Acked-by: Roger Pau Monné <roger.pau@citrix.com>
Committed-by: Ian Campbell <ian.campbell@citrix.com>
In the 300+ page PDF this produces I couldn't see anything which
wasn't the autogenerated doxygen boilerplate stuff.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Roger Pau Monné <roger.pau@citrix.com>
Committed-by: Ian Campbell <ian.campbell@citrix.com>
This document is about an old unmaintained version of the XenAPI,
which bears little to no relation to what is implemented in xapi and
which is only partially implemented in xend (which is deprecated). The
doc hasn't seen much in the way of updates since 2009.
Anyone who is actually interested can continue to use the version
which was in 4.2.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Roger Pau Monné <roger.pau@citrix.com>
Committed-by: Ian Campbell <ian.campbell@citrix.com>
We gate the whole of the "txt" target on pod2text. I think this is
better than gating only the pod-generated outputs; it avoids a partial
output tree.
Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Campbell <ian.campbell@citrix.com>
Add annotations for a couple of the hypercalls:
HYPERVISOR_set_trap_table
HYPERVISOR_mmu_update
We do this by
* annotating the list of #defines for hypercall numbers
* annotating the list of error values
* providing a function prototype for the systematically-named functions
The header generator does the rest.
This exercise revealed a couple of infelicities:
* In the actual source code, do_mmu_update is defined to return an int
and do_set_trap_table a long. However both functions return either
-Efoo (on error) or 0 for success.
* The error numbers are defined only in the private header file
xen/include/xen/errno.h and then only with names which will
typically clash with other projects. It would be nice to include a
public version of this header which defines XEN_E*. But for now
we run xen-headers on errno.h too.
Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
"xen-headers" generates HTML from header files. So far this generates
just some type cross-references, if you say
make -C docs html/hypercall/stamp
An index page, proper wiring into the build system, and a few more
annotations in the headers, and will be forthcoming.
Signed-off-by: Ian Jackson <ian.jackson@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
A browser will display them just fine.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Jackson <ian.jackson.citrix.com>
Acked-by: Ian Jackson <ian.jackson.citrix.com>
Taking over the top level "user" entry with a relatively obsolete document is a
bit of an annoyance but these docs are not so out of date that they should be
deleted. Move them out of the top-level instead.
(the original motivation here was to allow for user/xl-domain-cfg.markdown but
we have since decided to go with man/xl.cfg.pod.5 instead so perhaps this is a
waste of time)
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Jackson <ian.jackson.citrix.com>
Acked-by: Ian Jackson <ian.jackson.citrix.com>
nb: I'm not a Perl wizard...
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Jackson <ian.jackson.citrix.com>
Acked-by: Ian Jackson <ian.jackson.citrix.com>
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Jackson <ian.jackson.citrix.com>
Acked-by: Ian Jackson <ian.jackson.citrix.com>
Previously only some targets did this. An alternative would be to make a hard
dependency on these tools, this might make more sense especially for markdown?
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
Including markdown docs.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Ian Jackson <ian.jackson.citrix.com>
Committed-by: Ian Jackson <ian.jackson.citrix.com>
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Ian Jackson <ian.jackson.citrix.com>
Committed-by: Ian Jackson <ian.jackson.citrix.com>
Otherwise make can search the path relative to certain standard paths
such as /usr/include (e.g., the line '-include $(XEN_ROOT)/.config' in
Config.mk suffers from this).
Signed-off-by: Keir Fraser <keir@xen.org>
Cédric Bosdonnat
Andrew Cooper
Julien Grall
Olaf Hering
Jan Beulich
Ian Campbell
Christoph Egger
Daniel Kiper
Patrick Welche
Ian Jackson
Keir Fraser