From 93e83ff52f3af65023f7a95fb0f79e660603ebe3 Mon Sep 17 00:00:00 2001 From: Pádraig Brady Date: Fri, 27 Nov 2015 11:13:06 +0000 Subject: doc: update to latest help2man Sync with version 1.47.3 which provides these significant changes: - support for reproducible builds by using $SOURCE_DATE_EPOCH. - Adjust spacing of italic text at roman/italic boundaries. --- man/help2man | 74 ++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 19 deletions(-) (limited to 'man/help2man') diff --git a/man/help2man b/man/help2man index fe786ac22..1f90bc537 100755 --- a/man/help2man +++ b/man/help2man @@ -2,7 +2,7 @@ # Generate a short man page from --help and --version output. # Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, -# 2010, 2011, 2012, 2013 Free Software Foundation, Inc. +# 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc. # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -23,11 +23,12 @@ use 5.008; use strict; use Getopt::Long; +use Text::ParseWords qw(shellwords); use Text::Tabs qw(expand); use POSIX qw(strftime setlocale LC_ALL); my $this_program = 'help2man'; -my $this_version = '1.43.3'; +my $this_version = '1.47.3'; sub _ { $_[0] } sub configure_locale @@ -46,12 +47,13 @@ sub N_ { $_[0] } sub program_basename; sub get_option_value; sub convert_option; +sub fix_italic_spacing; my $version_info = enc_user sprintf _(<<'EOT'), $this_program, $this_version; GNU %s %s Copyright (C) 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010, -2011, 2012, 2013 Free Software Foundation, Inc. +2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. @@ -125,7 +127,7 @@ my %include = (); my %replace = (); my %append = (); my %append_match = (); -my @include = (); # retain order given in include file +my @sections = (); # retain order of include file or in-line *section*s # Process include file (if given). Format is: # @@ -190,9 +192,7 @@ while (@opt_include) $hash = \%include; } - push @include, $key - unless $include{$key} or $replace{$key} or $append{$key}; - + push @sections, $key; next; } @@ -221,7 +221,7 @@ while (@opt_include) # handle options if (/^-/) { - local @ARGV = split; + local @ARGV = shellwords $_; GetOptions %opt_def; } @@ -247,11 +247,23 @@ for my $hash (\(%include, %replace, %append, %append_match)) my $help_text = get_option_value $ARGV[0], $help_option; $version_text ||= get_option_value $ARGV[0], $version_option; +# By default the generated manual pages will include the current date. This may +# however be overriden by setting the environment variable $SOURCE_DATE_EPOCH +# to an integer value of the seconds since the UNIX epoch. This is primarily +# intended to support reproducible builds (wiki.debian.org/ReproducibleBuilds) +# and will additionally ensure that the output date string is UTC. +my $epoch_secs = time; +if (exists $ENV{SOURCE_DATE_EPOCH} and $ENV{SOURCE_DATE_EPOCH} =~ /^(\d+)$/) +{ + $epoch_secs = $1; + $ENV{TZ} = 'UTC'; +} + # Translators: the following message is a strftime(3) format string, which in # the English version expands to the month as a word and the full year. It # is used on the footer of the generated manual pages. If in doubt, you may # just use %x as the value (which should be the full locale-specific date). -my $date = enc strftime _("%B %Y"), localtime; +my $date = enc strftime _("%B %Y"), localtime $epoch_secs; my $program = program_basename $ARGV[0]; my $package = $program; my $version; @@ -373,6 +385,7 @@ if ($help_text =~ s/^($PAT_USAGE):( +(\S+))(.*)((?:\n(?: {6}\1| *($PAT_USAGE_CON s/\\fI$//; s/^\./\\&./; + $_ = fix_italic_spacing $_; $synopsis .= "$_\n"; } @@ -426,28 +439,37 @@ s/^Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/mg; while (length) { # Convert some standard paragraph names. - if (s/^($PAT_OPTIONS): *\n//o) + if (s/^($PAT_OPTIONS): *\n+//o) { $sect = _('OPTIONS'); next; } - if (s/^($PAT_ENVIRONMENT): *\n//o) + if (s/^($PAT_ENVIRONMENT): *\n+//o) { $sect = _('ENVIRONMENT'); next; } - if (s/^($PAT_FILES): *\n//o) + if (s/^($PAT_FILES): *\n+//o) { $sect = _('FILES'); next; } - elsif (s/^($PAT_EXAMPLES): *\n//o) + elsif (s/^($PAT_EXAMPLES): *\n+//o) { $sect = _('EXAMPLES'); next; } - # Copyright section + # Custom section indicated by a line containing "*Section Name*". + if (s/^\*(\w(.*\w)?)\* *\n+//) + { + $sect = uc $1; + $sect =~ tr/*/ /; # also accept *Section*Name* + push @sections, $sect; + next; + } + + # Copyright section. if (/^Copyright /) { $sect = _('COPYRIGHT'); @@ -577,6 +599,8 @@ while (length) ) ($|[ ,;.)]) # space/punctuation after !$1\\fI$2\\fP$3!xmg; + + $_ = fix_italic_spacing $_; } # Escape remaining hyphens. @@ -668,14 +692,17 @@ EOT # Section ordering. my @pre = (_('NAME'), _('SYNOPSIS'), _('DESCRIPTION'), _('OPTIONS'), - _('ENVIRONMENT'), _('FILES'), _('EXAMPLES')); - -my @post = (_('AUTHOR'), _('REPORTING BUGS'), _('COPYRIGHT'), _('SEE ALSO')); -my $filter = join '|', @pre, @post; + _('EXAMPLES')); +my @post = (_('ENVIRONMENT'), _('FILES'), _('AUTHOR'), + _('REPORTING BUGS'), _('COPYRIGHT'), _('SEE ALSO')); +my %filter = map { $_ => 1 } @pre, @post; # Output content. -for my $sect (@pre, (grep ! /^($filter)$/o, @include), @post) +my %done; +for my $sect (@pre, (grep !$filter{$_}, @sections), @post) { + next if $done{$sect}++; # ignore duplicates + next unless $include{$sect}; if ($include{$sect}) { my $quote = $sect =~ /\W/ ? '"' : ''; @@ -751,3 +778,12 @@ sub convert_option $_; } + +# Insert spacing escape characters \, and \/ before and after italic text. See +# http://www.gnu.org/software/groff/manual/html_node/Ligatures-and-Kerning.html +sub fix_italic_spacing +{ + local $_ = shift; + s!\\fI(.*?)\\f([BRP])!\\fI\\,$1\\/\\f$2!g; + return $_; +} -- cgit v1.2.3-70-g09d2