> 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.
Is this an assumption, a prejudice or wishful thinking? Or, do you have facts
to back this up? Perhaps your assumption is correct wrt to your average
mainstream web surfer, but for devs many of them use command line quite a bit.
While I use tortoise for more common commands, I do drop to the command line
quite frequently to use svn.exe and to read the help text.
> 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
>
