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: Sat, 6 Dec 2014 11:24:28 -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> 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 1417893899 5154 80.91.229.3 (6 Dec 2014 19:24:59 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 6 Dec 2014 19:24:59 +0000 (UTC) To: Stephen Leake , emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 06 20:24:52 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 1XxKyI-0006cH-Qk for ged-emacs-devel@m.gmane.org; Sat, 06 Dec 2014 20:24:51 +0100 Original-Received: from localhost ([::1]:55360 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XxKyG-00031o-8M for ged-emacs-devel@m.gmane.org; Sat, 06 Dec 2014 14:24:48 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38746) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XxKy6-00031d-Q8 for emacs-devel@gnu.org; Sat, 06 Dec 2014 14:24:46 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XxKxz-0006Ue-Cd for emacs-devel@gnu.org; Sat, 06 Dec 2014 14:24:38 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:48711) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XxKxz-0006Ua-4v for emacs-devel@gnu.org; Sat, 06 Dec 2014 14:24:31 -0500 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id sB6JOSRB018699 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 6 Dec 2014 19:24:29 GMT Original-Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id sB6JORGx003416 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 6 Dec 2014 19:24:28 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 sB6JORVN020024; Sat, 6 Dec 2014 19:24:27 GMT In-Reply-To: <857fy4ipsd.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: acsinet21.oracle.com [141.146.126.237] 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:179206 Archived-At: > > Would it hurt to put the information you refer to, which is > > aimed at Emacs contributors, into the Emacs manual, as a > > separate section? >=20 > There is such a section; (info "(emacs)Contributing). It just > references > emacs-devel@gnu.org, http://savannah.gnu.org/projects/emacs/ and > etc/CONTRIBUTE. Yes, I know. That is not at all what I meant (and said), which was: "put the information you refer to, which is aimed at Emacs contributors, into the Emacs manual" It's not about providing a reference to some local file or a mailing list. It's about *moving* the complete information to the manual (the Emacs manual or a new, dedicated manual). > 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? The point is to let the manual be the single source of truth. It is a mistake (asking for trouble), IMO, to have two or more such sources. But I'm probably missing something that you are trying to say here. > > 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. >=20 > 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." (And please don't bother to nitpick about there being still other official doc that is also not in Info form. That can be ignored for now, or it can in turn be considered as a candidate for moving to Info.) > > I think that doing this might have these benefits: > > > > 1. Put more of an accent on it, for everyone. >=20 > That comes from _advertising_, not from format. >=20 > It makes it a little more accessible. But ./CONTRIBUTE is on the web > now: http://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE On the web is not in Info. (That's in fact part of the other, parallel discussion initiated by ESR. *Web doc does not sufficient Emacs doc make.*) > I just did a Google search for "Emacs contribute"... > How much more accessible does it need to be? 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. What's good for the Emacs-manual gander is good for the CONTRIBUTE goose. Make that information into a manual (Info) or part of the Emacs manual.=20 > > The content and form would need to be clear and complete, >=20 > That comes from editing skill (I have yet to hear if my edits are > acceptable). By that I meant also that ALL of the information about contributing should be moved to Info. A lot of work goes into making sure that the information in the manuals is clear and complete. I can't speak to whether this is also true for other, non-Info kinds of "official" Emacs doc. If it is, so much the better - just move it to Info. > > 2. Let users know that they can contribute, >=20 > 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) Both of my points #1 and #2 are introduced by this phrase: "I think that doing this might have these benefits:" where "doing this" refers to moving such information completely to the Emacs manual (to Info form, at least, with mirroring on the web). > > and just what's involved (yes, in detail). >=20 > I don't see why the format affects this. Again, the point was to move the complete, detailed information to the manual (Info format), NOT to simply have a reference from the manual, as now. The difference is whether the details are in Info format or not, so yes, the format "affects this" - it's all about the format (and location). > Some have suggested that the current crop of potential contributors > are more comfortable reading web stuff than file stuff; do you agree > with that? Probably. But it doesn't matter whether I agree, or care. My point is that this information belongs with the rest of the Emacs information for users: in the manual. It is of course important that the manuals be mirrored on the web. And as I (and others) made clear in the sister thread, web access to the information is necessary but not sufficient. Manuals on the web do not provide the features that manuals provide *in Emacs*, from Info. Not even close. > > 3. Encourage people to reference it, as they do now for > > questions about key-binding conventions etc. >=20 > 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. > 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, in Info form. It should be integrated with the other user doc. > Exception: the short list of "other ways to contribute" should be on > a web page somewhere. >=20 > > Just a thought. Disclaimer: I'm not familiar with the > > info I'm conjecturing about. >=20 > 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. (And (why not?) detailed information about Emacs internals - such as the doc that exists for XEmacs. But this is not necessarily part of what I proposed in the immediate.) It doesn't matter what I understand or think about the particular detailed information. Information about how to contribute and develop Emacs should be available to users in Info form, IMO. That's all. I have no informed opinion about whether all of it belongs in the Emacs manual or it should have its own, dedicated manual. But *Info it should be* - and mirrored on the web in the same way as the Emacs and Elisp manuals.