From 3f4a0d5370ae6c34afe180df96add3b8522f4af1 Mon Sep 17 00:00:00 2001 From: mattkae Date: Wed, 11 May 2022 09:23:58 -0400 Subject: initial commit --- elpa/org-9.5.2/doc/Documentation_Standards.org | 171 +++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 elpa/org-9.5.2/doc/Documentation_Standards.org (limited to 'elpa/org-9.5.2/doc/Documentation_Standards.org') diff --git a/elpa/org-9.5.2/doc/Documentation_Standards.org b/elpa/org-9.5.2/doc/Documentation_Standards.org new file mode 100644 index 0000000..c4dd862 --- /dev/null +++ b/elpa/org-9.5.2/doc/Documentation_Standards.org @@ -0,0 +1,171 @@ +#+TITLE: Notes on documenting Org +#+AUTHOR: Phil Rooke +#+EMAIL: phil@yax.org.uk +#+LANGUAGE: en +#+STARTUP: showall +#+TEXT: Notes to myself justifying the conventions and standards in my +#+TEXT: set of recent doc patches. +#+OPTIONS: H:3 num:t toc:t \n:nil @:t ::t |:t ^:nil *:t TeX:t + +* Background + +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 +happen to read or hack on the code of this particular package. To +that end significant effort has been made and continues to be made by +the Org community to ensure that high quality, user focused, +documentation is readily available to everyone. + +Org itself contains a comprehensive guide to using all aspects of the +system, how to extend it yourself, and highlights some of the many +burgeoning number of add-on packages that others are contributing. +This guide, [[info:org:Top][The Org Manual]], concentrates on the facts of working with +the system. Supplementing this, the [[Org web pages]] contain pointers to +many tutorials and how-to's which capture much of spirit and +imagination people show when using Org as a basis for building broader +organizational systems that help them help themselves. + +I use Org, but it is a big system, and so I happen to think that +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 +way of justification and clarification, this short note attempts to +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 others when making their own contributions. + +* 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 +major mode, some minor modes, and an increasing number of additional +packages and plug-ins that build on the core Org functionality. It is +really hard to find a consistent way to refer to all these things, but +what I am trying to do is follow these guidelines (which are not +perfect, merely a start): + +- In general write "Org" as much as possible and, in particular, when + discussing concepts, features and functions that are generally + 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 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. + +- Prefer "Org mode" to "Org-mode" or "org-mode". This is simply + because it reflects an existing convention in [[info:emacs:Top][The Emacs Manual]] which + consistently documents mode names in this form - "Text mode", + "Outline mode", "Mail mode", etc. + +- Likewise refer, if at all possible, to "Org file or "Org buffer" + meaning with, great generality, any file or buffer which requires + use of some part of Org to edit it properly. + +- Org uses "org-..." to ring fence a name space for itself in the + Emacs code base. This is obviously retained in code snippets. + +* Other Org specific conventions + +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). + +- Org has *lots* of commands and a /lot/ of them take prefix arguments of + one sort or another. Write in full "prefix argument", "numeric + prefix argument" or, maybe, "a numeric prefix argument N" when you + want to refer to the argument again. + +- Org lives in various states of harmony and discord with other Emacs + packages. Try and write the names of those packages as their + authors and maintainers write them. So it should be (I think) BBDB, + MH-E, Rmail, VM, Gnus, CDLaTeX etc. + +- TODO keywords, whether Org or user defined, are written in capitals. + +- Built-in tags with a special meaning (e.g. ARCHIVE) are written in + uppercase. User defined tags (e.g. boss, home) are written in + lowercase. + +- Built-in properties (e.g. PRIORITY) are written in uppercase. User + defined properties (e.g. Release) are written in lowercase. + +- Entries in the concept index are normally all lower case unless some + other rule dictates otherwise. + +* org-manual.org specific conventions + +Org git repository comes with an .org version of the manual in the +=doc/= directory. Here are indications that are specific to this +version of the manual. + +- 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 + +- 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 = ... =, + + anything that is meant to be written in the Org buffer uses = ... =, + + any meaningful token in a programming language uses ~ ... ~. + +* Miscellaneous + + - Only two of the standard Texinfo indexes are used; those for + concepts and keys. This has some implications: + + + The preference is to document commands by key rather than by name + + + 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. + + - Org documentation is written in American English, which is somewhat + 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 run together. Instead of worrying about whether these + should be separate, hyphenated or compound I have simply gone with + the majority case as originally written and then tried to make sure + the spell checker knows what this chosen standard should be so that + I do not worry about it anymore. + + - I have run a spell checker periodically. Aspell works well and has + a useful Texinfo filter (although, annoyingly, I cannot make this + work with ispell.el and so I run it from the command line). I have + an Org specific Aspell configuration file (which sets an American + dictionary, rules for compound words etc) and which, along with the + associated word and replacement files, captures some of the more + detailed and somewhat arbitrary rules I have used. + + - Org has really low entry barriers. Requirements seem simply to be: + + + You can use Text mode or, pretty much, any derivative of it + + You have some motivation to become slightly better organized. + + Therefore, try and write the documentation so that it is relevant + to, and can be read by such a diverse audience. + +# Local variables: +# mode: org +# ispell-local-dictionary: "en_US-w_accents" +# ispell-local-pdict: "./.aspell.org.pws" +# End: -- cgit v1.2.1