ndwarshuis
/
org-mode
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

doc/Documentation_Standards.org: Clean indentation

This commit is contained in:
Bastien 2018-03-04 21:31:14 +01:00
parent 4d50d5c9a4
commit 66d2474ccb
1 changed files with 58 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
doc/Documentation_Standards.org
View File

@ -11,18 +11,18 @@
I think it is an express objective of Carsten's that Org should be I think it is an express objective of Carsten's that Org should be
readily accessible to all users of Emacs and not just those who might readily accessible to all users of Emacs and not just those who might
happen to read or hack on the code of this particular package. To that happen to read or hack on the code of this particular package. To
end significant effort has been made and continues to be made by the Org that end significant effort has been made and continues to be made by
community to ensure that high quality, user focused, documentation is the Org community to ensure that high quality, user focused,
readily available to everyone. documentation is readily available to everyone.
Org itself contains a comprehensive guide to using all aspects of the Org itself contains a comprehensive guide to using all aspects of the
system, how to extend it yourself, and highlights some of the many system, how to extend it yourself, and highlights some of the many
burgeoning number of add-on packages that others are contributing. This burgeoning number of add-on packages that others are contributing.
guide, [[info:org:Top][The Org Manual]], concentrates on the facts of working with the This guide, [[info:org:Top][The Org Manual]], concentrates on the facts of working with
system. Supplementing this, the [[Org web pages]] contain pointers to many the system. Supplementing this, the [[Org web pages]] contain pointers to
tutorials and how-to's which capture much of spirit and imagination many tutorials and how-to's which capture much of spirit and
people show when using Org as a basis for building broader imagination people show when using Org as a basis for building broader
organizational systems that help them help themselves. organizational systems that help them help themselves.
I use Org, but it is a big system, and so I happen to think that I use Org, but it is a big system, and so I happen to think that
@ -30,8 +30,8 @@ improving the consistency, clarity and accuracy of Org documents helps
both me and all other users of the system. In support of this and by both me and all other users of the system. In support of this and by
way of justification and clarification, this short note attempts to way of justification and clarification, this short note attempts to
capture some of the existing guidelines and standards that have been capture some of the existing guidelines and standards that have been
used in the patches I am submitting and, which I hope, may be adopted by used in the patches I am submitting and, which I hope, may be adopted
others when making their own contributions. by others when making their own contributions.
* Org - Referencing systems, packages, modes and much else * Org - Referencing systems, packages, modes and much else
@ -48,39 +48,39 @@ perfect, merely a start):
discussing concepts, features and functions that are generally discussing concepts, features and functions that are generally
applicable to Org as a whole. applicable to Org as a whole.
- Be more specific and write, for example, "the Orgtbl minor mode" when - Be more specific and write, for example, "the Orgtbl minor mode"
referring to something unique to that feature. It maybe, for example, when referring to something unique to that feature. It maybe, for
a command is only available when you are actually editing a file using example, a command is only available when you are actually editing
just that mode, add-on package or plug-in. a file using just that mode, add-on package or plug-in.
- Prefer "Org mode" to "Org-mode" or "org-mode". This is simply because - Prefer "Org mode" to "Org-mode" or "org-mode". This is simply
it reflects an existing convention in [[info:emacs:Top][The Emacs Manual]] which because it reflects an existing convention in [[info:emacs:Top][The Emacs Manual]]
consistently documents mode names in this form - "Text mode", "Outline which consistently documents mode names in this form - "Text mode",
mode", "Mail mode" etc. "Outline mode", "Mail mode" etc.
- Likewise refer, if at all possible, to "Org file or "Org buffer" - Likewise refer, if at all possible, to "Org file or "Org buffer"
meaning with, great generality, any file or buffer which requires use meaning with, great generality, any file or buffer which requires
of some part of Org to edit it properly. use of some part of Org to edit it properly.
- Org uses "org-..." to ring fence a name space for itself in the Emacs - Org uses "org-..." to ring fence a name space for itself in the
code base. This is obviously retained in code snippets. Emacs code base. This is obviously retained in code snippets.
* Other Org specific conventions * 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 following conventions. (I think all can be justified by reference to
Carsten or precedent in other significant Emacs documentation...unless I Carsten or precedent in other significant Emacs documentation...unless
have made them up of course). I have made them up of course).
- Org has *lots* of commands and a /lot/ of them take prefix arguments - Org has *lots* of commands and a /lot/ of them take prefix arguments of
of one sort or another. Write in full "prefix argument", "numeric one sort or another. Write in full "prefix argument", "numeric
prefix argument" or, maybe, "a numeric prefix argument N" when you prefix argument" or, maybe, "a numeric prefix argument N" when you
want to refer to the argument again. want to refer to the argument again.
- Org lives in various states of harmony and discord with other Emacs - Org lives in various states of harmony and discord with other Emacs
packages. Try and write the names of those packages as their authors packages. Try and write the names of those packages as their
and maintainers write them. So it should be (I think) BBDB, MH-E, authors and maintainers write them. So it should be (I think)
Rmail, VM, Gnus, CDLaTeX etc. BBDB, MH-E, Rmail, VM, Gnus, CDLaTeX etc.
- TODO keywords, whether Org or user defined, are written in capitals. - TODO keywords, whether Org or user defined, are written in capitals.
@ -88,14 +88,14 @@ have made them up of course).
uppercase. User defined tags (eg boss, home) are written in uppercase. User defined tags (eg boss, home) are written in
lowercase. lowercase.
- Built-in properties (eg PRIORITY) are written in uppercase. User defined - Built-in properties (eg PRIORITY) are written in uppercase. User
properties (eg Release) are written in lowercase. defined properties (eg Release) are written in lowercase.
- [[info:org:Top][The Org Manual]] uses the @chapter, @section and @subsection Texinfo - [[info:org:Top][The Org Manual]] uses the @chapter, @section and @subsection Texinfo
commands for sectioning. I have tried to capitalize significant words commands for sectioning. I have tried to capitalize significant
in @chapter headings. In @section and @subsection headings, just the words in @chapter headings. In @section and @subsection headings,
first word is capitalized and all other words are lowercase (with just the first word is capitalized and all other words are
exceptions of course...). Thus, use: lowercase (with exceptions of course...). Thus, use:
@chapter Properties and Columns @chapter Properties and Columns
@ -107,15 +107,16 @@ have made them up of course).
* Miscellaneous * Miscellaneous
- Only two of the standard Texinfo indexes are used; those for concepts - Only two of the standard Texinfo indexes are used; those for
and keys. This has some implications: concepts and keys. This has some implications:
+ The preference is to document commands by key rather than by name + The preference is to document commands by key rather than by name
+ Texinfo commands such as @var and @defoption are not used. The + Texinfo commands such as @var and @defoption are not used. The
preference for this type of thing is that the user browses 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 customize groups. If you want or need to refer to, say, a
then document it as "the variable @code{org-startup-folded}" variable then document it as "the variable
@code{org-startup-folded}"
+ Entries in the concept index are normally all lower case unless + Entries in the concept index are normally all lower case unless
some other rule dictates otherwise. some other rule dictates otherwise.
@ -123,30 +124,30 @@ have made them up of course).
- Org documentation is written in American English, which is somewhat - Org documentation is written in American English, which is somewhat
foreign as far as I am concerned, but live with it anyway. foreign as far as I am concerned, but live with it anyway.
- Org uses a number of compound words, words that I wouldn't necessarily - Org uses a number of compound words, words that I wouldn't
run together. Instead of worrying about whether these should be necessarily run together. Instead of worrying about whether these
separate, hyphenated or compound I have simply gone with the majority should be separate, hyphenated or compound I have simply gone with
case as originally written and then tried to make sure the spell the majority case as originally written and then tried to make sure
checker knows what this chosen standard should be so that I do not the spell checker knows what this chosen standard should be so that
worry about it anymore. I do not worry about it anymore.
- I have run a spell checker periodically. Aspell works well and has a - I have run a spell checker periodically. Aspell works well and has
useful Texinfo filter (although, annoyingly, I cannot make this work a useful Texinfo filter (although, annoyingly, I cannot make this
with ispell.el and so I run it from the command line). I have an Org work with ispell.el and so I run it from the command line). I have
specific Aspell configuration file (which sets an American dictionary, an Org specific Aspell configuration file (which sets an American
rules for compound words etc) and which, along with the associated dictionary, rules for compound words etc) and which, along with the
word and replacement files, captures some of the more detailed and associated word and replacement files, captures some of the more
somewhat arbitrary rules I have used. detailed and somewhat arbitrary rules I have used.
- Org has really low entry barriers. The requirements seem simply - Org has really low entry barriers. The requirements seem simply to
to be: be:
+ You can use Text mode or, pretty much, any derivative of it + You can use Text mode or, pretty much, any derivative of it
+ You have some motivation to become slightly better organized. + You have some motivation to become slightly better organized.
Therefore, try and write the documentation so that it is relevant to, Therefore, try and write the documentation so that it is relevant
and can be read by such a diverse audience. to, and can be read by such a diverse audience.
# Local variables: # Local variables:
# mode: org # mode: org