-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathorgmanual.info
20485 lines (16179 loc) · 860 KB
/
orgmanual.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is orgmanual.info, produced by makeinfo version 4.13 from
orgmanual.texi.
This manual is for Org version 8.0-pre (release_8.0-pre-16-g3f6b24).
Copyright (C) 2004-2013 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual," and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License."
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom."
This document is part of a collection distributed under the GNU
Free Documentation License. If you want to distribute this
document separately from the collection, you can do so by adding a
copy of the license to the document, as described in section 6 of
the license.
INFO-DIR-SECTION Emacs editing modes
START-INFO-DIR-ENTRY
* Org Mode: (org). Outline-based notes management and organizer
END-INFO-DIR-ENTRY
File: orgmanual.info, Node: Top, Next: Introduction, Up: (dir)
Org Mode Manual
***************
This manual is for Org version 8.0-pre (release_8.0-pre-16-g3f6b24).
Copyright (C) 2004-2013 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with the Front-Cover texts
being "A GNU Manual," and with the Back-Cover Texts as in (a)
below. A copy of the license is included in the section entitled
"GNU Free Documentation License."
(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
modify this GNU manual. Buying copies from the FSF supports it in
developing GNU and promoting software freedom."
This document is part of a collection distributed under the GNU
Free Documentation License. If you want to distribute this
document separately from the collection, you can do so by adding a
copy of the license to the document, as described in section 6 of
the license.
* Menu:
* Introduction:: Getting started
* Document structure:: A tree works like your brain
* Tables:: Pure magic for quick formatting
* Hyperlinks:: Notes in context
* TODO items:: Every tree branch can be a TODO item
* Tags:: Tagging headlines and matching sets of tags
* Properties and columns:: Storing information about an entry
* Dates and times:: Making items useful for planning
* Capture - Refile - Archive:: The ins and outs for projects
* Agenda views:: Collecting information into views
* Markup for rich export:: Prepare text for rich export
* Exporting:: Sharing and publishing notes
* Publishing:: Create a web site of linked Org files
* Working with source code:: Export, evaluate, and tangle code blocks
* Miscellaneous:: All the rest which did not fit elsewhere
* Hacking:: How to hack your way around
* MobileOrg:: Viewing and capture on a mobile device
* History and acknowledgments:: How Org came into being
* Concept index:: Org's concepts and features
* Key index:: Key bindings and where they are described
* Command and function index:: Command names and some internal functions
* Variable index:: Variables mentioned in the manual
--- The Detailed Node Listing ---
Introduction
* Summary:: Brief summary of what Org-mode does
* Installation:: How to install a downloaded version of Org-mode
* Activation:: How to activate Org-mode for certain buffers
* Feedback:: Bug reports, ideas, patches, etc.
* How to create a useful backtrace:: The best way to report an error
* Conventions:: Typesetting conventions in the manual
Conventions
* Three types of keywords:: TODO, tags, and properties
* Keybindings and commands:: Bind useful commands to keys
Document structure
* Outlines:: Org mode is based on Outline mode
* Headlines:: How to typeset Org tree headlines
* Visibility cycling:: Show and hide, much simplified
* Motion:: Jumping to other headlines
* Structure editing:: Changing sequence and level of headlines
* Sparse trees:: Matches embedded in context
* Plain lists:: Additional structure within an entry
* Drawers:: Tucking stuff away
* Blocks:: Folding blocks
* Creating footnotes:: Define footnotes in Org syntax
* Orgstruct mode:: Structure editing outside Org
Tables
* Built-in table editor:: Simple tables
* Column width and alignment:: Overrule the automatic settings
* Column groups:: Grouping to trigger vertical lines
* The Orgtbl mode minor mode:: The table editor as minor mode
* The spreadsheet:: The table editor has spreadsheet capabilities
* Org-Plot:: Plotting from Org tables
Built-in table editor
* Creation and conversion:: Creating tabular data in Org
* Re-aligning and field motion:: Navigating and tidying
* Column and row editing:: Insert, kill, or move
* Regions:: Manipulate parts of a table
* Calculations:: Sum and copy
* Misc:: Some other useful operations
The spreadsheet
* References:: How to refer to another field or range
* Formula syntax for Calc:: Using Calc to compute stuff
* Emacs Lisp forms as formulas:: Writing formulas in Emacs Lisp
* Duration and time values:: How to compute duration and time values
* Field and range formulas:: Formulas for specific (ranges of) fields
* Column formulas:: Formulas valid for an entire column
* Lookup functions:: Lookup functions for searching tables
* Editing and debugging formulas:: Fixing formulas
* Debugging formulas:: Help fixing formulas
* Updating the table:: Recomputing all dependent fields
* Advanced features:: Field and column names, parameters, and automatic recalc
References
* Field references:: Refer to a particular field
* Range references:: Refer to a range of fields
* Field coordinates in formulas:: Refer to fields in Lisp or Calc
* Named references:: Name columns or constants
* Remote references:: Refer to information in other tables
Hyperlinks
* Link format:: How links in Org are formatted
* Internal links:: Links to other places in the current file
* Radio targets:: Automatically create internal links
* External links:: URL-like links to the world
* Handling links:: URL-like links to the world
* Using links outside Org:: Linking from my C source code?
* Link abbreviations:: Shortcuts for writing complex links
* Search options:: Linking to a specific location
* Custom searches:: When the default search is not enough
TODO items
* TODO basics:: Marking and displaying TODO entries
* TODO extensions:: Work flow and assignments
* Progress logging:: Dates and notes for progress
* Priorities:: Some things are more important than others
* Breaking down tasks:: Splitting a task into manageable pieces
* Checkboxes:: Tick-off lists
TODO extensions
* Workflow states:: From TODO to DONE in steps
* TODO types:: I do this, Fred does the rest
* Multiple sets in one file:: Mixing it all, and still finding your way
* Fast access to TODO states:: Single letter selection of state
* Per-file keywords:: Different files, different requirements
* Faces for TODO keywords:: Highlighting states
* TODO dependencies:: When one task needs to wait for others
Progress logging
* Closing items:: When was this entry marked DONE?
* Tracking TODO state changes:: When did the status change?
* Tracking your habits:: How consistent have you been?
Tags
* Tag inheritance:: Tags use the tree structure of an outline
* Setting tags:: How to assign tags to a headline
* Tag searches:: Searching for combinations of tags
Properties and columns
* Property syntax:: How properties are spelled out
* Special properties:: Access to other Org mode features
* Property searches:: Matching property values
* Property inheritance:: Passing values down a tree
* Column view:: Tabular viewing and editing
* Property API:: Properties for Lisp programmers
Column view
* Defining columns:: The COLUMNS format property
* Using column view:: How to create and use column view
* Capturing column view:: A dynamic block for column view
Defining columns
* Scope of column definitions:: Where defined, where valid?
* Column attributes:: Appearance and content of a column
Dates and times
* Timestamps:: Assigning a time to a tree entry
* Creating timestamps:: Commands to insert timestamps
* Deadlines and scheduling:: Planning your work
* Clocking work time:: Tracking how long you spend on a task
* Effort estimates:: Planning work effort in advance
* Relative timer:: Notes with a running timer
* Countdown timer:: Starting a countdown timer for a task
Creating timestamps
* The date/time prompt:: How Org mode helps you enter dates and times
* Custom time format:: Making dates look different
Deadlines and scheduling
* Inserting deadline/schedule:: Planning items
* Repeated tasks:: Items that show up again and again
Clocking work time
* Clocking commands:: Starting and stopping a clock
* The clock table:: Detailed reports
* Resolving idle time:: Resolving time when you've been idle
* Continuous clocking::
Capture - Refile - Archive
* Capture:: Capturing new stuff
* Attachments:: Add files to tasks
* RSS feeds:: Getting input from RSS feeds
* Protocols:: External (e.g., browser) access to Emacs and Org
* Refile and copy:: Moving/copying a tree from one place to another
* Archiving:: What to do with finished products
Capture
* Setting up capture:: Where notes will be stored
* Using capture:: Commands to invoke and terminate capture
* Capture templates:: Define the outline of different note types
Capture templates
* Template elements:: What is needed for a complete template entry
* Template expansion:: Filling in information about time and context
* Templates in contexts:: Only show a template in a specific context
Archiving
* Moving subtrees:: Moving a tree to an archive file
* Internal archiving:: Switch off a tree but keep it in the file
Agenda views
* Agenda files:: Files being searched for agenda information
* Agenda dispatcher:: Keyboard access to agenda views
* Built-in agenda views:: What is available out of the box?
* Presentation and sorting:: How agenda items are prepared for display
* Agenda commands:: Remote editing of Org trees
* Custom agenda views:: Defining special searches and views
* Exporting agenda views:: Writing a view to a file
* Using column view in the agenda:: Using column view for collected entries
Built-in agenda views
* Weekly/daily agenda:: The calendar page with current tasks
* Global TODO list:: All unfinished action items
* Matching tags and properties:: Structured information with fine-tuned search
* Timeline for a single file:: Time-sorted view for a single file
* Search view:: Find entries by searching for text
* Stuck projects:: Find projects you need to review
Weekly/daily agenda
* Calendar/Diary integration:: Integrate the Emacs diary with Org
* Anniversaries from BBDB:: Integrate Big Brother Database and Org
* Appointment reminders:: Integrate the Emacs appointment facility and Org
Presentation and sorting
* Categories:: Not all tasks are equal
* Time-of-day specifications:: How the agenda knows the time
* Sorting of agenda items:: The order of things
Agenda commands
* Motion2::
* View/Go to Org file::
* Change display::
* Secondary filtering and query editing::
* Remote editing::
* Bulk remote editing selected entries::
* Calendar commands::
* Exporting to a file::
* Quit and exit::
Custom agenda views
* Storing searches:: Type once, use often
* Block agenda:: All the stuff you need in a single buffer
* Setting options for custom commands:: Changing the rules
Markup for rich export
* Structural markup elements:: The basic structure as seen by the exporter
* Images and tables:: Tables and images can be exported
* Literal examples:: Source code examples with special formatting
* Include files:: Include additional files into a document
* Index entries:: Making an index
* Macro replacement:: Use macros to create complex output
* Embedded LaTeX:: LaTeX can be freely used inside Org documents
Structural markup elements
* Document title:: Where the title is taken from
* Headings and sections:: The document structure as seen by the exporter
* Table of contents:: The if and where of the table of contents
* Initial text:: Text before the first heading?
* Lists:: Lists
* Paragraphs:: Paragraphs
* Footnote markup:: Footnotes
* Emphasis and monospace:: Bold, italic, etc.
* Horizontal rules:: Make a line
* Comment lines:: What will *not* be exported
Embedded LaTeX
* Special symbols:: Greek letters and other symbols
* Subscripts and superscripts:: Simple syntax for raising/lowering text
* LaTeX fragments:: Complex formulas made easy
* Previewing LaTeX fragments:: What will this snippet look like?
* CDLaTeX mode:: Speed up entering of formulas
Exporting
* Selective export:: Using tags to select and exclude trees
* Export options:: Per-file export settings
* The export dispatcher:: How to access exporter commands
* ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
* HTML export:: Exporting to HTML
* LaTeX and PDF export:: Exporting to LaTeX and processing to PDF
* DocBook export:: Exporting to DocBook
* OpenDocument Text export:: Exporting to OpenDocument Text
* TaskJuggler export:: Exporting to TaskJuggler
* Freemind export:: Exporting to Freemind mind maps
* XOXO export:: Exporting to XOXO
* iCalendar export:: Exporting to iCalendar format
HTML export
* HTML export commands:: How to invoke HTML export
* HTML preamble and postamble:: How to insert a preamble and postamble
* Quoting HTML tags:: Using direct HTML in Org mode
* Links in HTML export:: How links will be interpreted and formatted
* Tables in HTML export:: How to modify the formatting of tables
* Images in HTML export:: How to insert figures into HTML output
* Math formatting in HTML export:: Beautiful math also on the web
* Text areas in HTML export:: An alternate way to show an example
* CSS support:: Changing the appearance of the output
* JavaScript support:: Info and folding in a web browser
LaTeX and PDF export
* LaTeX/PDF export commands:: Invoking export to LaTeX/PDF
* Header and sectioning:: Setting up the export file structure
* Quoting LaTeX code:: Incorporating literal LaTeX code
* Tables in LaTeX export:: Options for exporting tables to LaTeX
* Images in LaTeX export:: How to insert figures into LaTeX output
* Beamer class export:: Turning the file into a presentation
DocBook export
* DocBook export commands:: How to invoke DocBook export
* Quoting DocBook code:: Incorporating DocBook code in Org files
* Recursive sections:: Recursive sections in DocBook
* Tables in DocBook export:: Tables are exported as HTML tables
* Images in DocBook export:: How to insert figures into DocBook output
* Special characters:: How to handle special characters
OpenDocument Text export
* Pre-requisites for ODT export:: What packages ODT exporter relies on
* ODT export commands:: How to invoke ODT export
* Extending ODT export:: How to produce ~doc~, ~pdf~ files
* Applying custom styles:: How to apply custom styles to the output
* Links in ODT export:: How links will be interpreted and formatted
* Tables in ODT export:: How tables are exported
* Images in ODT export:: How to insert images
* Math formatting in ODT export:: How LaTeX fragments are formatted
* Labels and captions in ODT export:: How captions are rendered
* Literal examples in ODT export:: How source and example blocks are formatted
* Advanced topics in ODT export:: Read this if you are a power user
Extending ODT export
* Automatically exporting to other formats:: Automatic conversion to doc, docx, etc.
* Converting between document formats:: Interacting with configured converters
Math formatting in ODT export
* Working with LaTeX math snippets:: How to embed LaTeX math fragments
* Working with MathML or OpenDocument formula files:: How to embed equations in native format
Advanced topics in ODT export
* Configuring a document converter:: How to register a document converter
* Working with OpenDocument style files:: Explore the internals
* Creating one-off styles:: How to produce custom highlighting, etc.
* Customizing tables in ODT export:: How to define and use table templates
* Validating OpenDocument XML:: How to debug corrupt OpenDocument files
TaskJuggler export
* TaskJuggler export commands:: Key bindings for TaskJuggler export
* Tasks:: Marking tasks for TaskJuggler export
* Resources:: Define TaskJuggler resources
* Export of properties:: Which properties will be exported?
* Dependencies:: How the exporter handles dependencies
* Reports:: Gantt charts, etc.
Publishing
* Configuration:: Defining projects
* Uploading files:: How to get files up on the server
* Sample configuration:: Example projects
* Triggering publication:: Publication commands
Configuration
* Project alist:: The central configuration variable
* Sources and destinations:: From here to there
* Selecting files:: What files are part of the project?
* Publishing action:: Setting the function doing the publishing
* Publishing options:: Tweaking HTML/LaTeX export
* Publishing links:: Which links keep working after publishing?
* Site map:: Generating a list of all pages
* Generating an index:: An index that reaches across pages
Sample configuration
* Simple example:: One-component publishing
* Complex example:: A multi-component publishing example
Working with source code
* Structure of code blocks:: Code block syntax described
* Editing source code:: Language major-mode editing
* Exporting code blocks:: Export contents and/or results
* Extracting source code:: Create pure source code files
* Evaluating code blocks:: Place results in the Org buffer
* Library of Babel:: Use and contribute to a source code library
* Languages:: Supported code block languages
* Header arguments:: Configure code block functionality
* Results of evaluation:: How evaluation results are handled
* Noweb reference syntax:: Literate programming in Org mode
* Key bindings and useful functions:: Work quickly with code blocks
* Batch execution:: Call functions from the command line
Extracting source code
* Header arguments for tangling::
* Functions for tangling::
* Hooks for tangling::
Header arguments
* Using header arguments:: Different ways to set header arguments
* Specific header arguments:: List of header arguments
Using header arguments
* System-wide header arguments:: Set global default values
* Language-specific header arguments:: Set default values by language
* Buffer-wide header arguments:: Set default values for a specific buffer
* Header arguments in Org mode properties:: Set default values for a buffer or heading
* Code block specific header arguments:: The most common way to set values
* Header arguments in function calls:: The most specific level
Specific header arguments
* var:: Pass arguments to code blocks
* results:: Specify the type of results and how they will be collected and handled
* file:: Specify a path for file output
* file-desc:: Specify a description for file results
* dir:: Specify the default (possibly remote) directory for code block execution
* exports:: Export code and/or results
* tangle:: Toggle tangling and specify file name
* mkdirp:: Toggle creation of parent directories of target files during tangling
* comments:: Toggle insertion of comments in tangled code files
* padline:: Control insertion of padding lines in tangle code files
* no-expand:: Turn off variable assignment and noweb expansion during tangling
* session:: Preserve state of code evaluation
* noweb:: Toggle expansion of noweb references
* noweb-ref:: Specify block's noweb reference resolution target
* noweb-sep:: String used to separate noweb references
* cache:: Avoid re-evaluating unchanged code blocks
* sep:: Delimiter for writing tabular results outside Org
* hlines:: Handle horizontal lines in tables
* colnames:: Handle column names in tables
* rownames:: Handle row names in tables
* shebang:: Make tangles files executable
* eval:: Limit evaluation of specific code blocks
* wrap:: Mark source block evaluation results
Results of evaluation
* Non-session::
* Session::
Miscellaneous
* Completion:: M-TAB knows what you need
* Easy templates:: Quick insertion of structural elements
* Speed keys:: Electric commands at the beginning of a headline
* Code evaluation security:: Org mode files evaluate in-line code
* Customization:: Adapting Org to your taste
* In-buffer settings:: Overview of the #+KEYWORDS
* The very busy C-c C-c key:: When in doubt, press C-c C-c
* Clean view:: Getting rid of leading stars in the outline
* TTY keys:: Using Org on a tty
* Interaction:: Other Emacs packages
* org-crypt:: Encrypting Org files
Interaction
* Cooperation:: Packages Org cooperates with
* Conflicts:: Packages that lead to conflicts
Hacking
* Hooks:: How to reach into Org's internals
* Add-on packages:: Available extensions
* Adding hyperlink types:: New custom link types
* Context-sensitive commands:: How to add functionality to such commands
* Tables in arbitrary syntax:: Orgtbl for LaTeX and other programs
* Dynamic blocks:: Automatically filled blocks
* Special agenda views:: Customized views
* Extracting agenda information:: Post-processing agenda information
* Using the property API:: Writing programs that use entry properties
* Using the mapping API:: Mapping over all or selected entries
Tables in arbitrary syntax
* Radio tables:: Sending and receiving radio tables
* A LaTeX example:: Step by step, almost a tutorial
* Translator functions:: Copy and modify
* Radio lists:: Doing the same for lists
MobileOrg
* Setting up the staging area:: Where to interact with the mobile device
* Pushing to MobileOrg:: Uploading Org files and agendas
* Pulling from MobileOrg:: Integrating captured and flagged items
History and acknowledgments
* From Carsten::
* From Bastien::
* List of contributions::
File: orgmanual.info, Node: Introduction, Next: Document structure, Prev: Top, Up: Top
1 Introduction
**************
* Menu:
* Summary:: Brief summary of what Org-mode does
* Installation:: How to install a downloaded version of Org-mode
* Activation:: How to activate Org-mode for certain buffers
* Feedback:: Bug reports, ideas, patches, etc.
* How to create a useful backtrace:: The best way to report an error
* Conventions:: Typesetting conventions in the manual
File: orgmanual.info, Node: Summary, Next: Installation, Up: Introduction
1.1 Summary
===========
Org is a mode for keeping notes, maintaining TODO lists, and doing
project planning with a fast and effective plain-text system.
Org develops organizational tasks around NOTES files that contain
lists or information about projects as plain text. Org is implemented
on top of Outline mode, which makes it possible to keep the content of
large files well structured. Visibility cycling and structure editing
help to work with the tree. Tables are easily created with a built-in
table editor. Org supports TODO items, deadlines, timestamps, and
scheduling. It dynamically compiles entries into an agenda that
utilizes and smoothly integrates much of the Emacs calendar and diary.
Plain text URL-like links connect to websites, emails, Usenet messages,
BBDB entries, and any files related to the projects. For printing and
sharing of notes, an Org file can be exported as a structured ASCII
file, as HTML, or as an iCalendar file.(1) It can also serve as a
publishing tool for a set of linked web pages.
As a project planning environment, Org works by adding metadata to
outline nodes. Based on this data, specific entries can be extracted in
queries and create dynamic _agenda views_.
Org mode contains the Org Babel environment which allows you to work
with embedded source code blocks in a file, to facilitate code
evaluation, documentation, and literate programming techniques.
Org's automatic, context-sensitive table editor with spreadsheet
capabilities can be integrated into any major mode by activating the
minor Orgtbl mode. Using a translation step, it can be used to maintain
tables in arbitrary file types, for example in LaTeX. The structure
editing and list creation capabilities can be used outside Org with the
minor Orgstruct mode.
Org keeps simple things simple. When first fired up, it should feel
like a straightforward, easy to use outliner. Complexity is not
imposed, but a large amount of functionality is available when you need
it. Org is a toolbox and can be used in different ways and for
different ends, for example:
* an outline extension with visibility cycling and structure editing
* an ASCII system and table editor for taking structured notes
* a TODO list editor
* a full agenda and planner with deadlines and work scheduling
* an environment in which to implement David Allen's GTD system
* a simple hypertext system, with HTML and LaTeX export
* a publishing tool to create a set of interlinked web pages
* an environment for literate programming
There is a website for Org (http://orgmode.org) that provides links
to the newest version of Org, as well as additional information,
frequently asked questions (FAQ), links to tutorials, etc.
Version 7.3 of this manual is available as a paperback book from
Network Theory Ltd. (http://www.network-theory.co.uk/org/manual/)
---------- Footnotes ----------
(1) The iCalendar file will contain TODO and agenda items only.
File: orgmanual.info, Node: Installation, Next: Activation, Prev: Summary, Up: Introduction
1.2 Installation
================
*Important:* If you have the version of Org that comes with Emacs or as
a XEmacs package, please skip this section and go directly to *note
Activation::. If you downloaded Org as an ELPA package, please read the
instructions on the Org ELPA page (http://orgmode.org/elpa.html). To
see what version of Org (if any) is part of your Emacs distribution,
type `M-x org-version'.(1)
Installation of Org mode uses a build system, which is described in
more detail on Worg (http://orgmode.org/worg/dev/org-build-system.html).
If you have downloaded Org from the Web as a distribution `.zip' or
`.tar.gz' archive, take the following steps to install it:
* Unpack the distribution archive
* Change into (`cd') the Org directory
* Run `make help config' and then check and edit the file `local.mk'
if the default configuration does not match your system
* Set the name of the Emacs binary (likely either `emacs' or
`xemacs'), and the paths to the directories where local Lisp
and Info files will be installed
* If the Emacs binary is not in your path, give the full path to
the executable
* Avoid spaces in any path names
* Run `make config' again to check the configuration
* Run `make install' or `sudo make install' to build and install Org
mode on your system
If you use a cloned Git repository, then the procedure is slightly
different. The following description assumes that you are using the
`master' branch.(2) You could also use the `maint' branch instead,
where the release versions are published, just replace `master' with
`maint' in the description below.
* Change into (`cd') the Org repository
* Run `git checkout master' to switch to the `master' branch of the
Org repository
* Run `make help' and then check and edit the file `local.mk'
* You must set the name of the Emacs binary (likely either
`emacs' or `xemacs'), and the paths to the directories where
local Lisp and Info files will be installed
* If the Emacs binary is not in your path, you must give the
full path to the executable
* Avoid spaces in any path names
* Run `make config' to check the configuration
* Optionally run `make test' to build Org mode and then run the full
test suite
* Run `make update2' or `make up2' to update the Git repository and
build and install Org mode. The latter invocation runs the
complete test suite before installation and installs only if the
build passes all tests
If you don't have access to the system-wide directories and you don't
want to install somewhere into your home directory, you can run Org
directly from the distribution directory or Org repository by compiling
Org mode in place:
* Change into (`cd') the Org repository
* Run `git checkout master' to switch to the `master' branch of the
Org repository
* Run `make compile'
Last but not least you can also run Org mode directly from an Org
repository without any compilation. Simply replace the last step in
the recipe above with `make uncompiled'.
Then add the following line to `.emacs':
(add-to-list 'load-path "~/path/to/orgdir/lisp")
If you plan to use code files from the `contrib' subdirectory without
compiling them, do a similar step for this directory:
(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
If you want to include those files with the build and install, please
customize the variable `ORG_ADD_CONTRIB' instead in your `local.mk'
file. For more details please see this description on Worg
(http://orgmode.org/worg/dev/org-build-system.html#sec-4-1-2).
Installing Info files is system dependent, because of differences in
the `install-info' program. The Info documentation is installed
together with the rest of Org mode. If you don't install Org mode, it
is possible to install the Info documentation separately if you have
install-info on your system.(3)
The command to do this is:
make install-info
Do not forget to activate Org as described in the following section.
---------- Footnotes ----------
(1) If your Emacs distribution does not come with Org, the function
`org-version' will not be defined.
(2) The `master' branch is where development takes place.
(3) The output from install-info (if any) is system dependent. In
particular, Debian and its derivatives use two different versions of
install-info. You may safely ignore the message:
This is not dpkg install-info anymore, but GNU install-info
See the man page for ginstall-info for command line arguments
returned by install-info.
File: orgmanual.info, Node: Activation, Next: Feedback, Prev: Installation, Up: Introduction
1.3 Activation
==============
Since Emacs 22.2, files with the `.org' extension use Org mode by
default. If you are using an earlier version of Emacs, add this line
to your `.emacs' file:
(add-to-list 'auto-mode-alist '("\\.org\\'" . org-mode))
Org mode buffers need font-lock to be turned on - this is the
default in Emacs.(1)
There are compatibility issues between Org mode and some other Elisp
packages, please take the time to check the list (see *note
Conflicts::).
The four Org commands `org-store-link', `org-capture', `org-agenda',
and `org-iswitchb' should be accessible through global keys (i.e.,
anywhere in Emacs, not just in Org buffers). Here are suggested
bindings for these keys, please modify the keys to your own liking.
(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-cc" 'org-capture)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cb" 'org-iswitchb)
With this setup, all files with extension `.org' will be put into
Org mode. As an alternative, make the first line of a file look like
this:
MY PROJECTS -*- mode: org; -*-
which will select Org mode for this buffer no matter what the file's
name is. See also the variable `org-insert-mode-line-in-empty-file'.
Many commands in Org work on the region if the region is _active_. To
make use of this, you need to have `transient-mark-mode'
(`zmacs-regions' in XEmacs) turned on. In Emacs 23 this is the default,
in Emacs 22 you need to do this yourself with
(transient-mark-mode 1)
If you do not like `transient-mark-mode', you can create an active
region by using the mouse to select a region, or pressing `C-<SPC>'
twice before moving the cursor.
---------- Footnotes ----------
(1) If you don't use font-lock globally, turn it on in an Org buffer
with `(add-hook 'org-mode-hook 'turn-on-font-lock)'.
File: orgmanual.info, Node: Feedback, Next: How to create a useful backtrace, Prev: Activation, Up: Introduction
1.4 Feedback
============
If you find problems with Org, or if you have questions, remarks, or
ideas about it, please mail to the Org mailing list
<[email protected]>. If you are not a member of the mailing list,
your mail will be passed to the list after a moderator has approved
it.(1)
For bug reports, please first try to reproduce the bug with the
latest version of Org available--if you are running an outdated
version, it is quite possible that the bug has been fixed already. If
the bug persists, prepare a report and provide as much information as
possible, including the version information of Emacs (`M-x
emacs-version <RET>') and Org (`M-x org-version <RET>'), as well as the
Org related setup in `.emacs'. The easiest way to do this is to use the
command `M-x org-submit-bug-report', which will put all this
information into an Emacs mail buffer so that you only need to add your
description. If you are not sending the Email from within Emacs, please
copy and paste the content into your Email program.
Sometimes you might face a problem due to an error in your Emacs or
Org mode setup. Before reporting a bug, it is very helpful to start
Emacs with minimal customizations and reproduce the problem. Doing so
often helps you determine if the problem is with your customization or
with Org mode itself. You can start a typical minimal session with a
command like the example below.
$ emacs -Q -l /path/to/minimal-org.el
However if you are using Org mode distributed with Emacs, a minimal
setup is not necessary. In that case it is sufficient to start Emacs as
`emacs -Q'. The `minimal-org.el' setup file can have contents as shown
below.
;;; Minimal setup to load latest `org-mode'
;; activate debugging
(setq debug-on-error t
debug-on-signal nil
debug-on-quit nil)
;; add latest org-mode to load path
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
If an error occurs, a backtrace can be very useful (see *note How to
create a useful backtrace::). Often a small example file helps, along
with clear information about:
1. What exactly did you do?
2. What did you expect to happen?
3. What happened instead?
Thank you for helping to improve this program.
---------- Footnotes ----------
(1) Please consider subscribing to the mailing list in order to
minimize the work the mailing list moderators have to do.
File: orgmanual.info, Node: How to create a useful backtrace, Next: Conventions, Prev: Feedback, Up: Introduction
1.5 How to create a useful backtrace
====================================
If working with Org produces an error with a message you don't
understand, you may have hit a bug. The best way to report this is by
providing, in addition to what was mentioned above, a _backtrace_.
This is information from the built-in debugger about where and how the
error occurred. Here is how to produce a useful backtrace:
1. Reload uncompiled versions of all Org mode Lisp files. The
backtrace contains much more information if it is produced with
uncompiled code. To do this, use `C-u M-x org-reload <RET>' or
select `Org -> Refresh/Reload -> Reload Org uncompiled' from the
menu.
2. Go to the `Options' menu and select `Enter Debugger on Error'
(XEmacs has this option in the `Troubleshooting' sub-menu).
3. Do whatever you have to do to hit the error. Don't forget to
document the steps you take.
4. When you hit the error, a `*Backtrace*' buffer will appear on the
screen. Save this buffer to a file (for example using `C-x C-w')
and attach it to your bug report.
File: orgmanual.info, Node: Conventions, Prev: How to create a useful backtrace, Up: Introduction
1.6 Conventions
===============
Conventions for typesetting keywords, keybindings, and commands in this
manual are described.
* Menu:
* Three types of keywords:: TODO, tags, and properties
* Keybindings and commands:: Bind useful commands to keys
File: orgmanual.info, Node: Three types of keywords, Next: Keybindings and commands, Up: Conventions
1.6.1 Three types of keywords
-----------------------------
Org mainly uses three types of keywords: TODO keywords, tags and
property names. In this manual we use the following conventions:
`TODO, WAITING'
TODO keywords are written with all capitals, even if they are
user-defined.
`boss, ARCHIVE'
User-defined tags are written in lowercase; built-in tags with
special meaning are written with all capitals.
`Release, PRIORITY'
User-defined properties are capitalized; built-in properties with
special meaning are written with all capitals.
Moreover, Org uses _option keywords_ (like `#+TITLE' to set the
title) and _environment keywords_ (like `#+BEGIN_HTML' to start a `HTML'
environment). They are written in uppercase in the manual to enhance
its readability, but you can use lowercase in your Org files.(1)
---------- Footnotes ----------
(1) Easy templates insert lowercase keywords and Babel dynamically
inserts `#+results'.
File: orgmanual.info, Node: Keybindings and commands, Prev: Three types of keywords, Up: Conventions
1.6.2 Keybindings and commands
------------------------------
The manual suggests two global keybindings: `C-c a' for `org-agenda'