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

[Pedro Alves <palves at redhat dot com>]

On 06/12/2014 04:35 AM, Mingjie Xing wrote:
> Hi Pedro, thank you for the careful checking.  See the attachment for
> the new patch and the diff result.  Following my comment,
> 
> 2014-06-11 19:39 GMT+08:00 Pedro Alves <palves@redhat.com>:
>> On 06/10/2014 06:56 PM, Eli Zaretskii wrote:
>>
>>> Thanks.  This looks good to me.  If no one objects, it should go in
>>> soon.
>>
>> I applied the patch locally, and noticed some things misrendered in the
>> new man page, like, options are now listed with double quotes instead
>> of being highlighted.  E.g.:
>>
>>        "-help"
>>        "-h"
> 
> This is because the previous man page uses "@table @env" while the
> current Invoke sections uses "@table @code".  I've fixed.
> 
>> This one is preexisting, but note "C@t{++}" in:
>>
>>  "You can use GDB to debug programs written in C, C@t{++}, Fortran and Modula-2."
> 
> This seems that texi2pod is unable to handle "@t".  The problem also
> occurs for the old man page if you build from the current git.

But then we lose formatting on the info pages, right?

Should we re-define it as a macro under ifset man ?

@ifset man
@macro t{text}
\text\
@end macro
@end ifset

(I don't actually know whether possible.)

> 
>> This sentence seems to be out of place:
>>
>>  "You can run GDB in various alternative modes---for example, in batch mode or quiet mode."
> 
> OK, I've put it out.
> 
>> Not sure, but "---" might be misrendered too.
> 
> Hmm, there are many such usage (no space before/afert "--") in gdb.texinfo.

Those three dashes are rendered as an em dash in texinfo:

 http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Conventions.html

I'd assume the man page should end up with \(em instead of literal ---.

Should we have a macro for this too?

> 
>> This incomplete sentence appears, seemingly trying to refer to a chapter
>> in the manual:
>>
>> " For further documentation on startup processing, For documentation on how to write command files,"
> 
> Yes, still seems texi2pod's problem, which simply through away the
> content for @xref/@pxref.  I've changed ", @xref" to ", see @ref" to
> correctly display them in man page.
> 
> Note, that current doc uses @xref after a comma, which is incorrect.
> 
>> At this point, I generated a diff of the old/new man pages, in plain text, with:
>>
>> $ man ./gdb.1 > gdb.1.txt
>> $ man ./gdb.1.new > gdb.1.new.txt
>> $ diff -up gdb.1.txt gdb.1.new.txt
>>
>> I think that's helpful to review this.  The result is below.  Seems there are
>> other odd things in there, like "GDB/MI INTERFACE" in all caps?
> 
> Still texi2pod's problem.  It can't handle correctly the nested form
> "@dfn{@sc{gdb/mi} interface}".  This can be fix by reorder the process
> sequence.  Move
> 
>     s/\@sc\{([^\}]*)\}/\U$1/g;
> 
> before
> 
>     s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g;
> 
> But, what if @sc{@dfn{...}}?

Hopefully Eli can take a new look.  The new resulting output diff
looks much better to me now.  Thanks for doing this.

-- 
Pedro Alves