On 09/09/2014 03:52 PM, Michael Stone wrote: > On Tue, Sep 09, 2014 at 03:31:35PM +0100, Pádraig Brady wrote: >> It's useful to many, but I agree most don't bother with it >> due to the awkward non intuitive default info reader _interface_ >> (though pinfo is a bit better in that regard). > > Right. I've heard the argument for 15 years that info docs are really good, > it's just the interface. :) In all that time, a better interface hasn't > really caught on, and the web happened. > >> Though it would be better to have direct links. >> Now the above full node URL is too long/awkward, so I've just now setup >> redirects, >> so the following proposed new trailers for ls --help and man pages should >> work: >> >> ls --help: >> ... >> Full documentation online at: <http://www.gnu.org/software/coreutils/ls> >> Full installed documentation: info '(coreutils) ls invocation' > > A huge improvement. I suspect that this might also help the info docs show up > in google, instead of being below the fold. Alternative wording: > > Full documentation online at: <http://www.gnu.org/software/coreutils/ls> > or available locally via: info '(coreutils) ls invocation' > > To make it more clear it's the same thing available different ways.
Done in the attached which I'll push later. thanks, Pádraig.
>From e4627416b4be078a184372b9b0582517612a3c39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draig=20Brady?= <p...@draigbrady.com> Date: Tue, 9 Sep 2014 02:05:45 +0100 Subject: [PATCH 1/2] doc: adjust reference to info nodes in man pages old form: coreutils '$cmd invocation' new form: '(coreutils) $cmd invocation' The old form erroneously referenced the node for the 'coreutils' multi-call program. Now that problematic node name was renamed in commit v8.23-18-g72e470b, but the newer less ambiguous form also has the advantage of working with the pinfo viewer for example. Full discussion at http://bugs.gnu.org/18428 * man/local.mk: Adjust man page references to texinfo nodes. * src/system.h: Adjust --help references to texinfo nodes. --- man/dummy-man | 2 +- man/local.mk | 2 +- src/system.h | 3 ++- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/man/dummy-man b/man/dummy-man index dca2b67..bf31912 100755 --- a/man/dummy-man +++ b/man/dummy-man @@ -69,5 +69,5 @@ The full documentation for is maintained as a Texinfo manual, which should be accessible on your system via the command .IP -.B info coreutils $bs(aq$progname invocation$bs(aq +.B info $bs(aq(coreutils) $progname invocation$bs(aq END diff --git a/man/local.mk b/man/local.mk index f4b213f..f2d1357 100644 --- a/man/local.mk +++ b/man/local.mk @@ -102,7 +102,7 @@ man/dynamic-deps.mk: Makefile --source='$(PACKAGE_STRING)' \ --include=$(srcdir)/man/$$name.x \ --output=$$t/$$name.1 $$t/$$argv \ - --info-page='coreutils \(aq'$$name' invocation\(aq' \ + --info-page='\(aq(coreutils) '$$name' invocation\(aq' \ && sed \ -e 's|$*\.td/||g' \ -e '/For complete documentation/d' \ diff --git a/src/system.h b/src/system.h index 162446c..00180cb 100644 --- a/src/system.h +++ b/src/system.h @@ -582,7 +582,8 @@ emit_ancillary_info (void) last_component (program_name)); } printf (_("For complete documentation, run: " - "info coreutils '%s invocation'\n"), last_component (program_name)); + "info '(coreutils) %s invocation'\n"), + last_component (program_name)); } static inline void -- 1.7.7.6 >From 0b96a07dd2576fc4a3c64aee48307f3707b38cd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draig=20Brady?= <p...@draigbrady.com> Date: Wed, 10 Sep 2014 11:53:50 +0100 Subject: [PATCH 2/2] doc: reference online info pages directly from man pages * src/system.h (emit_ancillary_info): Add a direct reference to the corresponding online info documentation. Corresponding redirects were put in place on www.gnu.org to allow for concise links. * help2man: Adjust to add the "online help" link (and subsequent translation bugs link) to a "REPORTING BUGS" section. Also add the concise links for further information in --help to the "SEE ALSO" section, and dispense with the more verbose default for that. --- man/help2man | 23 +++++++++++++++++++++-- src/system.h | 13 ++++++++----- 2 files changed, 29 insertions(+), 7 deletions(-) diff --git a/man/help2man b/man/help2man index bfeb989..47aa2a7 100755 --- a/man/help2man +++ b/man/help2man @@ -405,16 +405,19 @@ 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_BUGS = _('Report +(?:[\w-]+ +)?bugs|' . + 'Email +bug +reports +to|' . + '.* +online +help:'); 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_SEE_ALSO = _('Full +documentation'); # Start a new paragraph (if required) for these. -s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR) /$1\n\n$2 /og; +s/([^\n])\n($PAT_BUGS|$PAT_AUTHOR|$PAT_SEE_ALSO) /$1\n\n$2 /og; # Convert iso-8859-1 copyright symbol or (c) to nroff # character. @@ -462,6 +465,12 @@ while (length) $sect = _('AUTHOR'); } + elsif (/^($PAT_SEE_ALSO)/o) + { + $sect = _('SEE ALSO'); + $opt_no_info = 1; + } + # Examples, indicated by an indented leading $, % or > are # rendered in a constant width font. if (/^( +)([\$\%>] )\S/) @@ -588,6 +597,16 @@ while (length) # ... s/\n([[:upper:]])/\n.br\n$1/g; } + elsif ($sect eq _('SEE ALSO')) + { + # Handle external references of the form: + # + # GNU <package> online resources: <addr> + # Full documentation at: <addr> + # or available locally via: info ... + # + s/\n(.)/\n.br\n$1/g; + } } # Check if matched paragraph contains /pat/. diff --git a/src/system.h b/src/system.h index 00180cb..1682b32 100644 --- a/src/system.h +++ b/src/system.h @@ -567,7 +567,10 @@ Otherwise, units default to 1024 bytes (or 512 if POSIXLY_CORRECT is set).\n\ static inline void emit_ancillary_info (void) { + char const * program = last_component (program_name); + printf (_("\n%s online help: <%s>\n"), PACKAGE_NAME, PACKAGE_URL); + /* Don't output this redundant message for English locales. Note we still output for 'C' so that it gets included in the man page. */ const char *lc_messages = setlocale (LC_MESSAGES, NULL); @@ -578,12 +581,12 @@ emit_ancillary_info (void) the URLs at http://translationproject.org/team/. Otherwise, replace the entire URL with your translation team's email address. */ printf (_("Report %s translation bugs to " - "<http://translationproject.org/team/>\n"), - last_component (program_name)); + "<http://translationproject.org/team/>\n"), program); } - printf (_("For complete documentation, run: " - "info '(coreutils) %s invocation'\n"), - last_component (program_name)); + printf (_("Full documentation at: <%s%s>\n"), + PACKAGE_URL, program); + printf (_("or available locally via: info '(coreutils) %s invocation'\n"), + program); } static inline void -- 1.7.7.6
