[libvirt] [PATCH 0/3] Minor docs fixes
Here are some fixes I was still having in my local branch. I finally found a way to generate search.php automatically (even though it is not the way I wanted it) and since the others are fixing docs as well, I'm sending them in a series. Last patch of the series is more like a question if we can change it or not. Martin Kletzander (3): docs: fix 404 page when fetched from different location docs: autogenerate search.php docs/virsh: various minor fixes .gitignore | 1 + docs/404.html.in | 2 +- docs/Makefile.am | 24 +++++++- docs/api_extension.html.in | 4 -- docs/pending.html.in | 4 -- docs/{search.php => search.php.code.in} | 90 ++----------------------------- docs/search.php.in | 17 ++++++ docs/site.xsl | 11 ++++- tools/virsh-host.c | 4 +- 9 files changed, 57 insertions(+), 100 deletions(-) rename docs/{search.php => search.php.code.in} (66%) create mode 100644 docs/search.php.in -- 1.7.8.6
Error 404 page had relative paths specified for both the image and stylesheets which caused a problem when requested URL included a subfolder (e.g. http://libvirt.org/asdf/asdf ). This patch corrects this behaviour by modifying href_base to '/' and changing the src of the image. --- docs/404.html.in | 2 +- docs/site.xsl | 11 ++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/docs/404.html.in b/docs/404.html.in index 9363871..202cdb8 100644 --- a/docs/404.html.in +++ b/docs/404.html.in @@ -15,7 +15,7 @@ </ul> <p class="image"> - <img src="libvirtLogo404.png" alt="libvirt Logo"/> + <img src="{$href_base}libvirtLogo404.png" alt="libvirt Logo"/> </p> diff --git a/docs/site.xsl b/docs/site.xsl index a6801e6..a65c10d 100644 --- a/docs/site.xsl +++ b/docs/site.xsl @@ -14,7 +14,16 @@ doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"/> - <xsl:variable name="href_base" select="''"/> + <xsl:variable name="href_base"> + <xsl:choose> + <xsl:when test="$pagename = '404.html'"> + <xsl:value-of select="'/'"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="''"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable> <xsl:template match="/"> <xsl:apply-templates select="." mode="page"> -- 1.7.8.6
On 08/09/2012 08:17 AM, Martin Kletzander wrote:
Error 404 page had relative paths specified for both the image and stylesheets which caused a problem when requested URL included a subfolder (e.g. http://libvirt.org/asdf/asdf ). This patch corrects this behaviour by modifying href_base to '/' and changing the src of the image. --- docs/404.html.in | 2 +- docs/site.xsl | 11 ++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-)
I'm no xsl expert, but
- <xsl:variable name="href_base" select="''"/> + <xsl:variable name="href_base"> + <xsl:choose> + <xsl:when test="$pagename = '404.html'"> + <xsl:value-of select="'/'"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="''"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable>
this reads pretty straightforward, so I'm okay giving: ACK. -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On 08/09/2012 04:25 PM, Eric Blake wrote:
On 08/09/2012 08:17 AM, Martin Kletzander wrote:
Error 404 page had relative paths specified for both the image and stylesheets which caused a problem when requested URL included a subfolder (e.g. http://libvirt.org/asdf/asdf ). This patch corrects this behaviour by modifying href_base to '/' and changing the src of the image. --- docs/404.html.in | 2 +- docs/site.xsl | 11 ++++++++++- 2 files changed, 11 insertions(+), 2 deletions(-)
I'm no xsl expert, but
- <xsl:variable name="href_base" select="''"/> + <xsl:variable name="href_base"> + <xsl:choose> + <xsl:when test="$pagename = '404.html'"> + <xsl:value-of select="'/'"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="''"/> + </xsl:otherwise> + </xsl:choose> + </xsl:variable>
this reads pretty straightforward, so I'm okay giving:
ACK.
Thanks, pushed with a trivial fix (I realized that href_base is only for the stylesheets and other things added in the xsl, thus is not replaced in the html, so I changed it to '/' in the image and double checked that it generates correctly before pushing). I'm not good with xsl as well, I just talked about this with DV and he helped me with some of these things. Thanks DV. Martin
This patch makes search.php autogenerated from search.php.in, thus removing hardcoded menus, footer etc. and the search.php is added to .gitignore. There is new rule added for *.php files (to make it bit less hardcoded) that takes *.php.code.in and injects it inside the generated *.php (xslt was not happy about php code in the source xml). --- .gitignore | 1 + docs/Makefile.am | 24 +++++++- docs/{search.php => search.php.code.in} | 90 ++----------------------------- docs/search.php.in | 17 ++++++ 4 files changed, 44 insertions(+), 88 deletions(-) rename docs/{search.php => search.php.code.in} (66%) create mode 100644 docs/search.php.in diff --git a/.gitignore b/.gitignore index cd8a85c..17dcae4 100644 --- a/.gitignore +++ b/.gitignore @@ -61,6 +61,7 @@ /docs/libvirt-api.xml /docs/libvirt-qemu-*.xml /docs/libvirt-refs.xml +/docs/search.php /docs/todo.html.in /examples/domain-events/events-c/event-test /examples/dominfo/info1 diff --git a/docs/Makefile.am b/docs/Makefile.am index 88407b1..83747e4 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -75,6 +75,10 @@ dot_html_in = $(notdir $(wildcard $(srcdir)/*.html.in)) todo.html.in hvsupport.h $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/internals/*.html.in)) dot_html = $(dot_html_in:%.html.in=%.html) +dot_php_in = $(notdir $(wildcard $(srcdir)/*.php.in)) +dot_php_code_in = $(dot_php_in:%.php.in=%.php.code.in) +dot_php = $(dot_php_in:%.php.in=%.php) + patches = $(patsubst $(srcdir)/%,%,$(wildcard $(srcdir)/api_extension/*.patch)) xml = \ @@ -107,21 +111,22 @@ EXTRA_DIST= \ $(dot_html) $(dot_html_in) $(gif) $(apihtml) $(apipng) \ $(devhelphtml) $(devhelppng) $(devhelpcss) $(devhelpxsl) \ $(xml) $(qemu_xml) $(fig) $(png) $(css) \ - $(patches) \ + $(patches) $(dot_php_in) $(dot_php_code_in) $(dot_php)\ sitemap.html.in \ todo.pl hvsupport.pl todo.cfg-example MAINTAINERCLEANFILES = \ $(addprefix $(srcdir)/,$(dot_html)) \ $(addprefix $(srcdir)/,$(apihtml)) \ - $(addprefix $(srcdir)/,$(devhelphtml)) + $(addprefix $(srcdir)/,$(devhelphtml)) \ + $(addprefix $(srcdir)/,$(dot_php)) all-am: web api: $(srcdir)/libvirt-api.xml $(srcdir)/libvirt-refs.xml qemu_api: $(srcdir)/libvirt-qemu-api.xml $(srcdir)/libvirt-qemu-refs.xml -web: $(dot_html) html/index.html devhelp/index.html +web: $(dot_html) html/index.html devhelp/index.html $(dot_php) todo.html.in: todo.pl if [ -f todo.cfg ]; then \ @@ -173,6 +178,19 @@ internals/%.html.tmp: internals/%.html.in subsite.xsl page.xsl sitemap.html.in || { rm $(srcdir)/$@ && exit 1; }; \ else echo "missing XHTML1 DTD" ; fi ; fi +%.php.tmp: %.php.in site.xsl page.xsl sitemap.html.in + @if [ -x $(XSLTPROC) ] ; then \ + echo "Generating $@"; \ + name=`echo $@ | sed -e 's/.tmp//'`; \ + $(XSLTPROC) --stringparam pagename $$name --nonet --html \ + $(top_srcdir)/docs/site.xsl $< > $@ \ + || { rm $@ && exit 1; }; fi + +%.php: %.php.tmp %.php.code.in + @echo "Scripting $@"; \ + sed -e '/<a id="php_placeholder"><\/a>/r '"$(srcdir)/$@.code.in"\ + -e /php_placeholder/d < $@.tmp > $(srcdir)/$@ \ + || { rm $(srcdir)/$@ && exit 1; } html/index.html: libvirt-api.xml newapi.xsl page.xsl sitemap.html.in $(AM_V_GEN)if [ -x $(XSLTPROC) ] ; then \ diff --git a/docs/search.php b/docs/search.php.code.in similarity index 66% rename from docs/search.php rename to docs/search.php.code.in index 768e06f..df25cd6 100644 --- a/docs/search.php +++ b/docs/search.php.code.in @@ -1,49 +1,28 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> -<!-- - This file is autogenerated from the PHP output - Do not edit this file. Changes will be lost. - --> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /> - <link rel="stylesheet" type="text/css" href="main.css" /> - <link rel="SHORTCUT ICON" href="32favicon.png" /> - <title>Search the documentation on Libvir.org</title> - <meta name="description" content="libvirt, virtualization, virtualization API" /> - </head> - <body> - <div id="header"> - <div id="headerLogo"></div> - </div> - <div id="body"> - <div id="content"> <?php $query = $_GET['query']; // We handle only the first argument so far $query = ltrim ($query); - if (! $query) { - echo "<h1 align='center'>Search the documentation on Libvir.org</h1>"; - } + $scope = $_GET['scope']; if ($scope == NULL) $scope = "any"; $scope = ltrim ($scope); if ($scope == "") $scope = "any"; - ?> -<p> The search service indexes the libvirt APIs and documentation as well as the libvir-list@redhat.com mailing-list archives. To use it simply provide a set of keywords:</p> + <form action="<?php echo $_SERVER['PHP_SELF'], "?query=", rawurlencode($query) ?>" enctype="application/x-www-form-urlencoded" method="get"> <input name="query" type="text" size="50" value="<?php echo $query?>"/> <select name="scope"> <option value="any">Search All</option> <option value="API" <?php if ($scope == 'API') print "selected='selected'"?>>Only the APIs</option> - <option value="DOCS" <?php if ($scope == 'DOCS') print "selected"?>>Only the Documentation</option> - <option value="LISTS" <?php if ($scope == 'LISTS') print "selected"?>>Only the lists archives</option> + <option value="DOCS" <?php if ($scope == 'DOCS') print "selected='selected'"?>>Only the Documentation</option> + <option value="LISTS" <?php if ($scope == 'LISTS') print "selected='selected'"?>>Only the lists archives</option> </select> <input name="submit" type="submit" value="Search ..."/> </form> + <?php function logQueryWord($word) { $result = mysql_query ("SELECT ID,Count FROM Queries WHERE Value='$word'"); @@ -243,62 +222,3 @@ } } ?> - <img src="libvirtLogo.png" alt="libvirt Logo" /> - </div> - <div id="menu"> - <ul class="l0"><li> - <span class="active">Home</span> - </li><li> - <a title="Details of new features and bugs fixed in each release" class="inactive" href="news.html">News</a> - </li><li> - <a title="Get the latest source releases, binary builds and get access to the source repository" class="inactive" href="downloads.html">Downloads</a> - </li><li> - <a title="Information for users, administrators and developers" class="inactive" href="docs.html">Documentation</a> - </li><li> - <a title="User contributed content" class="inactive" href="http://wiki.libvirt.org">Wiki</a> - </li><li> - <a title="Frequently asked questions" class="inactive" href="http://wiki.libvirt.org/page/FAQ">FAQ</a> - </li><li> - <a title="How and where to report bugs and request features" class="inactive" href="bugs.html">Bug reports</a> - </li><li> - <a title="How to contact the developers via email and IRC" class="inactive" href="contact.html">Contact</a> - </li><li> - <a title="Miscellaneous links of interest related to libvirt" class="inactive" href="relatedlinks.html">Related Links</a> - </li><li> - <a title="Overview of all content on the website" class="inactive" href="sitemap.html">Sitemap</a> - </li></ul> - </div> - </div> - <div id="footer"> - <div id="projects"> - <dl id="p1"><dt> - <a href="http://augeas.net/">Augeas</a> - </dt><dd> - <span>A configuration editing tool and API</span> - </dd><dt> - <a href="http://libvirt.org/">libvirt</a> - </dt><dd> - <span>The open source virtualization API</span> - </dd></dl> - <dl id="p2"><dt> - <a href="http://cobbler.et.redhat.com/">Cobbler</a> - </dt><dd> - <span>OS provisioning and profile management</span> - </dd><dt> - <a href="http://ovirt.org/">oVirt</a> - </dt><dd> - <span>Virtualization management across the data center</span> - </dd></dl> - <dl id="p3"><dt> - <a href="http://freeipa.org/">FreeIPA</a> - </dt><dd> - <span>Identity, policy and audit management</span> - </dd><dt> - <a href="http://virt-manager.org/">Virtual Machine Manager</a> - </dt><dd> - <span>Virtualization management from the desktop</span> - </dd></dl> - </div> - </div> - </body> -</html> diff --git a/docs/search.php.in b/docs/search.php.in new file mode 100644 index 0000000..ee8f4a3 --- /dev/null +++ b/docs/search.php.in @@ -0,0 +1,17 @@ +<?xml version="1.0"?> +<html> + <body> + <h1>Search the documentation on Libvirt.org</h1> + + <p> + The search service indexes the libvirt APIs and documentation as + well as the libvir-list@redhat.com mailing-list archives. To use + it simply provide a set of keywords: + </p> + +<a id="php_placeholder"/> + + <img src="libvirtLogo.png" alt="libvirt Logo" /> + + </body> +</html> -- 1.7.8.6
On 08/09/2012 08:17 AM, Martin Kletzander wrote:
This patch makes search.php autogenerated from search.php.in, thus removing hardcoded menus, footer etc. and the search.php is added to .gitignore.
There is new rule added for *.php files (to make it bit less hardcoded) that takes *.php.code.in and injects it inside the generated *.php (xslt was not happy about php code in the source xml). ---
I will flat-out admit I've never coded in php. However, I can at least review the makefile portions for correctness, as well as apply and test that the patch does what it claims (and indeed, the generated search.php file resembles the original checked in version, with the differences being improvements in the boilerplate now that it went through the same code generation steps as the rest of our pages). I did _not_ test a 'make dist' from a VPATH build; there's a slight possibility that we may need some cleanup patches as a result, but I'm okay with that risk.
@@ -173,6 +178,19 @@ internals/%.html.tmp: internals/%.html.in subsite.xsl page.xsl sitemap.html.in || { rm $(srcdir)/$@ && exit 1; }; \ else echo "missing XHTML1 DTD" ; fi ; fi
+%.php.tmp: %.php.in site.xsl page.xsl sitemap.html.in + @if [ -x $(XSLTPROC) ] ; then \ + echo "Generating $@"; \ + name=`echo $@ | sed -e 's/.tmp//'`; \
This works, although '\.' is technically tighter than '.' for matching the literal '.' in the file name. But why bother with sed and `` in the first place? You've go make to do it for you: name=$(@:.tmp=)
+ $(XSLTPROC) --stringparam pagename $$name --nonet --html \
or even skip $$name and directly inline $(@:.tmp=) here.
+ $(top_srcdir)/docs/site.xsl $< > $@ \ + || { rm $@ && exit 1; }; fi + +%.php: %.php.tmp %.php.code.in + @echo "Scripting $@"; \ + sed -e '/<a id="php_placeholder"><\/a>/r '"$(srcdir)/$@.code.in"\
Missing space before \, for consistent style. ACK with those minor tweaks. -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On 08/09/2012 05:00 PM, Eric Blake wrote:
On 08/09/2012 08:17 AM, Martin Kletzander wrote:
This patch makes search.php autogenerated from search.php.in, thus removing hardcoded menus, footer etc. and the search.php is added to .gitignore.
There is new rule added for *.php files (to make it bit less hardcoded) that takes *.php.code.in and injects it inside the generated *.php (xslt was not happy about php code in the source xml). ---
I will flat-out admit I've never coded in php. However, I can at least review the makefile portions for correctness, as well as apply and test that the patch does what it claims (and indeed, the generated search.php file resembles the original checked in version, with the differences being improvements in the boilerplate now that it went through the same code generation steps as the rest of our pages).
I did _not_ test a 'make dist' from a VPATH build; there's a slight possibility that we may need some cleanup patches as a result, but I'm okay with that risk.
I'll try that, but I won't probably find necessarily all the issues that might occur.
@@ -173,6 +178,19 @@ internals/%.html.tmp: internals/%.html.in subsite.xsl page.xsl sitemap.html.in || { rm $(srcdir)/$@ && exit 1; }; \ else echo "missing XHTML1 DTD" ; fi ; fi
+%.php.tmp: %.php.in site.xsl page.xsl sitemap.html.in + @if [ -x $(XSLTPROC) ] ; then \ + echo "Generating $@"; \ + name=`echo $@ | sed -e 's/.tmp//'`; \
This works, although '\.' is technically tighter than '.' for matching the literal '.' in the file name. But why bother with sed and `` in the first place? You've go make to do it for you:
name=$(@:.tmp=)
Yes, I haven't realized that when remaking other rule to suit my needs, but it's definitely better looking, easier and faster. All the other rules use this, so I'll see what I can do with that later (maybe some bigger cleanup wouldn't hurt), but ...
+ $(XSLTPROC) --stringparam pagename $$name --nonet --html \
or even skip $$name and directly inline $(@:.tmp=) here.
... I went with this version in this patch.
+ $(top_srcdir)/docs/site.xsl $< > $@ \ + || { rm $@ && exit 1; }; fi + +%.php: %.php.tmp %.php.code.in + @echo "Scripting $@"; \ + sed -e '/<a id="php_placeholder"><\/a>/r '"$(srcdir)/$@.code.in"\
Missing space before \, for consistent style.
Fixed.
ACK with those minor tweaks.
Thanks, pushed. Martin
List: - some old libvir/libvirt rename leftovers (the only problem can be if somebody parses 'virsh version' output really badly) - remove pointless tags specified in some pages that are not used --- docs/api_extension.html.in | 4 ---- docs/pending.html.in | 4 ---- tools/virsh-host.c | 4 ++-- 3 files changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/api_extension.html.in b/docs/api_extension.html.in index 8d74752..83c488c 100644 --- a/docs/api_extension.html.in +++ b/docs/api_extension.html.in @@ -1,8 +1,4 @@ <html> - <head> - <title>Implementing a new API in Libvirt</title> - </head> - <body> <h1>Implementing a new API in Libvirt</h1> diff --git a/docs/pending.html.in b/docs/pending.html.in index 7a31878..f2978bf 100644 --- a/docs/pending.html.in +++ b/docs/pending.html.in @@ -1,8 +1,4 @@ <html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <title>Pending patches needing review</title> - </head> <body> <h1>Pending patches needing review</h1> <p> A list of pending patches needing review upstream is available diff --git a/tools/virsh-host.c b/tools/virsh-host.c index d9d09b4..b09d9f9 100644 --- a/tools/virsh-host.c +++ b/tools/virsh-host.c @@ -762,7 +762,7 @@ cmdVersion(vshControl *ctl, const vshCmd *cmd ATTRIBUTE_UNUSED) includeVersion %= 1000000; minor = includeVersion / 1000; rel = includeVersion % 1000; - vshPrint(ctl, _("Compiled against library: libvir %d.%d.%d\n"), + vshPrint(ctl, _("Compiled against library: libvirt %d.%d.%d\n"), major, minor, rel); ret = virGetVersion(&libVersion, hvType, &apiVersion); @@ -774,7 +774,7 @@ cmdVersion(vshControl *ctl, const vshCmd *cmd ATTRIBUTE_UNUSED) libVersion %= 1000000; minor = libVersion / 1000; rel = libVersion % 1000; - vshPrint(ctl, _("Using library: libvir %d.%d.%d\n"), + vshPrint(ctl, _("Using library: libvirt %d.%d.%d\n"), major, minor, rel); major = apiVersion / 1000000; -- 1.7.8.6
On 08/09/2012 08:18 AM, Martin Kletzander wrote:
List: - some old libvir/libvirt rename leftovers (the only problem can be if somebody parses 'virsh version' output really badly) - remove pointless tags specified in some pages that are not used --- docs/api_extension.html.in | 4 ---- docs/pending.html.in | 4 ---- tools/virsh-host.c | 4 ++-- 3 files changed, 2 insertions(+), 10 deletions(-)
ACK. -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
On 08/09/2012 04:31 PM, Eric Blake wrote:
On 08/09/2012 08:18 AM, Martin Kletzander wrote:
List: - some old libvir/libvirt rename leftovers (the only problem can be if somebody parses 'virsh version' output really badly) - remove pointless tags specified in some pages that are not used --- docs/api_extension.html.in | 4 ---- docs/pending.html.in | 4 ---- tools/virsh-host.c | 4 ++-- 3 files changed, 2 insertions(+), 10 deletions(-)
ACK.
Thanks, pushed. Martin
participants (2)
-
Eric Blake -
Martin Kletzander