From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stephen Leake Newsgroups: gmane.emacs.devel Subject: Re: More metaproblem Date: Sun, 07 Dec 2014 16:07:59 -0600 Message-ID: <85y4qjdsg0.fsf@stephe-leake.org> References: <20141203142859.24393.98673@vcs.savannah.gnu.org> <20141203192721.GE12748@thyrsus.com> <547F6774.50700@cs.ucla.edu> <838uio5vjw.fsf@gnu.org> <20141203211447.GB15111@thyrsus.com> <871toge5zw.fsf@floss.red-bean.com> <83388v6hsq.fsf@gnu.org> <87egsftgd5.fsf@ktab.red-bean.com> <83egsf3yci.fsf@gnu.org> <87iohq6nvn.fsf@ktab.red-bean.com> <85bnnhkuep.fsf@stephe-leake.org> <857fy4ipsd.fsf@stephe-leake.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1417990118 18017 80.91.229.3 (7 Dec 2014 22:08:38 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 7 Dec 2014 22:08:38 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Dec 07 23:08:32 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Xxk0E-0002ya-A3 for ged-emacs-devel@m.gmane.org; Sun, 07 Dec 2014 23:08:30 +0100 Original-Received: from localhost ([::1]:59362 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xxk0D-0008CW-QN for ged-emacs-devel@m.gmane.org; Sun, 07 Dec 2014 17:08:29 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47059) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xxjzv-0008CQ-An for emacs-devel@gnu.org; Sun, 07 Dec 2014 17:08:16 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xxjzp-0006W1-8D for emacs-devel@gnu.org; Sun, 07 Dec 2014 17:08:11 -0500 Original-Received: from dnvrco-outbound-snat.email.rr.com ([107.14.73.225]:60254 helo=dnvrco-oedge-vip.email.rr.com) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xxjzp-0006Vk-1I for emacs-devel@gnu.org; Sun, 07 Dec 2014 17:08:05 -0500 Original-Received: from [70.94.38.149] ([70.94.38.149:53407] helo=TAKVER) by dnvrco-oedge03 (envelope-from ) (ecelerity 3.5.0.35861 r(Momo-dev:tip)) with ESMTP id 6F/A8-16169-1CFC4845; Sun, 07 Dec 2014 22:08:02 +0000 In-Reply-To: (Drew Adams's message of "Sat, 6 Dec 2014 11:24:28 -0800 (PST)") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3.94 (windows-nt) X-RR-Connecting-IP: 107.14.64.142:25 X-Authority-Analysis: v=2.1 cv=W762VHmk c=1 sm=1 tr=0 a=AppmJ/7ZOOFWL/q6u6u93g==:117 a=AppmJ/7ZOOFWL/q6u6u93g==:17 a=ayC55rCoAAAA:8 a=fNEgcOh0sVsA:10 a=9i_RQKNPAAAA:8 a=yPCof4ZbAAAA:8 a=mDV3o1hIAAAA:8 a=aFXqz4MuSzITmaIyF7QA:9 a=fMFCAVngmFAvRo2h:21 a=KSiCloM2LjBatRo3:21 X-Cloudmark-Score: 0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 107.14.73.225 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:179318 Archived-At: Drew Adams writes: >> As you say below, I don't think we should duplicate the information >> in the two files, but I would not be averse to moving the info >> into the manual, and leaving ./CONTRIBUTE as a reference. > > If you agree that we should not duplicate the information, then > why would you leave ./CONTRIBUTE? That's duplication, no? I meant "change the content of ./CONTRIBUTE to refer to the manual". So people who look for a file CONTRIBUTE will still find the information. >> > IMO, it does not matter whether such info is detailed, boring, >> > internal stuff. It would still be good to move it from other >> > files to the official doc, and give it the proper love that >> > such doc requires. >> >> I consider ./CONTRIBUTE to _be_ "official doc". Why do you think >> otherwise? > > It is official. But it is not in Info form, and it deserves > to be (users deserve it to be). That's what I meant. Perhaps > I should have said "move it from other files to where > the rest of the official is presented to users: in Info." But the information in ./CONTRIBUTE is _not_ for users; it is for developers. > My (personal) answer is that it should be in Info, not just > on the web somewhere, and not just in a file in the Emacs > distribution somewhere, and not just as a pointer to a mailing > list somewhere. > > Imagine if all of the important Emacs documentation had only > the form/accessibility you are referring to. Would you be > content to replace the Emacs manual (Info) with a link to a > web page or a local plain-text file? I wouldn't want that. As an Emacs _user_, I agree, I want the Emacs user manual in Info. As an Emacs _developer_, it makes some sense to use Info, but it should be in a separate manual (as you allow below). Texinfo is _almost_ as easy to edit as plain text, but there is some cost. What is the actual gain? You have to know the file is there, or know how to look for it. That's why is was move up from etc/; easier to find. It's also why it's referenced from the Emacs manual. However, I agree an "Emacs developers manual" in the top-level Info menu would be even easier to find. Whether it is in info or plain text (or some other format) is a secondary issue. We are only talking about 330 lines, that have been in plain text for a long time. Is there really a big reason to change? I hear you saying that you prefer Info. I'm still not clear _why_ you prefer Info, for this specific information. I think you would reply "everyone that uses Emacs simply _expects_ all documentation to be in Info". I can see why that might be true. I fall back on "developers are not everyone" and "having different conventions for developers and users makes it clearer which is which". Not very strong points, I'll admit. For me, it really comes down to ease of maintenance and use. I find the plain text format slightly easier to both maintain and use (partly because I have a C-F12 function that does 'find-file-or-url-at-point'). But if someone else wants to put in the time to move it to texinfo, I won't object. If the file gets much longer, I would want to move it to texinfo. >> > 2. Let users know that they can contribute, >> >> That is certainly implied by the Free Software nature of Emacs. > > I think you are missing the point of my suggestion. Putting this > information in the Emacs manual would make it much more visible > to "ordinary" users (and much more navigable). (IMHO) (info "(emacs)Contributing") Feel free to submit patches. >> > 3. Encourage people to reference it, as they do now for >> > questions about key-binding conventions etc. >> >> I don't see why >> http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributin >> g.html would be a better/simpler/easier reference than ./CONTRIBUTE. > > No one said it would be. I think you have not understood my > suggestion well enough. You said "encourage people to reference it". Hmm, since we are talking about info, the proper reference would be (info "(emacs)Contributing"). Much better. If it's a (slightly) longer string, that (slightly) discourages me from referencing it. Perhaps if everyone expects all docs to be in Info, you would feel reluctant to reference something that is not in Info? That makes some sense. >> If you need to read ./CONTRIBUTE, you already have the source on >> your disk. > > Having the information on your disk is not enough. Having it on > the web is not enough. It should be available from Emacs, It is, if it is on your disk. > in Info form. That is the issue under discussion. >> Exception: the short list of "other ways to contribute" should be on >> a web page somewhere. >> >> > Just a thought. Disclaimer: I'm not familiar with the >> > info I'm conjecturing about. >> >> Please take a moment to read it; it's only 339 lines, about 1/3 >> white space. > > I'm talking also about details that explain conventions and > methods used for developing/maintaining Emacs. Where are they? The ones I'm aware of are referenced from the current trunk version of ./CONTRIBUTE. I am deliberately ignoring the wiki. -- -- Stephe