Re: man pages out of date [was internal/external diff docs and usage]

On Fri, Mar 14, 2003 at 06:45:49PM +0000, Joe Orton wrote:
> On Fri, Mar 14, 2003 at 07:31:57AM -0800, Ben Collins-Sussman wrote:
> > To be honest, I hate seeing all this duplication of documentation:
> >
> > * all our binaries are already self-documenting ('svn help foo')
> >
> > * the man pages potentially contain the same information
> >
> > * chapter 8 of the book has the same information, plus some
> > discussion.
>
> Since Fitz did the <refentry> stuff in chapter 8 of the book, it can be
> transformed directly into man pages if you have the right tools. (It
> almost works with published docbook-xsl releases but you need a few
> tweaks). Sample svn_add.1 attached...
>
> $ xmlto man book.xml
> Writing svn_add.1 for refentry
> Writing svn_cat.1 for refentry
> Writing svn_checkout.1 for refentry
> Writing svn_cleanup.1 for refentry
> Writing svn_commit.1 for refentry
> Writing svn_copy.1 for refentry
> ...

If those can be merged into one big svn.1 ...

> .TH "" "" "" ""

Hmm.

> .SH NAME
> svn add \- Adds files and directories

The LHS of NAME should usually include the basename of the man page
(without the section extension). Another reason why separate man pages
for subcommands should be avoided.

> .SH "SYNOPSIS"
>
> .nf
> svn add PATH [PATH [PATH ... ]]
> .fi

Not great *roff, but maybe that's a function of the source XML.

-- 
Colin Watson                                  [cjwatson@flatline.org.uk]
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org