zsh-workers
 help / color / mirror / code / Atom feed
From: "Jun. T" <takimoto-j@kba.biglobe.ne.jp>
To: zsh-workers@zsh.org
Subject: Re: [PATCH] FAQ update for aliasing
Date: Sun, 12 Jun 2022 22:10:43 +0900	[thread overview]
Message-ID: <3391D472-6F5D-481E-B114-1E0D1310ED63@kba.biglobe.ne.jp> (raw)
In-Reply-To: <CAH+w=7bhYMMe7p4ueOGH+NWWsUM5H-qs2fK7ABP5iQYzdh+rnA@mail.gmail.com>

[-- Attachment #1: Type: text/plain, Size: 1682 bytes --]

I've found that the text version of FAQ has some format problems,
and then found that it was already reported one-and-half year ago:

> 2021/01/30 4:35, Bart Schaefer <schaefer@brasslantern.com> wrote:
> 
> However, when I do "cd Etc; make FAQ" on Ubuntu 20.04.1 LTS, I get
> some strange formatting.
(snip)
> That is, most paragraphs get a hanging left indent (outdent?),

It seems yodl removes any indent of the 1st line of a paragraph in
text mode by default (a paragraph is started by a blank line).

But at line 152 of the FAQ:
 (As a method of reading the following in Emacs, you can type \M-2   
  \C-x $ to make all the indented text vanish, ...

I have _NO_ experience with emacs, but I guess the lack of indent
would break this feature?

With some trial and error, I found the indent can be preserved by the
following patch.
But with this patch two or more consecutive blank lines in FAQ.yo
are copied to the text output as is. I guess the symbol XXparagraph
contains all the preceding blank lines. Using ifnewparagraph() didn't
work. So I removed many blank lines. These trivial changes are only
included in the attached file.


diff --git a/Etc/FAQ.yo b/Etc/FAQ.yo
index 8a6895454..ebe86c202 100644
--- a/Etc/FAQ.yo
+++ b/Etc/FAQ.yo
@@ -57,6 +57,11 @@ def(emdash)(0)(\
     whentxt(--))\
 SUBST(_LPAR_)(CHAR(40))\
 SUBST(_RPAR_)(CHAR(41))
+COMMENT(-- preserve the indent of the 1st line of paragraph --)\
+IFDEF(txt)(\
+  DEFINESYMBOL(XXparagraph)()\
+  PUSHMACRO(PARAGRAPH)(0)(SYMBOLVALUE(XXparagraph))\
+)()
 myreport(Z-Shell Frequently-Asked Questions)(Peter Stephenson)(2010/02/15)
 COMMENT(-- the following are for Usenet and must appear first)\
 description(\





[-- Attachment #2: FAQ-indent.patch --]
[-- Type: application/octet-stream, Size: 17955 bytes --]

diff --git a/Etc/FAQ.yo b/Etc/FAQ.yo
index 8a6895454..ebe86c202 100644
--- a/Etc/FAQ.yo
+++ b/Etc/FAQ.yo
@@ -57,6 +57,11 @@ def(emdash)(0)(\
     whentxt(--))\
 SUBST(_LPAR_)(CHAR(40))\
 SUBST(_RPAR_)(CHAR(41))
+COMMENT(-- preserve the indent of the 1st line of paragraph --)\
+IFDEF(txt)(\
+  DEFINESYMBOL(XXparagraph)()\
+  PUSHMACRO(PARAGRAPH)(0)(SYMBOLVALUE(XXparagraph))\
+)()
 myreport(Z-Shell Frequently-Asked Questions)(Peter Stephenson)(2010/02/15)
 COMMENT(-- the following are for Usenet and must appear first)\
 description(\
@@ -163,7 +168,7 @@ Acknowledgments
 
 Copyright
 --- End of Contents ---
-)
+)\
 
 chapter(Introducing zsh and how to install it)
 
@@ -222,7 +227,6 @@ email(mail-server@rtfm.mit.edu)
   For any more eclectic information, you should contact the mailing
   list:  see question link(6.2)(62).
 
-
 sect(What is it?)
 
   Zsh is a UNIX command interpreter (shell) which of the standard
@@ -242,7 +246,6 @@ sect(What is it?)
   included with the source distribution are highly recommended.  A list
   of features is given in FEATURES, also with the source.
 
-
 sect(What is it good at?)
 
   Here are some things that zsh is particularly good at.  No claim of
@@ -284,7 +287,6 @@ sect(What is it good at?)
   it() Spelling correction.
   )
 
-
 sect(On what machines will it run?)
 
   From version 3.0, zsh uses GNU autoconf as the installation
@@ -313,7 +315,6 @@ sect(On what machines will it run?)
   signames.h file. This makes the signals code unusable. This often happens
   on Ultrix, HP-UX, IRIX (?). Install gawk if you experience such problems.
 
-
 sect(What's the latest version?)
 
   Zsh 5.9 is the latest production version.  For details of all the
@@ -335,7 +336,6 @@ sect(What's the latest version?)
   users), or to enhance compatibility with other Bourne shell
   derivatives, or (mostly in the 3.0 series) to provide POSIX compliance.
 
-
 sect(Where do I get it?)
 label(16)
 
@@ -435,7 +435,6 @@ sect(I don't have root access: how do I make zsh my login shell?)
   /etc/shells on all appropriate machines, including NIS clients, or you
   may have problems with FTP to that machine.
 
-
 chapter(How does zsh differ from...?)
 
 As has already been mentioned, zsh is most similar to ksh, while many
@@ -639,7 +638,6 @@ link(2.3)(23).
   )
   )
 
-
 sect(Similarities with csh)
 
   Although certain features aim to ease the withdrawal symptoms of csh
@@ -673,7 +671,6 @@ sect(Similarities with csh)
   it()  Arrays have csh-like features (see under link(2.1)(21)).
   )
 
-
 sect(Why do my csh aliases not work?  (Plus other alias pitfalls.))
 label(23)
 
@@ -863,7 +860,6 @@ mytt(compctl)
   )
   and can now bind tt(run-fg-editor) just like any other editor function.
 
-
 sect(Similarities with bash)
 label(25)
 
@@ -889,7 +885,6 @@ label(25)
   and `tt((#e))' to match the end.  These require the option
   tt(EXTENDED_GLOB) to be set.
 
-
 sect(Shouldn't zsh be more/less like ksh/(t)csh?)
 
   People often ask why zsh has all these `unnecessary' csh-like features,
@@ -916,7 +911,6 @@ sect(Shouldn't zsh be more/less like ksh/(t)csh?)
   want.  The introduction of loadable in modules in version 3.1 should
   help.
 
-
 sect(What is zsh's support for Unicode/UTF-8?)
 
   `Unicode', or UCS for Universal Character Set, is the modern way
@@ -935,7 +929,6 @@ sect(What is zsh's support for Unicode/UTF-8?)
   this becomes a production release.)  This is discussed more
   fully below, see `Multibyte input and output'.
 
-
 sect(Why does my bash script report an error when I run it under zsh?)
 label(28)
 
@@ -996,7 +989,6 @@ label(28)
   languages and adjusting it accordingly, just like you would
   when translating a book from American English to British English.
 
-
 chapter(How to get various things to work)
 
 sect(Why does mytt($var) where mytt(var="foo bar") not do what I expect?)
@@ -1166,7 +1158,6 @@ sect(In which startup file do I put...?)
   put in tt(.zshrc)
   to save your history.
 
-
 sect(What is the difference between `export' and the tt(ALL_EXPORT) option?)
 
   Normally, you would put a variable into the environment by using
@@ -1192,7 +1183,6 @@ sect(What is the difference between `export' and the tt(ALL_EXPORT) option?)
   it immediately afterwards.  Only those variables will be automatically
   exported.
 
-
 sect(How do I turn off spelling correction/globbing for a single command?)
 
   In the first case, you presumably have mytt(setopt correctall) in an
@@ -1217,7 +1207,6 @@ sect(How do I turn off spelling correction/globbing for a single command?)
   Note also that a shell function won't work: the no... directives must
   be expanded before the rest of the command line is parsed.
 
-
 sect(How do I get the Meta key to work on my xterm?)
 label(35)
 
@@ -1255,7 +1244,6 @@ label(35)
   each byte is used to indicate a part of a multibyte character.  See
   link(chapter 5)(c5).
 
-
 sect(How do I automatically display the directory in my xterm title bar?)
 
   You should use the special function mytt(chpwd), which is called when
@@ -1283,7 +1271,6 @@ sect(How do I automatically display the directory in my xterm title bar?)
   directly: just put mytt(chpwd) in tt(.zshrc) after it is defined or \
   autoloaded.
 
-
 sect(How do I make the completion list use eight bit characters?)
 
   If you are sure your terminal handles this, the easiest way from versions
@@ -1297,7 +1284,6 @@ sect(How do I make the completion list use eight bit characters?)
   possibility may be to set tt(LC_ALL=en_US).  For older versions of the
   shell, there is no easy way out.
 
-
 sect(Why do the cursor (arrow) keys not work?  (And other terminal oddities.))
 
   The cursor keys send different codes depending on the terminal; zsh
@@ -1365,7 +1351,6 @@ sect(Why do the cursor (arrow) keys not work?  (And other terminal oddities.))
   what we used to get the cursor keys above), replace mytt(echoti smkx)
   with mytt(echotc ks) and replace mytt(echoti rmkx) with mytt(echotc ke).
 
-
 sect(Why does my terminal act funny in some way?)
 
   If you are using an OpenWindows cmdtool as your terminal, any
@@ -1408,7 +1393,6 @@ sect(Why does my terminal act funny in some way?)
   afterwards: just the modes it uses itself and a number of special
   processing characters (see the tt(stty(1)) manual page).
 
-
 sect(Why does zsh not work in an Emacs shell mode any more?)
 
   (This information comes from Bart Schaefer and other zsh-workers.)
@@ -1438,7 +1422,6 @@ sect(Why does zsh not work in an Emacs shell mode any more?)
   )
   to ~/.emacs.
 
-
 sect(Why do my autoloaded functions not autoload [the first time]?)
 
   The problem is that there are two possible ways of autoloading a
@@ -1484,7 +1467,6 @@ sect(Why do my autoloaded functions not autoload [the first time]?)
   parentheses removes the directory part of the filenames, leaving
   just the function names.)
 
-
 sect(How does base arithmetic work?)
 
   The ksh syntax is now understood, i.e.
@@ -1528,7 +1510,6 @@ sect(How does base arithmetic work?)
     print $(( [#16] 255 ))
   )
 
-
 sect(How do I get a newline in my prompt?)
 label(313)
 
@@ -1551,7 +1532,6 @@ label(313)
   is a neat way of doing what you want.  Note that it is the quotes, not
   the prompt expansion, which turns the `tt(\n)' into a newline.
 
-
 sect(Why does mytt(bindkey ^a command-name) or mytt(stty intr ^-) do something funny?)
 
   You probably have the extendedglob option set in which case tt(^) and tt(#)
@@ -1561,7 +1541,6 @@ sect(Why does mytt(bindkey ^a command-name) or mytt(stty intr ^-) do something f
   See link(3.27)(327) if you want to know more about the pattern
   character mytt(^).
 
-
 sect(Why can't I bind tt(\C-s) and tt(\C-q) any more?)
 
   The control-s and control-q keys now do flow control by default,
@@ -1575,7 +1554,6 @@ sect(Why can't I bind tt(\C-s) and tt(\C-q) any more?)
   control and hence restoring the use of the keys: put mytt(setopt
   noflowcontrol) in your tt(.zshrc) file.
 
-
 sect(How do I execute command mytt(foo) within function mytt(foo)?)
 
   The command mytt(command foo) does just that.  You don't need this with
@@ -1587,7 +1565,6 @@ sect(How do I execute command mytt(foo) within function mytt(foo)?)
   using `command'.  If mytt(foo) is a builtin rather than an external
   command, use mytt(builtin foo) instead.
 
-
 sect(Why do history substitutions with single bangs do something funny?)
 
   If you have a command like "tt(echo !-2:$ !$)", the first history
@@ -1596,7 +1573,6 @@ sect(Why do history substitutions with single bangs do something funny?)
   tt(!-2:$).  The option tt(CSH_JUNKIE_HISTORY) makes all single bangs refer
   to the last command.
 
-
 sect(Why does zsh kill off all my background jobs when I logout?)
 
   Simple answer: you haven't asked it not to.  Zsh (unlike [t]csh) gives
@@ -1614,13 +1590,11 @@ sect(Why does zsh kill off all my background jobs when I logout?)
   Likewise, you can start a background job with mytt(&!) instead of just
   mytt(&) at the end, which will automatically disown the job.
 
-
 sect(How do I list all my history entries?)
 
   Tell zsh to start from entry 1: mytt(history 1).  Those entries at the
   start which are no longer in memory will be silently omitted.
 
-
 sect(How does the alternative loop syntax, e.g. mytt(while {...} {...}) \
 work?)
 
@@ -1678,7 +1652,6 @@ work?)
   manual), which you are in any case encouraged even more strongly not
   to use in programs as it can be very confusing.
 
-
 sect(Why is my history not being saved?)
 label(321)
 
@@ -1696,7 +1669,6 @@ label(321)
   above.  There are also various options affecting history; see the
   manual.
 
-
 sect(How do I get a variable's value to be evaluated as another variable?)
 
   The problem is that you have a variable tt($E) containing the string
@@ -1733,7 +1705,6 @@ sect(How do I get a variable's value to be evaluated as another variable?)
   it, this works).  So in mytt(${${E}}), the internal mytt(${...})
   actually does nothing.
 
-
 sect(How do I prevent the prompt overwriting output when there is no newline?)
 
   The problem is normally limited to zsh versions prior to 4.3.0 due to the
@@ -1776,7 +1747,6 @@ sect(How do I prevent the prompt overwriting output when there is no newline?)
   One final alternative is to put a newline in your prompt -- see question
   link(3.13)(313) for that.
 
-
 sect(What's wrong with cut and paste on my xterm?)
 
   On the majority of modern UNIX systems, cutting text from one window and
@@ -1815,7 +1785,6 @@ sect(What's wrong with cut and paste on my xterm?)
      in the tt(zshparam) manual page for details.
   )
 
-
 sect(How do I get coloured prompts on my colour xterm?)
 
   (Or `color xterm', if you're reading this in black and white.)
@@ -1859,7 +1828,6 @@ sect(How do I get coloured prompts on my colour xterm?)
   `mytt(<ESC>[0m)' puts printing back to normal so that the rest of the line
   is unchanged.
 
-
 sect(Why is my output duplicated with `tt(foo 2>&1 >foo.out | bar)'?)
 
   This is a slightly unexpected effect of the option tt(MULTIOS), which is
@@ -1903,7 +1871,6 @@ sect(Why is my output duplicated with `tt(foo 2>&1 >foo.out | bar)'?)
   (to the pipe) and start anew with tt(>foo.out) instead of adding it as a
   redirection target to stdout.
 
-
 sect(What are these `^' and `~' pattern characters, anyway?)
 label(327)
 
@@ -2030,7 +1997,6 @@ label(327)
      in the current directory or any parent.)
   )
 
-
 sect(How do I edit the input buffer in $EDITOR?)
 label(328)
 
@@ -2046,7 +2012,6 @@ label(328)
   command-line for editing.  The command will not be automatically executed;
   quitting the editor will only return to zsh's command-line editing mode.
 
-
 sect(Why does `which' output for missing commands go to stdout?)
 
   The issue is that if you run:
@@ -2076,7 +2041,6 @@ sect(Why does `which' output for missing commands go to stdout?)
   other Bourne-style shells it is in fact self-consistent.  Note that
   the exit status does reflect the fact the command can't be found.
 
-
 sect(Why doesn't the expansion mytt(*.{tex,aux,pdf}) do what I expect?)
 
   Based on the behaviour of some other shells, you might guess that the
@@ -2114,10 +2078,8 @@ sect(Why doesn't the expansion mytt(*.{tex,aux,pdf}) do what I expect?)
   This is harder for the user to remember but easier for the shell to
   parse!
 
-
 chapter(The mysteries of completion)
 
-
 sect(What is completion?)
 
   `Completion' is where you hit a particular command key (TAB is the
@@ -2147,7 +2109,6 @@ sect(What is completion?)
   compinit; compinit)' in your tt(.zshrc) should be enough if the system is
   installed properly.
 
-
 sect(What sorts of things can be completed?)
 label(42)
 
@@ -2171,7 +2132,6 @@ label(42)
   `anything where an automated guess is possible'.  Just hit TAB
   and see if the shell manages to guess correctly.
 
-
 sect(How does zsh deal with ambiguous completions?)
 
   Often there will be more than one possible completion: two files
@@ -2209,7 +2169,6 @@ sect(How does zsh deal with ambiguous completions?)
   from version 3.1 tt(LIST_AMBIGUOUS) is set by default; if you use
   autolist, you may well want to `unsetopt listambiguous'.
 
-
 sect(How do I complete in the middle of words / just what's before the cursor?)
 
   Sometimes you have a word on the command-line which is incomplete in the
@@ -2238,7 +2197,6 @@ sect(How do I complete in the middle of words / just what's before the cursor?)
   can expand to tt(/usr/local/bin) or anything else that matches.  This
   saves you having to expand the middle part of the path separately.
 
-
 sect(How do I get started with programmable completion?)
 label(45)
 
@@ -2251,7 +2209,6 @@ label(45)
   tells you how to configure the completion system and chapter 15 how
   to write your own completion functions.
 
-
 sect(Suppose I want to complete all files during a special completion?)
 
   If you're using the completion system the shell will decide what
@@ -2283,7 +2240,6 @@ sect(Suppose I want to complete all files during a special completion?)
   completion.  Your actual completer style may include other actions,
   such as expansion or approximate completion.
 
-
 chapter(Multibyte input and output)
 label(c5)
 
@@ -2334,7 +2290,6 @@ sect(What is multibyte input?)
   way, for example on Windows, but the shell can't deal directly with text
   in those formats.)
 
-
 sect(How does zsh handle multibyte input and output?)
 
   Until version 4.3, zsh didn't handle multibyte input properly at all.
@@ -2379,7 +2334,6 @@ sect(How does zsh handle multibyte input and output?)
   in inverse video.  Highlighting of such special characters can
   be modified using the new array parameter tt(zle_highlight).
 
-
 sect(How do I ensure multibyte input and output work on my system?)
 
   Once you have a version of zsh with multibyte support, you need to
@@ -2451,7 +2405,6 @@ sect(How do I ensure multibyte input and output work on my system?)
   to compile with the tt(MULTIBYTE) option enabled, but the system
   didn't provide full support for it.
 
-
 sect(How can I input characters that aren't on my keyboard?)
 
   Two functions are provided with zsh that help you input characters.
@@ -2495,7 +2448,6 @@ url(http://www.unicode.org/charts/)(http://www.unicode.org/charts/).
   See also url(http://www.cl.cam.ac.uk/~mgk25/unicode.html#input)(http://www.cl.cam.ac.uk/~mgk25/unicode.html#input)
   for general information on entering Unicode characters from a keyboard.
 
-
 chapter(The future of zsh)
 
 sect(What bugs are currently known and unfixed? (Plus recent \
@@ -2512,7 +2464,6 @@ label(61)
   most important changes, and in particular draws attention to
   incompatibilities you might notice.
 
-
 sect(Where do I report bugs, get more info / who's working on zsh?)
 label(62)
 
@@ -2577,7 +2528,6 @@ label(62)
   Of course, you can also post zsh queries to the Usenet group
   comp.unix.shell; if all else fails, you could even e-mail me.
 
-
 sect(What's on the wish-list?)
 
   The code bears the marks of the ages and many things could be done much
@@ -2601,7 +2551,6 @@ sect(What's on the wish-list?)
   it() Option for glob qualifiers to follow perl syntax (a traditional item).
   )
 
-
 sect(Did zsh have problems in the year 2000?)
 
   Not that I heard of; it's up to you to be careful with two-digit dates,
@@ -2609,7 +2558,6 @@ sect(Did zsh have problems in the year 2000?)
   and also by the command `tt(print -P)'.  Earlier versions of zsh may
   show problems here.
 
-
 sect(When reporting a bug, how do I reduce my mytt(.zshrc) into a minimal reproduction recipe?)
 
   When reporting a bug, the gold standard is to include with the bug
@@ -2623,9 +2571,8 @@ sect(When reporting a bug, how do I reduce my mytt(.zshrc) into a minimal reprod
   and then, within that instance of the shell, run a minimal short
   sequence of commands that reproduces the bug.  A good way to devise
   such recipes is the following:
-
 COMMENT(For reference, here's Vim's write-up of a similar process:
-https://github.com/chrisbra/vim_faq/blob/de424bd8e08bcf0e6b1e0563ee49514dfed926ae/vim_faq.txt#L1153-L1228)
+https://github.com/chrisbra/vim_faq/blob/de424bd8e08bcf0e6b1e0563ee49514dfed926ae/vim_faq.txt#L1153-L1228)\
 
   enumeration(
   myeit() First, ensure the bug is reproducible.  To do this, start
@@ -2701,7 +2648,6 @@ https://github.com/chrisbra/vim_faq/blob/de424bd8e08bcf0e6b1e0563ee49514dfed926a
   Bug reports should be emailed to the mytt(zsh-workers@zsh.org) public
   mailing list; see link(6.2)(62) for details.
 
-
 nsect(Acknowledgments:)
 
 Thanks to zsh-list, in particular Bart Schaefer, for suggestions
@@ -2713,7 +2659,6 @@ thanks.  The world is eternally in the debt of Paul Falstad for inventing
 zsh in the first place (though the wizzo extended completion is by Sven
 Wischnowsky).
 
-
 nsect(Copyright Information:)
 
 This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997,

  parent reply	other threads:[~2022-06-12 13:11 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-01-29 19:35 Bart Schaefer
2021-02-01 16:13 ` Daniel Shahaf
2021-02-01 20:11   ` Bart Schaefer
2021-02-03 11:15     ` Daniel Shahaf
2022-06-12 13:10 ` Jun. T [this message]
2022-06-12 16:26   ` Bart Schaefer
2022-06-13 14:58     ` Jun. T
2022-06-13 15:04       ` Peter Stephenson
2022-06-13 17:13         ` Jun. T
2022-06-14  8:38         ` Peter Stephenson

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=3391D472-6F5D-481E-B114-1E0D1310ED63@kba.biglobe.ne.jp \
    --to=takimoto-j@kba.biglobe.ne.jp \
    --cc=zsh-workers@zsh.org \
    --subject='Re: [PATCH] FAQ update for aliasing' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://git.vuxu.org/mirror/zsh/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).