m Ec@sdkZdkZdkZdkZdkZdkZdkZdklZdk l Z l Z dk l Z lZdkZdkZdkZdkZdkZdklZdZdZdZdZd Zd Zd Zd Zd ZdZdZ dZ!dZ"dZ#dZ$dZ%dZ&dZ'dZ(dZ)dZ*dZ+dZ,dZ-dZ.dZ/dZ0d Z1d!Z2dd"Z4e4d#Z5d$Z6d%Z7he4d&Z8dS('N(s copyright(shtmlizerstext(smicrodoms domhelpers(sInsensitiveDictcCs>ddddg}x%ti|dD]}|id}ti|d|joq%n|iddd joq%n|iddid d joq%n|i d p||i d  i d oet i i |\}}d |jo"|d |id dd}n|}|id||q%q%WdS(s  Rewrite links to XHTML lore input documents so they point to lore XHTML output documents. Any node with an C{href} attribute which does not contain a value starting with C{http}, C{https}, C{ftp}, or C{mailto} and which does not have a C{class} attribute of C{absolute} or which contains C{listing} and which does point to an URL ending with C{html} will have that attribute value rewritten so that the filename extension is C{ext} instead of C{html}. @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @type ext: C{str} @param ext: The extension to use when selecting an output file name. This replaces the extension of the input file name. @return: C{None} thttpthttpstftptmailtothrefitclassttabsolutetlistingithtmlt#iN(tsupported_schemest domhelperstfindElementsWithAttributetdocumenttnodet getAttributeRturlparsetfindtendswithtrfindtostpathtsplitexttfnametfexttexttsplitt setAttribute(RRRR RRR((ti/home/radix/Projects/Twisted/branches/releases/twisted-core-2.5.x-2329-2/Twisted.exp/twisted/lore/tree.pytfixLinks s""- "cCsOxHti|ddD]1}|ititit i i |qWdS(sN Set the last modified time of the given document. @type document: A DOM Node or Document @param document: The output template which defines the presentation of the last modified time. @type fullpath: C{str} @param fullpath: The file name from which to take the last modified time. @return: C{None} RtmtimeN( R R RRt appendChildtmicrodomtTextttimetctimeRRtgetmtimetfullpath(RR&R((RtaddMtime7s cCs?d}|ido|idd}n||idiS(s Retrieve the fully qualified Python name represented by the given node. The name is represented by one or two aspects of the node: the value of the node's first child forms the end of the name. If the node has a C{base} attribute, that attribute's value is prepended to the node's value, with C{.} separating the two parts. @rtype: C{str} @return: The fully qualified Python name. Rtbaset.iN(R(Rt hasAttributeRt childNodest nodeValue(RR(((Rt_getAPIIs cCs}xvti|ddD]_}t|}tidhd||<d|<}|i |_ |g|_ |i dqWdS(s Replace API references with links to API documentation. @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @type url: C{str} @param url: A string which will be interpolated with the fully qualified Python name of any API reference encountered in the input document, the result of which will be used as a link to API documentation for that name in the output document. @return: C{None} RtAPItaRttitleR(N( R R RRR-tfullnameR!tElementturltnode2R+tremoveAttribute(RR3RR4R1((RtfixAPI\s (  cCs4d}x$ti||D]}t|qWdS(s Syntax color any node in the given document which contains a Python source listing. @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @return: C{None} cCs3|idjo#|ido|iddjS(NtpreRtpython(RtnodeNameR*R(R((RtmatchersN(R:R t findElementsRRtfontifyPythonNode(RRR:((Rt fontifyPythonvs  cCsti}ti||idhdd<dd<dd<ti|iid}ti}t i ||d t i |i d ti|i}|id d |ii||d S(sZ Syntax color the given node containing Python source code. @return: C{None} tentitiestltttampt&s twriteriRR8N(t cStringIOtStringIOtoldiotlatext getLatexTextRtwritetgetvaluetstriptnewiothtmlizertfiltertSmallerHTMLWritertseekR!tparsetdocumentElementtnewelRt parentNodet replaceChild(RRURHRN((RR<s %  cCsxti|ddD]}|id}ti}t t i t t ii||i}di|t|idd}titi|}ti||dti|i}t|||dqWdS( s Insert Python source listings into the given document from files in the given directory based on C{py-listing} nodes. Any node in C{document} with a C{class} attribute set to C{py-listing} will have source lines taken from the file named in that node's C{href} attribute (searched for in C{dir}) inserted in place of that node. If a node has a C{skipLines} attribute, its value will be parsed as an integer and that many lines will be skipped at the beginning of the source file. @type document: A DOM Node or Document @param document: The document within which to make listing replacements. @type dir: C{str} @param dir: The directory in which to find source files containing the referenced Python listings. @return: C{None} Rs py-listingRs t skipLinesiREN(R R RRRtfilenameRFRGtoutfiletmaptstringtrstriptopenRRtjointdirt readlinestlinestinttdatattexttremoveLeadingTrailingBlanksRORPRQRLtvalt_replaceWithListing(RR`RRgRbRYRZRd((Rt addPyListingss -% cCstti|}|tii|jo d}nd|||||f}t i |i }|ii||dS(NsSource listingsi
%s
%s - %s
(R t getNodeTextRt captionTitleRRtbasenameRYtclass_RgReR!t parseStringRTtnewnodeRVRW(RRgRYRmReRkRo((RRhs  cCstxmti|ddD]V}|id}dtitt i i ||i }t|||dqWdS(ss Insert HTML source listings into the given document from files in the given directory based on C{html-listing} nodes. Any node in C{document} with a C{class} attribute set to C{html-listing} will have source lines taken from the file named in that node's C{href} attribute (searched for in C{dir}) inserted in place of that node. @type document: A DOM Node or Document @param document: The document within which to make listing replacements. @type dir: C{str} @param dir: The directory in which to find source files containing the referenced HTML listings. @return: C{None} Rs html-listingRs!
%s
N(R R RRRRYtcgitescapeR^RRR_R`treadRgRh(RR`RRgRY((RtaddHTMLListingss.cCstxmti|ddD]V}|id}dtitt i i ||i }t|||dqWdS(sb Insert text listings into the given document from files in the given directory based on C{listing} nodes. Any node in C{document} with a C{class} attribute set to C{listing} will have source lines taken from the file named in that node's C{href} attribute (searched for in C{dir}) inserted in place of that node. @type document: A DOM Node or Document @param document: The document within which to make listing replacements. @type dir: C{str} @param dir: The directory in which to find source files containing the referenced text listings. @return: C{None} RRRs
%s
N(R R RRRRYRpRqR^RRR_R`RrRgRh(RR`RRgRY((RtaddPlainListingss.cCs"ti|tididS(s| Return all H2 and H3 nodes in the given document. @type document: A DOM Node or Document @rtype: C{list} sh[23]$cCs ||iS(N(tmtnR9(RvRu((Rt sN(R R;Rtretcompiletmatch(R((Rt getHeaderss cCsd \}}}xt|D]}t|idd}|||d7}|||d7}|d|7}|t i |7}|d7}|}t i d |i }|ii||d7}qW|d|7}|d 7}t i |i S( s Create a table of contents for the given document. @type document: A DOM Node or Document @rtype: A DOM Node @return: a Node containing a table of contents based on the headers of the given document. s
    iiis s
N(s
    ii(ttoctleveltidR{RtelementRcttagNamet elementLevelR RjR!RnRTtanchorR+tappend(RR}RRRR|R~((Rt generateToCs"    cCs:ti|dd}|o|d}|g|_ndS(s Insert the given table of contents into the given document. The node with C{class} attribute set to C{toc} has its children replaced with C{toc}. @type document: A DOM Node or Document @type toc: A DOM Node RR|iN(R R RttocOrigR|R+(RR|R((RtputInToC+s  cCsIti|d}tid}x!|D]}|ii ||q(WdS(s Replace all C{h1} nodes in the given document with empty C{span} nodes. C{h1} nodes mark up document sections and the output template is given an opportunity to present this information in a different way. @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @return: C{None} th1tspanN( R tfindNodesNamedRRR!R2temptyRRVRW(RRRR((RtremoveH1<s c CsSti|dd} | pdSntid}d} x| D]}ti dt i }di ti|i}|id|tid d hd d | <}|g|_tid }|g|_|ii||ii||| d7} q@Wti|dd}ti di }|ii||ii|dS(s Find footnotes in the given document, move them to the end of the body, and generate links to them. A footnote is any node with a C{class} attribute set to C{footnote}. Footnote links are generated as superscript. Footnotes are collected in a C{ol} node at the end of the document. @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @return: C{None} RtfootnoteNtolis4%(id)dt R0R/t attributestnames footnote-%dtlitbodyis

    Footnotes

    (R R Rt footnotesR!R2tfootnoteElementR~RRntvarsRTRR_RjRReRttargetR+tfootnoteContentRRVRWRRtheader( RRRRRReRRRRR~((RRPs.  "  cCsOti|dd}tidi}x!|D]}|i i d|q.WdS(s Find notes in the given document and mark them up as such. A note is any node with a C{class} attribute set to C{note}. (I think this is a very stupid feature. When I found it I actually exclaimed out loud. -exarkun) @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @return: C{None} RtnotesNote: iN( R R RtnotesR!RnRTt notePrefixRR+tinsert(RRRR((RRys cCs;t|d|d}|o|Snt|d|dS(sj Perform in every way identically to L{cmp} for valid inputs. XXX - replace this with L{cmp} iiN(tcmpR/tbtlinecmp(R/RR((RtcompareMarkPoss cCst|i|iS(sB Compare the two elements given by their position in the document or documents they were parsed from. @type firstElement: C{twisted.web.microdom.Element} @type secondElement: C{twisted.web.microdom.Element} @return: C{-1}, C{0}, or C{1}, with the same meanings as the return value of L{cmp}. N(Rt firstElementt_markpost secondElement(RR((RtcomparePositions cCs?d}x2|D]*}t||djo|Sn|}q W|S(s Find the node in C{nodes} which appeared immediately before C{target} in the input document. @type target: L{twisted.web.microdom.Element} @type nodes: C{list} of L{twisted.web.microdom.Element} @return: An element from C{nodes} iN(tNonetresulttnodesRRR(RRRR((RtfindNodeJustBefores cCsOxHti|dD]3}ti|d}t|djo|SqqWgS(s Visit the ancestors of C{entry} until one with at least one C{h2} child node is found, then return all of that node's C{h2} child nodes. @type entry: A DOM Node @param entry: The node from which to begin traversal. This node itself is excluded from consideration. @rtype: C{list} of DOM Nodes @return: All C{h2} nodes of the ultimately selected parent node. ith2iN(R t getParentstentryR/Rtheaderstlen(RR/R((Rt!getFirstAncestorWithSectionHeaders  cCs#|pdSn|idiiS(s Retrieve the section number of the given node. @type header: A DOM Node or L{None} @param header: The section from which to extract a number. The section number is the value of this node's first child. @return: C{None} or a C{str} giving the section number. iN(RRR+tvalueRM(R((RtgetSectionNumbers cCs%t|}t||}t|S(s Find the section number which contains the given node. This function looks at the given node's ancestry until it finds a node which defines a section, then returns that section's number. @type entry: A DOM Node @param entry: The node for which to determine the section. @rtype: C{str} @return: The section number, as returned by C{getSectionNumber} of the first ancestor of C{entry} which defines a section, as determined by L{getFirstAncestorWithSectionHeader}. N(RRRRtmyHeaderR(RRR((RtgetSectionReferences cCsti|dd}|pdSnd}x|D]}|d7}d|}|ot|p|}nd}t i |||i d|d |_|_|_thd |<|_ q1WdS( s Extract index entries from the given document and store them for later use and insert named anchors so that the index can link back to those entries. Any node with a C{class} attribute set to C{index} is considered an index entry. @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @type filename: C{str} @param filename: A link to the output for the given document which will be included in the index to link to any index entry found here. @type chapterReference: ??? @param chapterReference: ??? @return: C{None} RtindexNiis index%02dtlinkRR/R(R R RtentriestiRRtchapterReferenceRtreftindexertaddEntryRYRR9Rt endTagNametInsensitiveDict(RRYRRRRRR((RRs  cCsh|pdSnti|dd}x=|D]5}d|_|_|_t hd|<|_ q+WdS(s Insert a link to an index document. Any node with a C{class} attribute set to C{index-link} will have its tag name changed to C{a} and its C{href} attribute set to C{indexFilename}. @type template: A DOM Node or Document @param template: The output template which defines the presentation of the version information. @type indexFilename: C{str} @param indexFilename: The address of the index document to which to link. If any C{False} value, this function will do nothing. @return: C{None} NRs index-linkR/R( t indexFilenameR R ttemplatet indexLinksRR9RRRR(RRRR((Rt setIndexLinkscCsWd}xJti|dD]6}tid||fg|i|_|d7}qWdS(s Number the sections of the given document. A dot-separated chapter, section number is added to the beginning of each section, as defined by C{h2} nodes. @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @type chapterNumber: C{int} @param chapterNumber: The chapter number of this content in an overall document. @return: C{None} iRs%s.%d N( RR RRRR!R"t chapterNumberR+(RRRR((RtnumberDocument7s &cCsx}dD]u}xlti||D]X}|i|}|id o2|id o!|i|||i|q q WqWdS(sy Replace relative links in C{str} and C{href} attributes with links relative to C{linkrel}. @type document: A DOM Node or Document @param document: The output template. @type linkrel: C{str} @param linkrel: An prefix to apply to all relative links in C{src} or C{href} attributes in the input document when generating the output document. tsrcRRt/N(Rshref( tattrR R RRRRt startswithRtlinkrel(RRRRR((RtfixRelativeLinksOs "cCsxti|dti|ddfD]^}|oQtio,|o%|dii t i d|n|dii |q(q(WdS(s Add title and chapter number information to the template document. The title is added to the end of the first C{title} tag and the end of the first tag with a C{class} attribute set to C{title}. If specified, the chapter is inserted before the title. @type template: A DOM Node or Document @param template: The output template which defines the presentation of the version information. @type title: C{list} of DOM Nodes @param title: Nodes from the input document defining its title. @type chapterNumber: C{int} @param chapterNumber: The chapter number of this content in an overall document. If not applicable, any C{False} value will result in this information being omitted. @return: C{None} R0Ris%s. N(R RRR tnodeListtnumberertgetNumberSectionsRR+RR!R"textendR0(RR0RR((RtsetTitleds %c Cs6d}xx|D]p\}}d||f} ||f|djo/t|djo | }q}|d| 7}q || d7}q Wtid|di}x-t i |d d D]}|ii |qWt i|d d }g}|D]-\}}|tid ||fid q~}|ii |dS(s" Add author information to the template document. Names and contact information for authors are added to each node with a C{class} attribute set to C{authors} and to the template head as C{link} nodes. @type template: A DOM Node or Document @param template: The output template which defines the presentation of the version information. @type authors: C{list} of two-tuples of C{str} @param authors: List of names and contact information for the authors of the input document. @return: C{None} Rs%siisand t,ssRtauthorstheadis)N(ReRRRRRR!RnR+R R RRRRRt_[1]( RRRRRRReRR+R((Rt setAuthorss$    AcCs:x3ti|ddD]}|iti|qWdS(s< Add a version indicator to the given template. @type template: A DOM Node or Document @param template: The output template which defines the presentation of the version information. @type version: C{str} @param version: The version string to add to the template. @return: C{None} RtversionN(R R RRR R!R"R(RRR((Rt setVersions cCstii|d|S(s Return a filename which is the same as C{originalFileName} except for the extension, which is replaced with C{outputExtension}. For example, if C{originalFileName} is C{'/foo/bar.baz'} and C{outputExtension} is C{'quux'}, the return value will be C{'/foo/bar.quux'}. @type originalFileName: C{str} @type outputExtension: C{stR} @param index: ignored, never passed. @rtype: C{str} iN(RRRtoriginalFileNametoutputExtension(RRR((RtgetOutputFileNames c Cs2t||t||t||idt pt ||nt |t ||t||t||t||t|t|t|t|t|tit||iddti|} ti|ddi } t"|| | t#i$o| ot%|| nt&||t(i)i*|d|ti+|ti|d} g}| D]H} | i/ddd jo)|| i/dd| i/d dfqq~} t0|| ti|d d} ti2|d d d}| i |_ |i4d d dS(s/ Mutate C{template} until it resembles C{document}. @type document: A DOM Node or Document @param document: The input document which contains all of the content to be presented. @type template: A DOM Node or Document @param template: The template document which defines the desired presentation format of the content. @type linkrel: C{str} @param linkrel: An prefix to apply to all relative links in C{src} or C{href} attributes in the input document when generating the output document. @type dir: C{str} @param dir: The directory in which to search for source listing files. @type fullpath: C{str} @param fullpath: The file name which contained the input document. @type ext: C{str} @param ext: The extension to use when selecting an output file name. This replaces the extension of the input file name. @type url: C{str} @param url: A string which will be interpolated with the fully qualified Python name of any API reference encountered in the input document, the result of which will be used as a link to API documentation for that name in the output document. @type config: C{dict} @param config: Further specification of the desired form of the output. Valid keys in this dictionary:: noapi: If present and set to a True value, links to API documentation will not be generated. version: A string which will be included in the output to indicate the version of this documentation. @type outfileGenerator: Callable of C{str}, C{str} returning C{str} @param outfileGenerator: Output filename factory. This is invoked with the intput filename and C{ext} and the output document is serialized to the file with the name returned. @return: C{None} tnoapiRRR0iiRtreltauthorRRRtcontentN(5RRRR'R&RRtconfigtgettFalseR6R3R=RRRiR`RsRtRRRRRRtgetIndexFilenameRthtmlbookt getNumberRR RR+R0RRRRRtoutfileGeneratorRRRt getReferenceRRRRRRR ttmplbodyR(RRRR`R&RR3RRRR0RRRRR((Rtmunges>1          "\    cCsytit|SWntij oS}tid|i|i |i |i fd|i |i |i |i fnptij o.}tid|i|i|ifn4tj o'}ti|id|dnXdS(sp Parse and return the contents of the given lore XHTML document. @type filename: C{str} @param filename: The name of a file containing a lore XHTML document to load. @raise process.ProcessingFailure: When the contents of the specified file cannot be parsed. @rtype: A DOM Document @return: The document contained in C{filename}. s'%s:%s: begin mismatched tags <%s>/s%%s:%s: end mismatched tags <%s>/s%s:%s:%ss, filename was 't'N(R!RSR^RYtMismatchedTagstetprocesstProcessingFailuretbegLinetbegColtgottexpecttendLinetendColt ParseErrortlinetcoltmessagetIOErrortstrerror(RYR((RtparseFileAndReport0s %))cCsLtii|}tii|}tii|pti|ndS(N(RRtabspathRYtdirnametexiststmakedirs(RYR((RtmakeSureDirectoryExistsKsc Cs|t|}|id} t|| |ti i |||||| |||}t|| it|ddS(sr Process the input document at C{filename} and write an output document. @type filename: C{str} @param filename: The path to the input file which will be processed. @type linkrel: C{str} @param linkrel: An prefix to apply to all relative links in C{src} or C{href} attributes in the input document when generating the output document. @type ext: C{str} @param ext: The extension to use when selecting an output file name. This replaces the extension of the input file name. @type url: C{str} @param url: A string which will be interpolated with the fully qualified Python name of any API reference encountered in the input document, the result of which will be used as a link to API documentation for that name in the output document. @type templ: A DOM Node or Document @param templ: The template on which the output document will be based. This is mutated and then serialized to the output file. @type options: C{dict} @param options: Further specification of the desired form of the output. Valid keys in this dictionary:: noapi: If present and set to a True value, links to API documentation will not be generated. version: A string which will be included in the output to indicate the version of this documentation. @type outfileGenerator: Callable of C{str}, C{str} returning C{str} @param outfileGenerator: Output filename factory. This is invoked with the intput filename and C{ext} and the output document is serialized to the file with the name returned. @return: C{None} itwbN(RRYtdocttemplt cloneNodet clonedNodeRRRRRRR3toptionsRt newFilenameRtwritexmlR^( RYRRR3RRRRRR((RtdoFileQs* !  (9RxRRFR#RpR\Rttwistedt copyrightttwisted.pythonRORet twisted.webR!R RRIRRRttwisted.python.utilRRR'R-R6R=R<RiRhRsRtR{RRRRRRRRRRRRRRRRRRRRRRRR(4R=RFRRRRReRR{RRRsRRRRRRRR-RxRR<RpR\RORtRRRRRRRR'RRiRRIRRRRhRR R!R6RR#RRR((Rt?sN? -  *      #       )       '    /   X