[FFmpeg-devel] [PATCH] doc/texi2pod: rework man inclusion logic

[Stefano Sabatini]

On date Monday 2012-12-17 12:37:29 -0500, Derek Buitenhuis encoded:
> On 16/12/2012 11:48 AM, Stefano Sabatini wrote:
> > Ignore @c man begin ... @c man end comments, rely on @chapter for marking
> > the beginning of the various manual sections.
> > 
> > This allows to write markup which is not depending on the specific
> > texi2pod.pl implementation.
> 
> s/allows/allows us/ && s/depending/dependent/
> 
> > This change causes a bit rendering issues, which will be fixed in further
> > patches.
> 

> Do you plan to wait for those before you push?

Yes, I'll push this with the fixing patches together.

Problems are the synopsis wrong rendering due to the HTML/POD hacks,
and Authors and See Also section not displayed because they are
currently in an @ignore block (which per-spec should be ignored for
display directives but is not due to the current @c man being ... @c
man end obfuscated logic). Both are fixed by the synopsys and tool See
Also patch (which still doesn't address the "See Also" chapters in the
other manuals).
 
> > -    # Look for blocks surrounded by @c man begin SECTION ... @c man end.
> > -    # This really oughta be @ifman ... @end ifman and the like, but such
> > -    # would require rev'ing all other Texinfo translators.
> > -    /^\@c\s+man\s+begin\s+([A-Za-z ]+)/ and $sect = $1, push (@sects_sequence, $sect), $output = 1, next;
> > -    /^\@c\s+man\s+end/ and do {
> > -        $sects{$sect} = "" unless exists $sects{$sect};
> > -        $sects{$sect} .= postprocess($section);
> > -        $section = "";
> > -        $output = 0;

> > +    /^\@chapter\s+([A-Za-z ]+)/ and do {
> 
> Don't plan to support numbers in chapter names? (It might be forbidden by the spec,
> for all I know.)

Don't know, but looks unrelated.

> 
> > +        # close old chapter
> > +        $chapters{$chapter_name} .= postprocess($chapter) if ($chapter_name);
> > +
> > +        # start new chapter
> > +        $chapter_name = $1, push (@chapters_sequence, $chapter_name);
> 

> I'm not actually familiar with this particular pattern (the way comma is used).

This one keeps the two instructions in the same statements, it's not
making any difference in this particular instance, it may be useful in
constructs like:
$foo++, next if CONDITION;

where the variable $foo++ is updated *and* the next operator is executed
if CONDITION is true, which is clearly different from:
$foo++; next if CONDITION;

> 
> Rest seems OK, mostly being s/sect/chapter/.
> 
> The script still scares me, though. ;)

Thanks, will push when the other following patches will be approved.
-- 
FFmpeg = Fascinating & Forgiving Mastering Powered Easy Gigant