| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040 |
- AsciiDoc User Guide
- ===================
- Stuart Rackham <srackham@gmail.com>
- :Author Initials: SJR
- :toc:
- :icons:
- :numbered:
- :website: http://www.methods.co.nz/asciidoc/
- AsciiDoc is a text document format for writing notes, documentation,
- articles, books, ebooks, slideshows, web pages, blogs and UNIX man
- pages. AsciiDoc files can be translated to many formats including
- HTML, PDF, EPUB, man page. AsciiDoc is highly configurable: both the
- AsciiDoc source file syntax and the backend output markups (which can
- be almost any type of SGML/XML markup) can be customized and extended
- by the user.
- .This document
- **********************************************************************
- This is an overly large document, it probably needs to be refactored
- into a Tutorial, Quick Reference and Formal Reference.
- If you're new to AsciiDoc read this section and the <<X6,Getting
- Started>> section and take a look at the example AsciiDoc (`*.txt`)
- source files in the distribution `doc` directory.
- **********************************************************************
- Introduction
- ------------
- AsciiDoc is a plain text human readable/writable document format that
- can be translated to DocBook or HTML using the asciidoc(1) command.
- You can then either use asciidoc(1) generated HTML directly or run
- asciidoc(1) DocBook output through your favorite DocBook toolchain or
- use the AsciiDoc a2x(1) toolchain wrapper to produce PDF, EPUB, DVI,
- LaTeX, PostScript, man page, HTML and text formats.
- The AsciiDoc format is a useful presentation format in its own right:
- AsciiDoc markup is simple, intuitive and as such is easily proofed and
- edited.
- AsciiDoc is light weight: it consists of a single Python script and a
- bunch of configuration files. Apart from asciidoc(1) and a Python
- interpreter, no other programs are required to convert AsciiDoc text
- files to DocBook or HTML. See <<X11,Example AsciiDoc Documents>>
- below.
- Text markup conventions tend to be a matter of (often strong) personal
- preference: if the default syntax is not to your liking you can define
- your own by editing the text based asciidoc(1) configuration files.
- You can also create configuration files to translate AsciiDoc
- documents to almost any SGML/XML markup.
- asciidoc(1) comes with a set of configuration files to translate
- AsciiDoc articles, books and man pages to HTML or DocBook backend
- formats.
- .My AsciiDoc Itch
- **********************************************************************
- DocBook has emerged as the de facto standard Open Source documentation
- format. But DocBook is a complex language, the markup is difficult to
- read and even more difficult to write directly -- I found I was
- spending more time typing markup tags, consulting reference manuals
- and fixing syntax errors, than I was writing the documentation.
- **********************************************************************
- [[X6]]
- Getting Started
- ---------------
- Installing AsciiDoc
- ~~~~~~~~~~~~~~~~~~~
- See the `README` and `INSTALL` files for install prerequisites and
- procedures. Packagers take a look at <<X38,Packager Notes>>.
- [[X11]]
- Example AsciiDoc Documents
- ~~~~~~~~~~~~~~~~~~~~~~~~~~
- The best way to quickly get a feel for AsciiDoc is to view the
- AsciiDoc web site and/or distributed examples:
- - Take a look at the linked examples on the AsciiDoc web site home
- page {website}. Press the 'Page Source' sidebar menu item to view
- corresponding AsciiDoc source.
- - Read the `*.txt` source files in the distribution `./doc` directory
- along with the corresponding HTML and DocBook XML files.
- AsciiDoc Document Types
- -----------------------
- There are three types of AsciiDoc documents: article, book and
- manpage. All document types share the same AsciiDoc format with some
- minor variations. If you are familiar with DocBook you will have
- noticed that AsciiDoc document types correspond to the same-named
- DocBook document types.
- Use the asciidoc(1) `-d` (`--doctype`) option to specify the AsciiDoc
- document type -- the default document type is 'article'.
- By convention the `.txt` file extension is used for AsciiDoc document
- source files.
- article
- ~~~~~~~
- Used for short documents, articles and general documentation. See the
- AsciiDoc distribution `./doc/article.txt` example.
- AsciiDoc defines standard DocBook article frontmatter and backmatter
- <<X93,section markup templates>> (appendix, abstract, bibliography,
- glossary, index).
- book
- ~~~~
- Books share the same format as articles, with the following
- differences:
- - The part titles in multi-part books are <<X17,top level titles>>
- (same level as book title).
- - Some sections are book specific e.g. preface and colophon.
- Book documents will normally be used to produce DocBook output since
- DocBook processors can automatically generate footnotes, table of
- contents, list of tables, list of figures, list of examples and
- indexes.
- AsciiDoc defines standard DocBook book frontmatter and backmatter
- <<X93,section markup templates>> (appendix, dedication, preface,
- bibliography, glossary, index, colophon).
- .Example book documents
- Book::
- The `./doc/book.txt` file in the AsciiDoc distribution.
- Multi-part book::
- The `./doc/book-multi.txt` file in the AsciiDoc distribution.
- manpage
- ~~~~~~~
- Used to generate roff format UNIX manual pages. AsciiDoc manpage
- documents observe special header title and section naming conventions
- -- see the <<X1,Manpage Documents>> section for details.
- AsciiDoc defines the 'synopsis' <<X93,section markup template>> to
- generate the DocBook `refsynopsisdiv` section.
- See also the asciidoc(1) man page source (`./doc/asciidoc.1.txt`) from
- the AsciiDoc distribution.
- [[X5]]
- AsciiDoc Backends
- -----------------
- The asciidoc(1) command translates an AsciiDoc formatted file to the
- backend format specified by the `-b` (`--backend`) command-line
- option. asciidoc(1) itself has little intrinsic knowledge of backend
- formats, all translation rules are contained in customizable cascading
- configuration files. Backend specific attributes are listed in the
- <<X88,Backend Attributes>> section.
- docbook45::
- Outputs DocBook XML 4.5 markup.
- html4::
- This backend generates plain HTML 4.01 Transitional markup.
- xhtml11::
- This backend generates XHTML 1.1 markup styled with CSS2. Output
- files have an `.html` extension.
- html5::
- This backend generates HTML 5 markup, apart from the inclusion of
- <<X98,audio and video block macros>> it is functionally identical to
- the 'xhtml11' backend.
- slidy::
- Use this backend to generate self-contained
- http://www.w3.org/Talks/Tools/Slidy2/[Slidy] HTML slideshows for
- your web browser from AsciiDoc documents. The Slidy backend is
- documented in the distribution `doc/slidy.txt` file and
- {website}slidy.html[online].
- wordpress::
- A minor variant of the 'html4' backend to support
- http://srackham.wordpress.com/blogpost1/[blogpost].
- latex::
- Experimental LaTeX backend.
- Backend Aliases
- ~~~~~~~~~~~~~~~
- Backend aliases are alternative names for AsciiDoc backends. AsciiDoc
- comes with two backend aliases: 'html' (aliased to 'xhtml11') and
- 'docbook' (aliased to 'docbook45').
- You can assign (or reassign) backend aliases by setting an AsciiDoc
- attribute named like `backend-alias-<alias>` to an AsciiDoc backend
- name. For example, the following backend alias attribute definitions
- appear in the `[attributes]` section of the global `asciidoc.conf`
- configuration file:
- backend-alias-html=xhtml11
- backend-alias-docbook=docbook45
- [[X100]]
- Backend Plugins
- ~~~~~~~~~~~~~~~
- The asciidoc(1) `--backend` option is also used to install and manage
- backend <<X101,plugins>>.
- - A backend plugin is used just like the built-in backends.
- - Backend plugins <<X27,take precedence>> over built-in backends with
- the same name.
- - You can use the `{asciidoc-confdir}` <<X60, intrinsic attribute>> to
- refer to the built-in backend configuration file location from
- backend plugin configuration files.
- - You can use the `{backend-confdir}` <<X60, intrinsic attribute>> to
- refer to the backend plugin configuration file location.
- - By default backends plugins are installed in
- `$HOME/.asciidoc/backends/<backend>` where `<backend>` is the
- backend name.
- DocBook
- -------
- AsciiDoc generates 'article', 'book' and 'refentry'
- http://www.docbook.org/[DocBook] documents (corresponding to the
- AsciiDoc 'article', 'book' and 'manpage' document types).
- Most Linux distributions come with conversion tools (collectively
- called a toolchain) for <<X12,converting DocBook files>> to
- presentation formats such as Postscript, HTML, PDF, EPUB, DVI,
- PostScript, LaTeX, roff (the native man page format), HTMLHelp,
- JavaHelp and text. There are also programs that allow you to view
- DocBook files directly, for example http://live.gnome.org/Yelp[Yelp]
- (the GNOME help viewer).
- [[X12]]
- Converting DocBook to other file formats
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- DocBook files are validated, parsed and translated various
- presentation file formats using a combination of applications
- collectively called a DocBook 'tool chain'. The function of a tool
- chain is to read the DocBook markup (produced by AsciiDoc) and
- transform it to a presentation format (for example HTML, PDF, HTML
- Help, EPUB, DVI, PostScript, LaTeX).
- A wide range of user output format requirements coupled with a choice
- of available tools and stylesheets results in many valid tool chain
- combinations.
- [[X43]]
- a2x Toolchain Wrapper
- ~~~~~~~~~~~~~~~~~~~~~
- One of the biggest hurdles for new users is installing, configuring
- and using a DocBook XML toolchain. `a2x(1)` can help -- it's a
- toolchain wrapper command that will generate XHTML (chunked and
- unchunked), PDF, EPUB, DVI, PS, LaTeX, man page, HTML Help and text
- file outputs from an AsciiDoc text file. `a2x(1)` does all the grunt
- work associated with generating and sequencing the toolchain commands
- and managing intermediate and output files. `a2x(1)` also optionally
- deploys admonition and navigation icons and a CSS stylesheet. See the
- `a2x(1)` man page for more details. In addition to `asciidoc(1)` you
- also need <<X40,xsltproc(1)>>, <<X13,DocBook XSL Stylesheets>> and
- optionally: <<X31,dblatex>> or <<X14,FOP>> (to generate PDF);
- `w3m(1)` or `lynx(1)` (to generate text).
- The following examples generate `doc/source-highlight-filter.pdf` from
- the AsciiDoc `doc/source-highlight-filter.txt` source file. The first
- example uses `dblatex(1)` (the default PDF generator) the second
- example forces FOP to be used:
- $ a2x -f pdf doc/source-highlight-filter.txt
- $ a2x -f pdf --fop doc/source-highlight-filter.txt
- See the `a2x(1)` man page for details.
- TIP: Use the `--verbose` command-line option to view executed
- toolchain commands.
- HTML generation
- ~~~~~~~~~~~~~~~
- AsciiDoc produces nicely styled HTML directly without requiring a
- DocBook toolchain but there are also advantages in going the DocBook
- route:
- - HTML from DocBook can optionally include automatically generated
- indexes, tables of contents, footnotes, lists of figures and tables.
- - DocBook toolchains can also (optionally) generate separate (chunked)
- linked HTML pages for each document section.
- - Toolchain processing performs link and document validity checks.
- - If the DocBook 'lang' attribute is set then things like table of
- contents, figure and table captions and admonition captions will be
- output in the specified language (setting the AsciiDoc 'lang'
- attribute sets the DocBook 'lang' attribute).
- On the other hand, HTML output directly from AsciiDoc is much faster,
- is easily customized and can be used in situations where there is no
- suitable DocBook toolchain (for example, see the {website}[AsciiDoc
- website]).
- PDF generation
- ~~~~~~~~~~~~~~
- There are two commonly used tools to generate PDFs from DocBook,
- <<X31,dblatex>> and <<X14,FOP>>.
- .dblatex or FOP?
- - 'dblatex' is easier to install, there's zero configuration
- required and no Java VM to install -- it just works out of the box.
- - 'dblatex' source code highlighting and numbering is superb.
- - 'dblatex' is easier to use as it converts DocBook directly to PDF
- whereas before using 'FOP' you have to convert DocBook to XML-FO
- using <<X13,DocBook XSL Stylesheets>>.
- - 'FOP' is more feature complete (for example, callouts are processed
- inside literal layouts) and arguably produces nicer looking output.
- HTML Help generation
- ~~~~~~~~~~~~~~~~~~~~
- . Convert DocBook XML documents to HTML Help compiler source files
- using <<X13,DocBook XSL Stylesheets>> and <<X40,xsltproc(1)>>.
- . Convert the HTML Help source (`.hhp` and `.html`) files to HTML Help
- (`.chm`) files using the <<X67,Microsoft HTML Help Compiler>>.
- Toolchain components summary
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- AsciiDoc::
- Converts AsciiDoc (`.txt`) files to DocBook XML (`.xml`) files.
- [[X13]]http://docbook.sourceforge.net/projects/xsl/[DocBook XSL Stylesheets]::
- These are a set of XSL stylesheets containing rules for converting
- DocBook XML documents to HTML, XSL-FO, manpage and HTML Help files.
- The stylesheets are used in conjunction with an XML parser such as
- <<X40,xsltproc(1)>>.
- [[X40]]http://www.xmlsoft.org[xsltproc]::
- An XML parser for applying XSLT stylesheets (in our case the
- <<X13,DocBook XSL Stylesheets>>) to XML documents.
- [[X31]]http://dblatex.sourceforge.net/[dblatex]::
- Generates PDF, DVI, PostScript and LaTeX formats directly from
- DocBook source via the intermediate LaTeX typesetting language --
- uses <<X13,DocBook XSL Stylesheets>>, <<X40,xsltproc(1)>> and
- `latex(1)`.
- [[X14]]http://xml.apache.org/fop/[FOP]::
- The Apache Formatting Objects Processor converts XSL-FO (`.fo`)
- files to PDF files. The XSL-FO files are generated from DocBook
- source files using <<X13,DocBook XSL Stylesheets>> and
- <<X40,xsltproc(1)>>.
- [[X67]]Microsoft Help Compiler::
- The Microsoft HTML Help Compiler (`hhc.exe`) is a command-line tool
- that converts HTML Help source files to a single HTML Help (`.chm`)
- file. It runs on MS Windows platforms and can be downloaded from
- http://www.microsoft.com.
- AsciiDoc dblatex configuration files
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The AsciiDoc distribution `./dblatex` directory contains
- `asciidoc-dblatex.xsl` (customized XSL parameter settings) and
- `asciidoc-dblatex.sty` (customized LaTeX settings). These are examples
- of optional <<X31,dblatex>> output customization and are used by
- <<X43,a2x(1)>>.
- AsciiDoc DocBook XSL Stylesheets drivers
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- You will have noticed that the distributed HTML and HTML Help
- documentation files (for example `./doc/asciidoc.html`) are not the
- plain outputs produced using the default 'DocBook XSL Stylesheets'
- configuration. This is because they have been processed using
- customized DocBook XSL Stylesheets along with (in the case of HTML
- outputs) the custom `./stylesheets/docbook-xsl.css` CSS stylesheet.
- You'll find the customized DocBook XSL drivers along with additional
- documentation in the distribution `./docbook-xsl` directory. The
- examples that follow are executed from the distribution documentation
- (`./doc`) directory. These drivers are also used by <<X43,a2x(1)>>.
- `common.xsl`::
- Shared driver parameters. This file is not used directly but is
- included in all the following drivers.
- `chunked.xsl`::
- Generate chunked XHTML (separate HTML pages for each document
- section) in the `./doc/chunked` directory. For example:
- $ python ../asciidoc.py -b docbook asciidoc.txt
- $ xsltproc --nonet ../docbook-xsl/chunked.xsl asciidoc.xml
- `epub.xsl`::
- Used by <<X43,a2x(1)>> to generate EPUB formatted documents.
- `fo.xsl`::
- Generate XSL Formatting Object (`.fo`) files for subsequent PDF
- file generation using FOP. For example:
- $ python ../asciidoc.py -b docbook article.txt
- $ xsltproc --nonet ../docbook-xsl/fo.xsl article.xml > article.fo
- $ fop article.fo article.pdf
- `htmlhelp.xsl`::
- Generate Microsoft HTML Help source files for the MS HTML Help
- Compiler in the `./doc/htmlhelp` directory. This example is run on
- MS Windows from a Cygwin shell prompt:
- $ python ../asciidoc.py -b docbook asciidoc.txt
- $ xsltproc --nonet ../docbook-xsl/htmlhelp.xsl asciidoc.xml
- $ c:/Program\ Files/HTML\ Help\ Workshop/hhc.exe htmlhelp.hhp
- `manpage.xsl`::
- Generate a `roff(1)` format UNIX man page from a DocBook XML
- 'refentry' document. This example generates an `asciidoc.1` man
- page file:
- $ python ../asciidoc.py -d manpage -b docbook asciidoc.1.txt
- $ xsltproc --nonet ../docbook-xsl/manpage.xsl asciidoc.1.xml
- `xhtml.xsl`::
- Convert a DocBook XML file to a single XHTML file. For example:
- $ python ../asciidoc.py -b docbook asciidoc.txt
- $ xsltproc --nonet ../docbook-xsl/xhtml.xsl asciidoc.xml > asciidoc.html
- If you want to see how the complete documentation set is processed
- take a look at the A-A-P script `./doc/main.aap`.
- Generating Plain Text Files
- ---------------------------
- AsciiDoc does not have a text backend (for most purposes AsciiDoc
- source text is fine), however you can convert AsciiDoc text files to
- formatted text using the AsciiDoc <<X43,a2x(1)>> toolchain wrapper
- utility.
- [[X35]]
- HTML5 and XHTML 1.1
- -------------------
- The 'xhtml11' and 'html5' backends embed or link CSS and JavaScript
- files in their outputs, there is also a <<X99,themes>> plugin
- framework.
- - If the AsciiDoc 'linkcss' attribute is defined then CSS and
- JavaScript files are linked to the output document, otherwise they
- are embedded (the default behavior).
- - The default locations for CSS and JavaScript files can be changed by
- setting the AsciiDoc 'stylesdir' and 'scriptsdir' attributes
- respectively.
- - The default locations for embedded and linked files differ and are
- calculated at different times -- embedded files are loaded when
- asciidoc(1) generates the output document, linked files are loaded
- by the browser when the user views the output document.
- - Embedded files are automatically inserted in the output files but
- you need to manually copy linked CSS and Javascript files from
- AsciiDoc <<X27,configuration directories>> to the correct location
- relative to the output document.
- .Stylesheet file locations
- [cols="3*",frame="topbot",options="header"]
- |====================================================================
- |'stylesdir' attribute
- |Linked location ('linkcss' attribute defined)
- |Embedded location ('linkcss' attribute undefined)
- |Undefined (default).
- |Same directory as the output document.
- |`stylesheets` subdirectory in the AsciiDoc configuration directory
- (the directory containing the backend conf file).
- |Absolute or relative directory name.
- |Absolute or relative to the output document.
- |Absolute or relative to the AsciiDoc configuration directory (the
- directory containing the backend conf file).
- |====================================================================
- .JavaScript file locations
- [cols="3*",frame="topbot",options="header"]
- |====================================================================
- |'scriptsdir' attribute
- |Linked location ('linkcss' attribute defined)
- |Embedded location ('linkcss' attribute undefined)
- |Undefined (default).
- |Same directory as the output document.
- |`javascripts` subdirectory in the AsciiDoc configuration directory
- (the directory containing the backend conf file).
- |Absolute or relative directory name.
- |Absolute or relative to the output document.
- |Absolute or relative to the AsciiDoc configuration directory (the
- directory containing the backend conf file).
- |====================================================================
- [[X99]]
- Themes
- ~~~~~~
- The AsciiDoc 'theme' attribute is used to select an alternative CSS
- stylesheet and to optionally include additional JavaScript code.
- - Theme files reside in an AsciiDoc <<X27,configuration directory>>
- named `themes/<theme>/` (where `<theme>` is the the theme name set
- by the 'theme' attribute). asciidoc(1) sets the 'themedir' attribute
- to the theme directory path name.
- - The 'theme' attribute can also be set using the asciidoc(1)
- `--theme` option, the `--theme` option can also be used to manage
- theme <<X101,plugins>>.
- - AsciiDoc ships with two themes: 'flask' and 'volnitsky'.
- - The `<theme>.css` file replaces the default `asciidoc.css` CSS file.
- - The `<theme>.js` file is included in addition to the default
- `asciidoc.js` JavaScript file.
- - If the <<X66,data-uri>> attribute is defined then icons are loaded
- from the theme `icons` sub-directory if it exists (i.e. the
- 'iconsdir' attribute is set to theme `icons` sub-directory path).
- - Embedded theme files are automatically inserted in the output files
- but you need to manually copy linked CSS and Javascript files to the
- location of the output documents.
- - Linked CSS and JavaScript theme files are linked to the same linked
- locations as <<X35,other CSS and JavaScript files>>.
- For example, the command-line option `--theme foo` (or `--attribute
- theme=foo`) will cause asciidoc(1) to search <<"X27","configuration
- file locations 1, 2 and 3">> for a sub-directory called `themes/foo`
- containing the stylesheet `foo.css` and optionally a JavaScript file
- name `foo.js`.
- Document Structure
- ------------------
- An AsciiDoc document consists of a series of <<X8,block elements>>
- starting with an optional document Header, followed by an optional
- Preamble, followed by zero or more document Sections.
- Almost any combination of zero or more elements constitutes a valid
- AsciiDoc document: documents can range from a single sentence to a
- multi-part book.
- Block Elements
- ~~~~~~~~~~~~~~
- Block elements consist of one or more lines of text and may contain
- other block elements.
- The AsciiDoc block structure can be informally summarized as follows
- footnote:[This is a rough structural guide, not a rigorous syntax
- definition]:
- Document ::= (Header?,Preamble?,Section*)
- Header ::= (Title,(AuthorInfo,RevisionInfo?)?)
- AuthorInfo ::= (FirstName,(MiddleName?,LastName)?,EmailAddress?)
- RevisionInfo ::= (RevisionNumber?,RevisionDate,RevisionRemark?)
- Preamble ::= (SectionBody)
- Section ::= (Title,SectionBody?,(Section)*)
- SectionBody ::= ((BlockTitle?,Block)|BlockMacro)+
- Block ::= (Paragraph|DelimitedBlock|List|Table)
- List ::= (BulletedList|NumberedList|LabeledList|CalloutList)
- BulletedList ::= (ListItem)+
- NumberedList ::= (ListItem)+
- CalloutList ::= (ListItem)+
- LabeledList ::= (ListEntry)+
- ListEntry ::= (ListLabel,ListItem)
- ListLabel ::= (ListTerm+)
- ListItem ::= (ItemText,(List|ListParagraph|ListContinuation)*)
- Where:
- - '?' implies zero or one occurrence, '+' implies one or more
- occurrences, '*' implies zero or more occurrences.
- - All block elements are separated by line boundaries.
- - `BlockId`, `AttributeEntry` and `AttributeList` block elements (not
- shown) can occur almost anywhere.
- - There are a number of document type and backend specific
- restrictions imposed on the block syntax.
- - The following elements cannot contain blank lines: Header, Title,
- Paragraph, ItemText.
- - A ListParagraph is a Paragraph with its 'listelement' option set.
- - A ListContinuation is a <<X15,list continuation element>>.
- [[X95]]
- Header
- ~~~~~~
- The Header contains document meta-data, typically title plus optional
- authorship and revision information:
- - The Header is optional, but if it is used it must start with a
- document <<X17,title>>.
- - Optional Author and Revision information immediately follows the
- header title.
- - The document header must be separated from the remainder of the
- document by one or more blank lines and cannot contain blank lines.
- - The header can include comments.
- - The header can include <<X18,attribute entries>>, typically
- 'doctype', 'lang', 'encoding', 'icons', 'data-uri', 'toc',
- 'numbered'.
- - Header attributes are overridden by command-line attributes.
- - If the header contains non-UTF-8 characters then the 'encoding' must
- precede the header (either in the document or on the command-line).
- Here's an example AsciiDoc document header:
- Writing Documentation using AsciiDoc
- ====================================
- Joe Bloggs <jbloggs@mymail.com>
- v2.0, February 2003:
- Rewritten for version 2 release.
- The author information line contains the author's name optionally
- followed by the author's email address. The author's name is formatted
- like:
- firstname[ [middlename ]lastname][ <email>]]
- i.e. a first name followed by optional middle and last names followed
- by an email address in that order. Multi-word first, middle and last
- names can be entered using the underscore as a word separator. The
- email address comes last and must be enclosed in angle <> brackets.
- Here a some examples of author information lines:
- Joe Bloggs <jbloggs@mymail.com>
- Joe Bloggs
- Vincent Willem van_Gogh
- If the author line does not match the above specification then the
- entire author line is treated as the first name.
- The optional revision information line follows the author information
- line. The revision information can be one of two formats:
- . An optional document revision number followed by an optional
- revision date followed by an optional revision remark:
- +
- --
- * If the revision number is specified it must be followed by a
- comma.
- * The revision number must contain at least one numeric character.
- * Any non-numeric characters preceding the first numeric character
- will be dropped.
- * If a revision remark is specified it must be preceded by a colon.
- The revision remark extends from the colon up to the next blank
- line, attribute entry or comment and is subject to normal text
- substitutions.
- * If a revision number or remark has been set but the revision date
- has not been set then the revision date is set to the value of the
- 'docdate' attribute.
- Examples:
- v2.0, February 2003
- February 2003
- v2.0,
- v2.0, February 2003: Rewritten for version 2 release.
- February 2003: Rewritten for version 2 release.
- v2.0,: Rewritten for version 2 release.
- :Rewritten for version 2 release.
- --
- . The revision information line can also be an RCS/CVS/SVN $Id$
- marker:
- +
- --
- * AsciiDoc extracts the 'revnumber', 'revdate', and 'author'
- attributes from the $Id$ revision marker and displays them in the
- document header.
- * If an $Id$ revision marker is used the header author line can be
- omitted.
- Example:
- $Id: mydoc.txt,v 1.5 2009/05/17 17:58:44 jbloggs Exp $
- --
- You can override or set header parameters by passing 'revnumber',
- 'revremark', 'revdate', 'email', 'author', 'authorinitials',
- 'firstname' and 'lastname' attributes using the asciidoc(1) `-a`
- (`--attribute`) command-line option. For example:
- $ asciidoc -a revdate=2004/07/27 article.txt
- Attribute entries can also be added to the header for substitution in
- the header template with <<X18,Attribute Entry>> elements.
- The 'title' element in HTML outputs is set to the AsciiDoc document
- title, you can set it to a different value by including a 'title'
- attribute entry in the document header.
- [[X87]]
- Additional document header information
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- AsciiDoc has two mechanisms for optionally including additional
- meta-data in the header of the output document:
- 'docinfo' configuration file sections::
- If a <<X7,configuration file>> section named 'docinfo' has been loaded
- then it will be included in the document header. Typically the
- 'docinfo' section name will be prefixed with a '+' character so that it
- is appended to (rather than replace) other 'docinfo' sections.
- 'docinfo' files::
- Two docinfo files are recognized: one named `docinfo` and a second
- named like the AsciiDoc source file with a `-docinfo` suffix. For
- example, if the source document is called `mydoc.txt` then the
- document information files would be `docinfo.xml` and
- `mydoc-docinfo.xml` (for DocBook outputs) and `docinfo.html` and
- `mydoc-docinfo.html` (for HTML outputs). The <<X97,docinfo, docinfo1
- and docinfo2>> attributes control which docinfo files are included in
- the output files.
- The contents docinfo templates and files is dependent on the type of
- output:
- HTML::
- Valid 'head' child elements. Typically 'style' and 'script' elements
- for CSS and JavaScript inclusion.
- DocBook::
- Valid 'articleinfo' or 'bookinfo' child elements. DocBook defines
- numerous elements for document meta-data, for example: copyrights,
- document history and authorship information. See the DocBook
- `./doc/article-docinfo.xml` example that comes with the AsciiDoc
- distribution. The rendering of meta-data elements (or not) is
- DocBook processor dependent.
- [[X86]]
- Preamble
- ~~~~~~~~
- The Preamble is an optional untitled section body between the document
- Header and the first Section title.
- Sections
- ~~~~~~~~
- In addition to the document title (level 0), AsciiDoc supports four
- section levels: 1 (top) to 4 (bottom). Section levels are delimited
- by section <<X17,titles>>. Sections are translated using
- configuration file <<X93,section markup templates>>. AsciiDoc
- generates the following <<X60,intrinsic attributes>> specifically for
- use in section markup templates:
- level::
- The `level` attribute is the section level number, it is normally just
- the <<X17,title>> level number (1..4). However, if the `leveloffset`
- attribute is defined it will be added to the `level` attribute. The
- `leveloffset` attribute is useful for <<X90,combining documents>>.
- sectnum::
- The `-n` (`--section-numbers`) command-line option generates the
- `sectnum` (section number) attribute. The `sectnum` attribute is used
- for section numbers in HTML outputs (DocBook section numbering are
- handled automatically by the DocBook toolchain commands).
- [[X93]]
- Section markup templates
- ^^^^^^^^^^^^^^^^^^^^^^^^
- Section markup templates specify output markup and are defined in
- AsciiDoc configuration files. Section markup template names are
- derived as follows (in order of precedence):
- 1. From the title's first positional attribute or 'template'
- attribute. For example, the following three section titles are
- functionally equivalent:
- +
- .....................................................................
- [[terms]]
- [glossary]
- List of Terms
- -------------
- ["glossary",id="terms"]
- List of Terms
- -------------
- [template="glossary",id="terms"]
- List of Terms
- -------------
- .....................................................................
- 2. When the title text matches a configuration file
- <<X16,`[specialsections]`>> entry.
- 3. If neither of the above the default `sect<level>` template is used
- (where `<level>` is a number from 1 to 4).
- In addition to the normal section template names ('sect1', 'sect2',
- 'sect3', 'sect4') AsciiDoc has the following templates for
- frontmatter, backmatter and other special sections: 'abstract',
- 'preface', 'colophon', 'dedication', 'glossary', 'bibliography',
- 'synopsis', 'appendix', 'index'. These special section templates
- generate the corresponding Docbook elements; for HTML outputs they
- default to the 'sect1' section template.
- Section IDs
- ^^^^^^^^^^^
- If no explicit section ID is specified an ID will be synthesised from
- the section title. The primary purpose of this feature is to ensure
- persistence of table of contents links (permalinks): the missing
- section IDs are generated dynamically by the JavaScript TOC generator
- *after* the page is loaded. If you link to a dynamically generated TOC
- address the page will load but the browser will ignore the (as yet
- ungenerated) section ID.
- The IDs are generated by the following algorithm:
- - Replace all non-alphanumeric title characters with underscores.
- - Strip leading or trailing underscores.
- - Convert to lowercase.
- - Prepend the `idprefix` attribute (so there's no possibility of name
- clashes with existing document IDs). Prepend an underscore if the
- `idprefix` attribute is not defined.
- - A numbered suffix (`_2`, `_3` ...) is added if a same named
- auto-generated section ID exists.
- - If the `ascii-ids` attribute is defined then non-ASCII characters
- are replaced with ASCII equivalents. This attribute may be
- deprecated in future releases and *should be avoided*, it's sole
- purpose is to accommodate deficient downstream applications that
- cannot process non-ASCII ID attributes.
- Example: the title 'Jim's House' would generate the ID `_jim_s_house`.
- Section ID synthesis can be disabled by undefining the `sectids`
- attribute.
- [[X16]]
- Special Section Titles
- ^^^^^^^^^^^^^^^^^^^^^^
- AsciiDoc has a mechanism for mapping predefined section titles
- auto-magically to specific markup templates. For example a title
- 'Appendix A: Code Reference' will automatically use the 'appendix'
- <<X93,section markup template>>. The mappings from title to template
- name are specified in `[specialsections]` sections in the Asciidoc
- language configuration files (`lang-*.conf`). Section entries are
- formatted like:
- <title>=<template>
- `<title>` is a Python regular expression and `<template>` is the name
- of a configuration file markup template section. If the `<title>`
- matches an AsciiDoc document section title then the backend output is
- marked up using the `<template>` markup template (instead of the
- default `sect<level>` section template). The `{title}` attribute value
- is set to the value of the matched regular expression group named
- 'title', if there is no 'title' group `{title}` defaults to the whole
- of the AsciiDoc section title. If `<template>` is blank then any
- existing entry with the same `<title>` will be deleted.
- .Special section titles vs. explicit template names
- *********************************************************************
- AsciiDoc has two mechanisms for specifying non-default section markup
- templates: you can specify the template name explicitly (using the
- 'template' attribute) or indirectly (using 'special section titles').
- Specifying a <<X93,section template>> attribute explicitly is
- preferred. Auto-magical 'special section titles' have the following
- drawbacks:
- - They are non-obvious, you have to know the exact matching
- title for each special section on a language by language basis.
- - Section titles are predefined and can only be customised with a
- configuration change.
- - The implementation is complicated by multiple languages: every
- special section title has to be defined for each language (in each
- of the `lang-*.conf` files).
- Specifying special section template names explicitly does add more
- noise to the source document (the 'template' attribute declaration),
- but the intention is obvious and the syntax is consistent with other
- AsciiDoc elements c.f. bibliographic, Q&A and glossary lists.
- Special section titles have been deprecated but are retained for
- backward compatibility.
- *********************************************************************
- Inline Elements
- ~~~~~~~~~~~~~~~
- <<X34,Inline document elements>> are used to format text and to
- perform various types of text substitution. Inline elements and inline
- element syntax is defined in the asciidoc(1) configuration files.
- Here is a list of AsciiDoc inline elements in the (default) order in
- which they are processed:
- Special characters::
- These character sequences escape special characters used by
- the backend markup (typically `<`, `>`, and `&` characters).
- See `[specialcharacters]` configuration file sections.
- Quotes::
- Elements that markup words and phrases; usually for character
- formatting. See `[quotes]` configuration file sections.
- Special Words::
- Word or word phrase patterns singled out for markup without
- the need for further annotation. See `[specialwords]`
- configuration file sections.
- Replacements::
- Each replacement defines a word or word phrase pattern to
- search for along with corresponding replacement text. See
- `[replacements]` configuration file sections.
- Attribute references::
- Document attribute names enclosed in braces are replaced by
- the corresponding attribute value.
- Inline Macros::
- Inline macros are replaced by the contents of parametrized
- configuration file sections.
- Document Processing
- -------------------
- The AsciiDoc source document is read and processed as follows:
- 1. The document 'Header' is parsed, header parameter values are
- substituted into the configuration file `[header]` template section
- which is then written to the output file.
- 2. Each document 'Section' is processed and its constituent elements
- translated to the output file.
- 3. The configuration file `[footer]` template section is substituted
- and written to the output file.
- When a block element is encountered asciidoc(1) determines the type of
- block by checking in the following order (first to last): (section)
- Titles, BlockMacros, Lists, DelimitedBlocks, Tables, AttributeEntrys,
- AttributeLists, BlockTitles, Paragraphs.
- The default paragraph definition `[paradef-default]` is last element
- to be checked.
- Knowing the parsing order will help you devise unambiguous macro, list
- and block syntax rules.
- Inline substitutions within block elements are performed in the
- following default order:
- 1. Special characters
- 2. Quotes
- 3. Special words
- 4. Replacements
- 5. Attributes
- 6. Inline Macros
- 7. Replacements2
- The substitutions and substitution order performed on
- Title, Paragraph and DelimitedBlock elements is determined by
- configuration file parameters.
- Text Formatting
- ---------------
- [[X51]]
- Quoted Text
- ~~~~~~~~~~~
- Words and phrases can be formatted by enclosing inline text with
- quote characters:
- _Emphasized text_::
- Word phrases \'enclosed in single quote characters' (acute
- accents) or \_underline characters_ are emphasized.
- *Strong text*::
- Word phrases \*enclosed in asterisk characters* are rendered
- in a strong font (usually bold).
- [[X81]]+Monospaced text+::
- Word phrases \+enclosed in plus characters+ are rendered in a
- monospaced font. Word phrases \`enclosed in backtick
- characters` (grave accents) are also rendered in a monospaced
- font but in this case the enclosed text is rendered literally
- and is not subject to further expansion (see <<X80,inline
- literal passthrough>>).
- `Single quoted text'::
- Phrases enclosed with a \`single grave accent to the left and
- a single acute accent to the right' are rendered in single
- quotation marks.
- ``Double quoted text''::
- Phrases enclosed with \\``two grave accents to the left and
- two acute accents to the right'' are rendered in quotation
- marks.
- #Unquoted text#::
- Placing \#hashes around text# does nothing, it is a mechanism
- to allow inline attributes to be applied to otherwise
- unformatted text.
- New quote types can be defined by editing asciidoc(1) configuration
- files. See the <<X7,Configuration Files>> section for details.
- .Quoted text behavior
- - Quoting cannot be overlapped.
- - Different quoting types can be nested.
- - To suppress quoted text formatting place a backslash character
- immediately in front of the leading quote character(s). In the case
- of ambiguity between escaped and non-escaped text you will need to
- escape both leading and trailing quotes, in the case of
- multi-character quotes you may even need to escape individual
- characters.
- [[X96]]
- Quoted text attributes
- ^^^^^^^^^^^^^^^^^^^^^^
- Quoted text can be prefixed with an <<X21,attribute list>>. The first
- positional attribute ('role' attribute) is translated by AsciiDoc to
- an HTML 'span' element 'class' attribute or a DocBook 'phrase' element
- 'role' attribute.
- DocBook XSL Stylesheets translate DocBook 'phrase' elements with
- 'role' attributes to corresponding HTML 'span' elements with the same
- 'class' attributes; CSS can then be used
- http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
- generated HTML]. Thus CSS styling can be applied to both DocBook and
- AsciiDoc generated HTML outputs. You can also specify multiple class
- names separated by spaces.
- CSS rules for text color, text background color, text size and text
- decorators are included in the distributed AsciiDoc CSS files and are
- used in conjunction with AsciiDoc 'xhtml11', 'html5' and 'docbook'
- outputs. The CSS class names are:
- - '<color>' (text foreground color).
- - '<color>-background' (text background color).
- - 'big' and 'small' (text size).
- - 'underline', 'overline' and 'line-through' (strike through) text
- decorators.
- Where '<color>' can be any of the
- http://en.wikipedia.org/wiki/Web_colors#HTML_color_names[sixteen HTML
- color names]. Examples:
- [red]#Obvious# and [big red yellow-background]*very obvious*.
- [underline]#Underline text#, [overline]#overline text# and
- [blue line-through]*bold blue and line-through*.
- is rendered as:
- [red]#Obvious# and [big red yellow-background]*very obvious*.
- [underline]#Underline text#, [overline]#overline text# and
- [bold blue line-through]*bold blue and line-through*.
- NOTE: Color and text decorator attributes are rendered for XHTML and
- HTML 5 outputs using CSS stylesheets. The mechanism to implement
- color and text decorator attributes is provided for DocBook toolchains
- via the DocBook 'phrase' element 'role' attribute, but the actual
- rendering is toolchain specific and is not part of the AsciiDoc
- distribution.
- [[X52]]
- Constrained and Unconstrained Quotes
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- There are actually two types of quotes:
- Constrained quotes
- ++++++++++++++++++
- Quoted must be bounded by white space or commonly adjoining
- punctuation characters. These are the most commonly used type of
- quote.
- Unconstrained quotes
- ++++++++++++++++++++
- Unconstrained quotes have no boundary constraints and can be placed
- anywhere within inline text. For consistency and to make them easier
- to remember unconstrained quotes are double-ups of the `_`, `*`, `+`
- and `#` constrained quotes:
- __unconstrained emphasized text__
- **unconstrained strong text**
- ++unconstrained monospaced text++
- ##unconstrained unquoted text##
- The following example emboldens the letter F:
- **F**ile Open...
- Superscripts and Subscripts
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Put \^carets on either^ side of the text to be superscripted, put
- \~tildes on either side~ of text to be subscripted. For example, the
- following line:
- e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
- and ~some sub text~
- Is rendered like:
- e^πi^+1 = 0. H~2~O and x^10^. Some ^super text^
- and ~some sub text~
- Superscripts and subscripts are implemented as <<X52,unconstrained
- quotes>> and they can be escaped with a leading backslash and prefixed
- with with an attribute list.
- Line Breaks
- ~~~~~~~~~~~
- A plus character preceded by at least one space character at the end
- of a non-blank line forces a line break. It generates a line break
- (`br`) tag for HTML outputs and a custom XML `asciidoc-br` processing
- instruction for DocBook outputs. The `asciidoc-br` processing
- instruction is handled by <<X43,a2x(1)>>.
- Page Breaks
- ~~~~~~~~~~~
- A line of three or more less-than (`<<<`) characters will generate a
- hard page break in DocBook and printed HTML outputs. It uses the CSS
- `page-break-after` property for HTML outputs and a custom XML
- `asciidoc-pagebreak` processing instruction for DocBook outputs. The
- `asciidoc-pagebreak` processing instruction is handled by
- <<X43,a2x(1)>>. Hard page breaks are sometimes handy but as a general
- rule you should let your page processor generate page breaks for you.
- Rulers
- ~~~~~~
- A line of three or more apostrophe characters will generate a ruler
- line. It generates a ruler (`hr`) tag for HTML outputs and a custom
- XML `asciidoc-hr` processing instruction for DocBook outputs. The
- `asciidoc-hr` processing instruction is handled by <<X43,a2x(1)>>.
- Tabs
- ~~~~
- By default tab characters input files will translated to 8 spaces. Tab
- expansion is set with the 'tabsize' entry in the configuration file
- `[miscellaneous]` section and can be overridden in included files by
- setting a 'tabsize' attribute in the `include` macro's attribute list.
- For example:
- include::addendum.txt[tabsize=2]
- The tab size can also be set using the attribute command-line option,
- for example `--attribute tabsize=4`
- Replacements
- ~~~~~~~~~~~~
- The following replacements are defined in the default AsciiDoc
- configuration:
- (C) copyright, (TM) trademark, (R) registered trademark,
- -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
- double arrow, <= left double arrow.
- Which are rendered as:
- (C) copyright, (TM) trademark, (R) registered trademark,
- -- em dash, ... ellipsis, -> right arrow, <- left arrow, => right
- double arrow, <= left double arrow.
- You can also include arbitrary entity references in the AsciiDoc
- source. Examples:
- ➊ ¶
- renders:
- ➊ ¶
- To render a replacement literally escape it with a leading back-slash.
- The <<X7,Configuration Files>> section explains how to configure your
- own replacements.
- Special Words
- ~~~~~~~~~~~~~
- Words defined in `[specialwords]` configuration file sections are
- automatically marked up without having to be explicitly notated.
- The <<X7,Configuration Files>> section explains how to add and replace
- special words.
- [[X17]]
- Titles
- ------
- Document and section titles can be in either of two formats:
- Two line titles
- ~~~~~~~~~~~~~~~
- A two line title consists of a title line, starting hard against the
- left margin, and an underline. Section underlines consist a repeated
- character pairs spanning the width of the preceding title (give or
- take up to two characters):
- The default title underlines for each of the document levels are:
- Level 0 (top level): ======================
- Level 1: ----------------------
- Level 2: ~~~~~~~~~~~~~~~~~~~~~~
- Level 3: ^^^^^^^^^^^^^^^^^^^^^^
- Level 4 (bottom level): ++++++++++++++++++++++
- Examples:
- Level One Section Title
- -----------------------
- Level 2 Subsection Title
- ~~~~~~~~~~~~~~~~~~~~~~~~
- [[X46]]
- One line titles
- ~~~~~~~~~~~~~~~
- One line titles consist of a single line delimited on either side by
- one or more equals characters (the number of equals characters
- corresponds to the section level minus one). Here are some examples:
- = Document Title (level 0) =
- == Section title (level 1) ==
- === Section title (level 2) ===
- ==== Section title (level 3) ====
- ===== Section title (level 4) =====
- [NOTE]
- =====================================================================
- - One or more spaces must fall between the title and the delimiters.
- - The trailing title delimiter is optional.
- - The one-line title syntax can be changed by editing the
- configuration file `[titles]` section `sect0`...`sect4` entries.
- =====================================================================
- Floating titles
- ~~~~~~~~~~~~~~~
- Setting the title's first positional attribute or 'style' attribute to
- 'float' generates a free-floating title. A free-floating title is
- rendered just like a normal section title but is not formally
- associated with a text body and is not part of the regular section
- hierarchy so the normal ordering rules do not apply. Floating titles
- can also be used in contexts where section titles are illegal: for
- example sidebar and admonition blocks. Example:
- [float]
- The second day
- ~~~~~~~~~~~~~~
- Floating titles do not appear in a document's table of contents.
- [[X42]]
- Block Titles
- ------------
- A 'BlockTitle' element is a single line beginning with a period
- followed by the title text. A BlockTitle is applied to the immediately
- following Paragraph, DelimitedBlock, List, Table or BlockMacro. For
- example:
- ........................
- .Notes
- - Note 1.
- - Note 2.
- ........................
- is rendered as:
- .Notes
- - Note 1.
- - Note 2.
- [[X41]]
- BlockId Element
- ---------------
- A 'BlockId' is a single line block element containing a unique
- identifier enclosed in double square brackets. It is used to assign an
- identifier to the ensuing block element. For example:
- [[chapter-titles]]
- Chapter titles can be ...
- The preceding example identifies the ensuing paragraph so it can be
- referenced from other locations, for example with
- `<<chapter-titles,chapter titles>>`.
- 'BlockId' elements can be applied to Title, Paragraph, List,
- DelimitedBlock, Table and BlockMacro elements. The BlockId element
- sets the `{id}` attribute for substitution in the subsequent block's
- markup template. If a second positional argument is supplied it sets
- the `{reftext}` attribute which is used to set the DocBook `xreflabel`
- attribute.
- The 'BlockId' element has the same syntax and serves the same function
- to the <<X30,anchor inline macro>>.
- [[X79]]
- AttributeList Element
- ---------------------
- An 'AttributeList' block element is an <<X21,attribute list>> on a
- line by itself:
- - 'AttributeList' attributes are only applied to the immediately
- following block element -- the attributes are made available to the
- block's markup template.
- - Multiple contiguous 'AttributeList' elements are additively combined
- in the order they appear..
- - The first positional attribute in the list is often used to specify
- the ensuing element's <<X23,style>>.
- Attribute value substitution
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- By default, only substitutions that take place inside attribute list
- values are attribute references, this is because not all attributes
- are destined to be marked up and rendered as text (for example the
- table 'cols' attribute). To perform normal inline text substitutions
- (special characters, quotes, macros, replacements) on an attribute
- value you need to enclose it in single quotes. In the following quote
- block the second attribute value in the AttributeList is quoted to
- ensure the 'http' macro is expanded to a hyperlink.
- ---------------------------------------------------------------------
- [quote,'http://en.wikipedia.org/wiki/Samuel_Johnson[Samuel Johnson]']
- _____________________________________________________________________
- Sir, a woman's preaching is like a dog's walking on his hind legs. It
- is not done well; but you are surprised to find it done at all.
- _____________________________________________________________________
- ---------------------------------------------------------------------
- Common attributes
- ~~~~~~~~~~~~~~~~~
- Most block elements support the following attributes:
- [cols="1e,1,5a",frame="topbot",options="header"]
- |====================================================================
- |Name |Backends |Description
- |id |html4, html5, xhtml11, docbook |
- Unique identifier typically serve as link targets.
- Can also be set by the 'BlockId' element.
- |role |html4, html5, xhtml11, docbook |
- Role contains a string used to classify or subclassify an element and
- can be applied to AsciiDoc block elements. The AsciiDoc 'role'
- attribute is translated to the 'role' attribute in DocBook outputs and
- is included in the 'class' attribute in HTML outputs, in this respect
- it behaves like the <<X96,quoted text role attribute>>.
- DocBook XSL Stylesheets translate DocBook 'role' attributes to HTML
- 'class' attributes; CSS can then be used
- http://www.sagehill.net/docbookxsl/UsingCSS.html[to style the
- generated HTML].
- |reftext |docbook |
- 'reftext' is used to set the DocBook 'xreflabel' attribute.
- The 'reftext' attribute can an also be set by the 'BlockId' element.
- |====================================================================
- Paragraphs
- ----------
- Paragraphs are blocks of text terminated by a blank line, the end of
- file, or the start of a delimited block or a list. There are three
- paragraph syntaxes: normal, indented (literal) and admonition which
- are rendered, by default, with the corresponding paragraph style.
- Each syntax has a default style, but you can explicitly apply any
- paragraph style to any paragraph syntax. You can also apply
- <<X104,delimited block>> styles to single paragraphs.
- The built-in paragraph styles are: 'normal', 'literal', 'verse',
- 'quote', 'listing', 'TIP', 'NOTE', 'IMPORTANT', 'WARNING', 'CAUTION',
- 'abstract', 'partintro', 'comment', 'example', 'sidebar', 'source',
- 'music', 'latex', 'graphviz'.
- normal paragraph syntax
- ~~~~~~~~~~~~~~~~~~~~~~~
- Normal paragraph syntax consists of one or more non-blank lines of
- text. The first line must start hard against the left margin (no
- intervening white space). The default processing expectation is that
- of a normal paragraph of text.
- [[X85]]
- literal paragraph syntax
- ~~~~~~~~~~~~~~~~~~~~~~~~
- Literal paragraphs are rendered verbatim in a monospaced font without
- any distinguishing background or border. By default there is no text
- formatting or substitutions within Literal paragraphs apart from
- Special Characters and Callouts.
- The 'literal' style is applied implicitly to indented paragraphs i.e.
- where the first line of the paragraph is indented by one or more space
- or tab characters. For example:
- ---------------------------------------------------------------------
- Consul *necessitatibus* per id,
- consetetur, eu pro everti postulant
- homero verear ea mea, qui.
- ---------------------------------------------------------------------
- Renders:
- Consul *necessitatibus* per id,
- consetetur, eu pro everti postulant
- homero verear ea mea, qui.
- NOTE: Because <<X64,lists>> can be indented it's possible for your
- indented paragraph to be misinterpreted as a list -- in situations
- like this apply the 'literal' style to a normal paragraph.
- Instead of using a paragraph indent you could apply the 'literal'
- style explicitly, for example:
- ---------------------------------------------------------------------
- [literal]
- Consul *necessitatibus* per id,
- consetetur, eu pro everti postulant
- homero verear ea mea, qui.
- ---------------------------------------------------------------------
- Renders:
- [literal]
- Consul *necessitatibus* per id,
- consetetur, eu pro everti postulant
- homero verear ea mea, qui.
- [[X94]]
- quote and verse paragraph styles
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The optional 'attribution' and 'citetitle' attributes (positional
- attributes 2 and 3) specify the author and source respectively.
- The 'verse' style retains the line breaks, for example:
- ---------------------------------------------------------------------
- [verse, William Blake, from Auguries of Innocence]
- To see a world in a grain of sand,
- And a heaven in a wild flower,
- Hold infinity in the palm of your hand,
- And eternity in an hour.
- ---------------------------------------------------------------------
- Which is rendered as:
- [verse, William Blake, from Auguries of Innocence]
- To see a world in a grain of sand,
- And a heaven in a wild flower,
- Hold infinity in the palm of your hand,
- And eternity in an hour.
- The 'quote' style flows the text at left and right margins, for
- example:
- ---------------------------------------------------------------------
- [quote, Bertrand Russell, The World of Mathematics (1956)]
- A good notation has subtlety and suggestiveness which at times makes
- it almost seem like a live teacher.
- ---------------------------------------------------------------------
- Which is rendered as:
- [quote, Bertrand Russell, The World of Mathematics (1956)]
- A good notation has subtlety and suggestiveness which at times makes
- it almost seem like a live teacher.
- [[X28]]
- Admonition Paragraphs
- ~~~~~~~~~~~~~~~~~~~~~
- 'TIP', 'NOTE', 'IMPORTANT', 'WARNING' and 'CAUTION' admonishment
- paragraph styles are generated by placing `NOTE:`, `TIP:`,
- `IMPORTANT:`, `WARNING:` or `CAUTION:` as the first word of the
- paragraph. For example:
- NOTE: This is an example note.
- Alternatively, you can specify the paragraph admonition style
- explicitly using an <<X79,AttributeList element>>. For example:
- [NOTE]
- This is an example note.
- Renders:
- NOTE: This is an example note.
- TIP: If your admonition requires more than a single paragraph use an
- <<X22,admonition block>> instead.
- [[X47]]
- Admonition Icons and Captions
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- NOTE: Admonition customization with `icons`, `iconsdir`, `icon` and
- `caption` attributes does not apply when generating DocBook output. If
- you are going the DocBook route then the <<X43,a2x(1)>> `--no-icons`
- and `--icons-dir` options can be used to set the appropriate XSL
- Stylesheets parameters.
- By default the asciidoc(1) HTML backends generate text captions
- instead of admonition icon image links. To generate links to icon
- images define the <<X45,`icons`>> attribute, for example using the `-a
- icons` command-line option.
- The <<X44,`iconsdir`>> attribute sets the location of linked icon
- images.
- You can override the default icon image using the `icon` attribute to
- specify the path of the linked image. For example:
- [icon="./images/icons/wink.png"]
- NOTE: What lovely war.
- Use the `caption` attribute to customize the admonition captions (not
- applicable to `docbook` backend). The following example suppresses the
- icon image and customizes the caption of a 'NOTE' admonition
- (undefining the `icons` attribute with `icons=None` is only necessary
- if <<X45,admonition icons>> have been enabled):
- [icons=None, caption="My Special Note"]
- NOTE: This is my special note.
- This subsection also applies to <<X22,Admonition Blocks>>.
- [[X104]]
- Delimited Blocks
- ----------------
- Delimited blocks are blocks of text enveloped by leading and trailing
- delimiter lines (normally a series of four or more repeated
- characters). The behavior of Delimited Blocks is specified by entries
- in configuration file `[blockdef-*]` sections.
- Predefined Delimited Blocks
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
- AsciiDoc ships with a number of predefined DelimitedBlocks (see the
- `asciidoc.conf` configuration file in the asciidoc(1) program
- directory):
- Predefined delimited block underlines:
- CommentBlock: //////////////////////////
- PassthroughBlock: ++++++++++++++++++++++++++
- ListingBlock: --------------------------
- LiteralBlock: ..........................
- SidebarBlock: **************************
- QuoteBlock: __________________________
- ExampleBlock: ==========================
- OpenBlock: --
- .Default DelimitedBlock substitutions
- [cols="2e,7*^",frame="topbot",options="header,autowidth"]
- |=====================================================
- | |Attributes |Callouts |Macros | Quotes |Replacements
- |Special chars |Special words
- |PassthroughBlock |Yes |No |Yes |No |No |No |No
- |ListingBlock |No |Yes |No |No |No |Yes |No
- |LiteralBlock |No |Yes |No |No |No |Yes |No
- |SidebarBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
- |QuoteBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
- |ExampleBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
- |OpenBlock |Yes |No |Yes |Yes |Yes |Yes |Yes
- |=====================================================
- Listing Blocks
- ~~~~~~~~~~~~~~
- 'ListingBlocks' are rendered verbatim in a monospaced font, they
- retain line and whitespace formatting and are often distinguished by a
- background or border. There is no text formatting or substitutions
- within Listing blocks apart from Special Characters and Callouts.
- Listing blocks are often used for computer output and file listings.
- Here's an example:
- [listing]
- ......................................
- --------------------------------------
- #include <stdio.h>
- int main() {
- printf("Hello World!\n");
- exit(0);
- }
- --------------------------------------
- ......................................
- Which will be rendered like:
- --------------------------------------
- #include <stdio.h>
- int main() {
- printf("Hello World!\n");
- exit(0);
- }
- --------------------------------------
- By convention <<X59,filter blocks>> use the listing block syntax and
- are implemented as distinct listing block styles.
- [[X65]]
- Literal Blocks
- ~~~~~~~~~~~~~~
- 'LiteralBlocks' are rendered just like <<X85,literal paragraphs>>.
- Example:
- ---------------------------------------------------------------------
- ...................................
- Consul *necessitatibus* per id,
- consetetur, eu pro everti postulant
- homero verear ea mea, qui.
- ...................................
- ---------------------------------------------------------------------
- Renders:
- ...................................
- Consul *necessitatibus* per id,
- consetetur, eu pro everti postulant
- homero verear ea mea, qui.
- ...................................
- If the 'listing' style is applied to a LiteralBlock it will be
- rendered as a ListingBlock (this is handy if you have a listing
- containing a ListingBlock).
- Sidebar Blocks
- ~~~~~~~~~~~~~~
- A sidebar is a short piece of text presented outside the narrative
- flow of the main text. The sidebar is normally presented inside a
- bordered box to set it apart from the main text.
- The sidebar body is treated like a normal section body.
- Here's an example:
- ---------------------------------------------------------------------
- .An Example Sidebar
- ************************************************
- Any AsciiDoc SectionBody element (apart from
- SidebarBlocks) can be placed inside a sidebar.
- ************************************************
- ---------------------------------------------------------------------
- Which will be rendered like:
- .An Example Sidebar
- ************************************************
- Any AsciiDoc SectionBody element (apart from
- SidebarBlocks) can be placed inside a sidebar.
- ************************************************
- [[X26]]
- Comment Blocks
- ~~~~~~~~~~~~~~
- The contents of 'CommentBlocks' are not processed; they are useful for
- annotations and for excluding new or outdated content that you don't
- want displayed. CommentBlocks are never written to output files.
- Example:
- ---------------------------------------------------------------------
- //////////////////////////////////////////
- CommentBlock contents are not processed by
- asciidoc(1).
- //////////////////////////////////////////
- ---------------------------------------------------------------------
- See also <<X25,Comment Lines>>.
- NOTE: System macros are executed inside comment blocks.
- [[X76]]
- Passthrough Blocks
- ~~~~~~~~~~~~~~~~~~
- By default the block contents is subject only to 'attributes' and
- 'macros' substitutions (use an explicit 'subs' attribute to apply
- different substitutions). PassthroughBlock content will often be
- backend specific. Here's an example:
- ---------------------------------------------------------------------
- [subs="quotes"]
- ++++++++++++++++++++++++++++++++++++++
- <table border="1"><tr>
- <td>*Cell 1*</td>
- <td>*Cell 2*</td>
- </tr></table>
- ++++++++++++++++++++++++++++++++++++++
- ---------------------------------------------------------------------
- The following styles can be applied to passthrough blocks:
- pass::
- No substitutions are performed. This is equivalent to `subs="none"`.
- asciimath, latexmath::
- By default no substitutions are performed, the contents are rendered
- as <<X78,mathematical formulas>>.
- Quote Blocks
- ~~~~~~~~~~~~
- 'QuoteBlocks' are used for quoted passages of text. There are two
- styles: 'quote' and 'verse'. The style behavior is identical to
- <<X94,quote and verse paragraphs>> except that blocks can contain
- multiple paragraphs and, in the case of the 'quote' style, other
- section elements. The first positional attribute sets the style, if
- no attributes are specified the 'quote' style is used. The optional
- 'attribution' and 'citetitle' attributes (positional attributes 2 and
- 3) specify the quote's author and source. For example:
- ---------------------------------------------------------------------
- [quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
- ____________________________________________________________________
- As he spoke there was the sharp sound of horses' hoofs and
- grating wheels against the curb, followed by a sharp pull at the
- bell. Holmes whistled.
- "A pair, by the sound," said he. "Yes," he continued, glancing
- out of the window. "A nice little brougham and a pair of
- beauties. A hundred and fifty guineas apiece. There's money in
- this case, Watson, if there is nothing else."
- ____________________________________________________________________
- ---------------------------------------------------------------------
- Which is rendered as:
- [quote, Sir Arthur Conan Doyle, The Adventures of Sherlock Holmes]
- ____________________________________________________________________
- As he spoke there was the sharp sound of horses' hoofs and
- grating wheels against the curb, followed by a sharp pull at the
- bell. Holmes whistled.
- "A pair, by the sound," said he. "Yes," he continued, glancing
- out of the window. "A nice little brougham and a pair of
- beauties. A hundred and fifty guineas apiece. There's money in
- this case, Watson, if there is nothing else."
- ____________________________________________________________________
- [[X48]]
- Example Blocks
- ~~~~~~~~~~~~~~
- 'ExampleBlocks' encapsulate the DocBook Example element and are used
- for, well, examples. Example blocks can be titled by preceding them
- with a 'BlockTitle'. DocBook toolchains will normally automatically
- number examples and generate a 'List of Examples' backmatter section.
- Example blocks are delimited by lines of equals characters and can
- contain any block elements apart from Titles, BlockTitles and
- Sidebars) inside an example block. For example:
- ---------------------------------------------------------------------
- .An example
- =====================================================================
- Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens.
- =====================================================================
- ---------------------------------------------------------------------
- Renders:
- .An example
- =====================================================================
- Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens.
- =====================================================================
- A title prefix that can be inserted with the `caption` attribute
- (HTML backends). For example:
- ---------------------------------------------------------------------
- [caption="Example 1: "]
- .An example with a custom caption
- =====================================================================
- Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens.
- =====================================================================
- ---------------------------------------------------------------------
- [[X22]]
- Admonition Blocks
- ~~~~~~~~~~~~~~~~~
- The 'ExampleBlock' definition includes a set of admonition
- <<X23,styles>> ('NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION') for
- generating admonition blocks (admonitions containing more than a
- <<X28,single paragraph>>). Just precede the 'ExampleBlock' with an
- attribute list specifying the admonition style name. For example:
- ---------------------------------------------------------------------
- [NOTE]
- .A NOTE admonition block
- =====================================================================
- Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens.
- . Fusce euismod commodo velit.
- . Vivamus fringilla mi eu lacus.
- .. Fusce euismod commodo velit.
- .. Vivamus fringilla mi eu lacus.
- . Donec eget arcu bibendum
- nunc consequat lobortis.
- =====================================================================
- ---------------------------------------------------------------------
- Renders:
- [NOTE]
- .A NOTE admonition block
- =====================================================================
- Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens.
- . Fusce euismod commodo velit.
- . Vivamus fringilla mi eu lacus.
- .. Fusce euismod commodo velit.
- .. Vivamus fringilla mi eu lacus.
- . Donec eget arcu bibendum
- nunc consequat lobortis.
- =====================================================================
- See also <<X47,Admonition Icons and Captions>>.
- [[X29]]
- Open Blocks
- ~~~~~~~~~~~
- Open blocks are special:
- - The open block delimiter is line containing two hyphen characters
- (instead of four or more repeated characters).
- - They can be used to group block elements for <<X15,List item
- continuation>>.
- - Open blocks can be styled to behave like any other type of delimited
- block. The following built-in styles can be applied to open
- blocks: 'literal', 'verse', 'quote', 'listing', 'TIP', 'NOTE',
- 'IMPORTANT', 'WARNING', 'CAUTION', 'abstract', 'partintro',
- 'comment', 'example', 'sidebar', 'source', 'music', 'latex',
- 'graphviz'. For example, the following open block and listing block
- are functionally identical:
- [listing]
- --
- Lorum ipsum ...
- --
- ---------------
- Lorum ipsum ...
- ---------------
- - An unstyled open block groups section elements but otherwise does
- nothing.
- Open blocks are used to generate document abstracts and book part
- introductions:
- - Apply the 'abstract' style to generate an abstract, for example:
- [abstract]
- --
- In this paper we will ...
- --
- . Apply the 'partintro' style to generate a book part introduction for
- a multi-part book, for example:
- [partintro]
- .Optional part introduction title
- --
- Optional part introduction goes here.
- --
- [[X64]]
- Lists
- -----
- .List types
- - Bulleted lists. Also known as itemized or unordered lists.
- - Numbered lists. Also called ordered lists.
- - Labeled lists. Sometimes called variable or definition lists.
- - Callout lists (a list of callout annotations).
- .List behavior
- - List item indentation is optional and does not determine nesting,
- indentation does however make the source more readable.
- - Another list or a literal paragraph immediately following a list
- item will be implicitly included in the list item; use <<X15, list
- item continuation>> to explicitly append other block elements to a
- list item.
- - A comment block or a comment line block macro element will terminate
- a list -- use inline comment lines to put comments inside lists.
- - The `listindex` <<X60,intrinsic attribute>> is the current list item
- index (1..). If this attribute is used outside a list then it's value
- is the number of items in the most recently closed list. Useful for
- displaying the number of items in a list.
- Bulleted Lists
- ~~~~~~~~~~~~~~
- Bulleted list items start with a single dash or one to five asterisks
- followed by some white space then some text. Bulleted list syntaxes
- are:
- ...................
- - List item.
- * List item.
- ** List item.
- *** List item.
- **** List item.
- ***** List item.
- ...................
- Numbered Lists
- ~~~~~~~~~~~~~~
- List item numbers are explicit or implicit.
- .Explicit numbering
- List items begin with a number followed by some white space then the
- item text. The numbers can be decimal (arabic), roman (upper or lower
- case) or alpha (upper or lower case). Decimal and alpha numbers are
- terminated with a period, roman numbers are terminated with a closing
- parenthesis. The different terminators are necessary to ensure 'i',
- 'v' and 'x' roman numbers are are distinguishable from 'x', 'v' and
- 'x' alpha numbers. Examples:
- .....................................................................
- 1. Arabic (decimal) numbered list item.
- a. Lower case alpha (letter) numbered list item.
- F. Upper case alpha (letter) numbered list item.
- iii) Lower case roman numbered list item.
- IX) Upper case roman numbered list item.
- .....................................................................
- .Implicit numbering
- List items begin one to five period characters, followed by some white
- space then the item text. Examples:
- .....................................................................
- . Arabic (decimal) numbered list item.
- .. Lower case alpha (letter) numbered list item.
- ... Lower case roman numbered list item.
- .... Upper case alpha (letter) numbered list item.
- ..... Upper case roman numbered list item.
- .....................................................................
- You can use the 'style' attribute (also the first positional
- attribute) to specify an alternative numbering style. The numbered
- list style can be one of the following values: 'arabic', 'loweralpha',
- 'upperalpha', 'lowerroman', 'upperroman'.
- Here are some examples of bulleted and numbered lists:
- ---------------------------------------------------------------------
- - Praesent eget purus quis magna eleifend eleifend.
- 1. Fusce euismod commodo velit.
- a. Fusce euismod commodo velit.
- b. Vivamus fringilla mi eu lacus.
- c. Donec eget arcu bibendum nunc consequat lobortis.
- 2. Vivamus fringilla mi eu lacus.
- i) Fusce euismod commodo velit.
- ii) Vivamus fringilla mi eu lacus.
- 3. Donec eget arcu bibendum nunc consequat lobortis.
- 4. Nam fermentum mattis ante.
- - Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
- * Fusce euismod commodo velit.
- ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens. Sit munere ponderum dignissim et. Minim luptatum et
- vel.
- ** Vivamus fringilla mi eu lacus.
- * Donec eget arcu bibendum nunc consequat lobortis.
- - Nulla porttitor vulputate libero.
- . Fusce euismod commodo velit.
- . Vivamus fringilla mi eu lacus.
- [upperroman]
- .. Fusce euismod commodo velit.
- .. Vivamus fringilla mi eu lacus.
- . Donec eget arcu bibendum nunc consequat lobortis.
- ---------------------------------------------------------------------
- Which render as:
- - Praesent eget purus quis magna eleifend eleifend.
- 1. Fusce euismod commodo velit.
- a. Fusce euismod commodo velit.
- b. Vivamus fringilla mi eu lacus.
- c. Donec eget arcu bibendum nunc consequat lobortis.
- 2. Vivamus fringilla mi eu lacus.
- i) Fusce euismod commodo velit.
- ii) Vivamus fringilla mi eu lacus.
- 3. Donec eget arcu bibendum nunc consequat lobortis.
- 4. Nam fermentum mattis ante.
- - Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
- * Fusce euismod commodo velit.
- ** Qui in magna commodo, est labitur dolorum an. Est ne magna primis
- adolescens. Sit munere ponderum dignissim et. Minim luptatum et
- vel.
- ** Vivamus fringilla mi eu lacus.
- * Donec eget arcu bibendum nunc consequat lobortis.
- - Nulla porttitor vulputate libero.
- . Fusce euismod commodo velit.
- . Vivamus fringilla mi eu lacus.
- [upperroman]
- .. Fusce euismod commodo velit.
- .. Vivamus fringilla mi eu lacus.
- . Donec eget arcu bibendum nunc consequat lobortis.
- A predefined 'compact' option is available to bulleted and numbered
- lists -- this translates to the DocBook 'spacing="compact"' lists
- attribute which may or may not be processed by the DocBook toolchain.
- Example:
- [options="compact"]
- - Compact list item.
- - Another compact list item.
- TIP: To apply the 'compact' option globally define a document-wide
- 'compact-option' attribute, e.g. using the `-a compact-option`
- command-line option.
- You can set the list start number using the 'start' attribute (works
- for HTML outputs and DocBook outputs processed by DocBook XSL
- Stylesheets). Example:
- [start=7]
- . List item 7.
- . List item 8.
- Labeled Lists
- ~~~~~~~~~~~~~
- Labeled list items consist of one or more text labels followed by the
- text of the list item.
- An item label begins a line with an alphanumeric character hard
- against the left margin and ends with two, three or four colons or two
- semi-colons. A list item can have multiple labels, one per line.
- The list item text consists of one or more lines of text starting
- after the last label (either on the same line or a new line) and can
- be followed by nested List or ListParagraph elements. Item text can be
- optionally indented.
- Here are some examples:
- ---------------------------------------------------------------------
- In::
- Lorem::
- Fusce euismod commodo velit.
- Fusce euismod commodo velit.
- Ipsum:: Vivamus fringilla mi eu lacus.
- * Vivamus fringilla mi eu lacus.
- * Donec eget arcu bibendum nunc consequat lobortis.
- Dolor::
- Donec eget arcu bibendum nunc consequat lobortis.
- Suspendisse;;
- A massa id sem aliquam auctor.
- Morbi;;
- Pretium nulla vel lorem.
- In;;
- Dictum mauris in urna.
- Vivamus::: Fringilla mi eu lacus.
- Donec::: Eget arcu bibendum nunc consequat lobortis.
- ---------------------------------------------------------------------
- Which render as:
- In::
- Lorem::
- Fusce euismod commodo velit.
- Fusce euismod commodo velit.
- Ipsum:: Vivamus fringilla mi eu lacus.
- * Vivamus fringilla mi eu lacus.
- * Donec eget arcu bibendum nunc consequat lobortis.
- Dolor::
- Donec eget arcu bibendum nunc consequat lobortis.
- Suspendisse;;
- A massa id sem aliquam auctor.
- Morbi;;
- Pretium nulla vel lorem.
- In;;
- Dictum mauris in urna.
- Vivamus::: Fringilla mi eu lacus.
- Donec::: Eget arcu bibendum nunc consequat lobortis.
- Horizontal labeled list style
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- The 'horizontal' labeled list style (also the first positional
- attribute) places the list text side-by-side with the label instead of
- under the label. Here is an example:
- ---------------------------------------------------------------------
- [horizontal]
- *Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
- labitur dolorum an. Est ne magna primis adolescens.
- Fusce euismod commodo velit.
- *Ipsum*:: Vivamus fringilla mi eu lacus.
- - Vivamus fringilla mi eu lacus.
- - Donec eget arcu bibendum nunc consequat lobortis.
- *Dolor*::
- - Vivamus fringilla mi eu lacus.
- - Donec eget arcu bibendum nunc consequat lobortis.
- ---------------------------------------------------------------------
- Which render as:
- [horizontal]
- *Lorem*:: Fusce euismod commodo velit. Qui in magna commodo, est
- labitur dolorum an. Est ne magna primis adolescens.
- Fusce euismod commodo velit.
- *Ipsum*:: Vivamus fringilla mi eu lacus.
- - Vivamus fringilla mi eu lacus.
- - Donec eget arcu bibendum nunc consequat lobortis.
- *Dolor*::
- - Vivamus fringilla mi eu lacus.
- - Donec eget arcu bibendum nunc consequat lobortis.
- [NOTE]
- =====================================================================
- - Current PDF toolchains do not make a good job of determining
- the relative column widths for horizontal labeled lists.
- - Nested horizontal labeled lists will generate DocBook validation
- errors because the 'DocBook XML V4.2' DTD does not permit nested
- informal tables (although <<X13,DocBook XSL Stylesheets>> and
- <<X31,dblatex>> process them correctly).
- - The label width can be set as a percentage of the total width by
- setting the 'width' attribute e.g. `width="10%"`
- =====================================================================
- Question and Answer Lists
- ~~~~~~~~~~~~~~~~~~~~~~~~~
- AsciiDoc comes pre-configured with a 'qanda' style labeled list for generating
- DocBook question and answer (Q&A) lists. Example:
- ---------------------------------------------------------------------
- [qanda]
- Question one::
- Answer one.
- Question two::
- Answer two.
- ---------------------------------------------------------------------
- Renders:
- [qanda]
- Question one::
- Answer one.
- Question two::
- Answer two.
- Glossary Lists
- ~~~~~~~~~~~~~~
- AsciiDoc comes pre-configured with a 'glossary' style labeled list for
- generating DocBook glossary lists. Example:
- ---------------------------------------------------------------------
- [glossary]
- A glossary term::
- The corresponding definition.
- A second glossary term::
- The corresponding definition.
- ---------------------------------------------------------------------
- For working examples see the `article.txt` and `book.txt` documents in
- the AsciiDoc `./doc` distribution directory.
- NOTE: To generate valid DocBook output glossary lists must be located
- in a section that uses the 'glossary' <<X93,section markup template>>.
- Bibliography Lists
- ~~~~~~~~~~~~~~~~~~
- AsciiDoc comes with a predefined 'bibliography' bulleted list style
- generating DocBook bibliography entries. Example:
- ---------------------------------------------------------------------
- [bibliography]
- .Optional list title
- - [[[taoup]]] Eric Steven Raymond. 'The Art of UNIX
- Programming'. Addison-Wesley. ISBN 0-13-142901-9.
- - [[[walsh-muellner]]] Norman Walsh & Leonard Muellner.
- 'DocBook - The Definitive Guide'. O'Reilly & Associates.
- 1999. ISBN 1-56592-580-7.
- ---------------------------------------------------------------------
- The `[[[<reference>]]]` syntax is a bibliography entry anchor, it
- generates an anchor named `<reference>` and additionally displays
- `[<reference>]` at the anchor position. For example `[[[taoup]]]`
- generates an anchor named `taoup` that displays `[taoup]` at the
- anchor position. Cite the reference from elsewhere your document using
- `<<taoup>>`, this displays a hyperlink (`[taoup]`) to the
- corresponding bibliography entry anchor.
- For working examples see the `article.txt` and `book.txt` documents in
- the AsciiDoc `./doc` distribution directory.
- NOTE: To generate valid DocBook output bibliography lists must be
- located in a <<X93,bibliography section>>.
- [[X15]]
- List Item Continuation
- ~~~~~~~~~~~~~~~~~~~~~~
- Another list or a literal paragraph immediately following a list item
- is implicitly appended to the list item; to append other block
- elements to a list item you need to explicitly join them to the list
- item with a 'list continuation' (a separator line containing a single
- plus character). Multiple block elements can be appended to a list
- item using list continuations (provided they are legal list item
- children in the backend markup).
- Here are some examples of list item continuations: list item one
- contains multiple continuations; list item two is continued with an
- <<X29,OpenBlock>> containing multiple elements:
- ---------------------------------------------------------------------
- 1. List item one.
- +
- List item one continued with a second paragraph followed by an
- Indented block.
- +
- .................
- $ ls *.sh
- $ mv *.sh ~/tmp
- .................
- +
- List item continued with a third paragraph.
- 2. List item two continued with an open block.
- +
- --
- This paragraph is part of the preceding list item.
- a. This list is nested and does not require explicit item continuation.
- +
- This paragraph is part of the preceding list item.
- b. List item b.
- This paragraph belongs to item two of the outer list.
- --
- ---------------------------------------------------------------------
- Renders:
- 1. List item one.
- +
- List item one continued with a second paragraph followed by an
- Indented block.
- +
- .................
- $ ls *.sh
- $ mv *.sh ~/tmp
- .................
- +
- List item continued with a third paragraph.
- 2. List item two continued with an open block.
- +
- --
- This paragraph is part of the preceding list item.
- a. This list is nested and does not require explicit item continuation.
- +
- This paragraph is part of the preceding list item.
- b. List item b.
- This paragraph belongs to item two of the outer list.
- --
- [[X92]]
- Footnotes
- ---------
- The shipped AsciiDoc configuration includes three footnote inline
- macros:
- `footnote:[<text>]`::
- Generates a footnote with text `<text>`.
- `footnoteref:[<id>,<text>]`::
- Generates a footnote with a reference ID `<id>` and text `<text>`.
- `footnoteref:[<id>]`::
- Generates a reference to the footnote with ID `<id>`.
- The footnote text can span multiple lines.
- The 'xhtml11' and 'html5' backends render footnotes dynamically using
- JavaScript; 'html4' outputs do not use JavaScript and leave the
- footnotes inline; 'docbook' footnotes are processed by the downstream
- DocBook toolchain.
- Example footnotes:
- A footnote footnote:[An example footnote.];
- a second footnote with a reference ID footnoteref:[note2,Second footnote.];
- finally a reference to the second footnote footnoteref:[note2].
- Renders:
- A footnote footnote:[An example footnote.];
- a second footnote with a reference ID footnoteref:[note2,Second footnote.];
- finally a reference to the second footnote footnoteref:[note2].
- Indexes
- -------
- The shipped AsciiDoc configuration includes the inline macros for
- generating DocBook index entries.
- `indexterm:[<primary>,<secondary>,<tertiary>]`::
- `(((<primary>,<secondary>,<tertiary>)))`::
- This inline macro generates an index term (the `<secondary>` and
- `<tertiary>` positional attributes are optional). Example:
- `indexterm:[Tigers,Big cats]` (or, using the alternative syntax
- `(((Tigers,Big cats)))`. Index terms that have secondary and
- tertiary entries also generate separate index terms for the
- secondary and tertiary entries. The index terms appear in the
- index, not the primary text flow.
- `indexterm2:[<primary>]`::
- `((<primary>))`::
- This inline macro generates an index term that appears in both the
- index and the primary text flow. The `<primary>` should not be
- padded to the left or right with white space characters.
- For working examples see the `article.txt` and `book.txt` documents in
- the AsciiDoc `./doc` distribution directory.
- NOTE: Index entries only really make sense if you are generating
- DocBook markup -- DocBook conversion programs automatically generate
- an index at the point an 'Index' section appears in source document.
- [[X105]]
- Callouts
- --------
- Callouts are a mechanism for annotating verbatim text (for example:
- source code, computer output and user input). Callout markers are
- placed inside the annotated text while the actual annotations are
- presented in a callout list after the annotated text. Here's an
- example:
- ---------------------------------------------------------------------
- .MS-DOS directory listing
- -----------------------------------------------------
- 10/17/97 9:04 <DIR> bin
- 10/16/97 14:11 <DIR> DOS \<1>
- 10/16/97 14:40 <DIR> Program Files
- 10/16/97 14:46 <DIR> TEMP
- 10/17/97 9:04 <DIR> tmp
- 10/16/97 14:37 <DIR> WINNT
- 10/16/97 14:25 119 AUTOEXEC.BAT \<2>
- 2/13/94 6:21 54,619 COMMAND.COM \<2>
- 10/16/97 14:25 115 CONFIG.SYS \<2>
- 11/16/97 17:17 61,865,984 pagefile.sys
- 2/13/94 6:21 9,349 WINA20.386 \<3>
- -----------------------------------------------------
- \<1> This directory holds MS-DOS.
- \<2> System startup code for DOS.
- \<3> Some sort of Windows 3.1 hack.
- ---------------------------------------------------------------------
- Which renders:
- .MS-DOS directory listing
- -----------------------------------------------------
- 10/17/97 9:04 <DIR> bin
- 10/16/97 14:11 <DIR> DOS <1>
- 10/16/97 14:40 <DIR> Program Files
- 10/16/97 14:46 <DIR> TEMP
- 10/17/97 9:04 <DIR> tmp
- 10/16/97 14:37 <DIR> WINNT
- 10/16/97 14:25 119 AUTOEXEC.BAT <2>
- 2/13/94 6:21 54,619 COMMAND.COM <2>
- 10/16/97 14:25 115 CONFIG.SYS <2>
- 11/16/97 17:17 61,865,984 pagefile.sys
- 2/13/94 6:21 9,349 WINA20.386 <3>
- -----------------------------------------------------
- <1> This directory holds MS-DOS.
- <2> System startup code for DOS.
- <3> Some sort of Windows 3.1 hack.
- .Explanation
- - The callout marks are whole numbers enclosed in angle brackets --
- they refer to the correspondingly numbered item in the following
- callout list.
- - By default callout marks are confined to 'LiteralParagraphs',
- 'LiteralBlocks' and 'ListingBlocks' (although this is a
- configuration file option and can be changed).
- - Callout list item numbering is fairly relaxed -- list items can
- start with `<n>`, `n>` or `>` where `n` is the optional list item
- number (in the latter case list items starting with a single `>`
- character are implicitly numbered starting at one).
- - Callout lists should not be nested.
- - Callout lists start list items hard against the left margin.
- - If you want to present a number inside angle brackets you'll need to
- escape it with a backslash to prevent it being interpreted as a
- callout mark.
- NOTE: Define the AsciiDoc 'icons' attribute (for example using the `-a
- icons` command-line option) to display callout icons.
- Implementation Notes
- ~~~~~~~~~~~~~~~~~~~~
- Callout marks are generated by the 'callout' inline macro while
- callout lists are generated using the 'callout' list definition. The
- 'callout' macro and 'callout' list are special in that they work
- together. The 'callout' inline macro is not enabled by the normal
- 'macros' substitutions option, instead it has its own 'callouts'
- substitution option.
- The following attributes are available during inline callout macro
- substitution:
- `{index}`::
- The callout list item index inside the angle brackets.
- `{coid}`::
- An identifier formatted like `CO<listnumber>-<index>` that
- uniquely identifies the callout mark. For example `CO2-4`
- identifies the fourth callout mark in the second set of callout
- marks.
- The `{coids}` attribute can be used during callout list item
- substitution -- it is a space delimited list of callout IDs that refer
- to the explanatory list item.
- Including callouts in included code
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- You can annotate working code examples with callouts -- just remember
- to put the callouts inside source code comments. This example displays
- the `test.py` source file (containing a single callout) using the
- 'source' (code highlighter) filter:
- .AsciiDoc source
- ---------------------------------------------------------------------
- [source,python]
- -------------------------------------------
- \include::test.py[]
- -------------------------------------------
- \<1> Print statement.
- ---------------------------------------------------------------------
- .Included `test.py` source
- ---------------------------------------------------------------------
- print 'Hello World!' # \<1>
- ---------------------------------------------------------------------
- Macros
- ------
- Macros are a mechanism for substituting parametrized text into output
- documents.
- Macros have a 'name', a single 'target' argument and an 'attribute
- list'. The usual syntax is `<name>:<target>[<attrlist>]` (for
- inline macros) and `<name>::<target>[<attrlist>]` (for block
- macros). Here are some examples:
- http://www.docbook.org/[DocBook.org]
- include::chapt1.txt[tabsize=2]
- mailto:srackham@gmail.com[]
- .Macro behavior
- - `<name>` is the macro name. It can only contain letters, digits or
- dash characters and cannot start with a dash.
- - The optional `<target>` cannot contain white space characters.
- - `<attrlist>` is a <<X21,list of attributes>> enclosed in square
- brackets.
- - `]` characters inside attribute lists must be escaped with a
- backslash.
- - Expansion of macro references can normally be escaped by prefixing a
- backslash character (see the AsciiDoc 'FAQ' for examples of
- exceptions to this rule).
- - Attribute references in block macros are expanded.
- - The substitutions performed prior to Inline macro macro expansion
- are determined by the inline context.
- - Macros are processed in the order they appear in the configuration
- file(s).
- - Calls to inline macros can be nested inside different inline macros
- (an inline macro call cannot contain a nested call to itself).
- - In addition to `<name>`, `<target>` and `<attrlist>` the
- `<passtext>` and `<subslist>` named groups are available to
- <<X77,passthrough macros>>. A macro is a passthrough macro if the
- definition includes a `<passtext>` named group.
- Inline Macros
- ~~~~~~~~~~~~~
- Inline Macros occur in an inline element context. Predefined Inline
- macros include 'URLs', 'image' and 'link' macros.
- URLs
- ^^^^
- 'http', 'https', 'ftp', 'file', 'mailto' and 'callto' URLs are
- rendered using predefined inline macros.
- - If you don't need a custom link caption you can enter the 'http',
- 'https', 'ftp', 'file' URLs and email addresses without any special
- macro syntax.
- - If the `<attrlist>` is empty the URL is displayed.
- Here are some examples:
- http://www.docbook.org/[DocBook.org]
- http://www.docbook.org/
- mailto:joe.bloggs@foobar.com[email Joe Bloggs]
- joe.bloggs@foobar.com
- Which are rendered:
- http://www.docbook.org/[DocBook.org]
- http://www.docbook.org/
- mailto:joe.bloggs@foobar.com[email Joe Bloggs]
- joe.bloggs@foobar.com
- If the `<target>` necessitates space characters use `%20`, for example
- `large%20image.png`.
- Internal Cross References
- ^^^^^^^^^^^^^^^^^^^^^^^^^
- Two AsciiDoc inline macros are provided for creating hypertext links
- within an AsciiDoc document. You can use either the standard macro
- syntax or the (preferred) alternative.
- [[X30]]
- anchor
- ++++++
- Used to specify hypertext link targets:
- [[<id>,<xreflabel>]]
- anchor:<id>[<xreflabel>]
- The `<id>` is a unique string that conforms to the output markup's
- anchor syntax. The optional `<xreflabel>` is the text to be displayed
- by captionless 'xref' macros that refer to this anchor. The optional
- `<xreflabel>` is only really useful when generating DocBook output.
- Example anchor:
- [[X1]]
- You may have noticed that the syntax of this inline element is the
- same as that of the <<X41,BlockId block element>>, this is no
- coincidence since they are functionally equivalent.
- xref
- ++++
- Creates a hypertext link to a document anchor.
- <<<id>,<caption>>>
- xref:<id>[<caption>]
- The `<id>` refers to an anchor ID. The optional `<caption>` is the
- link's displayed text. Example:
- <<X21,attribute lists>>
- If `<caption>` is not specified then the displayed text is
- auto-generated:
- - The AsciiDoc 'xhtml11' and 'html5' backends display the `<id>`
- enclosed in square brackets.
- - If DocBook is produced the DocBook toolchain is responsible for the
- displayed text which will normally be the referenced figure, table
- or section title number followed by the element's title text.
- Here is an example:
- ---------------------------------------------------------------------
- [[tiger_image]]
- .Tyger tyger
- image::tiger.png[]
- This can be seen in <<tiger_image>>.
- ---------------------------------------------------------------------
- Linking to Local Documents
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
- Hypertext links to files on the local file system are specified using
- the 'link' inline macro.
- link:<target>[<caption>]
- The 'link' macro generates relative URLs. The link macro `<target>` is
- the target file name (relative to the file system location of the
- referring document). The optional `<caption>` is the link's displayed
- text. If `<caption>` is not specified then `<target>` is displayed.
- Example:
- link:downloads/foo.zip[download foo.zip]
- You can use the `<filename>#<id>` syntax to refer to an anchor within
- a target document but this usually only makes sense when targeting
- HTML documents.
- [[X9]]
- Images
- ^^^^^^
- Inline images are inserted into the output document using the 'image'
- macro. The inline syntax is:
- image:<target>[<attributes>]
- The contents of the image file `<target>` is displayed. To display the
- image its file format must be supported by the target backend
- application. HTML and DocBook applications normally support PNG or JPG
- files.
- `<target>` file name paths are relative to the location of the
- referring document.
- [[X55]]
- .Image macro attributes
- - The optional 'alt' attribute is also the first positional attribute,
- it specifies alternative text which is displayed if the output
- application is unable to display the image file (see also
- http://htmlhelp.com/feature/art3.htm[Use of ALT texts in IMGs]). For
- example:
- image:images/logo.png[Company Logo]
- - The optional 'title' attribute provides a title for the image. The
- <<X49,block image macro>> renders the title alongside the image.
- The inline image macro displays the title as a popup ``tooltip'' in
- visual browsers (AsciiDoc HTML outputs only).
- - The optional `width` and `height` attributes scale the image size
- and can be used in any combination. The units are pixels. The
- following example scales the previous example to a height of 32
- pixels:
- image:images/logo.png["Company Logo",height=32]
- - The optional `link` attribute is used to link the image to an
- external document. The following example links a screenshot
- thumbnail to a full size version:
- image:screen-thumbnail.png[height=32,link="screen.png"]
- - The optional `scaledwidth` attribute is only used in DocBook block
- images (specifically for PDF documents). The following example
- scales the images to 75% of the available print width:
- image::images/logo.png[scaledwidth="75%",alt="Company Logo"]
- - The image `scale` attribute sets the DocBook `imagedata` element
- `scale` attribute.
- - The optional `align` attribute is used for horizontal image
- alignment. Allowed values are `center`, `left` and `right`. For
- example:
- image::images/tiger.png["Tiger image",align="left"]
- - The optional `float` attribute floats the image `left` or `right` on
- the page (works with HTML outputs only, has no effect on DocBook
- outputs). `float` and `align` attributes are mutually exclusive.
- Use the `unfloat::[]` block macro to stop floating.
- Comment Lines
- ^^^^^^^^^^^^^
- See <<X25,comment block macro>>.
- Block Macros
- ~~~~~~~~~~~~
- A Block macro reference must be contained in a single line separated
- either side by a blank line or a block delimiter.
- Block macros behave just like Inline macros, with the following
- differences:
- - They occur in a block context.
- - The default syntax is `<name>::<target>[<attrlist>]` (two
- colons, not one).
- - Markup template section names end in `-blockmacro` instead of
- `-inlinemacro`.
- Block Identifier
- ^^^^^^^^^^^^^^^^
- The Block Identifier macro sets the `id` attribute and has the same
- syntax as the <<X30,anchor inline macro>> since it performs
- essentially the same function -- block templates use the `id`
- attribute as a block element ID. For example:
- [[X30]]
- This is equivalent to the `[id="X30"]` <<X79,AttributeList element>>).
- [[X49]]
- Images
- ^^^^^^
- The 'image' block macro is used to display images in a block context.
- The syntax is:
- image::<target>[<attributes>]
- The block `image` macro has the same <<X55,macro attributes>> as it's
- <<X9,inline image macro>> counterpart.
- Block images can be titled by preceding the 'image' macro with a
- 'BlockTitle'. DocBook toolchains normally number titled block images
- and optionally list them in an automatically generated 'List of
- Figures' backmatter section.
- This example:
- .Main circuit board
- image::images/layout.png[J14P main circuit board]
- is equivalent to:
- image::images/layout.png["J14P main circuit board",
- title="Main circuit board"]
- A title prefix that can be inserted with the `caption` attribute
- (HTML backends). For example:
- .Main circuit board
- [caption="Figure 2: "]
- image::images/layout.png[J14P main circuit board]
- [[X66]]
- .Embedding images in XHTML documents
- *********************************************************************
- If you define the `data-uri` attribute then images will be embedded in
- XHTML outputs using the
- http://en.wikipedia.org/wiki/Data:_URI_scheme[data URI scheme]. You
- can use the 'data-uri' attribute with the 'xhtml11' and 'html5'
- backends to produce single-file XHTML documents with embedded images
- and CSS, for example:
- $ asciidoc -a data-uri mydocument.txt
- [NOTE]
- ======
- - All current popular browsers support data URIs, although versions
- of Internet Explorer prior to version 8 do not.
- - Some browsers limit the size of data URIs.
- ======
- *********************************************************************
- [[X25]]
- Comment Lines
- ^^^^^^^^^^^^^
- Single lines starting with two forward slashes hard up against the
- left margin are treated as comments. Comment lines do not appear in
- the output unless the 'showcomments' attribute is defined. Comment
- lines have been implemented as both block and inline macros so a
- comment line can appear as a stand-alone block or within block elements
- that support inline macro expansion. Example comment line:
- // This is a comment.
- If the 'showcomments' attribute is defined comment lines are written
- to the output:
- - In DocBook the comment lines are enclosed by the 'remark' element
- (which may or may not be rendered by your toolchain).
- - The 'showcomments' attribute does not expose <<X26,Comment Blocks>>.
- Comment Blocks are never passed to the output.
- System Macros
- ~~~~~~~~~~~~~
- System macros are block macros that perform a predefined task and are
- hardwired into the asciidoc(1) program.
- - You can escape system macros with a leading backslash character
- (as you can with other macros).
- - The syntax and tasks performed by system macros is built into
- asciidoc(1) so they don't appear in configuration files. You can
- however customize the syntax by adding entries to a configuration
- file `[macros]` section.
- [[X63]]
- Include Macros
- ^^^^^^^^^^^^^^
- The `include` and `include1` system macros to include the contents of
- a named file into the source document.
- The `include` macro includes a file as if it were part of the parent
- document -- tabs are expanded and system macros processed. The
- contents of `include1` files are not subject to tab expansion or
- system macro processing nor are attribute or lower priority
- substitutions performed. The `include1` macro's intended use is to
- include verbatim embedded CSS or scripts into configuration file
- headers. Example:
- ------------------------------------
- \include::chapter1.txt[tabsize=4]
- ------------------------------------
- .Include macro behavior
- - If the included file name is specified with a relative path then the
- path is relative to the location of the referring document.
- - Include macros can appear inside configuration files.
- - Files included from within 'DelimitedBlocks' are read to completion
- to avoid false end-of-block underline termination.
- - Attribute references are expanded inside the include 'target'; if an
- attribute is undefined then the included file is silently skipped.
- - The 'tabsize' macro attribute sets the number of space characters to
- be used for tab expansion in the included file (not applicable to
- `include1` macro).
- - The 'depth' macro attribute sets the maximum permitted number of
- subsequent nested includes (not applicable to `include1` macro which
- does not process nested includes). Setting 'depth' to '1' disables
- nesting inside the included file. By default, nesting is limited to
- a depth of ten.
- - If the he 'warnings' attribute is set to 'False' (or any other
- Python literal that evaluates to boolean false) then no warning
- message is printed if the included file does not exist. By default
- 'warnings' are enabled.
- - Internally the `include1` macro is translated to the `include1`
- system attribute which means it must be evaluated in a region where
- attribute substitution is enabled. To inhibit nested substitution in
- included files it is preferable to use the `include` macro and set
- the attribute `depth=1`.
- Conditional Inclusion Macros
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Lines of text in the source document can be selectively included or
- excluded from processing based on the existence (or not) of a document
- attribute.
- Document text between the `ifdef` and `endif` macros is included if a
- document attribute is defined:
- ifdef::<attribute>[]
- :
- endif::<attribute>[]
- Document text between the `ifndef` and `endif` macros is not included
- if a document attribute is defined:
- ifndef::<attribute>[]
- :
- endif::<attribute>[]
- `<attribute>` is an attribute name which is optional in the trailing
- `endif` macro.
- If you only want to process a single line of text then the text can be
- put inside the square brackets and the `endif` macro omitted, for
- example:
- ifdef::revnumber[Version number 42]
- Is equivalent to:
- ifdef::revnumber[]
- Version number 42
- endif::revnumber[]
- 'ifdef' and 'ifndef' macros also accept multiple attribute names:
- - Multiple ',' separated attribute names evaluate to defined if one
- or more of the attributes is defined, otherwise it's value is
- undefined.
- - Multiple '+' separated attribute names evaluate to defined if all
- of the attributes is defined, otherwise it's value is undefined.
- Document text between the `ifeval` and `endif` macros is included if
- the Python expression inside the square brackets is true. Example:
- ifeval::[{rs458}==2]
- :
- endif::[]
- - Document attribute references are expanded before the expression is
- evaluated.
- - If an attribute reference is undefined then the expression is
- considered false.
- Take a look at the `*.conf` configuration files in the AsciiDoc
- distribution for examples of conditional inclusion macro usage.
- Executable system macros
- ^^^^^^^^^^^^^^^^^^^^^^^^
- The 'eval', 'sys' and 'sys2' block macros exhibit the same behavior as
- their same named <<X24, system attribute references>>. The difference
- is that system macros occur in a block macro context whereas system
- attributes are confined to inline contexts where attribute
- substitution is enabled.
- The following example displays a long directory listing inside a
- literal block:
- ------------------
- sys::[ls -l *.txt]
- ------------------
- NOTE: There are no block macro versions of the 'eval3' and 'sys3'
- system attributes.
- Template System Macro
- ^^^^^^^^^^^^^^^^^^^^^
- The `template` block macro allows the inclusion of one configuration
- file template section within another. The following example includes
- the `[admonitionblock]` section in the `[admonitionparagraph]`
- section:
- [admonitionparagraph]
- template::[admonitionblock]
- .Template macro behavior
- - The `template::[]` macro is useful for factoring configuration file
- markup.
- - `template::[]` macros cannot be nested.
- - `template::[]` macro expansion is applied after all configuration
- files have been read.
- [[X77]]
- Passthrough macros
- ~~~~~~~~~~~~~~~~~~
- Passthrough macros are analogous to <<X76,passthrough blocks>> and are
- used to pass text directly to the output. The substitution performed
- on the text is determined by the macro definition but can be overridden
- by the `<subslist>`. The usual syntax is
- `<name>:<subslist>[<passtext>]` (for inline macros) and
- `<name>::<subslist>[<passtext>]` (for block macros). Passthroughs, by
- definition, take precedence over all other text substitutions.
- pass::
- Inline and block. Passes text unmodified (apart from explicitly
- specified substitutions). Examples:
- pass:[<q>To be or not to be</q>]
- pass:attributes,quotes[<u>the '{author}'</u>]
- asciimath, latexmath::
- Inline and block. Passes text unmodified. Used for
- <<X78,mathematical formulas>>.
- \+++::
- Inline and block. The triple-plus passthrough is functionally
- identical to the 'pass' macro but you don't have to escape `]`
- characters and you can prefix with quoted attributes in the inline
- version. Example:
- Red [red]+++`sum_(i=1)\^n i=(n(n+1))/2`$+++ AsciiMathML formula
- $$::
- Inline and block. The double-dollar passthrough is functionally
- identical to the triple-plus passthrough with one exception: special
- characters are escaped. Example:
- $$`[[a,b],[c,d]]((n),(k))`$$
- [[X80]]`::
- Text quoted with single backtick characters constitutes an 'inline
- literal' passthrough. The enclosed text is rendered in a monospaced
- font and is only subject to special character substitution. This
- makes sense since monospace text is usually intended to be rendered
- literally and often contains characters that would otherwise have to
- be escaped. If you need monospaced text containing inline
- substitutions use a <<X81,plus character instead of a backtick>>.
- Macro Definitions
- ~~~~~~~~~~~~~~~~~
- Each entry in the configuration `[macros]` section is a macro
- definition which can take one of the following forms:
- `<pattern>=<name>[<subslist]`:: Inline macro definition.
- `<pattern>=#<name>[<subslist]`:: Block macro definition.
- `<pattern>=+<name>[<subslist]`:: System macro definition.
- `<pattern>`:: Delete the existing macro with this `<pattern>`.
- `<pattern>` is a Python regular expression and `<name>` is the name of
- a markup template. If `<name>` is omitted then it is the value of the
- regular expression match group named 'name'. The optional
- `[<subslist]` is a comma-separated list of substitution names enclosed
- in `[]` brackets, it sets the default substitutions for passthrough
- text, if omitted then no passthrough substitutions are performed.
- .Pattern named groups
- The following named groups can be used in macro `<pattern>` regular
- expressions and are available as markup template attributes:
- name::
- The macro name.
- target::
- The macro target.
- attrlist::
- The macro attribute list.
- passtext::
- Contents of this group are passed unmodified to the output subject
- only to 'subslist' substitutions.
- subslist::
- Processed as a comma-separated list of substitution names for
- 'passtext' substitution, overrides the the macro definition
- 'subslist'.
- .Here's what happens during macro substitution
- - Each contextually relevant macro 'pattern' from the `[macros]`
- section is matched against the input source line.
- - If a match is found the text to be substituted is loaded from a
- configuration markup template section named like
- `<name>-inlinemacro` or `<name>-blockmacro` (depending on the macro
- type).
- - Global and macro attribute list attributes are substituted in the
- macro's markup template.
- - The substituted template replaces the macro reference in the output
- document.
- [[X98]]
- HTML 5 audio and video block macros
- -----------------------------------
- The 'html5' backend 'audio' and 'video' block macros generate the HTML
- 5 'audio' and 'video' elements respectively. They follow the usual
- AsciiDoc block macro syntax `<name>::<target>[<attrlist>]` where:
- [horizontal]
- `<name>`:: 'audio' or 'video'.
- `<target>`:: The URL or file name of the video or audio file.
- `<attrlist>`:: A list of named attributes (see below).
- .Audio macro attributes
- [options="header",cols="1,5",frame="topbot"]
- |====================================================================
- |Name | Value
- |options
- |A comma separated list of one or more of the following items:
- 'autoplay', 'loop' which correspond to the same-named HTML 5 'audio'
- element boolean attributes. By default the player 'controls' are
- enabled, include the 'nocontrols' option value to hide them.
- |====================================================================
- .Video macro attributes
- [options="header",cols="1,5",frame="topbot"]
- |====================================================================
- |Name | Value
- |height | The height of the player in pixels.
- |width | The width of the player in pixels.
- |poster | The URL or file name of an image representing the video.
- |options
- |A comma separated list of one or more of the following items:
- 'autoplay', 'loop' and 'nocontrols'. The 'autoplay' and 'loop' options
- correspond to the same-named HTML 5 'video' element boolean
- attributes. By default the player 'controls' are enabled, include the
- 'nocontrols' option value to hide them.
- |====================================================================
- Examples:
- ---------------------------------------------------------------------
- audio::images/example.ogg[]
- video::gizmo.ogv[width=200,options="nocontrols,autoplay"]
- .Example video
- video::gizmo.ogv[]
- video::http://www.808.dk/pics/video/gizmo.ogv[]
- ---------------------------------------------------------------------
- If your needs are more complex put raw HTML 5 in a markup block, for
- example (from http://www.808.dk/?code-html-5-video):
- ---------------------------------------------------------------------
- ++++
- <video poster="pics/video/gizmo.jpg" id="video" style="cursor: pointer;" >
- <source src="pics/video/gizmo.mp4" />
- <source src="pics/video/gizmo.webm" type="video/webm" />
- <source src="pics/video/gizmo.ogv" type="video/ogg" />
- Video not playing? <a href="pics/video/gizmo.mp4">Download file</a> instead.
- </video>
- <script type="text/javascript">
- var video = document.getElementById('video');
- video.addEventListener('click',function(){
- video.play();
- },false);
- </script>
- ++++
- ---------------------------------------------------------------------
- Tables
- ------
- The AsciiDoc table syntax looks and behaves like other delimited block
- types and supports standard <<X73,block configuration entries>>.
- Formatting is easy to read and, just as importantly, easy to enter.
- - Cells and columns can be formatted using built-in customizable styles.
- - Horizontal and vertical cell alignment can be set on columns and
- cell.
- - Horizontal and vertical cell spanning is supported.
- .Use tables sparingly
- *********************************************************************
- When technical users first start creating documents, tables (complete
- with column spanning and table nesting) are often considered very
- important. The reality is that tables are seldom used, even in
- technical documentation.
- Try this exercise: thumb through your library of technical books,
- you'll be surprised just how seldom tables are actually used, even
- less seldom are tables containing block elements (such as paragraphs
- or lists) or spanned cells. This is no accident, like figures, tables
- are outside the normal document flow -- tables are for consulting not
- for reading.
- Tables are designed for, and should normally only be used for,
- displaying column oriented tabular data.
- *********************************************************************
- Example tables
- ~~~~~~~~~~~~~~
- .Simple table
- [width="15%"]
- |=======
- |1 |2 |A
- |3 |4 |B
- |5 |6 |C
- |=======
- .AsciiDoc source
- ---------------------------------------------------------------------
- [width="15%"]
- |=======
- |1 |2 |A
- |3 |4 |B
- |5 |6 |C
- |=======
- ---------------------------------------------------------------------
- .Columns formatted with strong, monospaced and emphasis styles
- [width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
- |==========================
- | 2+|Columns 2 and 3
- |1 |Item 1 |Item 1
- |2 |Item 2 |Item 2
- |3 |Item 3 |Item 3
- |4 |Item 4 |Item 4
- |footer 1|footer 2|footer 3
- |==========================
- .AsciiDoc source
- ---------------------------------------------------------------------
- .An example table
- [width="50%",cols=">s,^m,e",frame="topbot",options="header,footer"]
- |==========================
- | 2+|Columns 2 and 3
- |1 |Item 1 |Item 1
- |2 |Item 2 |Item 2
- |3 |Item 3 |Item 3
- |4 |Item 4 |Item 4
- |footer 1|footer 2|footer 3
- |==========================
- ---------------------------------------------------------------------
- .Horizontal and vertical source data
- [width="80%",cols="3,^2,^2,10",options="header"]
- |=========================================================
- |Date |Duration |Avg HR |Notes
- |22-Aug-08 |10:24 | 157 |
- Worked out MSHR (max sustainable heart rate) by going hard
- for this interval.
- |22-Aug-08 |23:03 | 152 |
- Back-to-back with previous interval.
- |24-Aug-08 |40:00 | 145 |
- Moderately hard interspersed with 3x 3min intervals (2min
- hard + 1min really hard taking the HR up to 160).
- |=========================================================
- Short cells can be entered horizontally, longer cells vertically. The
- default behavior is to strip leading and trailing blank lines within a
- cell. These characteristics aid readability and data entry.
- .AsciiDoc source
- ---------------------------------------------------------------------
- .Windtrainer workouts
- [width="80%",cols="3,^2,^2,10",options="header"]
- |=========================================================
- |Date |Duration |Avg HR |Notes
- |22-Aug-08 |10:24 | 157 |
- Worked out MSHR (max sustainable heart rate) by going hard
- for this interval.
- |22-Aug-08 |23:03 | 152 |
- Back-to-back with previous interval.
- |24-Aug-08 |40:00 | 145 |
- Moderately hard interspersed with 3x 3min intervals (2min
- hard + 1min really hard taking the HR up to 160).
- |=========================================================
- ---------------------------------------------------------------------
- .A table with externally sourced CSV data
- [format="csv",cols="^1,4*2",options="header"]
- |===================================================
- ID,Customer Name,Contact Name,Customer Address,Phone
- include::customers.csv[]
- |===================================================
- .AsciiDoc source
- ---------------------------------------------------------------------
- [format="csv",cols="^1,4*2",options="header"]
- |===================================================
- ID,Customer Name,Contact Name,Customer Address,Phone
- \include::customers.csv[]
- |===================================================
- ---------------------------------------------------------------------
- .Cell spans, alignments and styles
- [cols="e,m,^,>s",width="25%"]
- |============================
- |1 >s|2 |3 |4
- ^|5 2.2+^.^|6 .3+<.>m|7
- ^|8
- |9 2+>|10
- |============================
- .AsciiDoc source
- ---------------------------------------------------------------------
- [cols="e,m,^,>s",width="25%"]
- |============================
- |1 >s|2 |3 |4
- ^|5 2.2+^.^|6 .3+<.>m|7
- ^|8
- |9 2+>|10
- |============================
- ---------------------------------------------------------------------
- [[X68]]
- Table input data formats
- ~~~~~~~~~~~~~~~~~~~~~~~~
- AsciiDoc table data can be 'psv', 'dsv' or 'csv' formatted. The
- default table format is 'psv'.
- AsciiDoc 'psv' ('Prefix Separated Values') and 'dsv' ('Delimiter
- Separated Values') formats are cell oriented -- the table is treated
- as a sequence of cells -- there are no explicit row separators.
- - 'psv' prefixes each cell with a separator whereas 'dsv' delimits
- cells with a separator.
- - 'psv' and 'dsv' separators are Python regular expressions.
- - The default 'psv' separator contains <<X84, cell specifier>> related
- named regular expression groups.
- - The default 'dsv' separator is `:|\n` (a colon or a new line
- character).
- - 'psv' and 'dsv' cell separators can be escaped by preceding them
- with a backslash character.
- Here are four 'psv' cells (the second item spans two columns; the
- last contains an escaped separator):
- |One 2+|Two and three |A \| separator character
- 'csv' is the quasi-standard row oriented 'Comma Separated Values
- (CSV)' format commonly used to import and export spreadsheet and
- database data.
- [[X69]]
- Table attributes
- ~~~~~~~~~~~~~~~~
- Tables can be customized by the following attributes:
- format::
- 'psv' (default), 'dsv' or 'csv' (See <<X68, Table Data Formats>>).
- separator::
- The cell separator. A Python regular expression ('psv' and 'dsv'
- formats) or a single character ('csv' format).
- frame::
- Defines the table border and can take the following values: 'topbot'
- (top and bottom), 'all' (all sides), 'none' and 'sides' (left and
- right sides). The default value is 'all'.
- grid::
- Defines which ruler lines are drawn between table rows and columns.
- The 'grid' attribute value can be any of the following values: 'none',
- 'cols', 'rows' and 'all'. The default value is 'all'.
- align::
- Use the 'align' attribute to horizontally align the table on the
- page (works with HTML outputs only, has no effect on DocBook outputs).
- The following values are valid: 'left', 'right', and 'center'.
- float::
- Use the 'float' attribute to float the table 'left' or 'right' on the
- page (works with HTML outputs only, has no effect on DocBook outputs).
- Floating only makes sense in conjunction with a table 'width'
- attribute value of less than 100% (otherwise the table will take up
- all the available space). 'float' and 'align' attributes are mutually
- exclusive. Use the `unfloat::[]` block macro to stop floating.
- halign::
- Use the 'halign' attribute to horizontally align all cells in a table.
- The following values are valid: 'left', 'right', and 'center'
- (defaults to 'left'). Overridden by <<X70,Column specifiers>> and
- <<X84,Cell specifiers>>.
- valign::
- Use the 'valign' attribute to vertically align all cells in a table.
- The following values are valid: 'top', 'bottom', and 'middle'
- (defaults to 'top'). Overridden by <<X70,Column specifiers>> and
- <<X84,Cell specifiers>>.
- options::
- The 'options' attribute can contain comma separated values, for
- example: 'header', 'footer'. By default header and footer rows are
- omitted. See <<X74,attribute options>> for a complete list of
- available table options.
- cols::
- The 'cols' attribute is a comma separated list of <<X70,column
- specifiers>>. For example `cols="2<p,2*,4p,>"`.
- - If 'cols' is present it must specify all columns.
- - If the 'cols' attribute is not specified the number of columns is
- calculated as the number of data items in the *first line* of the
- table.
- - The degenerate form for the 'cols' attribute is an integer
- specifying the number of columns e.g. `cols=4`.
- width::
- The 'width' attribute is expressed as a percentage value
- ('"1%"'...'"99%"'). The width specifies the table width relative to
- the available width. HTML backends use this value to set the table
- width attribute. It's a bit more complicated with DocBook, see the
- <<X89,DocBook table widths>> sidebar.
- filter::
- The 'filter' attribute defines an external shell command that is
- invoked for each cell. The built-in 'asciidoc' table style is
- implemented using a filter.
- [[X89]]
- .DocBook table widths
- **********************************************************************
- The AsciiDoc docbook backend generates CALS tables. CALS tables do not
- support a table width attribute -- table width can only be controlled
- by specifying absolute column widths.
- Specifying absolute column widths is not media independent because
- different presentation media have different physical dimensions. To
- get round this limitation both
- http://www.sagehill.net/docbookxsl/Tables.html#TableWidth[DocBook XSL
- Stylesheets] and
- http://dblatex.sourceforge.net/doc/manual/ch03s05.html#sec-table-width[dblatex]
- have implemented table width processing instructions for setting the
- table width as a percentage of the available width. AsciiDoc emits
- these processing instructions if the 'width' attribute is set along
- with proportional column widths (the AsciiDoc docbook backend
- 'pageunits' attribute defaults to '*').
- To generate DocBook tables with absolute column widths set the
- 'pageunits' attribute to a CALS absolute unit such as 'pt' and set the
- 'pagewidth' attribute to match the width of the presentation media.
- **********************************************************************
- [[X70]]
- Column Specifiers
- ~~~~~~~~~~~~~~~~~
- Column specifiers define how columns are rendered and appear in the
- table <<X69,cols attribute>>. A column specifier consists of an
- optional column multiplier followed by optional alignment, width and
- style values and is formatted like:
- [<multiplier>*][<align>][<width>][<style>]
- - All components are optional. The multiplier must be first and the
- style last. The order of `<align>` or `<width>` is not important.
- - Column `<width>` can be either an integer proportional value (1...)
- or a percentage (1%...100%). The default value is 1. To ensure
- portability across different backends, there is no provision for
- absolute column widths (not to be confused with output column width
- <<X72,markup attributes>> which are available in both percentage and
- absolute units).
- - The '<align>' column alignment specifier is formatted like:
- [<horizontal>][.<vertical>]
- +
- Where `<horizontal>` and `<vertical>` are one of the following
- characters: `<`, `^` or `>` which represent 'left', 'center' and
- 'right' horizontal alignment or 'top', 'middle' and 'bottom' vertical
- alignment respectively.
- - A `<multiplier>` can be used to specify repeated columns e.g.
- `cols="4*<"` specifies four left-justified columns. The default
- multiplier value is 1.
- - The `<style>` name specifies a <<X71,table style>> to used to markup
- column cells (you can use the full style names if you wish but the
- first letter is normally sufficient).
- - Column specific styles are not applied to header rows.
- [[X84]]
- Cell Specifiers
- ~~~~~~~~~~~~~~~
- Cell specifiers allow individual cells in 'psv' formatted tables to be
- spanned, multiplied, aligned and styled. Cell specifiers prefix 'psv'
- `|` delimiters and are formatted like:
- [<span>*|+][<align>][<style>]
- - '<span>' specifies horizontal and vertical cell spans ('+' operator) or
- the number of times the cell is replicated ('*' operator). '<span>'
- is formatted like:
- [<colspan>][.<rowspan>]
- +
- Where `<colspan>` and `<rowspan>` are integers specifying the number of
- columns and rows to span.
- - `<align>` specifies horizontal and vertical cell alignment an is the
- same as in <<X70,column specifiers>>.
- - A `<style>` value is the first letter of <<X71,table style>> name.
- For example, the following 'psv' formatted cell will span two columns
- and the text will be centered and emphasized:
- `2+^e| Cell text`
- [[X71]]
- Table styles
- ~~~~~~~~~~~~
- Table styles can be applied to the entire table (by setting the
- 'style' attribute in the table's attribute list) or on a per column
- basis (by specifying the style in the table's <<X69,cols attribute>>).
- Table data can be formatted using the following predefined styles:
- default::
- The default style: AsciiDoc inline text formatting; blank lines are
- treated as paragraph breaks.
- emphasis::
- Like default but all text is emphasised.
- monospaced::
- Like default but all text is in a monospaced font.
- strong::
- Like default but all text is bold.
- header::
- Apply the same style as the table header. Normally used to create a
- vertical header in the first column.
- asciidoc::
- With this style table cells can contain any of the AsciiDoc elements
- that are allowed inside document sections. This style runs asciidoc(1)
- as a filter to process cell contents. See also <<X83,Docbook table
- limitations>>.
- literal::
- No text formatting; monospaced font; all line breaks are retained
- (the same as the AsciiDoc <<X65,LiteralBlock>> element).
- verse::
- All line breaks are retained (just like the AsciiDoc <<X94,verse
- paragraph style>>).
- [[X72]]
- Markup attributes
- ~~~~~~~~~~~~~~~~~
- AsciiDoc makes a number of attributes available to table markup
- templates and tags. Column specific attributes are available when
- substituting the 'colspec' cell data tags.
- pageunits::
- DocBook backend only. Specifies table column absolute width units.
- Defaults to '*'.
- pagewidth::
- DocBook backend only. The nominal output page width in 'pageunit'
- units. Used to calculate CALS tables absolute column and table
- widths. Defaults to '425'.
- tableabswidth::
- Integer value calculated from 'width' and 'pagewidth' attributes.
- In 'pageunit' units.
- tablepcwidth::
- Table width expressed as a percentage of the available width. Integer
- value (0..100).
- colabswidth::
- Integer value calculated from 'cols' column width, 'width' and
- 'pagewidth' attributes. In 'pageunit' units.
- colpcwidth::
- Column width expressed as a percentage of the table width. Integer
- value (0..100).
- colcount::
- Total number of table columns.
- rowcount::
- Total number of table rows.
- halign::
- Horizontal cell content alignment: 'left', 'right' or 'center'.
- valign::
- Vertical cell content alignment: 'top', 'bottom' or 'middle'.
- colnumber, colstart::
- The number of the leftmost column occupied by the cell (1...).
- colend::
- The number of the rightmost column occupied by the cell (1...).
- colspan::
- Number of columns the cell should span.
- rowspan::
- Number of rows the cell should span (1...).
- morerows::
- Number of additional rows the cell should span (0...).
- Nested tables
- ~~~~~~~~~~~~~
- An alternative 'psv' separator character '!' can be used (instead of
- '|') in nested tables. This allows a single level of table nesting.
- Columns containing nested tables must use the 'asciidoc' style. An
- example can be found in `./examples/website/newtables.txt`.
- [[X83]]
- DocBook table limitations
- ~~~~~~~~~~~~~~~~~~~~~~~~~
- Fully implementing tables is not trivial, some DocBook toolchains do
- better than others. AsciiDoc HTML table outputs are rendered
- correctly in all the popular browsers -- if your DocBook generated
- tables don't look right compare them with the output generated by the
- AsciiDoc 'xhtml11' backend or try a different DocBook toolchain. Here
- is a list of things to be aware of:
- - Although nested tables are not legal in DocBook 4 the FOP and
- dblatex toolchains will process them correctly. If you use `a2x(1)`
- you will need to include the `--no-xmllint` option to suppress
- DocBook validation errors.
- +
- NOTE: In theory you can nest DocBook 4 tables one level using the
- 'entrytbl' element, but not all toolchains process 'entrytbl'.
- - DocBook only allows a subset of block elements inside table cells so
- not all AsciiDoc elements produce valid DocBook inside table cells.
- If you get validation errors running `a2x(1)` try the `--no-xmllint`
- option, toolchains will often process nested block elements such as
- sidebar blocks and floating titles correctly even though, strictly
- speaking, they are not legal.
- - Text formatting in cells using the 'monospaced' table style will
- raise validation errors because the DocBook 'literal' element was
- not designed to support formatted text (using the 'literal' element
- is a kludge on the part of AsciiDoc as there is no easy way to set
- the font style in DocBook.
- - Cell alignments are ignored for 'verse', 'literal' or 'asciidoc'
- table styles.
- [[X1]]
- Manpage Documents
- -----------------
- Sooner or later, if you program in a UNIX environment, you're going
- to have to write a man page.
- By observing a couple of additional conventions (detailed below) you
- can write AsciiDoc files that will generate HTML and PDF man pages
- plus the native manpage roff format. The easiest way to generate roff
- manpages from AsciiDoc source is to use the a2x(1) command. The
- following example generates a roff formatted manpage file called
- `asciidoc.1` (a2x(1) uses asciidoc(1) to convert `asciidoc.1.txt` to
- DocBook which it then converts to roff using DocBook XSL Stylesheets):
- a2x --doctype manpage --format manpage asciidoc.1.txt
- .Viewing and printing manpage files
- **********************************************************************
- Use the `man(1)` command to view the manpage file:
- $ man -l asciidoc.1
- To print a high quality man page to a postscript printer:
- $ man -l -Tps asciidoc.1 | lpr
- You could also create a PDF version of the man page by converting
- PostScript to PDF using `ps2pdf(1)`:
- $ man -l -Tps asciidoc.1 | ps2pdf - asciidoc.1.pdf
- The `ps2pdf(1)` command is included in the Ghostscript distribution.
- **********************************************************************
- To find out more about man pages view the `man(7)` manpage
- (`man 7 man` and `man man-pages` commands).
- Document Header
- ~~~~~~~~~~~~~~~
- A manpage document Header is mandatory. The title line contains the
- man page name followed immediately by the manual section number in
- brackets, for example 'ASCIIDOC(1)'. The title name should not contain
- white space and the manual section number is a single digit optionally
- followed by a single character.
- The NAME Section
- ~~~~~~~~~~~~~~~~
- The first manpage section is mandatory, must be titled 'NAME' and must
- contain a single paragraph (usually a single line) consisting of a
- list of one or more comma separated command name(s) separated from the
- command purpose by a dash character. The dash must have at least one
- white space character on either side. For example:
- printf, fprintf, sprintf - print formatted output
- The SYNOPSIS Section
- ~~~~~~~~~~~~~~~~~~~~
- The second manpage section is mandatory and must be titled 'SYNOPSIS'.
- refmiscinfo attributes
- ~~~~~~~~~~~~~~~~~~~~~~
- In addition to the automatically created man page <<X60,intrinsic
- attributes>> you can assign DocBook
- http://www.docbook.org/tdg5/en/html/refmiscinfo.html[refmiscinfo]
- element 'source', 'version' and 'manual' values using AsciiDoc
- `{mansource}`, `{manversion}` and `{manmanual}` attributes
- respectively. This example is from the AsciiDoc header of a man page
- source file:
- :man source: AsciiDoc
- :man version: {revnumber}
- :man manual: AsciiDoc Manual
- [[X78]]
- Mathematical Formulas
- ---------------------
- The 'asciimath' and 'latexmath' <<X77,passthrough macros>> along with
- 'asciimath' and 'latexmath' <<X76,passthrough blocks>> provide a
- (backend dependent) mechanism for rendering mathematical formulas. You
- can use the following math markups:
- NOTE: The 'latexmath' macro used to include 'LaTeX Math' in DocBook
- outputs is not the same as the 'latexmath' macro used to include
- 'LaTeX MathML' in XHTML outputs. 'LaTeX Math' applies to DocBook
- outputs that are processed by <<X31,dblatex>> and is normally used to
- generate PDF files. 'LaTeXMathML' is very much a subset of 'LaTeX
- Math' and applies to XHTML documents.
- LaTeX Math
- ~~~~~~~~~~
- ftp://ftp.ams.org/pub/tex/doc/amsmath/short-math-guide.pdf[LaTeX
- math] can be included in documents that are processed by
- <<X31,dblatex(1)>>. Example inline formula:
- latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$]
- For more examples see the {website}[AsciiDoc website] or the
- distributed `doc/latexmath.txt` file.
- ASCIIMathML
- ~~~~~~~~~~~
- /////////////////////////////////////////////////////////////////////
- The older ASCIIMathML 1.47 version is used instead of version 2
- because:
- 1. Version 2 doesn't work when embedded.
- 2. Version 2 is much larger.
- /////////////////////////////////////////////////////////////////////
- http://www1.chapman.edu/~jipsen/mathml/asciimath.html[ASCIIMathML]
- formulas can be included in XHTML documents generated using the
- 'xhtml11' and 'html5' backends. To enable ASCIIMathML support you must
- define the 'asciimath' attribute, for example using the `-a asciimath`
- command-line option. Example inline formula:
- asciimath:[`x/x={(1,if x!=0),(text{undefined},if x=0):}`]
- For more examples see the {website}[AsciiDoc website] or the
- distributed `doc/asciimathml.txt` file.
- LaTeXMathML
- ~~~~~~~~~~~
- /////////////////////////////////////////////////////////////////////
- There is an http://math.etsu.edu/LaTeXMathML/[extended LaTeXMathML
- version] by Jeff Knisley, in addition to a JavaScript file it requires
- the inclusion of a CSS file.
- /////////////////////////////////////////////////////////////////////
- 'LaTeXMathML' allows LaTeX Math style formulas to be included in XHTML
- documents generated using the AsciiDoc 'xhtml11' and 'html5' backends.
- AsciiDoc uses the
- http://www.maths.nottingham.ac.uk/personal/drw/lm.html[original
- LaTeXMathML] by Douglas Woodall. 'LaTeXMathML' is derived from
- ASCIIMathML and is for users who are more familiar with or prefer
- using LaTeX math formulas (it recognizes a subset of LaTeX Math, the
- differences are documented on the 'LaTeXMathML' web page). To enable
- LaTeXMathML support you must define the 'latexmath' attribute, for
- example using the `-a latexmath` command-line option. Example inline
- formula:
- latexmath:[$\sum_{n=1}^\infty \frac{1}{2^n}$]
- For more examples see the {website}[AsciiDoc website] or the
- distributed `doc/latexmathml.txt` file.
- MathML
- ~~~~~~
- http://www.w3.org/Math/[MathML] is a low level XML markup for
- mathematics. AsciiDoc has no macros for MathML but users familiar with
- this markup could use passthrough macros and passthrough blocks to
- include MathML in output documents.
- [[X7]]
- Configuration Files
- -------------------
- AsciiDoc source file syntax and output file markup is largely
- controlled by a set of cascading, text based, configuration files. At
- runtime The AsciiDoc default configuration files are combined with
- optional user and document specific configuration files.
- Configuration File Format
- ~~~~~~~~~~~~~~~~~~~~~~~~~
- Configuration files contain named sections. Each section begins with a
- section name in square brackets []. The section body consists of the
- lines of text between adjacent section headings.
- - Section names consist of one or more alphanumeric, underscore or
- dash characters and cannot begin or end with a dash.
- - Lines starting with a '#' character are treated as comments and
- ignored.
- - If the section name is prefixed with a '+' character then the
- section contents is appended to the contents of an already existing
- same-named section.
- - Otherwise same-named sections and section entries override
- previously loaded sections and section entries (this is sometimes
- referred to as 'cascading'). Consequently, downstream configuration
- files need only contain those sections and section entries that need
- to be overridden.
- TIP: When creating custom configuration files you only need to include
- the sections and entries that differ from the default configuration.
- TIP: The best way to learn about configuration files is to read the
- default configuration files in the AsciiDoc distribution in
- conjunction with asciidoc(1) output files. You can view configuration
- file load sequence by turning on the asciidoc(1) `-v` (`--verbose`)
- command-line option.
- AsciiDoc reserves the following section names for specific purposes:
- miscellaneous::
- Configuration options that don't belong anywhere else.
- attributes::
- Attribute name/value entries.
- specialcharacters::
- Special characters reserved by the backend markup.
- tags::
- Backend markup tags.
- quotes::
- Definitions for quoted inline character formatting.
- specialwords::
- Lists of words and phrases singled out for special markup.
- replacements, replacements2, replacements3::
- Find and replace substitution definitions.
- specialsections::
- Used to single out special section names for specific markup.
- macros::
- Macro syntax definitions.
- titles::
- Heading, section and block title definitions.
- paradef-*::
- Paragraph element definitions.
- blockdef-*::
- DelimitedBlock element definitions.
- listdef-*::
- List element definitions.
- listtags-*::
- List element tag definitions.
- tabledef-*::
- Table element definitions.
- tabletags-*::
- Table element tag definitions.
- Each line of text in these sections is a 'section entry'. Section
- entries share the following syntax:
- name=value::
- The entry value is set to value.
- name=::
- The entry value is set to a zero length string.
- name!::
- The entry is undefined (deleted from the configuration). This
- syntax only applies to 'attributes' and 'miscellaneous'
- sections.
- .Section entry behavior
- - All equals characters inside the `name` must be escaped with a
- backslash character.
- - `name` and `value` are stripped of leading and trailing white space.
- - Attribute names, tag entry names and markup template section names
- consist of one or more alphanumeric, underscore or dash characters.
- Names should not begin or end with a dash.
- - A blank configuration file section (one without any entries) deletes
- any preceding section with the same name (applies to non-markup
- template sections).
- Miscellaneous section
- ~~~~~~~~~~~~~~~~~~~~~
- The optional `[miscellaneous]` section specifies the following
- `name=value` options:
- newline::
- Output file line termination characters. Can include any
- valid Python string escape sequences. The default value is
- `\r\n` (carriage return, line feed). Should not be quoted or
- contain explicit spaces (use `\x20` instead). For example:
- $ asciidoc -a 'newline=\n' -b docbook mydoc.txt
- outfilesuffix::
- The default extension for the output file, for example
- `outfilesuffix=.html`. Defaults to backend name.
- tabsize::
- The number of spaces to expand tab characters, for example
- `tabsize=4`. Defaults to 8. A 'tabsize' of zero suppresses tab
- expansion (useful when piping included files through block
- filters). Included files can override this option using the
- 'tabsize' attribute.
- pagewidth, pageunits::
- These global table related options are documented in the
- <<X4,Table Configuration File Definitions>> sub-section.
- NOTE: `[miscellaneous]` configuration file entries can be set using
- the asciidoc(1) `-a` (`--attribute`) command-line option.
- Titles section
- ~~~~~~~~~~~~~~
- sectiontitle::
- Two line section title pattern. The entry value is a Python
- regular expression containing the named group 'title'.
- underlines::
- A comma separated list of document and section title underline
- character pairs starting with the section level 0 and ending
- with section level 4 underline. The default setting is:
- underlines="==","--","~~","^^","++"
- sect0...sect4::
- One line section title patterns. The entry value is a Python
- regular expression containing the named group 'title'.
- blocktitle::
- <<X42,BlockTitle element>> pattern. The entry value is a
- Python regular expression containing the named group 'title'.
- subs::
- A comma separated list of substitutions that are performed on
- the document header and section titles. Defaults to 'normal'
- substitution.
- Tags section
- ~~~~~~~~~~~~
- The `[tags]` section contains backend tag definitions (one per
- line). Tags are used to translate AsciiDoc elements to backend
- markup.
- An AsciiDoc tag definition is formatted like
- `<tagname>=<starttag>|<endtag>`. For example:
- emphasis=<em>|</em>
- In this example asciidoc(1) replaces the | character with the
- emphasized text from the AsciiDoc input file and writes the result to
- the output file.
- Use the `{brvbar}` attribute reference if you need to include a | pipe
- character inside tag text.
- Attributes section
- ~~~~~~~~~~~~~~~~~~
- The optional `[attributes]` section contains predefined attributes.
- If the attribute value requires leading or trailing spaces then the
- text text should be enclosed in quotation mark (") characters.
- To delete a attribute insert a `name!` entry in a downstream
- configuration file or use the asciidoc(1) `--attribute name!`
- command-line option (an attribute name suffixed with a `!` character
- deletes the attribute)
- Special Characters section
- ~~~~~~~~~~~~~~~~~~~~~~~~~~
- The `[specialcharacters]` section specifies how to escape characters
- reserved by the backend markup. Each translation is specified on a
- single line formatted like:
- <special_character>=<translated_characters>
- Special characters are normally confined to those that resolve
- markup ambiguity (in the case of HTML and XML markups the ampersand,
- less than and greater than characters). The following example causes
- all occurrences of the `<` character to be replaced by `<`.
- <=<
- Quoted Text section
- ~~~~~~~~~~~~~~~~~~~
- Quoting is used primarily for text formatting. The `[quotes]` section
- defines AsciiDoc quoting characters and their corresponding backend
- markup tags. Each section entry value is the name of a of a `[tags]`
- section entry. The entry name is the character (or characters) that
- quote the text. The following examples are taken from AsciiDoc
- configuration files:
- [quotes]
- _=emphasis
- [tags]
- emphasis=<em>|</em>
- You can specify the left and right quote strings separately by
- separating them with a | character, for example:
- ``|''=quoted
- Omitting the tag will disable quoting, for example, if you don't want
- superscripts or subscripts put the following in a custom configuration
- file or edit the global `asciidoc.conf` configuration file:
- [quotes]
- ^=
- ~=
- <<X52,Unconstrained quotes>> are differentiated from constrained
- quotes by prefixing the tag name with a hash character, for example:
- __=#emphasis
- .Quoted text behavior
- - Quote characters must be non-alphanumeric.
- - To minimize quoting ambiguity try not to use the same quote
- characters in different quote types.
- Special Words section
- ~~~~~~~~~~~~~~~~~~~~~
- The `[specialwords]` section is used to single out words and phrases
- that you want to consistently format in some way throughout your
- document without having to repeatedly specify the markup. The name of
- each entry corresponds to a markup template section and the entry
- value consists of a list of words and phrases to be marked up. For
- example:
- [specialwords]
- strongwords=NOTE IMPORTANT
- [strongwords]
- <strong>{words}</strong>
- The examples specifies that any occurrence of `NOTE` or `IMPORTANT`
- should appear in a bold font.
- Words and word phrases are treated as Python regular expressions: for
- example, the word `^NOTE` would only match `NOTE` if appeared at
- the start of a line.
- AsciiDoc comes with three built-in Special Word types:
- 'emphasizedwords', 'monospacedwords' and 'strongwords', each has a
- corresponding (backend specific) markup template section. Edit the
- configuration files to customize existing Special Words and to add new
- ones.
- .Special word behavior
- - Word list entries must be separated by space characters.
- - Word list entries with embedded spaces should be enclosed in quotation (")
- characters.
- - A `[specialwords]` section entry of the form
- +name=word1{nbsp}[word2...]+ adds words to existing `name` entries.
- - A `[specialwords]` section entry of the form `name` undefines
- (deletes) all existing `name` words.
- - Since word list entries are processed as Python regular expressions
- you need to be careful to escape regular expression special
- characters.
- - By default Special Words are substituted before Inline Macros, this
- may lead to undesirable consequences. For example the special word
- `foobar` would be expanded inside the macro call
- `http://www.foobar.com[]`. A possible solution is to emphasize
- whole words only by defining the word using regular expression
- characters, for example `\bfoobar\b`.
- - If the first matched character of a special word is a backslash then
- the remaining characters are output without markup i.e. the
- backslash can be used to escape special word markup. For example
- the special word `\\?\b[Tt]en\b` will mark up the words `Ten` and
- `ten` only if they are not preceded by a backslash.
- [[X10]]
- Replacements section
- ~~~~~~~~~~~~~~~~~~~~
- `[replacements]`, `[replacements2]` and `[replacements3]`
- configuration file entries specify find and replace text and are
- formatted like:
- <find_pattern>=<replacement_text>
- The find text can be a Python regular expression; the replace text can
- contain Python regular expression group references.
- Use Replacement shortcuts for often used macro references, for
- example (the second replacement allows us to backslash escape the
- macro name):
- NEW!=image:./images/smallnew.png[New!]
- \\NEW!=NEW!
- The only difference between the three replacement types is how they
- are applied. By default 'replacements' and 'replacement2' are applied
- in <<X102,normal>> substitution contexts whereas 'replacements3' needs
- to be configured explicitly and should only be used in backend
- configuration files.
- .Replacement behavior
- - The built-in replacements can be escaped with a backslash.
- - If the find or replace text has leading or trailing spaces then the
- text should be enclosed in quotation (") characters.
- - Since the find text is processed as a regular expression you need to
- be careful to escape regular expression special characters.
- - Replacements are performed in the same order they appear in the
- configuration file replacements section.
- Markup Template Sections
- ~~~~~~~~~~~~~~~~~~~~~~~~
- Markup template sections supply backend markup for translating
- AsciiDoc elements. Since the text is normally backend dependent
- you'll find these sections in the backend specific configuration
- files. Template sections differ from other sections in that they
- contain a single block of text instead of per line 'name=value'
- entries. A markup template section body can contain:
- - Attribute references
- - System macro calls.
- - A document content placeholder
- The document content placeholder is a single | character and is
- replaced by text from the source element. Use the `{brvbar}`
- attribute reference if you need a literal | character in the template.
- [[X27]]
- Configuration file names, precedence and locations
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Configuration files have a `.conf` file name extension; they are
- loaded from the following locations:
- 1. The directory containing the asciidoc executable.
- 2. If there is no `asciidoc.conf` file in the directory containing the
- asciidoc executable then load from the global configuration
- directory (normally `/etc/asciidoc` or `/usr/local/etc/asciidoc`)
- i.e. the global configuration files directory is skipped if
- AsciiDoc configuration files are installed in the same directory as
- the asciidoc executable. This allows both a system wide copy and
- multiple local copies of AsciiDoc to coexist on the same host PC.
- 3. The user's `$HOME/.asciidoc` directory (if it exists).
- 4. The directory containing the AsciiDoc source file.
- 5. Explicit configuration files specified using:
- - The `conf-files` attribute (one or more file names separated by a
- `|` character). These files are loaded in the order they are
- specified and prior to files specified using the `--conf-file`
- command-line option.
- - The asciidoc(1) `--conf-file`) command-line option. The
- `--conf-file` option can be specified multiple times, in which
- case configuration files will be processed in the same order they
- appear on the command-line.
- 6. <<X100,Backend plugin>> configuration files are loaded from
- subdirectories named like `backends/<backend>` in locations 1, 2
- and 3.
- 7. <<X59,Filter>> configuration files are loaded from subdirectories
- named like `filters/<filter>` in locations 1, 2 and 3.
- Configuration files from the above locations are loaded in the
- following order:
- - The `[attributes]` section only from:
- * `asciidoc.conf` in location 3
- * Files from location 5.
- +
- This first pass makes locally set attributes available in the global
- `asciidoc.conf` file.
- - `asciidoc.conf` from locations 1, 2, 3.
- - 'attributes', 'titles' and 'specialcharacters' sections from the
- `asciidoc.conf` in location 4.
- - The document header is parsed at this point and we can assume the
- 'backend' and 'doctype' have now been defined.
- - Backend plugin `<backend>.conf` and `<backend>-<doctype>.conf` files
- from locations 6. If a backend plugin is not found then try
- locations 1, 2 and 3 for `<backend>.conf` and
- `<backend>-<doctype>.conf` backend configuration files.
- - Filter conf files from locations 7.
- - `lang-<lang>.conf` from locations 1, 2, 3.
- - `asciidoc.conf` from location 4.
- - `<backend>.conf` and `<backend>-<doctype>.conf` from location 4.
- - Filter conf files from location 4.
- - `<docfile>.conf` and `<docfile>-<backend>.conf` from location 4.
- - Configuration files from location 5.
- Where:
- - `<backend>` and `<doctype>` are values specified by the asciidoc(1)
- `-b` (`--backend`) and `-d` (`--doctype`) command-line options.
- - `<infile>` is the path name of the AsciiDoc input file without the
- file name extension.
- - `<lang>` is a two letter country code set by the the AsciiDoc 'lang'
- attribute.
- [NOTE]
- =====================================================================
- The backend and language global configuration files are loaded *after*
- the header has been parsed. This means that you can set most
- attributes in the document header. Here's an example header:
- Life's Mysteries
- ================
- :author: Hu Nose
- :doctype: book
- :toc:
- :icons:
- :data-uri:
- :lang: en
- :encoding: iso-8859-1
- Attributes set in the document header take precedence over
- configuration file attributes.
- =====================================================================
- TIP: Use the asciidoc(1) `-v` (`--verbose`) command-line option to see
- which configuration files are loaded and the order in which they are
- loaded.
- Document Attributes
- -------------------
- A document attribute is comprised of a 'name' and a textual 'value'
- and is used for textual substitution in AsciiDoc documents and
- configuration files. An attribute reference (an attribute name
- enclosed in braces) is replaced by the corresponding attribute
- value. Attribute names are case insensitive and can only contain
- alphanumeric, dash and underscore characters.
- There are four sources of document attributes (from highest to lowest
- precedence):
- - Command-line attributes.
- - AttributeEntry, AttributeList, Macro and BlockId elements.
- - Configuration file `[attributes]` sections.
- - Intrinsic attributes.
- Within each of these divisions the last processed entry takes
- precedence.
- NOTE: If an attribute is not defined then the line containing the
- attribute reference is dropped. This property is used extensively in
- AsciiDoc configuration files to facilitate conditional markup
- generation.
- [[X18]]
- Attribute Entries
- -----------------
- The `AttributeEntry` block element allows document attributes to be
- assigned within an AsciiDoc document. Attribute entries are added to
- the global document attributes dictionary. The attribute name/value
- syntax is a single line like:
- :<name>: <value>
- For example:
- :Author Initials: JB
- This will set an attribute reference `{authorinitials}` to the value
- 'JB' in the current document.
- To delete (undefine) an attribute use the following syntax:
- :<name>!:
- .AttributeEntry behavior
- - The attribute entry line begins with colon -- no white space allowed
- in left margin.
- - AsciiDoc converts the `<name>` to a legal attribute name (lower
- case, alphanumeric, dash and underscore characters only -- all other
- characters deleted). This allows more human friendly text to be
- used.
- - Leading and trailing white space is stripped from the `<value>`.
- - Lines ending in a space followed by a plus character are continued
- to the next line, for example:
- :description: AsciiDoc is a text document format for writing notes, +
- documentation, articles, books, slideshows, web pages +
- and man pages.
- - If the `<value>` is blank then the corresponding attribute value is
- set to an empty string.
- - Attribute references contained in the entry `<value>` will be
- expanded.
- - By default AttributeEntry values are substituted for
- `specialcharacters` and `attributes` (see above), if you want to
- change or disable AttributeEntry substitution use the <<X77,pass:[]
- inline macro>> syntax.
- - Attribute entries in the document Header are available for header
- markup template substitution.
- - Attribute elements override configuration file and intrinsic
- attributes but do not override command-line attributes.
- Here are some more attribute entry examples:
- ---------------------------------------------------------------------
- AsciiDoc User Manual
- ====================
- :author: Stuart Rackham
- :email: srackham@gmail.com
- :revdate: April 23, 2004
- :revnumber: 5.1.1
- ---------------------------------------------------------------------
- Which creates these attributes:
- {author}, {firstname}, {lastname}, {authorinitials}, {email},
- {revdate}, {revnumber}
- The previous example is equivalent to this <<X95,document header>>:
- ---------------------------------------------------------------------
- AsciiDoc User Manual
- ====================
- Stuart Rackham <srackham@gmail.com>
- 5.1.1, April 23, 2004
- ---------------------------------------------------------------------
- Setting configuration entries
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- A variant of the Attribute Entry syntax allows configuration file
- section entries and markup template sections to be set from within an
- AsciiDoc document:
- :<section_name>.[<entry_name>]: <entry_value>
- Where `<section_name>` is the configuration section name,
- `<entry_name>` is the name of the entry and `<entry_value>` is the
- optional entry value. This example sets the default labeled list
- style to 'horizontal':
- :listdef-labeled.style: horizontal
- It is exactly equivalent to a configuration file containing:
- [listdef-labeled]
- style=horizontal
- - If the `<entry_name>` is omitted then the entire section is
- substituted with the `<entry_value>`. This feature should only be
- used to set markup template sections. The following example sets the
- 'xref2' inline macro markup template:
- :xref2-inlinemacro.: <a href="#{1}">{2?{2}}</a>
- - No substitution is performed on configuration file attribute entries
- and they cannot be undefined.
- - This feature can only be used in attribute entries -- configuration
- attributes cannot be set using the asciidoc(1) command `--attribute`
- option.
- [[X62]]
- .Attribute entries promote clarity and eliminate repetition
- *********************************************************************
- URLs and file names in AsciiDoc macros are often quite long -- they
- break paragraph flow and readability suffers. The problem is
- compounded by redundancy if the same name is used repeatedly.
- Attribute entries can be used to make your documents easier to read
- and write, here are some examples:
- :1: http://freshmeat.net/projects/asciidoc/
- :homepage: http://methods.co.nz/asciidoc/[AsciiDoc home page]
- :new: image:./images/smallnew.png[]
- :footnote1: footnote:[A meaningless latin term]
- Using previously defined attributes: See the {1}[Freshmeat summary]
- or the {homepage} for something new {new}. Lorem ispum {footnote1}.
- .Note
- - The attribute entry definition must precede it's usage.
- - You are not limited to URLs or file names, entire macro calls or
- arbitrary lines of text can be abbreviated.
- - Shared attributes entries could be grouped into a separate file and
- <<X63,included>> in multiple documents.
- *********************************************************************
- [[X21]]
- Attribute Lists
- ---------------
- - An attribute list is a comma separated list of attribute values.
- - The entire list is enclosed in square brackets.
- - Attribute lists are used to pass parameters to macros, blocks (using
- the <<X79,AttributeList element>>) and inline quotes.
- The list consists of zero or more positional attribute values followed
- by zero or more named attribute values. Here are three examples: a
- single unquoted positional attribute; three unquoted positional
- attribute values; one positional attribute followed by two named
- attributes; the unquoted attribute value in the final example contains
- comma (`,`) and double-quote (`"`) character entities:
- [Hello]
- [quote, Bertrand Russell, The World of Mathematics (1956)]
- ["22 times", backcolor="#0e0e0e", options="noborders,wide"]
- [A footnote, "with an image" image:smallnew.png[]]
- .Attribute list behavior
- - If one or more attribute values contains a comma the all string
- values must be quoted (enclosed in double quotation mark
- characters).
- - If the list contains any named or quoted attributes then all string
- attribute values must be quoted.
- - To include a double quotation mark (") character in a quoted
- attribute value the the quotation mark must be escaped with a
- backslash.
- - List attributes take precedence over existing attributes.
- - List attributes can only be referenced in configuration file markup
- templates and tags, they are not available elsewhere in the
- document.
- - Setting a named attribute to `None` undefines the attribute.
- - Positional attributes are referred to as `{1}`,`{2}`,`{3}`,...
- - Attribute `{0}` refers to the entire list (excluding the enclosing
- square brackets).
- - Named attribute names cannot contain dash characters.
- [[X75]]
- Options attribute
- ~~~~~~~~~~~~~~~~~
- If the attribute list contains an attribute named `options` it is
- processed as a comma separated list of option names:
- - Each name generates an attribute named like `<option>-option` (where
- `<option>` is the option name) with an empty string value. For
- example `[options="opt1,opt2,opt3"]` is equivalent to setting the
- following three attributes
- `[opt1-option="",opt2-option="",opt2-option=""]`.
- - If you define a an option attribute globally (for example with an
- <<X18,attribute entry>>) then it will apply to all elements in the
- document.
- - AsciiDoc implements a number of predefined options which are listed
- in the <<X74,Attribute Options appendix>>.
- Macro Attribute lists
- ~~~~~~~~~~~~~~~~~~~~~
- Macros calls are suffixed with an attribute list. The list may be
- empty but it cannot be omitted. List entries are used to pass
- attribute values to macro markup templates.
- Attribute References
- --------------------
- An attribute reference is an attribute name (possibly followed by an
- additional parameters) enclosed in curly braces. When an attribute
- reference is encountered it is evaluated and replaced by its
- corresponding text value. If the attribute is undefined the line
- containing the attribute is dropped.
- There are three types of attribute reference: 'Simple', 'Conditional'
- and 'System'.
- .Attribute reference evaluation
- - You can suppress attribute reference expansion by placing a
- backslash character immediately in front of the opening brace
- character.
- - By default attribute references are not expanded in
- 'LiteralParagraphs', 'ListingBlocks' or 'LiteralBlocks'.
- - Attribute substitution proceeds line by line in reverse line order.
- - Attribute reference evaluation is performed in the following order:
- 'Simple' then 'Conditional' and finally 'System'.
- Simple Attributes References
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Simple attribute references take the form `{<name>}`. If the
- attribute name is defined its text value is substituted otherwise the
- line containing the reference is dropped from the output.
- Conditional Attribute References
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Additional parameters are used in conjunction with attribute names to
- calculate a substitution value. Conditional attribute references take
- the following forms:
- `{<names>=<value>}`::
- `<value>` is substituted if the attribute `<names>` is
- undefined otherwise its value is substituted. `<value>` can
- contain simple attribute references.
- `{<names>?<value>}`::
- `<value>` is substituted if the attribute `<names>` is defined
- otherwise an empty string is substituted. `<value>` can
- contain simple attribute references.
- `{<names>!<value>}`::
- `<value>` is substituted if the attribute `<names>` is
- undefined otherwise an empty string is substituted. `<value>`
- can contain simple attribute references.
- `{<names>#<value>}`::
- `<value>` is substituted if the attribute `<names>` is defined
- otherwise the undefined attribute entry causes the containing
- line to be dropped. `<value>` can contain simple attribute
- references.
- `{<names>%<value>}`::
- `<value>` is substituted if the attribute `<names>` is not
- defined otherwise the containing line is dropped. `<value>`
- can contain simple attribute references.
- `{<names>@<regexp>:<value1>[:<value2>]}`::
- `<value1>` is substituted if the value of attribute `<names>`
- matches the regular expression `<regexp>` otherwise `<value2>`
- is substituted. If attribute `<names>` is not defined the
- containing line is dropped. If `<value2>` is omitted an empty
- string is assumed. The values and the regular expression can
- contain simple attribute references. To embed colons in the
- values or the regular expression escape them with backslashes.
- `{<names>$<regexp>:<value1>[:<value2>]}`::
- Same behavior as the previous ternary attribute except for
- the following cases:
- `{<names>$<regexp>:<value>}`;;
- Substitutes `<value>` if `<names>` matches `<regexp>`
- otherwise the result is undefined and the containing
- line is dropped.
- `{<names>$<regexp>::<value>}`;;
- Substitutes `<value>` if `<names>` does not match
- `<regexp>` otherwise the result is undefined and the
- containing line is dropped.
- The attribute `<names>` parameter normally consists of a single
- attribute name but it can be any one of the following:
- - A single attribute name which evaluates to the attributes value.
- - Multiple ',' separated attribute names which evaluates to an empty
- string if one or more of the attributes is defined, otherwise it's
- value is undefined.
- - Multiple '+' separated attribute names which evaluates to an empty
- string if all of the attributes are defined, otherwise it's value is
- undefined.
- Conditional attributes with single attribute names are evaluated first
- so they can be used inside the multi-attribute conditional `<value>`.
- Conditional attribute examples
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Conditional attributes are mainly used in AsciiDoc configuration
- files -- see the distribution `.conf` files for examples.
- Attribute equality test::
- If `{backend}` is 'docbook45' or 'xhtml11' the example evaluates to
- ``DocBook 4.5 or XHTML 1.1 backend'' otherwise it evaluates to
- ``some other backend'':
- {backend@docbook45|xhtml11:DocBook 4.5 or XHTML 1.1 backend:some other backend}
- Attribute value map::
- This example maps the `frame` attribute values [`topbot`, `all`,
- `none`, `sides`] to [`hsides`, `border`, `void`, `vsides`]:
- {frame@topbot:hsides}{frame@all:border}{frame@none:void}{frame@sides:vsides}
- [[X24]]
- System Attribute References
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
- System attribute references generate the attribute text value by
- executing a predefined action that is parametrized by one or more
- arguments. The syntax is `{<action>:<arguments>}`.
- `{counter:<attrname>[:<seed>]}`::
- Increments the document attribute (if the attribute is
- undefined it is set to `1`). Returns the new attribute value.
- - Counters generate global (document wide) attributes.
- - The optional `<seed>` specifies the counter's initial value;
- it can be a number or a single letter; defaults to '1'.
- - `<seed>` can contain simple and conditional attribute
- references.
- - The 'counter' system attribute will not be executed if the
- containing line is dropped by the prior evaluation of an
- undefined attribute.
- `{counter2:<attrname>[:<seed>]}`::
- Same as `counter` except the it always returns a blank string.
- `{eval:<expression>}`::
- Substitutes the result of the Python `<expression>`.
- - If `<expression>` evaluates to `None` or `False` the
- reference is deemed undefined and the line containing the
- reference is dropped from the output.
- - If the expression evaluates to `True` the attribute
- evaluates to an empty string.
- - `<expression>` can contain simple and conditional attribute
- references.
- - The 'eval' system attribute can be nested inside other
- system attributes.
- `{eval3:<command>}`::
- Passthrough version of `{eval:<expression>}` -- the generated
- output is written directly to the output without any further
- substitutions.
- `{include:<filename>}`::
- Substitutes contents of the file named `<filename>`.
- - The included file is read at the time of attribute
- substitution.
- - If the file does not exist a warning is emitted and the line
- containing the reference is dropped from the output file.
- - Tabs are expanded based on the current 'tabsize' attribute
- value.
- `{set:<attrname>[!][:<value>]}`::
- Sets or unsets document attribute. Normally only used in
- configuration file markup templates (use
- <<X18,AttributeEntries>> in AsciiDoc documents).
- - If the attribute name is followed by an exclamation mark
- the attribute becomes undefined.
- - If `<value>` is omitted the attribute is set to a blank
- string.
- - `<value>` can contain simple and conditional attribute
- references.
- - Returns a blank string unless the attribute is undefined in
- which case the return value is undefined and the enclosing
- line will be dropped.
- `{set2:<attrname>[!][:<value>]}`::
- Same as `set` except that the attribute scope is local to the
- template.
- `{sys:<command>}`::
- Substitutes the stdout generated by the execution of the shell
- `<command>`.
- `{sys2:<command>}`::
- Substitutes the stdout and stderr generated by the execution
- of the shell `<command>`.
- `{sys3:<command>}`::
- Passthrough version of `{sys:<command>}` -- the generated
- output is written directly to the output without any further
- substitutions.
- `{template:<template>}`::
- Substitutes the contents of the configuration file section
- named `<template>`. Attribute references contained in the
- template are substituted.
- .System reference behavior
- - System attribute arguments can contain non-system attribute
- references.
- - Closing brace characters inside system attribute arguments must be
- escaped with a backslash.
- [[X60]]
- Intrinsic Attributes
- --------------------
- Intrinsic attributes are simple attributes that are created
- automatically from: AsciiDoc document header parameters; asciidoc(1)
- command-line arguments; attributes defined in the default
- configuration files; the execution context. Here's the list of
- predefined intrinsic attributes:
- {amp} ampersand (&) character entity
- {asciidoc-args} used to pass inherited arguments to asciidoc filters
- {asciidoc-confdir} the asciidoc(1) global configuration directory
- {asciidoc-dir} the asciidoc(1) application directory
- {asciidoc-file} the full path name of the asciidoc(1) script
- {asciidoc-version} the version of asciidoc(1)
- {author} author's full name
- {authored} empty string '' if {author} or {email} defined,
- {authorinitials} author initials (from document header)
- {backend-<backend>} empty string ''
- {<backend>-<doctype>} empty string ''
- {backend} document backend specified by `-b` option
- {backend-confdir} the directory containing the <backend>.conf file
- {backslash} backslash character
- {basebackend-<base>} empty string ''
- {basebackend} html or docbook
- {blockname} current block name (note 8).
- {brvbar} broken vertical bar (|) character
- {docdate} document last modified date
- {docdir} document input directory name (note 5)
- {docfile} document file name (note 5)
- {docname} document file name without extension (note 6)
- {doctime} document last modified time
- {doctitle} document title (from document header)
- {doctype-<doctype>} empty string ''
- {doctype} document type specified by `-d` option
- {email} author's email address (from document header)
- {empty} empty string ''
- {encoding} specifies input and output encoding
- {filetype-<fileext>} empty string ''
- {filetype} output file name file extension
- {firstname} author first name (from document header)
- {gt} greater than (>) character entity
- {id} running block id generated by BlockId elements
- {indir} input file directory name (note 2,5)
- {infile} input file name (note 2,5)
- {lastname} author last name (from document header)
- {ldquo} Left double quote character (note 7)
- {level} title level 1..4 (in section titles)
- {listindex} the list index (1..) of the most recent list item
- {localdate} the current date
- {localtime} the current time
- {lsquo} Left single quote character (note 7)
- {lt} less than (<) character entity
- {manname} manpage name (defined in NAME section)
- {manpurpose} manpage (defined in NAME section)
- {mantitle} document title minus the manpage volume number
- {manvolnum} manpage volume number (1..8) (from document header)
- {middlename} author middle name (from document header)
- {nbsp} non-breaking space character entity
- {notitle} do not display the document title
- {outdir} document output directory name (note 2)
- {outfile} output file name (note 2)
- {python} the full path name of the Python interpreter executable
- {rdquo} Right double quote character (note 7)
- {reftext} running block xreflabel generated by BlockId elements
- {revdate} document revision date (from document header)
- {revnumber} document revision number (from document header)
- {rsquo} Right single quote character (note 7)
- {sectnum} formatted section number (in section titles)
- {sp} space character
- {showcomments} send comment lines to the output
- {title} section title (in titled elements)
- {two-colons} Two colon characters
- {two-semicolons} Two semicolon characters
- {user-dir} the ~/.asciidoc directory (if it exists)
- {verbose} defined as '' if --verbose command option specified
- {wj} Word-joiner
- {zwsp} Zero-width space character entity
- [NOTE]
- ======
- 1. Intrinsic attributes are global so avoid defining custom attributes
- with the same names.
- 2. `{outfile}`, `{outdir}`, `{infile}`, `{indir}` attributes are
- effectively read-only (you can set them but it won't affect the
- input or output file paths).
- 3. See also the <<X88,Backend Attributes>> section for attributes
- that relate to AsciiDoc XHTML file generation.
- 4. The entries that translate to blank strings are designed to be used
- for conditional text inclusion. You can also use the `ifdef`,
- `ifndef` and `endif` System macros for conditional inclusion.
- footnote:[Conditional inclusion using `ifdef` and `ifndef` macros
- differs from attribute conditional inclusion in that the former
- occurs when the file is read while the latter occurs when the
- contents are written.]
- 5. `{docfile}` and `{docdir}` refer to root document specified on the
- asciidoc(1) command-line; `{infile}` and `{indir}` refer to the
- current input file which may be the root document or an included
- file. When the input is being read from the standard input
- (`stdin`) these attributes are undefined.
- 6. If the input file is the standard input and the output file is not
- the standard output then `{docname}` is the output file name sans
- file extension.
- 7. See
- http://en.wikipedia.org/wiki/Non-English_usage_of_quotation_marks[non-English
- usage of quotation marks].
- 8. The `{blockname}` attribute identifies the style of the current
- block. It applies to delimited blocks, lists and tables. Here is a
- list of `{blockname}` values (does not include filters or custom
- block and style names):
- delimited blocks:: comment, sidebar, open, pass, literal, verse,
- listing, quote, example, note, tip, important, caution, warning,
- abstract, partintro
- lists:: arabic, loweralpha, upperalpha, lowerroman, upperroman,
- labeled, labeled3, labeled4, qanda, horizontal, bibliography,
- glossary
- tables:: table
- ======
- [[X73]]
- Block Element Definitions
- -------------------------
- The syntax and behavior of Paragraph, DelimitedBlock, List and Table
- block elements is determined by block definitions contained in
- <<X7,AsciiDoc configuration file>> sections.
- Each definition consists of a section title followed by one or more
- section entries. Each entry defines a block parameter controlling some
- aspect of the block's behavior. Here's an example:
- ---------------------------------------------------------------------
- [blockdef-listing]
- delimiter=^-{4,}$
- template=listingblock
- presubs=specialcharacters,callouts
- ---------------------------------------------------------------------
- Configuration file block definition sections are processed
- incrementally after each configuration file is loaded. Block
- definition section entries are merged into the block definition, this
- allows block parameters to be overridden and extended by later
- <<X27,loading configuration files>>.
- AsciiDoc Paragraph, DelimitedBlock, List and Table block elements
- share a common subset of configuration file parameters:
- delimiter::
- A Python regular expression that matches the first line of a block
- element -- in the case of DelimitedBlocks and Tables it also matches
- the last line.
- template::
- The name of the configuration file markup template section that will
- envelope the block contents. The pipe ('|') character is substituted
- for the block contents. List elements use a set of (list specific)
- tag parameters instead of a single template. The template name can
- contain attribute references allowing dynamic template selection a
- the time of template substitution.
- options::
- A comma delimited list of element specific option names. In addition
- to being used internally, options are available during markup tag
- and template substitution as attributes with an empty string value
- named like `<option>-option` (where `<option>` is the option name).
- See <<X74,attribute options>> for a complete list of available
- options.
- subs, presubs, postsubs::
- * 'presubs' and 'postsubs' are lists of comma separated substitutions that are
- performed on the block contents. 'presubs' is applied first,
- 'postsubs' (if specified) second.
- * 'subs' is an alias for 'presubs'.
- * If a 'filter' is allowed (Paragraphs, DelimitedBlocks and Tables)
- and has been specified then 'presubs' and 'postsubs' substitutions
- are performed before and after the filter is run respectively.
- * Allowed values: 'specialcharacters', 'quotes', 'specialwords',
- 'replacements', 'macros', 'attributes', 'callouts'.
- * [[X102]]The following composite values are also allowed:
- 'none';;
- No substitutions.
- 'normal';;
- The following substitutions in the following order:
- 'specialcharacters', 'quotes', 'attributes', 'specialwords',
- 'replacements', 'macros', 'replacements2'.
- 'verbatim';;
- The following substitutions in the following order:
- 'specialcharacters' and 'callouts'.
- * 'normal' and 'verbatim' substitutions can be redefined by with
- `subsnormal` and `subsverbatim` entries in a configuration file
- `[miscellaneous]` section.
- * The substitutions are processed in the order in which they are
- listed and can appear more than once.
- filter::
- This optional entry specifies an executable shell command for
- processing block content (Paragraphs, DelimitedBlocks and Tables).
- The filter command can contain attribute references.
- posattrs::
- Optional comma separated list of positional attribute names. This
- list maps positional attributes (in the block's <<X21,attribute
- list>>) to named block attributes. The following example, from the
- QuoteBlock definition, maps the first and section positional
- attributes:
- posattrs=attribution,citetitle
- style::
- This optional parameter specifies the default style name.
- <stylename>-style::
- Optional style definition (see <<X23,Styles>> below).
- The following block parameters behave like document attributes and can
- be set in block attribute lists and style definitions: 'template',
- 'options', 'subs', 'presubs', 'postsubs', 'filter'.
- [[X23]]
- Styles
- ~~~~~~
- A style is a set of block parameter bundled as a single named
- parameter. The following example defines a style named 'verbatim':
- verbatim-style=template="literalblock",subs="verbatim"
- If a block's <<X21,attribute list>> contains a 'style' attribute then
- the corresponding style parameters are be merged into the default
- block definition parameters.
- - All style parameter names must be suffixed with `-style` and the
- style parameter value is in the form of a list of <<X21,named
- attributes>>.
- - The 'template' style parameter is mandatory, other parameters can be
- omitted in which case they inherit their values from the default
- block definition parameters.
- - Multi-item style parameters ('subs','presubs','postsubs','posattrs')
- must be specified using Python tuple syntax (rather than a simple
- list of values as they in separate entries) e.g.
- `postsubs=("callouts",)` not `postsubs="callouts"`.
- Paragraphs
- ~~~~~~~~~~
- Paragraph translation is controlled by `[paradef-*]` configuration
- file section entries. Users can define new types of paragraphs and
- modify the behavior of existing types by editing AsciiDoc
- configuration files.
- Here is the shipped Default paragraph definition:
- --------------------------------------------------------------------
- [paradef-default]
- delimiter=(?P<text>\S.*)
- template=paragraph
- --------------------------------------------------------------------
- The normal paragraph definition has a couple of special properties:
- 1. It must exist and be defined in a configuration file section named
- `[paradef-default]`.
- 2. Irrespective of its position in the configuration files default
- paragraph document matches are attempted only after trying all
- other paragraph types.
- Paragraph specific block parameter notes:
- delimiter::
- This regular expression must contain the named group 'text' which
- matches the text on the first line. Paragraphs are terminated by a
- blank line, the end of file, or the start of a DelimitedBlock.
- options::
- The 'listelement' option specifies that paragraphs of this type will
- automatically be considered part of immediately preceding list
- items. The 'skip' option causes the paragraph to be treated as a
- comment (see <<X26,CommentBlocks>>).
- .Paragraph processing proceeds as follows:
- 1. The paragraph text is aligned to the left margin.
- 2. Optional 'presubs' inline substitutions are performed on the
- paragraph text.
- 3. If a filter command is specified it is executed and the paragraph
- text piped to its standard input; the filter output replaces the
- paragraph text.
- 4. Optional 'postsubs' inline substitutions are performed on the
- paragraph text.
- 5. The paragraph text is enveloped by the paragraph's markup template
- and written to the output file.
- Delimited Blocks
- ~~~~~~~~~~~~~~~~
- DelimitedBlock 'options' values are:
- sectionbody::
- The block contents are processed as a SectionBody.
- skip::
- The block is treated as a comment (see <<X26,CommentBlocks>>).
- Preceding <<X21,attribute lists>> and <<X42,block titles>> are not
- consumed.
- 'presubs', 'postsubs' and 'filter' entries are ignored when
- 'sectionbody' or 'skip' options are set.
- DelimitedBlock processing proceeds as follows:
- 1. Optional 'presubs' substitutions are performed on the block
- contents.
- 2. If a filter is specified it is executed and the block's contents
- piped to its standard input. The filter output replaces the block
- contents.
- 3. Optional 'postsubs' substitutions are performed on the block
- contents.
- 4. The block contents is enveloped by the block's markup template and
- written to the output file.
- TIP: Attribute expansion is performed on the block filter command
- before it is executed, this is useful for passing arguments to the
- filter.
- Lists
- ~~~~~
- List behavior and syntax is determined by `[listdef-*]` configuration
- file sections. The user can change existing list behavior and add new
- list types by editing configuration files.
- List specific block definition notes:
- type::
- This is either 'bulleted','numbered','labeled' or 'callout'.
- delimiter::
- A Python regular expression that matches the first line of a
- list element entry. This expression can contain the named groups
- 'text' (bulleted groups), 'index' and 'text' (numbered lists),
- 'label' and 'text' (labeled lists).
- tags::
- The `<name>` of the `[listtags-<name>]` configuration file section
- containing list markup tag definitions. The tag entries ('list',
- 'entry', 'label', 'term', 'text') map the AsciiDoc list structure to
- backend markup; see the 'listtags' sections in the AsciiDoc
- distributed backend `.conf` configuration files for examples.
- Tables
- ~~~~~~
- Table behavior and syntax is determined by `[tabledef-*]` and
- `[tabletags-*]` configuration file sections. The user can change
- existing table behavior and add new table types by editing
- configuration files. The following `[tabledef-*]` section entries
- generate table output markup elements:
- colspec::
- The table 'colspec' tag definition.
- headrow, footrow, bodyrow::
- Table header, footer and body row tag definitions. 'headrow' and
- 'footrow' table definition entries default to 'bodyrow' if
- they are undefined.
- headdata, footdata, bodydata::
- Table header, footer and body data tag definitions. 'headdata' and
- 'footdata' table definition entries default to 'bodydata' if they
- are undefined.
- paragraph::
- If the 'paragraph' tag is specified then blank lines in the cell
- data are treated as paragraph delimiters and marked up using this
- tag.
- [[X4]]
- Table behavior is also influenced by the following `[miscellaneous]`
- configuration file entries:
- pagewidth::
- This integer value is the printable width of the output media. See
- <<X69,table attributes>>.
- pageunits::
- The units of width in output markup width attribute values.
- .Table definition behavior
- - The output markup generation is specifically designed to work with
- the HTML and CALS (DocBook) table models, but should be adaptable to
- most XML table schema.
- - Table definitions can be ``mixed in'' from multiple cascading
- configuration files.
- - New table definitions inherit the default table and table tags
- definitions (`[tabledef-default]` and `[tabletags-default]`) so you
- only need to override those conf file entries that require
- modification.
- [[X59]]
- Filters
- -------
- AsciiDoc filters allow external commands to process AsciiDoc
- 'Paragraphs', 'DelimitedBlocks' and 'Table' content. Filters are
- primarily an extension mechanism for generating specialized outputs.
- Filters are implemented using external commands which are specified in
- configuration file definitions.
- There's nothing special about the filters, they're just standard UNIX
- filters: they read text from the standard input, process it, and write
- to the standard output.
- The asciidoc(1) command `--filter` option can be used to install and
- remove filters. The same option is used to unconditionally load a
- filter.
- Attribute substitution is performed on the filter command prior to
- execution -- attributes can be used to pass parameters from the
- AsciiDoc source document to the filter.
- WARNING: Filters sometimes included executable code. Before installing
- a filter you should verify that it is from a trusted source.
- Filter Search Paths
- ~~~~~~~~~~~~~~~~~~~
- If the filter command does not specify a directory path then
- asciidoc(1) recursively searches for the executable filter command:
- - First it looks in the user's `$HOME/.asciidoc/filters` directory.
- - Next the global filters directory (usually `/etc/asciidoc/filters`
- or `/usr/local/etc/asciidoc`) directory is searched.
- - Then it looks in the asciidoc(1) `./filters` directory.
- - Finally it relies on the executing shell to search the environment
- search path (`$PATH`).
- Standard practice is to install each filter in it's own sub-directory
- with the same name as the filter's style definition. For example the
- music filter's style name is 'music' so it's configuration and filter
- files are stored in the `filters/music` directory.
- Filter Configuration Files
- ~~~~~~~~~~~~~~~~~~~~~~~~~~
- Filters are normally accompanied by a configuration file containing a
- Paragraph or DelimitedBlock definition along with corresponding markup
- templates.
- While it is possible to create new 'Paragraph' or 'DelimitedBlock'
- definitions the preferred way to implement a filter is to add a
- <<X23,style>> to the existing Paragraph and ListingBlock definitions
- (all filters shipped with AsciiDoc use this technique). The filter is
- applied to the paragraph or delimited block by preceding it with an
- attribute list: the first positional attribute is the style name,
- remaining attributes are normally filter specific parameters.
- asciidoc(1) auto-loads all `.conf` files found in the filter search
- paths unless the container directory also contains a file named
- `__noautoload__` (see previous section). The `__noautoload__` feature
- is used for filters that will be loaded manually using the `--filter`
- option.
- [[X56]]
- Example Filter
- ~~~~~~~~~~~~~~
- AsciiDoc comes with a toy filter for highlighting source code keywords
- and comments. See also the `./filters/code/code-filter-readme.txt`
- file.
- NOTE: The purpose of this toy filter is to demonstrate how to write a
- filter -- it's much to simplistic to be passed off as a code syntax
- highlighter. If you want a full featured multi-language highlighter
- use the {website}source-highlight-filter.html[source code highlighter
- filter].
- Built-in filters
- ~~~~~~~~~~~~~~~~
- The AsciiDoc distribution includes 'source', 'music', 'latex' and
- 'graphviz' filters, details are on the
- {website}index.html#_filters[AsciiDoc website].
- [cols="1e,5",frame="topbot",options="header"]
- .Built-in filters list
- |====================================================================
- |Filter name |Description
- |music
- |A {website}music-filter.html[music filter] is included in the
- distribution `./filters/` directory. It translates music in
- http://lilypond.org/[LilyPond] or http://abcnotation.org.uk/[ABC]
- notation to standard classical notation.
- |source
- |A {website}source-highlight-filter.html[source code highlight filter]
- is included in the distribution `./filters/` directory.
- |latex
- |The {website}latex-filter.html[AsciiDoc LaTeX filter] translates
- LaTeX source to a PNG image that is automatically inserted into the
- AsciiDoc output documents.
- |graphviz
- |Gouichi Iisaka has written a http://www.graphviz.org/[Graphviz]
- filter for AsciiDoc. Graphviz generates diagrams from a textual
- specification. Gouichi Iisaka's Graphviz filter is included in the
- AsciiDoc distribution. Here are some
- {website}asciidoc-graphviz-sample.html[AsciiDoc Graphviz examples].
- |====================================================================
- [[X58]]
- Filter plugins
- ~~~~~~~~~~~~~~
- Filter <<X101,plugins>> are a mechanism for distributing AsciiDoc
- filters. A filter plugin is a Zip file containing the files that
- constitute a filter. The asciidoc(1) `--filter` option is used to
- load and manage filer <<X101,plugins>>.
- - Filter plugins <<X27,take precedence>> over built-in filters with
- the same name.
- - By default filter plugins are installed in
- `$HOME/.asciidoc/filters/<filter>` where `<filter>` is the filter
- name.
- [[X101]]
- Plugins
- -------
- The AsciiDoc plugin architecture is an extension mechanism that allows
- additional <<X100,backends>>, <<X58,filters>> and <<X99,themes>> to be
- added to AsciiDoc.
- - A plugin is a Zip file containing an AsciiDoc backend, filter or
- theme (configuration files, stylesheets, scripts, images).
- - The asciidoc(1) `--backend`, `--filter` and `--theme` command-line
- options are used to load and manage plugins. Each of these options
- responds to the plugin management 'install', 'list', 'remove' and
- 'build' commands.
- - The plugin management command names are reserved and cannot be used
- for filter, backend or theme names.
- - The plugin Zip file name always begins with the backend, filter or
- theme name.
- Plugin commands and conventions are documented in the asciidoc(1) man
- page. You can find lists of plugins on the
- {website}plugins.html[AsciiDoc website].
- [[X36]]
- Help Commands
- -------------
- The asciidoc(1) command has a `--help` option which prints help topics
- to stdout. The default topic summarizes asciidoc(1) usage:
- $ asciidoc --help
- To print a help topic specify the topic name as a command argument.
- Help topic names can be shortened so long as they are not ambiguous.
- Examples:
- $ asciidoc --help manpage
- $ asciidoc -h m # Short version of previous example.
- $ asciidoc --help syntax
- $ asciidoc -h s # Short version of previous example.
- Customizing Help
- ~~~~~~~~~~~~~~~~
- To change, delete or add your own help topics edit a help
- configuration file. The help file name `help-<lang>.conf` is based on
- the setting of the `lang` attribute, it defaults to `help.conf`
- (English). The <<X27,help file location>> will depend on whether you
- want the topics to apply to all users or just the current user.
- The help topic files have the same named section format as other
- <<X7,configuration files>>. The `help.conf` files are stored in the
- same locations and loaded in the same order as other configuration
- files.
- When the `--help` command-line option is specified AsciiDoc loads the
- appropriate help files and then prints the contents of the section
- whose name matches the help topic name. If a topic name is not
- specified `default` is used. You don't need to specify the whole help
- topic name on the command-line, just enough letters to ensure it's not
- ambiguous. If a matching help file section is not found a list of
- available topics is printed.
- Tips and Tricks
- ---------------
- Know Your Editor
- ~~~~~~~~~~~~~~~~
- Writing AsciiDoc documents will be a whole lot more pleasant if you
- know your favorite text editor. Learn how to indent and reformat text
- blocks, paragraphs, lists and sentences. <<X20,Tips for 'vim' users>>
- follow.
- [[X20]]
- Vim Commands for Formatting AsciiDoc
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Text Wrap Paragraphs
- ^^^^^^^^^^^^^^^^^^^^
- Use the vim `:gq` command to reformat paragraphs. Setting the
- 'textwidth' sets the right text wrap margin; for example:
- :set textwidth=70
- To reformat a paragraph:
- 1. Position the cursor at the start of the paragraph.
- 2. Type `gq}`.
- Execute `:help gq` command to read about the vim gq command.
- [TIP]
- =====================================================================
- - Assign the `gq}` command to the Q key with the `nnoremap Q gq}`
- command or put it in your `~/.vimrc` file to so it's always
- available (see the <<X61, Example `~/.vimrc` file>>).
- - Put `set` commands in your `~/.vimrc` file so you don't have to
- enter them manually.
- - The Vim website (http://www.vim.org) has a wealth of resources,
- including scripts for automated spell checking and ASCII Art
- drawing.
- =====================================================================
- Format Lists
- ^^^^^^^^^^^^
- The `gq` command can also be used to format bulleted, numbered and
- callout lists. First you need to set the `comments`, `formatoptions`
- and `formatlistpat` (see the <<X61, Example `~/.vimrc` file>>).
- Now you can format simple lists that use dash, asterisk, period and
- plus bullets along with numbered ordered lists:
- 1. Position the cursor at the start of the list.
- 2. Type `gq}`.
- Indent Paragraphs
- ^^^^^^^^^^^^^^^^^
- Indent whole paragraphs by indenting the fist line with the desired
- indent and then executing the `gq}` command.
- [[X61]]
- Example `~/.vimrc` File
- ^^^^^^^^^^^^^^^^^^^^^^^
- ---------------------------------------------------------------------
- " Use bold bright fonts.
- set background=dark
- " Show tabs and trailing characters.
- set listchars=tab:»·,trail:·
- set list
- " Don't highlight searched text.
- highlight clear Search
- " Don't move to matched text while search pattern is being entered.
- set noincsearch
- " Reformat paragraphs and list.
- nnoremap R gq}
- " Delete trailing white space and Dos-returns and to expand tabs to spaces.
- nnoremap S :set et<CR>:retab!<CR>:%s/[\r \t]\+$//<CR>
- autocmd BufRead,BufNewFile *.txt,README,TODO,CHANGELOG,NOTES
- \ setlocal autoindent expandtab tabstop=8 softtabstop=2 shiftwidth=2 filetype=asciidoc
- \ textwidth=70 wrap formatoptions=tcqn
- \ formatlistpat=^\\s*\\d\\+\\.\\s\\+\\\\|^\\s*<\\d\\+>\\s\\+\\\\|^\\s*[a-zA-Z.]\\.\\s\\+\\\\|^\\s*[ivxIVX]\\+\\.\\s\\+
- \ comments=s1:/*,ex:*/,://,b:#,:%,:XCOMM,fb:-,fb:*,fb:+,fb:.,fb:>
- ---------------------------------------------------------------------
- Troubleshooting
- ~~~~~~~~~~~~~~~
- AsciiDoc diagnostic features are detailed in the <<X82,Diagnostics
- appendix>>.
- Gotchas
- ~~~~~~~
- Incorrect character encoding::
- If you get an error message like `'UTF-8' codec can't decode ...`
- then you source file contains invalid UTF-8 characters -- set the
- AsciiDoc <<X54,encoding attribute>> for the correct character set
- (typically ISO-8859-1 (Latin-1) for European languages).
- Invalid output::
- AsciiDoc attempts to validate the input AsciiDoc source but makes
- no attempt to validate the output markup, it leaves that to
- external tools such as `xmllint(1)` (integrated into `a2x(1)`).
- Backend validation cannot be hardcoded into AsciiDoc because
- backends are dynamically configured. The following example
- generates valid HTML but invalid DocBook (the DocBook `literal`
- element cannot contain an `emphasis` element):
- +monospaced text with an _emphasized_ word+
- Misinterpreted text formatting::
- You can suppress markup expansion by placing a backslash character
- immediately in front of the element. The following example
- suppresses inline monospaced formatting:
- \+1 for C++.
- Overlapping text formatting::
- Overlapping text formatting will generate illegal overlapping
- markup tags which will result in downstream XML parsing errors.
- Here's an example:
- Some *strong markup _that overlaps* emphasized markup_.
- Ambiguous underlines::
- A DelimitedBlock can immediately follow a paragraph without an
- intervening blank line, but be careful, a single line paragraph
- underline may be misinterpreted as a section title underline
- resulting in a ``closing block delimiter expected'' error.
- Ambiguous ordered list items::
- Lines beginning with numbers at the end of sentences will be
- interpreted as ordered list items. The following example
- (incorrectly) begins a new list with item number 1999:
- He was last sighted in
- 1999. Since then things have moved on.
- +
- The 'list item out of sequence' warning makes it unlikely that this
- problem will go unnoticed.
- Special characters in attribute values::
- Special character substitution precedes attribute substitution so
- if attribute values contain special characters you may, depending
- on the substitution context, need to escape the special characters
- yourself. For example:
- $ asciidoc -a 'orgname=Bill & Ben Inc.' mydoc.txt
- Attribute lists::
- If any named attribute entries are present then all string
- attribute values must be quoted. For example:
- ["Desktop screenshot",width=32]
- [[X90]]
- Combining separate documents
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- You have a number of stand-alone AsciiDoc documents that you want to
- process as a single document. Simply processing them with a series of
- `include` macros won't work because the documents contain (level 0)
- document titles. The solution is to create a top level wrapper
- document and use the `leveloffset` attribute to push them all down one
- level. For example:
- [listing]
- .....................................................................
- Combined Document Title
- =======================
- // Push titles down one level.
- :leveloffset: 1
- \include::document1.txt[]
- // Return to normal title levels.
- :leveloffset: 0
- A Top Level Section
- -------------------
- Lorum ipsum.
- // Push titles down one level.
- :leveloffset: 1
- \include::document2.txt[]
- \include::document3.txt[]
- .....................................................................
- The document titles in the included documents will now be processed as
- level 1 section titles, level 1 sections as level 2 sections and so
- on.
- - Put a blank line between the `include` macro lines to ensure the
- title of the included document is not seen as part of the last
- paragraph of the previous document.
- - You won't want non-title document header lines (for example, Author
- and Revision lines) in the included files -- conditionally exclude
- them if they are necessary for stand-alone processing.
- Processing document sections separately
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- You have divided your AsciiDoc document into separate files (one per
- top level section) which are combined and processed with the following
- top level document:
- ---------------------------------------------------------------------
- Combined Document Title
- =======================
- Joe Bloggs
- v1.0, 12-Aug-03
- \include::section1.txt[]
- \include::section2.txt[]
- \include::section3.txt[]
- ---------------------------------------------------------------------
- You also want to process the section files as separate documents.
- This is easy because asciidoc(1) will quite happily process
- `section1.txt`, `section2.txt` and `section3.txt` separately -- the
- resulting output documents contain the section but have no document
- title.
- Processing document snippets
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Use the `-s` (`--no-header-footer`) command-line option to suppress
- header and footer output, this is useful if the processed output is to
- be included in another file. For example:
- $ asciidoc -sb docbook section1.txt
- asciidoc(1) can be used as a filter, so you can pipe chunks of text
- through it. For example:
- $ echo 'Hello *World!*' | asciidoc -s -
- <div class="paragraph"><p>Hello <strong>World!</strong></p></div>
- Badges in HTML page footers
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~
- See the `[footer]` section in the AsciiDoc distribution `xhtml11.conf`
- configuration file.
- Pretty printing AsciiDoc output
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- If the indentation and layout of the asciidoc(1) output is not to your
- liking you can:
- 1. Change the indentation and layout of configuration file markup
- template sections. The `{empty}` attribute is useful for outputting
- trailing blank lines in markup templates.
- 2. Use Dave Raggett's http://tidy.sourceforge.net/[HTML Tidy] program
- to tidy asciidoc(1) output. Example:
- $ asciidoc -b docbook -o - mydoc.txt | tidy -indent -xml >mydoc.xml
- 3. Use the `xmllint(1)` format option. Example:
- $ xmllint --format mydoc.xml
- Supporting minor DocBook DTD variations
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The conditional inclusion of DocBook SGML markup at the end of the
- distribution `docbook45.conf` file illustrates how to support minor
- DTD variations. The included sections override corresponding entries
- from preceding sections.
- Creating stand-alone HTML documents
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- If you've ever tried to send someone an HTML document that includes
- stylesheets and images you'll know that it's not as straight-forward
- as exchanging a single file. AsciiDoc has options to create
- stand-alone documents containing embedded images, stylesheets and
- scripts. The following AsciiDoc command creates a single file
- containing <<X66,embedded images>>, CSS stylesheets, and JavaScript
- (for table of contents and footnotes):
- $ asciidoc -a data-uri -a icons -a toc -a max-width=55em article.txt
- You can view the HTML file here: {website}article-standalone.html[]
- Shipping stand-alone AsciiDoc source
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Reproducing presentation documents from someone else's source has one
- major problem: unless your configuration files are the same as the
- creator's you won't get the same output.
- The solution is to create a single backend specific configuration file
- using the asciidoc(1) `-c` (`--dump-conf`) command-line option. You
- then ship this file along with the AsciiDoc source document plus the
- `asciidoc.py` script. The only end user requirement is that they have
- Python installed (and that they consider you a trusted source). This
- example creates a composite HTML configuration file for `mydoc.txt`:
- $ asciidoc -cb xhtml11 mydoc.txt > mydoc-xhtml11.conf
- Ship `mydoc.txt`, `mydoc-html.conf`, and `asciidoc.py`. With
- these three files (and a Python interpreter) the recipient can
- regenerate the HMTL output:
- $ ./asciidoc.py -eb xhtml11 mydoc.txt
- The `-e` (`--no-conf`) option excludes the use of implicit
- configuration files, ensuring that only entries from the
- `mydoc-html.conf` configuration are used.
- Inserting blank space
- ~~~~~~~~~~~~~~~~~~~~~
- Adjust your style sheets to add the correct separation between block
- elements. Inserting blank paragraphs containing a single non-breaking
- space character `{nbsp}` works but is an ad hoc solution compared
- to using style sheets.
- Closing open sections
- ~~~~~~~~~~~~~~~~~~~~~
- You can close off section tags up to level `N` by calling the
- `eval::[Section.setlevel(N)]` system macro. This is useful if you
- want to include a section composed of raw markup. The following
- example includes a DocBook glossary division at the top section level
- (level 0):
- ---------------------------------------------------------------------
- \ifdef::basebackend-docbook[]
- \eval::[Section.setlevel(0)]
- +++++++++++++++++++++++++++++++
- <glossary>
- <title>Glossary</title>
- <glossdiv>
- ...
- </glossdiv>
- </glossary>
- +++++++++++++++++++++++++++++++
- \endif::basebackend-docbook[]
- ---------------------------------------------------------------------
- Validating output files
- ~~~~~~~~~~~~~~~~~~~~~~~
- Use `xmllint(1)` to check the AsciiDoc generated markup is both well
- formed and valid. Here are some examples:
- $ xmllint --nonet --noout --valid docbook-file.xml
- $ xmllint --nonet --noout --valid xhtml11-file.html
- $ xmllint --nonet --noout --valid --html html4-file.html
- The `--valid` option checks the file is valid against the document
- type's DTD, if the DTD is not installed in your system's catalog then
- it will be fetched from its Internet location. If you omit the
- `--valid` option the document will only be checked that it is well
- formed.
- The online http://validator.w3.org/#validate_by_uri+with_options[W3C
- Markup Validation Service] is the defacto standard when it comes to
- validating HTML (it validates all HTML standards including HTML5).
- :numbered!:
- [glossary]
- Glossary
- --------
- [glossary]
- [[X8]] Block element::
- An AsciiDoc block element is a document entity composed of one or
- more whole lines of text.
- [[X34]] Inline element::
- AsciiDoc inline elements occur within block element textual
- content, they perform formatting and substitution tasks.
- Formal element::
- An AsciiDoc block element that has a BlockTitle. Formal elements
- are normally listed in front or back matter, for example lists of
- tables, examples and figures.
- Verbatim element::
- The word verbatim indicates that white space and line breaks in
- the source document are to be preserved in the output document.
- [appendix]
- Migration Notes
- ---------------
- [[X53]]
- Version 7 to version 8
- ~~~~~~~~~~~~~~~~~~~~~~
- - A new set of quotes has been introduced which may match inline text
- in existing documents -- if they do you'll need to escape the
- matched text with backslashes.
- - The index entry inline macro syntax has changed -- if your documents
- include indexes you may need to edit them.
- - Replaced a2x(1) `--no-icons` and `--no-copy` options with their
- negated equivalents: `--icons` and `--copy` respectively. The
- default behavior has also changed -- the use of icons and copying of
- icon and CSS files must be specified explicitly with the `--icons`
- and `--copy` options.
- The rationale for the changes can be found in the AsciiDoc
- `CHANGELOG`.
- NOTE: If you want to disable unconstrained quotes, the new alternative
- constrained quotes syntax and the new index entry syntax then you can
- define the attribute `asciidoc7compatible` (for example by using the
- `-a asciidoc7compatible` command-line option).
- [[X38]]
- [appendix]
- Packager Notes
- --------------
- Read the `README` and `INSTALL` files (in the distribution root
- directory) for install prerequisites and procedures. The distribution
- `Makefile.in` (used by `configure` to generate the `Makefile`) is the
- canonical installation procedure.
- [[X39]]
- [appendix]
- AsciiDoc Safe Mode
- -------------------
- AsciiDoc 'safe mode' skips potentially dangerous scripted sections in
- AsciiDoc source files by inhibiting the execution of arbitrary code or
- the inclusion of arbitrary files.
- The safe mode is disabled by default, it can be enabled with the
- asciidoc(1) `--safe` command-line option.
- .Safe mode constraints
- - `eval`, `sys` and `sys2` executable attributes and block macros are
- not executed.
- - `include::<filename>[]` and `include1::<filename>[]` block macro
- files must reside inside the parent file's directory.
- - `{include:<filename>}` executable attribute files must reside
- inside the source document directory.
- - Passthrough Blocks are dropped.
- [WARNING]
- =====================================================================
- The safe mode is not designed to protect against unsafe AsciiDoc
- configuration files. Be especially careful when:
- 1. Implementing filters.
- 2. Implementing elements that don't escape special characters.
- 3. Accepting configuration files from untrusted sources.
- =====================================================================
- [appendix]
- Using AsciiDoc with non-English Languages
- -----------------------------------------
- AsciiDoc can process UTF-8 character sets but there are some things
- you need to be aware of:
- - If you are generating output documents using a DocBook toolchain
- then you should set the AsciiDoc `lang` attribute to the appropriate
- language (it defaults to `en` (English)). This will ensure things
- like table of contents, figure and table captions and admonition
- captions are output in the specified language. For example:
- $ a2x -a lang=es doc/article.txt
- - If you are outputting HTML directly from asciidoc(1) you'll
- need to set the various `*_caption` attributes to match your target
- language (see the list of captions and titles in the `[attributes]`
- section of the distribution `lang-*.conf` files). The easiest way is
- to create a language `.conf` file (see the AsciiDoc's `lang-en.conf`
- file).
- +
- NOTE: You still use the 'NOTE', 'CAUTION', 'TIP', 'WARNING',
- 'IMPORTANT' captions in the AsciiDoc source, they get translated in
- the HTML output file.
- - asciidoc(1) automatically loads configuration files named like
- `lang-<lang>.conf` where `<lang>` is a two letter language code that
- matches the current AsciiDoc `lang` attribute. See also
- <<X27,Configuration File Names and Locations>>.
- [appendix]
- Vim Syntax Highlighter
- ----------------------
- Syntax highlighting is incredibly useful, in addition to making
- reading AsciiDoc documents much easier syntax highlighting also helps
- you catch AsciiDoc syntax errors as you write your documents.
- The AsciiDoc `./vim/` distribution directory contains Vim syntax
- highlighter and filetype detection scripts for AsciiDoc. Syntax
- highlighting makes it much easier to spot AsciiDoc syntax errors.
- If Vim is installed on your system the AsciiDoc installer
- (`install.sh`) will automatically install the vim scripts in the Vim
- global configuration directory (`/etc/vim`).
- You can also turn on syntax highlighting by adding the following line
- to the end of you AsciiDoc source files:
- // vim: set syntax=asciidoc:
- TIP: Bold fonts are often easier to read, use the Vim `:set
- background=dark` command to set bold bright fonts.
- NOTE: There are a number of alternative syntax highlighters for
- various editors listed on the {website}[AsciiDoc website].
- Limitations
- ~~~~~~~~~~~
- The current implementation does a reasonable job but on occasions gets
- things wrong:
- - Nested quoted text formatting is highlighted according to the outer
- format.
- - If a closing Example Block delimiter is sometimes mistaken for a
- title underline. A workaround is to insert a blank line before the
- closing delimiter.
- - Lines within a paragraph starting with equals characters may be
- highlighted as single-line titles.
- - Lines within a paragraph beginning with a period may be highlighted
- as block titles.
- [[X74]]
- [appendix]
- Attribute Options
- -----------------
- Here is the list of predefined <<X75,attribute list options>>:
- [cols="2e,2,2,5",frame="topbot",options="header"]
- |====================================================================
- |Option|Backends|AsciiDoc Elements|Description
- |autowidth |xhtml11, html5, html4 |table|
- The column widths are determined by the browser, not the AsciiDoc
- 'cols' attribute. If there is no 'width' attribute the table width is
- also left up to the browser.
- |unbreakable |xhtml11, html5 |block elements|
- 'unbreakable' attempts to keep the block element together on a single
- printed page c.f. the 'breakable' and 'unbreakable' docbook (XSL/FO)
- options below.
- |breakable, unbreakable |docbook (XSL/FO) |table, example, block image|
- The 'breakable' options allows block elements to break across page
- boundaries; 'unbreakable' attempts to keep the block element together
- on a single page. If neither option is specified the default XSL
- stylesheet behavior prevails.
- |compact |docbook, xhtml11, html5 |bulleted list, numbered list|
- Minimizes vertical space in the list
- |footer |docbook, xhtml11, html5, html4 |table|
- The last row of the table is rendered as a footer.
- |header |docbook, xhtml11, html5, html4 |table|
- The first row of the table is rendered as a header.
- |pgwide |docbook (XSL/FO) |table, block image, horizontal labeled list|
- Specifies that the element should be rendered across the full text
- width of the page irrespective of the current indentation.
- |strong |xhtml11, html5, html4 |labeled lists|
- Emboldens label text.
- |====================================================================
- [[X82]]
- [appendix]
- Diagnostics
- -----------
- The `asciidoc(1)` `--verbose` command-line option prints additional
- information to stderr: files processed, filters processed, warnings,
- system attribute evaluation.
- A special attribute named 'trace' enables the output of
- element-by-element diagnostic messages detailing output markup
- generation to stderr. The 'trace' attribute can be set on the
- command-line or from within the document using <<X18,Attribute
- Entries>> (the latter allows tracing to be confined to specific
- portions of the document).
- - Trace messages print the source file name and line number and the
- trace name followed by related markup.
- - 'trace names' are normally the names of AsciiDoc elements (see the
- list below).
- - The trace message is only printed if the 'trace' attribute value
- matches the start of a 'trace name'. The 'trace' attribute value can
- be any Python regular expression. If a trace value is not specified
- all trace messages will be printed (this can result in large amounts
- of output if applied to the whole document).
- - In the case of inline substitutions:
- * The text before and after the substitution is printed; the before
- text is preceded by a line containing `<<<` and the after text by
- a line containing `>>>`.
- * The 'subs' trace value is an alias for all inline substitutions.
- .Trace names
- .....................................................................
- <blockname> block close
- <blockname> block open
- <subs>
- dropped line (a line containing an undefined attribute reference).
- floating title
- footer
- header
- list close
- list entry close
- list entry open
- list item close
- list item open
- list label close
- list label open
- list open
- macro block (a block macro)
- name (man page NAME section)
- paragraph
- preamble close
- preamble open
- push blockname
- pop blockname
- section close
- section open: level <level>
- subs (all inline substitutions)
- table
- .....................................................................
- Where:
- - `<level>` is section level number '0...4'.
- - `<blockname>` is a delimited block name: 'comment', 'sidebar',
- 'open', 'pass', 'listing', 'literal', 'quote', 'example'.
- - `<subs>` is an inline substitution type:
- 'specialcharacters','quotes','specialwords', 'replacements',
- 'attributes','macros','callouts', 'replacements2', 'replacements3'.
- Command-line examples:
- . Trace the entire document.
- $ asciidoc -a trace mydoc.txt
- . Trace messages whose names start with `quotes` or `macros`:
- $ asciidoc -a 'trace=quotes|macros' mydoc.txt
- . Print the first line of each trace message:
- $ asciidoc -a trace mydoc.txt 2>&1 | grep ^TRACE:
- Attribute Entry examples:
- . Begin printing all trace messages:
- :trace:
- . Print only matched trace messages:
- :trace: quotes|macros
- . Turn trace messages off:
- :trace!:
- [[X88]]
- [appendix]
- Backend Attributes
- ------------------
- This table contains a list of optional attributes that influence the
- generated outputs.
- [cols="1e,1,5a",frame="topbot",options="header"]
- |====================================================================
- |Name |Backends |Description
- |badges |xhtml11, html5 |
- Link badges ('XHTML 1.1' and 'CSS') in document footers. By default
- badges are omitted ('badges' is undefined).
- NOTE: The path names of images, icons and scripts are relative path
- names to the output document not the source document.
- |data-uri |xhtml11, html5 |
- Embed images using the <<X66,data: uri scheme>>.
- |css-signature |html5, xhtml11 |
- Set a 'CSS signature' for the document (sets the 'id' attribute of the
- HTML 'body' element). CSS signatures provide a mechanism that allows
- users to personalize the document appearance. The term 'CSS signature'
- was http://archivist.incutio.com/viewlist/css-discuss/13291[coined by
- Eric Meyer].
- |disable-javascript |xhtml11, html5 |
- If the `disable-javascript` attribute is defined the `asciidoc.js`
- JavaScript is not embedded or linked to the output document. By
- default AsciiDoc automatically embeds or links the `asciidoc.js`
- JavaScript to the output document. The script dynamically generates
- <<X91,table of contents>> and <<X92,footnotes>>.
- |[[X97]] docinfo, docinfo1, docinfo2 |All backends |
- These three attributes control which <<X87,document information
- files>> will be included in the the header of the output file:
- docinfo:: Include `<filename>-docinfo.<ext>`
- docinfo1:: Include `docinfo.<ext>`
- docinfo2:: Include `docinfo.<ext>` and `<filename>-docinfo.<ext>`
- Where `<filename>` is the file name (sans extension) of the AsciiDoc
- input file and `<ext>` is `.html` for HTML outputs or `.xml` for
- DocBook outputs. If the input file is the standard input then the
- output file name is used. The following example will include the
- `mydoc-docinfo.xml` docinfo file in the DocBook `mydoc.xml` output
- file:
- $ asciidoc -a docinfo -b docbook mydoc.txt
- This next example will include `docinfo.html` and `mydoc-docinfo.html`
- docinfo files in the HTML output file:
- $ asciidoc -a docinfo2 -b html4 mydoc.txt
- |[[X54]]encoding |html4, html5, xhtml11, docbook |
- Set the input and output document character set encoding. For example
- the `--attribute encoding=ISO-8859-1` command-line option will set the
- character set encoding to `ISO-8859-1`.
- - The default encoding is UTF-8.
- - This attribute specifies the character set in the output document.
- - The encoding name must correspond to a Python codec name or alias.
- - The 'encoding' attribute can be set using an AttributeEntry inside
- the document header. For example:
- :encoding: ISO-8859-1
- |[[X45]]icons |xhtml11, html5 |
- Link admonition paragraph and admonition block icon images and badge
- images. By default 'icons' is undefined and text is used in place of
- icon images.
- |[[X44]]iconsdir |html4, html5, xhtml11, docbook |
- The name of the directory containing linked admonition icons,
- navigation icons and the `callouts` sub-directory (the `callouts`
- sub-directory contains <<X105,callout>> number images). 'iconsdir'
- defaults to `./images/icons`.
- |imagesdir |html4, html5, xhtml11, docbook |
- If this attribute is defined it is prepended to the target image file
- name paths in inline and block image macros.
- |keywords, description, title |html4, html5, xhtml11 |
- The 'keywords' and 'description' attributes set the correspondingly
- named HTML meta tag contents; the 'title' attribute sets the HTML
- title tag contents. Their principle use is for SEO (Search Engine
- Optimisation). All three are optional, but if they are used they must
- appear in the document header (or on the command-line). If 'title' is
- not specified the AsciiDoc document title is used.
- |linkcss |html5, xhtml11 |
- Link CSS stylesheets and JavaScripts. By default 'linkcss' is
- undefined in which case stylesheets and scripts are automatically
- embedded in the output document.
- |[[X103]]max-width |html5, xhtml11 |
- Set the document maximum display width (sets the 'body' element CSS
- 'max-width' property).
- |numbered |html4, html5, xhtml11, docbook (XSL Stylesheets) |
- Adds section numbers to section titles. The 'docbook' backend ignores
- 'numbered' attribute entries after the document header.
- |plaintext | All backends |
- If this global attribute is defined all inline substitutions are
- suppressed and block indents are retained. This option is useful when
- dealing with large amounts of imported plain text.
- |quirks |xhtml11 |
- Include the `xhtml11-quirks.conf` configuration file and
- `xhtml11-quirks.css` <<X35,stylesheet>> to work around IE6 browser
- incompatibilities. This feature is deprecated and its use is
- discouraged -- documents are still viewable in IE6 without it.
- |revremark |docbook |
- A short summary of changes in this document revision. Must be defined
- prior to the first document section. The document also needs to be
- dated to output this attribute.
- |scriptsdir |html5, xhtml11 |
- The name of the directory containing linked JavaScripts.
- See <<X35,HTML stylesheets and JavaScript locations>>.
- |sgml |docbook45 |
- The `--backend=docbook45` command-line option produces DocBook 4.5
- XML. You can produce the older DocBook SGML format using the
- `--attribute sgml` command-line option.
- |stylesdir |html5, xhtml11 |
- The name of the directory containing linked or embedded
- <<X35,stylesheets>>.
- See <<X35,HTML stylesheets and JavaScript locations>>.
- |stylesheet |html5, xhtml11 |
- The file name of an optional additional CSS <<X35,stylesheet>>.
- |theme |html5, xhtml11 |
- Use alternative stylesheet (see <<X35,Stylesheets>>).
- |[[X91]]toc |html5, xhtml11, docbook (XSL Stylesheets) |
- Adds a table of contents to the start of an article or book document.
- The `toc` attribute can be specified using the `--attribute toc`
- command-line option or a `:toc:` attribute entry in the document
- header. The 'toc' attribute is defined by default when the 'docbook'
- backend is used. To disable table of contents generation undefine the
- 'toc' attribute by putting a `:toc!:` attribute entry in the document
- header or from the command-line with an `--attribute toc!` option.
- *xhtml11 and html5 backends*
- - JavaScript needs to be enabled in your browser.
- - The following example generates a numbered table of contents using a
- JavaScript embedded in the `mydoc.html` output document:
- $ asciidoc -a toc -a numbered mydoc.txt
- |toc2 |html5, xhtml11 |
- Adds a scrollable table of contents in the left hand margin of an
- article or book document. Use the 'max-width' attribute to change the
- content width. In all other respects behaves the same as the 'toc'
- attribute.
- |toc-placement |html5, xhtml11 |
- When set to 'auto' (the default value) asciidoc(1) will place the
- table of contents in the document header. When 'toc-placement' is set
- to 'manual' the TOC can be positioned anywhere in the document by
- placing the `toc::[]` block macro at the point you want the TOC to
- appear.
- NOTE: If you use 'toc-placement' then you also have to define the
- <<X91,toc>> attribute.
- |toc-title |html5, xhtml11 |
- Sets the table of contents title (defaults to 'Table of Contents').
- |toclevels |html5, xhtml11 |
- Sets the number of title levels (1..4) reported in the table of
- contents (see the 'toc' attribute above). Defaults to 2 and must be
- used with the 'toc' attribute. Example usage:
- $ asciidoc -a toc -a toclevels=3 doc/asciidoc.txt
- |====================================================================
- [appendix]
- License
- -------
- AsciiDoc is free software; you can redistribute it and/or modify it
- under the terms of the 'GNU General Public License version 2' (GPLv2)
- as published by the Free Software Foundation.
- AsciiDoc is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- General Public License version 2 for more details.
- AsciiDoc Highlighter sponsored by O'Reilly Media
- Copyright (C) 2002-2011 Stuart Rackham.
|