* Patch for documentation standards
@ 2018-03-04 2:15 Thomas S. Dye
2018-03-04 8:44 ` Bastien
0 siblings, 1 reply; 6+ messages in thread
From: Thomas S. Dye @ 2018-03-04 2:15 UTC (permalink / raw)
To: Org Mode List
[-- Attachment #1: Type: text/plain, Size: 120 bytes --]
Aloha all,
A lightly edited and augmented version of the Org documentation
standards is attached.
All the best,
Tom
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Documentation standards patch --]
[-- Type: text/x-diff, Size: 4431 bytes --]
From 010294deec9d35217bdc991bec55a80ab0f40853 Mon Sep 17 00:00:00 2001
From: "Thomas S. Dye" <tsd@tsdye.com>
Date: Sat, 3 Mar 2018 16:06:27 -1000
Subject: [PATCH] Update documentation standards
---
doc/Documentation_Standards.org | 57 ++++++++++++++++++++++++++---------------
1 file changed, 37 insertions(+), 20 deletions(-)
diff --git a/doc/Documentation_Standards.org b/doc/Documentation_Standards.org
index 357520b9f..f1495d2e8 100644
--- a/doc/Documentation_Standards.org
+++ b/doc/Documentation_Standards.org
@@ -34,7 +34,7 @@ used in the patches I am submitting and, which I hope, may be adopted by
others when making their own contributions.
* Org - Referencing systems, packages, modes and much else
-
+
Originally Org was a single mode and there was no ambiguity about what
Org mode could refer to. Things have changed rapidly though and it
seems that Carsten now thinks of Org as the system encompassing the
@@ -49,7 +49,7 @@ perfect, merely a start):
applicable to Org as a whole.
- Be more specific and write, for example, "the Orgtbl minor mode" when
- referring to something unique to that feature. It maybe, for example,
+ referring to something unique to that feature. It may be, for example,
a command is only available when you are actually editing a file using
just that mode, add-on package or plug-in.
@@ -67,7 +67,7 @@ perfect, merely a start):
* Other Org specific conventions
-Unless there is a good reason to do otherwise then try and adopt the
+Unless there is a good reason to do otherwise, then try and adopt the
following conventions. (I think all can be justified by reference to
Carsten or precedent in other significant Emacs documentation...unless I
have made them up of course).
@@ -89,36 +89,53 @@ have made them up of course).
lowercase.
- Built-in properties (eg PRIORITY) are written in uppercase. User defined
- properties (eg Release) are written in lowercase.
+ properties (e.g. Release) are written in lowercase.
- - [[info:org:Top][The Org Manual]] uses the @chapter, @section and @subsection Texinfo
- commands for sectioning. I have tried to capitalize significant words
- in @chapter headings. In @section and @subsection headings, just the
+ - [[info:org:Top][The Org Manual]] capitalizes significant words
+ in first level headings. In second and third level headings, just the
first word is capitalized and all other words are lowercase (with
exceptions of course...). Thus, use:
- @chapter Properties and Columns
+ * Properties and Columns
- @section Visibility cycling
+ ** Visibility cycling
*but*
- @section Fast access to TODO states
+ ** Fast access to TODO states
* Miscellaneous
- - Only two of the standard Texinfo indexes are used; those for concepts
- and keys. This has some implications:
+ - Five of the standard Texinfo indexes are used in the Org manual:
+
+ + #+cindex: :: concept index, for general concepts
+
+ + #+findex: :: function index, for function and function-like names
+
+ + #+kindex: :: keystroke index, for keyboard commands
+
+ + #+pindex: :: program index, for names of programs
+
+ + #+vindex: :: variable index, for variable names
+
+ - Entries in the concept index are normally all lower case unless
+ some other rule dictates otherwise
+
+ - 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 colons
+
+ - when to use =...= or ~...~ markup:
+
+ - files or extensions use =...=,
- + The preference is to document commands by key rather than by name
+ - anything that is meant to be written in the Org buffer uses =...=,
- + Texinfo commands such as @var and @defoption are not used. The
- preference for this type of thing is that the user browses the
- customize groups. If you want or need to refer to, say, a variable
- then document it as "the variable @code{org-startup-folded}"
-
- + Entries in the concept index are normally all lower case unless
- some other rule dictates otherwise.
+ - any meaningful token in a programming language uses ~...~.
- Org documentation is written in American English, which is somewhat
foreign as far as I am concerned, but live with it anyway.
--
2.14.1
[-- Attachment #3: Type: text/plain, Size: 39 bytes --]
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: Patch for documentation standards
2018-03-04 2:15 Patch for documentation standards Thomas S. Dye
@ 2018-03-04 8:44 ` Bastien
0 siblings, 0 replies; 6+ messages in thread
From: Bastien @ 2018-03-04 8:44 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Org Mode List
Hi Thomas,
"Thomas S. Dye" <tsd@tsdye.com> writes:
> A lightly edited and augmented version of the Org documentation
> standards is attached.
thanks a lot -- if I understand correctly, the patch fixes current
errors and also relies on the idea that the manual is written in org
(which is not yet the case).
Can you make separate patches, one fixing errors and another one
for the move to editing the manual with .org?
I don't want to commit anything premature.
Also, if you can push commits yourself, please go ahead!
Thanks,
--
Bastien
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Patch for documentation standards
@ 2018-03-04 17:37 Thomas S. Dye
2018-03-04 20:48 ` Bastien Guerry
0 siblings, 1 reply; 6+ messages in thread
From: Thomas S. Dye @ 2018-03-04 17:37 UTC (permalink / raw)
To: bzg; +Cc: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 369 bytes --]
Aloha Bastien,
> Can you make separate patches, one fixing errors and another one
> for the move to editing the manual with .org?
> I don't want to commit anything premature.
Feel free to cmmit when appropriate. IMO, the comment period for
Nicolas' manual project has been sufficiently long and I do not want to
work with you to prolong it.
All the best,
Tom
[-- Attachment #2: Type: text/html, Size: 531 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Patch for documentation standards
2018-03-04 17:37 Thomas S. Dye
@ 2018-03-04 20:48 ` Bastien Guerry
2018-03-05 1:06 ` Thomas S. Dye
0 siblings, 1 reply; 6+ messages in thread
From: Bastien Guerry @ 2018-03-04 20:48 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: emacs-orgmode
Hi Thomas,
> Feel free to cmmit when appropriate. IMO, the comment period for
> Nicolas' manual project has been sufficiently long and I do not want
> to work with you to prolong it.
Mhh... "working with me" would shorten it for sure!
Anyway, I committed this:
https://code.orgmode.org/bzg/org-mode/commit/dd99ed74430a8b6a48f6b63fac71a0bede3e772f
Let me know what you think.
Thanks,
--
Bastien
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Patch for documentation standards
2018-03-04 20:48 ` Bastien Guerry
@ 2018-03-05 1:06 ` Thomas S. Dye
2018-03-05 9:24 ` Bastien Guerry
0 siblings, 1 reply; 6+ messages in thread
From: Thomas S. Dye @ 2018-03-05 1:06 UTC (permalink / raw)
To: Bastien Guerry; +Cc: Thomas S. Dye, emacs-orgmode
Aloha Bastien,
Bastien Guerry writes:
> Hi Thomas,
>
>> Feel free to cmmit when appropriate. IMO, the comment period
>> for
>> Nicolas' manual project has been sufficiently long and I do not
>> want
>> to work with you to prolong it.
>
> Mhh... "working with me" would shorten it for sure!
>
> Anyway, I committed this:
>
> https://code.orgmode.org/bzg/org-mode/commit/dd99ed74430a8b6a48f6b63fac71a0bede3e772f
>
> Let me know what you think.
I hope you find it useful.
All the best,
Tom
--
Thomas S. Dye
http://www.tsdye.com
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Patch for documentation standards
2018-03-05 1:06 ` Thomas S. Dye
@ 2018-03-05 9:24 ` Bastien Guerry
0 siblings, 0 replies; 6+ messages in thread
From: Bastien Guerry @ 2018-03-05 9:24 UTC (permalink / raw)
To: Thomas S. Dye; +Cc: Thomas S. Dye, emacs-orgmode
"Thomas S. Dye" <tsd@tsdye.com> writes:
> I hope you find it useful.
I definitely do, thanks again!
--
Bastien
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2018-03-05 9:25 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-03-04 2:15 Patch for documentation standards Thomas S. Dye
2018-03-04 8:44 ` Bastien
-- strict thread matches above, loose matches on Subject: below --
2018-03-04 17:37 Thomas S. Dye
2018-03-04 20:48 ` Bastien Guerry
2018-03-05 1:06 ` Thomas S. Dye
2018-03-05 9:24 ` Bastien Guerry
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).