When documenting our public API in some places we use '@' to
refer to the variable. For instance:

 * This API tries to set guest time to the given value. The time
 * to set (@seconds and @nseconds) should be in seconds relative
 * to the Epoch of 1970-01-01 00:00:00 in UTC.

However, when generating HTML documentation these tokens are
copied verbatim. What we can do is drop the '@' character and
wrap the variable in <code/> so that it is formatted properly.

Due to the way we 'parse' docs a token might actually be slightly
more than just '@variable'. For instance in the example above we
will have the following tokens: '(@seconds' and '@nseconds)'.
Thus we need to handle possible substring before and after
variable.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
 docs/newapi.xsl | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/newapi.xsl b/docs/newapi.xsl
index 7ac8caa35d..e56a5f2a27 100644
--- a/docs/newapi.xsl
+++ b/docs/newapi.xsl
@@ -139,6 +139,12 @@
         </a>
         <xsl:value-of select="substring-after($token, '&gt;')"/>
       </xsl:when>
+      <xsl:when test="contains($token, '@')">
+        <xsl:variable name="prologue" select="substring-before($token, '@')"/>
+        <xsl:value-of select="$prologue"/>
+        <code><xsl:value-of select="$stem"/></code>
+        <xsl:value-of select="substring($token, string-length($prologue) + string-length($stem) + 2)"/>
+      </xsl:when>
       <xsl:otherwise>
         <xsl:value-of select="$token"/>
       </xsl:otherwise>
-- 
2.32.0

On a Friday in 2021, Michal Privoznik wrote:
>When documenting our public API in some places we use '@' to
>refer to the variable. For instance:
>
> * This API tries to set guest time to the given value. The time
> * to set (@seconds and @nseconds) should be in seconds relative
> * to the Epoch of 1970-01-01 00:00:00 in UTC.
>
>However, when generating HTML documentation these tokens are
>copied verbatim. What we can do is drop the '@' character and
>wrap the variable in <code/> so that it is formatted properly.
>
>Due to the way we 'parse' docs a token might actually be slightly
>more than just '@variable'. For instance in the example above we
>will have the following tokens: '(@seconds' and '@nseconds)'.
>Thus we need to handle possible substring before and after
>variable.
>
>Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
>---
> docs/newapi.xsl | 6 ++++++
> 1 file changed, 6 insertions(+)
>

Reviewed-by: Ján Tomko <jtomko@redhat.com>

Jano