[Guile-commits] 01/02: Use "G_" as the conventional alias for gettext

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit 4e89d0c061c585ca56a96ef8410dad17979ca5eb
Author: Andy Wingo <address@hidden>
Date:   Thu Sep 12 21:45:26 2019 +0200

    Use "G_" as the conventional alias for gettext
    
    Since the change in 2.2 noted in the NEWS as "Fix literal matching for
    module-bound literals", defining `_' makes `syntax-rules' and `match'
    fail to recognize `_' as the catch-all literal.  This change adapts the
    recommendations to current practice in 2.2, as users have had to adapt
    to this change.
    
    * doc/ref/api-i18n.texi (Gettext Support): Update documentation.
    * module/language/tree-il/analyze.scm (proc-ref?, gettext?): G_ is the
      conventional abbreviation, not _.
    * test-suite/tests/tree-il.test: Adapt.
    * module/ice-9/command-line.scm: Use G_ instead of _.
---
 doc/ref/api-i18n.texi               | 19 ++++++++++++-------
 module/ice-9/command-line.scm       | 22 +++++++++++-----------
 module/language/tree-il/analyze.scm |  8 ++++----
 test-suite/tests/tree-il.test       | 10 +++++-----
 4 files changed, 32 insertions(+), 27 deletions(-)

diff --git a/doc/ref/api-i18n.texi b/doc/ref/api-i18n.texi
index 0a27285..7c49b0a 100644
--- a/doc/ref/api-i18n.texi
+++ b/doc/ref/api-i18n.texi
@@ -508,17 +508,22 @@ utilities}).
 (display (gettext "You are in a maze of twisty passages."))
 @end example
 
-@code{_} is a commonly used shorthand, an application can make that an
-alias for @code{gettext}.  Or a library can make a definition that
-uses its specific @var{domain} (so an application can change the
-default without affecting the library).
+It is conventional to use @code{G_} as a shorthand for
+@code{gettext}.@footnote{Users of @code{gettext} might be a bit
+surprised that @code{G_} is the conventional abbreviation for
+@code{gettext}.  In most other languages, the conventional shorthand is
+@code{_}.  Guile uses @code{G_} because @code{_} is already taken, as it
+is bound to a syntactic keyword used by @code{syntax-rules},
+@code{match}, and other macros.}  Libraries can define @code{G_} in such
+a way to look up translations using its specific @var{domain}, allowing
+different parts of a program to have different translation sources.
 
 @example
-(define (_ msg) (gettext msg "mylibrary"))
-(display (_ "File not found."))
+(define (G_ msg) (gettext msg "mylibrary"))
+(display (G_ "File not found."))
 @end example
 
-@code{_} is also a good place to perhaps strip disambiguating extra
+@code{G_} is also a good place to perhaps strip disambiguating extra
 text from the message string, as for instance in @ref{GUI program
 problems,, How to use @code{gettext} in GUI programs, gettext, GNU
 @code{gettext} utilities}.
diff --git a/module/ice-9/command-line.scm b/module/ice-9/command-line.scm
index aaaedb7..ab22dca 100644
--- a/module/ice-9/command-line.scm
+++ b/module/ice-9/command-line.scm
@@ -40,15 +40,15 @@
             emit-bug-reporting-address))
 
 ;; An initial stab at i18n.
-(define _ gettext)
+(define G_ gettext)
 
 (define *GPLv3+*
-  (_ "License GPLv3+: GNU GPL version 3 or later 
<http://gnu.org/licenses/gpl.html>.
+  (G_ "License GPLv3+: GNU GPL version 3 or later 
<http://gnu.org/licenses/gpl.html>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law."))
 
 (define *LGPLv3+*
-  (_ "License LGPLv3+: GNU LGPL 3 or later <http://gnu.org/licenses/lgpl.html>.
+  (G_ "License LGPLv3+: GNU LGPL 3 or later 
<http://gnu.org/licenses/lgpl.html>.
 This is free software: you are free to change and redistribute it.
 There is NO WARRANTY, to the extent permitted by law."))
 
@@ -79,8 +79,8 @@ There is NO WARRANTY, to the extent permitted by law."))
 
   (if packager
       (if packager-version
-          (format port (_ "Packaged by ~a (~a)\n") packager packager-version)
-          (format port (_ "Packaged by ~a\n") packager)))
+          (format port (G_ "Packaged by ~a (~a)\n") packager packager-version)
+          (format port (G_ "Packaged by ~a\n") packager)))
   
   (display copyright port)
   (newline port)
@@ -98,15 +98,15 @@ There is NO WARRANTY, to the extent permitted by law."))
                                            package
                                            "/"))
                                      packager packager-bug-address)
-  (format port (_ "\nReport bugs to: ~a\n") bug-address)
+  (format port (G_ "\nReport bugs to: ~a\n") bug-address)
   (if (and packager packager-bug-address)
-      (format port (_ "Report ~a bugs to: ~a\n") packager 
packager-bug-address))
-  (format port (_ "~a home page: <~a>\n") package url)
+      (format port (G_ "Report ~a bugs to: ~a\n") packager 
packager-bug-address))
+  (format port (G_ "~a home page: <~a>\n") package url)
   (format port
-          (_ "General help using GNU software: 
<http://www.gnu.org/gethelp/>\n")))
+          (G_ "General help using GNU software: 
<http://www.gnu.org/gethelp/>\n")))
 
 (define *usage*
-  (_ "Evaluate code with Guile, interactively or from a script.
+  (G_ "Evaluate code with Guile, interactively or from a script.
 
   [-s] FILE      load source code from FILE, and exit
   -c EXPR        evalute expression EXPR, and exit
@@ -151,7 +151,7 @@ If FILE begins with `-' the -s switch is mandatory.
       (apply format port fmt args)
       (newline port))
 
-    (format port (_ "Usage: ~a [OPTION]... [FILE]...\n") name)
+    (format port (G_ "Usage: ~a [OPTION]... [FILE]...\n") name)
     (display *usage* port)
     (newline port)
 
diff --git a/module/language/tree-il/analyze.scm 
b/module/language/tree-il/analyze.scm
index eb83a8e..bc98f82 100644
--- a/module/language/tree-il/analyze.scm
+++ b/module/language/tree-il/analyze.scm
@@ -1,6 +1,6 @@
 ;;; TREE-IL -> GLIL compiler
 
-;; Copyright (C) 2001, 2008-2014, 2018 Free Software Foundation, Inc.
+;; Copyright (C) 2001,2008-2014,2016,2018-2019 Free Software Foundation, Inc.
 
 ;;;; This library is free software; you can redistribute it and/or
 ;;;; modify it under the terms of the GNU Lesser General Public
@@ -1422,7 +1422,7 @@ resort, return #t when EXP refers to the global variable 
SPECIAL-NAME."
 
   (match exp
     (($ <toplevel-ref> _ _ (? special?))
-     ;; Allow top-levels like: (define _ (cut gettext <> "my-domain")).
+     ;; Allow top-levels like: (define G_ (cut gettext <> "my-domain")).
      #t)
     (($ <toplevel-ref> _ _ name)
      (let ((var (module-variable env name)))
@@ -1440,7 +1440,7 @@ resort, return #t when EXP refers to the global variable 
SPECIAL-NAME."
      #t)
     (_ #f)))
 
-(define gettext? (cut proc-ref? <> gettext '_ <>))
+(define gettext? (cut proc-ref? <> gettext 'G_ <>))
 (define ngettext? (cut proc-ref? <> ngettext 'N_ <>))
 
 (define (const-fmt x env)
@@ -1450,7 +1450,7 @@ resort, return #t when EXP refers to the global variable 
SPECIAL-NAME."
      exp)
     (($ <call> _ (? (cut gettext? <> env))
         (($ <const> _ (? string? fmt))))
-     ;; Gettexted literals, like `(_ "foo")'.
+     ;; Gettexted literals, like `(G_ "foo")'.
      fmt)
     (($ <call> _ (? (cut ngettext? <> env))
         (($ <const> _ (? string? fmt)) ($ <const> _ (? string?)) _ ..1))
diff --git a/test-suite/tests/tree-il.test b/test-suite/tests/tree-il.test
index 46729ef..917316a 100644
--- a/test-suite/tests/tree-il.test
+++ b/test-suite/tests/tree-il.test
@@ -874,7 +874,7 @@
      (pass-if "non-literal format string using gettext as _"
        (null? (call-with-warnings
                (lambda ()
-                 (compile '(format #t (_ "~A ~A!") "hello" "world")
+                 (compile '(format #t (G_ "~A ~A!") "hello" "world")
                           #:opts %opts-w-format
                           #:to 'cps)))))
 
@@ -883,14 +883,14 @@
                (lambda ()
                  (compile '(begin
                              (define (_ s) (gettext s "my-domain"))
-                             (format #t (_ "~A ~A!") "hello" "world"))
+                             (format #t (G_ "~A ~A!") "hello" "world"))
                           #:opts %opts-w-format
                           #:to 'cps)))))
 
      (pass-if "non-literal format string using gettext as module-ref _"
        (null? (call-with-warnings
                (lambda ()
-                 (compile '(format #t ((@@ (foo) _) "~A ~A!") "hello" "world")
+                 (compile '(format #t ((@@ (foo) G_) "~A ~A!") "hello" "world")
                           #:opts %opts-w-format
                           #:to 'cps)))))
 
@@ -899,7 +899,7 @@
                (lambda ()
                  (compile '(let ((_ (lambda (s)
                                       (gettext s "my-domain"))))
-                             (format #t (_ "~A ~A!") "hello" "world"))
+                             (format #t (G_ "~A ~A!") "hello" "world"))
                           #:opts %opts-w-format
                           #:to 'cps)))))
 
@@ -924,7 +924,7 @@
                  (compile '(begin
                              (define _ gettext)
                              (define (foo)
-                               (format #t (_ "~A ~A!") "hello" "world")))
+                               (format #t (G_ "~A ~A!") "hello" "world")))
                           #:opts %opts-w-format
                           #:to 'cps)))))