Wrap pre-formatted example code in <code> elements. This works similar to Markdown[1] code blocks[2]: Every line indented with at least 2 spaces is considered a code block and gets wrapped in <pre> and <code> tags. Look at the documentation for e.g. virStreamSend for before-and-after effects. [1] http://daringfireball.net/projects/markdown/ [2] http://daringfireball.net/projects/markdown/syntax#precode Signed-off-by: Claudio Bley <cbley(a)av-test.de&gt; --- docs/newapi.xsl | 96 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 74 insertions(+), 22 deletions(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 7fa0f26..d62839a 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -150,6 +150,67 @@ </xsl:for-each> </xsl:template> + + <!-- process blocks of text. blocks are separated by two consecutive line --> + <!-- breaks. --> + <!-- --> + <!-- blocks indented with at least 2 spaces are considered code blocks. --> + <!-- --> + <!-- consecutive code blocks are collapsed into a single code block. --> + <xsl:template name="formatblock"> + <xsl:param name="block"/> + <xsl:param name="rest"/> + + <xsl:variable name="multipleCodeBlocks" + select="starts-with($block, ' ') and starts-with($rest, ' ')"/> + + <xsl:choose> + <xsl:when test="$multipleCodeBlocks"> + <xsl:call-template name="formatblock"> + <xsl:with-param name="block"> + <xsl:choose> + <xsl:when test="contains($rest, '&#xA;&#xA;')"> + <xsl:value-of select="concat($block, '&#xA; &#xA;', + substring-before($rest, '&#xA;&#xA;'))" /> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="concat($block, '&#xA; &#xA;', $rest)" /> + </xsl:otherwise> + </xsl:choose> + </xsl:with-param> + <xsl:with-param name="rest" select="substring-after($rest, '&#xA;&#xA;')"/> + </xsl:call-template> + </xsl:when> + <xsl:when test="starts-with($block, ' ')"> + <pre class="code"><xsl:for-each select="str:tokenize($block, '&#xA;')"> + <xsl:choose> + <xsl:when test="starts-with(., ' ')"> + <xsl:value-of select="substring(., 3)"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="."/> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="position() != last()"> + <xsl:text>&#xA;</xsl:text> + </xsl:if> + </xsl:for-each></pre> + </xsl:when> + <xsl:otherwise> + <p> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="$block"/> + </xsl:call-template> + </p> + </xsl:otherwise> + </xsl:choose> + <xsl:if test="not($multipleCodeBlocks)"> + <xsl:call-template name="formattext"> + <xsl:with-param name="text" select="$rest"/> + </xsl:call-template> + </xsl:if> + </xsl:template> + <xsl:template name="formattext"> <xsl:param name="text" /> @@ -157,28 +218,19 @@ <xsl:variable name="head" select="substring-before($text, '&#xA;&#xA;')"/> <xsl:variable name="rest" select="substring-after($text, '&#xA;&#xA;')"/> - <xsl:choose> - <xsl:when test="$head"> - <p> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="$head"/> - </xsl:call-template> - </p> - </xsl:when> - <xsl:when test="not($rest)"> - <p> - <xsl:call-template name="dumptext"> - <xsl:with-param name="text" select="$text"/> - </xsl:call-template> - </p> - </xsl:when> - </xsl:choose> - - <xsl:if test="$rest"> - <xsl:call-template name="formattext"> - <xsl:with-param name="text" select="$rest"/> - </xsl:call-template> - </xsl:if> + <xsl:call-template name="formatblock"> + <xsl:with-param name="block"> + <xsl:choose> + <xsl:when test="contains($text, '&#xA;&#xA;')"> + <xsl:value-of select="$head"/> + </xsl:when> + <xsl:otherwise> + <xsl:value-of select="$text"/> + </xsl:otherwise> + </xsl:choose> + </xsl:with-param> + <xsl:with-param name="rest" select="$rest"/> + </xsl:call-template> </xsl:if> </xsl:template> -- 1.7.9.5

Signed-off-by: Claudio Bley <cbley(a)av-test.de&gt; --- docs/newapi.xsl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index d62839a..a08b304 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -416,7 +416,7 @@ <xsl:variable name="name" select="string(@name)"/> <h3><a name="{$name}"><code><xsl:value-of select="$name"/></code></a></h3> <pre class="api"><span class="directive">#define</span><xsl:text> </xsl:text><xsl:value-of select="$name"/></pre> - <div> + <div class="description"> <xsl:call-template name="formattext"> <xsl:with-param name="text" select="info"/> </xsl:call-template> @@ -568,7 +568,7 @@ <xsl:text>) </xsl:text> </pre> - <div> + <div class="description"> <xsl:call-template name="formattext"> <xsl:with-param name="text" select="info"/> </xsl:call-template> @@ -644,7 +644,7 @@ </xsl:for-each> <xsl:text>)</xsl:text> </pre> - <div> + <div class="description"> <xsl:call-template name="formattext"> <xsl:with-param name="text" select="info"/> </xsl:call-template> -- 1.7.9.5

Signed-off-by: Claudio Bley <cbley(a)av-test.de&gt; --- docs/libvirt.css | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/libvirt.css b/docs/libvirt.css index ed67b2f..b324ac8 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -491,3 +491,10 @@ table.acl tr, table.acl td { table.acl thead { background: #ddd; } + +div.description pre.code { + border: 1px dashed grey; + background-color: inherit; + padding: 5px 10px 5px 10px; + margin-left: 2.5em; +} -- 1.7.9.5

See libvirt-libvirt.html#virStreamSend for the effect. Signed-off-by: Claudio Bley <cbley(a)av-test.de&gt; --- src/libvirt.c | 114 ++++++++++++++++++++++++++++----------------------------- 1 file changed, 57 insertions(+), 57 deletions(-) diff --git a/src/libvirt.c b/src/libvirt.c index 9f579a6..405c13f 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -16992,37 +16992,37 @@ virStreamRef(virStreamPtr stream) * An example using this with a hypothetical file upload * API looks like * - * virStreamPtr st = virStreamNew(conn, 0); - * int fd = open("demo.iso", O_RDONLY) + * virStreamPtr st = virStreamNew(conn, 0); + * int fd = open("demo.iso", O_RDONLY) * - * virConnectUploadFile(conn, "demo.iso", st); - * - * while (1) { - * char buf[1024]; - * int got = read(fd, buf, 1024); - * if (got < 0) { - * virStreamAbort(st); - * break; - * } - * if (got == 0) { - * virStreamFinish(st); - * break; - * } - * int offset = 0; - * while (offset < got) { - * int sent = virStreamSend(st, buf+offset, got-offset) - * if (sent < 0) { + * virConnectUploadFile(conn, "demo.iso", st); + * + * while (1) { + * char buf[1024]; + * int got = read(fd, buf, 1024); + * if (got < 0) { * virStreamAbort(st); - * goto done; + * break; * } - * offset += sent; - * } - * } - * if (virStreamFinish(st) < 0) - * ... report an error .... - * done: - * virStreamFree(st); - * close(fd); + * if (got == 0) { + * virStreamFinish(st); + * break; + * } + * int offset = 0; + * while (offset < got) { + * int sent = virStreamSend(st, buf+offset, got-offset) + * if (sent < 0) { + * virStreamAbort(st); + * goto done; + * } + * offset += sent; + * } + * } + * if (virStreamFinish(st) < 0) + * ... report an error .... + * done: + * virStreamFree(st); + * close(fd); * * Returns the number of bytes written, which may be less * than requested. @@ -17086,35 +17086,35 @@ error: * An example using this with a hypothetical file download * API looks like * - * virStreamPtr st = virStreamNew(conn, 0); - * int fd = open("demo.iso", O_WRONLY, 0600) - * - * virConnectDownloadFile(conn, "demo.iso", st); - * - * while (1) { - * char buf[1024]; - * int got = virStreamRecv(st, buf, 1024); - * if (got < 0) - * break; - * if (got == 0) { - * virStreamFinish(st); - * break; - * } - * int offset = 0; - * while (offset < got) { - * int sent = write(fd, buf+offset, got-offset) - * if (sent < 0) { - * virStreamAbort(st); - * goto done; - * } - * offset += sent; - * } - * } - * if (virStreamFinish(st) < 0) - * ... report an error .... - * done: - * virStreamFree(st); - * close(fd); + * virStreamPtr st = virStreamNew(conn, 0); + * int fd = open("demo.iso", O_WRONLY, 0600) + * + * virConnectDownloadFile(conn, "demo.iso", st); + * + * while (1) { + * char buf[1024]; + * int got = virStreamRecv(st, buf, 1024); + * if (got < 0) + * break; + * if (got == 0) { + * virStreamFinish(st); + * break; + * } + * int offset = 0; + * while (offset < got) { + * int sent = write(fd, buf+offset, got-offset) + * if (sent < 0) { + * virStreamAbort(st); + * goto done; + * } + * offset += sent; + * } + * } + * if (virStreamFinish(st) < 0) + * ... report an error .... + * done: + * virStreamFree(st); + * close(fd); * * * Returns the number of bytes read, which may be less -- 1.7.9.5

By indenting code inside of comments, it gets recognized as a code block when generating the HTML documentation. Signed-off-by: Claudio Bley <cbley(a)av-test.de&gt; --- src/libvirt.c | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/libvirt.c b/src/libvirt.c index 405c13f..c48bc7b 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -4057,14 +4057,14 @@ error: * * Here is a sample code snippet: * - * if ((virDomainGetMemoryParameters(dom, NULL, &nparams, 0) == 0) && - * (nparams != 0)) { - * if ((params = malloc(sizeof(*params) * nparams)) == NULL) - * goto error; - * memset(params, 0, sizeof(*params) * nparams); - * if (virDomainGetMemoryParameters(dom, params, &nparams, 0)) - * goto error; - * } + * if ((virDomainGetMemoryParameters(dom, NULL, &nparams, 0) == 0) && + * (nparams != 0)) { + * if ((params = malloc(sizeof(*params) * nparams)) == NULL) + * goto error; + * memset(params, 0, sizeof(*params) * nparams); + * if (virDomainGetMemoryParameters(dom, params, &nparams, 0)) + * goto error; + * } * * This function may require privileged access to the hypervisor. This function * expects the caller to allocate the @params. -- 1.7.9.5

There are two forms used throughout libvirt code comments, which are both supported by this patch. * plain links like e.g. http://www.libvirt.org/ * links enclosed in <> characters, e.g. <http://www.libvirt.org/> Signed-off-by: Claudio Bley <cbley(a)av-test.de&gt; --- docs/newapi.xsl | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/newapi.xsl b/docs/newapi.xsl index a08b304..815c1b9 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -129,6 +129,19 @@ <a href="libvirt-{$ref/@file}.html#{$ref/@name}"><xsl:value-of select="$stem"/></a> <xsl:value-of select="substring-after($token, $stem)"/> </xsl:when> + <xsl:when test="starts-with($token, 'http://')"> + <a href="{$token}"> + <xsl:value-of select="$token"/> + </a> + </xsl:when> + <xsl:when test="starts-with($token, '&lt;http://') and contains($token, '&gt;')"> + <xsl:variable name="link" + select="substring(substring-before($token, '&gt;'), 2)"/> + <a href="{$link}"> + <xsl:value-of select="$link"/> + </a> + <xsl:value-of select="substring-after($token, '&gt;')"/> + </xsl:when> <xsl:otherwise> <xsl:value-of select="$token"/> </xsl:otherwise> @@ -690,7 +703,11 @@ <h2 style="font-weight:bold;color:red;text-align:center">This module is deprecated</h2> </xsl:if> <xsl:if test="description"> - <p><xsl:value-of select="description"/></p> + <p> + <xsl:call-template name="dumptext"> + <xsl:with-param name="text" select="description"/> + </xsl:call-template> + </p> </xsl:if> </xsl:template> -- 1.7.9.5