[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: man pages for Subversion

From: Stefan Sperling <stsp_at_elego.de>
Date: Wed, 7 Aug 2013 11:27:13 +0200

On Wed, Aug 07, 2013 at 12:07:08AM -0400, James K. Lowden wrote:
> http://www.schemamania.org/svn/man1/
> e.g. http://www.schemamania.org/svn/man1/svn-propset.pdf
>
> I offer the above mdoc man pages to the Subversion project as a token
> of my appreciation, and in the hope they'll be included in future
> versions.
>
> I find using any command-line tool more convenient when it's documented
> with proper man pages, so that "man foo" instantly displays the
> reference manual. That's especially true of a complex tool like
> subversion. The "svn help foo | less" feature is OK, but it's not as
> convenient and lacks the boldface and underscores that assist in
> scanning the text. HTML is better-looking, but many clicks away.
>
> I hope you agree that the man pages are easier to read than plain
> text, and the PDFs just stunning.

Thanks. I've been thinking about how to better produce mdoc output
for Subversion man pages for a while now.

A related discussion can be found at
http://mail-archives.apache.org/mod_mbox/subversion-dev/201209.mbox/%3C1347648306.66873.YahooMailNeo%40web87705.mail.ir2.yahoo.com%3E

Please also see the Improve 'svn help' item on this page:
http://subversion.apache.org/ideas.html#ideas

> The pages represent perhaps 30 hours of work. The --help text was
> processed through the bin/manualize Perl script to create a rough
> mdoc draft. Then individual sections were edited by hand, sometimes to
> put finishing touches on the formatting, sometimes to clarify the text.

So essentially you are running a script to produce those pages
from 'svn help' output? Where can I find this script?

Can the finishing touches you mention be made on the source
material, i.e. 'svn help' as well? Ideally, we'd produce man pages
as part of our build process and ship them with Subversion releases.
Can you help us with achieving that goal?

I don't mind whether we're post-processing 'svn help' output to
produce man pages, or whether we're generating 'svn help' output
and man pages from the same source material somehow. As long as
we can get a set of quality man pages to ship with a release.

> The final result is surely a derived work, but it's not clear to me if
> the --help text is copyrighted. I am prepare to assign it as befits
> the project, if need be.

I would say that the ASF copyright applies, i.e. the licence is APLv2.

> You can generate your own man pages from whatever version of Subversion
> you have installed by unpacking the tarball and running "make".

Which tarball?
Received on 2013-08-07 11:28:04 CEST

This is an archived mail posted to the Subversion Dev mailing list.