James K. Lowden wrote on Wed, Aug 07, 2013 at 20:13:16 -0400:
> On Wed, 7 Aug 2013 12:45:36 +0300
> Daniel Shahaf <danielsh_at_elego.de> wrote:
>
> > Then individual sections were edited by hand, sometimes to
> > > put finishing touches on the formatting, sometimes to clarify the
> > > text.
> >
> > How can we incorporate that into the dev cycle?
> >
> > if manual tweaks are required, we would have to follow a scheme
> > similar to translations: the master English output
> > (subversion/svn/svn.c:svn_cl__cmd_table) is updated, and afterwards
> > someone comes along, regenerates the manpage, re-applies the manual
> > edits, and commits. The problem is that a release may happen before
> > someone gets to update the semi-manually-generated man pages, which
> > will cause them to be out-of-date (with respect to 'svn help' output)
> > in the release.
> >
> > So, in addition to Stefan's point about incorporating your man pages
> > into the build system, I think it'll be useful to eliminate the need
> > for manual steps.
>
> First of all, let me say thanks for the positive response from
> everyone, and thanks for asking. :-) I wasn't sure how my message
> would be received, and I'm gratified I wasn't wasting my time.
>
Perhaps this is a good time to point out that you were writing man pages
for 1.7, which is in "Security fixes only" mode. The supported release
is 1.8 and trunk (where new development should be targeted) is 1.9.
> 1. Keep the man pages in mdoc format as the "souce code".
> 2. Convert "svn foo --help" and "svn help foo" to invoke man(1), as
> git does. Or use groff to generate plain text for static inclusion in
> the the binary.
As Bert said: not possible. We support Windows and that has no man(1)
or nroff(1) binaries.
The Windows build system already has Python available. (You *might* be
able to assume Perl since it's required for OpenSSL, but that requires
discussion.) So you'd need a solution that allows compiling the man
pages source to C strings that uses only Python (and maybe Perl).
> My manualize script is just a throwaway hack; it was easier (probably)
> to parse the help output to generate the synopsis and option lists.
> Going forward, it's probably not worthwhile to try to maintain a
> database of options keyed by subcommand or whatever. Although the
You realise we already have such a database? svn_cl__cmd_table in
subversion/svn/svn.c.
> Contrary to popular wisdom, good old troff is the best system there is
Clearly you have a strong opinion on this.
> So: unless you already have a database of options somewhere, I'd
See above.
> To deal with the copyright issue, I would put "Donated to the
> Subversion project by James K. Lowden" or similar in each file in the
> Authors section.
ASF generally recommends against @author tag on source code, but having
an acknowledgement on the compiled documentation might be okay I think
--- especially given that it's pretty common for man pages to carry such
acknowledgements.
Received on 2013-08-08 07:59:09 CEST