@c-*-texinfo-*-@cThisispartoftheGNUEmacsLispReferenceManual.@cCopyright(C)1990,1991,1992,1993FreeSoftwareFoundation,Inc.@cSeethefileelisp.texiforcopyingconditions.@setfilename../info/tips@nodeTips,GNUEmacsInternals,Calendar,Top@appendixTipsandStandards@cindextips@cindexstandardsofcodingstyle@cindexcodingstandardsThischapterdescribesnoadditionalfeaturesofEmacsLisp.Insteaditgivesadviceonmakingeffectiveuseofthefeaturesdescribedinthepreviouschapters.@menu*StyleTips::Writingcleanandrobustprograms.*CompilationTips::Makingcompiledcoderunfast.*DocumentationTips::Writingreadabledocumentationstrings.*CommentTips::Conventionsforwritingcomments.*LibraryHeaders::Standardheadersforlibrarypackages.@endmenu@nodeStyleTips@sectionWritingCleanLispProgramsHerearesometipsforavoidingcommonerrorsinwritingLispcodeintendedforwidespreaduse:@itemize@bullet@itemSinceallglobalvariablessharethesamenamespace,andallfunctionsshareanothernamespace,youshouldchooseashortwordtodistinguishyourprogramfromotherLispprograms.Thentakecaretobeginthenamesofallglobalvariables,constants,andfunctionswiththechosenprefix.Thishelpsavoidnameconflicts.ThisrecommendationapplieseventonamesfortraditionalLispprimitivesthatarenotprimitivesinEmacsLisp---evento@code{cadr}.Believeitornot,thereismorethanoneplausiblewaytodefine@code{cadr}.Playitsafe;appendyournameprefixtoproduceanamelike@code{foo-cadr}or@code{mylib-cadr}instead.IfyouwriteafunctionthatyouthinkoughttobeaddedtoEmacsunderacertainname,suchas@code{twiddle-files},don'tcallitbythatnameinyourprogram.Callit@code{mylib-twiddle-files}inyourprogram,andsendmailto@samp{bug-gnu-emacs@@prep.ai.mit.edu}suggestingweaddittoEmacs.Ifandwhenwedo,wecanchangethenameeasilyenough.Ifoneprefixisinsufficient,yourpackagemayusetwoorthreealternativecommonprefixes,solongastheymakesense.Separatetheprefixfromtherestofthesymbolnamewithahyphen,@samp{-}.ThiswillbeconsistentwithEmacsitselfandwithmostEmacsLispprograms.@itemItisoftenusefultoputacallto@code{provide}ineachseparatelibraryprogram,atleastifthereismorethanoneentrypointtotheprogram.@itemIfafilerequirescertainotherlibraryprogramstobeloadedbeforehand,thenthecommentsatthebeginningofthefileshouldsayso.Also,use@code{require}tomakesuretheyareloaded.@itemIfonefile@var{foo}usesamacrodefinedinanotherfile@var{bar},@var{foo}shouldcontainthisexpressionbeforethefirstuseofthemacro:@example(eval-when-compile(require'@var{bar}))@endexample@noindent(And@var{bar}shouldcontain@code{(provide'@var{bar})},tomakethe@code{require}work.)Thiswillcause@var{bar}tobeloadedwhenyoubyte-compile@var{foo}.Otherwise,youriskcompiling@var{foo}withoutthenecessarymacroloaded,andthatwouldproducecompiledcodethatwon'tworkright.@xref{CompilingMacros}.Using@code{eval-when-compile}avoidsloading@var{bar}whenthecompiledversionof@var{foo}is@emph{used}.@itemIfyoudefineamajormode,makesuretorunahookvariableusing@code{run-hooks},justastheexistingmajormodesdo.@xref{Hooks}.@itemIfthepurposeofafunctionistotellyouwhetheracertainconditionistrueorfalse,givethefunctionanamethatendsin@samp{p}.Ifthenameisoneword,addjust@samp{p};ifthenameismultiplewords,add@samp{-p}.Examplesare@code{framep}and@code{frame-live-p}.@itemIfauseroptionvariablerecordsatrue-or-falsecondition,giveitanamethatendsin@samp{-flag}.@itemPleasedonotdefine@kbd{C-c@var{letter}}asakeyinyourmajormodes.Thesesequencesarereservedforusers;theyarethe@strong{only}sequencesreservedforusers,sowecannotdowithoutthem.Instead,definesequencesconsistingof@kbd{C-c}followedbyacontrolcharacter,adigit,orcertainpunctuationcharacters.Thesesequencesarereservedformajormodes.ChangingallthemajormodesinEmacs18sotheywouldfollowthisconventionwasalotofwork.Abandoningthisconventionwouldmakethatworkgotowaste,andinconvenienceusers.@itemSequencesconsistingof@kbd{C-c}followedby@kbd{@{},@kbd{@}},@kbd{<},@kbd{>},@kbd{:}or@kbd{;}arealsoreservedformajormodes.@itemSequencesconsistingof@kbd{C-c}followedbyanyotherpunctuationcharacterareallocatedforminormodes.Usingtheminamajormodeisnotabsolutelyprohibited,butifyoudothat,themajormodebindingmaybeshadowedfromtimetotimebyminormodes.@itemYoushouldnotbind@kbd{C-h}followinganyprefixcharacter(including@kbd{C-c}).Ifyoudon'tbind@kbd{C-h},itisautomaticallyavailableasahelpcharacterforlistingthesubcommandsoftheprefixcharacter.@itemYoushouldnotbindakeysequenceendingin@key{ESC}exceptfollowinganother@key{ESC}.(Thatis,itisoktobindasequenceendingin@kbd{@key{ESC}@key{ESC}}.)Thereasonforthisruleisthatanon-prefixbindingfor@key{ESC}inanycontextpreventsrecognitionofescapesequencesasfunctionkeysinthatcontext.@itemApplicationsshouldnotbindmouseeventsbasedonbutton1withtheshiftkeyhelddown.Theseeventsinclude@kbd{S-mouse-1},@kbd{M-S-mouse-1},@kbd{C-S-mouse-1},andsoon.Theyarereservedforusers.@itemModesshouldredefine@kbd{mouse-2}asacommandtofollowsomesortofreferenceinthetextofabuffer,ifusersusuallywouldnotwanttoalterthetextinthatbufferbyhand.ModessuchasDired,Info,Compilation,andOccurredefineitinthisway.@itemWhenapackageprovidesamodificationofordinaryEmacsbehavior,itisgoodtoincludeacommandtoenableanddisablethefeature,Provideacommandnamed@code{@var{whatever}-mode}whichturnsthefeatureonoroff,andmakeitautoload(@pxref{Autoload}).Designthepackagesothatsimplyloadingithasnovisibleeffect---thatshouldnotenablethefeature.Userswillrequestthefeaturebyinvokingthecommand.@itemItisabadideatodefinealiasesfortheEmacsprimitives.Usethestandardnamesinstead.@itemRedefininganEmacsprimitiveisanevenworseidea.Itmaydotherightthingforaparticularprogram,butthereisnotellingwhatotherprogramsmightbreakasaresult.@itemIfafiledoesreplaceanyofthefunctionsorlibraryprogramsofstandardEmacs,prominentcommentsatthebeginningofthefileshouldsaywhichfunctionsarereplaced,andhowthebehaviorofthereplacementsdiffersfromthatoftheoriginals.@itemPleasekeepthenamesofyourEmacsLispsourcefilesto13charactersorless.Thisway,ifthefilesarecompiled,thecompiledfiles'nameswillbe14charactersorless,whichisshortenoughtofitonallkindsofUnixsystems.@itemDon'tuse@code{next-line}or@code{previous-line}inprograms;nearlyalways,@code{forward-line}ismoreconvenientaswellasmorepredictableandrobust.@xref{TextLines}.@itemDon'tcallfunctionsthatsetthemark,unlesssettingthemarkisoneoftheintendedfeaturesofyourprogram.Themarkisauser-levelfeature,soitisincorrecttochangethemarkexcepttosupplyavaluefortheuser'sbenefit.@xref{TheMark}.Inparticular,don'tusethesefunctions:@itemize@bullet@item@code{beginning-of-buffer},@code{end-of-buffer}@item@code{replace-string},@code{replace-regexp}@enditemizeIfyoujustwanttomovepoint,orreplaceacertainstring,withoutanyoftheotherfeaturesintendedforinteractiveusers,youcanreplacethesefunctionswithoneortwolinesofsimpleLispcode.@itemUselistsratherthanvectors,exceptwhenthereisaparticularreasontouseavector.Lisphasmorefacilitiesformanipulatingliststhanforvectors,andworkingwithlistsisusuallymoreconvenient.Vectorsareadvantageousfortablesthataresubstantialinsizeandareaccessedinrandomorder(notsearchedfronttoback),providedthereisnoneedtoinsertordeleteelements(onlylistsallowthat).@itemTherecommendedwaytoprintamessageintheechoareaiswiththe@code{message}function,not@code{princ}.@xref{TheEchoArea}.@itemWhenyouencounteranerrorcondition,callthefunction@code{error}(or@code{signal}).Thefunction@code{error}doesnotreturn.@xref{SignalingErrors}.Donotuse@code{message},@code{throw},@code{sleep-for},or@code{beep}toreporterrors.@itemAnerrormessageshouldstartwithacapitalletterbutshouldnotendwithaperiod.@itemManycommandsthattakealongtimetoexecutedisplayamessagethatsays@samp{Operating...}whentheystart,andchangeitto@samp{Operating...done}whentheyfinish.Pleasekeepthestyleofthesemessagesuniform:@emph{no}spacearoundtheellipsis,and@emph{no}periodattheend.@itemTrytoavoidusingrecursiveedits.Instead,dowhattheRmail@kbd{e}commanddoes:useanewlocalkeymapthatcontainsonecommanddefinedtoswitchbacktotheoldlocalkeymap.Ordowhatthe@code{edit-options}commanddoes:switchtoanotherbufferandlettheuserswitchbackatwill.@xref{RecursiveEditing}.@itemInsomeothersystemsthereisaconventionofchoosingvariablenamesthatbeginandendwith@samp{*}.Wedon'tusethatconventioninEmacsLisp,sopleasedon'tuseitinyourprograms.(Emacsusessuchnamesonlyforprogram-generatedbuffers.)TheuserswillfindEmacsmorecoherentifalllibrariesusethesameconventions.@itemTrytoavoidcompilerwarningsaboutundefinedfreevariables,byadding@code{defvar}definitionsforthesevariables.Ifyoubindavariableinonefunction,anduseitorsetitinanotherfunction,thecompilerwarnsaboutthelatterfunctionunlessthevariablehasadefinition.Butoftenthesevariableshaveshortnames,anditisnotcleanforLisppackagestodefinesuchvariablesnames.Therefore,youshouldrenamethevariabletostartwiththenameprefixusedfortheotherfunctionsandvariablesinyourpackage.@itemIndenteachfunctionwith@kbd{C-M-q}(@code{indent-sexp})usingthedefaultindentationparameters.@itemDon'tmakeahabitofputtingclose-parenthesesonlinesbythemselves;Lispprogrammersfindthisdisconcerting.Onceinawhile,whenthereisasequenceofmanyconsecutiveclose-parentheses,itmaymakesensetosplittheminoneortwosignificantplaces.@itemPleaseputacopyrightnoticeonthefileifyougivecopiestoanyone.UsethesamelinesthatappearatthetopoftheLispfilesinEmacsitself.IfyouhavenotsignedpaperstoassignthecopyrighttotheFoundation,thenplaceyournameinthecopyrightnoticeinplaceoftheFoundation'sname.@enditemize@nodeCompilationTips@sectionTipsforMakingCompiledCodeFast@cindexexecutionspeed@cindexspeedupsHerearewaysofimprovingtheexecutionspeedofbyte-compiledLispprograms.@itemize@bullet@item@cindexprofiling@cindextimingprograms@cindex@file{profile.el}Usethe@file{profile}librarytoprofileyourprogram.Seethefile@file{profile.el}forinstructions.@itemUseiterationratherthanrecursionwheneverpossible.FunctioncallsareslowinEmacsLispevenwhenacompiledfunctioniscallinganothercompiledfunction.@itemUsingtheprimitivelist-searchingfunctions@code{memq},@code{member},@code{assq},or@code{assoc}isevenfasterthanexplicititeration.Itmaybeworthrearrangingadatastructuresothatoneoftheseprimitivesearchfunctionscanbeused.@itemCertainbuilt-infunctionsarehandledspeciallyinbyte-compiledcode,avoidingtheneedforanordinaryfunctioncall.Itisagoodideatousethesefunctionsratherthanalternatives.Toseewhetherafunctionishandledspeciallybythecompiler,examineits@code{byte-compile}property.Ifthepropertyisnon-@code{nil},thenthefunctionishandledspecially.Forexample,thefollowinginputwillshowyouthat@code{aref}iscompiledspecially(@pxref{ArrayFunctions})while@code{elt}isnot(@pxref{SequenceFunctions}):@example@group(get'aref'byte-compile)@result{}byte-compile-two-args@endgroup@group(get'elt'byte-compile)@result{}nil@endgroup@endexample@itemIfcallingasmallfunctionaccountsforasubstantialpartofyourprogram'srunningtime,makethefunctioninline.Thiseliminatesthefunctioncalloverhead.Sincemakingafunctioninlinereducestheflexibilityofchangingtheprogram,don'tdoitunlessitgivesanoticeablespeedupinsomethingslowenoughthatuserscareaboutthespeed.@xref{InlineFunctions}.@enditemize@nodeDocumentationTips@sectionTipsforDocumentationStringsHerearesometipsforthewritingofdocumentationstrings.@itemize@bullet@itemEverycommand,function,orvariableintendedforuserstoknowaboutshouldhaveadocumentationstring.@itemAninternalvariableorsubroutineofaLispprogrammightaswellhaveadocumentationstring.InearlierEmacsversions,youcouldsavespacebyusingacommentinsteadofadocumentationstring,butthatisnolongerthecase.@itemThefirstlineofthedocumentationstringshouldconsistofoneortwocompletesentencesthatstandontheirownasasummary.@kbd{M-xapropos}displaysjustthefirstline,andifitdoesn'tstandonitsown,theresultlooksbad.Inparticular,startthefirstlinewithacapitalletterandendwithaperiod.Thedocumentationstringcanhaveadditionallinesthatexpandonthedetailsofhowtousethefunctionorvariable.Theadditionallinesshouldbemadeupofcompletesentencesalso,buttheymaybefilledifthatlooksgood.@itemForconsistency,phrasetheverbinthefirstsentenceofadocumentationstringasaninfinitivewith``to''omitted.Forinstance,use``ReturntheconsofAandB.''inpreferenceto``ReturnstheconsofAandB@.''Usuallyitlooksgoodtodolikewisefortherestofthefirstparagraph.Subsequentparagraphsusuallylookbetteriftheyhavepropersubjects.@itemWritedocumentationstringsintheactivevoice,notthepassive,andinthepresenttense,notthefuture.Forinstance,use``ReturnalistcontainingAandB.''insteadof``AlistcontainingAandBwillbereturned.''@itemAvoidusingtheword``cause''(oritsequivalents)unnecessarily.Insteadof,``CauseEmacstodisplaytextinboldface,''writejust``Displaytextinboldface.''@itemDonotstartorendadocumentationstringwithwhitespace.@itemFormatthedocumentationstringsothatitfitsinanEmacswindowonan80-columnscreen.Itisagoodideaformostlinestobenowiderthan60characters.Thefirstlinecanbewiderifnecessarytofittheinformationthatoughttobethere.However,ratherthansimplyfillingtheentiredocumentationstring,youcanmakeitmuchmorereadablebychoosinglinebreakswithcare.Useblanklinesbetweentopicsifthedocumentationstringislong.@item@strong{Donot}indentsubsequentlinesofadocumentationstringsothatthetextislinedupinthesourcecodewiththetextofthefirstline.Thislooksniceinthesourcecode,butlooksbizarrewhenusersviewthedocumentation.Rememberthattheindentationbeforethestartingdouble-quoteisnotpartofthestring!@itemAvariable'sdocumentationstringshouldstartwith@samp{*}ifthevariableisonethatuserswouldoftenwanttosetinteractively.Ifthevalueisalonglist,orafunction,orifthevariablewouldbesetonlyininitfiles,thendon'tstartthedocumentationstringwith@samp{*}.@xref{DefiningVariables}.@itemThedocumentationstringforavariablethatisayes-or-noflagshouldstartwithwordssuchas``Non-nilmeans@dots{}'',tomakeitclearthatallnon-@code{nil}valuesareequivalentandindicateexplicitlywhat@code{nil}andnon-@code{nil}mean.@itemWhenafunction'sdocumentationstringmentionsthevalueofanargumentofthefunction,usetheargumentnameincapitallettersasifitwereanameforthatvalue.Thus,thedocumentationstringofthefunction@code{/}referstoitssecondargumentas@samp{DIVISOR},becausetheactualargumentnameis@code{divisor}.Alsouseallcapsformeta-syntacticvariables,suchaswhenyoushowthedecompositionofalistorvectorintosubunits,someofwhichmayvary.@item@iftexWhenadocumentationstringreferstoaLispsymbol,writeitasitwouldbeprinted(whichusuallymeansinlowercase),withsingle-quotesaroundit.Forexample:@samp{`lambda'}.Therearetwoexceptions:write@code{t}and@code{nil}withoutsingle-quotes.@endiftex@ifinfoWhenadocumentationstringreferstoaLispsymbol,writeitasitwouldbeprinted(whichusuallymeansinlowercase),withsingle-quotesaroundit.Forexample:@samp{lambda}.Therearetwoexceptions:writetandnilwithoutsingle-quotes.(Inthismanual,wenormallydousesingle-quotesforthosesymbols.)@endifinfo@itemDon'twritekeysequencesdirectlyindocumentationstrings.Instead,usethe@samp{\\[@dots{}]}constructtostandforthem.Forexample,insteadofwriting@samp{C-f},write@samp{\\[forward-char]}.WhenEmacsdisplaysthedocumentationstring,itsubstituteswhateverkeyiscurrentlyboundto@code{forward-char}.(Thisisnormally@samp{C-f},butitmaybesomeothercharacteriftheuserhasmovedkeybindings.)@xref{KeysinDocumentation}.@itemIndocumentationstringsforamajormode,youwillwanttorefertothekeybindingsofthatmode'slocalmap,ratherthanglobalones.Therefore,usetheconstruct@samp{\\<@dots{}>}onceinthedocumentationstringtospecifywhichkeymaptouse.Dothisbeforethefirstuseof@samp{\\[@dots{}]}.Thetextinsidethe@samp{\\<@dots{}>}shouldbethenameofthevariablecontainingthelocalkeymapforthemajormode.Itisnotpracticaltouse@samp{\\[@dots{}]}verymanytimes,becausedisplayofthedocumentationstringwillbecomeslow.Sousethistodescribethemostimportantcommandsinyourmajormode,andthenuse@samp{\\@{@dots{}@}}todisplaytherestofthemode'skeymap.@enditemize@nodeCommentTips@sectionTipsonWritingCommentsWerecommendtheseconventionsforwheretoputcommentsandhowtoindentthem:@table@samp@item;Commentsthatstartwithasinglesemicolon,@samp{;},shouldallbealignedtothesamecolumnontherightofthesourcecode.Suchcommentsusuallyexplainhowthecodeonthesamelinedoesitsjob.InLispmodeandrelatedmodes,the@kbd{M-;}(@code{indent-for-comment})commandautomaticallyinsertssucha@samp{;}intherightplace,oralignssuchacommentifitisalreadypresent.ThisandfollowingexamplesaretakenfromtheEmacssources.@smallexample@group(setqbase-version-list;therewasabase(assoc(substringfn0start-vn);versiontowhichfile-version-assoc-list));thislookslike;asubversion@endgroup@endsmallexample@item;;Commentsthatstartwithtwosemicolons,@samp{;;},shouldbealignedtothesamelevelofindentationasthecode.Suchcommentsusuallydescribethepurposeofthefollowinglinesorthestateoftheprogramatthatpoint.Forexample:@smallexample@group(prog1(setqauto-fill-function@dots{}@dots{};;updatemodeline(force-mode-line-update)))@endgroup@endsmallexampleEveryfunctionthathasnodocumentationstring(becauseitisuseonlyinternallywithinthepackageitbelongsto),shouldhaveinsteadatwo-semicoloncommentrightbeforethefunction,explainingwhatthefunctiondoesandhowtocallitproperly.Explainpreciselywhateachargumentmeansandhowthefunctioninterpretsitspossiblevalues.@item;;;Commentsthatstartwiththreesemicolons,@samp{;;;},shouldstartattheleftmargin.Suchcommentsareusedoutsidefunctiondefinitionstomakegeneralstatementsexplainingthedesignprinciplesoftheprogram.Forexample:@smallexample@group;;;ThisLispcodeisruninEmacs;;;whenitistooperateasaserver;;;forotherprocesses.@endgroup@endsmallexampleAnotherusefortriple-semicoloncommentsisforcommentingoutlineswithinafunction.Weusetriple-semicolonsforthispreciselysothattheyremainattheleftmargin.@smallexample(defunfoo(a);;;Thisisnolongernecessary.;;;(force-mode-line-update)(message"Finished with %s"a))@endsmallexample@item;;;;Commentsthatstartwithfoursemicolons,@samp{;;;;},shouldbealignedtotheleftmarginandareusedforheadingsofmajorsectionsofaprogram.Forexample:@smallexample;;;;Thekillring@endsmallexample@endtable@noindentTheindentationcommandsoftheLispmodesinEmacs,suchas@kbd{M-;}(@code{indent-for-comment})and@key{TAB}(@code{lisp-indent-line})automaticallyindentcommentsaccordingtotheseconventions,dependingonthenumberofsemicolons.@xref{Comments,,ManipulatingComments,emacs,TheGNUEmacsManual}.@nodeLibraryHeaders@sectionConventionalHeadersforEmacsLibraries@cindexheadercomments@cindexlibraryheadercommentsEmacs19hasconventionsforusingspecialcommentsinLisplibrariestodividethemintosectionsandgiveinformationsuchaswhowrotethem.Thissectionexplainstheseconventions.First,anexample:@smallexample@group;;;lisp-mnt.el---minormodeforEmacsLispmaintainers;;Copyright(C)1992FreeSoftwareFoundation,Inc.@endgroup;;Author:EricS.Raymond<esr@@snark.thyrsus.com>;;Maintainer:EricS.Raymond<esr@@snark.thyrsus.com>;;Created:14Jul1992;;Version:1.2@group;;Keywords:docs;;ThisfileispartofGNUEmacs.@var{copyingpermissions}@dots{}@endgroup@endsmallexampleTheveryfirstlineshouldhavethisformat:@example;;;@var{filename}---@var{description}@endexample@noindentThedescriptionshouldbecompleteinoneline.Afterthecopyrightnoticecomeseveral@dfn{headercomment}lines,eachbeginningwith@samp{;;@var{header-name}:}.Hereisatableoftheconventionalpossibilitiesfor@var{header-name}:@table@samp@itemAuthorThislinestatesthenameandnetaddressofatleasttheprincipalauthorofthelibrary.Iftherearemultipleauthors,youcanlistthemoncontinuationlinesledby@code{;;}andatabcharacter,likethis:@smallexample@group;;Author:AshwinRam<Ram-Ashwin@@cs.yale.edu>;;DaveSill<de5@@ornl.gov>;;DaveBrennan<brennan@@hal.com>;;EricRaymond<esr@@snark.thyrsus.com>@endgroup@endsmallexample@itemMaintainerThislineshouldcontainasinglename/addressasintheAuthorline,oranaddressonly,orthestring@samp{FSF}.Ifthereisnomaintainerline,theperson(s)intheAuthorfieldarepresumedtobethemaintainers.Theexampleaboveismildlybogusbecausethemaintainerlineisredundant.Theideabehindthe@samp{Author}and@samp{Maintainer}linesistomakepossibleaLispfunctionto``sendmailtothemaintainer''withouthavingtominethenameoutbyhand.Besuretosurroundthenetworkaddresswith@samp{<@dots{}>}ifyouincludetheperson'sfullnameaswellasthenetworkaddress.@itemCreatedThisoptionallinegivestheoriginalcreationdateofthefile.Forhistoricalinterestonly.@itemVersionIfyouwishtorecordversionnumbersfortheindividualLispprogram,puttheminthisline.@itemAdapted-ByInthisheaderline,placethenameofthepersonwhoadaptedthelibraryforinstallation(tomakeitfitthestyleconventions,forexample).@itemKeywordsThislinelistskeywordsforthe@code{finder-by-keyword}helpcommand.Thisfieldisimportant;it'showpeoplewillfindyourpackagewhenthey'relookingforthingsbytopicarea.Toseparatethekeywords,youcanusespaces,commas,orboth.@endtableJustabouteveryLisplibraryoughttohavethe@samp{Author}and@samp{Keywords}headercommentlines.Usetheothersiftheyareappropriate.Youcanalsoputinheaderlineswithotherheadernames---theyhavenostandardmeanings,sotheycan'tdoanyharm.Weuseadditionalstylizedcommentstosubdividethecontentsofthelibraryfile.Hereisatableofthem:@table@samp@item;;;Commentary:Thisbeginsintroductorycommentsthatexplainhowthelibraryworks.Itshouldcomerightafterthecopyingpermissions.@item;;;Changelog:Thisbeginschangeloginformationstoredinthelibraryfile(ifyoustorethechangehistorythere).FormostoftheLispfilesdistributedwithEmacs,thechangehistoryiskeptinthefile@file{ChangeLog}andnotinthesourcefileatall;thesefilesdonothavea@samp{;;;Changelog:}line.@item;;;Code:Thisbeginstheactualcodeoftheprogram.@item;;;@var{filename}endshereThisisthe@dfn{footerline};itappearsattheveryendofthefile.Itspurposeistoenablepeopletodetecttruncatedversionsofthefilefromthelackofafooterline.@endtable