From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.devel Subject: RE: More metaproblem Date: Sun, 7 Dec 2014 15:00:38 -0800 (PST) Message-ID: 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> <85y4qjdsg0.fsf@stephe-leake.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1417993270 31830 80.91.229.3 (7 Dec 2014 23:01:10 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 7 Dec 2014 23:01:10 +0000 (UTC) To: Stephen Leake , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Dec 08 00:01:03 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 1Xxkp4-0002PI-EI for ged-emacs-devel@m.gmane.org; Mon, 08 Dec 2014 00:01:02 +0100 Original-Received: from localhost ([::1]:59488 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xxkp3-0002q4-TX for ged-emacs-devel@m.gmane.org; Sun, 07 Dec 2014 18:01:01 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56150) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xxkos-0002pt-8G for emacs-devel@gnu.org; Sun, 07 Dec 2014 18:00:58 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xxkoh-0008NK-OQ for emacs-devel@gnu.org; Sun, 07 Dec 2014 18:00:50 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:33240) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xxkoh-0008NA-8j for emacs-devel@gnu.org; Sun, 07 Dec 2014 18:00:39 -0500 Original-Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id sB7N0bgY028079 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sun, 7 Dec 2014 23:00:38 GMT Original-Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id sB7N0ahj002836 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sun, 7 Dec 2014 23:00:37 GMT Original-Received: from abhmp0015.oracle.com (abhmp0015.oracle.com [141.146.116.21]) by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id sB7N0aWP002982; Sun, 7 Dec 2014 23:00:36 GMT In-Reply-To: <85y4qjdsg0.fsf@stephe-leake.org> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8.2 (807160) [OL 12.0.6691.5000 (x86)] X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-Received-From: 156.151.31.81 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:179326 Archived-At: > 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. Good. > >> > 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." >=20 > But the information in ./CONTRIBUTE is _not_ for users; it is for > developers. Developers are users. Some users are developers. There is no reason not to provide such info for users in general (IMHO). Especially if we want to encourage users to contribute. > > 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. >=20 > 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). I don't have a problem with that. My preference would probably be to add it to the Emacs manual, a priori. But I haven't heard any argument to convince me that it should be in a separate manual - perhaps I would change my mind if I did. The argument that users are different from developers makes little sense to me. Might as well say that because some users don't use the Calendar we should move all of the Calendar stuff out of the Emacs manual into a separate one. Or all of the International stuff. Or all of the Mail stuff. Now there's a good candidate! Move all of the Sending Mail, Rmail, and Gnus stuff to a separate manual. Yes, please. ;-) > Texinfo is _almost_ as easy to edit as plain text, but there is some > cost. What is the actual gain? What is the gain of having this information in Info form? See my previous messages. Should be a no-brainer. And the gain of having it in the Emacs manual is to invite Emacs users to consider contributing, and how to do so. > You have to know the file is there, or know how to look for it. That's another argument for moving the information to the manual. > That's why is was move up from etc/; easier to find. It's also > why it's referenced from the Emacs manual. Why just reference it when you can include it? Why use a plain-text file when you can use Info? And it will automatically end up as HTML on the web, in the same location as the other Emacs information. > However, I agree an "Emacs developers manual" in the top-level Info > menu would be even easier to find. >=20 > Whether it is in info or plain text (or some other format) is a > secondary issue. OK. I don't care which is considered primary and which secondary. To me, both are good ideas: move it to Info, and put its node link in the top-level `dir' menu or the top-level menu of the Emacs manual. > 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 imagine there are more than 330 lines for all of the "internal" developer/contributor information. At least I hope there are. XEmacs has a nice internals manual, IIUC. Doesn't GNU Emacs deserve similar? > I hear you saying that you prefer Info. I'm still not clear > _why_ you prefer Info, for this specific information. It is information for Emacs users on how to help develop Emacs. We have some such info in the Elisp manual (the various "conventions" nodes). I think that other "developer" info deserves a similar treatment, whatever manual it ends up in. > I think you would reply "everyone that uses Emacs simply > _expects_ all documentation to be in Info".=20 I don't know whether they do. But if you put it there they will. ;-) And why shouldn't they? > I can see why that might be true. I fall back on "developers > are not everyone"=20 Not everyone uses Gnus, either. Every developer is a user. Some users contribute to development. Some do so by filing bugs. Some by fixing bugs. Some by testing bug fixes. Some by maintaining releases & distribution. Some by coming up with new features (think how many features were originally developed by users, in 3rd-party libraries - Emacs itself is full of them). =20 > and "having different conventions for developers and users > makes it clearer which is which". Not very strong points, > I'll admit. It can only be clear in the sense of roles. Now you wear your user hat; now you wear your developer hat. But yes, the developer-oriented doc should be written with an Emacs developer orientation, of course. Just as the Elisp doc is written with an Elisp user orientation. > For me, it really comes down to ease of maintenance and use. Use, fine. Maintenance should not be a primary concern. This is no different from maintaining and using any manual. > 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. I hope someone does. I think Emacs would benefit. Just one opinion. > > I'm talking also about details that explain conventions and > > methods used for developing/maintaining Emacs. >=20 > Where are they? The ones I'm aware of are referenced from the > current trunk version of ./CONTRIBUTE. I am deliberately > ignoring the wiki. Sorry; I don't know. But if they were in the manual I would be able to tell you.