Re: [PATCH] FAQ update for aliasing

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

Bart Schaefer wrote on Fri, Jan 29, 2021 at 11:35:28 -0800:
> The section on csh-to-zsh alias equivalence had a number of
> not-incorrect but not-up-to-date references.  Attached patch fixes
> these.
> 
> However, when I do "cd Etc; make FAQ" on Ubuntu 20.04.1 LTS, I get
> some strange formatting.  Hopefully you can see what I mean in the
> copy-paste below despite possible gmail line wrap:
> 
> --- 8< ---
> Here is Bart Schaefer's guide to converting csh aliases for zsh.
> 
> 
>   1. ) If the csh alias references "parameters" (\!:1, \!* etc.),
>      then in zsh you need a function (referencing $1, $* etc.).
>      In recent versions of zsh this can be done by defining an anonymous
>      function within the alias.  Otherwise, a simple zsh alias suffices.
> 
> 2. ) If you use a zsh function, you need to refer _at_least_ to
>      $* in the body (inside the { }).  Parameters don't magically
>      appear inside the { } the way they get appended to an alias.
> --- 8< ---
> 
> That is, most paragraphs get a hanging left indent (outdent?), but not
> all do.  This happens in other sections, not just the one touched in
> the patch.  I'm not sure the hanging leader is even intentional.  Do
> others see this?

You mean the additional indentation of the "1."?  I see it both with and
without the patch:

[[[
--- Etc/FAQ.unpatched
+++ Etc/FAQ.patched
@@ -640,21 +640,22 @@
   (which converts your home directory to a ~).  In fact, this problem is
   better solved by defining the special function chpwd() (see
   the manual). Note also that the `;' at the end of the function is
   optional in zsh, but not in ksh or sh (for sh's where it exists).
 
 Here is Bart Schaefer's guide to converting csh aliases for zsh.
 
 
   1. ) If the csh alias references "parameters" (\!:1, \!* etc.),
      then in zsh you need a function (referencing $1, $* etc.).
-     Otherwise, you can use a zsh alias.
+     In recent versions of zsh this can be done by defining an anonymous
+     function within the alias.  Otherwise, a simple zsh alias suffices.
 
 2. ) If you use a zsh function, you need to refer _at_least_ to
      $* in the body (inside the { }).  Parameters don't magically
      appear inside the { } the way they get appended to an alias.
 
 3. ) If the csh alias references its own name (alias rm "rm -i"),
      then in a zsh function you need the "command" or "builtin" keyword
      (function rm() { command rm -i "$@" }), but in a zsh alias
      you don't (alias rm="rm -i").
 
@@ -683,44 +684,43 @@
      \!^-          $*[1,$#-1]
      \!*:q         "$@"
      \!*:x         $=*             ($*:x doesn't work (yet))
         
 
 6. ) Remember that it is NOT a syntax error in a zsh function to
      refer to a position ($1, $2, etc.) greater than the number of
      parameters. (E.g., in a csh alias, a reference to \!:5 will
      cause an error if 4 or fewer arguments are given; in a zsh
      function, $5 is the empty string if there are 4 or fewer
-     parameters.)
+     parameters.  Force an error in this example by using ${5?}.)
 
 7. ) To begin a zsh alias with a - (dash, hyphen) character, use
      `alias --':
       
              csh                            zsh
         ===============             ==================
         alias - "fg %-"             alias -- -="fg %-"
       
 
 8. ) Stay away from `alias -g' in zsh until you REALLY know what
      you're doing.
   
 
 There is one other serious problem with aliases: consider
   
     alias l='/bin/ls -F'
     l() { /bin/ls -la "$@" | more }
   
   `l' in the function definition is in command position and is expanded
   as an alias, defining `/bin/ls' and `-F' as functions which call
-  `/bin/ls', which gets a bit recursive.  This can be avoided if you use
-  `function' to define a function, which doesn't expand aliases.  It is
-  possible to argue for extra warnings somewhere in this mess.
+  `/bin/ls', which gets a bit recursive.  Recent versions of zsh treat
+  this as an error, but older versions silently create the functions.
 
 One workaround for this is to use the "function" keyword instead:
   
     alias l='/bin/ls -F'
     function l { /bin/ls -la "$@" | more }
   
   The `l' after `function' is not expanded.  Note you don't need
   the `()' in this case, although it's harmless.
 
 You need to be careful if you are defining a function with multiple
]]]

Adding a blank line between «enumeration(» and «myeit()» fixes it:

[[[
--- Etc/FAQ.unpatched
+++ Etc/FAQ.patched
@@ -637,22 +637,21 @@
   
     cd() { builtin cd "$@"; print -D $PWD; }
   
   (which converts your home directory to a ~).  In fact, this problem is
   better solved by defining the special function chpwd() (see
   the manual). Note also that the `;' at the end of the function is
   optional in zsh, but not in ksh or sh (for sh's where it exists).
 
 Here is Bart Schaefer's guide to converting csh aliases for zsh.
 
-
-  1. ) If the csh alias references "parameters" (\!:1, \!* etc.),
+1. ) If the csh alias references "parameters" (\!:1, \!* etc.),
      then in zsh you need a function (referencing $1, $* etc.).
      Otherwise, you can use a zsh alias.
 
 2. ) If you use a zsh function, you need to refer _at_least_ to
      $* in the body (inside the { }).  Parameters don't magically
      appear inside the { } the way they get appended to an alias.
 
 3. ) If the csh alias references its own name (alias rm "rm -i"),
      then in a zsh function you need the "command" or "builtin" keyword
      (function rm() { command rm -i "$@" }), but in a zsh alias
]]]