From mboxrd@z Thu Jan  1 00:00:00 1970
From: "Thomas S. Dye" <tsd@tsdye.com>
Subject: Re: [RFC] Moving "manual.org" into core
Date: Tue, 23 Jan 2018 10:06:17 -1000
Message-ID: <m2inbspcg6.fsf@tsdye.com>
References: <87bmhooaj9.fsf@nicolasgoaziou.fr> <87tvveqi7u.fsf@bzg.fr>
	<87wp0a57i5.fsf@nicolasgoaziou.fr>
Mime-Version: 1.0
Content-Type: text/plain; format=flowed
Return-path: <emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org>
Received: from eggs.gnu.org ([2001:4830:134:3::10]:51411)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <tsd@tsdye.com>) id 1ee4qA-0003jR-FA
	for emacs-orgmode@gnu.org; Tue, 23 Jan 2018 15:06:43 -0500
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <tsd@tsdye.com>) id 1ee4q6-0008Ma-GF
	for emacs-orgmode@gnu.org; Tue, 23 Jan 2018 15:06:42 -0500
Received: from gproxy7-pub.mail.unifiedlayer.com ([70.40.196.235]:38850)
	by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32)
	(Exim 4.71) (envelope-from <tsd@tsdye.com>) id 1ee4q6-0008KI-9y
	for emacs-orgmode@gnu.org; Tue, 23 Jan 2018 15:06:38 -0500
Received: from CMOut01 (unknown [10.0.90.82])
	by gproxy7.mail.unifiedlayer.com (Postfix) with ESMTP id 71AE4215CD2
	for <emacs-orgmode@gnu.org>; Tue, 23 Jan 2018 13:06:35 -0700 (MST)
In-reply-to: <87wp0a57i5.fsf@nicolasgoaziou.fr>
List-Id: "General discussions about Org-mode." <emacs-orgmode.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/emacs-orgmode/>
List-Post: <mailto:emacs-orgmode@gnu.org>
List-Help: <mailto:emacs-orgmode-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
	<mailto:emacs-orgmode-request@gnu.org?subject=subscribe>
Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org
Sender: "Emacs-orgmode"
	<emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org>
To: Nicolas Goaziou <mail@nicolasgoaziou.fr>
Cc: Bastien Guerry <bzg@gnu.org>, Achim Gratz <Stromeko@nexgo.de>, Org Mode List <emacs-orgmode@gnu.org>

Aloha all,

Nicolas Goaziou writes:

>
> Note that I made a few design choices I didn't write about, 
> e.g.,:
>
>   - use fixed-width area for one-line examples,
>   - use example blocks for Org syntax instead of "begin_src 
>   org",
>   - internal links to headlines always start with a star,
>   - tags, node properties, are not shown with the surrounding 
>   columns,
>   - when to use =...= or ~...~ markup:
>     - files or extensions use =...=,
>     - anything that is meant to be written in the Org buffer 
>     uses =...=,
>     - any meaningful token in a programming language uses ~...~.

I'd like to follow up on an earlier suggestion to put together a 
style guide for manual.org based on Phil Rooke's 
Documentation_Standards.org.  The idea was to "translate" Phil's 
document to follow the change from .texi source to .org source.

I think it will prove useful to have design choices described 
together in one place.

I've copied Phil in case he objects to having his "Notes to myself 
..." document used in this way.

Any comments welcome.

All the best,
Tom

--
Thomas S. Dye
http://www.tsdye.com