Earlier this year, the problem of documentation duplication was
discussed on this list, but apparently nothing ever came of it.
This evening, I've been experimenting with a process to generate
the help command text from the refentries in the book, and I have
an alpha-quality solution.
I've created a relatively small XSL stylesheet that generates
roff output. That output is then processed a bit more, run
through troff and grotty, and finally run through a Perl program.
The output is a C string for inclusion into the client program's
help structure.
(I used Perl because text processing in C is about as fun as
pulling teeth; any language would do.)
I'm attaching the XSL stylesheet and the Perl program. The
pipeline looks something like the following. Assuming that the
refentry for svn status has been extracted into svn-status.xml:
> xsltproc refentry-to-cstring.xsl svn-status.xml | \
[1] sed 's/^ *//' | \
[2] sed "s/^'/ '/" | \
troff -man -Tlatin1 | \
[3] grotty -b -c | \
cleanup-cstring.pl > svn-status.h
Notes:
1: The only alternative to this that I can find is to edit the
source XML so that character data is always flush left, like:
<para>This is a rather
short paragraph.</para>
2: ' in the first column of roff input is considered to be a
command character.
3: Don't perform the stupid ASCII tricks that groff likes to
use for highlighting and underlining.
I am not at all a roff person, and I'm still relatively new at
XSL, particularly for generating text instead of XML, so there
may well be better ways to handle some of the above issues.
I'll also attach the svn status string as generated by the above
pipeline; that's one of the most complex help strings, so it's a
decent proof of concept. I did remove the xref tags from the
refentry before processing.
There isn't a good way to handle <xref> tags. I'm personally of
the opinion that refentries shouldn't use xref or link tags, so
that they can be meaningfully translated into man pages.
(I also believe that the refentries _should_ be processed to
generate individual man pages. I always disliked searching
through the giant single man page for cvs.)
Another caveat: currently, only the Description refsect1 is
processed. The current online help for svn status includes
examples, so that section should be processed too; looking at the
XML, there will need to be templates for at least screen and
warning added before that will work properly.
--
John R. Daily
<email><mailbox>john</mailbox><domain>geekhavoc.com</domain></email>
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<xsl:output method="text"/>
<xsl:strip-space elements="*"/>
<xsl:template match="/">
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="/refentry/refnamediv">
<xsl:text>.P
</xsl:text>
<xsl:value-of select="refpurpose"/><xsl:text>
</xsl:text>
</xsl:template>
<xsl:template match="/refentry/refsect1[normalize-space(title)='Synopsis']">
<xsl:text>.br
</xsl:text>
<xsl:text>usage: </xsl:text><xsl:value-of select="programlisting"/><xsl:text>
.in +3
</xsl:text>
</xsl:template>
<xsl:template match="/refentry/refsect1[normalize-space(title)='Description']">
<xsl:apply-templates/>
</xsl:template>
<xsl:template match="variablelist|itemizedlist">
<xsl:text>.in +3
</xsl:text>
<xsl:apply-templates/>
<xsl:text>.in -3
</xsl:text>
</xsl:template>
<xsl:template match="listitem/para">
<xsl:apply-templates/><xsl:text>
.br
</xsl:text>
</xsl:template>
<xsl:template match="varlistentry/term">
<xsl:apply-templates/><xsl:text> </xsl:text>
</xsl:template>
<xsl:template match="para">
<xsl:text>.P
</xsl:text>
<xsl:apply-templates/><xsl:text>
</xsl:text>
</xsl:template>
<!-- We don't want any titles to be displayed -->
<xsl:template match="title"/>
<!-- We only want the Description refsect1 to be processed -->
<xsl:template match="refsect1"/>
</xsl:stylesheet>
"Print the status of working copy files and directories.\n"
"usage: svn status [PATH...]\n"
"\n"
" Print the status of working copy files and directories. With\n"
" no arguments, it prints only locally modified items (no repos-\n"
" itory access). With --show-updates, add working revision and\n"
" server out-of-date information. With --verbose, print full\n"
" revision information on every item.\n"
"\n"
" The first five columns in the output are each one character\n"
" wide, and each column gives you information about different\n"
" aspects of each working copy item.\n"
"\n"
" The first column indicates that an item was added, deleted, or\n"
" otherwise changed.\n"
"\n"
" ' ' No modifications.\n"
" 'A' Item is scheduled for Addition.\n"
" 'D' Item is scheduled for Deletion.\n"
" 'M' Item has been modified.\n"
" 'C' Item is in conflict with updates received from the\n"
" repository.\n"
" 'I' Item is being ignored (e.g. with the svn:ignore prop-\n"
" erty)\n"
" '?' Item is not under version control.\n"
" '!' Item is missing (e.g. you moved or deleted it without\n"
" using svn). This also indicates that a directory is incom-\n"
" plete (a checkout or update was interrupted).\n"
" '~' Item is versioned as a directory, but has been re-\n"
" placed by a file, or vice versa\n"
"\n"
" The second column tells the status of a file's or directory's\n"
" properties.\n"
"\n"
" ' ' No modifications.\n"
" 'M' Properties for this item have been modified.\n"
" 'C' Properties for this item are in conflict with property\n"
" updates received from the repository.\n"
"\n"
" The third column is populated only if the working copy direc-\n"
" tory is locked.\n"
"\n"
" ' ' Item is not locked.\n"
" 'L' Item is locked.\n"
"\n"
" The fourth column is populated only if the item is scheduled\n"
" for addition-with-history.\n"
"\n"
" ' ' No history scheduled with commit.\n"
" '+' History scheduled with commit.\n"
"\n"
" The fifth column is populated only if the item is switched\n"
" relative to its parent.\n"
"\n"
" ' ' Item is child of its parent directory.\n"
" 'S' Item is switched.\n"
"\n"
" The out-of-date information appears in the eighth column (only\n"
" if you pass the --show-updates switch).\n"
"\n"
" ' ' The item in your working copy is up-to-date.\n"
" '*' A newer revision of the item exists on the server.\n"
"\n"
" The remaining fields are variable width and delimited by\n"
" spaces. The working revision is the next field if the --show-\n"
" updates or --verbose switches are passed.\n"
"\n"
" If the --verbose switch is passed, the last committed revision\n"
" and last committed author are displayed next.\n"
"\n"
" The working copy path is always the final field, so it can in-\n"
" clude spaces.\n"
"\n",
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Wed Nov 12 07:41:23 2003