From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Thomas S. Dye" Subject: Re: [RFC] Dog food, anyone? Date: Tue, 19 Dec 2017 10:11:55 -1000 Message-ID: References: <87efntod73.fsf@nicolasgoaziou.fr> <87efnrlml3.fsf@nicolasgoaziou.fr> <87r2rqjzac.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:40900) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eROFS-0007wr-R3 for emacs-orgmode@gnu.org; Tue, 19 Dec 2017 15:12:24 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eROFN-0002lC-Jk for emacs-orgmode@gnu.org; Tue, 19 Dec 2017 15:12:22 -0500 Received: from gproxy5-pub.mail.unifiedlayer.com ([67.222.38.55]:54215) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1eROFN-0002ZL-Av for emacs-orgmode@gnu.org; Tue, 19 Dec 2017 15:12:17 -0500 Received: from cmgw4 (unknown [10.0.90.85]) by gproxy5.mail.unifiedlayer.com (Postfix) with ESMTP id 073D01406EA for ; Tue, 19 Dec 2017 13:12:05 -0700 (MST) In-reply-to: <87r2rqjzac.fsf@nicolasgoaziou.fr> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: Nicolas Goaziou Cc: Org Mode List Aloha Nicolas, Nicolas Goaziou writes: > Hello, > > "Thomas S. Dye" writes: > >> I find the en-dash with spaces more aesthetically pleasing, too. > > Unfortunately, Emacs manual thoroughly uses em-dash. We have to bite the > bullet, IMO. > > I will change " -- " into "---" if there is no objection. No objection here. >> Agreed. This is one of the first things we might do if manual.org >> becomes the official source of the Org manual. >> >> FYI, Phil Rooke's Documentation_Standards.org suggests title case for >> chapter heads and sentence case for section and subsection headings. > > OTOH, Emacs manual seems to use title case at every level, barring some > exceptions (e.g., "Terminal emulator"). > > Maybe we should stick to title case to every heading that belong to > a menu, i.e., we can use sentence case for "notoc" headings. > > Since Texinfo node names are derived from headlines, it means external > references to Org manual, if such thing exists, are going to break. > > WDYT? I think we should identify and follow the appropriate style guide, but I'm confused about what *is* the appropriate style guide. The style guide for GNU documentation seems more about teaching coders how to communicate with other humans and less about the nitty-gritty style issues that send an editor to a guide like the Chicago Manual of Style. See: https://www.fsf.org/gnu-press/GNU-Press-styleguide.pdf Note that the GNU style guide uses sentence case for section heads, and em-dashes with spaces (" --- ")! Of course, the TexInfo style guide I cited in an earlier post appears to have conflicting advice about dashes :( In the end, the important thing is consistency. A good document "trains" its readers how to read it by hewing to a consistent standard. My recommendation at this point is to follow Phil Rooke's style guide and augment it where possible. If manual.org becomes the official source for Org documentation, then it would be useful to "translate" Rooke's guide to show how to achieve its style prescriptions using Org markup. hth, Tom -- Thomas S. Dye http://www.tsdye.com