Re: [patch] Share options between info and man page

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Mon, 7 Jul 2014 07:18:43 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, Pedro Alves <palves@redhat.com>,
> 	gdb-patches@sourceware.org
> 
> > Ping.
> > 
> > 2014-06-26 17:34 GMT+08:00 Mingjie Xing <mingjie.xing@gmail.com>:
> > > I'd like to put an updated patch for both gdb.texinfo and texi2pod.pl,
> > > plus the new comparing result.
> > >
> > > etc/ChangeLog:
> > >
> > >         * texi2pod.pl (postprocess): Move command process for '@sc' to the
> > >         front of '@dfn'.  Add a new command process for '@t{...}', just print
> > >         the content.
> > >
> > > gdb/doc/ChangeLog:
> > >
> > >         * gdb.texinfo (Man Pages): Remove the content of man OPTIONS
> > > gdb, add
> > >         a cross reference to 'Invoking GDB'.
> > >         (Invoking GDB): Share the option sub-sections with man OPTIONS
> > > gdb,
> > >         move the uniqe part of man here.  To display correrctly in man
> > > page,
> > >         change '@xref' after a comma to 'see @ref', and change '@table
> > > @code'
> > >         to '@table @env'.
> 
> This is a documentation patch, so best to attract the documentation
> maintainer's attention by adding something like "DOCO" in the email
> subject.

Frankly, I just don't know what to do with this patch.

I don't know enough Perl to judge the texi2pod.pl patch, and don't
intend to learn Perl just for that purpose.  On top of that, this
whole "produce man pages from Texinfo" business was sold to us on the
assumption that "it makes maintenance simpler" (see
https://sourceware.org/ml/gdb-patches/2013-02/msg00290.html and the
discussions around it).  To me this means that we put a bunch of
telltale markers into the Texinfo files, add a few Makefile rules, and
promptly forget everything we knew about that.

But now it sounds like this arrangement is not simple at all, that we
need non-trivial changes to follow (which will probably stump someone
at some point, and perhaps even be changed and break the man-page
generation), we need to maintain texi2pod.pl, and whatnot else.  And
I'm the person who needs to be responsible for it.

So I'm beginning to doubt that this is for the better.

Thoughts?