org.texi 769 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076707770787079708070817082708370847085708670877088708970907091709270937094709570967097709870997100710171027103710471057106710771087109711071117112711371147115711671177118711971207121712271237124712571267127712871297130713171327133713471357136713771387139714071417142714371447145714671477148714971507151715271537154715571567157715871597160716171627163716471657166716771687169717071717172717371747175717671777178717971807181718271837184718571867187718871897190719171927193719471957196719771987199720072017202720372047205720672077208720972107211721272137214721572167217721872197220722172227223722472257226722772287229723072317232723372347235723672377238723972407241724272437244724572467247724872497250725172527253725472557256725772587259726072617262726372647265726672677268726972707271727272737274727572767277727872797280728172827283728472857286728772887289729072917292729372947295729672977298729973007301730273037304730573067307730873097310731173127313731473157316731773187319732073217322732373247325732673277328732973307331733273337334733573367337733873397340734173427343734473457346734773487349735073517352735373547355735673577358735973607361736273637364736573667367736873697370737173727373737473757376737773787379738073817382738373847385738673877388738973907391739273937394739573967397739873997400740174027403740474057406740774087409741074117412741374147415741674177418741974207421742274237424742574267427742874297430743174327433743474357436743774387439744074417442744374447445744674477448744974507451745274537454745574567457745874597460746174627463746474657466746774687469747074717472747374747475747674777478747974807481748274837484748574867487748874897490749174927493749474957496749774987499750075017502750375047505750675077508750975107511751275137514751575167517751875197520752175227523752475257526752775287529753075317532753375347535753675377538753975407541754275437544754575467547754875497550755175527553755475557556755775587559756075617562756375647565756675677568756975707571757275737574757575767577757875797580758175827583758475857586758775887589759075917592759375947595759675977598759976007601760276037604760576067607760876097610761176127613761476157616761776187619762076217622762376247625762676277628762976307631763276337634763576367637763876397640764176427643764476457646764776487649765076517652765376547655765676577658765976607661766276637664766576667667766876697670767176727673767476757676767776787679768076817682768376847685768676877688768976907691769276937694769576967697769876997700770177027703770477057706770777087709771077117712771377147715771677177718771977207721772277237724772577267727772877297730773177327733773477357736773777387739774077417742774377447745774677477748774977507751775277537754775577567757775877597760776177627763776477657766776777687769777077717772777377747775777677777778777977807781778277837784778577867787778877897790779177927793779477957796779777987799780078017802780378047805780678077808780978107811781278137814781578167817781878197820782178227823782478257826782778287829783078317832783378347835783678377838783978407841784278437844784578467847784878497850785178527853785478557856785778587859786078617862786378647865786678677868786978707871787278737874787578767877787878797880788178827883788478857886788778887889789078917892789378947895789678977898789979007901790279037904790579067907790879097910791179127913791479157916791779187919792079217922792379247925792679277928792979307931793279337934793579367937793879397940794179427943794479457946794779487949795079517952795379547955795679577958795979607961796279637964796579667967796879697970797179727973797479757976797779787979798079817982798379847985798679877988798979907991799279937994799579967997799879998000800180028003800480058006800780088009801080118012801380148015801680178018801980208021802280238024802580268027802880298030803180328033803480358036803780388039804080418042804380448045804680478048804980508051805280538054805580568057805880598060806180628063806480658066806780688069807080718072807380748075807680778078807980808081808280838084808580868087808880898090809180928093809480958096809780988099810081018102810381048105810681078108810981108111811281138114811581168117811881198120812181228123812481258126812781288129813081318132813381348135813681378138813981408141814281438144814581468147814881498150815181528153815481558156815781588159816081618162816381648165816681678168816981708171817281738174817581768177817881798180818181828183818481858186818781888189819081918192819381948195819681978198819982008201820282038204820582068207820882098210821182128213821482158216821782188219822082218222822382248225822682278228822982308231823282338234823582368237823882398240824182428243824482458246824782488249825082518252825382548255825682578258825982608261826282638264826582668267826882698270827182728273827482758276827782788279828082818282828382848285828682878288828982908291829282938294829582968297829882998300830183028303830483058306830783088309831083118312831383148315831683178318831983208321832283238324832583268327832883298330833183328333833483358336833783388339834083418342834383448345834683478348834983508351835283538354835583568357835883598360836183628363836483658366836783688369837083718372837383748375837683778378837983808381838283838384838583868387838883898390839183928393839483958396839783988399840084018402840384048405840684078408840984108411841284138414841584168417841884198420842184228423842484258426842784288429843084318432843384348435843684378438843984408441844284438444844584468447844884498450845184528453845484558456845784588459846084618462846384648465846684678468846984708471847284738474847584768477847884798480848184828483848484858486848784888489849084918492849384948495849684978498849985008501850285038504850585068507850885098510851185128513851485158516851785188519852085218522852385248525852685278528852985308531853285338534853585368537853885398540854185428543854485458546854785488549855085518552855385548555855685578558855985608561856285638564856585668567856885698570857185728573857485758576857785788579858085818582858385848585858685878588858985908591859285938594859585968597859885998600860186028603860486058606860786088609861086118612861386148615861686178618861986208621862286238624862586268627862886298630863186328633863486358636863786388639864086418642864386448645864686478648864986508651865286538654865586568657865886598660866186628663866486658666866786688669867086718672867386748675867686778678867986808681868286838684868586868687868886898690869186928693869486958696869786988699870087018702870387048705870687078708870987108711871287138714871587168717871887198720872187228723872487258726872787288729873087318732873387348735873687378738873987408741874287438744874587468747874887498750875187528753875487558756875787588759876087618762876387648765876687678768876987708771877287738774877587768777877887798780878187828783878487858786878787888789879087918792879387948795879687978798879988008801880288038804880588068807880888098810881188128813881488158816881788188819882088218822882388248825882688278828882988308831883288338834883588368837883888398840884188428843884488458846884788488849885088518852885388548855885688578858885988608861886288638864886588668867886888698870887188728873887488758876887788788879888088818882888388848885888688878888888988908891889288938894889588968897889888998900890189028903890489058906890789088909891089118912891389148915891689178918891989208921892289238924892589268927892889298930893189328933893489358936893789388939894089418942894389448945894689478948894989508951895289538954895589568957895889598960896189628963896489658966896789688969897089718972897389748975897689778978897989808981898289838984898589868987898889898990899189928993899489958996899789988999900090019002900390049005900690079008900990109011901290139014901590169017901890199020902190229023902490259026902790289029903090319032903390349035903690379038903990409041904290439044904590469047904890499050905190529053905490559056905790589059906090619062906390649065906690679068906990709071907290739074907590769077907890799080908190829083908490859086908790889089909090919092909390949095909690979098909991009101910291039104910591069107910891099110911191129113911491159116911791189119912091219122912391249125912691279128912991309131913291339134913591369137913891399140914191429143914491459146914791489149915091519152915391549155915691579158915991609161916291639164916591669167916891699170917191729173917491759176917791789179918091819182918391849185918691879188918991909191919291939194919591969197919891999200920192029203920492059206920792089209921092119212921392149215921692179218921992209221922292239224922592269227922892299230923192329233923492359236923792389239924092419242924392449245924692479248924992509251925292539254925592569257925892599260926192629263926492659266926792689269927092719272927392749275927692779278927992809281928292839284928592869287928892899290929192929293929492959296929792989299930093019302930393049305930693079308930993109311931293139314931593169317931893199320932193229323932493259326932793289329933093319332933393349335933693379338933993409341934293439344934593469347934893499350935193529353935493559356935793589359936093619362936393649365936693679368936993709371937293739374937593769377937893799380938193829383938493859386938793889389939093919392939393949395939693979398939994009401940294039404940594069407940894099410941194129413941494159416941794189419942094219422942394249425942694279428942994309431943294339434943594369437943894399440944194429443944494459446944794489449945094519452945394549455945694579458945994609461946294639464946594669467946894699470947194729473947494759476947794789479948094819482948394849485948694879488948994909491949294939494949594969497949894999500950195029503950495059506950795089509951095119512951395149515951695179518951995209521952295239524952595269527952895299530953195329533953495359536953795389539954095419542954395449545954695479548954995509551955295539554955595569557955895599560956195629563956495659566956795689569957095719572957395749575957695779578957995809581958295839584958595869587958895899590959195929593959495959596959795989599960096019602960396049605960696079608960996109611961296139614961596169617961896199620962196229623962496259626962796289629963096319632963396349635963696379638963996409641964296439644964596469647964896499650965196529653965496559656965796589659966096619662966396649665966696679668966996709671967296739674967596769677967896799680968196829683968496859686968796889689969096919692969396949695969696979698969997009701970297039704970597069707970897099710971197129713971497159716971797189719972097219722972397249725972697279728972997309731973297339734973597369737973897399740974197429743974497459746974797489749975097519752975397549755975697579758975997609761976297639764976597669767976897699770977197729773977497759776977797789779978097819782978397849785978697879788978997909791979297939794979597969797979897999800980198029803980498059806980798089809981098119812981398149815981698179818981998209821982298239824982598269827982898299830983198329833983498359836983798389839984098419842984398449845984698479848984998509851985298539854985598569857985898599860986198629863986498659866986798689869987098719872987398749875987698779878987998809881988298839884988598869887988898899890989198929893989498959896989798989899990099019902990399049905990699079908990999109911991299139914991599169917991899199920992199229923992499259926992799289929993099319932993399349935993699379938993999409941994299439944994599469947994899499950995199529953995499559956995799589959996099619962996399649965996699679968996999709971997299739974997599769977997899799980998199829983998499859986998799889989999099919992999399949995999699979998999910000100011000210003100041000510006100071000810009100101001110012100131001410015100161001710018100191002010021100221002310024100251002610027100281002910030100311003210033100341003510036100371003810039100401004110042100431004410045100461004710048100491005010051100521005310054100551005610057100581005910060100611006210063100641006510066100671006810069100701007110072100731007410075100761007710078100791008010081100821008310084100851008610087100881008910090100911009210093100941009510096100971009810099101001010110102101031010410105101061010710108101091011010111101121011310114101151011610117101181011910120101211012210123101241012510126101271012810129101301013110132101331013410135101361013710138101391014010141101421014310144101451014610147101481014910150101511015210153101541015510156101571015810159101601016110162101631016410165101661016710168101691017010171101721017310174101751017610177101781017910180101811018210183101841018510186101871018810189101901019110192101931019410195101961019710198101991020010201102021020310204102051020610207102081020910210102111021210213102141021510216102171021810219102201022110222102231022410225102261022710228102291023010231102321023310234102351023610237102381023910240102411024210243102441024510246102471024810249102501025110252102531025410255102561025710258102591026010261102621026310264102651026610267102681026910270102711027210273102741027510276102771027810279102801028110282102831028410285102861028710288102891029010291102921029310294102951029610297102981029910300103011030210303103041030510306103071030810309103101031110312103131031410315103161031710318103191032010321103221032310324103251032610327103281032910330103311033210333103341033510336103371033810339103401034110342103431034410345103461034710348103491035010351103521035310354103551035610357103581035910360103611036210363103641036510366103671036810369103701037110372103731037410375103761037710378103791038010381103821038310384103851038610387103881038910390103911039210393103941039510396103971039810399104001040110402104031040410405104061040710408104091041010411104121041310414104151041610417104181041910420104211042210423104241042510426104271042810429104301043110432104331043410435104361043710438104391044010441104421044310444104451044610447104481044910450104511045210453104541045510456104571045810459104601046110462104631046410465104661046710468104691047010471104721047310474104751047610477104781047910480104811048210483104841048510486104871048810489104901049110492104931049410495104961049710498104991050010501105021050310504105051050610507105081050910510105111051210513105141051510516105171051810519105201052110522105231052410525105261052710528105291053010531105321053310534105351053610537105381053910540105411054210543105441054510546105471054810549105501055110552105531055410555105561055710558105591056010561105621056310564105651056610567105681056910570105711057210573105741057510576105771057810579105801058110582105831058410585105861058710588105891059010591105921059310594105951059610597105981059910600106011060210603106041060510606106071060810609106101061110612106131061410615106161061710618106191062010621106221062310624106251062610627106281062910630106311063210633106341063510636106371063810639106401064110642106431064410645106461064710648106491065010651106521065310654106551065610657106581065910660106611066210663106641066510666106671066810669106701067110672106731067410675106761067710678106791068010681106821068310684106851068610687106881068910690106911069210693106941069510696106971069810699107001070110702107031070410705107061070710708107091071010711107121071310714107151071610717107181071910720107211072210723107241072510726107271072810729107301073110732107331073410735107361073710738107391074010741107421074310744107451074610747107481074910750107511075210753107541075510756107571075810759107601076110762107631076410765107661076710768107691077010771107721077310774107751077610777107781077910780107811078210783107841078510786107871078810789107901079110792107931079410795107961079710798107991080010801108021080310804108051080610807108081080910810108111081210813108141081510816108171081810819108201082110822108231082410825108261082710828108291083010831108321083310834108351083610837108381083910840108411084210843108441084510846108471084810849108501085110852108531085410855108561085710858108591086010861108621086310864108651086610867108681086910870108711087210873108741087510876108771087810879108801088110882108831088410885108861088710888108891089010891108921089310894108951089610897108981089910900109011090210903109041090510906109071090810909109101091110912109131091410915109161091710918109191092010921109221092310924109251092610927109281092910930109311093210933109341093510936109371093810939109401094110942109431094410945109461094710948109491095010951109521095310954109551095610957109581095910960109611096210963109641096510966109671096810969109701097110972109731097410975109761097710978109791098010981109821098310984109851098610987109881098910990109911099210993109941099510996109971099810999110001100111002110031100411005110061100711008110091101011011110121101311014110151101611017110181101911020110211102211023110241102511026110271102811029110301103111032110331103411035110361103711038110391104011041110421104311044110451104611047110481104911050110511105211053110541105511056110571105811059110601106111062110631106411065110661106711068110691107011071110721107311074110751107611077110781107911080110811108211083110841108511086110871108811089110901109111092110931109411095110961109711098110991110011101111021110311104111051110611107111081110911110111111111211113111141111511116111171111811119111201112111122111231112411125111261112711128111291113011131111321113311134111351113611137111381113911140111411114211143111441114511146111471114811149111501115111152111531115411155111561115711158111591116011161111621116311164111651116611167111681116911170111711117211173111741117511176111771117811179111801118111182111831118411185111861118711188111891119011191111921119311194111951119611197111981119911200112011120211203112041120511206112071120811209112101121111212112131121411215112161121711218112191122011221112221122311224112251122611227112281122911230112311123211233112341123511236112371123811239112401124111242112431124411245112461124711248112491125011251112521125311254112551125611257112581125911260112611126211263112641126511266112671126811269112701127111272112731127411275112761127711278112791128011281112821128311284112851128611287112881128911290112911129211293112941129511296112971129811299113001130111302113031130411305113061130711308113091131011311113121131311314113151131611317113181131911320113211132211323113241132511326113271132811329113301133111332113331133411335113361133711338113391134011341113421134311344113451134611347113481134911350113511135211353113541135511356113571135811359113601136111362113631136411365113661136711368113691137011371113721137311374113751137611377113781137911380113811138211383113841138511386113871138811389113901139111392113931139411395113961139711398113991140011401114021140311404114051140611407114081140911410114111141211413114141141511416114171141811419114201142111422114231142411425114261142711428114291143011431114321143311434114351143611437114381143911440114411144211443114441144511446114471144811449114501145111452114531145411455114561145711458114591146011461114621146311464114651146611467114681146911470114711147211473114741147511476114771147811479114801148111482114831148411485114861148711488114891149011491114921149311494114951149611497114981149911500115011150211503115041150511506115071150811509115101151111512115131151411515115161151711518115191152011521115221152311524115251152611527115281152911530115311153211533115341153511536115371153811539115401154111542115431154411545115461154711548115491155011551115521155311554115551155611557115581155911560115611156211563115641156511566115671156811569115701157111572115731157411575115761157711578115791158011581115821158311584115851158611587115881158911590115911159211593115941159511596115971159811599116001160111602116031160411605116061160711608116091161011611116121161311614116151161611617116181161911620116211162211623116241162511626116271162811629116301163111632116331163411635116361163711638116391164011641116421164311644116451164611647116481164911650116511165211653116541165511656116571165811659116601166111662116631166411665116661166711668116691167011671116721167311674116751167611677116781167911680116811168211683116841168511686116871168811689116901169111692116931169411695116961169711698116991170011701117021170311704117051170611707117081170911710117111171211713117141171511716117171171811719117201172111722117231172411725117261172711728117291173011731117321173311734117351173611737117381173911740117411174211743117441174511746117471174811749117501175111752117531175411755117561175711758117591176011761117621176311764117651176611767117681176911770117711177211773117741177511776117771177811779117801178111782117831178411785117861178711788117891179011791117921179311794117951179611797117981179911800118011180211803118041180511806118071180811809118101181111812118131181411815118161181711818118191182011821118221182311824118251182611827118281182911830118311183211833118341183511836118371183811839118401184111842118431184411845118461184711848118491185011851118521185311854118551185611857118581185911860118611186211863118641186511866118671186811869118701187111872118731187411875118761187711878118791188011881118821188311884118851188611887118881188911890118911189211893118941189511896118971189811899119001190111902119031190411905119061190711908119091191011911119121191311914119151191611917119181191911920119211192211923119241192511926119271192811929119301193111932119331193411935119361193711938119391194011941119421194311944119451194611947119481194911950119511195211953119541195511956119571195811959119601196111962119631196411965119661196711968119691197011971119721197311974119751197611977119781197911980119811198211983119841198511986119871198811989119901199111992119931199411995119961199711998119991200012001120021200312004120051200612007120081200912010120111201212013120141201512016120171201812019120201202112022120231202412025120261202712028120291203012031120321203312034120351203612037120381203912040120411204212043120441204512046120471204812049120501205112052120531205412055120561205712058120591206012061120621206312064120651206612067120681206912070120711207212073120741207512076120771207812079120801208112082120831208412085120861208712088120891209012091120921209312094120951209612097120981209912100121011210212103121041210512106121071210812109121101211112112121131211412115121161211712118121191212012121121221212312124121251212612127121281212912130121311213212133121341213512136121371213812139121401214112142121431214412145121461214712148121491215012151121521215312154121551215612157121581215912160121611216212163121641216512166121671216812169121701217112172121731217412175121761217712178121791218012181121821218312184121851218612187121881218912190121911219212193121941219512196121971219812199122001220112202122031220412205122061220712208122091221012211122121221312214122151221612217122181221912220122211222212223122241222512226122271222812229122301223112232122331223412235122361223712238122391224012241122421224312244122451224612247122481224912250122511225212253122541225512256122571225812259122601226112262122631226412265122661226712268122691227012271122721227312274122751227612277122781227912280122811228212283122841228512286122871228812289122901229112292122931229412295122961229712298122991230012301123021230312304123051230612307123081230912310123111231212313123141231512316123171231812319123201232112322123231232412325123261232712328123291233012331123321233312334123351233612337123381233912340123411234212343123441234512346123471234812349123501235112352123531235412355123561235712358123591236012361123621236312364123651236612367123681236912370123711237212373123741237512376123771237812379123801238112382123831238412385123861238712388123891239012391123921239312394123951239612397123981239912400124011240212403124041240512406124071240812409124101241112412124131241412415124161241712418124191242012421124221242312424124251242612427124281242912430124311243212433124341243512436124371243812439124401244112442124431244412445124461244712448124491245012451124521245312454124551245612457124581245912460124611246212463124641246512466124671246812469124701247112472124731247412475124761247712478124791248012481124821248312484124851248612487124881248912490124911249212493124941249512496124971249812499125001250112502125031250412505125061250712508125091251012511125121251312514125151251612517125181251912520125211252212523125241252512526125271252812529125301253112532125331253412535125361253712538125391254012541125421254312544125451254612547125481254912550125511255212553125541255512556125571255812559125601256112562125631256412565125661256712568125691257012571125721257312574125751257612577125781257912580125811258212583125841258512586125871258812589125901259112592125931259412595125961259712598125991260012601126021260312604126051260612607126081260912610126111261212613126141261512616126171261812619126201262112622126231262412625126261262712628126291263012631126321263312634126351263612637126381263912640126411264212643126441264512646126471264812649126501265112652126531265412655126561265712658126591266012661126621266312664126651266612667126681266912670126711267212673126741267512676126771267812679126801268112682126831268412685126861268712688126891269012691126921269312694126951269612697126981269912700127011270212703127041270512706127071270812709127101271112712127131271412715127161271712718127191272012721127221272312724127251272612727127281272912730127311273212733127341273512736127371273812739127401274112742127431274412745127461274712748127491275012751127521275312754127551275612757127581275912760127611276212763127641276512766127671276812769127701277112772127731277412775127761277712778127791278012781127821278312784127851278612787127881278912790127911279212793127941279512796127971279812799128001280112802128031280412805128061280712808128091281012811128121281312814128151281612817128181281912820128211282212823128241282512826128271282812829128301283112832128331283412835128361283712838128391284012841128421284312844128451284612847128481284912850128511285212853128541285512856128571285812859128601286112862128631286412865128661286712868128691287012871128721287312874128751287612877128781287912880128811288212883128841288512886128871288812889128901289112892128931289412895128961289712898128991290012901129021290312904129051290612907129081290912910129111291212913129141291512916129171291812919129201292112922129231292412925129261292712928129291293012931129321293312934129351293612937129381293912940129411294212943129441294512946129471294812949129501295112952129531295412955129561295712958129591296012961129621296312964129651296612967129681296912970129711297212973129741297512976129771297812979129801298112982129831298412985129861298712988129891299012991129921299312994129951299612997129981299913000130011300213003130041300513006130071300813009130101301113012130131301413015130161301713018130191302013021130221302313024130251302613027130281302913030130311303213033130341303513036130371303813039130401304113042130431304413045130461304713048130491305013051130521305313054130551305613057130581305913060130611306213063130641306513066130671306813069130701307113072130731307413075130761307713078130791308013081130821308313084130851308613087130881308913090130911309213093130941309513096130971309813099131001310113102131031310413105131061310713108131091311013111131121311313114131151311613117131181311913120131211312213123131241312513126131271312813129131301313113132131331313413135131361313713138131391314013141131421314313144131451314613147131481314913150131511315213153131541315513156131571315813159131601316113162131631316413165131661316713168131691317013171131721317313174131751317613177131781317913180131811318213183131841318513186131871318813189131901319113192131931319413195131961319713198131991320013201132021320313204132051320613207132081320913210132111321213213132141321513216132171321813219132201322113222132231322413225132261322713228132291323013231132321323313234132351323613237132381323913240132411324213243132441324513246132471324813249132501325113252132531325413255132561325713258132591326013261132621326313264132651326613267132681326913270132711327213273132741327513276132771327813279132801328113282132831328413285132861328713288132891329013291132921329313294132951329613297132981329913300133011330213303133041330513306133071330813309133101331113312133131331413315133161331713318133191332013321133221332313324133251332613327133281332913330133311333213333133341333513336133371333813339133401334113342133431334413345133461334713348133491335013351133521335313354133551335613357133581335913360133611336213363133641336513366133671336813369133701337113372133731337413375133761337713378133791338013381133821338313384133851338613387133881338913390133911339213393133941339513396133971339813399134001340113402134031340413405134061340713408134091341013411134121341313414134151341613417134181341913420134211342213423134241342513426134271342813429134301343113432134331343413435134361343713438134391344013441134421344313444134451344613447134481344913450134511345213453134541345513456134571345813459134601346113462134631346413465134661346713468134691347013471134721347313474134751347613477134781347913480134811348213483134841348513486134871348813489134901349113492134931349413495134961349713498134991350013501135021350313504135051350613507135081350913510135111351213513135141351513516135171351813519135201352113522135231352413525135261352713528135291353013531135321353313534135351353613537135381353913540135411354213543135441354513546135471354813549135501355113552135531355413555135561355713558135591356013561135621356313564135651356613567135681356913570135711357213573135741357513576135771357813579135801358113582135831358413585135861358713588135891359013591135921359313594135951359613597135981359913600136011360213603136041360513606136071360813609136101361113612136131361413615136161361713618136191362013621136221362313624136251362613627136281362913630136311363213633136341363513636136371363813639136401364113642136431364413645136461364713648136491365013651136521365313654136551365613657136581365913660136611366213663136641366513666136671366813669136701367113672136731367413675136761367713678136791368013681136821368313684136851368613687136881368913690136911369213693136941369513696136971369813699137001370113702137031370413705137061370713708137091371013711137121371313714137151371613717137181371913720137211372213723137241372513726137271372813729137301373113732137331373413735137361373713738137391374013741137421374313744137451374613747137481374913750137511375213753137541375513756137571375813759137601376113762137631376413765137661376713768137691377013771137721377313774137751377613777137781377913780137811378213783137841378513786137871378813789137901379113792137931379413795137961379713798137991380013801138021380313804138051380613807138081380913810138111381213813138141381513816138171381813819138201382113822138231382413825138261382713828138291383013831138321383313834138351383613837138381383913840138411384213843138441384513846138471384813849138501385113852138531385413855138561385713858138591386013861138621386313864138651386613867138681386913870138711387213873138741387513876138771387813879138801388113882138831388413885138861388713888138891389013891138921389313894138951389613897138981389913900139011390213903139041390513906139071390813909139101391113912139131391413915139161391713918139191392013921139221392313924139251392613927139281392913930139311393213933139341393513936139371393813939139401394113942139431394413945139461394713948139491395013951139521395313954139551395613957139581395913960139611396213963139641396513966139671396813969139701397113972139731397413975139761397713978139791398013981139821398313984139851398613987139881398913990139911399213993139941399513996139971399813999140001400114002140031400414005140061400714008140091401014011140121401314014140151401614017140181401914020140211402214023140241402514026140271402814029140301403114032140331403414035140361403714038140391404014041140421404314044140451404614047140481404914050140511405214053140541405514056140571405814059140601406114062140631406414065140661406714068140691407014071140721407314074140751407614077140781407914080140811408214083140841408514086140871408814089140901409114092140931409414095140961409714098140991410014101141021410314104141051410614107141081410914110141111411214113141141411514116141171411814119141201412114122141231412414125141261412714128141291413014131141321413314134141351413614137141381413914140141411414214143141441414514146141471414814149141501415114152141531415414155141561415714158141591416014161141621416314164141651416614167141681416914170141711417214173141741417514176141771417814179141801418114182141831418414185141861418714188141891419014191141921419314194141951419614197141981419914200142011420214203142041420514206142071420814209142101421114212142131421414215142161421714218142191422014221142221422314224142251422614227142281422914230142311423214233142341423514236142371423814239142401424114242142431424414245142461424714248142491425014251142521425314254142551425614257142581425914260142611426214263142641426514266142671426814269142701427114272142731427414275142761427714278142791428014281142821428314284142851428614287142881428914290142911429214293142941429514296142971429814299143001430114302143031430414305143061430714308143091431014311143121431314314143151431614317143181431914320143211432214323143241432514326143271432814329143301433114332143331433414335143361433714338143391434014341143421434314344143451434614347143481434914350143511435214353143541435514356143571435814359143601436114362143631436414365143661436714368143691437014371143721437314374143751437614377143781437914380143811438214383143841438514386143871438814389143901439114392143931439414395143961439714398143991440014401144021440314404144051440614407144081440914410144111441214413144141441514416144171441814419144201442114422144231442414425144261442714428144291443014431144321443314434144351443614437144381443914440144411444214443144441444514446144471444814449144501445114452144531445414455144561445714458144591446014461144621446314464144651446614467144681446914470144711447214473144741447514476144771447814479144801448114482144831448414485144861448714488144891449014491144921449314494144951449614497144981449914500145011450214503145041450514506145071450814509145101451114512145131451414515145161451714518145191452014521145221452314524145251452614527145281452914530145311453214533145341453514536145371453814539145401454114542145431454414545145461454714548145491455014551145521455314554145551455614557145581455914560145611456214563145641456514566145671456814569145701457114572145731457414575145761457714578145791458014581145821458314584145851458614587145881458914590145911459214593145941459514596145971459814599146001460114602146031460414605146061460714608146091461014611146121461314614146151461614617146181461914620146211462214623146241462514626146271462814629146301463114632146331463414635146361463714638146391464014641146421464314644146451464614647146481464914650146511465214653146541465514656146571465814659146601466114662146631466414665146661466714668146691467014671146721467314674146751467614677146781467914680146811468214683146841468514686146871468814689146901469114692146931469414695146961469714698146991470014701147021470314704147051470614707147081470914710147111471214713147141471514716147171471814719147201472114722147231472414725147261472714728147291473014731147321473314734147351473614737147381473914740147411474214743147441474514746147471474814749147501475114752147531475414755147561475714758147591476014761147621476314764147651476614767147681476914770147711477214773147741477514776147771477814779147801478114782147831478414785147861478714788147891479014791147921479314794147951479614797147981479914800148011480214803148041480514806148071480814809148101481114812148131481414815148161481714818148191482014821148221482314824148251482614827148281482914830148311483214833148341483514836148371483814839148401484114842148431484414845148461484714848148491485014851148521485314854148551485614857148581485914860148611486214863148641486514866148671486814869148701487114872148731487414875148761487714878148791488014881148821488314884148851488614887148881488914890148911489214893148941489514896148971489814899149001490114902149031490414905149061490714908149091491014911149121491314914149151491614917149181491914920149211492214923149241492514926149271492814929149301493114932149331493414935149361493714938149391494014941149421494314944149451494614947149481494914950149511495214953149541495514956149571495814959149601496114962149631496414965149661496714968149691497014971149721497314974149751497614977149781497914980149811498214983149841498514986149871498814989149901499114992149931499414995149961499714998149991500015001150021500315004150051500615007150081500915010150111501215013150141501515016150171501815019150201502115022150231502415025150261502715028150291503015031150321503315034150351503615037150381503915040150411504215043150441504515046150471504815049150501505115052150531505415055150561505715058150591506015061150621506315064150651506615067150681506915070150711507215073150741507515076150771507815079150801508115082150831508415085150861508715088150891509015091150921509315094150951509615097150981509915100151011510215103151041510515106151071510815109151101511115112151131511415115151161511715118151191512015121151221512315124151251512615127151281512915130151311513215133151341513515136151371513815139151401514115142151431514415145151461514715148151491515015151151521515315154151551515615157151581515915160151611516215163151641516515166151671516815169151701517115172151731517415175151761517715178151791518015181151821518315184151851518615187151881518915190151911519215193151941519515196151971519815199152001520115202152031520415205152061520715208152091521015211152121521315214152151521615217152181521915220152211522215223152241522515226152271522815229152301523115232152331523415235152361523715238152391524015241152421524315244152451524615247152481524915250152511525215253152541525515256152571525815259152601526115262152631526415265152661526715268152691527015271152721527315274152751527615277152781527915280152811528215283152841528515286152871528815289152901529115292152931529415295152961529715298152991530015301153021530315304153051530615307153081530915310153111531215313153141531515316153171531815319153201532115322153231532415325153261532715328153291533015331153321533315334153351533615337153381533915340153411534215343153441534515346153471534815349153501535115352153531535415355153561535715358153591536015361153621536315364153651536615367153681536915370153711537215373153741537515376153771537815379153801538115382153831538415385153861538715388153891539015391153921539315394153951539615397153981539915400154011540215403154041540515406154071540815409154101541115412154131541415415154161541715418154191542015421154221542315424154251542615427154281542915430154311543215433154341543515436154371543815439154401544115442154431544415445154461544715448154491545015451154521545315454154551545615457154581545915460154611546215463154641546515466154671546815469154701547115472154731547415475154761547715478154791548015481154821548315484154851548615487154881548915490154911549215493154941549515496154971549815499155001550115502155031550415505155061550715508155091551015511155121551315514155151551615517155181551915520155211552215523155241552515526155271552815529155301553115532155331553415535155361553715538155391554015541155421554315544155451554615547155481554915550155511555215553155541555515556155571555815559155601556115562155631556415565155661556715568155691557015571155721557315574155751557615577155781557915580155811558215583155841558515586155871558815589155901559115592155931559415595155961559715598155991560015601156021560315604156051560615607156081560915610156111561215613156141561515616156171561815619156201562115622156231562415625156261562715628156291563015631156321563315634156351563615637156381563915640156411564215643156441564515646156471564815649156501565115652156531565415655156561565715658156591566015661156621566315664156651566615667156681566915670156711567215673156741567515676156771567815679156801568115682156831568415685156861568715688156891569015691156921569315694156951569615697156981569915700157011570215703157041570515706157071570815709157101571115712157131571415715157161571715718157191572015721157221572315724157251572615727157281572915730157311573215733157341573515736157371573815739157401574115742157431574415745157461574715748157491575015751157521575315754157551575615757157581575915760157611576215763157641576515766157671576815769157701577115772157731577415775157761577715778157791578015781157821578315784157851578615787157881578915790157911579215793157941579515796157971579815799158001580115802158031580415805158061580715808158091581015811158121581315814158151581615817158181581915820158211582215823158241582515826158271582815829158301583115832158331583415835158361583715838158391584015841158421584315844158451584615847158481584915850158511585215853158541585515856158571585815859158601586115862158631586415865158661586715868158691587015871158721587315874158751587615877158781587915880158811588215883158841588515886158871588815889158901589115892158931589415895158961589715898158991590015901159021590315904159051590615907159081590915910159111591215913159141591515916159171591815919159201592115922159231592415925159261592715928159291593015931159321593315934159351593615937159381593915940159411594215943159441594515946159471594815949159501595115952159531595415955159561595715958159591596015961159621596315964159651596615967159681596915970159711597215973159741597515976159771597815979159801598115982159831598415985159861598715988159891599015991159921599315994159951599615997159981599916000160011600216003160041600516006160071600816009160101601116012160131601416015160161601716018160191602016021160221602316024160251602616027160281602916030160311603216033160341603516036160371603816039160401604116042160431604416045160461604716048160491605016051160521605316054160551605616057160581605916060160611606216063160641606516066160671606816069160701607116072160731607416075160761607716078160791608016081160821608316084160851608616087160881608916090160911609216093160941609516096160971609816099161001610116102161031610416105161061610716108161091611016111161121611316114161151611616117161181611916120161211612216123161241612516126161271612816129161301613116132161331613416135161361613716138161391614016141161421614316144161451614616147161481614916150161511615216153161541615516156161571615816159161601616116162161631616416165161661616716168161691617016171161721617316174161751617616177161781617916180161811618216183161841618516186161871618816189161901619116192161931619416195161961619716198161991620016201162021620316204162051620616207162081620916210162111621216213162141621516216162171621816219162201622116222162231622416225162261622716228162291623016231162321623316234162351623616237162381623916240162411624216243162441624516246162471624816249162501625116252162531625416255162561625716258162591626016261162621626316264162651626616267162681626916270162711627216273162741627516276162771627816279162801628116282162831628416285162861628716288162891629016291162921629316294162951629616297162981629916300163011630216303163041630516306163071630816309163101631116312163131631416315163161631716318163191632016321163221632316324163251632616327163281632916330163311633216333163341633516336163371633816339163401634116342163431634416345163461634716348163491635016351163521635316354163551635616357163581635916360163611636216363163641636516366163671636816369163701637116372163731637416375163761637716378163791638016381163821638316384163851638616387163881638916390163911639216393163941639516396163971639816399164001640116402164031640416405164061640716408164091641016411164121641316414164151641616417164181641916420164211642216423164241642516426164271642816429164301643116432164331643416435164361643716438164391644016441164421644316444164451644616447164481644916450164511645216453164541645516456164571645816459164601646116462164631646416465164661646716468164691647016471164721647316474164751647616477164781647916480164811648216483164841648516486164871648816489164901649116492164931649416495164961649716498164991650016501165021650316504165051650616507165081650916510165111651216513165141651516516165171651816519165201652116522165231652416525165261652716528165291653016531165321653316534165351653616537165381653916540165411654216543165441654516546165471654816549165501655116552165531655416555165561655716558165591656016561165621656316564165651656616567165681656916570165711657216573165741657516576165771657816579165801658116582165831658416585165861658716588165891659016591165921659316594165951659616597165981659916600166011660216603166041660516606166071660816609166101661116612166131661416615166161661716618166191662016621166221662316624166251662616627166281662916630166311663216633166341663516636166371663816639166401664116642166431664416645166461664716648166491665016651166521665316654166551665616657166581665916660166611666216663166641666516666166671666816669166701667116672166731667416675166761667716678166791668016681166821668316684166851668616687166881668916690166911669216693166941669516696166971669816699167001670116702167031670416705167061670716708167091671016711167121671316714167151671616717167181671916720167211672216723167241672516726167271672816729167301673116732167331673416735167361673716738167391674016741167421674316744167451674616747167481674916750167511675216753167541675516756167571675816759167601676116762167631676416765167661676716768167691677016771167721677316774167751677616777167781677916780167811678216783167841678516786167871678816789167901679116792167931679416795167961679716798167991680016801168021680316804168051680616807168081680916810168111681216813168141681516816168171681816819168201682116822168231682416825168261682716828168291683016831168321683316834168351683616837168381683916840168411684216843168441684516846168471684816849168501685116852168531685416855168561685716858168591686016861168621686316864168651686616867168681686916870168711687216873168741687516876168771687816879168801688116882168831688416885168861688716888168891689016891168921689316894168951689616897168981689916900169011690216903169041690516906169071690816909169101691116912169131691416915169161691716918169191692016921169221692316924169251692616927169281692916930169311693216933169341693516936169371693816939169401694116942169431694416945169461694716948169491695016951169521695316954169551695616957169581695916960169611696216963169641696516966169671696816969169701697116972169731697416975169761697716978169791698016981169821698316984169851698616987169881698916990169911699216993169941699516996169971699816999170001700117002170031700417005170061700717008170091701017011170121701317014170151701617017170181701917020170211702217023170241702517026170271702817029170301703117032170331703417035170361703717038170391704017041170421704317044170451704617047170481704917050170511705217053170541705517056170571705817059170601706117062170631706417065170661706717068170691707017071170721707317074170751707617077170781707917080170811708217083170841708517086170871708817089170901709117092170931709417095170961709717098170991710017101171021710317104171051710617107171081710917110171111711217113171141711517116171171711817119171201712117122171231712417125171261712717128171291713017131171321713317134171351713617137171381713917140171411714217143171441714517146171471714817149171501715117152171531715417155171561715717158171591716017161171621716317164171651716617167171681716917170171711717217173171741717517176171771717817179171801718117182171831718417185171861718717188171891719017191171921719317194171951719617197171981719917200172011720217203172041720517206172071720817209172101721117212172131721417215172161721717218172191722017221172221722317224172251722617227172281722917230172311723217233172341723517236172371723817239172401724117242172431724417245172461724717248172491725017251172521725317254172551725617257172581725917260172611726217263172641726517266172671726817269172701727117272172731727417275172761727717278172791728017281172821728317284172851728617287172881728917290172911729217293172941729517296172971729817299173001730117302173031730417305173061730717308173091731017311173121731317314173151731617317173181731917320173211732217323173241732517326173271732817329173301733117332173331733417335173361733717338173391734017341173421734317344173451734617347173481734917350173511735217353173541735517356173571735817359173601736117362173631736417365173661736717368173691737017371173721737317374173751737617377173781737917380173811738217383173841738517386173871738817389173901739117392173931739417395173961739717398173991740017401174021740317404174051740617407174081740917410174111741217413174141741517416174171741817419174201742117422174231742417425174261742717428174291743017431174321743317434174351743617437174381743917440174411744217443174441744517446174471744817449174501745117452174531745417455174561745717458174591746017461174621746317464174651746617467174681746917470174711747217473174741747517476174771747817479174801748117482174831748417485174861748717488174891749017491174921749317494174951749617497174981749917500175011750217503175041750517506175071750817509175101751117512175131751417515175161751717518175191752017521175221752317524175251752617527175281752917530175311753217533175341753517536175371753817539175401754117542175431754417545175461754717548175491755017551175521755317554175551755617557175581755917560175611756217563175641756517566175671756817569175701757117572175731757417575175761757717578175791758017581175821758317584175851758617587175881758917590175911759217593175941759517596175971759817599176001760117602176031760417605176061760717608176091761017611176121761317614176151761617617176181761917620176211762217623176241762517626176271762817629176301763117632176331763417635176361763717638176391764017641176421764317644176451764617647176481764917650176511765217653176541765517656176571765817659176601766117662176631766417665176661766717668176691767017671176721767317674176751767617677176781767917680176811768217683176841768517686176871768817689176901769117692176931769417695176961769717698176991770017701177021770317704177051770617707177081770917710177111771217713177141771517716177171771817719177201772117722177231772417725177261772717728177291773017731177321773317734177351773617737177381773917740177411774217743177441774517746177471774817749177501775117752177531775417755177561775717758177591776017761177621776317764177651776617767177681776917770177711777217773177741777517776177771777817779177801778117782177831778417785177861778717788177891779017791177921779317794177951779617797177981779917800178011780217803178041780517806178071780817809178101781117812178131781417815178161781717818178191782017821178221782317824178251782617827178281782917830178311783217833178341783517836178371783817839178401784117842178431784417845178461784717848178491785017851178521785317854178551785617857178581785917860178611786217863178641786517866178671786817869178701787117872178731787417875178761787717878178791788017881178821788317884178851788617887178881788917890178911789217893178941789517896178971789817899179001790117902179031790417905179061790717908179091791017911179121791317914179151791617917179181791917920179211792217923179241792517926179271792817929179301793117932179331793417935179361793717938179391794017941179421794317944179451794617947179481794917950179511795217953179541795517956179571795817959179601796117962179631796417965179661796717968179691797017971179721797317974179751797617977179781797917980179811798217983179841798517986179871798817989179901799117992179931799417995179961799717998179991800018001180021800318004180051800618007180081800918010180111801218013180141801518016180171801818019180201802118022180231802418025180261802718028180291803018031180321803318034180351803618037180381803918040180411804218043180441804518046180471804818049180501805118052180531805418055180561805718058180591806018061180621806318064180651806618067180681806918070180711807218073180741807518076180771807818079180801808118082180831808418085180861808718088180891809018091180921809318094180951809618097180981809918100181011810218103181041810518106181071810818109181101811118112181131811418115181161811718118181191812018121181221812318124181251812618127181281812918130181311813218133181341813518136181371813818139181401814118142181431814418145181461814718148181491815018151181521815318154181551815618157181581815918160181611816218163181641816518166181671816818169181701817118172181731817418175181761817718178181791818018181181821818318184181851818618187181881818918190181911819218193181941819518196181971819818199182001820118202182031820418205182061820718208182091821018211182121821318214182151821618217182181821918220182211822218223182241822518226182271822818229182301823118232182331823418235182361823718238182391824018241182421824318244182451824618247182481824918250182511825218253182541825518256182571825818259182601826118262182631826418265182661826718268182691827018271182721827318274182751827618277182781827918280182811828218283182841828518286182871828818289182901829118292182931829418295182961829718298182991830018301183021830318304183051830618307183081830918310183111831218313183141831518316183171831818319183201832118322183231832418325183261832718328183291833018331183321833318334183351833618337183381833918340183411834218343183441834518346183471834818349183501835118352183531835418355183561835718358183591836018361183621836318364183651836618367183681836918370183711837218373183741837518376183771837818379183801838118382183831838418385183861838718388183891839018391183921839318394183951839618397183981839918400184011840218403184041840518406184071840818409184101841118412184131841418415184161841718418184191842018421184221842318424184251842618427184281842918430184311843218433184341843518436184371843818439184401844118442184431844418445184461844718448184491845018451184521845318454184551845618457184581845918460184611846218463184641846518466184671846818469184701847118472184731847418475184761847718478184791848018481184821848318484184851848618487184881848918490184911849218493184941849518496184971849818499185001850118502185031850418505185061850718508185091851018511185121851318514185151851618517185181851918520185211852218523185241852518526185271852818529185301853118532185331853418535185361853718538185391854018541185421854318544185451854618547185481854918550185511855218553185541855518556185571855818559185601856118562185631856418565185661856718568185691857018571185721857318574185751857618577185781857918580185811858218583185841858518586185871858818589185901859118592185931859418595185961859718598185991860018601186021860318604186051860618607186081860918610186111861218613186141861518616186171861818619186201862118622186231862418625186261862718628186291863018631186321863318634186351863618637186381863918640186411864218643186441864518646186471864818649186501865118652186531865418655186561865718658186591866018661186621866318664186651866618667186681866918670186711867218673186741867518676186771867818679186801868118682186831868418685186861868718688186891869018691186921869318694186951869618697186981869918700187011870218703187041870518706187071870818709187101871118712187131871418715187161871718718187191872018721187221872318724187251872618727187281872918730187311873218733187341873518736187371873818739187401874118742187431874418745187461874718748187491875018751187521875318754187551875618757187581875918760187611876218763187641876518766187671876818769187701877118772187731877418775187761877718778187791878018781187821878318784187851878618787187881878918790187911879218793187941879518796187971879818799188001880118802188031880418805188061880718808188091881018811188121881318814188151881618817188181881918820188211882218823188241882518826188271882818829188301883118832188331883418835188361883718838188391884018841188421884318844188451884618847188481884918850188511885218853188541885518856188571885818859188601886118862188631886418865188661886718868188691887018871188721887318874188751887618877188781887918880188811888218883188841888518886188871888818889188901889118892188931889418895188961889718898188991890018901189021890318904189051890618907189081890918910189111891218913189141891518916189171891818919189201892118922189231892418925189261892718928189291893018931189321893318934189351893618937189381893918940189411894218943189441894518946189471894818949189501895118952189531895418955189561895718958189591896018961189621896318964189651896618967189681896918970189711897218973189741897518976189771897818979189801898118982189831898418985189861898718988189891899018991189921899318994189951899618997189981899919000190011900219003190041900519006190071900819009190101901119012190131901419015190161901719018190191902019021190221902319024190251902619027190281902919030190311903219033190341903519036190371903819039190401904119042190431904419045190461904719048190491905019051190521905319054190551905619057190581905919060190611906219063190641906519066190671906819069190701907119072190731907419075190761907719078190791908019081190821908319084190851908619087190881908919090190911909219093190941909519096190971909819099191001910119102191031910419105191061910719108191091911019111191121911319114191151911619117191181911919120191211912219123191241912519126191271912819129191301913119132191331913419135191361913719138191391914019141191421914319144191451914619147191481914919150191511915219153191541915519156191571915819159191601916119162191631916419165191661916719168191691917019171191721917319174191751917619177191781917919180191811918219183191841918519186191871918819189191901919119192191931919419195191961919719198191991920019201192021920319204192051920619207192081920919210192111921219213192141921519216192171921819219192201922119222192231922419225192261922719228192291923019231192321923319234192351923619237192381923919240192411924219243192441924519246192471924819249192501925119252192531925419255192561925719258192591926019261192621926319264192651926619267192681926919270192711927219273192741927519276192771927819279192801928119282192831928419285192861928719288192891929019291192921929319294192951929619297192981929919300193011930219303193041930519306193071930819309193101931119312193131931419315193161931719318193191932019321193221932319324193251932619327193281932919330193311933219333193341933519336193371933819339193401934119342193431934419345193461934719348193491935019351193521935319354193551935619357193581935919360193611936219363193641936519366193671936819369193701937119372193731937419375193761937719378193791938019381193821938319384193851938619387193881938919390193911939219393193941939519396193971939819399194001940119402194031940419405194061940719408194091941019411194121941319414194151941619417194181941919420194211942219423194241942519426194271942819429194301943119432194331943419435194361943719438194391944019441194421944319444194451944619447194481944919450194511945219453194541945519456194571945819459194601946119462194631946419465194661946719468194691947019471194721947319474194751947619477194781947919480194811948219483194841948519486194871948819489194901949119492194931949419495194961949719498194991950019501195021950319504195051950619507195081950919510195111951219513195141951519516195171951819519195201952119522195231952419525195261952719528195291953019531195321953319534195351953619537195381953919540195411954219543195441954519546195471954819549195501955119552195531955419555195561955719558195591956019561195621956319564195651956619567195681956919570195711957219573195741957519576195771957819579195801958119582195831958419585195861958719588195891959019591195921959319594195951959619597195981959919600196011960219603196041960519606196071960819609196101961119612196131961419615196161961719618196191962019621196221962319624196251962619627196281962919630196311963219633196341963519636196371963819639196401964119642196431964419645196461964719648196491965019651196521965319654196551965619657196581965919660196611966219663196641966519666196671966819669196701967119672196731967419675196761967719678196791968019681196821968319684196851968619687196881968919690196911969219693196941969519696196971969819699197001970119702
  1. \input texinfo @c -*- coding: utf-8 -*-
  2. @c %**start of header
  3. @setfilename ../../info/org.info
  4. @settitle The Org Manual
  5. @include docstyle.texi
  6. @include org-version.inc
  7. @c Version and Contact Info
  8. @set MAINTAINERSITE @uref{http://orgmode.org,maintainers web page}
  9. @set AUTHOR Carsten Dominik
  10. @set MAINTAINER Carsten Dominik
  11. @set MAINTAINEREMAIL @email{carsten at orgmode dot org}
  12. @set MAINTAINERCONTACT @uref{mailto:carsten at orgmode dot org,contact the maintainer}
  13. @c %**end of header
  14. @finalout
  15. @c -----------------------------------------------------------------------------
  16. @c Macro definitions for commands and keys
  17. @c =======================================
  18. @c The behavior of the key/command macros will depend on the flag cmdnames
  19. @c When set, commands names are shown. When clear, they are not shown.
  20. @set cmdnames
  21. @c Below we define the following macros for Org key tables:
  22. @c orgkey{key} A key item
  23. @c orgcmd{key,cmd} Key with command name
  24. @c xorgcmd{key,cmd} Key with command name as @itemx
  25. @c orgcmdnki{key,cmd} Like orgcmd, but do not index the key
  26. @c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key
  27. @c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or"
  28. @c orgcmdkxkc{key1,key2,cmd} Two keys with one command name, but
  29. @c different functions, so format as @itemx
  30. @c orgcmdkskc{key1,key2,cmd} Same as orgcmdkkc, but use "or short"
  31. @c xorgcmdkskc{key1,key2,cmd} Same as previous, but use @itemx
  32. @c orgcmdkkcc{key1,key2,cmd1,cmd2} Two keys and two commands
  33. @c a key but no command
  34. @c Inserts: @item key
  35. @macro orgkey{key}
  36. @kindex \key\
  37. @item @kbd{\key\}
  38. @end macro
  39. @macro xorgkey{key}
  40. @kindex \key\
  41. @itemx @kbd{\key\}
  42. @end macro
  43. @c one key with a command
  44. @c Inserts: @item KEY COMMAND
  45. @macro orgcmd{key,command}
  46. @ifset cmdnames
  47. @kindex \key\
  48. @findex \command\
  49. @iftex
  50. @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
  51. @end iftex
  52. @ifnottex
  53. @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
  54. @end ifnottex
  55. @end ifset
  56. @ifclear cmdnames
  57. @kindex \key\
  58. @item @kbd{\key\}
  59. @end ifclear
  60. @end macro
  61. @c One key with one command, formatted using @itemx
  62. @c Inserts: @itemx KEY COMMAND
  63. @macro xorgcmd{key,command}
  64. @ifset cmdnames
  65. @kindex \key\
  66. @findex \command\
  67. @iftex
  68. @itemx @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
  69. @end iftex
  70. @ifnottex
  71. @itemx @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
  72. @end ifnottex
  73. @end ifset
  74. @ifclear cmdnames
  75. @kindex \key\
  76. @itemx @kbd{\key\}
  77. @end ifclear
  78. @end macro
  79. @c one key with a command, bit do not index the key
  80. @c Inserts: @item KEY COMMAND
  81. @macro orgcmdnki{key,command}
  82. @ifset cmdnames
  83. @findex \command\
  84. @iftex
  85. @item @kbd{\key\} @hskip 0pt plus 1filll @code{\command\}
  86. @end iftex
  87. @ifnottex
  88. @item @kbd{\key\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
  89. @end ifnottex
  90. @end ifset
  91. @ifclear cmdnames
  92. @item @kbd{\key\}
  93. @end ifclear
  94. @end macro
  95. @c one key with a command, and special text to replace key in item
  96. @c Inserts: @item TEXT COMMAND
  97. @macro orgcmdtkc{text,key,command}
  98. @ifset cmdnames
  99. @kindex \key\
  100. @findex \command\
  101. @iftex
  102. @item @kbd{\text\} @hskip 0pt plus 1filll @code{\command\}
  103. @end iftex
  104. @ifnottex
  105. @item @kbd{\text\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
  106. @end ifnottex
  107. @end ifset
  108. @ifclear cmdnames
  109. @kindex \key\
  110. @item @kbd{\text\}
  111. @end ifclear
  112. @end macro
  113. @c two keys with one command
  114. @c Inserts: @item KEY1 or KEY2 COMMAND
  115. @macro orgcmdkkc{key1,key2,command}
  116. @ifset cmdnames
  117. @kindex \key1\
  118. @kindex \key2\
  119. @findex \command\
  120. @iftex
  121. @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
  122. @end iftex
  123. @ifnottex
  124. @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
  125. @end ifnottex
  126. @end ifset
  127. @ifclear cmdnames
  128. @kindex \key1\
  129. @kindex \key2\
  130. @item @kbd{\key1\} @ @r{or} @ @kbd{\key2\}
  131. @end ifclear
  132. @end macro
  133. @c Two keys with one command name, but different functions, so format as
  134. @c @itemx
  135. @c Inserts: @item KEY1
  136. @c @itemx KEY2 COMMAND
  137. @macro orgcmdkxkc{key1,key2,command}
  138. @ifset cmdnames
  139. @kindex \key1\
  140. @kindex \key2\
  141. @findex \command\
  142. @iftex
  143. @item @kbd{\key1\}
  144. @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
  145. @end iftex
  146. @ifnottex
  147. @item @kbd{\key1\}
  148. @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
  149. @end ifnottex
  150. @end ifset
  151. @ifclear cmdnames
  152. @kindex \key1\
  153. @kindex \key2\
  154. @item @kbd{\key1\}
  155. @itemx @kbd{\key2\}
  156. @end ifclear
  157. @end macro
  158. @c Same as previous, but use "or short"
  159. @c Inserts: @item KEY1 or short KEY2 COMMAND
  160. @macro orgcmdkskc{key1,key2,command}
  161. @ifset cmdnames
  162. @kindex \key1\
  163. @kindex \key2\
  164. @findex \command\
  165. @iftex
  166. @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
  167. @end iftex
  168. @ifnottex
  169. @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
  170. @end ifnottex
  171. @end ifset
  172. @ifclear cmdnames
  173. @kindex \key1\
  174. @kindex \key2\
  175. @item @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
  176. @end ifclear
  177. @end macro
  178. @c Same as previous, but use @itemx
  179. @c Inserts: @itemx KEY1 or short KEY2 COMMAND
  180. @macro xorgcmdkskc{key1,key2,command}
  181. @ifset cmdnames
  182. @kindex \key1\
  183. @kindex \key2\
  184. @findex \command\
  185. @iftex
  186. @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @hskip 0pt plus 1filll @code{\command\}
  187. @end iftex
  188. @ifnottex
  189. @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command\})
  190. @end ifnottex
  191. @end ifset
  192. @ifclear cmdnames
  193. @kindex \key1\
  194. @kindex \key2\
  195. @itemx @kbd{\key1\} @ @r{or short} @ @kbd{\key2\}
  196. @end ifclear
  197. @end macro
  198. @c two keys with two commands
  199. @c Inserts: @item KEY1 COMMAND1
  200. @c @itemx KEY2 COMMAND2
  201. @macro orgcmdkkcc{key1,key2,command1,command2}
  202. @ifset cmdnames
  203. @kindex \key1\
  204. @kindex \key2\
  205. @findex \command1\
  206. @findex \command2\
  207. @iftex
  208. @item @kbd{\key1\} @hskip 0pt plus 1filll @code{\command1\}
  209. @itemx @kbd{\key2\} @hskip 0pt plus 1filll @code{\command2\}
  210. @end iftex
  211. @ifnottex
  212. @item @kbd{\key1\} @tie{}@tie{}@tie{}@tie{}(@code{\command1\})
  213. @itemx @kbd{\key2\} @tie{}@tie{}@tie{}@tie{}(@code{\command2\})
  214. @end ifnottex
  215. @end ifset
  216. @ifclear cmdnames
  217. @kindex \key1\
  218. @kindex \key2\
  219. @item @kbd{\key1\}
  220. @itemx @kbd{\key2\}
  221. @end ifclear
  222. @end macro
  223. @c -----------------------------------------------------------------------------
  224. @iftex
  225. @c @hyphenation{time-stamp time-stamps time-stamp-ing time-stamp-ed}
  226. @end iftex
  227. @c Subheadings inside a table.
  228. @macro tsubheading{text}
  229. @ifinfo
  230. @subsubheading \text\
  231. @end ifinfo
  232. @ifnotinfo
  233. @item @b{\text\}
  234. @end ifnotinfo
  235. @end macro
  236. @copying
  237. This manual is for Org version @value{VERSION}.
  238. Copyright @copyright{} 2004--2017 Free Software Foundation, Inc.
  239. @quotation
  240. Permission is granted to copy, distribute and/or modify this document
  241. under the terms of the GNU Free Documentation License, Version 1.3 or
  242. any later version published by the Free Software Foundation; with no
  243. Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
  244. and with the Back-Cover Texts as in (a) below. A copy of the license
  245. is included in the section entitled ``GNU Free Documentation License.''
  246. (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  247. modify this GNU manual.''
  248. @end quotation
  249. @end copying
  250. @dircategory Emacs editing modes
  251. @direntry
  252. * Org Mode: (org). Outline-based notes management and organizer
  253. @end direntry
  254. @titlepage
  255. @title The Org Manual
  256. @subtitle Release @value{VERSION}
  257. @author by Carsten Dominik
  258. with contributions by Bastien Guerry, Nicolas Goaziou, Eric Schulte,
  259. Jambunathan K, Dan Davison, Thomas Dye, David O'Toole, and Philip Rooke.
  260. @c The following two commands start the copyright page.
  261. @page
  262. @vskip 0pt plus 1filll
  263. @insertcopying
  264. @end titlepage
  265. @c Output the short table of contents at the beginning.
  266. @shortcontents
  267. @c Output the table of contents at the beginning.
  268. @contents
  269. @ifnottex
  270. @node Top, Introduction, (dir), (dir)
  271. @top Org Mode Manual
  272. @insertcopying
  273. @end ifnottex
  274. @menu
  275. * Introduction:: Getting started
  276. * Document structure:: A tree works like your brain
  277. * Tables:: Pure magic for quick formatting
  278. * Hyperlinks:: Notes in context
  279. * TODO items:: Every tree branch can be a TODO item
  280. * Tags:: Tagging headlines and matching sets of tags
  281. * Properties and columns:: Storing information about an entry
  282. * Dates and times:: Making items useful for planning
  283. * Capture - Refile - Archive:: The ins and outs for projects
  284. * Agenda views:: Collecting information into views
  285. * Markup:: Prepare text for rich export
  286. * Exporting:: Sharing and publishing notes
  287. * Publishing:: Create a web site of linked Org files
  288. * Working with source code:: Export, evaluate, and tangle code blocks
  289. * Miscellaneous:: All the rest which did not fit elsewhere
  290. * Hacking:: How to hack your way around
  291. * MobileOrg:: Viewing and capture on a mobile device
  292. * History and acknowledgments:: How Org came into being
  293. * GNU Free Documentation License:: The license for this documentation.
  294. * Main Index:: An index of Org's concepts and features
  295. * Key Index:: Key bindings and where they are described
  296. * Command and Function Index:: Command names and some internal functions
  297. * Variable Index:: Variables mentioned in the manual
  298. @detailmenu
  299. --- The Detailed Node Listing ---
  300. Introduction
  301. * Summary:: Brief summary of what Org does
  302. * Installation:: Installing Org
  303. * Activation:: How to activate Org for certain buffers
  304. * Feedback:: Bug reports, ideas, patches etc.
  305. * Conventions:: Typesetting conventions in the manual
  306. Document structure
  307. * Outlines:: Org is based on Outline mode
  308. * Headlines:: How to typeset Org tree headlines
  309. * Visibility cycling:: Show and hide, much simplified
  310. * Motion:: Jumping to other headlines
  311. * Structure editing:: Changing sequence and level of headlines
  312. * Sparse trees:: Matches embedded in context
  313. * Plain lists:: Additional structure within an entry
  314. * Drawers:: Tucking stuff away
  315. * Blocks:: Folding blocks
  316. * Footnotes:: How footnotes are defined in Org's syntax
  317. * Orgstruct mode:: Structure editing outside Org
  318. * Org syntax:: Formal description of Org's syntax
  319. Visibility cycling
  320. * Global and local cycling:: Cycling through various visibility states
  321. * Initial visibility:: Setting the initial visibility state
  322. * Catching invisible edits:: Preventing mistakes when editing invisible parts
  323. Tables
  324. * Built-in table editor:: Simple tables
  325. * Column width and alignment:: Overrule the automatic settings
  326. * Column groups:: Grouping to trigger vertical lines
  327. * Orgtbl mode:: The table editor as minor mode
  328. * The spreadsheet:: The table editor has spreadsheet capabilities
  329. * Org-Plot:: Plotting from org tables
  330. The spreadsheet
  331. * References:: How to refer to another field or range
  332. * Formula syntax for Calc:: Using Calc to compute stuff
  333. * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
  334. * Durations and time values:: How to compute durations and time values
  335. * Field and range formulas:: Formula for specific (ranges of) fields
  336. * Column formulas:: Formulas valid for an entire column
  337. * Lookup functions:: Lookup functions for searching tables
  338. * Editing and debugging formulas:: Fixing formulas
  339. * Updating the table:: Recomputing all dependent fields
  340. * Advanced features:: Field and column names, parameters and automatic recalc
  341. Hyperlinks
  342. * Link format:: How links in Org are formatted
  343. * Internal links:: Links to other places in the current file
  344. * External links:: URL-like links to the world
  345. * Handling links:: Creating, inserting and following
  346. * Using links outside Org:: Linking from my C source code?
  347. * Link abbreviations:: Shortcuts for writing complex links
  348. * Search options:: Linking to a specific location
  349. * Custom searches:: When the default search is not enough
  350. Internal links
  351. * Radio targets:: Make targets trigger links in plain text
  352. TODO items
  353. * TODO basics:: Marking and displaying TODO entries
  354. * TODO extensions:: Workflow and assignments
  355. * Progress logging:: Dates and notes for progress
  356. * Priorities:: Some things are more important than others
  357. * Breaking down tasks:: Splitting a task into manageable pieces
  358. * Checkboxes:: Tick-off lists
  359. Extended use of TODO keywords
  360. * Workflow states:: From TODO to DONE in steps
  361. * TODO types:: I do this, Fred does the rest
  362. * Multiple sets in one file:: Mixing it all, and still finding your way
  363. * Fast access to TODO states:: Single letter selection of a state
  364. * Per-file keywords:: Different files, different requirements
  365. * Faces for TODO keywords:: Highlighting states
  366. * TODO dependencies:: When one task needs to wait for others
  367. Progress logging
  368. * Closing items:: When was this entry marked DONE?
  369. * Tracking TODO state changes:: When did the status change?
  370. * Tracking your habits:: How consistent have you been?
  371. Tags
  372. * Tag inheritance:: Tags use the tree structure of the outline
  373. * Setting tags:: How to assign tags to a headline
  374. * Tag hierarchy:: Create a hierarchy of tags
  375. * Tag searches:: Searching for combinations of tags
  376. Properties and columns
  377. * Property syntax:: How properties are spelled out
  378. * Special properties:: Access to other Org mode features
  379. * Property searches:: Matching property values
  380. * Property inheritance:: Passing values down the tree
  381. * Column view:: Tabular viewing and editing
  382. * Property API:: Properties for Lisp programmers
  383. Column view
  384. * Defining columns:: The COLUMNS format property
  385. * Using column view:: How to create and use column view
  386. * Capturing column view:: A dynamic block for column view
  387. Defining columns
  388. * Scope of column definitions:: Where defined, where valid?
  389. * Column attributes:: Appearance and content of a column
  390. Dates and times
  391. * Timestamps:: Assigning a time to a tree entry
  392. * Creating timestamps:: Commands which insert timestamps
  393. * Deadlines and scheduling:: Planning your work
  394. * Clocking work time:: Tracking how long you spend on a task
  395. * Effort estimates:: Planning work effort in advance
  396. * Timers:: Notes with a running timer
  397. Creating timestamps
  398. * The date/time prompt:: How Org mode helps you entering date and time
  399. * Custom time format:: Making dates look different
  400. Deadlines and scheduling
  401. * Inserting deadline/schedule:: Planning items
  402. * Repeated tasks:: Items that show up again and again
  403. Clocking work time
  404. * Clocking commands:: Starting and stopping a clock
  405. * The clock table:: Detailed reports
  406. * Resolving idle time:: Resolving time when you've been idle
  407. Capture - Refile - Archive
  408. * Capture:: Capturing new stuff
  409. * Attachments:: Add files to tasks
  410. * RSS feeds:: Getting input from RSS feeds
  411. * Protocols:: External (e.g., Browser) access to Emacs and Org
  412. * Refile and copy:: Moving/copying a tree from one place to another
  413. * Archiving:: What to do with finished projects
  414. Capture
  415. * Setting up capture:: Where notes will be stored
  416. * Using capture:: Commands to invoke and terminate capture
  417. * Capture templates:: Define the outline of different note types
  418. Capture templates
  419. * Template elements:: What is needed for a complete template entry
  420. * Template expansion:: Filling in information about time and context
  421. * Templates in contexts:: Only show a template in a specific context
  422. Protocols for external access
  423. * @code{store-link} protocol:: Store a link, push URL to kill-ring.
  424. * @code{capture} protocol:: Fill a buffer with external information.
  425. * @code{open-source} protocol:: Edit published contents.
  426. Archiving
  427. * Moving subtrees:: Moving a tree to an archive file
  428. * Internal archiving:: Switch off a tree but keep it in the file
  429. Agenda views
  430. * Agenda files:: Files being searched for agenda information
  431. * Agenda dispatcher:: Keyboard access to agenda views
  432. * Built-in agenda views:: What is available out of the box?
  433. * Presentation and sorting:: How agenda items are prepared for display
  434. * Agenda commands:: Remote editing of Org trees
  435. * Custom agenda views:: Defining special searches and views
  436. * Exporting agenda views:: Writing a view to a file
  437. * Agenda column view:: Using column view for collected entries
  438. The built-in agenda views
  439. * Weekly/daily agenda:: The calendar page with current tasks
  440. * Global TODO list:: All unfinished action items
  441. * Matching tags and properties:: Structured information with fine-tuned search
  442. * Search view:: Find entries by searching for text
  443. * Stuck projects:: Find projects you need to review
  444. Presentation and sorting
  445. * Categories:: Not all tasks are equal
  446. * Time-of-day specifications:: How the agenda knows the time
  447. * Sorting agenda items:: The order of things
  448. * Filtering/limiting agenda items:: Dynamically narrow the agenda
  449. Custom agenda views
  450. * Storing searches:: Type once, use often
  451. * Block agenda:: All the stuff you need in a single buffer
  452. * Setting options:: Changing the rules
  453. Markup for rich export
  454. * Paragraphs:: The basic unit of text
  455. * Emphasis and monospace:: Bold, italic, etc.
  456. * Horizontal rules:: Make a line
  457. * Images and tables:: Images, tables and caption mechanism
  458. * Literal examples:: Source code examples with special formatting
  459. * Special symbols:: Greek letters and other symbols
  460. * Subscripts and superscripts:: Simple syntax for raising/lowering text
  461. * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
  462. Embedded @LaTeX{}
  463. * @LaTeX{} fragments:: Complex formulas made easy
  464. * Previewing @LaTeX{} fragments:: What will this snippet look like?
  465. * CDLaTeX mode:: Speed up entering of formulas
  466. Exporting
  467. * The export dispatcher:: The main interface
  468. * Export settings:: Common export settings
  469. * Table of contents:: The if and where of the table of contents
  470. * Include files:: Include additional files into a document
  471. * Macro replacement:: Use macros to create templates
  472. * Comment lines:: What will not be exported
  473. * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
  474. * Beamer export:: Exporting as a Beamer presentation
  475. * HTML export:: Exporting to HTML
  476. * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
  477. * Markdown export:: Exporting to Markdown
  478. * OpenDocument Text export:: Exporting to OpenDocument Text
  479. * Org export:: Exporting to Org
  480. * Texinfo export:: Exporting to Texinfo
  481. * iCalendar export:: Exporting to iCalendar
  482. * Other built-in back-ends:: Exporting to a man page
  483. * Advanced configuration:: Fine-tuning the export output
  484. * Export in foreign buffers:: Author tables and lists in Org syntax
  485. Beamer export
  486. * Beamer export commands:: For creating Beamer documents.
  487. * Beamer specific export settings:: For customizing Beamer export.
  488. * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
  489. * Beamer specific syntax:: For using in Org documents.
  490. * Editing support:: For using helper functions.
  491. * A Beamer example:: A complete presentation.
  492. HTML export
  493. * HTML Export commands:: Invoking HTML export
  494. * HTML Specific export settings:: Settings for HTML export
  495. * HTML doctypes:: Exporting various (X)HTML flavors
  496. * HTML preamble and postamble:: Inserting preamble and postamble
  497. * Quoting HTML tags:: Using direct HTML in Org files
  498. * Links in HTML export:: Interpreting and formatting links
  499. * Tables in HTML export:: Formatting and modifying tables
  500. * Images in HTML export:: Inserting figures with HTML output
  501. * Math formatting in HTML export:: Handling math equations
  502. * Text areas in HTML export:: Showing an alternate approach, an example
  503. * CSS support:: Styling HTML output
  504. * JavaScript support:: Folding scripting in the web browser
  505. @LaTeX{} export
  506. * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
  507. * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
  508. * @LaTeX{} header and sectioning:: For file structure.
  509. * Quoting @LaTeX{} code:: Directly in the Org document.
  510. * Tables in @LaTeX{} export:: Attributes specific to tables.
  511. * Images in @LaTeX{} export:: Attributes specific to images.
  512. * Plain lists in @LaTeX{} export:: Attributes specific to lists.
  513. * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
  514. * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
  515. * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
  516. * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
  517. OpenDocument Text export
  518. * Pre-requisites for ODT export:: Required packages.
  519. * ODT export commands:: Invoking export.
  520. * ODT specific export settings:: Configuration options.
  521. * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
  522. * Applying custom styles:: Styling the output.
  523. * Links in ODT export:: Handling and formatting links.
  524. * Tables in ODT export:: Org table conversions.
  525. * Images in ODT export:: Inserting images.
  526. * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
  527. * Labels and captions in ODT export:: Rendering objects.
  528. * Literal examples in ODT export:: For source code and example blocks.
  529. * Advanced topics in ODT export:: For power users.
  530. Math formatting in ODT export
  531. * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
  532. * Working with MathML or OpenDocument formula files:: Embedding in native format.
  533. Advanced topics in ODT export
  534. * Configuring a document converter:: Registering a document converter.
  535. * Working with OpenDocument style files:: Exploring internals.
  536. * Creating one-off styles:: Customizing styles, highlighting.
  537. * Customizing tables in ODT export:: Defining table templates.
  538. * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
  539. Texinfo export
  540. * Texinfo export commands:: Invoking commands.
  541. * Texinfo specific export settings:: Setting the environment.
  542. * Texinfo file header:: Generating the header.
  543. * Texinfo title and copyright page:: Creating preamble pages.
  544. * Info directory file:: Installing a manual in Info file hierarchy.
  545. * Headings and sectioning structure:: Building document structure.
  546. * Indices:: Creating indices.
  547. * Quoting Texinfo code:: Incorporating literal Texinfo code.
  548. * Plain lists in Texinfo export:: List attributes.
  549. * Tables in Texinfo export:: Table attributes.
  550. * Images in Texinfo export:: Image attributes.
  551. * Special blocks in Texinfo export:: Special block attributes.
  552. * A Texinfo example:: Processing Org to Texinfo.
  553. Publishing
  554. * Configuration:: Defining projects
  555. * Uploading files:: How to get files up on the server
  556. * Sample configuration:: Example projects
  557. * Triggering publication:: Publication commands
  558. Configuration
  559. * Project alist:: The central configuration variable
  560. * Sources and destinations:: From here to there
  561. * Selecting files:: What files are part of the project?
  562. * Publishing action:: Setting the function doing the publishing
  563. * Publishing options:: Tweaking HTML/@LaTeX{} export
  564. * Publishing links:: Which links keep working after publishing?
  565. * Sitemap:: Generating a list of all pages
  566. * Generating an index:: An index that reaches across pages
  567. Sample configuration
  568. * Simple example:: One-component publishing
  569. * Complex example:: A multi-component publishing example
  570. Working with source code
  571. * Structure of code blocks:: Code block syntax described
  572. * Editing source code:: Language major-mode editing
  573. * Exporting code blocks:: Export contents and/or results
  574. * Extracting source code:: Create pure source code files
  575. * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
  576. * Library of Babel:: Use and contribute to a library of useful code blocks
  577. * Languages:: List of supported code block languages
  578. * Header arguments:: Configure code block functionality
  579. * Results of evaluation:: How evaluation results are handled
  580. * Noweb reference syntax:: Literate programming in Org mode
  581. * Key bindings and useful functions:: Work quickly with code blocks
  582. * Batch execution:: Call functions from the command line
  583. Header arguments
  584. * Using header arguments:: Different ways to set header arguments
  585. * Specific header arguments:: List of header arguments
  586. Using header arguments
  587. * System-wide header arguments:: Set globally, language-specific
  588. * Language-specific header arguments:: Set in the Org file's headers
  589. * Header arguments in Org mode properties:: Set in the Org file
  590. * Language-specific mode properties::
  591. * Code block specific header arguments:: The most commonly used method
  592. * Arguments in function calls:: The most specific level, takes highest priority
  593. Specific header arguments
  594. * var:: Pass arguments to @samp{src} code blocks
  595. * results:: Specify results type; how to collect
  596. * file:: Specify a path for output file
  597. * file-desc:: Specify a description for file results
  598. * file-ext:: Specify an extension for file output
  599. * output-dir:: Specify a directory for output file
  600. * dir:: Specify the default directory for code block execution
  601. * exports:: Specify exporting code, results, both, none
  602. * tangle:: Toggle tangling; or specify file name
  603. * mkdirp:: Toggle for parent directory creation for target files during tangling
  604. * comments:: Toggle insertion of comments in tangled code files
  605. * padline:: Control insertion of padding lines in tangled code files
  606. * no-expand:: Turn off variable assignment and noweb expansion during tangling
  607. * session:: Preserve the state of code evaluation
  608. * noweb:: Toggle expansion of noweb references
  609. * noweb-ref:: Specify block's noweb reference resolution target
  610. * noweb-sep:: String to separate noweb references
  611. * cache:: Avoid re-evaluating unchanged code blocks
  612. * sep:: Delimiter for writing tabular results outside Org
  613. * hlines:: Handle horizontal lines in tables
  614. * colnames:: Handle column names in tables
  615. * rownames:: Handle row names in tables
  616. * shebang:: Make tangled files executable
  617. * tangle-mode:: Set permission of tangled files
  618. * eval:: Limit evaluation of specific code blocks
  619. * wrap:: Mark source block evaluation results
  620. * post:: Post processing of results of code block evaluation
  621. * prologue:: Text to prepend to body of code block
  622. * epilogue:: Text to append to body of code block
  623. Miscellaneous
  624. * Completion:: M-TAB guesses completions
  625. * Easy templates:: Quick insertion of structural elements
  626. * Speed keys:: Electric commands at the beginning of a headline
  627. * Code evaluation security:: Org mode files evaluate inline code
  628. * Customization:: Adapting Org to changing tastes
  629. * In-buffer settings:: Overview of the #+KEYWORDS
  630. * The very busy C-c C-c key:: When in doubt, press C-c C-c
  631. * Clean view:: Getting rid of leading stars in the outline
  632. * TTY keys:: Using Org on a tty
  633. * Interaction:: With other Emacs packages
  634. * org-crypt:: Encrypting Org files
  635. Interaction with other packages
  636. * Cooperation:: Packages Org cooperates with
  637. * Conflicts:: Packages that lead to conflicts
  638. Hacking
  639. * Hooks:: How to reach into Org's internals
  640. * Add-on packages:: Available extensions
  641. * Adding hyperlink types:: New custom link types
  642. * Adding export back-ends:: How to write new export back-ends
  643. * Context-sensitive commands:: How to add functionality to such commands
  644. * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
  645. * Dynamic blocks:: Automatically filled blocks
  646. * Special agenda views:: Customized views
  647. * Speeding up your agendas:: Tips on how to speed up your agendas
  648. * Extracting agenda information:: Post-processing of agenda information
  649. * Using the property API:: Writing programs that use entry properties
  650. * Using the mapping API:: Mapping over all or selected entries
  651. Tables and lists in arbitrary syntax
  652. * Radio tables:: Sending and receiving radio tables
  653. * A @LaTeX{} example:: Step by step, almost a tutorial
  654. * Translator functions:: Copy and modify
  655. * Radio lists:: Sending and receiving lists
  656. MobileOrg
  657. * Setting up the staging area:: For the mobile device
  658. * Pushing to MobileOrg:: Uploading Org files and agendas
  659. * Pulling from MobileOrg:: Integrating captured and flagged items
  660. @end detailmenu
  661. @end menu
  662. @node Introduction
  663. @chapter Introduction
  664. @cindex introduction
  665. @menu
  666. * Summary:: Brief summary of what Org does
  667. * Installation:: Installing Org
  668. * Activation:: How to activate Org for certain buffers
  669. * Feedback:: Bug reports, ideas, patches etc.
  670. * Conventions:: Typesetting conventions in the manual
  671. @end menu
  672. @node Summary
  673. @section Summary
  674. @cindex summary
  675. Org is a mode for keeping notes, maintaining TODO lists, and project planning
  676. with a fast and effective plain-text system. It also is an authoring system
  677. with unique support for literate programming and reproducible research.
  678. Org is implemented on top of Outline mode, which makes it possible to keep
  679. the content of large files well structured. Visibility cycling and structure
  680. editing help to work with the tree. Tables are easily created with a
  681. built-in table editor. Plain text URL-like links connect to websites,
  682. emails, Usenet messages, BBDB entries, and any files related to the projects.
  683. Org develops organizational tasks around notes files that contain lists or
  684. information about projects as plain text. Project planning and task
  685. management makes use of metadata which is part of an outline node. Based on
  686. this data, specific entries can be extracted in queries and create dynamic
  687. @i{agenda views} that also integrate the Emacs calendar and diary. Org can
  688. be used to implement many different project planning schemes, such as David
  689. Allen's GTD system.
  690. Org files can serve as a single source authoring system with export to many
  691. different formats such as HTML, @LaTeX{}, Open Document, and Markdown. New
  692. export backends can be derived from existing ones, or defined from scratch.
  693. Org files can include source code blocks, which makes Org uniquely suited for
  694. authoring technical documents with code examples. Org source code blocks are
  695. fully functional; they can be evaluated in place and their results can be
  696. captured in the file. This makes it possible to create a single file
  697. reproducible research compendium.
  698. Org keeps simple things simple. When first fired up, it should feel like a
  699. straightforward, easy to use outliner. Complexity is not imposed, but a
  700. large amount of functionality is available when needed. Org is a toolbox.
  701. Many users actually run only a (very personal) fraction of Org's capabilities, and
  702. know that there is more whenever they need it.
  703. All of this is achieved with strictly plain text files, the most portable and
  704. future-proof file format. Org runs in Emacs. Emacs is one of the most
  705. widely ported programs, so that Org mode is available on every major
  706. platform.
  707. @cindex FAQ
  708. There is a website for Org which provides links to the newest
  709. version of Org, as well as additional information, frequently asked
  710. questions (FAQ), links to tutorials, etc. This page is located at
  711. @uref{http://orgmode.org}.
  712. @cindex print edition
  713. An earlier version (7.3) of this manual is available as a
  714. @uref{http://www.network-theory.co.uk/org/manual/, paperback book from
  715. Network Theory Ltd.}
  716. @page
  717. @node Installation
  718. @section Installation
  719. @cindex installation
  720. Org is part of recent distributions of GNU Emacs, so you normally don't need
  721. to install it. If, for one reason or another, you want to install Org on top
  722. of this pre-packaged version, there are three ways to do it:
  723. @itemize @bullet
  724. @item By using Emacs package system.
  725. @item By downloading Org as an archive.
  726. @item By using Org's git repository.
  727. @end itemize
  728. We @b{strongly recommend} to stick to a single installation method.
  729. @subsubheading Using Emacs packaging system
  730. Recent Emacs distributions include a packaging system which lets you install
  731. Elisp libraries. You can install Org with @kbd{M-x package-install RET org}.
  732. @noindent @b{Important}: you need to do this in a session where no @code{.org} file has
  733. been visited, i.e., where no Org built-in function have been loaded.
  734. Otherwise autoload Org functions will mess up the installation.
  735. Then, to make sure your Org configuration is taken into account, initialize
  736. the package system with @code{(package-initialize)} in your Emacs init file
  737. before setting any Org option. If you want to use Org's package repository,
  738. check out the @uref{http://orgmode.org/elpa.html, Org ELPA page}.
  739. @subsubheading Downloading Org as an archive
  740. You can download Org latest release from @uref{http://orgmode.org/, Org's
  741. website}. In this case, make sure you set the load-path correctly in your
  742. Emacs init file:
  743. @lisp
  744. (add-to-list 'load-path "~/path/to/orgdir/lisp")
  745. @end lisp
  746. The downloaded archive contains contributed libraries that are not included
  747. in Emacs. If you want to use them, add the @file{contrib} directory to your
  748. load-path:
  749. @lisp
  750. (add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t)
  751. @end lisp
  752. Optionally, you can compile the files and/or install them in your system.
  753. Run @code{make help} to list compilation and installation options.
  754. @subsubheading Using Org's git repository
  755. You can clone Org's repository and install Org like this:
  756. @example
  757. $ cd ~/src/
  758. $ git clone git://orgmode.org/org-mode.git
  759. $ make autoloads
  760. @end example
  761. Note that in this case, @code{make autoloads} is mandatory: it defines Org's
  762. version in @file{org-version.el} and Org's autoloads in
  763. @file{org-loaddefs.el}.
  764. Remember to add the correct load-path as described in the method above.
  765. You can also compile with @code{make}, generate the documentation with
  766. @code{make doc}, create a local configuration with @code{make config} and
  767. install Org with @code{make install}. Please run @code{make help} to get
  768. the list of compilation/installation options.
  769. For more detailed explanations on Org's build system, please check the Org
  770. Build System page on @uref{http://orgmode.org/worg/dev/org-build-system.html,
  771. Worg}.
  772. @node Activation
  773. @section Activation
  774. @cindex activation
  775. @cindex autoload
  776. @cindex ELPA
  777. @cindex global key bindings
  778. @cindex key bindings, global
  779. @findex org-agenda
  780. @findex org-capture
  781. @findex org-store-link
  782. @findex org-iswitchb
  783. Org mode buffers need font-lock to be turned on: this is the default in
  784. Emacs@footnote{If you don't use font-lock globally, turn it on in Org buffer
  785. with @code{(add-hook 'org-mode-hook 'turn-on-font-lock)}}.
  786. There are compatibility issues between Org mode and some other Elisp
  787. packages, please take the time to check the list (@pxref{Conflicts}).
  788. The four Org commands @command{org-store-link}, @command{org-capture},
  789. @command{org-agenda}, and @command{org-iswitchb} should be accessible through
  790. global keys (i.e., anywhere in Emacs, not just in Org buffers). Here are
  791. suggested bindings for these keys, please modify the keys to your own
  792. liking.
  793. @lisp
  794. (global-set-key "\C-cl" 'org-store-link)
  795. (global-set-key "\C-ca" 'org-agenda)
  796. (global-set-key "\C-cc" 'org-capture)
  797. (global-set-key "\C-cb" 'org-iswitchb)
  798. @end lisp
  799. @cindex Org mode, turning on
  800. Files with the @file{.org} extension use Org mode by default. To turn on Org
  801. mode in a file that does not have the extension @file{.org}, make the first
  802. line of a file look like this:
  803. @example
  804. MY PROJECTS -*- mode: org; -*-
  805. @end example
  806. @vindex org-insert-mode-line-in-empty-file
  807. @noindent which will select Org mode for this buffer no matter what
  808. the file's name is. See also the variable
  809. @code{org-insert-mode-line-in-empty-file}.
  810. Many commands in Org work on the region if the region is @i{active}. To make
  811. use of this, you need to have @code{transient-mark-mode} turned on, which is
  812. the default. If you do not like @code{transient-mark-mode}, you can create
  813. an active region by using the mouse to select a region, or pressing
  814. @kbd{C-@key{SPC}} twice before moving the cursor.
  815. @node Feedback
  816. @section Feedback
  817. @cindex feedback
  818. @cindex bug reports
  819. @cindex maintainer
  820. @cindex author
  821. If you find problems with Org, or if you have questions, remarks, or ideas
  822. about it, please mail to the Org mailing list @email{emacs-orgmode@@gnu.org}.
  823. You can subscribe to the list
  824. @uref{https://lists.gnu.org/mailman/listinfo/emacs-orgmode, on this web page}.
  825. If you are not a member of the mailing list, your mail will be passed to the
  826. list after a moderator has approved it@footnote{Please consider subscribing
  827. to the mailing list, in order to minimize the work the mailing list
  828. moderators have to do.}.
  829. For bug reports, please first try to reproduce the bug with the latest
  830. version of Org available---if you are running an outdated version, it is
  831. quite possible that the bug has been fixed already. If the bug persists,
  832. prepare a report and provide as much information as possible, including the
  833. version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org
  834. (@kbd{M-x org-version RET}), as well as the Org related setup in the Emacs
  835. init file. The easiest way to do this is to use the command
  836. @example
  837. @kbd{M-x org-submit-bug-report RET}
  838. @end example
  839. @noindent which will put all this information into an Emacs mail buffer so
  840. that you only need to add your description. If you are not sending the Email
  841. from within Emacs, please copy and paste the content into your Email program.
  842. Sometimes you might face a problem due to an error in your Emacs or Org mode
  843. setup. Before reporting a bug, it is very helpful to start Emacs with minimal
  844. customizations and reproduce the problem. Doing so often helps you determine
  845. if the problem is with your customization or with Org mode itself. You can
  846. start a typical minimal session with a command like the example below.
  847. @example
  848. $ emacs -Q -l /path/to/minimal-org.el
  849. @end example
  850. However if you are using Org mode as distributed with Emacs, a minimal setup
  851. is not necessary. In that case it is sufficient to start Emacs as
  852. @code{emacs -Q}. The @code{minimal-org.el} setup file can have contents as
  853. shown below.
  854. @lisp
  855. ;;; Minimal setup to load latest 'org-mode'
  856. ;; activate debugging
  857. (setq debug-on-error t
  858. debug-on-signal nil
  859. debug-on-quit nil)
  860. ;; add latest org-mode to load path
  861. (add-to-list 'load-path "/path/to/org-mode/lisp")
  862. (add-to-list 'load-path "/path/to/org-mode/contrib/lisp" t)
  863. @end lisp
  864. If an error occurs, a backtrace can be very useful (see below on how to
  865. create one). Often a small example file helps, along with clear information
  866. about:
  867. @enumerate
  868. @item What exactly did you do?
  869. @item What did you expect to happen?
  870. @item What happened instead?
  871. @end enumerate
  872. @noindent Thank you for helping to improve this program.
  873. @subsubheading How to create a useful backtrace
  874. @cindex backtrace of an error
  875. If working with Org produces an error with a message you don't
  876. understand, you may have hit a bug. The best way to report this is by
  877. providing, in addition to what was mentioned above, a @emph{backtrace}.
  878. This is information from the built-in debugger about where and how the
  879. error occurred. Here is how to produce a useful backtrace:
  880. @enumerate
  881. @item
  882. Reload uncompiled versions of all Org mode Lisp files. The backtrace
  883. contains much more information if it is produced with uncompiled code.
  884. To do this, use
  885. @example
  886. @kbd{C-u M-x org-reload RET}
  887. @end example
  888. @noindent
  889. or select @code{Org -> Refresh/Reload -> Reload Org uncompiled} from the
  890. menu.
  891. @item
  892. Go to the @code{Options} menu and select @code{Enter Debugger on Error}.
  893. @item
  894. Do whatever you have to do to hit the error. Don't forget to
  895. document the steps you take.
  896. @item
  897. When you hit the error, a @file{*Backtrace*} buffer will appear on the
  898. screen. Save this buffer to a file (for example using @kbd{C-x C-w}) and
  899. attach it to your bug report.
  900. @end enumerate
  901. @node Conventions
  902. @section Typesetting conventions used in this manual
  903. @subsubheading TODO keywords, tags, properties, etc.
  904. Org mainly uses three types of keywords: TODO keywords, tags and property
  905. names. In this manual we use the following conventions:
  906. @table @code
  907. @item TODO
  908. @itemx WAITING
  909. TODO keywords are written with all capitals, even if they are
  910. user-defined.
  911. @item boss
  912. @itemx ARCHIVE
  913. User-defined tags are written in lowercase; built-in tags with special
  914. meaning are written with all capitals.
  915. @item Release
  916. @itemx PRIORITY
  917. User-defined properties are capitalized; built-in properties with
  918. special meaning are written with all capitals.
  919. @end table
  920. Moreover, Org uses @i{option keywords} (like @code{#+TITLE} to set the title)
  921. and @i{environment keywords} (like @code{#+BEGIN_EXPORT html} to start
  922. a @code{HTML} environment). They are written in uppercase in the manual to
  923. enhance its readability, but you can use lowercase in your Org file.
  924. @subsubheading Key bindings and commands
  925. @kindex C-c a
  926. @findex org-agenda
  927. @kindex C-c c
  928. @findex org-capture
  929. The manual suggests a few global key bindings, in particular @kbd{C-c a} for
  930. @code{org-agenda} and @kbd{C-c c} for @code{org-capture}. These are only
  931. suggestions, but the rest of the manual assumes that these key bindings are in
  932. place in order to list commands by key access.
  933. Also, the manual lists both the keys and the corresponding commands for
  934. accessing a functionality. Org mode often uses the same key for different
  935. functions, depending on context. The command that is bound to such keys has
  936. a generic name, like @code{org-metaright}. In the manual we will, wherever
  937. possible, give the function that is internally called by the generic command.
  938. For example, in the chapter on document structure, @kbd{M-@key{right}} will
  939. be listed to call @code{org-do-demote}, while in the chapter on tables, it
  940. will be listed to call @code{org-table-move-column-right}. If you prefer,
  941. you can compile the manual without the command names by unsetting the flag
  942. @code{cmdnames} in @file{org.texi}.
  943. @node Document structure
  944. @chapter Document structure
  945. @cindex document structure
  946. @cindex structure of document
  947. Org is based on Outline mode and provides flexible commands to
  948. edit the structure of the document.
  949. @menu
  950. * Outlines:: Org is based on Outline mode
  951. * Headlines:: How to typeset Org tree headlines
  952. * Visibility cycling:: Show and hide, much simplified
  953. * Motion:: Jumping to other headlines
  954. * Structure editing:: Changing sequence and level of headlines
  955. * Sparse trees:: Matches embedded in context
  956. * Plain lists:: Additional structure within an entry
  957. * Drawers:: Tucking stuff away
  958. * Blocks:: Folding blocks
  959. * Footnotes:: How footnotes are defined in Org's syntax
  960. * Orgstruct mode:: Structure editing outside Org
  961. * Org syntax:: Formal description of Org's syntax
  962. @end menu
  963. @node Outlines
  964. @section Outlines
  965. @cindex outlines
  966. @cindex Outline mode
  967. Org is implemented on top of Outline mode. Outlines allow a
  968. document to be organized in a hierarchical structure, which (at least
  969. for me) is the best representation of notes and thoughts. An overview
  970. of this structure is achieved by folding (hiding) large parts of the
  971. document to show only the general document structure and the parts
  972. currently being worked on. Org greatly simplifies the use of
  973. outlines by compressing the entire show/hide functionality into a single
  974. command, @command{org-cycle}, which is bound to the @key{TAB} key.
  975. @node Headlines
  976. @section Headlines
  977. @cindex headlines
  978. @cindex outline tree
  979. @vindex org-special-ctrl-a/e
  980. @vindex org-special-ctrl-k
  981. @vindex org-ctrl-k-protect-subtree
  982. Headlines define the structure of an outline tree. The headlines in Org
  983. start with one or more stars, on the left margin@footnote{See the variables
  984. @code{org-special-ctrl-a/e}, @code{org-special-ctrl-k}, and
  985. @code{org-ctrl-k-protect-subtree} to configure special behavior of @kbd{C-a},
  986. @kbd{C-e}, and @kbd{C-k} in headlines.} @footnote{Clocking only works with
  987. headings indented less than 30 stars.}. For example:
  988. @example
  989. * Top level headline
  990. ** Second level
  991. *** 3rd level
  992. some text
  993. *** 3rd level
  994. more text
  995. * Another top level headline
  996. @end example
  997. @vindex org-footnote-section
  998. @noindent Note that a headline named after @code{org-footnote-section},
  999. which defaults to @samp{Footnotes}, is considered as special. A subtree with
  1000. this headline will be silently ignored by exporting functions.
  1001. Some people find the many stars too noisy and would prefer an
  1002. outline that has whitespace followed by a single star as headline
  1003. starters. @ref{Clean view}, describes a setup to realize this.
  1004. @vindex org-cycle-separator-lines
  1005. An empty line after the end of a subtree is considered part of it and
  1006. will be hidden when the subtree is folded. However, if you leave at
  1007. least two empty lines, one empty line will remain visible after folding
  1008. the subtree, in order to structure the collapsed view. See the
  1009. variable @code{org-cycle-separator-lines} to modify this behavior.
  1010. @node Visibility cycling
  1011. @section Visibility cycling
  1012. @cindex cycling, visibility
  1013. @cindex visibility cycling
  1014. @cindex trees, visibility
  1015. @cindex show hidden text
  1016. @cindex hide text
  1017. @menu
  1018. * Global and local cycling:: Cycling through various visibility states
  1019. * Initial visibility:: Setting the initial visibility state
  1020. * Catching invisible edits:: Preventing mistakes when editing invisible parts
  1021. @end menu
  1022. @node Global and local cycling
  1023. @subsection Global and local cycling
  1024. Outlines make it possible to hide parts of the text in the buffer.
  1025. Org uses just two commands, bound to @key{TAB} and
  1026. @kbd{S-@key{TAB}} to change the visibility in the buffer.
  1027. @cindex subtree visibility states
  1028. @cindex subtree cycling
  1029. @cindex folded, subtree visibility state
  1030. @cindex children, subtree visibility state
  1031. @cindex subtree, subtree visibility state
  1032. @table @asis
  1033. @orgcmd{@key{TAB},org-cycle}
  1034. @emph{Subtree cycling}: Rotate current subtree among the states
  1035. @example
  1036. ,-> FOLDED -> CHILDREN -> SUBTREE --.
  1037. '-----------------------------------'
  1038. @end example
  1039. @vindex org-cycle-emulate-tab
  1040. The cursor must be on a headline for this to work@footnote{see, however,
  1041. the option @code{org-cycle-emulate-tab}.}.
  1042. @cindex global visibility states
  1043. @cindex global cycling
  1044. @cindex overview, global visibility state
  1045. @cindex contents, global visibility state
  1046. @cindex show all, global visibility state
  1047. @orgcmd{S-@key{TAB},org-global-cycle}
  1048. @itemx C-u @key{TAB}
  1049. @emph{Global cycling}: Rotate the entire buffer among the states
  1050. @example
  1051. ,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
  1052. '--------------------------------------'
  1053. @end example
  1054. When @kbd{S-@key{TAB}} is called with a numeric prefix argument N, the
  1055. CONTENTS view up to headlines of level N will be shown. Note that inside
  1056. tables, @kbd{S-@key{TAB}} jumps to the previous field.
  1057. @vindex org-cycle-global-at-bob
  1058. You can run global cycling using @key{TAB} only if point is at the very
  1059. beginning of the buffer and @code{org-cycle-global-at-bob} is set to
  1060. a non-@code{nil} value.
  1061. @cindex set startup visibility, command
  1062. @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
  1063. Switch back to the startup visibility of the buffer (@pxref{Initial visibility}).
  1064. @cindex show all, command
  1065. @orgcmd{C-u C-u C-u @key{TAB},outline-show-all}
  1066. Show all, including drawers.
  1067. @cindex revealing context
  1068. @orgcmd{C-c C-r,org-reveal}
  1069. Reveal context around point, showing the current entry, the following heading
  1070. and the hierarchy above. Useful for working near a location that has been
  1071. exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command
  1072. (@pxref{Agenda commands}). With a prefix argument show, on each
  1073. level, all sibling headings. With a double prefix argument, also show the
  1074. entire subtree of the parent.
  1075. @cindex show branches, command
  1076. @orgcmd{C-c C-k,outline-show-branches}
  1077. Expose all the headings of the subtree, CONTENT view for just one subtree.
  1078. @cindex show children, command
  1079. @orgcmd{C-c @key{TAB},outline-show-children}
  1080. Expose all direct children of the subtree. With a numeric prefix argument N,
  1081. expose all children down to level N@.
  1082. @orgcmd{C-c C-x b,org-tree-to-indirect-buffer}
  1083. Show the current subtree in an indirect buffer@footnote{The indirect buffer
  1084. (@pxref{Indirect Buffers,,,emacs,GNU Emacs Manual}) will contain the entire
  1085. buffer, but will be narrowed to the current tree. Editing the indirect
  1086. buffer will also change the original buffer, but without affecting visibility
  1087. in that buffer.}. With a numeric prefix argument N, go up to level N and
  1088. then take that tree. If N is negative then go up that many levels. With
  1089. a @kbd{C-u} prefix, do not remove the previously used indirect buffer.
  1090. @orgcmd{C-c C-x v,org-copy-visible}
  1091. Copy the @i{visible} text in the region into the kill ring.
  1092. @end table
  1093. @node Initial visibility
  1094. @subsection Initial visibility
  1095. @cindex visibility, initialize
  1096. @vindex org-startup-folded
  1097. @vindex org-agenda-inhibit-startup
  1098. @cindex @code{overview}, STARTUP keyword
  1099. @cindex @code{content}, STARTUP keyword
  1100. @cindex @code{showall}, STARTUP keyword
  1101. @cindex @code{showeverything}, STARTUP keyword
  1102. When Emacs first visits an Org file, the global state is set to OVERVIEW,
  1103. i.e., only the top level headlines are visible@footnote{When
  1104. @code{org-agenda-inhibit-startup} is non-@code{nil}, Org will not honor the default
  1105. visibility state when first opening a file for the agenda (@pxref{Speeding up
  1106. your agendas}).}. This can be configured through the variable
  1107. @code{org-startup-folded}, or on a per-file basis by adding one of the
  1108. following lines anywhere in the buffer:
  1109. @example
  1110. #+STARTUP: overview
  1111. #+STARTUP: content
  1112. #+STARTUP: showall
  1113. #+STARTUP: showeverything
  1114. @end example
  1115. @cindex property, VISIBILITY
  1116. @noindent
  1117. Furthermore, any entries with a @samp{VISIBILITY} property (@pxref{Properties
  1118. and columns}) will get their visibility adapted accordingly. Allowed values
  1119. for this property are @code{folded}, @code{children}, @code{content}, and
  1120. @code{all}.
  1121. @table @asis
  1122. @orgcmd{C-u C-u @key{TAB},org-set-startup-visibility}
  1123. Switch back to the startup visibility of the buffer, i.e., whatever is
  1124. requested by startup options and @samp{VISIBILITY} properties in individual
  1125. entries.
  1126. @end table
  1127. @node Catching invisible edits
  1128. @subsection Catching invisible edits
  1129. @vindex org-catch-invisible-edits
  1130. @cindex edits, catching invisible
  1131. Sometimes you may inadvertently edit an invisible part of the buffer and be
  1132. confused on what has been edited and how to undo the mistake. Setting
  1133. @code{org-catch-invisible-edits} to non-@code{nil} will help prevent this. See the
  1134. docstring of this option on how Org should catch invisible edits and process
  1135. them.
  1136. @node Motion
  1137. @section Motion
  1138. @cindex motion, between headlines
  1139. @cindex jumping, to headlines
  1140. @cindex headline navigation
  1141. The following commands jump to other headlines in the buffer.
  1142. @table @asis
  1143. @orgcmd{C-c C-n,org-next-visible-heading}
  1144. Next heading.
  1145. @orgcmd{C-c C-p,org-previous-visible-heading}
  1146. Previous heading.
  1147. @orgcmd{C-c C-f,org-forward-same-level}
  1148. Next heading same level.
  1149. @orgcmd{C-c C-b,org-backward-same-level}
  1150. Previous heading same level.
  1151. @orgcmd{C-c C-u,outline-up-heading}
  1152. Backward to higher level heading.
  1153. @orgcmd{C-c C-j,org-goto}
  1154. Jump to a different place without changing the current outline
  1155. visibility. Shows the document structure in a temporary buffer, where
  1156. you can use the following keys to find your destination:
  1157. @vindex org-goto-auto-isearch
  1158. @example
  1159. @key{TAB} @r{Cycle visibility.}
  1160. @key{down} / @key{up} @r{Next/previous visible headline.}
  1161. @key{RET} @r{Select this location.}
  1162. @kbd{/} @r{Do a Sparse-tree search}
  1163. @r{The following keys work if you turn off @code{org-goto-auto-isearch}}
  1164. n / p @r{Next/previous visible headline.}
  1165. f / b @r{Next/previous headline same level.}
  1166. u @r{One level up.}
  1167. 0-9 @r{Digit argument.}
  1168. q @r{Quit}
  1169. @end example
  1170. @vindex org-goto-interface
  1171. @noindent
  1172. See also the option @code{org-goto-interface}.
  1173. @end table
  1174. @node Structure editing
  1175. @section Structure editing
  1176. @cindex structure editing
  1177. @cindex headline, promotion and demotion
  1178. @cindex promotion, of subtrees
  1179. @cindex demotion, of subtrees
  1180. @cindex subtree, cut and paste
  1181. @cindex pasting, of subtrees
  1182. @cindex cutting, of subtrees
  1183. @cindex copying, of subtrees
  1184. @cindex sorting, of subtrees
  1185. @cindex subtrees, cut and paste
  1186. @table @asis
  1187. @orgcmd{M-@key{RET},org-meta-return}
  1188. @vindex org-M-RET-may-split-line
  1189. Insert a new heading, item or row.
  1190. If the command is used at the @emph{beginning} of a line, and if there is
  1191. a heading or a plain list item (@pxref{Plain lists}) at point, the new
  1192. heading/item is created @emph{before} the current line. When used at the
  1193. beginning of a regular line of text, turn that line into a heading.
  1194. When this command is used in the middle of a line, the line is split and the
  1195. rest of the line becomes the new item or headline. If you do not want the
  1196. line to be split, customize @code{org-M-RET-may-split-line}.
  1197. Calling the command with a @kbd{C-u} prefix unconditionally inserts a new
  1198. heading at the end of the current subtree, thus preserving its contents.
  1199. With a double @kbd{C-u C-u} prefix, the new heading is created at the end of
  1200. the parent subtree instead.
  1201. @orgcmd{C-@key{RET},org-insert-heading-respect-content}
  1202. Insert a new heading at the end of the current subtree.
  1203. @orgcmd{M-S-@key{RET},org-insert-todo-heading}
  1204. @vindex org-treat-insert-todo-heading-as-state-change
  1205. Insert new TODO entry with same level as current heading. See also the
  1206. variable @code{org-treat-insert-todo-heading-as-state-change}.
  1207. @orgcmd{C-S-@key{RET},org-insert-todo-heading-respect-content}
  1208. Insert new TODO entry with same level as current heading. Like
  1209. @kbd{C-@key{RET}}, the new headline will be inserted after the current
  1210. subtree.
  1211. @orgcmd{@key{TAB},org-cycle}
  1212. In a new entry with no text yet, the first @key{TAB} demotes the entry to
  1213. become a child of the previous one. The next @key{TAB} makes it a parent,
  1214. and so on, all the way to top level. Yet another @key{TAB}, and you are back
  1215. to the initial level.
  1216. @orgcmd{M-@key{left},org-do-promote}
  1217. Promote current heading by one level.
  1218. @orgcmd{M-@key{right},org-do-demote}
  1219. Demote current heading by one level.
  1220. @orgcmd{M-S-@key{left},org-promote-subtree}
  1221. Promote the current subtree by one level.
  1222. @orgcmd{M-S-@key{right},org-demote-subtree}
  1223. Demote the current subtree by one level.
  1224. @orgcmd{M-S-@key{up},org-move-subtree-up}
  1225. Move subtree up (swap with previous subtree of same
  1226. level).
  1227. @orgcmd{M-S-@key{down},org-move-subtree-down}
  1228. Move subtree down (swap with next subtree of same level).
  1229. @orgcmd{M-h,org-mark-element}
  1230. Mark the element at point. Hitting repeatedly will mark subsequent elements
  1231. of the one just marked. E.g., hitting @key{M-h} on a paragraph will mark it,
  1232. hitting @key{M-h} immediately again will mark the next one.
  1233. @orgcmd{C-c @@,org-mark-subtree}
  1234. Mark the subtree at point. Hitting repeatedly will mark subsequent subtrees
  1235. of the same level than the marked subtree.
  1236. @orgcmd{C-c C-x C-w,org-cut-subtree}
  1237. Kill subtree, i.e., remove it from buffer but save in kill ring.
  1238. With a numeric prefix argument N, kill N sequential subtrees.
  1239. @orgcmd{C-c C-x M-w,org-copy-subtree}
  1240. Copy subtree to kill ring. With a numeric prefix argument N, copy the N
  1241. sequential subtrees.
  1242. @orgcmd{C-c C-x C-y,org-paste-subtree}
  1243. Yank subtree from kill ring. This does modify the level of the subtree to
  1244. make sure the tree fits in nicely at the yank position. The yank level can
  1245. also be specified with a numeric prefix argument, or by yanking after a
  1246. headline marker like @samp{****}.
  1247. @orgcmd{C-y,org-yank}
  1248. @vindex org-yank-adjusted-subtrees
  1249. @vindex org-yank-folded-subtrees
  1250. Depending on the options @code{org-yank-adjusted-subtrees} and
  1251. @code{org-yank-folded-subtrees}, Org's internal @code{yank} command will
  1252. paste subtrees folded and in a clever way, using the same command as @kbd{C-c
  1253. C-x C-y}. With the default settings, no level adjustment will take place,
  1254. but the yanked tree will be folded unless doing so would swallow text
  1255. previously visible. Any prefix argument to this command will force a normal
  1256. @code{yank} to be executed, with the prefix passed along. A good way to
  1257. force a normal yank is @kbd{C-u C-y}. If you use @code{yank-pop} after a
  1258. yank, it will yank previous kill items plainly, without adjustment and
  1259. folding.
  1260. @orgcmd{C-c C-x c,org-clone-subtree-with-time-shift}
  1261. Clone a subtree by making a number of sibling copies of it. You will be
  1262. prompted for the number of copies to make, and you can also specify if any
  1263. timestamps in the entry should be shifted. This can be useful, for example,
  1264. to create a number of tasks related to a series of lectures to prepare. For
  1265. more details, see the docstring of the command
  1266. @code{org-clone-subtree-with-time-shift}.
  1267. @orgcmd{C-c C-w,org-refile}
  1268. Refile entry or region to a different location. @xref{Refile and copy}.
  1269. @orgcmd{C-c ^,org-sort}
  1270. Sort same-level entries. When there is an active region, all entries in the
  1271. region will be sorted. Otherwise the children of the current headline are
  1272. sorted. The command prompts for the sorting method, which can be
  1273. alphabetically, numerically, by time (first timestamp with active preferred,
  1274. creation time, scheduled time, deadline time), by priority, by TODO keyword
  1275. (in the sequence the keywords have been defined in the setup) or by the value
  1276. of a property. Reverse sorting is possible as well. You can also supply
  1277. your own function to extract the sorting key. With a @kbd{C-u} prefix,
  1278. sorting will be case-sensitive.
  1279. @orgcmd{C-x n s,org-narrow-to-subtree}
  1280. Narrow buffer to current subtree.
  1281. @orgcmd{C-x n b,org-narrow-to-block}
  1282. Narrow buffer to current block.
  1283. @orgcmd{C-x n w,widen}
  1284. Widen buffer to remove narrowing.
  1285. @orgcmd{C-c *,org-toggle-heading}
  1286. Turn a normal line or plain list item into a headline (so that it becomes a
  1287. subheading at its location). Also turn a headline into a normal line by
  1288. removing the stars. If there is an active region, turn all lines in the
  1289. region into headlines. If the first line in the region was an item, turn
  1290. only the item lines into headlines. Finally, if the first line is a
  1291. headline, remove the stars from all headlines in the region.
  1292. @end table
  1293. @cindex region, active
  1294. @cindex active region
  1295. @cindex transient mark mode
  1296. When there is an active region (Transient Mark mode), promotion and
  1297. demotion work on all headlines in the region. To select a region of
  1298. headlines, it is best to place both point and mark at the beginning of a
  1299. line, mark at the beginning of the first headline, and point at the line
  1300. just after the last headline to change. Note that when the cursor is
  1301. inside a table (@pxref{Tables}), the Meta-Cursor keys have different
  1302. functionality.
  1303. @node Sparse trees
  1304. @section Sparse trees
  1305. @cindex sparse trees
  1306. @cindex trees, sparse
  1307. @cindex folding, sparse trees
  1308. @cindex occur, command
  1309. @vindex org-show-context-detail
  1310. An important feature of Org mode is the ability to construct @emph{sparse
  1311. trees} for selected information in an outline tree, so that the entire
  1312. document is folded as much as possible, but the selected information is made
  1313. visible along with the headline structure above it@footnote{See also the
  1314. variable @code{org-show-context-detail} to decide how much context is shown
  1315. around each match.}. Just try it out and you will see immediately how it
  1316. works.
  1317. Org mode contains several commands for creating such trees, all these
  1318. commands can be accessed through a dispatcher:
  1319. @table @asis
  1320. @orgcmd{C-c /,org-sparse-tree}
  1321. This prompts for an extra key to select a sparse-tree creating command.
  1322. @orgcmdkkc{C-c / r,C-c / /,org-occur}
  1323. @vindex org-remove-highlights-with-change
  1324. Prompts for a regexp and shows a sparse tree with all matches. If
  1325. the match is in a headline, the headline is made visible. If the match is in
  1326. the body of an entry, headline and body are made visible. In order to
  1327. provide minimal context, also the full hierarchy of headlines above the match
  1328. is shown, as well as the headline following the match. Each match is also
  1329. highlighted; the highlights disappear when the buffer is changed by an
  1330. editing command@footnote{This depends on the option
  1331. @code{org-remove-highlights-with-change}}, or by pressing @kbd{C-c C-c}.
  1332. When called with a @kbd{C-u} prefix argument, previous highlights are kept,
  1333. so several calls to this command can be stacked.
  1334. @orgcmdkkc{M-g n,M-g M-n,next-error}
  1335. Jump to the next sparse tree match in this buffer.
  1336. @orgcmdkkc{M-g p,M-g M-p,previous-error}
  1337. Jump to the previous sparse tree match in this buffer.
  1338. @end table
  1339. @noindent
  1340. @vindex org-agenda-custom-commands
  1341. For frequently used sparse trees of specific search strings, you can
  1342. use the option @code{org-agenda-custom-commands} to define fast
  1343. keyboard access to specific sparse trees. These commands will then be
  1344. accessible through the agenda dispatcher (@pxref{Agenda dispatcher}).
  1345. For example:
  1346. @lisp
  1347. (setq org-agenda-custom-commands
  1348. '(("f" occur-tree "FIXME")))
  1349. @end lisp
  1350. @noindent will define the key @kbd{C-c a f} as a shortcut for creating
  1351. a sparse tree matching the string @samp{FIXME}.
  1352. The other sparse tree commands select headings based on TODO keywords,
  1353. tags, or properties and will be discussed later in this manual.
  1354. @kindex C-c C-e C-v
  1355. @cindex printing sparse trees
  1356. @cindex visible text, printing
  1357. To print a sparse tree, you can use the Emacs command
  1358. @code{ps-print-buffer-with-faces} which does not print invisible parts of the
  1359. document. Or you can use @kbd{C-c C-e C-v} to export only the visible part
  1360. of the document and print the resulting file.
  1361. @node Plain lists
  1362. @section Plain lists
  1363. @cindex plain lists
  1364. @cindex lists, plain
  1365. @cindex lists, ordered
  1366. @cindex ordered lists
  1367. Within an entry of the outline tree, hand-formatted lists can provide
  1368. additional structure. They also provide a way to create lists of checkboxes
  1369. (@pxref{Checkboxes}). Org supports editing such lists, and every exporter
  1370. (@pxref{Exporting}) can parse and format them.
  1371. Org knows ordered lists, unordered lists, and description lists.
  1372. @itemize @bullet
  1373. @item
  1374. @emph{Unordered} list items start with @samp{-}, @samp{+}, or
  1375. @samp{*}@footnote{When using @samp{*} as a bullet, lines must be indented or
  1376. they will be seen as top-level headlines. Also, when you are hiding leading
  1377. stars to get a clean outline view, plain list items starting with a star may
  1378. be hard to distinguish from true headlines. In short: even though @samp{*}
  1379. is supported, it may be better to not use it for plain list items.} as
  1380. bullets.
  1381. @item
  1382. @vindex org-plain-list-ordered-item-terminator
  1383. @vindex org-list-allow-alphabetical
  1384. @emph{Ordered} list items start with a numeral followed by either a period or
  1385. a right parenthesis@footnote{You can filter out any of them by configuring
  1386. @code{org-plain-list-ordered-item-terminator}.}, such as @samp{1.} or
  1387. @samp{1)}@footnote{You can also get @samp{a.}, @samp{A.}, @samp{a)} and
  1388. @samp{A)} by configuring @code{org-list-allow-alphabetical}. To minimize
  1389. confusion with normal text, those are limited to one character only. Beyond
  1390. that limit, bullets will automatically fallback to numbers.}. If you want a
  1391. list to start with a different value (e.g., 20), start the text of the item
  1392. with @code{[@@20]}@footnote{If there's a checkbox in the item, the cookie
  1393. must be put @emph{before} the checkbox. If you have activated alphabetical
  1394. lists, you can also use counters like @code{[@@b]}.}. Those constructs can
  1395. be used in any item of the list in order to enforce a particular numbering.
  1396. @item
  1397. @emph{Description} list items are unordered list items, and contain the
  1398. separator @samp{ :: } to distinguish the description @emph{term} from the
  1399. description.
  1400. @end itemize
  1401. Items belonging to the same list must have the same indentation on the first
  1402. line. In particular, if an ordered list reaches number @samp{10.}, then the
  1403. 2--digit numbers must be written left-aligned with the other numbers in the
  1404. list. An item ends before the next line that is less or equally indented
  1405. than its bullet/number.
  1406. @vindex org-list-empty-line-terminates-plain-lists
  1407. A list ends whenever every item has ended, which means before any line less
  1408. or equally indented than items at top level. It also ends before two blank
  1409. lines@footnote{See also @code{org-list-empty-line-terminates-plain-lists}.}.
  1410. In that case, all items are closed. Here is an example:
  1411. @example
  1412. @group
  1413. ** Lord of the Rings
  1414. My favorite scenes are (in this order)
  1415. 1. The attack of the Rohirrim
  1416. 2. Eowyn's fight with the witch king
  1417. + this was already my favorite scene in the book
  1418. + I really like Miranda Otto.
  1419. 3. Peter Jackson being shot by Legolas
  1420. - on DVD only
  1421. He makes a really funny face when it happens.
  1422. But in the end, no individual scenes matter but the film as a whole.
  1423. Important actors in this film are:
  1424. - @b{Elijah Wood} :: He plays Frodo
  1425. - @b{Sean Astin} :: He plays Sam, Frodo's friend. I still remember
  1426. him very well from his role as Mikey Walsh in @i{The Goonies}.
  1427. @end group
  1428. @end example
  1429. Org supports these lists by tuning filling and wrapping commands to deal with
  1430. them correctly, and by exporting them properly (@pxref{Exporting}). Since
  1431. indentation is what governs the structure of these lists, many structural
  1432. constructs like @code{#+BEGIN_...} blocks can be indented to signal that they
  1433. belong to a particular item.
  1434. @vindex org-list-demote-modify-bullet
  1435. @vindex org-list-indent-offset
  1436. If you find that using a different bullet for a sub-list (than that used for
  1437. the current list-level) improves readability, customize the variable
  1438. @code{org-list-demote-modify-bullet}. To get a greater difference of
  1439. indentation between items and their sub-items, customize
  1440. @code{org-list-indent-offset}.
  1441. @vindex org-list-automatic-rules
  1442. The following commands act on items when the cursor is in the first line of
  1443. an item (the line with the bullet or number). Some of them imply the
  1444. application of automatic rules to keep list structure intact. If some of
  1445. these actions get in your way, configure @code{org-list-automatic-rules}
  1446. to disable them individually.
  1447. @table @asis
  1448. @orgcmd{@key{TAB},org-cycle}
  1449. @cindex cycling, in plain lists
  1450. @vindex org-cycle-include-plain-lists
  1451. Items can be folded just like headline levels. Normally this works only if
  1452. the cursor is on a plain list item. For more details, see the variable
  1453. @code{org-cycle-include-plain-lists}. If this variable is set to
  1454. @code{integrate}, plain list items will be treated like low-level
  1455. headlines. The level of an item is then given by the indentation of the
  1456. bullet/number. Items are always subordinate to real headlines, however; the
  1457. hierarchies remain completely separated. In a new item with no text yet, the
  1458. first @key{TAB} demotes the item to become a child of the previous
  1459. one. Subsequent @key{TAB}s move the item to meaningful levels in the list
  1460. and eventually get it back to its initial position.
  1461. @orgcmd{M-@key{RET},org-insert-heading}
  1462. @vindex org-M-RET-may-split-line
  1463. @vindex org-list-automatic-rules
  1464. Insert new item at current level. With a prefix argument, force a new
  1465. heading (@pxref{Structure editing}). If this command is used in the middle
  1466. of an item, that item is @emph{split} in two, and the second part becomes the
  1467. new item@footnote{If you do not want the item to be split, customize the
  1468. variable @code{org-M-RET-may-split-line}.}. If this command is executed
  1469. @emph{before item's body}, the new item is created @emph{before} the current
  1470. one.
  1471. @end table
  1472. @table @kbd
  1473. @kindex M-S-@key{RET}
  1474. @item M-S-@key{RET}
  1475. Insert a new item with a checkbox (@pxref{Checkboxes}).
  1476. @kindex S-@key{down}
  1477. @item S-up
  1478. @itemx S-down
  1479. @cindex shift-selection-mode
  1480. @vindex org-support-shift-select
  1481. @vindex org-list-use-circular-motion
  1482. Jump to the previous/next item in the current list@footnote{If you want to
  1483. cycle around items that way, you may customize
  1484. @code{org-list-use-circular-motion}.}, but only if
  1485. @code{org-support-shift-select} is off. If not, you can still use paragraph
  1486. jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite
  1487. similar effect.
  1488. @kindex M-@key{up}
  1489. @kindex M-@key{down}
  1490. @item M-up
  1491. @itemx M-down
  1492. Move the item including subitems up/down@footnote{See
  1493. @code{org-list-use-circular-motion} for a cyclic behavior.} (swap with
  1494. previous/next item of same indentation). If the list is ordered, renumbering
  1495. is automatic.
  1496. @kindex M-@key{left}
  1497. @kindex M-@key{right}
  1498. @item M-left
  1499. @itemx M-right
  1500. Decrease/increase the indentation of an item, leaving children alone.
  1501. @kindex M-S-@key{left}
  1502. @kindex M-S-@key{right}
  1503. @item M-S-@key{left}
  1504. @itemx M-S-@key{right}
  1505. Decrease/increase the indentation of the item, including subitems.
  1506. Initially, the item tree is selected based on current indentation. When
  1507. these commands are executed several times in direct succession, the initially
  1508. selected region is used, even if the new indentation would imply a different
  1509. hierarchy. To use the new hierarchy, break the command chain with a cursor
  1510. motion or so.
  1511. As a special case, using this command on the very first item of a list will
  1512. move the whole list. This behavior can be disabled by configuring
  1513. @code{org-list-automatic-rules}. The global indentation of a list has no
  1514. influence on the text @emph{after} the list.
  1515. @kindex C-c C-c
  1516. @item C-c C-c
  1517. If there is a checkbox (@pxref{Checkboxes}) in the item line, toggle the
  1518. state of the checkbox. In any case, verify bullets and indentation
  1519. consistency in the whole list.
  1520. @kindex C-c -
  1521. @vindex org-plain-list-ordered-item-terminator
  1522. @item C-c -
  1523. Cycle the entire list level through the different itemize/enumerate bullets
  1524. (@samp{-}, @samp{+}, @samp{*}, @samp{1.}, @samp{1)}) or a subset of them,
  1525. depending on @code{org-plain-list-ordered-item-terminator}, the type of list,
  1526. and its indentation. With a numeric prefix argument N, select the Nth bullet
  1527. from this list. If there is an active region when calling this, all selected
  1528. lines are converted to list items. With a prefix argument, selected text is
  1529. changed into a single item. If the first line already was a list item, any
  1530. item marker will be removed from the list. Finally, even without an active
  1531. region, a normal line will be converted into a list item.
  1532. @kindex C-c *
  1533. @item C-c *
  1534. Turn a plain list item into a headline (so that it becomes a subheading at
  1535. its location). @xref{Structure editing}, for a detailed explanation.
  1536. @kindex C-c C-*
  1537. @item C-c C-*
  1538. Turn the whole plain list into a subtree of the current heading. Checkboxes
  1539. (@pxref{Checkboxes}) will become TODO (resp. DONE) keywords when unchecked
  1540. (resp. checked).
  1541. @kindex S-@key{left}
  1542. @kindex S-@key{right}
  1543. @item S-left/right
  1544. @vindex org-support-shift-select
  1545. This command also cycles bullet styles when the cursor in on the bullet or
  1546. anywhere in an item line, details depending on
  1547. @code{org-support-shift-select}.
  1548. @kindex C-c ^
  1549. @cindex sorting, of plain list
  1550. @item C-c ^
  1551. Sort the plain list. You will be prompted for the sorting method:
  1552. numerically, alphabetically, by time, by checked status for check lists,
  1553. or by a custom function.
  1554. @end table
  1555. @node Drawers
  1556. @section Drawers
  1557. @cindex drawers
  1558. @cindex visibility cycling, drawers
  1559. @cindex org-insert-drawer
  1560. @kindex C-c C-x d
  1561. Sometimes you want to keep information associated with an entry, but you
  1562. normally don't want to see it. For this, Org mode has @emph{drawers}. They
  1563. can contain anything but a headline and another drawer. Drawers look like
  1564. this:
  1565. @example
  1566. ** This is a headline
  1567. Still outside the drawer
  1568. :DRAWERNAME:
  1569. This is inside the drawer.
  1570. :END:
  1571. After the drawer.
  1572. @end example
  1573. You can interactively insert drawers at point by calling
  1574. @code{org-insert-drawer}, which is bound to @key{C-c C-x d}. With an active
  1575. region, this command will put the region inside the drawer. With a prefix
  1576. argument, this command calls @code{org-insert-property-drawer} and add
  1577. a property drawer right below the current headline. Completion over drawer
  1578. keywords is also possible using @kbd{M-@key{TAB}}@footnote{Many desktops
  1579. intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
  1580. @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}.
  1581. Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and
  1582. show the entry, but keep the drawer collapsed to a single line. In order to
  1583. look inside the drawer, you need to move the cursor to the drawer line and
  1584. press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for
  1585. storing properties (@pxref{Properties and columns}), and you can also arrange
  1586. for state change notes (@pxref{Tracking TODO state changes}) and clock times
  1587. (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you
  1588. want to store a quick note in the LOGBOOK drawer, in a similar way to state
  1589. changes, use
  1590. @table @kbd
  1591. @kindex C-c C-z
  1592. @item C-c C-z
  1593. Add a time-stamped note to the LOGBOOK drawer.
  1594. @end table
  1595. @vindex org-export-with-drawers
  1596. @vindex org-export-with-properties
  1597. You can select the name of the drawers which should be exported with
  1598. @code{org-export-with-drawers}. In that case, drawer contents will appear in
  1599. export output. Property drawers are not affected by this variable: configure
  1600. @code{org-export-with-properties} instead.
  1601. @node Blocks
  1602. @section Blocks
  1603. @vindex org-hide-block-startup
  1604. @cindex blocks, folding
  1605. Org mode uses begin...end blocks for various purposes from including source
  1606. code examples (@pxref{Literal examples}) to capturing time logging
  1607. information (@pxref{Clocking work time}). These blocks can be folded and
  1608. unfolded by pressing TAB in the begin line. You can also get all blocks
  1609. folded at startup by configuring the option @code{org-hide-block-startup}
  1610. or on a per-file basis by using
  1611. @cindex @code{hideblocks}, STARTUP keyword
  1612. @cindex @code{nohideblocks}, STARTUP keyword
  1613. @example
  1614. #+STARTUP: hideblocks
  1615. #+STARTUP: nohideblocks
  1616. @end example
  1617. @node Footnotes
  1618. @section Footnotes
  1619. @cindex footnotes
  1620. Org mode supports the creation of footnotes.
  1621. A footnote is started by a footnote marker in square brackets in column 0, no
  1622. indentation allowed. It ends at the next footnote definition, headline, or
  1623. after two consecutive empty lines. The footnote reference is simply the
  1624. marker in square brackets, inside text. Markers always start with
  1625. @code{fn:}. For example:
  1626. @example
  1627. The Org homepage[fn:1] now looks a lot better than it used to.
  1628. ...
  1629. [fn:1] The link is: http://orgmode.org
  1630. @end example
  1631. Org mode extends the number-based syntax to @emph{named} footnotes and
  1632. optional inline definition. Here are the valid references:
  1633. @table @code
  1634. @item [fn:name]
  1635. A named footnote reference, where @code{name} is a unique label word, or, for
  1636. simplicity of automatic creation, a number.
  1637. @item [fn::This is the inline definition of this footnote]
  1638. A @LaTeX{}-like anonymous footnote where the definition is given directly at the
  1639. reference point.
  1640. @item [fn:name:a definition]
  1641. An inline definition of a footnote, which also specifies a name for the note.
  1642. Since Org allows multiple references to the same note, you can then use
  1643. @code{[fn:name]} to create additional references.
  1644. @end table
  1645. @vindex org-footnote-auto-label
  1646. Footnote labels can be created automatically, or you can create names yourself.
  1647. This is handled by the variable @code{org-footnote-auto-label} and its
  1648. corresponding @code{#+STARTUP} keywords. See the docstring of that variable
  1649. for details.
  1650. @noindent The following command handles footnotes:
  1651. @table @kbd
  1652. @kindex C-c C-x f
  1653. @item C-c C-x f
  1654. The footnote action command.
  1655. When the cursor is on a footnote reference, jump to the definition. When it
  1656. is at a definition, jump to the (first) reference.
  1657. @vindex org-footnote-define-inline
  1658. @vindex org-footnote-section
  1659. @vindex org-footnote-auto-adjust
  1660. Otherwise, create a new footnote. Depending on the option
  1661. @code{org-footnote-define-inline}@footnote{The corresponding in-buffer
  1662. setting is: @code{#+STARTUP: fninline} or @code{#+STARTUP: nofninline}}, the
  1663. definition will be placed right into the text as part of the reference, or
  1664. separately into the location determined by the option
  1665. @code{org-footnote-section}.
  1666. When this command is called with a prefix argument, a menu of additional
  1667. options is offered:
  1668. @example
  1669. s @r{Sort the footnote definitions by reference sequence. During editing,}
  1670. @r{Org makes no effort to sort footnote definitions into a particular}
  1671. @r{sequence. If you want them sorted, use this command, which will}
  1672. @r{also move entries according to @code{org-footnote-section}. Automatic}
  1673. @r{sorting after each insertion/deletion can be configured using the}
  1674. @r{option @code{org-footnote-auto-adjust}.}
  1675. r @r{Renumber the simple @code{fn:N} footnotes. Automatic renumbering}
  1676. @r{after each insertion/deletion can be configured using the option}
  1677. @r{@code{org-footnote-auto-adjust}.}
  1678. S @r{Short for first @code{r}, then @code{s} action.}
  1679. n @r{Normalize the footnotes by collecting all definitions (including}
  1680. @r{inline definitions) into a special section, and then numbering them}
  1681. @r{in sequence. The references will then also be numbers.}
  1682. d @r{Delete the footnote at point, and all definitions of and references}
  1683. @r{to it.}
  1684. @end example
  1685. Depending on the variable @code{org-footnote-auto-adjust}@footnote{the
  1686. corresponding in-buffer options are @code{fnadjust} and @code{nofnadjust}.},
  1687. renumbering and sorting footnotes can be automatic after each insertion or
  1688. deletion.
  1689. @kindex C-c C-c
  1690. @item C-c C-c
  1691. If the cursor is on a footnote reference, jump to the definition. If it is a
  1692. the definition, jump back to the reference. When called at a footnote
  1693. location with a prefix argument, offer the same menu as @kbd{C-c C-x f}.
  1694. @kindex C-c C-o
  1695. @kindex mouse-1
  1696. @kindex mouse-2
  1697. @item C-c C-o @r{or} mouse-1/2
  1698. Footnote labels are also links to the corresponding definition/reference, and
  1699. you can use the usual commands to follow these links.
  1700. @vindex org-edit-footnote-reference
  1701. @kindex C-c '
  1702. @item C-c '
  1703. @item C-c '
  1704. Edit the footnote definition corresponding to the reference at point in
  1705. a separate window. The window can be closed by pressing @kbd{C-c '}.
  1706. @end table
  1707. @node Orgstruct mode
  1708. @section The Orgstruct minor mode
  1709. @cindex Orgstruct mode
  1710. @cindex minor mode for structure editing
  1711. If you like the intuitive way the Org mode structure editing and list
  1712. formatting works, you might want to use these commands in other modes like
  1713. Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes
  1714. this possible. Toggle the mode with @kbd{M-x orgstruct-mode RET}, or
  1715. turn it on by default, for example in Message mode, with one of:
  1716. @lisp
  1717. (add-hook 'message-mode-hook 'turn-on-orgstruct)
  1718. (add-hook 'message-mode-hook 'turn-on-orgstruct++)
  1719. @end lisp
  1720. When this mode is active and the cursor is on a line that looks to Org like a
  1721. headline or the first line of a list item, most structure editing commands
  1722. will work, even if the same keys normally have different functionality in the
  1723. major mode you are using. If the cursor is not in one of those special
  1724. lines, Orgstruct mode lurks silently in the shadows.
  1725. When you use @code{orgstruct++-mode}, Org will also export indentation and
  1726. autofill settings into that mode, and detect item context after the first
  1727. line of an item.
  1728. @vindex orgstruct-heading-prefix-regexp
  1729. You can also use Org structure editing to fold and unfold headlines in
  1730. @emph{any} file, provided you defined @code{orgstruct-heading-prefix-regexp}:
  1731. the regular expression must match the local prefix to use before Org's
  1732. headlines. For example, if you set this variable to @code{";; "} in Emacs
  1733. Lisp files, you will be able to fold and unfold headlines in Emacs Lisp
  1734. commented lines. Some commands like @code{org-demote} are disabled when the
  1735. prefix is set, but folding/unfolding will work correctly.
  1736. @node Org syntax
  1737. @section Org syntax
  1738. @cindex Org syntax
  1739. A reference document providing a formal description of Org's syntax is
  1740. available as @uref{http://orgmode.org/worg/dev/org-syntax.html, a draft on
  1741. Worg}, written and maintained by Nicolas Goaziou. It defines Org's core
  1742. internal concepts such as @code{headlines}, @code{sections}, @code{affiliated
  1743. keywords}, @code{(greater) elements} and @code{objects}. Each part of an Org
  1744. file falls into one of the categories above.
  1745. To explore the abstract structure of an Org buffer, run this in a buffer:
  1746. @lisp
  1747. M-: (org-element-parse-buffer) RET
  1748. @end lisp
  1749. It will output a list containing the buffer's content represented as an
  1750. abstract structure. The export engine relies on the information stored in
  1751. this list. Most interactive commands (e.g., for structure editing) also
  1752. rely on the syntactic meaning of the surrounding context.
  1753. @cindex syntax checker
  1754. @cindex linter
  1755. You can check syntax in your documents using @code{org-lint} command.
  1756. @node Tables
  1757. @chapter Tables
  1758. @cindex tables
  1759. @cindex editing tables
  1760. Org comes with a fast and intuitive table editor. Spreadsheet-like
  1761. calculations are supported using the Emacs @file{calc} package
  1762. (@pxref{Top, Calc, , calc, Gnu Emacs Calculator Manual}).
  1763. @menu
  1764. * Built-in table editor:: Simple tables
  1765. * Column width and alignment:: Overrule the automatic settings
  1766. * Column groups:: Grouping to trigger vertical lines
  1767. * Orgtbl mode:: The table editor as minor mode
  1768. * The spreadsheet:: The table editor has spreadsheet capabilities
  1769. * Org-Plot:: Plotting from org tables
  1770. @end menu
  1771. @node Built-in table editor
  1772. @section The built-in table editor
  1773. @cindex table editor, built-in
  1774. Org makes it easy to format tables in plain ASCII@. Any line with @samp{|} as
  1775. the first non-whitespace character is considered part of a table. @samp{|}
  1776. is also the column separator@footnote{To insert a vertical bar into a table
  1777. field, use @code{\vert} or, inside a word @code{abc\vert@{@}def}.}. A table
  1778. might look like this:
  1779. @example
  1780. | Name | Phone | Age |
  1781. |-------+-------+-----|
  1782. | Peter | 1234 | 17 |
  1783. | Anna | 4321 | 25 |
  1784. @end example
  1785. A table is re-aligned automatically each time you press @key{TAB} or
  1786. @key{RET} or @kbd{C-c C-c} inside the table. @key{TAB} also moves to
  1787. the next field (@key{RET} to the next row) and creates new table rows
  1788. at the end of the table or before horizontal lines. The indentation
  1789. of the table is set by the first line. Any line starting with
  1790. @samp{|-} is considered as a horizontal separator line and will be
  1791. expanded on the next re-align to span the whole table width. So, to
  1792. create the above table, you would only type
  1793. @example
  1794. |Name|Phone|Age|
  1795. |-
  1796. @end example
  1797. @noindent and then press @key{TAB} to align the table and start filling in
  1798. fields. Even faster would be to type @code{|Name|Phone|Age} followed by
  1799. @kbd{C-c @key{RET}}.
  1800. @vindex org-table-auto-blank-field
  1801. When typing text into a field, Org treats @key{DEL}, @key{Backspace}, and all
  1802. character keys in a special way, so that inserting and deleting avoids
  1803. shifting other fields. Also, when typing @emph{immediately after the cursor
  1804. was moved into a new field with @kbd{@key{TAB}}, @kbd{S-@key{TAB}} or
  1805. @kbd{@key{RET}}}, the field is automatically made blank. If this behavior is
  1806. too unpredictable for you, configure the option
  1807. @code{org-table-auto-blank-field}.
  1808. @table @kbd
  1809. @tsubheading{Creation and conversion}
  1810. @orgcmd{C-c |,org-table-create-or-convert-from-region}
  1811. Convert the active region to a table. If every line contains at least one
  1812. TAB character, the function assumes that the material is tab separated.
  1813. If every line contains a comma, comma-separated values (CSV) are assumed.
  1814. If not, lines are split at whitespace into fields. You can use a prefix
  1815. argument to force a specific separator: @kbd{C-u} forces CSV, @kbd{C-u
  1816. C-u} forces TAB, @kbd{C-u C-u C-u} will prompt for a regular expression to
  1817. match the separator, and a numeric argument N indicates that at least N
  1818. consecutive spaces, or alternatively a TAB will be the separator.
  1819. @*
  1820. If there is no active region, this command creates an empty Org
  1821. table. But it is easier just to start typing, like
  1822. @kbd{|Name|Phone|Age @key{RET} |- @key{TAB}}.
  1823. @tsubheading{Re-aligning and field motion}
  1824. @orgcmd{C-c C-c,org-table-align}
  1825. Re-align the table and don't move to another field.
  1826. @c
  1827. @orgcmd{C-c SPC,org-table-blank-field}
  1828. Blank the field at point.
  1829. @c
  1830. @orgcmd{TAB,org-table-next-field}
  1831. Re-align the table, move to the next field. Creates a new row if
  1832. necessary.
  1833. @c
  1834. @orgcmd{S-@key{TAB},org-table-previous-field}
  1835. Re-align, move to previous field.
  1836. @c
  1837. @orgcmd{@key{RET},org-table-next-row}
  1838. Re-align the table and move down to next row. Creates a new row if
  1839. necessary. At the beginning or end of a line, @key{RET} still does
  1840. NEWLINE, so it can be used to split a table.
  1841. @c
  1842. @orgcmd{M-a,org-table-beginning-of-field}
  1843. Move to beginning of the current table field, or on to the previous field.
  1844. @orgcmd{M-e,org-table-end-of-field}
  1845. Move to end of the current table field, or on to the next field.
  1846. @tsubheading{Column and row editing}
  1847. @orgcmdkkcc{M-@key{left},M-@key{right},org-table-move-column-left,org-table-move-column-right}
  1848. Move the current column left/right.
  1849. @c
  1850. @orgcmd{M-S-@key{left},org-table-delete-column}
  1851. Kill the current column.
  1852. @c
  1853. @orgcmd{M-S-@key{right},org-table-insert-column}
  1854. Insert a new column to the left of the cursor position.
  1855. @c
  1856. @orgcmdkkcc{M-@key{up},M-@key{down},org-table-move-row-up,org-table-move-row-down}
  1857. Move the current row up/down.
  1858. @c
  1859. @orgcmd{M-S-@key{up},org-table-kill-row}
  1860. Kill the current row or horizontal line.
  1861. @c
  1862. @orgcmd{M-S-@key{down},org-table-insert-row}
  1863. Insert a new row above the current row. With a prefix argument, the line is
  1864. created below the current one.
  1865. @c
  1866. @orgcmd{C-c -,org-table-insert-hline}
  1867. Insert a horizontal line below current row. With a prefix argument, the line
  1868. is created above the current line.
  1869. @c
  1870. @orgcmd{C-c @key{RET},org-table-hline-and-move}
  1871. Insert a horizontal line below current row, and move the cursor into the row
  1872. below that line.
  1873. @c
  1874. @orgcmd{C-c ^,org-table-sort-lines}
  1875. Sort the table lines in the region. The position of point indicates the
  1876. column to be used for sorting, and the range of lines is the range
  1877. between the nearest horizontal separator lines, or the entire table. If
  1878. point is before the first column, you will be prompted for the sorting
  1879. column. If there is an active region, the mark specifies the first line
  1880. and the sorting column, while point should be in the last line to be
  1881. included into the sorting. The command prompts for the sorting type
  1882. (alphabetically, numerically, or by time). You can sort in normal or
  1883. reverse order. You can also supply your own key extraction and comparison
  1884. functions. When called with a prefix argument, alphabetic sorting will be
  1885. case-sensitive.
  1886. @tsubheading{Regions}
  1887. @orgcmd{C-c C-x M-w,org-table-copy-region}
  1888. Copy a rectangular region from a table to a special clipboard. Point and
  1889. mark determine edge fields of the rectangle. If there is no active region,
  1890. copy just the current field. The process ignores horizontal separator lines.
  1891. @c
  1892. @orgcmd{C-c C-x C-w,org-table-cut-region}
  1893. Copy a rectangular region from a table to a special clipboard, and
  1894. blank all fields in the rectangle. So this is the ``cut'' operation.
  1895. @c
  1896. @orgcmd{C-c C-x C-y,org-table-paste-rectangle}
  1897. Paste a rectangular region into a table.
  1898. The upper left corner ends up in the current field. All involved fields
  1899. will be overwritten. If the rectangle does not fit into the present table,
  1900. the table is enlarged as needed. The process ignores horizontal separator
  1901. lines.
  1902. @c
  1903. @orgcmd{M-@key{RET},org-table-wrap-region}
  1904. Split the current field at the cursor position and move the rest to the line
  1905. below. If there is an active region, and both point and mark are in the same
  1906. column, the text in the column is wrapped to minimum width for the given
  1907. number of lines. A numeric prefix argument may be used to change the number
  1908. of desired lines. If there is no region, but you specify a prefix argument,
  1909. the current field is made blank, and the content is appended to the field
  1910. above.
  1911. @tsubheading{Calculations}
  1912. @cindex formula, in tables
  1913. @cindex calculations, in tables
  1914. @cindex region, active
  1915. @cindex active region
  1916. @cindex transient mark mode
  1917. @orgcmd{C-c +,org-table-sum}
  1918. Sum the numbers in the current column, or in the rectangle defined by
  1919. the active region. The result is shown in the echo area and can
  1920. be inserted with @kbd{C-y}.
  1921. @c
  1922. @orgcmd{S-@key{RET},org-table-copy-down}
  1923. @vindex org-table-copy-increment
  1924. When current field is empty, copy from first non-empty field above. When not
  1925. empty, copy current field down to next row and move cursor along with it.
  1926. Depending on the option @code{org-table-copy-increment}, integer field
  1927. values will be incremented during copy. Integers that are too large will not
  1928. be incremented. Also, a @code{0} prefix argument temporarily disables the
  1929. increment. This key is also used by shift-selection and related modes
  1930. (@pxref{Conflicts}).
  1931. @tsubheading{Miscellaneous}
  1932. @orgcmd{C-c `,org-table-edit-field}
  1933. Edit the current field in a separate window. This is useful for fields that
  1934. are not fully visible (@pxref{Column width and alignment}). When called with
  1935. a @kbd{C-u} prefix, just make the full field visible, so that it can be
  1936. edited in place. When called with two @kbd{C-u} prefixes, make the editor
  1937. window follow the cursor through the table and always show the current
  1938. field. The follow mode exits automatically when the cursor leaves the table,
  1939. or when you repeat this command with @kbd{C-u C-u C-c `}.
  1940. @c
  1941. @item M-x org-table-import RET
  1942. Import a file as a table. The table should be TAB or whitespace
  1943. separated. Use, for example, to import a spreadsheet table or data
  1944. from a database, because these programs generally can write
  1945. TAB-separated text files. This command works by inserting the file into
  1946. the buffer and then converting the region to a table. Any prefix
  1947. argument is passed on to the converter, which uses it to determine the
  1948. separator.
  1949. @orgcmd{C-c |,org-table-create-or-convert-from-region}
  1950. Tables can also be imported by pasting tabular text into the Org
  1951. buffer, selecting the pasted text with @kbd{C-x C-x} and then using the
  1952. @kbd{C-c |} command (see above under @i{Creation and conversion}).
  1953. @c
  1954. @item M-x org-table-export RET
  1955. @findex org-table-export
  1956. @vindex org-table-export-default-format
  1957. Export the table, by default as a TAB-separated file. Use for data
  1958. exchange with, for example, spreadsheet or database programs. The format
  1959. used to export the file can be configured in the option
  1960. @code{org-table-export-default-format}. You may also use properties
  1961. @code{TABLE_EXPORT_FILE} and @code{TABLE_EXPORT_FORMAT} to specify the file
  1962. name and the format for table export in a subtree. Org supports quite
  1963. general formats for exported tables. The exporter format is the same as the
  1964. format used by Orgtbl radio tables, see @ref{Translator functions}, for a
  1965. detailed description.
  1966. @end table
  1967. If you don't like the automatic table editor because it gets in your
  1968. way on lines which you would like to start with @samp{|}, you can turn
  1969. it off with
  1970. @lisp
  1971. (setq org-enable-table-editor nil)
  1972. @end lisp
  1973. @noindent Then the only table command that still works is
  1974. @kbd{C-c C-c} to do a manual re-align.
  1975. @node Column width and alignment
  1976. @section Column width and alignment
  1977. @cindex narrow columns in tables
  1978. @cindex alignment in tables
  1979. The width of columns is automatically determined by the table editor. And
  1980. also the alignment of a column is determined automatically from the fraction
  1981. of number-like versus non-number fields in the column.
  1982. Sometimes a single field or a few fields need to carry more text, leading to
  1983. inconveniently wide columns. Or maybe you want to make a table with several
  1984. columns having a fixed width, regardless of content. To set the width of
  1985. a column, one field anywhere in the column may contain just the string
  1986. @samp{<N>} where @samp{N} is an integer specifying the width of the column in
  1987. characters. The next re-align will then set the width of this column to this
  1988. value.
  1989. @example
  1990. @group
  1991. |---+------------------------------| |---+--------|
  1992. | | | | | <6> |
  1993. | 1 | one | | 1 | one |
  1994. | 2 | two | ----\ | 2 | two |
  1995. | 3 | This is a long chunk of text | ----/ | 3 | This=> |
  1996. | 4 | four | | 4 | four |
  1997. |---+------------------------------| |---+--------|
  1998. @end group
  1999. @end example
  2000. @noindent
  2001. Fields that are wider become clipped and end in the string @samp{=>}.
  2002. Note that the full text is still in the buffer but is hidden.
  2003. To see the full text, hold the mouse over the field---a tool-tip window
  2004. will show the full content. To edit such a field, use the command
  2005. @kbd{C-c `} (that is @kbd{C-c} followed by the grave accent). This will
  2006. open a new window with the full field. Edit it and finish with @kbd{C-c
  2007. C-c}.
  2008. @vindex org-startup-align-all-tables
  2009. When visiting a file containing a table with narrowed columns, the
  2010. necessary character hiding has not yet happened, and the table needs to
  2011. be aligned before it looks nice. Setting the option
  2012. @code{org-startup-align-all-tables} will realign all tables in a file
  2013. upon visiting, but also slow down startup. You can also set this option
  2014. on a per-file basis with:
  2015. @example
  2016. #+STARTUP: align
  2017. #+STARTUP: noalign
  2018. @end example
  2019. If you would like to overrule the automatic alignment of number-rich columns
  2020. to the right and of string-rich columns to the left, you can use @samp{<r>},
  2021. @samp{<c>}@footnote{Centering does not work inside Emacs, but it does have an
  2022. effect when exporting to HTML.} or @samp{<l>} in a similar fashion. You may
  2023. also combine alignment and field width like this: @samp{<r10>}.
  2024. Lines which only contain these formatting cookies will be removed
  2025. automatically when exporting the document.
  2026. @node Column groups
  2027. @section Column groups
  2028. @cindex grouping columns in tables
  2029. When Org exports tables, it does so by default without vertical lines because
  2030. that is visually more satisfying in general. Occasionally however, vertical
  2031. lines can be useful to structure a table into groups of columns, much like
  2032. horizontal lines can do for groups of rows. In order to specify column
  2033. groups, you can use a special row where the first field contains only
  2034. @samp{/}. The further fields can either contain @samp{<} to indicate that
  2035. this column should start a group, @samp{>} to indicate the end of a group, or
  2036. @samp{<>} (no space between @samp{<} and @samp{>}) to make a column a group
  2037. of its own. Boundaries between column groups will upon export be marked with
  2038. vertical lines. Here is an example:
  2039. @example
  2040. | N | N^2 | N^3 | N^4 | ~sqrt(n)~ | ~sqrt[4](N)~ |
  2041. |---+-----+-----+-----+-----------+--------------|
  2042. | / | < | | > | < | > |
  2043. | 1 | 1 | 1 | 1 | 1 | 1 |
  2044. | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 |
  2045. | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 |
  2046. |---+-----+-----+-----+-----------+--------------|
  2047. #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
  2048. @end example
  2049. It is also sufficient to just insert the column group starters after
  2050. every vertical line you would like to have:
  2051. @example
  2052. | N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
  2053. |----+-----+-----+-----+---------+------------|
  2054. | / | < | | | < | |
  2055. @end example
  2056. @node Orgtbl mode
  2057. @section The Orgtbl minor mode
  2058. @cindex Orgtbl mode
  2059. @cindex minor mode for tables
  2060. If you like the intuitive way the Org table editor works, you
  2061. might also want to use it in other modes like Text mode or Mail mode.
  2062. The minor mode Orgtbl mode makes this possible. You can always toggle
  2063. the mode with @kbd{M-x orgtbl-mode RET}. To turn it on by default, for
  2064. example in Message mode, use
  2065. @lisp
  2066. (add-hook 'message-mode-hook 'turn-on-orgtbl)
  2067. @end lisp
  2068. Furthermore, with some special setup, it is possible to maintain tables
  2069. in arbitrary syntax with Orgtbl mode. For example, it is possible to
  2070. construct @LaTeX{} tables with the underlying ease and power of
  2071. Orgtbl mode, including spreadsheet capabilities. For details, see
  2072. @ref{Tables in arbitrary syntax}.
  2073. @node The spreadsheet
  2074. @section The spreadsheet
  2075. @cindex calculations, in tables
  2076. @cindex spreadsheet capabilities
  2077. @cindex @file{calc} package
  2078. The table editor makes use of the Emacs @file{calc} package to implement
  2079. spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to
  2080. derive fields from other fields. While fully featured, Org's implementation
  2081. is not identical to other spreadsheets. For example, Org knows the concept
  2082. of a @emph{column formula} that will be applied to all non-header fields in a
  2083. column without having to copy the formula to each relevant field. There is
  2084. also a formula debugger, and a formula editor with features for highlighting
  2085. fields in the table corresponding to the references at the point in the
  2086. formula, moving these references by arrow keys
  2087. @menu
  2088. * References:: How to refer to another field or range
  2089. * Formula syntax for Calc:: Using Calc to compute stuff
  2090. * Formula syntax for Lisp:: Writing formulas in Emacs Lisp
  2091. * Durations and time values:: How to compute durations and time values
  2092. * Field and range formulas:: Formula for specific (ranges of) fields
  2093. * Column formulas:: Formulas valid for an entire column
  2094. * Lookup functions:: Lookup functions for searching tables
  2095. * Editing and debugging formulas:: Fixing formulas
  2096. * Updating the table:: Recomputing all dependent fields
  2097. * Advanced features:: Field and column names, parameters and automatic recalc
  2098. @end menu
  2099. @node References
  2100. @subsection References
  2101. @cindex references
  2102. To compute fields in the table from other fields, formulas must
  2103. reference other fields or ranges. In Org, fields can be referenced
  2104. by name, by absolute coordinates, and by relative coordinates. To find
  2105. out what the coordinates of a field are, press @kbd{C-c ?} in that
  2106. field, or press @kbd{C-c @}} to toggle the display of a grid.
  2107. @subsubheading Field references
  2108. @cindex field references
  2109. @cindex references, to fields
  2110. Formulas can reference the value of another field in two ways. Like in
  2111. any other spreadsheet, you may reference fields with a letter/number
  2112. combination like @code{B3}, meaning the 2nd field in the 3rd row.
  2113. @vindex org-table-use-standard-references
  2114. However, Org prefers@footnote{Org will understand references typed by the
  2115. user as @samp{B4}, but it will not use this syntax when offering a formula
  2116. for editing. You can customize this behavior using the option
  2117. @code{org-table-use-standard-references}.} to use another, more general
  2118. representation that looks like this:
  2119. @example
  2120. @@@var{row}$@var{column}
  2121. @end example
  2122. Column specifications can be absolute like @code{$1},
  2123. @code{$2},...@code{$@var{N}}, or relative to the current column (i.e., the
  2124. column of the field which is being computed) like @code{$+1} or @code{$-2}.
  2125. @code{$<} and @code{$>} are immutable references to the first and last
  2126. column, respectively, and you can use @code{$>>>} to indicate the third
  2127. column from the right.
  2128. The row specification only counts data lines and ignores horizontal separator
  2129. lines (hlines). Like with columns, you can use absolute row numbers
  2130. @code{@@1}, @code{@@2},...@code{@@@var{N}}, and row numbers relative to the
  2131. current row like @code{@@+3} or @code{@@-1}. @code{@@<} and @code{@@>} are
  2132. immutable references the first and last@footnote{For backward compatibility
  2133. you can also use special names like @code{$LR5} and @code{$LR12} to refer in
  2134. a stable way to the 5th and 12th field in the last row of the table.
  2135. However, this syntax is deprecated, it should not be used for new documents.
  2136. Use @code{@@>$} instead.} row in the table, respectively. You may also
  2137. specify the row relative to one of the hlines: @code{@@I} refers to the first
  2138. hline, @code{@@II} to the second, etc. @code{@@-I} refers to the first such
  2139. line above the current line, @code{@@+I} to the first such line below the
  2140. current line. You can also write @code{@@III+2} which is the second data line
  2141. after the third hline in the table.
  2142. @code{@@0} and @code{$0} refer to the current row and column, respectively,
  2143. i.e., to the row/column for the field being computed. Also, if you omit
  2144. either the column or the row part of the reference, the current row/column is
  2145. implied.
  2146. Org's references with @emph{unsigned} numbers are fixed references
  2147. in the sense that if you use the same reference in the formula for two
  2148. different fields, the same field will be referenced each time.
  2149. Org's references with @emph{signed} numbers are floating
  2150. references because the same reference operator can reference different
  2151. fields depending on the field being calculated by the formula.
  2152. Here are a few examples:
  2153. @example
  2154. @@2$3 @r{2nd row, 3rd column (same as @code{C2})}
  2155. $5 @r{column 5 in the current row (same as @code{E&})}
  2156. @@2 @r{current column, row 2}
  2157. @@-1$-3 @r{the field one row up, three columns to the left}
  2158. @@-I$2 @r{field just under hline above current row, column 2}
  2159. @@>$5 @r{field in the last row, in column 5}
  2160. @end example
  2161. @subsubheading Range references
  2162. @cindex range references
  2163. @cindex references, to ranges
  2164. You may reference a rectangular range of fields by specifying two field
  2165. references connected by two dots @samp{..}. If both fields are in the
  2166. current row, you may simply use @samp{$2..$7}, but if at least one field
  2167. is in a different row, you need to use the general @code{@@row$column}
  2168. format at least for the first field (i.e the reference must start with
  2169. @samp{@@} in order to be interpreted correctly). Examples:
  2170. @example
  2171. $1..$3 @r{first three fields in the current row}
  2172. $P..$Q @r{range, using column names (see under Advanced)}
  2173. $<<<..$>> @r{start in third column, continue to the last but one}
  2174. @@2$1..@@4$3 @r{6 fields between these two fields (same as @code{A2..C4})}
  2175. @@-1$-2..@@-1 @r{3 fields in the row above, starting from 2 columns on the left}
  2176. @@I..II @r{between first and second hline, short for @code{@@I..@@II}}
  2177. @end example
  2178. @noindent Range references return a vector of values that can be fed
  2179. into Calc vector functions. Empty fields in ranges are normally suppressed,
  2180. so that the vector contains only the non-empty fields. For other options
  2181. with the mode switches @samp{E}, @samp{N} and examples @pxref{Formula syntax
  2182. for Calc}.
  2183. @subsubheading Field coordinates in formulas
  2184. @cindex field coordinates
  2185. @cindex coordinates, of field
  2186. @cindex row, of field coordinates
  2187. @cindex column, of field coordinates
  2188. One of the very first actions during evaluation of Calc formulas and Lisp
  2189. formulas is to substitute @code{@@#} and @code{$#} in the formula with the
  2190. row or column number of the field where the current result will go to. The
  2191. traditional Lisp formula equivalents are @code{org-table-current-dline} and
  2192. @code{org-table-current-column}. Examples:
  2193. @table @code
  2194. @item if(@@# % 2, $#, string(""))
  2195. Insert column number on odd rows, set field to empty on even rows.
  2196. @item $2 = '(identity remote(FOO, @@@@#$1))
  2197. Copy text or values of each row of column 1 of the table named @code{FOO}
  2198. into column 2 of the current table.
  2199. @item @@3 = 2 * remote(FOO, @@1$$#)
  2200. Insert the doubled value of each column of row 1 of the table named
  2201. @code{FOO} into row 3 of the current table.
  2202. @end table
  2203. @noindent For the second/third example, the table named @code{FOO} must have
  2204. at least as many rows/columns as the current table. Note that this is
  2205. inefficient@footnote{The computation time scales as O(N^2) because the table
  2206. named @code{FOO} is parsed for each field to be read.} for large number of
  2207. rows/columns.
  2208. @subsubheading Named references
  2209. @cindex named references
  2210. @cindex references, named
  2211. @cindex name, of column or field
  2212. @cindex constants, in calculations
  2213. @cindex #+CONSTANTS
  2214. @vindex org-table-formula-constants
  2215. @samp{$name} is interpreted as the name of a column, parameter or
  2216. constant. Constants are defined globally through the option
  2217. @code{org-table-formula-constants}, and locally (for the file) through a
  2218. line like
  2219. @example
  2220. #+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
  2221. @end example
  2222. @noindent
  2223. @vindex constants-unit-system
  2224. @pindex constants.el
  2225. Also properties (@pxref{Properties and columns}) can be used as
  2226. constants in table formulas: for a property @samp{:Xyz:} use the name
  2227. @samp{$PROP_Xyz}, and the property will be searched in the current
  2228. outline entry and in the hierarchy above it. If you have the
  2229. @file{constants.el} package, it will also be used to resolve constants,
  2230. including natural constants like @samp{$h} for Planck's constant, and
  2231. units like @samp{$km} for kilometers@footnote{@file{constants.el} can
  2232. supply the values of constants in two different unit systems, @code{SI}
  2233. and @code{cgs}. Which one is used depends on the value of the variable
  2234. @code{constants-unit-system}. You can use the @code{#+STARTUP} options
  2235. @code{constSI} and @code{constcgs} to set this value for the current
  2236. buffer.}. Column names and parameters can be specified in special table
  2237. lines. These are described below, see @ref{Advanced features}. All
  2238. names must start with a letter, and further consist of letters and
  2239. numbers.
  2240. @subsubheading Remote references
  2241. @cindex remote references
  2242. @cindex references, remote
  2243. @cindex references, to a different table
  2244. @cindex name, of column or field
  2245. @cindex constants, in calculations
  2246. @cindex #+NAME, for table
  2247. You may also reference constants, fields and ranges from a different table,
  2248. either in the current file or even in a different file. The syntax is
  2249. @example
  2250. remote(NAME-OR-ID,REF)
  2251. @end example
  2252. @noindent
  2253. where NAME can be the name of a table in the current file as set by a
  2254. @code{#+NAME: Name} line before the table. It can also be the ID of an
  2255. entry, even in a different file, and the reference then refers to the first
  2256. table in that entry. REF is an absolute field or range reference as
  2257. described above for example @code{@@3$3} or @code{$somename}, valid in the
  2258. referenced table.
  2259. Indirection of NAME-OR-ID: When NAME-OR-ID has the format @code{@@ROW$COLUMN}
  2260. it will be substituted with the name or ID found in this field of the current
  2261. table. For example @code{remote($1, @@>$2)} => @code{remote(year_2013,
  2262. @@>$1)}. The format @code{B3} is not supported because it can not be
  2263. distinguished from a plain table name or ID.
  2264. @node Formula syntax for Calc
  2265. @subsection Formula syntax for Calc
  2266. @cindex formula syntax, Calc
  2267. @cindex syntax, of formulas
  2268. A formula can be any algebraic expression understood by the Emacs @file{Calc}
  2269. package. Note that @file{calc} has the non-standard convention that @samp{/}
  2270. has lower precedence than @samp{*}, so that @samp{a/b*c} is interpreted as
  2271. @samp{a/(b*c)}. Before evaluation by @code{calc-eval} (@pxref{Calling Calc
  2272. from Your Programs, calc-eval, Calling Calc from Your Lisp Programs, calc,
  2273. GNU Emacs Calc Manual}), variable substitution takes place according to the
  2274. rules described above.
  2275. @cindex vectors, in table calculations
  2276. The range vectors can be directly fed into the Calc vector functions
  2277. like @samp{vmean} and @samp{vsum}.
  2278. @cindex format specifier
  2279. @cindex mode, for @file{calc}
  2280. @vindex org-calc-default-modes
  2281. A formula can contain an optional mode string after a semicolon. This
  2282. string consists of flags to influence Calc and other modes during
  2283. execution. By default, Org uses the standard Calc modes (precision
  2284. 12, angular units degrees, fraction and symbolic modes off). The display
  2285. format, however, has been changed to @code{(float 8)} to keep tables
  2286. compact. The default settings can be configured using the option
  2287. @code{org-calc-default-modes}.
  2288. @noindent List of modes:
  2289. @table @asis
  2290. @item @code{p20}
  2291. Set the internal Calc calculation precision to 20 digits.
  2292. @item @code{n3}, @code{s3}, @code{e2}, @code{f4}
  2293. Normal, scientific, engineering or fixed format of the result of Calc passed
  2294. back to Org. Calc formatting is unlimited in precision as long as the Calc
  2295. calculation precision is greater.
  2296. @item @code{D}, @code{R}
  2297. Degree and radian angle modes of Calc.
  2298. @item @code{F}, @code{S}
  2299. Fraction and symbolic modes of Calc.
  2300. @item @code{T}, @code{t}, @code{U}
  2301. Duration computations in Calc or Lisp, @pxref{Durations and time values}.
  2302. @item @code{E}
  2303. If and how to consider empty fields. Without @samp{E} empty fields in range
  2304. references are suppressed so that the Calc vector or Lisp list contains only
  2305. the non-empty fields. With @samp{E} the empty fields are kept. For empty
  2306. fields in ranges or empty field references the value @samp{nan} (not a
  2307. number) is used in Calc formulas and the empty string is used for Lisp
  2308. formulas. Add @samp{N} to use 0 instead for both formula types. For the
  2309. value of a field the mode @samp{N} has higher precedence than @samp{E}.
  2310. @item @code{N}
  2311. Interpret all fields as numbers, use 0 for non-numbers. See the next section
  2312. to see how this is essential for computations with Lisp formulas. In Calc
  2313. formulas it is used only occasionally because there number strings are
  2314. already interpreted as numbers without @samp{N}.
  2315. @item @code{L}
  2316. Literal, for Lisp formulas only. See the next section.
  2317. @end table
  2318. @noindent
  2319. Unless you use large integer numbers or high-precision-calculation and
  2320. -display for floating point numbers you may alternatively provide a
  2321. @samp{printf} format specifier to reformat the Calc result after it has been
  2322. passed back to Org instead of letting Calc already do the
  2323. formatting@footnote{The @samp{printf} reformatting is limited in precision
  2324. because the value passed to it is converted into an @samp{integer} or
  2325. @samp{double}. The @samp{integer} is limited in size by truncating the
  2326. signed value to 32 bits. The @samp{double} is limited in precision to 64
  2327. bits overall which leaves approximately 16 significant decimal digits.}. A
  2328. few examples:
  2329. @example
  2330. $1+$2 @r{Sum of first and second field}
  2331. $1+$2;%.2f @r{Same, format result to two decimals}
  2332. exp($2)+exp($1) @r{Math functions can be used}
  2333. $0;%.1f @r{Reformat current cell to 1 decimal}
  2334. ($3-32)*5/9 @r{Degrees F -> C conversion}
  2335. $c/$1/$cm @r{Hz -> cm conversion, using @file{constants.el}}
  2336. tan($1);Dp3s1 @r{Compute in degrees, precision 3, display SCI 1}
  2337. sin($1);Dp3%.1e @r{Same, but use printf specifier for display}
  2338. taylor($3,x=7,2) @r{Taylor series of $3, at x=7, second degree}
  2339. @end example
  2340. Calc also contains a complete set of logical operations, (@pxref{Logical
  2341. Operations, , Logical Operations, calc, GNU Emacs Calc Manual}). For example
  2342. @table @code
  2343. @item if($1 < 20, teen, string(""))
  2344. "teen" if age $1 is less than 20, else the Org table result field is set to
  2345. empty with the empty string.
  2346. @item if("$1" == "nan" || "$2" == "nan", string(""), $1 + $2); E f-1
  2347. Sum of the first two columns. When at least one of the input fields is empty
  2348. the Org table result field is set to empty. @samp{E} is required to not
  2349. convert empty fields to 0. @samp{f-1} is an optional Calc format string
  2350. similar to @samp{%.1f} but leaves empty results empty.
  2351. @item if(typeof(vmean($1..$7)) == 12, string(""), vmean($1..$7); E
  2352. Mean value of a range unless there is any empty field. Every field in the
  2353. range that is empty is replaced by @samp{nan} which lets @samp{vmean} result
  2354. in @samp{nan}. Then @samp{typeof == 12} detects the @samp{nan} from
  2355. @samp{vmean} and the Org table result field is set to empty. Use this when
  2356. the sample set is expected to never have missing values.
  2357. @item if("$1..$7" == "[]", string(""), vmean($1..$7))
  2358. Mean value of a range with empty fields skipped. Every field in the range
  2359. that is empty is skipped. When all fields in the range are empty the mean
  2360. value is not defined and the Org table result field is set to empty. Use
  2361. this when the sample set can have a variable size.
  2362. @item vmean($1..$7); EN
  2363. To complete the example before: Mean value of a range with empty fields
  2364. counting as samples with value 0. Use this only when incomplete sample sets
  2365. should be padded with 0 to the full size.
  2366. @end table
  2367. You can add your own Calc functions defined in Emacs Lisp with @code{defmath}
  2368. and use them in formula syntax for Calc.
  2369. @node Formula syntax for Lisp
  2370. @subsection Emacs Lisp forms as formulas
  2371. @cindex Lisp forms, as table formulas
  2372. It is also possible to write a formula in Emacs Lisp. This can be useful
  2373. for string manipulation and control structures, if Calc's functionality is
  2374. not enough.
  2375. If a formula starts with an apostrophe followed by an opening parenthesis,
  2376. then it is evaluated as a Lisp form. The evaluation should return either a
  2377. string or a number. Just as with @file{calc} formulas, you can specify modes
  2378. and a printf format after a semicolon.
  2379. With Emacs Lisp forms, you need to be conscious about the way field
  2380. references are interpolated into the form. By default, a reference will be
  2381. interpolated as a Lisp string (in double-quotes) containing the field. If
  2382. you provide the @samp{N} mode switch, all referenced elements will be numbers
  2383. (non-number fields will be zero) and interpolated as Lisp numbers, without
  2384. quotes. If you provide the @samp{L} flag, all fields will be interpolated
  2385. literally, without quotes. I.e., if you want a reference to be interpreted
  2386. as a string by the Lisp form, enclose the reference operator itself in
  2387. double-quotes, like @code{"$3"}. Ranges are inserted as space-separated
  2388. fields, so you can embed them in list or vector syntax.
  2389. Here are a few examples---note how the @samp{N} mode is used when we do
  2390. computations in Lisp:
  2391. @table @code
  2392. @item '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))
  2393. Swap the first two characters of the content of column 1.
  2394. @item '(+ $1 $2);N
  2395. Add columns 1 and 2, equivalent to Calc's @code{$1+$2}.
  2396. @item '(apply '+ '($1..$4));N
  2397. Compute the sum of columns 1 to 4, like Calc's @code{vsum($1..$4)}.
  2398. @end table
  2399. @node Durations and time values
  2400. @subsection Durations and time values
  2401. @cindex Duration, computing
  2402. @cindex Time, computing
  2403. @vindex org-table-duration-custom-format
  2404. If you want to compute time values use the @code{T}, @code{t}, or @code{U}
  2405. flag, either in Calc formulas or Elisp formulas:
  2406. @example
  2407. @group
  2408. | Task 1 | Task 2 | Total |
  2409. |---------+----------+----------|
  2410. | 2:12 | 1:47 | 03:59:00 |
  2411. | 2:12 | 1:47 | 03:59 |
  2412. | 3:02:20 | -2:07:00 | 0.92 |
  2413. #+TBLFM: @@2$3=$1+$2;T::@@3$3=$1+$2;U::@@4$3=$1+$2;t
  2414. @end group
  2415. @end example
  2416. Input duration values must be of the form @code{HH:MM[:SS]}, where seconds
  2417. are optional. With the @code{T} flag, computed durations will be displayed
  2418. as @code{HH:MM:SS} (see the first formula above). With the @code{U} flag,
  2419. seconds will be omitted so that the result will be only @code{HH:MM} (see
  2420. second formula above). Zero-padding of the hours field will depend upon the
  2421. value of the variable @code{org-table-duration-hour-zero-padding}.
  2422. With the @code{t} flag, computed durations will be displayed according to the
  2423. value of the option @code{org-table-duration-custom-format}, which defaults
  2424. to @code{'hours} and will display the result as a fraction of hours (see the
  2425. third formula in the example above).
  2426. Negative duration values can be manipulated as well, and integers will be
  2427. considered as seconds in addition and subtraction.
  2428. @node Field and range formulas
  2429. @subsection Field and range formulas
  2430. @cindex field formula
  2431. @cindex range formula
  2432. @cindex formula, for individual table field
  2433. @cindex formula, for range of fields
  2434. To assign a formula to a particular field, type it directly into the field,
  2435. preceded by @samp{:=}, for example @samp{:=vsum(@@II..III)}. When you press
  2436. @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
  2437. the formula will be stored as the formula for this field, evaluated, and the
  2438. current field will be replaced with the result.
  2439. @cindex #+TBLFM
  2440. Formulas are stored in a special line starting with @samp{#+TBLFM:} directly
  2441. below the table. If you type the equation in the 4th field of the 3rd data
  2442. line in the table, the formula will look like @samp{@@3$4=$1+$2}. When
  2443. inserting/deleting/swapping columns and rows with the appropriate commands,
  2444. @i{absolute references} (but not relative ones) in stored formulas are
  2445. modified in order to still reference the same field. To avoid this, in
  2446. particular in range references, anchor ranges at the table borders (using
  2447. @code{@@<}, @code{@@>}, @code{$<}, @code{$>}), or at hlines using the
  2448. @code{@@I} notation. Automatic adaptation of field references does of course
  2449. not happen if you edit the table structure with normal editing
  2450. commands---then you must fix the equations yourself.
  2451. Instead of typing an equation into the field, you may also use the following
  2452. command
  2453. @table @kbd
  2454. @orgcmd{C-u C-c =,org-table-eval-formula}
  2455. Install a new formula for the current field. The command prompts for a
  2456. formula with default taken from the @samp{#+TBLFM:} line, applies
  2457. it to the current field, and stores it.
  2458. @end table
  2459. The left-hand side of a formula can also be a special expression in order to
  2460. assign the formula to a number of different fields. There is no keyboard
  2461. shortcut to enter such range formulas. To add them, use the formula editor
  2462. (@pxref{Editing and debugging formulas}) or edit the @code{#+TBLFM:} line
  2463. directly.
  2464. @table @code
  2465. @item $2=
  2466. Column formula, valid for the entire column. This is so common that Org
  2467. treats these formulas in a special way, see @ref{Column formulas}.
  2468. @item @@3=
  2469. Row formula, applies to all fields in the specified row. @code{@@>=} means
  2470. the last row.
  2471. @item @@1$2..@@4$3=
  2472. Range formula, applies to all fields in the given rectangular range. This
  2473. can also be used to assign a formula to some but not all fields in a row.
  2474. @item $name=
  2475. Named field, see @ref{Advanced features}.
  2476. @end table
  2477. @node Column formulas
  2478. @subsection Column formulas
  2479. @cindex column formula
  2480. @cindex formula, for table column
  2481. When you assign a formula to a simple column reference like @code{$3=}, the
  2482. same formula will be used in all fields of that column, with the following
  2483. very convenient exceptions: (i) If the table contains horizontal separator
  2484. hlines with rows above and below, everything before the first such hline is
  2485. considered part of the table @emph{header} and will not be modified by column
  2486. formulas. Therefore a header is mandatory when you use column formulas and
  2487. want to add hlines to group rows, like for example to separate a total row at
  2488. the bottom from the summand rows above. (ii) Fields that already get a value
  2489. from a field/range formula will be left alone by column formulas. These
  2490. conditions make column formulas very easy to use.
  2491. To assign a formula to a column, type it directly into any field in the
  2492. column, preceded by an equal sign, like @samp{=$1+$2}. When you press
  2493. @key{TAB} or @key{RET} or @kbd{C-c C-c} with the cursor still in the field,
  2494. the formula will be stored as the formula for the current column, evaluated
  2495. and the current field replaced with the result. If the field contains only
  2496. @samp{=}, the previously stored formula for this column is used. For each
  2497. column, Org will only remember the most recently used formula. In the
  2498. @samp{#+TBLFM:} line, column formulas will look like @samp{$4=$1+$2}. The
  2499. left-hand side of a column formula cannot be the name of column, it must be
  2500. the numeric column reference or @code{$>}.
  2501. Instead of typing an equation into the field, you may also use the
  2502. following command:
  2503. @table @kbd
  2504. @orgcmd{C-c =,org-table-eval-formula}
  2505. Install a new formula for the current column and replace current field with
  2506. the result of the formula. The command prompts for a formula, with default
  2507. taken from the @samp{#+TBLFM} line, applies it to the current field and
  2508. stores it. With a numeric prefix argument(e.g., @kbd{C-5 C-c =}) the command
  2509. will apply it to that many consecutive fields in the current column.
  2510. @end table
  2511. @node Lookup functions
  2512. @subsection Lookup functions
  2513. @cindex lookup functions in tables
  2514. @cindex table lookup functions
  2515. Org has three predefined Emacs Lisp functions for lookups in tables.
  2516. @table @code
  2517. @item (org-lookup-first VAL S-LIST R-LIST &optional PREDICATE)
  2518. @findex org-lookup-first
  2519. Searches for the first element @code{S} in list @code{S-LIST} for which
  2520. @lisp
  2521. (PREDICATE VAL S)
  2522. @end lisp
  2523. is @code{t}; returns the value from the corresponding position in list
  2524. @code{R-LIST}. The default @code{PREDICATE} is @code{equal}. Note that the
  2525. parameters @code{VAL} and @code{S} are passed to @code{PREDICATE} in the same
  2526. order as the corresponding parameters are in the call to
  2527. @code{org-lookup-first}, where @code{VAL} precedes @code{S-LIST}. If
  2528. @code{R-LIST} is @code{nil}, the matching element @code{S} of @code{S-LIST}
  2529. is returned.
  2530. @item (org-lookup-last VAL S-LIST R-LIST &optional PREDICATE)
  2531. @findex org-lookup-last
  2532. Similar to @code{org-lookup-first} above, but searches for the @i{last}
  2533. element for which @code{PREDICATE} is @code{t}.
  2534. @item (org-lookup-all VAL S-LIST R-LIST &optional PREDICATE)
  2535. @findex org-lookup-all
  2536. Similar to @code{org-lookup-first}, but searches for @i{all} elements for
  2537. which @code{PREDICATE} is @code{t}, and returns @i{all} corresponding
  2538. values. This function can not be used by itself in a formula, because it
  2539. returns a list of values. However, powerful lookups can be built when this
  2540. function is combined with other Emacs Lisp functions.
  2541. @end table
  2542. If the ranges used in these functions contain empty fields, the @code{E} mode
  2543. for the formula should usually be specified: otherwise empty fields will not be
  2544. included in @code{S-LIST} and/or @code{R-LIST} which can, for example, result
  2545. in an incorrect mapping from an element of @code{S-LIST} to the corresponding
  2546. element of @code{R-LIST}.
  2547. These three functions can be used to implement associative arrays, count
  2548. matching cells, rank results, group data etc. For practical examples
  2549. see @uref{http://orgmode.org/worg/org-tutorials/org-lookups.html, this
  2550. tutorial on Worg}.
  2551. @node Editing and debugging formulas
  2552. @subsection Editing and debugging formulas
  2553. @cindex formula editing
  2554. @cindex editing, of table formulas
  2555. @vindex org-table-use-standard-references
  2556. You can edit individual formulas in the minibuffer or directly in the field.
  2557. Org can also prepare a special buffer with all active formulas of a table.
  2558. When offering a formula for editing, Org converts references to the standard
  2559. format (like @code{B3} or @code{D&}) if possible. If you prefer to only work
  2560. with the internal format (like @code{@@3$2} or @code{$4}), configure the
  2561. option @code{org-table-use-standard-references}.
  2562. @table @kbd
  2563. @orgcmdkkc{C-c =,C-u C-c =,org-table-eval-formula}
  2564. Edit the formula associated with the current column/field in the
  2565. minibuffer. See @ref{Column formulas}, and @ref{Field and range formulas}.
  2566. @orgcmd{C-u C-u C-c =,org-table-eval-formula}
  2567. Re-insert the active formula (either a
  2568. field formula, or a column formula) into the current field, so that you
  2569. can edit it directly in the field. The advantage over editing in the
  2570. minibuffer is that you can use the command @kbd{C-c ?}.
  2571. @orgcmd{C-c ?,org-table-field-info}
  2572. While editing a formula in a table field, highlight the field(s)
  2573. referenced by the reference at the cursor position in the formula.
  2574. @kindex C-c @}
  2575. @findex org-table-toggle-coordinate-overlays
  2576. @item C-c @}
  2577. Toggle the display of row and column numbers for a table, using overlays
  2578. (@command{org-table-toggle-coordinate-overlays}). These are updated each
  2579. time the table is aligned; you can force it with @kbd{C-c C-c}.
  2580. @kindex C-c @{
  2581. @findex org-table-toggle-formula-debugger
  2582. @item C-c @{
  2583. Toggle the formula debugger on and off
  2584. (@command{org-table-toggle-formula-debugger}). See below.
  2585. @orgcmd{C-c ',org-table-edit-formulas}
  2586. Edit all formulas for the current table in a special buffer, where the
  2587. formulas will be displayed one per line. If the current field has an
  2588. active formula, the cursor in the formula editor will mark it.
  2589. While inside the special buffer, Org will automatically highlight
  2590. any field or range reference at the cursor position. You may edit,
  2591. remove and add formulas, and use the following commands:
  2592. @table @kbd
  2593. @orgcmdkkc{C-c C-c,C-x C-s,org-table-fedit-finish}
  2594. Exit the formula editor and store the modified formulas. With @kbd{C-u}
  2595. prefix, also apply the new formulas to the entire table.
  2596. @orgcmd{C-c C-q,org-table-fedit-abort}
  2597. Exit the formula editor without installing changes.
  2598. @orgcmd{C-c C-r,org-table-fedit-toggle-ref-type}
  2599. Toggle all references in the formula editor between standard (like
  2600. @code{B3}) and internal (like @code{@@3$2}).
  2601. @orgcmd{@key{TAB},org-table-fedit-lisp-indent}
  2602. Pretty-print or indent Lisp formula at point. When in a line containing
  2603. a Lisp formula, format the formula according to Emacs Lisp rules.
  2604. Another @key{TAB} collapses the formula back again. In the open
  2605. formula, @key{TAB} re-indents just like in Emacs Lisp mode.
  2606. @orgcmd{M-@key{TAB},lisp-complete-symbol}
  2607. Complete Lisp symbols, just like in Emacs Lisp mode.@footnote{Many desktops
  2608. intercept @kbd{M-@key{TAB}} to switch windows. Use @kbd{C-M-i} or
  2609. @kbd{@key{ESC} @key{TAB}} instead for completion (@pxref{Completion}).}
  2610. @kindex S-@key{up}
  2611. @kindex S-@key{down}
  2612. @kindex S-@key{left}
  2613. @kindex S-@key{right}
  2614. @findex org-table-fedit-ref-up
  2615. @findex org-table-fedit-ref-down
  2616. @findex org-table-fedit-ref-left
  2617. @findex org-table-fedit-ref-right
  2618. @item S-@key{up}/@key{down}/@key{left}/@key{right}
  2619. Shift the reference at point. For example, if the reference is
  2620. @code{B3} and you press @kbd{S-@key{right}}, it will become @code{C3}.
  2621. This also works for relative references and for hline references.
  2622. @orgcmdkkcc{M-S-@key{up},M-S-@key{down},org-table-fedit-line-up,org-table-fedit-line-down}
  2623. Move the test line for column formulas in the Org buffer up and
  2624. down.
  2625. @orgcmdkkcc{M-@key{up},M-@key{down},org-table-fedit-scroll-down,org-table-fedit-scroll-up}
  2626. Scroll the window displaying the table.
  2627. @kindex C-c @}
  2628. @findex org-table-toggle-coordinate-overlays
  2629. @item C-c @}
  2630. Turn the coordinate grid in the table on and off.
  2631. @end table
  2632. @end table
  2633. Making a table field blank does not remove the formula associated with
  2634. the field, because that is stored in a different line (the @samp{#+TBLFM}
  2635. line)---during the next recalculation the field will be filled again.
  2636. To remove a formula from a field, you have to give an empty reply when
  2637. prompted for the formula, or to edit the @samp{#+TBLFM} line.
  2638. @kindex C-c C-c
  2639. You may edit the @samp{#+TBLFM} directly and re-apply the changed
  2640. equations with @kbd{C-c C-c} in that line or with the normal
  2641. recalculation commands in the table.
  2642. @anchor{Using multiple #+TBLFM lines}
  2643. @subsubheading Using multiple #+TBLFM lines
  2644. @cindex #+TBLFM line, multiple
  2645. @cindex #+TBLFM
  2646. @cindex #+TBLFM, switching
  2647. @kindex C-c C-c
  2648. You may apply the formula temporarily. This is useful when you
  2649. switch the formula. Place multiple @samp{#+TBLFM} lines right
  2650. after the table, and then press @kbd{C-c C-c} on the formula to
  2651. apply. Here is an example:
  2652. @example
  2653. | x | y |
  2654. |---+---|
  2655. | 1 | |
  2656. | 2 | |
  2657. #+TBLFM: $2=$1*1
  2658. #+TBLFM: $2=$1*2
  2659. @end example
  2660. @noindent
  2661. Pressing @kbd{C-c C-c} in the line of @samp{#+TBLFM: $2=$1*2} yields:
  2662. @example
  2663. | x | y |
  2664. |---+---|
  2665. | 1 | 2 |
  2666. | 2 | 4 |
  2667. #+TBLFM: $2=$1*1
  2668. #+TBLFM: $2=$1*2
  2669. @end example
  2670. @noindent
  2671. Note: If you recalculate this table (with @kbd{C-u C-c *}, for example), you
  2672. will get the following result of applying only the first @samp{#+TBLFM} line.
  2673. @example
  2674. | x | y |
  2675. |---+---|
  2676. | 1 | 1 |
  2677. | 2 | 2 |
  2678. #+TBLFM: $2=$1*1
  2679. #+TBLFM: $2=$1*2
  2680. @end example
  2681. @subsubheading Debugging formulas
  2682. @cindex formula debugging
  2683. @cindex debugging, of table formulas
  2684. When the evaluation of a formula leads to an error, the field content
  2685. becomes the string @samp{#ERROR}. If you would like see what is going
  2686. on during variable substitution and calculation in order to find a bug,
  2687. turn on formula debugging in the @code{Tbl} menu and repeat the
  2688. calculation, for example by pressing @kbd{C-u C-u C-c = @key{RET}} in a
  2689. field. Detailed information will be displayed.
  2690. @node Updating the table
  2691. @subsection Updating the table
  2692. @cindex recomputing table fields
  2693. @cindex updating, table
  2694. Recalculation of a table is normally not automatic, but needs to be
  2695. triggered by a command. See @ref{Advanced features}, for a way to make
  2696. recalculation at least semi-automatic.
  2697. In order to recalculate a line of a table or the entire table, use the
  2698. following commands:
  2699. @table @kbd
  2700. @orgcmd{C-c *,org-table-recalculate}
  2701. Recalculate the current row by first applying the stored column formulas
  2702. from left to right, and all field/range formulas in the current row.
  2703. @c
  2704. @kindex C-u C-c *
  2705. @item C-u C-c *
  2706. @kindex C-u C-c C-c
  2707. @itemx C-u C-c C-c
  2708. Recompute the entire table, line by line. Any lines before the first
  2709. hline are left alone, assuming that these are part of the table header.
  2710. @c
  2711. @orgcmdkkc{C-u C-u C-c *,C-u C-u C-c C-c,org-table-iterate}
  2712. Iterate the table by recomputing it until no further changes occur.
  2713. This may be necessary if some computed fields use the value of other
  2714. fields that are computed @i{later} in the calculation sequence.
  2715. @item M-x org-table-recalculate-buffer-tables RET
  2716. @findex org-table-recalculate-buffer-tables
  2717. Recompute all tables in the current buffer.
  2718. @item M-x org-table-iterate-buffer-tables RET
  2719. @findex org-table-iterate-buffer-tables
  2720. Iterate all tables in the current buffer, in order to converge table-to-table
  2721. dependencies.
  2722. @end table
  2723. @node Advanced features
  2724. @subsection Advanced features
  2725. If you want the recalculation of fields to happen automatically, or if you
  2726. want to be able to assign @i{names}@footnote{Such names must start by an
  2727. alphabetic character and use only alphanumeric/underscore characters.} to
  2728. fields and columns, you need to reserve the first column of the table for
  2729. special marking characters.
  2730. @table @kbd
  2731. @orgcmd{C-#,org-table-rotate-recalc-marks}
  2732. Rotate the calculation mark in first column through the states @samp{ },
  2733. @samp{#}, @samp{*}, @samp{!}, @samp{$}. When there is an active region,
  2734. change all marks in the region.
  2735. @end table
  2736. Here is an example of a table that collects exam results of students and
  2737. makes use of these features:
  2738. @example
  2739. @group
  2740. |---+---------+--------+--------+--------+-------+------|
  2741. | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note |
  2742. |---+---------+--------+--------+--------+-------+------|
  2743. | ! | | P1 | P2 | P3 | Tot | |
  2744. | # | Maximum | 10 | 15 | 25 | 50 | 10.0 |
  2745. | ^ | | m1 | m2 | m3 | mt | |
  2746. |---+---------+--------+--------+--------+-------+------|
  2747. | # | Peter | 10 | 8 | 23 | 41 | 8.2 |
  2748. | # | Sam | 2 | 4 | 3 | 9 | 1.8 |
  2749. |---+---------+--------+--------+--------+-------+------|
  2750. | | Average | | | | 25.0 | |
  2751. | ^ | | | | | at | |
  2752. | $ | max=50 | | | | | |
  2753. |---+---------+--------+--------+--------+-------+------|
  2754. #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@@-II..@@-I);%.1f
  2755. @end group
  2756. @end example
  2757. @noindent @b{Important}: please note that for these special tables,
  2758. recalculating the table with @kbd{C-u C-c *} will only affect rows that
  2759. are marked @samp{#} or @samp{*}, and fields that have a formula assigned
  2760. to the field itself. The column formulas are not applied in rows with
  2761. empty first field.
  2762. @cindex marking characters, tables
  2763. The marking characters have the following meaning:
  2764. @table @samp
  2765. @item !
  2766. The fields in this line define names for the columns, so that you may
  2767. refer to a column as @samp{$Tot} instead of @samp{$6}.
  2768. @item ^
  2769. This row defines names for the fields @emph{above} the row. With such
  2770. a definition, any formula in the table may use @samp{$m1} to refer to
  2771. the value @samp{10}. Also, if you assign a formula to a names field, it
  2772. will be stored as @samp{$name=...}.
  2773. @item _
  2774. Similar to @samp{^}, but defines names for the fields in the row
  2775. @emph{below}.
  2776. @item $
  2777. Fields in this row can define @emph{parameters} for formulas. For
  2778. example, if a field in a @samp{$} row contains @samp{max=50}, then
  2779. formulas in this table can refer to the value 50 using @samp{$max}.
  2780. Parameters work exactly like constants, only that they can be defined on
  2781. a per-table basis.
  2782. @item #
  2783. Fields in this row are automatically recalculated when pressing
  2784. @key{TAB} or @key{RET} or @kbd{S-@key{TAB}} in this row. Also, this row
  2785. is selected for a global recalculation with @kbd{C-u C-c *}. Unmarked
  2786. lines will be left alone by this command.
  2787. @item *
  2788. Selects this line for global recalculation with @kbd{C-u C-c *}, but
  2789. not for automatic recalculation. Use this when automatic
  2790. recalculation slows down editing too much.
  2791. @item @w{ }
  2792. Unmarked lines are exempt from recalculation with @kbd{C-u C-c *}.
  2793. All lines that should be recalculated should be marked with @samp{#}
  2794. or @samp{*}.
  2795. @item /
  2796. Do not export this line. Useful for lines that contain the narrowing
  2797. @samp{<N>} markers or column group markers.
  2798. @end table
  2799. Finally, just to whet your appetite for what can be done with the
  2800. fantastic @file{calc.el} package, here is a table that computes the Taylor
  2801. series of degree @code{n} at location @code{x} for a couple of
  2802. functions.
  2803. @example
  2804. @group
  2805. |---+-------------+---+-----+--------------------------------------|
  2806. | | Func | n | x | Result |
  2807. |---+-------------+---+-----+--------------------------------------|
  2808. | # | exp(x) | 1 | x | 1 + x |
  2809. | # | exp(x) | 2 | x | 1 + x + x^2 / 2 |
  2810. | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 |
  2811. | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 |
  2812. | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 |
  2813. | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 |
  2814. |---+-------------+---+-----+--------------------------------------|
  2815. #+TBLFM: $5=taylor($2,$4,$3);n3
  2816. @end group
  2817. @end example
  2818. @node Org-Plot
  2819. @section Org-Plot
  2820. @cindex graph, in tables
  2821. @cindex plot tables using Gnuplot
  2822. @cindex #+PLOT
  2823. Org-Plot can produce graphs of information stored in org tables, either
  2824. graphically or in ASCII-art.
  2825. @subheading Graphical plots using @file{Gnuplot}
  2826. Org-Plot produces 2D and 3D graphs using @file{Gnuplot}
  2827. @uref{http://www.gnuplot.info/} and @file{gnuplot-mode}
  2828. @uref{http://xafs.org/BruceRavel/GnuplotMode}. To see this in action, ensure
  2829. that you have both Gnuplot and Gnuplot mode installed on your system, then
  2830. call @kbd{C-c " g} or @kbd{M-x org-plot/gnuplot @key{RET}} on the following
  2831. table.
  2832. @example
  2833. @group
  2834. #+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]"
  2835. | Sede | Max cites | H-index |
  2836. |-----------+-----------+---------|
  2837. | Chile | 257.72 | 21.39 |
  2838. | Leeds | 165.77 | 19.68 |
  2839. | Sao Paolo | 71.00 | 11.50 |
  2840. | Stockholm | 134.19 | 14.33 |
  2841. | Morelia | 257.56 | 17.67 |
  2842. @end group
  2843. @end example
  2844. Notice that Org Plot is smart enough to apply the table's headers as labels.
  2845. Further control over the labels, type, content, and appearance of plots can
  2846. be exercised through the @code{#+PLOT:} lines preceding a table. See below
  2847. for a complete list of Org-plot options. The @code{#+PLOT:} lines are
  2848. optional. For more information and examples see the Org-plot tutorial at
  2849. @uref{http://orgmode.org/worg/org-tutorials/org-plot.html}.
  2850. @subsubheading Plot Options
  2851. @table @code
  2852. @item set
  2853. Specify any @command{gnuplot} option to be set when graphing.
  2854. @item title
  2855. Specify the title of the plot.
  2856. @item ind
  2857. Specify which column of the table to use as the @code{x} axis.
  2858. @item deps
  2859. Specify the columns to graph as a Lisp style list, surrounded by parentheses
  2860. and separated by spaces for example @code{dep:(3 4)} to graph the third and
  2861. fourth columns (defaults to graphing all other columns aside from the @code{ind}
  2862. column).
  2863. @item type
  2864. Specify whether the plot will be @code{2d}, @code{3d}, or @code{grid}.
  2865. @item with
  2866. Specify a @code{with} option to be inserted for every col being plotted
  2867. (e.g., @code{lines}, @code{points}, @code{boxes}, @code{impulses}, etc...).
  2868. Defaults to @code{lines}.
  2869. @item file
  2870. If you want to plot to a file, specify @code{"@var{path/to/desired/output-file}"}.
  2871. @item labels
  2872. List of labels to be used for the @code{deps} (defaults to the column headers
  2873. if they exist).
  2874. @item line
  2875. Specify an entire line to be inserted in the Gnuplot script.
  2876. @item map
  2877. When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a
  2878. flat mapping rather than a @code{3d} slope.
  2879. @item timefmt
  2880. Specify format of Org mode timestamps as they will be parsed by Gnuplot.
  2881. Defaults to @samp{%Y-%m-%d-%H:%M:%S}.
  2882. @item script
  2883. If you want total control, you can specify a script file (place the file name
  2884. between double-quotes) which will be used to plot. Before plotting, every
  2885. instance of @code{$datafile} in the specified script will be replaced with
  2886. the path to the generated data file. Note: even if you set this option, you
  2887. may still want to specify the plot type, as that can impact the content of
  2888. the data file.
  2889. @end table
  2890. @subheading ASCII bar plots
  2891. While the cursor is on a column, typing @kbd{C-c " a} or
  2892. @kbd{M-x orgtbl-ascii-plot @key{RET}} create a new column containing an
  2893. ASCII-art bars plot. The plot is implemented through a regular column
  2894. formula. When the source column changes, the bar plot may be updated by
  2895. refreshing the table, for example typing @kbd{C-u C-c *}.
  2896. @example
  2897. @group
  2898. | Sede | Max cites | |
  2899. |---------------+-----------+--------------|
  2900. | Chile | 257.72 | WWWWWWWWWWWW |
  2901. | Leeds | 165.77 | WWWWWWWh |
  2902. | Sao Paolo | 71.00 | WWW; |
  2903. | Stockholm | 134.19 | WWWWWW: |
  2904. | Morelia | 257.56 | WWWWWWWWWWWH |
  2905. | Rochefourchat | 0.00 | |
  2906. #+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12)
  2907. @end group
  2908. @end example
  2909. The formula is an elisp call:
  2910. @lisp
  2911. (orgtbl-ascii-draw COLUMN MIN MAX WIDTH)
  2912. @end lisp
  2913. @table @code
  2914. @item COLUMN
  2915. is a reference to the source column.
  2916. @item MIN MAX
  2917. are the minimal and maximal values displayed. Sources values
  2918. outside this range are displayed as @samp{too small}
  2919. or @samp{too large}.
  2920. @item WIDTH
  2921. is the width in characters of the bar-plot. It defaults to @samp{12}.
  2922. @end table
  2923. @node Hyperlinks
  2924. @chapter Hyperlinks
  2925. @cindex hyperlinks
  2926. Like HTML, Org provides links inside a file, external links to
  2927. other files, Usenet articles, emails, and much more.
  2928. @menu
  2929. * Link format:: How links in Org are formatted
  2930. * Internal links:: Links to other places in the current file
  2931. * External links:: URL-like links to the world
  2932. * Handling links:: Creating, inserting and following
  2933. * Using links outside Org:: Linking from my C source code?
  2934. * Link abbreviations:: Shortcuts for writing complex links
  2935. * Search options:: Linking to a specific location
  2936. * Custom searches:: When the default search is not enough
  2937. @end menu
  2938. @node Link format
  2939. @section Link format
  2940. @cindex link format
  2941. @cindex format, of links
  2942. Org will recognize plain URL-like links and activate them as
  2943. clickable links. The general link format, however, looks like this:
  2944. @example
  2945. [[link][description]] @r{or alternatively} [[link]]
  2946. @end example
  2947. @noindent
  2948. Once a link in the buffer is complete (all brackets present), Org
  2949. will change the display so that @samp{description} is displayed instead
  2950. of @samp{[[link][description]]} and @samp{link} is displayed instead of
  2951. @samp{[[link]]}. Links will be highlighted in the face @code{org-link},
  2952. which by default is an underlined face. You can directly edit the
  2953. visible part of a link. Note that this can be either the @samp{link}
  2954. part (if there is no description) or the @samp{description} part. To
  2955. edit also the invisible @samp{link} part, use @kbd{C-c C-l} with the
  2956. cursor on the link.
  2957. If you place the cursor at the beginning or just behind the end of the
  2958. displayed text and press @key{BACKSPACE}, you will remove the
  2959. (invisible) bracket at that location. This makes the link incomplete
  2960. and the internals are again displayed as plain text. Inserting the
  2961. missing bracket hides the link internals again. To show the
  2962. internal structure of all links, use the menu entry
  2963. @code{Org->Hyperlinks->Literal links}.
  2964. @node Internal links
  2965. @section Internal links
  2966. @cindex internal links
  2967. @cindex links, internal
  2968. @cindex targets, for links
  2969. @cindex property, CUSTOM_ID
  2970. If the link does not look like a URL, it is considered to be internal in the
  2971. current file. The most important case is a link like
  2972. @samp{[[#my-custom-id]]} which will link to the entry with the
  2973. @code{CUSTOM_ID} property @samp{my-custom-id}. You are responsible yourself
  2974. to make sure these custom IDs are unique in a file.
  2975. Links such as @samp{[[My Target]]} or @samp{[[My Target][Find my target]]}
  2976. lead to a text search in the current file.
  2977. The link can be followed with @kbd{C-c C-o} when the cursor is on the link,
  2978. or with a mouse click (@pxref{Handling links}). Links to custom IDs will
  2979. point to the corresponding headline. The preferred match for a text link is
  2980. a @i{dedicated target}: the same string in double angular brackets, like
  2981. @samp{<<My Target>>}.
  2982. @cindex #+NAME
  2983. If no dedicated target exists, the link will then try to match the exact name
  2984. of an element within the buffer. Naming is done with the @code{#+NAME}
  2985. keyword, which has to be put in the line before the element it refers to, as
  2986. in the following example
  2987. @example
  2988. #+NAME: My Target
  2989. | a | table |
  2990. |----+------------|
  2991. | of | four cells |
  2992. @end example
  2993. If none of the above succeeds, Org will search for a headline that is exactly
  2994. the link text but may also include a TODO keyword and tags@footnote{To insert
  2995. a link targeting a headline, in-buffer completion can be used. Just type
  2996. a star followed by a few optional letters into the buffer and press
  2997. @kbd{M-@key{TAB}}. All headlines in the current buffer will be offered as
  2998. completions.}.
  2999. During export, internal links will be used to mark objects and assign them
  3000. a number. Marked objects will then be referenced by links pointing to them.
  3001. In particular, links without a description will appear as the number assigned
  3002. to the marked object@footnote{When targeting a @code{#+NAME} keyword,
  3003. @code{#+CAPTION} keyword is mandatory in order to get proper numbering
  3004. (@pxref{Images and tables}).}. In the following excerpt from an Org buffer
  3005. @example
  3006. - one item
  3007. - <<target>>another item
  3008. Here we refer to item [[target]].
  3009. @end example
  3010. @noindent
  3011. The last sentence will appear as @samp{Here we refer to item 2} when
  3012. exported.
  3013. In non-Org files, the search will look for the words in the link text. In
  3014. the above example the search would be for @samp{my target}.
  3015. Following a link pushes a mark onto Org's own mark ring. You can
  3016. return to the previous position with @kbd{C-c &}. Using this command
  3017. several times in direct succession goes back to positions recorded
  3018. earlier.
  3019. @menu
  3020. * Radio targets:: Make targets trigger links in plain text
  3021. @end menu
  3022. @node Radio targets
  3023. @subsection Radio targets
  3024. @cindex radio targets
  3025. @cindex targets, radio
  3026. @cindex links, radio targets
  3027. Org can automatically turn any occurrences of certain target names
  3028. in normal text into a link. So without explicitly creating a link, the
  3029. text connects to the target radioing its position. Radio targets are
  3030. enclosed by triple angular brackets. For example, a target @samp{<<<My
  3031. Target>>>} causes each occurrence of @samp{my target} in normal text to
  3032. become activated as a link. The Org file is scanned automatically
  3033. for radio targets only when the file is first loaded into Emacs. To
  3034. update the target list during editing, press @kbd{C-c C-c} with the
  3035. cursor on or at a target.
  3036. @node External links
  3037. @section External links
  3038. @cindex links, external
  3039. @cindex external links
  3040. @cindex Gnus links
  3041. @cindex BBDB links
  3042. @cindex IRC links
  3043. @cindex URL links
  3044. @cindex file links
  3045. @cindex RMAIL links
  3046. @cindex MH-E links
  3047. @cindex USENET links
  3048. @cindex SHELL links
  3049. @cindex Info links
  3050. @cindex Elisp links
  3051. Org supports links to files, websites, Usenet and email messages, BBDB
  3052. database entries and links to both IRC conversations and their logs.
  3053. External links are URL-like locators. They start with a short identifying
  3054. string followed by a colon. There can be no space after the colon. The
  3055. following list shows examples for each link type.
  3056. @example
  3057. http://www.astro.uva.nl/~dominik @r{on the web}
  3058. doi:10.1000/182 @r{DOI for an electronic resource}
  3059. file:/home/dominik/images/jupiter.jpg @r{file, absolute path}
  3060. /home/dominik/images/jupiter.jpg @r{same as above}
  3061. file:papers/last.pdf @r{file, relative path}
  3062. ./papers/last.pdf @r{same as above}
  3063. file:/ssh:myself@@some.where:papers/last.pdf @r{file, path on remote machine}
  3064. /ssh:myself@@some.where:papers/last.pdf @r{same as above}
  3065. file:sometextfile::NNN @r{file, jump to line number}
  3066. file:projects.org @r{another Org file}
  3067. file:projects.org::some words @r{text search in Org file}@footnote{
  3068. The actual behavior of the search will depend on the value of
  3069. the option @code{org-link-search-must-match-exact-headline}. If its value
  3070. is @code{nil}, then a fuzzy text search will be done. If it is @code{t}, then only
  3071. the exact headline will be matched, ignoring spaces and cookies. If the
  3072. value is @code{query-to-create}, then an exact headline will be searched; if
  3073. it is not found, then the user will be queried to create it.}
  3074. file:projects.org::*task title @r{heading search in Org file}@footnote{
  3075. Headline searches always match the exact headline, ignoring
  3076. spaces and cookies. If the headline is not found and the value of the option
  3077. @code{org-link-search-must-match-exact-headline} is @code{query-to-create},
  3078. then the user will be queried to create it.}
  3079. docview:papers/last.pdf::NNN @r{open in doc-view mode at page}
  3080. id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID}
  3081. news:comp.emacs @r{Usenet link}
  3082. mailto:adent@@galaxy.net @r{Mail link}
  3083. mhe:folder @r{MH-E folder link}
  3084. mhe:folder#id @r{MH-E message link}
  3085. rmail:folder @r{RMAIL folder link}
  3086. rmail:folder#id @r{RMAIL message link}
  3087. gnus:group @r{Gnus group link}
  3088. gnus:group#id @r{Gnus article link}
  3089. bbdb:R.*Stallman @r{BBDB link (with regexp)}
  3090. irc:/irc.com/#emacs/bob @r{IRC link}
  3091. info:org#External links @r{Info node or index link}
  3092. shell:ls *.org @r{A shell command}
  3093. elisp:org-agenda @r{Interactive Elisp command}
  3094. elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate}
  3095. @end example
  3096. @cindex VM links
  3097. @cindex WANDERLUST links
  3098. On top of these built-in link types, some are available through the
  3099. @code{contrib/} directory (@pxref{Installation}). For example, these links
  3100. to VM or Wanderlust messages are available when you load the corresponding
  3101. libraries from the @code{contrib/} directory:
  3102. @example
  3103. vm:folder @r{VM folder link}
  3104. vm:folder#id @r{VM message link}
  3105. vm://myself@@some.where.org/folder#id @r{VM on remote machine}
  3106. vm-imap:account:folder @r{VM IMAP folder link}
  3107. vm-imap:account:folder#id @r{VM IMAP message link}
  3108. wl:folder @r{WANDERLUST folder link}
  3109. wl:folder#id @r{WANDERLUST message link}
  3110. @end example
  3111. For customizing Org to add new link types @ref{Adding hyperlink types}.
  3112. A link should be enclosed in double brackets and may contain a descriptive
  3113. text to be displayed instead of the URL (@pxref{Link format}), for example:
  3114. @example
  3115. [[https://www.gnu.org/software/emacs/][GNU Emacs]]
  3116. @end example
  3117. @noindent
  3118. If the description is a file name or URL that points to an image, HTML
  3119. export (@pxref{HTML export}) will inline the image as a clickable
  3120. button. If there is no description at all and the link points to an
  3121. image,
  3122. that image will be inlined into the exported HTML file.
  3123. @cindex square brackets, around links
  3124. @cindex plain text external links
  3125. Org also finds external links in the normal text and activates them
  3126. as links. If spaces must be part of the link (for example in
  3127. @samp{bbdb:Richard Stallman}), or if you need to remove ambiguities
  3128. about the end of the link, enclose them in square brackets.
  3129. @node Handling links
  3130. @section Handling links
  3131. @cindex links, handling
  3132. Org provides methods to create a link in the correct syntax, to
  3133. insert it into an Org file, and to follow the link.
  3134. @table @kbd
  3135. @orgcmd{C-c l,org-store-link}
  3136. @cindex storing links
  3137. Store a link to the current location. This is a @emph{global} command (you
  3138. must create the key binding yourself) which can be used in any buffer to
  3139. create a link. The link will be stored for later insertion into an Org
  3140. buffer (see below). What kind of link will be created depends on the current
  3141. buffer:
  3142. @b{Org mode buffers}@*
  3143. For Org files, if there is a @samp{<<target>>} at the cursor, the link points
  3144. to the target. Otherwise it points to the current headline, which will also
  3145. be the description@footnote{If the headline contains a timestamp, it will be
  3146. removed from the link and result in a wrong link---you should avoid putting
  3147. timestamp in the headline.}.
  3148. @vindex org-id-link-to-org-use-id
  3149. @cindex property, CUSTOM_ID
  3150. @cindex property, ID
  3151. If the headline has a @code{CUSTOM_ID} property, a link to this custom ID
  3152. will be stored. In addition or alternatively (depending on the value of
  3153. @code{org-id-link-to-org-use-id}), a globally unique @code{ID} property will
  3154. be created and/or used to construct a link@footnote{The library
  3155. @file{org-id.el} must first be loaded, either through @code{org-customize} by
  3156. enabling @code{org-id} in @code{org-modules}, or by adding @code{(require
  3157. 'org-id)} in your Emacs init file.}. So using this command in Org buffers
  3158. will potentially create two links: a human-readable from the custom ID, and
  3159. one that is globally unique and works even if the entry is moved from file to
  3160. file. Later, when inserting the link, you need to decide which one to use.
  3161. @b{Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus}@*
  3162. Pretty much all Emacs mail clients are supported. The link will point to the
  3163. current article, or, in some GNUS buffers, to the group. The description is
  3164. constructed from the author and the subject.
  3165. @b{Web browsers: Eww, W3 and W3M}@*
  3166. Here the link will be the current URL, with the page title as description.
  3167. @b{Contacts: BBDB}@*
  3168. Links created in a BBDB buffer will point to the current entry.
  3169. @b{Chat: IRC}@*
  3170. @vindex org-irc-link-to-logs
  3171. For IRC links, if you set the option @code{org-irc-link-to-logs} to @code{t},
  3172. a @samp{file:/} style link to the relevant point in the logs for the current
  3173. conversation is created. Otherwise an @samp{irc:/} style link to the
  3174. user/channel/server under the point will be stored.
  3175. @b{Other files}@*
  3176. For any other files, the link will point to the file, with a search string
  3177. (@pxref{Search options}) pointing to the contents of the current line. If
  3178. there is an active region, the selected words will form the basis of the
  3179. search string. If the automatically created link is not working correctly or
  3180. accurately enough, you can write custom functions to select the search string
  3181. and to do the search for particular file types---see @ref{Custom searches}.
  3182. The key binding @kbd{C-c l} is only a suggestion---see @ref{Installation}.
  3183. @b{Agenda view}@*
  3184. When the cursor is in an agenda view, the created link points to the
  3185. entry referenced by the current line.
  3186. @c
  3187. @orgcmd{C-c C-l,org-insert-link}
  3188. @cindex link completion
  3189. @cindex completion, of links
  3190. @cindex inserting links
  3191. @vindex org-keep-stored-link-after-insertion
  3192. @vindex org-link-parameters
  3193. Insert a link@footnote{Note that you don't have to use this command to
  3194. insert a link. Links in Org are plain text, and you can type or paste them
  3195. straight into the buffer. By using this command, the links are automatically
  3196. enclosed in double brackets, and you will be asked for the optional
  3197. descriptive text.}. This prompts for a link to be inserted into the buffer.
  3198. You can just type a link, using text for an internal link, or one of the link
  3199. type prefixes mentioned in the examples above. The link will be inserted
  3200. into the buffer@footnote{After insertion of a stored link, the link will be
  3201. removed from the list of stored links. To keep it in the list later use, use
  3202. a triple @kbd{C-u} prefix argument to @kbd{C-c C-l}, or configure the option
  3203. @code{org-keep-stored-link-after-insertion}.}, along with a descriptive text.
  3204. If some text was selected when this command is called, the selected text
  3205. becomes the default description.
  3206. @b{Inserting stored links}@*
  3207. All links stored during the
  3208. current session are part of the history for this prompt, so you can access
  3209. them with @key{up} and @key{down} (or @kbd{M-p/n}).
  3210. @b{Completion support}@* Completion with @key{TAB} will help you to insert
  3211. valid link prefixes like @samp{https:}, including the prefixes
  3212. defined through link abbreviations (@pxref{Link abbreviations}). If you
  3213. press @key{RET} after inserting only the @var{prefix}, Org will offer
  3214. specific completion support for some link types@footnote{This works if
  3215. a completion function is defined in the @samp{:complete} property of a link
  3216. in @code{org-link-parameters}.} For example, if you type @kbd{file
  3217. @key{RET}}, file name completion (alternative access: @kbd{C-u C-c C-l}, see
  3218. below) will be offered, and after @kbd{bbdb @key{RET}} you can complete
  3219. contact names.
  3220. @orgkey C-u C-c C-l
  3221. @cindex file name completion
  3222. @cindex completion, of file names
  3223. When @kbd{C-c C-l} is called with a @kbd{C-u} prefix argument, a link to
  3224. a file will be inserted and you may use file name completion to select
  3225. the name of the file. The path to the file is inserted relative to the
  3226. directory of the current Org file, if the linked file is in the current
  3227. directory or in a sub-directory of it, or if the path is written relative
  3228. to the current directory using @samp{../}. Otherwise an absolute path
  3229. is used, if possible with @samp{~/} for your home directory. You can
  3230. force an absolute path with two @kbd{C-u} prefixes.
  3231. @c
  3232. @item C-c C-l @ @r{(with cursor on existing link)}
  3233. When the cursor is on an existing link, @kbd{C-c C-l} allows you to edit the
  3234. link and description parts of the link.
  3235. @c
  3236. @cindex following links
  3237. @orgcmd{C-c C-o,org-open-at-point}
  3238. @vindex org-file-apps
  3239. @vindex org-link-frame-setup
  3240. Open link at point. This will launch a web browser for URLs (using
  3241. @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for
  3242. the corresponding links, and execute the command in a shell link. When the
  3243. cursor is on an internal link, this command runs the corresponding search.
  3244. When the cursor is on a TAG list in a headline, it creates the corresponding
  3245. TAGS view. If the cursor is on a timestamp, it compiles the agenda for that
  3246. date. Furthermore, it will visit text and remote files in @samp{file:} links
  3247. with Emacs and select a suitable application for local non-text files.
  3248. Classification of files is based on file extension only. See option
  3249. @code{org-file-apps}. If you want to override the default application and
  3250. visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid
  3251. opening in Emacs, use a @kbd{C-u C-u} prefix.@*
  3252. If the cursor is on a headline, but not on a link, offer all links in the
  3253. headline and entry text. If you want to setup the frame configuration for
  3254. following links, customize @code{org-link-frame-setup}.
  3255. @orgkey @key{RET}
  3256. @vindex org-return-follows-link
  3257. When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow
  3258. the link at point.
  3259. @c
  3260. @kindex mouse-2
  3261. @kindex mouse-1
  3262. @item mouse-2
  3263. @itemx mouse-1
  3264. On links, @kbd{mouse-1} and @kbd{mouse-2} will open the link just as @kbd{C-c
  3265. C-o} would.
  3266. @c
  3267. @kindex mouse-3
  3268. @item mouse-3
  3269. @vindex org-display-internal-link-with-indirect-buffer
  3270. Like @kbd{mouse-2}, but force file links to be opened with Emacs, and
  3271. internal links to be displayed in another window@footnote{See the
  3272. option @code{org-display-internal-link-with-indirect-buffer}}.
  3273. @c
  3274. @orgcmd{C-c C-x C-v,org-toggle-inline-images}
  3275. @cindex inlining images
  3276. @cindex images, inlining
  3277. @vindex org-startup-with-inline-images
  3278. @cindex @code{inlineimages}, STARTUP keyword
  3279. @cindex @code{noinlineimages}, STARTUP keyword
  3280. Toggle the inline display of linked images. Normally this will only inline
  3281. images that have no description part in the link, i.e., images that will also
  3282. be inlined during export. When called with a prefix argument, also display
  3283. images that do have a link description. You can ask for inline images to be
  3284. displayed at startup by configuring the variable
  3285. @code{org-startup-with-inline-images}@footnote{with corresponding
  3286. @code{#+STARTUP} keywords @code{inlineimages} and @code{noinlineimages}}.
  3287. @orgcmd{C-c %,org-mark-ring-push}
  3288. @cindex mark ring
  3289. Push the current position onto the mark ring, to be able to return
  3290. easily. Commands following an internal link do this automatically.
  3291. @c
  3292. @orgcmd{C-c &,org-mark-ring-goto}
  3293. @cindex links, returning to
  3294. Jump back to a recorded position. A position is recorded by the
  3295. commands following internal links, and by @kbd{C-c %}. Using this
  3296. command several times in direct succession moves through a ring of
  3297. previously recorded positions.
  3298. @c
  3299. @orgcmdkkcc{C-c C-x C-n,C-c C-x C-p,org-next-link,org-previous-link}
  3300. @cindex links, finding next/previous
  3301. Move forward/backward to the next link in the buffer. At the limit of
  3302. the buffer, the search fails once, and then wraps around. The key
  3303. bindings for this are really too long; you might want to bind this also
  3304. to @kbd{C-n} and @kbd{C-p}
  3305. @lisp
  3306. (add-hook 'org-load-hook
  3307. (lambda ()
  3308. (define-key org-mode-map "\C-n" 'org-next-link)
  3309. (define-key org-mode-map "\C-p" 'org-previous-link)))
  3310. @end lisp
  3311. @end table
  3312. @node Using links outside Org
  3313. @section Using links outside Org
  3314. You can insert and follow links that have Org syntax not only in
  3315. Org, but in any Emacs buffer. For this, you should create two
  3316. global commands, like this (please select suitable global keys
  3317. yourself):
  3318. @lisp
  3319. (global-set-key "\C-c L" 'org-insert-link-global)
  3320. (global-set-key "\C-c o" 'org-open-at-point-global)
  3321. @end lisp
  3322. @node Link abbreviations
  3323. @section Link abbreviations
  3324. @cindex link abbreviations
  3325. @cindex abbreviation, links
  3326. Long URLs can be cumbersome to type, and often many similar links are
  3327. needed in a document. For this you can use link abbreviations. An
  3328. abbreviated link looks like this
  3329. @example
  3330. [[linkword:tag][description]]
  3331. @end example
  3332. @noindent
  3333. @vindex org-link-abbrev-alist
  3334. where the tag is optional.
  3335. The @i{linkword} must be a word, starting with a letter, followed by
  3336. letters, numbers, @samp{-}, and @samp{_}. Abbreviations are resolved
  3337. according to the information in the variable @code{org-link-abbrev-alist}
  3338. that relates the linkwords to replacement text. Here is an example:
  3339. @smalllisp
  3340. @group
  3341. (setq org-link-abbrev-alist
  3342. '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
  3343. ("url-to-ja" . "http://translate.google.fr/translate?sl=en&tl=ja&u=%h")
  3344. ("google" . "http://www.google.com/search?q=")
  3345. ("gmap" . "http://maps.google.com/maps?q=%s")
  3346. ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1")
  3347. ("ads" . "http://adsabs.harvard.edu/cgi-bin/nph-abs_connect?author=%s&db_key=AST")))
  3348. @end group
  3349. @end smalllisp
  3350. If the replacement text contains the string @samp{%s}, it will be
  3351. replaced with the tag. Using @samp{%h} instead of @samp{%s} will
  3352. url-encode the tag (see the example above, where we need to encode
  3353. the URL parameter.) Using @samp{%(my-function)} will pass the tag
  3354. to a custom function, and replace it by the resulting string.
  3355. If the replacement text doesn't contain any specifier, the tag will simply be
  3356. appended in order to create the link.
  3357. Instead of a string, you may also specify a function that will be
  3358. called with the tag as the only argument to create the link.
  3359. With the above setting, you could link to a specific bug with
  3360. @code{[[bugzilla:129]]}, search the web for @samp{OrgMode} with
  3361. @code{[[google:OrgMode]]}, show the map location of the Free Software
  3362. Foundation @code{[[gmap:51 Franklin Street, Boston]]} or of Carsten office
  3363. @code{[[omap:Science Park 904, Amsterdam, The Netherlands]]} and find out
  3364. what the Org author is doing besides Emacs hacking with
  3365. @code{[[ads:Dominik,C]]}.
  3366. If you need special abbreviations just for a single Org buffer, you
  3367. can define them in the file with
  3368. @cindex #+LINK
  3369. @example
  3370. #+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
  3371. #+LINK: google http://www.google.com/search?q=%s
  3372. @end example
  3373. @noindent
  3374. In-buffer completion (@pxref{Completion}) can be used after @samp{[} to
  3375. complete link abbreviations. You may also define a function that implements
  3376. special (e.g., completion) support for inserting such a link with @kbd{C-c
  3377. C-l}. Such a function should not accept any arguments, and return the full
  3378. link with prefix. You can add a completion function to a link like this:
  3379. @lisp
  3380. (org-link-set-parameters ``type'' :complete #'some-function)
  3381. @end lisp
  3382. @node Search options
  3383. @section Search options in file links
  3384. @cindex search option in file links
  3385. @cindex file links, searching
  3386. File links can contain additional information to make Emacs jump to a
  3387. particular location in the file when following a link. This can be a
  3388. line number or a search option after a double@footnote{For backward
  3389. compatibility, line numbers can also follow a single colon.} colon. For
  3390. example, when the command @kbd{C-c l} creates a link (@pxref{Handling
  3391. links}) to a file, it encodes the words in the current line as a search
  3392. string that can be used to find this line back later when following the
  3393. link with @kbd{C-c C-o}.
  3394. Here is the syntax of the different ways to attach a search to a file
  3395. link, together with an explanation:
  3396. @example
  3397. [[file:~/code/main.c::255]]
  3398. [[file:~/xx.org::My Target]]
  3399. [[file:~/xx.org::*My Target]]
  3400. [[file:~/xx.org::#my-custom-id]]
  3401. [[file:~/xx.org::/regexp/]]
  3402. @end example
  3403. @table @code
  3404. @item 255
  3405. Jump to line 255.
  3406. @item My Target
  3407. Search for a link target @samp{<<My Target>>}, or do a text search for
  3408. @samp{my target}, similar to the search in internal links, see
  3409. @ref{Internal links}. In HTML export (@pxref{HTML export}), such a file
  3410. link will become an HTML reference to the corresponding named anchor in
  3411. the linked file.
  3412. @item *My Target
  3413. In an Org file, restrict search to headlines.
  3414. @item #my-custom-id
  3415. Link to a heading with a @code{CUSTOM_ID} property
  3416. @item /regexp/
  3417. Do a regular expression search for @code{regexp}. This uses the Emacs
  3418. command @code{occur} to list all matches in a separate window. If the
  3419. target file is in Org mode, @code{org-occur} is used to create a
  3420. sparse tree with the matches.
  3421. @c If the target file is a directory,
  3422. @c @code{grep} will be used to search all files in the directory.
  3423. @end table
  3424. As a degenerate case, a file link with an empty file name can be used
  3425. to search the current file. For example, @code{[[file:::find me]]} does
  3426. a search for @samp{find me} in the current file, just as
  3427. @samp{[[find me]]} would.
  3428. @node Custom searches
  3429. @section Custom Searches
  3430. @cindex custom search strings
  3431. @cindex search strings, custom
  3432. The default mechanism for creating search strings and for doing the
  3433. actual search related to a file link may not work correctly in all
  3434. cases. For example, Bib@TeX{} database files have many entries like
  3435. @samp{year="1993"} which would not result in good search strings,
  3436. because the only unique identification for a Bib@TeX{} entry is the
  3437. citation key.
  3438. @vindex org-create-file-search-functions
  3439. @vindex org-execute-file-search-functions
  3440. If you come across such a problem, you can write custom functions to set
  3441. the right search string for a particular file type, and to do the search
  3442. for the string in the file. Using @code{add-hook}, these functions need
  3443. to be added to the hook variables
  3444. @code{org-create-file-search-functions} and
  3445. @code{org-execute-file-search-functions}. See the docstring for these
  3446. variables for more information. Org actually uses this mechanism
  3447. for Bib@TeX{} database files, and you can use the corresponding code as
  3448. an implementation example. See the file @file{org-bibtex.el}.
  3449. @node TODO items
  3450. @chapter TODO items
  3451. @cindex TODO items
  3452. Org mode does not maintain TODO lists as separate documents@footnote{Of
  3453. course, you can make a document that contains only long lists of TODO items,
  3454. but this is not required.}. Instead, TODO items are an integral part of the
  3455. notes file, because TODO items usually come up while taking notes! With Org
  3456. mode, simply mark any entry in a tree as being a TODO item. In this way,
  3457. information is not duplicated, and the entire context from which the TODO
  3458. item emerged is always present.
  3459. Of course, this technique for managing TODO items scatters them
  3460. throughout your notes file. Org mode compensates for this by providing
  3461. methods to give you an overview of all the things that you have to do.
  3462. @menu
  3463. * TODO basics:: Marking and displaying TODO entries
  3464. * TODO extensions:: Workflow and assignments
  3465. * Progress logging:: Dates and notes for progress
  3466. * Priorities:: Some things are more important than others
  3467. * Breaking down tasks:: Splitting a task into manageable pieces
  3468. * Checkboxes:: Tick-off lists
  3469. @end menu
  3470. @node TODO basics
  3471. @section Basic TODO functionality
  3472. Any headline becomes a TODO item when it starts with the word
  3473. @samp{TODO}, for example:
  3474. @example
  3475. *** TODO Write letter to Sam Fortune
  3476. @end example
  3477. @noindent
  3478. The most important commands to work with TODO entries are:
  3479. @table @kbd
  3480. @orgcmd{C-c C-t,org-todo}
  3481. @cindex cycling, of TODO states
  3482. @vindex org-use-fast-todo-selection
  3483. Rotate the TODO state of the current item among
  3484. @example
  3485. ,-> (unmarked) -> TODO -> DONE --.
  3486. '--------------------------------'
  3487. @end example
  3488. If TODO keywords have fast access keys (see @ref{Fast access to TODO
  3489. states}), you will be prompted for a TODO keyword through the fast selection
  3490. interface; this is the default behavior when
  3491. @code{org-use-fast-todo-selection} is non-@code{nil}.
  3492. The same rotation can also be done ``remotely'' from agenda buffers with the
  3493. @kbd{t} command key (@pxref{Agenda commands}).
  3494. @orgkey{C-u C-c C-t}
  3495. When TODO keywords have no selection keys, select a specific keyword using
  3496. completion; otherwise force cycling through TODO states with no prompt. When
  3497. @code{org-use-fast-todo-selection} is set to @code{prefix}, use the fast
  3498. selection interface.
  3499. @kindex S-@key{right}
  3500. @kindex S-@key{left}
  3501. @item S-@key{right} @ @r{/} @ S-@key{left}
  3502. @vindex org-treat-S-cursor-todo-selection-as-state-change
  3503. Select the following/preceding TODO state, similar to cycling. Useful
  3504. mostly if more than two TODO states are possible (@pxref{TODO
  3505. extensions}). See also @ref{Conflicts}, for a discussion of the interaction
  3506. with @code{shift-selection-mode}. See also the variable
  3507. @code{org-treat-S-cursor-todo-selection-as-state-change}.
  3508. @orgcmd{C-c / t,org-show-todo-tree}
  3509. @cindex sparse tree, for TODO
  3510. @vindex org-todo-keywords
  3511. View TODO items in a @emph{sparse tree} (@pxref{Sparse trees}). Folds the
  3512. entire buffer, but shows all TODO items (with not-DONE state) and the
  3513. headings hierarchy above them. With a prefix argument (or by using @kbd{C-c
  3514. / T}), search for a specific TODO@. You will be prompted for the keyword,
  3515. and you can also give a list of keywords like @code{KWD1|KWD2|...} to list
  3516. entries that match any one of these keywords. With a numeric prefix argument
  3517. N, show the tree for the Nth keyword in the option @code{org-todo-keywords}.
  3518. With two prefix arguments, find all TODO states, both un-done and done.
  3519. @orgcmd{C-c a t,org-todo-list}
  3520. Show the global TODO list. Collects the TODO items (with not-DONE states)
  3521. from all agenda files (@pxref{Agenda views}) into a single buffer. The new
  3522. buffer will be in @code{agenda-mode}, which provides commands to examine and
  3523. manipulate the TODO entries from the new buffer (@pxref{Agenda commands}).
  3524. @xref{Global TODO list}, for more information.
  3525. @orgcmd{S-M-@key{RET},org-insert-todo-heading}
  3526. Insert a new TODO entry below the current one.
  3527. @end table
  3528. @noindent
  3529. @vindex org-todo-state-tags-triggers
  3530. Changing a TODO state can also trigger tag changes. See the docstring of the
  3531. option @code{org-todo-state-tags-triggers} for details.
  3532. @node TODO extensions
  3533. @section Extended use of TODO keywords
  3534. @cindex extended TODO keywords
  3535. @vindex org-todo-keywords
  3536. By default, marked TODO entries have one of only two states: TODO and
  3537. DONE@. Org mode allows you to classify TODO items in more complex ways
  3538. with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With
  3539. special setup, the TODO keyword system can work differently in different
  3540. files.
  3541. Note that @i{tags} are another way to classify headlines in general and
  3542. TODO items in particular (@pxref{Tags}).
  3543. @menu
  3544. * Workflow states:: From TODO to DONE in steps
  3545. * TODO types:: I do this, Fred does the rest
  3546. * Multiple sets in one file:: Mixing it all, and still finding your way
  3547. * Fast access to TODO states:: Single letter selection of a state
  3548. * Per-file keywords:: Different files, different requirements
  3549. * Faces for TODO keywords:: Highlighting states
  3550. * TODO dependencies:: When one task needs to wait for others
  3551. @end menu
  3552. @node Workflow states
  3553. @subsection TODO keywords as workflow states
  3554. @cindex TODO workflow
  3555. @cindex workflow states as TODO keywords
  3556. You can use TODO keywords to indicate different @emph{sequential} states
  3557. in the process of working on an item, for example@footnote{Changing
  3558. this variable only becomes effective after restarting Org mode in a
  3559. buffer.}:
  3560. @lisp
  3561. (setq org-todo-keywords
  3562. '((sequence "TODO" "FEEDBACK" "VERIFY" "|" "DONE" "DELEGATED")))
  3563. @end lisp
  3564. The vertical bar separates the TODO keywords (states that @emph{need
  3565. action}) from the DONE states (which need @emph{no further action}). If
  3566. you don't provide the separator bar, the last state is used as the DONE
  3567. state.
  3568. @cindex completion, of TODO keywords
  3569. With this setup, the command @kbd{C-c C-t} will cycle an entry from TODO
  3570. to FEEDBACK, then to VERIFY, and finally to DONE and DELEGATED@. You may
  3571. also use a numeric prefix argument to quickly select a specific state. For
  3572. example @kbd{C-3 C-c C-t} will change the state immediately to VERIFY@.
  3573. Or you can use @kbd{S-@key{left}} to go backward through the sequence. If you
  3574. define many keywords, you can use in-buffer completion
  3575. (@pxref{Completion}) or even a special one-key selection scheme
  3576. (@pxref{Fast access to TODO states}) to insert these words into the
  3577. buffer. Changing a TODO state can be logged with a timestamp, see
  3578. @ref{Tracking TODO state changes}, for more information.
  3579. @node TODO types
  3580. @subsection TODO keywords as types
  3581. @cindex TODO types
  3582. @cindex names as TODO keywords
  3583. @cindex types as TODO keywords
  3584. The second possibility is to use TODO keywords to indicate different
  3585. @emph{types} of action items. For example, you might want to indicate
  3586. that items are for ``work'' or ``home''. Or, when you work with several
  3587. people on a single project, you might want to assign action items
  3588. directly to persons, by using their names as TODO keywords. This would
  3589. be set up like this:
  3590. @lisp
  3591. (setq org-todo-keywords '((type "Fred" "Sara" "Lucy" "|" "DONE")))
  3592. @end lisp
  3593. In this case, different keywords do not indicate a sequence, but rather
  3594. different types. So the normal work flow would be to assign a task to
  3595. a person, and later to mark it DONE@. Org mode supports this style by
  3596. adapting the workings of the command @kbd{C-c C-t}@footnote{This is also true
  3597. for the @kbd{t} command in the agenda buffers.}. When used several times in
  3598. succession, it will still cycle through all names, in order to first select
  3599. the right type for a task. But when you return to the item after some time
  3600. and execute @kbd{C-c C-t} again, it will switch from any name directly to
  3601. DONE@. Use prefix arguments or completion to quickly select a specific name.
  3602. You can also review the items of a specific TODO type in a sparse tree by
  3603. using a numeric prefix to @kbd{C-c / t}. For example, to see all things Lucy
  3604. has to do, you would use @kbd{C-3 C-c / t}. To collect Lucy's items from all
  3605. agenda files into a single buffer, you would use the numeric prefix argument
  3606. as well when creating the global TODO list: @kbd{C-3 C-c a t}.
  3607. @node Multiple sets in one file
  3608. @subsection Multiple keyword sets in one file
  3609. @cindex TODO keyword sets
  3610. Sometimes you may want to use different sets of TODO keywords in
  3611. parallel. For example, you may want to have the basic
  3612. @code{TODO}/@code{DONE}, but also a workflow for bug fixing, and a
  3613. separate state indicating that an item has been canceled (so it is not
  3614. DONE, but also does not require action). Your setup would then look
  3615. like this:
  3616. @lisp
  3617. (setq org-todo-keywords
  3618. '((sequence "TODO" "|" "DONE")
  3619. (sequence "REPORT" "BUG" "KNOWNCAUSE" "|" "FIXED")
  3620. (sequence "|" "CANCELED")))
  3621. @end lisp
  3622. The keywords should all be different, this helps Org mode to keep track
  3623. of which subsequence should be used for a given entry. In this setup,
  3624. @kbd{C-c C-t} only operates within a subsequence, so it switches from
  3625. @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to
  3626. (nothing) to @code{REPORT}. Therefore you need a mechanism to initially
  3627. select the correct sequence. Besides the obvious ways like typing a
  3628. keyword or using completion, you may also apply the following commands:
  3629. @table @kbd
  3630. @kindex C-S-@key{right}
  3631. @kindex C-S-@key{left}
  3632. @kindex C-u C-u C-c C-t
  3633. @item C-u C-u C-c C-t
  3634. @itemx C-S-@key{right}
  3635. @itemx C-S-@key{left}
  3636. These keys jump from one TODO subset to the next. In the above example,
  3637. @kbd{C-u C-u C-c C-t} or @kbd{C-S-@key{right}} would jump from @code{TODO} or
  3638. @code{DONE} to @code{REPORT}, and any of the words in the second row to
  3639. @code{CANCELED}. Note that the @kbd{C-S-} key binding conflict with
  3640. @code{shift-selection-mode} (@pxref{Conflicts}).
  3641. @kindex S-@key{right}
  3642. @kindex S-@key{left}
  3643. @item S-@key{right}
  3644. @itemx S-@key{left}
  3645. @kbd{S-@key{left}} and @kbd{S-@key{right}} and walk through @emph{all}
  3646. keywords from all sets, so for example @kbd{S-@key{right}} would switch
  3647. from @code{DONE} to @code{REPORT} in the example above. See also
  3648. @ref{Conflicts}, for a discussion of the interaction with
  3649. @code{shift-selection-mode}.
  3650. @end table
  3651. @node Fast access to TODO states
  3652. @subsection Fast access to TODO states
  3653. If you would like to quickly change an entry to an arbitrary TODO state
  3654. instead of cycling through the states, you can set up keys for single-letter
  3655. access to the states. This is done by adding the selection character after
  3656. each keyword, in parentheses@footnote{All characters are allowed except
  3657. @code{@@^!}, which have a special meaning here.}. For example:
  3658. @lisp
  3659. (setq org-todo-keywords
  3660. '((sequence "TODO(t)" "|" "DONE(d)")
  3661. (sequence "REPORT(r)" "BUG(b)" "KNOWNCAUSE(k)" "|" "FIXED(f)")
  3662. (sequence "|" "CANCELED(c)")))
  3663. @end lisp
  3664. @vindex org-fast-tag-selection-include-todo
  3665. If you then press @kbd{C-c C-t} followed by the selection key, the entry
  3666. will be switched to this state. @kbd{SPC} can be used to remove any TODO
  3667. keyword from an entry.@footnote{Check also the option
  3668. @code{org-fast-tag-selection-include-todo}, it allows you to change the TODO
  3669. state through the tags interface (@pxref{Setting tags}), in case you like to
  3670. mingle the two concepts. Note that this means you need to come up with
  3671. unique keys across both sets of keywords.}
  3672. @node Per-file keywords
  3673. @subsection Setting up keywords for individual files
  3674. @cindex keyword options
  3675. @cindex per-file keywords
  3676. @cindex #+TODO
  3677. @cindex #+TYP_TODO
  3678. @cindex #+SEQ_TODO
  3679. It can be very useful to use different aspects of the TODO mechanism in
  3680. different files. For file-local settings, you need to add special lines to
  3681. the file which set the keywords and interpretation for that file only. For
  3682. example, to set one of the two examples discussed above, you need one of the
  3683. following lines anywhere in the file:
  3684. @example
  3685. #+TODO: TODO FEEDBACK VERIFY | DONE CANCELED
  3686. @end example
  3687. @noindent (you may also write @code{#+SEQ_TODO} to be explicit about the
  3688. interpretation, but it means the same as @code{#+TODO}), or
  3689. @example
  3690. #+TYP_TODO: Fred Sara Lucy Mike | DONE
  3691. @end example
  3692. A setup for using several sets in parallel would be:
  3693. @example
  3694. #+TODO: TODO | DONE
  3695. #+TODO: REPORT BUG KNOWNCAUSE | FIXED
  3696. #+TODO: | CANCELED
  3697. @end example
  3698. @cindex completion, of option keywords
  3699. @kindex M-@key{TAB}
  3700. @noindent To make sure you are using the correct keyword, type
  3701. @samp{#+} into the buffer and then use @kbd{M-@key{TAB}} completion.
  3702. @cindex DONE, final TODO keyword
  3703. Remember that the keywords after the vertical bar (or the last keyword
  3704. if no bar is there) must always mean that the item is DONE (although you
  3705. may use a different word). After changing one of these lines, use
  3706. @kbd{C-c C-c} with the cursor still in the line to make the changes
  3707. known to Org mode@footnote{Org mode parses these lines only when
  3708. Org mode is activated after visiting a file. @kbd{C-c C-c} with the
  3709. cursor in a line starting with @samp{#+} is simply restarting Org mode
  3710. for the current buffer.}.
  3711. @node Faces for TODO keywords
  3712. @subsection Faces for TODO keywords
  3713. @cindex faces, for TODO keywords
  3714. @vindex org-todo @r{(face)}
  3715. @vindex org-done @r{(face)}
  3716. @vindex org-todo-keyword-faces
  3717. Org mode highlights TODO keywords with special faces: @code{org-todo}
  3718. for keywords indicating that an item still has to be acted upon, and
  3719. @code{org-done} for keywords indicating that an item is finished. If
  3720. you are using more than 2 different states, you might want to use
  3721. special faces for some of them. This can be done using the option
  3722. @code{org-todo-keyword-faces}. For example:
  3723. @lisp
  3724. @group
  3725. (setq org-todo-keyword-faces
  3726. '(("TODO" . org-warning) ("STARTED" . "yellow")
  3727. ("CANCELED" . (:foreground "blue" :weight bold))))
  3728. @end group
  3729. @end lisp
  3730. While using a list with face properties as shown for CANCELED @emph{should}
  3731. work, this does not always seem to be the case. If necessary, define a
  3732. special face and use that. A string is interpreted as a color. The option
  3733. @code{org-faces-easy-properties} determines if that color is interpreted as a
  3734. foreground or a background color.
  3735. @node TODO dependencies
  3736. @subsection TODO dependencies
  3737. @cindex TODO dependencies
  3738. @cindex dependencies, of TODO states
  3739. @cindex TODO dependencies, NOBLOCKING
  3740. @vindex org-enforce-todo-dependencies
  3741. @cindex property, ORDERED
  3742. The structure of Org files (hierarchy and lists) makes it easy to define TODO
  3743. dependencies. Usually, a parent TODO task should not be marked DONE until
  3744. all subtasks (defined as children tasks) are marked as DONE@. And sometimes
  3745. there is a logical sequence to a number of (sub)tasks, so that one task
  3746. cannot be acted upon before all siblings above it are done. If you customize
  3747. the option @code{org-enforce-todo-dependencies}, Org will block entries
  3748. from changing state to DONE while they have children that are not DONE@.
  3749. Furthermore, if an entry has a property @code{ORDERED}, each of its children
  3750. will be blocked until all earlier siblings are marked DONE@. Here is an
  3751. example:
  3752. @example
  3753. * TODO Blocked until (two) is done
  3754. ** DONE one
  3755. ** TODO two
  3756. * Parent
  3757. :PROPERTIES:
  3758. :ORDERED: t
  3759. :END:
  3760. ** TODO a
  3761. ** TODO b, needs to wait for (a)
  3762. ** TODO c, needs to wait for (a) and (b)
  3763. @end example
  3764. You can ensure an entry is never blocked by using the @code{NOBLOCKING}
  3765. property:
  3766. @example
  3767. * This entry is never blocked
  3768. :PROPERTIES:
  3769. :NOBLOCKING: t
  3770. :END:
  3771. @end example
  3772. @table @kbd
  3773. @orgcmd{C-c C-x o,org-toggle-ordered-property}
  3774. @vindex org-track-ordered-property-with-tag
  3775. @cindex property, ORDERED
  3776. Toggle the @code{ORDERED} property of the current entry. A property is used
  3777. for this behavior because this should be local to the current entry, not
  3778. inherited like a tag. However, if you would like to @i{track} the value of
  3779. this property with a tag for better visibility, customize the option
  3780. @code{org-track-ordered-property-with-tag}.
  3781. @orgkey{C-u C-u C-u C-c C-t}
  3782. Change TODO state, circumventing any state blocking.
  3783. @end table
  3784. @vindex org-agenda-dim-blocked-tasks
  3785. If you set the option @code{org-agenda-dim-blocked-tasks}, TODO entries
  3786. that cannot be closed because of such dependencies will be shown in a dimmed
  3787. font or even made invisible in agenda views (@pxref{Agenda views}).
  3788. @cindex checkboxes and TODO dependencies
  3789. @vindex org-enforce-todo-dependencies
  3790. You can also block changes of TODO states by looking at checkboxes
  3791. (@pxref{Checkboxes}). If you set the option
  3792. @code{org-enforce-todo-checkbox-dependencies}, an entry that has unchecked
  3793. checkboxes will be blocked from switching to DONE.
  3794. If you need more complex dependency structures, for example dependencies
  3795. between entries in different trees or files, check out the contributed
  3796. module @file{org-depend.el}.
  3797. @page
  3798. @node Progress logging
  3799. @section Progress logging
  3800. @cindex progress logging
  3801. @cindex logging, of progress
  3802. Org mode can automatically record a timestamp and possibly a note when
  3803. you mark a TODO item as DONE, or even each time you change the state of
  3804. a TODO item. This system is highly configurable; settings can be on a
  3805. per-keyword basis and can be localized to a file or even a subtree. For
  3806. information on how to clock working time for a task, see @ref{Clocking
  3807. work time}.
  3808. @menu
  3809. * Closing items:: When was this entry marked DONE?
  3810. * Tracking TODO state changes:: When did the status change?
  3811. * Tracking your habits:: How consistent have you been?
  3812. @end menu
  3813. @node Closing items
  3814. @subsection Closing items
  3815. The most basic logging is to keep track of @emph{when} a certain TODO
  3816. item was finished. This is achieved with@footnote{The corresponding
  3817. in-buffer setting is: @code{#+STARTUP: logdone}}
  3818. @lisp
  3819. (setq org-log-done 'time)
  3820. @end lisp
  3821. @vindex org-closed-keep-when-no-todo
  3822. @noindent
  3823. Then each time you turn an entry from a TODO (not-done) state into any of the
  3824. DONE states, a line @samp{CLOSED: [timestamp]} will be inserted just after
  3825. the headline. If you turn the entry back into a TODO item through further
  3826. state cycling, that line will be removed again. If you turn the entry back
  3827. to a non-TODO state (by pressing @key{C-c C-t SPC} for example), that line
  3828. will also be removed, unless you set @code{org-closed-keep-when-no-todo} to
  3829. non-@code{nil}. If you want to record a note along with the timestamp,
  3830. use@footnote{The corresponding in-buffer setting is: @code{#+STARTUP:
  3831. lognotedone}.}
  3832. @lisp
  3833. (setq org-log-done 'note)
  3834. @end lisp
  3835. @noindent
  3836. You will then be prompted for a note, and that note will be stored below
  3837. the entry with a @samp{Closing Note} heading.
  3838. @node Tracking TODO state changes
  3839. @subsection Tracking TODO state changes
  3840. @cindex drawer, for state change recording
  3841. @vindex org-log-states-order-reversed
  3842. @vindex org-log-into-drawer
  3843. @cindex property, LOG_INTO_DRAWER
  3844. When TODO keywords are used as workflow states (@pxref{Workflow states}), you
  3845. might want to keep track of when a state change occurred and maybe take a
  3846. note about this change. You can either record just a timestamp, or a
  3847. time-stamped note for a change. These records will be inserted after the
  3848. headline as an itemized list, newest first@footnote{See the option
  3849. @code{org-log-states-order-reversed}}. When taking a lot of notes, you might
  3850. want to get the notes out of the way into a drawer (@pxref{Drawers}).
  3851. Customize @code{org-log-into-drawer} to get this behavior---the recommended
  3852. drawer for this is called @code{LOGBOOK}@footnote{Note that the
  3853. @code{LOGBOOK} drawer is unfolded when pressing @key{SPC} in the agenda to
  3854. show an entry---use @key{C-u SPC} to keep it folded here}. You can also
  3855. overrule the setting of this variable for a subtree by setting a
  3856. @code{LOG_INTO_DRAWER} property.
  3857. Since it is normally too much to record a note for every state, Org mode
  3858. expects configuration on a per-keyword basis for this. This is achieved by
  3859. adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note
  3860. with timestamp) in parentheses after each keyword. For example, with the
  3861. setting
  3862. @lisp
  3863. (setq org-todo-keywords
  3864. '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)")))
  3865. @end lisp
  3866. To record a timestamp without a note for TODO keywords configured with
  3867. @samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted.
  3868. @noindent
  3869. @vindex org-log-done
  3870. You not only define global TODO keywords and fast access keys, but also
  3871. request that a time is recorded when the entry is set to
  3872. DONE@footnote{It is possible that Org mode will record two timestamps
  3873. when you are using both @code{org-log-done} and state change logging.
  3874. However, it will never prompt for two notes---if you have configured
  3875. both, the state change recording note will take precedence and cancel
  3876. the @samp{Closing Note}.}, and that a note is recorded when switching to
  3877. WAIT or CANCELED@. The setting for WAIT is even more special: the
  3878. @samp{!} after the slash means that in addition to the note taken when
  3879. entering the state, a timestamp should be recorded when @i{leaving} the
  3880. WAIT state, if and only if the @i{target} state does not configure
  3881. logging for entering it. So it has no effect when switching from WAIT
  3882. to DONE, because DONE is configured to record a timestamp only. But
  3883. when switching from WAIT back to TODO, the @samp{/!} in the WAIT
  3884. setting now triggers a timestamp even though TODO has no logging
  3885. configured.
  3886. You can use the exact same syntax for setting logging preferences local
  3887. to a buffer:
  3888. @example
  3889. #+TODO: TODO(t) WAIT(w@@/!) | DONE(d!) CANCELED(c@@)
  3890. @end example
  3891. @cindex property, LOGGING
  3892. In order to define logging settings that are local to a subtree or a
  3893. single item, define a LOGGING property in this entry. Any non-empty
  3894. LOGGING property resets all logging settings to @code{nil}. You may then turn
  3895. on logging for this specific tree using STARTUP keywords like
  3896. @code{lognotedone} or @code{logrepeat}, as well as adding state specific
  3897. settings like @code{TODO(!)}. For example
  3898. @example
  3899. * TODO Log each state with only a time
  3900. :PROPERTIES:
  3901. :LOGGING: TODO(!) WAIT(!) DONE(!) CANCELED(!)
  3902. :END:
  3903. * TODO Only log when switching to WAIT, and when repeating
  3904. :PROPERTIES:
  3905. :LOGGING: WAIT(@@) logrepeat
  3906. :END:
  3907. * TODO No logging at all
  3908. :PROPERTIES:
  3909. :LOGGING: nil
  3910. :END:
  3911. @end example
  3912. @node Tracking your habits
  3913. @subsection Tracking your habits
  3914. @cindex habits
  3915. Org has the ability to track the consistency of a special category of TODOs,
  3916. called ``habits''. A habit has the following properties:
  3917. @enumerate
  3918. @item
  3919. You have enabled the @code{habits} module by customizing @code{org-modules}.
  3920. @item
  3921. The habit is a TODO item, with a TODO keyword representing an open state.
  3922. @item
  3923. The property @code{STYLE} is set to the value @code{habit}.
  3924. @item
  3925. The TODO has a scheduled date, usually with a @code{.+} style repeat
  3926. interval. A @code{++} style may be appropriate for habits with time
  3927. constraints, e.g., must be done on weekends, or a @code{+} style for an
  3928. unusual habit that can have a backlog, e.g., weekly reports.
  3929. @item
  3930. The TODO may also have minimum and maximum ranges specified by using the
  3931. syntax @samp{.+2d/3d}, which says that you want to do the task at least every
  3932. three days, but at most every two days.
  3933. @item
  3934. You must also have state logging for the @code{DONE} state enabled
  3935. (@pxref{Tracking TODO state changes}), in order for historical data to be
  3936. represented in the consistency graph. If it is not enabled it is not an
  3937. error, but the consistency graphs will be largely meaningless.
  3938. @end enumerate
  3939. To give you an idea of what the above rules look like in action, here's an
  3940. actual habit with some history:
  3941. @example
  3942. ** TODO Shave
  3943. SCHEDULED: <2009-10-17 Sat .+2d/4d>
  3944. :PROPERTIES:
  3945. :STYLE: habit
  3946. :LAST_REPEAT: [2009-10-19 Mon 00:36]
  3947. :END:
  3948. - State "DONE" from "TODO" [2009-10-15 Thu]
  3949. - State "DONE" from "TODO" [2009-10-12 Mon]
  3950. - State "DONE" from "TODO" [2009-10-10 Sat]
  3951. - State "DONE" from "TODO" [2009-10-04 Sun]
  3952. - State "DONE" from "TODO" [2009-10-02 Fri]
  3953. - State "DONE" from "TODO" [2009-09-29 Tue]
  3954. - State "DONE" from "TODO" [2009-09-25 Fri]
  3955. - State "DONE" from "TODO" [2009-09-19 Sat]
  3956. - State "DONE" from "TODO" [2009-09-16 Wed]
  3957. - State "DONE" from "TODO" [2009-09-12 Sat]
  3958. @end example
  3959. What this habit says is: I want to shave at most every 2 days (given by the
  3960. @code{SCHEDULED} date and repeat interval) and at least every 4 days. If
  3961. today is the 15th, then the habit first appears in the agenda on Oct 17,
  3962. after the minimum of 2 days has elapsed, and will appear overdue on Oct 19,
  3963. after four days have elapsed.
  3964. What's really useful about habits is that they are displayed along with a
  3965. consistency graph, to show how consistent you've been at getting that task
  3966. done in the past. This graph shows every day that the task was done over the
  3967. past three weeks, with colors for each day. The colors used are:
  3968. @table @code
  3969. @item Blue
  3970. If the task wasn't to be done yet on that day.
  3971. @item Green
  3972. If the task could have been done on that day.
  3973. @item Yellow
  3974. If the task was going to be overdue the next day.
  3975. @item Red
  3976. If the task was overdue on that day.
  3977. @end table
  3978. In addition to coloring each day, the day is also marked with an asterisk if
  3979. the task was actually done that day, and an exclamation mark to show where
  3980. the current day falls in the graph.
  3981. There are several configuration variables that can be used to change the way
  3982. habits are displayed in the agenda.
  3983. @table @code
  3984. @item org-habit-graph-column
  3985. The buffer column at which the consistency graph should be drawn. This will
  3986. overwrite any text in that column, so it is a good idea to keep your habits'
  3987. titles brief and to the point.
  3988. @item org-habit-preceding-days
  3989. The amount of history, in days before today, to appear in consistency graphs.
  3990. @item org-habit-following-days
  3991. The number of days after today that will appear in consistency graphs.
  3992. @item org-habit-show-habits-only-for-today
  3993. If non-@code{nil}, only show habits in today's agenda view. This is set to true by
  3994. default.
  3995. @end table
  3996. Lastly, pressing @kbd{K} in the agenda buffer will cause habits to
  3997. temporarily be disabled and they won't appear at all. Press @kbd{K} again to
  3998. bring them back. They are also subject to tag filtering, if you have habits
  3999. which should only be done in certain contexts, for example.
  4000. @node Priorities
  4001. @section Priorities
  4002. @cindex priorities
  4003. If you use Org mode extensively, you may end up with enough TODO items that
  4004. it starts to make sense to prioritize them. Prioritizing can be done by
  4005. placing a @emph{priority cookie} into the headline of a TODO item, like this
  4006. @example
  4007. *** TODO [#A] Write letter to Sam Fortune
  4008. @end example
  4009. @noindent
  4010. @vindex org-priority-faces
  4011. By default, Org mode supports three priorities: @samp{A}, @samp{B}, and
  4012. @samp{C}. @samp{A} is the highest priority. An entry without a cookie is
  4013. treated just like priority @samp{B}. Priorities make a difference only for
  4014. sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they
  4015. have no inherent meaning to Org mode. The cookies can be highlighted with
  4016. special faces by customizing @code{org-priority-faces}.
  4017. Priorities can be attached to any outline node; they do not need to be TODO
  4018. items.
  4019. @table @kbd
  4020. @item @kbd{C-c ,}
  4021. @kindex @kbd{C-c ,}
  4022. @findex org-priority
  4023. Set the priority of the current headline (@command{org-priority}). The
  4024. command prompts for a priority character @samp{A}, @samp{B} or @samp{C}.
  4025. When you press @key{SPC} instead, the priority cookie is removed from the
  4026. headline. The priorities can also be changed ``remotely'' from the agenda
  4027. buffer with the @kbd{,} command (@pxref{Agenda commands}).
  4028. @c
  4029. @orgcmdkkcc{S-@key{up},S-@key{down},org-priority-up,org-priority-down}
  4030. @vindex org-priority-start-cycle-with-default
  4031. Increase/decrease priority of current headline@footnote{See also the option
  4032. @code{org-priority-start-cycle-with-default}.}. Note that these keys are
  4033. also used to modify timestamps (@pxref{Creating timestamps}). See also
  4034. @ref{Conflicts}, for a discussion of the interaction with
  4035. @code{shift-selection-mode}.
  4036. @end table
  4037. @vindex org-highest-priority
  4038. @vindex org-lowest-priority
  4039. @vindex org-default-priority
  4040. You can change the range of allowed priorities by setting the options
  4041. @code{org-highest-priority}, @code{org-lowest-priority}, and
  4042. @code{org-default-priority}. For an individual buffer, you may set
  4043. these values (highest, lowest, default) like this (please make sure that
  4044. the highest priority is earlier in the alphabet than the lowest
  4045. priority):
  4046. @cindex #+PRIORITIES
  4047. @example
  4048. #+PRIORITIES: A C B
  4049. @end example
  4050. @node Breaking down tasks
  4051. @section Breaking tasks down into subtasks
  4052. @cindex tasks, breaking down
  4053. @cindex statistics, for TODO items
  4054. @vindex org-agenda-todo-list-sublevels
  4055. It is often advisable to break down large tasks into smaller, manageable
  4056. subtasks. You can do this by creating an outline tree below a TODO item,
  4057. with detailed subtasks on the tree@footnote{To keep subtasks out of the
  4058. global TODO list, see the @code{org-agenda-todo-list-sublevels}.}. To keep
  4059. the overview over the fraction of subtasks that are already completed, insert
  4060. either @samp{[/]} or @samp{[%]} anywhere in the headline. These cookies will
  4061. be updated each time the TODO status of a child changes, or when pressing
  4062. @kbd{C-c C-c} on the cookie. For example:
  4063. @example
  4064. * Organize Party [33%]
  4065. ** TODO Call people [1/2]
  4066. *** TODO Peter
  4067. *** DONE Sarah
  4068. ** TODO Buy food
  4069. ** DONE Talk to neighbor
  4070. @end example
  4071. @cindex property, COOKIE_DATA
  4072. If a heading has both checkboxes and TODO children below it, the meaning of
  4073. the statistics cookie become ambiguous. Set the property
  4074. @code{COOKIE_DATA} to either @samp{checkbox} or @samp{todo} to resolve
  4075. this issue.
  4076. @vindex org-hierarchical-todo-statistics
  4077. If you would like to have the statistics cookie count any TODO entries in the
  4078. subtree (not just direct children), configure
  4079. @code{org-hierarchical-todo-statistics}. To do this for a single subtree,
  4080. include the word @samp{recursive} into the value of the @code{COOKIE_DATA}
  4081. property.
  4082. @example
  4083. * Parent capturing statistics [2/20]
  4084. :PROPERTIES:
  4085. :COOKIE_DATA: todo recursive
  4086. :END:
  4087. @end example
  4088. If you would like a TODO entry to automatically change to DONE
  4089. when all children are done, you can use the following setup:
  4090. @example
  4091. (defun org-summary-todo (n-done n-not-done)
  4092. "Switch entry to DONE when all subentries are done, to TODO otherwise."
  4093. (let (org-log-done org-log-states) ; turn off logging
  4094. (org-todo (if (= n-not-done 0) "DONE" "TODO"))))
  4095. (add-hook 'org-after-todo-statistics-hook 'org-summary-todo)
  4096. @end example
  4097. Another possibility is the use of checkboxes to identify (a hierarchy of) a
  4098. large number of subtasks (@pxref{Checkboxes}).
  4099. @node Checkboxes
  4100. @section Checkboxes
  4101. @cindex checkboxes
  4102. @vindex org-list-automatic-rules
  4103. Every item in a plain list@footnote{With the exception of description
  4104. lists. But you can allow it by modifying @code{org-list-automatic-rules}
  4105. accordingly.} (@pxref{Plain lists}) can be made into a checkbox by starting
  4106. it with the string @samp{[ ]}. This feature is similar to TODO items
  4107. (@pxref{TODO items}), but is more lightweight. Checkboxes are not included
  4108. in the global TODO list, so they are often great to split a task into a
  4109. number of simple steps. Or you can use them in a shopping list. To toggle a
  4110. checkbox, use @kbd{C-c C-c}, or use the mouse (thanks to Piotr Zielinski's
  4111. @file{org-mouse.el}).
  4112. Here is an example of a checkbox list.
  4113. @example
  4114. * TODO Organize party [2/4]
  4115. - [-] call people [1/3]
  4116. - [ ] Peter
  4117. - [X] Sarah
  4118. - [ ] Sam
  4119. - [X] order food
  4120. - [ ] think about what music to play
  4121. - [X] talk to the neighbors
  4122. @end example
  4123. Checkboxes work hierarchically, so if a checkbox item has children that
  4124. are checkboxes, toggling one of the children checkboxes will make the
  4125. parent checkbox reflect if none, some, or all of the children are
  4126. checked.
  4127. @cindex statistics, for checkboxes
  4128. @cindex checkbox statistics
  4129. @cindex property, COOKIE_DATA
  4130. @vindex org-checkbox-hierarchical-statistics
  4131. The @samp{[2/4]} and @samp{[1/3]} in the first and second line are cookies
  4132. indicating how many checkboxes present in this entry have been checked off,
  4133. and the total number of checkboxes present. This can give you an idea on how
  4134. many checkboxes remain, even without opening a folded entry. The cookies can
  4135. be placed into a headline or into (the first line of) a plain list item.
  4136. Each cookie covers checkboxes of direct children structurally below the
  4137. headline/item on which the cookie appears@footnote{Set the option
  4138. @code{org-checkbox-hierarchical-statistics} if you want such cookies to
  4139. count all checkboxes below the cookie, not just those belonging to direct
  4140. children.}. You have to insert the cookie yourself by typing either
  4141. @samp{[/]} or @samp{[%]}. With @samp{[/]} you get an @samp{n out of m}
  4142. result, as in the examples above. With @samp{[%]} you get information about
  4143. the percentage of checkboxes checked (in the above example, this would be
  4144. @samp{[50%]} and @samp{[33%]}, respectively). In a headline, a cookie can
  4145. count either checkboxes below the heading or TODO states of children, and it
  4146. will display whatever was changed last. Set the property @code{COOKIE_DATA}
  4147. to either @samp{checkbox} or @samp{todo} to resolve this issue.
  4148. @cindex blocking, of checkboxes
  4149. @cindex checkbox blocking
  4150. @cindex property, ORDERED
  4151. If the current outline node has an @code{ORDERED} property, checkboxes must
  4152. be checked off in sequence, and an error will be thrown if you try to check
  4153. off a box while there are unchecked boxes above it.
  4154. @noindent The following commands work with checkboxes:
  4155. @table @kbd
  4156. @orgcmd{C-c C-c,org-toggle-checkbox}
  4157. Toggle checkbox status or (with prefix arg) checkbox presence at point. With
  4158. a single prefix argument, add an empty checkbox or remove the current
  4159. one@footnote{@kbd{C-u C-c C-c} before the @emph{first} bullet in a list with
  4160. no checkbox will add checkboxes to the rest of the list.}. With a double
  4161. prefix argument, set it to @samp{[-]}, which is considered to be an
  4162. intermediate state.
  4163. @orgcmd{C-c C-x C-b,org-toggle-checkbox}
  4164. Toggle checkbox status or (with prefix arg) checkbox presence at point. With
  4165. double prefix argument, set it to @samp{[-]}, which is considered to be an
  4166. intermediate state.
  4167. @itemize @minus
  4168. @item
  4169. If there is an active region, toggle the first checkbox in the region
  4170. and set all remaining boxes to the same status as the first. With a prefix
  4171. arg, add or remove the checkbox for all items in the region.
  4172. @item
  4173. If the cursor is in a headline, toggle the state of the first checkbox in the
  4174. region between this headline and the next---so @emph{not} the entire
  4175. subtree---and propagate this new state to all other checkboxes in the same
  4176. area.
  4177. @item
  4178. If there is no active region, just toggle the checkbox at point.
  4179. @end itemize
  4180. @orgcmd{M-S-@key{RET},org-insert-todo-heading}
  4181. Insert a new item with a checkbox. This works only if the cursor is already
  4182. in a plain list item (@pxref{Plain lists}).
  4183. @orgcmd{C-c C-x o,org-toggle-ordered-property}
  4184. @vindex org-track-ordered-property-with-tag
  4185. @cindex property, ORDERED
  4186. Toggle the @code{ORDERED} property of the entry, to toggle if checkboxes must
  4187. be checked off in sequence. A property is used for this behavior because
  4188. this should be local to the current entry, not inherited like a tag.
  4189. However, if you would like to @i{track} the value of this property with a tag
  4190. for better visibility, customize @code{org-track-ordered-property-with-tag}.
  4191. @orgcmd{C-c #,org-update-statistics-cookies}
  4192. Update the statistics cookie in the current outline entry. When called with
  4193. a @kbd{C-u} prefix, update the entire file. Checkbox statistic cookies are
  4194. updated automatically if you toggle checkboxes with @kbd{C-c C-c} and make
  4195. new ones with @kbd{M-S-@key{RET}}. TODO statistics cookies update when
  4196. changing TODO states. If you delete boxes/entries or add/change them by
  4197. hand, use this command to get things back into sync.
  4198. @end table
  4199. @node Tags
  4200. @chapter Tags
  4201. @cindex tags
  4202. @cindex headline tagging
  4203. @cindex matching, tags
  4204. @cindex sparse tree, tag based
  4205. An excellent way to implement labels and contexts for cross-correlating
  4206. information is to assign @i{tags} to headlines. Org mode has extensive
  4207. support for tags.
  4208. @vindex org-tag-faces
  4209. Every headline can contain a list of tags; they occur at the end of the
  4210. headline. Tags are normal words containing letters, numbers, @samp{_}, and
  4211. @samp{@@}. Tags must be preceded and followed by a single colon, e.g.,
  4212. @samp{:work:}. Several tags can be specified, as in @samp{:work:urgent:}.
  4213. Tags will by default be in bold face with the same color as the headline.
  4214. You may specify special faces for specific tags using the option
  4215. @code{org-tag-faces}, in much the same way as you can for TODO keywords
  4216. (@pxref{Faces for TODO keywords}).
  4217. @menu
  4218. * Tag inheritance:: Tags use the tree structure of the outline
  4219. * Setting tags:: How to assign tags to a headline
  4220. * Tag hierarchy:: Create a hierarchy of tags
  4221. * Tag searches:: Searching for combinations of tags
  4222. @end menu
  4223. @node Tag inheritance
  4224. @section Tag inheritance
  4225. @cindex tag inheritance
  4226. @cindex inheritance, of tags
  4227. @cindex sublevels, inclusion into tags match
  4228. @i{Tags} make use of the hierarchical structure of outline trees. If a
  4229. heading has a certain tag, all subheadings will inherit the tag as
  4230. well. For example, in the list
  4231. @example
  4232. * Meeting with the French group :work:
  4233. ** Summary by Frank :boss:notes:
  4234. *** TODO Prepare slides for him :action:
  4235. @end example
  4236. @noindent
  4237. the final heading will have the tags @samp{:work:}, @samp{:boss:},
  4238. @samp{:notes:}, and @samp{:action:} even though the final heading is not
  4239. explicitly marked with all those tags. You can also set tags that all
  4240. entries in a file should inherit just as if these tags were defined in
  4241. a hypothetical level zero that surrounds the entire file. Use a line like
  4242. this@footnote{As with all these in-buffer settings, pressing @kbd{C-c C-c}
  4243. activates any changes in the line.}:
  4244. @cindex #+FILETAGS
  4245. @example
  4246. #+FILETAGS: :Peter:Boss:Secret:
  4247. @end example
  4248. @noindent
  4249. @vindex org-use-tag-inheritance
  4250. @vindex org-tags-exclude-from-inheritance
  4251. To limit tag inheritance to specific tags, use @code{org-tags-exclude-from-inheritance}.
  4252. To turn it off entirely, use @code{org-use-tag-inheritance}.
  4253. @vindex org-tags-match-list-sublevels
  4254. When a headline matches during a tags search while tag inheritance is turned
  4255. on, all the sublevels in the same tree will (for a simple match form) match
  4256. as well@footnote{This is only true if the search does not involve more
  4257. complex tests including properties (@pxref{Property searches}).}. The list
  4258. of matches may then become very long. If you only want to see the first tags
  4259. match in a subtree, configure @code{org-tags-match-list-sublevels} (not
  4260. recommended).
  4261. @vindex org-agenda-use-tag-inheritance
  4262. Tag inheritance is relevant when the agenda search tries to match a tag,
  4263. either in the @code{tags} or @code{tags-todo} agenda types. In other agenda
  4264. types, @code{org-use-tag-inheritance} has no effect. Still, you may want to
  4265. have your tags correctly set in the agenda, so that tag filtering works fine,
  4266. with inherited tags. Set @code{org-agenda-use-tag-inheritance} to control
  4267. this: the default value includes all agenda types, but setting this to @code{nil}
  4268. can really speed up agenda generation.
  4269. @node Setting tags
  4270. @section Setting tags
  4271. @cindex setting tags
  4272. @cindex tags, setting
  4273. @kindex M-@key{TAB}
  4274. Tags can simply be typed into the buffer at the end of a headline.
  4275. After a colon, @kbd{M-@key{TAB}} offers completion on tags. There is
  4276. also a special command for inserting tags:
  4277. @table @kbd
  4278. @orgcmd{C-c C-q,org-set-tags-command}
  4279. @cindex completion, of tags
  4280. @vindex org-tags-column
  4281. Enter new tags for the current headline. Org mode will either offer
  4282. completion or a special single-key interface for setting tags, see
  4283. below. After pressing @key{RET}, the tags will be inserted and aligned
  4284. to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all
  4285. tags in the current buffer will be aligned to that column, just to make
  4286. things look nice. TAGS are automatically realigned after promotion,
  4287. demotion, and TODO state changes (@pxref{TODO basics}).
  4288. @orgcmd{C-c C-c,org-set-tags-command}
  4289. When the cursor is in a headline, this does the same as @kbd{C-c C-q}.
  4290. @end table
  4291. @vindex org-tag-alist
  4292. Org supports tag insertion based on a @emph{list of tags}. By
  4293. default this list is constructed dynamically, containing all tags
  4294. currently used in the buffer. You may also globally specify a hard list
  4295. of tags with the variable @code{org-tag-alist}. Finally you can set
  4296. the default tags for a given file with lines like
  4297. @cindex #+TAGS
  4298. @example
  4299. #+TAGS: @@work @@home @@tennisclub
  4300. #+TAGS: laptop car pc sailboat
  4301. @end example
  4302. If you have globally defined your preferred set of tags using the
  4303. variable @code{org-tag-alist}, but would like to use a dynamic tag list
  4304. in a specific file, add an empty TAGS option line to that file:
  4305. @example
  4306. #+TAGS:
  4307. @end example
  4308. @vindex org-tag-persistent-alist
  4309. If you have a preferred set of tags that you would like to use in every file,
  4310. in addition to those defined on a per-file basis by TAGS option lines, then
  4311. you may specify a list of tags with the variable
  4312. @code{org-tag-persistent-alist}. You may turn this off on a per-file basis
  4313. by adding a STARTUP option line to that file:
  4314. @example
  4315. #+STARTUP: noptag
  4316. @end example
  4317. By default Org mode uses the standard minibuffer completion facilities for
  4318. entering tags. However, it also implements another, quicker, tag selection
  4319. method called @emph{fast tag selection}. This allows you to select and
  4320. deselect tags with just a single key press. For this to work well you should
  4321. assign unique, case-sensitive, letters to most of your commonly used tags.
  4322. You can do this globally by configuring the variable @code{org-tag-alist} in
  4323. your Emacs init file. For example, you may find the need to tag many items
  4324. in different files with @samp{:@@home:}. In this case you can set something
  4325. like:
  4326. @lisp
  4327. (setq org-tag-alist '(("@@work" . ?w) ("@@home" . ?h) ("laptop" . ?l)))
  4328. @end lisp
  4329. @noindent If the tag is only relevant to the file you are working on, then you
  4330. can instead set the TAGS option line as:
  4331. @example
  4332. #+TAGS: @@work(w) @@home(h) @@tennisclub(t) laptop(l) pc(p)
  4333. @end example
  4334. @noindent The tags interface will show the available tags in a splash
  4335. window. If you want to start a new line after a specific tag, insert
  4336. @samp{\n} into the tag list
  4337. @example
  4338. #+TAGS: @@work(w) @@home(h) @@tennisclub(t) \n laptop(l) pc(p)
  4339. @end example
  4340. @noindent or write them in two lines:
  4341. @example
  4342. #+TAGS: @@work(w) @@home(h) @@tennisclub(t)
  4343. #+TAGS: laptop(l) pc(p)
  4344. @end example
  4345. @noindent
  4346. You can also group together tags that are mutually exclusive by using
  4347. braces, as in:
  4348. @example
  4349. #+TAGS: @{ @@work(w) @@home(h) @@tennisclub(t) @} laptop(l) pc(p)
  4350. @end example
  4351. @noindent you indicate that at most one of @samp{@@work}, @samp{@@home},
  4352. and @samp{@@tennisclub} should be selected. Multiple such groups are allowed.
  4353. @noindent Don't forget to press @kbd{C-c C-c} with the cursor in one of
  4354. these lines to activate any changes.
  4355. @noindent
  4356. To set these mutually exclusive groups in the variable @code{org-tag-alist},
  4357. you must use the dummy tags @code{:startgroup} and @code{:endgroup} instead
  4358. of the braces. Similarly, you can use @code{:newline} to indicate a line
  4359. break. The previous example would be set globally by the following
  4360. configuration:
  4361. @lisp
  4362. (setq org-tag-alist '((:startgroup . nil)
  4363. ("@@work" . ?w) ("@@home" . ?h)
  4364. ("@@tennisclub" . ?t)
  4365. (:endgroup . nil)
  4366. ("laptop" . ?l) ("pc" . ?p)))
  4367. @end lisp
  4368. If at least one tag has a selection key then pressing @kbd{C-c C-c} will
  4369. automatically present you with a special interface, listing inherited tags,
  4370. the tags of the current headline, and a list of all valid tags with
  4371. corresponding keys@footnote{Keys will automatically be assigned to tags which
  4372. have no configured keys.}.
  4373. Pressing keys assigned to tags will add or remove them from the list of tags
  4374. in the current line. Selecting a tag in a group of mutually exclusive tags
  4375. will turn off any other tags from that group.
  4376. In this interface, you can also use the following special keys:
  4377. @table @kbd
  4378. @kindex @key{TAB}
  4379. @item @key{TAB}
  4380. Enter a tag in the minibuffer, even if the tag is not in the predefined
  4381. list. You will be able to complete on all tags present in the buffer.
  4382. You can also add several tags: just separate them with a comma.
  4383. @kindex @key{SPC}
  4384. @item @key{SPC}
  4385. Clear all tags for this line.
  4386. @kindex @key{RET}
  4387. @item @key{RET}
  4388. Accept the modified set.
  4389. @item C-g
  4390. Abort without installing changes.
  4391. @item q
  4392. If @kbd{q} is not assigned to a tag, it aborts like @kbd{C-g}.
  4393. @item !
  4394. Turn off groups of mutually exclusive tags. Use this to (as an
  4395. exception) assign several tags from such a group.
  4396. @item C-c
  4397. Toggle auto-exit after the next change (see below).
  4398. If you are using expert mode, the first @kbd{C-c} will display the
  4399. selection window.
  4400. @end table
  4401. @noindent
  4402. This method lets you assign tags to a headline with very few keys. With
  4403. the above setup, you could clear the current tags and set @samp{@@home},
  4404. @samp{laptop} and @samp{pc} tags with just the following keys: @kbd{C-c
  4405. C-c @key{SPC} h l p @key{RET}}. Switching from @samp{@@home} to
  4406. @samp{@@work} would be done with @kbd{C-c C-c w @key{RET}} or
  4407. alternatively with @kbd{C-c C-c C-c w}. Adding the non-predefined tag
  4408. @samp{Sarah} could be done with @kbd{C-c C-c @key{TAB} S a r a h
  4409. @key{RET} @key{RET}}.
  4410. @vindex org-fast-tag-selection-single-key
  4411. If you find that most of the time you need only a single key press to
  4412. modify your list of tags, set @code{org-fast-tag-selection-single-key}.
  4413. Then you no longer have to press @key{RET} to exit fast tag selection---it
  4414. will immediately exit after the first change. If you then occasionally
  4415. need more keys, press @kbd{C-c} to turn off auto-exit for the current tag
  4416. selection process (in effect: start selection with @kbd{C-c C-c C-c}
  4417. instead of @kbd{C-c C-c}). If you set the variable to the value
  4418. @code{expert}, the special window is not even shown for single-key tag
  4419. selection, it comes up only when you press an extra @kbd{C-c}.
  4420. @node Tag hierarchy
  4421. @section Tag hierarchy
  4422. @cindex group tags
  4423. @cindex tags, groups
  4424. @cindex tag hierarchy
  4425. Tags can be defined in hierarchies. A tag can be defined as a @emph{group
  4426. tag} for a set of other tags. The group tag can be seen as the ``broader
  4427. term'' for its set of tags. Defining multiple @emph{group tags} and nesting
  4428. them creates a tag hierarchy.
  4429. One use-case is to create a taxonomy of terms (tags) that can be used to
  4430. classify nodes in a document or set of documents.
  4431. When you search for a group tag, it will return matches for all members in
  4432. the group and its subgroups. In an agenda view, filtering by a group tag
  4433. will display or hide headlines tagged with at least one of the members of the
  4434. group or any of its subgroups. This makes tag searches and filters even more
  4435. flexible.
  4436. You can set group tags by using brackets and inserting a colon between the
  4437. group tag and its related tags---beware that all whitespaces are mandatory so
  4438. that Org can parse this line correctly:
  4439. @example
  4440. #+TAGS: [ GTD : Control Persp ]
  4441. @end example
  4442. In this example, @samp{GTD} is the @emph{group tag} and it is related to two
  4443. other tags: @samp{Control}, @samp{Persp}. Defining @samp{Control} and
  4444. @samp{Persp} as group tags creates an hierarchy of tags:
  4445. @example
  4446. #+TAGS: [ Control : Context Task ]
  4447. #+TAGS: [ Persp : Vision Goal AOF Project ]
  4448. @end example
  4449. That can conceptually be seen as a hierarchy of tags:
  4450. @example
  4451. - GTD
  4452. - Persp
  4453. - Vision
  4454. - Goal
  4455. - AOF
  4456. - Project
  4457. - Control
  4458. - Context
  4459. - Task
  4460. @end example
  4461. You can use the @code{:startgrouptag}, @code{:grouptags} and
  4462. @code{:endgrouptag} keyword directly when setting @code{org-tag-alist}
  4463. directly:
  4464. @lisp
  4465. (setq org-tag-alist '((:startgrouptag)
  4466. ("GTD")
  4467. (:grouptags)
  4468. ("Control")
  4469. ("Persp")
  4470. (:endgrouptag)
  4471. (:startgrouptag)
  4472. ("Control")
  4473. (:grouptags)
  4474. ("Context")
  4475. ("Task")
  4476. (:endgrouptag)))
  4477. @end lisp
  4478. The tags in a group can be mutually exclusive if using the same group syntax
  4479. as is used for grouping mutually exclusive tags together; using curly
  4480. brackets.
  4481. @example
  4482. #+TAGS: @{ Context : @@Home @@Work @@Call @}
  4483. @end example
  4484. When setting @code{org-tag-alist} you can use @code{:startgroup} &
  4485. @code{:endgroup} instead of @code{:startgrouptag} & @code{:endgrouptag} to
  4486. make the tags mutually exclusive.
  4487. Furthermore, the members of a @emph{group tag} can also be regular
  4488. expressions, creating the possibility of a more dynamic and rule-based
  4489. tag structure. The regular expressions in the group must be specified
  4490. within @{ @}. Here is an expanded example:
  4491. @example
  4492. #+TAGS: [ Vision : @{V@@@.+@} ]
  4493. #+TAGS: [ Goal : @{G@@@.+@} ]
  4494. #+TAGS: [ AOF : @{AOF@@@.+@} ]
  4495. #+TAGS: [ Project : @{P@@@.+@} ]
  4496. @end example
  4497. Searching for the tag @samp{Project} will now list all tags also including
  4498. regular expression matches for @samp{P@@@.+}, and similarly for tag searches on
  4499. @samp{Vision}, @samp{Goal} and @samp{AOF}. For example, this would work well
  4500. for a project tagged with a common project-identifier, e.g. @samp{P@@2014_OrgTags}.
  4501. @kindex C-c C-x q
  4502. @vindex org-group-tags
  4503. If you want to ignore group tags temporarily, toggle group tags support
  4504. with @command{org-toggle-tags-groups}, bound to @kbd{C-c C-x q}. If you
  4505. want to disable tag groups completely, set @code{org-group-tags} to @code{nil}.
  4506. @node Tag searches
  4507. @section Tag searches
  4508. @cindex tag searches
  4509. @cindex searching for tags
  4510. Once a system of tags has been set up, it can be used to collect related
  4511. information into special lists.
  4512. @table @kbd
  4513. @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
  4514. Create a sparse tree with all headlines matching a tags/property/TODO search.
  4515. With a @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
  4516. @xref{Matching tags and properties}.
  4517. @orgcmd{C-c a m,org-tags-view}
  4518. Create a global list of tag matches from all agenda files. @xref{Matching
  4519. tags and properties}.
  4520. @orgcmd{C-c a M,org-tags-view}
  4521. @vindex org-tags-match-list-sublevels
  4522. Create a global list of tag matches from all agenda files, but check
  4523. only TODO items and force checking subitems (see the option
  4524. @code{org-tags-match-list-sublevels}).
  4525. @end table
  4526. These commands all prompt for a match string which allows basic Boolean logic
  4527. like @samp{+boss+urgent-project1}, to find entries with tags @samp{boss} and
  4528. @samp{urgent}, but not @samp{project1}, or @samp{Kathy|Sally} to find entries
  4529. tagged as @samp{Kathy} or @samp{Sally}. The full syntax of the search string
  4530. is rich and allows also matching against TODO keywords, entry levels and
  4531. properties. For a complete description with many examples, see @ref{Matching
  4532. tags and properties}.
  4533. @node Properties and columns
  4534. @chapter Properties and columns
  4535. @cindex properties
  4536. A property is a key-value pair associated with an entry. Properties can be
  4537. set so they are associated with a single entry, with every entry in a tree,
  4538. or with every entry in an Org mode file.
  4539. There are two main applications for properties in Org mode. First,
  4540. properties are like tags, but with a value. Imagine maintaining a file where
  4541. you document bugs and plan releases for a piece of software. Instead of
  4542. using tags like @code{:release_1:}, @code{:release_2:}, you can use a
  4543. property, say @code{:Release:}, that in different subtrees has different
  4544. values, such as @code{1.0} or @code{2.0}. Second, you can use properties to
  4545. implement (very basic) database capabilities in an Org buffer. Imagine
  4546. keeping track of your music CDs, where properties could be things such as the
  4547. album, artist, date of release, number of tracks, and so on.
  4548. Properties can be conveniently edited and viewed in column view
  4549. (@pxref{Column view}).
  4550. @menu
  4551. * Property syntax:: How properties are spelled out
  4552. * Special properties:: Access to other Org mode features
  4553. * Property searches:: Matching property values
  4554. * Property inheritance:: Passing values down the tree
  4555. * Column view:: Tabular viewing and editing
  4556. * Property API:: Properties for Lisp programmers
  4557. @end menu
  4558. @node Property syntax
  4559. @section Property syntax
  4560. @cindex property syntax
  4561. @cindex drawer, for properties
  4562. Properties are key-value pairs. When they are associated with a single entry
  4563. or with a tree they need to be inserted into a special drawer
  4564. (@pxref{Drawers}) with the name @code{PROPERTIES}, which has to be located
  4565. right below a headline, and its planning line (@pxref{Deadlines and
  4566. scheduling}) when applicable. Each property is specified on a single line,
  4567. with the key (surrounded by colons) first, and the value after it. Keys are
  4568. case-insensitive. Here is an example:
  4569. @example
  4570. * CD collection
  4571. ** Classic
  4572. *** Goldberg Variations
  4573. :PROPERTIES:
  4574. :Title: Goldberg Variations
  4575. :Composer: J.S. Bach
  4576. :Artist: Glen Gould
  4577. :Publisher: Deutsche Grammophon
  4578. :NDisks: 1
  4579. :END:
  4580. @end example
  4581. Depending on the value of @code{org-use-property-inheritance}, a property set
  4582. this way will either be associated with a single entry, or the subtree
  4583. defined by the entry, see @ref{Property inheritance}.
  4584. You may define the allowed values for a particular property @samp{:Xyz:}
  4585. by setting a property @samp{:Xyz_ALL:}. This special property is
  4586. @emph{inherited}, so if you set it in a level 1 entry, it will apply to
  4587. the entire tree. When allowed values are defined, setting the
  4588. corresponding property becomes easier and is less prone to typing
  4589. errors. For the example with the CD collection, we can predefine
  4590. publishers and the number of disks in a box like this:
  4591. @example
  4592. * CD collection
  4593. :PROPERTIES:
  4594. :NDisks_ALL: 1 2 3 4
  4595. :Publisher_ALL: "Deutsche Grammophon" Philips EMI
  4596. :END:
  4597. @end example
  4598. If you want to set properties that can be inherited by any entry in a
  4599. file, use a line like
  4600. @cindex property, _ALL
  4601. @cindex #+PROPERTY
  4602. @example
  4603. #+PROPERTY: NDisks_ALL 1 2 3 4
  4604. @end example
  4605. Contrary to properties set from a special drawer, you have to refresh the
  4606. buffer with @kbd{C-c C-c} to activate this change.
  4607. If you want to add to the value of an existing property, append a @code{+} to
  4608. the property name. The following results in the property @code{var} having
  4609. the value ``foo=1 bar=2''.
  4610. @cindex property, +
  4611. @example
  4612. #+PROPERTY: var foo=1
  4613. #+PROPERTY: var+ bar=2
  4614. @end example
  4615. It is also possible to add to the values of inherited properties. The
  4616. following results in the @code{genres} property having the value ``Classic
  4617. Baroque'' under the @code{Goldberg Variations} subtree.
  4618. @cindex property, +
  4619. @example
  4620. * CD collection
  4621. ** Classic
  4622. :PROPERTIES:
  4623. :GENRES: Classic
  4624. :END:
  4625. *** Goldberg Variations
  4626. :PROPERTIES:
  4627. :Title: Goldberg Variations
  4628. :Composer: J.S. Bach
  4629. :Artist: Glen Gould
  4630. :Publisher: Deutsche Grammophon
  4631. :NDisks: 1
  4632. :GENRES+: Baroque
  4633. :END:
  4634. @end example
  4635. Note that a property can only have one entry per Drawer.
  4636. @vindex org-global-properties
  4637. Property values set with the global variable
  4638. @code{org-global-properties} can be inherited by all entries in all
  4639. Org files.
  4640. @noindent
  4641. The following commands help to work with properties:
  4642. @table @kbd
  4643. @orgcmd{M-@key{TAB},pcomplete}
  4644. After an initial colon in a line, complete property keys. All keys used
  4645. in the current file will be offered as possible completions.
  4646. @orgcmd{C-c C-x p,org-set-property}
  4647. Set a property. This prompts for a property name and a value. If
  4648. necessary, the property drawer is created as well.
  4649. @item C-u M-x org-insert-drawer RET
  4650. @cindex org-insert-drawer
  4651. Insert a property drawer into the current entry. The drawer will be
  4652. inserted early in the entry, but after the lines with planning
  4653. information like deadlines.
  4654. @orgcmd{C-c C-c,org-property-action}
  4655. With the cursor in a property drawer, this executes property commands.
  4656. @orgcmd{C-c C-c s,org-set-property}
  4657. Set a property in the current entry. Both the property and the value
  4658. can be inserted using completion.
  4659. @orgcmdkkcc{S-@key{right},S-@key{left},org-property-next-allowed-value,org-property-previous-allowed-value}
  4660. Switch property at point to the next/previous allowed value.
  4661. @orgcmd{C-c C-c d,org-delete-property}
  4662. Remove a property from the current entry.
  4663. @orgcmd{C-c C-c D,org-delete-property-globally}
  4664. Globally remove a property, from all entries in the current file.
  4665. @orgcmd{C-c C-c c,org-compute-property-at-point}
  4666. Compute the property at point, using the operator and scope from the
  4667. nearest column format definition.
  4668. @end table
  4669. @node Special properties
  4670. @section Special properties
  4671. @cindex properties, special
  4672. Special properties provide an alternative access method to Org mode features,
  4673. like the TODO state or the priority of an entry, discussed in the previous
  4674. chapters. This interface exists so that you can include these states in
  4675. a column view (@pxref{Column view}), or to use them in queries. The
  4676. following property names are special and should not be used as keys in the
  4677. properties drawer:
  4678. @cindex property, special, ALLTAGS
  4679. @cindex property, special, BLOCKED
  4680. @cindex property, special, CLOCKSUM
  4681. @cindex property, special, CLOCKSUM_T
  4682. @cindex property, special, CLOSED
  4683. @cindex property, special, DEADLINE
  4684. @cindex property, special, FILE
  4685. @cindex property, special, ITEM
  4686. @cindex property, special, PRIORITY
  4687. @cindex property, special, SCHEDULED
  4688. @cindex property, special, TAGS
  4689. @cindex property, special, TIMESTAMP
  4690. @cindex property, special, TIMESTAMP_IA
  4691. @cindex property, special, TODO
  4692. @example
  4693. ALLTAGS @r{All tags, including inherited ones.}
  4694. BLOCKED @r{"t" if task is currently blocked by children or siblings.}
  4695. CLOCKSUM @r{The sum of CLOCK intervals in the subtree. @code{org-clock-sum}}
  4696. @r{must be run first to compute the values in the current buffer.}
  4697. CLOCKSUM_T @r{The sum of CLOCK intervals in the subtree for today.}
  4698. @r{@code{org-clock-sum-today} must be run first to compute the}
  4699. @r{values in the current buffer.}
  4700. CLOSED @r{When was this entry closed?}
  4701. DEADLINE @r{The deadline time string, without the angular brackets.}
  4702. FILE @r{The filename the entry is located in.}
  4703. ITEM @r{The headline of the entry.}
  4704. PRIORITY @r{The priority of the entry, a string with a single letter.}
  4705. SCHEDULED @r{The scheduling timestamp, without the angular brackets.}
  4706. TAGS @r{The tags defined directly in the headline.}
  4707. TIMESTAMP @r{The first keyword-less timestamp in the entry.}
  4708. TIMESTAMP_IA @r{The first inactive timestamp in the entry.}
  4709. TODO @r{The TODO keyword of the entry.}
  4710. @end example
  4711. @node Property searches
  4712. @section Property searches
  4713. @cindex properties, searching
  4714. @cindex searching, of properties
  4715. To create sparse trees and special lists with selection based on properties,
  4716. the same commands are used as for tag searches (@pxref{Tag searches}).
  4717. @table @kbd
  4718. @orgcmdkkc{C-c / m,C-c \\,org-match-sparse-tree}
  4719. Create a sparse tree with all matching entries. With a
  4720. @kbd{C-u} prefix argument, ignore headlines that are not a TODO line.
  4721. @orgcmd{C-c a m,org-tags-view}
  4722. Create a global list of tag/property matches from all agenda files.
  4723. @xref{Matching tags and properties}.
  4724. @orgcmd{C-c a M,org-tags-view}
  4725. @vindex org-tags-match-list-sublevels
  4726. Create a global list of tag matches from all agenda files, but check
  4727. only TODO items and force checking of subitems (see the option
  4728. @code{org-tags-match-list-sublevels}).
  4729. @end table
  4730. The syntax for the search string is described in @ref{Matching tags and
  4731. properties}.
  4732. There is also a special command for creating sparse trees based on a
  4733. single property:
  4734. @table @kbd
  4735. @orgkey{C-c / p}
  4736. Create a sparse tree based on the value of a property. This first
  4737. prompts for the name of a property, and then for a value. A sparse tree
  4738. is created with all entries that define this property with the given
  4739. value. If you enclose the value in curly braces, it is interpreted as
  4740. a regular expression and matched against the property values.
  4741. @end table
  4742. @node Property inheritance
  4743. @section Property Inheritance
  4744. @cindex properties, inheritance
  4745. @cindex inheritance, of properties
  4746. @vindex org-use-property-inheritance
  4747. The outline structure of Org mode documents lends itself to an
  4748. inheritance model of properties: if the parent in a tree has a certain
  4749. property, the children can inherit this property. Org mode does not
  4750. turn this on by default, because it can slow down property searches
  4751. significantly and is often not needed. However, if you find inheritance
  4752. useful, you can turn it on by setting the variable
  4753. @code{org-use-property-inheritance}. It may be set to @code{t} to make
  4754. all properties inherited from the parent, to a list of properties
  4755. that should be inherited, or to a regular expression that matches
  4756. inherited properties. If a property has the value @code{nil}, this is
  4757. interpreted as an explicit undefine of the property, so that inheritance
  4758. search will stop at this value and return @code{nil}.
  4759. Org mode has a few properties for which inheritance is hard-coded, at
  4760. least for the special applications for which they are used:
  4761. @cindex property, COLUMNS
  4762. @table @code
  4763. @item COLUMNS
  4764. The @code{:COLUMNS:} property defines the format of column view
  4765. (@pxref{Column view}). It is inherited in the sense that the level
  4766. where a @code{:COLUMNS:} property is defined is used as the starting
  4767. point for a column view table, independently of the location in the
  4768. subtree from where columns view is turned on.
  4769. @item CATEGORY
  4770. @cindex property, CATEGORY
  4771. For agenda view, a category set through a @code{:CATEGORY:} property
  4772. applies to the entire subtree.
  4773. @item ARCHIVE
  4774. @cindex property, ARCHIVE
  4775. For archiving, the @code{:ARCHIVE:} property may define the archive
  4776. location for the entire subtree (@pxref{Moving subtrees}).
  4777. @item LOGGING
  4778. @cindex property, LOGGING
  4779. The LOGGING property may define logging settings for an entry or a
  4780. subtree (@pxref{Tracking TODO state changes}).
  4781. @end table
  4782. @node Column view
  4783. @section Column view
  4784. A great way to view and edit properties in an outline tree is
  4785. @emph{column view}. In column view, each outline node is turned into a
  4786. table row. Columns in this table provide access to properties of the
  4787. entries. Org mode implements columns by overlaying a tabular structure
  4788. over the headline of each item. While the headlines have been turned
  4789. into a table row, you can still change the visibility of the outline
  4790. tree. For example, you get a compact table by switching to CONTENTS
  4791. view (@kbd{S-@key{TAB} S-@key{TAB}}, or simply @kbd{c} while column view
  4792. is active), but you can still open, read, and edit the entry below each
  4793. headline. Or, you can switch to column view after executing a sparse
  4794. tree command and in this way get a table only for the selected items.
  4795. Column view also works in agenda buffers (@pxref{Agenda views}) where
  4796. queries have collected selected items, possibly from a number of files.
  4797. @menu
  4798. * Defining columns:: The COLUMNS format property
  4799. * Using column view:: How to create and use column view
  4800. * Capturing column view:: A dynamic block for column view
  4801. @end menu
  4802. @node Defining columns
  4803. @subsection Defining columns
  4804. @cindex column view, for properties
  4805. @cindex properties, column view
  4806. Setting up a column view first requires defining the columns. This is
  4807. done by defining a column format line.
  4808. @menu
  4809. * Scope of column definitions:: Where defined, where valid?
  4810. * Column attributes:: Appearance and content of a column
  4811. @end menu
  4812. @node Scope of column definitions
  4813. @subsubsection Scope of column definitions
  4814. To define a column format for an entire file, use a line like
  4815. @cindex #+COLUMNS
  4816. @example
  4817. #+COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
  4818. @end example
  4819. To specify a format that only applies to a specific tree, add a
  4820. @code{:COLUMNS:} property to the top node of that tree, for example:
  4821. @example
  4822. ** Top node for columns view
  4823. :PROPERTIES:
  4824. :COLUMNS: %25ITEM %TAGS %PRIORITY %TODO
  4825. :END:
  4826. @end example
  4827. If a @code{:COLUMNS:} property is present in an entry, it defines columns
  4828. for the entry itself, and for the entire subtree below it. Since the
  4829. column definition is part of the hierarchical structure of the document,
  4830. you can define columns on level 1 that are general enough for all
  4831. sublevels, and more specific columns further down, when you edit a
  4832. deeper part of the tree.
  4833. @node Column attributes
  4834. @subsubsection Column attributes
  4835. A column definition sets the attributes of a column. The general
  4836. definition looks like this:
  4837. @example
  4838. %[@var{width}]@var{property}[(@var{title})][@{@var{summary-type}@}]
  4839. @end example
  4840. @noindent
  4841. Except for the percent sign and the property name, all items are
  4842. optional. The individual parts have the following meaning:
  4843. @example
  4844. @var{width} @r{An integer specifying the width of the column in characters.}
  4845. @r{If omitted, the width will be determined automatically.}
  4846. @var{property} @r{The property that should be edited in this column.}
  4847. @r{Special properties representing meta data are allowed here}
  4848. @r{as well (@pxref{Special properties})}
  4849. @var{title} @r{The header text for the column. If omitted, the property}
  4850. @r{name is used.}
  4851. @{@var{summary-type}@} @r{The summary type. If specified, the column values for}
  4852. @r{parent nodes are computed from the children@footnote{If
  4853. more than one summary type apply to the property, the parent
  4854. values are computed according to the first of them.}.}
  4855. @r{Supported summary types are:}
  4856. @{+@} @r{Sum numbers in this column.}
  4857. @{+;%.1f@} @r{Like @samp{+}, but format result with @samp{%.1f}.}
  4858. @{$@} @r{Currency, short for @samp{+;%.2f}.}
  4859. @{min@} @r{Smallest number in column.}
  4860. @{max@} @r{Largest number.}
  4861. @{mean@} @r{Arithmetic mean of numbers.}
  4862. @{X@} @r{Checkbox status, @samp{[X]} if all children are @samp{[X]}.}
  4863. @{X/@} @r{Checkbox status, @samp{[n/m]}.}
  4864. @{X%@} @r{Checkbox status, @samp{[n%]}.}
  4865. @{:@} @r{Sum times, HH:MM, plain numbers are
  4866. hours@footnote{A time can also be a duration, using effort
  4867. modifiers defined in @code{org-effort-durations}, e.g.,
  4868. @samp{3d 1h}. If any value in the column is as such, the
  4869. summary will also be an effort duration.}.}
  4870. @{:min@} @r{Smallest time value in column.}
  4871. @{:max@} @r{Largest time value.}
  4872. @{:mean@} @r{Arithmetic mean of time values.}
  4873. @{@@min@} @r{Minimum age@footnote{An age is defined as
  4874. a duration since a given time-stamp (@pxref{Timestamps}). It
  4875. can also be expressed as days, hours, minutes and seconds,
  4876. identified by @samp{d}, @samp{h}, @samp{m} and @samp{s}
  4877. suffixes, all mandatory, e.g., @samp{0d 13h 0m 10s}.} (in
  4878. days/hours/mins/seconds).}
  4879. @{@@max@} @r{Maximum age (in days/hours/mins/seconds).}
  4880. @{@@mean@} @r{Arithmetic mean of ages (in days/hours/mins/seconds).}
  4881. @{est+@} @r{Add @samp{low-high} estimates.}
  4882. @end example
  4883. The @code{est+} summary type requires further explanation. It is used for
  4884. combining estimates, expressed as @samp{low-high} ranges or plain numbers.
  4885. For example, instead of estimating a particular task will take 5 days, you
  4886. might estimate it as 5--6 days if you're fairly confident you know how much
  4887. work is required, or 1--10 days if you don't really know what needs to be
  4888. done. Both ranges average at 5.5 days, but the first represents a more
  4889. predictable delivery.
  4890. When combining a set of such estimates, simply adding the lows and highs
  4891. produces an unrealistically wide result. Instead, @code{est+} adds the
  4892. statistical mean and variance of the sub-tasks, generating a final estimate
  4893. from the sum. For example, suppose you had ten tasks, each of which was
  4894. estimated at 0.5 to 2 days of work. Straight addition produces an estimate
  4895. of 5 to 20 days, representing what to expect if everything goes either
  4896. extremely well or extremely poorly. In contrast, @code{est+} estimates the
  4897. full job more realistically, at 10--15 days.
  4898. Numbers are right-aligned when a format specifier with an explicit width like
  4899. @code{%5d} or @code{%5.1f} is used.
  4900. @vindex org-columns-summary-types
  4901. You can also define custom summary types by setting
  4902. @code{org-columns-summary-types}, which see.
  4903. Here is an example for a complete columns definition, along with allowed
  4904. values.
  4905. @example
  4906. :COLUMNS: %25ITEM %9Approved(Approved?)@{X@} %Owner %11Status \@footnote{Please note that the COLUMNS definition must be on a single line---it is wrapped here only because of formatting constraints.}
  4907. %10Time_Estimate@{:@} %CLOCKSUM %CLOCKSUM_T
  4908. :Owner_ALL: Tammy Mark Karl Lisa Don
  4909. :Status_ALL: "In progress" "Not started yet" "Finished" ""
  4910. :Approved_ALL: "[ ]" "[X]"
  4911. @end example
  4912. @noindent
  4913. The first column, @samp{%25ITEM}, means the first 25 characters of the
  4914. item itself, i.e., of the headline. You probably always should start the
  4915. column definition with the @samp{ITEM} specifier. The other specifiers
  4916. create columns @samp{Owner} with a list of names as allowed values, for
  4917. @samp{Status} with four different possible values, and for a checkbox
  4918. field @samp{Approved}. When no width is given after the @samp{%}
  4919. character, the column will be exactly as wide as it needs to be in order
  4920. to fully display all values. The @samp{Approved} column does have a
  4921. modified title (@samp{Approved?}, with a question mark). Summaries will
  4922. be created for the @samp{Time_Estimate} column by adding time duration
  4923. expressions like HH:MM, and for the @samp{Approved} column, by providing
  4924. an @samp{[X]} status if all children have been checked. The
  4925. @samp{CLOCKSUM} and @samp{CLOCKSUM_T} columns are special, they lists the
  4926. sums of CLOCK intervals in the subtree, either for all clocks or just for
  4927. today.
  4928. @node Using column view
  4929. @subsection Using column view
  4930. @table @kbd
  4931. @tsubheading{Turning column view on and off}
  4932. @orgcmd{C-c C-x C-c,org-columns}
  4933. @vindex org-columns-default-format
  4934. Turn on column view. If the cursor is before the first headline in the file,
  4935. or the function called with the universal prefix argument, column view is
  4936. turned on for the entire file, using the @code{#+COLUMNS} definition. If the
  4937. cursor is somewhere inside the outline, this command searches the hierarchy,
  4938. up from point, for a @code{:COLUMNS:} property that defines a format. When
  4939. one is found, the column view table is established for the tree starting at
  4940. the entry that contains the @code{:COLUMNS:} property. If no such property
  4941. is found, the format is taken from the @code{#+COLUMNS} line or from the
  4942. variable @code{org-columns-default-format}, and column view is established
  4943. for the current entry and its subtree.
  4944. @orgcmd{r,org-columns-redo}
  4945. Recreate the column view, to include recent changes made in the buffer.
  4946. @orgcmd{g,org-columns-redo}
  4947. Same as @kbd{r}.
  4948. @orgcmd{q,org-columns-quit}
  4949. Exit column view.
  4950. @tsubheading{Editing values}
  4951. @item @key{left} @key{right} @key{up} @key{down}
  4952. Move through the column view from field to field.
  4953. @kindex S-@key{left}
  4954. @kindex S-@key{right}
  4955. @item S-@key{left}/@key{right}
  4956. Switch to the next/previous allowed value of the field. For this, you
  4957. have to have specified allowed values for a property.
  4958. @item 1..9,0
  4959. Directly select the Nth allowed value, @kbd{0} selects the 10th value.
  4960. @orgcmdkkcc{n,p,org-columns-next-allowed-value,org-columns-previous-allowed-value}
  4961. Same as @kbd{S-@key{left}/@key{right}}
  4962. @orgcmd{e,org-columns-edit-value}
  4963. Edit the property at point. For the special properties, this will
  4964. invoke the same interface that you normally use to change that
  4965. property. For example, when editing a TAGS property, the tag completion
  4966. or fast selection interface will pop up.
  4967. @orgcmd{C-c C-c,org-columns-set-tags-or-toggle}
  4968. When there is a checkbox at point, toggle it.
  4969. @orgcmd{v,org-columns-show-value}
  4970. View the full value of this property. This is useful if the width of
  4971. the column is smaller than that of the value.
  4972. @orgcmd{a,org-columns-edit-allowed}
  4973. Edit the list of allowed values for this property. If the list is found
  4974. in the hierarchy, the modified value is stored there. If no list is
  4975. found, the new value is stored in the first entry that is part of the
  4976. current column view.
  4977. @tsubheading{Modifying the table structure}
  4978. @orgcmdkkcc{<,>,org-columns-narrow,org-columns-widen}
  4979. Make the column narrower/wider by one character.
  4980. @orgcmd{S-M-@key{right},org-columns-new}
  4981. Insert a new column, to the left of the current column.
  4982. @orgcmd{S-M-@key{left},org-columns-delete}
  4983. Delete the current column.
  4984. @end table
  4985. @node Capturing column view
  4986. @subsection Capturing column view
  4987. Since column view is just an overlay over a buffer, it cannot be
  4988. exported or printed directly. If you want to capture a column view, use
  4989. a @code{columnview} dynamic block (@pxref{Dynamic blocks}). The frame
  4990. of this block looks like this:
  4991. @cindex #+BEGIN, columnview
  4992. @example
  4993. * The column view
  4994. #+BEGIN: columnview :hlines 1 :id "label"
  4995. #+END:
  4996. @end example
  4997. @noindent This dynamic block has the following parameters:
  4998. @table @code
  4999. @item :id
  5000. This is the most important parameter. Column view is a feature that is
  5001. often localized to a certain (sub)tree, and the capture block might be
  5002. at a different location in the file. To identify the tree whose view to
  5003. capture, you can use 4 values:
  5004. @cindex property, ID
  5005. @example
  5006. local @r{use the tree in which the capture block is located}
  5007. global @r{make a global view, including all headings in the file}
  5008. "file:@var{path-to-file}"
  5009. @r{run column view at the top of this file}
  5010. "@var{ID}" @r{call column view in the tree that has an @code{:ID:}}
  5011. @r{property with the value @i{label}. You can use}
  5012. @r{@kbd{M-x org-id-copy RET} to create a globally unique ID for}
  5013. @r{the current entry and copy it to the kill-ring.}
  5014. @end example
  5015. @item :hlines
  5016. When @code{t}, insert an hline after every line. When a number @var{N}, insert
  5017. an hline before each headline with level @code{<= @var{N}}.
  5018. @item :vlines
  5019. When set to @code{t}, force column groups to get vertical lines.
  5020. @item :maxlevel
  5021. When set to a number, don't capture entries below this level.
  5022. @item :skip-empty-rows
  5023. When set to @code{t}, skip rows where the only non-empty specifier of the
  5024. column view is @code{ITEM}.
  5025. @item :indent
  5026. When non-@code{nil}, indent each @code{ITEM} field according to its level.
  5027. @end table
  5028. @noindent
  5029. The following commands insert or update the dynamic block:
  5030. @table @kbd
  5031. @orgcmd{C-c C-x i,org-insert-columns-dblock}
  5032. Insert a dynamic block capturing a column view. You will be prompted
  5033. for the scope or ID of the view.
  5034. @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
  5035. Update dynamic block at point. The cursor needs to be in the
  5036. @code{#+BEGIN} line of the dynamic block.
  5037. @orgcmd{C-u C-c C-x C-u,org-update-all-dblocks}
  5038. Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
  5039. you have several clock table blocks, column-capturing blocks or other dynamic
  5040. blocks in a buffer.
  5041. @end table
  5042. You can add formulas to the column view table and you may add plotting
  5043. instructions in front of the table---these will survive an update of the
  5044. block. If there is a @code{#+TBLFM:} after the table, the table will
  5045. actually be recalculated automatically after an update.
  5046. An alternative way to capture and process property values into a table is
  5047. provided by Eric Schulte's @file{org-collector.el} which is a contributed
  5048. package@footnote{Contributed packages are not part of Emacs, but are
  5049. distributed with the main distribution of Org (visit
  5050. @uref{http://orgmode.org}).}. It provides a general API to collect
  5051. properties from entries in a certain scope, and arbitrary Lisp expressions to
  5052. process these values before inserting them into a table or a dynamic block.
  5053. @node Property API
  5054. @section The Property API
  5055. @cindex properties, API
  5056. @cindex API, for properties
  5057. There is a full API for accessing and changing properties. This API can
  5058. be used by Emacs Lisp programs to work with properties and to implement
  5059. features based on them. For more information see @ref{Using the
  5060. property API}.
  5061. @node Dates and times
  5062. @chapter Dates and times
  5063. @cindex dates
  5064. @cindex times
  5065. @cindex timestamp
  5066. @cindex date stamp
  5067. To assist project planning, TODO items can be labeled with a date and/or
  5068. a time. The specially formatted string carrying the date and time
  5069. information is called a @emph{timestamp} in Org mode. This may be a
  5070. little confusing because timestamp is often used to indicate when
  5071. something was created or last changed. However, in Org mode this term
  5072. is used in a much wider sense.
  5073. @menu
  5074. * Timestamps:: Assigning a time to a tree entry
  5075. * Creating timestamps:: Commands which insert timestamps
  5076. * Deadlines and scheduling:: Planning your work
  5077. * Clocking work time:: Tracking how long you spend on a task
  5078. * Effort estimates:: Planning work effort in advance
  5079. * Timers:: Notes with a running timer
  5080. @end menu
  5081. @node Timestamps
  5082. @section Timestamps, deadlines, and scheduling
  5083. @cindex timestamps
  5084. @cindex ranges, time
  5085. @cindex date stamps
  5086. @cindex deadlines
  5087. @cindex scheduling
  5088. A timestamp is a specification of a date (possibly with a time or a range of
  5089. times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this
  5090. simplest form, the day name is optional when you type the date yourself.
  5091. However, any dates inserted or modified by Org will add that day name, for
  5092. reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16
  5093. Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601
  5094. date/time format. To use an alternative format, see @ref{Custom time
  5095. format}.}. A timestamp can appear anywhere in the headline or body of an Org
  5096. tree entry. Its presence causes entries to be shown on specific dates in the
  5097. agenda (@pxref{Weekly/daily agenda}). We distinguish:
  5098. @table @var
  5099. @item Plain timestamp; Event; Appointment
  5100. @cindex timestamp
  5101. @cindex appointment
  5102. A simple timestamp just assigns a date/time to an item. This is just like
  5103. writing down an appointment or event in a paper agenda. In the agenda
  5104. display, the headline of an entry associated with a plain timestamp will be
  5105. shown exactly on that date.
  5106. @example
  5107. * Meet Peter at the movies
  5108. <2006-11-01 Wed 19:15>
  5109. * Discussion on climate change
  5110. <2006-11-02 Thu 20:00-22:00>
  5111. @end example
  5112. @item Timestamp with repeater interval
  5113. @cindex timestamp, with repeater interval
  5114. A timestamp may contain a @emph{repeater interval}, indicating that it
  5115. applies not only on the given date, but again and again after a certain
  5116. interval of N days (d), weeks (w), months (m), or years (y). The
  5117. following will show up in the agenda every Wednesday:
  5118. @example
  5119. * Pick up Sam at school
  5120. <2007-05-16 Wed 12:30 +1w>
  5121. @end example
  5122. @item Diary-style sexp entries
  5123. For more complex date specifications, Org mode supports using the special
  5124. sexp diary entries implemented in the Emacs calendar/diary
  5125. package@footnote{When working with the standard diary sexp functions, you
  5126. need to be very careful with the order of the arguments. That order depends
  5127. evilly on the variable @code{calendar-date-style} (or, for older Emacs
  5128. versions, @code{european-calendar-style}). For example, to specify a date
  5129. December 1, 2005, the call might look like @code{(diary-date 12 1 2005)} or
  5130. @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on
  5131. the settings. This has been the source of much confusion. Org mode users
  5132. can resort to special versions of these functions like @code{org-date} or
  5133. @code{org-anniversary}. These work just like the corresponding @code{diary-}
  5134. functions, but with stable ISO order of arguments (year, month, day) wherever
  5135. applicable, independent of the value of @code{calendar-date-style}.}. For
  5136. example with optional time
  5137. @example
  5138. * 22:00-23:00 The nerd meeting on every 2nd Thursday of the month
  5139. <%%(diary-float t 4 2)>
  5140. @end example
  5141. @item Time/Date range
  5142. @cindex timerange
  5143. @cindex date range
  5144. Two timestamps connected by @samp{--} denote a range. The headline
  5145. will be shown on the first and last day of the range, and on any dates
  5146. that are displayed and fall in the range. Here is an example:
  5147. @example
  5148. ** Meeting in Amsterdam
  5149. <2004-08-23 Mon>--<2004-08-26 Thu>
  5150. @end example
  5151. @item Inactive timestamp
  5152. @cindex timestamp, inactive
  5153. @cindex inactive timestamp
  5154. Just like a plain timestamp, but with square brackets instead of
  5155. angular ones. These timestamps are inactive in the sense that they do
  5156. @emph{not} trigger an entry to show up in the agenda.
  5157. @example
  5158. * Gillian comes late for the fifth time
  5159. [2006-11-01 Wed]
  5160. @end example
  5161. @end table
  5162. @node Creating timestamps
  5163. @section Creating timestamps
  5164. @cindex creating timestamps
  5165. @cindex timestamps, creating
  5166. For Org mode to recognize timestamps, they need to be in the specific
  5167. format. All commands listed below produce timestamps in the correct
  5168. format.
  5169. @table @kbd
  5170. @orgcmd{C-c .,org-time-stamp}
  5171. Prompt for a date and insert a corresponding timestamp. When the cursor is
  5172. at an existing timestamp in the buffer, the command is used to modify this
  5173. timestamp instead of inserting a new one. When this command is used twice in
  5174. succession, a time range is inserted.
  5175. @c
  5176. @orgcmd{C-c !,org-time-stamp-inactive}
  5177. Like @kbd{C-c .}, but insert an inactive timestamp that will not cause
  5178. an agenda entry.
  5179. @c
  5180. @kindex C-u C-c .
  5181. @kindex C-u C-c !
  5182. @item C-u C-c .
  5183. @itemx C-u C-c !
  5184. @vindex org-time-stamp-rounding-minutes
  5185. Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which
  5186. contains date and time. The default time can be rounded to multiples of 5
  5187. minutes, see the option @code{org-time-stamp-rounding-minutes}.
  5188. @c
  5189. @orgkey{C-c C-c}
  5190. Normalize timestamp, insert/fix day name if missing or wrong.
  5191. @c
  5192. @orgcmd{C-c <,org-date-from-calendar}
  5193. Insert a timestamp corresponding to the cursor date in the Calendar.
  5194. @c
  5195. @orgcmd{C-c >,org-goto-calendar}
  5196. Access the Emacs calendar for the current date. If there is a
  5197. timestamp in the current line, go to the corresponding date
  5198. instead.
  5199. @c
  5200. @orgcmd{C-c C-o,org-open-at-point}
  5201. Access the agenda for the date given by the timestamp or -range at
  5202. point (@pxref{Weekly/daily agenda}).
  5203. @c
  5204. @orgcmdkkcc{S-@key{left},S-@key{right},org-timestamp-down-day,org-timestamp-up-day}
  5205. Change date at cursor by one day. These key bindings conflict with
  5206. shift-selection and related modes (@pxref{Conflicts}).
  5207. @c
  5208. @orgcmdkkcc{S-@key{up},S-@key{down},org-timestamp-up,org-timestamp-down-down}
  5209. Change the item under the cursor in a timestamp. The cursor can be on a
  5210. year, month, day, hour or minute. When the timestamp contains a time range
  5211. like @samp{15:30-16:30}, modifying the first time will also shift the second,
  5212. shifting the time block with constant length. To change the length, modify
  5213. the second time. Note that if the cursor is in a headline and not at a
  5214. timestamp, these same keys modify the priority of an item.
  5215. (@pxref{Priorities}). The key bindings also conflict with shift-selection and
  5216. related modes (@pxref{Conflicts}).
  5217. @c
  5218. @orgcmd{C-c C-y,org-evaluate-time-range}
  5219. @cindex evaluate time range
  5220. Evaluate a time range by computing the difference between start and end.
  5221. With a prefix argument, insert result after the time range (in a table: into
  5222. the following column).
  5223. @end table
  5224. @menu
  5225. * The date/time prompt:: How Org mode helps you entering date and time
  5226. * Custom time format:: Making dates look different
  5227. @end menu
  5228. @node The date/time prompt
  5229. @subsection The date/time prompt
  5230. @cindex date, reading in minibuffer
  5231. @cindex time, reading in minibuffer
  5232. @vindex org-read-date-prefer-future
  5233. When Org mode prompts for a date/time, the default is shown in default
  5234. date/time format, and the prompt therefore seems to ask for a specific
  5235. format. But it will in fact accept date/time information in a variety of
  5236. formats. Generally, the information should start at the beginning of the
  5237. string. Org mode will find whatever information is in
  5238. there and derive anything you have not specified from the @emph{default date
  5239. and time}. The default is usually the current date and time, but when
  5240. modifying an existing timestamp, or when entering the second stamp of a
  5241. range, it is taken from the stamp in the buffer. When filling in
  5242. information, Org mode assumes that most of the time you will want to enter a
  5243. date in the future: if you omit the month/year and the given day/month is
  5244. @i{before} today, it will assume that you mean a future date@footnote{See the
  5245. variable @code{org-read-date-prefer-future}. You may set that variable to
  5246. the symbol @code{time} to even make a time before now shift the date to
  5247. tomorrow.}. If the date has been automatically shifted into the future, the
  5248. time prompt will show this with @samp{(=>F).}
  5249. For example, let's assume that today is @b{June 13, 2006}. Here is how
  5250. various inputs will be interpreted, the items filled in by Org mode are
  5251. in @b{bold}.
  5252. @example
  5253. 3-2-5 @result{} 2003-02-05
  5254. 2/5/3 @result{} 2003-02-05
  5255. 14 @result{} @b{2006}-@b{06}-14
  5256. 12 @result{} @b{2006}-@b{07}-12
  5257. 2/5 @result{} @b{2007}-02-05
  5258. Fri @result{} nearest Friday after the default date
  5259. sep 15 @result{} @b{2006}-09-15
  5260. feb 15 @result{} @b{2007}-02-15
  5261. sep 12 9 @result{} 2009-09-12
  5262. 12:45 @result{} @b{2006}-@b{06}-@b{13} 12:45
  5263. 22 sept 0:34 @result{} @b{2006}-09-22 00:34
  5264. w4 @result{} ISO week four of the current year @b{2006}
  5265. 2012 w4 fri @result{} Friday of ISO week 4 in 2012
  5266. 2012-w04-5 @result{} Same as above
  5267. @end example
  5268. Furthermore you can specify a relative date by giving, as the @emph{first}
  5269. thing in the input: a plus/minus sign, a number and a letter ([hdwmy]) to
  5270. indicate change in hours, days, weeks, months, or years. With a single plus
  5271. or minus, the date is always relative to today. With a double plus or minus,
  5272. it is relative to the default date. If instead of a single letter, you use
  5273. the abbreviation of day name, the date will be the Nth such day, e.g.:
  5274. @example
  5275. +0 @result{} today
  5276. . @result{} today
  5277. +4d @result{} four days from today
  5278. +4 @result{} same as above
  5279. +2w @result{} two weeks from today
  5280. ++5 @result{} five days from default date
  5281. +2tue @result{} second Tuesday from now
  5282. -wed @result{} last Wednesday
  5283. @end example
  5284. @vindex parse-time-months
  5285. @vindex parse-time-weekdays
  5286. The function understands English month and weekday abbreviations. If
  5287. you want to use unabbreviated names and/or other languages, configure
  5288. the variables @code{parse-time-months} and @code{parse-time-weekdays}.
  5289. @vindex org-read-date-force-compatible-dates
  5290. Not all dates can be represented in a given Emacs implementation. By default
  5291. Org mode forces dates into the compatibility range 1970--2037 which works on
  5292. all Emacs implementations. If you want to use dates outside of this range,
  5293. read the docstring of the variable
  5294. @code{org-read-date-force-compatible-dates}.
  5295. You can specify a time range by giving start and end times or by giving a
  5296. start time and a duration (in HH:MM format). Use one or two dash(es) as the
  5297. separator in the former case and use '+' as the separator in the latter
  5298. case, e.g.:
  5299. @example
  5300. 11am-1:15pm @result{} 11:00-13:15
  5301. 11am--1:15pm @result{} same as above
  5302. 11am+2:15 @result{} same as above
  5303. @end example
  5304. @cindex calendar, for selecting date
  5305. @vindex org-popup-calendar-for-date-prompt
  5306. Parallel to the minibuffer prompt, a calendar is popped up@footnote{If
  5307. you don't need/want the calendar, configure the variable
  5308. @code{org-popup-calendar-for-date-prompt}.}. When you exit the date
  5309. prompt, either by clicking on a date in the calendar, or by pressing
  5310. @key{RET}, the date selected in the calendar will be combined with the
  5311. information entered at the prompt. You can control the calendar fully
  5312. from the minibuffer:
  5313. @kindex <
  5314. @kindex >
  5315. @kindex M-v
  5316. @kindex C-v
  5317. @kindex mouse-1
  5318. @kindex S-@key{right}
  5319. @kindex S-@key{left}
  5320. @kindex S-@key{down}
  5321. @kindex S-@key{up}
  5322. @kindex M-S-@key{right}
  5323. @kindex M-S-@key{left}
  5324. @kindex @key{RET}
  5325. @kindex M-S-@key{down}
  5326. @kindex M-S-@key{up}
  5327. @example
  5328. @key{RET} @r{Choose date at cursor in calendar.}
  5329. mouse-1 @r{Select date by clicking on it.}
  5330. S-@key{right}/@key{left} @r{One day forward/backward.}
  5331. S-@key{down}/@key{up} @r{One week forward/backward.}
  5332. M-S-@key{right}/@key{left} @r{One month forward/backward.}
  5333. > / < @r{Scroll calendar forward/backward by one month.}
  5334. M-v / C-v @r{Scroll calendar forward/backward by 3 months.}
  5335. M-S-@key{down}/@key{up} @r{Scroll calendar forward/backward by one year.}
  5336. @end example
  5337. @vindex org-read-date-display-live
  5338. The actions of the date/time prompt may seem complex, but I assure you they
  5339. will grow on you, and you will start getting annoyed by pretty much any other
  5340. way of entering a date/time out there. To help you understand what is going
  5341. on, the current interpretation of your input will be displayed live in the
  5342. minibuffer@footnote{If you find this distracting, turn the display off with
  5343. @code{org-read-date-display-live}.}.
  5344. @node Custom time format
  5345. @subsection Custom time format
  5346. @cindex custom date/time format
  5347. @cindex time format, custom
  5348. @cindex date format, custom
  5349. @vindex org-display-custom-times
  5350. @vindex org-time-stamp-custom-formats
  5351. Org mode uses the standard ISO notation for dates and times as it is
  5352. defined in ISO 8601. If you cannot get used to this and require another
  5353. representation of date and time to keep you happy, you can get it by
  5354. customizing the options @code{org-display-custom-times} and
  5355. @code{org-time-stamp-custom-formats}.
  5356. @table @kbd
  5357. @orgcmd{C-c C-x C-t,org-toggle-time-stamp-overlays}
  5358. Toggle the display of custom formats for dates and times.
  5359. @end table
  5360. @noindent
  5361. Org mode needs the default format for scanning, so the custom date/time
  5362. format does not @emph{replace} the default format---instead it is put
  5363. @emph{over} the default format using text properties. This has the
  5364. following consequences:
  5365. @itemize @bullet
  5366. @item
  5367. You cannot place the cursor onto a timestamp anymore, only before or
  5368. after.
  5369. @item
  5370. The @kbd{S-@key{up}/@key{down}} keys can no longer be used to adjust
  5371. each component of a timestamp. If the cursor is at the beginning of
  5372. the stamp, @kbd{S-@key{up}/@key{down}} will change the stamp by one day,
  5373. just like @kbd{S-@key{left}/@key{right}}. At the end of the stamp, the
  5374. time will be changed by one minute.
  5375. @item
  5376. If the timestamp contains a range of clock times or a repeater, these
  5377. will not be overlaid, but remain in the buffer as they were.
  5378. @item
  5379. When you delete a timestamp character-by-character, it will only
  5380. disappear from the buffer after @emph{all} (invisible) characters
  5381. belonging to the ISO timestamp have been removed.
  5382. @item
  5383. If the custom timestamp format is longer than the default and you are
  5384. using dates in tables, table alignment will be messed up. If the custom
  5385. format is shorter, things do work as expected.
  5386. @end itemize
  5387. @node Deadlines and scheduling
  5388. @section Deadlines and scheduling
  5389. A timestamp may be preceded by special keywords to facilitate planning. Both
  5390. the timestamp and the keyword have to be positioned immediately after the task
  5391. they refer to.
  5392. @table @var
  5393. @item DEADLINE
  5394. @cindex DEADLINE keyword
  5395. Meaning: the task (most likely a TODO item, though not necessarily) is supposed
  5396. to be finished on that date.
  5397. @vindex org-deadline-warning-days
  5398. @vindex org-agenda-skip-deadline-prewarning-if-scheduled
  5399. On the deadline date, the task will be listed in the agenda. In
  5400. addition, the agenda for @emph{today} will carry a warning about the
  5401. approaching or missed deadline, starting
  5402. @code{org-deadline-warning-days} before the due date, and continuing
  5403. until the entry is marked DONE@. An example:
  5404. @example
  5405. *** TODO write article about the Earth for the Guide
  5406. DEADLINE: <2004-02-29 Sun>
  5407. The editor in charge is [[bbdb:Ford Prefect]]
  5408. @end example
  5409. You can specify a different lead time for warnings for a specific
  5410. deadline using the following syntax. Here is an example with a warning
  5411. period of 5 days @code{DEADLINE: <2004-02-29 Sun -5d>}. This warning is
  5412. deactivated if the task gets scheduled and you set
  5413. @code{org-agenda-skip-deadline-prewarning-if-scheduled} to @code{t}.
  5414. @item SCHEDULED
  5415. @cindex SCHEDULED keyword
  5416. Meaning: you are planning to start working on that task on the given
  5417. date.
  5418. @vindex org-agenda-skip-scheduled-if-done
  5419. The headline will be listed under the given date@footnote{It will still
  5420. be listed on that date after it has been marked DONE@. If you don't like
  5421. this, set the variable @code{org-agenda-skip-scheduled-if-done}.}. In
  5422. addition, a reminder that the scheduled date has passed will be present
  5423. in the compilation for @emph{today}, until the entry is marked DONE, i.e.,
  5424. the task will automatically be forwarded until completed.
  5425. @example
  5426. *** TODO Call Trillian for a date on New Years Eve.
  5427. SCHEDULED: <2004-12-25 Sat>
  5428. @end example
  5429. @vindex org-scheduled-delay-days
  5430. @vindex org-agenda-skip-scheduled-delay-if-deadline
  5431. If you want to @emph{delay} the display of this task in the agenda, use
  5432. @code{SCHEDULED: <2004-12-25 Sat -2d>}: the task is still scheduled on the
  5433. 25th but will appear two days later. In case the task contains a repeater,
  5434. the delay is considered to affect all occurrences; if you want the delay to
  5435. only affect the first scheduled occurrence of the task, use @code{--2d}
  5436. instead. See @code{org-scheduled-delay-days} and
  5437. @code{org-agenda-skip-scheduled-delay-if-deadline} for details on how to
  5438. control this globally or per agenda.
  5439. @noindent
  5440. @b{Important:} Scheduling an item in Org mode should @i{not} be
  5441. understood in the same way that we understand @i{scheduling a meeting}.
  5442. Setting a date for a meeting is just a simple appointment, you should
  5443. mark this entry with a simple plain timestamp, to get this item shown
  5444. on the date where it applies. This is a frequent misunderstanding by
  5445. Org users. In Org mode, @i{scheduling} means setting a date when you
  5446. want to start working on an action item.
  5447. @end table
  5448. You may use timestamps with repeaters in scheduling and deadline
  5449. entries. Org mode will issue early and late warnings based on the
  5450. assumption that the timestamp represents the @i{nearest instance} of
  5451. the repeater. However, the use of diary sexp entries like
  5452. @c
  5453. @code{<%%(diary-float t 42)>}
  5454. @c
  5455. in scheduling and deadline timestamps is limited. Org mode does not
  5456. know enough about the internals of each sexp function to issue early and
  5457. late warnings. However, it will show the item on each day where the
  5458. sexp entry matches.
  5459. @menu
  5460. * Inserting deadline/schedule:: Planning items
  5461. * Repeated tasks:: Items that show up again and again
  5462. @end menu
  5463. @node Inserting deadline/schedule
  5464. @subsection Inserting deadlines or schedules
  5465. The following commands allow you to quickly insert a deadline or to schedule
  5466. an item:
  5467. @table @kbd
  5468. @c
  5469. @orgcmd{C-c C-d,org-deadline}
  5470. Insert @samp{DEADLINE} keyword along with a stamp. Any CLOSED timestamp will
  5471. be removed. When called with a prefix arg, an existing deadline will be
  5472. removed from the entry. Depending on the variable
  5473. @code{org-log-redeadline}@footnote{with corresponding @code{#+STARTUP}
  5474. keywords @code{logredeadline}, @code{lognoteredeadline}, and
  5475. @code{nologredeadline}}, a note will be taken when changing an existing
  5476. deadline.
  5477. @orgcmd{C-c C-s,org-schedule}
  5478. Insert @samp{SCHEDULED} keyword along with a stamp. Any CLOSED timestamp
  5479. will be removed. When called with a prefix argument, remove the scheduling
  5480. date from the entry. Depending on the variable
  5481. @code{org-log-reschedule}@footnote{with corresponding @code{#+STARTUP}
  5482. keywords @code{logreschedule}, @code{lognotereschedule}, and
  5483. @code{nologreschedule}}, a note will be taken when changing an existing
  5484. scheduling time.
  5485. @c
  5486. @orgcmd{C-c / d,org-check-deadlines}
  5487. @cindex sparse tree, for deadlines
  5488. @vindex org-deadline-warning-days
  5489. Create a sparse tree with all deadlines that are either past-due, or
  5490. which will become due within @code{org-deadline-warning-days}.
  5491. With @kbd{C-u} prefix, show all deadlines in the file. With a numeric
  5492. prefix, check that many days. For example, @kbd{C-1 C-c / d} shows
  5493. all deadlines due tomorrow.
  5494. @c
  5495. @orgcmd{C-c / b,org-check-before-date}
  5496. Sparse tree for deadlines and scheduled items before a given date.
  5497. @c
  5498. @orgcmd{C-c / a,org-check-after-date}
  5499. Sparse tree for deadlines and scheduled items after a given date.
  5500. @end table
  5501. Note that @code{org-schedule} and @code{org-deadline} supports
  5502. setting the date by indicating a relative time: e.g., +1d will set
  5503. the date to the next day after today, and --1w will set the date
  5504. to the previous week before any current timestamp.
  5505. @node Repeated tasks
  5506. @subsection Repeated tasks
  5507. @cindex tasks, repeated
  5508. @cindex repeated tasks
  5509. Some tasks need to be repeated again and again. Org mode helps to
  5510. organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED,
  5511. or plain timestamp. In the following example
  5512. @example
  5513. ** TODO Pay the rent
  5514. DEADLINE: <2005-10-01 Sat +1m>
  5515. @end example
  5516. @noindent
  5517. the @code{+1m} is a repeater; the intended interpretation is that the task
  5518. has a deadline on <2005-10-01> and repeats itself every (one) month starting
  5519. from that time. You can use yearly, monthly, weekly, daily and hourly repeat
  5520. cookies by using the @code{y/w/m/d/h} letters. If you need both a repeater
  5521. and a special warning period in a deadline entry, the repeater should come
  5522. first and the warning period last: @code{DEADLINE: <2005-10-01 Sat +1m -3d>}.
  5523. @vindex org-todo-repeat-to-state
  5524. Deadlines and scheduled items produce entries in the agenda when they are
  5525. over-due, so it is important to be able to mark such an entry as completed
  5526. once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO
  5527. keyword DONE, it will no longer produce entries in the agenda. The problem
  5528. with this is, however, that then also the @emph{next} instance of the
  5529. repeated entry will not be active. Org mode deals with this in the following
  5530. way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will
  5531. shift the base date of the repeating timestamp by the repeater interval, and
  5532. immediately set the entry state back to TODO@footnote{In fact, the target
  5533. state is taken from, in this sequence, the @code{REPEAT_TO_STATE} property or
  5534. the variable @code{org-todo-repeat-to-state}. If neither of these is
  5535. specified, the target state defaults to the first state of the TODO state
  5536. sequence.}. In the example above, setting the state to DONE would actually
  5537. switch the date like this:
  5538. @example
  5539. ** TODO Pay the rent
  5540. DEADLINE: <2005-11-01 Tue +1m>
  5541. @end example
  5542. To mark a task with a repeater as @code{DONE}, use @kbd{C-- 1 C-c C-t}
  5543. (i.e., @code{org-todo} with a numeric prefix argument of -1.)
  5544. @vindex org-log-repeat
  5545. A timestamp@footnote{You can change this using the option
  5546. @code{org-log-repeat}, or the @code{#+STARTUP} options @code{logrepeat},
  5547. @code{lognoterepeat}, and @code{nologrepeat}. With @code{lognoterepeat}, you
  5548. will also be prompted for a note.} will be added under the deadline, to keep
  5549. a record that you actually acted on the previous instance of this deadline.
  5550. As a consequence of shifting the base date, this entry will no longer be
  5551. visible in the agenda when checking past dates, but all future instances
  5552. will be visible.
  5553. With the @samp{+1m} cookie, the date shift will always be exactly one
  5554. month. So if you have not paid the rent for three months, marking this
  5555. entry DONE will still keep it as an overdue deadline. Depending on the
  5556. task, this may not be the best way to handle it. For example, if you
  5557. forgot to call your father for 3 weeks, it does not make sense to call
  5558. him 3 times in a single day to make up for it. Finally, there are tasks
  5559. like changing batteries which should always repeat a certain time
  5560. @i{after} the last time you did it. For these tasks, Org mode has
  5561. special repeaters @samp{++} and @samp{.+}. For example:
  5562. @example
  5563. ** TODO Call Father
  5564. DEADLINE: <2008-02-10 Sun ++1w>
  5565. Marking this DONE will shift the date by at least one week,
  5566. but also by as many weeks as it takes to get this date into
  5567. the future. However, it stays on a Sunday, even if you called
  5568. and marked it done on Saturday.
  5569. ** TODO Empty kitchen trash
  5570. DEADLINE: <2008-02-08 Fri 20:00 ++1d>
  5571. Marking this DONE will shift the date by at least one day, and
  5572. also by as many days as it takes to get the timestamp into the
  5573. future. Since there is a time in the timestamp, the next
  5574. deadline in the future will be on today's date if you
  5575. complete the task before 20:00.
  5576. ** TODO Check the batteries in the smoke detectors
  5577. DEADLINE: <2005-11-01 Tue .+1m>
  5578. Marking this DONE will shift the date to one month after
  5579. today.
  5580. @end example
  5581. @vindex org-agenda-skip-scheduled-if-deadline-is-shown
  5582. You may have both scheduling and deadline information for a specific task.
  5583. If the repeater is set for the scheduling information only, you probably want
  5584. the repeater to be ignored after the deadline. If so, set the variable
  5585. @code{org-agenda-skip-scheduled-if-deadline-is-shown} to
  5586. @code{repeated-after-deadline}. However, any scheduling information without
  5587. a repeater is no longer relevant once the task is done, and thus, removed
  5588. upon repeating the task. If you want both scheduling and deadline
  5589. information to repeat after the same interval, set the same repeater for both
  5590. timestamps.
  5591. An alternative to using a repeater is to create a number of copies of a task
  5592. subtree, with dates shifted in each copy. The command @kbd{C-c C-x c} was
  5593. created for this purpose, it is described in @ref{Structure editing}.
  5594. @node Clocking work time
  5595. @section Clocking work time
  5596. @cindex clocking time
  5597. @cindex time clocking
  5598. Org mode allows you to clock the time you spend on specific tasks in a
  5599. project. When you start working on an item, you can start the clock. When
  5600. you stop working on that task, or when you mark the task done, the clock is
  5601. stopped and the corresponding time interval is recorded. It also computes
  5602. the total time spent on each subtree@footnote{Clocking only works if all
  5603. headings are indented with less than 30 stars. This is a hardcoded
  5604. limitation of @code{lmax} in @code{org-clock-sum}.} of a project.
  5605. And it remembers a history or tasks recently clocked, so that you can jump
  5606. quickly between a number of tasks absorbing your time.
  5607. To save the clock history across Emacs sessions, use
  5608. @lisp
  5609. (setq org-clock-persist 'history)
  5610. (org-clock-persistence-insinuate)
  5611. @end lisp
  5612. When you clock into a new task after resuming Emacs, the incomplete
  5613. clock@footnote{To resume the clock under the assumption that you have worked
  5614. on this task while outside Emacs, use @code{(setq org-clock-persist t)}.}
  5615. will be found (@pxref{Resolving idle time}) and you will be prompted about
  5616. what to do with it.
  5617. @menu
  5618. * Clocking commands:: Starting and stopping a clock
  5619. * The clock table:: Detailed reports
  5620. * Resolving idle time:: Resolving time when you've been idle
  5621. @end menu
  5622. @node Clocking commands
  5623. @subsection Clocking commands
  5624. @table @kbd
  5625. @orgcmd{C-c C-x C-i,org-clock-in}
  5626. @vindex org-clock-into-drawer
  5627. @vindex org-clock-continuously
  5628. @cindex property, LOG_INTO_DRAWER
  5629. Start the clock on the current item (clock-in). This inserts the CLOCK
  5630. keyword together with a timestamp. If this is not the first clocking of
  5631. this item, the multiple CLOCK lines will be wrapped into a
  5632. @code{:LOGBOOK:} drawer (see also the variable
  5633. @code{org-clock-into-drawer}). You can also overrule
  5634. the setting of this variable for a subtree by setting a
  5635. @code{CLOCK_INTO_DRAWER} or @code{LOG_INTO_DRAWER} property.
  5636. When called with a @kbd{C-u} prefix argument,
  5637. select the task from a list of recently clocked tasks. With two @kbd{C-u
  5638. C-u} prefixes, clock into the task at point and mark it as the default task;
  5639. the default task will then always be available with letter @kbd{d} when
  5640. selecting a clocking task. With three @kbd{C-u C-u C-u} prefixes, force
  5641. continuous clocking by starting the clock when the last clock stopped.@*
  5642. @cindex property: CLOCK_MODELINE_TOTAL
  5643. @cindex property: LAST_REPEAT
  5644. @vindex org-clock-modeline-total
  5645. While the clock is running, the current clocking time is shown in the mode
  5646. line, along with the title of the task. The clock time shown will be all
  5647. time ever clocked for this task and its children. If the task has an effort
  5648. estimate (@pxref{Effort estimates}), the mode line displays the current
  5649. clocking time against it@footnote{To add an effort estimate ``on the fly'',
  5650. hook a function doing this to @code{org-clock-in-prepare-hook}.} If the task
  5651. is a repeating one (@pxref{Repeated tasks}), only the time since the last
  5652. reset of the task @footnote{as recorded by the @code{LAST_REPEAT} property}
  5653. will be shown. More control over what time is shown can be exercised with
  5654. the @code{CLOCK_MODELINE_TOTAL} property. It may have the values
  5655. @code{current} to show only the current clocking instance, @code{today} to
  5656. show all time clocked on this task today (see also the variable
  5657. @code{org-extend-today-until}), @code{all} to include all time, or
  5658. @code{auto} which is the default@footnote{See also the variable
  5659. @code{org-clock-modeline-total}.}.@* Clicking with @kbd{mouse-1} onto the
  5660. mode line entry will pop up a menu with clocking options.
  5661. @c
  5662. @orgcmd{C-c C-x C-o,org-clock-out}
  5663. @vindex org-log-note-clock-out
  5664. Stop the clock (clock-out). This inserts another timestamp at the same
  5665. location where the clock was last started. It also directly computes
  5666. the resulting time and inserts it after the time range as @samp{=>
  5667. HH:MM}. See the variable @code{org-log-note-clock-out} for the
  5668. possibility to record an additional note together with the clock-out
  5669. timestamp@footnote{The corresponding in-buffer setting is:
  5670. @code{#+STARTUP: lognoteclock-out}}.
  5671. @orgcmd{C-c C-x C-x,org-clock-in-last}
  5672. @vindex org-clock-continuously
  5673. Reclock the last clocked task. With one @kbd{C-u} prefix argument,
  5674. select the task from the clock history. With two @kbd{C-u} prefixes,
  5675. force continuous clocking by starting the clock when the last clock
  5676. stopped.
  5677. @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
  5678. Update the effort estimate for the current clock task.
  5679. @kindex C-c C-y
  5680. @kindex C-c C-c
  5681. @orgcmdkkc{C-c C-c,C-c C-y,org-evaluate-time-range}
  5682. Recompute the time interval after changing one of the timestamps. This
  5683. is only necessary if you edit the timestamps directly. If you change
  5684. them with @kbd{S-@key{cursor}} keys, the update is automatic.
  5685. @orgcmd{C-S-@key{up/down},org-clock-timestamps-up/down}
  5686. On @code{CLOCK} log lines, increase/decrease both timestamps so that the
  5687. clock duration keeps the same.
  5688. @orgcmd{S-M-@key{up/down},org-timestamp-up/down}
  5689. On @code{CLOCK} log lines, increase/decrease the timestamp at point and
  5690. the one of the previous (or the next clock) timestamp by the same duration.
  5691. For example, if you hit @kbd{S-M-@key{up}} to increase a clocked-out timestamp
  5692. by five minutes, then the clocked-in timestamp of the next clock will be
  5693. increased by five minutes.
  5694. @orgcmd{C-c C-t,org-todo}
  5695. Changing the TODO state of an item to DONE automatically stops the clock
  5696. if it is running in this same item.
  5697. @orgcmd{C-c C-x C-q,org-clock-cancel}
  5698. Cancel the current clock. This is useful if a clock was started by
  5699. mistake, or if you ended up working on something else.
  5700. @orgcmd{C-c C-x C-j,org-clock-goto}
  5701. Jump to the headline of the currently clocked in task. With a @kbd{C-u}
  5702. prefix arg, select the target task from a list of recently clocked tasks.
  5703. @orgcmd{C-c C-x C-d,org-clock-display}
  5704. @vindex org-remove-highlights-with-change
  5705. Display time summaries for each subtree in the current buffer. This puts
  5706. overlays at the end of each headline, showing the total time recorded under
  5707. that heading, including the time of any subheadings. You can use visibility
  5708. cycling to study the tree, but the overlays disappear when you change the
  5709. buffer (see variable @code{org-remove-highlights-with-change}) or press
  5710. @kbd{C-c C-c}.
  5711. @end table
  5712. The @kbd{l} key may be used the agenda (@pxref{Weekly/daily agenda}) to show
  5713. which tasks have been worked on or closed during a day.
  5714. @strong{Important:} note that both @code{org-clock-out} and
  5715. @code{org-clock-in-last} can have a global key binding and will not
  5716. modify the window disposition.
  5717. @node The clock table
  5718. @subsection The clock table
  5719. @cindex clocktable, dynamic block
  5720. @cindex report, of clocked time
  5721. Org mode can produce quite complex reports based on the time clocking
  5722. information. Such a report is called a @emph{clock table}, because it is
  5723. formatted as one or several Org tables.
  5724. @table @kbd
  5725. @orgcmd{C-c C-x C-r,org-clock-report}
  5726. Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock
  5727. report as an Org mode table into the current file. When the cursor is
  5728. at an existing clock table, just update it. When called with a prefix
  5729. argument, jump to the first clock report in the current document and
  5730. update it. The clock table always includes also trees with
  5731. @code{:ARCHIVE:} tag.
  5732. @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update}
  5733. Update dynamic block at point. The cursor needs to be in the
  5734. @code{#+BEGIN} line of the dynamic block.
  5735. @orgkey{C-u C-c C-x C-u}
  5736. Update all dynamic blocks (@pxref{Dynamic blocks}). This is useful if
  5737. you have several clock table blocks in a buffer.
  5738. @orgcmdkxkc{S-@key{left},S-@key{right},org-clocktable-try-shift}
  5739. Shift the current @code{:block} interval and update the table. The cursor
  5740. needs to be in the @code{#+BEGIN: clocktable} line for this command. If
  5741. @code{:block} is @code{today}, it will be shifted to @code{today-1} etc.
  5742. @end table
  5743. Here is an example of the frame for a clock table as it is inserted into the
  5744. buffer with the @kbd{C-c C-x C-r} command:
  5745. @cindex #+BEGIN, clocktable
  5746. @example
  5747. #+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
  5748. #+END: clocktable
  5749. @end example
  5750. @noindent
  5751. @vindex org-clocktable-defaults
  5752. The @samp{BEGIN} line specifies a number of options to define the scope,
  5753. structure, and formatting of the report. Defaults for all these options can
  5754. be configured in the variable @code{org-clocktable-defaults}.
  5755. @noindent First there are options that determine which clock entries are to
  5756. be selected:
  5757. @example
  5758. :maxlevel @r{Maximum level depth to which times are listed in the table.}
  5759. @r{Clocks at deeper levels will be summed into the upper level.}
  5760. :scope @r{The scope to consider. This can be any of the following:}
  5761. nil @r{the current buffer or narrowed region}
  5762. file @r{the full current buffer}
  5763. subtree @r{the subtree where the clocktable is located}
  5764. tree@var{N} @r{the surrounding level @var{N} tree, for example @code{tree3}}
  5765. tree @r{the surrounding level 1 tree}
  5766. agenda @r{all agenda files}
  5767. ("file"..) @r{scan these files}
  5768. function @r{the list of files returned by a function of no argument}
  5769. file-with-archives @r{current file and its archives}
  5770. agenda-with-archives @r{all agenda files, including archives}
  5771. :block @r{The time block to consider. This block is specified either}
  5772. @r{absolutely, or relative to the current time and may be any of}
  5773. @r{these formats:}
  5774. 2007-12-31 @r{New year eve 2007}
  5775. 2007-12 @r{December 2007}
  5776. 2007-W50 @r{ISO-week 50 in 2007}
  5777. 2007-Q2 @r{2nd quarter in 2007}
  5778. 2007 @r{the year 2007}
  5779. today, yesterday, today-@var{N} @r{a relative day}
  5780. thisweek, lastweek, thisweek-@var{N} @r{a relative week}
  5781. thismonth, lastmonth, thismonth-@var{N} @r{a relative month}
  5782. thisyear, lastyear, thisyear-@var{N} @r{a relative year}
  5783. untilnow
  5784. @r{Use @kbd{S-@key{left}/@key{right}} keys to shift the time interval.}
  5785. :tstart @r{A time string specifying when to start considering times.}
  5786. @r{Relative times like @code{"<-2w>"} can also be used. See}
  5787. @r{@ref{Matching tags and properties} for relative time syntax.}
  5788. :tend @r{A time string specifying when to stop considering times.}
  5789. @r{Relative times like @code{"<now>"} can also be used. See}
  5790. @r{@ref{Matching tags and properties} for relative time syntax.}
  5791. :wstart @r{The starting day of the week. The default is 1 for monday.}
  5792. :mstart @r{The starting day of the month. The default 1 is for the first}
  5793. @r{day of the month.}
  5794. :step @r{@code{week} or @code{day}, to split the table into chunks.}
  5795. @r{To use this, @code{:block} or @code{:tstart}, @code{:tend} are needed.}
  5796. :stepskip0 @r{Do not show steps that have zero time.}
  5797. :fileskip0 @r{Do not show table sections from files which did not contribute.}
  5798. :tags @r{A tags match to select entries that should contribute. See}
  5799. @r{@ref{Matching tags and properties} for the match syntax.}
  5800. @end example
  5801. Then there are options which determine the formatting of the table. These
  5802. options are interpreted by the function @code{org-clocktable-write-default},
  5803. but you can specify your own function using the @code{:formatter} parameter.
  5804. @example
  5805. :emphasize @r{When @code{t}, emphasize level one and level two items.}
  5806. :lang @r{Language@footnote{Language terms can be set through the variable @code{org-clock-clocktable-language-setup}.} to use for descriptive cells like "Task".}
  5807. :link @r{Link the item headlines in the table to their origins.}
  5808. :narrow @r{An integer to limit the width of the headline column in}
  5809. @r{the org table. If you write it like @samp{50!}, then the}
  5810. @r{headline will also be shortened in export.}
  5811. :indent @r{Indent each headline field according to its level.}
  5812. :tcolumns @r{Number of columns to be used for times. If this is smaller}
  5813. @r{than @code{:maxlevel}, lower levels will be lumped into one column.}
  5814. :level @r{Should a level number column be included?}
  5815. :sort @r{A cons cell like containing the column to sort and a sorting type.}
  5816. @r{E.g., @code{:sort (1 . ?a)} sorts the first column alphabetically.}
  5817. :compact @r{Abbreviation for @code{:level nil :indent t :narrow 40! :tcolumns 1}}
  5818. @r{All are overwritten except if there is an explicit @code{:narrow}}
  5819. :timestamp @r{A timestamp for the entry, when available. Look for SCHEDULED,}
  5820. @r{DEADLINE, TIMESTAMP and TIMESTAMP_IA, in this order.}
  5821. :properties @r{List of properties that should be shown in the table. Each}
  5822. @r{property will get its own column.}
  5823. :inherit-props @r{When this flag is @code{t}, the values for @code{:properties} will be inherited.}
  5824. :formula @r{Content of a @code{#+TBLFM} line to be added and evaluated.}
  5825. @r{As a special case, @samp{:formula %} adds a column with % time.}
  5826. @r{If you do not specify a formula here, any existing formula}
  5827. @r{below the clock table will survive updates and be evaluated.}
  5828. :formatter @r{A function to format clock data and insert it into the buffer.}
  5829. @end example
  5830. To get a clock summary of the current level 1 tree, for the current
  5831. day, you could write
  5832. @example
  5833. #+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
  5834. #+END: clocktable
  5835. @end example
  5836. @noindent
  5837. and to use a specific time range you could write@footnote{Note that all
  5838. parameters must be specified in a single line---the line is broken here
  5839. only to fit it into the manual.}
  5840. @example
  5841. #+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
  5842. :tend "<2006-08-10 Thu 12:00>"
  5843. #+END: clocktable
  5844. @end example
  5845. A range starting a week ago and ending right now could be written as
  5846. @example
  5847. #+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
  5848. #+END: clocktable
  5849. @end example
  5850. A summary of the current subtree with % times would be
  5851. @example
  5852. #+BEGIN: clocktable :scope subtree :link t :formula %
  5853. #+END: clocktable
  5854. @end example
  5855. A horizontally compact representation of everything clocked during last week
  5856. would be
  5857. @example
  5858. #+BEGIN: clocktable :scope agenda :block lastweek :compact t
  5859. #+END: clocktable
  5860. @end example
  5861. @node Resolving idle time
  5862. @subsection Resolving idle time and continuous clocking
  5863. @subsubheading Resolving idle time
  5864. @cindex resolve idle time
  5865. @vindex org-clock-x11idle-program-name
  5866. @cindex idle, resolve, dangling
  5867. If you clock in on a work item, and then walk away from your
  5868. computer---perhaps to take a phone call---you often need to ``resolve'' the
  5869. time you were away by either subtracting it from the current clock, or
  5870. applying it to another one.
  5871. @vindex org-clock-idle-time
  5872. By customizing the variable @code{org-clock-idle-time} to some integer, such
  5873. as 10 or 15, Emacs can alert you when you get back to your computer after
  5874. being idle for that many minutes@footnote{On computers using Mac OS X,
  5875. idleness is based on actual user idleness, not just Emacs' idle time. For
  5876. X11, you can install a utility program @file{x11idle.c}, available in the
  5877. @code{contrib/scripts} directory of the Org git distribution, or install the
  5878. @file{xprintidle} package and set it to the variable
  5879. @code{org-clock-x11idle-program-name} if you are running Debian, to get the
  5880. same general treatment of idleness. On other systems, idle time refers to
  5881. Emacs idle time only.}, and ask what you want to do with the idle time.
  5882. There will be a question waiting for you when you get back, indicating how
  5883. much idle time has passed (constantly updated with the current amount), as
  5884. well as a set of choices to correct the discrepancy:
  5885. @table @kbd
  5886. @item k
  5887. To keep some or all of the minutes and stay clocked in, press @kbd{k}. Org
  5888. will ask how many of the minutes to keep. Press @key{RET} to keep them all,
  5889. effectively changing nothing, or enter a number to keep that many minutes.
  5890. @item K
  5891. If you use the shift key and press @kbd{K}, it will keep however many minutes
  5892. you request and then immediately clock out of that task. If you keep all of
  5893. the minutes, this is the same as just clocking out of the current task.
  5894. @item s
  5895. To keep none of the minutes, use @kbd{s} to subtract all the away time from
  5896. the clock, and then check back in from the moment you returned.
  5897. @item S
  5898. To keep none of the minutes and just clock out at the start of the away time,
  5899. use the shift key and press @kbd{S}. Remember that using shift will always
  5900. leave you clocked out, no matter which option you choose.
  5901. @item C
  5902. To cancel the clock altogether, use @kbd{C}. Note that if instead of
  5903. canceling you subtract the away time, and the resulting clock amount is less
  5904. than a minute, the clock will still be canceled rather than clutter up the
  5905. log with an empty entry.
  5906. @end table
  5907. What if you subtracted those away minutes from the current clock, and now
  5908. want to apply them to a new clock? Simply clock in to any task immediately
  5909. after the subtraction. Org will notice that you have subtracted time ``on
  5910. the books'', so to speak, and will ask if you want to apply those minutes to
  5911. the next task you clock in on.
  5912. There is one other instance when this clock resolution magic occurs. Say you
  5913. were clocked in and hacking away, and suddenly your cat chased a mouse who
  5914. scared a hamster that crashed into your UPS's power button! You suddenly
  5915. lose all your buffers, but thanks to auto-save you still have your recent Org
  5916. mode changes, including your last clock in.
  5917. If you restart Emacs and clock into any task, Org will notice that you have a
  5918. dangling clock which was never clocked out from your last session. Using
  5919. that clock's starting time as the beginning of the unaccounted-for period,
  5920. Org will ask how you want to resolve that time. The logic and behavior is
  5921. identical to dealing with away time due to idleness; it is just happening due
  5922. to a recovery event rather than a set amount of idle time.
  5923. You can also check all the files visited by your Org agenda for dangling
  5924. clocks at any time using @kbd{M-x org-resolve-clocks RET} (or @kbd{C-c C-x C-z}).
  5925. @subsubheading Continuous clocking
  5926. @cindex continuous clocking
  5927. @vindex org-clock-continuously
  5928. You may want to start clocking from the time when you clocked out the
  5929. previous task. To enable this systematically, set @code{org-clock-continuously}
  5930. to @code{t}. Each time you clock in, Org retrieves the clock-out time of the
  5931. last clocked entry for this session, and start the new clock from there.
  5932. If you only want this from time to time, use three universal prefix arguments
  5933. with @code{org-clock-in} and two @kbd{C-u C-u} with @code{org-clock-in-last}.
  5934. @node Effort estimates
  5935. @section Effort estimates
  5936. @cindex effort estimates
  5937. @cindex property, Effort
  5938. If you want to plan your work in a very detailed way, or if you need to
  5939. produce offers with quotations of the estimated work effort, you may want to
  5940. assign effort estimates to entries. If you are also clocking your work, you
  5941. may later want to compare the planned effort with the actual working time,
  5942. a great way to improve planning estimates. Effort estimates are stored in
  5943. a special property @code{EFFORT}. You can set the effort for an entry with
  5944. the following commands:
  5945. @table @kbd
  5946. @orgcmd{C-c C-x e,org-set-effort}
  5947. Set the effort estimate for the current entry. With a numeric prefix
  5948. argument, set it to the Nth allowed value (see below). This command is also
  5949. accessible from the agenda with the @kbd{e} key.
  5950. @orgcmd{C-c C-x C-e,org-clock-modify-effort-estimate}
  5951. Modify the effort estimate of the item currently being clocked.
  5952. @end table
  5953. Clearly the best way to work with effort estimates is through column view
  5954. (@pxref{Column view}). You should start by setting up discrete values for
  5955. effort estimates, and a @code{COLUMNS} format that displays these values
  5956. together with clock sums (if you want to clock your time). For a specific
  5957. buffer you can use
  5958. @example
  5959. #+PROPERTY: Effort_ALL 0 0:10 0:30 1:00 2:00 3:00 4:00 5:00 6:00 7:00
  5960. #+COLUMNS: %40ITEM(Task) %17Effort(Estimated Effort)@{:@} %CLOCKSUM
  5961. @end example
  5962. @noindent
  5963. @vindex org-global-properties
  5964. @vindex org-columns-default-format
  5965. or, even better, you can set up these values globally by customizing the
  5966. variables @code{org-global-properties} and @code{org-columns-default-format}.
  5967. In particular if you want to use this setup also in the agenda, a global
  5968. setup may be advised.
  5969. The way to assign estimates to individual items is then to switch to column
  5970. mode, and to use @kbd{S-@key{right}} and @kbd{S-@key{left}} to change the
  5971. value. The values you enter will immediately be summed up in the hierarchy.
  5972. In the column next to it, any clocked time will be displayed.
  5973. @vindex org-agenda-columns-add-appointments-to-effort-sum
  5974. If you switch to column view in the daily/weekly agenda, the effort column
  5975. will summarize the estimated work effort for each day@footnote{Please note
  5976. the pitfalls of summing hierarchical data in a flat list (@pxref{Agenda
  5977. column view}).}, and you can use this to find space in your schedule. To get
  5978. an overview of the entire part of the day that is committed, you can set the
  5979. option @code{org-agenda-columns-add-appointments-to-effort-sum}. The
  5980. appointments on a day that take place over a specified time interval will
  5981. then also be added to the load estimate of the day.
  5982. Effort estimates can be used in secondary agenda filtering that is triggered
  5983. with the @kbd{/} key in the agenda (@pxref{Agenda commands}). If you have
  5984. these estimates defined consistently, two or three key presses will narrow
  5985. down the list to stuff that fits into an available time slot.
  5986. @node Timers
  5987. @section Taking notes with a timer
  5988. @cindex relative timer
  5989. @cindex countdown timer
  5990. @kindex ;
  5991. Org provides two types of timers. There is a relative timer that counts up,
  5992. which can be useful when taking notes during, for example, a meeting or
  5993. a video viewing. There is also a countdown timer.
  5994. The relative and countdown are started with separate commands.
  5995. @table @kbd
  5996. @orgcmd{C-c C-x 0,org-timer-start}
  5997. Start or reset the relative timer. By default, the timer is set to 0. When
  5998. called with a @kbd{C-u} prefix, prompt the user for a starting offset. If
  5999. there is a timer string at point, this is taken as the default, providing a
  6000. convenient way to restart taking notes after a break in the process. When
  6001. called with a double prefix argument @kbd{C-u C-u}, change all timer strings
  6002. in the active region by a certain amount. This can be used to fix timer
  6003. strings if the timer was not started at exactly the right moment.
  6004. @orgcmd{C-c C-x ;,org-timer-set-timer}
  6005. Start a countdown timer. The user is prompted for a duration.
  6006. @code{org-timer-default-timer} sets the default countdown value. Giving
  6007. a numeric prefix argument overrides this default value. This command is
  6008. available as @kbd{;} in agenda buffers.
  6009. @end table
  6010. Once started, relative and countdown timers are controlled with the same
  6011. commands.
  6012. @table @kbd
  6013. @orgcmd{C-c C-x .,org-timer}
  6014. Insert the value of the current relative or countdown timer into the buffer.
  6015. If no timer is running, the relative timer will be started. When called with
  6016. a prefix argument, the relative timer is restarted.
  6017. @orgcmd{C-c C-x -,org-timer-item}
  6018. Insert a description list item with the value of the current relative or
  6019. countdown timer. With a prefix argument, first reset the relative timer to
  6020. 0.
  6021. @orgcmd{M-@key{RET},org-insert-heading}
  6022. Once the timer list is started, you can also use @kbd{M-@key{RET}} to insert
  6023. new timer items.
  6024. @orgcmd{C-c C-x @comma{},org-timer-pause-or-continue}
  6025. Pause the timer, or continue it if it is already paused.
  6026. @orgcmd{C-c C-x _,org-timer-stop}
  6027. Stop the timer. After this, you can only start a new timer, not continue the
  6028. old one. This command also removes the timer from the mode line.
  6029. @end table
  6030. @node Capture - Refile - Archive
  6031. @chapter Capture - Refile - Archive
  6032. @cindex capture
  6033. An important part of any organization system is the ability to quickly
  6034. capture new ideas and tasks, and to associate reference material with them.
  6035. Org does this using a process called @i{capture}. It also can store files
  6036. related to a task (@i{attachments}) in a special directory. Once in the
  6037. system, tasks and projects need to be moved around. Moving completed project
  6038. trees to an archive file keeps the system compact and fast.
  6039. @menu
  6040. * Capture:: Capturing new stuff
  6041. * Attachments:: Add files to tasks
  6042. * RSS feeds:: Getting input from RSS feeds
  6043. * Protocols:: External (e.g., Browser) access to Emacs and Org
  6044. * Refile and copy:: Moving/copying a tree from one place to another
  6045. * Archiving:: What to do with finished projects
  6046. @end menu
  6047. @node Capture
  6048. @section Capture
  6049. @cindex capture
  6050. Capture lets you quickly store notes with little interruption of your work
  6051. flow. Org's method for capturing new items is heavily inspired by John
  6052. Wiegley excellent @file{remember.el} package. Up to version 6.36, Org
  6053. used a special setup for @file{remember.el}, then replaced it with
  6054. @file{org-remember.el}. As of version 8.0, @file{org-remember.el} has
  6055. been completely replaced by @file{org-capture.el}.
  6056. If your configuration depends on @file{org-remember.el}, you need to update
  6057. it and use the setup described below. To convert your
  6058. @code{org-remember-templates}, run the command
  6059. @example
  6060. @kbd{M-x org-capture-import-remember-templates RET}
  6061. @end example
  6062. @noindent and then customize the new variable with @kbd{M-x
  6063. customize-variable org-capture-templates}, check the result, and save the
  6064. customization.
  6065. @menu
  6066. * Setting up capture:: Where notes will be stored
  6067. * Using capture:: Commands to invoke and terminate capture
  6068. * Capture templates:: Define the outline of different note types
  6069. @end menu
  6070. @node Setting up capture
  6071. @subsection Setting up capture
  6072. The following customization sets a default target file for notes, and defines
  6073. a global key@footnote{Please select your own key, @kbd{C-c c} is only a
  6074. suggestion.} for capturing new material.
  6075. @vindex org-default-notes-file
  6076. @smalllisp
  6077. @group
  6078. (setq org-default-notes-file (concat org-directory "/notes.org"))
  6079. (define-key global-map "\C-cc" 'org-capture)
  6080. @end group
  6081. @end smalllisp
  6082. @node Using capture
  6083. @subsection Using capture
  6084. @table @kbd
  6085. @orgcmd{C-c c,org-capture}
  6086. Call the command @code{org-capture}. Note that this key binding is global and
  6087. not active by default: you need to install it. If you have templates
  6088. @cindex date tree
  6089. defined @pxref{Capture templates}, it will offer these templates for
  6090. selection or use a new Org outline node as the default template. It will
  6091. insert the template into the target file and switch to an indirect buffer
  6092. narrowed to this new node. You may then insert the information you want.
  6093. @orgcmd{C-c C-c,org-capture-finalize}
  6094. Once you have finished entering information into the capture buffer, @kbd{C-c
  6095. C-c} will return you to the window configuration before the capture process,
  6096. so that you can resume your work without further distraction. When called
  6097. with a prefix arg, finalize and then jump to the captured item.
  6098. @orgcmd{C-c C-w,org-capture-refile}
  6099. Finalize the capture process by refiling (@pxref{Refile and copy}) the note to
  6100. a different place. Please realize that this is a normal refiling command
  6101. that will be executed---so the cursor position at the moment you run this
  6102. command is important. If you have inserted a tree with a parent and
  6103. children, first move the cursor back to the parent. Any prefix argument
  6104. given to this command will be passed on to the @code{org-refile} command.
  6105. @orgcmd{C-c C-k,org-capture-kill}
  6106. Abort the capture process and return to the previous state.
  6107. @end table
  6108. You can also call @code{org-capture} in a special way from the agenda, using
  6109. the @kbd{k c} key combination. With this access, any timestamps inserted by
  6110. the selected capture template will default to the cursor date in the agenda,
  6111. rather than to the current date.
  6112. To find the locations of the last stored capture, use @code{org-capture} with
  6113. prefix commands:
  6114. @table @kbd
  6115. @orgkey{C-u C-c c}
  6116. Visit the target location of a capture template. You get to select the
  6117. template in the usual way.
  6118. @orgkey{C-u C-u C-c c}
  6119. Visit the last stored capture item in its buffer.
  6120. @end table
  6121. @vindex org-capture-bookmark
  6122. @cindex org-capture-last-stored
  6123. You can also jump to the bookmark @code{org-capture-last-stored}, which will
  6124. automatically be created unless you set @code{org-capture-bookmark} to
  6125. @code{nil}.
  6126. To insert the capture at point in an Org buffer, call @code{org-capture} with
  6127. a @code{C-0} prefix argument.
  6128. @node Capture templates
  6129. @subsection Capture templates
  6130. @cindex templates, for Capture
  6131. You can use templates for different types of capture items, and
  6132. for different target locations. The easiest way to create such templates is
  6133. through the customize interface.
  6134. @table @kbd
  6135. @orgkey{C-c c C}
  6136. Customize the variable @code{org-capture-templates}.
  6137. @end table
  6138. Before we give the formal description of template definitions, let's look at
  6139. an example. Say you would like to use one template to create general TODO
  6140. entries, and you want to put these entries under the heading @samp{Tasks} in
  6141. your file @file{~/org/gtd.org}. Also, a date tree in the file
  6142. @file{journal.org} should capture journal entries. A possible configuration
  6143. would look like:
  6144. @smalllisp
  6145. @group
  6146. (setq org-capture-templates
  6147. '(("t" "Todo" entry (file+headline "~/org/gtd.org" "Tasks")
  6148. "* TODO %?\n %i\n %a")
  6149. ("j" "Journal" entry (file+olp+datetree "~/org/journal.org")
  6150. "* %?\nEntered on %U\n %i\n %a")))
  6151. @end group
  6152. @end smalllisp
  6153. @noindent If you then press @kbd{C-c c t}, Org will prepare the template
  6154. for you like this:
  6155. @example
  6156. * TODO
  6157. [[file:@var{link to where you initiated capture}]]
  6158. @end example
  6159. @noindent
  6160. During expansion of the template, @code{%a} has been replaced by a link to
  6161. the location from where you called the capture command. This can be
  6162. extremely useful for deriving tasks from emails, for example. You fill in
  6163. the task definition, press @kbd{C-c C-c} and Org returns you to the same
  6164. place where you started the capture process.
  6165. To define special keys to capture to a particular template without going
  6166. through the interactive template selection, you can create your key binding
  6167. like this:
  6168. @lisp
  6169. (define-key global-map "\C-cx"
  6170. (lambda () (interactive) (org-capture nil "x")))
  6171. @end lisp
  6172. @menu
  6173. * Template elements:: What is needed for a complete template entry
  6174. * Template expansion:: Filling in information about time and context
  6175. * Templates in contexts:: Only show a template in a specific context
  6176. @end menu
  6177. @node Template elements
  6178. @subsubsection Template elements
  6179. Now lets look at the elements of a template definition. Each entry in
  6180. @code{org-capture-templates} is a list with the following items:
  6181. @table @var
  6182. @item keys
  6183. The keys that will select the template, as a string, characters
  6184. only, for example @code{"a"} for a template to be selected with a
  6185. single key, or @code{"bt"} for selection with two keys. When using
  6186. several keys, keys using the same prefix key must be sequential
  6187. in the list and preceded by a 2-element entry explaining the
  6188. prefix key, for example
  6189. @smalllisp
  6190. ("b" "Templates for marking stuff to buy")
  6191. @end smalllisp
  6192. @noindent If you do not define a template for the @kbd{C} key, this key will
  6193. be used to open the customize buffer for this complex variable.
  6194. @item description
  6195. A short string describing the template, which will be shown during
  6196. selection.
  6197. @item type
  6198. The type of entry, a symbol. Valid values are:
  6199. @table @code
  6200. @item entry
  6201. An Org mode node, with a headline. Will be filed as the child of the target
  6202. entry or as a top-level entry. The target file should be an Org mode file.
  6203. @item item
  6204. A plain list item, placed in the first plain list at the target
  6205. location. Again the target file should be an Org file.
  6206. @item checkitem
  6207. A checkbox item. This only differs from the plain list item by the
  6208. default template.
  6209. @item table-line
  6210. a new line in the first table at the target location. Where exactly the
  6211. line will be inserted depends on the properties @code{:prepend} and
  6212. @code{:table-line-pos} (see below).
  6213. @item plain
  6214. Text to be inserted as it is.
  6215. @end table
  6216. @item target
  6217. @vindex org-default-notes-file
  6218. Specification of where the captured item should be placed. In Org mode
  6219. files, targets usually define a node. Entries will become children of this
  6220. node. Other types will be added to the table or list in the body of this
  6221. node. Most target specifications contain a file name. If that file name is
  6222. the empty string, it defaults to @code{org-default-notes-file}. A file can
  6223. also be given as a variable or as a function called with no argument. When
  6224. an absolute path is not specified for a target, it is taken as relative to
  6225. @code{org-directory}.
  6226. Valid values are:
  6227. @table @code
  6228. @item (file "path/to/file")
  6229. Text will be placed at the beginning or end of that file.
  6230. @item (id "id of existing org entry")
  6231. Filing as child of this entry, or in the body of the entry.
  6232. @item (file+headline "path/to/file" "node headline")
  6233. Fast configuration if the target heading is unique in the file.
  6234. @item (file+olp "path/to/file" "Level 1 heading" "Level 2" ...)
  6235. For non-unique headings, the full path is safer.
  6236. @item (file+regexp "path/to/file" "regexp to find location")
  6237. Use a regular expression to position the cursor.
  6238. @item (file+olp+datetree "path/to/file" [ "Level 1 heading" ....])
  6239. This target@footnote{Org used to offer four different targets for date/week
  6240. tree capture. Now, Org automatically translates these to use
  6241. @code{file+olp+datetree}, applying the @code{:time-prompt} and
  6242. @code{:tree-type} properties. Please rewrite your date/week-tree targets
  6243. using @code{file+olp+datetree} since the older targets are now deprecated.}
  6244. will create a heading in a date tree@footnote{A date tree is an outline
  6245. structure with years on the highest level, months or ISO-weeks as sublevels
  6246. and then dates on the lowest level. Tags are allowed in the tree structure.}
  6247. for today's date. If the optional outline path is given, the tree will be
  6248. built under the node it is pointing to, instead of at top level. Check out
  6249. the @code{:time-prompt} and @code{:tree-type} properties below for additional
  6250. options.
  6251. @item (file+function "path/to/file" function-finding-location)
  6252. A function to find the right location in the file.
  6253. @item (clock)
  6254. File to the entry that is currently being clocked.
  6255. @item (function function-finding-location)
  6256. Most general way: write your own function which both visits
  6257. the file and moves point to the right location.
  6258. @end table
  6259. @item template
  6260. The template for creating the capture item. If you leave this empty, an
  6261. appropriate default template will be used. Otherwise this is a string with
  6262. escape codes, which will be replaced depending on time and context of the
  6263. capture call. The string with escapes may be loaded from a template file,
  6264. using the special syntax @code{(file "path/to/template")}. See below for
  6265. more details.
  6266. @item properties
  6267. The rest of the entry is a property list of additional options.
  6268. Recognized properties are:
  6269. @table @code
  6270. @item :prepend
  6271. Normally new captured information will be appended at
  6272. the target location (last child, last table line, last list item...).
  6273. Setting this property will change that.
  6274. @item :immediate-finish
  6275. When set, do not offer to edit the information, just
  6276. file it away immediately. This makes sense if the template only needs
  6277. information that can be added automatically.
  6278. @item :empty-lines
  6279. Set this to the number of lines to insert
  6280. before and after the new item. Default 0, only common other value is 1.
  6281. @item :clock-in
  6282. Start the clock in this item.
  6283. @item :clock-keep
  6284. Keep the clock running when filing the captured entry.
  6285. @item :clock-resume
  6286. If starting the capture interrupted a clock, restart that clock when finished
  6287. with the capture. Note that @code{:clock-keep} has precedence over
  6288. @code{:clock-resume}. When setting both to @code{t}, the current clock will
  6289. run and the previous one will not be resumed.
  6290. @item :time-prompt
  6291. Prompt for a date/time to be used for date/week trees and when filling the
  6292. template. Without this property, capture uses the current date and time.
  6293. Even if this property has not been set, you can force the same behavior by
  6294. calling @code{org-capture} with a @kbd{C-1} prefix argument.
  6295. @item :tree-type
  6296. When `week', make a week tree instead of the month tree, i.e. place the
  6297. headings for each day under a heading with the current iso week.
  6298. @item :unnarrowed
  6299. Do not narrow the target buffer, simply show the full buffer. Default is to
  6300. narrow it so that you only see the new material.
  6301. @item :table-line-pos
  6302. Specification of the location in the table where the new line should be
  6303. inserted. It can be a string, a variable holding a string or a function
  6304. returning a string. The string should look like @code{"II-3"} meaning that
  6305. the new line should become the third line before the second horizontal
  6306. separator line.
  6307. @item :kill-buffer
  6308. If the target file was not yet visited when capture was invoked, kill the
  6309. buffer again after capture is completed.
  6310. @end table
  6311. @end table
  6312. @node Template expansion
  6313. @subsubsection Template expansion
  6314. In the template itself, special @kbd{%}-escapes@footnote{If you need one of
  6315. these sequences literally, escape the @kbd{%} with a backslash.} allow
  6316. dynamic insertion of content. The templates are expanded in the order given here:
  6317. @smallexample
  6318. %[@var{file}] @r{Insert the contents of the file given by @var{file}.}
  6319. %(@var{sexp}) @r{Evaluate Elisp @var{sexp} and replace with the result.}
  6320. @r{For convenience, %:keyword (see below) placeholders}
  6321. @r{within the expression will be expanded prior to this.}
  6322. @r{The sexp must return a string.}
  6323. %<...> @r{The result of format-time-string on the ... format specification.}
  6324. %t @r{Timestamp, date only.}
  6325. %T @r{Timestamp, with date and time.}
  6326. %u, %U @r{Like the above, but inactive timestamps.}
  6327. %i @r{Initial content, the region when capture is called while the}
  6328. @r{region is active.}
  6329. @r{The entire text will be indented like @code{%i} itself.}
  6330. %a @r{Annotation, normally the link created with @code{org-store-link}.}
  6331. %A @r{Like @code{%a}, but prompt for the description part.}
  6332. %l @r{Like %a, but only insert the literal link.}
  6333. %c @r{Current kill ring head.}
  6334. %x @r{Content of the X clipboard.}
  6335. %k @r{Title of the currently clocked task.}
  6336. %K @r{Link to the currently clocked task.}
  6337. %n @r{User name (taken from @code{user-full-name}).}
  6338. %f @r{File visited by current buffer when org-capture was called.}
  6339. %F @r{Full path of the file or directory visited by current buffer.}
  6340. %:keyword @r{Specific information for certain link types, see below.}
  6341. %^g @r{Prompt for tags, with completion on tags in target file.}
  6342. %^G @r{Prompt for tags, with completion all tags in all agenda files.}
  6343. %^t @r{Like @code{%t}, but prompt for date. Similarly @code{%^T}, @code{%^u}, @code{%^U}.}
  6344. @r{You may define a prompt like @code{%^@{Birthday@}t}.}
  6345. %^C @r{Interactive selection of which kill or clip to use.}
  6346. %^L @r{Like @code{%^C}, but insert as link.}
  6347. %^@{@var{prop}@}p @r{Prompt the user for a value for property @var{prop}.}
  6348. %^@{@var{prompt}@} @r{prompt the user for a string and replace this sequence with it.}
  6349. @r{You may specify a default value and a completion table with}
  6350. @r{%^@{prompt|default|completion2|completion3...@}.}
  6351. @r{The arrow keys access a prompt-specific history.}
  6352. %\1 @dots{} %\N @r{Insert the text entered at the Nth %^@{@var{prompt}@}, where @code{N} is}
  6353. @r{a number, starting from 1.@footnote{As required in Emacs
  6354. Lisp, it is necessary to escape any backslash character in
  6355. a string with another backslash. So, in order to use
  6356. @samp{%\1} placeholder, you need to write @samp{%\\1} in
  6357. the template.}}
  6358. %? @r{After completing the template, position cursor here.}
  6359. @end smallexample
  6360. @noindent
  6361. For specific link types, the following keywords will be
  6362. defined@footnote{If you define your own link types (@pxref{Adding
  6363. hyperlink types}), any property you store with
  6364. @code{org-store-link-props} can be accessed in capture templates in a
  6365. similar way.}:
  6366. @vindex org-from-is-user-regexp
  6367. @smallexample
  6368. Link type | Available keywords
  6369. ---------------------------------+----------------------------------------------
  6370. bbdb | %:name %:company
  6371. irc | %:server %:port %:nick
  6372. vm, vm-imap, wl, mh, mew, rmail, | %:type %:subject %:message-id
  6373. gnus, notmuch | %:from %:fromname %:fromaddress
  6374. | %:to %:toname %:toaddress
  6375. | %:date @r{(message date header field)}
  6376. | %:date-timestamp @r{(date as active timestamp)}
  6377. | %:date-timestamp-inactive @r{(date as inactive timestamp)}
  6378. | %:fromto @r{(either "to NAME" or "from NAME")@footnote{This will always be the other, not the user. See the variable @code{org-from-is-user-regexp}.}}
  6379. gnus | %:group, @r{for messages also all email fields}
  6380. eww, w3, w3m | %:url
  6381. info | %:file %:node
  6382. calendar | %:date
  6383. @end smallexample
  6384. @noindent
  6385. To place the cursor after template expansion use:
  6386. @smallexample
  6387. %? @r{After completing the template, position cursor here.}
  6388. @end smallexample
  6389. @node Templates in contexts
  6390. @subsubsection Templates in contexts
  6391. @vindex org-capture-templates-contexts
  6392. To control whether a capture template should be accessible from a specific
  6393. context, you can customize @code{org-capture-templates-contexts}. Let's say
  6394. for example that you have a capture template @code{"p"} for storing Gnus
  6395. emails containing patches. Then you would configure this option like this:
  6396. @smalllisp
  6397. (setq org-capture-templates-contexts
  6398. '(("p" (in-mode . "message-mode"))))
  6399. @end smalllisp
  6400. You can also tell that the command key @code{"p"} should refer to another
  6401. template. In that case, add this command key like this:
  6402. @smalllisp
  6403. (setq org-capture-templates-contexts
  6404. '(("p" "q" (in-mode . "message-mode"))))
  6405. @end smalllisp
  6406. See the docstring of the variable for more information.
  6407. @node Attachments
  6408. @section Attachments
  6409. @cindex attachments
  6410. @vindex org-attach-directory
  6411. It is often useful to associate reference material with an outline node/task.
  6412. Small chunks of plain text can simply be stored in the subtree of a project.
  6413. Hyperlinks (@pxref{Hyperlinks}) can establish associations with
  6414. files that live elsewhere on your computer or in the cloud, like emails or
  6415. source code files belonging to a project. Another method is @i{attachments},
  6416. which are files located in a directory belonging to an outline node. Org
  6417. uses directories named by the unique ID of each entry. These directories are
  6418. located in the @file{data} directory which lives in the same directory where
  6419. your Org file lives@footnote{If you move entries or Org files from one
  6420. directory to another, you may want to configure @code{org-attach-directory}
  6421. to contain an absolute path.}. If you initialize this directory with
  6422. @code{git init}, Org will automatically commit changes when it sees them.
  6423. The attachment system has been contributed to Org by John Wiegley.
  6424. In cases where it seems better to do so, you can also attach a directory of your
  6425. choice to an entry. You can also make children inherit the attachment
  6426. directory from a parent, so that an entire subtree uses the same attached
  6427. directory.
  6428. @noindent The following commands deal with attachments:
  6429. @table @kbd
  6430. @orgcmd{C-c C-a,org-attach}
  6431. The dispatcher for commands related to the attachment system. After these
  6432. keys, a list of commands is displayed and you must press an additional key
  6433. to select a command:
  6434. @table @kbd
  6435. @orgcmdtkc{a,C-c C-a a,org-attach-attach}
  6436. @vindex org-attach-method
  6437. Select a file and move it into the task's attachment directory. The file
  6438. will be copied, moved, or linked, depending on @code{org-attach-method}.
  6439. Note that hard links are not supported on all systems.
  6440. @kindex C-c C-a c
  6441. @kindex C-c C-a m
  6442. @kindex C-c C-a l
  6443. @item c/m/l
  6444. Attach a file using the copy/move/link method.
  6445. Note that hard links are not supported on all systems.
  6446. @orgcmdtkc{u,C-c C-a u,org-attach-url}
  6447. Attach a file from URL
  6448. @orgcmdtkc{n,C-c C-a n,org-attach-new}
  6449. Create a new attachment as an Emacs buffer.
  6450. @orgcmdtkc{z,C-c C-a z,org-attach-sync}
  6451. Synchronize the current task with its attachment directory, in case you added
  6452. attachments yourself.
  6453. @orgcmdtkc{o,C-c C-a o,org-attach-open}
  6454. @vindex org-file-apps
  6455. Open current task's attachment. If there is more than one, prompt for a
  6456. file name first. Opening will follow the rules set by @code{org-file-apps}.
  6457. For more details, see the information on following hyperlinks
  6458. (@pxref{Handling links}).
  6459. @orgcmdtkc{O,C-c C-a O,org-attach-open-in-emacs}
  6460. Also open the attachment, but force opening the file in Emacs.
  6461. @orgcmdtkc{f,C-c C-a f,org-attach-reveal}
  6462. Open the current task's attachment directory.
  6463. @orgcmdtkc{F,C-c C-a F,org-attach-reveal-in-emacs}
  6464. Also open the directory, but force using @command{dired} in Emacs.
  6465. @orgcmdtkc{d,C-c C-a d,org-attach-delete-one}
  6466. Select and delete a single attachment.
  6467. @orgcmdtkc{D,C-c C-a D,org-attach-delete-all}
  6468. Delete all of a task's attachments. A safer way is to open the directory in
  6469. @command{dired} and delete from there.
  6470. @orgcmdtkc{s,C-c C-a s,org-attach-set-directory}
  6471. @cindex property, ATTACH_DIR
  6472. Set a specific directory as the entry's attachment directory. This works by
  6473. putting the directory path into the @code{ATTACH_DIR} property.
  6474. @orgcmdtkc{i,C-c C-a i,org-attach-set-inherit}
  6475. @cindex property, ATTACH_DIR_INHERIT
  6476. Set the @code{ATTACH_DIR_INHERIT} property, so that children will use the
  6477. same directory for attachments as the parent does.
  6478. @end table
  6479. @end table
  6480. @node RSS feeds
  6481. @section RSS feeds
  6482. @cindex RSS feeds
  6483. @cindex Atom feeds
  6484. Org can add and change entries based on information found in RSS feeds and
  6485. Atom feeds. You could use this to make a task out of each new podcast in a
  6486. podcast feed. Or you could use a phone-based note-creating service on the
  6487. web to import tasks into Org. To access feeds, configure the variable
  6488. @code{org-feed-alist}. The docstring of this variable has detailed
  6489. information. Here is just an example:
  6490. @smalllisp
  6491. @group
  6492. (setq org-feed-alist
  6493. '(("Slashdot"
  6494. "http://rss.slashdot.org/Slashdot/slashdot"
  6495. "~/txt/org/feeds.org" "Slashdot Entries")))
  6496. @end group
  6497. @end smalllisp
  6498. @noindent
  6499. will configure that new items from the feed provided by
  6500. @code{rss.slashdot.org} will result in new entries in the file
  6501. @file{~/org/feeds.org} under the heading @samp{Slashdot Entries}, whenever
  6502. the following command is used:
  6503. @table @kbd
  6504. @orgcmd{C-c C-x g,org-feed-update-all}
  6505. @item C-c C-x g
  6506. Collect items from the feeds configured in @code{org-feed-alist} and act upon
  6507. them.
  6508. @orgcmd{C-c C-x G,org-feed-goto-inbox}
  6509. Prompt for a feed name and go to the inbox configured for this feed.
  6510. @end table
  6511. Under the same headline, Org will create a drawer @samp{FEEDSTATUS} in which
  6512. it will store information about the status of items in the feed, to avoid
  6513. adding the same item several times.
  6514. For more information, including how to read atom feeds, see
  6515. @file{org-feed.el} and the docstring of @code{org-feed-alist}.
  6516. @node Protocols
  6517. @section Protocols for external access
  6518. @cindex protocols, for external access
  6519. Org protocol is a mean to trigger custom actions in Emacs from external
  6520. applications. Any application that supports calling external programs with
  6521. an URL as argument may be used with this functionality. For example, you can
  6522. configure bookmarks in your web browser to send a link to the current page to
  6523. Org and create a note from it using capture (@pxref{Capture}). You can also
  6524. create a bookmark that tells Emacs to open the local source file of a remote
  6525. website you are browsing.
  6526. @cindex Org protocol, set-up
  6527. @cindex Installing Org protocol
  6528. In order to use Org protocol from an application, you need to register
  6529. @samp{org-protocol://} as a valid scheme-handler. External calls are passed
  6530. to Emacs through the @code{emacsclient} command, so you also need to ensure
  6531. an Emacs server is running. More precisely, when the application calls
  6532. @example
  6533. emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2
  6534. @end example
  6535. @noindent
  6536. Emacs calls the handler associated to @samp{PROTOCOL} with argument
  6537. @samp{(:key1 val1 :key2 val2)}.
  6538. @cindex protocol, new protocol
  6539. @cindex defining new protocols
  6540. Org protocol comes with three predefined protocols, detailed in the following
  6541. sections. Configure @code{org-protocol-protocol-alist} to define your own.
  6542. @menu
  6543. * @code{store-link} protocol:: Store a link, push URL to kill-ring.
  6544. * @code{capture} protocol:: Fill a buffer with external information.
  6545. * @code{open-source} protocol:: Edit published contents.
  6546. @end menu
  6547. @node @code{store-link} protocol
  6548. @subsection @code{store-link} protocol
  6549. @cindex store-link protocol
  6550. @cindex protocol, store-link
  6551. Using @code{store-link} handler, you can copy links, insertable through
  6552. @kbd{M-x org-insert-link} or yanking thereafter. More precisely, the command
  6553. @example
  6554. emacsclient org-protocol://store-link?url=URL&title=TITLE
  6555. @end example
  6556. @noindent
  6557. stores the following link:
  6558. @example
  6559. [[URL][TITLE]]
  6560. @end example
  6561. In addition, @samp{URL} is pushed on the kill-ring for yanking. You need to
  6562. encode @samp{URL} and @samp{TITLE} if they contain slashes, and probably
  6563. quote those for the shell.
  6564. To use this feature from a browser, add a bookmark with an arbitrary name,
  6565. e.g., @samp{Org: store-link} and enter this as @emph{Location}:
  6566. @example
  6567. javascript:location.href='org-protocol://store-link?url='+
  6568. encodeURIComponent(location.href);
  6569. @end example
  6570. @node @code{capture} protocol
  6571. @subsection @code{capture} protocol
  6572. @cindex capture protocol
  6573. @cindex protocol, capture
  6574. @cindex capture, %:url placeholder
  6575. @cindex %:url template expansion in capture
  6576. @cindex capture, %:title placeholder
  6577. @cindex %:title template expansion in capture
  6578. Activating @code{capture} handler pops up a @samp{Capture} buffer and fills
  6579. the capture template associated to the @samp{X} key with them. The template
  6580. refers to the data through @code{%:url} and @code{%:title} placeholders.
  6581. Moreover, any selected text in the browser is appended to the body of the
  6582. entry.
  6583. @example
  6584. emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY
  6585. @end example
  6586. To use this feature, add a bookmark with an arbitrary name, e.g.
  6587. @samp{Org: capture} and enter this as @samp{Location}:
  6588. @example
  6589. javascript:location.href='org-protocol://template=x'+
  6590. '&url='+encodeURIComponent(window.location.href)+
  6591. '&title='+encodeURIComponent(document.title)+
  6592. '&body='+encodeURIComponent(window.getSelection());
  6593. @end example
  6594. @vindex org-protocol-default-template-key
  6595. The result depends on the capture template used, which is set in the bookmark
  6596. itself, as in the example above, or in
  6597. @code{org-protocol-default-template-key}.
  6598. @node @code{open-source} protocol
  6599. @subsection @code{open-source} protocol
  6600. @cindex open-source protocol
  6601. @cindex protocol, open-source
  6602. The @code{open-source} handler is designed to help with editing local sources
  6603. when reading a document. To that effect, you can use a bookmark with the
  6604. following location:
  6605. @example
  6606. javascript:location.href='org-protocol://open-source?&url='+
  6607. encodeURIComponent(location.href)
  6608. @end example
  6609. @cindex protocol, open-source, :base-url property
  6610. @cindex :base-url property in open-source protocol
  6611. @cindex protocol, open-source, :working-directory property
  6612. @cindex :working-directory property in open-source protocol
  6613. @cindex protocol, open-source, :online-suffix property
  6614. @cindex :online-suffix property in open-source protocol
  6615. @cindex protocol, open-source, :working-suffix property
  6616. @cindex :working-suffix property in open-source protocol
  6617. @vindex org-protocol-project-alist
  6618. The variable @code{org-protocol-project-alist} maps URLs to local file names,
  6619. by stripping URL parameters from the end and replacing the @code{:base-url}
  6620. with @code{:working-directory} and @code{:online-suffix} with
  6621. @code{:working-suffix}. For example, assuming you own a local copy of
  6622. @url{http://orgmode.org/worg/} contents at @file{/home/user/worg}, you can
  6623. set @code{org-protocol-project-alist} to the following
  6624. @lisp
  6625. (setq org-protocol-project-alist
  6626. '(("Worg"
  6627. :base-url "http://orgmode.org/worg/"
  6628. :working-directory "/home/user/worg/"
  6629. :online-suffix ".html"
  6630. :working-suffix ".org")))
  6631. @end lisp
  6632. @noindent
  6633. If you are now browsing
  6634. @url{http://orgmode.org/worg/org-contrib/org-protocol.html} and find a typo
  6635. or have an idea about how to enhance the documentation, simply click the
  6636. bookmark and start editing.
  6637. @cindex handle rewritten URL in open-source protocol
  6638. @cindex protocol, open-source rewritten URL
  6639. However, such mapping may not yield the desired results. Suppose you
  6640. maintain an online store located at @url{http://example.com/}. The local
  6641. sources reside in @file{/home/user/example/}. It is common practice to serve
  6642. all products in such a store through one file and rewrite URLs that do not
  6643. match an existing file on the server. That way, a request to
  6644. @url{http://example.com/print/posters.html} might be rewritten on the server
  6645. to something like
  6646. @url{http://example.com/shop/products.php/posters.html.php}. The
  6647. @code{open-source} handler probably cannot find a file named
  6648. @file{/home/user/example/print/posters.html.php} and fails.
  6649. @cindex protocol, open-source, :rewrites property
  6650. @cindex :rewrites property in open-source protocol
  6651. Such an entry in @code{org-protocol-project-alist} may hold an additional
  6652. property @code{:rewrites}. This property is a list of cons cells, each of
  6653. which maps a regular expression to a path relative to the
  6654. @code{:working-directory}.
  6655. Now map the URL to the path @file{/home/user/example/products.php} by adding
  6656. @code{:rewrites} rules like this:
  6657. @lisp
  6658. (setq org-protocol-project-alist
  6659. '(("example.com"
  6660. :base-url "http://example.com/"
  6661. :working-directory "/home/user/example/"
  6662. :online-suffix ".php"
  6663. :working-suffix ".php"
  6664. :rewrites (("example.com/print/" . "products.php")
  6665. ("example.com/$" . "index.php")))))
  6666. @end lisp
  6667. @noindent
  6668. Since @samp{example.com/$} is used as a regular expression, it maps
  6669. @url{http://example.com/}, @url{https://example.com},
  6670. @url{http://www.example.com/} and similar to
  6671. @file{/home/user/example/index.php}.
  6672. The @code{:rewrites} rules are searched as a last resort if and only if no
  6673. existing file name is matched.
  6674. @cindex protocol, open-source, set-up mapping
  6675. @cindex set-up mappings in open-source protocol
  6676. @findex org-protocol-create
  6677. @findex org-protocol-create-for-org
  6678. Two functions can help you filling @code{org-protocol-project-alist} with
  6679. valid contents: @code{org-protocol-create} and
  6680. @code{org-protocol-create-for-org}. The latter is of use if you're editing
  6681. an Org file that is part of a publishing project.
  6682. @node Refile and copy
  6683. @section Refile and copy
  6684. @cindex refiling notes
  6685. @cindex copying notes
  6686. When reviewing the captured data, you may want to refile or to copy some of
  6687. the entries into a different list, for example into a project. Cutting,
  6688. finding the right location, and then pasting the note is cumbersome. To
  6689. simplify this process, you can use the following special command:
  6690. @table @kbd
  6691. @orgcmd{C-c M-w,org-copy}
  6692. @findex org-copy
  6693. Copying works like refiling, except that the original note is not deleted.
  6694. @orgcmd{C-c C-w,org-refile}
  6695. @findex org-refile
  6696. @vindex org-reverse-note-order
  6697. @vindex org-refile-targets
  6698. @vindex org-refile-use-outline-path
  6699. @vindex org-outline-path-complete-in-steps
  6700. @vindex org-refile-allow-creating-parent-nodes
  6701. @vindex org-log-refile
  6702. @vindex org-refile-use-cache
  6703. @vindex org-refile-keep
  6704. Refile the entry or region at point. This command offers possible locations
  6705. for refiling the entry and lets you select one with completion. The item (or
  6706. all items in the region) is filed below the target heading as a subitem.
  6707. Depending on @code{org-reverse-note-order}, it will be either the first or
  6708. last subitem.@*
  6709. By default, all level 1 headlines in the current buffer are considered to be
  6710. targets, but you can have more complex definitions across a number of files.
  6711. See the variable @code{org-refile-targets} for details. If you would like to
  6712. select a location via a file-path-like completion along the outline path, see
  6713. the variables @code{org-refile-use-outline-path} and
  6714. @code{org-outline-path-complete-in-steps}. If you would like to be able to
  6715. create new nodes as new parents for refiling on the fly, check the
  6716. variable @code{org-refile-allow-creating-parent-nodes}.
  6717. When the variable @code{org-log-refile}@footnote{with corresponding
  6718. @code{#+STARTUP} keywords @code{logrefile}, @code{lognoterefile},
  6719. and @code{nologrefile}} is set, a timestamp or a note will be
  6720. recorded when an entry has been refiled.
  6721. @orgkey{C-u C-c C-w}
  6722. Use the refile interface to jump to a heading.
  6723. @orgcmd{C-u C-u C-c C-w,org-refile-goto-last-stored}
  6724. Jump to the location where @code{org-refile} last moved a tree to.
  6725. @item C-2 C-c C-w
  6726. Refile as the child of the item currently being clocked.
  6727. @item C-3 C-c C-w
  6728. Refile and keep the entry in place. Also see @code{org-refile-keep} to make
  6729. this the default behavior, and beware that this may result in duplicated
  6730. @code{ID} properties.
  6731. @orgcmdtkc{C-0 C-c C-w @ @r{or} @ C-u C-u C-u C-c C-w,C-0 C-c C-w,org-refile-cache-clear}
  6732. Clear the target cache. Caching of refile targets can be turned on by
  6733. setting @code{org-refile-use-cache}. To make the command see new possible
  6734. targets, you have to clear the cache with this command.
  6735. @end table
  6736. @node Archiving
  6737. @section Archiving
  6738. @cindex archiving
  6739. When a project represented by a (sub)tree is finished, you may want
  6740. to move the tree out of the way and to stop it from contributing to the
  6741. agenda. Archiving is important to keep your working files compact and global
  6742. searches like the construction of agenda views fast.
  6743. @table @kbd
  6744. @orgcmd{C-c C-x C-a,org-archive-subtree-default}
  6745. @vindex org-archive-default-command
  6746. Archive the current entry using the command specified in the variable
  6747. @code{org-archive-default-command}.
  6748. @end table
  6749. @menu
  6750. * Moving subtrees:: Moving a tree to an archive file
  6751. * Internal archiving:: Switch off a tree but keep it in the file
  6752. @end menu
  6753. @node Moving subtrees
  6754. @subsection Moving a tree to the archive file
  6755. @cindex external archiving
  6756. The most common archiving action is to move a project tree to another file,
  6757. the archive file.
  6758. @table @kbd
  6759. @orgcmdkskc{C-c C-x C-s,C-c $,org-archive-subtree}
  6760. @vindex org-archive-location
  6761. Archive the subtree starting at the cursor position to the location
  6762. given by @code{org-archive-location}.
  6763. @orgkey{C-u C-c C-x C-s}
  6764. Check if any direct children of the current headline could be moved to
  6765. the archive. To do this, each subtree is checked for open TODO entries.
  6766. If none are found, the command offers to move it to the archive
  6767. location. If the cursor is @emph{not} on a headline when this command
  6768. is invoked, the level 1 trees will be checked.
  6769. @orgkey{C-u C-u C-c C-x C-s}
  6770. As above, but check subtree for timestamps instead of TODO entries. The
  6771. command will offer to archive the subtree if it @emph{does} contain a
  6772. timestamp, and that timestamp is in the past.
  6773. @end table
  6774. @cindex archive locations
  6775. The default archive location is a file in the same directory as the
  6776. current file, with the name derived by appending @file{_archive} to the
  6777. current file name. You can also choose what heading to file archived
  6778. items under, with the possibility to add them to a datetree in a file.
  6779. For information and examples on how to specify the file and the heading,
  6780. see the documentation string of the variable
  6781. @code{org-archive-location}.
  6782. There is also an in-buffer option for setting this variable, for example:
  6783. @cindex #+ARCHIVE
  6784. @example
  6785. #+ARCHIVE: %s_done::
  6786. @end example
  6787. @cindex property, ARCHIVE
  6788. @noindent
  6789. If you would like to have a special ARCHIVE location for a single entry
  6790. or a (sub)tree, give the entry an @code{:ARCHIVE:} property with the
  6791. location as the value (@pxref{Properties and columns}).
  6792. @vindex org-archive-save-context-info
  6793. When a subtree is moved, it receives a number of special properties that
  6794. record context information like the file from where the entry came, its
  6795. outline path the archiving time etc. Configure the variable
  6796. @code{org-archive-save-context-info} to adjust the amount of information
  6797. added.
  6798. @node Internal archiving
  6799. @subsection Internal archiving
  6800. @cindex archive tag
  6801. If you want to just switch off---for agenda views---certain subtrees without
  6802. moving them to a different file, you can use the archive tag.
  6803. A headline that is marked with the @samp{:ARCHIVE:} tag (@pxref{Tags}) stays
  6804. at its location in the outline tree, but behaves in the following way:
  6805. @itemize @minus
  6806. @item
  6807. @vindex org-cycle-open-archived-trees
  6808. It does not open when you attempt to do so with a visibility cycling
  6809. command (@pxref{Visibility cycling}). You can force cycling archived
  6810. subtrees with @kbd{C-@key{TAB}}, or by setting the option
  6811. @code{org-cycle-open-archived-trees}. Also normal outline commands like
  6812. @code{show-all} will open archived subtrees.
  6813. @item
  6814. @vindex org-sparse-tree-open-archived-trees
  6815. During sparse tree construction (@pxref{Sparse trees}), matches in
  6816. archived subtrees are not exposed, unless you configure the option
  6817. @code{org-sparse-tree-open-archived-trees}.
  6818. @item
  6819. @vindex org-agenda-skip-archived-trees
  6820. During agenda view construction (@pxref{Agenda views}), the content of
  6821. archived trees is ignored unless you configure the option
  6822. @code{org-agenda-skip-archived-trees}, in which case these trees will always
  6823. be included. In the agenda you can press @kbd{v a} to get archives
  6824. temporarily included.
  6825. @item
  6826. @vindex org-export-with-archived-trees
  6827. Archived trees are not exported (@pxref{Exporting}), only the headline
  6828. is. Configure the details using the variable
  6829. @code{org-export-with-archived-trees}.
  6830. @item
  6831. @vindex org-columns-skip-archived-trees
  6832. Archived trees are excluded from column view unless the variable
  6833. @code{org-columns-skip-archived-trees} is configured to @code{nil}.
  6834. @end itemize
  6835. The following commands help manage the ARCHIVE tag:
  6836. @table @kbd
  6837. @orgcmd{C-c C-x a,org-toggle-archive-tag}
  6838. Toggle the ARCHIVE tag for the current headline. When the tag is set,
  6839. the headline changes to a shadowed face, and the subtree below it is
  6840. hidden.
  6841. @orgkey{C-u C-c C-x a}
  6842. Check if any direct children of the current headline should be archived.
  6843. To do this, each subtree is checked for open TODO entries. If none are
  6844. found, the command offers to set the ARCHIVE tag for the child. If the
  6845. cursor is @emph{not} on a headline when this command is invoked, the
  6846. level 1 trees will be checked.
  6847. @orgcmd{C-@kbd{TAB},org-force-cycle-archived}
  6848. Cycle a tree even if it is tagged with ARCHIVE.
  6849. @orgcmd{C-c C-x A,org-archive-to-archive-sibling}
  6850. Move the current entry to the @emph{Archive Sibling}. This is a sibling of
  6851. the entry with the heading @samp{Archive} and the tag @samp{ARCHIVE}. The
  6852. entry becomes a child of that sibling and in this way retains a lot of its
  6853. original context, including inherited tags and approximate position in the
  6854. outline.
  6855. @end table
  6856. @node Agenda views
  6857. @chapter Agenda views
  6858. @cindex agenda views
  6859. Due to the way Org works, TODO items, time-stamped items, and
  6860. tagged headlines can be scattered throughout a file or even a number of
  6861. files. To get an overview of open action items, or of events that are
  6862. important for a particular date, this information must be collected,
  6863. sorted and displayed in an organized way.
  6864. Org can select items based on various criteria and display them
  6865. in a separate buffer. Six different view types are provided:
  6866. @itemize @bullet
  6867. @item
  6868. an @emph{agenda} that is like a calendar and shows information
  6869. for specific dates,
  6870. @item
  6871. a @emph{TODO list} that covers all unfinished
  6872. action items,
  6873. @item
  6874. a @emph{match view}, showings headlines based on the tags, properties, and
  6875. TODO state associated with them,
  6876. @item
  6877. a @emph{text search view} that shows all entries from multiple files
  6878. that contain specified keywords,
  6879. @item
  6880. a @emph{stuck projects view} showing projects that currently don't move
  6881. along, and
  6882. @item
  6883. @emph{custom views} that are special searches and combinations of different
  6884. views.
  6885. @end itemize
  6886. @noindent
  6887. The extracted information is displayed in a special @emph{agenda
  6888. buffer}. This buffer is read-only, but provides commands to visit the
  6889. corresponding locations in the original Org files, and even to
  6890. edit these files remotely.
  6891. @vindex org-agenda-skip-comment-trees
  6892. @vindex org-agenda-skip-archived-trees
  6893. @cindex commented entries, in agenda views
  6894. @cindex archived entries, in agenda views
  6895. By default, the report ignores commented (@pxref{Comment lines}) and archived
  6896. (@pxref{Internal archiving}) entries. You can override this by setting
  6897. @code{org-agenda-skip-comment-trees} and
  6898. @code{org-agenda-skip-archived-trees} to @code{nil}.
  6899. @vindex org-agenda-window-setup
  6900. @vindex org-agenda-restore-windows-after-quit
  6901. Two variables control how the agenda buffer is displayed and whether the
  6902. window configuration is restored when the agenda exits:
  6903. @code{org-agenda-window-setup} and
  6904. @code{org-agenda-restore-windows-after-quit}.
  6905. @menu
  6906. * Agenda files:: Files being searched for agenda information
  6907. * Agenda dispatcher:: Keyboard access to agenda views
  6908. * Built-in agenda views:: What is available out of the box?
  6909. * Presentation and sorting:: How agenda items are prepared for display
  6910. * Agenda commands:: Remote editing of Org trees
  6911. * Custom agenda views:: Defining special searches and views
  6912. * Exporting agenda views:: Writing a view to a file
  6913. * Agenda column view:: Using column view for collected entries
  6914. @end menu
  6915. @node Agenda files
  6916. @section Agenda files
  6917. @cindex agenda files
  6918. @cindex files for agenda
  6919. @vindex org-agenda-files
  6920. The information to be shown is normally collected from all @emph{agenda
  6921. files}, the files listed in the variable
  6922. @code{org-agenda-files}@footnote{If the value of that variable is not a
  6923. list, but a single file name, then the list of agenda files will be
  6924. maintained in that external file.}. If a directory is part of this list,
  6925. all files with the extension @file{.org} in this directory will be part
  6926. of the list.
  6927. Thus, even if you only work with a single Org file, that file should
  6928. be put into the list@footnote{When using the dispatcher, pressing
  6929. @kbd{<} before selecting a command will actually limit the command to
  6930. the current file, and ignore @code{org-agenda-files} until the next
  6931. dispatcher command.}. You can customize @code{org-agenda-files}, but
  6932. the easiest way to maintain it is through the following commands
  6933. @cindex files, adding to agenda list
  6934. @table @kbd
  6935. @orgcmd{C-c [,org-agenda-file-to-front}
  6936. Add current file to the list of agenda files. The file is added to
  6937. the front of the list. If it was already in the list, it is moved to
  6938. the front. With a prefix argument, file is added/moved to the end.
  6939. @orgcmd{C-c ],org-remove-file}
  6940. Remove current file from the list of agenda files.
  6941. @kindex C-,
  6942. @cindex cycling, of agenda files
  6943. @orgcmd{C-',org-cycle-agenda-files}
  6944. @itemx C-,
  6945. Cycle through agenda file list, visiting one file after the other.
  6946. @kindex M-x org-iswitchb
  6947. @item M-x org-iswitchb RET
  6948. Command to use an @code{iswitchb}-like interface to switch to and between Org
  6949. buffers.
  6950. @end table
  6951. @noindent
  6952. The Org menu contains the current list of files and can be used
  6953. to visit any of them.
  6954. If you would like to focus the agenda temporarily on a file not in
  6955. this list, or on just one file in the list, or even on only a subtree in a
  6956. file, then this can be done in different ways. For a single agenda command,
  6957. you may press @kbd{<} once or several times in the dispatcher
  6958. (@pxref{Agenda dispatcher}). To restrict the agenda scope for an
  6959. extended period, use the following commands:
  6960. @table @kbd
  6961. @orgcmd{C-c C-x <,org-agenda-set-restriction-lock}
  6962. Permanently restrict the agenda to the current subtree. When with a
  6963. prefix argument, or with the cursor before the first headline in a file,
  6964. the agenda scope is set to the entire file. This restriction remains in
  6965. effect until removed with @kbd{C-c C-x >}, or by typing either @kbd{<}
  6966. or @kbd{>} in the agenda dispatcher. If there is a window displaying an
  6967. agenda view, the new restriction takes effect immediately.
  6968. @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
  6969. Remove the permanent restriction created by @kbd{C-c C-x <}.
  6970. @end table
  6971. @noindent
  6972. When working with @file{speedbar.el}, you can use the following commands in
  6973. the Speedbar frame:
  6974. @table @kbd
  6975. @orgcmdtkc{< @r{in the speedbar frame},<,org-speedbar-set-agenda-restriction}
  6976. Permanently restrict the agenda to the item---either an Org file or a subtree
  6977. in such a file---at the cursor in the Speedbar frame.
  6978. If there is a window displaying an agenda view, the new restriction takes
  6979. effect immediately.
  6980. @orgcmdtkc{> @r{in the speedbar frame},>,org-agenda-remove-restriction-lock}
  6981. Lift the restriction.
  6982. @end table
  6983. @node Agenda dispatcher
  6984. @section The agenda dispatcher
  6985. @cindex agenda dispatcher
  6986. @cindex dispatching agenda commands
  6987. The views are created through a dispatcher, which should be bound to a
  6988. global key---for example @kbd{C-c a} (@pxref{Activation}). In the
  6989. following we will assume that @kbd{C-c a} is indeed how the dispatcher
  6990. is accessed and list keyboard access to commands accordingly. After
  6991. pressing @kbd{C-c a}, an additional letter is required to execute a
  6992. command. The dispatcher offers the following default commands:
  6993. @table @kbd
  6994. @item a
  6995. Create the calendar-like agenda (@pxref{Weekly/daily agenda}).
  6996. @item t @r{/} T
  6997. Create a list of all TODO items (@pxref{Global TODO list}).
  6998. @item m @r{/} M
  6999. Create a list of headlines matching a TAGS expression (@pxref{Matching
  7000. tags and properties}).
  7001. @item s
  7002. Create a list of entries selected by a boolean expression of keywords
  7003. and/or regular expressions that must or must not occur in the entry.
  7004. @item /
  7005. @vindex org-agenda-text-search-extra-files
  7006. Search for a regular expression in all agenda files and additionally in
  7007. the files listed in @code{org-agenda-text-search-extra-files}. This
  7008. uses the Emacs command @code{multi-occur}. A prefix argument can be
  7009. used to specify the number of context lines for each match, default is
  7010. 1.
  7011. @item # @r{/} !
  7012. Create a list of stuck projects (@pxref{Stuck projects}).
  7013. @item <
  7014. Restrict an agenda command to the current buffer@footnote{For backward
  7015. compatibility, you can also press @kbd{1} to restrict to the current
  7016. buffer.}. After pressing @kbd{<}, you still need to press the character
  7017. selecting the command.
  7018. @item < <
  7019. If there is an active region, restrict the following agenda command to
  7020. the region. Otherwise, restrict it to the current subtree@footnote{For
  7021. backward compatibility, you can also press @kbd{0} to restrict to the
  7022. current region/subtree.}. After pressing @kbd{< <}, you still need to press the
  7023. character selecting the command.
  7024. @item *
  7025. @cindex agenda, sticky
  7026. @vindex org-agenda-sticky
  7027. Toggle sticky agenda views. By default, Org maintains only a single agenda
  7028. buffer and rebuilds it each time you change the view, to make sure everything
  7029. is always up to date. If you often switch between agenda views and the build
  7030. time bothers you, you can turn on sticky agenda buffers or make this the
  7031. default by customizing the variable @code{org-agenda-sticky}. With sticky
  7032. agendas, the agenda dispatcher will not recreate agenda views from scratch,
  7033. it will only switch to the selected one, and you need to update the agenda by
  7034. hand with @kbd{r} or @kbd{g} when needed. You can toggle sticky agenda view
  7035. any time with @code{org-toggle-sticky-agenda}.
  7036. @end table
  7037. You can also define custom commands that will be accessible through the
  7038. dispatcher, just like the default commands. This includes the
  7039. possibility to create extended agenda buffers that contain several
  7040. blocks together, for example the weekly agenda, the global TODO list and
  7041. a number of special tags matches. @xref{Custom agenda views}.
  7042. @node Built-in agenda views
  7043. @section The built-in agenda views
  7044. In this section we describe the built-in views.
  7045. @menu
  7046. * Weekly/daily agenda:: The calendar page with current tasks
  7047. * Global TODO list:: All unfinished action items
  7048. * Matching tags and properties:: Structured information with fine-tuned search
  7049. * Search view:: Find entries by searching for text
  7050. * Stuck projects:: Find projects you need to review
  7051. @end menu
  7052. @node Weekly/daily agenda
  7053. @subsection The weekly/daily agenda
  7054. @cindex agenda
  7055. @cindex weekly agenda
  7056. @cindex daily agenda
  7057. The purpose of the weekly/daily @emph{agenda} is to act like a page of a
  7058. paper agenda, showing all the tasks for the current week or day.
  7059. @table @kbd
  7060. @cindex org-agenda, command
  7061. @orgcmd{C-c a a,org-agenda-list}
  7062. Compile an agenda for the current week from a list of Org files. The agenda
  7063. shows the entries for each day. With a numeric prefix@footnote{For backward
  7064. compatibility, the universal prefix @kbd{C-u} causes all TODO entries to be
  7065. listed before the agenda. This feature is deprecated, use the dedicated TODO
  7066. list, or a block agenda instead (@pxref{Block agenda}).} (like @kbd{C-u 2 1
  7067. C-c a a}) you may set the number of days to be displayed.
  7068. @end table
  7069. @vindex org-agenda-span
  7070. @vindex org-agenda-ndays
  7071. @vindex org-agenda-start-day
  7072. @vindex org-agenda-start-on-weekday
  7073. The default number of days displayed in the agenda is set by the variable
  7074. @code{org-agenda-span} (or the obsolete @code{org-agenda-ndays}). This
  7075. variable can be set to any number of days you want to see by default in the
  7076. agenda, or to a span name, such as @code{day}, @code{week}, @code{month} or
  7077. @code{year}. For weekly agendas, the default is to start on the previous
  7078. monday (see @code{org-agenda-start-on-weekday}). You can also set the start
  7079. date using a date shift: @code{(setq org-agenda-start-day "+10d")} will
  7080. start the agenda ten days from today in the future.
  7081. Remote editing from the agenda buffer means, for example, that you can
  7082. change the dates of deadlines and appointments from the agenda buffer.
  7083. The commands available in the Agenda buffer are listed in @ref{Agenda
  7084. commands}.
  7085. @subsubheading Calendar/Diary integration
  7086. @cindex calendar integration
  7087. @cindex diary integration
  7088. Emacs contains the calendar and diary by Edward M. Reingold. The
  7089. calendar displays a three-month calendar with holidays from different
  7090. countries and cultures. The diary allows you to keep track of
  7091. anniversaries, lunar phases, sunrise/set, recurrent appointments
  7092. (weekly, monthly) and more. In this way, it is quite complementary to
  7093. Org. It can be very useful to combine output from Org with
  7094. the diary.
  7095. In order to include entries from the Emacs diary into Org mode's
  7096. agenda, you only need to customize the variable
  7097. @lisp
  7098. (setq org-agenda-include-diary t)
  7099. @end lisp
  7100. @noindent After that, everything will happen automatically. All diary
  7101. entries including holidays, anniversaries, etc., will be included in the
  7102. agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and
  7103. @key{RET} can be used from the agenda buffer to jump to the diary
  7104. file in order to edit existing diary entries. The @kbd{i} command to
  7105. insert new entries for the current date works in the agenda buffer, as
  7106. well as the commands @kbd{S}, @kbd{M}, and @kbd{C} to display
  7107. Sunrise/Sunset times, show lunar phases and to convert to other
  7108. calendars, respectively. @kbd{c} can be used to switch back and forth
  7109. between calendar and agenda.
  7110. If you are using the diary only for sexp entries and holidays, it is
  7111. faster to not use the above setting, but instead to copy or even move
  7112. the entries into an Org file. Org mode evaluates diary-style sexp
  7113. entries, and does it faster because there is no overhead for first
  7114. creating the diary display. Note that the sexp entries must start at
  7115. the left margin, no whitespace is allowed before them. For example,
  7116. the following segment of an Org file will be processed and entries
  7117. will be made in the agenda:
  7118. @example
  7119. * Holidays
  7120. :PROPERTIES:
  7121. :CATEGORY: Holiday
  7122. :END:
  7123. %%(org-calendar-holiday) ; special function for holiday names
  7124. * Birthdays
  7125. :PROPERTIES:
  7126. :CATEGORY: Ann
  7127. :END:
  7128. %%(org-anniversary 1956 5 14)@footnote{@code{org-anniversary} is just like @code{diary-anniversary}, but the argument order is always according to ISO and therefore independent of the value of @code{calendar-date-style}.} Arthur Dent is %d years old
  7129. %%(org-anniversary 1869 10 2) Mahatma Gandhi would be %d years old
  7130. @end example
  7131. @subsubheading Anniversaries from BBDB
  7132. @cindex BBDB, anniversaries
  7133. @cindex anniversaries, from BBDB
  7134. If you are using the Big Brothers Database to store your contacts, you will
  7135. very likely prefer to store anniversaries in BBDB rather than in a
  7136. separate Org or diary file. Org supports this and will show BBDB
  7137. anniversaries as part of the agenda. All you need to do is to add the
  7138. following to one of your agenda files:
  7139. @example
  7140. * Anniversaries
  7141. :PROPERTIES:
  7142. :CATEGORY: Anniv
  7143. :END:
  7144. %%(org-bbdb-anniversaries)
  7145. @end example
  7146. You can then go ahead and define anniversaries for a BBDB record. Basically,
  7147. you need to press @kbd{C-o anniversary @key{RET}} with the cursor in a BBDB
  7148. record and then add the date in the format @code{YYYY-MM-DD} or @code{MM-DD},
  7149. followed by a space and the class of the anniversary (@samp{birthday} or
  7150. @samp{wedding}, or a format string). If you omit the class, it will default to
  7151. @samp{birthday}. Here are a few examples, the header for the file
  7152. @file{org-bbdb.el} contains more detailed information.
  7153. @example
  7154. 1973-06-22
  7155. 06-22
  7156. 1955-08-02 wedding
  7157. 2008-04-14 %s released version 6.01 of org mode, %d years ago
  7158. @end example
  7159. After a change to BBDB, or for the first agenda display during an Emacs
  7160. session, the agenda display will suffer a short delay as Org updates its
  7161. hash with anniversaries. However, from then on things will be very fast---much
  7162. faster in fact than a long list of @samp{%%(diary-anniversary)} entries
  7163. in an Org or Diary file.
  7164. If you would like to see upcoming anniversaries with a bit of forewarning,
  7165. you can use the following instead:
  7166. @example
  7167. * Anniversaries
  7168. :PROPERTIES:
  7169. :CATEGORY: Anniv
  7170. :END:
  7171. %%(org-bbdb-anniversaries-future 3)
  7172. @end example
  7173. That will give you three days' warning: on the anniversary date itself and the
  7174. two days prior. The argument is optional: if omitted, it defaults to 7.
  7175. @subsubheading Appointment reminders
  7176. @cindex @file{appt.el}
  7177. @cindex appointment reminders
  7178. @cindex appointment
  7179. @cindex reminders
  7180. Org can interact with Emacs appointments notification facility. To add the
  7181. appointments of your agenda files, use the command @code{org-agenda-to-appt}.
  7182. This command lets you filter through the list of your appointments and add
  7183. only those belonging to a specific category or matching a regular expression.
  7184. It also reads a @code{APPT_WARNTIME} property which will then override the
  7185. value of @code{appt-message-warning-time} for this appointment. See the
  7186. docstring for details.
  7187. @node Global TODO list
  7188. @subsection The global TODO list
  7189. @cindex global TODO list
  7190. @cindex TODO list, global
  7191. The global TODO list contains all unfinished TODO items formatted and
  7192. collected into a single place.
  7193. @table @kbd
  7194. @orgcmd{C-c a t,org-todo-list}
  7195. Show the global TODO list. This collects the TODO items from all agenda
  7196. files (@pxref{Agenda views}) into a single buffer. By default, this lists
  7197. items with a state the is not a DONE state. The buffer is in
  7198. @code{agenda-mode}, so there are commands to examine and manipulate the TODO
  7199. entries directly from that buffer (@pxref{Agenda commands}).
  7200. @orgcmd{C-c a T,org-todo-list}
  7201. @cindex TODO keyword matching
  7202. @vindex org-todo-keywords
  7203. Like the above, but allows selection of a specific TODO keyword. You can
  7204. also do this by specifying a prefix argument to @kbd{C-c a t}. You are
  7205. prompted for a keyword, and you may also specify several keywords by
  7206. separating them with @samp{|} as the boolean OR operator. With a numeric
  7207. prefix, the Nth keyword in @code{org-todo-keywords} is selected.
  7208. @kindex r
  7209. The @kbd{r} key in the agenda buffer regenerates it, and you can give
  7210. a prefix argument to this command to change the selected TODO keyword,
  7211. for example @kbd{3 r}. If you often need a search for a specific
  7212. keyword, define a custom command for it (@pxref{Agenda dispatcher}).@*
  7213. Matching specific TODO keywords can also be done as part of a tags
  7214. search (@pxref{Tag searches}).
  7215. @end table
  7216. Remote editing of TODO items means that you can change the state of a
  7217. TODO entry with a single key press. The commands available in the
  7218. TODO list are described in @ref{Agenda commands}.
  7219. @cindex sublevels, inclusion into TODO list
  7220. Normally the global TODO list simply shows all headlines with TODO
  7221. keywords. This list can become very long. There are two ways to keep
  7222. it more compact:
  7223. @itemize @minus
  7224. @item
  7225. @vindex org-agenda-todo-ignore-scheduled
  7226. @vindex org-agenda-todo-ignore-deadlines
  7227. @vindex org-agenda-todo-ignore-timestamp
  7228. @vindex org-agenda-todo-ignore-with-date
  7229. Some people view a TODO item that has been @emph{scheduled} for execution or
  7230. have a @emph{deadline} (@pxref{Timestamps}) as no longer @emph{open}.
  7231. Configure the variables @code{org-agenda-todo-ignore-scheduled},
  7232. @code{org-agenda-todo-ignore-deadlines},
  7233. @code{org-agenda-todo-ignore-timestamp} and/or
  7234. @code{org-agenda-todo-ignore-with-date} to exclude such items from the global
  7235. TODO list.
  7236. @item
  7237. @vindex org-agenda-todo-list-sublevels
  7238. TODO items may have sublevels to break up the task into subtasks. In
  7239. such cases it may be enough to list only the highest level TODO headline
  7240. and omit the sublevels from the global list. Configure the variable
  7241. @code{org-agenda-todo-list-sublevels} to get this behavior.
  7242. @end itemize
  7243. @node Matching tags and properties
  7244. @subsection Matching tags and properties
  7245. @cindex matching, of tags
  7246. @cindex matching, of properties
  7247. @cindex tags view
  7248. @cindex match view
  7249. If headlines in the agenda files are marked with @emph{tags} (@pxref{Tags}),
  7250. or have properties (@pxref{Properties and columns}), you can select headlines
  7251. based on this metadata and collect them into an agenda buffer. The match
  7252. syntax described here also applies when creating sparse trees with @kbd{C-c /
  7253. m}.
  7254. @table @kbd
  7255. @orgcmd{C-c a m,org-tags-view}
  7256. Produce a list of all headlines that match a given set of tags. The
  7257. command prompts for a selection criterion, which is a boolean logic
  7258. expression with tags, like @samp{+work+urgent-withboss} or
  7259. @samp{work|home} (@pxref{Tags}). If you often need a specific search,
  7260. define a custom command for it (@pxref{Agenda dispatcher}).
  7261. @orgcmd{C-c a M,org-tags-view}
  7262. @vindex org-tags-match-list-sublevels
  7263. @vindex org-agenda-tags-todo-honor-ignore-options
  7264. Like @kbd{C-c a m}, but only select headlines that are also TODO items in a
  7265. not-DONE state and force checking subitems (see variable
  7266. @code{org-tags-match-list-sublevels}). To exclude scheduled/deadline items,
  7267. see the variable @code{org-agenda-tags-todo-honor-ignore-options}. Matching
  7268. specific TODO keywords together with a tags match is also possible, see
  7269. @ref{Tag searches}.
  7270. @end table
  7271. The commands available in the tags list are described in @ref{Agenda
  7272. commands}.
  7273. @subsubheading Match syntax
  7274. @cindex Boolean logic, for tag/property searches
  7275. A search string can use Boolean operators @samp{&} for @code{AND} and
  7276. @samp{|} for @code{OR}@. @samp{&} binds more strongly than @samp{|}.
  7277. Parentheses are not implemented. Each element in the search is either a
  7278. tag, a regular expression matching tags, or an expression like
  7279. @code{PROPERTY OPERATOR VALUE} with a comparison operator, accessing a
  7280. property value. Each element may be preceded by @samp{-}, to select
  7281. against it, and @samp{+} is syntactic sugar for positive selection. The
  7282. @code{AND} operator @samp{&} is optional when @samp{+} or @samp{-} is
  7283. present. Here are some examples, using only tags.
  7284. @table @samp
  7285. @item work
  7286. Select headlines tagged @samp{:work:}.
  7287. @item work&boss
  7288. Select headlines tagged @samp{:work:} and @samp{:boss:}.
  7289. @item +work-boss
  7290. Select headlines tagged @samp{:work:}, but discard those also tagged
  7291. @samp{:boss:}.
  7292. @item work|laptop
  7293. Selects lines tagged @samp{:work:} or @samp{:laptop:}.
  7294. @item work|laptop+night
  7295. Like before, but require the @samp{:laptop:} lines to be tagged also
  7296. @samp{:night:}.
  7297. @end table
  7298. @cindex regular expressions, with tags search
  7299. Instead of a tag, you may also specify a regular expression enclosed in curly
  7300. braces. For example,
  7301. @samp{work+@{^boss.*@}} matches headlines that contain the tag
  7302. @samp{:work:} and any tag @i{starting} with @samp{boss}.
  7303. @cindex group tags, as regular expressions
  7304. Group tags (@pxref{Tag hierarchy}) are expanded as regular expressions. E.g.,
  7305. if @samp{:work:} is a group tag for the group @samp{:work:lab:conf:}, then
  7306. searching for @samp{work} will search for @samp{@{\(?:work\|lab\|conf\)@}}
  7307. and searching for @samp{-work} will search for all headlines but those with
  7308. one of the tags in the group (i.e., @samp{-@{\(?:work\|lab\|conf\)@}}).
  7309. @cindex TODO keyword matching, with tags search
  7310. @cindex level, require for tags/property match
  7311. @cindex category, require for tags/property match
  7312. @vindex org-odd-levels-only
  7313. You may also test for properties (@pxref{Properties and columns}) at the same
  7314. time as matching tags. The properties may be real properties, or special
  7315. properties that represent other metadata (@pxref{Special properties}). For
  7316. example, the ``property'' @code{TODO} represents the TODO keyword of the
  7317. entry and the ``property'' @code{PRIORITY} represents the PRIORITY keyword of
  7318. the entry.
  7319. In addition to the properties mentioned above, @code{LEVEL} represents the
  7320. level of an entry. So a search @samp{+LEVEL=3+boss-TODO="DONE"} lists all
  7321. level three headlines that have the tag @samp{boss} and are @emph{not} marked
  7322. with the TODO keyword DONE@. In buffers with @code{org-odd-levels-only} set,
  7323. @samp{LEVEL} does not count the number of stars, but @samp{LEVEL=2} will
  7324. correspond to 3 stars etc.
  7325. Here are more examples:
  7326. @table @samp
  7327. @item work+TODO="WAITING"
  7328. Select @samp{:work:}-tagged TODO lines with the specific TODO
  7329. keyword @samp{WAITING}.
  7330. @item work+TODO="WAITING"|home+TODO="WAITING"
  7331. Waiting tasks both at work and at home.
  7332. @end table
  7333. When matching properties, a number of different operators can be used to test
  7334. the value of a property. Here is a complex example:
  7335. @example
  7336. +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 \
  7337. +With=@{Sarah\|Denny@}+SCHEDULED>="<2008-10-11>"
  7338. @end example
  7339. @noindent
  7340. The type of comparison will depend on how the comparison value is written:
  7341. @itemize @minus
  7342. @item
  7343. If the comparison value is a plain number, a numerical comparison is done,
  7344. and the allowed operators are @samp{<}, @samp{=}, @samp{>}, @samp{<=},
  7345. @samp{>=}, and @samp{<>}.
  7346. @item
  7347. If the comparison value is enclosed in double-quotes,
  7348. a string comparison is done, and the same operators are allowed.
  7349. @item
  7350. If the comparison value is enclosed in double-quotes @emph{and} angular
  7351. brackets (like @samp{DEADLINE<="<2008-12-24 18:30>"}), both values are
  7352. assumed to be date/time specifications in the standard Org way, and the
  7353. comparison will be done accordingly. Special values that will be recognized
  7354. are @code{"<now>"} for now (including time), and @code{"<today>"}, and
  7355. @code{"<tomorrow>"} for these days at 00:00 hours, i.e., without a time
  7356. specification. Also strings like @code{"<+5d>"} or @code{"<-2m>"} with units
  7357. @code{d}, @code{w}, @code{m}, and @code{y} for day, week, month, and year,
  7358. respectively, can be used.
  7359. @item
  7360. If the comparison value is enclosed
  7361. in curly braces, a regexp match is performed, with @samp{=} meaning that the
  7362. regexp matches the property value, and @samp{<>} meaning that it does not
  7363. match.
  7364. @end itemize
  7365. So the search string in the example finds entries tagged @samp{:work:} but
  7366. not @samp{:boss:}, which also have a priority value @samp{A}, a
  7367. @samp{:Coffee:} property with the value @samp{unlimited}, an @samp{Effort}
  7368. property that is numerically smaller than 2, a @samp{:With:} property that is
  7369. matched by the regular expression @samp{Sarah\|Denny}, and that are scheduled
  7370. on or after October 11, 2008.
  7371. You can configure Org mode to use property inheritance during a search, but
  7372. beware that this can slow down searches considerably. See @ref{Property
  7373. inheritance}, for details.
  7374. For backward compatibility, and also for typing speed, there is also a
  7375. different way to test TODO states in a search. For this, terminate the
  7376. tags/property part of the search string (which may include several terms
  7377. connected with @samp{|}) with a @samp{/} and then specify a Boolean
  7378. expression just for TODO keywords. The syntax is then similar to that for
  7379. tags, but should be applied with care: for example, a positive selection on
  7380. several TODO keywords cannot meaningfully be combined with boolean AND@.
  7381. However, @emph{negative selection} combined with AND can be meaningful. To
  7382. make sure that only lines are checked that actually have any TODO keyword
  7383. (resulting in a speed-up), use @kbd{C-c a M}, or equivalently start the TODO
  7384. part after the slash with @samp{!}. Using @kbd{C-c a M} or @samp{/!} will
  7385. not match TODO keywords in a DONE state. Examples:
  7386. @table @samp
  7387. @item work/WAITING
  7388. Same as @samp{work+TODO="WAITING"}
  7389. @item work/!-WAITING-NEXT
  7390. Select @samp{:work:}-tagged TODO lines that are neither @samp{WAITING}
  7391. nor @samp{NEXT}
  7392. @item work/!+WAITING|+NEXT
  7393. Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or
  7394. @samp{NEXT}.
  7395. @end table
  7396. @node Search view
  7397. @subsection Search view
  7398. @cindex search view
  7399. @cindex text search
  7400. @cindex searching, for text
  7401. This agenda view is a general text search facility for Org mode entries.
  7402. It is particularly useful to find notes.
  7403. @table @kbd
  7404. @orgcmd{C-c a s,org-search-view}
  7405. This is a special search that lets you select entries by matching a substring
  7406. or specific words using a boolean logic.
  7407. @end table
  7408. For example, the search string @samp{computer equipment} will find entries
  7409. that contain @samp{computer equipment} as a substring. If the two words are
  7410. separated by more space or a line break, the search will still match.
  7411. Search view can also search for specific keywords in the entry, using Boolean
  7412. logic. The search string @samp{+computer +wifi -ethernet -@{8\.11[bg]@}}
  7413. will search for note entries that contain the keywords @code{computer}
  7414. and @code{wifi}, but not the keyword @code{ethernet}, and which are also
  7415. not matched by the regular expression @code{8\.11[bg]}, meaning to
  7416. exclude both 8.11b and 8.11g. The first @samp{+} is necessary to turn on
  7417. word search, other @samp{+} characters are optional. For more details, see
  7418. the docstring of the command @code{org-search-view}.
  7419. @vindex org-agenda-text-search-extra-files
  7420. Note that in addition to the agenda files, this command will also search
  7421. the files listed in @code{org-agenda-text-search-extra-files}.
  7422. @node Stuck projects
  7423. @subsection Stuck projects
  7424. @pindex GTD, Getting Things Done
  7425. If you are following a system like David Allen's GTD to organize your
  7426. work, one of the ``duties'' you have is a regular review to make sure
  7427. that all projects move along. A @emph{stuck} project is a project that
  7428. has no defined next actions, so it will never show up in the TODO lists
  7429. Org mode produces. During the review, you need to identify such
  7430. projects and define next actions for them.
  7431. @table @kbd
  7432. @orgcmd{C-c a #,org-agenda-list-stuck-projects}
  7433. List projects that are stuck.
  7434. @kindex C-c a !
  7435. @item C-c a !
  7436. @vindex org-stuck-projects
  7437. Customize the variable @code{org-stuck-projects} to define what a stuck
  7438. project is and how to find it.
  7439. @end table
  7440. You almost certainly will have to configure this view before it will
  7441. work for you. The built-in default assumes that all your projects are
  7442. level-2 headlines, and that a project is not stuck if it has at least
  7443. one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.
  7444. Let's assume that you, in your own way of using Org mode, identify
  7445. projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
  7446. indicate a project that should not be considered yet. Let's further
  7447. assume that the TODO keyword DONE marks finished projects, and that NEXT
  7448. and TODO indicate next actions. The tag @@SHOP indicates shopping and
  7449. is a next action even without the NEXT tag. Finally, if the project
  7450. contains the special word IGNORE anywhere, it should not be listed
  7451. either. In this case you would start by identifying eligible projects
  7452. with a tags/todo match@footnote{@xref{Tag searches}.}
  7453. @samp{+PROJECT/-MAYBE-DONE}, and then check for TODO, NEXT, @@SHOP, and
  7454. IGNORE in the subtree to identify projects that are not stuck. The
  7455. correct customization for this is
  7456. @lisp
  7457. (setq org-stuck-projects
  7458. '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@@SHOP")
  7459. "\\<IGNORE\\>"))
  7460. @end lisp
  7461. Note that if a project is identified as non-stuck, the subtree of this entry
  7462. will still be searched for stuck projects.
  7463. @node Presentation and sorting
  7464. @section Presentation and sorting
  7465. @cindex presentation, of agenda items
  7466. @vindex org-agenda-prefix-format
  7467. @vindex org-agenda-tags-column
  7468. Before displaying items in an agenda view, Org mode visually prepares the
  7469. items and sorts them. Each item occupies a single line. The line starts
  7470. with a @emph{prefix} that contains the @emph{category} (@pxref{Categories})
  7471. of the item and other important information. You can customize in which
  7472. column tags will be displayed through @code{org-agenda-tags-column}. You can
  7473. also customize the prefix using the option @code{org-agenda-prefix-format}.
  7474. This prefix is followed by a cleaned-up version of the outline headline
  7475. associated with the item.
  7476. @menu
  7477. * Categories:: Not all tasks are equal
  7478. * Time-of-day specifications:: How the agenda knows the time
  7479. * Sorting agenda items:: The order of things
  7480. * Filtering/limiting agenda items:: Dynamically narrow the agenda
  7481. @end menu
  7482. @node Categories
  7483. @subsection Categories
  7484. @cindex category
  7485. @cindex #+CATEGORY
  7486. The category is a broad label assigned to each agenda item. By default, the
  7487. category is simply derived from the file name, but you can also specify it
  7488. with a special line in the buffer, like this:
  7489. @example
  7490. #+CATEGORY: Thesis
  7491. @end example
  7492. @noindent
  7493. @cindex property, CATEGORY
  7494. If you would like to have a special CATEGORY for a single entry or a
  7495. (sub)tree, give the entry a @code{:CATEGORY:} property with the
  7496. special category you want to apply as the value.
  7497. @noindent
  7498. The display in the agenda buffer looks best if the category is not
  7499. longer than 10 characters.
  7500. @noindent
  7501. You can set up icons for category by customizing the
  7502. @code{org-agenda-category-icon-alist} variable.
  7503. @node Time-of-day specifications
  7504. @subsection Time-of-day specifications
  7505. @cindex time-of-day specification
  7506. Org mode checks each agenda item for a time-of-day specification. The
  7507. time can be part of the timestamp that triggered inclusion into the
  7508. agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time
  7509. ranges can be specified with two timestamps, like
  7510. @c
  7511. @w{@samp{<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>}}.
  7512. In the headline of the entry itself, a time(range) may also appear as
  7513. plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda
  7514. integrates the Emacs diary (@pxref{Weekly/daily agenda}), time
  7515. specifications in diary entries are recognized as well.
  7516. For agenda display, Org mode extracts the time and displays it in a
  7517. standard 24 hour format as part of the prefix. The example times in
  7518. the previous paragraphs would end up in the agenda like this:
  7519. @example
  7520. 8:30-13:00 Arthur Dent lies in front of the bulldozer
  7521. 12:45...... Ford Prefect arrives and takes Arthur to the pub
  7522. 19:00...... The Vogon reads his poem
  7523. 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
  7524. @end example
  7525. @cindex time grid
  7526. If the agenda is in single-day mode, or for the display of today, the
  7527. timed entries are embedded in a time grid, like
  7528. @example
  7529. 8:00...... ------------------
  7530. 8:30-13:00 Arthur Dent lies in front of the bulldozer
  7531. 10:00...... ------------------
  7532. 12:00...... ------------------
  7533. 12:45...... Ford Prefect arrives and takes Arthur to the pub
  7534. 14:00...... ------------------
  7535. 16:00...... ------------------
  7536. 18:00...... ------------------
  7537. 19:00...... The Vogon reads his poem
  7538. 20:00...... ------------------
  7539. 20:30-22:15 Marvin escorts the Hitchhikers to the bridge
  7540. @end example
  7541. @vindex org-agenda-use-time-grid
  7542. @vindex org-agenda-time-grid
  7543. The time grid can be turned on and off with the variable
  7544. @code{org-agenda-use-time-grid}, and can be configured with
  7545. @code{org-agenda-time-grid}.
  7546. @node Sorting agenda items
  7547. @subsection Sorting agenda items
  7548. @cindex sorting, of agenda items
  7549. @cindex priorities, of agenda items
  7550. Before being inserted into a view, the items are sorted. How this is
  7551. done depends on the type of view.
  7552. @itemize @bullet
  7553. @item
  7554. @vindex org-agenda-files
  7555. For the daily/weekly agenda, the items for each day are sorted. The
  7556. default order is to first collect all items containing an explicit
  7557. time-of-day specification. These entries will be shown at the beginning
  7558. of the list, as a @emph{schedule} for the day. After that, items remain
  7559. grouped in categories, in the sequence given by @code{org-agenda-files}.
  7560. Within each category, items are sorted by priority (@pxref{Priorities}),
  7561. which is composed of the base priority (2000 for priority @samp{A}, 1000
  7562. for @samp{B}, and 0 for @samp{C}), plus additional increments for
  7563. overdue scheduled or deadline items.
  7564. @item
  7565. For the TODO list, items remain in the order of categories, but within
  7566. each category, sorting takes place according to priority
  7567. (@pxref{Priorities}). The priority used for sorting derives from the
  7568. priority cookie, with additions depending on how close an item is to its due
  7569. or scheduled date.
  7570. @item
  7571. For tags matches, items are not sorted at all, but just appear in the
  7572. sequence in which they are found in the agenda files.
  7573. @end itemize
  7574. @vindex org-agenda-sorting-strategy
  7575. Sorting can be customized using the variable
  7576. @code{org-agenda-sorting-strategy}, and may also include criteria based on
  7577. the estimated effort of an entry (@pxref{Effort estimates}).
  7578. @node Filtering/limiting agenda items
  7579. @subsection Filtering/limiting agenda items
  7580. Agenda built-in or customized commands are statically defined. Agenda
  7581. filters and limits provide two ways of dynamically narrowing down the list of
  7582. agenda entries: @emph{filters} and @emph{limits}. Filters only act on the
  7583. display of the items, while limits take effect before the list of agenda
  7584. entries is built. Filters are more often used interactively, while limits are
  7585. mostly useful when defined as local variables within custom agenda commands.
  7586. @subsubheading Filtering in the agenda
  7587. @cindex filtering, by tag, category, top headline and effort, in agenda
  7588. @cindex tag filtering, in agenda
  7589. @cindex category filtering, in agenda
  7590. @cindex top headline filtering, in agenda
  7591. @cindex effort filtering, in agenda
  7592. @cindex query editing, in agenda
  7593. @table @kbd
  7594. @orgcmd{/,org-agenda-filter-by-tag}
  7595. @vindex org-agenda-tag-filter-preset
  7596. Filter the agenda view with respect to a tag and/or effort estimates. The
  7597. difference between this and a custom agenda command is that filtering is very
  7598. fast, so that you can switch quickly between different filters without having
  7599. to recreate the agenda.@footnote{Custom commands can preset a filter by
  7600. binding the variable @code{org-agenda-tag-filter-preset} as an option. This
  7601. filter will then be applied to the view and persist as a basic filter through
  7602. refreshes and more secondary filtering. The filter is a global property of
  7603. the entire agenda view---in a block agenda, you should only set this in the
  7604. global options section, not in the section of an individual block.}
  7605. You will be prompted for a tag selection letter; @key{SPC} will mean any tag
  7606. at all. Pressing @key{TAB} at that prompt will offer use completion to
  7607. select a tag (including any tags that do not have a selection character).
  7608. The command then hides all entries that do not contain or inherit this tag.
  7609. When called with prefix arg, remove the entries that @emph{do} have the tag.
  7610. A second @kbd{/} at the prompt will turn off the filter and unhide any hidden
  7611. entries. Pressing @kbd{+} or @kbd{-} switches between filtering and
  7612. excluding the next tag.
  7613. Org also supports automatic, context-aware tag filtering. If the variable
  7614. @code{org-agenda-auto-exclude-function} is set to a user-defined function,
  7615. that function can decide which tags should be excluded from the agenda
  7616. automatically. Once this is set, the @kbd{/} command then accepts @kbd{RET}
  7617. as a sub-option key and runs the auto exclusion logic. For example, let's
  7618. say you use a @code{Net} tag to identify tasks which need network access, an
  7619. @code{Errand} tag for errands in town, and a @code{Call} tag for making phone
  7620. calls. You could auto-exclude these tags based on the availability of the
  7621. Internet, and outside of business hours, with something like this:
  7622. @smalllisp
  7623. @group
  7624. (defun org-my-auto-exclude-function (tag)
  7625. (and (cond
  7626. ((string= tag "Net")
  7627. (/= 0 (call-process "/sbin/ping" nil nil nil
  7628. "-c1" "-q" "-t1" "mail.gnu.org")))
  7629. ((or (string= tag "Errand") (string= tag "Call"))
  7630. (let ((hour (nth 2 (decode-time))))
  7631. (or (< hour 8) (> hour 21)))))
  7632. (concat "-" tag)))
  7633. (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)
  7634. @end group
  7635. @end smalllisp
  7636. @c
  7637. @kindex [
  7638. @kindex ]
  7639. @kindex @{
  7640. @kindex @}
  7641. @item [ ] @{ @}
  7642. @table @i
  7643. @item @r{in} search view
  7644. add new search words (@kbd{[} and @kbd{]}) or new regular expressions
  7645. (@kbd{@{} and @kbd{@}}) to the query string. The opening bracket/brace will
  7646. add a positive search term prefixed by @samp{+}, indicating that this search
  7647. term @i{must} occur/match in the entry. The closing bracket/brace will add a
  7648. negative search term which @i{must not} occur/match in the entry for it to be
  7649. selected.
  7650. @end table
  7651. @orgcmd{<,org-agenda-filter-by-category}
  7652. @vindex org-agenda-category-filter-preset
  7653. Filter the current agenda view with respect to the category of the item at
  7654. point. Pressing @code{<} another time will remove this filter. When called
  7655. with a prefix argument exclude the category of the item at point from the
  7656. agenda.
  7657. You can add a filter preset in custom agenda commands through the option
  7658. @code{org-agenda-category-filter-preset}. @xref{Setting options}.
  7659. @orgcmd{^,org-agenda-filter-by-top-headline}
  7660. Filter the current agenda view and only display the siblings and the parent
  7661. headline of the one at point.
  7662. @orgcmd{=,org-agenda-filter-by-regexp}
  7663. @vindex org-agenda-regexp-filter-preset
  7664. Filter the agenda view by a regular expression: only show agenda entries
  7665. matching the regular expression the user entered. When called with a prefix
  7666. argument, it will filter @emph{out} entries matching the regexp. With two
  7667. universal prefix arguments, it will remove all the regexp filters, which can
  7668. be accumulated.
  7669. You can add a filter preset in custom agenda commands through the option
  7670. @code{org-agenda-regexp-filter-preset}. @xref{Setting options}.
  7671. @orgcmd{_,org-agenda-filter-by-effort}
  7672. @vindex org-agenda-effort-filter-preset
  7673. @vindex org-sort-agenda-noeffort-is-high
  7674. Filter the agenda view with respect to effort estimates.
  7675. You first need to set up allowed efforts globally, for example
  7676. @lisp
  7677. (setq org-global-properties
  7678. '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
  7679. @end lisp
  7680. You can then filter for an effort by first typing an operator, one of
  7681. @kbd{<}, @kbd{>}, and @kbd{=}, and then the one-digit index of an effort
  7682. estimate in your array of allowed values, where @kbd{0} means the 10th value.
  7683. The filter will then restrict to entries with effort smaller-or-equal, equal,
  7684. or larger-or-equal than the selected value. For application of the operator,
  7685. entries without a defined effort will be treated according to the value of
  7686. @code{org-sort-agenda-noeffort-is-high}.
  7687. When called with a prefix argument, it will remove entries matching the
  7688. condition. With two universal prefix arguments, it will clear effort
  7689. filters, which can be accumulated.
  7690. You can add a filter preset in custom agenda commands through the option
  7691. @code{org-agenda-effort-filter-preset}. @xref{Setting options}.
  7692. @orgcmd{|,org-agenda-filter-remove-all}
  7693. Remove all filters in the current agenda view.
  7694. @end table
  7695. @subsubheading Setting limits for the agenda
  7696. @cindex limits, in agenda
  7697. @vindex org-agenda-max-entries
  7698. @vindex org-agenda-max-effort
  7699. @vindex org-agenda-max-todos
  7700. @vindex org-agenda-max-tags
  7701. Here is a list of options that you can set, either globally, or locally in
  7702. your custom agenda views (@pxref{Custom agenda views}).
  7703. @table @code
  7704. @item org-agenda-max-entries
  7705. Limit the number of entries.
  7706. @item org-agenda-max-effort
  7707. Limit the duration of accumulated efforts (as minutes).
  7708. @item org-agenda-max-todos
  7709. Limit the number of entries with TODO keywords.
  7710. @item org-agenda-max-tags
  7711. Limit the number of tagged entries.
  7712. @end table
  7713. When set to a positive integer, each option will exclude entries from other
  7714. categories: for example, @code{(setq org-agenda-max-effort 100)} will limit
  7715. the agenda to 100 minutes of effort and exclude any entry that has no effort
  7716. property. If you want to include entries with no effort property, use a
  7717. negative value for @code{org-agenda-max-effort}.
  7718. One useful setup is to use @code{org-agenda-max-entries} locally in a custom
  7719. command. For example, this custom command will display the next five entries
  7720. with a @code{NEXT} TODO keyword.
  7721. @smalllisp
  7722. (setq org-agenda-custom-commands
  7723. '(("n" todo "NEXT"
  7724. ((org-agenda-max-entries 5)))))
  7725. @end smalllisp
  7726. Once you mark one of these five entry as @code{DONE}, rebuilding the agenda
  7727. will again the next five entries again, including the first entry that was
  7728. excluded so far.
  7729. You can also dynamically set temporary limits, which will be lost when
  7730. rebuilding the agenda:
  7731. @table @kbd
  7732. @orgcmd{~,org-agenda-limit-interactively}
  7733. This prompts for the type of limit to apply and its value.
  7734. @end table
  7735. @node Agenda commands
  7736. @section Commands in the agenda buffer
  7737. @cindex commands, in agenda buffer
  7738. Entries in the agenda buffer are linked back to the Org file or diary
  7739. file where they originate. You are not allowed to edit the agenda
  7740. buffer itself, but commands are provided to show and jump to the
  7741. original entry location, and to edit the Org files ``remotely'' from
  7742. the agenda buffer. In this way, all information is stored only once,
  7743. removing the risk that your agenda and note files may diverge.
  7744. Some commands can be executed with mouse clicks on agenda lines. For
  7745. the other commands, the cursor needs to be in the desired line.
  7746. @table @kbd
  7747. @tsubheading{Motion}
  7748. @cindex motion commands in agenda
  7749. @orgcmd{n,org-agenda-next-line}
  7750. Next line (same as @key{down} and @kbd{C-n}).
  7751. @orgcmd{p,org-agenda-previous-line}
  7752. Previous line (same as @key{up} and @kbd{C-p}).
  7753. @orgcmd{N,org-agenda-next-item}
  7754. Next item: same as next line, but only consider items.
  7755. @orgcmd{P,org-agenda-previous-item}
  7756. Previous item: same as previous line, but only consider items.
  7757. @tsubheading{View/Go to Org file}
  7758. @orgcmdkkc{@key{SPC},mouse-3,org-agenda-show-and-scroll-up}
  7759. Display the original location of the item in another window. With prefix
  7760. arg, make sure that drawers stay folded.
  7761. @c
  7762. @orgcmd{L,org-agenda-recenter}
  7763. Display original location and recenter that window.
  7764. @c
  7765. @orgcmdkkc{@key{TAB},mouse-2,org-agenda-goto}
  7766. Go to the original location of the item in another window.
  7767. @c
  7768. @orgcmd{@key{RET},org-agenda-switch-to}
  7769. Go to the original location of the item and delete other windows.
  7770. @c
  7771. @orgcmd{F,org-agenda-follow-mode}
  7772. @vindex org-agenda-start-with-follow-mode
  7773. Toggle Follow mode. In Follow mode, as you move the cursor through
  7774. the agenda buffer, the other window always shows the corresponding
  7775. location in the Org file. The initial setting for this mode in new
  7776. agenda buffers can be set with the variable
  7777. @code{org-agenda-start-with-follow-mode}.
  7778. @c
  7779. @orgcmd{C-c C-x b,org-agenda-tree-to-indirect-buffer}
  7780. Display the entire subtree of the current item in an indirect buffer. With a
  7781. numeric prefix argument N, go up to level N and then take that tree. If N is
  7782. negative, go up that many levels. With a @kbd{C-u} prefix, do not remove the
  7783. previously used indirect buffer.
  7784. @orgcmd{C-c C-o,org-agenda-open-link}
  7785. Follow a link in the entry. This will offer a selection of any links in the
  7786. text belonging to the referenced Org node. If there is only one link, it
  7787. will be followed without a selection prompt.
  7788. @tsubheading{Change display}
  7789. @cindex display changing, in agenda
  7790. @kindex A
  7791. @item A
  7792. Interactively select another agenda view and append it to the current view.
  7793. @c
  7794. @kindex o
  7795. @item o
  7796. Delete other windows.
  7797. @c
  7798. @orgcmdkskc{v d,d,org-agenda-day-view}
  7799. @xorgcmdkskc{v w,w,org-agenda-week-view}
  7800. @xorgcmd{v t,org-agenda-fortnight-view}
  7801. @xorgcmd{v m,org-agenda-month-view}
  7802. @xorgcmd{v y,org-agenda-year-view}
  7803. @xorgcmd{v SPC,org-agenda-reset-view}
  7804. @vindex org-agenda-span
  7805. Switch to day/week/month/year view. When switching to day or week view, this
  7806. setting becomes the default for subsequent agenda refreshes. Since month and
  7807. year views are slow to create, they do not become the default. A numeric
  7808. prefix argument may be used to jump directly to a specific day of the year,
  7809. ISO week, month, or year, respectively. For example, @kbd{32 d} jumps to
  7810. February 1st, @kbd{9 w} to ISO week number 9. When setting day, week, or
  7811. month view, a year may be encoded in the prefix argument as well. For
  7812. example, @kbd{200712 w} will jump to week 12 in 2007. If such a year
  7813. specification has only one or two digits, it will be mapped to the interval
  7814. 1938--2037. @kbd{v @key{SPC}} will reset to what is set in
  7815. @code{org-agenda-span}.
  7816. @c
  7817. @orgcmd{f,org-agenda-later}
  7818. Go forward in time to display the following @code{org-agenda-current-span} days.
  7819. For example, if the display covers a week, switch to the following week.
  7820. With prefix arg, go forward that many times @code{org-agenda-current-span} days.
  7821. @c
  7822. @orgcmd{b,org-agenda-earlier}
  7823. Go backward in time to display earlier dates.
  7824. @c
  7825. @orgcmd{.,org-agenda-goto-today}
  7826. Go to today.
  7827. @c
  7828. @orgcmd{j,org-agenda-goto-date}
  7829. Prompt for a date and go there.
  7830. @c
  7831. @orgcmd{J,org-agenda-clock-goto}
  7832. Go to the currently clocked-in task @i{in the agenda buffer}.
  7833. @c
  7834. @orgcmd{D,org-agenda-toggle-diary}
  7835. Toggle the inclusion of diary entries. See @ref{Weekly/daily agenda}.
  7836. @c
  7837. @orgcmdkskc{v l,l,org-agenda-log-mode}
  7838. @kindex v L
  7839. @vindex org-log-done
  7840. @vindex org-agenda-log-mode-items
  7841. Toggle Logbook mode. In Logbook mode, entries that were marked DONE while
  7842. logging was on (variable @code{org-log-done}) are shown in the agenda, as are
  7843. entries that have been clocked on that day. You can configure the entry
  7844. types that should be included in log mode using the variable
  7845. @code{org-agenda-log-mode-items}. When called with a @kbd{C-u} prefix, show
  7846. all possible logbook entries, including state changes. When called with two
  7847. prefix arguments @kbd{C-u C-u}, show only logging information, nothing else.
  7848. @kbd{v L} is equivalent to @kbd{C-u v l}.
  7849. @c
  7850. @orgcmdkskc{v [,[,org-agenda-manipulate-query-add}
  7851. Include inactive timestamps into the current view. Only for weekly/daily
  7852. agenda.
  7853. @c
  7854. @orgcmd{v a,org-agenda-archives-mode}
  7855. @xorgcmd{v A,org-agenda-archives-mode 'files}
  7856. @cindex Archives mode
  7857. Toggle Archives mode. In Archives mode, trees that are marked
  7858. @code{ARCHIVED} are also scanned when producing the agenda. When you use the
  7859. capital @kbd{A}, even all archive files are included. To exit archives mode,
  7860. press @kbd{v a} again.
  7861. @c
  7862. @orgcmdkskc{v R,R,org-agenda-clockreport-mode}
  7863. @vindex org-agenda-start-with-clockreport-mode
  7864. @vindex org-clock-report-include-clocking-task
  7865. Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will
  7866. always show a table with the clocked times for the time span and file scope
  7867. covered by the current agenda view. The initial setting for this mode in new
  7868. agenda buffers can be set with the variable
  7869. @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument
  7870. when toggling this mode (i.e., @kbd{C-u R}), the clock table will not show
  7871. contributions from entries that are hidden by agenda filtering@footnote{Only
  7872. tags filtering will be respected here, effort filtering is ignored.}. See
  7873. also the variable @code{org-clock-report-include-clocking-task}.
  7874. @c
  7875. @orgkey{v c}
  7876. @vindex org-agenda-clock-consistency-checks
  7877. Show overlapping clock entries, clocking gaps, and other clocking problems in
  7878. the current agenda range. You can then visit clocking lines and fix them
  7879. manually. See the variable @code{org-agenda-clock-consistency-checks} for
  7880. information on how to customize the definition of what constituted a clocking
  7881. problem. To return to normal agenda display, press @kbd{l} to exit Logbook
  7882. mode.
  7883. @c
  7884. @orgcmdkskc{v E,E,org-agenda-entry-text-mode}
  7885. @vindex org-agenda-start-with-entry-text-mode
  7886. @vindex org-agenda-entry-text-maxlines
  7887. Toggle entry text mode. In entry text mode, a number of lines from the Org
  7888. outline node referenced by an agenda line will be displayed below the line.
  7889. The maximum number of lines is given by the variable
  7890. @code{org-agenda-entry-text-maxlines}. Calling this command with a numeric
  7891. prefix argument will temporarily modify that number to the prefix value.
  7892. @c
  7893. @orgcmd{G,org-agenda-toggle-time-grid}
  7894. @vindex org-agenda-use-time-grid
  7895. @vindex org-agenda-time-grid
  7896. Toggle the time grid on and off. See also the variables
  7897. @code{org-agenda-use-time-grid} and @code{org-agenda-time-grid}.
  7898. @c
  7899. @orgcmd{r,org-agenda-redo}
  7900. Recreate the agenda buffer, for example to reflect the changes after
  7901. modification of the timestamps of items with @kbd{S-@key{left}} and
  7902. @kbd{S-@key{right}}. When the buffer is the global TODO list, a prefix
  7903. argument is interpreted to create a selective list for a specific TODO
  7904. keyword.
  7905. @orgcmd{g,org-agenda-redo}
  7906. Same as @kbd{r}.
  7907. @c
  7908. @orgcmdkskc{C-x C-s,s,org-save-all-org-buffers}
  7909. Save all Org buffers in the current Emacs session, and also the locations of
  7910. IDs.
  7911. @c
  7912. @orgcmd{C-c C-x C-c,org-agenda-columns}
  7913. @vindex org-columns-default-format
  7914. Invoke column view (@pxref{Column view}) in the agenda buffer. The column
  7915. view format is taken from the entry at point, or (if there is no entry at
  7916. point), from the first entry in the agenda view. So whatever the format for
  7917. that entry would be in the original buffer (taken from a property, from a
  7918. @code{#+COLUMNS} line, or from the default variable
  7919. @code{org-columns-default-format}), will be used in the agenda.
  7920. @orgcmd{C-c C-x >,org-agenda-remove-restriction-lock}
  7921. Remove the restriction lock on the agenda, if it is currently restricted to a
  7922. file or subtree (@pxref{Agenda files}).
  7923. @tsubheading{Secondary filtering and query editing}
  7924. For a detailed description of these commands, @pxref{Filtering/limiting
  7925. agenda items}.
  7926. @orgcmd{/,org-agenda-filter-by-tag}
  7927. Filter the agenda view with respect to a tag and/or effort estimates.
  7928. @orgcmd{<,org-agenda-filter-by-category}
  7929. Filter the current agenda view with respect to the category of the item at
  7930. point.
  7931. @orgcmd{^,org-agenda-filter-by-top-headline}
  7932. Filter the current agenda view and only display the siblings and the parent
  7933. headline of the one at point.
  7934. @orgcmd{=,org-agenda-filter-by-regexp}
  7935. Filter the agenda view by a regular expression.
  7936. @orgcmd{_,org-agenda-filter-by-effort}
  7937. Filter the agenda view with respect to effort estimates.
  7938. @orgcmd{|,org-agenda-filter-remove-all}
  7939. Remove all filters in the current agenda view.
  7940. @tsubheading{Remote editing}
  7941. @cindex remote editing, from agenda
  7942. @item 0--9
  7943. Digit argument.
  7944. @c
  7945. @cindex undoing remote-editing events
  7946. @cindex remote editing, undo
  7947. @orgcmd{C-_,org-agenda-undo}
  7948. Undo a change due to a remote editing command. The change is undone
  7949. both in the agenda buffer and in the remote buffer.
  7950. @c
  7951. @orgcmd{t,org-agenda-todo}
  7952. Change the TODO state of the item, both in the agenda and in the
  7953. original org file.
  7954. @c
  7955. @orgcmd{C-S-@key{right},org-agenda-todo-nextset}
  7956. @orgcmd{C-S-@key{left},org-agenda-todo-previousset}
  7957. Switch to the next/previous set of TODO keywords.
  7958. @c
  7959. @orgcmd{C-k,org-agenda-kill}
  7960. @vindex org-agenda-confirm-kill
  7961. Delete the current agenda item along with the entire subtree belonging
  7962. to it in the original Org file. If the text to be deleted remotely
  7963. is longer than one line, the kill needs to be confirmed by the user. See
  7964. variable @code{org-agenda-confirm-kill}.
  7965. @c
  7966. @orgcmd{C-c C-w,org-agenda-refile}
  7967. Refile the entry at point.
  7968. @c
  7969. @orgcmdkskc{C-c C-x C-a,a,org-agenda-archive-default-with-confirmation}
  7970. @vindex org-archive-default-command
  7971. Archive the subtree corresponding to the entry at point using the default
  7972. archiving command set in @code{org-archive-default-command}. When using the
  7973. @code{a} key, confirmation will be required.
  7974. @c
  7975. @orgcmd{C-c C-x a,org-agenda-toggle-archive-tag}
  7976. Toggle the ARCHIVE tag for the current headline.
  7977. @c
  7978. @orgcmd{C-c C-x A,org-agenda-archive-to-archive-sibling}
  7979. Move the subtree corresponding to the current entry to its @emph{archive
  7980. sibling}.
  7981. @c
  7982. @orgcmdkskc{C-c C-x C-s,$,org-agenda-archive}
  7983. Archive the subtree corresponding to the current headline. This means the
  7984. entry will be moved to the configured archive location, most likely a
  7985. different file.
  7986. @c
  7987. @orgcmd{T,org-agenda-show-tags}
  7988. @vindex org-agenda-show-inherited-tags
  7989. Show all tags associated with the current item. This is useful if you have
  7990. turned off @code{org-agenda-show-inherited-tags}, but still want to see all
  7991. tags of a headline occasionally.
  7992. @c
  7993. @orgcmd{:,org-agenda-set-tags}
  7994. Set tags for the current headline. If there is an active region in the
  7995. agenda, change a tag for all headings in the region.
  7996. @c
  7997. @kindex ,
  7998. @item ,
  7999. Set the priority for the current item (@command{org-agenda-priority}).
  8000. Org mode prompts for the priority character. If you reply with @key{SPC},
  8001. the priority cookie is removed from the entry.
  8002. @c
  8003. @orgcmd{P,org-agenda-show-priority}
  8004. Display weighted priority of current item.
  8005. @c
  8006. @orgcmdkkc{+,S-@key{up},org-agenda-priority-up}
  8007. Increase the priority of the current item. The priority is changed in
  8008. the original buffer, but the agenda is not resorted. Use the @kbd{r}
  8009. key for this.
  8010. @c
  8011. @orgcmdkkc{-,S-@key{down},org-agenda-priority-down}
  8012. Decrease the priority of the current item.
  8013. @c
  8014. @orgcmdkkc{z,C-c C-z,org-agenda-add-note}
  8015. @vindex org-log-into-drawer
  8016. Add a note to the entry. This note will be recorded, and then filed to the
  8017. same location where state change notes are put. Depending on
  8018. @code{org-log-into-drawer}, this may be inside a drawer.
  8019. @c
  8020. @orgcmd{C-c C-a,org-attach}
  8021. Dispatcher for all command related to attachments.
  8022. @c
  8023. @orgcmd{C-c C-s,org-agenda-schedule}
  8024. Schedule this item. With prefix arg remove the scheduling timestamp
  8025. @c
  8026. @orgcmd{C-c C-d,org-agenda-deadline}
  8027. Set a deadline for this item. With prefix arg remove the deadline.
  8028. @c
  8029. @orgcmd{S-@key{right},org-agenda-do-date-later}
  8030. Change the timestamp associated with the current line by one day into the
  8031. future. If the date is in the past, the first call to this command will move
  8032. it to today.@*
  8033. With a numeric prefix argument, change it by that many days. For example,
  8034. @kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix,
  8035. change the time by one hour. If you immediately repeat the command, it will
  8036. continue to change hours even without the prefix arg. With a double @kbd{C-u
  8037. C-u} prefix, do the same for changing minutes.@*
  8038. The stamp is changed in the original Org file, but the change is not directly
  8039. reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer.
  8040. @c
  8041. @orgcmd{S-@key{left},org-agenda-do-date-earlier}
  8042. Change the timestamp associated with the current line by one day
  8043. into the past.
  8044. @c
  8045. @orgcmd{>,org-agenda-date-prompt}
  8046. Change the timestamp associated with the current line. The key @kbd{>} has
  8047. been chosen, because it is the same as @kbd{S-.} on my keyboard.
  8048. @c
  8049. @orgcmd{I,org-agenda-clock-in}
  8050. Start the clock on the current item. If a clock is running already, it
  8051. is stopped first.
  8052. @c
  8053. @orgcmd{O,org-agenda-clock-out}
  8054. Stop the previously started clock.
  8055. @c
  8056. @orgcmd{X,org-agenda-clock-cancel}
  8057. Cancel the currently running clock.
  8058. @c
  8059. @orgcmd{J,org-agenda-clock-goto}
  8060. Jump to the running clock in another window.
  8061. @c
  8062. @orgcmd{k,org-agenda-capture}
  8063. Like @code{org-capture}, but use the date at point as the default date for
  8064. the capture template. See @code{org-capture-use-agenda-date} to make this
  8065. the default behavior of @code{org-capture}.
  8066. @cindex capturing, from agenda
  8067. @vindex org-capture-use-agenda-date
  8068. @tsubheading{Dragging agenda lines forward/backward}
  8069. @cindex dragging, agenda lines
  8070. @orgcmd{M-<up>,org-agenda-drag-line-backward}
  8071. Drag the line at point backward one line@footnote{Moving agenda lines does
  8072. not persist after an agenda refresh and does not modify the contributing
  8073. @file{.org} files}. With a numeric prefix argument, drag backward by that
  8074. many lines.
  8075. @orgcmd{M-<down>,org-agenda-drag-line-forward}
  8076. Drag the line at point forward one line. With a numeric prefix argument,
  8077. drag forward by that many lines.
  8078. @tsubheading{Bulk remote editing selected entries}
  8079. @cindex remote editing, bulk, from agenda
  8080. @vindex org-agenda-bulk-custom-functions
  8081. @orgcmd{m,org-agenda-bulk-mark}
  8082. Mark the entry at point for bulk action. With numeric prefix argument, mark
  8083. that many successive entries.
  8084. @c
  8085. @orgcmd{*,org-agenda-bulk-mark-all}
  8086. Mark all visible agenda entries for bulk action.
  8087. @c
  8088. @orgcmd{u,org-agenda-bulk-unmark}
  8089. Unmark entry at point for bulk action.
  8090. @c
  8091. @orgcmd{U,org-agenda-bulk-remove-all-marks}
  8092. Unmark all marked entries for bulk action.
  8093. @c
  8094. @orgcmd{M-m,org-agenda-bulk-toggle}
  8095. Toggle mark of the entry at point for bulk action.
  8096. @c
  8097. @orgcmd{M-*,org-agenda-bulk-toggle-all}
  8098. Toggle marks of all visible entries for bulk action.
  8099. @c
  8100. @orgcmd{%,org-agenda-bulk-mark-regexp}
  8101. Mark entries matching a regular expression for bulk action.
  8102. @c
  8103. @orgcmd{B,org-agenda-bulk-action}
  8104. Bulk action: act on all marked entries in the agenda. This will prompt for
  8105. another key to select the action to be applied. The prefix arg to @kbd{B}
  8106. will be passed through to the @kbd{s} and @kbd{d} commands, to bulk-remove
  8107. these special timestamps. By default, marks are removed after the bulk. If
  8108. you want them to persist, set @code{org-agenda-persistent-marks} to @code{t}
  8109. or hit @kbd{p} at the prompt.
  8110. @table @kbd
  8111. @item *
  8112. Toggle persistent marks.
  8113. @item $
  8114. Archive all selected entries.
  8115. @item A
  8116. Archive entries by moving them to their respective archive siblings.
  8117. @item t
  8118. Change TODO state. This prompts for a single TODO keyword and changes the
  8119. state of all selected entries, bypassing blocking and suppressing logging
  8120. notes (but not timestamps).
  8121. @item +
  8122. Add a tag to all selected entries.
  8123. @item -
  8124. Remove a tag from all selected entries.
  8125. @item s
  8126. Schedule all items to a new date. To shift existing schedule dates by a
  8127. fixed number of days, use something starting with double plus at the prompt,
  8128. for example @samp{++8d} or @samp{++2w}.
  8129. @item d
  8130. Set deadline to a specific date.
  8131. @item r
  8132. Prompt for a single refile target and move all entries. The entries will no
  8133. longer be in the agenda; refresh (@kbd{g}) to bring them back.
  8134. @item S
  8135. Reschedule randomly into the coming N days. N will be prompted for. With
  8136. prefix arg (@kbd{C-u B S}), scatter only across weekdays.
  8137. @item f
  8138. Apply a function@footnote{You can also create persistent custom functions
  8139. through @code{org-agenda-bulk-custom-functions}.} to marked entries. For
  8140. example, the function below sets the CATEGORY property of the entries to web.
  8141. @lisp
  8142. @group
  8143. (defun set-category ()
  8144. (interactive "P")
  8145. (let* ((marker (or (org-get-at-bol 'org-hd-marker)
  8146. (org-agenda-error)))
  8147. (buffer (marker-buffer marker)))
  8148. (with-current-buffer buffer
  8149. (save-excursion
  8150. (save-restriction
  8151. (widen)
  8152. (goto-char marker)
  8153. (org-back-to-heading t)
  8154. (org-set-property "CATEGORY" "web"))))))
  8155. @end group
  8156. @end lisp
  8157. @end table
  8158. @tsubheading{Calendar commands}
  8159. @cindex calendar commands, from agenda
  8160. @orgcmd{c,org-agenda-goto-calendar}
  8161. Open the Emacs calendar and move to the date at the agenda cursor.
  8162. @c
  8163. @orgcmd{c,org-calendar-goto-agenda}
  8164. When in the calendar, compute and show the Org mode agenda for the
  8165. date at the cursor.
  8166. @c
  8167. @cindex diary entries, creating from agenda
  8168. @orgcmd{i,org-agenda-diary-entry}
  8169. @vindex org-agenda-diary-file
  8170. Insert a new entry into the diary, using the date at the cursor and (for
  8171. block entries) the date at the mark. This will add to the Emacs diary
  8172. file@footnote{This file is parsed for the agenda when
  8173. @code{org-agenda-include-diary} is set.}, in a way similar to the @kbd{i}
  8174. command in the calendar. The diary file will pop up in another window, where
  8175. you can add the entry.
  8176. If you configure @code{org-agenda-diary-file} to point to an Org mode file,
  8177. Org will create entries (in Org mode syntax) in that file instead. Most
  8178. entries will be stored in a date-based outline tree that will later make it
  8179. easy to archive appointments from previous months/years. The tree will be
  8180. built under an entry with a @code{DATE_TREE} property, or else with years as
  8181. top-level entries. Emacs will prompt you for the entry text---if you specify
  8182. it, the entry will be created in @code{org-agenda-diary-file} without further
  8183. interaction. If you directly press @key{RET} at the prompt without typing
  8184. text, the target file will be shown in another window for you to finish the
  8185. entry there. See also the @kbd{k r} command.
  8186. @c
  8187. @orgcmd{M,org-agenda-phases-of-moon}
  8188. Show the phases of the moon for the three months around current date.
  8189. @c
  8190. @orgcmd{S,org-agenda-sunrise-sunset}
  8191. Show sunrise and sunset times. The geographical location must be set
  8192. with calendar variables, see the documentation for the Emacs calendar.
  8193. @c
  8194. @orgcmd{C,org-agenda-convert-date}
  8195. Convert the date at cursor into many other cultural and historic
  8196. calendars.
  8197. @c
  8198. @orgcmd{H,org-agenda-holidays}
  8199. Show holidays for three months around the cursor date.
  8200. @item M-x org-icalendar-combine-agenda-files RET
  8201. Export a single iCalendar file containing entries from all agenda files.
  8202. This is a globally available command, and also available in the agenda menu.
  8203. @tsubheading{Exporting to a file}
  8204. @orgcmd{C-x C-w,org-agenda-write}
  8205. @cindex exporting agenda views
  8206. @cindex agenda views, exporting
  8207. @vindex org-agenda-exporter-settings
  8208. Write the agenda view to a file. Depending on the extension of the selected
  8209. file name, the view will be exported as HTML (@file{.html} or @file{.htm}),
  8210. Postscript (@file{.ps}), PDF (@file{.pdf}), Org (@file{.org}) and plain text
  8211. (any other extension). When exporting to Org, only the body of original
  8212. headlines are exported, not subtrees or inherited tags. When called with a
  8213. @kbd{C-u} prefix argument, immediately open the newly created file. Use the
  8214. variable @code{org-agenda-exporter-settings} to set options for
  8215. @file{ps-print} and for @file{htmlize} to be used during export.
  8216. @tsubheading{Quit and Exit}
  8217. @orgcmd{q,org-agenda-quit}
  8218. Quit agenda, remove the agenda buffer.
  8219. @c
  8220. @cindex agenda files, removing buffers
  8221. @orgcmd{x,org-agenda-exit}
  8222. Exit agenda, remove the agenda buffer and all buffers loaded by Emacs
  8223. for the compilation of the agenda. Buffers created by the user to
  8224. visit Org files will not be removed.
  8225. @end table
  8226. @node Custom agenda views
  8227. @section Custom agenda views
  8228. @cindex custom agenda views
  8229. @cindex agenda views, custom
  8230. Custom agenda commands serve two purposes: to store and quickly access
  8231. frequently used TODO and tags searches, and to create special composite
  8232. agenda buffers. Custom agenda commands will be accessible through the
  8233. dispatcher (@pxref{Agenda dispatcher}), just like the default commands.
  8234. @menu
  8235. * Storing searches:: Type once, use often
  8236. * Block agenda:: All the stuff you need in a single buffer
  8237. * Setting options:: Changing the rules
  8238. @end menu
  8239. @node Storing searches
  8240. @subsection Storing searches
  8241. The first application of custom searches is the definition of keyboard
  8242. shortcuts for frequently used searches, either creating an agenda
  8243. buffer, or a sparse tree (the latter covering of course only the current
  8244. buffer).
  8245. @kindex C-c a C
  8246. @vindex org-agenda-custom-commands
  8247. @cindex agenda views, main example
  8248. @cindex agenda, as an agenda views
  8249. @cindex agenda*, as an agenda views
  8250. @cindex tags, as an agenda view
  8251. @cindex todo, as an agenda view
  8252. @cindex tags-todo
  8253. @cindex todo-tree
  8254. @cindex occur-tree
  8255. @cindex tags-tree
  8256. Custom commands are configured in the variable
  8257. @code{org-agenda-custom-commands}. You can customize this variable, for
  8258. example by pressing @kbd{C-c a C}. You can also directly set it with Emacs
  8259. Lisp in the Emacs init file. The following example contains all valid agenda
  8260. views:
  8261. @lisp
  8262. @group
  8263. (setq org-agenda-custom-commands
  8264. '(("x" agenda)
  8265. ("y" agenda*)
  8266. ("w" todo "WAITING")
  8267. ("W" todo-tree "WAITING")
  8268. ("u" tags "+boss-urgent")
  8269. ("v" tags-todo "+boss-urgent")
  8270. ("U" tags-tree "+boss-urgent")
  8271. ("f" occur-tree "\\<FIXME\\>")
  8272. ("h" . "HOME+Name tags searches") ; description for "h" prefix
  8273. ("hl" tags "+home+Lisa")
  8274. ("hp" tags "+home+Peter")
  8275. ("hk" tags "+home+Kim")))
  8276. @end group
  8277. @end lisp
  8278. @noindent
  8279. The initial string in each entry defines the keys you have to press
  8280. after the dispatcher command @kbd{C-c a} in order to access the command.
  8281. Usually this will be just a single character, but if you have many
  8282. similar commands, you can also define two-letter combinations where the
  8283. first character is the same in several combinations and serves as a
  8284. prefix key@footnote{You can provide a description for a prefix key by
  8285. inserting a cons cell with the prefix and the description.}. The second
  8286. parameter is the search type, followed by the string or regular
  8287. expression to be used for the matching. The example above will
  8288. therefore define:
  8289. @table @kbd
  8290. @item C-c a x
  8291. as a global search for agenda entries planned@footnote{@emph{Planned} means
  8292. here that these entries have some planning information attached to them, like
  8293. a time-stamp, a scheduled or a deadline string. See
  8294. @code{org-agenda-entry-types} on how to set what planning information will be
  8295. taken into account.} this week/day.
  8296. @item C-c a y
  8297. as a global search for agenda entries planned this week/day, but only those
  8298. with an hour specification like @code{[h]h:mm}---think of them as appointments.
  8299. @item C-c a w
  8300. as a global search for TODO entries with @samp{WAITING} as the TODO
  8301. keyword
  8302. @item C-c a W
  8303. as the same search, but only in the current buffer and displaying the
  8304. results as a sparse tree
  8305. @item C-c a u
  8306. as a global tags search for headlines marked @samp{:boss:} but not
  8307. @samp{:urgent:}
  8308. @item C-c a v
  8309. as the same search as @kbd{C-c a u}, but limiting the search to
  8310. headlines that are also TODO items
  8311. @item C-c a U
  8312. as the same search as @kbd{C-c a u}, but only in the current buffer and
  8313. displaying the result as a sparse tree
  8314. @item C-c a f
  8315. to create a sparse tree (again: current buffer only) with all entries
  8316. containing the word @samp{FIXME}
  8317. @item C-c a h
  8318. as a prefix command for a HOME tags search where you have to press an
  8319. additional key (@kbd{l}, @kbd{p} or @kbd{k}) to select a name (Lisa,
  8320. Peter, or Kim) as additional tag to match.
  8321. @end table
  8322. Note that the @code{*-tree} agenda views need to be called from an
  8323. Org buffer as they operate on the current buffer only.
  8324. @node Block agenda
  8325. @subsection Block agenda
  8326. @cindex block agenda
  8327. @cindex agenda, with block views
  8328. Another possibility is the construction of agenda views that comprise
  8329. the results of @emph{several} commands, each of which creates a block in
  8330. the agenda buffer. The available commands include @code{agenda} for the
  8331. daily or weekly agenda (as created with @kbd{C-c a a}), @code{alltodo}
  8332. for the global TODO list (as constructed with @kbd{C-c a t}), and the
  8333. matching commands discussed above: @code{todo}, @code{tags}, and
  8334. @code{tags-todo}. Here are two examples:
  8335. @lisp
  8336. @group
  8337. (setq org-agenda-custom-commands
  8338. '(("h" "Agenda and Home-related tasks"
  8339. ((agenda "")
  8340. (tags-todo "home")
  8341. (tags "garden")))
  8342. ("o" "Agenda and Office-related tasks"
  8343. ((agenda "")
  8344. (tags-todo "work")
  8345. (tags "office")))))
  8346. @end group
  8347. @end lisp
  8348. @noindent
  8349. This will define @kbd{C-c a h} to create a multi-block view for stuff
  8350. you need to attend to at home. The resulting agenda buffer will contain
  8351. your agenda for the current week, all TODO items that carry the tag
  8352. @samp{home}, and also all lines tagged with @samp{garden}. Finally the
  8353. command @kbd{C-c a o} provides a similar view for office tasks.
  8354. @node Setting options
  8355. @subsection Setting options for custom commands
  8356. @cindex options, for custom agenda views
  8357. @vindex org-agenda-custom-commands
  8358. Org mode contains a number of variables regulating agenda construction
  8359. and display. The global variables define the behavior for all agenda
  8360. commands, including the custom commands. However, if you want to change
  8361. some settings just for a single custom view, you can do so. Setting
  8362. options requires inserting a list of variable names and values at the
  8363. right spot in @code{org-agenda-custom-commands}. For example:
  8364. @lisp
  8365. @group
  8366. (setq org-agenda-custom-commands
  8367. '(("w" todo "WAITING"
  8368. ((org-agenda-sorting-strategy '(priority-down))
  8369. (org-agenda-prefix-format " Mixed: ")))
  8370. ("U" tags-tree "+boss-urgent"
  8371. ((org-show-context-detail 'minimal)))
  8372. ("N" search ""
  8373. ((org-agenda-files '("~org/notes.org"))
  8374. (org-agenda-text-search-extra-files nil)))))
  8375. @end group
  8376. @end lisp
  8377. @noindent
  8378. Now the @kbd{C-c a w} command will sort the collected entries only by
  8379. priority, and the prefix format is modified to just say @samp{ Mixed: }
  8380. instead of giving the category of the entry. The sparse tags tree of
  8381. @kbd{C-c a U} will now turn out ultra-compact, because neither the
  8382. headline hierarchy above the match, nor the headline following the match
  8383. will be shown. The command @kbd{C-c a N} will do a text search limited
  8384. to only a single file.
  8385. @vindex org-agenda-custom-commands
  8386. For command sets creating a block agenda,
  8387. @code{org-agenda-custom-commands} has two separate spots for setting
  8388. options. You can add options that should be valid for just a single
  8389. command in the set, and options that should be valid for all commands in
  8390. the set. The former are just added to the command entry; the latter
  8391. must come after the list of command entries. Going back to the block
  8392. agenda example (@pxref{Block agenda}), let's change the sorting strategy
  8393. for the @kbd{C-c a h} commands to @code{priority-down}, but let's sort
  8394. the results for GARDEN tags query in the opposite order,
  8395. @code{priority-up}. This would look like this:
  8396. @lisp
  8397. @group
  8398. (setq org-agenda-custom-commands
  8399. '(("h" "Agenda and Home-related tasks"
  8400. ((agenda)
  8401. (tags-todo "home")
  8402. (tags "garden"
  8403. ((org-agenda-sorting-strategy '(priority-up)))))
  8404. ((org-agenda-sorting-strategy '(priority-down))))
  8405. ("o" "Agenda and Office-related tasks"
  8406. ((agenda)
  8407. (tags-todo "work")
  8408. (tags "office")))))
  8409. @end group
  8410. @end lisp
  8411. As you see, the values and parentheses setting is a little complex.
  8412. When in doubt, use the customize interface to set this variable---it
  8413. fully supports its structure. Just one caveat: when setting options in
  8414. this interface, the @emph{values} are just Lisp expressions. So if the
  8415. value is a string, you need to add the double-quotes around the value
  8416. yourself.
  8417. @vindex org-agenda-custom-commands-contexts
  8418. To control whether an agenda command should be accessible from a specific
  8419. context, you can customize @code{org-agenda-custom-commands-contexts}. Let's
  8420. say for example that you have an agenda command @code{"o"} displaying a view
  8421. that you only need when reading emails. Then you would configure this option
  8422. like this:
  8423. @lisp
  8424. (setq org-agenda-custom-commands-contexts
  8425. '(("o" (in-mode . "message-mode"))))
  8426. @end lisp
  8427. You can also tell that the command key @code{"o"} should refer to another
  8428. command key @code{"r"}. In that case, add this command key like this:
  8429. @lisp
  8430. (setq org-agenda-custom-commands-contexts
  8431. '(("o" "r" (in-mode . "message-mode"))))
  8432. @end lisp
  8433. See the docstring of the variable for more information.
  8434. @node Exporting agenda views
  8435. @section Exporting agenda views
  8436. @cindex agenda views, exporting
  8437. If you are away from your computer, it can be very useful to have a printed
  8438. version of some agenda views to carry around. Org mode can export custom
  8439. agenda views as plain text, HTML@footnote{You need to install
  8440. @file{htmlize.el} from @uref{https://github.com/hniksic/emacs-htmlize,Hrvoje
  8441. Niksic's repository.}}, Postscript, PDF@footnote{To create PDF output, the
  8442. ghostscript @file{ps2pdf} utility must be installed on the system. Selecting
  8443. a PDF file will also create the postscript file.}, and iCalendar files. If
  8444. you want to do this only occasionally, use the command
  8445. @table @kbd
  8446. @orgcmd{C-x C-w,org-agenda-write}
  8447. @cindex exporting agenda views
  8448. @cindex agenda views, exporting
  8449. @vindex org-agenda-exporter-settings
  8450. Write the agenda view to a file. Depending on the extension of the selected
  8451. file name, the view will be exported as HTML (extension @file{.html} or
  8452. @file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension
  8453. @file{.ics}), or plain text (any other extension). Use the variable
  8454. @code{org-agenda-exporter-settings} to set options for @file{ps-print} and
  8455. for @file{htmlize} to be used during export, for example
  8456. @vindex org-agenda-add-entry-text-maxlines
  8457. @vindex htmlize-output-type
  8458. @vindex ps-number-of-columns
  8459. @vindex ps-landscape-mode
  8460. @lisp
  8461. (setq org-agenda-exporter-settings
  8462. '((ps-number-of-columns 2)
  8463. (ps-landscape-mode t)
  8464. (org-agenda-add-entry-text-maxlines 5)
  8465. (htmlize-output-type 'css)))
  8466. @end lisp
  8467. @end table
  8468. If you need to export certain agenda views frequently, you can associate
  8469. any custom agenda command with a list of output file names
  8470. @footnote{If you want to store standard views like the weekly agenda
  8471. or the global TODO list as well, you need to define custom commands for
  8472. them in order to be able to specify file names.}. Here is an example
  8473. that first defines custom commands for the agenda and the global
  8474. TODO list, together with a number of files to which to export them.
  8475. Then we define two block agenda commands and specify file names for them
  8476. as well. File names can be relative to the current working directory,
  8477. or absolute.
  8478. @lisp
  8479. @group
  8480. (setq org-agenda-custom-commands
  8481. '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
  8482. ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
  8483. ("h" "Agenda and Home-related tasks"
  8484. ((agenda "")
  8485. (tags-todo "home")
  8486. (tags "garden"))
  8487. nil
  8488. ("~/views/home.html"))
  8489. ("o" "Agenda and Office-related tasks"
  8490. ((agenda)
  8491. (tags-todo "work")
  8492. (tags "office"))
  8493. nil
  8494. ("~/views/office.ps" "~/calendars/office.ics"))))
  8495. @end group
  8496. @end lisp
  8497. The extension of the file name determines the type of export. If it is
  8498. @file{.html}, Org mode will try to use the @file{htmlize.el} package to
  8499. convert the buffer to HTML and save it to this file name. If the extension
  8500. is @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce
  8501. Postscript output. If the extension is @file{.ics}, iCalendar export is run
  8502. export over all files that were used to construct the agenda, and limit the
  8503. export to entries listed in the agenda. Any other extension produces a plain
  8504. ASCII file.
  8505. The export files are @emph{not} created when you use one of those
  8506. commands interactively because this might use too much overhead.
  8507. Instead, there is a special command to produce @emph{all} specified
  8508. files in one step:
  8509. @table @kbd
  8510. @orgcmd{C-c a e,org-store-agenda-views}
  8511. Export all agenda views that have export file names associated with
  8512. them.
  8513. @end table
  8514. You can use the options section of the custom agenda commands to also
  8515. set options for the export commands. For example:
  8516. @lisp
  8517. (setq org-agenda-custom-commands
  8518. '(("X" agenda ""
  8519. ((ps-number-of-columns 2)
  8520. (ps-landscape-mode t)
  8521. (org-agenda-prefix-format " [ ] ")
  8522. (org-agenda-with-colors nil)
  8523. (org-agenda-remove-tags t))
  8524. ("theagenda.ps"))))
  8525. @end lisp
  8526. @noindent
  8527. This command sets two options for the Postscript exporter, to make it
  8528. print in two columns in landscape format---the resulting page can be cut
  8529. in two and then used in a paper agenda. The remaining settings modify
  8530. the agenda prefix to omit category and scheduling information, and
  8531. instead include a checkbox to check off items. We also remove the tags
  8532. to make the lines compact, and we don't want to use colors for the
  8533. black-and-white printer. Settings specified in
  8534. @code{org-agenda-exporter-settings} will also apply, but the settings
  8535. in @code{org-agenda-custom-commands} take precedence.
  8536. @noindent
  8537. From the command line you may also use
  8538. @example
  8539. emacs -eval (org-batch-store-agenda-views) -kill
  8540. @end example
  8541. @noindent
  8542. or, if you need to modify some parameters@footnote{Quoting depends on the
  8543. system you use, please check the FAQ for examples.}
  8544. @example
  8545. emacs -eval '(org-batch-store-agenda-views \
  8546. org-agenda-span (quote month) \
  8547. org-agenda-start-day "2007-11-01" \
  8548. org-agenda-include-diary nil \
  8549. org-agenda-files (quote ("~/org/project.org")))' \
  8550. -kill
  8551. @end example
  8552. @noindent
  8553. which will create the agenda views restricted to the file
  8554. @file{~/org/project.org}, without diary entries and with a 30-day
  8555. extent.
  8556. You can also extract agenda information in a way that allows further
  8557. processing by other programs. See @ref{Extracting agenda information}, for
  8558. more information.
  8559. @node Agenda column view
  8560. @section Using column view in the agenda
  8561. @cindex column view, in agenda
  8562. @cindex agenda, column view
  8563. Column view (@pxref{Column view}) is normally used to view and edit
  8564. properties embedded in the hierarchical structure of an Org file. It can be
  8565. quite useful to use column view also from the agenda, where entries are
  8566. collected by certain criteria.
  8567. @table @kbd
  8568. @orgcmd{C-c C-x C-c,org-agenda-columns}
  8569. Turn on column view in the agenda.
  8570. @end table
  8571. To understand how to use this properly, it is important to realize that the
  8572. entries in the agenda are no longer in their proper outline environment.
  8573. This causes the following issues:
  8574. @enumerate
  8575. @item
  8576. @vindex org-columns-default-format
  8577. @vindex org-overriding-columns-format
  8578. Org needs to make a decision which @code{COLUMNS} format to use. Since the
  8579. entries in the agenda are collected from different files, and different files
  8580. may have different @code{COLUMNS} formats, this is a non-trivial problem.
  8581. Org first checks if the variable @code{org-agenda-overriding-columns-format}
  8582. is currently set, and if so, takes the format from there. Otherwise it takes
  8583. the format associated with the first item in the agenda, or, if that item
  8584. does not have a specific format---defined in a property, or in its file---it
  8585. uses @code{org-columns-default-format}.
  8586. @item
  8587. @cindex property, special, CLOCKSUM
  8588. If any of the columns has a summary type defined (@pxref{Column attributes}),
  8589. turning on column view in the agenda will visit all relevant agenda files and
  8590. make sure that the computations of this property are up to date. This is
  8591. also true for the special @code{CLOCKSUM} property. Org will then sum the
  8592. values displayed in the agenda. In the daily/weekly agenda, the sums will
  8593. cover a single day; in all other views they cover the entire block. It is
  8594. vital to realize that the agenda may show the same entry @emph{twice}---for
  8595. example as scheduled and as a deadline---and it may show two entries from the
  8596. same hierarchy---for example a @emph{parent} and its @emph{child}. In these
  8597. cases, the summation in the agenda will lead to incorrect results because
  8598. some values will count double.
  8599. @item
  8600. When the column view in the agenda shows the @code{CLOCKSUM}, that is always
  8601. the entire clocked time for this item. So even in the daily/weekly agenda,
  8602. the clocksum listed in column view may originate from times outside the
  8603. current view. This has the advantage that you can compare these values with
  8604. a column listing the planned total effort for a task---one of the major
  8605. applications for column view in the agenda. If you want information about
  8606. clocked time in the displayed period use clock table mode (press @kbd{R} in
  8607. the agenda).
  8608. @item
  8609. @cindex property, special, CLOCKSUM_T
  8610. When the column view in the agenda shows the @code{CLOCKSUM_T}, that is
  8611. always today's clocked time for this item. So even in the weekly agenda, the
  8612. clocksum listed in column view only originates from today. This lets you
  8613. compare the time you spent on a task for today, with the time already
  8614. spent ---via @code{CLOCKSUM}---and with the planned total effort for it.
  8615. @end enumerate
  8616. @node Markup
  8617. @chapter Markup for rich export
  8618. When exporting Org mode documents, the exporter tries to reflect the
  8619. structure of the document as accurately as possible in the back-end. Since
  8620. export targets like HTML and @LaTeX{} allow much richer formatting, Org mode has
  8621. rules on how to prepare text for rich export. This section summarizes the
  8622. markup rules used in an Org mode buffer.
  8623. @menu
  8624. * Paragraphs:: The basic unit of text
  8625. * Emphasis and monospace:: Bold, italic, etc.
  8626. * Horizontal rules:: Make a line
  8627. * Images and tables:: Images, tables and caption mechanism
  8628. * Literal examples:: Source code examples with special formatting
  8629. * Special symbols:: Greek letters and other symbols
  8630. * Subscripts and superscripts:: Simple syntax for raising/lowering text
  8631. * Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents
  8632. @end menu
  8633. @node Paragraphs
  8634. @section Paragraphs, line breaks, and quoting
  8635. @cindex paragraphs, markup rules
  8636. Paragraphs are separated by at least one empty line. If you need to enforce
  8637. a line break within a paragraph, use @samp{\\} at the end of a line.
  8638. To preserve the line breaks, indentation and blank lines in a region, but
  8639. otherwise use normal formatting, you can use this construct, which can also
  8640. be used to format poetry.
  8641. @cindex #+BEGIN_VERSE
  8642. @cindex verse blocks
  8643. @example
  8644. #+BEGIN_VERSE
  8645. Great clouds overhead
  8646. Tiny black birds rise and fall
  8647. Snow covers Emacs
  8648. -- AlexSchroeder
  8649. #+END_VERSE
  8650. @end example
  8651. When quoting a passage from another document, it is customary to format this
  8652. as a paragraph that is indented on both the left and the right margin. You
  8653. can include quotations in Org mode documents like this:
  8654. @cindex #+BEGIN_QUOTE
  8655. @cindex quote blocks
  8656. @example
  8657. #+BEGIN_QUOTE
  8658. Everything should be made as simple as possible,
  8659. but not any simpler -- Albert Einstein
  8660. #+END_QUOTE
  8661. @end example
  8662. If you would like to center some text, do it like this:
  8663. @cindex #+BEGIN_CENTER
  8664. @cindex center blocks
  8665. @example
  8666. #+BEGIN_CENTER
  8667. Everything should be made as simple as possible, \\
  8668. but not any simpler
  8669. #+END_CENTER
  8670. @end example
  8671. @node Emphasis and monospace
  8672. @section Emphasis and monospace
  8673. @cindex underlined text, markup rules
  8674. @cindex bold text, markup rules
  8675. @cindex italic text, markup rules
  8676. @cindex verbatim text, markup rules
  8677. @cindex code text, markup rules
  8678. @cindex strike-through text, markup rules
  8679. @vindex org-fontify-emphasized-text
  8680. @vindex org-emphasis-regexp-components
  8681. @vindex org-emphasis-alist
  8682. You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=verbatim=}
  8683. and @code{~code~}, and, if you must, @samp{+strike-through+}. Text
  8684. in the code and verbatim string is not processed for Org mode specific
  8685. syntax, it is exported verbatim.
  8686. To turn off fontification for marked up text, you can set
  8687. @code{org-fontify-emphasized-text} to @code{nil}. To narrow down the list of
  8688. available markup syntax, you can customize @code{org-emphasis-alist}. To fine
  8689. tune what characters are allowed before and after the markup characters, you
  8690. can tweak @code{org-emphasis-regexp-components}. Beware that changing one of
  8691. the above variables will no take effect until you reload Org, for which you
  8692. may need to restart Emacs.
  8693. @node Horizontal rules
  8694. @section Horizontal rules
  8695. @cindex horizontal rules, markup rules
  8696. A line consisting of only dashes, and at least 5 of them, will be exported as
  8697. a horizontal line.
  8698. @node Images and tables
  8699. @section Images and Tables
  8700. @cindex tables, markup rules
  8701. @cindex #+CAPTION
  8702. @cindex #+NAME
  8703. Both the native Org mode tables (@pxref{Tables}) and tables formatted with
  8704. the @file{table.el} package will be exported properly. For Org mode tables,
  8705. the lines before the first horizontal separator line will become table header
  8706. lines. You can use the following lines somewhere before the table to assign
  8707. a caption and a label for cross references, and in the text you can refer to
  8708. the object with @code{[[tab:basic-data]]} (@pxref{Internal links}):
  8709. @example
  8710. #+CAPTION: This is the caption for the next table (or link)
  8711. #+NAME: tab:basic-data
  8712. | ... | ...|
  8713. |-----|----|
  8714. @end example
  8715. Optionally, the caption can take the form:
  8716. @example
  8717. #+CAPTION[Caption for list of tables]: Caption for table.
  8718. @end example
  8719. @cindex inlined images, markup rules
  8720. Some back-ends allow you to directly include images into the exported
  8721. document. Org does this, if a link to an image files does not have
  8722. a description part, for example @code{[[./img/a.jpg]]}. If you wish to
  8723. define a caption for the image and maybe a label for internal cross
  8724. references, make sure that the link is on a line by itself and precede it
  8725. with @code{#+CAPTION} and @code{#+NAME} as follows:
  8726. @example
  8727. #+CAPTION: This is the caption for the next figure link (or table)
  8728. #+NAME: fig:SED-HR4049
  8729. [[./img/a.jpg]]
  8730. @end example
  8731. @noindent
  8732. Such images can be displayed within the buffer. @xref{Handling links,the
  8733. discussion of image links}.
  8734. Even though images and tables are prominent examples of captioned structures,
  8735. the same caption mechanism can apply to many others (e.g., @LaTeX{}
  8736. equations, source code blocks). Depending on the export back-end, those may
  8737. or may not be handled.
  8738. @node Literal examples
  8739. @section Literal examples
  8740. @cindex literal examples, markup rules
  8741. @cindex code line references, markup rules
  8742. You can include literal examples that should not be subjected to
  8743. markup. Such examples will be typeset in monospace, so this is well suited
  8744. for source code and similar examples.
  8745. @cindex #+BEGIN_EXAMPLE
  8746. @example
  8747. #+BEGIN_EXAMPLE
  8748. Some example from a text file.
  8749. #+END_EXAMPLE
  8750. @end example
  8751. Note that such blocks may be @i{indented} in order to align nicely with
  8752. indented text and in particular with plain list structure (@pxref{Plain
  8753. lists}). For simplicity when using small examples, you can also start the
  8754. example lines with a colon followed by a space. There may also be additional
  8755. whitespace before the colon:
  8756. @example
  8757. Here is an example
  8758. : Some example from a text file.
  8759. @end example
  8760. @cindex formatting source code, markup rules
  8761. @vindex org-latex-listings
  8762. If the example is source code from a programming language, or any other text
  8763. that can be marked up by font-lock in Emacs, you can ask for the example to
  8764. look like the fontified Emacs buffer@footnote{This works automatically for
  8765. the HTML back-end (it requires version 1.34 of the @file{htmlize.el} package,
  8766. which you need to install). Fontified code chunks in @LaTeX{} can be
  8767. achieved using either the
  8768. @url{https://www.ctan.org/tex-archive/macros/latex/contrib/listings/?lang=en, listings,}
  8769. or the
  8770. @url{https://github.com/gpoore/minted, minted,} package.
  8771. If you use minted or listing, you must load the packages manually, for
  8772. example by adding the desired package to
  8773. @code{org-latex-packages-alist}. Refer to @code{org-latex-listings}
  8774. for details.}. This is done with the @samp{src} block, where you also need
  8775. to specify the name of the major mode that should be used to fontify the
  8776. example@footnote{Code in @samp{src} blocks may also be evaluated either
  8777. interactively or on export. @xref{Working with source code}, for more
  8778. information on evaluating code blocks.}, see @ref{Easy templates} for
  8779. shortcuts to easily insert code blocks.
  8780. @cindex #+BEGIN_SRC
  8781. @example
  8782. #+BEGIN_SRC emacs-lisp
  8783. (defun org-xor (a b)
  8784. "Exclusive or."
  8785. (if a (not b) b))
  8786. #+END_SRC
  8787. @end example
  8788. Both in @code{example} and in @code{src} snippets, you can add a @code{-n}
  8789. switch to the end of the @code{BEGIN} line, to get the lines of the example
  8790. numbered. The @code{-n} takes an optional numeric argument specifying the
  8791. starting line number of the block. If you use a @code{+n} switch, the
  8792. numbering from the previous numbered snippet will be continued in the current
  8793. one. The @code{+n} can also take a numeric argument. The value of the
  8794. argument will be added to the last line of the previous block to determine
  8795. the starting line number.
  8796. @example
  8797. #+BEGIN_SRC emacs-lisp -n 20
  8798. ;; this will export with line number 20
  8799. (message "This is line 21")
  8800. #+END_SRC
  8801. #+BEGIN_SRC emacs-lisp +n 10
  8802. ;; This will be listed as line 31
  8803. (message "This is line 32")
  8804. #+END_SRC
  8805. @end example
  8806. In literal examples, Org will interpret strings like @samp{(ref:name)} as
  8807. labels, and use them as targets for special hyperlinks like @code{[[(name)]]}
  8808. (i.e., the reference name enclosed in single parenthesis). In HTML, hovering
  8809. the mouse over such a link will remote-highlight the corresponding code line,
  8810. which is kind of cool.
  8811. You can also add a @code{-r} switch which @i{removes} the labels from the
  8812. source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the
  8813. labels in the source code while using line numbers for the links, which might
  8814. be useful to explain those in an Org mode example code.}. With the @code{-n}
  8815. switch, links to these references will be labeled by the line numbers from
  8816. the code listing, otherwise links will use the labels with no parentheses.
  8817. Here is an example:
  8818. @example
  8819. #+BEGIN_SRC emacs-lisp -n -r
  8820. (save-excursion (ref:sc)
  8821. (goto-char (point-min))) (ref:jump)
  8822. #+END_SRC
  8823. In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]]
  8824. jumps to point-min.
  8825. @end example
  8826. @cindex indentation, in source blocks
  8827. Finally, you can use @code{-i} to preserve the indentation of a specific code
  8828. block (@pxref{Editing source code}).
  8829. @vindex org-coderef-label-format
  8830. If the syntax for the label format conflicts with the language syntax, use a
  8831. @code{-l} switch to change the format, for example @samp{#+BEGIN_SRC pascal
  8832. -n -r -l "((%s))"}. See also the variable @code{org-coderef-label-format}.
  8833. HTML export also allows examples to be published as text areas (@pxref{Text
  8834. areas in HTML export}).
  8835. Because the @code{#+BEGIN_...} and @code{#+END_...} patterns need to be added
  8836. so often, shortcuts are provided using the Easy templates facility
  8837. (@pxref{Easy templates}).
  8838. @table @kbd
  8839. @kindex C-c '
  8840. @item C-c '
  8841. Edit the source code example at point in its native mode. This works by
  8842. switching to a temporary buffer with the source code. You need to exit by
  8843. pressing @kbd{C-c '} again@footnote{Upon exit, lines starting with @samp{*},
  8844. @samp{,*}, @samp{#+} and @samp{,#+} will get a comma prepended, to keep them
  8845. from being interpreted by Org as outline nodes or special syntax. These
  8846. commas will be stripped for editing with @kbd{C-c '}, and also for export.}.
  8847. The edited version will then replace the old version in the Org buffer.
  8848. Fixed-width regions (where each line starts with a colon followed by a space)
  8849. will be edited using @code{artist-mode}@footnote{You may select
  8850. a different-mode with the variable @code{org-edit-fixed-width-region-mode}.}
  8851. to allow creating ASCII drawings easily. Using this command in an empty line
  8852. will create a new fixed-width region.
  8853. @kindex C-c l
  8854. @item C-c l
  8855. Calling @code{org-store-link} while editing a source code example in a
  8856. temporary buffer created with @kbd{C-c '} will prompt for a label. Make sure
  8857. that it is unique in the current buffer, and insert it with the proper
  8858. formatting like @samp{(ref:label)} at the end of the current line. Then the
  8859. label is stored as a link @samp{(label)}, for retrieval with @kbd{C-c C-l}.
  8860. @end table
  8861. @node Special symbols
  8862. @section Special symbols
  8863. @cindex Org entities
  8864. @cindex math symbols
  8865. @cindex special symbols
  8866. @cindex HTML entities
  8867. @cindex @LaTeX{} entities
  8868. You can use @LaTeX{}-like syntax to insert special symbols---named
  8869. entities---like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to
  8870. indicate an arrow. Completion for these symbols is available, just type
  8871. @samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible
  8872. completions. If you need such a symbol inside a word, terminate it with
  8873. a pair of curly brackets. For example
  8874. @example
  8875. Pro tip: Given a circle \Gamma of diameter d, the length of its circumference
  8876. is \pi@{@}d.
  8877. @end example
  8878. @findex org-entities-help
  8879. @vindex org-entities-user
  8880. A large number of entities is provided, with names taken from both HTML and
  8881. @LaTeX{}; you can comfortably browse the complete list from a dedicated
  8882. buffer using the command @code{org-entities-help}. It is also possible to
  8883. provide your own special symbols in the variable @code{org-entities-user}.
  8884. During export, these symbols are transformed into the native format of the
  8885. exporter back-end. Strings like @code{\alpha} are exported as @code{&alpha;}
  8886. in the HTML output, and as @code{\(\alpha\)} in the @LaTeX{} output.
  8887. Similarly, @code{\nbsp} becomes @code{&nbsp;} in HTML and @code{~} in
  8888. @LaTeX{}.
  8889. @cindex escaping characters
  8890. Entities may also be used as a may to escape markup in an Org document, e.g.,
  8891. @samp{\under@{@}not underlined\under} exports as @samp{_not underlined_}.
  8892. @cindex special symbols, in-buffer display
  8893. If you would like to see entities displayed as UTF-8 characters, use the
  8894. following command@footnote{You can turn this on by default by setting the
  8895. variable @code{org-pretty-entities}, or on a per-file base with the
  8896. @code{#+STARTUP} option @code{entitiespretty}.}:
  8897. @table @kbd
  8898. @cindex @code{entitiespretty}, STARTUP keyword
  8899. @kindex C-c C-x \
  8900. @item C-c C-x \
  8901. Toggle display of entities as UTF-8 characters. This does not change the
  8902. buffer content which remains plain ASCII, but it overlays the UTF-8 character
  8903. for display purposes only.
  8904. @end table
  8905. @cindex shy hyphen, special symbol
  8906. @cindex dash, special symbol
  8907. @cindex ellipsis, special symbol
  8908. In addition to regular entities defined above, Org exports in a special
  8909. way@footnote{This behaviour can be disabled with @code{-} export setting
  8910. (@pxref{Export settings}).} the following commonly used character
  8911. combinations: @samp{\-} is treated as a shy hyphen, @samp{--} and @samp{---}
  8912. are converted into dashes, and @samp{...} becomes a compact set of dots.
  8913. @node Subscripts and superscripts
  8914. @section Subscripts and superscripts
  8915. @cindex subscript
  8916. @cindex superscript
  8917. @samp{^} and @samp{_} are used to indicate super- and subscripts. To
  8918. increase the readability of ASCII text, it is not necessary---but OK---to
  8919. surround multi-character sub- and superscripts with curly braces. Those are,
  8920. however, mandatory, when more than one word is involved. For example
  8921. @example
  8922. The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, the
  8923. radius of Alpha Centauri is R_@{Alpha Centauri@} = 1.28 x R_@{sun@}.
  8924. @end example
  8925. @vindex org-use-sub-superscripts
  8926. If you write a text where the underscore is often used in a different
  8927. context, Org's convention to always interpret these as subscripts can get in
  8928. your way. Configure the variable @code{org-use-sub-superscripts} to change
  8929. this convention. For example, when setting this variable to @code{@{@}},
  8930. @samp{a_b} will not be interpreted as a subscript, but @samp{a_@{b@}} will.
  8931. @table @kbd
  8932. @kindex C-c C-x \
  8933. @item C-c C-x \
  8934. In addition to showing entities as UTF-8 characters, this command will also
  8935. format sub- and superscripts in a WYSIWYM way.
  8936. @end table
  8937. @node Embedded @LaTeX{}
  8938. @section Embedded @LaTeX{}
  8939. @cindex @TeX{} interpretation
  8940. @cindex @LaTeX{} interpretation
  8941. Plain ASCII is normally sufficient for almost all note taking. Exceptions
  8942. include scientific notes, which often require mathematical symbols and the
  8943. occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on
  8944. Donald E. Knuth's @TeX{} system. Many of the features described here as
  8945. ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this
  8946. distinction.} is widely used to typeset scientific documents. Org mode
  8947. supports embedding @LaTeX{} code into its files, because many academics are
  8948. used to writing and reading @LaTeX{} source code, and because it can be
  8949. readily processed to produce pretty output for a number of export back-ends.
  8950. @menu
  8951. * @LaTeX{} fragments:: Complex formulas made easy
  8952. * Previewing @LaTeX{} fragments:: What will this snippet look like?
  8953. * CDLaTeX mode:: Speed up entering of formulas
  8954. @end menu
  8955. @node @LaTeX{} fragments
  8956. @subsection @LaTeX{} fragments
  8957. @cindex @LaTeX{} fragments
  8958. @vindex org-format-latex-header
  8959. Org mode can contain @LaTeX{} math fragments, and it supports ways to process
  8960. these for several export back-ends. When exporting to @LaTeX{}, the code is
  8961. left as it is. When exporting to HTML, Org can use either
  8962. @uref{http://www.mathjax.org, MathJax} (@pxref{Math formatting in HTML
  8963. export}) or transcode the math into images (see @pxref{Previewing @LaTeX{}
  8964. fragments}).
  8965. @LaTeX{} fragments don't need any special marking at all. The following
  8966. snippets will be identified as @LaTeX{} source code:
  8967. @itemize @bullet
  8968. @item
  8969. Environments of any kind@footnote{When MathJax is used, only the
  8970. environments recognized by MathJax will be processed. When
  8971. @file{dvipng} program, @file{dvisvgm} program or @file{imagemagick} suite is
  8972. used to create images, any @LaTeX{} environment will be handled.}. The only
  8973. requirement is that the @code{\begin} statement appears on a new line, at the
  8974. beginning of the line or after whitespaces only.
  8975. @item
  8976. Text within the usual @LaTeX{} math delimiters. To avoid conflicts with
  8977. currency specifications, single @samp{$} characters are only recognized as
  8978. math delimiters if the enclosed text contains at most two line breaks, is
  8979. directly attached to the @samp{$} characters with no whitespace in between,
  8980. and if the closing @samp{$} is followed by whitespace or punctuation
  8981. (parentheses and quotes are considered to be punctuation in this
  8982. context). For the other delimiters, there is no such restriction, so when in
  8983. doubt, use @samp{\(...\)} as inline math delimiters.
  8984. @end itemize
  8985. @noindent For example:
  8986. @example
  8987. \begin@{equation@}
  8988. x=\sqrt@{b@}
  8989. \end@{equation@}
  8990. If $a^2=b$ and \( b=2 \), then the solution must be
  8991. either $$ a=+\sqrt@{2@} $$ or \[ a=-\sqrt@{2@} \].
  8992. @end example
  8993. @c FIXME
  8994. @c @noindent
  8995. @c @vindex org-format-latex-options
  8996. @c If you need any of the delimiter ASCII sequences for other purposes, you
  8997. @c can configure the option @code{org-format-latex-options} to deselect the
  8998. @c ones you do not wish to have interpreted by the @LaTeX{} converter.
  8999. @vindex org-export-with-latex
  9000. @LaTeX{} processing can be configured with the variable
  9001. @code{org-export-with-latex}. The default setting is @code{t} which means
  9002. MathJax for HTML, and no processing for ASCII and @LaTeX{} back-ends.
  9003. You can also set this variable on a per-file basis using one of these
  9004. lines:
  9005. @example
  9006. #+OPTIONS: tex:t @r{Do the right thing automatically (MathJax)}
  9007. #+OPTIONS: tex:nil @r{Do not process @LaTeX{} fragments at all}
  9008. #+OPTIONS: tex:verbatim @r{Verbatim export, for jsMath or so}
  9009. @end example
  9010. @node Previewing @LaTeX{} fragments
  9011. @subsection Previewing @LaTeX{} fragments
  9012. @cindex @LaTeX{} fragments, preview
  9013. @vindex org-preview-latex-default-process
  9014. If you have a working @LaTeX{} installation and @file{dvipng}, @file{dvisvgm}
  9015. or @file{convert} installed@footnote{These are respectively available at
  9016. @url{http://sourceforge.net/projects/dvipng/}, @url{http://dvisvgm.bplaced.net/}
  9017. and from the @file{imagemagick} suite. Choose the converter by setting the
  9018. variable @code{org-preview-latex-default-process} accordingly.}, @LaTeX{}
  9019. fragments can be processed to produce images of the typeset expressions to be
  9020. used for inclusion while exporting to HTML (see @pxref{@LaTeX{} fragments}),
  9021. or for inline previewing within Org mode.
  9022. @vindex org-format-latex-options
  9023. @vindex org-format-latex-header
  9024. You can customize the variables @code{org-format-latex-options} and
  9025. @code{org-format-latex-header} to influence some aspects of the preview. In
  9026. particular, the @code{:scale} (and for HTML export, @code{:html-scale})
  9027. property of the former can be used to adjust the size of the preview images.
  9028. @table @kbd
  9029. @kindex C-c C-x C-l
  9030. @item C-c C-x C-l
  9031. Produce a preview image of the @LaTeX{} fragment at point and overlay it
  9032. over the source code. If there is no fragment at point, process all
  9033. fragments in the current entry (between two headlines). When called
  9034. with a prefix argument, process the entire subtree. When called with
  9035. two prefix arguments, or when the cursor is before the first headline,
  9036. process the entire buffer.
  9037. @kindex C-c C-c
  9038. @item C-c C-c
  9039. Remove the overlay preview images.
  9040. @end table
  9041. @vindex org-startup-with-latex-preview
  9042. You can turn on the previewing of all @LaTeX{} fragments in a file with
  9043. @example
  9044. #+STARTUP: latexpreview
  9045. @end example
  9046. To disable it, simply use
  9047. @example
  9048. #+STARTUP: nolatexpreview
  9049. @end example
  9050. @node CDLaTeX mode
  9051. @subsection Using CD@LaTeX{} to enter math
  9052. @cindex CD@LaTeX{}
  9053. CD@LaTeX{} mode is a minor mode that is normally used in combination with a
  9054. major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of
  9055. environments and math templates. Inside Org mode, you can make use of
  9056. some of the features of CD@LaTeX{} mode. You need to install
  9057. @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with
  9058. AUC@TeX{}) from @url{https://staff.fnwi.uva.nl/c.dominik/Tools/cdlatex}.
  9059. Don't use CD@LaTeX{} mode itself under Org mode, but use the light
  9060. version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it
  9061. on for the current buffer with @kbd{M-x org-cdlatex-mode RET}, or for all
  9062. Org files with
  9063. @lisp
  9064. (add-hook 'org-mode-hook 'turn-on-org-cdlatex)
  9065. @end lisp
  9066. When this mode is enabled, the following features are present (for more
  9067. details see the documentation of CD@LaTeX{} mode):
  9068. @itemize @bullet
  9069. @kindex C-c @{
  9070. @item
  9071. Environment templates can be inserted with @kbd{C-c @{}.
  9072. @item
  9073. @kindex @key{TAB}
  9074. The @key{TAB} key will do template expansion if the cursor is inside a
  9075. @LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is
  9076. inside such a fragment, see the documentation of the function
  9077. @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will
  9078. expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor
  9079. correctly inside the first brace. Another @key{TAB} will get you into
  9080. the second brace. Even outside fragments, @key{TAB} will expand
  9081. environment abbreviations at the beginning of a line. For example, if
  9082. you write @samp{equ} at the beginning of a line and press @key{TAB},
  9083. this abbreviation will be expanded to an @code{equation} environment.
  9084. To get a list of all abbreviations, type @kbd{M-x cdlatex-command-help RET}.
  9085. @item
  9086. @kindex _
  9087. @kindex ^
  9088. @vindex cdlatex-simplify-sub-super-scripts
  9089. Pressing @kbd{_} and @kbd{^} inside a @LaTeX{} fragment will insert these
  9090. characters together with a pair of braces. If you use @key{TAB} to move
  9091. out of the braces, and if the braces surround only a single character or
  9092. macro, they are removed again (depending on the variable
  9093. @code{cdlatex-simplify-sub-super-scripts}).
  9094. @item
  9095. @kindex `
  9096. Pressing the grave accent @kbd{`} followed by a character inserts math
  9097. macros, also outside @LaTeX{} fragments. If you wait more than 1.5 seconds
  9098. after the grave accent, a help window will pop up.
  9099. @item
  9100. @kindex '
  9101. Pressing the apostrophe @kbd{'} followed by another character modifies
  9102. the symbol before point with an accent or a font. If you wait more than
  9103. 1.5 seconds after the apostrophe, a help window will pop up. Character
  9104. modification will work only inside @LaTeX{} fragments; outside the quote
  9105. is normal.
  9106. @end itemize
  9107. @node Exporting
  9108. @chapter Exporting
  9109. @cindex exporting
  9110. Sometimes, you may want to pretty print your notes, publish them on the web
  9111. or even share them with people not using Org. In these cases, the Org export
  9112. facilities can be used to convert your documents to a variety of other
  9113. formats, while retaining as much structure (@pxref{Document structure}) and
  9114. markup (@pxref{Markup}) as possible.
  9115. @cindex export back-end
  9116. Libraries responsible for such translation are called back-ends. Org ships
  9117. with the following ones
  9118. @itemize
  9119. @item ascii (ASCII format)
  9120. @item beamer (@LaTeX{} Beamer format)
  9121. @item html (HTML format)
  9122. @item icalendar (iCalendar format)
  9123. @item latex (@LaTeX{} format)
  9124. @item md (Markdown format)
  9125. @item odt (OpenDocument Text format)
  9126. @item org (Org format)
  9127. @item texinfo (Texinfo format)
  9128. @item man (Man page format)
  9129. @end itemize
  9130. @noindent Org also uses additional libraries located in @code{contrib/}
  9131. directory (@pxref{Installation}). Users can install additional export
  9132. libraries for additional formats from the Emacs packaging system. For easy
  9133. discovery, these packages have a common naming scheme: @file{ox-NAME}, where
  9134. NAME is one of the formats. For example, @file{ox-koma-letter} for
  9135. @code{koma-letter} back-end.
  9136. @vindex org-export-backends
  9137. Org loads back-ends for the following formats by default: @code{ascii},
  9138. @code{html}, @code{icalendar}, @code{latex} and @code{odt}.
  9139. Org can load additional back-ends either of two ways: through the
  9140. @code{org-export-backends} variable configuration; or, by requiring the
  9141. library in the Emacs init file like this:
  9142. @lisp
  9143. (require 'ox-md)
  9144. @end lisp
  9145. @menu
  9146. * The export dispatcher:: The main interface
  9147. * Export settings:: Common export settings
  9148. * Table of contents:: The if and where of the table of contents
  9149. * Include files:: Include additional files into a document
  9150. * Macro replacement:: Use macros to create templates
  9151. * Comment lines:: What will not be exported
  9152. * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding
  9153. * Beamer export:: Exporting as a Beamer presentation
  9154. * HTML export:: Exporting to HTML
  9155. * @LaTeX{} export:: Exporting to @LaTeX{}, and processing to PDF
  9156. * Markdown export:: Exporting to Markdown
  9157. * OpenDocument Text export:: Exporting to OpenDocument Text
  9158. * Org export:: Exporting to Org
  9159. * Texinfo export:: Exporting to Texinfo
  9160. * iCalendar export:: Exporting to iCalendar
  9161. * Other built-in back-ends:: Exporting to a man page
  9162. * Advanced configuration:: Fine-tuning the export output
  9163. * Export in foreign buffers:: Author tables and lists in Org syntax
  9164. @end menu
  9165. @node The export dispatcher
  9166. @section The export dispatcher
  9167. @vindex org-export-dispatch-use-expert-ui
  9168. @cindex Export, dispatcher
  9169. The export dispatcher is the main interface for Org's exports. A
  9170. hierarchical menu presents the currently configured export formats. Options
  9171. are shown as easy toggle switches on the same screen.
  9172. Org also has a minimal prompt interface for the export dispatcher. When the
  9173. variable @code{org-export-dispatch-use-expert-ui} is set to a non-@code{nil}
  9174. value, Org prompts in the minibuffer. To switch back to the hierarchical
  9175. menu, press @key{?}.
  9176. @table @asis
  9177. @orgcmd{C-c C-e,org-export-dispatch}
  9178. Invokes the export dispatcher interface. The options show default settings.
  9179. The @kbd{C-u} prefix argument preserves options from the previous export,
  9180. including any sub-tree selections.
  9181. @end table
  9182. Org exports the entire buffer by default. If the Org buffer has an active
  9183. region, then Org exports just that region.
  9184. These are the export options, the key combinations that toggle them
  9185. (@pxref{Export settings}):
  9186. @table @kbd
  9187. @item C-a
  9188. @vindex org-export-async-init-file
  9189. Toggles asynchronous export. Asynchronous export uses an external Emacs
  9190. process with a specially configured initialization file to complete the
  9191. exporting process in the background thereby releasing the current interface.
  9192. This is particularly useful when exporting long documents.
  9193. Output from an asynchronous export is saved on the ``the export stack''. To
  9194. view this stack, call the export dispatcher with a double @kbd{C-u} prefix
  9195. argument. If already in the export dispatcher menu, @kbd{&} displays the
  9196. stack.
  9197. @vindex org-export-in-background
  9198. To make the background export process the default, customize the variable,
  9199. @code{org-export-in-background}.
  9200. @item C-b
  9201. Toggle body-only export. Useful for excluding headers and footers in the
  9202. export. Affects only those back-end formats that have such sections---like
  9203. @code{<head>...</head>} in HTML.
  9204. @item C-s
  9205. @vindex org-export-initial-scope
  9206. Toggle sub-tree export. When turned on, Org exports only the sub-tree starting
  9207. from the cursor position at the time the export dispatcher was invoked. Org
  9208. uses the top heading of this sub-tree as the document's title. If the cursor
  9209. is not on a heading, Org uses the nearest enclosing header. If the cursor is
  9210. in the document preamble, Org signals an error and aborts export.
  9211. To make the sub-tree export the default, customize the variable,
  9212. @code{org-export-initial-scope}.
  9213. @item C-v
  9214. Toggle visible-only export. Useful for exporting only visible parts of an
  9215. Org document by adjusting outline visibility settings.
  9216. @end table
  9217. @node Export settings
  9218. @section Export settings
  9219. @cindex Export, settings
  9220. @cindex #+OPTIONS
  9221. Export options can be set: globally with variables; for an individual file by
  9222. making variables buffer-local with in-buffer settings (@pxref{In-buffer
  9223. settings}), by setting individual keywords, or by specifying them in a
  9224. compact form with the @code{#+OPTIONS} keyword; or for a tree by setting
  9225. properties (@pxref{Properties and columns}). Options set at a specific level
  9226. override options set at a more general level.
  9227. @cindex #+SETUPFILE
  9228. In-buffer settings may appear anywhere in the file, either directly or
  9229. indirectly through a file included using @samp{#+SETUPFILE: filename or URL}
  9230. syntax. Option keyword sets tailored to a particular back-end can be
  9231. inserted from the export dispatcher (@pxref{The export dispatcher}) using the
  9232. @code{Insert template} command by pressing @key{#}. To insert keywords
  9233. individually, a good way to make sure the keyword is correct is to type
  9234. @code{#+} and then to use @kbd{M-@key{TAB}}@footnote{Many desktops intercept
  9235. @kbd{M-TAB} to switch windows. Use @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}}
  9236. instead.} for completion.
  9237. The export keywords available for every back-end, and their equivalent global
  9238. variables, include:
  9239. @table @samp
  9240. @item AUTHOR
  9241. @cindex #+AUTHOR
  9242. @vindex user-full-name
  9243. The document author (@code{user-full-name}).
  9244. @item CREATOR
  9245. @cindex #+CREATOR
  9246. @vindex org-export-creator-string
  9247. Entity responsible for output generation (@code{org-export-creator-string}).
  9248. @item DATE
  9249. @cindex #+DATE
  9250. @vindex org-export-date-timestamp-format
  9251. A date or a time-stamp@footnote{The variable
  9252. @code{org-export-date-timestamp-format} defines how this time-stamp will be
  9253. exported.}.
  9254. @item EMAIL
  9255. @cindex #+EMAIL
  9256. @vindex user-mail-address
  9257. The email address (@code{user-mail-address}).
  9258. @item LANGUAGE
  9259. @cindex #+LANGUAGE
  9260. @vindex org-export-default-language
  9261. Language to use for translating certain strings
  9262. (@code{org-export-default-language}). With @samp{#+LANGUAGE: fr}, for
  9263. example, Org translates @emph{Table of contents} to the French @emph{Table
  9264. des matières}.
  9265. @item SELECT_TAGS
  9266. @cindex #+SELECT_TAGS
  9267. @vindex org-export-select-tags
  9268. The default value is @code{:export:}. When a tree is tagged with
  9269. @code{:export:} (@code{org-export-select-tags}), Org selects that tree and
  9270. its sub-trees for export. Org excludes trees with @code{:noexport:} tags,
  9271. see below. When selectively exporting files with @code{:export:} tags set,
  9272. Org does not export any text that appears before the first headline.
  9273. @item EXCLUDE_TAGS
  9274. @cindex #+EXCLUDE_TAGS
  9275. @vindex org-export-exclude-tags
  9276. The default value is @code{:noexport:}. When a tree is tagged with
  9277. @code{:noexport:} (@code{org-export-exclude-tags}), Org excludes that tree
  9278. and its sub-trees from export. Entries tagged with @code{:noexport:} will be
  9279. unconditionally excluded from the export, even if they have an
  9280. @code{:export:} tag. Even if a sub-tree is not exported, Org will execute any
  9281. code blocks contained in them.
  9282. @item TITLE
  9283. @cindex #+TITLE
  9284. @cindex document title
  9285. Org displays this title. For long titles, use multiple @code{#+TITLE} lines.
  9286. @item EXPORT_FILE_NAME
  9287. @cindex #+EXPORT_FILE_NAME
  9288. The name of the output file to be generated. Otherwise, Org generates the
  9289. file name based on the buffer name and the extension based on the back-end
  9290. format.
  9291. @end table
  9292. The @code{#+OPTIONS} keyword is a compact form. To configure multiple
  9293. options, use several @code{#+OPTIONS} lines. @code{#+OPTIONS} recognizes the
  9294. following arguments.
  9295. @table @code
  9296. @item ':
  9297. @vindex org-export-with-smart-quotes
  9298. Toggle smart quotes (@code{org-export-with-smart-quotes}). Depending on the
  9299. language used, when activated, Org treats pairs of double quotes as primary
  9300. quotes, pairs of single quotes as secondary quotes, and single quote marks as
  9301. apostrophes.
  9302. @item *:
  9303. Toggle emphasized text (@code{org-export-with-emphasize}).
  9304. @item -:
  9305. @vindex org-export-with-special-strings
  9306. Toggle conversion of special strings
  9307. (@code{org-export-with-special-strings}).
  9308. @item ::
  9309. @vindex org-export-with-fixed-width
  9310. Toggle fixed-width sections
  9311. (@code{org-export-with-fixed-width}).
  9312. @item <:
  9313. @vindex org-export-with-timestamps
  9314. Toggle inclusion of time/date active/inactive stamps
  9315. (@code{org-export-with-timestamps}).
  9316. @item \n:
  9317. @vindex org-export-preserve-breaks
  9318. Toggles whether to preserve line breaks (@code{org-export-preserve-breaks}).
  9319. @item ^:
  9320. @vindex org-export-with-sub-superscripts
  9321. Toggle @TeX{}-like syntax for sub- and superscripts. If you write "^:@{@}",
  9322. @samp{a_@{b@}} will be interpreted, but the simple @samp{a_b} will be left as
  9323. it is (@code{org-export-with-sub-superscripts}).
  9324. @item arch:
  9325. @vindex org-export-with-archived-trees
  9326. Configure how archived trees are exported. When set to @code{headline}, the
  9327. export process skips the contents and processes only the headlines
  9328. (@code{org-export-with-archived-trees}).
  9329. @item author:
  9330. @vindex org-export-with-author
  9331. Toggle inclusion of author name into exported file
  9332. (@code{org-export-with-author}).
  9333. @item broken-links:
  9334. @vindex org-export-with-broken-links
  9335. Toggles if Org should continue exporting upon finding a broken internal link.
  9336. When set to @code{mark}, Org clearly marks the problem link in the output
  9337. (@code{org-export-with-broken-links}).
  9338. @item c:
  9339. @vindex org-export-with-clocks
  9340. Toggle inclusion of CLOCK keywords (@code{org-export-with-clocks}).
  9341. @item creator:
  9342. @vindex org-export-with-creator
  9343. Toggle inclusion of creator information in the exported file
  9344. (@code{org-export-with-creator}).
  9345. @item d:
  9346. @vindex org-export-with-drawers
  9347. Toggles inclusion of drawers, or list of drawers to include, or list of
  9348. drawers to exclude (@code{org-export-with-drawers}).
  9349. @item date:
  9350. @vindex org-export-with-date
  9351. Toggle inclusion of a date into exported file (@code{org-export-with-date}).
  9352. @item e:
  9353. @vindex org-export-with-entities
  9354. Toggle inclusion of entities (@code{org-export-with-entities}).
  9355. @item email:
  9356. @vindex org-export-with-email
  9357. Toggle inclusion of the author's e-mail into exported file
  9358. (@code{org-export-with-email}).
  9359. @item f:
  9360. @vindex org-export-with-footnotes
  9361. Toggle the inclusion of footnotes (@code{org-export-with-footnotes}).
  9362. @item H:
  9363. @vindex org-export-headline-levels
  9364. Set the number of headline levels for export
  9365. (@code{org-export-headline-levels}). Below that level, headlines are treated
  9366. differently. In most back-ends, they become list items.
  9367. @item inline:
  9368. @vindex org-export-with-inlinetasks
  9369. Toggle inclusion of inlinetasks (@code{org-export-with-inlinetasks}).
  9370. @item num:
  9371. @vindex org-export-with-section-numbers
  9372. @cindex property, UNNUMBERED
  9373. Toggle section-numbers (@code{org-export-with-section-numbers}). When set to
  9374. number @samp{n}, Org numbers only those headlines at level @samp{n} or above.
  9375. Set @code{UNNUMBERED} property to non-@code{nil} to disable numbering of
  9376. heading and subheadings entirely.
  9377. @item p:
  9378. @vindex org-export-with-planning
  9379. Toggle export of planning information (@code{org-export-with-planning}).
  9380. ``Planning information'' comes from lines located right after the headline
  9381. and contain any combination of these cookies: @code{SCHEDULED:},
  9382. @code{DEADLINE:}, or @code{CLOSED:}.
  9383. @item pri:
  9384. @vindex org-export-with-priority
  9385. Toggle inclusion of priority cookies (@code{org-export-with-priority}).
  9386. @item prop:
  9387. @vindex org-export-with-properties
  9388. Toggle inclusion of property drawers, or list the properties to include
  9389. (@code{org-export-with-properties}).
  9390. @item stat:
  9391. @vindex org-export-with-statistics-cookies
  9392. Toggle inclusion of statistics cookies
  9393. (@code{org-export-with-statistics-cookies}).
  9394. @item tags:
  9395. @vindex org-export-with-tags
  9396. Toggle inclusion of tags, may also be @code{not-in-toc}
  9397. (@code{org-export-with-tags}).
  9398. @item tasks:
  9399. @vindex org-export-with-tasks
  9400. Toggle inclusion of tasks (TODO items); or @code{nil} to remove all tasks; or
  9401. @code{todo} to remove DONE tasks; or list the keywords to keep
  9402. (@code{org-export-with-tasks}).
  9403. @item tex:
  9404. @vindex org-export-with-latex
  9405. @code{nil} does not export; @code{t} exports; @code{verbatim} keeps
  9406. everything in verbatim (@code{org-export-with-latex}).
  9407. @item timestamp:
  9408. @vindex org-export-time-stamp-file
  9409. Toggle inclusion of the creation time in the exported file
  9410. (@code{org-export-time-stamp-file}).
  9411. @item title:
  9412. @vindex org-export-with-title
  9413. Toggle inclusion of title (@code{org-export-with-title}).
  9414. @item toc:
  9415. @vindex org-export-with-toc
  9416. Toggle inclusion of the table of contents, or set the level limit
  9417. (@code{org-export-with-toc}).
  9418. @item todo:
  9419. @vindex org-export-with-todo-keywords
  9420. Toggle inclusion of TODO keywords into exported text
  9421. (@code{org-export-with-todo-keywords}).
  9422. @item |:
  9423. @vindex org-export-with-tables
  9424. Toggle inclusion of tables (@code{org-export-with-tables}).
  9425. @end table
  9426. When exporting sub-trees, special node properties in them can override the
  9427. above keywords. They are special because they have an @samp{EXPORT_} prefix.
  9428. For example, @samp{DATE} and @samp{EXPORT_FILE_NAME} keywords become,
  9429. respectively, @samp{EXPORT_DATE} and @samp{EXPORT_FILE_NAME}. Except for
  9430. @samp{SETUPFILE}, all other keywords listed above have an @samp{EXPORT_}
  9431. equivalent.
  9432. @cindex #+BIND
  9433. @vindex org-export-allow-bind-keywords
  9434. If @code{org-export-allow-bind-keywords} is non-@code{nil}, Emacs variables
  9435. can become buffer-local during export by using the BIND keyword. Its syntax
  9436. is @samp{#+BIND: variable value}. This is particularly useful for in-buffer
  9437. settings that cannot be changed using keywords.
  9438. @node Table of contents
  9439. @section Table of contents
  9440. @cindex table of contents
  9441. @cindex list of tables
  9442. @cindex list of listings
  9443. @cindex #+TOC
  9444. @vindex org-export-with-toc
  9445. Org normally inserts the table of contents directly before the first headline
  9446. of the file. Org sets the TOC depth the same as the headline levels in the
  9447. file. Use a lower number for lower TOC depth. To turn off TOC entirely, use
  9448. @code{nil}. This is configured in the @code{org-export-with-toc} variable or
  9449. as keywords in an Org file as:
  9450. @example
  9451. #+OPTIONS: toc:2 @r{only include two levels in TOC}
  9452. #+OPTIONS: toc:nil @r{no default TOC at all}
  9453. @end example
  9454. To move the table of contents to a different location, first turn off the
  9455. default with @code{org-export-with-toc} variable or with @code{#+OPTIONS:
  9456. toc:nil}. Then insert @code{#+TOC: headlines N} at the desired location(s).
  9457. @example
  9458. #+OPTIONS: toc:nil @r{no default TOC}
  9459. ...
  9460. #+TOC: headlines 2 @r{insert TOC here, with two headline levels}
  9461. @end example
  9462. To adjust the TOC depth for a specific section of the Org document, append an
  9463. additional @samp{local} parameter. This parameter becomes a relative depth
  9464. for the current level.
  9465. Note that for this feature to work properly in @LaTeX{} export, the Org file
  9466. requires the inclusion of the @code{titletoc} package. Because of
  9467. compatibility issues, @code{titletoc} has to be loaded @emph{before}
  9468. @code{hyperref}. Customize the @code{org-latex-default-packages-alist}
  9469. variable.
  9470. @example
  9471. * Section #+TOC: headlines 1 local @r{insert local TOC, with direct children
  9472. only}
  9473. @end example
  9474. Use the @code{TOC} keyword to generate list of tables (resp.@: all listings)
  9475. with captions.
  9476. @example
  9477. #+TOC: listings @r{build a list of listings}
  9478. #+TOC: tables @r{build a list of tables}
  9479. @end example
  9480. @cindex property, ALT_TITLE
  9481. Normally Org uses the headline for its entry in the table of contents. But
  9482. with @code{ALT_TITLE} property, a different entry can be specified for the
  9483. table of contents.
  9484. @node Include files
  9485. @section Include files
  9486. @cindex include files, during export
  9487. Include other files during export. For example, to include your @file{.emacs}
  9488. file, you could use:
  9489. @cindex #+INCLUDE
  9490. @example
  9491. #+INCLUDE: "~/.emacs" src emacs-lisp
  9492. @end example
  9493. @noindent
  9494. The first parameter is the file name to include. The optional second
  9495. parameter specifies the block type: @samp{example}, @samp{export} or
  9496. @samp{src}. The optional third parameter specifies the source code language
  9497. to use for formatting the contents. This is relevant to both @samp{export}
  9498. and @samp{src} block types.
  9499. If an include file is specified as having a markup language, Org neither
  9500. checks for valid syntax nor changes the contents in any way. For
  9501. @samp{example} and @samp{src} blocks, Org code-escapes the contents before
  9502. inclusion.
  9503. If an include file is not specified as having any markup language, Org
  9504. assumes it be in Org format and proceeds as usual with a few exceptions. Org
  9505. makes the footnote labels (@pxref{Footnotes}) in the included file local to
  9506. that file. The contents of the included file will belong to the same
  9507. structure---headline, item---containing the @code{INCLUDE} keyword. In
  9508. particular, headlines within the file will become children of the current
  9509. section. That behavior can be changed by providing an additional keyword
  9510. parameter, @code{:minlevel}. It shifts the headlines in the included file to
  9511. become the lowest level. For example, this syntax makes the included file
  9512. a sibling of the current top-level headline:
  9513. @example
  9514. #+INCLUDE: "~/my-book/chapter2.org" :minlevel 1
  9515. @end example
  9516. Inclusion of only portions of files are specified using ranges parameter with
  9517. @code{:lines} keyword. The line at the upper end of the range will not be
  9518. included. The start and/or the end of the range may be omitted to use the
  9519. obvious defaults.
  9520. @example
  9521. #+INCLUDE: "~/.emacs" :lines "5-10" @r{Include lines 5 to 10, 10 excluded}
  9522. #+INCLUDE: "~/.emacs" :lines "-10" @r{Include lines 1 to 10, 10 excluded}
  9523. #+INCLUDE: "~/.emacs" :lines "10-" @r{Include lines from 10 to EOF}
  9524. @end example
  9525. Inclusions may specify a file-link to extract an object matched by
  9526. @code{org-link-search}@footnote{Note that
  9527. @code{org-link-search-must-match-exact-headline} is locally bound to
  9528. non-@code{nil}. Therefore, @code{org-link-search} only matches headlines and
  9529. named elements.} (@pxref{Search options}).
  9530. To extract only the contents of the matched object, set @code{:only-contents}
  9531. property to non-@code{nil}. This will omit any planning lines or property
  9532. drawers. The ranges for @code{:lines} keyword are relative to the requested
  9533. element. Some examples:
  9534. @example
  9535. #+INCLUDE: "./paper.org::#theory" :only-contents t
  9536. @r{Include the body of the heading with the custom id @samp{theory}}
  9537. #+INCLUDE: "./paper.org::mytable" @r{Include named element.}
  9538. #+INCLUDE: "./paper.org::*conclusion" :lines 1-20
  9539. @r{Include the first 20 lines of the headline named @samp{conclusion}.}
  9540. @end example
  9541. @table @kbd
  9542. @kindex C-c '
  9543. @item C-c '
  9544. Visit the include file at point.
  9545. @end table
  9546. @node Macro replacement
  9547. @section Macro replacement
  9548. @cindex macro replacement, during export
  9549. @cindex #+MACRO
  9550. @vindex org-export-global-macros
  9551. Macros replace text snippets during export. Macros are defined globally in
  9552. @code{org-export-global-macros}, or document-wise with the following syntax:
  9553. @example
  9554. #+MACRO: name replacement text $1, $2 are arguments
  9555. @end example
  9556. @noindent which can be referenced using
  9557. @code{@{@{@{name(arg1, arg2)@}@}@}}@footnote{Since commas separate the
  9558. arguments, commas within arguments have to be escaped with the backslash
  9559. character. So only those backslash characters before a comma need escaping
  9560. with another backslash character.}.
  9561. Org recognizes macro references in following Org markup areas: paragraphs,
  9562. headlines, verse blocks, tables cells and lists. Org also recognizes macro
  9563. references in keywords, such as @code{#+CAPTION}, @code{#+TITLE},
  9564. @code{#+AUTHOR}, @code{#+DATE}, and for some back-end specific export
  9565. options.
  9566. Org comes with following pre-defined macros:
  9567. @table @code
  9568. @item @{@{@{title@}@}@}
  9569. @itemx @{@{@{author@}@}@}
  9570. @itemx @{@{@{email@}@}@}
  9571. @cindex title, macro
  9572. @cindex author, macro
  9573. @cindex email, macro
  9574. Org replaces these macro references with available information at the time of
  9575. export.
  9576. @item @{@{@{date@}@}@}
  9577. @itemx @{@{@{date(@var{FORMAT})@}@}@}
  9578. @cindex date, macro
  9579. This macro refers to the @code{#+DATE} keyword. @var{FORMAT} is an optional
  9580. argument to the @code{@{@{@{date@}@}@}} macro that will be used only if
  9581. @code{#+DATE} is a single timestamp. @var{FORMAT} should be a format string
  9582. understood by @code{format-time-string}.
  9583. @item @{@{@{time(@var{FORMAT})@}@}@}
  9584. @itemx @{@{@{modification-time(@var{FORMAT}, @var{VC})@}@}@}
  9585. @cindex time, macro
  9586. @cindex modification time, macro
  9587. These macros refer to the document's date and time of export and date and
  9588. time of modification. @var{FORMAT} is a string understood by
  9589. @code{format-time-string}. If the second argument to the
  9590. @code{modification-time} macro is non-@code{nil}, Org uses @file{vc.el} to
  9591. retrieve the document's modification time from the version control
  9592. system. Otherwise Org reads the file attributes.
  9593. @item @{@{@{input-file@}@}@}
  9594. @cindex input file, macro
  9595. This macro refers to the filename of the exported file.
  9596. @item @{@{@{property(@var{PROPERTY-NAME})@}@}@}
  9597. @itemx @{@{@{property(@var{PROPERTY-NAME},@var{SEARCH-OPTION})@}@}@}
  9598. @cindex property, macro
  9599. This macro returns the value of property @var{PROPERTY-NAME} in the current
  9600. entry. If @var{SEARCH-OPTION} (@pxref{Search options}) refers to a remote
  9601. entry, that will be used instead.
  9602. @item @{@{@{n@}@}@}
  9603. @itemx @{@{@{n(@var{NAME})@}@}@}
  9604. @itemx @{@{@{n(@var{NAME},@var{ACTION})@}@}@}
  9605. @cindex n, macro
  9606. @cindex counter, macro
  9607. This macro implements custom counters by returning the number of times the
  9608. macro has been expanded so far while exporting the buffer. You can create
  9609. more than one counter using different @var{NAME} values. If @var{ACTION} is
  9610. @code{-}, previous value of the counter is held, i.e. the specified counter
  9611. is not incremented. If the value is a number, the specified counter is set
  9612. to that value. If it is any other non-empty string, the specified counter is
  9613. reset to 1. You may leave @var{NAME} empty to reset the default counter.
  9614. @end table
  9615. The surrounding brackets can be made invisible by setting
  9616. @code{org-hide-macro-markers} non-@code{nil}.
  9617. Org expands macros at the very beginning of the export process.
  9618. @node Comment lines
  9619. @section Comment lines
  9620. @cindex exporting, not
  9621. @cindex comment lines
  9622. Lines starting with zero or more whitespace characters followed by one
  9623. @samp{#} and a whitespace are treated as comments and, as such, are not
  9624. exported.
  9625. @cindex #+BEGIN_COMMENT
  9626. Likewise, regions surrounded by @samp{#+BEGIN_COMMENT}
  9627. ... @samp{#+END_COMMENT} are not exported.
  9628. @cindex comment trees
  9629. Finally, a @samp{COMMENT} keyword at the beginning of an entry, but after any
  9630. other keyword or priority cookie, comments out the entire subtree. In this
  9631. case, the subtree is not exported and no code block within it is executed
  9632. either@footnote{For a less drastic behavior, consider using a select tag
  9633. (@pxref{Export settings}) instead.}. The command below helps changing the
  9634. comment status of a headline.
  9635. @table @kbd
  9636. @kindex C-c ;
  9637. @item C-c ;
  9638. Toggle the @samp{COMMENT} keyword at the beginning of an entry.
  9639. @end table
  9640. @node ASCII/Latin-1/UTF-8 export
  9641. @section ASCII/Latin-1/UTF-8 export
  9642. @cindex ASCII export
  9643. @cindex Latin-1 export
  9644. @cindex UTF-8 export
  9645. ASCII export produces an output file containing only plain ASCII characters.
  9646. This is the most simplest and direct text output. It does not contain any
  9647. Org markup either. Latin-1 and UTF-8 export use additional characters and
  9648. symbols available in these encoding standards. All three of these export
  9649. formats offer the most basic of text output for maximum portability.
  9650. @vindex org-ascii-text-width
  9651. On export, Org fills and justifies text according to the text width set in
  9652. @code{org-ascii-text-width}.
  9653. @vindex org-ascii-links-to-notes
  9654. Org exports links using a footnote-like style where the descriptive part is
  9655. in the text and the link is in a note before the next heading. See the
  9656. variable @code{org-ascii-links-to-notes} for details.
  9657. @subheading ASCII export commands
  9658. @table @kbd
  9659. @orgcmd{C-c C-e t a/l/u,org-ascii-export-to-ascii}
  9660. Export as an ASCII file with a @file{.txt} extension. For @file{myfile.org},
  9661. Org exports to @file{myfile.txt}, overwriting without warning. For
  9662. @file{myfile.txt}, Org exports to @file{myfile.txt.txt} in order to prevent
  9663. data loss.
  9664. @orgcmd{C-c C-e t A/L/U,org-ascii-export-as-ascii}
  9665. Export to a temporary buffer. Does not create a file.
  9666. @end table
  9667. @subheading ASCII specific export settings
  9668. The ASCII export back-end has one extra keyword for customizing ASCII output.
  9669. Setting this keyword works similar to the general options (@pxref{Export
  9670. settings}).
  9671. @table @samp
  9672. @item SUBTITLE
  9673. @cindex #+SUBTITLE (ASCII)
  9674. The document subtitle. For long subtitles, use multiple @code{#+SUBTITLE}
  9675. lines in the Org file. Org prints them on one continuous line, wrapping into
  9676. multiple lines if necessary.
  9677. @end table
  9678. @subheading Header and sectioning structure
  9679. Org converts the first three outline levels into headlines for ASCII export.
  9680. The remaining levels are turned into lists. To change this cut-off point
  9681. where levels become lists, @pxref{Export settings}.
  9682. @subheading Quoting ASCII text
  9683. To insert text within the Org file by the ASCII back-end, use one the
  9684. following constructs, inline, keyword, or export block:
  9685. @cindex #+ASCII
  9686. @cindex #+BEGIN_EXPORT ascii
  9687. @example
  9688. Inline text @@@@ascii:and additional text@@@@ within a paragraph.
  9689. #+ASCII: Some text
  9690. #+BEGIN_EXPORT ascii
  9691. Org exports text in this block only when using ASCII back-end.
  9692. #+END_EXPORT
  9693. @end example
  9694. @subheading ASCII specific attributes
  9695. @cindex #+ATTR_ASCII
  9696. @cindex horizontal rules, in ASCII export
  9697. ASCII back-end recognizes only one attribute, @code{:width}, which specifies
  9698. the width of an horizontal rule in number of characters. The keyword and
  9699. syntax for specifying widths is:
  9700. @example
  9701. #+ATTR_ASCII: :width 10
  9702. -----
  9703. @end example
  9704. @subheading ASCII special blocks
  9705. @cindex special blocks, in ASCII export
  9706. @cindex #+BEGIN_JUSTIFYLEFT
  9707. @cindex #+BEGIN_JUSTIFYRIGHT
  9708. Besides @code{#+BEGIN_CENTER} blocks (@pxref{Paragraphs}), ASCII back-end has
  9709. these two left and right justification blocks:
  9710. @example
  9711. #+BEGIN_JUSTIFYLEFT
  9712. It's just a jump to the left...
  9713. #+END_JUSTIFYLEFT
  9714. #+BEGIN_JUSTIFYRIGHT
  9715. ...and then a step to the right.
  9716. #+END_JUSTIFYRIGHT
  9717. @end example
  9718. @node Beamer export
  9719. @section Beamer export
  9720. @cindex Beamer export
  9721. Org uses @emph{Beamer} export to convert an Org file tree structure into a
  9722. high-quality interactive slides for presentations. @emph{Beamer} is a
  9723. @LaTeX{} document class for creating presentations in PDF, HTML, and other
  9724. popular display formats.
  9725. @menu
  9726. * Beamer export commands:: For creating Beamer documents.
  9727. * Beamer specific export settings:: For customizing Beamer export.
  9728. * Sectioning Frames and Blocks in Beamer:: For composing Beamer slides.
  9729. * Beamer specific syntax:: For using in Org documents.
  9730. * Editing support:: For using helper functions.
  9731. * A Beamer example:: A complete presentation.
  9732. @end menu
  9733. @node Beamer export commands
  9734. @subsection Beamer export commands
  9735. @table @kbd
  9736. @orgcmd{C-c C-e l b,org-beamer-export-to-latex}
  9737. Export as @LaTeX{} file with a @file{.tex} extension. For @file{myfile.org},
  9738. Org exports to @file{myfile.tex}, overwriting without warning.
  9739. @orgcmd{C-c C-e l B,org-beamer-export-as-latex}
  9740. Export to a temporary buffer. Does not create a file.
  9741. @orgcmd{C-c C-e l P,org-beamer-export-to-pdf}
  9742. Export as @LaTeX{} file and then convert it to PDF format.
  9743. @item C-c C-e l O
  9744. Export as @LaTeX{} file, convert it to PDF format, and then open the PDF
  9745. file.
  9746. @end table
  9747. @node Beamer specific export settings
  9748. @subsection Beamer specific export settings
  9749. Beamer export back-end has several additional keywords for customizing Beamer
  9750. output. These keywords work similar to the general options settings
  9751. (@pxref{Export settings}).
  9752. @table @samp
  9753. @item BEAMER_THEME
  9754. @cindex #+BEAMER_THEME
  9755. @vindex org-beamer-theme
  9756. The Beamer layout theme (@code{org-beamer-theme}). Use square brackets for
  9757. options. For example:
  9758. @smallexample
  9759. #+BEAMER_THEME: Rochester [height=20pt]
  9760. @end smallexample
  9761. @item BEAMER_FONT_THEME
  9762. @cindex #+BEAMER_FONT_THEME
  9763. The Beamer font theme.
  9764. @item BEAMER_INNER_THEME
  9765. @cindex #+BEAMER_INNER_THEME
  9766. The Beamer inner theme.
  9767. @item BEAMER_OUTER_THEME
  9768. @cindex #+BEAMER_OUTER_THEME
  9769. The Beamer outer theme.
  9770. @item BEAMER_HEADER
  9771. @cindex #+BEAMER_HEADER
  9772. Arbitrary lines inserted in the preamble, just before the @samp{hyperref}
  9773. settings.
  9774. @item DESCRIPTION
  9775. @cindex #+DESCRIPTION (Beamer)
  9776. The document description. For long descriptions, use multiple
  9777. @code{#+DESCRIPTION} keywords. By default, @samp{hyperref} inserts
  9778. @code{#+DESCRIPTION} as metadata. Use @code{org-latex-hyperref-template} to
  9779. configure document metadata. Use @code{org-latex-title-command} to configure
  9780. typesetting of description as part of front matter.
  9781. @item KEYWORDS
  9782. @cindex #+KEYWORDS (Beamer)
  9783. The keywords for defining the contents of the document. Use multiple
  9784. @code{#+KEYWORDS} lines if necessary. By default, @samp{hyperref} inserts
  9785. @code{#+KEYWORDS} as metadata. Use @code{org-latex-hyperref-template} to
  9786. configure document metadata. Use @code{org-latex-title-command} to configure
  9787. typesetting of keywords as part of front matter.
  9788. @item SUBTITLE
  9789. @cindex #+SUBTITLE (Beamer)
  9790. @vindex org-beamer-subtitle-format
  9791. Document's subtitle. For typesetting, use @code{org-beamer-subtitle-format}
  9792. string. Use @code{org-latex-hyperref-template} to configure document
  9793. metadata. Use @code{org-latex-title-command} to configure typesetting of
  9794. subtitle as part of front matter.
  9795. @end table
  9796. @node Sectioning Frames and Blocks in Beamer
  9797. @subsection Sectioning, Frames and Blocks in Beamer
  9798. Org transforms heading levels into Beamer's sectioning elements, frames and
  9799. blocks. Any Org tree with a not-too-deep-level nesting should in principle
  9800. be exportable as a Beamer presentation.
  9801. @itemize @minus
  9802. @item
  9803. @vindex org-beamer-frame-level
  9804. Org headlines become Beamer frames when the heading level in Org is equal to
  9805. @code{org-beamer-frame-level} or @code{H} value in an @code{OPTIONS} line
  9806. (@pxref{Export settings}).
  9807. @cindex property, BEAMER_ENV
  9808. Org overrides headlines to frames conversion for the current tree of an Org
  9809. file if it encounters the @code{BEAMER_ENV} property set to @code{frame} or
  9810. @code{fullframe}. Org ignores whatever @code{org-beamer-frame-level} happens
  9811. to be for that headline level in the Org tree. In Beamer terminology, a
  9812. @code{fullframe} is a frame without its title.
  9813. @item
  9814. @vindex org-beamer-environments-default
  9815. @vindex org-beamer-environments-extra
  9816. Org exports a Beamer frame's objects as @code{block} environments. Org can
  9817. enforce wrapping in special block types when @code{BEAMER_ENV} property is
  9818. set@footnote{If @code{BEAMER_ENV} is set, Org export adds
  9819. @code{:B_environment:} tag to make it visible. The tag serves as a visual
  9820. aid and has no semantic relevance.}. For valid values see
  9821. @code{org-beamer-environments-default}. To add more values, see
  9822. @code{org-beamer-environments-extra}.
  9823. @item
  9824. @cindex property, BEAMER_REF
  9825. If @code{BEAMER_ENV} is set to @code{appendix}, Org exports the entry as an
  9826. appendix. When set to @code{note}, Org exports the entry as a note within
  9827. the frame or between frames, depending on the entry's heading level. When
  9828. set to @code{noteNH}, Org exports the entry as a note without its title.
  9829. When set to @code{againframe}, Org exports the entry with @code{\againframe}
  9830. command, which makes setting the @code{BEAMER_REF} property mandatory because
  9831. @code{\againframe} needs frame to resume.
  9832. When @code{ignoreheading} is set, Org export ignores the entry's headline but
  9833. not its content. This is useful for inserting content between frames. It is
  9834. also useful for properly closing a @code{column} environment.
  9835. @end itemize
  9836. @cindex property, BEAMER_ACT
  9837. @cindex property, BEAMER_OPT
  9838. When @code{BEAMER_ACT} is set for a headline, Org export translates that
  9839. headline as an overlay or action specification. When enclosed in square
  9840. brackets, Org export makes the overlay specification a default. Use
  9841. @code{BEAMER_OPT} to set any options applicable to the current Beamer frame
  9842. or block. The Beamer export back-end wraps with appropriate angular or
  9843. square brackets. It also adds the @code{fragile} option for any code that may
  9844. require a verbatim block.
  9845. @cindex property, BEAMER_COL
  9846. To create a column on the Beamer slide, use the @code{BEAMER_COL} property
  9847. for its headline in the Org file. Set the value of @code{BEAMER_COL} to a
  9848. decimal number representing the fraction of the total text width. Beamer
  9849. export uses this value to set the column's width and fills the column with
  9850. the contents of the Org entry. If the Org entry has no specific environment
  9851. defined, Beamer export ignores the heading. If the Org entry has a defined
  9852. environment, Beamer export uses the heading as title. Behind the scenes,
  9853. Beamer export automatically handles @LaTeX{} column separations for
  9854. contiguous headlines. To manually adjust them for any unique configurations
  9855. needs, use the @code{BEAMER_ENV} property.
  9856. @node Beamer specific syntax
  9857. @subsection Beamer specific syntax
  9858. Since Org's Beamer export back-end is an extension of the @LaTeX{} back-end,
  9859. it recognizes other @LaTeX{} specific syntax---for example, @samp{#+LATEX:}
  9860. or @samp{#+ATTR_LATEX:}. @xref{@LaTeX{} export}, for details.
  9861. Beamer export wraps the table of contents generated with @code{toc:t}
  9862. @code{OPTION} keyword in a @code{frame} environment. Beamer export does not
  9863. wrap the table of contents generated with @code{TOC} keyword (@pxref{Table of
  9864. contents}). Use square brackets for specifying options.
  9865. @example
  9866. #+TOC: headlines [currentsection]
  9867. @end example
  9868. Insert Beamer-specific code using the following constructs:
  9869. @cindex #+BEAMER
  9870. @cindex #+BEGIN_EXPORT beamer
  9871. @example
  9872. #+BEAMER: \pause
  9873. #+BEGIN_EXPORT beamer
  9874. Only Beamer export back-end will export this line.
  9875. #+END_BEAMER
  9876. Text @@@@beamer:some code@@@@ within a paragraph.
  9877. @end example
  9878. Inline constructs, such as the last one above, are useful for adding overlay
  9879. specifications to objects with @code{bold}, @code{item}, @code{link},
  9880. @code{radio-target} and @code{target} types. Enclose the value in angular
  9881. brackets and place the specification at the beginning the object as shown in
  9882. this example:
  9883. @example
  9884. A *@@@@beamer:<2->@@@@useful* feature
  9885. @end example
  9886. @cindex #+ATTR_BEAMER
  9887. Beamer export recognizes the @code{ATTR_BEAMER} keyword with the following
  9888. attributes from Beamer configurations: @code{:environment} for changing local
  9889. Beamer environment, @code{:overlay} for specifying Beamer overlays in angular
  9890. or square brackets, and @code{:options} for inserting optional arguments.
  9891. @example
  9892. #+ATTR_BEAMER: :environment nonindentlist
  9893. - item 1, not indented
  9894. - item 2, not indented
  9895. - item 3, not indented
  9896. @end example
  9897. @example
  9898. #+ATTR_BEAMER: :overlay <+->
  9899. - item 1
  9900. - item 2
  9901. @end example
  9902. @example
  9903. #+ATTR_BEAMER: :options [Lagrange]
  9904. Let $G$ be a finite group, and let $H$ be
  9905. a subgroup of $G$. Then the order of $H$ divides the order of $G$.
  9906. @end example
  9907. @node Editing support
  9908. @subsection Editing support
  9909. The @code{org-beamer-mode} is a special minor mode for faster editing of
  9910. Beamer documents.
  9911. @example
  9912. #+STARTUP: beamer
  9913. @end example
  9914. @table @kbd
  9915. @orgcmd{C-c C-b,org-beamer-select-environment}
  9916. The @code{org-beamer-mode} provides this key for quicker selections in Beamer
  9917. normal environments, and for selecting the @code{BEAMER_COL} property.
  9918. @end table
  9919. @node A Beamer example
  9920. @subsection A Beamer example
  9921. Here is an example of an Org document ready for Beamer export.
  9922. @example
  9923. #+TITLE: Example Presentation
  9924. #+AUTHOR: Carsten Dominik
  9925. #+OPTIONS: H:2 toc:t num:t
  9926. #+LATEX_CLASS: beamer
  9927. #+LATEX_CLASS_OPTIONS: [presentation]
  9928. #+BEAMER_THEME: Madrid
  9929. #+COLUMNS: %45ITEM %10BEAMER_ENV(Env) %10BEAMER_ACT(Act) %4BEAMER_COL(Col) %8BEAMER_OPT(Opt)
  9930. * This is the first structural section
  9931. ** Frame 1
  9932. *** Thanks to Eric Fraga :B_block:
  9933. :PROPERTIES:
  9934. :BEAMER_COL: 0.48
  9935. :BEAMER_ENV: block
  9936. :END:
  9937. for the first viable Beamer setup in Org
  9938. *** Thanks to everyone else :B_block:
  9939. :PROPERTIES:
  9940. :BEAMER_COL: 0.48
  9941. :BEAMER_ACT: <2->
  9942. :BEAMER_ENV: block
  9943. :END:
  9944. for contributing to the discussion
  9945. **** This will be formatted as a beamer note :B_note:
  9946. :PROPERTIES:
  9947. :BEAMER_env: note
  9948. :END:
  9949. ** Frame 2 (where we will not use columns)
  9950. *** Request
  9951. Please test this stuff!
  9952. @end example
  9953. @node HTML export
  9954. @section HTML export
  9955. @cindex HTML export
  9956. Org mode contains an HTML exporter with extensive HTML formatting compatible
  9957. with XHTML 1.0 strict standard.
  9958. @menu
  9959. * HTML Export commands:: Invoking HTML export
  9960. * HTML Specific export settings:: Settings for HTML export
  9961. * HTML doctypes:: Exporting various (X)HTML flavors
  9962. * HTML preamble and postamble:: Inserting preamble and postamble
  9963. * Quoting HTML tags:: Using direct HTML in Org files
  9964. * Links in HTML export:: Interpreting and formatting links
  9965. * Tables in HTML export:: Formatting and modifying tables
  9966. * Images in HTML export:: Inserting figures with HTML output
  9967. * Math formatting in HTML export:: Handling math equations
  9968. * Text areas in HTML export:: Showing an alternate approach, an example
  9969. * CSS support:: Styling HTML output
  9970. * JavaScript support:: Folding scripting in the web browser
  9971. @end menu
  9972. @node HTML Export commands
  9973. @subsection HTML export commands
  9974. @table @kbd
  9975. @orgcmd{C-c C-e h h,org-html-export-to-html}
  9976. Export as HTML file with a @file{.html} extension. For @file{myfile.org},
  9977. Org exports to @file{myfile.html}, overwriting without warning. @kbd{C-c C-e
  9978. h o} Exports to HTML and opens it in a web browser.
  9979. @orgcmd{C-c C-e h H,org-html-export-as-html}
  9980. Exports to a temporary buffer. Does not create a file.
  9981. @end table
  9982. @node HTML Specific export settings
  9983. @subsection HTML Specific export settings
  9984. HTML export has a number of keywords, similar to the general options settings
  9985. described in @ref{Export settings}.
  9986. @table @samp
  9987. @item DESCRIPTION
  9988. @cindex #+DESCRIPTION (HTML)
  9989. This is the document's description, which the HTML exporter inserts it as a
  9990. HTML meta tag in the HTML file. For long descriptions, use multiple
  9991. @code{#+DESCRIPTION} lines. The exporter takes care of wrapping the lines
  9992. properly.
  9993. @item HTML_DOCTYPE
  9994. @cindex #+HTML_DOCTYPE
  9995. @vindex org-html-doctype
  9996. Specify the document type, for example: HTML5 (@code{org-html-doctype}).
  9997. @item HTML_CONTAINER
  9998. @cindex #+HTML_CONTAINER
  9999. @vindex org-html-container-element
  10000. Specify the HTML container, such as @samp{div}, for wrapping sections and
  10001. elements (@code{org-html-container-element}).
  10002. @item HTML_LINK_HOME
  10003. @cindex #+HTML_LINK_HOME
  10004. @vindex org-html-link-home
  10005. The URL for home link (@code{org-html-link-home}).
  10006. @item HTML_LINK_UP
  10007. @cindex #+HTML_LINK_UP
  10008. @vindex org-html-link-up
  10009. The URL for the up link of exported HTML pages (@code{org-html-link-up}).
  10010. @item HTML_MATHJAX
  10011. @cindex #+HTML_MATHJAX
  10012. @vindex org-html-mathjax-options
  10013. Options for MathJax (@code{org-html-mathjax-options}). MathJax is used to
  10014. typeset @LaTeX{} math in HTML documents. @xref{Math formatting in HTML
  10015. export}, for an example.
  10016. @item HTML_HEAD
  10017. @cindex #+HTML_HEAD
  10018. @vindex org-html-head
  10019. Arbitrary lines for appending to the HTML document's head
  10020. (@code{org-html-head}).
  10021. @item HTML_HEAD_EXTRA
  10022. @cindex #+HTML_HEAD_EXTRA
  10023. @vindex org-html-head-extra
  10024. More arbitrary lines for appending to the HTML document's head
  10025. (@code{org-html-head-extra}).
  10026. @item KEYWORDS
  10027. @cindex #+KEYWORDS (HTML)
  10028. Keywords to describe the document's content. HTML exporter inserts these
  10029. keywords as HTML meta tags. For long keywords, use multiple
  10030. @code{#+KEYWORDS} lines.
  10031. @item LATEX_HEADER
  10032. @cindex #+LATEX_HEADER (HTML)
  10033. Arbitrary lines for appending to the preamble; HTML exporter appends when
  10034. transcoding @LaTeX{} fragments to images (@pxref{Math formatting in HTML
  10035. export}).
  10036. @item SUBTITLE
  10037. @cindex #+SUBTITLE (HTML)
  10038. The document's subtitle. HTML exporter formats subtitle if document type is
  10039. @samp{HTML5} and the CSS has a @samp{subtitle} class.
  10040. @end table
  10041. Some of these keywords are explained in more detail in the following sections
  10042. of the manual.
  10043. @node HTML doctypes
  10044. @subsection HTML doctypes
  10045. Org can export to various (X)HTML flavors.
  10046. @vindex org-html-doctype
  10047. @vindex org-html-doctype-alist
  10048. Set the @code{org-html-doctype} variable for different (X)HTML variants.
  10049. Depending on the variant, the HTML exporter adjusts the syntax of HTML
  10050. conversion accordingly. Org includes the following ready-made variants:
  10051. @itemize
  10052. @item
  10053. ``html4-strict''
  10054. @item
  10055. ``html4-transitional''
  10056. @item
  10057. ``html4-frameset''
  10058. @item
  10059. ``xhtml-strict''
  10060. @item
  10061. ``xhtml-transitional''
  10062. @item
  10063. ``xhtml-frameset''
  10064. @item
  10065. ``xhtml-11''
  10066. @item
  10067. ``html5''
  10068. @item
  10069. ``xhtml5''
  10070. @end itemize
  10071. @noindent See the variable @code{org-html-doctype-alist} for details.
  10072. The default is ``xhtml-strict''.
  10073. @vindex org-html-html5-fancy
  10074. @cindex HTML5, export new elements
  10075. Org's HTML exporter does not by default enable new block elements introduced
  10076. with the HTML5 standard. To enable them, set @code{org-html-html5-fancy} to
  10077. non-@code{nil}. Or use an @code{OPTIONS} line in the file to set
  10078. @code{html5-fancy}. HTML5 documents can now have arbitrary @code{#+BEGIN}
  10079. and @code{#+END} blocks. For example:
  10080. @example
  10081. #+BEGIN_aside
  10082. Lorem ipsum
  10083. #+END_aside
  10084. @end example
  10085. Will export to:
  10086. @example
  10087. <aside>
  10088. <p>Lorem ipsum</p>
  10089. </aside>
  10090. @end example
  10091. While this:
  10092. @example
  10093. #+ATTR_HTML: :controls controls :width 350
  10094. #+BEGIN_video
  10095. #+HTML: <source src="movie.mp4" type="video/mp4">
  10096. #+HTML: <source src="movie.ogg" type="video/ogg">
  10097. Your browser does not support the video tag.
  10098. #+END_video
  10099. @end example
  10100. Exports to:
  10101. @example
  10102. <video controls="controls" width="350">
  10103. <source src="movie.mp4" type="video/mp4">
  10104. <source src="movie.ogg" type="video/ogg">
  10105. <p>Your browser does not support the video tag.</p>
  10106. </video>
  10107. @end example
  10108. @vindex org-html-html5-elements
  10109. When special blocks do not have a corresponding HTML5 element, the HTML
  10110. exporter reverts to standard translation (see
  10111. @code{org-html-html5-elements}). For example, @code{#+BEGIN_lederhosen}
  10112. exports to @samp{<div class="lederhosen">}.
  10113. Special blocks cannot have headlines. For the HTML exporter to wrap the
  10114. headline and its contents in @samp{<section>} or @samp{<article>} tags, set
  10115. the @code{HTML_CONTAINER} property for the headline.
  10116. @node HTML preamble and postamble
  10117. @subsection HTML preamble and postamble
  10118. @vindex org-html-preamble
  10119. @vindex org-html-postamble
  10120. @vindex org-html-preamble-format
  10121. @vindex org-html-postamble-format
  10122. @vindex org-html-validation-link
  10123. @vindex org-export-creator-string
  10124. @vindex org-export-time-stamp-file
  10125. The HTML exporter has delineations for preamble and postamble. The default
  10126. value for @code{org-html-preamble} is @code{t}, which makes the HTML exporter
  10127. insert the preamble. See the variable @code{org-html-preamble-format} for
  10128. the format string.
  10129. Set @code{org-html-preamble} to a string to override the default format
  10130. string. If the string is a function, the HTML exporter expects the function
  10131. to return a string upon execution. The HTML exporter inserts this string in
  10132. the preamble. The HTML exporter will not insert a preamble if
  10133. @code{org-html-preamble} is set @code{nil}.
  10134. The default value for @code{org-html-postamble} is @code{auto}, which makes
  10135. the HTML exporter build a postamble from looking up author's name, email
  10136. address, creator's name, and date. Set @code{org-html-postamble} to @code{t}
  10137. to insert the postamble in the format specified in the
  10138. @code{org-html-postamble-format} variable. The HTML exporter will not insert
  10139. a postamble if @code{org-html-postamble} is set to @code{nil}.
  10140. @node Quoting HTML tags
  10141. @subsection Quoting HTML tags
  10142. The HTML export back-end transforms @samp{<} and @samp{>} to @samp{&lt;} and
  10143. @samp{&gt;}. To include raw HTML code in the Org file so the HTML export
  10144. back-end can insert that HTML code in the output, use this inline syntax:
  10145. @samp{@@@@html:}. For example: @samp{@@@@html:<b>@@@@bold
  10146. text@@@@html:</b>@@@@}. For larger raw HTML code blocks, use these HTML
  10147. export code blocks:
  10148. @cindex #+HTML
  10149. @cindex #+BEGIN_EXPORT html
  10150. @example
  10151. #+HTML: Literal HTML code for export
  10152. @end example
  10153. @noindent or
  10154. @cindex #+BEGIN_EXPORT html
  10155. @example
  10156. #+BEGIN_EXPORT html
  10157. All lines between these markers are exported literally
  10158. #+END_EXPORT
  10159. @end example
  10160. @node Links in HTML export
  10161. @subsection Links in HTML export
  10162. @cindex links, in HTML export
  10163. @cindex internal links, in HTML export
  10164. @cindex external links, in HTML export
  10165. @vindex org-html-link-org-files-as-html
  10166. The HTML export back-end transforms Org's internal links (@pxref{Internal
  10167. links}) to equivalent HTML links in the output. The back-end similarly
  10168. handles Org's automatic links created by radio targets (@pxref{Radio
  10169. targets}) similarly. For Org links to external files, the back-end
  10170. transforms the links to @emph{relative} paths.
  10171. For Org links to other @file{.org} files, the back-end automatically changes
  10172. the file extension to @file{.html} and makes file paths relative. If the
  10173. @file{.org} files have an equivalent @file{.html} version at the same
  10174. location, then the converted links should work without any further manual
  10175. intervention. However, to disable this automatic path translation, set
  10176. @code{org-html-link-org-files-as-html} to @code{nil}. When disabled, the
  10177. HTML export back-end substitutes the @samp{id:}-based links in the HTML
  10178. output. For more about linking files when publishing to a directory,
  10179. @pxref{Publishing links}.
  10180. Org files can also have special directives to the HTML export back-end. For
  10181. example, by using @code{#+ATTR_HTML} lines to specify new format attributes
  10182. to @code{<a>} or @code{<img>} tags. This example shows changing the link's
  10183. @code{title} and @code{style}:
  10184. @cindex #+ATTR_HTML
  10185. @example
  10186. #+ATTR_HTML: :title The Org mode homepage :style color:red;
  10187. [[http://orgmode.org]]
  10188. @end example
  10189. @node Tables in HTML export
  10190. @subsection Tables in HTML export
  10191. @cindex tables, in HTML
  10192. @vindex org-html-table-default-attributes
  10193. The HTML export back-end uses @code{org-html-table-default-attributes} when
  10194. exporting Org tables to HTML. By default, the exporter does not draw frames
  10195. and cell borders. To change for this for a table, use the following lines
  10196. before the table in the Org file:
  10197. @cindex #+CAPTION
  10198. @cindex #+ATTR_HTML
  10199. @example
  10200. #+CAPTION: This is a table with lines around and between cells
  10201. #+ATTR_HTML: :border 2 :rules all :frame border
  10202. @end example
  10203. The HTML export back-end preserves column groupings in Org tables
  10204. (@pxref{Column groups}) when exporting to HTML.
  10205. Additional options for customizing tables for HTML export.
  10206. @table @code
  10207. @vindex org-html-table-align-individual-fields
  10208. @item org-html-table-align-individual-fields
  10209. Non-@code{nil} attaches style attributes for alignment to each table field.
  10210. @vindex org-html-table-caption-above
  10211. @item org-html-table-caption-above
  10212. Non-@code{nil} places caption string at the beginning of the table.
  10213. @vindex org-html-table-data-tags
  10214. @item org-html-table-data-tags
  10215. Opening and ending tags for table data fields.
  10216. @vindex org-html-table-default-attributes
  10217. @item org-html-table-default-attributes
  10218. Default attributes and values for table tags.
  10219. @vindex org-html-table-header-tags
  10220. @item org-html-table-header-tags
  10221. Opening and ending tags for table's header fields.
  10222. @vindex org-html-table-row-tags
  10223. @item org-html-table-row-tags
  10224. Opening and ending tags for table rows.
  10225. @vindex org-html-table-use-header-tags-for-first-column
  10226. @item org-html-table-use-header-tags-for-first-column
  10227. Non-@code{nil} formats column one in tables with header tags.
  10228. @end table
  10229. @node Images in HTML export
  10230. @subsection Images in HTML export
  10231. @cindex images, inline in HTML
  10232. @cindex inlining images in HTML
  10233. @vindex org-html-inline-images
  10234. The HTML export back-end has features to convert Org image links to HTML
  10235. inline images and HTML clickable image links.
  10236. When the link in the Org file has no description, the HTML export back-end by
  10237. default in-lines that image. For example: @samp{[[file:myimg.jpg]]} is
  10238. in-lined, while @samp{[[file:myimg.jpg][the image]]} links to the text,
  10239. @samp{the image}.
  10240. For more details, see the variable @code{org-html-inline-images}.
  10241. On the other hand, if the description part of the Org link is itself another
  10242. link, such as @code{file:} or @code{http:} URL pointing to an image, the HTML
  10243. export back-end in-lines this image and links to the main image. This Org
  10244. syntax enables the back-end to link low-resolution thumbnail to the
  10245. high-resolution version of the image, as shown in this example:
  10246. @example
  10247. [[file:highres.jpg][file:thumb.jpg]]
  10248. @end example
  10249. To change attributes of in-lined images, use @code{#+ATTR_HTML} lines in the
  10250. Org file. This example shows realignment to right, and adds @code{alt} and
  10251. @code{title} attributes in support of text viewers and modern web accessibility
  10252. standards.
  10253. @cindex #+CAPTION
  10254. @cindex #+ATTR_HTML
  10255. @example
  10256. #+CAPTION: A black cat stalking a spider
  10257. #+ATTR_HTML: :alt cat/spider image :title Action! :align right
  10258. [[./img/a.jpg]]
  10259. @end example
  10260. @noindent
  10261. The HTML export back-end copies the @code{http} links from the Org file as
  10262. is.
  10263. @node Math formatting in HTML export
  10264. @subsection Math formatting in HTML export
  10265. @cindex MathJax
  10266. @cindex dvipng
  10267. @cindex dvisvgm
  10268. @cindex imagemagick
  10269. @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two
  10270. different ways on HTML pages. The default is to use
  10271. @uref{http://www.mathjax.org, MathJax} which should work out of the box with
  10272. Org@footnote{By default Org loads MathJax from @uref{https://cdnjs.com, cdnjs.com} as
  10273. recommended by @uref{http://www.mathjax.org, MathJax}.}. Some MathJax display
  10274. options can be configured via @code{org-html-mathjax-options}, or in the
  10275. buffer. For example, with the following settings,
  10276. @smallexample
  10277. #+HTML_MATHJAX: align: left indent: 5em tagside: left font: Neo-Euler
  10278. @end smallexample
  10279. equation labels will be displayed on the left margin and equations will be
  10280. five ems from the left margin.
  10281. @noindent See the docstring of
  10282. @code{org-html-mathjax-options} for all supported variables. The MathJax
  10283. template can be configure via @code{org-html-mathjax-template}.
  10284. If you prefer, you can also request that @LaTeX{} fragments are processed
  10285. into small images that will be inserted into the browser page. Before the
  10286. availability of MathJax, this was the default method for Org files. This
  10287. method requires that the @file{dvipng} program, @file{dvisvgm} or
  10288. @file{imagemagick} suite is available on your system. You can still get
  10289. this processing with
  10290. @example
  10291. #+OPTIONS: tex:dvipng
  10292. @end example
  10293. @example
  10294. #+OPTIONS: tex:dvisvgm
  10295. @end example
  10296. or:
  10297. @example
  10298. #+OPTIONS: tex:imagemagick
  10299. @end example
  10300. @node Text areas in HTML export
  10301. @subsection Text areas in HTML export
  10302. @cindex text areas, in HTML
  10303. Before Org mode's Babel, one popular approach to publishing code in HTML was
  10304. by using @code{:textarea}. The advantage of this approach was that copying
  10305. and pasting was built into browsers with simple JavaScript commands. Even
  10306. editing before pasting was made simple.
  10307. The HTML export back-end can create such text areas. It requires an
  10308. @code{#+ATTR_HTML:} line as shown in the example below with the
  10309. @code{:textarea} option. This must be followed by either an
  10310. @code{example} or a @code{src} code block. Other Org block types will not
  10311. honor the @code{:textarea} option.
  10312. By default, the HTML export back-end creates a text area 80 characters wide
  10313. and height just enough to fit the content. Override these defaults with
  10314. @code{:width} and @code{:height} options on the @code{#+ATTR_HTML:} line.
  10315. @example
  10316. #+ATTR_HTML: :textarea t :width 40
  10317. #+BEGIN_EXAMPLE
  10318. (defun org-xor (a b)
  10319. "Exclusive or."
  10320. (if a (not b) b))
  10321. #+END_EXAMPLE
  10322. @end example
  10323. @node CSS support
  10324. @subsection CSS support
  10325. @cindex CSS, for HTML export
  10326. @cindex HTML export, CSS
  10327. @vindex org-html-todo-kwd-class-prefix
  10328. @vindex org-html-tag-class-prefix
  10329. You can modify the CSS style definitions for the exported file. The HTML
  10330. exporter assigns the following special CSS classes@footnote{If the classes on
  10331. TODO keywords and tags lead to conflicts, use the variables
  10332. @code{org-html-todo-kwd-class-prefix} and @code{org-html-tag-class-prefix} to
  10333. make them unique.} to appropriate parts of the document---your style
  10334. specifications may change these, in addition to any of the standard classes
  10335. like for headlines, tables, etc.
  10336. @example
  10337. p.author @r{author information, including email}
  10338. p.date @r{publishing date}
  10339. p.creator @r{creator info, about org mode version}
  10340. .title @r{document title}
  10341. .subtitle @r{document subtitle}
  10342. .todo @r{TODO keywords, all not-done states}
  10343. .done @r{the DONE keywords, all states that count as done}
  10344. .WAITING @r{each TODO keyword also uses a class named after itself}
  10345. .timestamp @r{timestamp}
  10346. .timestamp-kwd @r{keyword associated with a timestamp, like SCHEDULED}
  10347. .timestamp-wrapper @r{span around keyword plus timestamp}
  10348. .tag @r{tag in a headline}
  10349. ._HOME @r{each tag uses itself as a class, "@@" replaced by "_"}
  10350. .target @r{target for links}
  10351. .linenr @r{the line number in a code example}
  10352. .code-highlighted @r{for highlighting referenced code lines}
  10353. div.outline-N @r{div for outline level N (headline plus text))}
  10354. div.outline-text-N @r{extra div for text at outline level N}
  10355. .section-number-N @r{section number in headlines, different for each level}
  10356. .figure-number @r{label like "Figure 1:"}
  10357. .table-number @r{label like "Table 1:"}
  10358. .listing-number @r{label like "Listing 1:"}
  10359. div.figure @r{how to format an in-lined image}
  10360. pre.src @r{formatted source code}
  10361. pre.example @r{normal example}
  10362. p.verse @r{verse paragraph}
  10363. div.footnotes @r{footnote section headline}
  10364. p.footnote @r{footnote definition paragraph, containing a footnote}
  10365. .footref @r{a footnote reference number (always a <sup>)}
  10366. .footnum @r{footnote number in footnote definition (always <sup>)}
  10367. .org-svg @r{default class for a linked @file{.svg} image}
  10368. @end example
  10369. @vindex org-html-style-default
  10370. @vindex org-html-head-include-default-style
  10371. @vindex org-html-head
  10372. @vindex org-html-head-extra
  10373. @cindex #+HTML_INCLUDE_STYLE
  10374. The HTML export back-end includes a compact default style in each exported
  10375. HTML file. To override the default style with another style, use these
  10376. keywords in the Org file. They will replace the global defaults the HTML
  10377. exporter uses.
  10378. @cindex #+HTML_HEAD
  10379. @cindex #+HTML_HEAD_EXTRA
  10380. @example
  10381. #+HTML_HEAD: <link rel="stylesheet" type="text/css" href="style1.css" />
  10382. #+HTML_HEAD_EXTRA: <link rel="alternate stylesheet" type="text/css" href="style2.css" />
  10383. @end example
  10384. To just turn off the default style, customize
  10385. @code{org-html-head-include-default-style} variable, or use this option line in
  10386. the Org file.
  10387. @example
  10388. #+OPTIONS: html-style:nil
  10389. @end example
  10390. @noindent
  10391. For longer style definitions, either use several @code{#+HTML_HEAD} and
  10392. @code{#+HTML_HEAD_EXTRA} lines, or use @code{<style>} @code{</style>} blocks
  10393. around them. Both of these approaches can avoid referring to an external
  10394. file.
  10395. In order to add styles to a sub-tree, use the @code{:HTML_CONTAINER_CLASS:}
  10396. property to assign a class to the tree. In order to specify CSS styles for a
  10397. particular headline, you can use the id specified in a @code{:CUSTOM_ID:}
  10398. property.
  10399. Never change the @code{org-html-style-default} constant. Instead use other
  10400. simpler ways of customizing as described above.
  10401. @c FIXME: More about header and footer styles
  10402. @c FIXME: Talk about links and targets.
  10403. @node JavaScript support
  10404. @subsection JavaScript supported display of web pages
  10405. @cindex Rose, Sebastian
  10406. Sebastian Rose has written a JavaScript program especially designed to
  10407. enhance the web viewing experience of HTML files created with Org. This
  10408. program enhances large files in two different ways of viewing. One is an
  10409. @emph{Info}-like mode where each section is displayed separately and
  10410. navigation can be done with the @kbd{n} and @kbd{p} keys (and some other keys
  10411. as well, press @kbd{?} for an overview of the available keys). The second
  10412. one has a @emph{folding} view, much like Org provides inside Emacs. The
  10413. script is available at @url{http://orgmode.org/org-info.js} and the
  10414. documentation at @url{http://orgmode.org/worg/code/org-info-js/}. The script
  10415. is hosted on @url{http://orgmode.org}, but for reliability, prefer installing
  10416. it on your own web server.
  10417. To use this program, just add this line to the Org file:
  10418. @cindex #+INFOJS_OPT
  10419. @example
  10420. #+INFOJS_OPT: view:info toc:nil
  10421. @end example
  10422. @noindent
  10423. The HTML header now has the code needed to automatically invoke the script.
  10424. For setting options, use the syntax from the above line for options described
  10425. below:
  10426. @example
  10427. path: @r{The path to the script. The default grabs the script from}
  10428. @r{@url{http://orgmode.org/org-info.js}, but you might want to have}
  10429. @r{a local copy and use a path like @samp{../scripts/org-info.js}.}
  10430. view: @r{Initial view when the website is first shown. Possible values are:}
  10431. info @r{Info-like interface with one section per page.}
  10432. overview @r{Folding interface, initially showing only top-level.}
  10433. content @r{Folding interface, starting with all headlines visible.}
  10434. showall @r{Folding interface, all headlines and text visible.}
  10435. sdepth: @r{Maximum headline level that will still become an independent}
  10436. @r{section for info and folding modes. The default is taken from}
  10437. @r{@code{org-export-headline-levels} (= the @code{H} switch in @code{#+OPTIONS}).}
  10438. @r{If this is smaller than in @code{org-export-headline-levels}, each}
  10439. @r{info/folding section can still contain child headlines.}
  10440. toc: @r{Should the table of contents @emph{initially} be visible?}
  10441. @r{Even when @code{nil}, you can always get to the "toc" with @kbd{i}.}
  10442. tdepth: @r{The depth of the table of contents. The defaults are taken from}
  10443. @r{the variables @code{org-export-headline-levels} and @code{org-export-with-toc}.}
  10444. ftoc: @r{Does the CSS of the page specify a fixed position for the "toc"?}
  10445. @r{If yes, the toc will never be displayed as a section.}
  10446. ltoc: @r{Should there be short contents (children) in each section?}
  10447. @r{Make this @code{above} if the section should be above initial text.}
  10448. mouse: @r{Headings are highlighted when the mouse is over them. Should be}
  10449. @r{@samp{underline} (default) or a background color like @samp{#cccccc}.}
  10450. buttons: @r{Should view-toggle buttons be everywhere? When @code{nil} (the}
  10451. @r{default), only one such button will be present.}
  10452. @end example
  10453. @noindent
  10454. @vindex org-html-infojs-options
  10455. @vindex org-html-use-infojs
  10456. You can choose default values for these options by customizing the variable
  10457. @code{org-html-infojs-options}. If you want the script to always apply to
  10458. your pages, configure the variable @code{org-html-use-infojs}.
  10459. @node @LaTeX{} export
  10460. @section @LaTeX{} export
  10461. @cindex @LaTeX{} export
  10462. @cindex PDF export
  10463. The @LaTeX{} export back-end can handle complex documents, incorporate
  10464. standard or custom @LaTeX{} document classes, generate documents using
  10465. alternate @LaTeX{} engines, and produce fully linked PDF files with indexes,
  10466. bibliographies, and tables of contents, destined for interactive online
  10467. viewing or high-quality print publication.
  10468. While the details are covered in-depth in this section, here are some quick
  10469. references to variables for the impatient: for engines, see
  10470. @code{org-latex-compiler}; for build sequences, see
  10471. @code{org-latex-pdf-process}; for packages, see
  10472. @code{org-latex-default-packages-alist} and @code{org-latex-packages-alist}.
  10473. An important note about the @LaTeX{} export back-end: it is sensitive to
  10474. blank lines in the Org document. That's because @LaTeX{} itself depends on
  10475. blank lines to tell apart syntactical elements, such as paragraphs.
  10476. @menu
  10477. * @LaTeX{} export commands:: For producing @LaTeX{} and PDF documents.
  10478. * @LaTeX{} specific export settings:: Unique to this @LaTeX{} back-end.
  10479. * @LaTeX{} header and sectioning:: For file structure.
  10480. * Quoting @LaTeX{} code:: Directly in the Org document.
  10481. * Tables in @LaTeX{} export:: Attributes specific to tables.
  10482. * Images in @LaTeX{} export:: Attributes specific to images.
  10483. * Plain lists in @LaTeX{} export:: Attributes specific to lists.
  10484. * Source blocks in @LaTeX{} export:: Attributes specific to source code blocks.
  10485. * Example blocks in @LaTeX{} export:: Attributes specific to example blocks.
  10486. * Special blocks in @LaTeX{} export:: Attributes specific to special blocks.
  10487. * Horizontal rules in @LaTeX{} export:: Attributes specific to horizontal rules.
  10488. @end menu
  10489. @node @LaTeX{} export commands
  10490. @subsection @LaTeX{} export commands
  10491. @table @kbd
  10492. @orgcmd{C-c C-e l l,org-latex-export-to-latex}
  10493. Export as @LaTeX{} file with a @file{.tex} extension. For @file{myfile.org},
  10494. Org exports to @file{myfile.tex}, overwriting without warning. @kbd{C-c C-e
  10495. l l} Exports to @LaTeX{} file.
  10496. @orgcmd{C-c C-e l L,org-latex-export-as-latex}
  10497. Export to a temporary buffer. Do not create a file.
  10498. @orgcmd{C-c C-e l p,org-latex-export-to-pdf}
  10499. Export as @LaTeX{} file and convert it to PDF file.
  10500. @item C-c C-e l o
  10501. Export as @LaTeX{} file and convert it to PDF, then open the PDF using the default viewer.
  10502. @end table
  10503. @vindex org-latex-compiler
  10504. @vindex org-latex-bibtex-compiler
  10505. @vindex org-latex-default-packages-alist
  10506. The @LaTeX{} export back-end can use any of these @LaTeX{} engines:
  10507. @samp{pdflatex}, @samp{xelatex}, and @samp{lualatex}. These engines compile
  10508. @LaTeX{} files with different compilers, packages, and output options. The
  10509. @LaTeX{} export back-end finds the compiler version to use from
  10510. @code{org-latex-compiler} variable or the @code{#+LATEX_COMPILER} keyword in
  10511. the Org file. See the docstring for the
  10512. @code{org-latex-default-packages-alist} for loading packages with certain
  10513. compilers. Also see @code{org-latex-bibtex-compiler} to set the bibliography
  10514. compiler@footnote{This does not allow setting different bibliography
  10515. compilers for different files. However, ``smart'' @LaTeX{} compilation
  10516. systems, such as @samp{latexmk}, can select the correct bibliography
  10517. compiler.}.
  10518. @node @LaTeX{} specific export settings
  10519. @subsection @LaTeX{} specific export settings
  10520. The @LaTeX{} export back-end has several additional keywords for customizing
  10521. @LaTeX{} output. Setting these keywords works similar to the general options
  10522. (@pxref{Export settings}).
  10523. @table @samp
  10524. @item DESCRIPTION
  10525. @cindex #+DESCRIPTION (@LaTeX{})
  10526. The document's description. The description along with author name,
  10527. keywords, and related file metadata are inserted in the output file by the
  10528. @samp{hyperref} package. See @code{org-latex-hyperref-template} for
  10529. customizing metadata items. See @code{org-latex-title-command} for
  10530. typesetting description into the document's front matter. Use multiple
  10531. @code{#+DESCRIPTION} lines for long descriptions.
  10532. @item LATEX_CLASS
  10533. @cindex #+LATEX_CLASS
  10534. @vindex org-latex-default-class
  10535. @vindex org-latex-classes
  10536. This is @LaTeX{} document class, such as @code{article}, @code{report},
  10537. @code{book}, and so on, which contain predefined preamble and headline level
  10538. mapping that the @LaTeX{} export back-end needs. The back-end reads the
  10539. default class name from the @code{org-latex-default-class} variable. Org has
  10540. @code{article} as the default class. A valid default class must be an
  10541. element of @code{org-latex-classes}.
  10542. @item LATEX_CLASS_OPTIONS
  10543. @cindex #+LATEX_CLASS_OPTIONS
  10544. Options the @LaTeX{} export back-end uses when calling the @LaTeX{} document
  10545. class.
  10546. @item LATEX_COMPILER
  10547. @cindex #+LATEX_COMPILER
  10548. @vindex org-latex-compiler
  10549. The compiler, such as @samp{pdflatex}, @samp{xelatex}, @samp{lualatex}, for
  10550. producing the PDF (@code{org-latex-compiler}).
  10551. @item LATEX_HEADER
  10552. @cindex #+LATEX_HEADER
  10553. @vindex org-latex-classes
  10554. Arbitrary lines to add to the document's preamble, before the @samp{hyperref}
  10555. settings. See @code{org-latex-classes} for adjusting the structure and order
  10556. of the @LaTeX{} headers.
  10557. @item LATEX_HEADER_EXTRA
  10558. @cindex #+LATEX_HEADER_EXTRA
  10559. @vindex org-latex-classes
  10560. Arbitrary lines to add to the document's preamble, before the @samp{hyperref}
  10561. settings. See @code{org-latex-classes} for adjusting the structure and order
  10562. of the @LaTeX{} headers.
  10563. @item KEYWORDS
  10564. @cindex #+KEYWORDS (@LaTeX{})
  10565. The keywords for the document. The description along with author name,
  10566. keywords, and related file metadata are inserted in the output file by the
  10567. @samp{hyperref} package. See @code{org-latex-hyperref-template} for
  10568. customizing metadata items. See @code{org-latex-title-command} for
  10569. typesetting description into the document's front matter. Use multiple
  10570. @code{#+KEYWORDS} lines if necessary.
  10571. @item SUBTITLE
  10572. @cindex #+SUBTITLE (@LaTeX{})
  10573. @vindex org-latex-subtitle-separate
  10574. @vindex org-latex-subtitle-format
  10575. The document's subtitle. It is typeset as per
  10576. @code{org-latex-subtitle-format}. If @code{org-latex-subtitle-separate} is
  10577. non-@code{nil}, it is typed as part of the @samp{\title}-macro. See
  10578. @code{org-latex-hyperref-template} for customizing metadata items. See
  10579. @code{org-latex-title-command} for typesetting description into the
  10580. document's front matter.
  10581. @end table
  10582. The following sections have further details.
  10583. @node @LaTeX{} header and sectioning
  10584. @subsection @LaTeX{} header and sectioning structure
  10585. @cindex @LaTeX{} class
  10586. @cindex @LaTeX{} sectioning structure
  10587. @cindex @LaTeX{} header
  10588. @cindex header, for @LaTeX{} files
  10589. @cindex sectioning structure, for @LaTeX{} export
  10590. The @LaTeX{} export back-end converts the first three of Org's outline levels
  10591. into @LaTeX{} headlines. The remaining Org levels are exported as
  10592. @code{itemize} or @code{enumerate} lists. To change this globally for the
  10593. cut-off point between levels and lists, (@pxref{Export settings}).
  10594. By default, the @LaTeX{} export back-end uses the @code{article} class.
  10595. @vindex org-latex-default-class
  10596. @vindex org-latex-classes
  10597. @vindex org-latex-default-packages-alist
  10598. @vindex org-latex-packages-alist
  10599. To change the default class globally, edit @code{org-latex-default-class}.
  10600. To change the default class locally in an Org file, add option lines
  10601. @code{#+LATEX_CLASS: myclass}. To change the default class for just a part
  10602. of the Org file, set a sub-tree property, @code{EXPORT_LATEX_CLASS}. The
  10603. class name entered here must be valid member of @code{org-latex-classes}.
  10604. This variable defines a header template for each class into which the
  10605. exporter splices the values of @code{org-latex-default-packages-alist} and
  10606. @code{org-latex-packages-alist}. Use the same three variables to define
  10607. custom sectioning or custom classes.
  10608. @cindex #+LATEX_CLASS
  10609. @cindex #+LATEX_CLASS_OPTIONS
  10610. @cindex property, EXPORT_LATEX_CLASS
  10611. @cindex property, EXPORT_LATEX_CLASS_OPTIONS
  10612. The @LaTeX{} export back-end sends the @code{LATEX_CLASS_OPTIONS} keyword and
  10613. @code{EXPORT_LATEX_CLASS_OPTIONS} property as options to the @LaTeX{}
  10614. @code{\documentclass} macro. The options and the syntax for specifying them,
  10615. including enclosing them in square brackets, follow @LaTeX{} conventions.
  10616. @example
  10617. #+LATEX_CLASS_OPTIONS: [a4paper,11pt,twoside,twocolumn]
  10618. @end example
  10619. @cindex #+LATEX_HEADER
  10620. @cindex #+LATEX_HEADER_EXTRA
  10621. The @LaTeX{} export back-end appends values from @code{LATEX_HEADER} and
  10622. @code{LATEX_HEADER_EXTRA} keywords to the @LaTeX{} header. The docstring for
  10623. @code{org-latex-classes} explains in more detail. Also note that @LaTeX{}
  10624. export back-end does not append @code{LATEX_HEADER_EXTRA} to the header when
  10625. previewing @LaTeX{} snippets (@pxref{Previewing @LaTeX{} fragments}).
  10626. A sample Org file with the above headers:
  10627. @example
  10628. #+LATEX_CLASS: article
  10629. #+LATEX_CLASS_OPTIONS: [a4paper]
  10630. #+LATEX_HEADER: \usepackage@{xyz@}
  10631. * Headline 1
  10632. some text
  10633. * Headline 2
  10634. some more text
  10635. @end example
  10636. @node Quoting @LaTeX{} code
  10637. @subsection Quoting @LaTeX{} code
  10638. The @LaTeX{} export back-end can insert any arbitrary @LaTeX{} code,
  10639. @pxref{Embedded @LaTeX{}}. There are three ways to embed such code in the
  10640. Org file and they all use different quoting syntax.
  10641. Inserting in-line quoted with @ symbols:
  10642. @cindex inline, in @LaTeX{} export
  10643. @example
  10644. Code embedded in-line @@@@latex:any arbitrary LaTeX code@@@@ in a paragraph.
  10645. @end example
  10646. Inserting as one or more keyword lines in the Org file:
  10647. @cindex #+LATEX
  10648. @example
  10649. #+LATEX: any arbitrary LaTeX code
  10650. @end example
  10651. Inserting as an export block in the Org file, where the back-end exports any
  10652. code between begin and end markers:
  10653. @cindex #+BEGIN_EXPORT latex
  10654. @example
  10655. #+BEGIN_EXPORT latex
  10656. any arbitrary LaTeX code
  10657. #+END_EXPORT
  10658. @end example
  10659. @node Tables in @LaTeX{} export
  10660. @subsection Tables in @LaTeX{} export
  10661. @cindex tables, in @LaTeX{} export
  10662. @cindex #+ATTR_LATEX, in tables
  10663. The @LaTeX{} export back-end can pass several @LaTeX{} attributes for table
  10664. contents and layout. Besides specifying label and caption (@pxref{Images and
  10665. tables}), the other valid @LaTeX{} attributes include:
  10666. @table @code
  10667. @item :mode
  10668. @vindex org-latex-default-table-mode
  10669. The @LaTeX{} export back-end wraps the table differently depending on the
  10670. mode for accurate rendering of math symbols. Mode is either @code{table},
  10671. @code{math}, @code{inline-math} or @code{verbatim}. For @code{math} or
  10672. @code{inline-math} mode, @LaTeX{} export back-end wraps the table in a math
  10673. environment, but every cell in it is exported as-is. The @LaTeX{} export
  10674. back-end determines the default mode from
  10675. @code{org-latex-default-table-mode}. For , The @LaTeX{} export back-end
  10676. merges contiguous tables in the same mode into a single environment.
  10677. @item :environment
  10678. @vindex org-latex-default-table-environment
  10679. Set the default @LaTeX{} table environment for the @LaTeX{} export back-end
  10680. to use when exporting Org tables. Common @LaTeX{} table environments are
  10681. provided by these packages: @code{tabularx}, @code{longtable}, @code{array},
  10682. @code{tabu}, and @code{bmatrix}. For packages, such as @code{tabularx} and
  10683. @code{tabu}, or any newer replacements, include them in the
  10684. @code{org-latex-packages-alist} variable so the @LaTeX{} export back-end can
  10685. insert the appropriate load package headers in the converted @LaTeX{} file.
  10686. Look in the docstring for the @code{org-latex-packages-alist} variable for
  10687. configuring these packages for @LaTeX{} snippet previews, if any.
  10688. @item :caption
  10689. Use @code{#+CAPTION} keyword to set a simple caption for a table
  10690. (@pxref{Images and tables}). For custom captions, use @code{:caption}
  10691. attribute, which accepts raw @LaTeX{} code. @code{:caption} value overrides
  10692. @code{#+CAPTION} value.
  10693. @item :float
  10694. @itemx :placement
  10695. The table environments by default are not floats in @LaTeX{}. To make them
  10696. floating objects use @code{:float} with one of the following options:
  10697. @code{sideways}, @code{multicolumn}, @code{t}, and @code{nil}. Note that
  10698. @code{sidewaystable} has been deprecated since Org 8.3. @LaTeX{} floats can
  10699. also have additional layout @code{:placement} attributes. These are the
  10700. usual @code{[h t b p ! H]} permissions specified in square brackets. Note
  10701. that for @code{:float sideways} tables, the @LaTeX{} export back-end ignores
  10702. @code{:placement} attributes.
  10703. @item :align
  10704. @itemx :font
  10705. @itemx :width
  10706. The @LaTeX{} export back-end uses these attributes for regular tables to set
  10707. their alignments, fonts, and widths.
  10708. @item :spread
  10709. When @code{:spread} is non-@code{nil}, the @LaTeX{} export back-end spreads
  10710. or shrinks the table by the @code{:width} for @code{tabu} and @code{longtabu}
  10711. environments. @code{:spread} has no effect if @code{:width} is not set.
  10712. @item :booktabs
  10713. @itemx :center
  10714. @itemx :rmlines
  10715. @vindex org-latex-tables-booktabs
  10716. @vindex org-latex-tables-centered
  10717. All three commands are toggles. @code{:booktabs} brings in modern
  10718. typesetting enhancements to regular tables. The @code{booktabs} package has
  10719. to be loaded through @code{org-latex-packages-alist}. @code{:center} is for
  10720. centering the table. @code{:rmlines} removes all but the very first
  10721. horizontal line made of ASCII characters from "table.el" tables only.
  10722. @item :math-prefix
  10723. @itemx :math-suffix
  10724. @itemx :math-arguments
  10725. The @LaTeX{} export back-end inserts @code{:math-prefix} string value in a
  10726. math environment before the table. The @LaTeX{} export back-end inserts
  10727. @code{:math-suffix} string value in a math environment after the table. The
  10728. @LaTeX{} export back-end inserts @code{:math-arguments} string value between
  10729. the macro name and the table's contents. @code{:math-arguments} comes in use
  10730. for matrix macros that require more than one argument, such as
  10731. @code{qbordermatrix}.
  10732. @end table
  10733. @LaTeX{} table attributes help formatting tables for a wide range of
  10734. situations, such as matrix product or spanning multiple pages:
  10735. @example
  10736. #+ATTR_LATEX: :environment longtable :align l|lp@{3cm@}r|l
  10737. | ..... | ..... |
  10738. | ..... | ..... |
  10739. #+ATTR_LATEX: :mode math :environment bmatrix :math-suffix \times
  10740. | a | b |
  10741. | c | d |
  10742. #+ATTR_LATEX: :mode math :environment bmatrix
  10743. | 1 | 2 |
  10744. | 3 | 4 |
  10745. @end example
  10746. Set the caption with the @LaTeX{} command
  10747. @code{\bicaption@{HeadingA@}@{HeadingB@}}:
  10748. @example
  10749. #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
  10750. | ..... | ..... |
  10751. | ..... | ..... |
  10752. @end example
  10753. @node Images in @LaTeX{} export
  10754. @subsection Images in @LaTeX{} export
  10755. @cindex images, inline in @LaTeX{}
  10756. @cindex inlining images in @LaTeX{}
  10757. @cindex #+ATTR_LATEX, in images
  10758. The @LaTeX{} export back-end processes image links in Org files that do not
  10759. have descriptions, such as these links @samp{[[file:img.jpg]]} or
  10760. @samp{[[./img.jpg]]}, as direct image insertions in the final PDF output. In
  10761. the PDF, they are no longer links but actual images embedded on the page.
  10762. The @LaTeX{} export back-end uses @code{\includegraphics} macro to insert the
  10763. image. But for TikZ@footnote{@url{http://sourceforge.net/projects/pgf/}}
  10764. images, the back-end uses an @code{\input} macro wrapped within
  10765. a @code{tikzpicture} environment.
  10766. For specifying image @code{:width}, @code{:height}, and other
  10767. @code{:options}, use this syntax:
  10768. @example
  10769. #+ATTR_LATEX: :width 5cm :options angle=90
  10770. [[./img/sed-hr4049.pdf]]
  10771. @end example
  10772. For custom commands for captions, use the @code{:caption} attribute. It will
  10773. override the default @code{#+CAPTION} value:
  10774. @example
  10775. #+ATTR_LATEX: :caption \bicaption@{HeadingA@}@{HeadingB@}
  10776. [[./img/sed-hr4049.pdf]]
  10777. @end example
  10778. When captions follow the method as described in @ref{Images and tables}, the
  10779. @LaTeX{} export back-end wraps the picture in a floating @code{figure}
  10780. environment. To float an image without specifying a caption, set the
  10781. @code{:float} attribute to one of the following:
  10782. @itemize @minus
  10783. @item
  10784. @code{t}: for a standard @samp{figure} environment; used by default whenever
  10785. an image has a caption.
  10786. @item
  10787. @code{multicolumn}: to span the image across multiple columns of a page; the
  10788. back-end wraps the image in a @code{figure*} environment.
  10789. @item
  10790. @code{wrap}: for text to flow around the image on the right; the figure
  10791. occupies the left half of the page.
  10792. @item
  10793. @code{sideways}: for a new page with the image sideways, rotated ninety
  10794. degrees, in a @code{sidewaysfigure} environment; overrides @code{:placement}
  10795. setting.
  10796. @item
  10797. @code{nil}: to avoid a @code{:float} even if using a caption.
  10798. @end itemize
  10799. @noindent
  10800. Use the @code{placement} attribute to modify a floating environment's placement.
  10801. @example
  10802. #+ATTR_LATEX: :float wrap :width 0.38\textwidth :placement
  10803. @{r@}@{0.4\textwidth@} [[./img/hst.png]]
  10804. @end example
  10805. @vindex org-latex-images-centered
  10806. @cindex center image (@LaTeX{} export)
  10807. @cindex image, centering (@LaTeX{} export)
  10808. The @LaTeX{} export back-end centers all images by default. Setting
  10809. @code{:center} attribute to @code{nil} disables centering. To disable
  10810. centering globally, set @code{org-latex-images-centered} to @code{t}.
  10811. Set the @code{:comment-include} attribute to non-@code{nil} value for the
  10812. @LaTeX{} export back-end to comment out the @code{\includegraphics} macro.
  10813. @node Plain lists in @LaTeX{} export
  10814. @subsection Plain lists in @LaTeX{} export
  10815. @cindex plain lists, in @LaTeX{} export
  10816. @cindex #+ATTR_LATEX, in plain lists
  10817. The @LaTeX{} export back-end accepts the @code{:environment} and
  10818. @code{:options} attributes for plain lists. Both attributes work together
  10819. for customizing lists, as shown in the examples:
  10820. @example
  10821. #+LATEX_HEADER: \usepackage[inline]@{enumitem@}
  10822. Some ways to say "Hello":
  10823. #+ATTR_LATEX: :environment itemize*
  10824. #+ATTR_LATEX: :options [label=@{@}, itemjoin=@{,@}, itemjoin*=@{, and@}]
  10825. - Hola
  10826. - Bonjour
  10827. - Guten Tag.
  10828. @end example
  10829. Since @LaTeX{} supports only four levels of nesting for lists, use an
  10830. external package, such as @samp{enumitem} in @LaTeX{}, for levels deeper than
  10831. four:
  10832. @example
  10833. #+LATEX_HEADER: \usepackage@{enumitem@}
  10834. #+LATEX_HEADER: \renewlist@{itemize@}@{itemize@}@{9@}
  10835. #+LATEX_HEADER: \setlist[itemize]@{label=$\circ$@}
  10836. - One
  10837. - Two
  10838. - Three
  10839. - Four
  10840. - Five
  10841. @end example
  10842. @node Source blocks in @LaTeX{} export
  10843. @subsection Source blocks in @LaTeX{} export
  10844. @cindex source blocks, in @LaTeX{} export
  10845. @cindex #+ATTR_LATEX, in source blocks
  10846. The @LaTeX{} export back-end can make source code blocks into floating
  10847. objects through the attributes @code{:float} and @code{:options}. For
  10848. @code{:float}:
  10849. @itemize @minus
  10850. @item
  10851. @code{t}: makes a source block float; by default floats any source block with
  10852. a caption.
  10853. @item
  10854. @code{multicolumn}: spans the source block across multiple columns of a page.
  10855. @item
  10856. @code{nil}: avoids a @code{:float} even if using a caption; useful for
  10857. source code blocks that may not fit on a page.
  10858. @end itemize
  10859. @example
  10860. #+ATTR_LATEX: :float nil
  10861. #+BEGIN_SRC emacs-lisp
  10862. Lisp code that may not fit in a single page.
  10863. #+END_SRC
  10864. @end example
  10865. @vindex org-latex-listings-options
  10866. @vindex org-latex-minted-options
  10867. The @LaTeX{} export back-end passes string values in @code{:options} to
  10868. @LaTeX{} packages for customization of that specific source block. In the
  10869. example below, the @code{:options} are set for Minted. Minted is a source
  10870. code highlighting @LaTeX{}package with many configurable options.
  10871. @example
  10872. #+ATTR_LATEX: :options commentstyle=\bfseries
  10873. #+BEGIN_SRC emacs-lisp
  10874. (defun Fib (n)
  10875. (if (< n 2) n (+ (Fib (- n 1)) (Fib (- n 2)))))
  10876. #+END_SRC
  10877. @end example
  10878. To apply similar configuration options for all source blocks in a file, use
  10879. the @code{org-latex-listings-options} and @code{org-latex-minted-options}
  10880. variables.
  10881. @node Example blocks in @LaTeX{} export
  10882. @subsection Example blocks in @LaTeX{} export
  10883. @cindex example blocks, in @LaTeX{} export
  10884. @cindex verbatim blocks, in @LaTeX{} export
  10885. @cindex #+ATTR_LATEX, in example blocks
  10886. The @LaTeX{} export back-end wraps the contents of example blocks in a
  10887. @samp{verbatim} environment. To change this behavior to use another
  10888. environment globally, specify an appropriate export filter (@pxref{Advanced
  10889. configuration}). To change this behavior to use another environment for each
  10890. block, use the @code{:environment} parameter to specify a custom environment.
  10891. @example
  10892. #+ATTR_LATEX: :environment myverbatim
  10893. #+BEGIN_EXAMPLE
  10894. This sentence is false.
  10895. #+END_EXAMPLE
  10896. @end example
  10897. @node Special blocks in @LaTeX{} export
  10898. @subsection Special blocks in @LaTeX{} export
  10899. @cindex special blocks, in @LaTeX{} export
  10900. @cindex abstract, in @LaTeX{} export
  10901. @cindex proof, in @LaTeX{} export
  10902. @cindex #+ATTR_LATEX, in special blocks
  10903. For other special blocks in the Org file, the @LaTeX{} export back-end makes
  10904. a special environment of the same name. The back-end also takes
  10905. @code{:options}, if any, and appends as-is to that environment's opening
  10906. string. For example:
  10907. @example
  10908. #+BEGIN_abstract
  10909. We demonstrate how to solve the Syracuse problem.
  10910. #+END_abstract
  10911. #+ATTR_LATEX: :options [Proof of important theorem]
  10912. #+BEGIN_proof
  10913. ...
  10914. Therefore, any even number greater than 2 is the sum of two primes.
  10915. #+END_proof
  10916. @end example
  10917. @noindent
  10918. exports to
  10919. @example
  10920. \begin@{abstract@}
  10921. We demonstrate how to solve the Syracuse problem.
  10922. \end@{abstract@}
  10923. \begin@{proof@}[Proof of important theorem]
  10924. ...
  10925. Therefore, any even number greater than 2 is the sum of two primes.
  10926. \end@{proof@}
  10927. @end example
  10928. If you need to insert a specific caption command, use @code{:caption}
  10929. attribute. It will override standard @code{#+CAPTION} value, if any. For
  10930. example:
  10931. @example
  10932. #+ATTR_LATEX: :caption \MyCaption@{HeadingA@}
  10933. #+BEGIN_proof
  10934. ...
  10935. #+END_proof
  10936. @end example
  10937. @node Horizontal rules in @LaTeX{} export
  10938. @subsection Horizontal rules in @LaTeX{} export
  10939. @cindex horizontal rules, in @LaTeX{} export
  10940. @cindex #+ATTR_LATEX, in horizontal rules
  10941. The @LaTeX{} export back-end converts horizontal rules by the specified
  10942. @code{:width} and @code{:thickness} attributes. For example:
  10943. @example
  10944. #+ATTR_LATEX: :width .6\textwidth :thickness 0.8pt
  10945. -----
  10946. @end example
  10947. @node Markdown export
  10948. @section Markdown export
  10949. @cindex Markdown export
  10950. The Markdown export back-end, @code{md}, converts an Org file to a Markdown
  10951. format, as defined at @url{http://daringfireball.net/projects/markdown/}.
  10952. Since @code{md} is built on top of the HTML back-end, any Org constructs not
  10953. supported by Markdown, such as tables, the underlying @code{html} back-end
  10954. (@pxref{HTML export}) converts them.
  10955. @subheading Markdown export commands
  10956. @table @kbd
  10957. @orgcmd{C-c C-e m m,org-md-export-to-markdown}
  10958. Export to a text file with Markdown syntax. For @file{myfile.org}, Org
  10959. exports to @file{myfile.md}, overwritten without warning.
  10960. @orgcmd{C-c C-e m M,org-md-export-as-markdown}
  10961. Export to a temporary buffer. Does not create a file.
  10962. @item C-c C-e m o
  10963. Export as a text file with Markdown syntax, then open it.
  10964. @end table
  10965. @subheading Header and sectioning structure
  10966. @vindex org-md-headline-style
  10967. Based on @code{org-md-headline-style}, markdown export can generate headlines
  10968. of both @code{atx} and @code{setext} types. @code{atx} limits headline
  10969. levels to two. @code{setext} limits headline levels to six. Beyond these
  10970. limits, the export back-end converts headlines to lists. To set a limit to a
  10971. level before the absolute limit (@pxref{Export settings}).
  10972. @c begin opendocument
  10973. @node OpenDocument Text export
  10974. @section OpenDocument Text export
  10975. @cindex ODT
  10976. @cindex OpenDocument
  10977. @cindex export, OpenDocument
  10978. @cindex LibreOffice
  10979. The ODT export back-end handles creating of OpenDocument Text (ODT) format
  10980. files. The format complies with @cite{OpenDocument-v1.2
  10981. specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
  10982. Open Document Format for Office Applications (OpenDocument) Version 1.2}} and
  10983. is compatible with LibreOffice 3.4.
  10984. @menu
  10985. * Pre-requisites for ODT export:: Required packages.
  10986. * ODT export commands:: Invoking export.
  10987. * ODT specific export settings:: Configuration options.
  10988. * Extending ODT export:: Producing @file{.doc}, @file{.pdf} files.
  10989. * Applying custom styles:: Styling the output.
  10990. * Links in ODT export:: Handling and formatting links.
  10991. * Tables in ODT export:: Org table conversions.
  10992. * Images in ODT export:: Inserting images.
  10993. * Math formatting in ODT export:: Formatting @LaTeX{} fragments.
  10994. * Labels and captions in ODT export:: Rendering objects.
  10995. * Literal examples in ODT export:: For source code and example blocks.
  10996. * Advanced topics in ODT export:: For power users.
  10997. @end menu
  10998. @node Pre-requisites for ODT export
  10999. @subsection Pre-requisites for ODT export
  11000. @cindex zip
  11001. The ODT export back-end relies on the @file{zip} program to create the final
  11002. compressed ODT output. Check if @file{zip} is locally available and
  11003. executable. Without @file{zip}, export cannot finish.
  11004. @node ODT export commands
  11005. @subsection ODT export commands
  11006. @anchor{x-export-to-odt}
  11007. @cindex region, active
  11008. @cindex active region
  11009. @cindex transient-mark-mode
  11010. @table @kbd
  11011. @orgcmd{C-c C-e o o,org-odt-export-to-odt}
  11012. @cindex property EXPORT_FILE_NAME
  11013. Export as OpenDocument Text file.
  11014. @vindex org-odt-preferred-output-format
  11015. If @code{org-odt-preferred-output-format} is specified, the ODT export
  11016. back-end automatically converts the exported file to that format.
  11017. @xref{x-export-to-other-formats, , Automatically exporting to other formats}.
  11018. For @file{myfile.org}, Org exports to @file{myfile.odt}, overwriting without
  11019. warning. The ODT export back-end exports a region only if a region was
  11020. active. Note for exporting active regions, the @code{transient-mark-mode}
  11021. has to be turned on.
  11022. If the selected region is a single tree, the ODT export back-end makes the
  11023. tree head the document title. Incidentally, @kbd{C-c @@} selects the current
  11024. sub-tree. If the tree head entry has, or inherits, an
  11025. @code{EXPORT_FILE_NAME} property, the ODT export back-end uses that for file
  11026. name.
  11027. @kbd{C-c C-e o O}
  11028. Export to an OpenDocument Text file format and open it.
  11029. @vindex org-odt-preferred-output-format
  11030. When @code{org-odt-preferred-output-format} is specified, open the converted
  11031. file instead. @xref{x-export-to-other-formats, , Automatically exporting to
  11032. other formats}.
  11033. @end table
  11034. @node ODT specific export settings
  11035. @subsection ODT specific export settings
  11036. The ODT export back-end has several additional keywords for customizing ODT
  11037. output. Setting these keywords works similar to the general options
  11038. (@pxref{Export settings}).
  11039. @table @samp
  11040. @item DESCRIPTION
  11041. @cindex #+DESCRIPTION (ODT)
  11042. This is the document's description, which the ODT export back-end inserts as
  11043. document metadata. For long descriptions, use multiple @code{#+DESCRIPTION}
  11044. lines.
  11045. @item KEYWORDS
  11046. @cindex #+KEYWORDS (ODT)
  11047. The keywords for the document. The ODT export back-end inserts the
  11048. description along with author name, keywords, and related file metadata as
  11049. metadata in the output file. Use multiple @code{#+KEYWORDS} lines if
  11050. necessary.
  11051. @item ODT_STYLES_FILE
  11052. @cindex ODT_STYLES_FILE
  11053. @vindex org-odt-styles-file
  11054. The ODT export back-end uses the @code{org-odt-styles-file} by default. See
  11055. @ref{Applying custom styles} for details.
  11056. @item SUBTITLE
  11057. @cindex SUBTITLE (ODT)
  11058. The document subtitle.
  11059. @end table
  11060. @node Extending ODT export
  11061. @subsection Extending ODT export
  11062. The ODT export back-end can produce documents in other formats besides ODT
  11063. using a specialized ODT converter process. Its common interface works with
  11064. popular converters to produce formats such as @samp{doc}, or convert a
  11065. document from one format, say @samp{csv}, to another format, say @samp{xls}.
  11066. @cindex @file{unoconv}
  11067. @cindex LibreOffice
  11068. Customize @code{org-odt-convert-process} variable to point to @code{unoconv},
  11069. which is the ODT's preferred converter. Working installations of LibreOffice
  11070. would already have @code{unoconv} installed. Alternatively, other converters
  11071. may be substituted here. @xref{Configuring a document converter}.
  11072. @subsubheading Automatically exporting to other formats
  11073. @anchor{x-export-to-other-formats}
  11074. @vindex org-odt-preferred-output-format
  11075. If ODT format is just an intermediate step to get to other formats, such as
  11076. @samp{doc}, @samp{docx}, @samp{rtf}, or @samp{pdf}, etc., then extend the ODT
  11077. export back-end to directly produce that format. Specify the final format in
  11078. the @code{org-odt-preferred-output-format} variable. This is one way to
  11079. extend (@pxref{x-export-to-odt,,Exporting to ODT}).
  11080. @subsubheading Converting between document formats
  11081. @anchor{x-convert-to-other-formats}
  11082. The Org export back-end is made to be inter-operable with a wide range of text
  11083. document format converters. Newer generation converters, such as LibreOffice
  11084. and Pandoc, can handle hundreds of formats at once. Org provides a
  11085. consistent interaction with whatever converter is installed. Here are some
  11086. generic commands:
  11087. @vindex org-odt-convert
  11088. @table @kbd
  11089. @item M-x org-odt-convert RET
  11090. Convert an existing document from one format to another. With a prefix
  11091. argument, opens the newly produced file.
  11092. @end table
  11093. @node Applying custom styles
  11094. @subsection Applying custom styles
  11095. @cindex styles, custom
  11096. @cindex template, custom
  11097. The ODT export back-end comes with many OpenDocument styles (@pxref{Working
  11098. with OpenDocument style files}). To expand or further customize these
  11099. built-in style sheets, either edit the style sheets directly or generate them
  11100. using an application such as LibreOffice. The example here shows creating a
  11101. style using LibreOffice.
  11102. @subsubheading Applying custom styles: the easy way
  11103. @enumerate
  11104. @item
  11105. Create a sample @file{example.org} file with settings as shown below, and
  11106. export it to ODT format.
  11107. @example
  11108. #+OPTIONS: H:10 num:t
  11109. @end example
  11110. @item
  11111. Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist}
  11112. to locate the target styles, which typically have the @samp{Org} prefix.
  11113. Open one, modify, and save as either OpenDocument Text (@file{.odt}) or
  11114. OpenDocument Template (@file{.ott}) file.
  11115. @item
  11116. @cindex #+ODT_STYLES_FILE
  11117. @vindex org-odt-styles-file
  11118. Customize the variable @code{org-odt-styles-file} and point it to the
  11119. newly created file. For additional configuration options
  11120. @pxref{x-overriding-factory-styles,,Overriding factory styles}.
  11121. To apply and ODT style to a particular file, use the @code{#+ODT_STYLES_FILE}
  11122. option as shown in the example below:
  11123. @example
  11124. #+ODT_STYLES_FILE: "/path/to/example.ott"
  11125. @end example
  11126. or
  11127. @example
  11128. #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))
  11129. @end example
  11130. @end enumerate
  11131. @subsubheading Using third-party styles and templates
  11132. The ODT export back-end relies on many templates and style names. Using
  11133. third-party styles and templates can lead to mismatches. Templates derived
  11134. from built in ODT templates and styles seem to have fewer problems.
  11135. @node Links in ODT export
  11136. @subsection Links in ODT export
  11137. @cindex links, in ODT export
  11138. ODT export back-end creates native cross-references for internal links and
  11139. Internet-style links for all other link types.
  11140. A link with no description and pointing to a regular---un-itemized---outline
  11141. heading is replaced with a cross-reference and section number of the heading.
  11142. A @samp{\ref@{label@}}-style reference to an image, table etc.@: is replaced
  11143. with a cross-reference and sequence number of the labeled entity.
  11144. @xref{Labels and captions in ODT export}.
  11145. @node Tables in ODT export
  11146. @subsection Tables in ODT export
  11147. @cindex tables, in ODT export
  11148. The ODT export back-end handles native Org mode tables (@pxref{Tables}) and
  11149. simple @file{table.el} tables. Complex @file{table.el} tables having column
  11150. or row spans are not supported. Such tables are stripped from the exported
  11151. document.
  11152. By default, the ODT export back-end exports a table with top and bottom
  11153. frames and with ruled lines separating row and column groups (@pxref{Column
  11154. groups}). All tables are typeset to occupy the same width. The ODT export
  11155. back-end honors any table alignments and relative widths for columns
  11156. (@pxref{Column width and alignment}).
  11157. Note that the ODT export back-end interprets column widths as weighted
  11158. ratios, the default weight being 1.
  11159. @cindex #+ATTR_ODT
  11160. Specifying @code{:rel-width} property on an @code{#+ATTR_ODT} line controls
  11161. the width of the table. For example:
  11162. @example
  11163. #+ATTR_ODT: :rel-width 50
  11164. | Area/Month | Jan | Feb | Mar | Sum |
  11165. |---------------+-------+-------+-------+-------|
  11166. | / | < | | | < |
  11167. | <l13> | <r5> | <r5> | <r5> | <r6> |
  11168. | North America | 1 | 21 | 926 | 948 |
  11169. | Middle East | 6 | 75 | 844 | 925 |
  11170. | Asia Pacific | 9 | 27 | 790 | 826 |
  11171. |---------------+-------+-------+-------+-------|
  11172. | Sum | 16 | 123 | 2560 | 2699 |
  11173. @end example
  11174. On export, the above table takes 50% of text width area. The exporter sizes
  11175. the columns in the ratio: 13:5:5:5:6. The first column is left-aligned and
  11176. rest of the columns, right-aligned. Vertical rules separate the header and
  11177. the last column. Horizontal rules separate the header and the last row.
  11178. For even more customization, create custom table styles and associate them
  11179. with a table using the @code{#+ATTR_ODT} line. @xref{Customizing tables in
  11180. ODT export}.
  11181. @node Images in ODT export
  11182. @subsection Images in ODT export
  11183. @cindex images, embedding in ODT
  11184. @cindex embedding images in ODT
  11185. @subsubheading Embedding images
  11186. The ODT export back-end processes image links in Org files that do not have
  11187. descriptions, such as these links @samp{[[file:img.jpg]]} or
  11188. @samp{[[./img.jpg]]}, as direct image insertions in the final output. Either
  11189. of these examples works:
  11190. @example
  11191. [[file:img.png]]
  11192. @end example
  11193. @example
  11194. [[./img.png]]
  11195. @end example
  11196. @subsubheading Embedding clickable images
  11197. For clickable images, provide a link whose description is another link to an
  11198. image file. For example, to embed a image @file{org-mode-unicorn.png} which
  11199. when clicked jumps to @uref{http://Orgmode.org} website, do the following
  11200. @example
  11201. [[http://orgmode.org][./org-mode-unicorn.png]]
  11202. @end example
  11203. @subsubheading Sizing and scaling of embedded images
  11204. @cindex #+ATTR_ODT
  11205. Control the size and scale of the embedded images with the @code{#+ATTR_ODT}
  11206. attribute.
  11207. @cindex identify, ImageMagick
  11208. @vindex org-odt-pixels-per-inch
  11209. The ODT export back-end starts with establishing the size of the image in the
  11210. final document. The dimensions of this size is measured in centimeters. The
  11211. back-end then queries the image file for its dimensions measured in pixels.
  11212. For this measurement, the back-end relies on ImageMagick's @file{identify}
  11213. program or Emacs @code{create-image} and @code{image-size} API. ImageMagick
  11214. is the preferred choice for large file sizes or frequent batch operations.
  11215. The back-end then converts the pixel dimensions using
  11216. @code{org-odt-pixels-per-inch} into the familiar 72 dpi or 96 dpi. The
  11217. default value for this is in @code{display-pixels-per-inch}, which can be
  11218. tweaked for better results based on the capabilities of the output device.
  11219. Here are some common image scaling operations:
  11220. @table @asis
  11221. @item Explicitly size the image
  11222. To embed @file{img.png} as a 10 cm x 10 cm image, do the following:
  11223. @example
  11224. #+ATTR_ODT: :width 10 :height 10
  11225. [[./img.png]]
  11226. @end example
  11227. @item Scale the image
  11228. To embed @file{img.png} at half its size, do the following:
  11229. @example
  11230. #+ATTR_ODT: :scale 0.5
  11231. [[./img.png]]
  11232. @end example
  11233. @item Scale the image to a specific width
  11234. To embed @file{img.png} with a width of 10 cm while retaining the original
  11235. height:width ratio, do the following:
  11236. @example
  11237. #+ATTR_ODT: :width 10
  11238. [[./img.png]]
  11239. @end example
  11240. @item Scale the image to a specific height
  11241. To embed @file{img.png} with a height of 10 cm while retaining the original
  11242. height:width ratio, do the following
  11243. @example
  11244. #+ATTR_ODT: :height 10
  11245. [[./img.png]]
  11246. @end example
  11247. @end table
  11248. @subsubheading Anchoring of images
  11249. @cindex #+ATTR_ODT
  11250. The ODT export back-end can anchor images to @samp{"as-char"},
  11251. @samp{"paragraph"}, or @samp{"page"}. Set the preferred anchor using the
  11252. @code{:anchor} property of the @code{#+ATTR_ODT} line.
  11253. To create an image that is anchored to a page:
  11254. @example
  11255. #+ATTR_ODT: :anchor "page"
  11256. [[./img.png]]
  11257. @end example
  11258. @node Math formatting in ODT export
  11259. @subsection Math formatting in ODT export
  11260. The ODT export back-end has special support built-in for handling math.
  11261. @menu
  11262. * Working with @LaTeX{} math snippets:: Embedding in @LaTeX{} format.
  11263. * Working with MathML or OpenDocument formula files:: Embedding in native format.
  11264. @end menu
  11265. @node Working with @LaTeX{} math snippets
  11266. @subsubheading Working with @LaTeX{} math snippets
  11267. @LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in an ODT
  11268. document in one of the following ways:
  11269. @cindex MathML
  11270. @enumerate
  11271. @item MathML
  11272. Add this line to the Org file. This option is activated on a per-file basis.
  11273. @example
  11274. #+OPTIONS: LaTeX:t
  11275. @end example
  11276. With this option, @LaTeX{} fragments are first converted into MathML
  11277. fragments using an external @LaTeX{}-to-MathML converter program. The
  11278. resulting MathML fragments are then embedded as an OpenDocument Formula in
  11279. the exported document.
  11280. @vindex org-latex-to-mathml-convert-command
  11281. @vindex org-latex-to-mathml-jar-file
  11282. To specify the @LaTeX{}-to-MathML converter, customize the variables
  11283. @code{org-latex-to-mathml-convert-command} and
  11284. @code{org-latex-to-mathml-jar-file}.
  11285. To use MathToWeb@footnote{See
  11286. @uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}.} as the
  11287. preferred converter, configure the above variables as
  11288. @lisp
  11289. (setq org-latex-to-mathml-convert-command
  11290. "java -jar %j -unicode -force -df %o %I"
  11291. org-latex-to-mathml-jar-file
  11292. "/path/to/mathtoweb.jar")
  11293. @end lisp
  11294. To use @LaTeX{}ML@footnote{See @uref{http://dlmf.nist.gov/LaTeXML/}.} use
  11295. @lisp
  11296. (setq org-latex-to-mathml-convert-command
  11297. "latexmlmath \"%i\" --presentationmathml=%o")
  11298. @end lisp
  11299. To quickly verify the reliability of the @LaTeX{}-to-MathML converter, use
  11300. the following commands:
  11301. @table @kbd
  11302. @item M-x org-odt-export-as-odf RET
  11303. Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file.
  11304. @item M-x org-odt-export-as-odf-and-open RET
  11305. Convert a @LaTeX{} math snippet to an OpenDocument formula (@file{.odf}) file
  11306. and open the formula file with the system-registered application.
  11307. @end table
  11308. @cindex dvipng
  11309. @cindex dvisvgm
  11310. @cindex imagemagick
  11311. @item PNG images
  11312. Add this line to the Org file. This option is activated on a per-file basis.
  11313. @example
  11314. #+OPTIONS: tex:dvipng
  11315. @end example
  11316. @example
  11317. #+OPTIONS: tex:dvisvgm
  11318. @end example
  11319. or:
  11320. @example
  11321. #+OPTIONS: tex:imagemagick
  11322. @end example
  11323. Under this option, @LaTeX{} fragments are processed into PNG or SVG images
  11324. and the resulting images are embedded in the exported document. This method
  11325. requires @file{dvipng} program, @file{dvisvgm} or @file{imagemagick}
  11326. programs.
  11327. @end enumerate
  11328. @node Working with MathML or OpenDocument formula files
  11329. @subsubheading Working with MathML or OpenDocument formula files
  11330. When embedding @LaTeX{} math snippets in ODT documents is not reliable, there
  11331. is one more option to try. Embed an equation by linking to its MathML
  11332. (@file{.mml}) source or its OpenDocument formula (@file{.odf}) file as shown
  11333. below:
  11334. @example
  11335. [[./equation.mml]]
  11336. @end example
  11337. or
  11338. @example
  11339. [[./equation.odf]]
  11340. @end example
  11341. @node Labels and captions in ODT export
  11342. @subsection Labels and captions in ODT export
  11343. ODT format handles labeling and captioning of objects based on their
  11344. types. Inline images, tables, @LaTeX{} fragments, and Math formulas are
  11345. numbered and captioned separately. Each object also gets a unique sequence
  11346. number based on its order of first appearance in the Org file. Each category
  11347. has its own sequence. A caption is just a label applied to these objects.
  11348. @example
  11349. #+CAPTION: Bell curve
  11350. #+LABEL: fig:SED-HR4049
  11351. [[./img/a.png]]
  11352. @end example
  11353. When rendered, it may show as follows in the exported document:
  11354. @example
  11355. Figure 2: Bell curve
  11356. @end example
  11357. @vindex org-odt-category-map-alist
  11358. To modify the category component of the caption, customize the option
  11359. @code{org-odt-category-map-alist}. For example, to tag embedded images with
  11360. the string @samp{Illustration} instead of the default string @samp{Figure},
  11361. use the following setting:
  11362. @lisp
  11363. (setq org-odt-category-map-alist
  11364. '(("__Figure__" "Illustration" "value" "Figure" org-odt--enumerable-image-p)))
  11365. @end lisp
  11366. With the above modification, the previous example changes to:
  11367. @example
  11368. Illustration 2: Bell curve
  11369. @end example
  11370. @node Literal examples in ODT export
  11371. @subsection Literal examples in ODT export
  11372. The ODT export back-end supports literal examples (@pxref{Literal examples})
  11373. with full fontification. Internally, the ODT export back-end relies on
  11374. @file{htmlfontify.el} to generate the style definitions needed for fancy
  11375. listings. The auto-generated styles get @samp{OrgSrc} prefix and inherit
  11376. colors from the faces used by Emacs @code{font-lock} library for that source
  11377. language.
  11378. @vindex org-odt-fontify-srcblocks
  11379. For custom fontification styles, customize the
  11380. @code{org-odt-create-custom-styles-for-srcblocks} option.
  11381. @vindex org-odt-create-custom-styles-for-srcblocks
  11382. To turn off fontification of literal examples, customize the
  11383. @code{org-odt-fontify-srcblocks} option.
  11384. @node Advanced topics in ODT export
  11385. @subsection Advanced topics in ODT export
  11386. The ODT export back-end has extensive features useful for power users and
  11387. frequent uses of ODT formats.
  11388. @menu
  11389. * Configuring a document converter:: Registering a document converter.
  11390. * Working with OpenDocument style files:: Exploring internals.
  11391. * Creating one-off styles:: Customizing styles, highlighting.
  11392. * Customizing tables in ODT export:: Defining table templates.
  11393. * Validating OpenDocument XML:: Debugging corrupted OpenDocument files.
  11394. @end menu
  11395. @node Configuring a document converter
  11396. @subsubheading Configuring a document converter
  11397. @cindex convert
  11398. @cindex doc, docx, rtf
  11399. @cindex converter
  11400. The ODT export back-end works with popular converters with little or no extra
  11401. configuration. @xref{Extending ODT export}. The following is for unsupported
  11402. converters or tweaking existing defaults.
  11403. @enumerate
  11404. @item Register the converter
  11405. @vindex org-odt-convert-processes
  11406. Add the name of the converter to the @code{org-odt-convert-processes}
  11407. variable. Note that it also requires how the converter is invoked on the
  11408. command line. See the variable's docstring for details.
  11409. @item Configure its capabilities
  11410. @vindex org-odt-convert-capabilities
  11411. @anchor{x-odt-converter-capabilities} Specify which formats the converter can
  11412. handle by customizing the variable @code{org-odt-convert-capabilities}. Use
  11413. the entry for the default values in this variable for configuring the new
  11414. converter. Also see its docstring for details.
  11415. @item Choose the converter
  11416. @vindex org-odt-convert-process
  11417. Select the newly added converter as the preferred one by customizing the
  11418. option @code{org-odt-convert-process}.
  11419. @end enumerate
  11420. @node Working with OpenDocument style files
  11421. @subsubheading Working with OpenDocument style files
  11422. @cindex styles, custom
  11423. @cindex template, custom
  11424. This section explores the internals of the ODT exporter; the means by which
  11425. it produces styled documents; the use of automatic and custom OpenDocument
  11426. styles.
  11427. @anchor{x-factory-styles}
  11428. @subsubheading a) Factory styles
  11429. The ODT exporter relies on two files for generating its output.
  11430. These files are bundled with the distribution under the directory pointed to
  11431. by the variable @code{org-odt-styles-dir}. The two files are:
  11432. @itemize
  11433. @anchor{x-orgodtstyles-xml}
  11434. @item
  11435. @file{OrgOdtStyles.xml}
  11436. This file contributes to the @file{styles.xml} file of the final @samp{ODT}
  11437. document. This file gets modified for the following purposes:
  11438. @enumerate
  11439. @item
  11440. To control outline numbering based on user settings.
  11441. @item
  11442. To add styles generated by @file{htmlfontify.el} for fontification of code
  11443. blocks.
  11444. @end enumerate
  11445. @anchor{x-orgodtcontenttemplate-xml}
  11446. @item
  11447. @file{OrgOdtContentTemplate.xml}
  11448. This file contributes to the @file{content.xml} file of the final @samp{ODT}
  11449. document. The contents of the Org outline are inserted between the
  11450. @samp{<office:text>}@dots{}@samp{</office:text>} elements of this file.
  11451. Apart from serving as a template file for the final @file{content.xml}, the
  11452. file serves the following purposes:
  11453. @enumerate
  11454. @item
  11455. It contains automatic styles for formatting of tables which are referenced by
  11456. the exporter.
  11457. @item
  11458. It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>}
  11459. elements that control numbering of tables, images, equations, and similar
  11460. entities.
  11461. @end enumerate
  11462. @end itemize
  11463. @anchor{x-overriding-factory-styles}
  11464. @subsubheading b) Overriding factory styles
  11465. The following two variables control the location from where the ODT exporter
  11466. picks up the custom styles and content template files. Customize these
  11467. variables to override the factory styles used by the exporter.
  11468. @itemize
  11469. @anchor{x-org-odt-styles-file}
  11470. @item
  11471. @code{org-odt-styles-file}
  11472. The ODT export back-end uses the file pointed to by this variable, such as
  11473. @file{styles.xml}, for the final output. It can take one of the following
  11474. values:
  11475. @enumerate
  11476. @item A @file{styles.xml} file
  11477. Use this file instead of the default @file{styles.xml}
  11478. @item A @file{.odt} or @file{.ott} file
  11479. Use the @file{styles.xml} contained in the specified OpenDocument Text or
  11480. Template file
  11481. @item A @file{.odt} or @file{.ott} file and a subset of files contained within them
  11482. Use the @file{styles.xml} contained in the specified OpenDocument Text or
  11483. Template file. Additionally extract the specified member files and embed
  11484. those within the final @samp{ODT} document.
  11485. Use this option if the @file{styles.xml} file references additional files
  11486. like header and footer images.
  11487. @item @code{nil}
  11488. Use the default @file{styles.xml}
  11489. @end enumerate
  11490. @anchor{x-org-odt-content-template-file}
  11491. @item
  11492. @code{org-odt-content-template-file}
  11493. Use this variable to specify the blank @file{content.xml} that will be used
  11494. in the final output.
  11495. @end itemize
  11496. @node Creating one-off styles
  11497. @subsubheading Creating one-off styles
  11498. The ODT export back-end can read embedded raw OpenDocument XML from the Org
  11499. file. Such direct formatting are useful for one-off instances.
  11500. @enumerate
  11501. @item Embedding ODT tags as part of regular text
  11502. Enclose OpenDocument syntax in @samp{@@@@odt:...@@@@} for inline markup. For
  11503. example, to highlight a region of text do the following:
  11504. @example
  11505. @@@@odt:<text:span text:style-name="Highlight">This is highlighted
  11506. text</text:span>@@@@. But this is regular text.
  11507. @end example
  11508. @strong{Hint:} To see the above example in action, edit the @file{styles.xml}
  11509. (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a custom
  11510. @samp{Highlight} style as shown below:
  11511. @example
  11512. <style:style style:name="Highlight" style:family="text">
  11513. <style:text-properties fo:background-color="#ff0000"/>
  11514. </style:style>
  11515. @end example
  11516. @item Embedding a one-line OpenDocument XML
  11517. The ODT export back-end can read one-liner options with @code{#+ODT:}
  11518. in the Org file. For example, to force a page break:
  11519. @example
  11520. #+ODT: <text:p text:style-name="PageBreak"/>
  11521. @end example
  11522. @strong{Hint:} To see the above example in action, edit your
  11523. @file{styles.xml} (@pxref{x-orgodtstyles-xml,,Factory styles}) and add a
  11524. custom @samp{PageBreak} style as shown below.
  11525. @example
  11526. <style:style style:name="PageBreak" style:family="paragraph"
  11527. style:parent-style-name="Text_20_body">
  11528. <style:paragraph-properties fo:break-before="page"/>
  11529. </style:style>
  11530. @end example
  11531. @item Embedding a block of OpenDocument XML
  11532. The ODT export back-end can also read ODT export blocks for OpenDocument XML.
  11533. Such blocks use the @code{#+BEGIN_EXPORT odt}@dots{}@code{#+END_EXPORT}
  11534. constructs.
  11535. For example, to create a one-off paragraph that uses bold text, do the
  11536. following:
  11537. @example
  11538. #+BEGIN_EXPORT odt
  11539. <text:p text:style-name="Text_20_body_20_bold">
  11540. This paragraph is specially formatted and uses bold text.
  11541. </text:p>
  11542. #+END_EXPORT
  11543. @end example
  11544. @end enumerate
  11545. @node Customizing tables in ODT export
  11546. @subsubheading Customizing tables in ODT export
  11547. @cindex tables, in ODT export
  11548. @cindex #+ATTR_ODT
  11549. Override the default table format by specifying a custom table style with the
  11550. @code{#+ATTR_ODT} line. For a discussion on default formatting of tables
  11551. @pxref{Tables in ODT export}.
  11552. This feature closely mimics the way table templates are defined in the
  11553. OpenDocument-v1.2
  11554. specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html,
  11555. OpenDocument-v1.2 Specification}}
  11556. @vindex org-odt-table-styles
  11557. For quick preview of this feature, install the settings below and export the
  11558. table that follows:
  11559. @lisp
  11560. (setq org-odt-table-styles
  11561. (append org-odt-table-styles
  11562. '(("TableWithHeaderRowAndColumn" "Custom"
  11563. ((use-first-row-styles . t)
  11564. (use-first-column-styles . t)))
  11565. ("TableWithFirstRowandLastRow" "Custom"
  11566. ((use-first-row-styles . t)
  11567. (use-last-row-styles . t))))))
  11568. @end lisp
  11569. @example
  11570. #+ATTR_ODT: :style TableWithHeaderRowAndColumn
  11571. | Name | Phone | Age |
  11572. | Peter | 1234 | 17 |
  11573. | Anna | 4321 | 25 |
  11574. @end example
  11575. The example above used @samp{Custom} template and installed two table styles
  11576. @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}.
  11577. @strong{Important:} The OpenDocument styles needed for producing the above
  11578. template were pre-defined. They are available in the section marked
  11579. @samp{Custom Table Template} in @file{OrgOdtContentTemplate.xml}
  11580. (@pxref{x-orgodtcontenttemplate-xml,,Factory styles}. For adding new
  11581. templates, define new styles here.
  11582. To use this feature proceed as follows:
  11583. @enumerate
  11584. @item
  11585. Create a table template@footnote{See the @code{<table:table-template>}
  11586. element of the OpenDocument-v1.2 specification}
  11587. A table template is set of @samp{table-cell} and @samp{paragraph} styles for
  11588. each of the following table cell categories:
  11589. @itemize @minus
  11590. @item Body
  11591. @item First column
  11592. @item Last column
  11593. @item First row
  11594. @item Last row
  11595. @item Even row
  11596. @item Odd row
  11597. @item Even column
  11598. @item Odd Column
  11599. @end itemize
  11600. The names for the above styles must be chosen based on the name of the table
  11601. template using a well-defined convention.
  11602. The naming convention is better illustrated with an example. For a table
  11603. template with the name @samp{Custom}, the needed style names are listed in
  11604. the following table.
  11605. @multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph}
  11606. @headitem Table cell type
  11607. @tab @code{table-cell} style
  11608. @tab @code{paragraph} style
  11609. @item
  11610. @tab
  11611. @tab
  11612. @item Body
  11613. @tab @samp{CustomTableCell}
  11614. @tab @samp{CustomTableParagraph}
  11615. @item First column
  11616. @tab @samp{CustomFirstColumnTableCell}
  11617. @tab @samp{CustomFirstColumnTableParagraph}
  11618. @item Last column
  11619. @tab @samp{CustomLastColumnTableCell}
  11620. @tab @samp{CustomLastColumnTableParagraph}
  11621. @item First row
  11622. @tab @samp{CustomFirstRowTableCell}
  11623. @tab @samp{CustomFirstRowTableParagraph}
  11624. @item Last row
  11625. @tab @samp{CustomLastRowTableCell}
  11626. @tab @samp{CustomLastRowTableParagraph}
  11627. @item Even row
  11628. @tab @samp{CustomEvenRowTableCell}
  11629. @tab @samp{CustomEvenRowTableParagraph}
  11630. @item Odd row
  11631. @tab @samp{CustomOddRowTableCell}
  11632. @tab @samp{CustomOddRowTableParagraph}
  11633. @item Even column
  11634. @tab @samp{CustomEvenColumnTableCell}
  11635. @tab @samp{CustomEvenColumnTableParagraph}
  11636. @item Odd column
  11637. @tab @samp{CustomOddColumnTableCell}
  11638. @tab @samp{CustomOddColumnTableParagraph}
  11639. @end multitable
  11640. To create a table template with the name @samp{Custom}, define the above
  11641. styles in the
  11642. @code{<office:automatic-styles>}...@code{</office:automatic-styles>} element
  11643. of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory
  11644. styles}).
  11645. @item
  11646. Define a table style@footnote{See the attributes @code{table:template-name},
  11647. @code{table:use-first-row-styles}, @code{table:use-last-row-styles},
  11648. @code{table:use-first-column-styles}, @code{table:use-last-column-styles},
  11649. @code{table:use-banding-rows-styles}, and
  11650. @code{table:use-banding-column-styles} of the @code{<table:table>} element in
  11651. the OpenDocument-v1.2 specification}
  11652. @vindex org-odt-table-styles
  11653. To define a table style, create an entry for the style in the variable
  11654. @code{org-odt-table-styles} and specify the following:
  11655. @itemize @minus
  11656. @item the name of the table template created in step (1)
  11657. @item the set of cell styles in that template that are to be activated
  11658. @end itemize
  11659. For example, the entry below defines two different table styles
  11660. @samp{TableWithHeaderRowAndColumn} and @samp{TableWithFirstRowandLastRow}
  11661. based on the same template @samp{Custom}. The styles achieve their intended
  11662. effect by selectively activating the individual cell styles in that template.
  11663. @lisp
  11664. (setq org-odt-table-styles
  11665. (append org-odt-table-styles
  11666. '(("TableWithHeaderRowAndColumn" "Custom"
  11667. ((use-first-row-styles . t)
  11668. (use-first-column-styles . t)))
  11669. ("TableWithFirstRowandLastRow" "Custom"
  11670. ((use-first-row-styles . t)
  11671. (use-last-row-styles . t))))))
  11672. @end lisp
  11673. @item
  11674. Associate a table with the table style
  11675. To do this, specify the table style created in step (2) as part of
  11676. the @code{ATTR_ODT} line as shown below.
  11677. @example
  11678. #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
  11679. | Name | Phone | Age |
  11680. | Peter | 1234 | 17 |
  11681. | Anna | 4321 | 25 |
  11682. @end example
  11683. @end enumerate
  11684. @node Validating OpenDocument XML
  11685. @subsubheading Validating OpenDocument XML
  11686. Sometimes ODT format files may not open due to @file{.odt} file corruption.
  11687. To verify if the @file{.odt} file is corrupt, validate it against the
  11688. OpenDocument RELAX NG Compact Syntax---RNC---schema. But first the
  11689. @file{.odt} files have to be decompressed using @samp{zip}. Note that
  11690. @file{.odt} files are @samp{zip} archives: @inforef{File Archives,,emacs}.
  11691. The contents of @file{.odt} files are in @file{.xml}. For general help with
  11692. validation---and schema-sensitive editing---of XML files:
  11693. @inforef{Introduction,,nxml-mode}.
  11694. @vindex org-odt-schema-dir
  11695. Customize @code{org-odt-schema-dir} to point to a directory with OpenDocument
  11696. @file{.rnc} files and the needed schema-locating rules. The ODT export
  11697. back-end takes care of updating the @code{rng-schema-locating-files}.
  11698. @c end opendocument
  11699. @node Org export
  11700. @section Org export
  11701. @cindex Org export
  11702. @code{org} export back-end creates a normalized version of the Org document
  11703. in current buffer. The exporter evaluates Babel code (@pxref{Evaluating code
  11704. blocks}) and removes content specific to other back-ends.
  11705. @subheading Org export commands
  11706. @table @kbd
  11707. @orgcmd{C-c C-e O o,org-org-export-to-org}
  11708. Export as an Org file with a @file{.org} extension. For @file{myfile.org},
  11709. Org exports to @file{myfile.org.org}, overwriting without warning.
  11710. @orgcmd{C-c C-e O O,org-org-export-as-org}
  11711. Export to a temporary buffer. Does not create a file.
  11712. @item C-c C-e O v
  11713. Export to an Org file, then open it.
  11714. @end table
  11715. @node Texinfo export
  11716. @section Texinfo export
  11717. @cindex Texinfo export
  11718. The @samp{texinfo} export back-end generates documents with Texinfo code that
  11719. can compile to Info format.
  11720. @menu
  11721. * Texinfo export commands:: Invoking commands.
  11722. * Texinfo specific export settings:: Setting the environment.
  11723. * Texinfo file header:: Generating the header.
  11724. * Texinfo title and copyright page:: Creating preamble pages.
  11725. * Info directory file:: Installing a manual in Info file hierarchy.
  11726. * Headings and sectioning structure:: Building document structure.
  11727. * Indices:: Creating indices.
  11728. * Quoting Texinfo code:: Incorporating literal Texinfo code.
  11729. * Plain lists in Texinfo export:: List attributes.
  11730. * Tables in Texinfo export:: Table attributes.
  11731. * Images in Texinfo export:: Image attributes.
  11732. * Special blocks in Texinfo export:: Special block attributes.
  11733. * A Texinfo example:: Processing Org to Texinfo.
  11734. @end menu
  11735. @node Texinfo export commands
  11736. @subsection Texinfo export commands
  11737. @vindex org-texinfo-info-process
  11738. @table @kbd
  11739. @orgcmd{C-c C-e i t,org-texinfo-export-to-texinfo}
  11740. Export as a Texinfo file with @file{.texi} extension. For @file{myfile.org},
  11741. Org exports to @file{myfile.texi}, overwriting without warning.
  11742. @orgcmd{C-c C-e i i,org-texinfo-export-to-info}
  11743. Export to Texinfo format first and then process it to make an Info file. To
  11744. generate other formats, such as DocBook, customize the
  11745. @code{org-texinfo-info-process} variable.
  11746. @end table
  11747. @node Texinfo specific export settings
  11748. @subsection Texinfo specific export settings
  11749. The Texinfo export back-end has several additional keywords for customizing
  11750. Texinfo output. Setting these keywords works similar to the general options
  11751. (@pxref{Export settings}).
  11752. @table @samp
  11753. @item SUBTITLE
  11754. @cindex #+SUBTITLE (Texinfo)
  11755. The document subtitle.
  11756. @item SUBAUTHOR
  11757. @cindex #+SUBAUTHOR
  11758. The document subauthor.
  11759. @item TEXINFO_FILENAME
  11760. @cindex #+TEXINFO_FILENAME
  11761. The Texinfo filename.
  11762. @item TEXINFO_CLASS
  11763. @cindex #+TEXINFO_CLASS
  11764. @vindex org-texinfo-default-class
  11765. The default document class (@code{org-texinfo-default-class}), which must be
  11766. a member of @code{org-texinfo-classes}.
  11767. @item TEXINFO_HEADER
  11768. @cindex #+TEXINFO_HEADER
  11769. Arbitrary lines inserted at the end of the header.
  11770. @item TEXINFO_POST_HEADER
  11771. @cindex #+TEXINFO_POST_HEADER
  11772. Arbitrary lines inserted after the end of the header.
  11773. @item TEXINFO_DIR_CATEGORY
  11774. @cindex #+TEXINFO_DIR_CATEGORY
  11775. The directory category of the document.
  11776. @item TEXINFO_DIR_TITLE
  11777. @cindex #+TEXINFO_DIR_TITLE
  11778. The directory title of the document.
  11779. @item TEXINFO_DIR_DESC
  11780. @cindex #+TEXINFO_DIR_DESC
  11781. The directory description of the document.
  11782. @item TEXINFO_PRINTED_TITLE
  11783. @cindex #+TEXINFO_PRINTED_TITLE
  11784. The printed title of the document.
  11785. @end table
  11786. @node Texinfo file header
  11787. @subsection Texinfo file header
  11788. @cindex #+TEXINFO_FILENAME
  11789. After creating the header for a Texinfo file, the Texinfo back-end
  11790. automatically generates a name and destination path for the Info file. To
  11791. override this default with a more sensible path and name, specify the
  11792. @code{#+TEXINFO_FILENAME} keyword.
  11793. @vindex org-texinfo-coding-system
  11794. @vindex org-texinfo-classes
  11795. @cindex #+TEXINFO_HEADER
  11796. @cindex #+TEXINFO_CLASS
  11797. Along with the output's file name, the Texinfo header also contains language
  11798. details (@pxref{Export settings}) and encoding system as set in the
  11799. @code{org-texinfo-coding-system} variable. Insert @code{#+TEXINFO_HEADER}
  11800. keywords for each additional command in the header, for example:
  11801. @@code@{@@synindex@}.
  11802. Instead of repeatedly installing the same set of commands, define a class in
  11803. @code{org-texinfo-classes} once, and then activate it in the document by
  11804. setting the @code{#+TEXINFO_CLASS} keyword to that class.
  11805. @node Texinfo title and copyright page
  11806. @subsection Texinfo title and copyright page
  11807. @cindex #+TEXINFO_PRINTED_TITLE
  11808. The default template for hard copy output has a title page with
  11809. @code{#+TITLE} and @code{#+AUTHOR} (@pxref{Export settings}). To replace the
  11810. regular @code{#+TITLE} with something different for the printed version, use
  11811. the @code{#+TEXINFO_PRINTED_TITLE} and @code{#+SUBTITLE} keywords. Both
  11812. expect raw Texinfo code for setting their values.
  11813. @cindex #+SUBAUTHOR
  11814. If one @code{#+AUTHOR} is not sufficient, add multiple @code{#+SUBAUTHOR}
  11815. keywords. They have to be set in raw Texinfo code.
  11816. @example
  11817. #+AUTHOR: Jane Smith
  11818. #+SUBAUTHOR: John Doe
  11819. #+TEXINFO_PRINTED_TITLE: This Long Title@@inlinefmt@{tex,@@*@} Is Broken in @@TeX@{@}
  11820. @end example
  11821. @cindex property, COPYING
  11822. Copying material is defined in a dedicated headline with a non-@code{nil}
  11823. @code{:COPYING:} property. The back-end inserts the contents within a
  11824. @code{@@copying} command at the beginning of the document. The heading
  11825. itself does not appear in the structure of the document.
  11826. Copyright information is printed on the back of the title page.
  11827. @example
  11828. * Legalese
  11829. :PROPERTIES:
  11830. :COPYING: t
  11831. :END:
  11832. This is a short example of a complete Texinfo file, version 1.0.
  11833. Copyright \copy 2016 Free Software Foundation, Inc.
  11834. @end example
  11835. @node Info directory file
  11836. @subsection Info directory file
  11837. @cindex @samp{dir} file, in Texinfo export
  11838. @cindex Texinfo export, @samp{dir} file
  11839. @cindex Info directory file, in Texinfo export
  11840. @cindex Texinfo export, Info directory file
  11841. @cindex @code{install-info} parameters, in Texinfo export
  11842. @cindex Texinfo export, @code{install-info} parameters
  11843. @cindex #+TEXINFO_DIR_CATEGORY
  11844. @cindex #+TEXINFO_DIR_TITLE
  11845. @cindex #+TEXINFO_DIR_DESC
  11846. The end result of the Texinfo export process is the creation of an Info file.
  11847. This Info file's metadata has variables for category, title, and description:
  11848. @code{#+TEXINFO_DIR_CATEGORY}, @code{#+TEXINFO_DIR_TITLE}, and
  11849. @code{#+TEXINFO_DIR_DESC} that establish where in the Info hierarchy the file
  11850. fits.
  11851. Here is an example that writes to the Info directory file:
  11852. @example
  11853. #+TEXINFO_DIR_CATEGORY: Emacs
  11854. #+TEXINFO_DIR_TITLE: Org Mode: (org)
  11855. #+TEXINFO_DIR_DESC: Outline-based notes management and organizer
  11856. @end example
  11857. @node Headings and sectioning structure
  11858. @subsection Headings and sectioning structure
  11859. @vindex org-texinfo-classes
  11860. @vindex org-texinfo-default-class
  11861. @cindex #+TEXINFO_CLASS
  11862. The Texinfo export back-end uses a pre-defined scheme to convert Org
  11863. headlines to an equivalent Texinfo structuring commands. A scheme like this
  11864. maps top-level headlines to numbered chapters tagged as @code{@@chapter} and
  11865. lower-level headlines to unnumbered chapters tagged as @code{@@unnumbered}.
  11866. To override such mappings to introduce @code{@@part} or other Texinfo
  11867. structuring commands, define a new class in @code{org-texinfo-classes}.
  11868. Activate the new class with the @code{#+TEXINFO_CLASS} keyword. When no new
  11869. class is defined and activated, the Texinfo export back-end defaults to the
  11870. @code{org-texinfo-default-class}.
  11871. If an Org headline's level has no associated Texinfo structuring command, or
  11872. is below a certain threshold (@pxref{Export settings}), then the Texinfo
  11873. export back-end makes it into a list item.
  11874. @cindex property, APPENDIX
  11875. The Texinfo export back-end makes any headline with a non-@code{nil}
  11876. @code{:APPENDIX:} property into an appendix. This happens independent of the
  11877. Org headline level or the @code{#+TEXINFO_CLASS}.
  11878. @cindex property, DESCRIPTION
  11879. The Texinfo export back-end creates a menu entry after the Org headline for
  11880. each regular sectioning structure. To override this with a shorter menu
  11881. entry, use the @code{:ALT_TITLE:} property (@pxref{Table of contents}).
  11882. Texinfo menu entries also have an option for a longer @code{:DESCRIPTION:}
  11883. property. Here's an example that uses both to override the default menu
  11884. entry:
  11885. @example
  11886. * Controlling Screen Display
  11887. :PROPERTIES:
  11888. :ALT_TITLE: Display
  11889. :DESCRIPTION: Controlling Screen Display
  11890. :END:
  11891. @end example
  11892. @cindex The Top node, in Texinfo export
  11893. @cindex Texinfo export, Top node
  11894. The text before the first headline belongs to the @samp{Top} node, i.e., the
  11895. node in which a reader enters an Info manual. As such, it is expected not to
  11896. appear in printed output generated from the @file{.texi} file. @inforef{The
  11897. Top Node,,texinfo}, for more information.
  11898. @node Indices
  11899. @subsection Indices
  11900. @cindex #+CINDEX
  11901. @cindex concept index, in Texinfo export
  11902. @cindex Texinfo export, index, concept
  11903. @cindex #+FINDEX
  11904. @cindex function index, in Texinfo export
  11905. @cindex Texinfo export, index, function
  11906. @cindex #+KINDEX
  11907. @cindex keystroke index, in Texinfo export
  11908. @cindex Texinfo export, keystroke index
  11909. @cindex #+PINDEX
  11910. @cindex program index, in Texinfo export
  11911. @cindex Texinfo export, program index
  11912. @cindex #+TINDEX
  11913. @cindex data type index, in Texinfo export
  11914. @cindex Texinfo export, data type index
  11915. @cindex #+VINDEX
  11916. @cindex variable index, in Texinfo export
  11917. @cindex Texinfo export, variable index
  11918. The Texinfo export back-end recognizes these indexing keywords if used in the
  11919. Org file: @code{#+CINDEX}, @code{#+FINDEX}, @code{#+KINDEX}, @code{#+PINDEX},
  11920. @code{#+TINDEX}, and @code{#+VINDEX}. Write their value as verbatim Texinfo
  11921. code; in particular, @samp{@{}, @samp{@}} and @samp{@@} characters need to be
  11922. escaped with @samp{@@} if they not belong to a Texinfo command.
  11923. @example
  11924. #+CINDEX: Defining indexing entries
  11925. @end example
  11926. @cindex property, INDEX
  11927. For the back-end to generate an index entry for a headline, set the
  11928. @code{:INDEX:} property to @samp{cp} or @samp{vr}. These abbreviations come
  11929. from Texinfo that stand for concept index and variable index. The Texinfo
  11930. manual has abbreviations for all other kinds of indexes. The back-end
  11931. exports the headline as an unnumbered chapter or section command, and then
  11932. inserts the index after its contents.
  11933. @example
  11934. * Concept Index
  11935. :PROPERTIES:
  11936. :INDEX: cp
  11937. :END:
  11938. @end example
  11939. @node Quoting Texinfo code
  11940. @subsection Quoting Texinfo code
  11941. Use any of the following three methods to insert or escape raw Texinfo code:
  11942. @cindex #+TEXINFO
  11943. @cindex #+BEGIN_EXPORT texinfo
  11944. @example
  11945. Richard @@@@texinfo:@@sc@{@@@@Stallman@@@@texinfo:@}@@@@ commence' GNU.
  11946. #+TEXINFO: @@need800
  11947. This paragraph is preceded by...
  11948. #+BEGIN_EXPORT texinfo
  11949. @@auindex Johnson, Mark
  11950. @@auindex Lakoff, George
  11951. #+END_EXPORT
  11952. @end example
  11953. @node Plain lists in Texinfo export
  11954. @subsection Plain lists in Texinfo export
  11955. @cindex #+ATTR_TEXINFO, in plain lists
  11956. @cindex Two-column tables, in Texinfo export
  11957. @cindex :table-type attribute, in Texinfo export
  11958. The Texinfo export back-end by default converts description lists in the Org
  11959. file using the default command @code{@@table}, which results in a table with
  11960. two columns. To change this behavior, specify @code{:table-type} with
  11961. @code{ftable} or @code{vtable} attributes. For more information,
  11962. @inforef{Two-column Tables,,texinfo}.
  11963. @vindex org-texinfo-table-default-markup
  11964. @cindex :indic attribute, in Texinfo export
  11965. The Texinfo export back-end by default also applies a text highlight based on
  11966. the defaults stored in @code{org-texinfo-table-default-markup}. To override
  11967. the default highlight command, specify another one with the @code{:indic}
  11968. attribute.
  11969. @cindex Multiple entries in two-column tables, in Texinfo export
  11970. @cindex :sep attribute, in Texinfo export
  11971. Org syntax is limited to one entry per list item. Nevertheless, the Texinfo
  11972. export back-end can split that entry according to any text provided through
  11973. the @code{:sep} attribute. Each part then becomes a new entry in the first
  11974. column of the table.
  11975. The following example illustrates all the attributes above:
  11976. @example
  11977. #+ATTR_TEXINFO: :table-type vtable :sep , :indic asis
  11978. - foo, bar :: This is the common text for variables foo and bar.
  11979. @end example
  11980. @noindent
  11981. becomes
  11982. @example
  11983. @@vtable @@asis
  11984. @@item foo
  11985. @@itemx bar
  11986. This is the common text for variables foo and bar.
  11987. @@end table
  11988. @end example
  11989. @node Tables in Texinfo export
  11990. @subsection Tables in Texinfo export
  11991. @cindex #+ATTR_TEXINFO, in tables
  11992. When exporting tables, the Texinfo export back-end uses the widest cell width
  11993. in each column. To override this and instead specify as fractions of line
  11994. length, use the @code{:columns} attribute. See example below.
  11995. @example
  11996. #+ATTR_TEXINFO: :columns .5 .5
  11997. | a cell | another cell |
  11998. @end example
  11999. @node Images in Texinfo export
  12000. @subsection Images in Texinfo export
  12001. @cindex #+ATTR_TEXINFO, in images
  12002. Insert a file link to the image in the Org file, and the Texinfo export
  12003. back-end inserts the image. These links must have the usual supported image
  12004. extensions and no descriptions. To scale the image, use @code{:width} and
  12005. @code{:height} attributes. For alternate text, use @code{:alt} and specify
  12006. the text using Texinfo code, as shown in the example:
  12007. @example
  12008. #+ATTR_TEXINFO: :width 1in :alt Alternate @@i@{text@}
  12009. [[ridt.pdf]]
  12010. @end example
  12011. @node Special blocks in Texinfo export
  12012. @subsection Special blocks
  12013. @cindex #+ATTR_TEXINFO, in special blocks
  12014. The Texinfo export back-end converts special blocks to commands with the same
  12015. name. It also adds any @code{:options} attributes to the end of the command,
  12016. as shown in this example:
  12017. @example
  12018. #+ATTR_TEXINFO: :options org-org-export-to-org ...
  12019. #+begin_defun
  12020. A somewhat obsessive function.
  12021. #+end_defun
  12022. @end example
  12023. @noindent
  12024. becomes
  12025. @example
  12026. @@defun org-org-export-to-org ...
  12027. A somewhat obsessive function.
  12028. @@end defun
  12029. @end example
  12030. @node A Texinfo example
  12031. @subsection A Texinfo example
  12032. Here is a more detailed example Org file. @xref{GNU Sample
  12033. Texts,,,texinfo,GNU Texinfo Manual} for an equivalent example using Texinfo
  12034. code.
  12035. @example
  12036. #+TITLE: GNU Sample @{@{@{version@}@}@}
  12037. #+SUBTITLE: for version @{@{@{version@}@}@}, @{@{@{updated@}@}@}
  12038. #+AUTHOR: A.U. Thor
  12039. #+EMAIL: bug-sample@@gnu.org
  12040. #+OPTIONS: ':t toc:t author:t email:t
  12041. #+LANGUAGE: en
  12042. #+MACRO: version 2.0
  12043. #+MACRO: updated last updated 4 March 2014
  12044. #+TEXINFO_FILENAME: sample.info
  12045. #+TEXINFO_HEADER: @@syncodeindex pg cp
  12046. #+TEXINFO_DIR_CATEGORY: Texinfo documentation system
  12047. #+TEXINFO_DIR_TITLE: sample: (sample)
  12048. #+TEXINFO_DIR_DESC: Invoking sample
  12049. #+TEXINFO_PRINTED_TITLE: GNU Sample
  12050. This manual is for GNU Sample (version @{@{@{version@}@}@},
  12051. @{@{@{updated@}@}@}).
  12052. * Copying
  12053. :PROPERTIES:
  12054. :COPYING: t
  12055. :END:
  12056. This manual is for GNU Sample (version @{@{@{version@}@}@},
  12057. @{@{@{updated@}@}@}), which is an example in the Texinfo documentation.
  12058. Copyright \copy 2016 Free Software Foundation, Inc.
  12059. #+BEGIN_QUOTE
  12060. Permission is granted to copy, distribute and/or modify this
  12061. document under the terms of the GNU Free Documentation License,
  12062. Version 1.3 or any later version published by the Free Software
  12063. Foundation; with no Invariant Sections, with no Front-Cover Texts,
  12064. and with no Back-Cover Texts. A copy of the license is included in
  12065. the section entitled "GNU Free Documentation License".
  12066. #+END_QUOTE
  12067. * Invoking sample
  12068. #+PINDEX: sample
  12069. #+CINDEX: invoking @@command@{sample@}
  12070. This is a sample manual. There is no sample program to invoke, but
  12071. if there were, you could see its basic usage and command line
  12072. options here.
  12073. * GNU Free Documentation License
  12074. :PROPERTIES:
  12075. :APPENDIX: t
  12076. :END:
  12077. #+TEXINFO: @@include fdl.texi
  12078. * Index
  12079. :PROPERTIES:
  12080. :INDEX: cp
  12081. :END:
  12082. @end example
  12083. @node iCalendar export
  12084. @section iCalendar export
  12085. @cindex iCalendar export
  12086. @vindex org-icalendar-include-todo
  12087. @vindex org-icalendar-use-deadline
  12088. @vindex org-icalendar-use-scheduled
  12089. @vindex org-icalendar-categories
  12090. @vindex org-icalendar-alarm-time
  12091. A large part of Org mode's inter-operability success is its ability to easily
  12092. export to or import from external applications. The iCalendar export
  12093. back-end takes calendar data from Org files and exports to the standard
  12094. iCalendar format.
  12095. The iCalendar export back-end can also incorporate TODO entries based on the
  12096. configuration of the @code{org-icalendar-include-todo} variable. The
  12097. back-end exports plain timestamps as VEVENT, TODO items as VTODO, and also
  12098. create events from deadlines that are in non-TODO items. The back-end uses
  12099. the deadlines and scheduling dates in Org TODO items for setting the start
  12100. and due dates for the iCalendar TODO entry. Consult the
  12101. @code{org-icalendar-use-deadline} and @code{org-icalendar-use-scheduled}
  12102. variables for more details.
  12103. For tags on the headline, the iCalendar export back-end makes them into
  12104. iCalendar categories. To tweak the inheritance of tags and TODO states,
  12105. configure the variable @code{org-icalendar-categories}. To assign clock
  12106. alarms based on time, configure the @code{org-icalendar-alarm-time} variable.
  12107. @vindex org-icalendar-store-UID
  12108. @cindex property, ID
  12109. The iCalendar format standard requires globally unique identifier---UID---for
  12110. each entry. The iCalendar export back-end creates UIDs during export. To
  12111. save a copy of the UID in the Org file set the variable
  12112. @code{org-icalendar-store-UID}. The back-end looks for the @code{:ID:}
  12113. property of the entry for re-using the same UID for subsequent exports.
  12114. Since a single Org entry can result in multiple iCalendar entries---as
  12115. timestamp, deadline, scheduled item, or TODO item---Org adds prefixes to the
  12116. UID, depending on which part of the Org entry triggered the creation of the
  12117. iCalendar entry. Prefixing ensures UIDs remains unique, yet enable
  12118. synchronization programs trace the connections.
  12119. @table @kbd
  12120. @orgcmd{C-c C-e c f,org-icalendar-export-to-ics}
  12121. Create iCalendar entries from the current Org buffer and store them in the
  12122. same directory, using a file extension @file{.ics}.
  12123. @orgcmd{C-c C-e c a, org-icalendar-export-agenda-files}
  12124. @vindex org-agenda-files
  12125. Create iCalendar entries from Org files in @code{org-agenda-files} and store
  12126. in a separate iCalendar file for each Org file.
  12127. @orgcmd{C-c C-e c c,org-icalendar-combine-agenda-files}
  12128. @vindex org-icalendar-combined-agenda-file
  12129. Create a combined iCalendar file from Org files in @code{org-agenda-files}
  12130. and write it to @code{org-icalendar-combined-agenda-file} file name.
  12131. @end table
  12132. @vindex org-use-property-inheritance
  12133. @vindex org-icalendar-include-body
  12134. @cindex property, SUMMARY
  12135. @cindex property, DESCRIPTION
  12136. @cindex property, LOCATION
  12137. @cindex property, TIMEZONE
  12138. The iCalendar export back-end includes SUMMARY, DESCRIPTION, LOCATION and
  12139. TIMEZONE properties from the Org entries when exporting. To force the
  12140. back-end to inherit the LOCATION and TIMEZONE properties, configure the
  12141. @code{org-use-property-inheritance} variable.
  12142. When Org entries do not have SUMMARY, DESCRIPTION and LOCATION properties,
  12143. the iCalendar export back-end derives the summary from the headline, and
  12144. derives the description from the body of the Org item. The
  12145. @code{org-icalendar-include-body} variable limits the maximum number of
  12146. characters of the content are turned into its description.
  12147. The TIMEZONE property can be used to specify a per-entry time zone, and will
  12148. be applied to any entry with timestamp information. Time zones should be
  12149. specified as per the IANA time zone database format, e.g.@: ``Asia/Almaty''.
  12150. Alternately, the property value can be ``UTC'', to force UTC time for this
  12151. entry only.
  12152. Exporting to iCalendar format depends in large part on the capabilities of
  12153. the destination application. Some are more lenient than others. Consult the
  12154. Org mode FAQ for advice on specific applications.
  12155. @node Other built-in back-ends
  12156. @section Other built-in back-ends
  12157. @cindex export back-ends, built-in
  12158. @vindex org-export-backends
  12159. Other export back-ends included with Org are:
  12160. @itemize
  12161. @item @file{ox-man.el}: export to a man page.
  12162. @end itemize
  12163. To activate such back-ends, either customize @code{org-export-backends} or
  12164. load directly with @code{(require 'ox-man)}. On successful load, the
  12165. back-end adds new keys in the export dispatcher (@pxref{The export
  12166. dispatcher}).
  12167. Follow the comment section of such files, for example, @file{ox-man.el}, for
  12168. usage and configuration details.
  12169. @node Advanced configuration
  12170. @section Advanced configuration
  12171. @subheading Hooks
  12172. @vindex org-export-before-processing-hook
  12173. @vindex org-export-before-parsing-hook
  12174. The export process executes two hooks before the actual exporting begins.
  12175. The first hook, @code{org-export-before-processing-hook}, runs before any
  12176. expansions of macros, Babel code, and include keywords in the buffer. The
  12177. second hook, @code{org-export-before-parsing-hook}, runs before the buffer is
  12178. parsed. Both hooks are specified as functions, see example below. Their main
  12179. use is for heavy duty structural modifications of the Org content. For
  12180. example, removing every headline in the buffer during export:
  12181. @lisp
  12182. @group
  12183. (defun my-headline-removal (backend)
  12184. "Remove all headlines in the current buffer.
  12185. BACKEND is the export back-end being used, as a symbol."
  12186. (org-map-entries
  12187. (lambda () (delete-region (point) (progn (forward-line) (point))))))
  12188. (add-hook 'org-export-before-parsing-hook 'my-headline-removal)
  12189. @end group
  12190. @end lisp
  12191. Note that the hook function must have a mandatory argument that is a symbol
  12192. for the back-end.
  12193. @subheading Filters
  12194. @cindex Filters, exporting
  12195. The Org export process relies on filters to process specific parts of
  12196. conversion process. Filters are just lists of functions to be applied to
  12197. certain parts for a given back-end. The output from the first function in
  12198. the filter is passed on to the next function in the filter. The final output
  12199. is the output from the final function in the filter.
  12200. The Org export process has many filter sets applicable to different types of
  12201. objects, plain text, parse trees, export options, and final output formats.
  12202. The filters are named after the element type or object type:
  12203. @code{org-export-filter-TYPE-functions}, where @code{TYPE} is the type
  12204. targeted by the filter. Valid types are:
  12205. @multitable @columnfractions .33 .33 .33
  12206. @item body
  12207. @tab bold
  12208. @tab babel-call
  12209. @item center-block
  12210. @tab clock
  12211. @tab code
  12212. @item diary-sexp
  12213. @tab drawer
  12214. @tab dynamic-block
  12215. @item entity
  12216. @tab example-block
  12217. @tab export-block
  12218. @item export-snippet
  12219. @tab final-output
  12220. @tab fixed-width
  12221. @item footnote-definition
  12222. @tab footnote-reference
  12223. @tab headline
  12224. @item horizontal-rule
  12225. @tab inline-babel-call
  12226. @tab inline-src-block
  12227. @item inlinetask
  12228. @tab italic
  12229. @tab item
  12230. @item keyword
  12231. @tab latex-environment
  12232. @tab latex-fragment
  12233. @item line-break
  12234. @tab link
  12235. @tab node-property
  12236. @item options
  12237. @tab paragraph
  12238. @tab parse-tree
  12239. @item plain-list
  12240. @tab plain-text
  12241. @tab planning
  12242. @item property-drawer
  12243. @tab quote-block
  12244. @tab radio-target
  12245. @item section
  12246. @tab special-block
  12247. @tab src-block
  12248. @item statistics-cookie
  12249. @tab strike-through
  12250. @tab subscript
  12251. @item superscript
  12252. @tab table
  12253. @tab table-cell
  12254. @item table-row
  12255. @tab target
  12256. @tab timestamp
  12257. @item underline
  12258. @tab verbatim
  12259. @tab verse-block
  12260. @end multitable
  12261. Here is an example filter that replaces non-breaking spaces @code{~} in the
  12262. Org buffer with @code{_} for the @LaTeX{} back-end.
  12263. @lisp
  12264. @group
  12265. (defun my-latex-filter-nobreaks (text backend info)
  12266. "Ensure \"_\" are properly handled in LaTeX export."
  12267. (when (org-export-derived-backend-p backend 'latex)
  12268. (replace-regexp-in-string "_" "~" text)))
  12269. (add-to-list 'org-export-filter-plain-text-functions
  12270. 'my-latex-filter-nobreaks)
  12271. @end group
  12272. @end lisp
  12273. A filter requires three arguments: the code to be transformed, the name of
  12274. the back-end, and some optional information about the export process. The
  12275. third argument can be safely ignored. Note the use of
  12276. @code{org-export-derived-backend-p} predicate that tests for @code{latex}
  12277. back-end or any other back-end, such as @code{beamer}, derived from
  12278. @code{latex}.
  12279. @subheading Defining filters for individual files
  12280. The Org export can filter not just for back-ends, but also for specific files
  12281. through the @code{#+BIND} keyword. Here is an example with two filters; one
  12282. removes brackets from time stamps, and the other removes strike-through text.
  12283. The filter functions are defined in a @samp{src} code block in the same Org
  12284. file, which is a handy location for debugging.
  12285. @example
  12286. #+BIND: org-export-filter-timestamp-functions (tmp-f-timestamp)
  12287. #+BIND: org-export-filter-strike-through-functions (tmp-f-strike-through)
  12288. #+begin_src emacs-lisp :exports results :results none
  12289. (defun tmp-f-timestamp (s backend info)
  12290. (replace-regexp-in-string "&[lg]t;\\|[][]" "" s))
  12291. (defun tmp-f-strike-through (s backend info) "")
  12292. #+end_src
  12293. @end example
  12294. @subheading Extending an existing back-end
  12295. Some parts of the conversion process can be extended for certain elements so
  12296. as to introduce a new or revised translation. That is how the HTML export
  12297. back-end was extended to handle Markdown format. The extensions work
  12298. seamlessly so any aspect of filtering not done by the extended back-end is
  12299. handled by the original back-end. Of all the export customization in Org,
  12300. extending is very powerful as it operates at the parser level.
  12301. For this example, make the @code{ascii} back-end display the language used in
  12302. a source code block. Also make it display only when some attribute is
  12303. non-@code{nil}, like the following:
  12304. @example
  12305. #+ATTR_ASCII: :language t
  12306. @end example
  12307. Then extend @code{ascii} back-end with a custom @code{my-ascii} back-end.
  12308. @lisp
  12309. @group
  12310. (defun my-ascii-src-block (src-block contents info)
  12311. "Transcode a SRC-BLOCK element from Org to ASCII.
  12312. CONTENTS is nil. INFO is a plist used as a communication
  12313. channel."
  12314. (if (not (org-export-read-attribute :attr_ascii src-block :language))
  12315. (org-export-with-backend 'ascii src-block contents info)
  12316. (concat
  12317. (format ",--[ %s ]--\n%s`----"
  12318. (org-element-property :language src-block)
  12319. (replace-regexp-in-string
  12320. "^" "| "
  12321. (org-element-normalize-string
  12322. (org-export-format-code-default src-block info)))))))
  12323. (org-export-define-derived-backend 'my-ascii 'ascii
  12324. :translate-alist '((src-block . my-ascii-src-block)))
  12325. @end group
  12326. @end lisp
  12327. The @code{my-ascii-src-block} function looks at the attribute above the
  12328. current element. If not true, hands over to @code{ascii} back-end. If true,
  12329. which it is in this example, it creates a box around the code and leaves room
  12330. for the inserting a string for language. The last form creates the new
  12331. back-end that springs to action only when translating @code{src-block} type
  12332. elements.
  12333. To use the newly defined back-end, call the following from an Org buffer:
  12334. @smalllisp
  12335. (org-export-to-buffer 'my-ascii "*Org MY-ASCII Export*")
  12336. @end smalllisp
  12337. Further steps to consider would be an interactive function, self-installing
  12338. an item in the export dispatcher menu, and other user-friendly improvements.
  12339. @node Export in foreign buffers
  12340. @section Export in foreign buffers
  12341. The export back-ends in Org often include commands to convert selected
  12342. regions. A convenient feature of this in-place conversion is that the
  12343. exported output replaces the original source. Here are such functions:
  12344. @table @code
  12345. @item org-html-convert-region-to-html
  12346. Convert the selected region into HTML.
  12347. @item org-latex-convert-region-to-latex
  12348. Convert the selected region into @LaTeX{}.
  12349. @item org-texinfo-convert-region-to-texinfo
  12350. Convert the selected region into @code{Texinfo}.
  12351. @item org-md-convert-region-to-md
  12352. Convert the selected region into @code{MarkDown}.
  12353. @end table
  12354. In-place conversions are particularly handy for quick conversion of tables
  12355. and lists in foreign buffers. For example, turn on the minor mode @code{M-x
  12356. orgstruct-mode} in an HTML buffer, then use the convenient Org keyboard
  12357. commands to create a list, select it, and covert it to HTML with @code{M-x
  12358. org-html-convert-region-to-html RET}.
  12359. @node Publishing
  12360. @chapter Publishing
  12361. @cindex publishing
  12362. Org includes a publishing management system that allows you to configure
  12363. automatic HTML conversion of @emph{projects} composed of interlinked org
  12364. files. You can also configure Org to automatically upload your exported HTML
  12365. pages and related attachments, such as images and source code files, to a web
  12366. server.
  12367. You can also use Org to convert files into PDF, or even combine HTML and PDF
  12368. conversion so that files are available in both formats on the server.
  12369. Publishing has been contributed to Org by David O'Toole.
  12370. @menu
  12371. * Configuration:: Defining projects
  12372. * Uploading files:: How to get files up on the server
  12373. * Sample configuration:: Example projects
  12374. * Triggering publication:: Publication commands
  12375. @end menu
  12376. @node Configuration
  12377. @section Configuration
  12378. Publishing needs significant configuration to specify files, destination
  12379. and many other properties of a project.
  12380. @menu
  12381. * Project alist:: The central configuration variable
  12382. * Sources and destinations:: From here to there
  12383. * Selecting files:: What files are part of the project?
  12384. * Publishing action:: Setting the function doing the publishing
  12385. * Publishing options:: Tweaking HTML/@LaTeX{} export
  12386. * Publishing links:: Which links keep working after publishing?
  12387. * Sitemap:: Generating a list of all pages
  12388. * Generating an index:: An index that reaches across pages
  12389. @end menu
  12390. @node Project alist
  12391. @subsection The variable @code{org-publish-project-alist}
  12392. @cindex org-publish-project-alist
  12393. @cindex projects, for publishing
  12394. @vindex org-publish-project-alist
  12395. Publishing is configured almost entirely through setting the value of one
  12396. variable, called @code{org-publish-project-alist}. Each element of the list
  12397. configures one project, and may be in one of the two following forms:
  12398. @lisp
  12399. ("project-name" :property value :property value ...)
  12400. @r{i.e., a well-formed property list with alternating keys and values}
  12401. @r{or}
  12402. ("project-name" :components ("project-name" "project-name" ...))
  12403. @end lisp
  12404. In both cases, projects are configured by specifying property values. A
  12405. project defines the set of files that will be published, as well as the
  12406. publishing configuration to use when publishing those files. When a project
  12407. takes the second form listed above, the individual members of the
  12408. @code{:components} property are taken to be sub-projects, which group
  12409. together files requiring different publishing options. When you publish such
  12410. a ``meta-project'', all the components will also be published, in the
  12411. sequence given.
  12412. @node Sources and destinations
  12413. @subsection Sources and destinations for files
  12414. @cindex directories, for publishing
  12415. Most properties are optional, but some should always be set. In
  12416. particular, Org needs to know where to look for source files,
  12417. and where to put published files.
  12418. @multitable @columnfractions 0.3 0.7
  12419. @item @code{:base-directory}
  12420. @tab Directory containing publishing source files
  12421. @item @code{:publishing-directory}
  12422. @tab Directory where output files will be published. You can directly
  12423. publish to a web server using a file name syntax appropriate for
  12424. the Emacs @file{tramp} package. Or you can publish to a local directory and
  12425. use external tools to upload your website (@pxref{Uploading files}).
  12426. @item @code{:preparation-function}
  12427. @tab Function or list of functions to be called before starting the
  12428. publishing process, for example, to run @code{make} for updating files to be
  12429. published. Each preparation function is called with a single argument, the
  12430. project property list.
  12431. @item @code{:completion-function}
  12432. @tab Function or list of functions called after finishing the publishing
  12433. process, for example, to change permissions of the resulting files. Each
  12434. completion function is called with a single argument, the project property
  12435. list.
  12436. @end multitable
  12437. @noindent
  12438. @node Selecting files
  12439. @subsection Selecting files
  12440. @cindex files, selecting for publishing
  12441. By default, all files with extension @file{.org} in the base directory
  12442. are considered part of the project. This can be modified by setting the
  12443. properties
  12444. @multitable @columnfractions 0.25 0.75
  12445. @item @code{:base-extension}
  12446. @tab Extension (without the dot!) of source files. This actually is a
  12447. regular expression. Set this to the symbol @code{any} if you want to get all
  12448. files in @code{:base-directory}, even without extension.
  12449. @item @code{:exclude}
  12450. @tab Regular expression to match file names that should not be
  12451. published, even though they have been selected on the basis of their
  12452. extension.
  12453. @item @code{:include}
  12454. @tab List of files to be included regardless of @code{:base-extension}
  12455. and @code{:exclude}.
  12456. @item @code{:recursive}
  12457. @tab non-@code{nil} means, check base-directory recursively for files to publish.
  12458. @end multitable
  12459. @node Publishing action
  12460. @subsection Publishing action
  12461. @cindex action, for publishing
  12462. Publishing means that a file is copied to the destination directory and
  12463. possibly transformed in the process. The default transformation is to export
  12464. Org files as HTML files, and this is done by the function
  12465. @code{org-html-publish-to-html}, which calls the HTML exporter (@pxref{HTML
  12466. export}). But you also can publish your content as PDF files using
  12467. @code{org-latex-publish-to-pdf} or as @code{ascii}, @code{Texinfo}, etc.,
  12468. using the corresponding functions.
  12469. If you want to publish the Org file as an @code{.org} file but with the
  12470. @i{archived}, @i{commented} and @i{tag-excluded} trees removed, use the
  12471. function @code{org-org-publish-to-org}. This will produce @file{file.org}
  12472. and put it in the publishing directory. If you want a htmlized version of
  12473. this file, set the parameter @code{:htmlized-source} to @code{t}, it will
  12474. produce @file{file.org.html} in the publishing directory@footnote{If the
  12475. publishing directory is the same than the source directory, @file{file.org}
  12476. will be exported as @file{file.org.org}, so probably don't want to do this.}.
  12477. Other files like images only need to be copied to the publishing destination.
  12478. For this you can use @code{org-publish-attachment}. For non-org files, you
  12479. always need to specify the publishing function:
  12480. @multitable @columnfractions 0.3 0.7
  12481. @item @code{:publishing-function}
  12482. @tab Function executing the publication of a file. This may also be a
  12483. list of functions, which will all be called in turn.
  12484. @item @code{:htmlized-source}
  12485. @tab non-@code{nil} means, publish htmlized source.
  12486. @end multitable
  12487. The function must accept three arguments: a property list containing at least
  12488. a @code{:publishing-directory} property, the name of the file to be published
  12489. and the path to the publishing directory of the output file. It should take
  12490. the specified file, make the necessary transformation (if any) and place the
  12491. result into the destination folder.
  12492. @node Publishing options
  12493. @subsection Options for the exporters
  12494. @cindex options, for publishing
  12495. The property list can be used to set export options during the publishing
  12496. process. In most cases, these properties correspond to user variables in
  12497. Org. While some properties are available for all export back-ends, most of
  12498. them are back-end specific. The following sections list properties along
  12499. with the variable they belong to. See the documentation string of these
  12500. options for details.
  12501. @vindex org-publish-project-alist
  12502. When a property is given a value in @code{org-publish-project-alist}, its
  12503. setting overrides the value of the corresponding user variable (if any)
  12504. during publishing. Options set within a file (@pxref{Export settings}),
  12505. however, override everything.
  12506. @subsubheading Generic properties
  12507. @multitable {@code{:with-sub-superscript}} {@code{org-export-with-sub-superscripts}}
  12508. @item @code{:archived-trees} @tab @code{org-export-with-archived-trees}
  12509. @item @code{:exclude-tags} @tab @code{org-export-exclude-tags}
  12510. @item @code{:headline-levels} @tab @code{org-export-headline-levels}
  12511. @item @code{:language} @tab @code{org-export-default-language}
  12512. @item @code{:preserve-breaks} @tab @code{org-export-preserve-breaks}
  12513. @item @code{:section-numbers} @tab @code{org-export-with-section-numbers}
  12514. @item @code{:select-tags} @tab @code{org-export-select-tags}
  12515. @item @code{:with-author} @tab @code{org-export-with-author}
  12516. @item @code{:with-broken-links} @tab @code{org-export-with-broken-links}
  12517. @item @code{:with-clocks} @tab @code{org-export-with-clocks}
  12518. @item @code{:with-creator} @tab @code{org-export-with-creator}
  12519. @item @code{:with-date} @tab @code{org-export-with-date}
  12520. @item @code{:with-drawers} @tab @code{org-export-with-drawers}
  12521. @item @code{:with-email} @tab @code{org-export-with-email}
  12522. @item @code{:with-emphasize} @tab @code{org-export-with-emphasize}
  12523. @item @code{:with-fixed-width} @tab @code{org-export-with-fixed-width}
  12524. @item @code{:with-footnotes} @tab @code{org-export-with-footnotes}
  12525. @item @code{:with-latex} @tab @code{org-export-with-latex}
  12526. @item @code{:with-planning} @tab @code{org-export-with-planning}
  12527. @item @code{:with-priority} @tab @code{org-export-with-priority}
  12528. @item @code{:with-properties} @tab @code{org-export-with-properties}
  12529. @item @code{:with-special-strings} @tab @code{org-export-with-special-strings}
  12530. @item @code{:with-sub-superscript} @tab @code{org-export-with-sub-superscripts}
  12531. @item @code{:with-tables} @tab @code{org-export-with-tables}
  12532. @item @code{:with-tags} @tab @code{org-export-with-tags}
  12533. @item @code{:with-tasks} @tab @code{org-export-with-tasks}
  12534. @item @code{:with-timestamps} @tab @code{org-export-with-timestamps}
  12535. @item @code{:with-title} @tab @code{org-export-with-title}
  12536. @item @code{:with-toc} @tab @code{org-export-with-toc}
  12537. @item @code{:with-todo-keywords} @tab @code{org-export-with-todo-keywords}
  12538. @end multitable
  12539. @subsubheading ASCII specific properties
  12540. @multitable {@code{:ascii-table-keep-all-vertical-lines}} {@code{org-ascii-table-keep-all-vertical-lines}}
  12541. @item @code{:ascii-bullets} @tab @code{org-ascii-bullets}
  12542. @item @code{:ascii-caption-above} @tab @code{org-ascii-caption-above}
  12543. @item @code{:ascii-charset} @tab @code{org-ascii-charset}
  12544. @item @code{:ascii-global-margin} @tab @code{org-ascii-global-margin}
  12545. @item @code{:ascii-format-drawer-function} @tab @code{org-ascii-format-drawer-function}
  12546. @item @code{:ascii-format-inlinetask-function} @tab @code{org-ascii-format-inlinetask-function}
  12547. @item @code{:ascii-headline-spacing} @tab @code{org-ascii-headline-spacing}
  12548. @item @code{:ascii-indented-line-width} @tab @code{org-ascii-indented-line-width}
  12549. @item @code{:ascii-inlinetask-width} @tab @code{org-ascii-inlinetask-width}
  12550. @item @code{:ascii-inner-margin} @tab @code{org-ascii-inner-margin}
  12551. @item @code{:ascii-links-to-notes} @tab @code{org-ascii-links-to-notes}
  12552. @item @code{:ascii-list-margin} @tab @code{org-ascii-list-margin}
  12553. @item @code{:ascii-paragraph-spacing} @tab @code{org-ascii-paragraph-spacing}
  12554. @item @code{:ascii-quote-margin} @tab @code{org-ascii-quote-margin}
  12555. @item @code{:ascii-table-keep-all-vertical-lines} @tab @code{org-ascii-table-keep-all-vertical-lines}
  12556. @item @code{:ascii-table-use-ascii-art} @tab @code{org-ascii-table-use-ascii-art}
  12557. @item @code{:ascii-table-widen-columns} @tab @code{org-ascii-table-widen-columns}
  12558. @item @code{:ascii-text-width} @tab @code{org-ascii-text-width}
  12559. @item @code{:ascii-underline} @tab @code{org-ascii-underline}
  12560. @item @code{:ascii-verbatim-format} @tab @code{org-ascii-verbatim-format}
  12561. @end multitable
  12562. @subsubheading Beamer specific properties
  12563. @multitable {@code{:beamer-frame-default-options}} {@code{org-beamer-frame-default-options}}
  12564. @item @code{:beamer-theme} @tab @code{org-beamer-theme}
  12565. @item @code{:beamer-column-view-format} @tab @code{org-beamer-column-view-format}
  12566. @item @code{:beamer-environments-extra} @tab @code{org-beamer-environments-extra}
  12567. @item @code{:beamer-frame-default-options} @tab @code{org-beamer-frame-default-options}
  12568. @item @code{:beamer-outline-frame-options} @tab @code{org-beamer-outline-frame-options}
  12569. @item @code{:beamer-outline-frame-title} @tab @code{org-beamer-outline-frame-title}
  12570. @item @code{:beamer-subtitle-format} @tab @code{org-beamer-subtitle-format}
  12571. @end multitable
  12572. @subsubheading HTML specific properties
  12573. @multitable {@code{:html-table-use-header-tags-for-first-column}} {@code{org-html-table-use-header-tags-for-first-column}}
  12574. @item @code{:html-allow-name-attribute-in-anchors} @tab @code{org-html-allow-name-attribute-in-anchors}
  12575. @item @code{:html-checkbox-type} @tab @code{org-html-checkbox-type}
  12576. @item @code{:html-container} @tab @code{org-html-container-element}
  12577. @item @code{:html-divs} @tab @code{org-html-divs}
  12578. @item @code{:html-doctype} @tab @code{org-html-doctype}
  12579. @item @code{:html-extension} @tab @code{org-html-extension}
  12580. @item @code{:html-footnote-format} @tab @code{org-html-footnote-format}
  12581. @item @code{:html-footnote-separator} @tab @code{org-html-footnote-separator}
  12582. @item @code{:html-footnotes-section} @tab @code{org-html-footnotes-section}
  12583. @item @code{:html-format-drawer-function} @tab @code{org-html-format-drawer-function}
  12584. @item @code{:html-format-headline-function} @tab @code{org-html-format-headline-function}
  12585. @item @code{:html-format-inlinetask-function} @tab @code{org-html-format-inlinetask-function}
  12586. @item @code{:html-head-extra} @tab @code{org-html-head-extra}
  12587. @item @code{:html-head-include-default-style} @tab @code{org-html-head-include-default-style}
  12588. @item @code{:html-head-include-scripts} @tab @code{org-html-head-include-scripts}
  12589. @item @code{:html-head} @tab @code{org-html-head}
  12590. @item @code{:html-home/up-format} @tab @code{org-html-home/up-format}
  12591. @item @code{:html-html5-fancy} @tab @code{org-html-html5-fancy}
  12592. @item @code{:html-indent} @tab @code{org-html-indent}
  12593. @item @code{:html-infojs-options} @tab @code{org-html-infojs-options}
  12594. @item @code{:html-infojs-template} @tab @code{org-html-infojs-template}
  12595. @item @code{:html-inline-image-rules} @tab @code{org-html-inline-image-rules}
  12596. @item @code{:html-inline-images} @tab @code{org-html-inline-images}
  12597. @item @code{:html-link-home} @tab @code{org-html-link-home}
  12598. @item @code{:html-link-org-files-as-html} @tab @code{org-html-link-org-files-as-html}
  12599. @item @code{:html-link-up} @tab @code{org-html-link-up}
  12600. @item @code{:html-link-use-abs-url} @tab @code{org-html-link-use-abs-url}
  12601. @item @code{:html-mathjax-options} @tab @code{org-html-mathjax-options}
  12602. @item @code{:html-mathjax-template} @tab @code{org-html-mathjax-template}
  12603. @item @code{:html-metadata-timestamp-format} @tab @code{org-html-metadata-timestamp-format}
  12604. @item @code{:html-postamble-format} @tab @code{org-html-postamble-format}
  12605. @item @code{:html-postamble} @tab @code{org-html-postamble}
  12606. @item @code{:html-preamble-format} @tab @code{org-html-preamble-format}
  12607. @item @code{:html-preamble} @tab @code{org-html-preamble}
  12608. @item @code{:html-table-align-individual-fields} @tab @code{org-html-table-align-individual-fields}
  12609. @item @code{:html-table-attributes} @tab @code{org-html-table-default-attributes}
  12610. @item @code{:html-table-caption-above} @tab @code{org-html-table-caption-above}
  12611. @item @code{:html-table-data-tags} @tab @code{org-html-table-data-tags}
  12612. @item @code{:html-table-header-tags} @tab @code{org-html-table-header-tags}
  12613. @item @code{:html-table-row-tags} @tab @code{org-html-table-row-tags}
  12614. @item @code{:html-table-use-header-tags-for-first-column} @tab @code{org-html-table-use-header-tags-for-first-column}
  12615. @item @code{:html-tag-class-prefix} @tab @code{org-html-tag-class-prefix}
  12616. @item @code{:html-text-markup-alist} @tab @code{org-html-text-markup-alist}
  12617. @item @code{:html-todo-kwd-class-prefix} @tab @code{org-html-todo-kwd-class-prefix}
  12618. @item @code{:html-toplevel-hlevel} @tab @code{org-html-toplevel-hlevel}
  12619. @item @code{:html-use-infojs} @tab @code{org-html-use-infojs}
  12620. @item @code{:html-validation-link} @tab @code{org-html-validation-link}
  12621. @item @code{:html-viewport} @tab @code{org-html-viewport}
  12622. @item @code{:html-xml-declaration} @tab @code{org-html-xml-declaration}
  12623. @end multitable
  12624. @subsubheading @LaTeX{} specific properties
  12625. @multitable {@code{:latex-link-with-unknown-path-format}} {@code{org-latex-link-with-unknown-path-format}}
  12626. @item @code{:latex-active-timestamp-format} @tab @code{org-latex-active-timestamp-format}
  12627. @item @code{:latex-caption-above} @tab @code{org-latex-caption-above}
  12628. @item @code{:latex-classes} @tab @code{org-latex-classes}
  12629. @item @code{:latex-class} @tab @code{org-latex-default-class}
  12630. @item @code{:latex-compiler} @tab @code{org-latex-compiler}
  12631. @item @code{:latex-default-figure-position} @tab @code{org-latex-default-figure-position}
  12632. @item @code{:latex-default-table-environment} @tab @code{org-latex-default-table-environment}
  12633. @item @code{:latex-default-table-mode} @tab @code{org-latex-default-table-mode}
  12634. @item @code{:latex-diary-timestamp-format} @tab @code{org-latex-diary-timestamp-format}
  12635. @item @code{:latex-footnote-defined-format} @tab @code{org-latex-footnote-defined-format}
  12636. @item @code{:latex-footnote-separator} @tab @code{org-latex-footnote-separator}
  12637. @item @code{:latex-format-drawer-function} @tab @code{org-latex-format-drawer-function}
  12638. @item @code{:latex-format-headline-function} @tab @code{org-latex-format-headline-function}
  12639. @item @code{:latex-format-inlinetask-function} @tab @code{org-latex-format-inlinetask-function}
  12640. @item @code{:latex-hyperref-template} @tab @code{org-latex-hyperref-template}
  12641. @item @code{:latex-image-default-height} @tab @code{org-latex-image-default-height}
  12642. @item @code{:latex-image-default-option} @tab @code{org-latex-image-default-option}
  12643. @item @code{:latex-image-default-width} @tab @code{org-latex-image-default-width}
  12644. @item @code{:latex-images-centered} @tab @code{org-latex-images-centered}
  12645. @item @code{:latex-inactive-timestamp-format} @tab @code{org-latex-inactive-timestamp-format}
  12646. @item @code{:latex-inline-image-rules} @tab @code{org-latex-inline-image-rules}
  12647. @item @code{:latex-link-with-unknown-path-format} @tab @code{org-latex-link-with-unknown-path-format}
  12648. @item @code{:latex-listings-langs} @tab @code{org-latex-listings-langs}
  12649. @item @code{:latex-listings-options} @tab @code{org-latex-listings-options}
  12650. @item @code{:latex-listings} @tab @code{org-latex-listings}
  12651. @item @code{:latex-minted-langs} @tab @code{org-latex-minted-langs}
  12652. @item @code{:latex-minted-options} @tab @code{org-latex-minted-options}
  12653. @item @code{:latex-prefer-user-labels} @tab @code{org-latex-prefer-user-labels}
  12654. @item @code{:latex-subtitle-format} @tab @code{org-latex-subtitle-format}
  12655. @item @code{:latex-subtitle-separate} @tab @code{org-latex-subtitle-separate}
  12656. @item @code{:latex-table-scientific-notation} @tab @code{org-latex-table-scientific-notation}
  12657. @item @code{:latex-tables-booktabs} @tab @code{org-latex-tables-booktabs}
  12658. @item @code{:latex-tables-centered} @tab @code{org-latex-tables-centered}
  12659. @item @code{:latex-text-markup-alist} @tab @code{org-latex-text-markup-alist}
  12660. @item @code{:latex-title-command} @tab @code{org-latex-title-command}
  12661. @item @code{:latex-toc-command} @tab @code{org-latex-toc-command}
  12662. @end multitable
  12663. @subsubheading Markdown specific properties
  12664. @multitable {@code{:md-footnotes-section}} {@code{org-md-footnotes-section}}
  12665. @item @code{:md-footnote-format} @tab @code{org-md-footnote-format}
  12666. @item @code{:md-footnotes-section} @tab @code{org-md-footnotes-section}
  12667. @item @code{:md-headline-style} @tab @code{org-md-headline-style}
  12668. @end multitable
  12669. @subsubheading ODT specific properties
  12670. @multitable {@code{:odt-format-inlinetask-function}} {@code{org-odt-format-inlinetask-function}}
  12671. @item @code{:odt-content-template-file} @tab @code{org-odt-content-template-file}
  12672. @item @code{:odt-display-outline-level} @tab @code{org-odt-display-outline-level}
  12673. @item @code{:odt-fontify-srcblocks} @tab @code{org-odt-fontify-srcblocks}
  12674. @item @code{:odt-format-drawer-function} @tab @code{org-odt-format-drawer-function}
  12675. @item @code{:odt-format-headline-function} @tab @code{org-odt-format-headline-function}
  12676. @item @code{:odt-format-inlinetask-function} @tab @code{org-odt-format-inlinetask-function}
  12677. @item @code{:odt-inline-formula-rules} @tab @code{org-odt-inline-formula-rules}
  12678. @item @code{:odt-inline-image-rules} @tab @code{org-odt-inline-image-rules}
  12679. @item @code{:odt-pixels-per-inch} @tab @code{org-odt-pixels-per-inch}
  12680. @item @code{:odt-styles-file} @tab @code{org-odt-styles-file}
  12681. @item @code{:odt-table-styles} @tab @code{org-odt-table-styles}
  12682. @item @code{:odt-use-date-fields} @tab @code{org-odt-use-date-fields}
  12683. @end multitable
  12684. @subsubheading Texinfo specific properties
  12685. @multitable {@code{:texinfo-link-with-unknown-path-format}} {@code{org-texinfo-link-with-unknown-path-format}}
  12686. @item @code{:texinfo-active-timestamp-format} @tab @code{org-texinfo-active-timestamp-format}
  12687. @item @code{:texinfo-classes} @tab @code{org-texinfo-classes}
  12688. @item @code{:texinfo-class} @tab @code{org-texinfo-default-class}
  12689. @item @code{:texinfo-table-default-markup} @tab @code{org-texinfo-table-default-markup}
  12690. @item @code{:texinfo-diary-timestamp-format} @tab @code{org-texinfo-diary-timestamp-format}
  12691. @item @code{:texinfo-filename} @tab @code{org-texinfo-filename}
  12692. @item @code{:texinfo-format-drawer-function} @tab @code{org-texinfo-format-drawer-function}
  12693. @item @code{:texinfo-format-headline-function} @tab @code{org-texinfo-format-headline-function}
  12694. @item @code{:texinfo-format-inlinetask-function} @tab @code{org-texinfo-format-inlinetask-function}
  12695. @item @code{:texinfo-inactive-timestamp-format} @tab @code{org-texinfo-inactive-timestamp-format}
  12696. @item @code{:texinfo-link-with-unknown-path-format} @tab @code{org-texinfo-link-with-unknown-path-format}
  12697. @item @code{:texinfo-node-description-column} @tab @code{org-texinfo-node-description-column}
  12698. @item @code{:texinfo-table-scientific-notation} @tab @code{org-texinfo-table-scientific-notation}
  12699. @item @code{:texinfo-tables-verbatim} @tab @code{org-texinfo-tables-verbatim}
  12700. @item @code{:texinfo-text-markup-alist} @tab @code{org-texinfo-text-markup-alist}
  12701. @end multitable
  12702. @node Publishing links
  12703. @subsection Links between published files
  12704. @cindex links, publishing
  12705. To create a link from one Org file to another, you would use something like
  12706. @samp{[[file:foo.org][The foo]]} or simply @samp{file:foo.org}
  12707. (@pxref{External links}). When published, this link becomes a link to
  12708. @file{foo.html}. You can thus interlink the pages of your ``org web''
  12709. project and the links will work as expected when you publish them to HTML.
  12710. If you also publish the Org source file and want to link to it, use an
  12711. @code{http:} link instead of a @code{file:} link, because @code{file:} links
  12712. are converted to link to the corresponding @file{html} file.
  12713. You may also link to related files, such as images. Provided you are careful
  12714. with relative file names, and provided you have also configured Org to upload
  12715. the related files, these links will work too. See @ref{Complex example}, for
  12716. an example of this usage.
  12717. Eventually, links between published documents can contain some search options
  12718. (@pxref{Search options}), which will be resolved to the appropriate location
  12719. in the linked file. For example, once published to HTML, the following links
  12720. all point to a dedicated anchor in @file{foo.html}.
  12721. @example
  12722. [[file:foo.org::*heading]]
  12723. [[file:foo.org::#custom-id]]
  12724. [[file:foo.org::target]]
  12725. @end example
  12726. @node Sitemap
  12727. @subsection Generating a sitemap
  12728. @cindex sitemap, of published pages
  12729. The following properties may be used to control publishing of
  12730. a map of files for a given project.
  12731. @multitable @columnfractions 0.35 0.65
  12732. @item @code{:auto-sitemap}
  12733. @tab When non-@code{nil}, publish a sitemap during @code{org-publish-current-project}
  12734. or @code{org-publish-all}.
  12735. @item @code{:sitemap-filename}
  12736. @tab Filename for output of sitemap. Defaults to @file{sitemap.org} (which
  12737. becomes @file{sitemap.html}).
  12738. @item @code{:sitemap-title}
  12739. @tab Title of sitemap page. Defaults to name of file.
  12740. @item @code{:sitemap-format-entry}
  12741. @tab With this option one can tell how a site-map entry is formatted in the
  12742. site-map. It is a function called with three arguments: the file or
  12743. directory name relative to base directory of the project, the site-map style
  12744. and the current project. It is expected to return a string. Default value
  12745. turns file names into links and use document titles as descriptions. For
  12746. specific formatting needs, one can use @code{org-publish-find-date},
  12747. @code{org-publish-find-title} and @code{org-publish-find-property}, to
  12748. retrieve additional information about published documents.
  12749. @item @code{:sitemap-function}
  12750. @tab Plug-in function to use for generation of the sitemap. It is called
  12751. with two arguments: the title of the site-map and a representation of the
  12752. files and directories involved in the project as a radio list (@pxref{Radio
  12753. lists}). The latter can further be transformed using
  12754. @code{org-list-to-generic}, @code{org-list-to-subtree} and alike. Default
  12755. value generates a plain list of links to all files in the project.
  12756. @item @code{:sitemap-sort-folders}
  12757. @tab Where folders should appear in the sitemap. Set this to @code{first}
  12758. (default) or @code{last} to display folders first or last, respectively.
  12759. When set to @code{ignore}, folders are ignored altogether. Any other value
  12760. will mix files and folders. This variable has no effect when site-map style
  12761. is @code{tree}.
  12762. @item @code{:sitemap-sort-files}
  12763. @tab How the files are sorted in the site map. Set this to
  12764. @code{alphabetically} (default), @code{chronologically} or
  12765. @code{anti-chronologically}. @code{chronologically} sorts the files with
  12766. older date first while @code{anti-chronologically} sorts the files with newer
  12767. date first. @code{alphabetically} sorts the files alphabetically. The date of
  12768. a file is retrieved with @code{org-publish-find-date}.
  12769. @item @code{:sitemap-ignore-case}
  12770. @tab Should sorting be case-sensitive? Default @code{nil}.
  12771. @item @code{:sitemap-date-format}
  12772. @tab Format string for the @code{format-time-string} function that tells how
  12773. a sitemap entry's date is to be formatted. This property bypasses
  12774. @code{org-publish-sitemap-date-format} which defaults to @code{%Y-%m-%d}.
  12775. @end multitable
  12776. @node Generating an index
  12777. @subsection Generating an index
  12778. @cindex index, in a publishing project
  12779. Org mode can generate an index across the files of a publishing project.
  12780. @multitable @columnfractions 0.25 0.75
  12781. @item @code{:makeindex}
  12782. @tab When non-@code{nil}, generate in index in the file @file{theindex.org} and
  12783. publish it as @file{theindex.html}.
  12784. @end multitable
  12785. The file will be created when first publishing a project with the
  12786. @code{:makeindex} set. The file only contains a statement @code{#+INCLUDE:
  12787. "theindex.inc"}. You can then build around this include statement by adding
  12788. a title, style information, etc.
  12789. @cindex #+INDEX
  12790. Index entries are specified with @code{#+INDEX} keyword. An entry that
  12791. contains an exclamation mark will create a sub item.
  12792. @example
  12793. * Curriculum Vitae
  12794. #+INDEX: CV
  12795. #+INDEX: Application!CV
  12796. @end example
  12797. @node Uploading files
  12798. @section Uploading files
  12799. @cindex rsync
  12800. @cindex unison
  12801. For those people already utilizing third party sync tools such as
  12802. @command{rsync} or @command{unison}, it might be preferable not to use the built in
  12803. @i{remote} publishing facilities of Org mode which rely heavily on
  12804. Tramp. Tramp, while very useful and powerful, tends not to be
  12805. so efficient for multiple file transfer and has been known to cause problems
  12806. under heavy usage.
  12807. Specialized synchronization utilities offer several advantages. In addition
  12808. to timestamp comparison, they also do content and permissions/attribute
  12809. checks. For this reason you might prefer to publish your web to a local
  12810. directory (possibly even @i{in place} with your Org files) and then use
  12811. @file{unison} or @file{rsync} to do the synchronization with the remote host.
  12812. Since Unison (for example) can be configured as to which files to transfer to
  12813. a certain remote destination, it can greatly simplify the project publishing
  12814. definition. Simply keep all files in the correct location, process your Org
  12815. files with @code{org-publish} and let the synchronization tool do the rest.
  12816. You do not need, in this scenario, to include attachments such as @file{jpg},
  12817. @file{css} or @file{gif} files in the project definition since the 3rd party
  12818. tool syncs them.
  12819. Publishing to a local directory is also much faster than to a remote one, so
  12820. that you can afford more easily to republish entire projects. If you set
  12821. @code{org-publish-use-timestamps-flag} to @code{nil}, you gain the main
  12822. benefit of re-including any changed external files such as source example
  12823. files you might include with @code{#+INCLUDE:}. The timestamp mechanism in
  12824. Org is not smart enough to detect if included files have been modified.
  12825. @node Sample configuration
  12826. @section Sample configuration
  12827. Below we provide two example configurations. The first one is a simple
  12828. project publishing only a set of Org files. The second example is
  12829. more complex, with a multi-component project.
  12830. @menu
  12831. * Simple example:: One-component publishing
  12832. * Complex example:: A multi-component publishing example
  12833. @end menu
  12834. @node Simple example
  12835. @subsection Example: simple publishing configuration
  12836. This example publishes a set of Org files to the @file{public_html}
  12837. directory on the local machine.
  12838. @lisp
  12839. (setq org-publish-project-alist
  12840. '(("org"
  12841. :base-directory "~/org/"
  12842. :publishing-directory "~/public_html"
  12843. :section-numbers nil
  12844. :with-toc nil
  12845. :html-head "<link rel=\"stylesheet\"
  12846. href=\"../other/mystyle.css\"
  12847. type=\"text/css\"/>")))
  12848. @end lisp
  12849. @node Complex example
  12850. @subsection Example: complex publishing configuration
  12851. This more complicated example publishes an entire website, including
  12852. Org files converted to HTML, image files, Emacs Lisp source code, and
  12853. style sheets. The publishing directory is remote and private files are
  12854. excluded.
  12855. To ensure that links are preserved, care should be taken to replicate
  12856. your directory structure on the web server, and to use relative file
  12857. paths. For example, if your Org files are kept in @file{~/org} and your
  12858. publishable images in @file{~/images}, you would link to an image with
  12859. @c
  12860. @example
  12861. file:../images/myimage.png
  12862. @end example
  12863. @c
  12864. On the web server, the relative path to the image should be the
  12865. same. You can accomplish this by setting up an "images" folder in the
  12866. right place on the web server, and publishing images to it.
  12867. @lisp
  12868. (setq org-publish-project-alist
  12869. '(("orgfiles"
  12870. :base-directory "~/org/"
  12871. :base-extension "org"
  12872. :publishing-directory "/ssh:user@@host:~/html/notebook/"
  12873. :publishing-function org-html-publish-to-html
  12874. :exclude "PrivatePage.org" ;; regexp
  12875. :headline-levels 3
  12876. :section-numbers nil
  12877. :with-toc nil
  12878. :html-head "<link rel=\"stylesheet\"
  12879. href=\"../other/mystyle.css\" type=\"text/css\"/>"
  12880. :html-preamble t)
  12881. ("images"
  12882. :base-directory "~/images/"
  12883. :base-extension "jpg\\|gif\\|png"
  12884. :publishing-directory "/ssh:user@@host:~/html/images/"
  12885. :publishing-function org-publish-attachment)
  12886. ("other"
  12887. :base-directory "~/other/"
  12888. :base-extension "css\\|el"
  12889. :publishing-directory "/ssh:user@@host:~/html/other/"
  12890. :publishing-function org-publish-attachment)
  12891. ("website" :components ("orgfiles" "images" "other"))))
  12892. @end lisp
  12893. @node Triggering publication
  12894. @section Triggering publication
  12895. Once properly configured, Org can publish with the following commands:
  12896. @table @kbd
  12897. @orgcmd{C-c C-e P x,org-publish}
  12898. Prompt for a specific project and publish all files that belong to it.
  12899. @orgcmd{C-c C-e P p,org-publish-current-project}
  12900. Publish the project containing the current file.
  12901. @orgcmd{C-c C-e P f,org-publish-current-file}
  12902. Publish only the current file.
  12903. @orgcmd{C-c C-e P a,org-publish-all}
  12904. Publish every project.
  12905. @end table
  12906. @vindex org-publish-use-timestamps-flag
  12907. Org uses timestamps to track when a file has changed. The above functions
  12908. normally only publish changed files. You can override this and force
  12909. publishing of all files by giving a prefix argument to any of the commands
  12910. above, or by customizing the variable @code{org-publish-use-timestamps-flag}.
  12911. This may be necessary in particular if files include other files via
  12912. @code{#+SETUPFILE:} or @code{#+INCLUDE:}.
  12913. @node Working with source code
  12914. @chapter Working with source code
  12915. @cindex Schulte, Eric
  12916. @cindex Davison, Dan
  12917. @cindex source code, working with
  12918. Source code here refers to any code typed in Org mode documents. Org can
  12919. manage source code in any Org file once such code is tagged with begin and
  12920. end markers. Working with source code begins with tagging source code
  12921. blocks. Tagged @samp{src} code blocks are not restricted to the preamble or
  12922. the end of an Org document; they can go anywhere---with a few exceptions,
  12923. such as not inside comments and fixed width areas. Here's a sample
  12924. @samp{src} code block in emacs-lisp:
  12925. @example
  12926. #+BEGIN_SRC emacs-lisp
  12927. (defun org-xor (a b)
  12928. "Exclusive or."
  12929. (if a (not b) b))
  12930. #+END_SRC
  12931. @end example
  12932. Org can take the code in the block between the @samp{#+BEGIN_SRC} and
  12933. @samp{#+END_SRC} tags, and format, compile, execute, and show the results.
  12934. Org can simplify many housekeeping tasks essential to modern code
  12935. maintenance. That's why these blocks in Org mode literature are sometimes
  12936. referred to as @samp{live code} blocks (as compared to the static text and
  12937. documentation around it). Users can control how @samp{live} they want each
  12938. block by tweaking the headers for compiling, execution, extraction.
  12939. Org's @samp{src} code block type is one of many block types, such as quote,
  12940. export, verse, latex, example, and verbatim. This section pertains to
  12941. @samp{src} code blocks between @samp{#+BEGIN_SRC} and @samp{#+END_SRC}
  12942. For editing @samp{src} code blocks, Org provides native Emacs major-modes.
  12943. That leverages the latest Emacs features for that source code language mode.
  12944. For exporting, Org can then extract @samp{src} code blocks into compilable
  12945. source files (in a conversion process known as @dfn{tangling} in literate
  12946. programming terminology).
  12947. For publishing, Org's back-ends can handle the @samp{src} code blocks and the
  12948. text for output to a variety of formats with native syntax highlighting.
  12949. For executing the source code in the @samp{src} code blocks, Org provides
  12950. facilities that glue the tasks of compiling, collecting the results of the
  12951. execution, and inserting them back to the Org file. Besides text output,
  12952. results may include links to other data types that Emacs can handle: audio,
  12953. video, and graphics.
  12954. An important feature of Org's execution of the @samp{src} code blocks is
  12955. passing variables, functions, and results between @samp{src} blocks. Such
  12956. interoperability uses a common syntax even if these @samp{src} blocks are in
  12957. different source code languages. The integration extends to linking the
  12958. debugger's error messages to the line in the @samp{src} code block in the Org
  12959. file. That should partly explain why this functionality by the original
  12960. contributors, Eric Schulte and Dan Davison, was called @samp{Org Babel}.
  12961. In literate programming, the main appeal is code and documentation
  12962. co-existing in one file. Org mode takes this several steps further. First
  12963. by enabling execution, and then by inserting results of that execution back
  12964. into the Org file. Along the way, Org provides extensive formatting
  12965. features, including handling tables. Org handles multiple source code
  12966. languages in one file, and provides a common syntax for passing variables,
  12967. functions, and results between @samp{src} code blocks.
  12968. Org mode fulfills the promise of easy verification and maintenance of
  12969. publishing reproducible research by keeping all these in the same file: text,
  12970. data, code, configuration settings of the execution environment, the results
  12971. of the execution, and associated narratives, claims, references, and internal
  12972. and external links.
  12973. Details of Org's facilities for working with source code are shown next.
  12974. @menu
  12975. * Structure of code blocks:: Code block syntax described
  12976. * Editing source code:: Language major-mode editing
  12977. * Exporting code blocks:: Export contents and/or results
  12978. * Extracting source code:: Create pure source code files
  12979. * Evaluating code blocks:: Place results of evaluation in the Org mode buffer
  12980. * Library of Babel:: Use and contribute to a library of useful code blocks
  12981. * Languages:: List of supported code block languages
  12982. * Header arguments:: Configure code block functionality
  12983. * Results of evaluation:: How evaluation results are handled
  12984. * Noweb reference syntax:: Literate programming in Org mode
  12985. * Key bindings and useful functions:: Work quickly with code blocks
  12986. * Batch execution:: Call functions from the command line
  12987. @end menu
  12988. @node Structure of code blocks
  12989. @section Structure of code blocks
  12990. @cindex code block, structure
  12991. @cindex source code, block structure
  12992. @cindex #+NAME
  12993. @cindex #+BEGIN_SRC
  12994. Org offers two ways to structure source code in Org documents: in a
  12995. @samp{src} block, and directly inline. Both specifications are shown below.
  12996. A @samp{src} block conforms to this structure:
  12997. @example
  12998. #+NAME: <name>
  12999. #+BEGIN_SRC <language> <switches> <header arguments>
  13000. <body>
  13001. #+END_SRC
  13002. @end example
  13003. Org mode's templates system (@pxref{Easy templates}) speeds up creating
  13004. @samp{src} code blocks with just three keystrokes. Do not be put-off by
  13005. having to remember the source block syntax. Org also works with other
  13006. completion systems in Emacs, some of which predate Org and have custom
  13007. domain-specific languages for defining templates. Regular use of templates
  13008. reduces errors, increases accuracy, and maintains consistency.
  13009. @cindex source code, inline
  13010. An inline code block conforms to this structure:
  13011. @example
  13012. src_<language>@{<body>@}
  13013. @end example
  13014. or
  13015. @example
  13016. src_<language>[<header arguments>]@{<body>@}
  13017. @end example
  13018. @table @code
  13019. @item #+NAME: <name>
  13020. Optional. Names the @samp{src} block so it can be called, like a function,
  13021. from other @samp{src} blocks or inline blocks to evaluate or to capture the
  13022. results. Code from other blocks, other files, and from table formulas
  13023. (@pxref{The spreadsheet}) can use the name to reference a @samp{src} block.
  13024. This naming serves the same purpose as naming Org tables. Org mode requires
  13025. unique names. For duplicate names, Org mode's behavior is undefined.
  13026. @cindex #+NAME
  13027. @item #+BEGIN_SRC
  13028. @item #+END_SRC
  13029. Mandatory. They mark the start and end of a block that Org requires. The
  13030. @code{#+BEGIN_SRC} line takes additional arguments, as described next.
  13031. @cindex begin block, end block
  13032. @item <language>
  13033. Mandatory for live code blocks. It is the identifier of the source code
  13034. language in the block. @xref{Languages}, for identifiers of supported
  13035. languages.
  13036. @cindex source code, language
  13037. @item <switches>
  13038. Optional. Switches provide finer control of the code execution, export, and
  13039. format (see the discussion of switches in @ref{Literal examples})
  13040. @cindex source code, switches
  13041. @item <header arguments>
  13042. Optional. Heading arguments control many aspects of evaluation, export and
  13043. tangling of code blocks (@pxref{Header arguments}). Using Org's properties
  13044. feature, header arguments can be selectively applied to the entire buffer or
  13045. specific sub-trees of the Org document.
  13046. @item source code, header arguments
  13047. @item <body>
  13048. Source code in the dialect of the specified language identifier.
  13049. @end table
  13050. @node Editing source code
  13051. @section Editing source code
  13052. @cindex code block, editing
  13053. @cindex source code, editing
  13054. @vindex org-edit-src-auto-save-idle-delay
  13055. @vindex org-edit-src-turn-on-auto-save
  13056. @kindex C-c '
  13057. @kbd{C-c '} for editing the current code block. It opens a new major-mode
  13058. edit buffer containing the body of the @samp{src} code block, ready for any
  13059. edits. @kbd{C-c '} again to close the buffer and return to the Org buffer.
  13060. @key{C-x C-s} saves the buffer and updates the contents of the Org buffer.
  13061. Set @code{org-edit-src-auto-save-idle-delay} to save the base buffer after
  13062. a certain idle delay time.
  13063. Set @code{org-edit-src-turn-on-auto-save} to auto-save this buffer into a
  13064. separate file using @code{auto-save-mode}.
  13065. @kbd{C-c '} to close the major-mode buffer and return back to the Org buffer.
  13066. While editing the source code in the major-mode, the @code{org-src-mode}
  13067. minor mode remains active. It provides these customization variables as
  13068. described below. For even more variables, look in the customization
  13069. group @code{org-edit-structure}.
  13070. @table @code
  13071. @item org-src-lang-modes
  13072. If an Emacs major-mode named @code{<lang>-mode} exists, where @code{<lang>}
  13073. is the language identifier from code block's header line, then the edit
  13074. buffer uses that major-mode. Use this variable to arbitrarily map language
  13075. identifiers to major modes.
  13076. @item org-src-window-setup
  13077. For specifying Emacs window arrangement when the new edit buffer is created.
  13078. @item org-src-preserve-indentation
  13079. @cindex indentation, in source blocks
  13080. Default is @code{nil}. Source code is indented. This indentation applies
  13081. during export or tangling, and depending on the context, may alter leading
  13082. spaces and tabs. When non-@code{nil}, source code is aligned with the
  13083. leftmost column. No lines are modified during export or tangling, which is
  13084. very useful for white-space sensitive languages, such as Python.
  13085. @item org-src-ask-before-returning-to-edit-buffer
  13086. When @code{nil}, Org returns to the edit buffer without further prompts. The
  13087. default prompts for a confirmation.
  13088. @end table
  13089. Set @code{org-src-fontify-natively} to non-@code{nil} to turn on native code
  13090. fontification in the @emph{Org} buffer. Fontification of @samp{src} code
  13091. blocks can give visual separation of text and code on the display page. To
  13092. further customize the appearance of @code{org-block} for specific languages,
  13093. customize @code{org-src-block-faces}. The following example shades the
  13094. background of regular blocks, and colors source blocks only for Python and
  13095. Emacs-Lisp languages.
  13096. @lisp
  13097. (require 'color)
  13098. (set-face-attribute 'org-block nil :background
  13099. (color-darken-name
  13100. (face-attribute 'default :background) 3))
  13101. (setq org-src-block-faces '(("emacs-lisp" (:background "#EEE2FF"))
  13102. ("python" (:background "#E5FFB8"))))
  13103. @end lisp
  13104. @node Exporting code blocks
  13105. @section Exporting code blocks
  13106. @cindex code block, exporting
  13107. @cindex source code, exporting
  13108. Org can flexibly export just the @emph{code} from the code blocks, just the
  13109. @emph{results} of evaluation of the code block, @emph{both} the code and the
  13110. results of the code block evaluation, or @emph{none}. Org defaults to
  13111. exporting @emph{code} for most languages. For some languages, such as
  13112. @code{ditaa}, Org defaults to @emph{results}. To export just the body of
  13113. code blocks, @pxref{Literal examples}. To selectively export sub-trees of
  13114. an Org document, @pxref{Exporting}.
  13115. The @code{:exports} header arguments control exporting code blocks only and
  13116. not inline code:
  13117. @subsubheading Header arguments:
  13118. @table @code
  13119. @cindex @code{:exports}, src header argument
  13120. @item :exports code
  13121. This is the default for most languages where the body of the code block is
  13122. exported. See @ref{Literal examples} for more.
  13123. @item :exports results
  13124. On export, Org includes only the results and not the code block. After each
  13125. evaluation, Org inserts the results after the end of code block in the Org
  13126. buffer. By default, Org replaces any previous results. Org can also append
  13127. results.
  13128. @item :exports both
  13129. Org exports both the code block and the results.
  13130. @item :exports none
  13131. Org does not export the code block nor the results.
  13132. @end table
  13133. @vindex org-export-use-babel
  13134. To stop Org from evaluating code blocks to speed exports, use the header
  13135. argument @code{:eval never-export} (@pxref{eval}). To stop Org from
  13136. evaluating code blocks for greater security, set the
  13137. @code{org-export-use-babel} variable to @code{nil}, but understand that
  13138. header arguments will have no effect.
  13139. Turning off evaluation comes in handy when batch processing. For example,
  13140. markup languages for wikis, which have a high risk of untrusted code.
  13141. Stopping code block evaluation also stops evaluation of all header arguments
  13142. of the code block. This may not be desirable in some circumstances. So
  13143. during export, to allow evaluation of just the header arguments but not any
  13144. code evaluation in the source block, set @code{:eval never-export}
  13145. (@pxref{eval}).
  13146. Org never evaluates code blocks in commented sub-trees when exporting
  13147. (@pxref{Comment lines}). On the other hand, Org does evaluate code blocks in
  13148. sub-trees excluded from export (@pxref{Export settings}).
  13149. @node Extracting source code
  13150. @section Extracting source code
  13151. @cindex tangling
  13152. @cindex source code, extracting
  13153. @cindex code block, extracting source code
  13154. Extracting source code from code blocks is a basic task in literate
  13155. programming. Org has features to make this easy. In literate programming
  13156. parlance, documents on creation are @emph{woven} with code and documentation,
  13157. and on export, the code is @emph{tangled} for execution by a computer. Org
  13158. facilitates weaving and tangling for producing, maintaining, sharing, and
  13159. exporting literate programming documents. Org provides extensive
  13160. customization options for extracting source code.
  13161. When Org tangles @samp{src} code blocks, it expands, merges, and transforms
  13162. them. Then Org recomposes them into one or more separate files, as
  13163. configured through the options. During this @emph{tangling} process, Org
  13164. expands variables in the source code, and resolves any Noweb style references
  13165. (@pxref{Noweb reference syntax}).
  13166. @subsubheading Header arguments
  13167. @table @code
  13168. @cindex @code{:tangle}, src header argument
  13169. @item :tangle no
  13170. By default, Org does not tangle the @samp{src} code block on export.
  13171. @item :tangle yes
  13172. Org extracts the contents of the code block for the tangled output. By
  13173. default, the output file name is the same as the Org file but with a file
  13174. extension derived from the language identifier of the @samp{src} code block.
  13175. @item :tangle filename
  13176. Override the default file name with this one for the tangled output.
  13177. @end table
  13178. @kindex C-c C-v t
  13179. @subsubheading Functions
  13180. @table @code
  13181. @item org-babel-tangle
  13182. Tangle the current file. Bound to @kbd{C-c C-v t}.
  13183. With prefix argument only tangle the current @samp{src} code block.
  13184. @item org-babel-tangle-file
  13185. Choose a file to tangle. Bound to @kbd{C-c C-v f}.
  13186. @end table
  13187. @subsubheading Hooks
  13188. @table @code
  13189. @item org-babel-post-tangle-hook
  13190. This hook runs from within code tangled by @code{org-babel-tangle}, making it
  13191. suitable for post-processing, compilation, and evaluation of code in the
  13192. tangled files.
  13193. @end table
  13194. @subsubheading Jumping between code and Org
  13195. Debuggers normally link errors and messages back to the source code. But for
  13196. tangled files, we want to link back to the Org file, not to the tangled
  13197. source file. To make this extra jump, Org uses
  13198. @code{org-babel-tangle-jump-to-org} function with two additional source code
  13199. block header arguments: One, set @code{padline} (@pxref{padline}) to true
  13200. (the default setting). Two, set @code{comments} (@pxref{comments}) to
  13201. @code{link}, which makes Org insert links to the Org file.
  13202. @node Evaluating code blocks
  13203. @section Evaluating code blocks
  13204. @cindex code block, evaluating
  13205. @cindex source code, evaluating
  13206. @cindex #+RESULTS
  13207. A note about security: With code evaluation comes the risk of harm. Org
  13208. safeguards by prompting for user's permission before executing any code in
  13209. the source block. To customize this safeguard (or disable it) see @ref{Code
  13210. evaluation security}.
  13211. Org captures the results of the @samp{src} code block evaluation and inserts
  13212. them in the Org file, right after the @samp{src} code block. The insertion
  13213. point is after a newline and the @code{#+RESULTS} label. Org creates the
  13214. @code{#+RESULTS} label if one is not already there.
  13215. By default, Org enables only @code{emacs-lisp} @samp{src} code blocks for
  13216. execution. See @ref{Languages} for identifiers to enable other languages.
  13217. @kindex C-c C-c
  13218. Org provides many ways to execute @samp{src} code blocks. @kbd{C-c C-c} or
  13219. @kbd{C-c C-v e} with the point on a @samp{src} code block@footnote{The option
  13220. @code{org-babel-no-eval-on-ctrl-c-ctrl-c} can be used to remove code
  13221. evaluation from the @kbd{C-c C-c} key binding.} calls the
  13222. @code{org-babel-execute-src-block} function, which executes the code in the
  13223. block, collects the results, and inserts them in the buffer.
  13224. @cindex #+CALL
  13225. By calling a named code block@footnote{Actually, the constructs call_<name>()
  13226. and src_<lang>@{@} are not evaluated when they appear in a keyword line
  13227. (i.e. lines starting with @code{#+KEYWORD:}, @pxref{In-buffer settings}).}
  13228. from an Org mode buffer or a table. Org can call the named @samp{src} code
  13229. blocks from the current Org mode buffer or from the ``Library of Babel''
  13230. (@pxref{Library of Babel}). Whether inline syntax or the @code{#+CALL:}
  13231. syntax is used, the result is wrapped based on the variable
  13232. @code{org-babel-inline-result-wrap}, which by default is set to @code{"=%s="}
  13233. to produce verbatim text suitable for markup.
  13234. The syntax for @code{#+CALL:} is
  13235. @example
  13236. #+CALL: <name>(<arguments>)
  13237. #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>
  13238. @end example
  13239. The syntax for inline named code block is
  13240. @example
  13241. ... call_<name>(<arguments>) ...
  13242. ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...
  13243. @end example
  13244. @table @code
  13245. @item <name>
  13246. This is the name of the code block to be evaluated (@pxref{Structure of
  13247. code blocks}).
  13248. @item <arguments>
  13249. Org passes arguments to the code block using standard function call syntax.
  13250. For example, a @code{#+CALL:} line that passes @samp{4} to a code block named
  13251. @code{double}, which declares the header argument @code{:var n=2}, would be
  13252. written as @code{#+CALL: double(n=4)}. Note how this function call syntax is
  13253. different from the header argument syntax.
  13254. @item <inside header arguments>
  13255. Org passes inside header arguments to the named @samp{src} code block using
  13256. the header argument syntax. Inside header arguments apply to code block
  13257. evaluation. For example, @code{[:results output]} collects results printed
  13258. to @code{STDOUT} during code execution of that block. Note how this header
  13259. argument syntax is different from the function call syntax.
  13260. @item <end header arguments>
  13261. End header arguments affect the results returned by the code block. For
  13262. example, @code{:results html} wraps the results in a @code{BEGIN_EXPORT html}
  13263. block before inserting the results in the Org buffer.
  13264. For more examples of header arguments for @code{#+CALL:} lines,
  13265. @pxref{Arguments in function calls}.
  13266. @end table
  13267. @node Library of Babel
  13268. @section Library of Babel
  13269. @cindex babel, library of
  13270. @cindex source code, library
  13271. @cindex code block, library
  13272. The ``Library of Babel'' is a collection of code blocks. Like a function
  13273. library, these code blocks can be called from other Org files. A collection
  13274. of useful code blocks is available on
  13275. @uref{http://orgmode.org/worg/library-of-babel.html,Worg}. For remote code
  13276. block evaluation syntax, @pxref{Evaluating code blocks}.
  13277. @kindex C-c C-v i
  13278. For any user to add code to the library, first save the code in regular
  13279. @samp{src} code blocks of an Org file, and then load the Org file with
  13280. @code{org-babel-lob-ingest}, which is bound to @kbd{C-c C-v i}.
  13281. @node Languages
  13282. @section Languages
  13283. @cindex babel, languages
  13284. @cindex source code, languages
  13285. @cindex code block, languages
  13286. Org supports the following languages for the @samp{src} code blocks:
  13287. @multitable @columnfractions 0.25 0.25 0.25 0.25
  13288. @headitem @b{Language} @tab @b{Identifier} @tab @b{Language} @tab @b{Identifier}
  13289. @item Asymptote @tab asymptote @tab Awk @tab awk
  13290. @item C @tab C @tab C++ @tab C++
  13291. @item Clojure @tab clojure @tab CSS @tab css
  13292. @item D @tab d @tab ditaa @tab ditaa
  13293. @item Graphviz @tab dot @tab Emacs Calc @tab calc
  13294. @item Emacs Lisp @tab emacs-lisp @tab Fortran @tab fortran
  13295. @item gnuplot @tab gnuplot @tab Haskell @tab haskell
  13296. @item Java @tab java @tab Javascript @tab js
  13297. @item LaTeX @tab latex @tab Ledger @tab ledger
  13298. @item Lisp @tab lisp @tab Lilypond @tab lilypond
  13299. @item Lua @tab lua @tab MATLAB @tab matlab
  13300. @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml
  13301. @item Octave @tab octave @tab Org mode @tab org
  13302. @item Oz @tab oz @tab Perl @tab perl
  13303. @item Plantuml @tab plantuml @tab Processing.js @tab processing
  13304. @item Python @tab python @tab R @tab R
  13305. @item Ruby @tab ruby @tab Sass @tab sass
  13306. @item Scheme @tab scheme @tab GNU Screen @tab screen
  13307. @item Sed @tab sed @tab shell @tab sh
  13308. @item SQL @tab sql @tab SQLite @tab sqlite
  13309. @item Vala @tab vala
  13310. @end multitable
  13311. Additional documentation for some languages are at
  13312. @uref{http://orgmode.org/worg/org-contrib/babel/languages.html}.
  13313. @vindex org-babel-load-languages
  13314. By default, only @code{emacs-lisp} is enabled for evaluation. To enable or
  13315. disable other languages, customize the @code{org-babel-load-languages}
  13316. variable either through the Emacs customization interface, or by adding code
  13317. to the init file as shown next:
  13318. In this example, evaluation is disabled for @code{emacs-lisp}, and enabled
  13319. for @code{R}.
  13320. @lisp
  13321. (org-babel-do-load-languages
  13322. 'org-babel-load-languages
  13323. '((emacs-lisp . nil)
  13324. (R . t)))
  13325. @end lisp
  13326. Note that this is not the only way to enable a language. Org also enables
  13327. languages when loaded with @code{require} statement. For example, the
  13328. following enables execution of @code{clojure} code blocks:
  13329. @lisp
  13330. (require 'ob-clojure)
  13331. @end lisp
  13332. @node Header arguments
  13333. @section Header arguments
  13334. @cindex code block, header arguments
  13335. @cindex source code, block header arguments
  13336. Details of configuring header arguments are shown here.
  13337. @menu
  13338. * Using header arguments:: Different ways to set header arguments
  13339. * Specific header arguments:: List of header arguments
  13340. @end menu
  13341. @node Using header arguments
  13342. @subsection Using header arguments
  13343. Since header arguments can be set in several ways, Org prioritizes them in
  13344. case of overlaps or conflicts by giving local settings a higher priority.
  13345. Header values in function calls, for example, override header values from
  13346. global defaults.
  13347. @menu
  13348. * System-wide header arguments:: Set globally, language-specific
  13349. * Language-specific header arguments:: Set in the Org file's headers
  13350. * Header arguments in Org mode properties:: Set in the Org file
  13351. * Language-specific mode properties::
  13352. * Code block specific header arguments:: The most commonly used method
  13353. * Arguments in function calls:: The most specific level, takes highest priority
  13354. @end menu
  13355. @node System-wide header arguments
  13356. @subsubheading System-wide header arguments
  13357. @vindex org-babel-default-header-args
  13358. System-wide values of header arguments can be specified by adapting the
  13359. @code{org-babel-default-header-args} variable:
  13360. @cindex @code{:session}, src header argument
  13361. @cindex @code{:results}, src header argument
  13362. @cindex @code{:exports}, src header argument
  13363. @cindex @code{:cache}, src header argument
  13364. @cindex @code{:noweb}, src header argument
  13365. @example
  13366. :session => "none"
  13367. :results => "replace"
  13368. :exports => "code"
  13369. :cache => "no"
  13370. :noweb => "no"
  13371. @end example
  13372. This example sets @code{:noweb} header arguments to @code{yes}, which makes
  13373. Org expand @code{:noweb} references by default.
  13374. @lisp
  13375. (setq org-babel-default-header-args
  13376. (cons '(:noweb . "yes")
  13377. (assq-delete-all :noweb org-babel-default-header-args)))
  13378. @end lisp
  13379. @node Language-specific header arguments
  13380. @subsubheading Language-specific header arguments
  13381. Each language can have separate default header arguments by customizing the
  13382. variable @code{org-babel-default-header-args:<lang>}, where @code{<lang>} is
  13383. the name of the language. For details, see the language-specific online
  13384. documentation at @uref{http://orgmode.org/worg/org-contrib/babel}.
  13385. @node Header arguments in Org mode properties
  13386. @subsubheading Header arguments in Org mode properties
  13387. For header arguments applicable to the buffer, use @code{#+PROPERTY:} lines
  13388. anywhere in the Org mode file (@pxref{Property syntax}).
  13389. The following example sets only for @samp{R} code blocks to @code{session},
  13390. making all the @samp{R} code blocks execute in the same session. Setting
  13391. @code{results} to @code{silent} ignores the results of executions for all
  13392. blocks, not just @samp{R} code blocks; no results inserted for any block.
  13393. @example
  13394. #+PROPERTY: header-args:R :session *R*
  13395. #+PROPERTY: header-args :results silent
  13396. @end example
  13397. @vindex org-use-property-inheritance
  13398. Header arguments set through Org's property drawers (@pxref{Property syntax})
  13399. apply at the sub-tree level on down. Since these property drawers can appear
  13400. anywhere in the file hierarchy, Org uses outermost call or source block to
  13401. resolve the values. Org ignores @code{org-use-property-inheritance} setting.
  13402. In this example, @code{:cache} defaults to @code{yes} for all code blocks in
  13403. the sub-tree starting with @samp{sample header}.
  13404. @example
  13405. * sample header
  13406. :PROPERTIES:
  13407. :header-args: :cache yes
  13408. :END:
  13409. @end example
  13410. @kindex C-c C-x p
  13411. @vindex org-babel-default-header-args
  13412. Properties defined through @code{org-set-property} function, bound to
  13413. @kbd{C-c C-x p}, apply to all active languages. They override properties set
  13414. in @code{org-babel-default-header-args}.
  13415. @node Language-specific mode properties
  13416. @subsubheading Language-specific mode properties
  13417. Language-specific header arguments are also read from properties
  13418. @code{header-args:<lang>} where @code{<lang>} is the language identifier.
  13419. For example,
  13420. @example
  13421. * Heading
  13422. :PROPERTIES:
  13423. :header-args:clojure: :session *clojure-1*
  13424. :header-args:R: :session *R*
  13425. :END:
  13426. ** Subheading
  13427. :PROPERTIES:
  13428. :header-args:clojure: :session *clojure-2*
  13429. :END:
  13430. @end example
  13431. would force separate sessions for clojure blocks in Heading and Subheading,
  13432. but use the same session for all @samp{R} blocks. Blocks in Subheading
  13433. inherit settings from Heading.
  13434. @node Code block specific header arguments
  13435. @subsubheading Code block specific header arguments
  13436. Header arguments are most commonly set at the @samp{src} code block level, on
  13437. the @code{#+BEGIN_SRC} line. Arguments set at this level take precedence
  13438. over those set in the @code{org-babel-default-header-args} variable, and also
  13439. those set as header properties.
  13440. In the following example, setting @code{results} to @code{silent} makes it
  13441. ignore results of the code execution. Setting @code{:exports} to @code{code}
  13442. exports only the body of the @samp{src} code block to HTML or @LaTeX{}.:
  13443. @example
  13444. #+NAME: factorial
  13445. #+BEGIN_SRC haskell :results silent :exports code :var n=0
  13446. fac 0 = 1
  13447. fac n = n * fac (n-1)
  13448. #+END_SRC
  13449. @end example
  13450. The same header arguments in an inline @samp{src} code block:
  13451. @example
  13452. src_haskell[:exports both]@{fac 5@}
  13453. @end example
  13454. Code block header arguments can span multiple lines using @code{#+HEADER:} on
  13455. each line. Note that Org currently accepts the plural spelling of
  13456. @code{#+HEADER:} only as a convenience for backward-compatibility. It may be
  13457. removed at some point.
  13458. @cindex #+HEADER:
  13459. Multi-line header arguments on an unnamed @samp{src} code block:
  13460. @example
  13461. #+HEADER: :var data1=1
  13462. #+BEGIN_SRC emacs-lisp :var data2=2
  13463. (message "data1:%S, data2:%S" data1 data2)
  13464. #+END_SRC
  13465. #+RESULTS:
  13466. : data1:1, data2:2
  13467. @end example
  13468. Multi-line header arguments on a named @samp{src} code block:
  13469. @example
  13470. #+NAME: named-block
  13471. #+HEADER: :var data=2
  13472. #+BEGIN_SRC emacs-lisp
  13473. (message "data:%S" data)
  13474. #+END_SRC
  13475. #+RESULTS: named-block
  13476. : data:2
  13477. @end example
  13478. @node Arguments in function calls
  13479. @subsubheading Arguments in function calls
  13480. Header arguments in function calls are the most specific and override all
  13481. other settings in case of an overlap. They get the highest priority. Two
  13482. @code{#+CALL:} examples are shown below. For the complete syntax of
  13483. @code{#+CALL:} lines, see @ref{Evaluating code blocks}.
  13484. In this example, @code{:exports results} header argument is applied to the
  13485. evaluation of the @code{#+CALL:} line.
  13486. @example
  13487. #+CALL: factorial(n=5) :exports results
  13488. @end example
  13489. In this example, @code{:session special} header argument is applied to the
  13490. evaluation of @code{factorial} code block.
  13491. @example
  13492. #+CALL: factorial[:session special](n=5)
  13493. @end example
  13494. @node Specific header arguments
  13495. @subsection Specific header arguments
  13496. Org comes with many header arguments common to all languages. New header
  13497. arguments are added for specific languages as they become available for use
  13498. in @samp{src} code blocks. A header argument is specified with an initial
  13499. colon followed by the argument's name in lowercase. Common header arguments
  13500. are:
  13501. @menu
  13502. * var:: Pass arguments to @samp{src} code blocks
  13503. * results:: Specify results type; how to collect
  13504. * file:: Specify a path for output file
  13505. * file-desc:: Specify a description for file results
  13506. * file-ext:: Specify an extension for file output
  13507. * output-dir:: Specify a directory for output file
  13508. * dir:: Specify the default directory for code block execution
  13509. * exports:: Specify exporting code, results, both, none
  13510. * tangle:: Toggle tangling; or specify file name
  13511. * mkdirp:: Toggle for parent directory creation for target files during tangling
  13512. * comments:: Toggle insertion of comments in tangled code files
  13513. * padline:: Control insertion of padding lines in tangled code files
  13514. * no-expand:: Turn off variable assignment and noweb expansion during tangling
  13515. * session:: Preserve the state of code evaluation
  13516. * noweb:: Toggle expansion of noweb references
  13517. * noweb-ref:: Specify block's noweb reference resolution target
  13518. * noweb-sep:: String to separate noweb references
  13519. * cache:: Avoid re-evaluating unchanged code blocks
  13520. * sep:: Delimiter for writing tabular results outside Org
  13521. * hlines:: Handle horizontal lines in tables
  13522. * colnames:: Handle column names in tables
  13523. * rownames:: Handle row names in tables
  13524. * shebang:: Make tangled files executable
  13525. * tangle-mode:: Set permission of tangled files
  13526. * eval:: Limit evaluation of specific code blocks
  13527. * wrap:: Mark source block evaluation results
  13528. * post:: Post processing of results of code block evaluation
  13529. * prologue:: Text to prepend to body of code block
  13530. * epilogue:: Text to append to body of code block
  13531. @end menu
  13532. For language-specific header arguments, see @ref{Languages}.
  13533. @node var
  13534. @subsubsection @code{:var}
  13535. @cindex @code{:var}, src header argument
  13536. Use @code{:var} for passing arguments to @samp{src} code blocks. The
  13537. specifics of variables in @samp{src} code blocks vary by the source language
  13538. and are covered in the language-specific documentation. The syntax for
  13539. @code{:var}, however, is the same for all languages. This includes declaring
  13540. a variable, and assigning a default value.
  13541. Arguments can take values as literals, or as references, or even as Emacs
  13542. Lisp code (@pxref{var, Emacs Lisp evaluation of variables}). References are
  13543. names from the Org file from the lines @code{#+NAME:} or @code{#+RESULTS:}.
  13544. References can also refer to tables, lists, @code{#+BEGIN_EXAMPLE} blocks,
  13545. other types of @samp{src} code blocks, or the results of execution of
  13546. @samp{src} code blocks.
  13547. For better performance, Org can cache results of evaluations. But caching
  13548. comes with severe limitations (@pxref{cache}).
  13549. Argument values are indexed like arrays (@pxref{var, Indexable variable
  13550. values}).
  13551. The following syntax is used to pass arguments to @samp{src} code blocks
  13552. using the @code{:var} header argument.
  13553. @example
  13554. :var name=assign
  13555. @end example
  13556. The @code{assign} is a literal value, such as a string @samp{"string"}, a
  13557. number @samp{9}, a reference to a table, a list, a literal example, another
  13558. code block (with or without arguments), or the results from evaluating a code
  13559. block.
  13560. Here are examples of passing values by reference:
  13561. @table @dfn
  13562. @item table
  13563. an Org mode table named with either a @code{#+NAME:} line
  13564. @example
  13565. #+NAME: example-table
  13566. | 1 |
  13567. | 2 |
  13568. | 3 |
  13569. | 4 |
  13570. #+NAME: table-length
  13571. #+BEGIN_SRC emacs-lisp :var table=example-table
  13572. (length table)
  13573. #+END_SRC
  13574. #+RESULTS: table-length
  13575. : 4
  13576. @end example
  13577. @item list
  13578. a simple list named with a @code{#+NAME:} line. Note that only the top level
  13579. list items are passed along. Nested list items are ignored.
  13580. @example
  13581. #+NAME: example-list
  13582. - simple
  13583. - not
  13584. - nested
  13585. - list
  13586. #+BEGIN_SRC emacs-lisp :var x=example-list
  13587. (print x)
  13588. #+END_SRC
  13589. #+RESULTS:
  13590. | simple | list |
  13591. @end example
  13592. @item code block without arguments
  13593. a code block name (from the example above), as assigned by @code{#+NAME:},
  13594. optionally followed by parentheses
  13595. @example
  13596. #+BEGIN_SRC emacs-lisp :var length=table-length()
  13597. (* 2 length)
  13598. #+END_SRC
  13599. #+RESULTS:
  13600. : 8
  13601. @end example
  13602. @item code block with arguments
  13603. a @samp{src} code block name, as assigned by @code{#+NAME:}, followed by
  13604. parentheses and optional arguments passed within the parentheses following
  13605. the @samp{src} code block name using standard function call syntax
  13606. @example
  13607. #+NAME: double
  13608. #+BEGIN_SRC emacs-lisp :var input=8
  13609. (* 2 input)
  13610. #+END_SRC
  13611. #+RESULTS: double
  13612. : 16
  13613. #+NAME: squared
  13614. #+BEGIN_SRC emacs-lisp :var input=double(input=2)
  13615. (* input input)
  13616. #+END_SRC
  13617. #+RESULTS: squared
  13618. : 4
  13619. @end example
  13620. @item literal example
  13621. a literal example block named with a @code{#+NAME:} line
  13622. @example
  13623. #+NAME: literal-example
  13624. #+BEGIN_EXAMPLE
  13625. A literal example
  13626. on two lines
  13627. #+END_EXAMPLE
  13628. #+NAME: read-literal-example
  13629. #+BEGIN_SRC emacs-lisp :var x=literal-example
  13630. (concatenate 'string x " for you.")
  13631. #+END_SRC
  13632. #+RESULTS: read-literal-example
  13633. : A literal example
  13634. : on two lines for you.
  13635. @end example
  13636. @end table
  13637. @subsubheading Indexable variable values
  13638. Indexing variable values enables referencing portions of a variable. Indexes
  13639. are 0 based with negative values counting backwards from the end. If an
  13640. index is separated by @code{,}s then each subsequent section will index as
  13641. the next dimension. Note that this indexing occurs @emph{before} other
  13642. table-related header arguments are applied, such as @code{:hlines},
  13643. @code{:colnames} and @code{:rownames}. The following example assigns the
  13644. last cell of the first row the table @code{example-table} to the variable
  13645. @code{data}:
  13646. @example
  13647. #+NAME: example-table
  13648. | 1 | a |
  13649. | 2 | b |
  13650. | 3 | c |
  13651. | 4 | d |
  13652. #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
  13653. data
  13654. #+END_SRC
  13655. #+RESULTS:
  13656. : a
  13657. @end example
  13658. Ranges of variable values can be referenced using two integers separated by a
  13659. @code{:}, in which case the entire inclusive range is referenced. For
  13660. example the following assigns the middle three rows of @code{example-table}
  13661. to @code{data}.
  13662. @example
  13663. #+NAME: example-table
  13664. | 1 | a |
  13665. | 2 | b |
  13666. | 3 | c |
  13667. | 4 | d |
  13668. | 5 | 3 |
  13669. #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
  13670. data
  13671. #+END_SRC
  13672. #+RESULTS:
  13673. | 2 | b |
  13674. | 3 | c |
  13675. | 4 | d |
  13676. @end example
  13677. To pick the entire range, use an empty index, or the single character
  13678. @code{*}. @code{0:-1} does the same thing. Example below shows how to
  13679. reference the first column only.
  13680. @example
  13681. #+NAME: example-table
  13682. | 1 | a |
  13683. | 2 | b |
  13684. | 3 | c |
  13685. | 4 | d |
  13686. #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
  13687. data
  13688. #+END_SRC
  13689. #+RESULTS:
  13690. | 1 | 2 | 3 | 4 |
  13691. @end example
  13692. Index referencing can be used for tables and code blocks. Index referencing
  13693. can handle any number of dimensions. Commas delimit multiple dimensions, as
  13694. shown below.
  13695. @example
  13696. #+NAME: 3D
  13697. #+BEGIN_SRC emacs-lisp
  13698. '(((1 2 3) (4 5 6) (7 8 9))
  13699. ((10 11 12) (13 14 15) (16 17 18))
  13700. ((19 20 21) (22 23 24) (25 26 27)))
  13701. #+END_SRC
  13702. #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
  13703. data
  13704. #+END_SRC
  13705. #+RESULTS:
  13706. | 11 | 14 | 17 |
  13707. @end example
  13708. @subsubheading Emacs Lisp evaluation of variables
  13709. Emacs lisp code can set the values for variables. To differentiate a value
  13710. from lisp code, Org interprets any value starting with @code{(}, @code{[},
  13711. @code{'} or @code{`} as Emacs Lisp code. The result of evaluating that code
  13712. is then assigned to the value of that variable. The following example shows
  13713. how to reliably query and pass file name of the Org mode buffer to a code
  13714. block using headers. We need reliability here because the file's name could
  13715. change once the code in the block starts executing.
  13716. @example
  13717. #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
  13718. wc -w $filename
  13719. #+END_SRC
  13720. @end example
  13721. Note that values read from tables and lists will not be mistakenly evaluated
  13722. as Emacs Lisp code, as illustrated in the following example.
  13723. @example
  13724. #+NAME: table
  13725. | (a b c) |
  13726. #+HEADER: :var data=table[0,0]
  13727. #+BEGIN_SRC perl
  13728. $data
  13729. #+END_SRC
  13730. #+RESULTS:
  13731. : (a b c)
  13732. @end example
  13733. @node results
  13734. @subsubsection @code{:results}
  13735. @cindex @code{:results}, src header argument
  13736. There are four classes of @code{:results} header arguments. Each @samp{src}
  13737. code block can take only one option per class.
  13738. @itemize @bullet
  13739. @item
  13740. @b{collection} for how the results should be collected from the @samp{src}
  13741. code block
  13742. @item
  13743. @b{type} for which type of result the code block will return; affects how Org
  13744. processes and inserts results in the Org buffer
  13745. @item
  13746. @b{format} for the result; affects how Org processes and inserts results in
  13747. the Org buffer
  13748. @item
  13749. @b{handling} for processing results after evaluation of the @samp{src} code
  13750. block
  13751. @end itemize
  13752. @subsubheading Collection
  13753. Collection options specify the results. Choose one of the options; they are
  13754. mutually exclusive.
  13755. @itemize @bullet
  13756. @item @code{value}
  13757. Default. Functional mode. Result is the value returned by the last
  13758. statement in the @samp{src} code block. Languages like Python may require an
  13759. explicit @code{return} statement in the @samp{src} code block. Usage
  13760. example: @code{:results value}.
  13761. @item @code{output}
  13762. Scripting mode. Result is collected from STDOUT during execution of the code
  13763. in the @samp{src} code block. Usage example: @code{:results output}.
  13764. @end itemize
  13765. @subsubheading Type
  13766. Type tells what result types to expect from the execution of the code
  13767. block. Choose one of the options; they are mutually exclusive. The default
  13768. behavior is to automatically determine the result type.
  13769. @itemize @bullet
  13770. @item @code{table}, @code{vector}
  13771. Interpret the results as an Org table. If the result is a single value,
  13772. create a table with one row and one column. Usage example: @code{:results
  13773. value table}.
  13774. @item @code{list}
  13775. Interpret the results as an Org list. If the result is a single value,
  13776. create a list of one element.
  13777. @item @code{scalar}, @code{verbatim}
  13778. Interpret literally and insert as quoted text. Do not create a table. Usage
  13779. example: @code{:results value verbatim}.
  13780. @item @code{file}
  13781. Interpret as path to a file. Inserts a link to the file. Usage example:
  13782. @code{:results value file}.
  13783. @end itemize
  13784. @subsubheading Format
  13785. Format pertains to the type of the result returned by the @samp{src} code
  13786. block. Choose one of the options; they are mutually exclusive. The default
  13787. follows from the type specified above.
  13788. @itemize @bullet
  13789. @item @code{raw}
  13790. Interpreted as raw Org mode. Inserted directly into the buffer. Aligned if
  13791. it is a table. Usage example: @code{:results value raw}.
  13792. @item @code{org}
  13793. Results enclosed in a @code{BEGIN_SRC org} block. For comma-escape, either
  13794. @kbd{TAB} in the block, or export the file. Usage example: @code{:results
  13795. value org}.
  13796. @item @code{html}
  13797. Results enclosed in a @code{BEGIN_EXPORT html} block. Usage example:
  13798. @code{:results value html}.
  13799. @item @code{latex}
  13800. Results enclosed in a @code{BEGIN_EXPORT latex} block. Usage example:
  13801. @code{:results value latex}.
  13802. @item @code{code}
  13803. Result enclosed in a @samp{src} code block. Useful for parsing. Usage
  13804. example: @code{:results value code}.
  13805. @item @code{pp}
  13806. Result converted to pretty-print source code. Enclosed in a @samp{src} code
  13807. block. Languages supported: Emacs Lisp, Python, and Ruby. Usage example:
  13808. @code{:results value pp}.
  13809. @item @code{drawer}
  13810. Result wrapped in a RESULTS drawer. Useful for containing @code{raw} or
  13811. @code{org} results for later scripting and automated processing. Usage
  13812. example: @code{:results value drawer}.
  13813. @end itemize
  13814. @subsubheading Handling
  13815. Handling options after collecting the results.
  13816. @itemize @bullet
  13817. @item @code{silent}
  13818. Do not insert results in the Org mode buffer, but echo them in the
  13819. minibuffer. Usage example: @code{:results output silent}.
  13820. @item @code{replace}
  13821. Default. Insert results in the Org buffer. Remove previous results. Usage
  13822. example: @code{:results output replace}.
  13823. @item @code{append}
  13824. Append results to the Org buffer. Latest results are at the bottom. Does
  13825. not remove previous results. Usage example: @code{:results output append}.
  13826. @item @code{prepend}
  13827. Prepend results to the Org buffer. Latest results are at the top. Does not
  13828. remove previous results. Usage example: @code{:results output prepend}.
  13829. @end itemize
  13830. @node file
  13831. @subsubsection @code{:file}
  13832. @cindex @code{:file}, src header argument
  13833. An external @code{:file} that saves the results of execution of the code
  13834. block. The @code{:file} is either a file name or two strings, where the
  13835. first is the file name and the second is the description. A link to the file
  13836. is inserted. It uses an Org mode style @code{[[file:]]} link (@pxref{Link
  13837. format}). Some languages, such as @samp{R}, @samp{dot}, @samp{ditaa}, and
  13838. @samp{gnuplot}, automatically wrap the source code in additional boilerplate
  13839. code. Such code wrapping helps recreate the output, especially graphics
  13840. output, by executing just the @code{:file} contents.
  13841. @node file-desc
  13842. @subsubsection @code{:file-desc}
  13843. A description of the results file. Org uses this description for the link
  13844. (see @ref{Link format}) it inserts in the Org file. If the @code{:file-desc}
  13845. has no value, Org will use file name for both the ``link'' and the
  13846. ``description'' portion of the Org mode link.
  13847. @node file-ext
  13848. @subsubsection @code{:file-ext}
  13849. @cindex @code{:file-ext}, src header argument
  13850. File name extension for the output file. Org generates the file's complete
  13851. name, and extension by combining @code{:file-ext}, @code{#+NAME:} of the
  13852. source block, and the @ref{output-dir} header argument. To override this
  13853. auto generated file name, use the @code{:file} header argument.
  13854. @node output-dir
  13855. @subsubsection @code{:output-dir}
  13856. @cindex @code{:output-dir}, src header argument
  13857. Specifies the @code{:output-dir} for the results file. Org accepts an
  13858. absolute path (beginning with @code{/}) or a relative directory (without
  13859. @code{/}). The value can be combined with @code{#+NAME:} of the source block
  13860. and @ref{file} or @ref{file-ext} header arguments.
  13861. @node dir
  13862. @subsubsection @code{:dir} and remote execution
  13863. @cindex @code{:dir}, src header argument
  13864. While the @code{:file} header argument can be used to specify the path to the
  13865. output file, @code{:dir} specifies the default directory during @samp{src}
  13866. code block execution. If it is absent, then the directory associated with
  13867. the current buffer is used. In other words, supplying @code{:dir path}
  13868. temporarily has the same effect as changing the current directory with
  13869. @kbd{M-x cd path RET}, and then not supplying @code{:dir}. Under the
  13870. surface, @code{:dir} simply sets the value of the Emacs variable
  13871. @code{default-directory}.
  13872. When using @code{:dir}, relative paths (for example, @code{:file myfile.jpg}
  13873. or @code{:file results/myfile.jpg}) become relative to the default directory.
  13874. For example, to save the plot file in the @samp{Work} folder of the home
  13875. directory (notice tilde is expanded):
  13876. @example
  13877. #+BEGIN_SRC R :file myplot.png :dir ~/Work
  13878. matplot(matrix(rnorm(100), 10), type="l")
  13879. #+END_SRC
  13880. @end example
  13881. @subsubheading Remote execution
  13882. To evaluate the @samp{src} code block on a remote machine, supply a remote s
  13883. directory name using @samp{Tramp} syntax. For example:
  13884. @example
  13885. #+BEGIN_SRC R :file plot.png :dir /scp:dand@@yakuba.princeton.edu:
  13886. plot(1:10, main=system("hostname", intern=TRUE))
  13887. #+END_SRC
  13888. @end example
  13889. Org first captures the text results as usual for insertion in the Org file.
  13890. Then Org also inserts a link to the remote file, thanks to Emacs
  13891. @samp{Tramp}. Org constructs the remote path to the file name from
  13892. @code{:dir} and @code{default-directory}, as illustrated here:
  13893. @example
  13894. [[file:/scp:dand@@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]
  13895. @end example
  13896. @subsubheading Some more warnings
  13897. @itemize @bullet
  13898. @item
  13899. When @code{:dir} is used with @code{:session}, Org sets the starting
  13900. directory for a new session. But Org will not alter the directory of an
  13901. already existing session.
  13902. @item
  13903. Do not use @code{:dir} with @code{:exports results} or with @code{:exports
  13904. both} to avoid Org inserting incorrect links to remote files. That is because
  13905. Org does not expand @code{default directory} to avoid some underlying
  13906. portability issues.
  13907. @end itemize
  13908. @node exports
  13909. @subsubsection @code{:exports}
  13910. @cindex @code{:exports}, src header argument
  13911. The @code{:exports} header argument is to specify if that part of the Org
  13912. file is exported to, say, HTML or @LaTeX{} formats. Note that
  13913. @code{:exports} affects only @samp{src} code blocks and not inline code.
  13914. @itemize @bullet
  13915. @item @code{code}
  13916. The default. The body of code is included into the exported file. Example:
  13917. @code{:exports code}.
  13918. @item @code{results}
  13919. The results of evaluation of the code is included in the exported file.
  13920. Example: @code{:exports results}.
  13921. @item @code{both}
  13922. Both the code and results of evaluation are included in the exported file.
  13923. Example: @code{:exports both}.
  13924. @item @code{none}
  13925. Neither the code nor the results of evaluation is included in the exported
  13926. file. Whether the code is evaluated at all depends on other
  13927. options. Example: @code{:exports none}.
  13928. @end itemize
  13929. @node tangle
  13930. @subsubsection @code{:tangle}
  13931. @cindex @code{:tangle}, src header argument
  13932. The @code{:tangle} header argument specifies if the @samp{src} code block is
  13933. exported to source file(s).
  13934. @itemize @bullet
  13935. @item @code{tangle}
  13936. Export the @samp{src} code block to source file. The file name for the
  13937. source file is derived from the name of the Org file, and the file extension
  13938. is derived from the source code language identifier. Example: @code{:tangle
  13939. yes}.
  13940. @item @code{no}
  13941. The default. Do not extract the code a source code file. Example:
  13942. @code{:tangle no}.
  13943. @item other
  13944. Export the @samp{src} code block to source file whose file name is derived
  13945. from any string passed to the @code{:tangle} header argument. Org derives
  13946. the file name as being relative to the directory of the Org file's location.
  13947. Example: @code{:tangle path}.
  13948. @end itemize
  13949. @node mkdirp
  13950. @subsubsection @code{:mkdirp}
  13951. @cindex @code{:mkdirp}, src header argument
  13952. The @code{:mkdirp} header argument creates parent directories for tangled
  13953. files if the directory does not exist. @code{yes} enables directory creation
  13954. and @code{no} inhibits directory creation.
  13955. @node comments
  13956. @subsubsection @code{:comments}
  13957. @cindex @code{:comments}, src header argument
  13958. Controls inserting comments into tangled files. These are above and beyond
  13959. whatever comments may already exist in the @samp{src} code block.
  13960. @itemize @bullet
  13961. @item @code{no}
  13962. The default. Do not insert any extra comments during tangling.
  13963. @item @code{link}
  13964. Wrap the @samp{src} code block in comments. Include links pointing back to
  13965. the place in the Org file from where the code was tangled.
  13966. @item @code{yes}
  13967. Kept for backward compatibility; same as ``link''.
  13968. @item @code{org}
  13969. Nearest headline text from Org file is inserted as comment. The exact text
  13970. that is inserted is picked from the leading context of the source block.
  13971. @item @code{both}
  13972. Includes both ``link'' and ``org'' comment options.
  13973. @item @code{noweb}
  13974. Includes ``link'' comment option, expands noweb references, and wraps them in
  13975. link comments inside the body of the @samp{src} code block.
  13976. @end itemize
  13977. @node padline
  13978. @subsubsection @code{:padline}
  13979. @cindex @code{:padline}, src header argument
  13980. Control insertion of newlines to pad @samp{src} code blocks in the tangled
  13981. file.
  13982. @itemize @bullet
  13983. @item @code{yes}
  13984. Default. Insert a newline before and after each @samp{src} code block in the
  13985. tangled file.
  13986. @item @code{no}
  13987. Do not insert newlines to pad the tangled @samp{src} code blocks.
  13988. @end itemize
  13989. @node no-expand
  13990. @subsubsection @code{:no-expand}
  13991. @cindex @code{:no-expand}, src header argument
  13992. By default Org expands @samp{src} code blocks during tangling. The
  13993. @code{:no-expand} header argument turns off such expansions. Note that one
  13994. side-effect of expansion by @code{org-babel-expand-src-block} also assigns
  13995. values to @code{:var} (@pxref{var}) variables. Expansions also replace Noweb
  13996. references with their targets (@pxref{Noweb reference syntax}). Some of
  13997. these expansions may cause premature assignment, hence this option. This
  13998. option makes a difference only for tangling. It has no effect when exporting
  13999. since @samp{src} code blocks for execution have to be expanded anyway.
  14000. @node session
  14001. @subsubsection @code{:session}
  14002. @cindex @code{:session}, src header argument
  14003. The @code{:session} header argument is for running multiple source code
  14004. blocks under one session. Org runs @samp{src} code blocks with the same
  14005. session name in the same interpreter process.
  14006. @itemize @bullet
  14007. @item @code{none}
  14008. Default. Each @samp{src} code block gets a new interpreter process to
  14009. execute. The process terminates once the block is evaluated.
  14010. @item @code{other}
  14011. Any string besides @code{none} turns that string into the name of that
  14012. session. For example, @code{:session mysession} names it @samp{mysession}.
  14013. If @code{:session} has no argument, then the session name is derived from the
  14014. source language identifier. Subsequent blocks with the same source code
  14015. language use the same session. Depending on the language, state variables,
  14016. code from other blocks, and the overall interpreted environment may be
  14017. shared. Some interpreted languages support concurrent sessions when
  14018. subsequent source code language blocks change session names.
  14019. @end itemize
  14020. @node noweb
  14021. @subsubsection @code{:noweb}
  14022. @cindex @code{:noweb}, src header argument
  14023. The @code{:noweb} header argument controls expansion of Noweb syntax
  14024. references (@pxref{Noweb reference syntax}). Expansions occur when source
  14025. code blocks are evaluated, tangled, or exported.
  14026. @itemize @bullet
  14027. @item @code{no}
  14028. Default. No expansion of Noweb syntax references in the body of the code
  14029. when evaluating, tangling, or exporting.
  14030. @item @code{yes}
  14031. Expansion of Noweb syntax references in the body of the @samp{src} code block
  14032. when evaluating, tangling, or exporting.
  14033. @item @code{tangle}
  14034. Expansion of Noweb syntax references in the body of the @samp{src} code block
  14035. when tangling. No expansion when evaluating or exporting.
  14036. @item @code{no-export}
  14037. Expansion of Noweb syntax references in the body of the @samp{src} code block
  14038. when evaluating or tangling. No expansion when exporting.
  14039. @item @code{strip-export}
  14040. Expansion of Noweb syntax references in the body of the @samp{src} code block
  14041. when expanding prior to evaluating or tangling. Removes Noweb syntax
  14042. references when exporting.
  14043. @item @code{eval}
  14044. Expansion of Noweb syntax references in the body of the @samp{src} code block
  14045. only before evaluating.
  14046. @end itemize
  14047. @subsubheading Noweb prefix lines
  14048. Noweb insertions now honor prefix characters that appear before the Noweb
  14049. syntax reference.
  14050. This behavior is illustrated in the following example. Because the
  14051. @code{<<example>>} noweb reference appears behind the SQL comment syntax,
  14052. each line of the expanded noweb reference will be commented.
  14053. With:
  14054. @example
  14055. #+NAME: example
  14056. #+BEGIN_SRC text
  14057. this is the
  14058. multi-line body of example
  14059. #+END_SRC
  14060. @end example
  14061. this @samp{src} code block:
  14062. @example
  14063. #+BEGIN_SRC sql :noweb yes
  14064. -- <<example>>
  14065. #+END_SRC
  14066. @end example
  14067. expands to:
  14068. @example
  14069. -- this is the
  14070. -- multi-line body of example
  14071. @end example
  14072. Since this change will not affect noweb replacement text without newlines in
  14073. them, inline noweb references are acceptable.
  14074. This feature can also be used for management of indentation in exported code snippets.
  14075. With:
  14076. @example
  14077. #+NAME: if-true
  14078. #+BEGIN_SRC python :exports none
  14079. print('Do things when True')
  14080. #+END_SRC
  14081. #+NAME: if-false
  14082. #+BEGIN_SRC python :exports none
  14083. print('Do things when False')
  14084. #+END_SRC
  14085. @end example
  14086. this @samp{src} code block:
  14087. @example
  14088. #+BEGIN_SRC python :noweb yes :results output
  14089. if True:
  14090. <<if-true>>
  14091. else:
  14092. <<if-false>>
  14093. #+END_SRC
  14094. @end example
  14095. expands to:
  14096. @example
  14097. if True:
  14098. print('Do things when True')
  14099. else:
  14100. print('Do things when False')
  14101. @end example
  14102. and evaluates to:
  14103. @example
  14104. Do things when True
  14105. @end example
  14106. @node noweb-ref
  14107. @subsubsection @code{:noweb-ref}
  14108. @cindex @code{:noweb-ref}, src header argument
  14109. When expanding Noweb style references, Org concatenates @samp{src} code
  14110. blocks by matching the reference name to either the code block name or the
  14111. @code{:noweb-ref} header argument.
  14112. For simple concatenation, set this @code{:noweb-ref} header argument at the
  14113. sub-tree or file level. In the example Org file shown next, the body of the
  14114. source code in each block is extracted for concatenation to a pure code file
  14115. when tangled.
  14116. @example
  14117. #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
  14118. <<fullest-disk>>
  14119. #+END_SRC
  14120. * the mount point of the fullest disk
  14121. :PROPERTIES:
  14122. :header-args: :noweb-ref fullest-disk
  14123. :END:
  14124. ** query all mounted disks
  14125. #+BEGIN_SRC sh
  14126. df \
  14127. #+END_SRC
  14128. ** strip the header row
  14129. #+BEGIN_SRC sh
  14130. |sed '1d' \
  14131. #+END_SRC
  14132. ** output mount point of fullest disk
  14133. #+BEGIN_SRC sh
  14134. |awk '@{if (u < +$5) @{u = +$5; m = $6@}@} END @{print m@}'
  14135. #+END_SRC
  14136. @end example
  14137. @node noweb-sep
  14138. @subsubsection @code{:noweb-sep}
  14139. @cindex @code{:noweb-sep}, src header argument
  14140. By default a newline separates each noweb reference concatenation. To change
  14141. this newline separator, edit the @code{:noweb-sep} (@pxref{noweb-sep}) header
  14142. argument.
  14143. @node cache
  14144. @subsubsection @code{:cache}
  14145. @cindex @code{:cache}, src header argument
  14146. The @code{:cache} header argument is for caching results of evaluating code
  14147. blocks. Caching results can avoid re-evaluating @samp{src} code blocks that
  14148. have not changed since the previous run. To benefit from the cache and avoid
  14149. redundant evaluations, the source block must have a result already present in
  14150. the buffer, and neither the header arguments (including the value of
  14151. @code{:var} references) nor the text of the block itself has changed since
  14152. the result was last computed. This feature greatly helps avoid long-running
  14153. calculations. For some edge cases, however, the cached results may not be
  14154. reliable.
  14155. The caching feature is best for when @samp{src} blocks are pure functions,
  14156. that is functions that return the same value for the same input arguments
  14157. (@pxref{var}), and that do not have side effects, and do not rely on external
  14158. variables other than the input arguments. Functions that depend on a timer,
  14159. file system objects, and random number generators are clearly unsuitable for
  14160. caching.
  14161. A note of warning: when @code{:cache} is used for a @code{:session}, caching
  14162. may cause unexpected results.
  14163. When the caching mechanism tests for any source code changes, it will not
  14164. expand Noweb style references (@pxref{Noweb reference syntax}). For reasons
  14165. why, see @uref{http://thread.gmane.org/gmane.emacs.orgmode/79046}.
  14166. The @code{:cache} header argument can have one of two values: @code{yes} or
  14167. @code{no}.
  14168. @itemize @bullet
  14169. @item @code{no}
  14170. Default. No caching of results; @samp{src} code block evaluated every time.
  14171. @item @code{yes}
  14172. Whether to run the code or return the cached results is determined by
  14173. comparing the SHA1 hash value of the combined @samp{src} code block and
  14174. arguments passed to it. This hash value is packed on the @code{#+RESULTS:}
  14175. line from previous evaluation. When hash values match, Org does not evaluate
  14176. the @samp{src} code block. When hash values mismatch, Org evaluates the
  14177. @samp{src} code block, inserts the results, recalculates the hash value, and
  14178. updates @code{#+RESULTS:} line.
  14179. @end itemize
  14180. In this example, both functions are cached. But @code{caller} runs only if
  14181. the result from @code{random} has changed since the last run.
  14182. @example
  14183. #+NAME: random
  14184. #+BEGIN_SRC R :cache yes
  14185. runif(1)
  14186. #+END_SRC
  14187. #+RESULTS[a2a72cd647ad44515fab62e144796432793d68e1]: random
  14188. 0.4659510825295
  14189. #+NAME: caller
  14190. #+BEGIN_SRC emacs-lisp :var x=random :cache yes
  14191. x
  14192. #+END_SRC
  14193. #+RESULTS[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
  14194. 0.254227238707244
  14195. @end example
  14196. @node sep
  14197. @subsubsection @code{:sep}
  14198. @cindex @code{:sep}, src header argument
  14199. The @code{:sep} header argument is the delimiter for saving results as tables
  14200. to files (@pxref{file}) external to Org mode. Org defaults to tab delimited
  14201. output. The function, @code{org-open-at-point}, which is bound to @kbd{C-c
  14202. C-o}, also uses @code{:sep} for opening tabular results.
  14203. @node hlines
  14204. @subsubsection @code{:hlines}
  14205. @cindex @code{:hlines}, src header argument
  14206. In-between each table row or below the table headings, sometimes results have
  14207. horizontal lines, which are also known as hlines. The @code{:hlines}
  14208. argument with the value @code{yes} accepts such lines. The default is
  14209. @code{no}.
  14210. @itemize @bullet
  14211. @item @code{no}
  14212. Strips horizontal lines from the input table. For most code, this is
  14213. desirable, or else those @code{hline} symbols raise unbound variable errors.
  14214. The default is @code{:hlines no}. The example shows hlines removed from the
  14215. input table.
  14216. @example
  14217. #+NAME: many-cols
  14218. | a | b | c |
  14219. |---+---+---|
  14220. | d | e | f |
  14221. |---+---+---|
  14222. | g | h | i |
  14223. #+NAME: echo-table
  14224. #+BEGIN_SRC python :var tab=many-cols
  14225. return tab
  14226. #+END_SRC
  14227. #+RESULTS: echo-table
  14228. | a | b | c |
  14229. | d | e | f |
  14230. | g | h | i |
  14231. @end example
  14232. @item @code{yes}
  14233. For @code{:hlines yes}, the example shows hlines unchanged.
  14234. @example
  14235. #+NAME: many-cols
  14236. | a | b | c |
  14237. |---+---+---|
  14238. | d | e | f |
  14239. |---+---+---|
  14240. | g | h | i |
  14241. #+NAME: echo-table
  14242. #+BEGIN_SRC python :var tab=many-cols :hlines yes
  14243. return tab
  14244. #+END_SRC
  14245. #+RESULTS: echo-table
  14246. | a | b | c |
  14247. |---+---+---|
  14248. | d | e | f |
  14249. |---+---+---|
  14250. | g | h | i |
  14251. @end example
  14252. @end itemize
  14253. @node colnames
  14254. @subsubsection @code{:colnames}
  14255. @cindex @code{:colnames}, src header argument
  14256. The @code{:colnames} header argument accepts @code{yes}, @code{no}, or
  14257. @code{nil} values. The default value is @code{nil}, which is unassigned.
  14258. But this header argument behaves differently depending on the source code
  14259. language.
  14260. @itemize @bullet
  14261. @item @code{nil}
  14262. If an input table has column names (because the second row is an hline), then
  14263. Org removes the column names, processes the table, puts back the column
  14264. names, and then writes the table to the results block.
  14265. @example
  14266. #+NAME: less-cols
  14267. | a |
  14268. |---|
  14269. | b |
  14270. | c |
  14271. #+NAME: echo-table-again
  14272. #+BEGIN_SRC python :var tab=less-cols
  14273. return [[val + '*' for val in row] for row in tab]
  14274. #+END_SRC
  14275. #+RESULTS: echo-table-again
  14276. | a |
  14277. |----|
  14278. | b* |
  14279. | c* |
  14280. @end example
  14281. Note that column names have to accounted for when using variable indexing
  14282. (@pxref{var, Indexable variable values}) because column names are not removed
  14283. for indexing.
  14284. @item @code{no}
  14285. Do not pre-process column names.
  14286. @item @code{yes}
  14287. For an input table that has no hlines, process it like the @code{nil}
  14288. value. That is, Org removes the column names, processes the table, puts back
  14289. the column names, and then writes the table to the results block.
  14290. @end itemize
  14291. @node rownames
  14292. @subsubsection @code{:rownames}
  14293. @cindex @code{:rownames}, src header argument
  14294. The @code{:rownames} header argument can take on values @code{yes} or
  14295. @code{no} values. The default is @code{no}. Note that @code{emacs-lisp}
  14296. code blocks ignore @code{:rownames} header argument because of the ease of
  14297. table-handling in Emacs.
  14298. @itemize @bullet
  14299. @item @code{no}
  14300. Org will not pre-process row names.
  14301. @item @code{yes}
  14302. If an input table has row names, then Org removes the row names, processes
  14303. the table, puts back the row names, and then writes the table to the results
  14304. block.
  14305. @example
  14306. #+NAME: with-rownames
  14307. | one | 1 | 2 | 3 | 4 | 5 |
  14308. | two | 6 | 7 | 8 | 9 | 10 |
  14309. #+NAME: echo-table-once-again
  14310. #+BEGIN_SRC python :var tab=with-rownames :rownames yes
  14311. return [[val + 10 for val in row] for row in tab]
  14312. #+END_SRC
  14313. #+RESULTS: echo-table-once-again
  14314. | one | 11 | 12 | 13 | 14 | 15 |
  14315. | two | 16 | 17 | 18 | 19 | 20 |
  14316. @end example
  14317. Note that row names have to accounted for when using variable indexing
  14318. (@pxref{var, Indexable variable values}) because row names are not removed
  14319. for indexing.
  14320. @end itemize
  14321. @node shebang
  14322. @subsubsection @code{:shebang}
  14323. @cindex @code{:shebang}, src header argument
  14324. This header argument can turn results into executable script files. By
  14325. setting the @code{:shebang} header argument to a string value (for example,
  14326. @code{:shebang "#!/bin/bash"}), Org inserts that string as the first line of
  14327. the tangled file that the @samp{src} code block is extracted to. Org then
  14328. turns on the tangled file's executable permission.
  14329. @node tangle-mode
  14330. @subsubsection @code{:tangle-mode}
  14331. @cindex @code{:tangle-mode}, src header argument
  14332. The @code{tangle-mode} header argument specifies what permissions to set for
  14333. tangled files by @code{set-file-modes}. For example, to make read-only
  14334. tangled file, use @code{:tangle-mode (identity #o444)}. To make it
  14335. executable, use @code{:tangle-mode (identity #o755)}.
  14336. On @samp{src} code blocks with @code{shebang} (@pxref{shebang}) header
  14337. argument, Org will automatically set the tangled file to executable
  14338. permissions. But this can be overridden with custom permissions using
  14339. @code{tangle-mode} header argument.
  14340. When multiple @samp{src} code blocks tangle to a single file with different
  14341. and conflicting @code{tangle-mode} header arguments, Org's behavior is
  14342. undefined.
  14343. @node eval
  14344. @subsubsection @code{:eval}
  14345. @cindex @code{:eval}, src header argument
  14346. The @code{:eval} header argument can limit evaluation of specific code
  14347. blocks. It is useful for protection against evaluating untrusted @samp{src}
  14348. code blocks by prompting for a confirmation. This protection is independent
  14349. of the @code{org-confirm-babel-evaluate} setting.
  14350. @table @code
  14351. @item never or no
  14352. Org will never evaluate this @samp{src} code block.
  14353. @item query
  14354. Org prompts the user for permission to evaluate this @samp{src} code block.
  14355. @item never-export or no-export
  14356. Org will not evaluate this @samp{src} code block when exporting, yet the user
  14357. can evaluate this source block interactively.
  14358. @item query-export
  14359. Org prompts the user for permission to export this @samp{src} code block.
  14360. @end table
  14361. If @code{:eval} header argument is not set for a source block, then Org
  14362. determines whether to evaluate from the @code{org-confirm-babel-evaluate}
  14363. variable (@pxref{Code evaluation security}).
  14364. @node wrap
  14365. @subsubsection @code{:wrap}
  14366. @cindex @code{:wrap}, src header argument
  14367. The @code{:wrap} header argument marks the results block by appending strings
  14368. to @code{#+BEGIN_} and @code{#+END_}. If no string is specified, Org wraps
  14369. the results in a @code{#+BEGIN/END_RESULTS} block.
  14370. @node post
  14371. @subsubsection @code{:post}
  14372. @cindex @code{:post}, src header argument
  14373. The @code{:post} header argument is for post-processing results from
  14374. @samp{src} block evaluation. When @code{:post} has any value, Org binds the
  14375. results to @code{*this*} variable for easy passing to @ref{var} header
  14376. argument specifications. That makes results available to other @samp{src}
  14377. code blocks, or for even direct Emacs Lisp code execution.
  14378. The following two examples illustrate @code{:post} header argument in action.
  14379. The first one shows how to attach @code{#+ATTR_LATEX:} line using
  14380. @code{:post}.
  14381. @example
  14382. #+name: attr_wrap
  14383. #+begin_src sh :var data="" :var width="\\textwidth" :results output
  14384. echo "#+ATTR_LATEX: :width $width"
  14385. echo "$data"
  14386. #+end_src
  14387. #+header: :file /tmp/it.png
  14388. #+begin_src dot :post attr_wrap(width="5cm", data=*this*) :results drawer
  14389. digraph@{
  14390. a -> b;
  14391. b -> c;
  14392. c -> a;
  14393. @}
  14394. #+end_src
  14395. #+RESULTS:
  14396. :RESULTS:
  14397. #+ATTR_LATEX :width 5cm
  14398. [[file:/tmp/it.png]]
  14399. :END:
  14400. @end example
  14401. The second example shows use of @code{:colnames} in @code{:post} to pass
  14402. data between @samp{src} code blocks.
  14403. @example
  14404. #+name: round-tbl
  14405. #+begin_src emacs-lisp :var tbl="" fmt="%.3f"
  14406. (mapcar (lambda (row)
  14407. (mapcar (lambda (cell)
  14408. (if (numberp cell)
  14409. (format fmt cell)
  14410. cell))
  14411. row))
  14412. tbl)
  14413. #+end_src
  14414. #+begin_src R :colnames yes :post round-tbl[:colnames yes](*this*)
  14415. set.seed(42)
  14416. data.frame(foo=rnorm(1))
  14417. #+end_src
  14418. #+RESULTS:
  14419. | foo |
  14420. |-------|
  14421. | 1.371 |
  14422. @end example
  14423. @node prologue
  14424. @subsubsection @code{:prologue}
  14425. @cindex @code{:prologue}, src header argument
  14426. The @code{prologue} header argument is for appending to the top of the code
  14427. block for execution. For example, a clear or reset code at the start of new
  14428. execution of a @samp{src} code block. A @code{reset} for @samp{gnuplot}:
  14429. @code{:prologue "reset"}. See also @ref{epilogue}.
  14430. @lisp
  14431. (add-to-list 'org-babel-default-header-args:gnuplot
  14432. '((:prologue . "reset")))
  14433. @end lisp
  14434. @node epilogue
  14435. @subsubsection @code{:epilogue}
  14436. @cindex @code{:epilogue}, src header argument
  14437. The value of the @code{epilogue} header argument is for appending to the end
  14438. of the code block for execution. See also @ref{prologue}.
  14439. @node Results of evaluation
  14440. @section Results of evaluation
  14441. @cindex code block, results of evaluation
  14442. @cindex source code, results of evaluation
  14443. How Org handles results of a code block execution depends on many header
  14444. arguments working together. Here is only a summary of these. For an
  14445. enumeration of all the header arguments that affect results, see
  14446. @ref{results}.
  14447. The primary determinant is the execution context. Is it in a @code{:session}
  14448. or not? Orthogonal to that is if the expected result is a @code{:results
  14449. value} or @code{:results output}, which is a concatenation of output from
  14450. start to finish of the @samp{src} code block's evaluation.
  14451. @multitable @columnfractions 0.26 0.33 0.41
  14452. @item @tab @b{Non-session} @tab @b{Session}
  14453. @item @code{:results value} @tab value of last expression @tab value of last expression
  14454. @item @code{:results output} @tab contents of STDOUT @tab concatenation of interpreter output
  14455. @end multitable
  14456. For @code{:session} and non-session, the @code{:results value} turns the
  14457. results into an Org mode table format. Single values are wrapped in a one
  14458. dimensional vector. Rows and columns of a table are wrapped in a
  14459. two-dimensional vector.
  14460. @subsection Non-session
  14461. @subsubsection @code{:results value}
  14462. @cindex @code{:results}, src header argument
  14463. Default. Org gets the value by wrapping the code in a function definition in
  14464. the language of the @samp{src} block. That is why when using @code{:results
  14465. value}, code should execute like a function and return a value. For
  14466. languages like Python, an explicit @code{return} statement is mandatory when
  14467. using @code{:results value}.
  14468. This is one of four evaluation contexts where Org automatically wraps the
  14469. code in a function definition.
  14470. @subsubsection @code{:results output}
  14471. @cindex @code{:results}, src header argument
  14472. For @code{:results output}, the code is passed to an external process running
  14473. the interpreter. Org returns the contents of the standard output stream as
  14474. as text results.
  14475. @subsection Session
  14476. @subsubsection @code{:results value}
  14477. @cindex @code{:results}, src header argument
  14478. For @code{:results value} from a @code{:session}, Org passes the code to an
  14479. interpreter running as an interactive Emacs inferior process. So only
  14480. languages that provide interactive evaluation can have session support. Not
  14481. all languages provide this support, such as @samp{C} and @samp{ditaa}. Even
  14482. those that do support, such as @samp{Python} and @samp{Haskell}, they impose
  14483. limitations on allowable language constructs that can run interactively. Org
  14484. inherits those limitations for those @samp{src} code blocks running in a
  14485. @code{:session}.
  14486. Org gets the value from the source code interpreter's last statement
  14487. output. Org has to use language-specific methods to obtain the value. For
  14488. example, from the variable @code{_} in @samp{Python} and @samp{Ruby}, and the
  14489. value of @code{.Last.value} in @samp{R}).
  14490. @subsubsection @code{:results output}
  14491. @cindex @code{:results}, src header argument
  14492. For @code{:results output}, Org passes the code to the interpreter running as
  14493. an interactive Emacs inferior process. Org concatenates whatever text output
  14494. emitted by the interpreter to return the collection as a result. Note that
  14495. this collection is not the same as collected from @code{STDOUT} of a
  14496. non-interactive interpreter running as an external process. Compare for
  14497. example these two blocks:
  14498. @example
  14499. #+BEGIN_SRC python :results output
  14500. print "hello"
  14501. 2
  14502. print "bye"
  14503. #+END_SRC
  14504. #+RESULTS:
  14505. : hello
  14506. : bye
  14507. @end example
  14508. In the above non-session mode, the ``2'' is not printed; so does not appear
  14509. in results.
  14510. @example
  14511. #+BEGIN_SRC python :results output :session
  14512. print "hello"
  14513. 2
  14514. print "bye"
  14515. #+END_SRC
  14516. #+RESULTS:
  14517. : hello
  14518. : 2
  14519. : bye
  14520. @end example
  14521. In the above @code{:session} mode, the interactive interpreter receives and
  14522. prints ``2''. Results show that.
  14523. @node Noweb reference syntax
  14524. @section Noweb reference syntax
  14525. @cindex code block, noweb reference
  14526. @cindex syntax, noweb
  14527. @cindex source code, noweb reference
  14528. Org supports named blocks in Noweb style syntax. For Noweb literate
  14529. programming details, see @uref{http://www.cs.tufts.edu/~nr/noweb/}).
  14530. @example
  14531. <<code-block-name>>
  14532. @end example
  14533. For the header argument @code{:noweb yes}, Org expands Noweb style references
  14534. in the @samp{src} code block before evaluation.
  14535. For the header argument @code{:noweb no}, Org does not expand Noweb style
  14536. references in the @samp{src} code block before evaluation.
  14537. The default is @code{:noweb no}. Org defaults to @code{:noweb no} so as not
  14538. to cause errors in languages where Noweb syntax is ambiguous. Change Org's
  14539. default to @code{:noweb yes} for languages where there is no risk of
  14540. confusion.
  14541. Org offers a more flexible way to resolve Noweb style references
  14542. (@pxref{noweb-ref}).
  14543. Org can include the @emph{results} of a code block rather than its body. To
  14544. that effect, append parentheses, possibly including arguments, to the code
  14545. block name, as show below.
  14546. @example
  14547. <<code-block-name(optional arguments)>>
  14548. @end example
  14549. Note that when using the above approach to a code block's results, the code
  14550. block name set by @code{#+NAME} keyword is required; the reference set by
  14551. @code{:noweb-ref} will not work.
  14552. Here is an example that demonstrates how the exported content changes when
  14553. Noweb style references are used with parentheses versus without.
  14554. With:
  14555. @example
  14556. #+NAME: some-code
  14557. #+BEGIN_SRC python :var num=0 :results output :exports none
  14558. print(num*10)
  14559. #+END_SRC
  14560. @end example
  14561. this code block:
  14562. @example
  14563. #+BEGIN_SRC text :noweb yes
  14564. <<some-code>>
  14565. #+END_SRC
  14566. @end example
  14567. expands to:
  14568. @example
  14569. print(num*10)
  14570. @end example
  14571. Below, a similar Noweb style reference is used, but with parentheses, while
  14572. setting a variable @code{num} to 10:
  14573. @example
  14574. #+BEGIN_SRC text :noweb yes
  14575. <<some-code(num=10)>>
  14576. #+END_SRC
  14577. @end example
  14578. Note that now the expansion contains the @emph{results} of the code block
  14579. @code{some-code}, not the code block itself:
  14580. @example
  14581. 100
  14582. @end example
  14583. For faster tangling of large Org mode files, set
  14584. @code{org-babel-use-quick-and-dirty-noweb-expansion} variable to @code{t}.
  14585. The speedup comes at the expense of not correctly resolving inherited values
  14586. of the @code{:noweb-ref} header argument.
  14587. @node Key bindings and useful functions
  14588. @section Key bindings and useful functions
  14589. @cindex code block, key bindings
  14590. Many common Org mode key sequences are re-bound depending on the context.
  14591. Active key bindings in code blocks:
  14592. @multitable @columnfractions 0.25 0.75
  14593. @kindex C-c C-c
  14594. @item @kbd{C-c C-c} @tab @code{org-babel-execute-src-block}
  14595. @kindex C-c C-o
  14596. @item @kbd{C-c C-o} @tab @code{org-babel-open-src-block-result}
  14597. @kindex M-up
  14598. @item @kbd{M-@key{up}} @tab @code{org-babel-load-in-session}
  14599. @kindex M-down
  14600. @item @kbd{M-@key{down}} @tab @code{org-babel-switch-to-session}
  14601. @end multitable
  14602. Active key bindings in Org mode buffer:
  14603. @multitable @columnfractions 0.5 0.5
  14604. @kindex C-c C-v p
  14605. @kindex C-c C-v C-p
  14606. @item @kbd{C-c C-v p} @ @ @r{or} @ @ @kbd{C-c C-v C-p} @tab @code{org-babel-previous-src-block}
  14607. @kindex C-c C-v n
  14608. @kindex C-c C-v C-n
  14609. @item @kbd{C-c C-v n} @ @ @r{or} @ @ @kbd{C-c C-v C-n} @tab @code{org-babel-next-src-block}
  14610. @kindex C-c C-v e
  14611. @kindex C-c C-v C-e
  14612. @item @kbd{C-c C-v e} @ @ @r{or} @ @ @kbd{C-c C-v C-e} @tab @code{org-babel-execute-maybe}
  14613. @kindex C-c C-v o
  14614. @kindex C-c C-v C-o
  14615. @item @kbd{C-c C-v o} @ @ @r{or} @ @ @kbd{C-c C-v C-o} @tab @code{org-babel-open-src-block-result}
  14616. @kindex C-c C-v v
  14617. @kindex C-c C-v C-v
  14618. @item @kbd{C-c C-v v} @ @ @r{or} @ @ @kbd{C-c C-v C-v} @tab @code{org-babel-expand-src-block}
  14619. @kindex C-c C-v u
  14620. @kindex C-c C-v C-u
  14621. @item @kbd{C-c C-v u} @ @ @r{or} @ @ @kbd{C-c C-v C-u} @tab @code{org-babel-goto-src-block-head}
  14622. @kindex C-c C-v g
  14623. @kindex C-c C-v C-g
  14624. @item @kbd{C-c C-v g} @ @ @r{or} @ @ @kbd{C-c C-v C-g} @tab @code{org-babel-goto-named-src-block}
  14625. @kindex C-c C-v r
  14626. @kindex C-c C-v C-r
  14627. @item @kbd{C-c C-v r} @ @ @r{or} @ @ @kbd{C-c C-v C-r} @tab @code{org-babel-goto-named-result}
  14628. @kindex C-c C-v b
  14629. @kindex C-c C-v C-b
  14630. @item @kbd{C-c C-v b} @ @ @r{or} @ @ @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
  14631. @kindex C-c C-v s
  14632. @kindex C-c C-v C-s
  14633. @item @kbd{C-c C-v s} @ @ @r{or} @ @ @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
  14634. @kindex C-c C-v d
  14635. @kindex C-c C-v C-d
  14636. @item @kbd{C-c C-v d} @ @ @r{or} @ @ @kbd{C-c C-v C-d} @tab @code{org-babel-demarcate-block}
  14637. @kindex C-c C-v t
  14638. @kindex C-c C-v C-t
  14639. @item @kbd{C-c C-v t} @ @ @r{or} @ @ @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
  14640. @kindex C-c C-v f
  14641. @kindex C-c C-v C-f
  14642. @item @kbd{C-c C-v f} @ @ @r{or} @ @ @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
  14643. @kindex C-c C-v c
  14644. @kindex C-c C-v C-c
  14645. @item @kbd{C-c C-v c} @ @ @r{or} @ @ @kbd{C-c C-v C-c} @tab @code{org-babel-check-src-block}
  14646. @kindex C-c C-v j
  14647. @kindex C-c C-v C-j
  14648. @item @kbd{C-c C-v j} @ @ @r{or} @ @ @kbd{C-c C-v C-j} @tab @code{org-babel-insert-header-arg}
  14649. @kindex C-c C-v l
  14650. @kindex C-c C-v C-l
  14651. @item @kbd{C-c C-v l} @ @ @r{or} @ @ @kbd{C-c C-v C-l} @tab @code{org-babel-load-in-session}
  14652. @kindex C-c C-v i
  14653. @kindex C-c C-v C-i
  14654. @item @kbd{C-c C-v i} @ @ @r{or} @ @ @kbd{C-c C-v C-i} @tab @code{org-babel-lob-ingest}
  14655. @kindex C-c C-v I
  14656. @kindex C-c C-v C-I
  14657. @item @kbd{C-c C-v I} @ @ @r{or} @ @ @kbd{C-c C-v C-I} @tab @code{org-babel-view-src-block-info}
  14658. @kindex C-c C-v z
  14659. @kindex C-c C-v C-z
  14660. @item @kbd{C-c C-v z} @ @ @r{or} @ @ @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session-with-code}
  14661. @kindex C-c C-v a
  14662. @kindex C-c C-v C-a
  14663. @item @kbd{C-c C-v a} @ @ @r{or} @ @ @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
  14664. @kindex C-c C-v h
  14665. @kindex C-c C-v C-h
  14666. @item @kbd{C-c C-v h} @ @ @r{or} @ @ @kbd{C-c C-v C-h} @tab @code{org-babel-describe-bindings}
  14667. @kindex C-c C-v x
  14668. @kindex C-c C-v C-x
  14669. @item @kbd{C-c C-v x} @ @ @r{or} @ @ @kbd{C-c C-v C-x} @tab @code{org-babel-do-key-sequence-in-edit-buffer}
  14670. @end multitable
  14671. @c Extended key bindings when control key is kept pressed:
  14672. @c @multitable @columnfractions 0.25 0.75
  14673. @c @item @kbd{C-c C-v C-a} @tab @code{org-babel-sha1-hash}
  14674. @c @item @kbd{C-c C-v C-b} @tab @code{org-babel-execute-buffer}
  14675. @c @item @kbd{C-c C-v C-f} @tab @code{org-babel-tangle-file}
  14676. @c @item @kbd{C-c C-v C-l} @tab @code{org-babel-lob-ingest}
  14677. @c @item @kbd{C-c C-v C-p} @tab @code{org-babel-expand-src-block}
  14678. @c @item @kbd{C-c C-v C-s} @tab @code{org-babel-execute-subtree}
  14679. @c @item @kbd{C-c C-v C-t} @tab @code{org-babel-tangle}
  14680. @c @item @kbd{C-c C-v C-z} @tab @code{org-babel-switch-to-session}
  14681. @c @end multitable
  14682. @node Batch execution
  14683. @section Batch execution
  14684. @cindex code block, batch execution
  14685. @cindex source code, batch execution
  14686. Org mode features, including working with source code facilities can be
  14687. invoked from the command line. This enables building shell scripts for batch
  14688. processing, running automated system tasks, and expanding Org mode's
  14689. usefulness.
  14690. The sample script shows batch processing of multiple files using
  14691. @code{org-babel-tangle}.
  14692. @example
  14693. #!/bin/sh
  14694. # tangle files with org-mode
  14695. #
  14696. emacs -Q --batch --eval "
  14697. (progn
  14698. (require 'ob-tangle)
  14699. (dolist (file command-line-args-left)
  14700. (with-current-buffer (find-file-noselect file)
  14701. (org-babel-tangle))))
  14702. " "$@@"
  14703. @end example
  14704. @node Miscellaneous
  14705. @chapter Miscellaneous
  14706. @menu
  14707. * Completion:: M-TAB guesses completions
  14708. * Easy templates:: Quick insertion of structural elements
  14709. * Speed keys:: Electric commands at the beginning of a headline
  14710. * Code evaluation security:: Org mode files evaluate inline code
  14711. * Customization:: Adapting Org to changing tastes
  14712. * In-buffer settings:: Overview of the #+KEYWORDS
  14713. * The very busy C-c C-c key:: When in doubt, press C-c C-c
  14714. * Clean view:: Getting rid of leading stars in the outline
  14715. * TTY keys:: Using Org on a tty
  14716. * Interaction:: With other Emacs packages
  14717. * org-crypt:: Encrypting Org files
  14718. @end menu
  14719. @node Completion
  14720. @section Completion
  14721. @cindex completion, of @TeX{} symbols
  14722. @cindex completion, of TODO keywords
  14723. @cindex completion, of dictionary words
  14724. @cindex completion, of option keywords
  14725. @cindex completion, of tags
  14726. @cindex completion, of property keys
  14727. @cindex completion, of link abbreviations
  14728. @cindex @TeX{} symbol completion
  14729. @cindex TODO keywords completion
  14730. @cindex dictionary word completion
  14731. @cindex option keyword completion
  14732. @cindex tag completion
  14733. @cindex link abbreviations, completion of
  14734. Org has in-buffer completions. Unlike minibuffer completions, which are
  14735. useful for quick command interactions, Org's in-buffer completions are more
  14736. suitable for content creation in Org documents. Type one or more letters and
  14737. invoke the hot key to complete the text in-place. Depending on the context
  14738. and the keys, Org will offer different types of completions. No minibuffer
  14739. is involved. Such mode-specific hot keys have become an integral part of
  14740. Emacs and Org provides several shortcuts.
  14741. @table @kbd
  14742. @kindex M-@key{TAB}
  14743. @item M-@key{TAB}
  14744. Complete word at point
  14745. @itemize @bullet
  14746. @item
  14747. At the beginning of a headline, complete TODO keywords.
  14748. @item
  14749. After @samp{\}, complete @TeX{} symbols supported by the exporter.
  14750. @item
  14751. After @samp{*}, complete headlines in the current buffer so that they
  14752. can be used in search links like @samp{[[*find this headline]]}.
  14753. @item
  14754. After @samp{:} in a headline, complete tags. The list of tags is taken
  14755. from the variable @code{org-tag-alist} (possibly set through the
  14756. @samp{#+TAGS} in-buffer option, @pxref{Setting tags}), or it is created
  14757. dynamically from all tags used in the current buffer.
  14758. @item
  14759. After @samp{:} and not in a headline, complete property keys. The list
  14760. of keys is constructed dynamically from all keys used in the current
  14761. buffer.
  14762. @item
  14763. After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}).
  14764. @item
  14765. After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or
  14766. file-specific @samp{OPTIONS}. After option keyword is complete, pressing
  14767. @kbd{M-@key{TAB}} again will insert example settings for that option.
  14768. @item
  14769. After @samp{#+STARTUP: }, complete startup keywords.
  14770. @item
  14771. When the point is anywhere else, complete dictionary words using Ispell.
  14772. @end itemize
  14773. @kindex C-M-i
  14774. If your desktop intercepts the combo @kbd{M-@key{TAB}} to switch windows, use
  14775. @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} as an alternative or customize your
  14776. environment.
  14777. @end table
  14778. @node Easy templates
  14779. @section Easy templates
  14780. @cindex template insertion
  14781. @cindex insertion, of templates
  14782. With just a few keystrokes, Org's easy templates inserts empty pairs of
  14783. structural elements, such as @code{#+BEGIN_SRC} and @code{#+END_SRC}. Easy
  14784. templates use an expansion mechanism, which is native to Org, in a process
  14785. similar to @file{yasnippet} and other Emacs template expansion packages.
  14786. @kbd{<} @kbd{s} @kbd{@key{TAB}} expands to a @samp{src} code block.
  14787. @kbd{<} @kbd{l} @kbd{@key{TAB}} expands to:
  14788. #+BEGIN_EXPORT latex
  14789. #+END_EXPORT
  14790. Org comes with these pre-defined easy templates:
  14791. @multitable @columnfractions 0.1 0.9
  14792. @item @kbd{s} @tab @code{#+BEGIN_SRC ... #+END_SRC}
  14793. @item @kbd{e} @tab @code{#+BEGIN_EXAMPLE ... #+END_EXAMPLE}
  14794. @item @kbd{q} @tab @code{#+BEGIN_QUOTE ... #+END_QUOTE}
  14795. @item @kbd{v} @tab @code{#+BEGIN_VERSE ... #+END_VERSE}
  14796. @item @kbd{c} @tab @code{#+BEGIN_CENTER ... #+END_CENTER}
  14797. @item @kbd{C} @tab @code{#+BEGIN_COMMENT ... #+END_COMMENT}
  14798. @item @kbd{l} @tab @code{#+BEGIN_EXPORT latex ... #+END_EXPORT}
  14799. @item @kbd{L} @tab @code{#+LATEX:}
  14800. @item @kbd{h} @tab @code{#+BEGIN_EXPORT html ... #+END_EXPORT}
  14801. @item @kbd{H} @tab @code{#+HTML:}
  14802. @item @kbd{a} @tab @code{#+BEGIN_EXPORT ascii ... #+END_EXPORT}
  14803. @item @kbd{A} @tab @code{#+ASCII:}
  14804. @item @kbd{i} @tab @code{#+INDEX:} line
  14805. @item @kbd{I} @tab @code{#+INCLUDE:} line
  14806. @end multitable
  14807. More templates can added by customizing the variable
  14808. @code{org-structure-template-alist}, whose docstring has additional details.
  14809. @node Speed keys
  14810. @section Speed keys
  14811. @cindex speed keys
  14812. Single keystrokes can execute custom commands in an Org file when the cursor
  14813. is on a headline. Without the extra burden of a meta or modifier key, Speed
  14814. Keys can speed navigation or execute custom commands. Besides faster
  14815. navigation, Speed Keys may come in handy on small mobile devices that do not
  14816. have full keyboards. Speed Keys may also work on TTY devices known for their
  14817. problems when entering Emacs keychords.
  14818. @vindex org-use-speed-commands
  14819. By default, Org has Speed Keys disabled. To activate Speed Keys, set the
  14820. variable @code{org-use-speed-commands} to a non-@code{nil} value. To trigger
  14821. a Speed Key, the cursor must be at the beginning of an Org headline, before
  14822. any of the stars.
  14823. @vindex org-speed-commands-user
  14824. @findex org-speed-command-help
  14825. Org comes with a pre-defined list of Speed Keys. To add or modify Speed
  14826. Keys, customize the variable, @code{org-speed-commands-user}. For more
  14827. details, see the variable's docstring. With Speed Keys activated, @kbd{M-x
  14828. org-speed-command-help}, or @kbd{?} when cursor is at the beginning of an Org
  14829. headline, shows currently active Speed Keys, including the user-defined ones.
  14830. @node Code evaluation security
  14831. @section Code evaluation and security issues
  14832. Unlike plain text, running code comes with risk. Each @samp{src} code block,
  14833. in terms of risk, is equivalent to an executable file. Org therefore puts a
  14834. few confirmation prompts by default. This is to alert the casual user from
  14835. accidentally running untrusted code.
  14836. For users who do not run code blocks or write code regularly, Org's default
  14837. settings should suffice. However, some users may want to tweak the prompts
  14838. for fewer interruptions. To weigh the risks of automatic execution of code
  14839. blocks, here are some details about code evaluation.
  14840. Org evaluates code in the following circumstances:
  14841. @table @i
  14842. @item Source code blocks
  14843. Org evaluates @samp{src} code blocks in an Org file during export. Org also
  14844. evaluates a @samp{src} code block with the @kbd{C-c C-c} key chord. Users
  14845. exporting or running code blocks must load files only from trusted sources.
  14846. Be wary of customizing variables that remove or alter default security
  14847. measures.
  14848. @defopt org-confirm-babel-evaluate
  14849. When @code{t}, Org prompts the user for confirmation before executing each
  14850. code block. When @code{nil}, Org executes code blocks without prompting the
  14851. user for confirmation. When this option is set to a custom function, Org
  14852. invokes the function with these two arguments: the source code language and
  14853. the body of the code block. The custom function must return either a
  14854. @code{t} or @code{nil}, which determines if the user is prompted. Each
  14855. source code language can be handled separately through this function
  14856. argument.
  14857. @end defopt
  14858. For example, this function enables execution of @samp{ditaa} code +blocks
  14859. without prompting:
  14860. @lisp
  14861. (defun my-org-confirm-babel-evaluate (lang body)
  14862. (not (string= lang "ditaa"))) ; don't ask for ditaa
  14863. (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)
  14864. @end lisp
  14865. @item Following @code{shell} and @code{elisp} links
  14866. Org has two link types that can also directly evaluate code (@pxref{External
  14867. links}). Because such code is not visible, these links have a potential
  14868. risk. Org therefore prompts the user when it encounters such links. The
  14869. customization variables are:
  14870. @defopt org-confirm-shell-link-function
  14871. Function that prompts the user before executing a shell link.
  14872. @end defopt
  14873. @defopt org-confirm-elisp-link-function
  14874. Function that prompts the user before executing an Emacs Lisp link.
  14875. @end defopt
  14876. @item Formulas in tables
  14877. Org executes formulas in tables (@pxref{The spreadsheet}) either through the
  14878. @emph{calc} or the @emph{Emacs Lisp} interpreters.
  14879. @end table
  14880. @node Customization
  14881. @section Customization
  14882. @cindex customization
  14883. @cindex options, for customization
  14884. @cindex variables, for customization
  14885. Org has more than 500 variables for customization. They can be accessed
  14886. through the usual @kbd{M-x org-customize RET} command. Or through the Org
  14887. menu, @code{Org->Customization->Browse Org Group}. Org also has per-file
  14888. settings for some variables (@pxref{In-buffer settings}).
  14889. @node In-buffer settings
  14890. @section Summary of in-buffer settings
  14891. @cindex in-buffer settings
  14892. @cindex special keywords
  14893. In-buffer settings start with @samp{#+}, followed by a keyword, a colon, and
  14894. then a word for each setting. Org accepts multiple settings on the same
  14895. line. Org also accepts multiple lines for a keyword. This manual describes
  14896. these settings throughout. A summary follows here.
  14897. @kbd{C-c C-c} activates any changes to the in-buffer settings. Closing and
  14898. reopening the Org file in Emacs also activates the changes.
  14899. @vindex org-archive-location
  14900. @table @kbd
  14901. @item #+ARCHIVE: %s_done::
  14902. Sets the archive location of the agenda file. This location applies to the
  14903. lines until the next @samp{#+ARCHIVE} line, if any, in the Org file. The
  14904. first archive location in the Org file also applies to any entries before it.
  14905. The corresponding variable is @code{org-archive-location}.
  14906. @item #+CATEGORY:
  14907. Sets the category of the agenda file, which applies to the entire document.
  14908. @item #+COLUMNS: %25ITEM ...
  14909. @cindex property, COLUMNS
  14910. Sets the default format for columns view. Org uses this format for column
  14911. views where there is no @code{COLUMNS} property.
  14912. @item #+CONSTANTS: name1=value1 ...
  14913. @vindex org-table-formula-constants
  14914. @vindex org-table-formula
  14915. Set file-local values for constants that table formulas can use. This line
  14916. sets the local variable @code{org-table-formula-constants-local}. The global
  14917. version of this variable is @code{org-table-formula-constants}.
  14918. @item #+FILETAGS: :tag1:tag2:tag3:
  14919. Set tags that all entries in the file will inherit from here, including the
  14920. top-level entries.
  14921. @item #+LINK: linkword replace
  14922. @vindex org-link-abbrev-alist
  14923. Each line specifies one abbreviation for one link. Use multiple
  14924. @code{#+LINK:} lines for more, @pxref{Link abbreviations}. The corresponding
  14925. variable is @code{org-link-abbrev-alist}.
  14926. @item #+PRIORITIES: highest lowest default
  14927. @vindex org-highest-priority
  14928. @vindex org-lowest-priority
  14929. @vindex org-default-priority
  14930. This line sets the limits and the default for the priorities. All three
  14931. must be either letters A--Z or numbers 0--9. The highest priority must
  14932. have a lower ASCII number than the lowest priority.
  14933. @item #+PROPERTY: Property_Name Value
  14934. This line sets a default inheritance value for entries in the current
  14935. buffer, most useful for specifying the allowed values of a property.
  14936. @cindex #+SETUPFILE
  14937. @item #+SETUPFILE: file or URL
  14938. The setup file or a URL pointing to such file is for additional in-buffer
  14939. settings. Org loads this file and parses it for any settings in it only when
  14940. Org opens the main file. If URL is specified, the contents are downloaded
  14941. and stored in a temporary file cache. @kbd{C-c C-c} on the settings line
  14942. will parse and load the file, and also reset the temporary file cache. Org
  14943. also parses and loads the document during normal exporting process. Org
  14944. parses the contents of this document as if it was included in the buffer. It
  14945. can be another Org file. To visit the file (not a URL), @kbd{C-c '} while
  14946. the cursor is on the line with the file name.
  14947. @item #+STARTUP:
  14948. @cindex #+STARTUP
  14949. Startup options Org uses when first visiting a file.
  14950. The first set of options deals with the initial visibility of the outline
  14951. tree. The corresponding variable for global default settings is
  14952. @code{org-startup-folded} with a default value of @code{t}, which is the same
  14953. as @code{overview}.
  14954. @vindex org-startup-folded
  14955. @cindex @code{overview}, STARTUP keyword
  14956. @cindex @code{content}, STARTUP keyword
  14957. @cindex @code{showall}, STARTUP keyword
  14958. @cindex @code{showeverything}, STARTUP keyword
  14959. @example
  14960. overview @r{top-level headlines only}
  14961. content @r{all headlines}
  14962. showall @r{no folding of any entries}
  14963. showeverything @r{show even drawer contents}
  14964. @end example
  14965. @vindex org-startup-indented
  14966. @cindex @code{indent}, STARTUP keyword
  14967. @cindex @code{noindent}, STARTUP keyword
  14968. Dynamic virtual indentation is controlled by the variable
  14969. @code{org-startup-indented}
  14970. @example
  14971. indent @r{start with @code{org-indent-mode} turned on}
  14972. noindent @r{start with @code{org-indent-mode} turned off}
  14973. @end example
  14974. @vindex org-startup-align-all-tables
  14975. Aligns tables consistently upon visiting a file; useful for restoring
  14976. narrowed table columns. The corresponding variable is
  14977. @code{org-startup-align-all-tables} with @code{nil} as default value.
  14978. @cindex @code{align}, STARTUP keyword
  14979. @cindex @code{noalign}, STARTUP keyword
  14980. @example
  14981. align @r{align all tables}
  14982. noalign @r{don't align tables on startup}
  14983. @end example
  14984. @vindex org-startup-with-inline-images
  14985. Whether Org should automatically display inline images. The corresponding
  14986. variable is @code{org-startup-with-inline-images}, with a default value
  14987. @code{nil} to avoid delays when visiting a file.
  14988. @cindex @code{inlineimages}, STARTUP keyword
  14989. @cindex @code{noinlineimages}, STARTUP keyword
  14990. @example
  14991. inlineimages @r{show inline images}
  14992. noinlineimages @r{don't show inline images on startup}
  14993. @end example
  14994. @vindex org-startup-with-latex-preview
  14995. Whether Org should automatically convert @LaTeX{} fragments to images. The
  14996. variable @code{org-startup-with-latex-preview}, which controls this setting,
  14997. is set to @code{nil} by default to avoid startup delays.
  14998. @cindex @code{latexpreview}, STARTUP keyword
  14999. @cindex @code{nolatexpreview}, STARTUP keyword
  15000. @example
  15001. latexpreview @r{preview @LaTeX{} fragments}
  15002. nolatexpreview @r{don't preview @LaTeX{} fragments}
  15003. @end example
  15004. @vindex org-log-done
  15005. @vindex org-log-note-clock-out
  15006. @vindex org-log-repeat
  15007. Logging the closing and reopening of TODO items and clock intervals can be
  15008. configured using these options (see variables @code{org-log-done},
  15009. @code{org-log-note-clock-out} and @code{org-log-repeat})
  15010. @cindex @code{logdone}, STARTUP keyword
  15011. @cindex @code{lognotedone}, STARTUP keyword
  15012. @cindex @code{nologdone}, STARTUP keyword
  15013. @cindex @code{lognoteclock-out}, STARTUP keyword
  15014. @cindex @code{nolognoteclock-out}, STARTUP keyword
  15015. @cindex @code{logrepeat}, STARTUP keyword
  15016. @cindex @code{lognoterepeat}, STARTUP keyword
  15017. @cindex @code{nologrepeat}, STARTUP keyword
  15018. @cindex @code{logreschedule}, STARTUP keyword
  15019. @cindex @code{lognotereschedule}, STARTUP keyword
  15020. @cindex @code{nologreschedule}, STARTUP keyword
  15021. @cindex @code{logredeadline}, STARTUP keyword
  15022. @cindex @code{lognoteredeadline}, STARTUP keyword
  15023. @cindex @code{nologredeadline}, STARTUP keyword
  15024. @cindex @code{logrefile}, STARTUP keyword
  15025. @cindex @code{lognoterefile}, STARTUP keyword
  15026. @cindex @code{nologrefile}, STARTUP keyword
  15027. @cindex @code{logdrawer}, STARTUP keyword
  15028. @cindex @code{nologdrawer}, STARTUP keyword
  15029. @cindex @code{logstatesreversed}, STARTUP keyword
  15030. @cindex @code{nologstatesreversed}, STARTUP keyword
  15031. @example
  15032. logdone @r{record a timestamp when an item is marked DONE}
  15033. lognotedone @r{record timestamp and a note when DONE}
  15034. nologdone @r{don't record when items are marked DONE}
  15035. logrepeat @r{record a time when reinstating a repeating item}
  15036. lognoterepeat @r{record a note when reinstating a repeating item}
  15037. nologrepeat @r{do not record when reinstating repeating item}
  15038. lognoteclock-out @r{record a note when clocking out}
  15039. nolognoteclock-out @r{don't record a note when clocking out}
  15040. logreschedule @r{record a timestamp when scheduling time changes}
  15041. lognotereschedule @r{record a note when scheduling time changes}
  15042. nologreschedule @r{do not record when a scheduling date changes}
  15043. logredeadline @r{record a timestamp when deadline changes}
  15044. lognoteredeadline @r{record a note when deadline changes}
  15045. nologredeadline @r{do not record when a deadline date changes}
  15046. logrefile @r{record a timestamp when refiling}
  15047. lognoterefile @r{record a note when refiling}
  15048. nologrefile @r{do not record when refiling}
  15049. logdrawer @r{store log into drawer}
  15050. nologdrawer @r{store log outside of drawer}
  15051. logstatesreversed @r{reverse the order of states notes}
  15052. nologstatesreversed @r{do not reverse the order of states notes}
  15053. @end example
  15054. @vindex org-hide-leading-stars
  15055. @vindex org-odd-levels-only
  15056. These options hide leading stars in outline headings, and indent outlines.
  15057. The corresponding variables are @code{org-hide-leading-stars} and
  15058. @code{org-odd-levels-only}, both with a default setting of @code{nil}
  15059. (meaning @code{showstars} and @code{oddeven}).
  15060. @cindex @code{hidestars}, STARTUP keyword
  15061. @cindex @code{showstars}, STARTUP keyword
  15062. @cindex @code{odd}, STARTUP keyword
  15063. @cindex @code{even}, STARTUP keyword
  15064. @example
  15065. hidestars @r{hide all stars on the headline except one.}
  15066. showstars @r{show all stars on the headline}
  15067. indent @r{virtual indents according to the outline level}
  15068. noindent @r{no virtual indents}
  15069. odd @r{show odd outline levels only (1,3,...)}
  15070. oddeven @r{show all outline levels}
  15071. @end example
  15072. @vindex org-put-time-stamp-overlays
  15073. @vindex org-time-stamp-overlay-formats
  15074. To turn on custom format overlays over timestamps (variables
  15075. @code{org-put-time-stamp-overlays} and
  15076. @code{org-time-stamp-overlay-formats}), use
  15077. @cindex @code{customtime}, STARTUP keyword
  15078. @example
  15079. customtime @r{overlay custom time format}
  15080. @end example
  15081. @vindex constants-unit-system
  15082. The following options influence the table spreadsheet (variable
  15083. @code{constants-unit-system}).
  15084. @cindex @code{constcgs}, STARTUP keyword
  15085. @cindex @code{constSI}, STARTUP keyword
  15086. @example
  15087. constcgs @r{@file{constants.el} should use the c-g-s unit system}
  15088. constSI @r{@file{constants.el} should use the SI unit system}
  15089. @end example
  15090. @vindex org-footnote-define-inline
  15091. @vindex org-footnote-auto-label
  15092. @vindex org-footnote-auto-adjust
  15093. For footnote settings, use the following keywords. The corresponding
  15094. variables are @code{org-footnote-define-inline},
  15095. @code{org-footnote-auto-label}, and @code{org-footnote-auto-adjust}.
  15096. @cindex @code{fninline}, STARTUP keyword
  15097. @cindex @code{nofninline}, STARTUP keyword
  15098. @cindex @code{fnlocal}, STARTUP keyword
  15099. @cindex @code{fnprompt}, STARTUP keyword
  15100. @cindex @code{fnauto}, STARTUP keyword
  15101. @cindex @code{fnconfirm}, STARTUP keyword
  15102. @cindex @code{fnplain}, STARTUP keyword
  15103. @cindex @code{fnadjust}, STARTUP keyword
  15104. @cindex @code{nofnadjust}, STARTUP keyword
  15105. @example
  15106. fninline @r{define footnotes inline}
  15107. fnnoinline @r{define footnotes in separate section}
  15108. fnlocal @r{define footnotes near first reference, but not inline}
  15109. fnprompt @r{prompt for footnote labels}
  15110. fnauto @r{create @code{[fn:1]}-like labels automatically (default)}
  15111. fnconfirm @r{offer automatic label for editing or confirmation}
  15112. fnplain @r{create @code{[1]}-like labels automatically}
  15113. fnadjust @r{automatically renumber and sort footnotes}
  15114. nofnadjust @r{do not renumber and sort automatically}
  15115. @end example
  15116. @cindex org-hide-block-startup
  15117. To hide blocks on startup, use these keywords. The corresponding variable is
  15118. @code{org-hide-block-startup}.
  15119. @cindex @code{hideblocks}, STARTUP keyword
  15120. @cindex @code{nohideblocks}, STARTUP keyword
  15121. @example
  15122. hideblocks @r{Hide all begin/end blocks on startup}
  15123. nohideblocks @r{Do not hide blocks on startup}
  15124. @end example
  15125. @cindex org-pretty-entities
  15126. The display of entities as UTF-8 characters is governed by the variable
  15127. @code{org-pretty-entities} and the keywords
  15128. @cindex @code{entitiespretty}, STARTUP keyword
  15129. @cindex @code{entitiesplain}, STARTUP keyword
  15130. @example
  15131. entitiespretty @r{Show entities as UTF-8 characters where possible}
  15132. entitiesplain @r{Leave entities plain}
  15133. @end example
  15134. @item #+TAGS: TAG1(c1) TAG2(c2)
  15135. @vindex org-tag-alist
  15136. These lines specify valid tags for this file. Org accepts multiple tags
  15137. lines. Tags could correspond to the @emph{fast tag selection} keys. The
  15138. corresponding variable is @code{org-tag-alist}.
  15139. @cindex #+TBLFM
  15140. @item #+TBLFM:
  15141. This line is for formulas for the table directly above. A table can have
  15142. multiple @samp{#+TBLFM:} lines. On table recalculation, Org applies only the
  15143. first @samp{#+TBLFM:} line. For details see @ref{Using multiple #+TBLFM
  15144. lines} in @ref{Editing and debugging formulas}.
  15145. @item #+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+DATE:,
  15146. @itemx #+OPTIONS:, #+BIND:,
  15147. @itemx #+SELECT_TAGS:, #+EXCLUDE_TAGS:
  15148. These lines provide settings for exporting files. For more details see
  15149. @ref{Export settings}.
  15150. @item #+TODO: #+SEQ_TODO: #+TYP_TODO:
  15151. @vindex org-todo-keywords
  15152. These lines set the TODO keywords and their significance to the current file.
  15153. The corresponding variable is @code{org-todo-keywords}.
  15154. @end table
  15155. @node The very busy C-c C-c key
  15156. @section The very busy C-c C-c key
  15157. @kindex C-c C-c
  15158. @cindex C-c C-c, overview
  15159. The @kbd{C-c C-c} key in Org serves many purposes depending on the context.
  15160. It is probably the most over-worked, multi-purpose key combination in Org.
  15161. Its uses are well-documented through out this manual, but here is a
  15162. consolidated list for easy reference.
  15163. @itemize @minus
  15164. @item
  15165. If any highlights shown in the buffer from the creation of a sparse tree, or
  15166. from clock display, remove such highlights.
  15167. @item
  15168. If the cursor is in one of the special @code{#+KEYWORD} lines, scan the
  15169. buffer for these lines and update the information. Also reset the Org file
  15170. cache used to temporary store the contents of URLs used as values for
  15171. keywords like @code{#+SETUPFILE}.
  15172. @item
  15173. If the cursor is inside a table, realign the table. The table realigns even
  15174. if automatic table editor is turned off.
  15175. @item
  15176. If the cursor is on a @code{#+TBLFM} line, re-apply the formulas to
  15177. the entire table.
  15178. @item
  15179. If the current buffer is a capture buffer, close the note and file it. With
  15180. a prefix argument, also jump to the target location after saving the note.
  15181. @item
  15182. If the cursor is on a @code{<<<target>>>}, update radio targets and
  15183. corresponding links in this buffer.
  15184. @item
  15185. If the cursor is on a property line or at the start or end of a property
  15186. drawer, offer property commands.
  15187. @item
  15188. If the cursor is at a footnote reference, go to the corresponding
  15189. definition, and @emph{vice versa}.
  15190. @item
  15191. If the cursor is on a statistics cookie, update it.
  15192. @item
  15193. If the cursor is in a plain list item with a checkbox, toggle the status
  15194. of the checkbox.
  15195. @item
  15196. If the cursor is on a numbered item in a plain list, renumber the
  15197. ordered list.
  15198. @item
  15199. If the cursor is on the @code{#+BEGIN} line of a dynamic block, the
  15200. block is updated.
  15201. @item
  15202. If the cursor is at a timestamp, fix the day name in the timestamp.
  15203. @end itemize
  15204. @node Clean view
  15205. @section A cleaner outline view
  15206. @cindex hiding leading stars
  15207. @cindex dynamic indentation
  15208. @cindex odd-levels-only outlines
  15209. @cindex clean outline view
  15210. Org's default outline with stars and no indents can become too cluttered for
  15211. short documents. For @emph{book-like} long documents, the effect is not as
  15212. noticeable. Org provides an alternate stars and indentation scheme, as shown
  15213. on the right in the following table. It uses only one star and indents text
  15214. to line with the heading:
  15215. @example
  15216. @group
  15217. * Top level headline | * Top level headline
  15218. ** Second level | * Second level
  15219. *** 3rd level | * 3rd level
  15220. some text | some text
  15221. *** 3rd level | * 3rd level
  15222. more text | more text
  15223. * Another top level headline | * Another top level headline
  15224. @end group
  15225. @end example
  15226. @noindent
  15227. To turn this mode on, use the minor mode, @code{org-indent-mode}. Text lines
  15228. that are not headlines are prefixed with spaces to vertically align with the
  15229. headline text@footnote{The @code{org-indent-mode} also sets the
  15230. @code{wrap-prefix} correctly for indenting and wrapping long lines of
  15231. headlines or text. This minor mode handles @code{visual-line-mode} and
  15232. directly applied settings through @code{word-wrap}.}.
  15233. To make more horizontal space, the headlines are shifted by two stars. This
  15234. can be configured by the @code{org-indent-indentation-per-level} variable.
  15235. Only one star on each headline is visible, the rest are masked with the same
  15236. font color as the background. This font face can be configured with the
  15237. @code{org-hide} variable.
  15238. Note that turning on @code{org-indent-mode} sets
  15239. @code{org-hide-leading-stars} to @code{t} and @code{org-adapt-indentation} to
  15240. @code{nil}; @samp{2.} below shows how this works.
  15241. To globally turn on @code{org-indent-mode} for all files, customize the
  15242. variable @code{org-startup-indented}.
  15243. To turn on indenting for individual files, use @code{#+STARTUP} option as
  15244. follows:
  15245. @example
  15246. #+STARTUP: indent
  15247. @end example
  15248. Indent on startup makes Org use hard spaces to align text with headings as
  15249. shown in examples below.
  15250. @enumerate
  15251. @item
  15252. @emph{Indentation of text below headlines}@*
  15253. Indent text to align with the headline.
  15254. @example
  15255. *** 3rd level
  15256. more text, now indented
  15257. @end example
  15258. @vindex org-adapt-indentation
  15259. Org adapts indentations with paragraph filling, line wrapping, and structure
  15260. editing@footnote{Also see the variable @code{org-adapt-indentation}.}.
  15261. @item
  15262. @vindex org-hide-leading-stars
  15263. @emph{Hiding leading stars}@* Org can make leading stars invisible. For
  15264. global preference, configure the variable @code{org-hide-leading-stars}. For
  15265. per-file preference, use these file @code{#+STARTUP} options:
  15266. @example
  15267. #+STARTUP: hidestars
  15268. #+STARTUP: showstars
  15269. @end example
  15270. With stars hidden, the tree is shown as:
  15271. @example
  15272. @group
  15273. * Top level headline
  15274. * Second level
  15275. * 3rd level
  15276. ...
  15277. @end group
  15278. @end example
  15279. @noindent
  15280. @vindex org-hide @r{(face)}
  15281. Because Org makes the font color same as the background color to hide to
  15282. stars, sometimes @code{org-hide} face may need tweaking to get the effect
  15283. right. For some black and white combinations, @code{grey90} on a white
  15284. background might mask the stars better.
  15285. @item
  15286. @vindex org-odd-levels-only
  15287. Using stars for only odd levels, 1, 3, 5, @dots{}, can also clean up the
  15288. clutter. This removes two stars from each level@footnote{Because
  15289. @samp{LEVEL=2} has 3 stars, @samp{LEVEL=3} has 4 stars, and so on}. For Org
  15290. to properly handle this cleaner structure during edits and exports, configure
  15291. the variable @code{org-odd-levels-only}. To set this per-file, use either
  15292. one of the following lines:
  15293. @example
  15294. #+STARTUP: odd
  15295. #+STARTUP: oddeven
  15296. @end example
  15297. To switch between single and double stars layouts, use @kbd{M-x
  15298. org-convert-to-odd-levels RET} and @kbd{M-x org-convert-to-oddeven-levels}.
  15299. @end enumerate
  15300. @node TTY keys
  15301. @section Using Org on a tty
  15302. @cindex tty key bindings
  15303. Org provides alternative key bindings for TTY and modern mobile devices that
  15304. cannot handle cursor keys and complex modifier key chords. Some of these
  15305. workarounds may be more cumbersome than necessary. Users should look into
  15306. customizing these further based on their usage needs. For example, the
  15307. normal @kbd{S-@key{cursor}} for editing timestamp might be better with
  15308. @kbd{C-c .} chord.
  15309. @multitable @columnfractions 0.15 0.2 0.1 0.2
  15310. @item @b{Default} @tab @b{Alternative 1} @tab @b{Speed key} @tab @b{Alternative 2}
  15311. @item @kbd{S-@key{TAB}} @tab @kbd{C-u @key{TAB}} @tab @kbd{C} @tab
  15312. @item @kbd{M-@key{left}} @tab @kbd{C-c C-x l} @tab @kbd{l} @tab @kbd{@key{Esc} @key{left}}
  15313. @item @kbd{M-S-@key{left}} @tab @kbd{C-c C-x L} @tab @kbd{L} @tab
  15314. @item @kbd{M-@key{right}} @tab @kbd{C-c C-x r} @tab @kbd{r} @tab @kbd{@key{Esc} @key{right}}
  15315. @item @kbd{M-S-@key{right}} @tab @kbd{C-c C-x R} @tab @kbd{R} @tab
  15316. @item @kbd{M-@key{up}} @tab @kbd{C-c C-x u} @tab @kbd{ } @tab @kbd{@key{Esc} @key{up}}
  15317. @item @kbd{M-S-@key{up}} @tab @kbd{C-c C-x U} @tab @kbd{U} @tab
  15318. @item @kbd{M-@key{down}} @tab @kbd{C-c C-x d} @tab @kbd{ } @tab @kbd{@key{Esc} @key{down}}
  15319. @item @kbd{M-S-@key{down}} @tab @kbd{C-c C-x D} @tab @kbd{D} @tab
  15320. @item @kbd{S-@key{RET}} @tab @kbd{C-c C-x c} @tab @kbd{ } @tab
  15321. @item @kbd{M-@key{RET}} @tab @kbd{C-c C-x m} @tab @kbd{ } @tab @kbd{@key{Esc} @key{RET}}
  15322. @item @kbd{M-S-@key{RET}} @tab @kbd{C-c C-x M} @tab @kbd{ } @tab
  15323. @item @kbd{S-@key{left}} @tab @kbd{C-c @key{left}} @tab @kbd{ } @tab
  15324. @item @kbd{S-@key{right}} @tab @kbd{C-c @key{right}} @tab @kbd{ } @tab
  15325. @item @kbd{S-@key{up}} @tab @kbd{C-c @key{up}} @tab @kbd{ } @tab
  15326. @item @kbd{S-@key{down}} @tab @kbd{C-c @key{down}} @tab @kbd{ } @tab
  15327. @item @kbd{C-S-@key{left}} @tab @kbd{C-c C-x @key{left}} @tab @kbd{ } @tab
  15328. @item @kbd{C-S-@key{right}} @tab @kbd{C-c C-x @key{right}} @tab @kbd{ } @tab
  15329. @end multitable
  15330. @node Interaction
  15331. @section Interaction with other packages
  15332. @cindex packages, interaction with other
  15333. Org's compatibility and the level of interaction with other Emacs packages
  15334. are documented here.
  15335. @menu
  15336. * Cooperation:: Packages Org cooperates with
  15337. * Conflicts:: Packages that lead to conflicts
  15338. @end menu
  15339. @node Cooperation
  15340. @subsection Packages that Org cooperates with
  15341. @table @asis
  15342. @cindex @file{calc.el}
  15343. @cindex Gillespie, Dave
  15344. @item @file{calc.el} by Dave Gillespie
  15345. Org uses the Calc package for tables to implement spreadsheet functionality
  15346. (@pxref{The spreadsheet}). Org also uses Calc for embedded calculations.
  15347. @xref{Embedded Mode, , Embedded Mode, calc, GNU Emacs Calc Manual}.
  15348. @item @file{constants.el} by Carsten Dominik
  15349. @cindex @file{constants.el}
  15350. @cindex Dominik, Carsten
  15351. @vindex org-table-formula-constants
  15352. Org can use names for constants in formulas in tables. Org can also use
  15353. calculation suffixes for units, such as @samp{M} for @samp{Mega}. For a
  15354. standard collection of such constants, install the @file{constants} package.
  15355. Install version 2.0 of this package, available at
  15356. @url{https://staff.fnwi.uva.nl/c.dominik/Tools/}. Org checks if the function
  15357. @code{constants-get} has been autoloaded. Installation instructions are in
  15358. the file, @file{constants.el}.
  15359. @item @file{cdlatex.el} by Carsten Dominik
  15360. @cindex @file{cdlatex.el}
  15361. @cindex Dominik, Carsten
  15362. Org mode can use CD@LaTeX{} package to efficiently enter @LaTeX{} fragments
  15363. into Org files (@pxref{CDLaTeX mode}).
  15364. @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg
  15365. @cindex @file{imenu.el}
  15366. Imenu creates dynamic menus based on an index of items in a file. Org mode
  15367. supports Imenu menus. Enable it with a mode hook as follows:
  15368. @lisp
  15369. (add-hook 'org-mode-hook
  15370. (lambda () (imenu-add-to-menubar "Imenu")))
  15371. @end lisp
  15372. @vindex org-imenu-depth
  15373. By default the Imenu index is two levels deep. Change the index depth using
  15374. thes variable, @code{org-imenu-depth}.
  15375. @item @file{speedbar.el} by Eric M. Ludlam
  15376. @cindex @file{speedbar.el}
  15377. @cindex Ludlam, Eric M.
  15378. Speedbar package creates a special Emacs frame for displaying files and index
  15379. items in files. Org mode supports Speedbar; users can drill into Org files
  15380. directly from the Speedbar. The @kbd{<} in the Speedbar frame tweaks the
  15381. agenda commands to that file or to a subtree.
  15382. @cindex @file{table.el}
  15383. @item @file{table.el} by Takaaki Ota
  15384. @kindex C-c C-c
  15385. @cindex table editor, @file{table.el}
  15386. @cindex @file{table.el}
  15387. @cindex Ota, Takaaki
  15388. Complex ASCII tables with automatic line wrapping, column- and row-spanning,
  15389. and alignment can be created using the Emacs table package by Takaaki Ota.
  15390. Org mode recognizes such tables and export them properly. @kbd{C-c '} to
  15391. edit these tables in a special buffer, much like Org's @samp{src} code
  15392. blocks. Because of interference with other Org mode functionality, Takaaki
  15393. Ota tables cannot be edited directly in the Org buffer.
  15394. @table @kbd
  15395. @orgcmd{C-c ',org-edit-special}
  15396. Edit a @file{table.el} table. Works when the cursor is in a table.el table.
  15397. @c
  15398. @orgcmd{C-c ~,org-table-create-with-table.el}
  15399. Insert a @file{table.el} table. If there is already a table at point, this
  15400. command converts it between the @file{table.el} format and the Org mode
  15401. format. See the documentation string of the command @code{org-convert-table}
  15402. for details.
  15403. @end table
  15404. @end table
  15405. @node Conflicts
  15406. @subsection Packages that conflict with Org mode
  15407. @table @asis
  15408. @cindex @code{shift-selection-mode}
  15409. @vindex org-support-shift-select
  15410. In Emacs, @code{shift-selection-mode} combines cursor motions with shift key
  15411. to enlarge regions. Emacs sets this mode by default. This conflicts with
  15412. Org's use of @kbd{S-@key{cursor}} commands to change timestamps, TODO
  15413. keywords, priorities, and item bullet types, etc. Since @kbd{S-@key{cursor}}
  15414. commands outside of specific contexts don't do anything, Org offers the
  15415. variable @code{org-support-shift-select} for customization. Org mode
  15416. accommodates shift selection by (i) making it available outside of the
  15417. special contexts where special commands apply, and (ii) extending an
  15418. existing active region even if the cursor moves across a special context.
  15419. @item @file{CUA.el} by Kim. F. Storm
  15420. @cindex @file{CUA.el}
  15421. @cindex Storm, Kim. F.
  15422. @vindex org-replace-disputed-keys
  15423. Org key bindings conflict with @kbd{S-<cursor>} keys used by CUA mode. For
  15424. Org to relinquish these bindings to CUA mode, configure the variable
  15425. @code{org-replace-disputed-keys}. When set, Org moves the following key
  15426. bindings in Org files, and in the agenda buffer (but not during date
  15427. selection).
  15428. @example
  15429. S-UP @result{} M-p S-DOWN @result{} M-n
  15430. S-LEFT @result{} M-- S-RIGHT @result{} M-+
  15431. C-S-LEFT @result{} M-S-- C-S-RIGHT @result{} M-S-+
  15432. @end example
  15433. @vindex org-disputed-keys
  15434. Yes, these are unfortunately more difficult to remember. To define a
  15435. different replacement keys, look at the variable @code{org-disputed-keys}.
  15436. @item @file{ecomplete.el} by Lars Magne Ingebrigtsen @email{larsi@@gnus.org}
  15437. @cindex @file{ecomplete.el}
  15438. Ecomplete provides ``electric'' address completion in address header
  15439. lines in message buffers. Sadly Orgtbl mode cuts ecompletes power
  15440. supply: No completion happens when Orgtbl mode is enabled in message
  15441. buffers while entering text in address header lines. If one wants to
  15442. use ecomplete one should @emph{not} follow the advice to automagically
  15443. turn on Orgtbl mode in message buffers (see @ref{Orgtbl mode}), but
  15444. instead---after filling in the message headers---turn on Orgtbl mode
  15445. manually when needed in the messages body.
  15446. @item @file{filladapt.el} by Kyle Jones
  15447. @cindex @file{filladapt.el}
  15448. Org mode tries to do the right thing when filling paragraphs, list items and
  15449. other elements. Many users reported problems using both @file{filladapt.el}
  15450. and Org mode, so a safe thing to do is to disable filladapt like this:
  15451. @lisp
  15452. (add-hook 'org-mode-hook 'turn-off-filladapt-mode)
  15453. @end lisp
  15454. @item @file{yasnippet.el}
  15455. @cindex @file{yasnippet.el}
  15456. The way Org mode binds the @key{TAB} key (binding to @code{[tab]} instead of
  15457. @code{"\t"}) overrules YASnippet's access to this key. The following code
  15458. fixed this problem:
  15459. @lisp
  15460. (add-hook 'org-mode-hook
  15461. (lambda ()
  15462. (setq-local yas/trigger-key [tab])
  15463. (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))
  15464. @end lisp
  15465. The latest version of yasnippet doesn't play well with Org mode. If the
  15466. above code does not fix the conflict, first define the following function:
  15467. @lisp
  15468. (defun yas/org-very-safe-expand ()
  15469. (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
  15470. @end lisp
  15471. Then tell Org mode to use that function:
  15472. @lisp
  15473. (add-hook 'org-mode-hook
  15474. (lambda ()
  15475. (make-variable-buffer-local 'yas/trigger-key)
  15476. (setq yas/trigger-key [tab])
  15477. (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
  15478. (define-key yas/keymap [tab] 'yas/next-field)))
  15479. @end lisp
  15480. @item @file{windmove.el} by Hovav Shacham
  15481. @cindex @file{windmove.el}
  15482. This package also uses the @kbd{S-<cursor>} keys, so everything written
  15483. in the paragraph above about CUA mode also applies here. If you want make
  15484. the windmove function active in locations where Org mode does not have
  15485. special functionality on @kbd{S-@key{cursor}}, add this to your
  15486. configuration:
  15487. @lisp
  15488. ;; Make windmove work in org-mode:
  15489. (add-hook 'org-shiftup-final-hook 'windmove-up)
  15490. (add-hook 'org-shiftleft-final-hook 'windmove-left)
  15491. (add-hook 'org-shiftdown-final-hook 'windmove-down)
  15492. (add-hook 'org-shiftright-final-hook 'windmove-right)
  15493. @end lisp
  15494. @item @file{viper.el} by Michael Kifer
  15495. @cindex @file{viper.el}
  15496. @kindex C-c /
  15497. Viper uses @kbd{C-c /} and therefore makes this key not access the
  15498. corresponding Org mode command @code{org-sparse-tree}. You need to find
  15499. another key for this command, or override the key in
  15500. @code{viper-vi-global-user-map} with
  15501. @lisp
  15502. (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)
  15503. @end lisp
  15504. @end table
  15505. @node org-crypt
  15506. @section org-crypt.el
  15507. @cindex @file{org-crypt.el}
  15508. @cindex @code{org-decrypt-entry}
  15509. Org crypt encrypts the text of an Org entry, but not the headline, or
  15510. properties. Org crypt uses the Emacs EasyPG library to encrypt and decrypt.
  15511. Any text below a headline that has a @samp{:crypt:} tag will be automatically
  15512. be encrypted when the file is saved. To use a different tag, customize the
  15513. @code{org-crypt-tag-matcher} variable.
  15514. Suggested Org crypt settings in Emacs init file:
  15515. @lisp
  15516. (require 'org-crypt)
  15517. (org-crypt-use-before-save-magic)
  15518. (setq org-tags-exclude-from-inheritance (quote ("crypt")))
  15519. (setq org-crypt-key nil)
  15520. ;; GPG key to use for encryption
  15521. ;; Either the Key ID or set to nil to use symmetric encryption.
  15522. (setq auto-save-default nil)
  15523. ;; Auto-saving does not cooperate with org-crypt.el: so you need
  15524. ;; to turn it off if you plan to use org-crypt.el quite often.
  15525. ;; Otherwise, you'll get an (annoying) message each time you
  15526. ;; start Org.
  15527. ;; To turn it off only locally, you can insert this:
  15528. ;;
  15529. ;; # -*- buffer-auto-save-file-name: nil; -*-
  15530. @end lisp
  15531. Excluding the crypt tag from inheritance prevents encrypting previously
  15532. encrypted text.
  15533. @node Hacking
  15534. @appendix Hacking
  15535. @cindex hacking
  15536. This appendix covers some areas where users can extend the functionality of
  15537. Org.
  15538. @menu
  15539. * Hooks:: How to reach into Org's internals
  15540. * Add-on packages:: Available extensions
  15541. * Adding hyperlink types:: New custom link types
  15542. * Adding export back-ends:: How to write new export back-ends
  15543. * Context-sensitive commands:: How to add functionality to such commands
  15544. * Tables in arbitrary syntax:: Orgtbl for @LaTeX{} and other programs
  15545. * Dynamic blocks:: Automatically filled blocks
  15546. * Special agenda views:: Customized views
  15547. * Speeding up your agendas:: Tips on how to speed up your agendas
  15548. * Extracting agenda information:: Post-processing of agenda information
  15549. * Using the property API:: Writing programs that use entry properties
  15550. * Using the mapping API:: Mapping over all or selected entries
  15551. @end menu
  15552. @node Hooks
  15553. @section Hooks
  15554. @cindex hooks
  15555. Org has a large number of hook variables for adding functionality. This
  15556. appendix illustrates using a few. A complete list of hooks with
  15557. documentation is maintained by the Worg project at
  15558. @uref{http://orgmode.org/worg/doc.html#hooks}.
  15559. @node Add-on packages
  15560. @section Add-on packages
  15561. @cindex add-on packages
  15562. Various authors wrote a large number of add-on packages for Org.
  15563. These packages are not part of Emacs, but they are distributed as contributed
  15564. packages with the separate release available at @uref{http://orgmode.org}.
  15565. See the @file{contrib/README} file in the source code directory for a list of
  15566. contributed files. Worg page with more information is at:
  15567. @uref{http://orgmode.org/worg/org-contrib/}.
  15568. @node Adding hyperlink types
  15569. @section Adding hyperlink types
  15570. @cindex hyperlinks, adding new types
  15571. Org has many built-in hyperlink types (@pxref{Hyperlinks}), and an interface
  15572. for adding new link types. The example file, @file{org-man.el}, shows the
  15573. process of adding Org links to Unix man pages, which look like this:
  15574. @samp{[[man:printf][The printf manpage]]}:
  15575. @lisp
  15576. ;;; org-man.el - Support for links to manpages in Org
  15577. (require 'org)
  15578. (org-add-link-type "man" 'org-man-open)
  15579. (add-hook 'org-store-link-functions 'org-man-store-link)
  15580. (defcustom org-man-command 'man
  15581. "The Emacs command to be used to display a man page."
  15582. :group 'org-link
  15583. :type '(choice (const man) (const woman)))
  15584. (defun org-man-open (path)
  15585. "Visit the manpage on PATH.
  15586. PATH should be a topic that can be thrown at the man command."
  15587. (funcall org-man-command path))
  15588. (defun org-man-store-link ()
  15589. "Store a link to a manpage."
  15590. (when (memq major-mode '(Man-mode woman-mode))
  15591. ;; This is a man page, we do make this link
  15592. (let* ((page (org-man-get-page-name))
  15593. (link (concat "man:" page))
  15594. (description (format "Manpage for %s" page)))
  15595. (org-store-link-props
  15596. :type "man"
  15597. :link link
  15598. :description description))))
  15599. (defun org-man-get-page-name ()
  15600. "Extract the page name from the buffer name."
  15601. ;; This works for both `Man-mode' and `woman-mode'.
  15602. (if (string-match " \\(\\S-+\\)\\*" (buffer-name))
  15603. (match-string 1 (buffer-name))
  15604. (error "Cannot create link to this man page")))
  15605. (provide 'org-man)
  15606. ;;; org-man.el ends here
  15607. @end lisp
  15608. @noindent
  15609. To activate links to man pages in Org, enter this in the init file:
  15610. @lisp
  15611. (require 'org-man)
  15612. @end lisp
  15613. @noindent
  15614. A review of @file{org-man.el}:
  15615. @enumerate
  15616. @item
  15617. First, @code{(require 'org)} ensures @file{org.el} is loaded.
  15618. @item
  15619. The @code{org-add-link-type} defines a new link type with @samp{man} prefix.
  15620. The call contains the function to call that follows the link type.
  15621. @item
  15622. @vindex org-store-link-functions
  15623. The next line adds a function to @code{org-store-link-functions} that records
  15624. a useful link with the command @kbd{C-c l} in a buffer displaying a man page.
  15625. @end enumerate
  15626. The rest of the file defines necessary variables and functions. First is the
  15627. customization variable @code{org-man-command}. It has two options,
  15628. @code{man} and @code{woman}. Next is a function whose argument is the link
  15629. path, which for man pages is the topic of the man command. To follow the
  15630. link, the function calls the @code{org-man-command} to display the man page.
  15631. @kbd{C-c l} constructs and stores the link.
  15632. @kbd{C-c l} calls the function @code{org-man-store-link}, which first checks
  15633. if the @code{major-mode} is appropriate. If check fails, the function
  15634. returns @code{nil}. Otherwise the function makes a link string by combining
  15635. the @samp{man:} prefix with the man topic. The function then calls
  15636. @code{org-store-link-props} with @code{:type} and @code{:link} properties. A
  15637. @code{:description} property is an optional string that is displayed when the
  15638. function inserts the link in the Org buffer.
  15639. @kbd{C-c C-l} inserts the stored link.
  15640. To define new link types, define a function that implements completion
  15641. support with @kbd{C-c C-l}. This function should not accept any arguments
  15642. but return the appropriate prefix and complete link string.
  15643. @node Adding export back-ends
  15644. @section Adding export back-ends
  15645. @cindex Export, writing back-ends
  15646. Org's export engine makes it easy for writing new back-ends. The framework
  15647. on which the engine was built makes it easy to derive new back-ends from
  15648. existing ones.
  15649. The two main entry points to the export engine are:
  15650. @code{org-export-define-backend} and
  15651. @code{org-export-define-derived-backend}. To grok these functions, see
  15652. @file{ox-latex.el} for an example of defining a new back-end from scratch,
  15653. and @file{ox-beamer.el} for an example of deriving from an existing engine.
  15654. For creating a new back-end from scratch, first set its name as a symbol in
  15655. an alist consisting of elements and export functions. To make the back-end
  15656. visible to the export dispatcher, set @code{:menu-entry} keyword. For export
  15657. options specific to this back-end, set the @code{:options-alist}.
  15658. For creating a new back-end from an existing one, set @code{:translate-alist}
  15659. to an alist of export functions. This alist replaces the parent back-end
  15660. functions.
  15661. For complete documentation, see
  15662. @url{http://orgmode.org/worg/dev/org-export-reference.html, the Org Export
  15663. Reference on Worg}.
  15664. @node Context-sensitive commands
  15665. @section Context-sensitive commands
  15666. @cindex context-sensitive commands, hooks
  15667. @cindex add-ons, context-sensitive commands
  15668. @vindex org-ctrl-c-ctrl-c-hook
  15669. Org has facilities for building context sensitive commands. Authors of Org
  15670. add-ons can tap into this functionality.
  15671. Some Org commands change depending on the context. The most important
  15672. example of this behavior is the @kbd{C-c C-c} (@pxref{The very busy C-c C-c
  15673. key}). Other examples are @kbd{M-cursor} and @kbd{M-S-cursor}.
  15674. These context sensitive commands work by providing a function that detects
  15675. special context for that add-on and executes functionality appropriate for
  15676. that context.
  15677. @node Tables in arbitrary syntax
  15678. @section Tables and lists in arbitrary syntax
  15679. @cindex tables, in other modes
  15680. @cindex lists, in other modes
  15681. @cindex Orgtbl mode
  15682. Because of Org's success in handling tables with Orgtbl, a frequently asked
  15683. feature is to Org's usability functions to other table formats native to
  15684. other modem's, such as @LaTeX{}. This would be hard to do in a general way
  15685. without complicated customization nightmares. Moreover, that would take Org
  15686. away from its simplicity roots that Orgtbl has proven. There is, however, an
  15687. alternate approach to accomplishing the same.
  15688. This approach involves implementing a custom @emph{translate} function that
  15689. operates on a native Org @emph{source table} to produce a table in another
  15690. format. This strategy would keep the excellently working Orgtbl simple and
  15691. isolate complications, if any, confined to the translate function. To add
  15692. more alien table formats, we just add more translate functions. Also the
  15693. burden of developing custom translate functions for new table formats will be
  15694. in the hands of those who know those formats best.
  15695. For an example of how this strategy works, see Orgstruct mode. In that mode,
  15696. Bastien added the ability to use Org's facilities to edit and re-structure
  15697. lists. He did by turning @code{orgstruct-mode} on, and then exporting the
  15698. list locally to another format, such as HTML, @LaTeX{} or Texinfo.
  15699. @menu
  15700. * Radio tables:: Sending and receiving radio tables
  15701. * A @LaTeX{} example:: Step by step, almost a tutorial
  15702. * Translator functions:: Copy and modify
  15703. * Radio lists:: Sending and receiving lists
  15704. @end menu
  15705. @node Radio tables
  15706. @subsection Radio tables
  15707. @cindex radio tables
  15708. Radio tables are target locations for translated tables that are not near
  15709. their source. Org finds the target location and inserts the translated
  15710. table.
  15711. The key to finding the target location are the magic words @code{BEGIN/END
  15712. RECEIVE ORGTBL}. They have to appear as comments in the current mode. If
  15713. the mode is C, then:
  15714. @example
  15715. /* BEGIN RECEIVE ORGTBL table_name */
  15716. /* END RECEIVE ORGTBL table_name */
  15717. @end example
  15718. @noindent
  15719. At the location of source, Org needs a special line to direct Orgtbl to
  15720. translate and to find the target for inserting the translated table. For
  15721. example:
  15722. @cindex #+ORGTBL
  15723. @example
  15724. #+ORGTBL: SEND table_name translation_function arguments...
  15725. @end example
  15726. @noindent
  15727. @code{table_name} is the table's reference name, which is also used in the
  15728. receiver lines, and the @code{translation_function} is the Lisp function that
  15729. translates. This line, in addition, may also contain alternating key and
  15730. value arguments at the end. The translation function gets these values as a
  15731. property list. A few standard parameters are already recognized and acted
  15732. upon before the translation function is called:
  15733. @table @code
  15734. @item :skip N
  15735. Skip the first N lines of the table. Hlines do count; include them if they
  15736. are to be skipped.
  15737. @item :skipcols (n1 n2 ...)
  15738. List of columns to be skipped. First Org automatically discards columns with
  15739. calculation marks and then sends the table to the translator function, which
  15740. then skips columns as specified in @samp{skipcols}.
  15741. @end table
  15742. @noindent
  15743. To keep the source table intact in the buffer without being disturbed when
  15744. the source file is compiled or otherwise being worked on, use one of these
  15745. strategies:
  15746. @itemize @bullet
  15747. @item
  15748. Place the table in a block comment. For example, in C mode you could wrap
  15749. the table between @samp{/*} and @samp{*/} lines.
  15750. @item
  15751. Put the table after an @samp{END} statement. For example @samp{\bye} in
  15752. @TeX{} and @samp{\end@{document@}} in @LaTeX{}.
  15753. @item
  15754. Comment and uncomment each line of the table during edits. The @kbd{M-x
  15755. orgtbl-toggle-comment RET} command makes toggling easy.
  15756. @end itemize
  15757. @node A @LaTeX{} example
  15758. @subsection A @LaTeX{} example of radio tables
  15759. @cindex @LaTeX{}, and Orgtbl mode
  15760. To wrap a source table in @LaTeX{}, use the @code{comment} environment
  15761. provided by @file{comment.sty}. To activate it, put
  15762. @code{\usepackage@{comment@}} in the document header. Orgtbl mode inserts a
  15763. radio table skeleton@footnote{By default this works only for @LaTeX{}, HTML,
  15764. and Texinfo. Configure the variable @code{orgtbl-radio-table-templates} to
  15765. install templates for other export formats.} with the command @kbd{M-x
  15766. orgtbl-insert-radio-table RET}, which prompts for a table name. For example,
  15767. if @samp{salesfigures} is the name, the template inserts:
  15768. @cindex #+ORGTBL, SEND
  15769. @example
  15770. % BEGIN RECEIVE ORGTBL salesfigures
  15771. % END RECEIVE ORGTBL salesfigures
  15772. \begin@{comment@}
  15773. #+ORGTBL: SEND salesfigures orgtbl-to-latex
  15774. | | |
  15775. \end@{comment@}
  15776. @end example
  15777. @noindent
  15778. @vindex @LaTeX{}-verbatim-environments
  15779. The line @code{#+ORGTBL: SEND} tells Orgtbl mode to use the function
  15780. @code{orgtbl-to-latex} to convert the table to @LaTeX{} format, then insert
  15781. the table at the target (receive) location named @code{salesfigures}. Now
  15782. the table is ready for data entry. It can even use spreadsheet
  15783. features@footnote{If the @samp{#+TBLFM} line contains an odd number of dollar
  15784. characters, this may cause problems with font-lock in @LaTeX{} mode. As
  15785. shown in the example you can fix this by adding an extra line inside the
  15786. @code{comment} environment that is used to balance the dollar expressions.
  15787. If you are using AUC@TeX{} with the font-latex library, a much better
  15788. solution is to add the @code{comment} environment to the variable
  15789. @code{LaTeX-verbatim-environments}.}:
  15790. @example
  15791. % BEGIN RECEIVE ORGTBL salesfigures
  15792. % END RECEIVE ORGTBL salesfigures
  15793. \begin@{comment@}
  15794. #+ORGTBL: SEND salesfigures orgtbl-to-latex
  15795. | Month | Days | Nr sold | per day |
  15796. |-------+------+---------+---------|
  15797. | Jan | 23 | 55 | 2.4 |
  15798. | Feb | 21 | 16 | 0.8 |
  15799. | March | 22 | 278 | 12.6 |
  15800. #+TBLFM: $4=$3/$2;%.1f
  15801. % $ (optional extra dollar to keep font-lock happy, see footnote)
  15802. \end@{comment@}
  15803. @end example
  15804. @noindent
  15805. After editing, @kbd{C-c C-c} inserts translated table at the target location,
  15806. between the two marker lines.
  15807. For hand-made custom tables, note that the translator needs to skip the first
  15808. two lines of the source table. Also the command has to @emph{splice} out the
  15809. target table without the header and footer.
  15810. @example
  15811. \begin@{tabular@}@{lrrr@}
  15812. Month & \multicolumn@{1@}@{c@}@{Days@} & Nr.\ sold & per day\\
  15813. % BEGIN RECEIVE ORGTBL salesfigures
  15814. % END RECEIVE ORGTBL salesfigures
  15815. \end@{tabular@}
  15816. %
  15817. \begin@{comment@}
  15818. #+ORGTBL: SEND salesfigures orgtbl-to-latex :splice t :skip 2
  15819. | Month | Days | Nr sold | per day |
  15820. |-------+------+---------+---------|
  15821. | Jan | 23 | 55 | 2.4 |
  15822. | Feb | 21 | 16 | 0.8 |
  15823. | March | 22 | 278 | 12.6 |
  15824. #+TBLFM: $4=$3/$2;%.1f
  15825. \end@{comment@}
  15826. @end example
  15827. The @LaTeX{} translator function @code{orgtbl-to-latex} is already part of
  15828. Orgtbl mode and uses @code{tabular} environment by default to typeset the
  15829. table and mark the horizontal lines with @code{\hline}. For additional
  15830. parameters to control output, @pxref{Translator functions}:
  15831. @table @code
  15832. @item :splice nil/t
  15833. When non-@code{nil}, returns only table body lines; not wrapped in tabular
  15834. environment. Default is @code{nil}.
  15835. @item :fmt fmt
  15836. Format to warp each field. It should contain @code{%s} for the original
  15837. field value. For example, to wrap each field value in dollar symbol, you
  15838. could use @code{:fmt "$%s$"}. Format can also wrap a property list with
  15839. column numbers and formats, for example @code{:fmt (2 "$%s$" 4 "%s\\%%")}.
  15840. In place of a string, a function of one argument can be used; the function
  15841. must return a formatted string.
  15842. @item :efmt efmt
  15843. Format numbers as exponentials. The spec should have @code{%s} twice for
  15844. inserting mantissa and exponent, for example @code{"%s\\times10^@{%s@}"}.
  15845. This may also be a property list with column numbers and formats, for example
  15846. @code{:efmt (2 "$%s\\times10^@{%s@}$" 4 "$%s\\cdot10^@{%s@}$")}. After
  15847. @code{efmt} has been applied to a value, @code{fmt} will also be applied.
  15848. Functions with two arguments can be supplied instead of strings. By default,
  15849. no special formatting is applied.
  15850. @end table
  15851. @node Translator functions
  15852. @subsection Translator functions
  15853. @cindex HTML, and Orgtbl mode
  15854. @cindex translator function
  15855. Orgtbl mode has built-in translator functions: @code{orgtbl-to-csv}
  15856. (comma-separated values), @code{orgtbl-to-tsv} (TAB-separated values),
  15857. @code{orgtbl-to-latex}, @code{orgtbl-to-html}, @code{orgtbl-to-texinfo},
  15858. @code{orgtbl-to-unicode} and @code{orgtbl-to-orgtbl}. They use the generic
  15859. translator, @code{orgtbl-to-generic}, which delegates translations to various
  15860. export back-ends.
  15861. Properties passed to the function through the @samp{ORGTBL SEND} line take
  15862. precedence over properties defined inside the function. For example, this
  15863. overrides the default @LaTeX{} line endings, @samp{\\}, with @samp{\\[2mm]}:
  15864. @example
  15865. #+ORGTBL: SEND test orgtbl-to-latex :lend " \\\\[2mm]"
  15866. @end example
  15867. For a new language translator, define a converter function. It can be a
  15868. generic function, such as shown in this example. It marks a beginning and
  15869. ending of a table with @samp{!BTBL!} and @samp{!ETBL!}; a beginning and
  15870. ending of lines with @samp{!BL!} and @samp{!EL!}; and uses a TAB for a field
  15871. separator:
  15872. @lisp
  15873. (defun orgtbl-to-language (table params)
  15874. "Convert the orgtbl-mode TABLE to language."
  15875. (orgtbl-to-generic
  15876. table
  15877. (org-combine-plists
  15878. '(:tstart "!BTBL!" :tend "!ETBL!" :lstart "!BL!" :lend "!EL!" :sep "\t")
  15879. params)))
  15880. @end lisp
  15881. @noindent
  15882. The documentation for the @code{orgtbl-to-generic} function shows a complete
  15883. list of parameters, each of which can be passed through to
  15884. @code{orgtbl-to-latex}, @code{orgtbl-to-texinfo}, and any other function
  15885. using that generic function.
  15886. For complicated translations the generic translator function could be
  15887. replaced by a custom translator function. Such a custom function must take
  15888. two arguments and return a single string containing the formatted table. The
  15889. first argument is the table whose lines are a list of fields or the symbol
  15890. @code{hline}. The second argument is the property list consisting of
  15891. parameters specified in the @samp{#+ORGTBL: SEND} line. Please share your
  15892. translator functions by posting them to the Org users mailing list,
  15893. @email{emacs-orgmode@@gnu.org}.
  15894. @node Radio lists
  15895. @subsection Radio lists
  15896. @cindex radio lists
  15897. @cindex org-list-insert-radio-list
  15898. Call the @code{org-list-insert-radio-list} function to insert a radio list
  15899. template in HTML, @LaTeX{}, and Texinfo mode documents. Sending and
  15900. receiving radio lists works is the same as for radio tables (@pxref{Radio
  15901. tables}) except for these differences:
  15902. @cindex #+ORGLST
  15903. @itemize @minus
  15904. @item
  15905. Orgstruct mode must be active.
  15906. @item
  15907. Use @code{ORGLST} keyword instead of @code{ORGTBL}.
  15908. @item
  15909. @kbd{C-c C-c} works only on the first list item.
  15910. @end itemize
  15911. Built-in translators functions are: @code{org-list-to-latex},
  15912. @code{org-list-to-html} and @code{org-list-to-texinfo}. They use the
  15913. @code{org-list-to-generic} translator function. See its documentation for
  15914. parameters for accurate customizations of lists. Here is a @LaTeX{} example:
  15915. @example
  15916. % BEGIN RECEIVE ORGLST to-buy
  15917. % END RECEIVE ORGLST to-buy
  15918. \begin@{comment@}
  15919. #+ORGLST: SEND to-buy org-list-to-latex
  15920. - a new house
  15921. - a new computer
  15922. + a new keyboard
  15923. + a new mouse
  15924. - a new life
  15925. \end@{comment@}
  15926. @end example
  15927. @kbd{C-c C-c} on @samp{a new house} inserts the translated @LaTeX{} list
  15928. in-between the BEGIN and END marker lines.
  15929. @node Dynamic blocks
  15930. @section Dynamic blocks
  15931. @cindex dynamic blocks
  15932. Org supports @emph{dynamic blocks} in Org documents. They are inserted with
  15933. begin and end markers like any other @samp{src} code block, but the contents
  15934. are updated automatically by a user function. For example, @kbd{C-c C-x C-r}
  15935. inserts a dynamic table that updates the work time (@pxref{Clocking work
  15936. time}).
  15937. Dynamic blocks can have names and function parameters. The syntax is similar
  15938. to @samp{src} code block specifications:
  15939. @cindex #+BEGIN:dynamic block
  15940. @example
  15941. #+BEGIN: myblock :parameter1 value1 :parameter2 value2 ...
  15942. #+END:
  15943. @end example
  15944. These command update dynamic blocks:
  15945. @table @kbd
  15946. @orgcmd{C-c C-x C-u,org-dblock-update}
  15947. Update dynamic block at point.
  15948. @orgkey{C-u C-c C-x C-u}
  15949. Update all dynamic blocks in the current file.
  15950. @end table
  15951. Before updating a dynamic block, Org removes content between the BEGIN and
  15952. END markers. Org then reads the parameters on the BEGIN line for passing to
  15953. the writer function. If the function expects to access the removed content,
  15954. then Org expects an extra parameter, @code{:content}, on the BEGIN line.
  15955. To syntax for calling a writer function with a named block, @code{myblock}
  15956. is: @code{org-dblock-write:myblock}. Parameters come from the BEGIN line.
  15957. The following is an example of a dynamic block and a block writer function
  15958. that updates the time when the function was last run:
  15959. @example
  15960. #+BEGIN: block-update-time :format "on %m/%d/%Y at %H:%M"
  15961. #+END:
  15962. @end example
  15963. @noindent
  15964. The dynamic block's writer function:
  15965. @lisp
  15966. (defun org-dblock-write:block-update-time (params)
  15967. (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
  15968. (insert "Last block update at: "
  15969. (format-time-string fmt))))
  15970. @end lisp
  15971. To keep dynamic blocks up-to-date in an Org file, use the function,
  15972. @code{org-update-all-dblocks} in hook, such as @code{before-save-hook}. The
  15973. @code{org-update-all-dblocks} function does not run if the file is not in
  15974. Org mode.
  15975. Dynamic blocks, like any other block, can be narrowed with
  15976. @code{org-narrow-to-block}.
  15977. @node Special agenda views
  15978. @section Special agenda views
  15979. @cindex agenda views, user-defined
  15980. @vindex org-agenda-skip-function
  15981. @vindex org-agenda-skip-function-global
  15982. Org provides a special hook to further limit items in agenda views:
  15983. @code{agenda}, @code{agenda*}@footnote{The @code{agenda*} view is the same as
  15984. @code{agenda} except that it only considers @emph{appointments}, i.e.,
  15985. scheduled and deadline items that have a time specification @samp{[h]h:mm} in
  15986. their time-stamps.}, @code{todo}, @code{alltodo}, @code{tags},
  15987. @code{tags-todo}, @code{tags-tree}. Specify a custom function that tests
  15988. inclusion of every matched item in the view. This function can also
  15989. skip as much as is needed.
  15990. For a global condition applicable to agenda views, use the
  15991. @code{org-agenda-skip-function-global} variable. Org uses a global condition
  15992. with @code{org-agenda-skip-function} for custom searching.
  15993. This example defines a function for a custom view showing TODO items with
  15994. WAITING status. Manually this is a multi step search process, but with a
  15995. custom view, this can be automated as follows:
  15996. The custom function searches the subtree for the WAITING tag and returns
  15997. @code{nil} on match. Otherwise it gives the location from where the search
  15998. continues.
  15999. @lisp
  16000. (defun my-skip-unless-waiting ()
  16001. "Skip trees that are not waiting"
  16002. (let ((subtree-end (save-excursion (org-end-of-subtree t))))
  16003. (if (re-search-forward ":waiting:" subtree-end t)
  16004. nil ; tag found, do not skip
  16005. subtree-end))) ; tag not found, continue after end of subtree
  16006. @end lisp
  16007. To use this custom function in a custom agenda command:
  16008. @lisp
  16009. (org-add-agenda-custom-command
  16010. '("b" todo "PROJECT"
  16011. ((org-agenda-skip-function 'my-skip-unless-waiting)
  16012. (org-agenda-overriding-header "Projects waiting for something: "))))
  16013. @end lisp
  16014. @vindex org-agenda-overriding-header
  16015. Note that this also binds @code{org-agenda-overriding-header} to a more
  16016. meaningful string suitable for the agenda view.
  16017. @vindex org-odd-levels-only
  16018. @vindex org-agenda-skip-function
  16019. Search for entries with a limit set on levels for the custom search. This is
  16020. a general approach to creating custom searches in Org. To include all
  16021. levels, use @samp{LEVEL>0}@footnote{Note that, for
  16022. @code{org-odd-levels-only}, a level number corresponds to order in the
  16023. hierarchy, not to the number of stars.}. Then to selectively pick the
  16024. matched entries, use @code{org-agenda-skip-function}, which also accepts Lisp
  16025. forms, such as @code{org-agenda-skip-entry-if} and
  16026. @code{org-agenda-skip-subtree-if}. For example:
  16027. @table @code
  16028. @item (org-agenda-skip-entry-if 'scheduled)
  16029. Skip current entry if it has been scheduled.
  16030. @item (org-agenda-skip-entry-if 'notscheduled)
  16031. Skip current entry if it has not been scheduled.
  16032. @item (org-agenda-skip-entry-if 'deadline)
  16033. Skip current entry if it has a deadline.
  16034. @item (org-agenda-skip-entry-if 'scheduled 'deadline)
  16035. Skip current entry if it has a deadline, or if it is scheduled.
  16036. @item (org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))
  16037. Skip current entry if the TODO keyword is TODO or WAITING.
  16038. @item (org-agenda-skip-entry-if 'todo 'done)
  16039. Skip current entry if the TODO keyword marks a DONE state.
  16040. @item (org-agenda-skip-entry-if 'timestamp)
  16041. Skip current entry if it has any timestamp, may also be deadline or scheduled.
  16042. @anchor{x-agenda-skip-entry-regexp}
  16043. @item (org-agenda-skip-entry-if 'regexp "regular expression")
  16044. Skip current entry if the regular expression matches in the entry.
  16045. @item (org-agenda-skip-entry-if 'notregexp "regular expression")
  16046. Skip current entry unless the regular expression matches.
  16047. @item (org-agenda-skip-subtree-if 'regexp "regular expression")
  16048. Same as above, but check and skip the entire subtree.
  16049. @end table
  16050. The following is an example of a search for @samp{WAITING} without the
  16051. special function:
  16052. @lisp
  16053. (org-add-agenda-custom-command
  16054. '("b" todo "PROJECT"
  16055. ((org-agenda-skip-function '(org-agenda-skip-subtree-if
  16056. 'regexp ":waiting:"))
  16057. (org-agenda-overriding-header "Projects waiting for something: "))))
  16058. @end lisp
  16059. @node Speeding up your agendas
  16060. @section Speeding up your agendas
  16061. @cindex agenda views, optimization
  16062. Some agenda commands slow down when the Org files grow in size or number.
  16063. Here are tips to speed up:
  16064. @enumerate
  16065. @item
  16066. Reduce the number of Org agenda files to avoid slowdowns due to hard drive
  16067. accesses.
  16068. @item
  16069. Reduce the number of @samp{DONE} and archived headlines so agenda operations
  16070. that skip over these can finish faster.
  16071. @item
  16072. @vindex org-agenda-dim-blocked-tasks
  16073. Do not dim blocked tasks:
  16074. @lisp
  16075. (setq org-agenda-dim-blocked-tasks nil)
  16076. @end lisp
  16077. @item
  16078. @vindex org-startup-folded
  16079. @vindex org-agenda-inhibit-startup
  16080. Stop preparing agenda buffers on startup:
  16081. @lisp
  16082. (setq org-agenda-inhibit-startup nil)
  16083. @end lisp
  16084. @item
  16085. @vindex org-agenda-show-inherited-tags
  16086. @vindex org-agenda-use-tag-inheritance
  16087. Disable tag inheritance for agendas:
  16088. @lisp
  16089. (setq org-agenda-use-tag-inheritance nil)
  16090. @end lisp
  16091. @end enumerate
  16092. These options can be applied to selected agenda views. For more details
  16093. about generation of agenda views, see the docstrings for the relevant
  16094. variables, and this @uref{http://orgmode.org/worg/agenda-optimization.html,
  16095. dedicated Worg page} for agenda optimization.
  16096. @node Extracting agenda information
  16097. @section Extracting agenda information
  16098. @cindex agenda, pipe
  16099. @cindex Scripts, for agenda processing
  16100. @vindex org-agenda-custom-commands
  16101. Org provides commands to access agendas through Emacs batch mode. Through
  16102. this command-line interface, agendas are automated for further processing or
  16103. printing.
  16104. @code{org-batch-agenda} creates an agenda view in ASCII and outputs to
  16105. STDOUT. This command takes one string parameter. When string length=1, Org
  16106. uses it as a key to @code{org-agenda-custom-commands}. These are the same
  16107. ones available through @kbd{C-c a}.
  16108. This example command line directly prints the TODO list to the printer:
  16109. @example
  16110. emacs -batch -l ~/.emacs -eval '(org-batch-agenda "t")' | lpr
  16111. @end example
  16112. When the string parameter length is two or more characters, Org matches it
  16113. with tags/TODO strings. For example, this example command line prints items
  16114. tagged with @samp{shop}, but excludes items tagged with @samp{NewYork}:
  16115. @example
  16116. emacs -batch -l ~/.emacs \
  16117. -eval '(org-batch-agenda "+shop-NewYork")' | lpr
  16118. @end example
  16119. @noindent
  16120. An example showing on-the-fly parameter modifications:
  16121. @example
  16122. emacs -batch -l ~/.emacs \
  16123. -eval '(org-batch-agenda "a" \
  16124. org-agenda-span (quote month) \
  16125. org-agenda-include-diary nil \
  16126. org-agenda-files (quote ("~/org/project.org")))' \
  16127. | lpr
  16128. @end example
  16129. @noindent
  16130. which will produce an agenda for the next 30 days from just the
  16131. @file{~/org/projects.org} file.
  16132. For structured processing of agenda output, use @code{org-batch-agenda-csv}
  16133. with the following fields:
  16134. @example
  16135. category @r{The category of the item}
  16136. head @r{The headline, without TODO keyword, TAGS and PRIORITY}
  16137. type @r{The type of the agenda entry, can be}
  16138. todo @r{selected in TODO match}
  16139. tagsmatch @r{selected in tags match}
  16140. diary @r{imported from diary}
  16141. deadline @r{a deadline}
  16142. scheduled @r{scheduled}
  16143. timestamp @r{appointment, selected by timestamp}
  16144. closed @r{entry was closed on date}
  16145. upcoming-deadline @r{warning about nearing deadline}
  16146. past-scheduled @r{forwarded scheduled item}
  16147. block @r{entry has date block including date}
  16148. todo @r{The TODO keyword, if any}
  16149. tags @r{All tags including inherited ones, separated by colons}
  16150. date @r{The relevant date, like 2007-2-14}
  16151. time @r{The time, like 15:00-16:50}
  16152. extra @r{String with extra planning info}
  16153. priority-l @r{The priority letter if any was given}
  16154. priority-n @r{The computed numerical priority}
  16155. @end example
  16156. @noindent
  16157. If the selection of the agenda item was based on a timestamp, including those
  16158. items with @samp{DEADLINE} and @samp{SCHEDULED} keywords, then Org includes
  16159. date and time in the output.
  16160. If the selection of the agenda item was based on a timestamp (or
  16161. deadline/scheduled), then Org includes date and time in the output.
  16162. Here is an example of a post-processing script in Perl. It takes the CSV
  16163. output from Emacs and prints with a checkbox:
  16164. @example
  16165. #!/usr/bin/perl
  16166. # define the Emacs command to run
  16167. $cmd = "emacs -batch -l ~/.emacs -eval '(org-batch-agenda-csv \"t\")'";
  16168. # run it and capture the output
  16169. $agenda = qx@{$cmd 2>/dev/null@};
  16170. # loop over all lines
  16171. foreach $line (split(/\n/,$agenda)) @{
  16172. # get the individual values
  16173. ($category,$head,$type,$todo,$tags,$date,$time,$extra,
  16174. $priority_l,$priority_n) = split(/,/,$line);
  16175. # process and print
  16176. print "[ ] $head\n";
  16177. @}
  16178. @end example
  16179. @node Using the property API
  16180. @section Using the property API
  16181. @cindex API, for properties
  16182. @cindex properties, API
  16183. Functions for working with properties.
  16184. @defun org-entry-properties &optional pom which
  16185. Get all properties of the entry at point-or-marker POM.@*
  16186. This includes the TODO keyword, the tags, time strings for deadline,
  16187. scheduled, and clocking, and any additional properties defined in the
  16188. entry. The return value is an alist. Keys may occur multiple times
  16189. if the property key was used several times.@*
  16190. POM may also be @code{nil}, in which case the current entry is used.
  16191. If WHICH is @code{nil} or @code{all}, get all properties. If WHICH is
  16192. @code{special} or @code{standard}, only get that subclass.
  16193. @end defun
  16194. @vindex org-use-property-inheritance
  16195. @findex org-insert-property-drawer
  16196. @defun org-entry-get pom property &optional inherit
  16197. Get value of @code{PROPERTY} for entry at point-or-marker @code{POM}@. By
  16198. default, this only looks at properties defined locally in the entry. If
  16199. @code{INHERIT} is non-@code{nil} and the entry does not have the property,
  16200. then also check higher levels of the hierarchy. If @code{INHERIT} is the
  16201. symbol @code{selective}, use inheritance if and only if the setting of
  16202. @code{org-use-property-inheritance} selects @code{PROPERTY} for inheritance.
  16203. @end defun
  16204. @defun org-entry-delete pom property
  16205. Delete the property @code{PROPERTY} from entry at point-or-marker POM.
  16206. @end defun
  16207. @defun org-entry-put pom property value
  16208. Set @code{PROPERTY} to @code{VALUE} for entry at point-or-marker POM.
  16209. @end defun
  16210. @defun org-buffer-property-keys &optional include-specials
  16211. Get all property keys in the current buffer.
  16212. @end defun
  16213. @defun org-insert-property-drawer
  16214. Insert a property drawer for the current entry.
  16215. @end defun
  16216. @defun org-entry-put-multivalued-property pom property &rest values
  16217. Set @code{PROPERTY} at point-or-marker @code{POM} to @code{VALUES}@.
  16218. @code{VALUES} should be a list of strings. They will be concatenated, with
  16219. spaces as separators.
  16220. @end defun
  16221. @defun org-entry-get-multivalued-property pom property
  16222. Treat the value of the property @code{PROPERTY} as a whitespace-separated
  16223. list of values and return the values as a list of strings.
  16224. @end defun
  16225. @defun org-entry-add-to-multivalued-property pom property value
  16226. Treat the value of the property @code{PROPERTY} as a whitespace-separated
  16227. list of values and make sure that @code{VALUE} is in this list.
  16228. @end defun
  16229. @defun org-entry-remove-from-multivalued-property pom property value
  16230. Treat the value of the property @code{PROPERTY} as a whitespace-separated
  16231. list of values and make sure that @code{VALUE} is @emph{not} in this list.
  16232. @end defun
  16233. @defun org-entry-member-in-multivalued-property pom property value
  16234. Treat the value of the property @code{PROPERTY} as a whitespace-separated
  16235. list of values and check if @code{VALUE} is in this list.
  16236. @end defun
  16237. @defopt org-property-allowed-value-functions
  16238. Hook for functions supplying allowed values for a specific property.
  16239. The functions must take a single argument, the name of the property, and
  16240. return a flat list of allowed values. If @samp{:ETC} is one of
  16241. the values, use the values as completion help, but allow also other values
  16242. to be entered. The functions must return @code{nil} if they are not
  16243. responsible for this property.
  16244. @end defopt
  16245. @node Using the mapping API
  16246. @section Using the mapping API
  16247. @cindex API, for mapping
  16248. @cindex mapping entries, API
  16249. Org has sophisticated mapping capabilities for finding entries. Org uses
  16250. this functionality internally for generating agenda views. Org also exposes
  16251. an API for executing arbitrary functions for each selected entry. The API's
  16252. main entry point is:
  16253. @defun org-map-entries func &optional match scope &rest skip
  16254. Call @samp{FUNC} at each headline selected by @code{MATCH} in @code{SCOPE}.
  16255. @samp{FUNC} is a function or a Lisp form. With the cursor positioned at the
  16256. beginning of the headline, call the function without arguments. Org returns
  16257. an alist of return values of calls to the function.
  16258. To avoid preserving point, Org wraps the call to @code{FUNC} in
  16259. save-excursion form. After evaluation, Org moves the cursor to the end of
  16260. the line that was just processed. Search continues from that point forward.
  16261. This may not always work as expected under some conditions, such as if the
  16262. current sub-tree was removed by a previous archiving operation. In such rare
  16263. circumstances, Org skips the next entry entirely when it should not. To stop
  16264. Org from such skips, make @samp{FUNC} set the variable
  16265. @code{org-map-continue-from} to a specific buffer position.
  16266. @samp{MATCH} is a tags/property/TODO match. Org iterates only matched
  16267. headlines. Org iterates over all headlines when @code{MATCH} is @code{nil}
  16268. or @code{t}.
  16269. @samp{SCOPE} determines the scope of this command. It can be any of:
  16270. @example
  16271. nil @r{the current buffer, respecting the restriction if any}
  16272. tree @r{the subtree started with the entry at point}
  16273. region @r{The entries within the active region, if any}
  16274. file @r{the current buffer, without restriction}
  16275. file-with-archives
  16276. @r{the current buffer, and any archives associated with it}
  16277. agenda @r{all agenda files}
  16278. agenda-with-archives
  16279. @r{all agenda files with any archive files associated with them}
  16280. (file1 file2 ...)
  16281. @r{if this is a list, all files in the list will be scanned}
  16282. @end example
  16283. @noindent
  16284. The remaining args are treated as settings for the scanner's skipping
  16285. facilities. Valid args are:
  16286. @vindex org-agenda-skip-function
  16287. @example
  16288. archive @r{skip trees with the archive tag}
  16289. comment @r{skip trees with the COMMENT keyword}
  16290. function or Lisp form
  16291. @r{will be used as value for @code{org-agenda-skip-function},}
  16292. @r{so whenever the function returns t, FUNC}
  16293. @r{will not be called for that entry and search will}
  16294. @r{continue from the point where the function leaves it}
  16295. @end example
  16296. @end defun
  16297. The mapping routine can call any arbitrary function, even functions that
  16298. change meta data or query the property API (@pxref{Using the property API}).
  16299. Here are some handy functions:
  16300. @defun org-todo &optional arg
  16301. Change the TODO state of the entry. See the docstring of the functions for
  16302. the many possible values for the argument @code{ARG}.
  16303. @end defun
  16304. @defun org-priority &optional action
  16305. Change the priority of the entry. See the docstring of this function for the
  16306. possible values for @code{ACTION}.
  16307. @end defun
  16308. @defun org-toggle-tag tag &optional onoff
  16309. Toggle the tag @code{TAG} in the current entry. Setting @code{ONOFF} to
  16310. either @code{on} or @code{off} will not toggle tag, but ensure that it is
  16311. either on or off.
  16312. @end defun
  16313. @defun org-promote
  16314. Promote the current entry.
  16315. @end defun
  16316. @defun org-demote
  16317. Demote the current entry.
  16318. @end defun
  16319. This example turns all entries tagged with @code{TOMORROW} into TODO entries
  16320. with keyword @code{UPCOMING}. Org ignores entries in comment trees and
  16321. archive trees.
  16322. @lisp
  16323. (org-map-entries
  16324. '(org-todo "UPCOMING")
  16325. "+TOMORROW" 'file 'archive 'comment)
  16326. @end lisp
  16327. The following example counts the number of entries with TODO keyword
  16328. @code{WAITING}, in all agenda files.
  16329. @lisp
  16330. (length (org-map-entries t "/+WAITING" 'agenda))
  16331. @end lisp
  16332. @node MobileOrg
  16333. @appendix MobileOrg
  16334. @cindex iPhone
  16335. @cindex MobileOrg
  16336. MobileOrg is a companion mobile app that runs on iOS and Android devices.
  16337. MobileOrg enables offline-views and capture support for an Org mode system
  16338. that is rooted on a ``real'' computer. MobileOrg can record changes to
  16339. existing entries.
  16340. The @uref{https://github.com/MobileOrg/, iOS implementation} for the
  16341. @emph{iPhone/iPod Touch/iPad} series of devices, was started by Richard
  16342. Moreland and is now in the hands Sean Escriva. Android users should check
  16343. out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg
  16344. Android} by Matt Jones. Though the two implementations are not identical,
  16345. they offer similar features.
  16346. This appendix describes Org's support for agenda view formats compatible with
  16347. MobileOrg. It also describes synchronizing changes, such as to notes,
  16348. between MobileOrg and the computer.
  16349. To change tags and TODO states in MobileOrg, first customize the variables
  16350. @code{org-todo-keywords} and @code{org-tag-alist}. These should cover all
  16351. the important tags and TODO keywords, even if Org files use only some of
  16352. them. Though MobileOrg has in-buffer settings, it understands TODO states
  16353. @emph{sets} (@pxref{Per-file keywords}) and @emph{mutually exclusive} tags
  16354. (@pxref{Setting tags}) only for those set in these variables.
  16355. @menu
  16356. * Setting up the staging area:: For the mobile device
  16357. * Pushing to MobileOrg:: Uploading Org files and agendas
  16358. * Pulling from MobileOrg:: Integrating captured and flagged items
  16359. @end menu
  16360. @node Setting up the staging area
  16361. @section Setting up the staging area
  16362. MobileOrg needs access to a file directory on a server to interact with
  16363. Emacs. With a public server, consider encrypting the files. MobileOrg
  16364. version 1.5 supports encryption for the iPhone. Org also requires
  16365. @file{openssl} installed on the local computer. To turn on encryption, set
  16366. the same password in MobileOrg and in Emacs. Set the password in the
  16367. variable @code{org-mobile-use-encryption}@footnote{If Emacs is configured for
  16368. safe storing of passwords, then configure the variable,
  16369. @code{org-mobile-encryption-password}; please read the docstring of that
  16370. variable.}. Note that even after MobileOrg encrypts the file contents, the
  16371. file names will remain visible on the file systems of the local computer, the
  16372. server, and the mobile device.
  16373. For a server to host files, consider options like
  16374. @uref{http://dropbox.com,Dropbox.com} account@footnote{An alternative is to
  16375. use webdav server. MobileOrg documentation has details of webdav server
  16376. configuration. Additional help is at
  16377. @uref{http://orgmode.org/worg/org-faq.html#mobileorg_webdav, FAQ entry}.}.
  16378. On first connection, MobileOrg creates a directory @file{MobileOrg/} on
  16379. Dropbox. Pass its location to Emacs through an init file variable as
  16380. follows:
  16381. @lisp
  16382. (setq org-mobile-directory "~/Dropbox/MobileOrg")
  16383. @end lisp
  16384. Org copies files to the above directory for MobileOrg. Org also uses the
  16385. same directory for sharing notes between Org and MobileOrg.
  16386. @node Pushing to MobileOrg
  16387. @section Pushing to MobileOrg
  16388. Org pushes files listed in @code{org-mobile-files} to
  16389. @code{org-mobile-directory}. Files include agenda files (as listed in
  16390. @code{org-agenda-files}). Customize @code{org-mobile-files} to add other
  16391. files. File names will be staged with paths relative to
  16392. @code{org-directory}, so all files should be inside this
  16393. directory@footnote{Symbolic links in @code{org-directory} should have the
  16394. same name as their targets.}.
  16395. Push creates a special Org file @file{agendas.org} with custom agenda views
  16396. defined by the user@footnote{While creating the agendas, Org mode will force
  16397. ID properties on all referenced entries, so that these entries can be
  16398. uniquely identified if MobileOrg flags them for further action. To avoid
  16399. setting properties configure the variable
  16400. @code{org-mobile-force-id-on-agenda-items} to @code{nil}. Org mode will then
  16401. rely on outline paths, assuming they are unique.}.
  16402. Org writes the file @file{index.org}, containing links to other files.
  16403. MobileOrg reads this file first from the server to determine what other files
  16404. to download for agendas. For faster downloads, MobileOrg will read only
  16405. those files whose checksums@footnote{Checksums are stored automatically in
  16406. the file @file{checksums.dat}.} have changed.
  16407. @node Pulling from MobileOrg
  16408. @section Pulling from MobileOrg
  16409. When MobileOrg synchronizes with the server, it pulls the Org files for
  16410. viewing. It then appends to the file @file{mobileorg.org} on the server the
  16411. captured entries, pointers to flagged and changed entries. Org integrates
  16412. its data in an inbox file format.
  16413. @enumerate
  16414. @item
  16415. Org moves all entries found in
  16416. @file{mobileorg.org}@footnote{@file{mobileorg.org} will be empty after this
  16417. operation.} and appends them to the file pointed to by the variable
  16418. @code{org-mobile-inbox-for-pull}. Each captured entry and each editing event
  16419. is a top-level entry in the inbox file.
  16420. @item
  16421. After moving the entries, Org attempts changes to MobileOrg. Some changes
  16422. are applied directly and without user interaction. Examples include changes
  16423. to tags, TODO state, headline and body text. Entries for further action are
  16424. tagged as @code{:FLAGGED:}. Org marks entries with problems with an error
  16425. message in the inbox. They have to be resolved manually.
  16426. @item
  16427. Org generates an agenda view for flagged entries for user intervention to
  16428. clean up. For notes stored in flagged entries, MobileOrg displays them in
  16429. the echo area when the cursor is on the corresponding agenda item.
  16430. @table @kbd
  16431. @kindex ?
  16432. @item ?
  16433. Pressing @kbd{?} displays the entire flagged note in another window. Org
  16434. also pushes it to the kill ring. To store flagged note as a normal note, use
  16435. @kbd{? z C-y C-c C-c}. Pressing @kbd{?} twice does these things: first it
  16436. removes the @code{:FLAGGED:} tag; second, it removes the flagged note from
  16437. the property drawer; third, it signals that manual editing of the flagged
  16438. entry is now finished.
  16439. @end table
  16440. @end enumerate
  16441. @kindex C-c a ?
  16442. @kbd{C-c a ?} returns to the agenda view to finish processing flagged
  16443. entries. Note that these entries may not be the most recent since MobileOrg
  16444. searches files that were last pulled. To get an updated agenda view with
  16445. changes since the last pull, pull again.
  16446. @node History and acknowledgments
  16447. @appendix History and acknowledgments
  16448. @cindex acknowledgments
  16449. @cindex history
  16450. @cindex thanks
  16451. @section From Carsten
  16452. Org was born in 2003, out of frustration over the user interface of the Emacs
  16453. Outline mode. I was trying to organize my notes and projects, and using
  16454. Emacs seemed to be the natural way to go. However, having to remember eleven
  16455. different commands with two or three keys per command, only to hide and show
  16456. parts of the outline tree, that seemed entirely unacceptable. Also, when
  16457. using outlines to take notes, I constantly wanted to restructure the tree,
  16458. organizing it paralleling my thoughts and plans. @emph{Visibility cycling}
  16459. and @emph{structure editing} were originally implemented in the package
  16460. @file{outline-magic.el}, but quickly moved to the more general @file{org.el}.
  16461. As this environment became comfortable for project planning, the next step
  16462. was adding @emph{TODO entries}, basic @emph{timestamps}, and @emph{table
  16463. support}. These areas highlighted the two main goals that Org still has
  16464. today: to be a new, outline-based, plain text mode with innovative and
  16465. intuitive editing features, and to incorporate project planning functionality
  16466. directly into a notes file.
  16467. Since the first release, literally thousands of emails to me or to
  16468. @email{emacs-orgmode@@gnu.org} have provided a constant stream of bug
  16469. reports, feedback, new ideas, and sometimes patches and add-on code.
  16470. Many thanks to everyone who has helped to improve this package. I am
  16471. trying to keep here a list of the people who had significant influence
  16472. in shaping one or more aspects of Org. The list may not be
  16473. complete, if I have forgotten someone, please accept my apologies and
  16474. let me know.
  16475. Before I get to this list, a few special mentions are in order:
  16476. @table @i
  16477. @item Bastien Guerry
  16478. Bastien has written a large number of extensions to Org (most of them
  16479. integrated into the core by now), including the @LaTeX{} exporter and the
  16480. plain list parser. His support during the early days was central to the
  16481. success of this project. Bastien also invented Worg, helped establishing the
  16482. Web presence of Org, and sponsored hosting costs for the orgmode.org website.
  16483. Bastien stepped in as maintainer of Org between 2011 and 2013, at a time when
  16484. I desperately needed a break.
  16485. @item Eric Schulte and Dan Davison
  16486. Eric and Dan are jointly responsible for the Org-babel system, which turns
  16487. Org into a multi-language environment for evaluating code and doing literate
  16488. programming and reproducible research. This has become one of Org's killer
  16489. features that define what Org is today.
  16490. @item John Wiegley
  16491. John has contributed a number of great ideas and patches directly to Org,
  16492. including the attachment system (@file{org-attach.el}), integration with
  16493. Apple Mail (@file{org-mac-message.el}), hierarchical dependencies of TODO
  16494. items, habit tracking (@file{org-habits.el}), and encryption
  16495. (@file{org-crypt.el}). Also, the capture system is really an extended copy
  16496. of his great @file{remember.el}.
  16497. @item Sebastian Rose
  16498. Without Sebastian, the HTML/XHTML publishing of Org would be the pitiful work
  16499. of an ignorant amateur. Sebastian has pushed this part of Org onto a much
  16500. higher level. He also wrote @file{org-info.js}, a Java script for displaying
  16501. web pages derived from Org using an Info-like or a folding interface with
  16502. single-key navigation.
  16503. @end table
  16504. @noindent See below for the full list of contributions! Again, please
  16505. let me know what I am missing here!
  16506. @section From Bastien
  16507. I (Bastien) have been maintaining Org between 2011 and 2013. This appendix
  16508. would not be complete without adding a few more acknowledgments and thanks.
  16509. I am first grateful to Carsten for his trust while handing me over the
  16510. maintainership of Org. His unremitting support is what really helped me
  16511. getting more confident over time, with both the community and the code.
  16512. When I took over maintainership, I knew I would have to make Org more
  16513. collaborative than ever, as I would have to rely on people that are more
  16514. knowledgeable than I am on many parts of the code. Here is a list of the
  16515. persons I could rely on, they should really be considered co-maintainers,
  16516. either of the code or the community:
  16517. @table @i
  16518. @item Eric Schulte
  16519. Eric is maintaining the Babel parts of Org. His reactivity here kept me away
  16520. from worrying about possible bugs here and let me focus on other parts.
  16521. @item Nicolas Goaziou
  16522. Nicolas is maintaining the consistency of the deepest parts of Org. His work
  16523. on @file{org-element.el} and @file{ox.el} has been outstanding, and it opened
  16524. the doors for many new ideas and features. He rewrote many of the old
  16525. exporters to use the new export engine, and helped with documenting this
  16526. major change. More importantly (if that's possible), he has been more than
  16527. reliable during all the work done for Org 8.0, and always very reactive on
  16528. the mailing list.
  16529. @item Achim Gratz
  16530. Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
  16531. into a flexible and conceptually clean process. He patiently coped with the
  16532. many hiccups that such a change can create for users.
  16533. @item Nick Dokos
  16534. The Org mode mailing list would not be such a nice place without Nick, who
  16535. patiently helped users so many times. It is impossible to overestimate such
  16536. a great help, and the list would not be so active without him.
  16537. @end table
  16538. I received support from so many users that it is clearly impossible to be
  16539. fair when shortlisting a few of them, but Org's history would not be
  16540. complete if the ones above were not mentioned in this manual.
  16541. @section List of contributions
  16542. @itemize @bullet
  16543. @item
  16544. @i{Russel Adams} came up with the idea for drawers.
  16545. @item
  16546. @i{Suvayu Ali} has steadily helped on the mailing list, providing useful
  16547. feedback on many features and several patches.
  16548. @item
  16549. @i{Luis Anaya} wrote @file{ox-man.el}.
  16550. @item
  16551. @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}.
  16552. @item
  16553. @i{Michael Brand} helped by reporting many bugs and testing many features.
  16554. He also implemented the distinction between empty fields and 0-value fields
  16555. in Org's spreadsheets.
  16556. @item
  16557. @i{Christophe Bataillon} created the great unicorn logo that we use on the
  16558. Org mode website.
  16559. @item
  16560. @i{Alex Bochannek} provided a patch for rounding timestamps.
  16561. @item
  16562. @i{Jan Böcker} wrote @file{org-docview.el}.
  16563. @item
  16564. @i{Brad Bozarth} showed how to pull RSS feed data into Org mode files.
  16565. @item
  16566. @i{Tom Breton} wrote @file{org-choose.el}.
  16567. @item
  16568. @i{Charles Cave}'s suggestion sparked the implementation of templates
  16569. for Remember, which are now templates for capture.
  16570. @item
  16571. @i{Pavel Chalmoviansky} influenced the agenda treatment of items with
  16572. specified time.
  16573. @item
  16574. @i{Gregory Chernov} patched support for Lisp forms into table
  16575. calculations and improved XEmacs compatibility, in particular by porting
  16576. @file{nouline.el} to XEmacs.
  16577. @item
  16578. @i{Sacha Chua} suggested copying some linking code from Planner, and helped
  16579. make Org popular through her blog.
  16580. @item
  16581. @i{Toby S. Cubitt} contributed to the code for clock formats.
  16582. @item
  16583. @i{Baoqiu Cui} contributed the first DocBook exporter. In Org 8.0, we go a
  16584. different route: you can now export to Texinfo and export the @file{.texi}
  16585. file to DocBook using @code{makeinfo}.
  16586. @item
  16587. @i{Eddward DeVilla} proposed and tested checkbox statistics. He also
  16588. came up with the idea of properties, and that there should be an API for
  16589. them.
  16590. @item
  16591. @i{Nick Dokos} tracked down several nasty bugs.
  16592. @item
  16593. @i{Kees Dullemond} used to edit projects lists directly in HTML and so
  16594. inspired some of the early development, including HTML export. He also
  16595. asked for a way to narrow wide table columns.
  16596. @item
  16597. @i{Jason Dunsmore} has been maintaining the Org-Mode server at Rackspace for
  16598. several years now. He also sponsored the hosting costs until Rackspace
  16599. started to host us for free.
  16600. @item
  16601. @i{Thomas S. Dye} contributed documentation on Worg and helped integrating
  16602. the Org-Babel documentation into the manual.
  16603. @item
  16604. @i{Christian Egli} converted the documentation into Texinfo format, inspired
  16605. the agenda, patched CSS formatting into the HTML exporter, and wrote
  16606. @file{org-taskjuggler.el}, which has been rewritten by Nicolas Goaziou as
  16607. @file{ox-taskjuggler.el} for Org 8.0.
  16608. @item
  16609. @i{David Emery} provided a patch for custom CSS support in exported
  16610. HTML agendas.
  16611. @item
  16612. @i{Sean Escriva} took over MobileOrg development on the iPhone platform.
  16613. @item
  16614. @i{Nic Ferrier} contributed mailcap and XOXO support.
  16615. @item
  16616. @i{Miguel A. Figueroa-Villanueva} implemented hierarchical checkboxes.
  16617. @item
  16618. @i{John Foerch} figured out how to make incremental search show context
  16619. around a match in a hidden outline tree.
  16620. @item
  16621. @i{Raimar Finken} wrote @file{org-git-line.el}.
  16622. @item
  16623. @i{Mikael Fornius} works as a mailing list moderator.
  16624. @item
  16625. @i{Austin Frank} works as a mailing list moderator.
  16626. @item
  16627. @i{Eric Fraga} drove the development of BEAMER export with ideas and
  16628. testing.
  16629. @item
  16630. @i{Barry Gidden} did proofreading the manual in preparation for the book
  16631. publication through Network Theory Ltd.
  16632. @item
  16633. @i{Niels Giesen} had the idea to automatically archive DONE trees.
  16634. @item
  16635. @i{Nicolas Goaziou} rewrote much of the plain list code. He also wrote
  16636. @file{org-element.el} and @file{org-export.el}, which was a huge step forward
  16637. in implementing a clean framework for Org exporters.
  16638. @item
  16639. @i{Kai Grossjohann} pointed out key-binding conflicts with other packages.
  16640. @item
  16641. @i{Brian Gough} of Network Theory Ltd publishes the Org mode manual as a
  16642. book.
  16643. @item
  16644. @i{Bernt Hansen} has driven much of the support for auto-repeating tasks,
  16645. task state change logging, and the clocktable. His clear explanations have
  16646. been critical when we started to adopt the Git version control system.
  16647. @item
  16648. @i{Manuel Hermenegildo} has contributed various ideas, small fixes and
  16649. patches.
  16650. @item
  16651. @i{Phil Jackson} wrote @file{org-irc.el}.
  16652. @item
  16653. @i{Scott Jaderholm} proposed footnotes, control over whitespace between
  16654. folded entries, and column view for properties.
  16655. @item
  16656. @i{Matt Jones} wrote @i{MobileOrg Android}.
  16657. @item
  16658. @i{Tokuya Kameshima} wrote @file{org-wl.el} and @file{org-mew.el}.
  16659. @item
  16660. @i{Jonathan Leech-Pepin} wrote @file{ox-texinfo.el}.
  16661. @item
  16662. @i{Shidai Liu} ("Leo") asked for embedded @LaTeX{} and tested it. He also
  16663. provided frequent feedback and some patches.
  16664. @item
  16665. @i{Matt Lundin} has proposed last-row references for table formulas and named
  16666. invisible anchors. He has also worked a lot on the FAQ.
  16667. @item
  16668. @i{David Maus} wrote @file{org-atom.el}, maintains the issues file for Org,
  16669. and is a prolific contributor on the mailing list with competent replies,
  16670. small fixes and patches.
  16671. @item
  16672. @i{Jason F. McBrayer} suggested agenda export to CSV format.
  16673. @item
  16674. @i{Max Mikhanosha} came up with the idea of refiling and sticky agendas.
  16675. @item
  16676. @i{Dmitri Minaev} sent a patch to set priority limits on a per-file
  16677. basis.
  16678. @item
  16679. @i{Stefan Monnier} provided a patch to keep the Emacs-Lisp compiler
  16680. happy.
  16681. @item
  16682. @i{Richard Moreland} wrote MobileOrg for the iPhone.
  16683. @item
  16684. @i{Rick Moynihan} proposed allowing multiple TODO sequences in a file
  16685. and being able to quickly restrict the agenda to a subtree.
  16686. @item
  16687. @i{Todd Neal} provided patches for links to Info files and Elisp forms.
  16688. @item
  16689. @i{Greg Newman} refreshed the unicorn logo into its current form.
  16690. @item
  16691. @i{Tim O'Callaghan} suggested in-file links, search options for general
  16692. file links, and TAGS.
  16693. @item
  16694. @i{Osamu Okano} wrote @file{orgcard2ref.pl}, a Perl program to create a text
  16695. version of the reference card.
  16696. @item
  16697. @i{Takeshi Okano} translated the manual and David O'Toole's tutorial
  16698. into Japanese.
  16699. @item
  16700. @i{Oliver Oppitz} suggested multi-state TODO items.
  16701. @item
  16702. @i{Scott Otterson} sparked the introduction of descriptive text for
  16703. links, among other things.
  16704. @item
  16705. @i{Pete Phillips} helped during the development of the TAGS feature, and
  16706. provided frequent feedback.
  16707. @item
  16708. @i{Francesco Pizzolante} provided patches that helped speeding up the agenda
  16709. generation.
  16710. @item
  16711. @i{Martin Pohlack} provided the code snippet to bundle character insertion
  16712. into bundles of 20 for undo.
  16713. @item
  16714. @i{Rackspace.com} is hosting our website for free. Thank you Rackspace!
  16715. @item
  16716. @i{T.V. Raman} reported bugs and suggested improvements.
  16717. @item
  16718. @i{Matthias Rempe} (Oelde) provided ideas, Windows support, and quality
  16719. control.
  16720. @item
  16721. @i{Paul Rivier} provided the basic implementation of named footnotes. He
  16722. also acted as mailing list moderator for some time.
  16723. @item
  16724. @i{Kevin Rogers} contributed code to access VM files on remote hosts.
  16725. @item
  16726. @i{Frank Ruell} solved the mystery of the @code{keymapp nil} bug, a
  16727. conflict with @file{allout.el}.
  16728. @item
  16729. @i{Jason Riedy} generalized the send-receive mechanism for Orgtbl tables with
  16730. extensive patches.
  16731. @item
  16732. @i{Philip Rooke} created the Org reference card, provided lots
  16733. of feedback, developed and applied standards to the Org documentation.
  16734. @item
  16735. @i{Christian Schlauer} proposed angular brackets around links, among
  16736. other things.
  16737. @item
  16738. @i{Christopher Schmidt} reworked @code{orgstruct-mode} so that users can
  16739. enjoy folding in non-org buffers by using Org headlines in comments.
  16740. @item
  16741. @i{Paul Sexton} wrote @file{org-ctags.el}.
  16742. @item
  16743. Linking to VM/BBDB/Gnus was first inspired by @i{Tom Shannon}'s
  16744. @file{organizer-mode.el}.
  16745. @item
  16746. @i{Ilya Shlyakhter} proposed the Archive Sibling, line numbering in literal
  16747. examples, and remote highlighting for referenced code lines.
  16748. @item
  16749. @i{Stathis Sideris} wrote the @file{ditaa.jar} ASCII to PNG converter that is
  16750. now packaged into Org's @file{contrib} directory.
  16751. @item
  16752. @i{Daniel Sinder} came up with the idea of internal archiving by locking
  16753. subtrees.
  16754. @item
  16755. @i{Dale Smith} proposed link abbreviations.
  16756. @item
  16757. @i{James TD Smith} has contributed a large number of patches for useful
  16758. tweaks and features.
  16759. @item
  16760. @i{Adam Spiers} asked for global linking commands, inspired the link
  16761. extension system, added support for mairix, and proposed the mapping API.
  16762. @item
  16763. @i{Ulf Stegemann} created the table to translate special symbols to HTML,
  16764. @LaTeX{}, UTF-8, Latin-1 and ASCII.
  16765. @item
  16766. @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content
  16767. with links transformation to Org syntax.
  16768. @item
  16769. @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual
  16770. chapter about publishing.
  16771. @item
  16772. @i{Jambunathan K} contributed the ODT exporter and rewrote the HTML exporter.
  16773. @item
  16774. @i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and
  16775. enabled source code highlighting in Gnus.
  16776. @item
  16777. @i{Stefan Vollmar} organized a video-recorded talk at the
  16778. Max-Planck-Institute for Neurology. He also inspired the creation of a
  16779. concept index for HTML export.
  16780. @item
  16781. @i{Jürgen Vollmer} contributed code generating the table of contents
  16782. in HTML output.
  16783. @item
  16784. @i{Samuel Wales} has provided important feedback and bug reports.
  16785. @item
  16786. @i{Chris Wallace} provided a patch implementing the @samp{QUOTE}
  16787. keyword.
  16788. @item
  16789. @i{David Wainberg} suggested archiving, and improvements to the linking
  16790. system.
  16791. @item
  16792. @i{Carsten Wimmer} suggested some changes and helped fix a bug in
  16793. linking to Gnus.
  16794. @item
  16795. @i{Roland Winkler} requested additional key bindings to make Org
  16796. work on a tty.
  16797. @item
  16798. @i{Piotr Zielinski} wrote @file{org-mouse.el}, proposed agenda blocks
  16799. and contributed various ideas and code snippets.
  16800. @item
  16801. @i{Marco Wahl} wrote @file{org-eww.el}.
  16802. @end itemize
  16803. @node GNU Free Documentation License
  16804. @appendix GNU Free Documentation License
  16805. @include doclicense.texi
  16806. @node Main Index
  16807. @unnumbered Concept index
  16808. @printindex cp
  16809. @node Key Index
  16810. @unnumbered Key index
  16811. @printindex ky
  16812. @node Command and Function Index
  16813. @unnumbered Command and function index
  16814. @printindex fn
  16815. @node Variable Index
  16816. @unnumbered Variable index
  16817. This is not a complete index of variables and faces, only the ones that are
  16818. mentioned in the manual. For a complete list, use @kbd{M-x org-customize
  16819. @key{RET}}.
  16820. @printindex vr
  16821. @bye
  16822. @c Local variables:
  16823. @c fill-column: 77
  16824. @c indent-tabs-mode: nil
  16825. @c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$"
  16826. @c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$"
  16827. @c End:
  16828. @c LocalWords: webdavhost pre