From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=MAILING_LIST_MULTI, RCVD_IN_DNSWL_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.2 Received: (qmail 3097 invoked from network); 7 May 2020 21:24:39 -0000 Received-SPF: pass (primenet.com.au: domain of zsh.org designates 203.24.36.2 as permitted sender) receiver=inbox.vuxu.org; client-ip=203.24.36.2 envelope-from= Received: from ns1.primenet.com.au (HELO primenet.com.au) (203.24.36.2) by inbox.vuxu.org with ESMTPUTF8; 7 May 2020 21:24:39 -0000 Received: (qmail 16723 invoked by alias); 7 May 2020 21:24:31 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: List-Unsubscribe: X-Seq: 45791 Received: (qmail 5604 invoked by uid 1010); 7 May 2020 21:24:31 -0000 X-Qmail-Scanner-Diagnostics: from wout1-smtp.messagingengine.com by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.102.2/25801. spamassassin: 3.4.4. Clear:RC:0(64.147.123.24):SA:0(-1.1/5.0):. Processed in 3.822133 secs); 07 May 2020 21:24:31 -0000 X-Envelope-From: d.s@daniel.shahaf.name X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | Received-SPF: none (ns1.primenet.com.au: domain at daniel.shahaf.name does not designate permitted sender hosts) X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduhedrkedtgdduheekucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucenucfjughrpefhvffufffkofggtgfgsehtkedttd ertdejnecuhfhrohhmpeffrghnihgvlhcuufhhrghhrghfuceougdrshesuggrnhhivghl rdhshhgrhhgrfhdrnhgrmhgvqeenucggtffrrghtthgvrhhnpeeljedtjeffudegieffje egudeitdefueetgeeklefgleeitefgueeihfeiueekleenucffohhmrghinhepghhrvggv nhgvnhgurdhorhhgrdhukhdpghhithhhuhgsrdgtohhmpdifihhkihhpvgguihgrrdhorh hgnecukfhppedutdelrdeiiedrudehrddvfeelnecuvehluhhsthgvrhfuihiivgeptden ucfrrghrrghmpehmrghilhhfrhhomhepugdrshesuggrnhhivghlrdhshhgrhhgrfhdrnh grmhgv X-ME-Proxy: From: Daniel Shahaf To: zsh-workers@zsh.org Subject: [PATCH] FAQ: Explain how to binary search one's dotfiles Date: Thu, 7 May 2020 21:23:51 +0000 Message-Id: <20200507212351.1501-1-danielsh@tarpaulin.shahaf.local2> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Feedback is welcome. I've stared at the text for too long to be able to find any bugs it may have remaining. myeit() creates a numbered list. (The "eit" stand for "enumerated items", I guess.) Cheers, Daniel Etc/FAQ.yo | 105 +++++++++++++++++++++++++++++++++++++++++++++++-- Util/zyodl.vim | 6 ++- 2 files changed, 107 insertions(+), 4 deletions(-) diff --git a/Etc/FAQ.yo b/Etc/FAQ.yo index d1f8b7d83..afc01b2bc 100644 --- a/Etc/FAQ.yo +++ b/Etc/FAQ.yo @@ -49,16 +49,22 @@ def(item)(2)( ARG1: ARG2)\ def(nofill)(1)(ARG1)\ def(uref)(1)(url(ARG1)(ARG1))\ +COMMENT(TODO: make this expand to a Unicode em dash (U+2014) in HTML output)\ +def(emdash)(0)(\ + whenlatex(---)\ + whenhtml(---)\ + whenman(--)whenms(--)whensgml(--)\ + whentxt(--))\ def(LPAR)(0)(CHAR(40))\ def(RPAR)(1)(CHAR(41)) myreport(Z-Shell Frequently-Asked Questions)(Peter Stephenson)(2010/02/15) COMMENT(-- the following are for Usenet and must appear first)\ description(\ mydit(Archive-Name:) unix-faq/shell/zsh -mydit(Last-Modified:) 2015/05/31 +mydit(Last-Modified:) 2020/05/06 mydit(Submitted-By:) email(coordinator@zsh.org (Peter Stephenson)) mydit(Posting-Frequency:) Monthly -mydit(Copyright:) (C) P.W. Stephenson, 1995--2016 (see end of document) +mydit(Copyright:) (C) P.W. Stephenson, 1995--2020 (see end of document) ) This document contains a list of frequently-asked (or otherwise @@ -150,6 +156,7 @@ Chapter 6: The future of zsh 6.2. Where do I report bugs, get more info / who's working on zsh? 6.3. What's on the wish-list? 6.4. Did zsh have problems in the year 2000? +6.5. When reporting a bug, how do I reduce my mytt(.zshrc) into a minimal reproduction recipe? Acknowledgments @@ -2527,6 +2534,98 @@ sect(Did zsh have problems in the year 2000?) 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 + a myem(minimal reproduction recipe), with which anyone who reads the bug + report can url(reproduce the bug for themselves) + (https://www.chiark.greenend.org.uk/~sgtatham/bugs.html#showmehow) + at will. + + When you run into a bug in the shell, particularly during interactive + use, a reproduction recipe would ideally start by running tt(zsh -f) + 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) + + enumeration( + myeit() First, ensure the bug is reproducible. To do this, start + a new instance of the shell emdash() for example, open a new tab in + your terminal emulator emdash() and reproduce the bug there. + + myeit() Start a new instance of the shell by running the + command mytt(zsh -f) from your regular shell prompt, and reproduce the + bug there. (The mytt(-f) flag inhibits mytt(.zshenv), + mytt(/etc/zprofile), mytt(.zprofile), mytt(/etc/zshrc), and + mytt(.zshrc) from being sourced.) + + If you succeeded in reproducing the bug in mytt(zsh -f), copy the + commands you used and their outputs (from the mytt(zsh -f) invocation + to the point the bug occurred) and include them in your bug report. + Skip the remaining steps of this procedure. + + If, however, the bug happens in your regular shell but not in mytt(zsh + -f), read the next steps. + + myeit() Make a backup of your tt(.zshrc) file. + + myeit() Delete your tt(.zshrc) file, start a new shell, and confirm + that the problem does em(not) reproduce there. (If the problem + does reproduce there, it's caused by something in mytt(.zshenv), + mytt(.zprofile), mytt(/etc/zprofile), or mytt(/etc/zshrc), so apply + this procedure from the top to those files rather than to your + mytt(.zshrc).) + COMMENT(Note that mytt(/etc/zshenv) is not mentioned, since by this + point we have established the bug does not occur under mytt(zsh -f), + which sources mytt(/etc/zshenv).) + COMMENT(mytt(.zlogout) and mytt(/etc/zlogout) aren't mentioned because + they're unlikely to be relevant to most readers.) + + myeit() At this point, you know that the problem is caused by + something in your mytt(.zshrc) file, but not what line exactly. + To find the responsible line, we will use + a url(variation)(https://en.wikipedia.org/wiki/Delta_debugging) + of the url(binary search)(https://en.wikipedia.org/wiki/Binary_search) + algorithm, as follows: + + Suppose your mytt(.zshrc) file has 200 lines. To start, copy + the em(first) half of your mytt(.zshrc) emdash() that is, lines + 1 through 100 emdash() from the backup copy to your live mytt(.zshrc) + file, and check whether the bug reproduces then. Now, empty the live + mytt(.zshrc) file again, and copy the em(second) half of your + mytt(.zshrc) file from the backup to the live mytt(.zshrc) file + emdash() the live file should now contain lines 101 through 200, only + emdash() and see whether the problem reproduces. + + Normally, the bug will reproduce em(either) with lines 1 through 100 + em(or) with lines 101 through 200, but not in both cases. To isolate + the specific line that causes the bug, repeat the above process on the + relevant half of the file: for example, if you've determined that the + bug reproduces when only lines 101 through 200 are installed, check + whether the bug reproduces (a) when only lines 101 through 150 are + installed, and (b) when only lines 151 through 200 are installed. + Repeat the process until the resulting mytt(.zshrc) is minimal. + + It is not important to break the file into two halves exactly. + Breaking the file into two parts sized one-third and two-thirds, for + example, will work equally well. You can even try restoring one line + at a time, but this is impractical for all but the shortest + mytt(.zshrc) files. + + myeit() Include the minimal set of lines you devised in the previous + step, along with the commands you used and their outputs, in your bug + report. + + myeit() Restore your mytt(.zshrc) from backup. + ) + + 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 @@ -2542,7 +2641,7 @@ Wischnowsky). nsect(Copyright Information:) This document is copyright (C) P.W. Stephenson, 1995, 1996, 1997, -1998, 1999, 2000, 2012. This text originates in the U.K. and the author +1998, 1999, 2000, 2012, 2020. This text originates in the U.K. and the author asserts his moral rights under the Copyrights, Designs and Patents Act, 1988. diff --git a/Util/zyodl.vim b/Util/zyodl.vim index 73cd027fd..db92de590 100644 --- a/Util/zyodl.vim +++ b/Util/zyodl.vim @@ -79,7 +79,8 @@ syn match zyodlSpecial "\