On Fri, 9 Aug 2013 11:21:23 +0300
Daniel Shahaf <danie...@elego.de> wrote:
> > 1. Get the sources for 1.9
> > 2. Examine svn_cl__cmd_table
> > 3. Prepare a doc build tree that creates two things:
> > a. man pages
> > b. plain text for --help, one file per subcommand
> >
> > The plain text filenames will have the extension ".in", so a
> > simple Makefile rule can convert them to ".h" for inclusion into the
> > appropriate source module.
>
> You'd have to figure out something for windows as well, since we don't
> use make that on that platform. (Several of our dependencies do, but
> we just generate Visual Studio projects.)
Hmm. This is a sticky wicket.
My plan is to keep mdoc sources and generate plain text for
inclusion in the help subsystem. That's done easily with groff, see
below. But I notice in INSTALL you support building on Windows not only
in a tarball but also directly in-tree. That means the Windows
build machine would have to be able to convert the mdoc sources to ASCII
strings.
I'd like to point out, btw, that in 2013 this is the tail wagging the
dog. Windows command-line users are rare; most people use Tortoise.
Those that do use the command line don't rely on --help very much,
either. Consider:
$ svn propset --help | wc -l
95
and that more.exe resembles UNIX more(1) circa 1984 and that most
Windows users don't even know it exists. "svn help" on Windows is not
the model of ease of use.
Preserving --help for anything more than a short recap of the options
isn't worth it, especially when PDFs are available! The time is much
better spent improving the documentation and Subversion itself.
But let us suppose ad argumentum that we want to preserve --help, and
to support in-tree builds on Windows. That means something has to
convert the mdoc source to plain text. I don't see any better way than
to require mdocml or groff to be installed.
> In general, it'll be best if you hook into the existing build system
> --- configure.ac, gen-make.py, and build.conf. The latter two are
> used on all platforms (on unix they generate build-outputs.mk).
I don't want to get too deeply involved. I know mdoc, and I want to
see man pages become part of Subversion. I'm willing to provide
up-to-date mdoc source for them, and to generate plain text, and to
write a little Perl to convert the plain text to static constant
character arrays in C. I'm prepared to do the work to make it easy
-- for someone who knows how -- to integrate that work into the build
system. I don't want to peek inside gen-make.py.
Below is a sample of what I'd expect from the mdoc -> ascii
conversion.
--jkl
$ groff -P -bc -Tascii -mdoc man1/svn-copy.1 \
| sed -ne '/NAME/,/specify/p'
NAME
svn copy -- Duplicate something in working copy or repository
SYNOPSIS
svn copy (cp) [-Fmq] [--config-dir DIR] [--config-option OPT]
[--editor-cmd CMD] [--encoding ENC] [--file] [--force-log]
[--ignore-externals] [--message] [--no-auth-cache]
[--non-interactive] [--parents] [--password PWD] [--quiet]
[{-r | --revision} REV] [--trust-server-cert] [--username
USR] [--with-revprop PROP] SRC[@REV] ... DST
DESCRIPTION
When copying multiple sources, they will be added as children of
DST, which must be a directory. SRC and DST can each be either a
working copy (WC) path or URL:
WC -> WC copy and schedule for addition (with history)
WC -> URL immediately commit a copy of WC to URL
URL -> WC check out URL into WC, schedule for addition
URL -> URL complete server-side copy; used to branch and tag
All the SRCs must be of the same type.
OPTIONS
--editor-cmd CMD use CMD as external editor
--encoding ENC treat value as being in charset encoding ENC
-F --file FIL read log message from file FIL
--force-log force validity of log message source
--ignore-externals ignore externals definitions
-m --message MSG specify log message MSG
