summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/amhello/Makefile.am2
-rw-r--r--doc/amhello/configure.ac2
-rw-r--r--doc/amhello/src/Makefile.am2
-rw-r--r--doc/amhello/src/main.c2
-rw-r--r--doc/automake-history.texi2
-rw-r--r--doc/automake.texi49
-rw-r--r--doc/fdl.texi2
-rwxr-xr-xdoc/help2man254
-rw-r--r--doc/local.mk (renamed from doc/Makefile.inc)16
9 files changed, 220 insertions, 111 deletions
diff --git a/doc/amhello/Makefile.am b/doc/amhello/Makefile.am
index 706c2f298..9ad1b8759 100644
--- a/doc/amhello/Makefile.am
+++ b/doc/amhello/Makefile.am
@@ -1,4 +1,4 @@
-# Copyright (C) 2006-2017 Free Software Foundation, Inc.
+# Copyright (C) 2006-2018 Free Software Foundation, Inc.
# This Makefile.am is free software; the Free Software Foundation
# gives unlimited permission to copy, distribute and modify it.
diff --git a/doc/amhello/configure.ac b/doc/amhello/configure.ac
index 381344d7a..dd810745d 100644
--- a/doc/amhello/configure.ac
+++ b/doc/amhello/configure.ac
@@ -1,4 +1,4 @@
-# Copyright (C) 2006-2017 Free Software Foundation, Inc.
+# Copyright (C) 2006-2018 Free Software Foundation, Inc.
# This configure.ac script is free software; the Free Software Foundation
# gives unlimited permission to copy, distribute and modify it.
diff --git a/doc/amhello/src/Makefile.am b/doc/amhello/src/Makefile.am
index e52ff3c3b..80c093371 100644
--- a/doc/amhello/src/Makefile.am
+++ b/doc/amhello/src/Makefile.am
@@ -1,4 +1,4 @@
-# Copyright (C) 2006-2017 Free Software Foundation, Inc.
+# Copyright (C) 2006-2018 Free Software Foundation, Inc.
# This Makefile.am is free software; the Free Software Foundation
# gives unlimited permission to copy, distribute and modify it.
diff --git a/doc/amhello/src/main.c b/doc/amhello/src/main.c
index 7a7ebec77..11a45ab17 100644
--- a/doc/amhello/src/main.c
+++ b/doc/amhello/src/main.c
@@ -1,4 +1,4 @@
-/* Copyright (C) 2006-2017 Free Software Foundation, Inc.
+/* Copyright (C) 2006-2018 Free Software Foundation, Inc.
This program is free software; the Free Software Foundation
gives unlimited permission to copy, distribute and modify it. */
diff --git a/doc/automake-history.texi b/doc/automake-history.texi
index 75141f97a..417149e33 100644
--- a/doc/automake-history.texi
+++ b/doc/automake-history.texi
@@ -10,7 +10,7 @@
This manual describes (part of) the history of GNU Automake, a program
that creates GNU standards-compliant Makefiles from template files.
-Copyright @copyright{} 1995-2017 Free Software Foundation, Inc.
+Copyright @copyright{} 1995-2018 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
diff --git a/doc/automake.texi b/doc/automake.texi
index da0aa2942..2df214a01 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -25,7 +25,7 @@ This manual is for GNU Automake (version @value{VERSION},
@value{UPDATED}), a program that creates GNU standards-compliant
Makefiles from template files.
-Copyright @copyright{} 1995-2017 Free Software Foundation, Inc.
+Copyright @copyright{} 1995-2018 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@@ -2277,7 +2277,7 @@ support new architectures and fix probes broken by changes in new
kernel versions. Each new release of Automake comes with up-to-date
copies of these programs. If your copy of Automake is getting old,
you are encouraged to fetch the latest versions of these files from
-@url{http://savannah.gnu.org/git/?group=config} before making a
+@url{https://savannah.gnu.org/git/?group=config} before making a
release.
@item depcomp
@@ -2321,7 +2321,7 @@ testsuite harness.
Not a program, this file is required for @samp{make dvi}, @samp{make
ps} and @samp{make pdf} to work when Texinfo sources are in the
package. The latest version can be downloaded from
-@url{http://www.gnu.org/software/texinfo/}.
+@url{https://www.gnu.org/software/texinfo/}.
@item ylwrap
This program wraps @command{lex} and @command{yacc} to rename their
@@ -2579,6 +2579,11 @@ for more information.
Look for Automake data files in directory @var{dir} instead of in the
installation directory. This is typically used for debugging.
+@vindex AUTOMAKE_LIBDIR
+The environment variable @env{AUTOMAKE_LIBDIR} provides another way to
+set the directory containing Automake data files. However
+@option{--libdir} takes precedence over it.
+
@item --print-libdir
@opindex --print-libdir
Print the path of the installation directory containing Automake-provided
@@ -3216,6 +3221,11 @@ overridden using the @env{AUTOM4TE} environment variable.
Look for the automake-provided macro files in @var{dir} instead of
in the installation directory. This is typically used for debugging.
+@vindex ACLOCAL_AUTOMAKE_DIR
+The environment variable @env{ACLOCAL_AUTOMAKE_DIR} provides another
+way to set the directory containing automake-provided macro files.
+However @option{--automake-acdir} takes precedence over it.
+
@item --system-acdir=@var{dir}
@opindex --system-acdir
Look for the system-wide third-party macro files (and the special
@@ -8576,7 +8586,7 @@ to supply additional flags to @command{configure}, define them in the
provided there by defining the @code{DISTCHECK_CONFIGURE_FLAGS} variable,
on the command line when invoking @command{make}.
@c See automake bug#14991 for more details about how the following holds.
-It's worth nothing that @command{make distcheck} needs complete control
+It's worth noting that @command{make distcheck} needs complete control
over the @command{configure} options @option{--srcdir} and
@option{--prefix}, so those options cannot be overridden by
@code{AM_DISTCHECK_CONFIGURE_FLAGS} nor by
@@ -8896,7 +8906,7 @@ Note however that, for tests based on more complex test protocols,
the exact effects of @code{XFAIL_TESTS} and @code{DISABLE_HARD_ERRORS}
might change, or they might even have no effect at all (for example,
@c Keep this in sync with tap-no-disable-hard-errors.sh
-in tests using TAP, there is not way to disable hard errors, and the
+in tests using TAP, there is no way to disable hard errors, and the
@code{DISABLE_HARD_ERRORS} variable has no effect on them).
@anchor{Testsuite progress on console}
@@ -9164,7 +9174,7 @@ as a side-effect.
It's important to note that, differently from what we've seen for the
serial test harness (@pxref{Serial Test Harness}), the
@code{AM_TESTS_ENVIRONMENT} and @code{TESTS_ENVIRONMENT} variables
-@emph{cannot} be use to define a custom test runner; the
+@emph{cannot} be used to define a custom test runner; the
@code{LOG_COMPILER} and @code{LOG_FLAGS} (or their extension-specific
counterparts) should be used instead:
@@ -9847,7 +9857,7 @@ a Java-based project implementing both a TAP producer and a TAP consumer.
@node DejaGnu Tests
@section DejaGnu Tests
-If @uref{ftp://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
+If @uref{https://ftp.gnu.org/gnu/dejagnu/, @command{dejagnu}} appears in
@code{AUTOMAKE_OPTIONS}, then a @command{dejagnu}-based test suite is
assumed. The variable @code{DEJATOOL} is a list of names that are
passed, one at a time, as the @option{--tool} argument to
@@ -10322,20 +10332,23 @@ directories. When using this format, consider using the
@option{filename-length-max=99} option to catch file names too long.
@option{tar-ustar} selects the ustar format defined by POSIX
-1003.1-1988. This format is believed to be old enough to be portable.
+1003.1-1988. This format is old enough to be portable:
+As of 2018, it is supported by the native @code{tar} command on
+GNU, FreeBSD, NetBSD, OpenBSD, AIX, HP-UX, Solaris, at least.
It fully supports empty directories. It can store file names with up
to 256 characters, provided that the file name can be split at
directory separator in two parts, first of them being at most 155
bytes long. So, in most cases the maximum file name length will be
-shorter than 256 characters. However you may run against broken tar
-implementations that incorrectly handle file names longer than 99
-characters (please report them to @email{@value{PACKAGE_BUGREPORT}} so we
-can document this accurately).
+shorter than 256 characters.
@option{tar-pax} selects the new pax interchange format defined by POSIX
1003.1-2001. It does not limit the length of file names. However,
this format is very young and should probably be restricted to
-packages that target only very modern platforms. There are moves to
+packages that target only very modern platforms.
+As of 2018, this format is supported by the native @code{tar} command only
+on GNU, FreeBSD, OpenBSD system; it is not supported by the native
+@code{tar} command on NetBSD, AIX, HP-UX, Solaris.
+There are moves to
change the pax format in an upward-compatible way, so this option may
refer to a more recent version in the future.
@@ -10451,7 +10464,7 @@ performing @ref{Automatic Rule Rewriting, , VPATH rewrites, autoconf,
The Autoconf Manual}).
Finally, Automake also emits rules to support the
-@uref{http://www.gnu.org/software/global/, GNU Global Tags program}.
+@uref{https://www.gnu.org/software/global/, GNU Global Tags program}.
The @code{GTAGS} rule runs Global Tags and puts the
result in the top build directory. The variable @code{GTAGS_ARGS}
holds arguments that are passed to @command{gtags}.
@@ -11040,7 +11053,7 @@ If the @option{--add-missing} option is given, @command{automake} will
add a generic version of the @file{INSTALL} file as well as the
@file{COPYING} file containing the text of the current version of the
GNU General Public License existing at the time of this Automake release
-(version 3 as this is written, @uref{http://www.gnu.org/@/copyleft/@/gpl.html}).
+(version 3 as this is written, @uref{https://www.gnu.org/@/copyleft/@/gpl.html}).
However, an existing @file{COPYING} file will never be overwritten by
@command{automake}.
@@ -13067,8 +13080,8 @@ To make it possible for us to fix a bug, please report it. In order to
do so effectively, it helps to know when and how to do it.
Before reporting a bug, it is a good idea to see if it is already known.
-You can look at the @uref{http://debbugs.gnu.org/, GNU Bug Tracker}
-and the @uref{http://lists.gnu.org/@/archive/@/html/@/bug-automake/,
+You can look at the @uref{https://debbugs.gnu.org/, GNU Bug Tracker}
+and the @uref{https://lists.gnu.org/@/archive/@/html/@/bug-automake/,
bug-automake mailing list archives} for previous bug reports. We
previously used a
@uref{http://sourceware.org/@/cgi-bin/@/gnatsweb.pl?database=automake,
@@ -13087,7 +13100,7 @@ features.
For a bug report, a feature request or other suggestions, please send
email to @email{@value{PACKAGE_BUGREPORT}}. This will then open a new
-bug in the @uref{http://debbugs.gnu.org/@/automake, bug tracker}. Be
+bug in the @uref{https://debbugs.gnu.org/@/automake, bug tracker}. Be
sure to include the versions of Autoconf and Automake that you use.
Ideally, post a minimal @file{Makefile.am} and @file{configure.ac} that
reproduces the problem you encounter. If you have encountered test
diff --git a/doc/fdl.texi b/doc/fdl.texi
index 16589f90b..ba802612f 100644
--- a/doc/fdl.texi
+++ b/doc/fdl.texi
@@ -5,7 +5,7 @@
@c hence no sectioning command or @node.
@display
-Copyright @copyright{} 2000-2017 Free Software Foundation, Inc.
+Copyright @copyright{} 2000-2018 Free Software Foundation, Inc.
@uref{http://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies
diff --git a/doc/help2man b/doc/help2man
index e651b8d2d..9268874fa 100755
--- a/doc/help2man
+++ b/doc/help2man
@@ -1,7 +1,7 @@
#!/usr/bin/perl -w
# Generate a short man page from --help and --version output.
-# Copyright (C) 1997-2017 Free Software Foundation, Inc.
+# Copyright (C) 1997-2018 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
@@ -14,19 +14,20 @@
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
-# along with this program; if not, see <http://www.gnu.org/licenses/>.
+# along with this program; if not, see <https://www.gnu.org/licenses/>.
# Written by Brendan O'Dea <bod@debian.org>
-# Available from ftp://ftp.gnu.org/gnu/help2man/
+# Available from https://ftp.gnu.org/gnu/help2man/
-use 5.006;
+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.40.8';
+my $this_version = '1.47.4';
sub _ { $_[0] }
sub configure_locale
@@ -42,11 +43,16 @@ sub enc_user { $_[0] }
sub kark { die +(sprintf shift, @_), "\n" }
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 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.
@@ -117,18 +123,32 @@ Getopt::Long::config('bundling');
die $help_info unless GetOptions %opt_def and @ARGV == 1;
my %include = ();
+my %replace = ();
my %append = ();
-my @include = (); # retain order given in include file
+my %append_match = ();
+my @sections = (); # retain order of include file or in-line *section*s
# Process include file (if given). Format is:
#
-# [section name]
-# verbatim text
+# Optional initial text, ignored. May include lines starting with `-'
+# which are processed as options.
+#
+# [section]
+# Verbatim text to be included in the named section. By default at
+# the start, but in the case of `name' and `synopsis' the content
+# will replace the autogenerated contents.
#
-# or
+# [<section]
+# Verbatim text to be inserted at the start of the named section.
+#
+# [=section]
+# Verbatim text to replace the named section.
+#
+# [>section]
+# Verbatim text to be appended to the end of the named section.
#
# /pattern/
-# verbatim text
+# Verbatim text for inclusion below a paragraph matching `pattern'.
#
while (@opt_include)
@@ -140,7 +160,7 @@ while (@opt_include)
unless open INC, $inc;
my $key;
- my $hash = \%include;
+ my $hash;
while (<INC>)
{
@@ -155,7 +175,23 @@ while (@opt_include)
$key =~ s/^\s+//;
$key =~ s/\s+$//;
$hash = \%include;
- push @include, $key unless $include{$key};
+ # Handle explicit [<section], [=section] and [>section]
+ if ($key =~ s/^([<>=])\s*//)
+ {
+ if ($1 eq '>') { $hash = \%append; }
+ elsif ($1 eq '=') { $hash = \%replace; }
+ }
+ # NAME/SYNOPSIS replace by default
+ elsif ($key eq _('NAME') or $key eq _('SYNOPSIS'))
+ {
+ $hash = \%replace;
+ }
+ else
+ {
+ $hash = \%include;
+ }
+
+ push @sections, $key;
next;
}
@@ -172,7 +208,7 @@ while (@opt_include)
die "$inc:$.:$@";
}
- $hash = \%append;
+ $hash = \%append_match;
next;
}
@@ -184,48 +220,57 @@ while (@opt_include)
# handle options
if (/^-/)
{
- local @ARGV = split;
+ local @ARGV = shellwords $_;
GetOptions %opt_def;
}
next;
}
- $hash->{$key} ||= '';
$hash->{$key} .= $_;
}
close INC;
kark N_("%s: no valid information found in `%s'"), $this_program, $inc
- unless $key;
+ unless $key;
}
# Compress trailing blank lines.
-for my $hash (\(%include, %append))
+for my $hash (\(%include, %replace, %append, %append_match))
{
for (keys %$hash) { $hash->{$_} =~ s/\n+$/\n/ }
}
-sub get_option_value;
-
# Grab help and version info from executable.
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 $program = $ARGV[0]) =~ s!.*/!!;
+my $date = enc strftime _("%B %Y"), localtime $epoch_secs;
+my $program = program_basename $ARGV[0];
my $package = $program;
my $version;
if ($opt_output)
{
unlink $opt_output or kark N_("%s: can't unlink %s (%s)"),
- $this_program, $opt_output, $! if -e $opt_output;
+ $this_program, $opt_output, $! if -e $opt_output;
open STDOUT, ">$opt_output"
or kark N_("%s: can't create %s (%s)"), $this_program, $opt_output, $!;
@@ -247,14 +292,14 @@ if ($opt_output)
if (/^(\S+) +\(((?:GNU|Free) +[^)]+)\) +(.*)/ or
/^(\S+) +- *((?:GNU|Free) +\S+) +(.*)/)
{
- $program = $1;
+ $program = program_basename $1;
$package = $2;
$version = $3;
}
elsif (/^((?:GNU|Free) +)?(\S+) +(.*)/)
{
- $program = $2;
- $package = $1 ? "$1$2" : $2;
+ $program = program_basename $2;
+ $package = $1 ? "$1$program" : $program;
$version = $3;
}
else
@@ -262,21 +307,21 @@ else
$version = $_;
}
-$program =~ s!.*/!!;
-
# No info for `info' itself.
$opt_no_info = 1 if $program eq 'info';
+if ($opt_name)
+{
+ # --name overrides --include contents.
+ $replace{_('NAME')} = "$program \\- $opt_name\n";
+}
+
# Translators: "NAME", "SYNOPSIS" and other one or two word strings in all
# upper case are manual page section headings. The man(1) manual page in your
# language, if available should provide the conventional translations.
-for ($include{_('NAME')})
+for ($replace{_('NAME')} || ($include{_('NAME')} ||= ''))
{
- if ($opt_name) # --name overrides --include contents.
- {
- $_ = "$program \\- $opt_name\n";
- }
- elsif ($_) # Use first name given as $program
+ if ($_) # Use first name given as $program
{
$program = $1 if /^([^\s,]+)(?:,?\s*[^\s,\\-]+)*\s+\\?-/;
}
@@ -339,10 +384,11 @@ if ($help_text =~ s/^($PAT_USAGE):( +(\S+))(.*)((?:\n(?: {6}\1| *($PAT_USAGE_CON
s/\\fI$//;
s/^\./\\&./;
+ $_ = fix_italic_spacing $_;
$synopsis .= "$_\n";
}
- $include{_('SYNOPSIS')} ||= $synopsis;
+ $include{_('SYNOPSIS')} .= $synopsis;
}
# Process text, initial section is DESCRIPTION.
@@ -371,13 +417,13 @@ s/\\/\x82/g;
# "(?:[\\w-]+ +)?" in the bug reporting pattern is used to indicate an
# optional word, so that either "Report bugs" or "Report _program_ bugs" will
# be matched.
-my $PAT_BUGS = _('Report +(?:[\w-]+ +)?bugs|Email +bug +reports +to');
-my $PAT_AUTHOR = _('Written +by');
-my $PAT_OPTIONS = _('Options');
-my $PAT_ENVIRONMENT = _('Environment');
-my $PAT_FILES = _('Files');
-my $PAT_EXAMPLES = _('Examples');
-my $PAT_FREE_SOFTWARE = _('This +is +free +software');
+my $PAT_BUGS = _('Report +(?:[\w-]+ +)?bugs|Email +bug +reports +to');
+my $PAT_AUTHOR = _('Written +by');
+my $PAT_OPTIONS = _('Options');
+my $PAT_ENVIRONMENT = _('Environment');
+my $PAT_FILES = _('Files');
+my $PAT_EXAMPLES = _('Examples');
+my $PAT_FREE_SOFTWARE = _('This +is +free +software');
# Start a new paragraph (if required) for these.
s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR) /$1\n\n$2 /og;
@@ -386,33 +432,40 @@ s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR) /$1\n\n$2 /og;
# character.
s/^Copyright +(?:\xa9|\([Cc]\))/Copyright \\(co/mg;
-sub convert_option;
-
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');
@@ -437,7 +490,6 @@ while (length)
my $indent = $1;
my $prefix = $2;
my $break = '.IP';
- $include{$sect} ||= '';
while (s/^$indent\Q$prefix\E(\S.*)\n*//)
{
$include{$sect} .= "$break\n\\f(CW$prefix$1\\fR\n";
@@ -448,12 +500,11 @@ while (length)
}
my $matched = '';
- $include{$sect} ||= '';
# Sub-sections have a trailing colon and the second line indented.
if (s/^(\S.*:) *\n / /)
{
- $matched .= $& if %append;
+ $matched .= $& if %append_match;
$include{$sect} .= qq(.SS "$1"\n);
}
@@ -463,7 +514,7 @@ while (length)
# Option with description.
if (s/^( {1,10}([+-]\S.*?))(?:( +(?!-))|\n( {20,}))(\S.*)\n//)
{
- $matched .= $& if %append;
+ $matched .= $& if %append_match;
$indent = length ($4 || "$1$3");
$content = ".TP\n\x84$2\n\x84$5\n";
unless ($4)
@@ -476,23 +527,23 @@ while (length)
# Option without description.
elsif (s/^ {1,10}([+-]\S.*)\n//)
{
- $matched .= $& if %append;
+ $matched .= $& if %append_match;
$content = ".HP\n\x84$1\n";
$indent = 80; # not continued
}
# Indented paragraph with tag.
- elsif (s/^( +(\S.*?) +)(\S.*)\n//)
+ elsif (s/^( +(\S.*?))(?:( +)|\n( {20,}))(\S.*)\n//)
{
- $matched .= $& if %append;
- $indent = length $1;
- $content = ".TP\n\x84$2\n\x84$3\n";
+ $matched .= $& if %append_match;
+ $indent = length ($4 || "$1$3");
+ $content = ".TP\n\x84$2\n\x84$5\n";
}
# Indented paragraph.
elsif (s/^( +)(\S.*)\n//)
{
- $matched .= $& if %append;
+ $matched .= $& if %append_match;
$indent = length $1;
$content = ".IP\n\x84$2\n";
}
@@ -501,7 +552,7 @@ while (length)
else
{
s/(.*)\n//;
- $matched .= $& if %append;
+ $matched .= $& if %append_match;
$content = ".PP\n" if $include{$sect};
$content .= "$1\n";
}
@@ -509,7 +560,7 @@ while (length)
# Append continuations.
while ($indent ? s/^ {$indent}(\S.*)\n// : s/^(\S.*)\n//)
{
- $matched .= $& if %append;
+ $matched .= $& if %append_match;
$content .= "\x84$1\n";
}
@@ -523,19 +574,35 @@ while (length)
s/\x84'/\x81/g;
s/\x84//g;
- # Convert options.
- s/(^| |\()(-[][\w=-]+)/$1 . convert_option $2/mge;
+ # Examples should be verbatim.
+ unless ($sect eq _('EXAMPLES'))
+ {
+ # Convert options.
+ s/(^|[ (])(-[][\w=-]+)/$1 . convert_option $2/mge;
+
+ # Italicise filenames: /a/b, $VAR/c/d, ~/e/f
+ s!
+ (^|[ (]) # space/punctuation before
+ (
+ (?:\$\w+|~)? # leading variable, or tilde
+ (?:/\w(?:[\w.-]*\w)?)+ # path components
+ )
+ ($|[ ,;.)]) # space/punctuation after
+ !$1\\fI$2\\fP$3!xmg;
+
+ $_ = fix_italic_spacing $_;
+ }
- # Escape remaining hyphens
+ # Escape remaining hyphens.
s/-/\x83/g;
- if ($sect eq 'COPYRIGHT')
+ if ($sect eq _('COPYRIGHT'))
{
# Insert line breaks before additional copyright messages
# and the disclaimer.
s/\n(Copyright |$PAT_FREE_SOFTWARE)/\n.br\n$1/og;
}
- elsif ($sect eq 'REPORTING BUGS')
+ elsif ($sect eq _('REPORTING BUGS'))
{
# Handle multi-line bug reporting sections of the form:
#
@@ -547,14 +614,14 @@ while (length)
}
# Check if matched paragraph contains /pat/.
- if (%append)
+ if (%append_match)
{
- for my $pat (keys %append)
+ for my $pat (keys %append_match)
{
if ($matched =~ $pat)
{
- $content .= ".PP\n" unless $append{$pat} =~ /^\./;
- $content .= $append{$pat};
+ $content .= ".PP\n" unless $append_match{$pat} =~ /^\./;
+ $content .= $append_match{$pat};
}
}
}
@@ -568,7 +635,6 @@ unless ($opt_no_info)
my $info_page = $opt_info || $program;
$sect = _('SEE ALSO');
- $include{$sect} ||= '';
$include{$sect} .= ".PP\n" if $include{$sect};
$include{$sect} .= sprintf _(<<'EOT'), $program, $program, $info_page;
The full documentation for
@@ -585,6 +651,18 @@ should give you access to the complete manual.
EOT
}
+# Append additional text.
+while (my ($sect, $text) = each %append)
+{
+ $include{$sect} .= $append{$sect};
+}
+
+# Replace sections.
+while (my ($sect, $text) = each %replace)
+{
+ $include{$sect} = $replace{$sect};
+}
+
# Output header.
print <<EOT;
.\\" DO NOT MODIFY THIS FILE! It was generated by $this_program $this_version.
@@ -592,15 +670,17 @@ print <<EOT;
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;
+my @pre = (_('NAME'), _('SYNOPSIS'), _('DESCRIPTION'), _('OPTIONS'));
+my @post = (_('ENVIRONMENT'), _('FILES'), _('EXAMPLES'), _('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/ ? '"' : '';
@@ -628,6 +708,15 @@ close STDOUT or kark N_("%s: error writing to %s (%s)"), $this_program,
exit;
+# Get program basename, and strip libtool "lt-" prefix if required.
+sub program_basename
+{
+ local $_ = shift;
+ s!.*/!!;
+ s/^lt-// if $opt_libtool;
+ $_;
+}
+
# Call program with given option and return results.
sub get_option_value
{
@@ -648,7 +737,7 @@ sub get_option_value
kark $err, $this_program, $opt, $prog, $extra;
}
- return $value;
+ $value;
}
# Convert option dashes to \- to stop nroff from hyphenating 'em, and
@@ -667,3 +756,12 @@ sub convert_option
$_;
}
+
+# Insert spacing escape characters \, and \/ before and after italic text. See
+# https://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 $_;
+}
diff --git a/doc/Makefile.inc b/doc/local.mk
index b39ce89c7..e76c04f5d 100644
--- a/doc/Makefile.inc
+++ b/doc/local.mk
@@ -1,6 +1,5 @@
-## Included by top-level Makefile for Automake.
-
-## Copyright (C) 1995-2017 Free Software Foundation, Inc.
+## -*- makefile-automake -*-
+## Copyright (C) 1995-2018 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
@@ -13,7 +12,7 @@
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
-## along with this program. If not, see <http://www.gnu.org/licenses/>.
+## along with this program. If not, see <https://www.gnu.org/licenses/>.
## ---------------- ##
## Documentation. ##
@@ -32,13 +31,13 @@ man1_MANS = \
$(man1_MANS): $(top_srcdir)/configure.ac
CLEANFILES += $(man1_MANS)
+# XXX: This script should be updated with 'fetch' target.
EXTRA_DIST += %D%/help2man
update_mans = \
$(AM_V_GEN): \
&& $(MKDIR_P) %D% \
- && $(extend_PATH) \
- && $(PERL) $(srcdir)/%D%/help2man --output=$@
+ && ./pre-inst-env $(PERL) $(srcdir)/%D%/help2man --output=$@
%D%/aclocal.1 %D%/automake.1:
$(AM_V_GEN): \
@@ -77,8 +76,7 @@ dist_noinst_DATA += $(amhello_sources)
dist_doc_DATA = $(srcdir)/%D%/amhello-1.0.tar.gz
setup_autotools_paths = { \
- $(extend_PATH) \
- && ACLOCAL=aclocal-$(APIVERSION) && export ACLOCAL \
+ ACLOCAL=aclocal-$(APIVERSION) && export ACLOCAL \
&& AUTOMAKE=automake-$(APIVERSION) && export AUTOMAKE \
&& AUTOCONF='$(am_AUTOCONF)' && export AUTOCONF \
&& AUTOM4TE='$(am_AUTOM4TE)' && export AUTOM4TE \
@@ -97,7 +95,7 @@ $(srcdir)/%D%/amhello-1.0.tar.gz: $(amhello_sources) $(srcdir)/configure.ac
&& $(setup_autotools_paths) \
&& ( \
{ $(AM_V_P) || exec 5>&2 >$$tmp 2>&1; } \
- && $(am_AUTORECONF) -vfi \
+ && $(abs_builddir)/pre-inst-env $(am_AUTORECONF) -vfi \
&& ./configure \
&& $(MAKE) $(AM_MAKEFLAGS) distcheck \
&& $(MAKE) $(AM_MAKEFLAGS) distclean \
View Lorry Controller Status