It isn't really part of the documentation. Furthermore, entries there
are in not determined order, which breaks build reproducibility.
Signed-off-by: Marek Marczykowski-Górecki <marmarek@invisiblethingslab.com>
Acked-by: Andrew Cooper <andrew.cooper3@citrix.com>
Don't use "set -x" for the figs rule. It doesn't take effect in the recursive
make environment.
Turn the HTML manpage comments into makefile comments, not shell comments.
This saves 3x shell invocations per manpage.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Jan Beulich <jbeulich@suse.com>
Release-acked-by: Paul Durrant <paul@xen.org>
This fixes the fact that qemu-deprivilege.md, non-cooperative-migration.md and
xenstore-migration.md don't currently get rendered at all, and are therefore
missing from xenbits.xen.org/docs
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Reviewed-by: Paul Durrant <paul@xen.org>
Reviewed-by: Ian Jackson <ian.jackson@eu.citrix.com>
Backport: 4.12
Sphinx uses ReStructuredText as its markup format. Although missing the
project wide integration, individual *.rst files can be rendered by pandoc to
suppliement our existing ad-hoc documentation.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
Sphinx is a documentation system, which is popular for technical writing. It
uses ReStructuredText as its markup syntax, and is designed for whole-project
documentation, rather than the misc assortment of individual files that we
currently have.
This is a skeleton setup which just enough infrastructure to render an empty
set of pages. It will become better integrated into Xen's docs system when it
becomes less WIP.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
Second try, this time also works for all links to xen-vbd-interface(7).
We don't try anymore to have pod2html generate relative links, instead
we do it ourself.
First, we modify all links to man pages to have what looks like an
absolute URL and pod2html will just write it in the html output.
Absolute URL in POD are in the form L<text|scheme:...> so let's just use
a scheme that isn't real, but easy to find in the resulting html output:
"relative:".
Then we fix the output and remove all the bogus scheme "relative" and
can end up with nice relative links.
Signed-off-by: Anthony PERARD <anthony.perard@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
Currently, all links to other man pages are sent to
http://man.he.net/man$mansection/$manpage, but that site doesn't have
Xen man pages, so all links to other Xen man pages are broken.
In order to fix that, this is going to be a bit complex.
First, we need to teach pod2html on where other .pod files can be found,
otherwise it isn't going make any links to our pages. This is done with
--podpath.
Second, pod2html doesn't actually understand our format
"$manpage.$mansection.pod". But instead of teaching it (which is
probably impossible) we are going to modify our .pod files in order to
tell pod2html which file to look for. This is done with the sed command
by transforming for example: "L<xl.conf(5)>" to "L<xl.conf(5)|xl.conf.5>".
Last but not least, in order to have relative links to the other
generated man page, we are going against the rules, we are going to use
"--htmlroot=." so that pod2html doesn't prepand "/" to all "relative"
links. We are also going to `cd` into the "man" dir and set podpath to
"." so that pod2html is going to generate relative links to other pod
file in the form "./$man" insteadof "man/$man" or "../$man" with other
compination of options. The result of --podpath + --podroot can be check
in pod2html's cache file "pod2html.tmp".
All of this is going to generate links in the form "./$html_manpage".
But all of this doesn't work for xen-vbd-interface(7), because it's not
a pod file... maybe we could generate pod2html's cache (pod2html.tmp)
file to add en entry.
Signed-off-by: Anthony PERARD <anthony.perard@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
Now that all use of markdown as been replaced with pandoc, drop it from
configure.ac and from the docs/ Makefile.
Instead of just deleting the markdown reference from README, adjust the line
to mention the other optional packages required for documentation.
Drop markdown from travis, but leave it in the docker containers as they get
used for stable branches as well.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
The original intent of this patch was to rename xen-vbd-interface.markdown.7
to xen-vbd-interface.pandoc.7 to remove the final markdown file from the docs/
tree.
The DOC_MANx lists are broken. They contain MANxSRC-y twice, the first half
with a partial %.pod substituation, and the second half with a partial
%.markdown substitution. This is also the root cause behind the filtering
activity in the uninstall-man$(i)-pages rule.
Furthermore, the logic for generating the manpage targets is unnecesserily
repetative, owing to the layout of source files in the man/ directory.
Therefore, tackle the problem by renaming all of our manpage source files from
"$FORMAT.$SECTION" to "$SECTION.$FORMAT". For the two xl.cfg.5 and xl.1 which
are preprocessed by autoconf to contain path information, this requires
updating configure.ac and .gitignore. The markdown to pandoc conversion is
performed as well, as it is also a straight rename.
An ancillary benefit of this renaming is that text editors stand a chance of
being able to work out the correct mode to use.
As for the makefile:
1) Break the MAN_SECTIONS list out of the GENERATE_MANPAGE_RULES loop, as we
are going to use it a second time.
2) Do away with the individaul MANxSRC-y variables. Use a single list,
derived from all *.pod and *.pandoc files, with their format suffixes
removed.
3) Use a $(foreach ...) to generate the DOC_MANx lists, filling them with the
correct content.
4) The DOC_HTML and DOC_TXT can now include all manpages with a single
substitution, as they don't need to separate the manpages by
section-numbered-directory.
5) Fix up the filenames in the manpage metarule to match the renaming.
No functional change.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
c/s a3a99df44 "docs/cmdline: Rewrite the cpuid_mask_* section" completely
forgot about how markdown gets rendered to HTML (as opposed to PDF), because
we use different translators depending on the destination format.
markdown and pandoc are very similar markup languages, but a couple of details
about pandoc cause it to have far more user-friendly inline markup.
Switch all markdown documents to be pandoc (so we are using a single
translator, and therefore a single flavour of markdown), which fixes the
rendered docs on xenbits.xen.org/docs.
While changing the format, fix the remainder of the escaped underscores in the
same mannor as the previous patch. The two problem cases here are __LINE__
and __FILE__ where the first underscore still needs escaping.
In addition, dmop.markdown and dom0less.markdown didn't used to get processed,
as only .markdown files in the misc/ directory got considered.
dom0less.pandoc gets picked up automatically now, due to being in the
features/ directory, but designs/ needs adding to the pandoc directory list
for dmop.pandoc to get processed.
While edting in appropriate areas, take the opportunity to fix some markup to
the surrounding style, and drop trailing whitespace.
No change in content - only formatting. This results in the text being easier
to read and grep.
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
The regexp used with find in order to list the man pages doesn't work
with FreeBSD find, so use a wildcard instead. No functional change.
Signed-off-by: Roger Pau Monné <roger.pau@citrix.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
We are going to want to format SUPPORT.md which does not match the
filename patterns in docs/. So provide a way to make an ad-hoc rule
using pandoc with the standard options.
No functional change in this patch.
Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Release-acked-by: Juergen Gross <jgross@suse.com>
Acked-by: Lars Kurth <lars.kurth@citrix.com>
Running "make uninstall" does not remove all installed files, a
situation which might cause link related issues if xen is re-installed
in a different location.
In order to make uninstall correctly remove the files it is best
the process should be done recursively by mirroring each "install"
target with an "uninstall" who removes the installed files.
An exception to this rule is uninstalling the files produced by
"qemu-xen-dir-remote" and "qemu-xen-traditional-dir", which are external
to the project. These projects do not implement an "uninstall" target so
the files have to be removed manually.
Signed-off-by: Petre Pircalabu <ppircalabu@bitdefender.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>
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>
Marek Marczykowski-Górecki