diff --git a/.gitignore b/.gitignore index 52ddd4999..6dc4d8a8e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,11 +1,14 @@ # Don't bother tracking a bunch of stuff when building and installing # Org from the master git repository. -# ...by ignoring everything created by 'make' and 'make doc'. +# ...by ignoring everything created by 'make', 'make doc', `make info' +# `make html_manual', `make release' *.aux +*.bak *.cp *.cps +*.dvi *.fn *.fns *.html @@ -19,16 +22,26 @@ *.vr *.dvi orgcard_letter.tex +org +org-install.el +org-*.tar.gz +org-*.zip +manual # aspell word and replacement lists .aspell.org.pws .aspell.org.prepl -*.bak + +# allow tmp and test directories that will not be tracked + +test +tmp # and collateral damage from Emacs *~ +.DS_Store # # Local variables: diff --git a/Makefile b/Makefile index 4de98d686..1258f49ca 100644 --- a/Makefile +++ b/Makefile @@ -165,7 +165,7 @@ web: html: doc/org.html -html_split: doc/org.texi +html_manual: doc/org.texi rm -rf doc/manual mkdir doc/manual $(TEXI2HTML) -o doc/manual doc/org.texi @@ -201,7 +201,7 @@ release: make webfiles make distfile make doc - make html_split + make html_manual rm -rf RELEASEDIR $(MKDIR) RELEASEDIR cp org-$(TAG).zip org-$(TAG).tar.gz RELEASEDIR diff --git a/doc/Documentation_Standards.org b/doc/Documentation_Standards.org new file mode 100644 index 000000000..04d67254d --- /dev/null +++ b/doc/Documentation_Standards.org @@ -0,0 +1,156 @@ +#+TITLE: Notes on documenting Org +#+AUTHOR: Phil Rooke +#+EMAIL: phil@yax.org.uk +#+LANGUAGE: en +#+STARTUP: showall +#+TEXT: Notes to myself justifying the coventions and standards in my +#+TEXT: set of recent doc patches. +#+OPTIONS: H:3 num:t toc:t \n:nil @:t ::t |:t ^:t *: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. + +* 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 +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 maybe, 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 (eg ARCHIVE) are written in + uppercase. User defined tags (eg boss, home) are written in + lowercase. + + - Built-in properties (eg PRIORITY) are written in uppercase. User defined + properties (eg 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 + first word is capitalized and all other words are lowercase (with + exceptions of course...). Thus, use: + + @chapter Properties and Columns + + @section Visibility cycling + + *but* + + @section Fast access to TODO states + +* 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. The 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 +# fill-column: 72 +# ispell-local-dictionary: "en_US-w_accents" +# ispell-local-pdict: "./.aspell.org.pws" +# End: diff --git a/doc/org.texi b/doc/org.texi index dcd80e84d..0ce30c83c 100644 --- a/doc/org.texi +++ b/doc/org.texi @@ -3289,7 +3289,7 @@ in a specific file, add an empty TAGS option line to that file: @end example By default Org mode uses the standard minibuffer completion facilities for -entering tags. However, it also implements another, quicker, tag completion +entering tags. However, it also implements another, quicker, tag selection method called @emph{fast tag selection}. This allows you to select and deselect tags with just a single key press. For this to work well you should assign unique letters to most of your commonly used tags. You can do this