David Kimdon wrote:
>
> Any objections or seconds to the following?
+1 (minor comments below). I like man pages. Mind you, I like them even better when they have the manual in them, but that was proving to be too difficult for us to maintain.
As we now have about six man pages sharing a sizeable block of text, it would be nice to factor out that block and build the man pages at build time from mostly shared source text.
- Julian
> -------------------------------------------------------------------
>
> Add small manpages for svndumpfilter, svnserve, and svnversion. Much
> like the current pages for svn, svnadmin and svnlook these pages
> briefly introduce Subversion and then point to the real documentation
> for more information.
>
> * build.conf (svndumpfilter,svnserve,svnversion) : Install manpages.
> * subversion/svndumpfilter/svndumpfilter.1 : New file.
> * subversion/svnserve/svnserve.1 : New file.
> * subversion/svnversion/svnversion.1 : New file.
> * subversion/svnversion/main.c : Turn the user relevant parts of a
"user relevant" -> "user-relevant"
> block comment before main() into help text that is displayed if
> 'svnversion' is run without arguments.
> (usage) : New function.
> Index: subversion/svnversion/main.c
> ===================================================================
> --- subversion/svnversion/main.c (revision 7390)
> +++ subversion/svnversion/main.c (working copy)
> @@ -70,29 +70,37 @@
> sb->wc_url = apr_pstrdup (sb->pool, status->entry->url);
> }
>
> +static void
> +usage(void)
> +{
> + fprintf(stderr,
> + " The svnversion program produces a compact \"version number\"\n"
> + " for the Subversion working copy. The program takes one or\n"
> + " two arguments, the first is the path to the working copy,\n"
> + " the second is the trailing portion of the trunk URL. The\n"
Given the "usage: svnversion wc_path [trail_url]" line that precedes this, it could just say:
+ " Produce a compact \"version number\" for a working copy WC_PATH.\n"
+ " TRAIL_URL is the trailing portion of the trunk URL."...
> + " version number is written to standard output. Here is an\n"
> + " example:\n"
> + "\n"
> + " $ svnversion . /repos/svn/trunk \n"
> + " 4168\n"
> + "\n"
> + " The version number will be a single number if the working\n"
> + " copy is single revision, unmodified, not switched and with\n"
> + " an URL that matches the trunk URL argument. If the working\n"
> + " copy is unusual the version number will be more complex:\n"
> + "\n"
> + " 4123:4168 mixed revision working copy\n"
> + " 4168M modified working copy\n"
> + " 4123S switched working copy\n"
> + " 4123:4168MS mixed revision, modified, switched working copy\n"
> + "\n"
> + " If invoked on a directory that is not a working copy, an\n"
> + " exported directory say, the program will output \"exported\".\n"
> + "\n");
> +}
>
...
> @@ -113,7 +121,8 @@
>
> if (argc != 2 && argc != 3)
> {
> - fprintf(stderr, "usage: svnversion wc_path [trail_url]\n");
> + fprintf(stderr, "usage: svnversion wc_path [trail_url]\n\n");
> + usage();
Well, I'd describe the "usage:" line as "usage", and the block text as "help", or put them together.
> return EXIT_FAILURE;
> }
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Oct 13 00:22:22 2003