Re: [O] [RFC] Dog food, anyone?

[Thomas S. Dye]

Aloha Nicolas,

Nicolas Goaziou writes:

> Hello,
>
> "Thomas S. Dye" <address@hidden> 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