From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Tino Calancha Newsgroups: gmane.emacs.bugs Subject: bug#25193: [PATCH] Improve the doc of re-search-forward and re-search-backward. Date: Sun, 2 Apr 2017 13:57:00 +0900 (JST) Message-ID: References: <1481599231-19381-1-git-send-email-hong@topbug.net> <87mvg0pcnc.fsf@gmail.com> <87o9wfxvvy.fsf@users.sourceforge.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; format=flowed; charset=US-ASCII X-Trace: blaine.gmane.org 1491109106 15626 195.159.176.226 (2 Apr 2017 04:58:26 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 2 Apr 2017 04:58:26 +0000 (UTC) User-Agent: Alpine 2.20 (DEB 67 2015-01-07) Cc: 25193@debbugs.gnu.org, Tino Calancha , Hong Xu To: npostavs@users.sourceforge.net Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Apr 02 06:58:16 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cuXaZ-0001nU-AJ for geb-bug-gnu-emacs@m.gmane.org; Sun, 02 Apr 2017 06:58:07 +0200 Original-Received: from localhost ([::1]:53687 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cuXad-0005JY-Jc for geb-bug-gnu-emacs@m.gmane.org; Sun, 02 Apr 2017 00:58:11 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:33054) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cuXaX-0005JG-NZ for bug-gnu-emacs@gnu.org; Sun, 02 Apr 2017 00:58:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cuXaU-00087y-IU for bug-gnu-emacs@gnu.org; Sun, 02 Apr 2017 00:58:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:58089) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cuXaU-00087q-E6 for bug-gnu-emacs@gnu.org; Sun, 02 Apr 2017 00:58:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cuXaU-0003m4-2W for bug-gnu-emacs@gnu.org; Sun, 02 Apr 2017 00:58:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Tino Calancha Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 02 Apr 2017 04:58:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 25193 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 25193-submit@debbugs.gnu.org id=B25193.149110903214450 (code B ref 25193); Sun, 02 Apr 2017 04:58:02 +0000 Original-Received: (at 25193) by debbugs.gnu.org; 2 Apr 2017 04:57:12 +0000 Original-Received: from localhost ([127.0.0.1]:56288 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cuXZg-0003kz-Is for submit@debbugs.gnu.org; Sun, 02 Apr 2017 00:57:12 -0400 Original-Received: from mail-pg0-f66.google.com ([74.125.83.66]:34824) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cuXZe-0003km-Ak for 25193@debbugs.gnu.org; Sun, 02 Apr 2017 00:57:10 -0400 Original-Received: by mail-pg0-f66.google.com with SMTP id g2so23633194pge.2 for <25193@debbugs.gnu.org>; Sat, 01 Apr 2017 21:57:10 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:date:to:cc:subject:in-reply-to:message-id:references :user-agent:mime-version; bh=6w10KdxNHlnpqQtosgRbDByt90LoYy9+qfO55g2RYQI=; b=UO7E1W+dqns1Q/0dBNLYjn+UfnnHQk+7rq7pp/05cNe07mrStL6LVDpQH78hPvdP0C wGfbm6on7/0g1VgNZmflTPr5mCn6V6EJ33o+riOilYcnXDv+5hc1rvMApXrBRJspX8OC pgehnC07Ow4N7/76NTxJX3xir73KszS4ZhZOvo8yXfQS+Nuds1O1IBuBK0RfkANbHCW2 oz6q6/ZY8O5/5SbNeRYFo0NBTv9EVNW/UGeqV6B4KJ/WXxG3AIc230LreYphFCb1o301 677AY6APtGvgQ1Eoo7cZquiYIfv8RiS5G9bVD47XIANyqWOftUG7E6avnzCWZMmMYIQD r0xw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:date:to:cc:subject:in-reply-to:message-id :references:user-agent:mime-version; bh=6w10KdxNHlnpqQtosgRbDByt90LoYy9+qfO55g2RYQI=; b=m8PWyfZai+vjUUzQHjPukoRQf4uCcA7WwrvrdLXKaLprsu3n1egQaoPSRq0Wt82Kpo 9XEx+Is8G1a2u6nwqx6EhYgcgk45rhu7n2cMqgwjOHj+2ZQIo7JuVS/LkdLVnRK209sI lXqzZH3PP33qCNeNiSvXq/qlLmRtRfZWhfmNdILbSPtIL4uVD5qPaulK053kNUfT22Na haYP6bcRFxE0689JcyXCRl/49rqQb+ze4AEEnOPa8lChyxKwXgE0dra4/ZPGRT4atJ6Z IE+96BsqRQo79+WQIJz3ReklPzC+u3pMEdYHK+DUkscfgfuiea4LimjIee9ID8BQNGqc y82A== X-Gm-Message-State: AFeK/H1PSQioufWqd/QIgAa3osAmPg49AbgZD+x2SNVcZ1Nkxor1I0gFoFOFWD82wB00xA== X-Received: by 10.98.160.194 with SMTP id p63mr10454108pfl.72.1491109024375; Sat, 01 Apr 2017 21:57:04 -0700 (PDT) Original-Received: from calancha-pc (234.204.100.220.dy.bbexcite.jp. [220.100.204.234]) by smtp.gmail.com with ESMTPSA id i15sm18455654pfj.51.2017.04.01.21.57.02 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sat, 01 Apr 2017 21:57:03 -0700 (PDT) X-Google-Original-From: Tino Calancha X-X-Sender: calancha@calancha-pc In-Reply-To: <87o9wfxvvy.fsf@users.sourceforge.net> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:131201 Archived-At: On Sun, 2 Apr 2017, npostavs@users.sourceforge.net wrote: > Tino Calancha writes: > >> Thanks for the report. >> You could refer for details to the manual, maybe providing a link to the >> proper node; but you don't want to refer to the doc string of another >> function 'B' to document the arguments of the current function 'A'. >> IMO the doc string of 'A' must introduce all its arguments. >> >> Otherwise, i am worry you could go an step further, f.i. >> `search-forward'/ `search-backward' share the same optional arguments, so: > > I think it's okay to point to other functions, as long as we keep the > chain to length 1. Maybe OK (see below for the rest of my answer, like in my example :) >> 1) doc string `re-search-backward': See the doc string of `re-search-forward' >> for details. >> 2) doc string `re-search-forward': See the doc string of >> `search-backward' for details. >> 3) doc string `search-backward': See the doc string of >> `search-forward' for details. >> 4) doc string `search-forward': Wow, you are are very persistent >> user! Please see the manual for details, i am a very busy doc string. > > :D > > But if all of `re-search-backword', re-search-forward', > `search-backward', would say "see doc string of `search-forward'" I > think it would be okay. OK for me if it's just 1 jump, but i slightly prefer self-contained docstrings. Don't know what Eli or John might think about it.