From: "Thomas S. Dye" <tsd@tsdye.com>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: Org Mode List <emacs-orgmode@gnu.org>
Subject: Re: [RFC] Dog food, anyone?
Date: Tue, 19 Dec 2017 10:11:55 -1000 [thread overview]
Message-ID: <m2fu86a35g.fsf@tsdye.com> (raw)
In-Reply-To: <87r2rqjzac.fsf@nicolasgoaziou.fr>
Aloha Nicolas,
Nicolas Goaziou writes:
> Hello,
>
> "Thomas S. Dye" <tsd@tsdye.com> 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
next prev parent reply other threads:[~2017-12-19 20:12 UTC|newest]
Thread overview: 42+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-12-17 10:34 [RFC] Dog food, anyone? Nicolas Goaziou
2017-12-17 11:59 ` Vikas Rawal
2017-12-17 18:41 ` Thomas S. Dye
2017-12-17 19:01 ` Nicolas Goaziou
2017-12-17 21:58 ` Thomas S. Dye
2017-12-17 23:03 ` Adrian Bradd
2017-12-18 1:13 ` Thomas S. Dye
2017-12-17 23:44 ` Nicolas Goaziou
2017-12-18 1:15 ` Vikas Rawal
2017-12-18 1:23 ` Thomas S. Dye
2017-12-17 18:51 ` Kaushal Modi
2017-12-17 19:27 ` Nicolas Goaziou
2017-12-17 18:58 ` [RFC] Official Org manual in Org! (Was: Dog food, anyone?) Kaushal Modi
2017-12-21 8:00 ` Marcin Borkowski
2017-12-21 13:47 ` [RFC] Official Org manual in Org! Nicolas Goaziou
2017-12-17 23:10 ` [RFC] Dog food, anyone? Eric Abrahamsen
2017-12-18 21:02 ` Thomas S. Dye
2017-12-18 22:04 ` Nicolas Goaziou
2017-12-19 0:12 ` Thomas S. Dye
2017-12-19 19:25 ` Nicolas Goaziou
2017-12-19 20:11 ` Thomas S. Dye [this message]
2017-12-19 20:16 ` Jonathan Leech-Pepin
2017-12-19 23:11 ` Nicolas Goaziou
2017-12-20 0:05 ` Jonathan Leech-Pepin
2017-12-20 0:59 ` Thomas S. Dye
[not found] ` <WM!57dfd1c25b2c2af3021c1294841c916968d326cf362c32864a6fbc9615cf19dba6ceadc1960e4c3ef5578687af476fba!@mailhub-mx1.ncl.ac.uk>
2017-12-21 12:58 ` Phillip Lord
2017-12-21 13:37 ` Nicolas Goaziou
2017-12-21 17:26 ` Phillip Lord
2017-12-21 19:53 ` Nicolas Goaziou
[not found] ` <WM!3e1c2e8dc2d528e2348759d2a34555337e2f3a5782534bcece582121239ecf030ff1b6d5efd2b2c4955a04c496f00ac6!@mailhub-mx2.ncl.ac.uk>
2017-12-21 22:13 ` Phillip Lord
2017-12-22 18:30 ` Nicolas Goaziou
2017-12-23 6:56 ` Yasushi SHOJI
2017-12-23 14:12 ` Kaushal Modi
2017-12-25 1:44 ` Yasushi SHOJI
2018-04-26 23:34 ` Bastien
2018-04-28 10:56 ` Nicolas Goaziou
2018-04-28 12:43 ` Bastien
2018-05-09 0:30 ` Nicolas Goaziou
2018-05-09 18:16 ` Gregor Zattler
2018-05-09 19:12 ` Nicolas Goaziou
-- strict thread matches above, loose matches on Subject: below --
2018-05-09 18:11 Jon Snader
2018-05-10 8:02 ` Neil Jerram
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=m2fu86a35g.fsf@tsdye.com \
--to=tsd@tsdye.com \
--cc=emacs-orgmode@gnu.org \
--cc=mail@nicolasgoaziou.fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).