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

Pedro Alves
2014-06-23T13:45:55Z

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