123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916119171191811919119201192111922119231192411925119261192711928119291193011931119321193311934119351193611937119381193911940119411194211943119441194511946119471194811949119501195111952119531195411955119561195711958119591196011961119621196311964119651196611967119681196911970119711197211973119741197511976119771197811979119801198111982119831198411985119861198711988119891199011991119921199311994119951199611997119981199912000120011200212003120041200512006120071200812009120101201112012120131201412015120161201712018120191202012021120221202312024120251202612027120281202912030120311203212033120341203512036120371203812039120401204112042120431204412045120461204712048120491205012051120521205312054120551205612057120581205912060120611206212063120641206512066120671206812069120701207112072120731207412075120761207712078120791208012081120821208312084120851208612087120881208912090120911209212093120941209512096120971209812099121001210112102121031210412105121061210712108121091211012111121121211312114121151211612117121181211912120121211212212123121241212512126121271212812129121301213112132121331213412135121361213712138121391214012141121421214312144121451214612147121481214912150121511215212153121541215512156121571215812159121601216112162121631216412165121661216712168121691217012171121721217312174121751217612177121781217912180121811218212183121841218512186121871218812189121901219112192121931219412195121961219712198121991220012201122021220312204122051220612207122081220912210122111221212213122141221512216122171221812219122201222112222122231222412225122261222712228122291223012231122321223312234122351223612237122381223912240122411224212243122441224512246122471224812249122501225112252122531225412255122561225712258122591226012261122621226312264122651226612267122681226912270122711227212273122741227512276122771227812279122801228112282122831228412285122861228712288122891229012291122921229312294122951229612297122981229912300123011230212303123041230512306123071230812309123101231112312123131231412315123161231712318123191232012321123221232312324123251232612327123281232912330123311233212333123341233512336123371233812339123401234112342123431234412345123461234712348123491235012351123521235312354123551235612357123581235912360123611236212363123641236512366123671236812369123701237112372123731237412375123761237712378123791238012381123821238312384123851238612387123881238912390123911239212393123941239512396123971239812399124001240112402124031240412405124061240712408124091241012411124121241312414124151241612417124181241912420124211242212423124241242512426124271242812429124301243112432124331243412435124361243712438124391244012441124421244312444124451244612447124481244912450124511245212453124541245512456124571245812459124601246112462124631246412465124661246712468124691247012471124721247312474124751247612477124781247912480124811248212483124841248512486124871248812489124901249112492124931249412495124961249712498124991250012501125021250312504125051250612507125081250912510125111251212513125141251512516125171251812519125201252112522125231252412525125261252712528125291253012531125321253312534125351253612537125381253912540125411254212543125441254512546125471254812549125501255112552125531255412555125561255712558125591256012561125621256312564125651256612567125681256912570125711257212573125741257512576125771257812579125801258112582125831258412585125861258712588125891259012591125921259312594125951259612597125981259912600126011260212603126041260512606126071260812609126101261112612126131261412615126161261712618126191262012621126221262312624126251262612627126281262912630126311263212633126341263512636126371263812639126401264112642126431264412645126461264712648126491265012651126521265312654126551265612657126581265912660126611266212663126641266512666126671266812669126701267112672126731267412675126761267712678126791268012681126821268312684126851268612687126881268912690126911269212693126941269512696126971269812699127001270112702127031270412705127061270712708127091271012711127121271312714127151271612717127181271912720127211272212723127241272512726127271272812729127301273112732127331273412735127361273712738127391274012741127421274312744127451274612747127481274912750127511275212753127541275512756127571275812759127601276112762127631276412765127661276712768127691277012771127721277312774127751277612777127781277912780127811278212783127841278512786127871278812789127901279112792127931279412795127961279712798127991280012801128021280312804128051280612807128081280912810128111281212813128141281512816128171281812819128201282112822128231282412825128261282712828128291283012831128321283312834128351283612837128381283912840128411284212843128441284512846128471284812849128501285112852128531285412855128561285712858128591286012861128621286312864128651286612867128681286912870128711287212873128741287512876128771287812879128801288112882128831288412885128861288712888128891289012891128921289312894128951289612897128981289912900129011290212903129041290512906129071290812909129101291112912129131291412915129161291712918129191292012921129221292312924129251292612927129281292912930129311293212933129341293512936129371293812939129401294112942129431294412945129461294712948129491295012951129521295312954129551295612957129581295912960129611296212963129641296512966129671296812969129701297112972129731297412975129761297712978129791298012981129821298312984129851298612987129881298912990129911299212993129941299512996129971299812999130001300113002130031300413005130061300713008130091301013011130121301313014130151301613017130181301913020130211302213023130241302513026130271302813029130301303113032130331303413035130361303713038130391304013041130421304313044130451304613047130481304913050130511305213053130541305513056130571305813059130601306113062130631306413065130661306713068130691307013071130721307313074130751307613077130781307913080130811308213083130841308513086130871308813089130901309113092130931309413095130961309713098130991310013101131021310313104131051310613107131081310913110131111311213113131141311513116131171311813119131201312113122131231312413125131261312713128131291313013131131321313313134131351313613137131381313913140131411314213143131441314513146131471314813149131501315113152131531315413155131561315713158131591316013161131621316313164131651316613167131681316913170131711317213173131741317513176131771317813179131801318113182131831318413185131861318713188131891319013191131921319313194131951319613197131981319913200132011320213203132041320513206132071320813209132101321113212132131321413215132161321713218132191322013221132221322313224132251322613227132281322913230132311323213233132341323513236132371323813239132401324113242132431324413245132461324713248132491325013251132521325313254132551325613257132581325913260132611326213263132641326513266132671326813269132701327113272132731327413275132761327713278132791328013281132821328313284132851328613287132881328913290132911329213293132941329513296132971329813299133001330113302133031330413305133061330713308133091331013311133121331313314133151331613317133181331913320133211332213323133241332513326133271332813329133301333113332133331333413335133361333713338133391334013341133421334313344133451334613347133481334913350133511335213353133541335513356133571335813359133601336113362133631336413365133661336713368133691337013371133721337313374133751337613377133781337913380133811338213383133841338513386133871338813389133901339113392133931339413395133961339713398133991340013401134021340313404134051340613407134081340913410134111341213413134141341513416134171341813419134201342113422134231342413425134261342713428134291343013431134321343313434134351343613437134381343913440134411344213443134441344513446134471344813449134501345113452134531345413455134561345713458134591346013461134621346313464134651346613467134681346913470134711347213473134741347513476134771347813479134801348113482134831348413485134861348713488134891349013491134921349313494134951349613497134981349913500135011350213503135041350513506135071350813509135101351113512135131351413515135161351713518135191352013521135221352313524135251352613527135281352913530135311353213533135341353513536135371353813539135401354113542135431354413545135461354713548135491355013551135521355313554135551355613557135581355913560135611356213563135641356513566135671356813569135701357113572135731357413575135761357713578135791358013581135821358313584135851358613587135881358913590135911359213593135941359513596135971359813599136001360113602136031360413605136061360713608136091361013611136121361313614136151361613617136181361913620136211362213623136241362513626136271362813629136301363113632136331363413635136361363713638136391364013641136421364313644136451364613647136481364913650136511365213653136541365513656136571365813659136601366113662136631366413665136661366713668136691367013671136721367313674136751367613677136781367913680136811368213683136841368513686136871368813689136901369113692136931369413695136961369713698136991370013701137021370313704137051370613707137081370913710137111371213713137141371513716137171371813719137201372113722137231372413725137261372713728137291373013731137321373313734137351373613737137381373913740137411374213743137441374513746137471374813749137501375113752137531375413755137561375713758137591376013761137621376313764137651376613767137681376913770137711377213773137741377513776137771377813779137801378113782137831378413785137861378713788137891379013791137921379313794137951379613797137981379913800138011380213803138041380513806138071380813809138101381113812138131381413815138161381713818138191382013821138221382313824138251382613827138281382913830138311383213833138341383513836138371383813839138401384113842138431384413845138461384713848138491385013851138521385313854138551385613857138581385913860138611386213863138641386513866138671386813869138701387113872138731387413875138761387713878138791388013881138821388313884138851388613887138881388913890138911389213893138941389513896138971389813899139001390113902139031390413905139061390713908139091391013911139121391313914139151391613917139181391913920139211392213923139241392513926139271392813929139301393113932139331393413935139361393713938139391394013941139421394313944139451394613947139481394913950139511395213953139541395513956139571395813959139601396113962139631396413965139661396713968139691397013971139721397313974139751397613977139781397913980139811398213983139841398513986139871398813989139901399113992139931399413995139961399713998139991400014001140021400314004140051400614007140081400914010140111401214013140141401514016140171401814019140201402114022140231402414025140261402714028140291403014031140321403314034140351403614037140381403914040140411404214043140441404514046140471404814049140501405114052140531405414055140561405714058140591406014061140621406314064140651406614067140681406914070140711407214073140741407514076140771407814079140801408114082140831408414085140861408714088140891409014091140921409314094140951409614097140981409914100141011410214103141041410514106141071410814109141101411114112141131411414115141161411714118141191412014121141221412314124141251412614127141281412914130141311413214133141341413514136141371413814139141401414114142141431414414145141461414714148141491415014151141521415314154141551415614157141581415914160141611416214163141641416514166141671416814169141701417114172141731417414175141761417714178141791418014181141821418314184141851418614187141881418914190141911419214193141941419514196141971419814199142001420114202142031420414205142061420714208142091421014211142121421314214142151421614217142181421914220142211422214223142241422514226142271422814229142301423114232142331423414235142361423714238142391424014241142421424314244142451424614247142481424914250142511425214253142541425514256142571425814259142601426114262142631426414265142661426714268142691427014271142721427314274142751427614277142781427914280142811428214283142841428514286142871428814289142901429114292142931429414295142961429714298142991430014301143021430314304143051430614307143081430914310143111431214313143141431514316143171431814319143201432114322143231432414325143261432714328143291433014331143321433314334143351433614337143381433914340143411434214343143441434514346143471434814349143501435114352143531435414355143561435714358143591436014361143621436314364143651436614367143681436914370143711437214373143741437514376143771437814379143801438114382143831438414385143861438714388143891439014391143921439314394143951439614397143981439914400144011440214403144041440514406144071440814409144101441114412144131441414415144161441714418144191442014421144221442314424144251442614427144281442914430144311443214433144341443514436144371443814439144401444114442144431444414445144461444714448144491445014451144521445314454144551445614457144581445914460144611446214463144641446514466144671446814469144701447114472144731447414475144761447714478144791448014481144821448314484144851448614487144881448914490144911449214493144941449514496144971449814499145001450114502145031450414505145061450714508145091451014511145121451314514145151451614517145181451914520145211452214523145241452514526145271452814529145301453114532145331453414535145361453714538145391454014541145421454314544145451454614547145481454914550145511455214553145541455514556145571455814559145601456114562145631456414565145661456714568145691457014571145721457314574145751457614577145781457914580145811458214583145841458514586145871458814589145901459114592145931459414595145961459714598145991460014601146021460314604146051460614607146081460914610146111461214613146141461514616146171461814619146201462114622146231462414625146261462714628146291463014631146321463314634146351463614637146381463914640146411464214643146441464514646146471464814649146501465114652146531465414655146561465714658146591466014661146621466314664146651466614667146681466914670146711467214673146741467514676146771467814679146801468114682146831468414685146861468714688146891469014691146921469314694146951469614697146981469914700147011470214703147041470514706147071470814709147101471114712147131471414715147161471714718147191472014721147221472314724147251472614727147281472914730147311473214733147341473514736147371473814739147401474114742147431474414745147461474714748147491475014751147521475314754147551475614757147581475914760147611476214763147641476514766147671476814769147701477114772147731477414775147761477714778147791478014781147821478314784147851478614787147881478914790147911479214793147941479514796147971479814799148001480114802148031480414805148061480714808148091481014811148121481314814148151481614817148181481914820148211482214823148241482514826148271482814829148301483114832148331483414835148361483714838148391484014841148421484314844148451484614847148481484914850148511485214853148541485514856148571485814859148601486114862148631486414865148661486714868148691487014871148721487314874148751487614877148781487914880148811488214883148841488514886148871488814889148901489114892148931489414895148961489714898148991490014901149021490314904149051490614907149081490914910149111491214913149141491514916149171491814919149201492114922149231492414925149261492714928149291493014931149321493314934149351493614937149381493914940149411494214943149441494514946149471494814949149501495114952149531495414955149561495714958149591496014961149621496314964149651496614967149681496914970149711497214973149741497514976149771497814979149801498114982149831498414985149861498714988149891499014991149921499314994149951499614997149981499915000150011500215003150041500515006150071500815009150101501115012150131501415015150161501715018150191502015021150221502315024150251502615027150281502915030150311503215033150341503515036150371503815039150401504115042150431504415045150461504715048150491505015051150521505315054150551505615057150581505915060150611506215063150641506515066150671506815069150701507115072150731507415075150761507715078150791508015081150821508315084150851508615087150881508915090150911509215093150941509515096150971509815099151001510115102151031510415105151061510715108151091511015111151121511315114151151511615117151181511915120151211512215123151241512515126151271512815129151301513115132151331513415135151361513715138151391514015141151421514315144151451514615147151481514915150151511515215153151541515515156151571515815159151601516115162151631516415165151661516715168151691517015171151721517315174151751517615177151781517915180151811518215183151841518515186151871518815189151901519115192151931519415195151961519715198151991520015201152021520315204152051520615207152081520915210152111521215213152141521515216152171521815219152201522115222152231522415225152261522715228152291523015231152321523315234152351523615237152381523915240152411524215243152441524515246152471524815249152501525115252152531525415255152561525715258152591526015261152621526315264152651526615267152681526915270152711527215273152741527515276152771527815279152801528115282152831528415285152861528715288152891529015291152921529315294152951529615297152981529915300153011530215303153041530515306153071530815309153101531115312153131531415315153161531715318153191532015321153221532315324153251532615327153281532915330153311533215333153341533515336153371533815339153401534115342153431534415345153461534715348153491535015351153521535315354153551535615357153581535915360153611536215363153641536515366153671536815369153701537115372153731537415375153761537715378153791538015381153821538315384153851538615387153881538915390153911539215393153941539515396153971539815399154001540115402154031540415405154061540715408154091541015411154121541315414154151541615417154181541915420154211542215423154241542515426154271542815429154301543115432154331543415435154361543715438154391544015441154421544315444154451544615447154481544915450154511545215453154541545515456154571545815459154601546115462154631546415465154661546715468154691547015471154721547315474154751547615477154781547915480154811548215483154841548515486154871548815489154901549115492154931549415495154961549715498154991550015501155021550315504155051550615507155081550915510155111551215513155141551515516155171551815519155201552115522155231552415525155261552715528155291553015531155321553315534155351553615537155381553915540155411554215543155441554515546155471554815549155501555115552155531555415555155561555715558155591556015561155621556315564155651556615567155681556915570155711557215573155741557515576155771557815579155801558115582155831558415585155861558715588155891559015591155921559315594155951559615597155981559915600156011560215603156041560515606156071560815609156101561115612156131561415615156161561715618156191562015621156221562315624156251562615627156281562915630156311563215633156341563515636156371563815639156401564115642156431564415645156461564715648156491565015651156521565315654156551565615657156581565915660156611566215663156641566515666156671566815669156701567115672156731567415675156761567715678156791568015681156821568315684156851568615687156881568915690156911569215693156941569515696156971569815699157001570115702157031570415705157061570715708157091571015711157121571315714157151571615717157181571915720157211572215723157241572515726157271572815729157301573115732157331573415735157361573715738157391574015741157421574315744157451574615747157481574915750157511575215753157541575515756157571575815759157601576115762157631576415765157661576715768157691577015771157721577315774157751577615777157781577915780157811578215783157841578515786157871578815789157901579115792157931579415795157961579715798157991580015801158021580315804158051580615807158081580915810158111581215813158141581515816158171581815819158201582115822158231582415825158261582715828158291583015831158321583315834158351583615837158381583915840158411584215843158441584515846158471584815849158501585115852158531585415855158561585715858158591586015861158621586315864158651586615867158681586915870158711587215873158741587515876158771587815879158801588115882158831588415885158861588715888158891589015891158921589315894158951589615897158981589915900159011590215903159041590515906159071590815909159101591115912159131591415915159161591715918159191592015921159221592315924159251592615927159281592915930159311593215933159341593515936159371593815939159401594115942159431594415945159461594715948159491595015951159521595315954159551595615957159581595915960159611596215963159641596515966159671596815969159701597115972159731597415975159761597715978159791598015981159821598315984159851598615987159881598915990159911599215993159941599515996159971599815999160001600116002160031600416005160061600716008160091601016011160121601316014160151601616017160181601916020160211602216023160241602516026160271602816029160301603116032160331603416035160361603716038160391604016041160421604316044160451604616047160481604916050160511605216053160541605516056160571605816059160601606116062160631606416065160661606716068160691607016071160721607316074160751607616077160781607916080160811608216083160841608516086160871608816089160901609116092160931609416095160961609716098160991610016101161021610316104161051610616107161081610916110161111611216113161141611516116161171611816119161201612116122161231612416125161261612716128161291613016131161321613316134161351613616137161381613916140161411614216143161441614516146161471614816149161501615116152161531615416155161561615716158161591616016161161621616316164161651616616167161681616916170161711617216173161741617516176161771617816179161801618116182161831618416185161861618716188161891619016191161921619316194161951619616197161981619916200162011620216203162041620516206162071620816209162101621116212162131621416215162161621716218162191622016221162221622316224162251622616227162281622916230162311623216233162341623516236162371623816239162401624116242162431624416245162461624716248162491625016251162521625316254162551625616257162581625916260162611626216263162641626516266162671626816269162701627116272162731627416275162761627716278162791628016281162821628316284162851628616287162881628916290162911629216293162941629516296162971629816299163001630116302163031630416305163061630716308163091631016311163121631316314163151631616317163181631916320163211632216323163241632516326163271632816329163301633116332163331633416335163361633716338163391634016341163421634316344163451634616347163481634916350163511635216353163541635516356163571635816359163601636116362163631636416365163661636716368163691637016371163721637316374163751637616377163781637916380163811638216383163841638516386163871638816389163901639116392163931639416395163961639716398163991640016401164021640316404164051640616407164081640916410164111641216413164141641516416164171641816419164201642116422164231642416425164261642716428164291643016431164321643316434164351643616437164381643916440164411644216443164441644516446164471644816449164501645116452164531645416455164561645716458164591646016461164621646316464164651646616467164681646916470164711647216473164741647516476164771647816479164801648116482164831648416485164861648716488164891649016491164921649316494164951649616497164981649916500165011650216503165041650516506165071650816509165101651116512165131651416515165161651716518165191652016521165221652316524165251652616527165281652916530165311653216533165341653516536165371653816539165401654116542165431654416545165461654716548165491655016551165521655316554165551655616557165581655916560165611656216563165641656516566165671656816569165701657116572165731657416575165761657716578165791658016581165821658316584165851658616587165881658916590165911659216593165941659516596165971659816599166001660116602166031660416605166061660716608166091661016611166121661316614166151661616617166181661916620166211662216623166241662516626166271662816629166301663116632166331663416635166361663716638166391664016641166421664316644166451664616647166481664916650166511665216653166541665516656166571665816659166601666116662166631666416665166661666716668166691667016671166721667316674166751667616677166781667916680166811668216683166841668516686166871668816689166901669116692166931669416695166961669716698166991670016701167021670316704167051670616707167081670916710167111671216713167141671516716167171671816719167201672116722167231672416725167261672716728167291673016731167321673316734167351673616737167381673916740167411674216743167441674516746167471674816749167501675116752167531675416755167561675716758167591676016761167621676316764167651676616767167681676916770167711677216773167741677516776167771677816779167801678116782167831678416785167861678716788167891679016791167921679316794167951679616797167981679916800168011680216803168041680516806168071680816809168101681116812168131681416815168161681716818168191682016821168221682316824168251682616827168281682916830168311683216833168341683516836168371683816839168401684116842168431684416845168461684716848168491685016851168521685316854168551685616857168581685916860168611686216863168641686516866168671686816869168701687116872168731687416875168761687716878168791688016881168821688316884168851688616887168881688916890168911689216893168941689516896168971689816899169001690116902169031690416905169061690716908169091691016911169121691316914169151691616917169181691916920169211692216923169241692516926169271692816929169301693116932169331693416935169361693716938169391694016941169421694316944169451694616947169481694916950169511695216953169541695516956169571695816959169601696116962169631696416965169661696716968169691697016971169721697316974169751697616977169781697916980169811698216983169841698516986169871698816989169901699116992169931699416995169961699716998169991700017001170021700317004170051700617007170081700917010170111701217013170141701517016170171701817019170201702117022170231702417025170261702717028170291703017031170321703317034170351703617037170381703917040170411704217043170441704517046170471704817049170501705117052170531705417055170561705717058170591706017061170621706317064170651706617067170681706917070170711707217073170741707517076170771707817079170801708117082170831708417085170861708717088170891709017091170921709317094170951709617097170981709917100171011710217103171041710517106171071710817109171101711117112171131711417115171161711717118171191712017121171221712317124171251712617127171281712917130171311713217133171341713517136171371713817139171401714117142171431714417145171461714717148171491715017151171521715317154171551715617157171581715917160171611716217163171641716517166171671716817169171701717117172171731717417175171761717717178171791718017181171821718317184171851718617187171881718917190171911719217193171941719517196171971719817199172001720117202172031720417205172061720717208172091721017211172121721317214172151721617217172181721917220172211722217223172241722517226172271722817229172301723117232172331723417235172361723717238172391724017241172421724317244172451724617247172481724917250172511725217253172541725517256172571725817259172601726117262172631726417265172661726717268172691727017271172721727317274172751727617277172781727917280172811728217283172841728517286172871728817289172901729117292172931729417295172961729717298172991730017301173021730317304173051730617307173081730917310173111731217313173141731517316173171731817319173201732117322173231732417325173261732717328173291733017331173321733317334173351733617337173381733917340173411734217343173441734517346173471734817349173501735117352173531735417355173561735717358173591736017361173621736317364173651736617367173681736917370173711737217373173741737517376173771737817379173801738117382173831738417385173861738717388173891739017391173921739317394173951739617397173981739917400174011740217403174041740517406174071740817409174101741117412174131741417415174161741717418174191742017421174221742317424174251742617427174281742917430174311743217433174341743517436174371743817439174401744117442174431744417445174461744717448174491745017451174521745317454174551745617457174581745917460174611746217463174641746517466174671746817469174701747117472174731747417475174761747717478174791748017481174821748317484174851748617487174881748917490174911749217493174941749517496174971749817499175001750117502175031750417505175061750717508175091751017511175121751317514175151751617517175181751917520175211752217523175241752517526175271752817529175301753117532175331753417535175361753717538175391754017541175421754317544175451754617547175481754917550175511755217553175541755517556175571755817559175601756117562175631756417565175661756717568175691757017571175721757317574175751757617577175781757917580175811758217583175841758517586175871758817589175901759117592175931759417595175961759717598175991760017601176021760317604176051760617607176081760917610176111761217613176141761517616176171761817619176201762117622176231762417625176261762717628176291763017631176321763317634176351763617637176381763917640176411764217643176441764517646176471764817649176501765117652176531765417655176561765717658176591766017661176621766317664176651766617667176681766917670176711767217673176741767517676176771767817679176801768117682176831768417685176861768717688176891769017691176921769317694176951769617697176981769917700177011770217703177041770517706177071770817709177101771117712177131771417715177161771717718177191772017721177221772317724177251772617727177281772917730177311773217733177341773517736177371773817739177401774117742177431774417745177461774717748177491775017751177521775317754177551775617757177581775917760177611776217763177641776517766177671776817769177701777117772177731777417775177761777717778177791778017781177821778317784177851778617787177881778917790177911779217793177941779517796177971779817799178001780117802178031780417805178061780717808178091781017811178121781317814178151781617817178181781917820178211782217823178241782517826178271782817829178301783117832178331783417835178361783717838178391784017841178421784317844178451784617847178481784917850178511785217853178541785517856178571785817859178601786117862178631786417865178661786717868178691787017871178721787317874178751787617877178781787917880178811788217883178841788517886178871788817889178901789117892178931789417895178961789717898178991790017901179021790317904179051790617907179081790917910179111791217913179141791517916179171791817919179201792117922179231792417925179261792717928179291793017931179321793317934179351793617937179381793917940179411794217943179441794517946179471794817949179501795117952179531795417955179561795717958179591796017961179621796317964179651796617967179681796917970179711797217973179741797517976179771797817979179801798117982179831798417985179861798717988179891799017991179921799317994179951799617997179981799918000180011800218003180041800518006180071800818009180101801118012180131801418015180161801718018180191802018021180221802318024180251802618027180281802918030180311803218033180341803518036180371803818039180401804118042180431804418045180461804718048180491805018051180521805318054180551805618057180581805918060180611806218063180641806518066180671806818069180701807118072180731807418075180761807718078180791808018081180821808318084180851808618087180881808918090180911809218093180941809518096180971809818099181001810118102181031810418105181061810718108181091811018111181121811318114181151811618117181181811918120181211812218123181241812518126181271812818129181301813118132181331813418135181361813718138181391814018141181421814318144181451814618147181481814918150181511815218153181541815518156181571815818159181601816118162181631816418165181661816718168181691817018171181721817318174181751817618177181781817918180181811818218183181841818518186181871818818189181901819118192181931819418195181961819718198181991820018201182021820318204182051820618207182081820918210182111821218213182141821518216182171821818219182201822118222182231822418225182261822718228182291823018231182321823318234182351823618237182381823918240182411824218243182441824518246182471824818249182501825118252182531825418255182561825718258182591826018261182621826318264182651826618267182681826918270182711827218273182741827518276182771827818279182801828118282182831828418285182861828718288182891829018291182921829318294182951829618297182981829918300183011830218303183041830518306183071830818309183101831118312183131831418315183161831718318183191832018321183221832318324183251832618327183281832918330183311833218333183341833518336183371833818339183401834118342183431834418345183461834718348183491835018351183521835318354183551835618357183581835918360183611836218363183641836518366183671836818369183701837118372183731837418375183761837718378183791838018381183821838318384183851838618387183881838918390183911839218393183941839518396183971839818399184001840118402184031840418405184061840718408184091841018411184121841318414184151841618417184181841918420184211842218423184241842518426184271842818429184301843118432184331843418435184361843718438184391844018441184421844318444184451844618447184481844918450184511845218453184541845518456184571845818459184601846118462184631846418465184661846718468184691847018471184721847318474184751847618477184781847918480184811848218483184841848518486184871848818489184901849118492184931849418495184961849718498184991850018501185021850318504185051850618507185081850918510185111851218513185141851518516185171851818519185201852118522185231852418525185261852718528185291853018531185321853318534185351853618537185381853918540185411854218543185441854518546185471854818549185501855118552185531855418555185561855718558185591856018561185621856318564185651856618567185681856918570185711857218573185741857518576185771857818579185801858118582185831858418585185861858718588185891859018591185921859318594185951859618597185981859918600186011860218603186041860518606186071860818609186101861118612186131861418615186161861718618186191862018621186221862318624186251862618627186281862918630186311863218633186341863518636186371863818639186401864118642186431864418645186461864718648186491865018651186521865318654186551865618657186581865918660186611866218663186641866518666186671866818669186701867118672186731867418675186761867718678186791868018681186821868318684186851868618687186881868918690186911869218693186941869518696186971869818699187001870118702187031870418705187061870718708187091871018711187121871318714187151871618717187181871918720187211872218723187241872518726187271872818729187301873118732187331873418735187361873718738187391874018741187421874318744187451874618747187481874918750187511875218753187541875518756187571875818759187601876118762187631876418765187661876718768187691877018771187721877318774187751877618777187781877918780187811878218783187841878518786187871878818789187901879118792187931879418795187961879718798187991880018801188021880318804188051880618807188081880918810188111881218813188141881518816188171881818819188201882118822188231882418825188261882718828188291883018831188321883318834188351883618837188381883918840188411884218843188441884518846188471884818849188501885118852188531885418855188561885718858188591886018861188621886318864188651886618867188681886918870188711887218873188741887518876188771887818879188801888118882188831888418885188861888718888188891889018891188921889318894188951889618897188981889918900189011890218903189041890518906189071890818909189101891118912189131891418915189161891718918189191892018921189221892318924189251892618927189281892918930189311893218933189341893518936189371893818939189401894118942189431894418945189461894718948189491895018951189521895318954189551895618957189581895918960189611896218963189641896518966189671896818969189701897118972189731897418975189761897718978189791898018981189821898318984189851898618987189881898918990189911899218993189941899518996189971899818999190001900119002190031900419005190061900719008190091901019011190121901319014190151901619017190181901919020190211902219023190241902519026190271902819029190301903119032190331903419035190361903719038190391904019041190421904319044190451904619047190481904919050190511905219053190541905519056190571905819059190601906119062190631906419065190661906719068190691907019071190721907319074190751907619077190781907919080190811908219083190841908519086190871908819089190901909119092190931909419095190961909719098190991910019101191021910319104191051910619107191081910919110191111911219113191141911519116191171911819119191201912119122191231912419125191261912719128191291913019131191321913319134191351913619137191381913919140191411914219143191441914519146191471914819149191501915119152191531915419155191561915719158191591916019161191621916319164191651916619167191681916919170191711917219173191741917519176191771917819179191801918119182191831918419185191861918719188191891919019191191921919319194191951919619197191981919919200192011920219203192041920519206192071920819209192101921119212192131921419215192161921719218192191922019221192221922319224192251922619227192281922919230192311923219233192341923519236192371923819239192401924119242192431924419245192461924719248192491925019251192521925319254192551925619257192581925919260192611926219263192641926519266192671926819269192701927119272192731927419275192761927719278192791928019281192821928319284192851928619287192881928919290192911929219293192941929519296192971929819299193001930119302193031930419305193061930719308193091931019311193121931319314193151931619317193181931919320193211932219323193241932519326193271932819329193301933119332193331933419335193361933719338193391934019341193421934319344193451934619347193481934919350193511935219353193541935519356193571935819359193601936119362193631936419365193661936719368193691937019371193721937319374193751937619377193781937919380193811938219383193841938519386193871938819389193901939119392193931939419395193961939719398193991940019401194021940319404194051940619407194081940919410194111941219413194141941519416194171941819419194201942119422194231942419425194261942719428194291943019431194321943319434194351943619437194381943919440194411944219443194441944519446194471944819449194501945119452194531945419455194561945719458194591946019461194621946319464194651946619467194681946919470194711947219473194741947519476194771947819479194801948119482194831948419485194861948719488194891949019491194921949319494194951949619497194981949919500195011950219503195041950519506195071950819509195101951119512195131951419515195161951719518195191952019521195221952319524195251952619527195281952919530195311953219533195341953519536195371953819539195401954119542195431954419545195461954719548195491955019551195521955319554195551955619557195581955919560195611956219563195641956519566195671956819569195701957119572195731957419575195761957719578195791958019581195821958319584195851958619587195881958919590195911959219593195941959519596195971959819599196001960119602196031960419605196061960719608196091961019611196121961319614196151961619617196181961919620196211962219623196241962519626196271962819629196301963119632196331963419635196361963719638196391964019641196421964319644196451964619647196481964919650196511965219653196541965519656196571965819659196601966119662196631966419665196661966719668196691967019671196721967319674196751967619677196781967919680196811968219683196841968519686196871968819689196901969119692196931969419695196961969719698196991970019701197021970319704197051970619707197081970919710197111971219713197141971519716197171971819719197201972119722197231972419725197261972719728197291973019731197321973319734197351973619737197381973919740 |
- \input texinfo @c -*- coding: utf-8 -*-
- @c %**start of header
- @setfilename ../../info/org.info
- @settitle The Org Manual
- @include docstyle.texi
- @include org-version.inc
- @c Version and Contact Info
- @set MAINTAINERSITE @uref{https://orgmode.org,maintainers web page}
- @set AUTHOR Carsten Dominik
- @set MAINTAINER Carsten Dominik
- @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
- @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
- @c %**end of header
- @finalout
- @c -----------------------------------------------------------------------------
- @c Macro definitions for commands and keys
- @c =======================================
- @c The behavior of the key/command macros will depend on the flag cmdnames
- @c When set, commands names are shown. When clear, they are not shown.
- @set cmdnames
- @c Below we define the following macros for Org key tables:
- @c orgkey{key} A key item
- @c orgcmd{key,cmd} Key with command name
- @c xorgcmd{key,cmd} Key with command name as @itemx
- @c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
- @c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
- @c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
- @c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but
- @c different functions, so format as @itemx
- @c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short"
- @c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx
- @c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands
- @c a key but no command
- @c Inserts: @item key
- @macro orgkey{key}
- @kindex \key\
- @item @kbd{\key\}
- @end macro
- @macro xorgkey{key}
- @kindex \key\
- @itemx @kbd{\key\}
- @end macro
- @c one key with a command
- @c Inserts: @item KEY COMMAND
- @macro orgcmd{key,command}
- @ifset cmdnames
- @kindex \key\
- @findex \command\
- @iftex
- @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
- @end iftex
- @ifnottex
- @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @kindex \key\
- @item @kbd{\key\}
- @end ifclear
- @end macro
- @c One key with one command, formatted using @itemx
- @c Inserts: @itemx KEY COMMAND
- @macro xorgcmd{key,command}
- @ifset cmdnames
- @kindex \key\
- @findex \command\
- @iftex
- @itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
- @end iftex
- @ifnottex
- @itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @kindex \key\
- @itemx @kbd{\key\}
- @end ifclear
- @end macro
- @c one key with a command, bit do not index the key
- @c Inserts: @item KEY COMMAND
- @macro orgcmdnki{key,command}
- @ifset cmdnames
- @findex \command\
- @iftex
- @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
- @end iftex
- @ifnottex
- @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @item @kbd{\key\}
- @end ifclear
- @end macro
- @c one key with a command, and special text to replace key in item
- @c Inserts: @item TEXT COMMAND
- @macro orgcmdtkc{text,key,command}
- @ifset cmdnames
- @kindex \key\
- @findex \command\
- @iftex
- @item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
- @end iftex
- @ifnottex
- @item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @kindex \key\
- @item @kbd{\text\}
- @end ifclear
- @end macro
- @c two keys with one command
- @c Inserts: @item KEY1 or KEY2 COMMAND
- @macro orgcmdkkc{key1,key2,command}
- @ifset cmdnames
- @kindex \key1\
- @kindex \key2\
- @findex \command\
- @iftex
- @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
- @end iftex
- @ifnottex
- @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @kindex \key1\
- @kindex \key2\
- @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
- @end ifclear
- @end macro
- @c Two keys with one command name, but different functions, so format as
- @c @itemx
- @c Inserts: @item KEY1
- @c @itemx KEY2 COMMAND
- @macro orgcmdkxkc{key1,key2,command}
- @ifset cmdnames
- @kindex \key1\
- @kindex \key2\
- @findex \command\
- @iftex
- @item @kbd{\key1\}
- @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
- @end iftex
- @ifnottex
- @item @kbd{\key1\}
- @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @kindex \key1\
- @kindex \key2\
- @item @kbd{\key1\}
- @itemx @kbd{\key2\}
- @end ifclear
- @end macro
- @c Same as previous, but use "or short"
- @c Inserts: @item KEY1 or short KEY2 COMMAND
- @macro orgcmdkskc{key1,key2,command}
- @ifset cmdnames
- @kindex \key1\
- @kindex \key2\
- @findex \command\
- @iftex
- @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
- @end iftex
- @ifnottex
- @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @kindex \key1\
- @kindex \key2\
- @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
- @end ifclear
- @end macro
- @c Same as previous, but use @itemx
- @c Inserts: @itemx KEY1 or short KEY2 COMMAND
- @macro xorgcmdkskc{key1,key2,command}
- @ifset cmdnames
- @kindex \key1\
- @kindex \key2\
- @findex \command\
- @iftex
- @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
- @end iftex
- @ifnottex
- @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @kindex \key1\
- @kindex \key2\
- @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
- @end ifclear
- @end macro
- @c two keys with two commands
- @c Inserts: @item KEY1 COMMAND1
- @c @itemx KEY2 COMMAND2
- @macro orgcmdkkcc{key1,key2,command1,command2}
- @ifset cmdnames
- @kindex \key1\
- @kindex \key2\
- @findex \command1\
- @findex \command2\
- @iftex
- @item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
- @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
- @end iftex
- @ifnottex
- @item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
- @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
- @end ifnottex
- @end ifset
- @ifclear cmdnames
- @kindex \key1\
- @kindex \key2\
- @item @kbd{\key1\}
- @itemx @kbd{\key2\}
- @end ifclear
- @end macro
- @c -----------------------------------------------------------------------------
- @iftex
- @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
- @end iftex
- @c Subheadings inside a table.
- @macro tsubheading{text}
- @ifinfo
- @subsubheading \text\
- @end ifinfo
- @ifnotinfo
- @item @b{\text\}
- @end ifnotinfo
- @end macro
- @copying
- This manual is for Org version @value{VERSION}.
- Copyright @copyright{} 2004--2018 Free Software Foundation, Inc.
- @quotation
- 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.''
- @end quotation
- @end copying
- @dircategory Emacs editing modes
- @direntry
- * Org Mode: (org). Outline-based notes management and organizer
- @end direntry
- @titlepage
- @title The Org Manual
- @subtitle Release @value{VERSION}
- @author by Carsten Dominik
- with contributions by Bastien Guerry, Nicolas Goaziou, Eric Schulte,
- Jambunathan K, Dan Davison, Thomas Dye, David O'Toole, and Philip Rooke.
- @c The following two commands start the copyright page.
- @page
- @vskip 0pt plus 1filll
- @insertcopying
- @end titlepage
- @c Output the short table of contents at the beginning.
- @shortcontents
- @c Output the table of contents at the beginning.
- @contents
- @ifnottex
- @node Top, Introduction, (dir), (dir)
- @top Org Mode Manual
- @insertcopying
- @end ifnottex
- @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:: 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
- * GNU Free Documentation License:: The license for this documentation.
- * Main Index:: An index of 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
- @detailmenu
- --- The Detailed Node Listing ---
- Introduction
- * Summary:: Brief summary of what Org does
- * Installation:: Installing Org
- * Activation:: How to activate Org for certain buffers
- * Feedback:: Bug reports, ideas, patches etc.
- * Conventions:: Typesetting conventions in the manual
- Document structure
- * Outlines:: Org 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
- * Footnotes:: How footnotes are defined in Org's syntax
- * Org syntax:: Formal description of Org's syntax
- Visibility cycling
- * Global and local cycling:: Cycling through various visibility states
- * Initial visibility:: Setting the initial visibility state
- * Catching invisible edits:: Preventing mistakes when editing invisible parts
- Tables
- * Built-in table editor:: Simple tables
- * Column width and alignment:: Overrule the automatic settings
- * Column groups:: Grouping to trigger vertical lines
- * Orgtbl mode:: The table editor as minor mode
- * The spreadsheet:: The table editor has spreadsheet capabilities
- * Org-Plot:: Plotting from org tables
- The spreadsheet
- * References:: How to refer to another field or range
- * Formula syntax for Calc:: Using Calc to compute stuff
- * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
- * Durations and time values:: How to compute durations and time values
- * Field and range formulas:: Formula 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
- * Updating the table:: Recomputing all dependent fields
- * Advanced features:: Field and column names, parameters and automatic recalc
- Hyperlinks
- * Link format:: How links in Org are formatted
- * Internal links:: Links to other places in the current file
- * External links:: URL-like links to the world
- * Handling links:: Creating, inserting and following
- * 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
- Internal links
- * Radio targets:: Make targets trigger links in plain text
- TODO items
- * TODO basics:: Marking and displaying TODO entries
- * TODO extensions:: Workflow 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
- Extended use of TODO keywords
- * 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 a 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 the outline
- * Setting tags:: How to assign tags to a headline
- * Tag hierarchy:: Create a hierarchy of tags
- * 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 the 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 which 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
- * Timers:: Notes with a running timer
- Creating timestamps
- * The date/time prompt:: How Org mode helps you entering date and time
- * 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
- 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 projects
- 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
- Protocols for external access
- * @code{store-link} protocol:: Store a link, push URL to kill-ring.
- * @code{capture} protocol:: Fill a buffer with external information.
- * @code{open-source} protocol:: Edit published contents.
- 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
- * Agenda column view:: Using column view for collected entries
- The 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
- * Search view:: Find entries by searching for text
- * Stuck projects:: Find projects you need to review
- Presentation and sorting
- * Categories:: Not all tasks are equal
- * Time-of-day specifications:: How the agenda knows the time
- * Sorting agenda items:: The order of things
- * Filtering/limiting agenda items:: Dynamically narrow the agenda
- Custom agenda views
- * Storing searches:: Type once, use often
- * Block agenda:: All the stuff you need in a single buffer
- * Setting options:: Changing the rules
- Markup for rich export
- * Paragraphs:: The basic unit of text
- * Emphasis and monospace:: Bold, italic, etc.
- * Horizontal rules:: Make a line
- * Images and tables:: Images, tables and caption mechanism
- * Literal examples:: Source code examples with special formatting
- * Special symbols:: Greek letters and other symbols
- * Subscripts and superscripts:: Simple syntax for raising/lowering text
- * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
- Embedded @LaTeX{}
- * @LaTeX{} fragments:: Complex formulas made easy
- * Previewing @LaTeX{} fragments:: What will this snippet look like?
- * CDLaTeX mode:: Speed up entering of formulas
- Exporting
- * The export dispatcher:: The main interface
- * Export settings:: Common export settings
- * Table of contents:: The if and where of the table of contents
- * Include files:: Include additional files into a document
- * Macro replacement:: Use macros to create templates
- * Comment lines:: What will not be exported
- * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
- * Beamer export:: Exporting as a Beamer presentation
- * HTML export:: Exporting to HTML
- * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
- * Markdown export:: Exporting to Markdown
- * OpenDocument Text export:: Exporting to OpenDocument Text
- * Org export:: Exporting to Org
- * Texinfo export:: Exporting to Texinfo
- * iCalendar export:: Exporting to iCalendar
- * Other built-in back-ends:: Exporting to a man page
- * Advanced configuration:: Fine-tuning the export output
- * Export in foreign buffers:: Author tables and lists in Org syntax
- Beamer export
- * Beamer export commands:: For creating Beamer documents.
- * Beamer specific export settings:: For customizing Beamer export.
- * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
- * Beamer specific syntax:: For using in Org documents.
- * Editing support:: For using helper functions.
- * A Beamer example:: A complete presentation.
- HTML export
- * HTML Export commands:: Invoking HTML export
- * HTML Specific export settings:: Settings for HTML export
- * HTML doctypes:: Exporting various (X)HTML flavors
- * HTML preamble and postamble:: Inserting preamble and postamble
- * Quoting HTML tags:: Using direct HTML in Org files
- * Links in HTML export:: Interpreting and formatting links
- * Tables in HTML export:: Formatting and modifying tables
- * Images in HTML export:: Inserting figures with HTML output
- * Math formatting in HTML export:: Handling math equations
- * Text areas in HTML export:: Showing an alternate approach, an example
- * CSS support:: Styling HTML output
- * JavaScript support:: Folding scripting in the web browser
- @LaTeX{} export
- * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
- * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
- * @LaTeX{} header and sectioning:: For file structure.
- * Quoting @LaTeX{} code:: Directly in the Org document.
- * Tables in @LaTeX{} export:: Attributes specific to tables.
- * Images in @LaTeX{} export:: Attributes specific to images.
- * Plain lists in @LaTeX{} export:: Attributes specific to lists.
- * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
- * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
- * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
- * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
- OpenDocument Text export
- * Pre-requisites for ODT export:: Required packages.
- * ODT export commands:: Invoking export.
- * ODT specific export settings:: Configuration options.
- * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
- * Applying custom styles:: Styling the output.
- * Links in ODT export:: Handling and formatting links.
- * Tables in ODT export:: Org table conversions.
- * Images in ODT export:: Inserting images.
- * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
- * Labels and captions in ODT export:: Rendering objects.
- * Literal examples in ODT export:: For source code and example blocks.
- * Advanced topics in ODT export:: For power users.
- Math formatting in ODT export
- * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
- * Working with MathML or OpenDocument formula files:: Embedding in native format.
- Advanced topics in ODT export
- * Configuring a document converter:: Registering a document converter.
- * Working with OpenDocument style files:: Exploring internals.
- * Creating one-off styles:: Customizing styles, highlighting.
- * Customizing tables in ODT export:: Defining table templates.
- * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
- Texinfo export
- * Texinfo export commands:: Invoking commands.
- * Texinfo specific export settings:: Setting the environment.
- * Texinfo file header:: Generating the header.
- * Texinfo title and copyright page:: Creating preamble pages.
- * Info directory file:: Installing a manual in Info file hierarchy.
- * Headings and sectioning structure:: Building document structure.
- * Indices:: Creating indices.
- * Quoting Texinfo code:: Incorporating literal Texinfo code.
- * Plain lists in Texinfo export:: List attributes.
- * Tables in Texinfo export:: Table attributes.
- * Images in Texinfo export:: Image attributes.
- * Special blocks in Texinfo export:: Special block attributes.
- * A Texinfo example:: Processing Org to Texinfo.
- 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?
- * Sitemap:: 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 of evaluation in the Org mode buffer
- * Library of Babel:: Use and contribute to a library of useful code blocks
- * Languages:: List of 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
- 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 globally, language-specific
- * Language-specific header arguments:: Set in the Org file's headers
- * Header arguments in Org mode properties:: Set in the Org file
- * Language-specific mode properties::
- * Code block specific header arguments:: The most commonly used method
- * Arguments in function calls:: The most specific level, takes highest priority
- Specific header arguments
- * var:: Pass arguments to @samp{src} code blocks
- * results:: Specify results type; how to collect
- * file:: Specify a path for output file
- * file-desc:: Specify a description for file results
- * file-ext:: Specify an extension for file output
- * output-dir:: Specify a directory for output file
- * dir:: Specify the default directory for code block execution
- * exports:: Specify exporting code, results, both, none
- * tangle:: Toggle tangling; or specify file name
- * mkdirp:: Toggle for parent directory creation for target files during tangling
- * comments:: Toggle insertion of comments in tangled code files
- * padline:: Control insertion of padding lines in tangled code files
- * no-expand:: Turn off variable assignment and noweb expansion during tangling
- * session:: Preserve the state of code evaluation
- * noweb:: Toggle expansion of noweb references
- * noweb-ref:: Specify block's noweb reference resolution target
- * noweb-sep:: String 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 tangled files executable
- * tangle-mode:: Set permission of tangled files
- * eval:: Limit evaluation of specific code blocks
- * wrap:: Mark source block evaluation results
- * post:: Post processing of results of code block evaluation
- * prologue:: Text to prepend to body of code block
- * epilogue:: Text to append to body of code block
- Miscellaneous
- * Completion:: M-TAB guesses completions
- * Structure templates:: Quick insertion of structural elements
- * Speed keys:: Electric commands at the beginning of a headline
- * Code evaluation security:: Org mode files evaluate inline code
- * Customization:: Adapting Org to changing tastes
- * 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:: With other Emacs packages
- * org-crypt:: Encrypting Org files
- Interaction with other packages
- * 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
- * Adding export back-ends:: How to write new export back-ends
- * 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
- * Speeding up your agendas:: Tips on how to speed up your agendas
- * Extracting agenda information:: Post-processing of agenda information
- * Using the property API:: Writing programs that use entry properties
- * Using the mapping API:: Mapping over all or selected entries
- Tables and lists in arbitrary syntax
- * Radio tables:: Sending and receiving radio tables
- * A @LaTeX{} example:: Step by step, almost a tutorial
- * Translator functions:: Copy and modify
- MobileOrg
- * Setting up the staging area:: For the mobile device
- * Pushing to MobileOrg:: Uploading Org files and agendas
- * Pulling from MobileOrg:: Integrating captured and flagged items
- @end detailmenu
- @end menu
- @node Introduction
- @chapter Introduction
- @cindex introduction
- @menu
- * Summary:: Brief summary of what Org does
- * Installation:: Installing Org
- * Activation:: How to activate Org for certain buffers
- * Feedback:: Bug reports, ideas, patches etc.
- * Conventions:: Typesetting conventions in the manual
- @end menu
- @node Summary
- @section Summary
- @cindex summary
- Org is a mode for keeping notes, maintaining TODO lists, and project planning
- with a fast and effective plain-text system. It also is an authoring system
- with unique support for literate programming and reproducible research.
- 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. Plain text URL-like links connect to websites,
- emails, Usenet messages, BBDB entries, and any files related to the projects.
- Org develops organizational tasks around notes files that contain lists or
- information about projects as plain text. Project planning and task
- management makes use of metadata which is part of an outline node. Based on
- this data, specific entries can be extracted in queries and create dynamic
- @i{agenda views} that also integrate the Emacs calendar and diary. Org can
- be used to implement many different project planning schemes, such as David
- Allen's GTD system.
- Org files can serve as a single source authoring system with export to many
- different formats such as HTML, @LaTeX{}, Open Document, and Markdown. New
- export backends can be derived from existing ones, or defined from scratch.
- Org files can include source code blocks, which makes Org uniquely suited for
- authoring technical documents with code examples. Org source code blocks are
- fully functional; they can be evaluated in place and their results can be
- captured in the file. This makes it possible to create a single file
- reproducible research compendium.
- 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 needed. Org is a toolbox.
- Many users actually run only a (very personal) fraction of Org's capabilities, and
- know that there is more whenever they need it.
- All of this is achieved with strictly plain text files, the most portable and
- future-proof file format. Org runs in Emacs. Emacs is one of the most
- widely ported programs, so that Org mode is available on every major
- platform.
- @cindex FAQ
- There is a website for Org which provides links to the newest
- version of Org, as well as additional information, frequently asked
- questions (FAQ), links to tutorials, etc. This page is located at
- @uref{https://orgmode.org}.
- @cindex print edition
- An earlier version (7.3) of this manual is available as a
- @uref{http://www.network-theory.co.uk/org/manual/, paperback book from
- Network Theory Ltd.}
- @page
- @node Installation
- @section Installation
- @cindex installation
- Org is part of recent distributions of GNU Emacs, so you normally don't need
- to install it. If, for one reason or another, you want to install Org on top
- of this pre-packaged version, there are three ways to do it:
- @itemize @bullet
- @item By using Emacs package system.
- @item By downloading Org as an archive.
- @item By using Org's git repository.
- @end itemize
- We @b{strongly recommend} to stick to a single installation method.
- @subsubheading Using Emacs packaging system
- Recent Emacs distributions include a packaging system which lets you install
- Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
- @noindent @b{Important}: you need to do this in a session where no @code{.org} file has
- been visited, i.e., where no Org built-in function have been loaded.
- Otherwise autoload Org functions will mess up the installation.
- Then, to make sure your Org configuration is taken into account, initialize
- the package system with @code{(package-initialize)} in your Emacs init file
- before setting any Org option. If you want to use Org's package repository,
- check out the @uref{https://orgmode.org/elpa.html, Org ELPA page}.
- @subsubheading Downloading Org as an archive
- You can download Org latest release from @uref{https://orgmode.org/, Org's
- website}. In this case, make sure you set the load-path correctly in your
- Emacs init file:
- @lisp
- (add-to-list 'load-path "~/path/to/orgdir/lisp")
- @end lisp
- The downloaded archive contains contributed libraries that are not included
- in Emacs. If you want to use them, add the @file{contrib} directory to your
- load-path:
- @lisp
- (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
- @end lisp
- Optionally, you can compile the files and/or install them in your system.
- Run @code{make help} to list compilation and installation options.
- @subsubheading Using Org's git repository
- You can clone Org's repository and install Org like this:
- @example
- $ cd ~/src/
- $ git clone https://code.orgmode.org/bzg/org-mode.git
- $ make autoloads
- @end example
- Note that in this case, @code{make autoloads} is mandatory: it defines Org's
- version in @file{org-version.el} and Org's autoloads in
- @file{org-loaddefs.el}.
- Remember to add the correct load-path as described in the method above.
- You can also compile with @code{make}, generate the documentation with
- @code{make doc}, create a local configuration with @code{make config} and
- install Org with @code{make install}. Please run @code{make help} to get
- the list of compilation/installation options.
- For more detailed explanations on Org's build system, please check the Org
- Build System page on @uref{https://orgmode.org/worg/dev/org-build-system.html,
- Worg}.
- @node Activation
- @section Activation
- @cindex activation
- @cindex autoload
- @cindex ELPA
- @cindex global key bindings
- @cindex key bindings, global
- @findex org-agenda
- @findex org-capture
- @findex org-store-link
- @findex org-iswitchb
- Org mode buffers need font-lock to be turned on: this is the default in
- Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
- with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
- There are compatibility issues between Org mode and some other Elisp
- packages, please take the time to check the list (@pxref{Conflicts}).
- The four Org commands @command{org-store-link}, @command{org-capture},
- @command{org-agenda}, and @command{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.
- @lisp
- (global-set-key "\C-cl" 'org-store-link)
- (global-set-key "\C-ca" 'org-agenda)
- (global-set-key "\C-cc" 'org-capture)
- (global-set-key "\C-cb" 'org-iswitchb)
- @end lisp
- @cindex Org mode, turning on
- Files with the @file{.org} extension use Org mode by default. To turn on Org
- mode in a file that does not have the extension @file{.org}, make the first
- line of a file look like this:
- @example
- MY PROJECTS -*- mode: org; -*-
- @end example
- @vindex org-insert-mode-line-in-empty-file
- @noindent which will select Org mode for this buffer no matter what
- the file's name is. See also the variable
- @code{org-insert-mode-line-in-empty-file}.
- Many commands in Org work on the region if the region is @i{active}. To make
- use of this, you need to have @code{transient-mark-mode} turned on, which is
- the default. If you do not like @code{transient-mark-mode}, you can create
- an active region by using the mouse to select a region, or pressing
- @kbd{C-@key{SPC}} twice before moving the cursor.
- @node Feedback
- @section Feedback
- @cindex feedback
- @cindex bug reports
- @cindex maintainer
- @cindex author
- If you find problems with Org, or if you have questions, remarks, or ideas
- about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
- You can subscribe to the list
- @uref{https://lists.gnu.org/mailman/listinfo/emacs-orgmode, on this web page}.
- If you are not a member of the mailing list, your mail will be passed to the
- list after a moderator has approved it@footnote{Please consider subscribing
- to the mailing list, in order to minimize the work the mailing list
- moderators have to do.}.
- 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 (@kbd{M-x emacs-version @key{RET}}) and Org
- (@kbd{M-x org-version RET}), as well as the Org related setup in the Emacs
- init file. The easiest way to do this is to use the command
- @example
- @kbd{M-x org-submit-bug-report RET}
- @end example
- @noindent 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.
- @example
- $ emacs -Q -l /path/to/minimal-org.el
- @end example
- However if you are using Org mode as distributed with Emacs, a minimal setup
- is not necessary. In that case it is sufficient to start Emacs as
- @code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
- shown below.
- @lisp
- ;;; 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 "/path/to/org-mode/lisp")
- (add-to-list 'load-path "/path/to/org-mode/contrib/lisp" t)
- @end lisp
- If an error occurs, a backtrace can be very useful (see below on how to
- create one). Often a small example file helps, along with clear information
- about:
- @enumerate
- @item What exactly did you do?
- @item What did you expect to happen?
- @item What happened instead?
- @end enumerate
- @noindent Thank you for helping to improve this program.
- @subsubheading How to create a useful backtrace
- @cindex backtrace of an error
- 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 @emph{backtrace}.
- This is information from the built-in debugger about where and how the
- error occurred. Here is how to produce a useful backtrace:
- @enumerate
- @item
- 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
- @example
- @kbd{C-u M-x org-reload RET}
- @end example
- @noindent
- or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
- menu.
- @item
- Go to the @code{Options} menu and select @code{Enter Debugger on Error}.
- @item
- Do whatever you have to do to hit the error. Don't forget to
- document the steps you take.
- @item
- When you hit the error, a @file{*Backtrace*} buffer will appear on the
- screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
- attach it to your bug report.
- @end enumerate
- @node Conventions
- @section Typesetting conventions used in this manual
- @subsubheading TODO keywords, tags, properties, etc.
- Org mainly uses three types of keywords: TODO keywords, tags and property
- names. In this manual we use the following conventions:
- @table @code
- @item TODO
- @itemx WAITING
- TODO keywords are written with all capitals, even if they are
- user-defined.
- @item boss
- @itemx ARCHIVE
- User-defined tags are written in lowercase; built-in tags with special
- meaning are written with all capitals.
- @item Release
- @itemx PRIORITY
- User-defined properties are capitalized; built-in properties with
- special meaning are written with all capitals.
- @end table
- Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
- and @i{environment keywords} (like @code{#+BEGIN_EXPORT html} to start
- a @code{HTML} environment). They are written in uppercase in the manual to
- enhance its readability, but you can use lowercase in your Org file.
- @subsubheading Key bindings and commands
- @kindex C-c a
- @findex org-agenda
- @kindex C-c c
- @findex org-capture
- The manual suggests a few global key bindings, in particular @kbd{C-c a} for
- @code{org-agenda} and @kbd{C-c c} for @code{org-capture}. These are only
- suggestions, but the rest of the manual assumes that these key bindings are in
- place in order to list commands by key access.
- Also, the manual lists both the keys and the corresponding commands for
- accessing a functionality. Org mode often uses the same key for different
- functions, depending on context. The command that is bound to such keys has
- a generic name, like @code{org-metaright}. In the manual we will, wherever
- possible, give the function that is internally called by the generic command.
- For example, in the chapter on document structure, @kbd{M-@key{right}} will
- be listed to call @code{org-do-demote}, while in the chapter on tables, it
- will be listed to call @code{org-table-move-column-right}. If you prefer,
- you can compile the manual without the command names by unsetting the flag
- @code{cmdnames} in @file{org.texi}.
- @node Document structure
- @chapter Document structure
- @cindex document structure
- @cindex structure of document
- Org is based on Outline mode and provides flexible commands to
- edit the structure of the document.
- @menu
- * Outlines:: Org 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
- * Footnotes:: How footnotes are defined in Org's syntax
- * Org syntax:: Formal description of Org's syntax
- @end menu
- @node Outlines
- @section Outlines
- @cindex outlines
- @cindex Outline mode
- Org is implemented on top of Outline mode. Outlines allow a
- document to be organized in a hierarchical structure, which (at least
- for me) is the best representation of notes and thoughts. An overview
- of this structure is achieved by folding (hiding) large parts of the
- document to show only the general document structure and the parts
- currently being worked on. Org greatly simplifies the use of
- outlines by compressing the entire show/hide functionality into a single
- command, @command{org-cycle}, which is bound to the @key{TAB} key.
- @node Headlines
- @section Headlines
- @cindex headlines
- @cindex outline tree
- @vindex org-special-ctrl-a/e
- @vindex org-special-ctrl-k
- @vindex org-ctrl-k-protect-subtree
- Headlines define the structure of an outline tree. The headlines in Org
- start with one or more stars, on the left margin@footnote{See the variables
- @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
- @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
- @kbd{C-e}, and @kbd{C-k} in headlines.} @footnote{Clocking only works with
- headings indented less than 30 stars.}. For example:
- @example
- * Top level headline
- ** Second level
- *** 3rd level
- some text
- *** 3rd level
- more text
- * Another top level headline
- @end example
- @vindex org-footnote-section
- @noindent Note that a headline named after @code{org-footnote-section},
- which defaults to @samp{Footnotes}, is considered as special. A subtree with
- this headline will be silently ignored by exporting functions.
- Some people find the many stars too noisy and would prefer an
- outline that has whitespace followed by a single star as headline
- starters. @ref{Clean view}, describes a setup to realize this.
- @vindex org-cycle-separator-lines
- An empty line after the end of a subtree is considered part of it and
- will be hidden when the subtree is folded. However, if you leave at
- least two empty lines, one empty line will remain visible after folding
- the subtree, in order to structure the collapsed view. See the
- variable @code{org-cycle-separator-lines} to modify this behavior.
- @node Visibility cycling
- @section Visibility cycling
- @cindex cycling, visibility
- @cindex visibility cycling
- @cindex trees, visibility
- @cindex show hidden text
- @cindex hide text
- @menu
- * Global and local cycling:: Cycling through various visibility states
- * Initial visibility:: Setting the initial visibility state
- * Catching invisible edits:: Preventing mistakes when editing invisible parts
- @end menu
- @node Global and local cycling
- @subsection Global and local cycling
- Outlines make it possible to hide parts of the text in the buffer.
- Org uses just two commands, bound to @key{TAB} and
- @kbd{S-@key{TAB}} to change the visibility in the buffer.
- @cindex subtree visibility states
- @cindex subtree cycling
- @cindex folded, subtree visibility state
- @cindex children, subtree visibility state
- @cindex subtree, subtree visibility state
- @table @asis
- @orgcmd{@key{TAB},org-cycle}
- @emph{Subtree cycling}: Rotate current subtree among the states
- @example
- ,-> FOLDED -> CHILDREN -> SUBTREE --.
- '-----------------------------------'
- @end example
- @vindex org-cycle-emulate-tab
- The cursor must be on a headline for this to work@footnote{see, however,
- the option @code{org-cycle-emulate-tab}.}.
- @cindex global visibility states
- @cindex global cycling
- @cindex overview, global visibility state
- @cindex contents, global visibility state
- @cindex show all, global visibility state
- @orgcmd{S-@key{TAB},org-global-cycle}
- @itemx C-u @key{TAB}
- @emph{Global cycling}: Rotate the entire buffer among the states
- @example
- ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
- '--------------------------------------'
- @end example
- When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
- CONTENTS view up to headlines of level N will be shown. Note that inside
- tables, @kbd{S-@key{TAB}} jumps to the previous field.
- @vindex org-cycle-global-at-bob
- You can run global cycling using @key{TAB} only if point is at the very
- beginning of the buffer, but not on a headline, and
- @code{org-cycle-global-at-bob} is set to a non-@code{nil} value.
- @cindex set startup visibility, command
- @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
- Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
- @cindex show all, command
- @orgcmd{C-u C-u C-u @key{TAB},outline-show-all}
- Show all, including drawers.
- @cindex revealing context
- @orgcmd{C-c C-r,org-reveal}
- Reveal context around point, showing the current entry, the following heading
- and the hierarchy above. Useful for working near a location that has been
- exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
- (@pxref{Agenda commands}). With a prefix argument show, on each
- level, all sibling headings. With a double prefix argument, also show the
- entire subtree of the parent.
- @cindex show branches, command
- @orgcmd{C-c C-k,outline-show-branches}
- Expose all the headings of the subtree, CONTENTS view for just one subtree.
- @cindex show children, command
- @orgcmd{C-c @key{TAB},outline-show-children}
- Expose all direct children of the subtree. With a numeric prefix argument N,
- expose all children down to level N@.
- @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
- Show the current subtree in an indirect buffer@footnote{The indirect buffer
- (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) will contain the entire
- buffer, but will be narrowed to the current tree. Editing the indirect
- buffer will also change the original buffer, but without affecting visibility
- in that buffer.}. With a numeric prefix argument N, go up to level N and
- then take that tree. If N is negative then go up that many levels. With
- a @kbd{C-u} prefix, do not remove the previously used indirect buffer.
- @orgcmd{C-c C-x v,org-copy-visible}
- Copy the @i{visible} text in the region into the kill ring.
- @end table
- @node Initial visibility
- @subsection Initial visibility
- @cindex visibility, initialize
- @vindex org-startup-folded
- @vindex org-agenda-inhibit-startup
- @cindex @code{overview}, STARTUP keyword
- @cindex @code{content}, STARTUP keyword
- @cindex @code{showall}, STARTUP keyword
- @cindex @code{showeverything}, STARTUP keyword
- When Emacs first visits an Org file, the global state is set to OVERVIEW,
- i.e., only the top level headlines are visible@footnote{When
- @code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default
- visibility state when first opening a file for the agenda (@pxref{Speeding up
- your agendas}).}. This can be configured through the variable
- @code{org-startup-folded}, or on a per-file basis by adding one of the
- following lines anywhere in the buffer:
- @example
- #+STARTUP: overview
- #+STARTUP: content
- #+STARTUP: showall
- #+STARTUP: showeverything
- @end example
- @cindex property, VISIBILITY
- @noindent
- Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
- and columns}) will get their visibility adapted accordingly. Allowed values
- for this property are @code{folded}, @code{children}, @code{content}, and
- @code{all}.
- @table @asis
- @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
- Switch back to the startup visibility of the buffer, i.e., whatever is
- requested by startup options and @samp{VISIBILITY} properties in individual
- entries.
- @end table
- @node Catching invisible edits
- @subsection Catching invisible edits
- @vindex org-catch-invisible-edits
- @cindex edits, catching invisible
- Sometimes you may inadvertently edit an invisible part of the buffer and be
- confused on what has been edited and how to undo the mistake. Setting
- @code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the
- docstring of this option on how Org should catch invisible edits and process
- them.
- @node Motion
- @section Motion
- @cindex motion, between headlines
- @cindex jumping, to headlines
- @cindex headline navigation
- The following commands jump to other headlines in the buffer.
- @table @asis
- @orgcmd{C-c C-n,org-next-visible-heading}
- Next heading.
- @orgcmd{C-c C-p,org-previous-visible-heading}
- Previous heading.
- @orgcmd{C-c C-f,org-forward-same-level}
- Next heading same level.
- @orgcmd{C-c C-b,org-backward-same-level}
- Previous heading same level.
- @orgcmd{C-c C-u,outline-up-heading}
- Backward to higher level heading.
- @orgcmd{C-c C-j,org-goto}
- Jump to a different place without changing the current outline
- visibility. Shows the document structure in a temporary buffer, where
- you can use the following keys to find your destination:
- @vindex org-goto-auto-isearch
- @example
- @key{TAB} @r{Cycle visibility.}
- @key{down} / @key{up} @r{Next/previous visible headline.}
- @key{RET} @r{Select this location.}
- @kbd{/} @r{Do a Sparse-tree search}
- @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
- n / p @r{Next/previous visible headline.}
- f / b @r{Next/previous headline same level.}
- u @r{One level up.}
- 0-9 @r{Digit argument.}
- q @r{Quit}
- @end example
- @vindex org-goto-interface
- @noindent
- See also the option @code{org-goto-interface}.
- @end table
- @node Structure editing
- @section Structure editing
- @cindex structure editing
- @cindex headline, promotion and demotion
- @cindex promotion, of subtrees
- @cindex demotion, of subtrees
- @cindex subtree, cut and paste
- @cindex pasting, of subtrees
- @cindex cutting, of subtrees
- @cindex copying, of subtrees
- @cindex sorting, of subtrees
- @cindex subtrees, cut and paste
- @table @asis
- @orgcmd{M-@key{RET},org-meta-return}
- @vindex org-M-RET-may-split-line
- Insert a new heading, item or row.
- If the command is used at the @emph{beginning} of a line, and if there is
- a heading or a plain list item (@pxref{Plain lists}) at point, the new
- heading/item is created @emph{before} the current line. When used at the
- beginning of a regular line of text, turn that line into a heading.
- When this command is used in the middle of a line, the line is split and the
- rest of the line becomes the new item or headline. If you do not want the
- line to be split, customize @code{org-M-RET-may-split-line}.
- Calling the command with a @kbd{C-u} prefix unconditionally inserts a new
- heading at the end of the current subtree, thus preserving its contents.
- With a double @kbd{C-u C-u} prefix, the new heading is created at the end of
- the parent subtree instead.
- @orgcmd{C-@key{RET},org-insert-heading-respect-content}
- Insert a new heading at the end of the current subtree.
- @orgcmd{M-S-@key{RET},org-insert-todo-heading}
- @vindex org-treat-insert-todo-heading-as-state-change
- Insert new TODO entry with same level as current heading. See also the
- variable @code{org-treat-insert-todo-heading-as-state-change}.
- @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
- Insert new TODO entry with same level as current heading. Like
- @kbd{C-@key{RET}}, the new headline will be inserted after the current
- subtree.
- @orgcmd{@key{TAB},org-cycle}
- In a new entry with no text yet, the first @key{TAB} demotes the entry to
- become a child of the previous one. The next @key{TAB} makes it a parent,
- and so on, all the way to top level. Yet another @key{TAB}, and you are back
- to the initial level.
- @orgcmd{M-@key{left},org-do-promote}
- Promote current heading by one level.
- @orgcmd{M-@key{right},org-do-demote}
- Demote current heading by one level.
- @orgcmd{M-S-@key{left},org-promote-subtree}
- Promote the current subtree by one level.
- @orgcmd{M-S-@key{right},org-demote-subtree}
- Demote the current subtree by one level.
- @orgcmd{M-@key{up},org-move-subtree-up}
- Move subtree up (swap with previous subtree of same
- level).
- @orgcmd{M-@key{down},org-move-subtree-down}
- Move subtree down (swap with next subtree of same level).
- @orgcmd{M-h,org-mark-element}
- Mark the element at point. Hitting repeatedly will mark subsequent elements
- of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
- hitting @key{M-h} immediately again will mark the next one.
- @orgcmd{C-c @@,org-mark-subtree}
- Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
- of the same level than the marked subtree.
- @orgcmd{C-c C-x C-w,org-cut-subtree}
- Kill subtree, i.e., remove it from buffer but save in kill ring.
- With a numeric prefix argument N, kill N sequential subtrees.
- @orgcmd{C-c C-x M-w,org-copy-subtree}
- Copy subtree to kill ring. With a numeric prefix argument N, copy the N
- sequential subtrees.
- @orgcmd{C-c C-x C-y,org-paste-subtree}
- Yank subtree from kill ring. This does modify the level of the subtree to
- make sure the tree fits in nicely at the yank position. The yank level can
- also be specified with a numeric prefix argument, or by yanking after a
- headline marker like @samp{****}.
- @orgcmd{C-y,org-yank}
- @vindex org-yank-adjusted-subtrees
- @vindex org-yank-folded-subtrees
- Depending on the options @code{org-yank-adjusted-subtrees} and
- @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
- paste subtrees folded and in a clever way, using the same command as @kbd{C-c
- C-x C-y}. With the default settings, no level adjustment will take place,
- but the yanked tree will be folded unless doing so would swallow text
- previously visible. Any prefix argument to this command will force a normal
- @code{yank} to be executed, with the prefix passed along. A good way to
- force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a
- yank, it will yank previous kill items plainly, without adjustment and
- folding.
- @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
- Clone a subtree by making a number of sibling copies of it. You will be
- prompted for the number of copies to make, and you can also specify if any
- timestamps in the entry should be shifted. This can be useful, for example,
- to create a number of tasks related to a series of lectures to prepare. For
- more details, see the docstring of the command
- @code{org-clone-subtree-with-time-shift}.
- @orgcmd{C-c C-w,org-refile}
- Refile entry or region to a different location. @xref{Refile and copy}.
- @orgcmd{C-c ^,org-sort}
- Sort same-level entries. When there is an active region, all entries in the
- region will be sorted. Otherwise the children of the current headline are
- sorted. The command prompts for the sorting method, which can be
- alphabetically, numerically, by time (first timestamp with active preferred,
- creation time, scheduled time, deadline time), by priority, by TODO keyword
- (in the sequence the keywords have been defined in the setup) or by the value
- of a property. Reverse sorting is possible as well. You can also supply
- your own function to extract the sorting key. With a @kbd{C-u} prefix,
- sorting will be case-sensitive.
- @orgcmd{C-x n s,org-narrow-to-subtree}
- Narrow buffer to current subtree.
- @orgcmd{C-x n b,org-narrow-to-block}
- Narrow buffer to current block.
- @orgcmd{C-x n w,widen}
- Widen buffer to remove narrowing.
- @orgcmd{C-c *,org-toggle-heading}
- Turn a normal line or plain list item into a headline (so that it becomes a
- subheading at its location). Also turn a headline into a normal line by
- removing the stars. If there is an active region, turn all lines in the
- region into headlines. If the first line in the region was an item, turn
- only the item lines into headlines. Finally, if the first line is a
- headline, remove the stars from all headlines in the region.
- @end table
- @cindex region, active
- @cindex active region
- @cindex transient mark mode
- When there is an active region (Transient Mark mode), promotion and
- demotion work on all headlines in the region. To select a region of
- headlines, it is best to place both point and mark at the beginning of a
- line, mark at the beginning of the first headline, and point at the line
- just after the last headline to change. Note that when the cursor is
- inside a table (@pxref{Tables}), the Meta-Cursor keys have different
- functionality.
- @node Sparse trees
- @section Sparse trees
- @cindex sparse trees
- @cindex trees, sparse
- @cindex folding, sparse trees
- @cindex occur, command
- @vindex org-show-context-detail
- An important feature of Org mode is the ability to construct @emph{sparse
- trees} for selected information in an outline tree, so that the entire
- document is folded as much as possible, but the selected information is made
- visible along with the headline structure above it@footnote{See also the
- variable @code{org-show-context-detail} to decide how much context is shown
- around each match.}. Just try it out and you will see immediately how it
- works.
- Org mode contains several commands for creating such trees, all these
- commands can be accessed through a dispatcher:
- @table @asis
- @orgcmd{C-c /,org-sparse-tree}
- This prompts for an extra key to select a sparse-tree creating command.
- @orgcmdkkc{C-c / r,C-c / /,org-occur}
- @vindex org-remove-highlights-with-change
- Prompts for a regexp and shows a sparse tree with all matches. If
- the match is in a headline, the headline is made visible. If the match is in
- the body of an entry, headline and body are made visible. In order to
- provide minimal context, also the full hierarchy of headlines above the match
- is shown, as well as the headline following the match. Each match is also
- highlighted; the highlights disappear when the buffer is changed by an
- editing command@footnote{This depends on the option
- @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
- When called with a @kbd{C-u} prefix argument, previous highlights are kept,
- so several calls to this command can be stacked.
- @orgcmdkkc{M-g n,M-g M-n,next-error}
- Jump to the next sparse tree match in this buffer.
- @orgcmdkkc{M-g p,M-g M-p,previous-error}
- Jump to the previous sparse tree match in this buffer.
- @end table
- @noindent
- @vindex org-agenda-custom-commands
- For frequently used sparse trees of specific search strings, you can
- use the option @code{org-agenda-custom-commands} to define fast
- keyboard access to specific sparse trees. These commands will then be
- accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
- For example:
- @lisp
- (setq org-agenda-custom-commands
- '(("f" occur-tree "FIXME")))
- @end lisp
- @noindent will define the key @kbd{C-c a f} as a shortcut for creating
- a sparse tree matching the string @samp{FIXME}.
- The other sparse tree commands select headings based on TODO keywords,
- tags, or properties and will be discussed later in this manual.
- @kindex C-c C-e C-v
- @cindex printing sparse trees
- @cindex visible text, printing
- To print a sparse tree, you can use the Emacs command
- @code{ps-print-buffer-with-faces} which does not print invisible parts of the
- document. Or you can use @kbd{C-c C-e C-v} to export only the visible part
- of the document and print the resulting file.
- @node Plain lists
- @section Plain lists
- @cindex plain lists
- @cindex lists, plain
- @cindex lists, ordered
- @cindex ordered lists
- Within an entry of the outline tree, hand-formatted lists can provide
- additional structure. They also provide a way to create lists of checkboxes
- (@pxref{Checkboxes}). Org supports editing such lists, and every exporter
- (@pxref{Exporting}) can parse and format them.
- Org knows ordered lists, unordered lists, and description lists.
- @itemize @bullet
- @item
- @emph{Unordered} list items start with @samp{-}, @samp{+}, or
- @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
- they will be seen as top-level headlines. Also, when you are hiding leading
- stars to get a clean outline view, plain list items starting with a star may
- be hard to distinguish from true headlines. In short: even though @samp{*}
- is supported, it may be better to not use it for plain list items.} as
- bullets.
- @item
- @vindex org-plain-list-ordered-item-terminator
- @vindex org-list-allow-alphabetical
- @emph{Ordered} list items start with a numeral followed by either a period or
- a right parenthesis@footnote{You can filter out any of them by configuring
- @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
- @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
- @samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize
- confusion with normal text, those are limited to one character only. Beyond
- that limit, bullets will automatically fallback to numbers.}. If you want a
- list to start with a different value (e.g., 20), start the text of the item
- with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
- must be put @emph{before} the checkbox. If you have activated alphabetical
- lists, you can also use counters like @code{[@@b]}.}. Those constructs can
- be used in any item of the list in order to enforce a particular numbering.
- @item
- @emph{Description} list items are unordered list items, and contain the
- separator @samp{ :: } to distinguish the description @emph{term} from the
- description.
- @end itemize
- Items belonging to the same list must have the same indentation on the first
- line. In particular, if an ordered list reaches number @samp{10.}, then the
- 2--digit numbers must be written left-aligned with the other numbers in the
- list. An item ends before the next line that is less or equally indented
- than its bullet/number.
- A list ends whenever every item has ended, which means before any line less
- or equally indented than items at top level. It also ends before two blank
- lines. In that case, all items are closed. Here is an example:
- @example
- @group
- ** Lord of the Rings
- My favorite scenes are (in this order)
- 1. The attack of the Rohirrim
- 2. Eowyn's fight with the witch king
- + this was already my favorite scene in the book
- + I really like Miranda Otto.
- 3. Peter Jackson being shot by Legolas
- - on DVD only
- He makes a really funny face when it happens.
- But in the end, no individual scenes matter but the film as a whole.
- Important actors in this film are:
- - @b{Elijah Wood} :: He plays Frodo
- - @b{Sean Astin} :: He plays Sam, Frodo's friend. I still remember
- him very well from his role as Mikey Walsh in @i{The Goonies}.
- @end group
- @end example
- Org supports these lists by tuning filling and wrapping commands to deal with
- them correctly, and by exporting them properly (@pxref{Exporting}). Since
- indentation is what governs the structure of these lists, many structural
- constructs like @code{#+BEGIN_...} blocks can be indented to signal that they
- belong to a particular item.
- @vindex org-list-demote-modify-bullet
- @vindex org-list-indent-offset
- If you find that using a different bullet for a sub-list (than that used for
- the current list-level) improves readability, customize the variable
- @code{org-list-demote-modify-bullet}. To get a greater difference of
- indentation between items and their sub-items, customize
- @code{org-list-indent-offset}.
- @vindex org-list-automatic-rules
- The following commands act on items when the cursor is in the first line of
- an item (the line with the bullet or number). Some of them imply the
- application of automatic rules to keep list structure intact. If some of
- these actions get in your way, configure @code{org-list-automatic-rules}
- to disable them individually.
- @table @asis
- @orgcmd{@key{TAB},org-cycle}
- @cindex cycling, in plain lists
- @vindex org-cycle-include-plain-lists
- Items can be folded just like headline levels. Normally this works only if
- the cursor is on a plain list item. For more details, see the variable
- @code{org-cycle-include-plain-lists}. If this variable is set to
- @code{integrate}, plain list items will be treated like low-level
- headlines. The level of an item is then given by the indentation of the
- bullet/number. Items are always subordinate to real headlines, however; the
- hierarchies remain completely separated. In a new item with no text yet, the
- first @key{TAB} demotes the item to become a child of the previous
- one. Subsequent @key{TAB}s move the item to meaningful levels in the list
- and eventually get it back to its initial position.
- @orgcmd{M-@key{RET},org-insert-heading}
- @vindex org-M-RET-may-split-line
- @vindex org-list-automatic-rules
- Insert new item at current level. With a prefix argument, force a new
- heading (@pxref{Structure editing}). If this command is used in the middle
- of an item, that item is @emph{split} in two, and the second part becomes the
- new item@footnote{If you do not want the item to be split, customize the
- variable @code{org-M-RET-may-split-line}.}. If this command is executed
- @emph{before item's body}, the new item is created @emph{before} the current
- one.
- @end table
- @table @kbd
- @kindex M-S-@key{RET}
- @item M-S-@key{RET}
- Insert a new item with a checkbox (@pxref{Checkboxes}).
- @kindex S-@key{down}
- @item S-up
- @itemx S-down
- @cindex shift-selection-mode
- @vindex org-support-shift-select
- @vindex org-list-use-circular-motion
- Jump to the previous/next item in the current list@footnote{If you want to
- cycle around items that way, you may customize
- @code{org-list-use-circular-motion}.}, but only if
- @code{org-support-shift-select} is off. If not, you can still use paragraph
- jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
- similar effect.
- @kindex M-@key{up}
- @kindex M-@key{down}
- @item M-up
- @itemx M-down
- Move the item including subitems up/down@footnote{See
- @code{org-list-use-circular-motion} for a cyclic behavior.} (swap with
- previous/next item of same indentation). If the list is ordered, renumbering
- is automatic.
- @kindex M-@key{left}
- @kindex M-@key{right}
- @item M-left
- @itemx M-right
- Decrease/increase the indentation of an item, leaving children alone.
- @kindex M-S-@key{left}
- @kindex M-S-@key{right}
- @item M-S-@key{left}
- @itemx M-S-@key{right}
- Decrease/increase the indentation of the item, including subitems.
- Initially, the item tree is selected based on current indentation. When
- these commands are executed several times in direct succession, the initially
- selected region is used, even if the new indentation would imply a different
- hierarchy. To use the new hierarchy, break the command chain with a cursor
- motion or so.
- As a special case, using this command on the very first item of a list will
- move the whole list. This behavior can be disabled by configuring
- @code{org-list-automatic-rules}. The global indentation of a list has no
- influence on the text @emph{after} the list.
- @kindex C-c C-c
- @item C-c C-c
- If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
- state of the checkbox. In any case, verify bullets and indentation
- consistency in the whole list.
- @kindex C-c -
- @vindex org-plain-list-ordered-item-terminator
- @item C-c -
- Cycle the entire list level through the different itemize/enumerate bullets
- (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
- depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
- and its indentation. With a numeric prefix argument N, select the Nth bullet
- from this list. If there is an active region when calling this, all selected
- lines are converted to list items. With a prefix argument, selected text is
- changed into a single item. If the first line already was a list item, any
- item marker will be removed from the list. Finally, even without an active
- region, a normal line will be converted into a list item.
- @kindex C-c *
- @item C-c *
- Turn a plain list item into a headline (so that it becomes a subheading at
- its location). @xref{Structure editing}, for a detailed explanation.
- @kindex C-c C-*
- @item C-c C-*
- Turn the whole plain list into a subtree of the current heading. Checkboxes
- (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
- (resp. checked).
- @kindex S-@key{left}
- @kindex S-@key{right}
- @item S-left/right
- @vindex org-support-shift-select
- This command also cycles bullet styles when the cursor in on the bullet or
- anywhere in an item line, details depending on
- @code{org-support-shift-select}.
- @kindex C-c ^
- @cindex sorting, of plain list
- @item C-c ^
- Sort the plain list. You will be prompted for the sorting method:
- numerically, alphabetically, by time, by checked status for check lists,
- or by a custom function.
- @end table
- @node Drawers
- @section Drawers
- @cindex drawers
- @cindex visibility cycling, drawers
- @cindex org-insert-drawer
- @kindex C-c C-x d
- Sometimes you want to keep information associated with an entry, but you
- normally don't want to see it. For this, Org mode has @emph{drawers}. They
- can contain anything but a headline and another drawer. Drawers look like
- this:
- @example
- ** This is a headline
- Still outside the drawer
- :DRAWERNAME:
- This is inside the drawer.
- :END:
- After the drawer.
- @end example
- You can interactively insert drawers at point by calling
- @code{org-insert-drawer}, which is bound to @key{C-c C-x d}. With an active
- region, this command will put the region inside the drawer. With a prefix
- argument, this command calls @code{org-insert-property-drawer} and add
- a property drawer right below the current headline. Completion over drawer
- keywords is also possible using @kbd{M-@key{TAB}}@footnote{Many desktops
- intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
- @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}.
- Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
- show the entry, but keep the drawer collapsed to a single line. In order to
- look inside the drawer, you need to move the cursor to the drawer line and
- press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
- storing properties (@pxref{Properties and columns}), and you can also arrange
- for state change notes (@pxref{Tracking TODO state changes}) and clock times
- (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
- want to store a quick note in the LOGBOOK drawer, in a similar way to state
- changes, use
- @table @kbd
- @kindex C-c C-z
- @item C-c C-z
- Add a time-stamped note to the LOGBOOK drawer.
- @end table
- @vindex org-export-with-drawers
- @vindex org-export-with-properties
- You can select the name of the drawers which should be exported with
- @code{org-export-with-drawers}. In that case, drawer contents will appear in
- export output. Property drawers are not affected by this variable: configure
- @code{org-export-with-properties} instead.
- @node Blocks
- @section Blocks
- @vindex org-hide-block-startup
- @cindex blocks, folding
- Org mode uses begin...end blocks for various purposes from including source
- code examples (@pxref{Literal examples}) to capturing time logging
- information (@pxref{Clocking work time}). These blocks can be folded and
- unfolded by pressing TAB in the begin line. You can also get all blocks
- folded at startup by configuring the option @code{org-hide-block-startup}
- or on a per-file basis by using
- @cindex @code{hideblocks}, STARTUP keyword
- @cindex @code{nohideblocks}, STARTUP keyword
- @example
- #+STARTUP: hideblocks
- #+STARTUP: nohideblocks
- @end example
- @node Footnotes
- @section Footnotes
- @cindex footnotes
- Org mode supports the creation of footnotes.
- A footnote is started by a footnote marker in square brackets in column 0, no
- indentation allowed. It ends at the next footnote definition, headline, or
- after two consecutive empty lines. The footnote reference is simply the
- marker in square brackets, inside text. Markers always start with
- @code{fn:}. For example:
- @example
- The Org homepage[fn:1] now looks a lot better than it used to.
- ...
- [fn:1] The link is: https://orgmode.org
- @end example
- Org mode extends the number-based syntax to @emph{named} footnotes and
- optional inline definition. Here are the valid references:
- @table @code
- @item [fn:name]
- A named footnote reference, where @code{name} is a unique label word, or, for
- simplicity of automatic creation, a number.
- @item [fn::This is the inline definition of this footnote]
- A @LaTeX{}-like anonymous footnote where the definition is given directly at the
- reference point.
- @item [fn:name:a definition]
- An inline definition of a footnote, which also specifies a name for the note.
- Since Org allows multiple references to the same note, you can then use
- @code{[fn:name]} to create additional references.
- @end table
- @vindex org-footnote-auto-label
- Footnote labels can be created automatically, or you can create names yourself.
- This is handled by the variable @code{org-footnote-auto-label} and its
- corresponding @code{#+STARTUP} keywords. See the docstring of that variable
- for details.
- @noindent The following command handles footnotes:
- @table @kbd
- @kindex C-c C-x f
- @item C-c C-x f
- The footnote action command.
- When the cursor is on a footnote reference, jump to the definition. When it
- is at a definition, jump to the (first) reference.
- @vindex org-footnote-define-inline
- @vindex org-footnote-section
- @vindex org-footnote-auto-adjust
- Otherwise, create a new footnote. Depending on the option
- @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
- setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
- definition will be placed right into the text as part of the reference, or
- separately into the location determined by the option
- @code{org-footnote-section}.
- When this command is called with a prefix argument, a menu of additional
- options is offered:
- @example
- s @r{Sort the footnote definitions by reference sequence. During editing,}
- @r{Org makes no effort to sort footnote definitions into a particular}
- @r{sequence. If you want them sorted, use this command, which will}
- @r{also move entries according to @code{org-footnote-section}. Automatic}
- @r{sorting after each insertion/deletion can be configured using the}
- @r{option @code{org-footnote-auto-adjust}.}
- r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
- @r{after each insertion/deletion can be configured using the option}
- @r{@code{org-footnote-auto-adjust}.}
- S @r{Short for first @code{r}, then @code{s} action.}
- n @r{Normalize the footnotes by collecting all definitions (including}
- @r{inline definitions) into a special section, and then numbering them}
- @r{in sequence. The references will then also be numbers.}
- d @r{Delete the footnote at point, and all definitions of and references}
- @r{to it.}
- @end example
- Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
- corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
- renumbering and sorting footnotes can be automatic after each insertion or
- deletion.
- @kindex C-c C-c
- @item C-c C-c
- If the cursor is on a footnote reference, jump to the definition. If it is a
- the definition, jump back to the reference. When called at a footnote
- location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
- @kindex C-c C-o
- @kindex mouse-1
- @kindex mouse-2
- @item C-c C-o @r{or} mouse-1/2
- Footnote labels are also links to the corresponding definition/reference, and
- you can use the usual commands to follow these links.
- @vindex org-edit-footnote-reference
- @kindex C-c '
- @item C-c '
- @item C-c '
- Edit the footnote definition corresponding to the reference at point in
- a separate window. The window can be closed by pressing @kbd{C-c '}.
- @end table
- @node Org syntax
- @section Org syntax
- @cindex Org syntax
- A reference document providing a formal description of Org's syntax is
- available as @uref{https://orgmode.org/worg/dev/org-syntax.html, a draft on
- Worg}, written and maintained by Nicolas Goaziou. It defines Org's core
- internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
- keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org
- file falls into one of the categories above.
- To explore the abstract structure of an Org buffer, run this in a buffer:
- @lisp
- M-: (org-element-parse-buffer) RET
- @end lisp
- It will output a list containing the buffer's content represented as an
- abstract structure. The export engine relies on the information stored in
- this list. Most interactive commands (e.g., for structure editing) also
- rely on the syntactic meaning of the surrounding context.
- @cindex syntax checker
- @cindex linter
- You can check syntax in your documents using @code{org-lint} command.
- @node Tables
- @chapter Tables
- @cindex tables
- @cindex editing tables
- Org comes with a fast and intuitive table editor. Spreadsheet-like
- calculations are supported using the Emacs @file{calc} package
- (@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
- @menu
- * Built-in table editor:: Simple tables
- * Column width and alignment:: Overrule the automatic settings
- * Column groups:: Grouping to trigger vertical lines
- * Orgtbl mode:: The table editor as minor mode
- * The spreadsheet:: The table editor has spreadsheet capabilities
- * Org-Plot:: Plotting from org tables
- @end menu
- @node Built-in table editor
- @section The built-in table editor
- @cindex table editor, built-in
- Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} as
- the first non-whitespace character is considered part of a table. @samp{|}
- is also the column separator@footnote{To insert a vertical bar into a table
- field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
- might look like this:
- @example
- | Name | Phone | Age |
- |-------+-------+-----|
- | Peter | 1234 | 17 |
- | Anna | 4321 | 25 |
- @end example
- A table is re-aligned automatically each time you press @key{TAB} or
- @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
- the next field (@key{RET} to the next row) and creates new table rows
- at the end of the table or before horizontal lines. The indentation
- of the table is set by the first line. Any line starting with
- @samp{|-} is considered as a horizontal separator line and will be
- expanded on the next re-align to span the whole table width. So, to
- create the above table, you would only type
- @example
- |Name|Phone|Age|
- |-
- @end example
- @noindent and then press @key{TAB} to align the table and start filling in
- fields. Even faster would be to type @code{|Name|Phone|Age} followed by
- @kbd{C-c @key{RET}}.
- @vindex org-table-auto-blank-field
- When typing text into a field, Org treats @key{DEL}, @key{Backspace}, and all
- character keys in a special way, so that inserting and deleting avoids
- shifting other fields. Also, when typing @emph{immediately after the cursor
- was moved into a new field with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or
- @kbd{@key{RET}}}, the field is automatically made blank. If this behavior is
- too unpredictable for you, configure the option
- @code{org-table-auto-blank-field}.
- @table @kbd
- @tsubheading{Creation and conversion}
- @orgcmd{C-c |,org-table-create-or-convert-from-region}
- Convert the active region to a table. If every line contains at least one
- TAB character, the function assumes that the material is tab separated.
- If every line contains a comma, comma-separated values (CSV) are assumed.
- If not, lines are split at whitespace into fields. You can use a prefix
- argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
- C-u} forces TAB, @kbd{C-u C-u C-u} will prompt for a regular expression to
- match the separator, and a numeric argument N indicates that at least N
- consecutive spaces, or alternatively a TAB will be the separator.
- @*
- If there is no active region, this command creates an empty Org
- table. But it is easier just to start typing, like
- @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
- @tsubheading{Re-aligning and field motion}
- @orgcmd{C-c C-c,org-table-align}
- Re-align the table and don't move to another field.
- @c
- @orgcmd{C-c SPC,org-table-blank-field}
- Blank the field at point.
- @c
- @orgcmd{TAB,org-table-next-field}
- Re-align the table, move to the next field. Creates a new row if
- necessary.
- @c
- @orgcmd{S-@key{TAB},org-table-previous-field}
- Re-align, move to previous field.
- @c
- @orgcmd{@key{RET},org-table-next-row}
- Re-align the table and move down to next row. Creates a new row if
- necessary. At the beginning or end of a line, @key{RET} still does
- NEWLINE, so it can be used to split a table.
- @c
- @orgcmd{M-a,org-table-beginning-of-field}
- Move to beginning of the current table field, or on to the previous field.
- @orgcmd{M-e,org-table-end-of-field}
- Move to end of the current table field, or on to the next field.
- @tsubheading{Column and row editing}
- @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
- Move the current column left/right.
- @c
- @orgcmd{M-S-@key{left},org-table-delete-column}
- Kill the current column.
- @c
- @orgcmd{M-S-@key{right},org-table-insert-column}
- Insert a new column to the left of the cursor position.
- @c
- @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
- Move the current row up/down.
- @c
- @orgcmd{M-S-@key{up},org-table-kill-row}
- Kill the current row or horizontal line.
- @c
- @orgcmd{M-S-@key{down},org-table-insert-row}
- Insert a new row above the current row. With a prefix argument, the line is
- created below the current one.
- @c
- @orgcmd{C-c -,org-table-insert-hline}
- Insert a horizontal line below current row. With a prefix argument, the line
- is created above the current line.
- @c
- @orgcmd{C-c @key{RET},org-table-hline-and-move}
- Insert a horizontal line below current row, and move the cursor into the row
- below that line.
- @c
- @orgcmd{C-c ^,org-table-sort-lines}
- Sort the table lines in the region. The position of point indicates the
- column to be used for sorting, and the range of lines is the range
- between the nearest horizontal separator lines, or the entire table. If
- point is before the first column, you will be prompted for the sorting
- column. If there is an active region, the mark specifies the first line
- and the sorting column, while point should be in the last line to be
- included into the sorting. The command prompts for the sorting type
- (alphabetically, numerically, or by time). You can sort in normal or
- reverse order. You can also supply your own key extraction and comparison
- functions. When called with a prefix argument, alphabetic sorting will be
- case-sensitive.
- @tsubheading{Regions}
- @orgcmd{C-c C-x M-w,org-table-copy-region}
- Copy a rectangular region from a table to a special clipboard. Point and
- mark determine edge fields of the rectangle. If there is no active region,
- copy just the current field. The process ignores horizontal separator lines.
- @c
- @orgcmd{C-c C-x C-w,org-table-cut-region}
- Copy a rectangular region from a table to a special clipboard, and
- blank all fields in the rectangle. So this is the ``cut'' operation.
- @c
- @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
- Paste a rectangular region into a table.
- The upper left corner ends up in the current field. All involved fields
- will be overwritten. If the rectangle does not fit into the present table,
- the table is enlarged as needed. The process ignores horizontal separator
- lines.
- @c
- @orgcmd{M-@key{RET},org-table-wrap-region}
- Split the current field at the cursor position and move the rest to the line
- below. If there is an active region, and both point and mark are in the same
- column, the text in the column is wrapped to minimum width for the given
- number of lines. A numeric prefix argument may be used to change the number
- of desired lines. If there is no region, but you specify a prefix argument,
- the current field is made blank, and the content is appended to the field
- above.
- @tsubheading{Calculations}
- @cindex formula, in tables
- @cindex calculations, in tables
- @cindex region, active
- @cindex active region
- @cindex transient mark mode
- @orgcmd{C-c +,org-table-sum}
- Sum the numbers in the current column, or in the rectangle defined by
- the active region. The result is shown in the echo area and can
- be inserted with @kbd{C-y}.
- @c
- @orgcmd{S-@key{RET},org-table-copy-down}
- @vindex org-table-copy-increment
- When current field is empty, copy from first non-empty field above. When not
- empty, copy current field down to next row and move cursor along with it.
- Depending on the option @code{org-table-copy-increment}, integer field
- values will be incremented during copy. Integers that are too large will not
- be incremented. Also, a @code{0} prefix argument temporarily disables the
- increment. This key is also used by shift-selection and related modes
- (@pxref{Conflicts}).
- @tsubheading{Miscellaneous}
- @orgcmd{C-c `,org-table-edit-field}
- Edit the current field in a separate window. This is useful for fields that
- are not fully visible (@pxref{Column width and alignment}). When called with
- a @kbd{C-u} prefix, just make the full field visible, so that it can be
- edited in place. When called with two @kbd{C-u} prefixes, make the editor
- window follow the cursor through the table and always show the current
- field. The follow mode exits automatically when the cursor leaves the table,
- or when you repeat this command with @kbd{C-u C-u C-c `}.
- @c
- @item M-x org-table-import RET
- Import a file as a table. The table should be TAB or whitespace
- separated. Use, for example, to import a spreadsheet table or data
- from a database, because these programs generally can write
- TAB-separated text files. This command works by inserting the file into
- the buffer and then converting the region to a table. Any prefix
- argument is passed on to the converter, which uses it to determine the
- separator.
- @orgcmd{C-c |,org-table-create-or-convert-from-region}
- Tables can also be imported by pasting tabular text into the Org
- buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
- @kbd{C-c |} command (see above under @i{Creation and conversion}).
- @c
- @item M-x org-table-export RET
- @findex org-table-export
- @vindex org-table-export-default-format
- Export the table, by default as a TAB-separated file. Use for data
- exchange with, for example, spreadsheet or database programs. The format
- used to export the file can be configured in the option
- @code{org-table-export-default-format}. You may also use properties
- @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
- name and the format for table export in a subtree. Org supports quite
- general formats for exported tables. The exporter format is the same as the
- format used by Orgtbl radio tables, see @ref{Translator functions}, for a
- detailed description.
- @end table
- @node Column width and alignment
- @section Column width and alignment
- @cindex narrow columns in tables
- @cindex alignment in tables
- The width of columns is automatically determined by the table editor. The
- alignment of a column is determined automatically from the fraction of
- number-like versus non-number fields in the column.
- @vindex org-table-automatic-realign
- Editing a field may modify alignment of the table. Moving a contiguous row
- or column---i.e., using @kbd{TAB} or @kbd{RET}---automatically re-aligns it.
- If you want to disable this behavior, set @code{org-table-automatic-realign}
- to @code{nil}. In any case, you can always align manually a table:
- @table @asis
- @orgcmd{C-c C-c,org-table-align}
- Align the current table.
- @end table
- @vindex org-startup-align-all-tables
- @noindent
- Setting the option @code{org-startup-align-all-tables} re-aligns all tables
- in a file upon visiting it. You can also set this option on a per-file basis
- with:
- @example
- #+STARTUP: align
- #+STARTUP: noalign
- @end example
- Sometimes a single field or a few fields need to carry more text, leading to
- inconveniently wide columns. Maybe you want to hide away several columns or
- display them with a fixed width, regardless of content, as shown in the
- following example.
- @example
- @group
- |---+---------------------+--------| |---+-------@dots{}|@dots{}|
- | | <6> | | | | <6> @dots{}|@dots{}|
- | 1 | one | some | ----\ | 1 | one @dots{}|@dots{}|
- | 2 | two | boring | ----/ | 2 | two @dots{}|@dots{}|
- | 3 | This is a long text | column | | 3 | This i@dots{}|@dots{}|
- |---+---------------------+--------| |---+-------@dots{}|@dots{}|
- @end group
- @end example
- To set the width of a column, one field anywhere in the column may contain
- just the string @samp{<N>} where @samp{N} specifies the width as a number of
- characters. You control displayed width of columns with the following tools:
- @table @asis
- @orgcmd{C-c @key{TAB},org-table-toggle-column-width}
- Shrink or expand current column.
- If a width cookie specifies a width W for the column, shrinking it displays
- the first W visible characters only. Otherwise, the column is shrunk to
- a single character.
- When called before the first column or after the last one, ask for a list of
- column ranges to operate on.
- @orgcmd{C-u C-c @key{TAB},org-table-shrink}
- Shrink all columns with a column width. Expand the others.
- @orgcmd{C-u C-u C-c @key{TAB},org-table-expand}
- Expand all columns.
- @end table
- To see the full text of a shrunk field, hold the mouse over it---a tool-tip
- window then shows the full content. Alternatively @kbd{C-h .}
- (@code{display-local-help}) reveals the full content. For convenience, any
- change to a shrunk column expands it.
- @vindex org-startup-shrink-all-tables
- Setting the option @code{org-startup-shrink-all-tables} shrinks all columns
- containing a width cookie in a file the moment it is visited. You can also
- set this option on a per-file basis with:
- @example
- #+STARTUP: shrink
- @end example
- If you would like to overrule the automatic alignment of number-rich columns
- to the right and of string-rich columns to the left, you can use @samp{<r>},
- @samp{<c>} or @samp{<l>} in a similar fashion. You may also combine
- alignment and field width like this: @samp{<r10>}.
- Lines which only contain these formatting cookies are removed automatically
- upon exporting the document.
- @node Column groups
- @section Column groups
- @cindex grouping columns in tables
- When Org exports tables, it does so by default without vertical lines because
- that is visually more satisfying in general. Occasionally however, vertical
- lines can be useful to structure a table into groups of columns, much like
- horizontal lines can do for groups of rows. In order to specify column
- groups, you can use a special row where the first field contains only
- @samp{/}. The further fields can either contain @samp{<} to indicate that
- this column should start a group, @samp{>} to indicate the end of a group, or
- @samp{<>} (no space between @samp{<} and @samp{>}) to make a column a group
- of its own. Boundaries between column groups will upon export be marked with
- vertical lines. Here is an example:
- @example
- | N | N^2 | N^3 | N^4 | ~sqrt(n)~ | ~sqrt[4](N)~ |
- |---+-----+-----+-----+-----------+--------------|
- | / | < | | > | < | > |
- | 1 | 1 | 1 | 1 | 1 | 1 |
- | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
- | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
- |---+-----+-----+-----+-----------+--------------|
- #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
- @end example
- It is also sufficient to just insert the column group starters after
- every vertical line you would like to have:
- @example
- | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
- |----+-----+-----+-----+---------+------------|
- | / | < | | | < | |
- @end example
- @node Orgtbl mode
- @section The Orgtbl minor mode
- @cindex Orgtbl mode
- @cindex minor mode for tables
- If you like the intuitive way the Org table editor works, you
- might also want to use it in other modes like Text mode or Mail mode.
- The minor mode Orgtbl mode makes this possible. You can always toggle
- the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for
- example in Message mode, use
- @lisp
- (add-hook 'message-mode-hook 'turn-on-orgtbl)
- @end lisp
- Furthermore, with some special setup, it is possible to maintain tables
- in arbitrary syntax with Orgtbl mode. For example, it is possible to
- construct @LaTeX{} tables with the underlying ease and power of
- Orgtbl mode, including spreadsheet capabilities. For details, see
- @ref{Tables in arbitrary syntax}.
- @node The spreadsheet
- @section The spreadsheet
- @cindex calculations, in tables
- @cindex spreadsheet capabilities
- @cindex @file{calc} package
- The table editor makes use of the Emacs @file{calc} package to implement
- spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
- derive fields from other fields. While fully featured, Org's implementation
- is not identical to other spreadsheets. For example, Org knows the concept
- of a @emph{column formula} that will be applied to all non-header fields in a
- column without having to copy the formula to each relevant field. There is
- also a formula debugger, and a formula editor with features for highlighting
- fields in the table corresponding to the references at the point in the
- formula, moving these references by arrow keys
- @menu
- * References:: How to refer to another field or range
- * Formula syntax for Calc:: Using Calc to compute stuff
- * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
- * Durations and time values:: How to compute durations and time values
- * Field and range formulas:: Formula 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
- * Updating the table:: Recomputing all dependent fields
- * Advanced features:: Field and column names, parameters and automatic recalc
- @end menu
- @node References
- @subsection References
- @cindex references
- To compute fields in the table from other fields, formulas must
- reference other fields or ranges. In Org, fields can be referenced
- by name, by absolute coordinates, and by relative coordinates. To find
- out what the coordinates of a field are, press @kbd{C-c ?} in that
- field, or press @kbd{C-c @}} to toggle the display of a grid.
- @subsubheading Field references
- @cindex field references
- @cindex references, to fields
- Formulas can reference the value of another field in two ways. Like in
- any other spreadsheet, you may reference fields with a letter/number
- combination like @code{B3}, meaning the 2nd field in the 3rd row.
- @vindex org-table-use-standard-references
- However, Org prefers@footnote{Org will understand references typed by the
- user as @samp{B4}, but it will not use this syntax when offering a formula
- for editing. You can customize this behavior using the option
- @code{org-table-use-standard-references}.} to use another, more general
- representation that looks like this:
- @example
- @@@var{row}$@var{column}
- @end example
- Column specifications can be absolute like @code{$1},
- @code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
- column of the field which is being computed) like @code{$+1} or @code{$-2}.
- @code{$<} and @code{$>} are immutable references to the first and last
- column, respectively, and you can use @code{$>>>} to indicate the third
- column from the right.
- The row specification only counts data lines and ignores horizontal separator
- lines (hlines). Like with columns, you can use absolute row numbers
- @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
- current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are
- immutable references the first and last@footnote{For backward compatibility
- you can also use special names like @code{$LR5} and @code{$LR12} to refer in
- a stable way to the 5th and 12th field in the last row of the table.
- However, this syntax is deprecated, it should not be used for new documents.
- Use @code{@@>$} instead.} row in the table, respectively. You may also
- specify the row relative to one of the hlines: @code{@@I} refers to the first
- hline, @code{@@II} to the second, etc. @code{@@-I} refers to the first such
- line above the current line, @code{@@+I} to the first such line below the
- current line. You can also write @code{@@III+2} which is the second data line
- after the third hline in the table.
- @code{@@0} and @code{$0} refer to the current row and column, respectively,
- i.e., to the row/column for the field being computed. Also, if you omit
- either the column or the row part of the reference, the current row/column is
- implied.
- Org's references with @emph{unsigned} numbers are fixed references
- in the sense that if you use the same reference in the formula for two
- different fields, the same field will be referenced each time.
- Org's references with @emph{signed} numbers are floating
- references because the same reference operator can reference different
- fields depending on the field being calculated by the formula.
- Here are a few examples:
- @example
- @@2$3 @r{2nd row, 3rd column (same as @code{C2})}
- $5 @r{column 5 in the current row (same as @code{E&})}
- @@2 @r{current column, row 2}
- @@-1$-3 @r{the field one row up, three columns to the left}
- @@-I$2 @r{field just under hline above current row, column 2}
- @@>$5 @r{field in the last row, in column 5}
- @end example
- @subsubheading Range references
- @cindex range references
- @cindex references, to ranges
- You may reference a rectangular range of fields by specifying two field
- references connected by two dots @samp{..}. If both fields are in the
- current row, you may simply use @samp{$2..$7}, but if at least one field
- is in a different row, you need to use the general @code{@@row$column}
- format at least for the first field (i.e the reference must start with
- @samp{@@} in order to be interpreted correctly). Examples:
- @example
- $1..$3 @r{first three fields in the current row}
- $P..$Q @r{range, using column names (see under Advanced)}
- $<<<..$>> @r{start in third column, continue to the last but one}
- @@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
- @@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left}
- @@I..II @r{between first and second hline, short for @code{@@I..@@II}}
- @end example
- @noindent Range references return a vector of values that can be fed
- into Calc vector functions. Empty fields in ranges are normally suppressed,
- so that the vector contains only the non-empty fields. For other options
- with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
- for Calc}.
- @subsubheading Field coordinates in formulas
- @cindex field coordinates
- @cindex coordinates, of field
- @cindex row, of field coordinates
- @cindex column, of field coordinates
- One of the very first actions during evaluation of Calc formulas and Lisp
- formulas is to substitute @code{@@#} and @code{$#} in the formula with the
- row or column number of the field where the current result will go to. The
- traditional Lisp formula equivalents are @code{org-table-current-dline} and
- @code{org-table-current-column}. Examples:
- @table @code
- @item if(@@# % 2, $#, string(""))
- Insert column number on odd rows, set field to empty on even rows.
- @item $2 = '(identity remote(FOO, @@@@#$1))
- Copy text or values of each row of column 1 of the table named @code{FOO}
- into column 2 of the current table.
- @item @@3 = 2 * remote(FOO, @@1$$#)
- Insert the doubled value of each column of row 1 of the table named
- @code{FOO} into row 3 of the current table.
- @end table
- @noindent For the second/third example, the table named @code{FOO} must have
- at least as many rows/columns as the current table. Note that this is
- inefficient@footnote{The computation time scales as O(N^2) because the table
- named @code{FOO} is parsed for each field to be read.} for large number of
- rows/columns.
- @subsubheading Named references
- @cindex named references
- @cindex references, named
- @cindex name, of column or field
- @cindex constants, in calculations
- @cindex #+CONSTANTS
- @vindex org-table-formula-constants
- @samp{$name} is interpreted as the name of a column, parameter or
- constant. Constants are defined globally through the option
- @code{org-table-formula-constants}, and locally (for the file) through a
- line like
- @example
- #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
- @end example
- @noindent
- @vindex constants-unit-system
- @pindex constants.el
- Also properties (@pxref{Properties and columns}) can be used as
- constants in table formulas: for a property @samp{:Xyz:} use the name
- @samp{$PROP_Xyz}, and the property will be searched in the current
- outline entry and in the hierarchy above it. If you have the
- @file{constants.el} package, it will also be used to resolve constants,
- including natural constants like @samp{$h} for Planck's constant, and
- units like @samp{$km} for kilometers@footnote{@file{constants.el} can
- supply the values of constants in two different unit systems, @code{SI}
- and @code{cgs}. Which one is used depends on the value of the variable
- @code{constants-unit-system}. You can use the @code{#+STARTUP} options
- @code{constSI} and @code{constcgs} to set this value for the current
- buffer.}. Column names and parameters can be specified in special table
- lines. These are described below, see @ref{Advanced features}. All
- names must start with a letter, and further consist of letters and
- numbers.
- @subsubheading Remote references
- @cindex remote references
- @cindex references, remote
- @cindex references, to a different table
- @cindex name, of column or field
- @cindex constants, in calculations
- @cindex #+NAME, for table
- You may also reference constants, fields and ranges from a different table,
- either in the current file or even in a different file. The syntax is
- @example
- remote(NAME-OR-ID,REF)
- @end example
- @noindent
- where NAME can be the name of a table in the current file as set by a
- @code{#+NAME: Name} line before the table. It can also be the ID of an
- entry, even in a different file, and the reference then refers to the first
- table in that entry. REF is an absolute field or range reference as
- described above for example @code{@@3$3} or @code{$somename}, valid in the
- referenced table.
- Indirection of NAME-OR-ID: When NAME-OR-ID has the format @code{@@ROW$COLUMN}
- it will be substituted with the name or ID found in this field of the current
- table. For example @code{remote($1, @@>$2)} => @code{remote(year_2013,
- @@>$1)}. The format @code{B3} is not supported because it can not be
- distinguished from a plain table name or ID.
- @node Formula syntax for Calc
- @subsection Formula syntax for Calc
- @cindex formula syntax, Calc
- @cindex syntax, of formulas
- A formula can be any algebraic expression understood by the Emacs @file{Calc}
- package. Note that @file{calc} has the non-standard convention that @samp{/}
- has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
- @samp{a/(b*c)}. Before evaluation by @code{calc-eval} (@pxref{Calling Calc
- from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc,
- GNU Emacs Calc Manual}), variable substitution takes place according to the
- rules described above.
- @cindex vectors, in table calculations
- The range vectors can be directly fed into the Calc vector functions
- like @samp{vmean} and @samp{vsum}.
- @cindex format specifier
- @cindex mode, for @file{calc}
- @vindex org-calc-default-modes
- A formula can contain an optional mode string after a semicolon. This
- string consists of flags to influence Calc and other modes during
- execution. By default, Org uses the standard Calc modes (precision
- 12, angular units degrees, fraction and symbolic modes off). The display
- format, however, has been changed to @code{(float 8)} to keep tables
- compact. The default settings can be configured using the option
- @code{org-calc-default-modes}.
- @noindent List of modes:
- @table @asis
- @item @code{p20}
- Set the internal Calc calculation precision to 20 digits.
- @item @code{n3}, @code{s3}, @code{e2}, @code{f4}
- Normal, scientific, engineering or fixed format of the result of Calc passed
- back to Org. Calc formatting is unlimited in precision as long as the Calc
- calculation precision is greater.
- @item @code{D}, @code{R}
- Degree and radian angle modes of Calc.
- @item @code{F}, @code{S}
- Fraction and symbolic modes of Calc.
- @item @code{T}, @code{t}, @code{U}
- Duration computations in Calc or Lisp, @pxref{Durations and time values}.
- @item @code{E}
- If and how to consider empty fields. Without @samp{E} empty fields in range
- references are suppressed so that the Calc vector or Lisp list contains only
- the non-empty fields. With @samp{E} the empty fields are kept. For empty
- fields in ranges or empty field references the value @samp{nan} (not a
- number) is used in Calc formulas and the empty string is used for Lisp
- formulas. Add @samp{N} to use 0 instead for both formula types. For the
- value of a field the mode @samp{N} has higher precedence than @samp{E}.
- @item @code{N}
- Interpret all fields as numbers, use 0 for non-numbers. See the next section
- to see how this is essential for computations with Lisp formulas. In Calc
- formulas it is used only occasionally because there number strings are
- already interpreted as numbers without @samp{N}.
- @item @code{L}
- Literal, for Lisp formulas only. See the next section.
- @end table
- @noindent
- Unless you use large integer numbers or high-precision-calculation and
- -display for floating point numbers you may alternatively provide a
- @samp{printf} format specifier to reformat the Calc result after it has been
- passed back to Org instead of letting Calc already do the
- formatting@footnote{The @samp{printf} reformatting is limited in precision
- because the value passed to it is converted into an @samp{integer} or
- @samp{double}. The @samp{integer} is limited in size by truncating the
- signed value to 32 bits. The @samp{double} is limited in precision to 64
- bits overall which leaves approximately 16 significant decimal digits.}. A
- few examples:
- @example
- $1+$2 @r{Sum of first and second field}
- $1+$2;%.2f @r{Same, format result to two decimals}
- exp($2)+exp($1) @r{Math functions can be used}
- $0;%.1f @r{Reformat current cell to 1 decimal}
- ($3-32)*5/9 @r{Degrees F -> C conversion}
- $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
- tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
- sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
- taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
- @end example
- Calc also contains a complete set of logical operations, (@pxref{Logical
- Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example
- @table @code
- @item if($1 < 20, teen, string(""))
- "teen" if age $1 is less than 20, else the Org table result field is set to
- empty with the empty string.
- @item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1
- Sum of the first two columns. When at least one of the input fields is empty
- the Org table result field is set to empty. @samp{E} is required to not
- convert empty fields to 0. @samp{f-1} is an optional Calc format string
- similar to @samp{%.1f} but leaves empty results empty.
- @item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
- Mean value of a range unless there is any empty field. Every field in the
- range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
- in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from
- @samp{vmean} and the Org table result field is set to empty. Use this when
- the sample set is expected to never have missing values.
- @item if("$1..$7" == "[]", string(""), vmean($1..$7))
- Mean value of a range with empty fields skipped. Every field in the range
- that is empty is skipped. When all fields in the range are empty the mean
- value is not defined and the Org table result field is set to empty. Use
- this when the sample set can have a variable size.
- @item vmean($1..$7); EN
- To complete the example before: Mean value of a range with empty fields
- counting as samples with value 0. Use this only when incomplete sample sets
- should be padded with 0 to the full size.
- @end table
- You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
- and use them in formula syntax for Calc.
- @node Formula syntax for Lisp
- @subsection Emacs Lisp forms as formulas
- @cindex Lisp forms, as table formulas
- It is also possible to write a formula in Emacs Lisp. This can be useful
- for string manipulation and control structures, if Calc's functionality is
- not enough.
- If a formula starts with an apostrophe followed by an opening parenthesis,
- then it is evaluated as a Lisp form. The evaluation should return either a
- string or a number. Just as with @file{calc} formulas, you can specify modes
- and a printf format after a semicolon.
- With Emacs Lisp forms, you need to be conscious about the way field
- references are interpolated into the form. By default, a reference will be
- interpolated as a Lisp string (in double-quotes) containing the field. If
- you provide the @samp{N} mode switch, all referenced elements will be numbers
- (non-number fields will be zero) and interpolated as Lisp numbers, without
- quotes. If you provide the @samp{L} flag, all fields will be interpolated
- literally, without quotes. I.e., if you want a reference to be interpreted
- as a string by the Lisp form, enclose the reference operator itself in
- double-quotes, like @code{"$3"}. Ranges are inserted as space-separated
- fields, so you can embed them in list or vector syntax.
- Here are a few examples---note how the @samp{N} mode is used when we do
- computations in Lisp:
- @table @code
- @item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
- Swap the first two characters of the content of column 1.
- @item '(+ $1 $2);N
- Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
- @item '(apply '+ '($1..$4));N
- Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
- @end table
- @node Durations and time values
- @subsection Durations and time values
- @cindex Duration, computing
- @cindex Time, computing
- @vindex org-table-duration-custom-format
- If you want to compute time values use the @code{T}, @code{t}, or @code{U}
- flag, either in Calc formulas or Elisp formulas:
- @example
- @group
- | Task 1 | Task 2 | Total |
- |---------+----------+----------|
- | 2:12 | 1:47 | 03:59:00 |
- | 2:12 | 1:47 | 03:59 |
- | 3:02:20 | -2:07:00 | 0.92 |
- #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;U::@@4$3=$1+$2;t
- @end group
- @end example
- Input duration values must be of the form @code{HH:MM[:SS]}, where seconds
- are optional. With the @code{T} flag, computed durations will be displayed
- as @code{HH:MM:SS} (see the first formula above). With the @code{U} flag,
- seconds will be omitted so that the result will be only @code{HH:MM} (see
- second formula above). Zero-padding of the hours field will depend upon the
- value of the variable @code{org-table-duration-hour-zero-padding}.
- With the @code{t} flag, computed durations will be displayed according to the
- value of the option @code{org-table-duration-custom-format}, which defaults
- to @code{'hours} and will display the result as a fraction of hours (see the
- third formula in the example above).
- Negative duration values can be manipulated as well, and integers will be
- considered as seconds in addition and subtraction.
- @node Field and range formulas
- @subsection Field and range formulas
- @cindex field formula
- @cindex range formula
- @cindex formula, for individual table field
- @cindex formula, for range of fields
- To assign a formula to a particular field, type it directly into the field,
- preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
- @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
- the formula will be stored as the formula for this field, evaluated, and the
- current field will be replaced with the result.
- @cindex #+TBLFM
- Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
- below the table. If you type the equation in the 4th field of the 3rd data
- line in the table, the formula will look like @samp{@@3$4=$1+$2}. When
- inserting/deleting/swapping columns and rows with the appropriate commands,
- @i{absolute references} (but not relative ones) in stored formulas are
- modified in order to still reference the same field. To avoid this, in
- particular in range references, anchor ranges at the table borders (using
- @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines using the
- @code{@@I} notation. Automatic adaptation of field references does of course
- not happen if you edit the table structure with normal editing
- commands---then you must fix the equations yourself.
- Instead of typing an equation into the field, you may also use the following
- command
- @table @kbd
- @orgcmd{C-u C-c =,org-table-eval-formula}
- Install a new formula for the current field. The command prompts for a
- formula with default taken from the @samp{#+TBLFM:} line, applies
- it to the current field, and stores it.
- @end table
- The left-hand side of a formula can also be a special expression in order to
- assign the formula to a number of different fields. There is no keyboard
- shortcut to enter such range formulas. To add them, use the formula editor
- (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
- directly.
- @table @code
- @item $2=
- Column formula, valid for the entire column. This is so common that Org
- treats these formulas in a special way, see @ref{Column formulas}.
- @item @@3=
- Row formula, applies to all fields in the specified row. @code{@@>=} means
- the last row.
- @item @@1$2..@@4$3=
- Range formula, applies to all fields in the given rectangular range. This
- can also be used to assign a formula to some but not all fields in a row.
- @item $name=
- Named field, see @ref{Advanced features}.
- @end table
- @node Column formulas
- @subsection Column formulas
- @cindex column formula
- @cindex formula, for table column
- When you assign a formula to a simple column reference like @code{$3=}, the
- same formula will be used in all fields of that column, with the following
- very convenient exceptions: (i) If the table contains horizontal separator
- hlines with rows above and below, everything before the first such hline is
- considered part of the table @emph{header} and will not be modified by column
- formulas. Therefore a header is mandatory when you use column formulas and
- want to add hlines to group rows, like for example to separate a total row at
- the bottom from the summand rows above. (ii) Fields that already get a value
- from a field/range formula will be left alone by column formulas. These
- conditions make column formulas very easy to use.
- To assign a formula to a column, type it directly into any field in the
- column, preceded by an equal sign, like @samp{=$1+$2}. When you press
- @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
- the formula will be stored as the formula for the current column, evaluated
- and the current field replaced with the result. If the field contains only
- @samp{=}, the previously stored formula for this column is used. For each
- column, Org will only remember the most recently used formula. In the
- @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
- left-hand side of a column formula cannot be the name of column, it must be
- the numeric column reference or @code{$>}.
- Instead of typing an equation into the field, you may also use the
- following command:
- @table @kbd
- @orgcmd{C-c =,org-table-eval-formula}
- Install a new formula for the current column and replace current field with
- the result of the formula. The command prompts for a formula, with default
- taken from the @samp{#+TBLFM} line, applies it to the current field and
- stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
- will apply it to that many consecutive fields in the current column.
- @end table
- @node Lookup functions
- @subsection Lookup functions
- @cindex lookup functions in tables
- @cindex table lookup functions
- Org has three predefined Emacs Lisp functions for lookups in tables.
- @table @code
- @item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
- @findex org-lookup-first
- Searches for the first element @code{S} in list @code{S-LIST} for which
- @lisp
- (PREDICATE VAL S)
- @end lisp
- is @code{t}; returns the value from the corresponding position in list
- @code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the
- parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
- order as the corresponding parameters are in the call to
- @code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If
- @code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
- is returned.
- @item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
- @findex org-lookup-last
- Similar to @code{org-lookup-first} above, but searches for the @i{last}
- element for which @code{PREDICATE} is @code{t}.
- @item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
- @findex org-lookup-all
- Similar to @code{org-lookup-first}, but searches for @i{all} elements for
- which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
- values. This function can not be used by itself in a formula, because it
- returns a list of values. However, powerful lookups can be built when this
- function is combined with other Emacs Lisp functions.
- @end table
- If the ranges used in these functions contain empty fields, the @code{E} mode
- for the formula should usually be specified: otherwise empty fields will not be
- included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
- in an incorrect mapping from an element of @code{S-LIST} to the corresponding
- element of @code{R-LIST}.
- These three functions can be used to implement associative arrays, count
- matching cells, rank results, group data etc. For practical examples
- see @uref{https://orgmode.org/worg/org-tutorials/org-lookups.html, this
- tutorial on Worg}.
- @node Editing and debugging formulas
- @subsection Editing and debugging formulas
- @cindex formula editing
- @cindex editing, of table formulas
- @vindex org-table-use-standard-references
- You can edit individual formulas in the minibuffer or directly in the field.
- Org can also prepare a special buffer with all active formulas of a table.
- When offering a formula for editing, Org converts references to the standard
- format (like @code{B3} or @code{D&}) if possible. If you prefer to only work
- with the internal format (like @code{@@3$2} or @code{$4}), configure the
- option @code{org-table-use-standard-references}.
- @table @kbd
- @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
- Edit the formula associated with the current column/field in the
- minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
- @orgcmd{C-u C-u C-c =,org-table-eval-formula}
- Re-insert the active formula (either a
- field formula, or a column formula) into the current field, so that you
- can edit it directly in the field. The advantage over editing in the
- minibuffer is that you can use the command @kbd{C-c ?}.
- @orgcmd{C-c ?,org-table-field-info}
- While editing a formula in a table field, highlight the field(s)
- referenced by the reference at the cursor position in the formula.
- @kindex C-c @}
- @findex org-table-toggle-coordinate-overlays
- @item C-c @}
- Toggle the display of row and column numbers for a table, using overlays
- (@command{org-table-toggle-coordinate-overlays}). These are updated each
- time the table is aligned; you can force it with @kbd{C-c C-c}.
- @kindex C-c @{
- @findex org-table-toggle-formula-debugger
- @item C-c @{
- Toggle the formula debugger on and off
- (@command{org-table-toggle-formula-debugger}). See below.
- @orgcmd{C-c ',org-table-edit-formulas}
- Edit all formulas for the current table in a special buffer, where the
- formulas will be displayed one per line. If the current field has an
- active formula, the cursor in the formula editor will mark it.
- While inside the special buffer, Org will automatically highlight
- any field or range reference at the cursor position. You may edit,
- remove and add formulas, and use the following commands:
- @table @kbd
- @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
- Exit the formula editor and store the modified formulas. With @kbd{C-u}
- prefix, also apply the new formulas to the entire table.
- @orgcmd{C-c C-q,org-table-fedit-abort}
- Exit the formula editor without installing changes.
- @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
- Toggle all references in the formula editor between standard (like
- @code{B3}) and internal (like @code{@@3$2}).
- @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
- Pretty-print or indent Lisp formula at point. When in a line containing
- a Lisp formula, format the formula according to Emacs Lisp rules.
- Another @key{TAB} collapses the formula back again. In the open
- formula, @key{TAB} re-indents just like in Emacs Lisp mode.
- @orgcmd{M-@key{TAB},lisp-complete-symbol}
- Complete Lisp symbols, just like in Emacs Lisp mode.@footnote{Many desktops
- intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
- @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}
- @kindex S-@key{up}
- @kindex S-@key{down}
- @kindex S-@key{left}
- @kindex S-@key{right}
- @findex org-table-fedit-ref-up
- @findex org-table-fedit-ref-down
- @findex org-table-fedit-ref-left
- @findex org-table-fedit-ref-right
- @item S-@key{up}/@key{down}/@key{left}/@key{right}
- Shift the reference at point. For example, if the reference is
- @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
- This also works for relative references and for hline references.
- @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
- Move the test line for column formulas in the Org buffer up and
- down.
- @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
- Scroll the window displaying the table.
- @kindex C-c @}
- @findex org-table-toggle-coordinate-overlays
- @item C-c @}
- Turn the coordinate grid in the table on and off.
- @end table
- @end table
- Making a table field blank does not remove the formula associated with
- the field, because that is stored in a different line (the @samp{#+TBLFM}
- line)---during the next recalculation the field will be filled again.
- To remove a formula from a field, you have to give an empty reply when
- prompted for the formula, or to edit the @samp{#+TBLFM} line.
- @kindex C-c C-c
- You may edit the @samp{#+TBLFM} directly and re-apply the changed
- equations with @kbd{C-c C-c} in that line or with the normal
- recalculation commands in the table.
- @anchor{Using multiple #+TBLFM lines}
- @subsubheading Using multiple #+TBLFM lines
- @cindex #+TBLFM line, multiple
- @cindex #+TBLFM
- @cindex #+TBLFM, switching
- @kindex C-c C-c
- You may apply the formula temporarily. This is useful when you
- switch the formula. Place multiple @samp{#+TBLFM} lines right
- after the table, and then press @kbd{C-c C-c} on the formula to
- apply. Here is an example:
- @example
- | x | y |
- |---+---|
- | 1 | |
- | 2 | |
- #+TBLFM: $2=$1*1
- #+TBLFM: $2=$1*2
- @end example
- @noindent
- Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
- @example
- | x | y |
- |---+---|
- | 1 | 2 |
- | 2 | 4 |
- #+TBLFM: $2=$1*1
- #+TBLFM: $2=$1*2
- @end example
- @noindent
- Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
- will get the following result of applying only the first @samp{#+TBLFM} line.
- @example
- | x | y |
- |---+---|
- | 1 | 1 |
- | 2 | 2 |
- #+TBLFM: $2=$1*1
- #+TBLFM: $2=$1*2
- @end example
- @subsubheading Debugging formulas
- @cindex formula debugging
- @cindex debugging, of table formulas
- When the evaluation of a formula leads to an error, the field content
- becomes the string @samp{#ERROR}. If you would like see what is going
- on during variable substitution and calculation in order to find a bug,
- turn on formula debugging in the @code{Tbl} menu and repeat the
- calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
- field. Detailed information will be displayed.
- @node Updating the table
- @subsection Updating the table
- @cindex recomputing table fields
- @cindex updating, table
- Recalculation of a table is normally not automatic, but needs to be
- triggered by a command. See @ref{Advanced features}, for a way to make
- recalculation at least semi-automatic.
- In order to recalculate a line of a table or the entire table, use the
- following commands:
- @table @kbd
- @orgcmd{C-c *,org-table-recalculate}
- Recalculate the current row by first applying the stored column formulas
- from left to right, and all field/range formulas in the current row.
- @c
- @kindex C-u C-c *
- @item C-u C-c *
- @kindex C-u C-c C-c
- @itemx C-u C-c C-c
- Recompute the entire table, line by line. Any lines before the first
- hline are left alone, assuming that these are part of the table header.
- @c
- @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
- Iterate the table by recomputing it until no further changes occur.
- This may be necessary if some computed fields use the value of other
- fields that are computed @i{later} in the calculation sequence.
- @item M-x org-table-recalculate-buffer-tables RET
- @findex org-table-recalculate-buffer-tables
- Recompute all tables in the current buffer.
- @item M-x org-table-iterate-buffer-tables RET
- @findex org-table-iterate-buffer-tables
- Iterate all tables in the current buffer, in order to converge table-to-table
- dependencies.
- @end table
- @node Advanced features
- @subsection Advanced features
- If you want the recalculation of fields to happen automatically, or if you
- want to be able to assign @i{names}@footnote{Such names must start by an
- alphabetic character and use only alphanumeric/underscore characters.} to
- fields and columns, you need to reserve the first column of the table for
- special marking characters.
- @table @kbd
- @orgcmd{C-#,org-table-rotate-recalc-marks}
- Rotate the calculation mark in first column through the states @samp{ },
- @samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
- change all marks in the region.
- @end table
- Here is an example of a table that collects exam results of students and
- makes use of these features:
- @example
- @group
- |---+---------+--------+--------+--------+-------+------|
- | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
- |---+---------+--------+--------+--------+-------+------|
- | ! | | P1 | P2 | P3 | Tot | |
- | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
- | ^ | | m1 | m2 | m3 | mt | |
- |---+---------+--------+--------+--------+-------+------|
- | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
- | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
- |---+---------+--------+--------+--------+-------+------|
- | | Average | | | | 25.0 | |
- | ^ | | | | | at | |
- | $ | max=50 | | | | | |
- |---+---------+--------+--------+--------+-------+------|
- #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
- @end group
- @end example
- @noindent @b{Important}: please note that for these special tables,
- recalculating the table with @kbd{C-u C-c *} will only affect rows that
- are marked @samp{#} or @samp{*}, and fields that have a formula assigned
- to the field itself. The column formulas are not applied in rows with
- empty first field.
- @cindex marking characters, tables
- The marking characters have the following meaning:
- @table @samp
- @item !
- The fields in this line define names for the columns, so that you may
- refer to a column as @samp{$Tot} instead of @samp{$6}.
- @item ^
- This row defines names for the fields @emph{above} the row. With such
- a definition, any formula in the table may use @samp{$m1} to refer to
- the value @samp{10}. Also, if you assign a formula to a names field, it
- will be stored as @samp{$name=...}.
- @item _
- Similar to @samp{^}, but defines names for the fields in the row
- @emph{below}.
- @item $
- Fields in this row can define @emph{parameters} for formulas. For
- example, if a field in a @samp{$} row contains @samp{max=50}, then
- formulas in this table can refer to the value 50 using @samp{$max}.
- Parameters work exactly like constants, only that they can be defined on
- a per-table basis.
- @item #
- Fields in this row are automatically recalculated when pressing
- @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
- is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
- lines will be left alone by this command.
- @item *
- Selects this line for global recalculation with @kbd{C-u C-c *}, but
- not for automatic recalculation. Use this when automatic
- recalculation slows down editing too much.
- @item @w{ }
- Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
- All lines that should be recalculated should be marked with @samp{#}
- or @samp{*}.
- @item /
- Do not export this line. Useful for lines that contain the narrowing
- @samp{<N>} markers or column group markers.
- @end table
- Finally, just to whet your appetite for what can be done with the
- fantastic @file{calc.el} package, here is a table that computes the Taylor
- series of degree @code{n} at location @code{x} for a couple of
- functions.
- @example
- @group
- |---+-------------+---+-----+--------------------------------------|
- | | Func | n | x | Result |
- |---+-------------+---+-----+--------------------------------------|
- | # | exp(x) | 1 | x | 1 + x |
- | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
- | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
- | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
- | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
- | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
- |---+-------------+---+-----+--------------------------------------|
- #+TBLFM: $5=taylor($2,$4,$3);n3
- @end group
- @end example
- @node Org-Plot
- @section Org-Plot
- @cindex graph, in tables
- @cindex plot tables using Gnuplot
- @cindex #+PLOT
- Org-Plot can produce graphs of information stored in org tables, either
- graphically or in ASCII-art.
- @subheading Graphical plots using @file{Gnuplot}
- Org-Plot produces 2D and 3D graphs using @file{Gnuplot}
- @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
- @uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
- that you have both Gnuplot and Gnuplot mode installed on your system, then
- call @kbd{C-c " g} or @kbd{M-x org-plot/gnuplot @key{RET}} on the following
- table.
- @example
- @group
- #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
- | Sede | Max cites | H-index |
- |-----------+-----------+---------|
- | Chile | 257.72 | 21.39 |
- | Leeds | 165.77 | 19.68 |
- | Sao Paolo | 71.00 | 11.50 |
- | Stockholm | 134.19 | 14.33 |
- | Morelia | 257.56 | 17.67 |
- @end group
- @end example
- Notice that Org Plot is smart enough to apply the table's headers as labels.
- Further control over the labels, type, content, and appearance of plots can
- be exercised through the @code{#+PLOT:} lines preceding a table. See below
- for a complete list of Org-plot options. The @code{#+PLOT:} lines are
- optional. For more information and examples see the Org-plot tutorial at
- @uref{https://orgmode.org/worg/org-tutorials/org-plot.html}.
- @subsubheading Plot Options
- @table @code
- @item set
- Specify any @command{gnuplot} option to be set when graphing.
- @item title
- Specify the title of the plot.
- @item ind
- Specify which column of the table to use as the @code{x} axis.
- @item deps
- Specify the columns to graph as a Lisp style list, surrounded by parentheses
- and separated by spaces for example @code{dep:(3 4)} to graph the third and
- fourth columns (defaults to graphing all other columns aside from the @code{ind}
- column).
- @item type
- Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
- @item with
- Specify a @code{with} option to be inserted for every col being plotted
- (e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
- Defaults to @code{lines}.
- @item file
- If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
- @item labels
- List of labels to be used for the @code{deps} (defaults to the column headers
- if they exist).
- @item line
- Specify an entire line to be inserted in the Gnuplot script.
- @item map
- When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
- flat mapping rather than a @code{3d} slope.
- @item timefmt
- Specify format of Org mode timestamps as they will be parsed by Gnuplot.
- Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
- @item script
- If you want total control, you can specify a script file (place the file name
- between double-quotes) which will be used to plot. Before plotting, every
- instance of @code{$datafile} in the specified script will be replaced with
- the path to the generated data file. Note: even if you set this option, you
- may still want to specify the plot type, as that can impact the content of
- the data file.
- @end table
- @subheading ASCII bar plots
- While the cursor is on a column, typing @kbd{C-c " a} or
- @kbd{M-x orgtbl-ascii-plot @key{RET}} create a new column containing an
- ASCII-art bars plot. The plot is implemented through a regular column
- formula. When the source column changes, the bar plot may be updated by
- refreshing the table, for example typing @kbd{C-u C-c *}.
- @example
- @group
- | Sede | Max cites | |
- |---------------+-----------+--------------|
- | Chile | 257.72 | WWWWWWWWWWWW |
- | Leeds | 165.77 | WWWWWWWh |
- | Sao Paolo | 71.00 | WWW; |
- | Stockholm | 134.19 | WWWWWW: |
- | Morelia | 257.56 | WWWWWWWWWWWH |
- | Rochefourchat | 0.00 | |
- #+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12)
- @end group
- @end example
- The formula is an elisp call:
- @lisp
- (orgtbl-ascii-draw COLUMN MIN MAX WIDTH)
- @end lisp
- @table @code
- @item COLUMN
- is a reference to the source column.
- @item MIN MAX
- are the minimal and maximal values displayed. Sources values
- outside this range are displayed as @samp{too small}
- or @samp{too large}.
- @item WIDTH
- is the width in characters of the bar-plot. It defaults to @samp{12}.
- @end table
- @node Hyperlinks
- @chapter Hyperlinks
- @cindex hyperlinks
- Like HTML, Org provides links inside a file, external links to
- other files, Usenet articles, emails, and much more.
- @menu
- * Link format:: How links in Org are formatted
- * Internal links:: Links to other places in the current file
- * External links:: URL-like links to the world
- * Handling links:: Creating, inserting and following
- * 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
- @end menu
- @node Link format
- @section Link format
- @cindex link format
- @cindex format, of links
- Org will recognize plain URL-like links and activate them as
- clickable links. The general link format, however, looks like this:
- @example
- [[link][description]] @r{or alternatively} [[link]]
- @end example
- @noindent
- Once a link in the buffer is complete (all brackets present), Org
- will change the display so that @samp{description} is displayed instead
- of @samp{[[link][description]]} and @samp{link} is displayed instead of
- @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
- which by default is an underlined face. You can directly edit the
- visible part of a link. Note that this can be either the @samp{link}
- part (if there is no description) or the @samp{description} part. To
- edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
- cursor on the link.
- If you place the cursor at the beginning or just behind the end of the
- displayed text and press @key{BACKSPACE}, you will remove the
- (invisible) bracket at that location. This makes the link incomplete
- and the internals are again displayed as plain text. Inserting the
- missing bracket hides the link internals again. To show the
- internal structure of all links, use the menu entry
- @code{Org->Hyperlinks->Literal links}.
- @node Internal links
- @section Internal links
- @cindex internal links
- @cindex links, internal
- @cindex targets, for links
- @cindex property, CUSTOM_ID
- If the link does not look like a URL, it is considered to be internal in the
- current file. The most important case is a link like
- @samp{[[#my-custom-id]]} which will link to the entry with the
- @code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
- to make sure these custom IDs are unique in a file.
- Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
- lead to a text search in the current file.
- The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
- or with a mouse click (@pxref{Handling links}). Links to custom IDs will
- point to the corresponding headline. The preferred match for a text link is
- a @i{dedicated target}: the same string in double angular brackets, like
- @samp{<<My Target>>}.
- @cindex #+NAME
- If no dedicated target exists, the link will then try to match the exact name
- of an element within the buffer. Naming is done with the @code{#+NAME}
- keyword, which has to be put in the line before the element it refers to, as
- in the following example
- @example
- #+NAME: My Target
- | a | table |
- |----+------------|
- | of | four cells |
- @end example
- If none of the above succeeds, Org will search for a headline that is exactly
- the link text but may also include a TODO keyword and tags@footnote{To insert
- a link targeting a headline, in-buffer completion can be used. Just type
- a star followed by a few optional letters into the buffer and press
- @kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
- completions.}.
- During export, internal links will be used to mark objects and assign them
- a number. Marked objects will then be referenced by links pointing to them.
- In particular, links without a description will appear as the number assigned
- to the marked object@footnote{When targeting a @code{#+NAME} keyword,
- @code{#+CAPTION} keyword is mandatory in order to get proper numbering
- (@pxref{Images and tables}).}. In the following excerpt from an Org buffer
- @example
- - one item
- - <<target>>another item
- Here we refer to item [[target]].
- @end example
- @noindent
- The last sentence will appear as @samp{Here we refer to item 2} when
- exported.
- In non-Org files, the search will look for the words in the link text. In
- the above example the search would be for @samp{my target}.
- Following a link pushes a mark onto Org's own mark ring. You can
- return to the previous position with @kbd{C-c &}. Using this command
- several times in direct succession goes back to positions recorded
- earlier.
- @menu
- * Radio targets:: Make targets trigger links in plain text
- @end menu
- @node Radio targets
- @subsection Radio targets
- @cindex radio targets
- @cindex targets, radio
- @cindex links, radio targets
- Org can automatically turn any occurrences of certain target names
- in normal text into a link. So without explicitly creating a link, the
- text connects to the target radioing its position. Radio targets are
- enclosed by triple angular brackets. For example, a target @samp{<<<My
- Target>>>} causes each occurrence of @samp{my target} in normal text to
- become activated as a link. The Org file is scanned automatically
- for radio targets only when the file is first loaded into Emacs. To
- update the target list during editing, press @kbd{C-c C-c} with the
- cursor on or at a target.
- @node External links
- @section External links
- @cindex links, external
- @cindex external links
- @cindex Gnus links
- @cindex BBDB links
- @cindex IRC links
- @cindex URL links
- @cindex file links
- @cindex RMAIL links
- @cindex MH-E links
- @cindex USENET links
- @cindex SHELL links
- @cindex Info links
- @cindex Elisp links
- Org supports links to files, websites, Usenet and email messages, BBDB
- database entries and links to both IRC conversations and their logs.
- External links are URL-like locators. They start with a short identifying
- string followed by a colon. There can be no space after the colon. The
- following list shows examples for each link type.
- @example
- http://www.astro.uva.nl/~dominik @r{on the web}
- doi:10.1000/182 @r{DOI for an electronic resource}
- file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
- /home/dominik/images/jupiter.jpg @r{same as above}
- file:papers/last.pdf @r{file, relative path}
- ./papers/last.pdf @r{same as above}
- file:/ssh:myself@@some.where:papers/last.pdf @r{file, path on remote machine}
- /ssh:myself@@some.where:papers/last.pdf @r{same as above}
- file:sometextfile::NNN @r{file, jump to line number}
- file:projects.org @r{another Org file}
- file:projects.org::some words @r{text search in Org file}@footnote{
- The actual behavior of the search will depend on the value of
- the option @code{org-link-search-must-match-exact-headline}. If its value
- is @code{nil}, then a fuzzy text search will be done. If it is @code{t}, then only
- the exact headline will be matched, ignoring spaces and cookies. If the
- value is @code{query-to-create}, then an exact headline will be searched; if
- it is not found, then the user will be queried to create it.}
- file:projects.org::*task title @r{heading search in Org file}@footnote{
- Headline searches always match the exact headline, ignoring
- spaces and cookies. If the headline is not found and the value of the option
- @code{org-link-search-must-match-exact-headline} is @code{query-to-create},
- then the user will be queried to create it.}
- docview:papers/last.pdf::NNN @r{open in doc-view mode at page}
- id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
- news:comp.emacs @r{Usenet link}
- mailto:adent@@galaxy.net @r{Mail link}
- mhe:folder @r{MH-E folder link}
- mhe:folder#id @r{MH-E message link}
- rmail:folder @r{RMAIL folder link}
- rmail:folder#id @r{RMAIL message link}
- gnus:group @r{Gnus group link}
- gnus:group#id @r{Gnus article link}
- bbdb:R.*Stallman @r{BBDB link (with regexp)}
- irc:/irc.com/#emacs/bob @r{IRC link}
- info:org#External links @r{Info node or index link}
- shell:ls *.org @r{A shell command}
- elisp:org-agenda @r{Interactive Elisp command}
- elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
- @end example
- @cindex VM links
- @cindex WANDERLUST links
- On top of these built-in link types, some are available through the
- @code{contrib/} directory (@pxref{Installation}). For example, these links
- to VM or Wanderlust messages are available when you load the corresponding
- libraries from the @code{contrib/} directory:
- @example
- vm:folder @r{VM folder link}
- vm:folder#id @r{VM message link}
- vm://myself@@some.where.org/folder#id @r{VM on remote machine}
- vm-imap:account:folder @r{VM IMAP folder link}
- vm-imap:account:folder#id @r{VM IMAP message link}
- wl:folder @r{WANDERLUST folder link}
- wl:folder#id @r{WANDERLUST message link}
- @end example
- For customizing Org to add new link types @ref{Adding hyperlink types}.
- A link should be enclosed in double brackets and may contain a descriptive
- text to be displayed instead of the URL (@pxref{Link format}), for example:
- @example
- [[https://www.gnu.org/software/emacs/][GNU Emacs]]
- @end example
- @noindent
- If the description is a file name or URL that points to an image, HTML
- export (@pxref{HTML export}) will inline the image as a clickable
- button. If there is no description at all and the link points to an
- image,
- that image will be inlined into the exported HTML file.
- @cindex square brackets, around links
- @cindex plain text external links
- Org also finds external links in the normal text and activates them
- as links. If spaces must be part of the link (for example in
- @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
- about the end of the link, enclose them in square brackets.
- @node Handling links
- @section Handling links
- @cindex links, handling
- Org provides methods to create a link in the correct syntax, to
- insert it into an Org file, and to follow the link.
- @table @kbd
- @orgcmd{C-c l,org-store-link}
- @cindex storing links
- Store a link to the current location. This is a @emph{global} command (you
- must create the key binding yourself) which can be used in any buffer to
- create a link. The link will be stored for later insertion into an Org
- buffer (see below). What kind of link will be created depends on the current
- buffer:
- @b{Org mode buffers}@*
- For Org files, if there is a @samp{<<target>>} at the cursor, the link points
- to the target. Otherwise it points to the current headline, which will also
- be the description@footnote{If the headline contains a timestamp, it will be
- removed from the link and result in a wrong link---you should avoid putting
- timestamp in the headline.}.
- @vindex org-id-link-to-org-use-id
- @cindex property, CUSTOM_ID
- @cindex property, ID
- If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
- will be stored. In addition or alternatively (depending on the value of
- @code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
- be created and/or used to construct a link@footnote{The library
- @file{org-id.el} must first be loaded, either through @code{org-customize} by
- enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
- 'org-id)} in your Emacs init file.}. So using this command in Org buffers
- will potentially create two links: a human-readable from the custom ID, and
- one that is globally unique and works even if the entry is moved from file to
- file. Later, when inserting the link, you need to decide which one to use.
- @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
- Pretty much all Emacs mail clients are supported. The link will point to the
- current article, or, in some GNUS buffers, to the group. The description is
- constructed from the author and the subject.
- @b{Web browsers: Eww, W3 and W3M}@*
- Here the link will be the current URL, with the page title as description.
- @b{Contacts: BBDB}@*
- Links created in a BBDB buffer will point to the current entry.
- @b{Chat: IRC}@*
- @vindex org-irc-link-to-logs
- For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
- a @samp{file:/} style link to the relevant point in the logs for the current
- conversation is created. Otherwise an @samp{irc:/} style link to the
- user/channel/server under the point will be stored.
- @b{Other files}@*
- For any other files, the link will point to the file, with a search string
- (@pxref{Search options}) pointing to the contents of the current line. If
- there is an active region, the selected words will form the basis of the
- search string. If the automatically created link is not working correctly or
- accurately enough, you can write custom functions to select the search string
- and to do the search for particular file types---see @ref{Custom searches}.
- The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
- @b{Agenda view}@*
- When the cursor is in an agenda view, the created link points to the
- entry referenced by the current line.
- @c
- @orgcmd{C-c C-l,org-insert-link}
- @cindex link completion
- @cindex completion, of links
- @cindex inserting links
- @vindex org-keep-stored-link-after-insertion
- @vindex org-link-parameters
- Insert a link@footnote{Note that you don't have to use this command to
- insert a link. Links in Org are plain text, and you can type or paste them
- straight into the buffer. By using this command, the links are automatically
- enclosed in double brackets, and you will be asked for the optional
- descriptive text.}. This prompts for a link to be inserted into the buffer.
- You can just type a link, using text for an internal link, or one of the link
- type prefixes mentioned in the examples above. The link will be inserted
- into the buffer@footnote{After insertion of a stored link, the link will be
- removed from the list of stored links. To keep it in the list later use, use
- a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
- @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
- If some text was selected when this command is called, the selected text
- becomes the default description.
- @b{Inserting stored links}@*
- All links stored during the
- current session are part of the history for this prompt, so you can access
- them with @key{up} and @key{down} (or @kbd{M-p/n}).
- @b{Completion support}@* Completion with @key{TAB} will help you to insert
- valid link prefixes like @samp{https:}, including the prefixes
- defined through link abbreviations (@pxref{Link abbreviations}). If you
- press @key{RET} after inserting only the @var{prefix}, Org will offer
- specific completion support for some link types@footnote{This works if
- a completion function is defined in the @samp{:complete} property of a link
- in @code{org-link-parameters}.} For example, if you type @kbd{file
- @key{RET}}, file name completion (alternative access: @kbd{C-u C-c C-l}, see
- below) will be offered, and after @kbd{bbdb @key{RET}} you can complete
- contact names.
- @orgkey C-u C-c C-l
- @cindex file name completion
- @cindex completion, of file names
- When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
- a file will be inserted and you may use file name completion to select
- the name of the file. The path to the file is inserted relative to the
- directory of the current Org file, if the linked file is in the current
- directory or in a sub-directory of it, or if the path is written relative
- to the current directory using @samp{../}. Otherwise an absolute path
- is used, if possible with @samp{~/} for your home directory. You can
- force an absolute path with two @kbd{C-u} prefixes.
- @c
- @item C-c C-l @ @r{(with cursor on existing link)}
- When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
- link and description parts of the link.
- @c
- @cindex following links
- @orgcmd{C-c C-o,org-open-at-point}
- @vindex org-file-apps
- @vindex org-link-frame-setup
- Open link at point. This will launch a web browser for URLs (using
- @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
- the corresponding links, and execute the command in a shell link. When the
- cursor is on an internal link, this command runs the corresponding search.
- When the cursor is on a TAG list in a headline, it creates the corresponding
- TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
- date. Furthermore, it will visit text and remote files in @samp{file:} links
- with Emacs and select a suitable application for local non-text files.
- Classification of files is based on file extension only. See option
- @code{org-file-apps}. If you want to override the default application and
- visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
- opening in Emacs, use a @kbd{C-u C-u} prefix.@*
- If the cursor is on a headline, but not on a link, offer all links in the
- headline and entry text. If you want to setup the frame configuration for
- following links, customize @code{org-link-frame-setup}.
- @orgkey @key{RET}
- @vindex org-return-follows-link
- When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
- the link at point.
- @c
- @kindex mouse-2
- @kindex mouse-1
- @item mouse-2
- @itemx mouse-1
- On links, @kbd{mouse-1} and @kbd{mouse-2} will open the link just as @kbd{C-c
- C-o} would.
- @c
- @kindex mouse-3
- @item mouse-3
- @vindex org-display-internal-link-with-indirect-buffer
- Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
- internal links to be displayed in another window@footnote{See the
- option @code{org-display-internal-link-with-indirect-buffer}}.
- @c
- @orgcmd{C-c C-x C-v,org-toggle-inline-images}
- @cindex inlining images
- @cindex images, inlining
- @vindex org-startup-with-inline-images
- @cindex @code{inlineimages}, STARTUP keyword
- @cindex @code{noinlineimages}, STARTUP keyword
- Toggle the inline display of linked images. Normally this will only inline
- images that have no description part in the link, i.e., images that will also
- be inlined during export. When called with a prefix argument, also display
- images that do have a link description. You can ask for inline images to be
- displayed at startup by configuring the variable
- @code{org-startup-with-inline-images}@footnote{with corresponding
- @code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
- @orgcmd{C-c %,org-mark-ring-push}
- @cindex mark ring
- Push the current position onto the mark ring, to be able to return
- easily. Commands following an internal link do this automatically.
- @c
- @orgcmd{C-c &,org-mark-ring-goto}
- @cindex links, returning to
- Jump back to a recorded position. A position is recorded by the
- commands following internal links, and by @kbd{C-c %}. Using this
- command several times in direct succession moves through a ring of
- previously recorded positions.
- @c
- @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
- @cindex links, finding next/previous
- Move forward/backward to the next link in the buffer. At the limit of
- the buffer, the search fails once, and then wraps around. The key
- bindings for this are really too long; you might want to bind this also
- to @kbd{C-n} and @kbd{C-p}
- @lisp
- (add-hook 'org-load-hook
- (lambda ()
- (define-key org-mode-map "\C-n" 'org-next-link)
- (define-key org-mode-map "\C-p" 'org-previous-link)))
- @end lisp
- @end table
- @node Using links outside Org
- @section Using links outside Org
- You can insert and follow links that have Org syntax not only in
- Org, but in any Emacs buffer. For this, you should create two
- global commands, like this (please select suitable global keys
- yourself):
- @lisp
- (global-set-key "\C-c L" 'org-insert-link-global)
- (global-set-key "\C-c o" 'org-open-at-point-global)
- @end lisp
- @node Link abbreviations
- @section Link abbreviations
- @cindex link abbreviations
- @cindex abbreviation, links
- Long URLs can be cumbersome to type, and often many similar links are
- needed in a document. For this you can use link abbreviations. An
- abbreviated link looks like this
- @example
- [[linkword:tag][description]]
- @end example
- @noindent
- @vindex org-link-abbrev-alist
- where the tag is optional.
- The @i{linkword} must be a word, starting with a letter, followed by
- letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved
- according to the information in the variable @code{org-link-abbrev-alist}
- that relates the linkwords to replacement text. Here is an example:
- @smalllisp
- @group
- (setq org-link-abbrev-alist
- '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
- ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
- ("google" . "http://www.google.com/search?q=")
- ("gmap" . "http://maps.google.com/maps?q=%s")
- ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
- ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
- @end group
- @end smalllisp
- If the replacement text contains the string @samp{%s}, it will be
- replaced with the tag. Using @samp{%h} instead of @samp{%s} will
- url-encode the tag (see the example above, where we need to encode
- the URL parameter.) Using @samp{%(my-function)} will pass the tag
- to a custom function, and replace it by the resulting string.
- If the replacement text doesn't contain any specifier, the tag will simply be
- appended in order to create the link.
- Instead of a string, you may also specify a function that will be
- called with the tag as the only argument to create the link.
- With the above setting, you could link to a specific bug with
- @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
- @code{[[google:OrgMode]]}, show the map location of the Free Software
- Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
- @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
- what the Org author is doing besides Emacs hacking with
- @code{[[ads:Dominik,C]]}.
- If you need special abbreviations just for a single Org buffer, you
- can define them in the file with
- @cindex #+LINK
- @example
- #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
- #+LINK: google http://www.google.com/search?q=%s
- @end example
- @noindent
- In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
- complete link abbreviations. You may also define a function that implements
- special (e.g., completion) support for inserting such a link with @kbd{C-c
- C-l}. Such a function should not accept any arguments, and return the full
- link with prefix. You can add a completion function to a link like this:
- @lisp
- (org-link-set-parameters ``type'' :complete #'some-function)
- @end lisp
- @node Search options
- @section Search options in file links
- @cindex search option in file links
- @cindex file links, searching
- File links can contain additional information to make Emacs jump to a
- particular location in the file when following a link. This can be a
- line number or a search option after a double@footnote{For backward
- compatibility, line numbers can also follow a single colon.} colon. For
- example, when the command @kbd{C-c l} creates a link (@pxref{Handling
- links}) to a file, it encodes the words in the current line as a search
- string that can be used to find this line back later when following the
- link with @kbd{C-c C-o}.
- Here is the syntax of the different ways to attach a search to a file
- link, together with an explanation:
- @example
- [[file:~/code/main.c::255]]
- [[file:~/xx.org::My Target]]
- [[file:~/xx.org::*My Target]]
- [[file:~/xx.org::#my-custom-id]]
- [[file:~/xx.org::/regexp/]]
- @end example
- @table @code
- @item 255
- Jump to line 255.
- @item My Target
- Search for a link target @samp{<<My Target>>}, or do a text search for
- @samp{my target}, similar to the search in internal links, see
- @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
- link will become an HTML reference to the corresponding named anchor in
- the linked file.
- @item *My Target
- In an Org file, restrict search to headlines.
- @item #my-custom-id
- Link to a heading with a @code{CUSTOM_ID} property
- @item /regexp/
- Do a regular expression search for @code{regexp}. This uses the Emacs
- command @code{occur} to list all matches in a separate window. If the
- target file is in Org mode, @code{org-occur} is used to create a
- sparse tree with the matches.
- @c If the target file is a directory,
- @c @code{grep} will be used to search all files in the directory.
- @end table
- As a degenerate case, a file link with an empty file name can be used
- to search the current file. For example, @code{[[file:::find me]]} does
- a search for @samp{find me} in the current file, just as
- @samp{[[find me]]} would.
- @node Custom searches
- @section Custom Searches
- @cindex custom search strings
- @cindex search strings, custom
- The default mechanism for creating search strings and for doing the
- actual search related to a file link may not work correctly in all
- cases. For example, Bib@TeX{} database files have many entries like
- @samp{year="1993"} which would not result in good search strings,
- because the only unique identification for a Bib@TeX{} entry is the
- citation key.
- @vindex org-create-file-search-functions
- @vindex org-execute-file-search-functions
- If you come across such a problem, you can write custom functions to set
- the right search string for a particular file type, and to do the search
- for the string in the file. Using @code{add-hook}, these functions need
- to be added to the hook variables
- @code{org-create-file-search-functions} and
- @code{org-execute-file-search-functions}. See the docstring for these
- variables for more information. Org actually uses this mechanism
- for Bib@TeX{} database files, and you can use the corresponding code as
- an implementation example. See the file @file{org-bibtex.el}.
- @node TODO items
- @chapter TODO items
- @cindex TODO items
- Org mode does not maintain TODO lists as separate documents@footnote{Of
- course, you can make a document that contains only long lists of TODO items,
- but this is not required.}. Instead, TODO items are an integral part of the
- notes file, because TODO items usually come up while taking notes! With Org
- mode, simply mark any entry in a tree as being a TODO item. In this way,
- information is not duplicated, and the entire context from which the TODO
- item emerged is always present.
- Of course, this technique for managing TODO items scatters them
- throughout your notes file. Org mode compensates for this by providing
- methods to give you an overview of all the things that you have to do.
- @menu
- * TODO basics:: Marking and displaying TODO entries
- * TODO extensions:: Workflow 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
- @end menu
- @node TODO basics
- @section Basic TODO functionality
- Any headline becomes a TODO item when it starts with the word
- @samp{TODO}, for example:
- @example
- *** TODO Write letter to Sam Fortune
- @end example
- @noindent
- The most important commands to work with TODO entries are:
- @table @kbd
- @orgcmd{C-c C-t,org-todo}
- @cindex cycling, of TODO states
- @vindex org-use-fast-todo-selection
- Rotate the TODO state of the current item among
- @example
- ,-> (unmarked) -> TODO -> DONE --.
- '--------------------------------'
- @end example
- If TODO keywords have fast access keys (see @ref{Fast access to TODO
- states}), you will be prompted for a TODO keyword through the fast selection
- interface; this is the default behavior when
- @code{org-use-fast-todo-selection} is non-@code{nil}.
- The same rotation can also be done ``remotely'' from agenda buffers with the
- @kbd{t} command key (@pxref{Agenda commands}).
- @orgkey{C-u C-c C-t}
- When TODO keywords have no selection keys, select a specific keyword using
- completion; otherwise force cycling through TODO states with no prompt. When
- @code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
- selection interface.
- @kindex S-@key{right}
- @kindex S-@key{left}
- @item S-@key{right} @ @r{/} @ S-@key{left}
- @vindex org-treat-S-cursor-todo-selection-as-state-change
- Select the following/preceding TODO state, similar to cycling. Useful
- mostly if more than two TODO states are possible (@pxref{TODO
- extensions}). See also @ref{Conflicts}, for a discussion of the interaction
- with @code{shift-selection-mode}. See also the variable
- @code{org-treat-S-cursor-todo-selection-as-state-change}.
- @orgcmd{C-c / t,org-show-todo-tree}
- @cindex sparse tree, for TODO
- @vindex org-todo-keywords
- View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
- entire buffer, but shows all TODO items (with not-DONE state) and the
- headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
- / T}), search for a specific TODO@. You will be prompted for the keyword,
- and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
- entries that match any one of these keywords. With a numeric prefix argument
- N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
- With two prefix arguments, find all TODO states, both un-done and done.
- @orgcmd{C-c a t,org-todo-list}
- Show the global TODO list. Collects the TODO items (with not-DONE states)
- from all agenda files (@pxref{Agenda views}) into a single buffer. The new
- buffer will be in @code{agenda-mode}, which provides commands to examine and
- manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
- @xref{Global TODO list}, for more information.
- @orgcmd{S-M-@key{RET},org-insert-todo-heading}
- Insert a new TODO entry below the current one.
- @end table
- @noindent
- @vindex org-todo-state-tags-triggers
- Changing a TODO state can also trigger tag changes. See the docstring of the
- option @code{org-todo-state-tags-triggers} for details.
- @node TODO extensions
- @section Extended use of TODO keywords
- @cindex extended TODO keywords
- @vindex org-todo-keywords
- By default, marked TODO entries have one of only two states: TODO and
- DONE@. Org mode allows you to classify TODO items in more complex ways
- with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
- special setup, the TODO keyword system can work differently in different
- files.
- Note that @i{tags} are another way to classify headlines in general and
- TODO items in particular (@pxref{Tags}).
- @menu
- * 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 a state
- * Per-file keywords:: Different files, different requirements
- * Faces for TODO keywords:: Highlighting states
- * TODO dependencies:: When one task needs to wait for others
- @end menu
- @node Workflow states
- @subsection TODO keywords as workflow states
- @cindex TODO workflow
- @cindex workflow states as TODO keywords
- You can use TODO keywords to indicate different @emph{sequential} states
- in the process of working on an item, for example@footnote{Changing
- this variable only becomes effective after restarting Org mode in a
- buffer.}:
- @lisp
- (setq org-todo-keywords
- '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
- @end lisp
- The vertical bar separates the TODO keywords (states that @emph{need
- action}) from the DONE states (which need @emph{no further action}). If
- you don't provide the separator bar, the last state is used as the DONE
- state.
- @cindex completion, of TODO keywords
- With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
- to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
- also use a numeric prefix argument to quickly select a specific state. For
- example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
- Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
- define many keywords, you can use in-buffer completion
- (@pxref{Completion}) or even a special one-key selection scheme
- (@pxref{Fast access to TODO states}) to insert these words into the
- buffer. Changing a TODO state can be logged with a timestamp, see
- @ref{Tracking TODO state changes}, for more information.
- @node TODO types
- @subsection TODO keywords as types
- @cindex TODO types
- @cindex names as TODO keywords
- @cindex types as TODO keywords
- The second possibility is to use TODO keywords to indicate different
- @emph{types} of action items. For example, you might want to indicate
- that items are for ``work'' or ``home''. Or, when you work with several
- people on a single project, you might want to assign action items
- directly to persons, by using their names as TODO keywords. This would
- be set up like this:
- @lisp
- (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
- @end lisp
- In this case, different keywords do not indicate a sequence, but rather
- different types. So the normal work flow would be to assign a task to
- a person, and later to mark it DONE@. Org mode supports this style by
- adapting the workings of the command @kbd{C-c C-t}@footnote{This is also true
- for the @kbd{t} command in the agenda buffers.}. When used several times in
- succession, it will still cycle through all names, in order to first select
- the right type for a task. But when you return to the item after some time
- and execute @kbd{C-c C-t} again, it will switch from any name directly to
- DONE@. Use prefix arguments or completion to quickly select a specific name.
- You can also review the items of a specific TODO type in a sparse tree by
- using a numeric prefix to @kbd{C-c / t}. For example, to see all things Lucy
- has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items from all
- agenda files into a single buffer, you would use the numeric prefix argument
- as well when creating the global TODO list: @kbd{C-3 C-c a t}.
- @node Multiple sets in one file
- @subsection Multiple keyword sets in one file
- @cindex TODO keyword sets
- Sometimes you may want to use different sets of TODO keywords in
- parallel. For example, you may want to have the basic
- @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
- separate state indicating that an item has been canceled (so it is not
- DONE, but also does not require action). Your setup would then look
- like this:
- @lisp
- (setq org-todo-keywords
- '((sequence "TODO" "|" "DONE")
- (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
- (sequence "|" "CANCELED")))
- @end lisp
- The keywords should all be different, this helps Org mode to keep track
- of which subsequence should be used for a given entry. In this setup,
- @kbd{C-c C-t} only operates within a subsequence, so it switches from
- @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
- (nothing) to @code{REPORT}. Therefore you need a mechanism to initially
- select the correct sequence. Besides the obvious ways like typing a
- keyword or using completion, you may also apply the following commands:
- @table @kbd
- @kindex C-S-@key{right}
- @kindex C-S-@key{left}
- @kindex C-u C-u C-c C-t
- @item C-u C-u C-c C-t
- @itemx C-S-@key{right}
- @itemx C-S-@key{left}
- These keys jump from one TODO subset to the next. In the above example,
- @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
- @code{DONE} to @code{REPORT}, and any of the words in the second row to
- @code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with
- @code{shift-selection-mode} (@pxref{Conflicts}).
- @kindex S-@key{right}
- @kindex S-@key{left}
- @item S-@key{right}
- @itemx S-@key{left}
- @kbd{S-@key{left}} and @kbd{S-@key{right}} and walk through @emph{all}
- keywords from all sets, so for example @kbd{S-@key{right}} would switch
- from @code{DONE} to @code{REPORT} in the example above. See also
- @ref{Conflicts}, for a discussion of the interaction with
- @code{shift-selection-mode}.
- @end table
- @node Fast access to TODO states
- @subsection Fast access to TODO states
- If you would like to quickly change an entry to an arbitrary TODO state
- instead of cycling through the states, you can set up keys for single-letter
- access to the states. This is done by adding the selection character after
- each keyword, in parentheses@footnote{All characters are allowed except
- @code{@@^!}, which have a special meaning here.}. For example:
- @lisp
- (setq org-todo-keywords
- '((sequence "TODO(t)" "|" "DONE(d)")
- (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
- (sequence "|" "CANCELED(c)")))
- @end lisp
- @vindex org-fast-tag-selection-include-todo
- If you then press @kbd{C-c C-t} followed by the selection key, the entry
- will be switched to this state. @kbd{SPC} can be used to remove any TODO
- keyword from an entry.@footnote{Check also the option
- @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
- state through the tags interface (@pxref{Setting tags}), in case you like to
- mingle the two concepts. Note that this means you need to come up with
- unique keys across both sets of keywords.}
- @node Per-file keywords
- @subsection Setting up keywords for individual files
- @cindex keyword options
- @cindex per-file keywords
- @cindex #+TODO
- @cindex #+TYP_TODO
- @cindex #+SEQ_TODO
- It can be very useful to use different aspects of the TODO mechanism in
- different files. For file-local settings, you need to add special lines to
- the file which set the keywords and interpretation for that file only. For
- example, to set one of the two examples discussed above, you need one of the
- following lines anywhere in the file:
- @example
- #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
- @end example
- @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
- interpretation, but it means the same as @code{#+TODO}), or
- @example
- #+TYP_TODO: Fred Sara Lucy Mike | DONE
- @end example
- A setup for using several sets in parallel would be:
- @example
- #+TODO: TODO | DONE
- #+TODO: REPORT BUG KNOWNCAUSE | FIXED
- #+TODO: | CANCELED
- @end example
- @cindex completion, of option keywords
- @kindex M-@key{TAB}
- @noindent To make sure you are using the correct keyword, type
- @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
- @cindex DONE, final TODO keyword
- Remember that the keywords after the vertical bar (or the last keyword
- if no bar is there) must always mean that the item is DONE (although you
- may use a different word). After changing one of these lines, use
- @kbd{C-c C-c} with the cursor still in the line to make the changes
- known to Org mode@footnote{Org mode parses these lines only when
- Org mode is activated after visiting a file. @kbd{C-c C-c} with the
- cursor in a line starting with @samp{#+} is simply restarting Org mode
- for the current buffer.}.
- @node Faces for TODO keywords
- @subsection Faces for TODO keywords
- @cindex faces, for TODO keywords
- @vindex org-todo @r{(face)}
- @vindex org-done @r{(face)}
- @vindex org-todo-keyword-faces
- Org mode highlights TODO keywords with special faces: @code{org-todo}
- for keywords indicating that an item still has to be acted upon, and
- @code{org-done} for keywords indicating that an item is finished. If
- you are using more than 2 different states, you might want to use
- special faces for some of them. This can be done using the option
- @code{org-todo-keyword-faces}. For example:
- @lisp
- @group
- (setq org-todo-keyword-faces
- '(("TODO" . org-warning) ("STARTED" . "yellow")
- ("CANCELED" . (:foreground "blue" :weight bold))))
- @end group
- @end lisp
- While using a list with face properties as shown for CANCELED @emph{should}
- work, this does not always seem to be the case. If necessary, define a
- special face and use that. A string is interpreted as a color. The option
- @code{org-faces-easy-properties} determines if that color is interpreted as a
- foreground or a background color.
- @node TODO dependencies
- @subsection TODO dependencies
- @cindex TODO dependencies
- @cindex dependencies, of TODO states
- @cindex TODO dependencies, NOBLOCKING
- @vindex org-enforce-todo-dependencies
- @cindex property, ORDERED
- The structure of Org files (hierarchy and lists) makes it easy to define TODO
- dependencies. Usually, a parent TODO task should not be marked DONE until
- all subtasks (defined as children tasks) are marked as DONE@. And sometimes
- there is a logical sequence to a number of (sub)tasks, so that one task
- cannot be acted upon before all siblings above it are done. If you customize
- the option @code{org-enforce-todo-dependencies}, Org will block entries
- from changing state to DONE while they have children that are not DONE@.
- Furthermore, if an entry has a property @code{ORDERED}, each of its children
- will be blocked until all earlier siblings are marked DONE@. Here is an
- example:
- @example
- * TODO Blocked until (two) is done
- ** DONE one
- ** TODO two
- * Parent
- :PROPERTIES:
- :ORDERED: t
- :END:
- ** TODO a
- ** TODO b, needs to wait for (a)
- ** TODO c, needs to wait for (a) and (b)
- @end example
- You can ensure an entry is never blocked by using the @code{NOBLOCKING}
- property:
- @example
- * This entry is never blocked
- :PROPERTIES:
- :NOBLOCKING: t
- :END:
- @end example
- @table @kbd
- @orgcmd{C-c C-x o,org-toggle-ordered-property}
- @vindex org-track-ordered-property-with-tag
- @cindex property, ORDERED
- Toggle the @code{ORDERED} property of the current entry. A property is used
- for this behavior because this should be local to the current entry, not
- inherited like a tag. However, if you would like to @i{track} the value of
- this property with a tag for better visibility, customize the option
- @code{org-track-ordered-property-with-tag}.
- @orgkey{C-u C-u C-u C-c C-t}
- Change TODO state, circumventing any state blocking.
- @end table
- @vindex org-agenda-dim-blocked-tasks
- If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
- that cannot be closed because of such dependencies will be shown in a dimmed
- font or even made invisible in agenda views (@pxref{Agenda views}).
- @cindex checkboxes and TODO dependencies
- @vindex org-enforce-todo-dependencies
- You can also block changes of TODO states by looking at checkboxes
- (@pxref{Checkboxes}). If you set the option
- @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
- checkboxes will be blocked from switching to DONE.
- If you need more complex dependency structures, for example dependencies
- between entries in different trees or files, check out the contributed
- module @file{org-depend.el}.
- @page
- @node Progress logging
- @section Progress logging
- @cindex progress logging
- @cindex logging, of progress
- Org mode can automatically record a timestamp and possibly a note when
- you mark a TODO item as DONE, or even each time you change the state of
- a TODO item. This system is highly configurable; settings can be on a
- per-keyword basis and can be localized to a file or even a subtree. For
- information on how to clock working time for a task, see @ref{Clocking
- work time}.
- @menu
- * 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?
- @end menu
- @node Closing items
- @subsection Closing items
- The most basic logging is to keep track of @emph{when} a certain TODO
- item was finished. This is achieved with@footnote{The corresponding
- in-buffer setting is: @code{#+STARTUP: logdone}}
- @lisp
- (setq org-log-done 'time)
- @end lisp
- @vindex org-closed-keep-when-no-todo
- @noindent
- Then each time you turn an entry from a TODO (not-done) state into any of the
- DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
- the headline. If you turn the entry back into a TODO item through further
- state cycling, that line will be removed again. If you turn the entry back
- to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
- will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
- non-@code{nil}. If you want to record a note along with the timestamp,
- use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
- lognotedone}.}
- @lisp
- (setq org-log-done 'note)
- @end lisp
- @noindent
- You will then be prompted for a note, and that note will be stored below
- the entry with a @samp{Closing Note} heading.
- @node Tracking TODO state changes
- @subsection Tracking TODO state changes
- @cindex drawer, for state change recording
- @vindex org-log-states-order-reversed
- @vindex org-log-into-drawer
- @cindex property, LOG_INTO_DRAWER
- When TODO keywords are used as workflow states (@pxref{Workflow states}), you
- might want to keep track of when a state change occurred and maybe take a
- note about this change. You can either record just a timestamp, or a
- time-stamped note for a change. These records will be inserted after the
- headline as an itemized list, newest first@footnote{See the option
- @code{org-log-states-order-reversed}}. When taking a lot of notes, you might
- want to get the notes out of the way into a drawer (@pxref{Drawers}).
- Customize @code{org-log-into-drawer} to get this behavior---the recommended
- drawer for this is called @code{LOGBOOK}@footnote{Note that the
- @code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
- show an entry---use @key{C-u SPC} to keep it folded here}. You can also
- overrule the setting of this variable for a subtree by setting a
- @code{LOG_INTO_DRAWER} property.
- Since it is normally too much to record a note for every state, Org mode
- expects configuration on a per-keyword basis for this. This is achieved by
- adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
- with timestamp) in parentheses after each keyword. For example, with the
- setting
- @lisp
- (setq org-todo-keywords
- '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
- @end lisp
- To record a timestamp without a note for TODO keywords configured with
- @samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
- @noindent
- @vindex org-log-done
- You not only define global TODO keywords and fast access keys, but also
- request that a time is recorded when the entry is set to
- DONE@footnote{It is possible that Org mode will record two timestamps
- when you are using both @code{org-log-done} and state change logging.
- However, it will never prompt for two notes---if you have configured
- both, the state change recording note will take precedence and cancel
- the @samp{Closing Note}.}, and that a note is recorded when switching to
- WAIT or CANCELED@. The setting for WAIT is even more special: the
- @samp{!} after the slash means that in addition to the note taken when
- entering the state, a timestamp should be recorded when @i{leaving} the
- WAIT state, if and only if the @i{target} state does not configure
- logging for entering it. So it has no effect when switching from WAIT
- to DONE, because DONE is configured to record a timestamp only. But
- when switching from WAIT back to TODO, the @samp{/!} in the WAIT
- setting now triggers a timestamp even though TODO has no logging
- configured.
- You can use the exact same syntax for setting logging preferences local
- to a buffer:
- @example
- #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
- @end example
- @cindex property, LOGGING
- In order to define logging settings that are local to a subtree or a
- single item, define a LOGGING property in this entry. Any non-empty
- LOGGING property resets all logging settings to @code{nil}. You may then turn
- on logging for this specific tree using STARTUP keywords like
- @code{lognotedone} or @code{logrepeat}, as well as adding state specific
- settings like @code{TODO(!)}. For example
- @example
- * TODO Log each state with only a time
- :PROPERTIES:
- :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
- :END:
- * TODO Only log when switching to WAIT, and when repeating
- :PROPERTIES:
- :LOGGING: WAIT(@@) logrepeat
- :END:
- * TODO No logging at all
- :PROPERTIES:
- :LOGGING: nil
- :END:
- @end example
- @node Tracking your habits
- @subsection Tracking your habits
- @cindex habits
- Org has the ability to track the consistency of a special category of TODOs,
- called ``habits''. A habit has the following properties:
- @enumerate
- @item
- You have enabled the @code{habits} module by customizing @code{org-modules}.
- @item
- The habit is a TODO item, with a TODO keyword representing an open state.
- @item
- The property @code{STYLE} is set to the value @code{habit}.
- @item
- The TODO has a scheduled date, usually with a @code{.+} style repeat
- interval. A @code{++} style may be appropriate for habits with time
- constraints, e.g., must be done on weekends, or a @code{+} style for an
- unusual habit that can have a backlog, e.g., weekly reports.
- @item
- The TODO may also have minimum and maximum ranges specified by using the
- syntax @samp{.+2d/3d}, which says that you want to do the task at least every
- three days, but at most every two days.
- @item
- You must also have state logging for the @code{DONE} state enabled
- (@pxref{Tracking TODO state changes}), in order for historical data to be
- represented in the consistency graph. If it is not enabled it is not an
- error, but the consistency graphs will be largely meaningless.
- @end enumerate
- To give you an idea of what the above rules look like in action, here's an
- actual habit with some history:
- @example
- ** TODO Shave
- SCHEDULED: <2009-10-17 Sat .+2d/4d>
- :PROPERTIES:
- :STYLE: habit
- :LAST_REPEAT: [2009-10-19 Mon 00:36]
- :END:
- - State "DONE" from "TODO" [2009-10-15 Thu]
- - State "DONE" from "TODO" [2009-10-12 Mon]
- - State "DONE" from "TODO" [2009-10-10 Sat]
- - State "DONE" from "TODO" [2009-10-04 Sun]
- - State "DONE" from "TODO" [2009-10-02 Fri]
- - State "DONE" from "TODO" [2009-09-29 Tue]
- - State "DONE" from "TODO" [2009-09-25 Fri]
- - State "DONE" from "TODO" [2009-09-19 Sat]
- - State "DONE" from "TODO" [2009-09-16 Wed]
- - State "DONE" from "TODO" [2009-09-12 Sat]
- @end example
- What this habit says is: I want to shave at most every 2 days (given by the
- @code{SCHEDULED} date and repeat interval) and at least every 4 days. If
- today is the 15th, then the habit first appears in the agenda on Oct 17,
- after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
- after four days have elapsed.
- What's really useful about habits is that they are displayed along with a
- consistency graph, to show how consistent you've been at getting that task
- done in the past. This graph shows every day that the task was done over the
- past three weeks, with colors for each day. The colors used are:
- @table @code
- @item Blue
- If the task wasn't to be done yet on that day.
- @item Green
- If the task could have been done on that day.
- @item Yellow
- If the task was going to be overdue the next day.
- @item Red
- If the task was overdue on that day.
- @end table
- In addition to coloring each day, the day is also marked with an asterisk if
- the task was actually done that day, and an exclamation mark to show where
- the current day falls in the graph.
- There are several configuration variables that can be used to change the way
- habits are displayed in the agenda.
- @table @code
- @item org-habit-graph-column
- The buffer column at which the consistency graph should be drawn. This will
- overwrite any text in that column, so it is a good idea to keep your habits'
- titles brief and to the point.
- @item org-habit-preceding-days
- The amount of history, in days before today, to appear in consistency graphs.
- @item org-habit-following-days
- The number of days after today that will appear in consistency graphs.
- @item org-habit-show-habits-only-for-today
- If non-@code{nil}, only show habits in today's agenda view. This is set to true by
- default.
- @end table
- Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
- temporarily be disabled and they won't appear at all. Press @kbd{K} again to
- bring them back. They are also subject to tag filtering, if you have habits
- which should only be done in certain contexts, for example.
- @node Priorities
- @section Priorities
- @cindex priorities
- If you use Org mode extensively, you may end up with enough TODO items that
- it starts to make sense to prioritize them. Prioritizing can be done by
- placing a @emph{priority cookie} into the headline of a TODO item, like this
- @example
- *** TODO [#A] Write letter to Sam Fortune
- @end example
- @noindent
- @vindex org-priority-faces
- By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
- @samp{C}. @samp{A} is the highest priority. An entry without a cookie is
- treated just like priority @samp{B}. Priorities make a difference only for
- sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
- have no inherent meaning to Org mode. The cookies can be highlighted with
- special faces by customizing @code{org-priority-faces}.
- Priorities can be attached to any outline node; they do not need to be TODO
- items.
- @table @kbd
- @item @kbd{C-c ,}
- @kindex @kbd{C-c ,}
- @findex org-priority
- Set the priority of the current headline (@command{org-priority}). The
- command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
- When you press @key{SPC} instead, the priority cookie is removed from the
- headline. The priorities can also be changed ``remotely'' from the agenda
- buffer with the @kbd{,} command (@pxref{Agenda commands}).
- @c
- @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
- @vindex org-priority-start-cycle-with-default
- Increase/decrease priority of current headline@footnote{See also the option
- @code{org-priority-start-cycle-with-default}.}. Note that these keys are
- also used to modify timestamps (@pxref{Creating timestamps}). See also
- @ref{Conflicts}, for a discussion of the interaction with
- @code{shift-selection-mode}.
- @end table
- @vindex org-highest-priority
- @vindex org-lowest-priority
- @vindex org-default-priority
- You can change the range of allowed priorities by setting the options
- @code{org-highest-priority}, @code{org-lowest-priority}, and
- @code{org-default-priority}. For an individual buffer, you may set
- these values (highest, lowest, default) like this (please make sure that
- the highest priority is earlier in the alphabet than the lowest
- priority):
- @cindex #+PRIORITIES
- @example
- #+PRIORITIES: A C B
- @end example
- @node Breaking down tasks
- @section Breaking tasks down into subtasks
- @cindex tasks, breaking down
- @cindex statistics, for TODO items
- @vindex org-agenda-todo-list-sublevels
- It is often advisable to break down large tasks into smaller, manageable
- subtasks. You can do this by creating an outline tree below a TODO item,
- with detailed subtasks on the tree@footnote{To keep subtasks out of the
- global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
- the overview over the fraction of subtasks that are already completed, insert
- either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
- be updated each time the TODO status of a child changes, or when pressing
- @kbd{C-c C-c} on the cookie. For example:
- @example
- * Organize Party [33%]
- ** TODO Call people [1/2]
- *** TODO Peter
- *** DONE Sarah
- ** TODO Buy food
- ** DONE Talk to neighbor
- @end example
- @cindex property, COOKIE_DATA
- If a heading has both checkboxes and TODO children below it, the meaning of
- the statistics cookie become ambiguous. Set the property
- @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
- this issue.
- @vindex org-hierarchical-todo-statistics
- If you would like to have the statistics cookie count any TODO entries in the
- subtree (not just direct children), configure
- @code{org-hierarchical-todo-statistics}. To do this for a single subtree,
- include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
- property.
- @example
- * Parent capturing statistics [2/20]
- :PROPERTIES:
- :COOKIE_DATA: todo recursive
- :END:
- @end example
- If you would like a TODO entry to automatically change to DONE
- when all children are done, you can use the following setup:
- @example
- (defun org-summary-todo (n-done n-not-done)
- "Switch entry to DONE when all subentries are done, to TODO otherwise."
- (let (org-log-done org-log-states) ; turn off logging
- (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
- (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
- @end example
- Another possibility is the use of checkboxes to identify (a hierarchy of) a
- large number of subtasks (@pxref{Checkboxes}).
- @node Checkboxes
- @section Checkboxes
- @cindex checkboxes
- @vindex org-list-automatic-rules
- Every item in a plain list@footnote{With the exception of description
- lists. But you can allow it by modifying @code{org-list-automatic-rules}
- accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
- it with the string @samp{[ ]}. This feature is similar to TODO items
- (@pxref{TODO items}), but is more lightweight. Checkboxes are not included
- in the global TODO list, so they are often great to split a task into a
- number of simple steps. Or you can use them in a shopping list. To toggle a
- checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
- @file{org-mouse.el}).
- Here is an example of a checkbox list.
- @example
- * TODO Organize party [2/4]
- - [-] call people [1/3]
- - [ ] Peter
- - [X] Sarah
- - [ ] Sam
- - [X] order food
- - [ ] think about what music to play
- - [X] talk to the neighbors
- @end example
- Checkboxes work hierarchically, so if a checkbox item has children that
- are checkboxes, toggling one of the children checkboxes will make the
- parent checkbox reflect if none, some, or all of the children are
- checked.
- @cindex statistics, for checkboxes
- @cindex checkbox statistics
- @cindex property, COOKIE_DATA
- @vindex org-checkbox-hierarchical-statistics
- The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
- indicating how many checkboxes present in this entry have been checked off,
- and the total number of checkboxes present. This can give you an idea on how
- many checkboxes remain, even without opening a folded entry. The cookies can
- be placed into a headline or into (the first line of) a plain list item.
- Each cookie covers checkboxes of direct children structurally below the
- headline/item on which the cookie appears@footnote{Set the option
- @code{org-checkbox-hierarchical-statistics} if you want such cookies to
- count all checkboxes below the cookie, not just those belonging to direct
- children.}. You have to insert the cookie yourself by typing either
- @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
- result, as in the examples above. With @samp{[%]} you get information about
- the percentage of checkboxes checked (in the above example, this would be
- @samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can
- count either checkboxes below the heading or TODO states of children, and it
- will display whatever was changed last. Set the property @code{COOKIE_DATA}
- to either @samp{checkbox} or @samp{todo} to resolve this issue.
- @cindex blocking, of checkboxes
- @cindex checkbox blocking
- @cindex property, ORDERED
- If the current outline node has an @code{ORDERED} property, checkboxes must
- be checked off in sequence, and an error will be thrown if you try to check
- off a box while there are unchecked boxes above it.
- @noindent The following commands work with checkboxes:
- @table @kbd
- @orgcmd{C-c C-c,org-toggle-checkbox}
- Toggle checkbox status or (with prefix arg) checkbox presence at point. With
- a single prefix argument, add an empty checkbox or remove the current
- one@footnote{@kbd{C-u C-c C-c} before the @emph{first} bullet in a list with
- no checkbox will add checkboxes to the rest of the list.}. With a double
- prefix argument, set it to @samp{[-]}, which is considered to be an
- intermediate state.
- @orgcmd{C-c C-x C-b,org-toggle-checkbox}
- Toggle checkbox status or (with prefix arg) checkbox presence at point. With
- double prefix argument, set it to @samp{[-]}, which is considered to be an
- intermediate state.
- @itemize @minus
- @item
- If there is an active region, toggle the first checkbox in the region
- and set all remaining boxes to the same status as the first. With a prefix
- arg, add or remove the checkbox for all items in the region.
- @item
- If the cursor is in a headline, toggle the state of the first checkbox in the
- region between this headline and the next---so @emph{not} the entire
- subtree---and propagate this new state to all other checkboxes in the same
- area.
- @item
- If there is no active region, just toggle the checkbox at point.
- @end itemize
- @orgcmd{M-S-@key{RET},org-insert-todo-heading}
- Insert a new item with a checkbox. This works only if the cursor is already
- in a plain list item (@pxref{Plain lists}).
- @orgcmd{C-c C-x o,org-toggle-ordered-property}
- @vindex org-track-ordered-property-with-tag
- @cindex property, ORDERED
- Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
- be checked off in sequence. A property is used for this behavior because
- this should be local to the current entry, not inherited like a tag.
- However, if you would like to @i{track} the value of this property with a tag
- for better visibility, customize @code{org-track-ordered-property-with-tag}.
- @orgcmd{C-c #,org-update-statistics-cookies}
- Update the statistics cookie in the current outline entry. When called with
- a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
- updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
- new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when
- changing TODO states. If you delete boxes/entries or add/change them by
- hand, use this command to get things back into sync.
- @end table
- @node Tags
- @chapter Tags
- @cindex tags
- @cindex headline tagging
- @cindex matching, tags
- @cindex sparse tree, tag based
- An excellent way to implement labels and contexts for cross-correlating
- information is to assign @i{tags} to headlines. Org mode has extensive
- support for tags.
- @vindex org-tag-faces
- Every headline can contain a list of tags; they occur at the end of the
- headline. Tags are normal words containing letters, numbers, @samp{_}, and
- @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
- @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
- Tags will by default be in bold face with the same color as the headline.
- You may specify special faces for specific tags using the option
- @code{org-tag-faces}, in much the same way as you can for TODO keywords
- (@pxref{Faces for TODO keywords}).
- @menu
- * Tag inheritance:: Tags use the tree structure of the outline
- * Setting tags:: How to assign tags to a headline
- * Tag hierarchy:: Create a hierarchy of tags
- * Tag searches:: Searching for combinations of tags
- @end menu
- @node Tag inheritance
- @section Tag inheritance
- @cindex tag inheritance
- @cindex inheritance, of tags
- @cindex sublevels, inclusion into tags match
- @i{Tags} make use of the hierarchical structure of outline trees. If a
- heading has a certain tag, all subheadings will inherit the tag as
- well. For example, in the list
- @example
- * Meeting with the French group :work:
- ** Summary by Frank :boss:notes:
- *** TODO Prepare slides for him :action:
- @end example
- @noindent
- the final heading will have the tags @samp{:work:}, @samp{:boss:},
- @samp{:notes:}, and @samp{:action:} even though the final heading is not
- explicitly marked with all those tags. You can also set tags that all
- entries in a file should inherit just as if these tags were defined in
- a hypothetical level zero that surrounds the entire file. Use a line like
- this@footnote{As with all these in-buffer settings, pressing @kbd{C-c C-c}
- activates any changes in the line.}:
- @cindex #+FILETAGS
- @example
- #+FILETAGS: :Peter:Boss:Secret:
- @end example
- @noindent
- @vindex org-use-tag-inheritance
- @vindex org-tags-exclude-from-inheritance
- To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
- To turn it off entirely, use @code{org-use-tag-inheritance}.
- @vindex org-tags-match-list-sublevels
- When a headline matches during a tags search while tag inheritance is turned
- on, all the sublevels in the same tree will (for a simple match form) match
- as well@footnote{This is only true if the search does not involve more
- complex tests including properties (@pxref{Property searches}).}. The list
- of matches may then become very long. If you only want to see the first tags
- match in a subtree, configure @code{org-tags-match-list-sublevels} (not
- recommended).
- @vindex org-agenda-use-tag-inheritance
- Tag inheritance is relevant when the agenda search tries to match a tag,
- either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
- types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
- have your tags correctly set in the agenda, so that tag filtering works fine,
- with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
- this: the default value includes all agenda types, but setting this to @code{nil}
- can really speed up agenda generation.
- @node Setting tags
- @section Setting tags
- @cindex setting tags
- @cindex tags, setting
- @kindex M-@key{TAB}
- Tags can simply be typed into the buffer at the end of a headline.
- After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
- also a special command for inserting tags:
- @table @kbd
- @orgcmd{C-c C-q,org-set-tags-command}
- @cindex completion, of tags
- @vindex org-tags-column
- Enter new tags for the current headline. Org mode will either offer
- completion or a special single-key interface for setting tags, see
- below. After pressing @key{RET}, the tags will be inserted and aligned
- to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
- tags in the current buffer will be aligned to that column, just to make
- things look nice. TAGS are automatically realigned after promotion,
- demotion, and TODO state changes (@pxref{TODO basics}).
- @orgcmd{C-c C-c,org-set-tags-command}
- When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
- @end table
- @vindex org-tag-alist
- Org supports tag insertion based on a @emph{list of tags}. By
- default this list is constructed dynamically, containing all tags
- currently used in the buffer. You may also globally specify a hard list
- of tags with the variable @code{org-tag-alist}. Finally you can set
- the default tags for a given file with lines like
- @cindex #+TAGS
- @example
- #+TAGS: @@work @@home @@tennisclub
- #+TAGS: laptop car pc sailboat
- @end example
- If you have globally defined your preferred set of tags using the
- variable @code{org-tag-alist}, but would like to use a dynamic tag list
- in a specific file, add an empty TAGS option line to that file:
- @example
- #+TAGS:
- @end example
- @vindex org-tag-persistent-alist
- If you have a preferred set of tags that you would like to use in every file,
- in addition to those defined on a per-file basis by TAGS option lines, then
- you may specify a list of tags with the variable
- @code{org-tag-persistent-alist}. You may turn this off on a per-file basis
- by adding a STARTUP option line to that file:
- @example
- #+STARTUP: noptag
- @end example
- By default Org mode uses the standard minibuffer completion facilities for
- 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, case-sensitive, letters to most of your commonly used tags.
- You can do this globally by configuring the variable @code{org-tag-alist} in
- your Emacs init file. For example, you may find the need to tag many items
- in different files with @samp{:@@home:}. In this case you can set something
- like:
- @lisp
- (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
- @end lisp
- @noindent If the tag is only relevant to the file you are working on, then you
- can instead set the TAGS option line as:
- @example
- #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
- @end example
- @noindent The tags interface will show the available tags in a splash
- window. If you want to start a new line after a specific tag, insert
- @samp{\n} into the tag list
- @example
- #+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)
- @end example
- @noindent or write them in two lines:
- @example
- #+TAGS: @@work(w) @@home(h) @@tennisclub(t)
- #+TAGS: laptop(l) pc(p)
- @end example
- @noindent
- You can also group together tags that are mutually exclusive by using
- braces, as in:
- @example
- #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
- @end example
- @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
- and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.
- @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
- these lines to activate any changes.
- @noindent
- To set these mutually exclusive groups in the variable @code{org-tag-alist},
- you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
- of the braces. Similarly, you can use @code{:newline} to indicate a line
- break. The previous example would be set globally by the following
- configuration:
- @lisp
- (setq org-tag-alist '((:startgroup . nil)
- ("@@work" . ?w) ("@@home" . ?h)
- ("@@tennisclub" . ?t)
- (:endgroup . nil)
- ("laptop" . ?l) ("pc" . ?p)))
- @end lisp
- If at least one tag has a selection key then pressing @kbd{C-c C-c} will
- automatically present you with a special interface, listing inherited tags,
- the tags of the current headline, and a list of all valid tags with
- corresponding keys@footnote{Keys will automatically be assigned to tags which
- have no configured keys.}.
- Pressing keys assigned to tags will add or remove them from the list of tags
- in the current line. Selecting a tag in a group of mutually exclusive tags
- will turn off any other tags from that group.
- In this interface, you can also use the following special keys:
- @table @kbd
- @kindex @key{TAB}
- @item @key{TAB}
- Enter a tag in the minibuffer, even if the tag is not in the predefined
- list. You will be able to complete on all tags present in the buffer.
- You can also add several tags: just separate them with a comma.
- @kindex @key{SPC}
- @item @key{SPC}
- Clear all tags for this line.
- @kindex @key{RET}
- @item @key{RET}
- Accept the modified set.
- @item C-g
- Abort without installing changes.
- @item q
- If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
- @item !
- Turn off groups of mutually exclusive tags. Use this to (as an
- exception) assign several tags from such a group.
- @item C-c
- Toggle auto-exit after the next change (see below).
- If you are using expert mode, the first @kbd{C-c} will display the
- selection window.
- @end table
- @noindent
- This method lets you assign tags to a headline with very few keys. With
- the above setup, you could clear the current tags and set @samp{@@home},
- @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
- C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to
- @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
- alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
- @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
- @key{RET} @key{RET}}.
- @vindex org-fast-tag-selection-single-key
- If you find that most of the time you need only a single key press to
- modify your list of tags, set @code{org-fast-tag-selection-single-key}.
- Then you no longer have to press @key{RET} to exit fast tag selection---it
- will immediately exit after the first change. If you then occasionally
- need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
- selection process (in effect: start selection with @kbd{C-c C-c C-c}
- instead of @kbd{C-c C-c}). If you set the variable to the value
- @code{expert}, the special window is not even shown for single-key tag
- selection, it comes up only when you press an extra @kbd{C-c}.
- @node Tag hierarchy
- @section Tag hierarchy
- @cindex group tags
- @cindex tags, groups
- @cindex tag hierarchy
- Tags can be defined in hierarchies. A tag can be defined as a @emph{group
- tag} for a set of other tags. The group tag can be seen as the ``broader
- term'' for its set of tags. Defining multiple @emph{group tags} and nesting
- them creates a tag hierarchy.
- One use-case is to create a taxonomy of terms (tags) that can be used to
- classify nodes in a document or set of documents.
- When you search for a group tag, it will return matches for all members in
- the group and its subgroups. In an agenda view, filtering by a group tag
- will display or hide headlines tagged with at least one of the members of the
- group or any of its subgroups. This makes tag searches and filters even more
- flexible.
- You can set group tags by using brackets and inserting a colon between the
- group tag and its related tags---beware that all whitespaces are mandatory so
- that Org can parse this line correctly:
- @example
- #+TAGS: [ GTD : Control Persp ]
- @end example
- In this example, @samp{GTD} is the @emph{group tag} and it is related to two
- other tags: @samp{Control}, @samp{Persp}. Defining @samp{Control} and
- @samp{Persp} as group tags creates an hierarchy of tags:
- @example
- #+TAGS: [ Control : Context Task ]
- #+TAGS: [ Persp : Vision Goal AOF Project ]
- @end example
- That can conceptually be seen as a hierarchy of tags:
- @example
- - GTD
- - Persp
- - Vision
- - Goal
- - AOF
- - Project
- - Control
- - Context
- - Task
- @end example
- You can use the @code{:startgrouptag}, @code{:grouptags} and
- @code{:endgrouptag} keyword directly when setting @code{org-tag-alist}
- directly:
- @lisp
- (setq org-tag-alist '((:startgrouptag)
- ("GTD")
- (:grouptags)
- ("Control")
- ("Persp")
- (:endgrouptag)
- (:startgrouptag)
- ("Control")
- (:grouptags)
- ("Context")
- ("Task")
- (:endgrouptag)))
- @end lisp
- The tags in a group can be mutually exclusive if using the same group syntax
- as is used for grouping mutually exclusive tags together; using curly
- brackets.
- @example
- #+TAGS: @{ Context : @@Home @@Work @@Call @}
- @end example
- When setting @code{org-tag-alist} you can use @code{:startgroup} &
- @code{:endgroup} instead of @code{:startgrouptag} & @code{:endgrouptag} to
- make the tags mutually exclusive.
- Furthermore, the members of a @emph{group tag} can also be regular
- expressions, creating the possibility of a more dynamic and rule-based
- tag structure. The regular expressions in the group must be specified
- within @{ @}. Here is an expanded example:
- @example
- #+TAGS: [ Vision : @{V@@@.+@} ]
- #+TAGS: [ Goal : @{G@@@.+@} ]
- #+TAGS: [ AOF : @{AOF@@@.+@} ]
- #+TAGS: [ Project : @{P@@@.+@} ]
- @end example
- Searching for the tag @samp{Project} will now list all tags also including
- regular expression matches for @samp{P@@@.+}, and similarly for tag searches on
- @samp{Vision}, @samp{Goal} and @samp{AOF}. For example, this would work well
- for a project tagged with a common project-identifier, e.g. @samp{P@@2014_OrgTags}.
- @kindex C-c C-x q
- @vindex org-group-tags
- If you want to ignore group tags temporarily, toggle group tags support
- with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you
- want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
- @node Tag searches
- @section Tag searches
- @cindex tag searches
- @cindex searching for tags
- Once a system of tags has been set up, it can be used to collect related
- information into special lists.
- @table @kbd
- @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
- Create a sparse tree with all headlines matching a tags/property/TODO search.
- With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
- @xref{Matching tags and properties}.
- @orgcmd{C-c a m,org-tags-view}
- Create a global list of tag matches from all agenda files. @xref{Matching
- tags and properties}.
- @orgcmd{C-c a M,org-tags-view}
- @vindex org-tags-match-list-sublevels
- Create a global list of tag matches from all agenda files, but check
- only TODO items and force checking subitems (see the option
- @code{org-tags-match-list-sublevels}).
- @end table
- These commands all prompt for a match string which allows basic Boolean logic
- like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
- @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
- tagged as @samp{Kathy} or @samp{Sally}. The full syntax of the search string
- is rich and allows also matching against TODO keywords, entry levels and
- properties. For a complete description with many examples, see @ref{Matching
- tags and properties}.
- @node Properties and columns
- @chapter Properties and columns
- @cindex properties
- A property is a key-value pair associated with an entry. Properties can be
- set so they are associated with a single entry, with every entry in a tree,
- or with every entry in an Org mode file.
- There are two main applications for properties in Org mode. First,
- properties are like tags, but with a value. Imagine maintaining a file where
- you document bugs and plan releases for a piece of software. Instead of
- using tags like @code{:release_1:}, @code{:release_2:}, you can use a
- property, say @code{:Release:}, that in different subtrees has different
- values, such as @code{1.0} or @code{2.0}. Second, you can use properties to
- implement (very basic) database capabilities in an Org buffer. Imagine
- keeping track of your music CDs, where properties could be things such as the
- album, artist, date of release, number of tracks, and so on.
- Properties can be conveniently edited and viewed in column view
- (@pxref{Column view}).
- @menu
- * 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 the tree
- * Column view:: Tabular viewing and editing
- * Property API:: Properties for Lisp programmers
- @end menu
- @node Property syntax
- @section Property syntax
- @cindex property syntax
- @cindex drawer, for properties
- Properties are key-value pairs. When they are associated with a single entry
- or with a tree they need to be inserted into a special drawer
- (@pxref{Drawers}) with the name @code{PROPERTIES}, which has to be located
- right below a headline, and its planning line (@pxref{Deadlines and
- scheduling}) when applicable. Each property is specified on a single line,
- with the key (surrounded by colons) first, and the value after it. Keys are
- case-insensitive. Here is an example:
- @example
- * CD collection
- ** Classic
- *** Goldberg Variations
- :PROPERTIES:
- :Title: Goldberg Variations
- :Composer: J.S. Bach
- :Artist: Glen Gould
- :Publisher: Deutsche Grammophon
- :NDisks: 1
- :END:
- @end example
- Depending on the value of @code{org-use-property-inheritance}, a property set
- this way will either be associated with a single entry, or the subtree
- defined by the entry, see @ref{Property inheritance}.
- You may define the allowed values for a particular property @samp{:Xyz:}
- by setting a property @samp{:Xyz_ALL:}. This special property is
- @emph{inherited}, so if you set it in a level 1 entry, it will apply to
- the entire tree. When allowed values are defined, setting the
- corresponding property becomes easier and is less prone to typing
- errors. For the example with the CD collection, we can predefine
- publishers and the number of disks in a box like this:
- @example
- * CD collection
- :PROPERTIES:
- :NDisks_ALL: 1 2 3 4
- :Publisher_ALL: "Deutsche Grammophon" Philips EMI
- :END:
- @end example
- If you want to set properties that can be inherited by any entry in a
- file, use a line like
- @cindex property, _ALL
- @cindex #+PROPERTY
- @example
- #+PROPERTY: NDisks_ALL 1 2 3 4
- @end example
- Contrary to properties set from a special drawer, you have to refresh the
- buffer with @kbd{C-c C-c} to activate this change.
- If you want to add to the value of an existing property, append a @code{+} to
- the property name. The following results in the property @code{var} having
- the value ``foo=1 bar=2''.
- @cindex property, +
- @example
- #+PROPERTY: var foo=1
- #+PROPERTY: var+ bar=2
- @end example
- It is also possible to add to the values of inherited properties. The
- following results in the @code{genres} property having the value ``Classic
- Baroque'' under the @code{Goldberg Variations} subtree.
- @cindex property, +
- @example
- * CD collection
- ** Classic
- :PROPERTIES:
- :GENRES: Classic
- :END:
- *** Goldberg Variations
- :PROPERTIES:
- :Title: Goldberg Variations
- :Composer: J.S. Bach
- :Artist: Glen Gould
- :Publisher: Deutsche Grammophon
- :NDisks: 1
- :GENRES+: Baroque
- :END:
- @end example
- Note that a property can only have one entry per Drawer.
- @vindex org-global-properties
- Property values set with the global variable
- @code{org-global-properties} can be inherited by all entries in all
- Org files.
- @noindent
- The following commands help to work with properties:
- @table @kbd
- @orgcmd{M-@key{TAB},pcomplete}
- After an initial colon in a line, complete property keys. All keys used
- in the current file will be offered as possible completions.
- @orgcmd{C-c C-x p,org-set-property}
- Set a property. This prompts for a property name and a value. If
- necessary, the property drawer is created as well.
- @item C-u M-x org-insert-drawer RET
- @cindex org-insert-drawer
- Insert a property drawer into the current entry. The drawer will be
- inserted early in the entry, but after the lines with planning
- information like deadlines.
- @orgcmd{C-c C-c,org-property-action}
- With the cursor in a property drawer, this executes property commands.
- @orgcmd{C-c C-c s,org-set-property}
- Set a property in the current entry. Both the property and the value
- can be inserted using completion.
- @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
- Switch property at point to the next/previous allowed value.
- @orgcmd{C-c C-c d,org-delete-property}
- Remove a property from the current entry.
- @orgcmd{C-c C-c D,org-delete-property-globally}
- Globally remove a property, from all entries in the current file.
- @orgcmd{C-c C-c c,org-compute-property-at-point}
- Compute the property at point, using the operator and scope from the
- nearest column format definition.
- @end table
- @node Special properties
- @section Special properties
- @cindex properties, special
- Special properties provide an alternative access method to Org mode features,
- like the TODO state or the priority of an entry, discussed in the previous
- chapters. This interface exists so that you can include these states in
- a column view (@pxref{Column view}), or to use them in queries. The
- following property names are special and should not be used as keys in the
- properties drawer:
- @cindex property, special, ALLTAGS
- @cindex property, special, BLOCKED
- @cindex property, special, CLOCKSUM
- @cindex property, special, CLOCKSUM_T
- @cindex property, special, CLOSED
- @cindex property, special, DEADLINE
- @cindex property, special, FILE
- @cindex property, special, ITEM
- @cindex property, special, PRIORITY
- @cindex property, special, SCHEDULED
- @cindex property, special, TAGS
- @cindex property, special, TIMESTAMP
- @cindex property, special, TIMESTAMP_IA
- @cindex property, special, TODO
- @example
- ALLTAGS @r{All tags, including inherited ones.}
- BLOCKED @r{"t" if task is currently blocked by children or siblings.}
- CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}}
- @r{must be run first to compute the values in the current buffer.}
- CLOCKSUM_T @r{The sum of CLOCK intervals in the subtree for today.}
- @r{@code{org-clock-sum-today} must be run first to compute the}
- @r{values in the current buffer.}
- CLOSED @r{When was this entry closed?}
- DEADLINE @r{The deadline time string, without the angular brackets.}
- FILE @r{The filename the entry is located in.}
- ITEM @r{The headline of the entry.}
- PRIORITY @r{The priority of the entry, a string with a single letter.}
- SCHEDULED @r{The scheduling timestamp, without the angular brackets.}
- TAGS @r{The tags defined directly in the headline.}
- TIMESTAMP @r{The first keyword-less timestamp in the entry.}
- TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
- TODO @r{The TODO keyword of the entry.}
- @end example
- @node Property searches
- @section Property searches
- @cindex properties, searching
- @cindex searching, of properties
- To create sparse trees and special lists with selection based on properties,
- the same commands are used as for tag searches (@pxref{Tag searches}).
- @table @kbd
- @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
- Create a sparse tree with all matching entries. With a
- @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
- @orgcmd{C-c a m,org-tags-view}
- Create a global list of tag/property matches from all agenda files.
- @xref{Matching tags and properties}.
- @orgcmd{C-c a M,org-tags-view}
- @vindex org-tags-match-list-sublevels
- Create a global list of tag matches from all agenda files, but check
- only TODO items and force checking of subitems (see the option
- @code{org-tags-match-list-sublevels}).
- @end table
- The syntax for the search string is described in @ref{Matching tags and
- properties}.
- There is also a special command for creating sparse trees based on a
- single property:
- @table @kbd
- @orgkey{C-c / p}
- Create a sparse tree based on the value of a property. This first
- prompts for the name of a property, and then for a value. A sparse tree
- is created with all entries that define this property with the given
- value. If you enclose the value in curly braces, it is interpreted as
- a regular expression and matched against the property values.
- @end table
- @node Property inheritance
- @section Property Inheritance
- @cindex properties, inheritance
- @cindex inheritance, of properties
- @vindex org-use-property-inheritance
- The outline structure of Org mode documents lends itself to an
- inheritance model of properties: if the parent in a tree has a certain
- property, the children can inherit this property. Org mode does not
- turn this on by default, because it can slow down property searches
- significantly and is often not needed. However, if you find inheritance
- useful, you can turn it on by setting the variable
- @code{org-use-property-inheritance}. It may be set to @code{t} to make
- all properties inherited from the parent, to a list of properties
- that should be inherited, or to a regular expression that matches
- inherited properties. If a property has the value @code{nil}, this is
- interpreted as an explicit undefine of the property, so that inheritance
- search will stop at this value and return @code{nil}.
- Org mode has a few properties for which inheritance is hard-coded, at
- least for the special applications for which they are used:
- @cindex property, COLUMNS
- @table @code
- @item COLUMNS
- The @code{:COLUMNS:} property defines the format of column view
- (@pxref{Column view}). It is inherited in the sense that the level
- where a @code{:COLUMNS:} property is defined is used as the starting
- point for a column view table, independently of the location in the
- subtree from where columns view is turned on.
- @item CATEGORY
- @cindex property, CATEGORY
- For agenda view, a category set through a @code{:CATEGORY:} property
- applies to the entire subtree.
- @item ARCHIVE
- @cindex property, ARCHIVE
- For archiving, the @code{:ARCHIVE:} property may define the archive
- location for the entire subtree (@pxref{Moving subtrees}).
- @item LOGGING
- @cindex property, LOGGING
- The LOGGING property may define logging settings for an entry or a
- subtree (@pxref{Tracking TODO state changes}).
- @end table
- @node Column view
- @section Column view
- A great way to view and edit properties in an outline tree is
- @emph{column view}. In column view, each outline node is turned into a
- table row. Columns in this table provide access to properties of the
- entries. Org mode implements columns by overlaying a tabular structure
- over the headline of each item. While the headlines have been turned
- into a table row, you can still change the visibility of the outline
- tree. For example, you get a compact table by switching to CONTENTS
- view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
- is active), but you can still open, read, and edit the entry below each
- headline. Or, you can switch to column view after executing a sparse
- tree command and in this way get a table only for the selected items.
- Column view also works in agenda buffers (@pxref{Agenda views}) where
- queries have collected selected items, possibly from a number of files.
- @menu
- * 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
- @end menu
- @node Defining columns
- @subsection Defining columns
- @cindex column view, for properties
- @cindex properties, column view
- Setting up a column view first requires defining the columns. This is
- done by defining a column format line.
- @menu
- * Scope of column definitions:: Where defined, where valid?
- * Column attributes:: Appearance and content of a column
- @end menu
- @node Scope of column definitions
- @subsubsection Scope of column definitions
- To define a column format for an entire file, use a line like
- @cindex #+COLUMNS
- @example
- #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
- @end example
- To specify a format that only applies to a specific tree, add a
- @code{:COLUMNS:} property to the top node of that tree, for example:
- @example
- ** Top node for columns view
- :PROPERTIES:
- :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
- :END:
- @end example
- If a @code{:COLUMNS:} property is present in an entry, it defines columns
- for the entry itself, and for the entire subtree below it. Since the
- column definition is part of the hierarchical structure of the document,
- you can define columns on level 1 that are general enough for all
- sublevels, and more specific columns further down, when you edit a
- deeper part of the tree.
- @node Column attributes
- @subsubsection Column attributes
- A column definition sets the attributes of a column. The general
- definition looks like this:
- @example
- %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
- @end example
- @noindent
- Except for the percent sign and the property name, all items are
- optional. The individual parts have the following meaning:
- @example
- @var{width} @r{An integer specifying the width of the column in characters.}
- @r{If omitted, the width will be determined automatically.}
- @var{property} @r{The property that should be edited in this column.}
- @r{Special properties representing meta data are allowed here}
- @r{as well (@pxref{Special properties})}
- @var{title} @r{The header text for the column. If omitted, the property}
- @r{name is used.}
- @{@var{summary-type}@} @r{The summary type. If specified, the column values for}
- @r{parent nodes are computed from the children@footnote{If
- more than one summary type apply to the property, the parent
- values are computed according to the first of them.}.}
- @r{Supported summary types are:}
- @{+@} @r{Sum numbers in this column.}
- @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
- @{$@} @r{Currency, short for @samp{+;%.2f}.}
- @{min@} @r{Smallest number in column.}
- @{max@} @r{Largest number.}
- @{mean@} @r{Arithmetic mean of numbers.}
- @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
- @{X/@} @r{Checkbox status, @samp{[n/m]}.}
- @{X%@} @r{Checkbox status, @samp{[n%]}.}
- @{:@} @r{Sum times, HH:MM, plain numbers are
- hours@footnote{A time can also be a duration, using effort
- modifiers defined in @code{org-effort-durations}, e.g.,
- @samp{3d 1h}. If any value in the column is as such, the
- summary will also be an effort duration.}.}
- @{:min@} @r{Smallest time value in column.}
- @{:max@} @r{Largest time value.}
- @{:mean@} @r{Arithmetic mean of time values.}
- @{@@min@} @r{Minimum age@footnote{An age is defined as
- a duration s
|