Re: Generation process for cpp.1

Re: Generation process for cpp.1

[Richard Kenner]

    \fP has been in every nroff/troff implemenation I have ever seen, and
    I used to use it regularly in some roff stuff I wrote back in 1984 or
    before.  (OK, I'm old).  Also, it's used heavily to implement the
    various macro packages.

I'm pretty sure it's quite a bit older than that, at least since 1980.

Re: Generation process for cpp.1

[Joe Buck]

> > Um, no, I meant \fP, which switches to the previous font.  This only
> > works if there's been exactly one font change, if you do a second one
> > you're hosed.
> 
> Oh... I didn't know you could do that.  Do you know how widespread support
> for that is?  It's not in the troff paper ...

\fP has been in every nroff/troff implemenation I have ever seen, and
I used to use it regularly in some roff stuff I wrote back in 1984 or
before.  (OK, I'm old).  Also, it's used heavily to implement the
various macro packages.

It is not an extension.  But there is no stack, it remembers only one
previous font.

Re: Generation process for cpp.1

[Russ Allbery]

Zack Weinberg <zackw@Stanford.EDU> writes:
> On Mon, Nov 13, 2000 at 09:24:27AM -0800, Russ Allbery wrote:
>> Zack Weinberg <zackw@Stanford.EDU> writes:

>>> Yes.  This is still a problem with podlators-1.04.

>>> .Sh "Brief description of \f(CW\*(C`gcov\*(C'\fR data files"

>>> I think the final \fR should be \fP.

>> \fB, you mean?  Ugh... this is a real mess.  That puts pod2man in the
>> situation of having to know what font the underlying macros are using
>> for a minor section header, and it could legitimately differ between
>> different man implementations.

> Um, no, I meant \fP, which switches to the previous font.  This only
> works if there's been exactly one font change, if you do a second one
> you're hosed.

Oh... I didn't know you could do that.  Do you know how widespread support
for that is?  It's not in the troff paper, which is what I normally use as
a reference manual for figuring out what I can do (I don't trust groff to
mark things that are GNU extensions).  That *might* give me enough
leverage to solve the common case, although it couldn't handle a more
complicated case of markup in headings.  I think I can see how to use this
in the font mapping code, though.  Maybe.

> Well, it *does* actually, it's just only one change deep.  But no
> argument from me here... and it's not just fonts, either.

*roff is a really nasty markup language in a bunch of ways.  I still like
it a bit better than HTML, but it's close (and from me, that's a pretty
negative opinion; I utterly detest HTML).

> I didn't know about -s, but I tested this with 'nroff -man
> /usr/man/man1/whatever.1 | less' so that's not a concern.  I only see
> the blank lines with pod2man-generated pages.  Also, for some reason I
> don't get a page footer except with pod2man-generated pages.  It's
> probably a bug in my tmac.an.

pod2man generates a full .TH line.  Maybe that's the difference?  I've
seen a lot of vendor man pages that only give .TH the first two (required)
arguments of page title and section and leave off the additional
parameters.

-- 
Russ Allbery (rra@stanford.edu)             < http://www.eyrie.org/~eagle/ >

Re: Generation process for cpp.1

[Zack Weinberg]

On Mon, Nov 13, 2000 at 09:24:27AM -0800, Russ Allbery wrote:
> Zack Weinberg <zackw@Stanford.EDU> writes:
> 
> > Yes.  This is still a problem with podlators-1.04.
> 
> > .Sh "Brief description of \f(CW\*(C`gcov\*(C'\fR data files"
> 
> > I think the final \fR should be \fP.
> 
> \fB, you mean?  Ugh... this is a real mess.  That puts pod2man in the
> situation of having to know what font the underlying macros are using for
> a minor section header, and it could legitimately differ between different
> man implementations.

Um, no, I meant \fP, which switches to the previous font.  This only
works if there's been exactly one font change, if you do a second one
you're hosed.

> Bleh.
> 
> This isn't the first time that I've realized that *roff made a really bad
> mistake by not having a stack of font changes that could be popped off,
> only an escape to set the font to something in particular.

Well, it *does* actually, it's just only one change deep.  But no
argument from me here... and it's not just fonts, either.

> > There is also a lengthy block of blank lines at the end of the nroffed
> > manpage.  I don't know where they come from, but they only show up in
> > pod2man-generated manpages, and not all of them either...
> 
> Hm.  I don't know why it would only show up in pod2man man pages.  I tend
> to see that all the time with all man pages when using a pager without the
> -s option (which man normally adds to the pager invocation to squeeze out
> blank lines) as *roff tries to fill out the last "page" with blank lines.

I didn't know about -s, but I tested this with 'nroff -man
/usr/man/man1/whatever.1 | less' so that's not a concern.  I only see
the blank lines with pod2man-generated pages.  Also, for some reason I
don't get a page footer except with pod2man-generated pages.  It's
probably a bug in my tmac.an.

zw

Re: Generation process for cpp.1

[Russ Allbery]

Zack Weinberg <zackw@Stanford.EDU> writes:

> Yes.  This is still a problem with podlators-1.04.

> .Sh "Brief description of \f(CW\*(C`gcov\*(C'\fR data files"

> I think the final \fR should be \fP.

\fB, you mean?  Ugh... this is a real mess.  That puts pod2man in the
situation of having to know what font the underlying macros are using for
a minor section header, and it could legitimately differ between different
man implementations.

Bleh.

This isn't the first time that I've realized that *roff made a really bad
mistake by not having a stack of font changes that could be popped off,
only an escape to set the font to something in particular.

> I've also noticed a problem with mysterious blank lines in the output.

[...]

> when nroffed.  I *think* this is actually a page break.

I'm pretty sure it is, yeah.

> There is also a lengthy block of blank lines at the end of the nroffed
> manpage.  I don't know where they come from, but they only show up in
> pod2man-generated manpages, and not all of them either...

Hm.  I don't know why it would only show up in pod2man man pages.  I tend
to see that all the time with all man pages when using a pager without the
-s option (which man normally adds to the pager invocation to squeeze out
blank lines) as *roff tries to fill out the last "page" with blank lines.

-- 
Russ Allbery (rra@stanford.edu)             < http://www.eyrie.org/~eagle/ >

Re: Generation process for cpp.1

[Zack Weinberg]

On Sun, Nov 12, 2000 at 11:44:36PM +0000, Joseph S. Myers wrote:
> On Sun, 12 Nov 2000, Zack Weinberg wrote:
> 
> > > Can't locate object method "U" via package "gnu" at ../texi2pod.pl line 58, <STDIN> line 105.
> >
> > *bonk* Take the 'e' modifier off this line:
> >
> > 	s/\@sc\{([^\}]*)\}/\U$1/eg;
> 
> With this patch (using unmodified pod2man from Perl 5.6.0), I get a
> reasonable manpage from gcov.texi.  When I try to extend the manpage to
> cover the whole of gcov.texi, I notice:
> 
> * It doesn't remove @node lines.

Add

    /^\@node/ and next;

right after 

    /^\@need/ and next;


> * The line
> 
> =head2 Brief description of C<gcov> data files
> 
> comes out oddly in the nroff output.  This would seem to be a pod2man
> problem: at the end of the C<...>, the standard font rather than the font
> used in the header gets restored.

Yes.  This is still a problem with podlators-1.04.

.Sh "Brief description of \f(CW\*(C`gcov\*(C'\fR data files"

I think the final \fR should be \fP.

I've also noticed a problem with mysterious blank lines in the output.
For instance:

.Ip "\fB\-x c\fR" 4
.IX Item "-x c"
.PD 0
.Ip "\fB\-x c++\fR" 4
.IX Item "-x c++"
.Ip "\fB\-x objective-c\fR" 4
.IX Item "-x objective-c"
.Ip "\fB\-x assembler-with-cpp\fR" 4
.IX Item "-x assembler-with-cpp"
.PD

gives

       -x c
       -x c++


       -x objective-c
       -x assembler-with-cpp

when nroffed.  I *think* this is actually a page break.  My copy of
tmac.an has some strange hack in it to prevent headers and footers
from showing up except at the very top and bottom of the text, but it
doesn't quite work.

There is also a lengthy block of blank lines at the end of the nroffed
manpage.  I don't know where they come from, but they only show up in
pod2man-generated manpages, and not all of them either...

zw

Re: Generation process for cpp.1

[Joseph S. Myers]

On Sun, 12 Nov 2000, Zack Weinberg wrote:

> > Can't locate object method "U" via package "gnu" at ../texi2pod.pl line 58, <STDIN> line 105.
>
> *bonk* Take the 'e' modifier off this line:
>
> 	s/\@sc\{([^\}]*)\}/\U$1/eg;

With this patch (using unmodified pod2man from Perl 5.6.0), I get a
reasonable manpage from gcov.texi.  When I try to extend the manpage to
cover the whole of gcov.texi, I notice:

* It doesn't remove @node lines.

* The line

=head2 Brief description of C<gcov> data files

comes out oddly in the nroff output.  This would seem to be a pod2man
problem: at the end of the C<...>, the standard font rather than the font
used in the header gets restored.

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: Generation process for cpp.1

[Zack Weinberg]

On Sun, Nov 12, 2000 at 11:04:50PM +0000, Joseph S. Myers wrote:
> On Sun, 12 Nov 2000, Zack Weinberg wrote:
> 
> > Give this patch a spin?  It should handle everything you listed.
> 
> Sorry, running it on my modified gcov.texi gives
> 
> Can't locate object method "U" via package "gnu" at ../texi2pod.pl line 58, <STDIN> line 105.

*bonk* Take the 'e' modifier off this line:

	s/\@sc\{([^\}]*)\}/\U$1/eg;

zw

Re: Generation process for cpp.1

[Joseph S. Myers]

On Sun, 12 Nov 2000, Zack Weinberg wrote:

> Give this patch a spin?  It should handle everything you listed.

Sorry, running it on my modified gcov.texi gives

Can't locate object method "U" via package "gnu" at ../texi2pod.pl line 58, <STDIN> line 105.

The section ending with line 105 is:

@c man begin DESCRIPTION

@code{gcov} is a test coverage program.  Use it in concert with @sc{gnu}
CC to analyze your programs to help create more efficient, faster
running code.  You can use @code{gcov} as a profiling tool to help
discover where your optimization efforts will best affect your code.  You
can also use @code{gcov} along with the other profiling tool,
@code{gprof}, to assess which parts of your code use the greatest amount
of computing time.

Profiling tools help you analyze your code's performance.  Using a
profiler such as @code{gcov} or @code{gprof}, you can find out some
basic performance statistics, such as:

@itemize @bullet
@item
how often each line of code executes

@item
what lines of code are actually executed

@item
how much computing time each section of code uses
@end itemize

Once you know these things about how your code works when compiled, you
can look at each module to see which modules should be optimized.
@code{gcov} helps you determine where to work on optimization.

Software developers also use coverage testing in concert with
testsuites, to make sure software is actually good enough for a release.
Testsuites can verify that a program works as expected; a coverage
program tests to see how much of the program is exercised by the
testsuite.  Developers can then determine what kinds of test cases need
to be added to the testsuites to create both better testing and a better
final product.

You should compile your code without optimization if you plan to use
@code{gcov} because the optimization, by combining some lines of code
into one function, may not give you as much information as you need to
look for `hot spots' where the code is using a great deal of computer
time.  Likewise, because @code{gcov} accumulates statistics by line (at
the lowest resolution), it works best with a programming style that
places only one statement on each line.  If you use complicated macros
that expand to loops or to other control structures, the statistics are
less helpful---they only report on the line where the macro call
appears.  If your complex macros behave like functions, you can replace
them with inline functions to solve this problem.

@code{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which
indicates how many times each line of a source file @file{@var{sourcefile}.c}
has executed.  You can use these logfiles along with @code{gprof} to aid
in fine-tuning the performance of your programs.  @code{gprof} gives
timing information you can use along with the information you get from
@code{gcov}.

@code{gcov} works only on code compiled with @sc{gnu} CC.  It is not
compatible with any other profiling or test coverage mechanism.

@c man end

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: Generation process for cpp.1

[Zack Weinberg]

On Sat, Nov 11, 2000 at 11:00:56PM +0000, Joseph S. Myers wrote:
> On Sat, 11 Nov 2000, Zack Weinberg wrote:
> 
> > months back; pl-1.04 has it.  This is no big deal.  I also found a
> > number of bugs in the texi2pod script, heh.
> 
> While fixing things in texi2pod.pl, you might look at the following, which
> I think would be useful for generating more manpages with it:
[list]

Give this patch a spin?  It should handle everything you listed.

zw

===================================================================
Index: texi2pod.pl
--- texi2pod.pl	1999/09/04 15:08:53	1.2
+++ texi2pod.pl	2000/11/12 22:51:42
@@ -4,64 +4,146 @@
 # markup to Perl POD format.  It's intended to be used to extract
 # something suitable for a manpage from a Texinfo document.
 
-$in = $ARGV[0];
-$out = "x";
-die "usage: $0 infile outfile\n" unless defined $in && defined $out;
-
-close STDIN;
-open(IN,$in);
-
 $output = 0;
 $ignore = 0;
+$skipping = 0;
 %sects = ();
 $section = "";
 @icstack = ();
 @endwstack = ();
+@skstack = ();
 $shift = "";
+%defs = ();
 
-while(<IN>)
+while($_ = shift)
 {
+    if (/^-D(.*)$/) {
+	if ($1 ne "") {
+	    $flag = $1;
+	} else {
+	    $flag = shift;
+	}
+	die "no flag specified for -D\n"
+	    unless $flag ne "";
+	die "flags may only contain letters, digits, hyphens, and underscores\n"
+	    unless $flag =~ /^[a-zA-Z0-9_-]+$/;
+	$defs{$flag} = "";
+    } elsif (/^-/) {
+	usage();
+    } else {
+	$in = $_, next unless defined $in;
+	$out = $_, next unless defined $out;
+	usage();
+    }
+}
+
+if (defined $in) {
+    open(STDIN, $in) or die "opening \"$in\": $!\n";
+}
+if (defined $out) {
+    open(STDOUT, ">$out") or die "opening \"$out\": $!\n";
+}
+
+while(<STDIN>)
+{
     chomp;
-    /^\@end ignore/ and $ignore = 0, next;
-    next if $ignore;
     /^\@c man begin ([A-Z]+)/ and $sect = $1, $output = 1, next;
     /^\@c man end/ and do {
 	$_ = $section;
-	s/</&lt;/g;
-	s/>/&gt;/g;
 
 	s/\@(?:dfn|var|emph|cite)\{([^\}]*)\}/I<$1>/g;
 	s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g;
 	s/\@(?:samp|strong|key)\{([^\}]*)\}/B<$1>/g;
+	s/\@value\{([a-zA-Z0-9_-]+)\}/$defs{$1}/g;
+	s/\@sc\{([^\}]*)\}/\U$1/eg;
 	s/\@file\{([^\}]*)\}/F<$1>/g;
 	s/\@(?:url|email)\{([^\}]*)\}/E<lt>C<$1>E<rt>/g;
-	s/\@[a-z]?ref\{(?:[^\}]*)\}.?//g;
-	s/\(\@p[a-z]?ref\{(?:[^\}]*)\}\).?//g;
+	s/\@xref\{(?:[^\}]*)\}[^.]*.//g;
+	s/\s+\(\@p[a-z]?ref\{(?:[^\}]*)\}\)//g;
 	s/\@copyright\{\}//g;
 	s/\@noindent\s*//g;
 	s/\@refill//g;
 	s/\@\././g;
 
-	s/&lt;/E<lt>/g;
-	s/&gt;/E<gt>/g;
+	# Turn B<blah I<blah> blah> into B<blah> I<blah> B<blah> to
+	# match Texinfo semantics of @emph inside @samp.
+
 	s/&LT;/</g;
 	s/&GT;/>/g;
+	1 while (s/B<([^<>]*)I<([^>]+)>/B<$1>I<$2>B</g);
+	1 while (s/I<([^<>]*)B<([^>]+)>/I<$1>B<$2>I</g);
+	s/[BI]<>//g;
+	s/([BI])<(\s+)([^>]+)>/$2$1<$3>/g;
+	s/([BI])<([^>]+?)(\s+)>/$1<$2>$3/g;
 
+	s/&lt;/E<lt>/g;
+	s/&gt;/E<gt>/g;
+	s/&lbrace;/\{/g;
+	s/&rbrace;/\}/g;
+
 	$sects{$sect} = $_;
 	$section = "";
 	$output = 0;
 	next;
     };
-    
+
     /^\@(c|[a-z]+index)\b/ and next;
+    /^\@subsection/ and next;
+    /^\@need/ and next;
 
     /^\@setfilename\s+([^.]+)/ and $fn = $1, next;
     /^\@settitle\s+([^.]+)/ and $tl = $1, next;
 
     next unless $output;
 
+    /^\@end\s+([a-z]+)/ and do {
+	if(defined $endw)
+	{
+	    die "\@$endw ended by \@end $1 at line $.\n"
+		unless $1 eq $endw;
+
+	    if($endw =~ /example$/)
+	    {
+		$shift = "";
+		$_ = "";
+	    }
+	    elsif($endw =~ /^if/)
+	    {
+		$skipping = pop @skstack;
+		$_ = "";
+	    }
+	    else
+	    {
+		$_ = "\n=back\n";
+		$ic = pop @icstack;
+	    }
+	    $endw = pop @endwstack;
+	}
+    };
+
+    /^\@end ignore/ and $ignore = 0, next;
+    next if $ignore;
+    next if $skipping;
+
     /^\@ignore/ and $ignore = 1, next;
 
+    /^\@set\s+([a-zA-Z0-9_-]+)\s*(.*)$/ and $defs{$1} = $2, next;
+    /^\@clear\s+([a-zA-Z0-9_-]+)/ and delete $defs{$1}, next;
+
+    /^\@ifset\s+([a-zA-Z0-9_-]+)/ and do {
+	push @endwstack, $endw;
+	push @skstack, $skipping;
+	$endw = "ifset";
+	$skipping = 1 unless exists $defs{$1};
+    };
+
+    /^\@ifclear\s+([a-zA-Z0-9_-]+)/ and do {
+	push @endwstack, $endw;
+	push @skstack, $skipping;
+	$endw = "ifset";
+	$skipping = 1 if exists $defs{$1};
+    };
+
     /^\@itemize (\@[a-z]+)/ and do {
 	push @endwstack, $endw;
 	push @icstack, $ic;
@@ -99,27 +181,6 @@ while(<IN>)
 	next;
     };
 
-    /^\@end\s+([a-z]+)/ and do {
-	if(defined $endw)
-	{
-	    die "\@$endw ended by \@end $1 at line $.\n"
-		unless $1 eq $endw;
-
-	    if($endw =~ /example$/)
-	    {
-		$shift = "";
-		$_ = "";
-	    }
-	    else
-	    {
-		$_ = "\n=back\n";
-		undef $endw;
-		$ic = pop @icstack;
-	    }
-	    $endw = pop @endwstack;
-	}
-    };
-
     /^\@itemx?\s*(.+)?$/ and do {
 	if(defined $1)
 	{
@@ -130,8 +191,22 @@ while(<IN>)
 	    $_ = "=item $ic\n";
 	    $ic =~ y/A-Ya-y1-8/B-Zb-z2-9/;
 	}
+    };
+
+    /^\@section\s+(.+)$/ and do {
+	$_ = "\n=head2 $1\n";
     };
-	
+
+    # POD doesn't interpret E<> inside a verbatim block.
+    if ($shift eq "") {
+	s/</&lt;/g;
+	s/>/&gt;/g;
+    } else {
+	s/</&LT;/g;
+	s/>/&GT;/g;
+    }
+    s/\@\{/&lbrace;/g;
+    s/\@\}/&rbrace;/g;
     $section .= $shift.$_."\n";
 }
 
@@ -148,4 +223,9 @@ for $sect (qw(NAME SYNOPSIS DESCRIPTION 
 	print $sects{$sect};
 	print "\n";
     }
+}
+
+sub usage
+{
+    die "usage: $0 [-D toggle...] [infile [outfile]]\n";
 }

Re: Generation process for cpp.1

[Zack Weinberg]

On Sat, Nov 11, 2000 at 08:12:31PM -0800, Russ Allbery wrote:
> Zack Weinberg <zackw@Stanford.EDU> writes:

> > What I actually *want* is what .BI does, i.e.
> 
> > .Ip "\fB\-A \fIpredicate\fB=\fIanswer\fR" 4
> 
> > I know I could get this by emitting
> 
> > =item B<-A> I<predicate>B<=>I<answer>
> 
> > but it's quite difficult to get there from the texinfo input.  (I might
> > add that the new rendering, with \f(BI, looks just fine when rendered
> > into Postscript.  The trouble is that nroff renders \f(BI identically
> > with \fB.  Or rather, less renders "_^Hp^Hp" as bold, not bold and
> > underlined.)
> 
> Hurm.  I'm not really sure what to do about this.  That POD asks for both
> bold and italic text, and *roff has a font for both bold and italic, which
> is what pod2man is giving.  The old pod2man was technically incorrect
> there, not producing the fonts warranted by the markup.

I found a way to generate POD that does what I want, with sufficiently
clever regexps.  It doesn't help readability, but texi2pod is all
clever regexps anyway.

> It really feels to me like this is a bug in less, as bold underlined text
> is possible in at least xterms and can be set with the standard ANSI
> escape sequences for character attributes.

Agree.

> > I also have a problem with `scare quotes', since X 4.0 has decided that
> > ' is to be vertical.  No solution, though.  It may be possible to
> > bludgeon the fonts into restoring a tilted-right '.
> 
> The next version of podlators will default to using "" instead of `'
> because of this issue, with a command-line option allowing you to set the
> quotes to anything that you want.

Okay, that works for me.  Thanks.

zw

Re: Generation process for cpp.1

[Russ Allbery]

Zack Weinberg <zackw@Stanford.EDU> writes:

> There's one remaining concern with 5.6.0+ pod2man.  texi2pod generates
> lines like this:

> =item B<-A I<predicate>=I<answer>>

> which is rendered as 

> .Ip "\fB\-A \f(BIpredicate\fB=\f(BIanswer\fB\fR" 4

> by pod2man.  The old one used to generate

> .Ip "\fB\-A \fIpredicate\fR=\fIanswer\fR\fR" 4

> What I actually *want* is what .BI does, i.e.

> .Ip "\fB\-A \fIpredicate\fB=\fIanswer\fR" 4

> I know I could get this by emitting

> =item B<-A> I<predicate>B<=>I<answer>

> but it's quite difficult to get there from the texinfo input.  (I might
> add that the new rendering, with \f(BI, looks just fine when rendered
> into Postscript.  The trouble is that nroff renders \f(BI identically
> with \fB.  Or rather, less renders "_^Hp^Hp" as bold, not bold and
> underlined.)

Hurm.  I'm not really sure what to do about this.  That POD asks for both
bold and italic text, and *roff has a font for both bold and italic, which
is what pod2man is giving.  The old pod2man was technically incorrect
there, not producing the fonts warranted by the markup.

It really feels to me like this is a bug in less, as bold underlined text
is possible in at least xterms and can be set with the standard ANSI
escape sequences for character attributes.

> I also have a problem with `scare quotes', since X 4.0 has decided that
> ' is to be vertical.  No solution, though.  It may be possible to
> bludgeon the fonts into restoring a tilted-right '.

The next version of podlators will default to using "" instead of `'
because of this issue, with a command-line option allowing you to set the
quotes to anything that you want.

-- 
Russ Allbery (rra@stanford.edu)             < http://www.eyrie.org/~eagle/ >

Re: Generation process for cpp.1

[Joseph S. Myers]

On Sat, 11 Nov 2000, Joseph S. Myers wrote:

> While fixing things in texi2pod.pl, you might look at the following, which
> I think would be useful for generating more manpages with it:

Also (from testing on gcov.texi as a simple case), could you remove @need
lines as well, and handle @sc{}?

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: Generation process for cpp.1

[Joseph S. Myers]

On Sat, 11 Nov 2000, Zack Weinberg wrote:

> months back; pl-1.04 has it.  This is no big deal.  I also found a
> number of bugs in the texi2pod script, heh.

While fixing things in texi2pod.pl, you might look at the following, which
I think would be useful for generating more manpages with it:

* Do something sensible with section/node headers within the man sections
- it would probably make sense to convert either the section or the node
name into =head2.  (invoke.texi is long enough that keeping some of its
internal headers would seem to make sense.)

* When removing cross-references (@xref), cut out the whole sentence -
since there may be trailing wording after the @xref which doesn't make
sense without the @xref itself, and the whole cross-reference probably
points outside the manpage anyway (presumably the reason for removing the
@xref).

* Some sort of way of handling @ifset INTERNALS / @ifclear INTERNALS will
be needed.

-- 
Joseph S. Myers
jsm28@cam.ac.uk

Re: Generation process for cpp.1

[Zack Weinberg]

On Fri, Nov 10, 2000 at 11:32:15PM -0800, Russ Allbery wrote:
> Zack Weinberg <zackw@Stanford.EDU> writes:
> 
> > This is because the amount of hand adjustment needed varies depending on
> > which version of pod2man you have.  I've been in touch with the pod2man
> > maintainer; the version in perl 5.6 supposedly only has cosmetic issues,
> > and 5.6.1-to-be shouldn't need any adjustment at all.
> 
> Folks who want to work on this can get the latest version of pod2man as
> part of the podlators package on either CPAN or ftp.eyrie.org in
> /pub/software/modules.  I'll be happy to work with anyone to improve the
> output quality if anything else turns up; Zack's help in reporting things
> it was doing that weren't ideal has improved the output quality quite a
> bit.

I just ran through some tests with 5.6.0's pod2man and podlators-1.04.
The version in 5.6.0 lacks the .PD 0/.PD feature we discussed a couple
months back; pl-1.04 has it.  This is no big deal.  I also found a
number of bugs in the texi2pod script, heh.

There's one remaining concern with 5.6.0+ pod2man.  texi2pod generates
lines like this:

=item B<-A I<predicate>=I<answer>>

which is rendered as 

.Ip "\fB\-A \f(BIpredicate\fB=\f(BIanswer\fB\fR" 4

by pod2man.  The old one used to generate

.Ip "\fB\-A \fIpredicate\fR=\fIanswer\fR\fR" 4

What I actually *want* is what .BI does, i.e.

.Ip "\fB\-A \fIpredicate\fB=\fIanswer\fR" 4

I know I could get this by emitting

=item B<-A> I<predicate>B<=>I<answer>

but it's quite difficult to get there from the texinfo input.  (I
might add that the new rendering, with \f(BI, looks just fine when
rendered into Postscript.  The trouble is that nroff renders \f(BI
identically with \fB.  Or rather, less renders "_^Hp^Hp" as bold,
not bold and underlined.)

I also have a problem with `scare quotes', since X 4.0 has decided
that ' is to be vertical.  No solution, though.  It may be possible to
bludgeon the fonts into restoring a tilted-right '.

> Should be in the current Perl 5.7.0; I'm not sure how unstable unstable
> wants to be.  It should be in 5.6.1 as well, but we've been waiting for
> that release for a while.

unstable just now picked up 5.6.0; they'll probably move to 5.6.1 as
soon as it shows up.  (Debian tends to have very long lead times on
picking up major releases, but almost-immediate takeup on patch
releases.)

zw

Re: Generation process for cpp.1

[Russ Allbery]

Zack Weinberg <zackw@Stanford.EDU> writes:

> This is because the amount of hand adjustment needed varies depending on
> which version of pod2man you have.  I've been in touch with the pod2man
> maintainer; the version in perl 5.6 supposedly only has cosmetic issues,
> and 5.6.1-to-be shouldn't need any adjustment at all.

Folks who want to work on this can get the latest version of pod2man as
part of the podlators package on either CPAN or ftp.eyrie.org in
/pub/software/modules.  I'll be happy to work with anyone to improve the
output quality if anything else turns up; Zack's help in reporting things
it was doing that weren't ideal has improved the output quality quite a
bit.

(I'm the pod2man maintainer.)

> I've been waiting for a version of pod2man that doesn't need any hand
> editing to turn up in Debian unstable.  Then I'll put in a Makefile
> target.

Should be in the current Perl 5.7.0; I'm not sure how unstable unstable
wants to be.  It should be in 5.6.1 as well, but we've been waiting for
that release for a while.

-- 
Russ Allbery (rra@stanford.edu)             < http://www.eyrie.org/~eagle/ >

Re: Generation process for cpp.1

[Zack Weinberg]

On Fri, Nov 10, 2000 at 05:16:25PM -0200, Alexandre Oliva wrote:
> On Nov 10, 2000, "Joseph S. Myers" <jsm28@cam.ac.uk> wrote:
> 
> > The manpage cpp.1 is created from cpp.texi using contrib/texi2pod.pl plus
> > pod2man and hand adjustments
> 
> Maybe we should use help2man instead, so that the man-page contains
> just the list of available options and points to the manual for more
> information?

help2man should be used only if no other alternative exists, IMO.  Its
output provides less information than a proper man page should have,
and is condescending to boot.

zw

Re: Generation process for cpp.1

[Joe Buck]

> Maybe we should use help2man instead, so that the man-page contains
> just the list of available options and points to the manual for more
> information?

invoke.texi has roughly the type of information one would want in a man
page, so if it can be auto-generated it will be kept current.

Re: Generation process for cpp.1

[Alexandre Oliva]

On Nov 10, 2000, "Joseph S. Myers" <jsm28@cam.ac.uk> wrote:

> The manpage cpp.1 is created from cpp.texi using contrib/texi2pod.pl plus
> pod2man and hand adjustments

Maybe we should use help2man instead, so that the man-page contains
just the list of available options and points to the manual for more
information?

-- 
Alexandre Oliva   Enjoy Guarana', see http://www.ic.unicamp.br/~oliva/
Red Hat GCC Developer                  aoliva@{cygnus.com, redhat.com}
CS PhD student at IC-Unicamp        oliva@{lsd.ic.unicamp.br, gnu.org}
Free Software Evangelist    *Please* write to mailing lists, not to me

Re: Generation process for cpp.1

[Zack Weinberg]

On Fri, Nov 10, 2000 at 04:42:43PM +0000, Joseph S. Myers wrote:
> The manpage cpp.1 is created from cpp.texi using contrib/texi2pod.pl plus
> pod2man and hand adjustments, but the precise process (including details
> of the adjustments needed) doesn't seem to be documented.

This is because the amount of hand adjustment needed varies depending
on which version of pod2man you have.  I've been in touch with the
pod2man maintainer; the version in perl 5.6 supposedly only has
cosmetic issues, and 5.6.1-to-be shouldn't need any adjustment at all.

Anyway, you just do 

contrib/texi2pod.pl < cpp.texi >cpp.pod
pod2man --center="GNU" --release="gcc-3.0" --section=1 cpp.pod > cpp.new.1

and then you run the result through nroff and see if it's okay.  If it
isn't, you edit it.

> I'm wondering about the possibility of using this script to replace
> the hopelessly out of date gcc.1 manpage with something generated
> from invoke.texi.

Cool idea.

The key to making this work is magic comments in cpp.texi.  If you
have

@c man begin DESCRIPTION
...
@c man end

around a chunk of text, that chunk becomes the DESCRIPTION section of
the manpage.  In some cases, you don't want it showing up in the Info
file; then you just put @ignore ... @end ignore around the magic
comments.  (The SYNOPSIS and SEE ALSO sections of cpp.1 are done thus.)

> would it be possible for the exact process to be documented,
> e.g. with an appropriate Makefile target to regenerate cpp.1 and
> another script in contrib to do what were the hand adjustments to
> the output?

I've been waiting for a version of pod2man that doesn't need any hand
editing to turn up in Debian unstable.  Then I'll put in a Makefile
target.

It hasn't historically been possible to automate the edits, they
usually involve aesthetic problems that a script can't really detect.

zw

Generation process for cpp.1

[Joseph S. Myers]

The manpage cpp.1 is created from cpp.texi using contrib/texi2pod.pl plus
pod2man and hand adjustments, but the precise process (including details
of the adjustments needed) doesn't seem to be documented.  I'm wondering
about the possibility of using this script to replace the hopelessly out
of date gcc.1 manpage with something generated from invoke.texi; would it
be possible for the exact process to be documented, e.g. with an
appropriate Makefile target to regenerate cpp.1 and another script in
contrib to do what were the hand adjustments to the output?

-- 
Joseph S. Myers
jsm28@cam.ac.uk