Re: Single source documentation

Much knowledge gained last night, particularly about whitespace
handling with XSL, so the pipeline is down to the effective
minimum: xsltproc for XML->text processing, groff for text
formatting, and a tool to wrap each line in quotes for use as a C
include.

svn status is still my development target, and now both the
Description and Examples sections are included; literal layouts
like <screen> tags are handled properly and admonitions are
explicitly supported.

One of the major remaining showstoppers is figuring out how to
prevent groff from treating an apostrophe at the beginning of a
line as a command sequence. groff allows that character to be
redefined, but there is no completely safe character to use; I'd
rather just turn it off entirely.

Pipeline:
   xsltproc refentry-to-cstring.xsl svn-status.xml \
     | groff -man -Tlatin1 -P -b -P -c \
     | ./cleanup-cstring.pl

I'm attaching both the stylesheet and the svn-status help text
generated by it.

-John

"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\n"
" repository access). With --show-updates, add working revision\n"
" and 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\n"
" property)\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\n"
" incomplete (a checkout or update was interrupted).\n"
" '~': Item is versioned as a directory, but has been\n"
" replaced 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\n"
" property updates received from the repository.\n"
"\n"
" The third column is populated only if the working copy\n"
" directory 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\n"
" include spaces.\n"
"\n"
" Examples:\n"
"\n"
" This is the easiest way to find out what changes you have made\n"
" to your working copy:\n"
"\n"
" $ svn status wc\n"
" M wc/bar.c\n"
" A + wc/qax.c\n"
"\n"
" If you want to find out what files in your working copy are\n"
" out-of-date, pass the --show-updates switch (this will not\n"
" make any changes to your working copy). Here you can see that\n"
" wc/foo.c has changed in the repository since we last updated\n"
" our working copy:\n"
"\n"
" $ svn status --show-updates wc\n"
" M 965 wc/bar.c\n"
" * 965 wc/foo.c\n"
" A + 965 wc/qax.c\n"
" Head revision: 981\n"
"\n"
" WARNING: --show-updates only places an asterisk next to items\n"
" that are out of date (that is, items that will be updated from\n"
" the repository if you run svn update). --show-updates does not\n"
" cause the status listing to reflect the repository's version\n"
" of the item.\n"
"\n"
" And finally, the most information you can get out of the\n"
" status subcommand:\n"
"\n"
" $ svn status --show-updates --verbose wc\n"
" M 965 938 sally wc/bar.c\n"
" * 965 922 harry wc/foo.c\n"
" A + 965 687 harry wc/qax.c\n"
" 965 687 harry wc/zig.c\n"
" Head revision: 981\n"
"\n",

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org