+
    VBi8                    R   R t ^ RIHt Rt^ RIHtHt ^ RIHt  ! R R]4      t	 ! R R]4      t
 ! R	 R
]4      t ! R R]4      t ! R R]4      t ! R R]4      t ! R R]4      t ! R R]4      t ! R R]4      t ! R R]4      t ! R R]4      t ! R R]P*                  4      tR# )z&
Transforms for resolving references.
)annotationsreStructuredText)nodesutils)	Transformc                  *    ] tR t^tRtRtR R ltRtR# )PropagateTargetsaC  
Propagate empty internal targets to the next element.

Given the following nodes::

    <target ids="internal1" names="internal1">
    <target anonymous="1" ids="id1">
    <target ids="internal2" names="internal2">
    <paragraph>
        This is a test.

`PropagateTargets` propagates the ids and names of the internal
targets preceding the paragraph to the paragraph itself::

    <target refid="internal1">
    <target anonymous="1" refid="id1">
    <target refid="internal2">
    <paragraph ids="internal2 id1 internal1" names="internal2 internal1">
        This is a test.
i  c                   V ^8  d   QhRR/#    returnNone )formats   "C/usr/lib/python3.14/site-packages/docutils/transforms/references.py__annotate__PropagateTargets.__annotate__*   s     5- 5-t 5-    c                	   V P                   P                  \        P                  4       EF  p\	        VP
                  \        P                  4      '       gF   VP                  R 4      '       g/   VP                  R4      '       g   VP                  R4      '       d   Ku  \        V4      ^ 8X  g   Q R4       hVP                  RR7      p\	        V\        P                  4      '       d   VP                  RRR7      pK5  VeQ   \	        V\        P                  \        P                  34      '       d$   \	        V\        P                  4      '       g   EK*  VR	,          P                  VR	,          4       VR
,          P                  VR
,          4       \        VR4      '       g   / Vn        \        VR4      '       g   / Vn        VR	,           F)  pW P                   P                   V&   WP                  V&   K+  	  VR
,           F  pWP                  V&   K  	  VP                  P#                  \%        VR/ 4      4       VP                  P#                  \%        VR/ 4      4       \	        VP
                  \        P&                  4      '       d?   \	        V\        P(                  4      '       d   VP
                  P+                  V4       EK  VR	,          ^ ,          VR &   . VR	&   . VR
&   V P                   P-                  V4       EK  	  R# )refidrefurirefnamez&error: block-level target has childrenT)ascendF)r   descendNidsnamesexpect_referenced_by_nameexpect_referenced_by_id)documentfindallr   target
isinstanceparentTextElementhasattrlen	next_nodesystem_message	Invisible
Targetableextendr   r   r   updategetattrfigurecaptionremove
note_refid)selfr    r&   idnames   &    r   applyPropagateTargets.apply*   s\   mm++ELL9F6==%*;*;<<NN7++v~~h/G/G~~i00v;!#M%MM#(((5IY(<(<==%//tU/K	 !i%//5;K;K)LMM"9ell;;e##F5M2g%%fWo69&ABB68	39&?@@46	1Umm(1!!"% 9?11"5 $ w<B33D9 ( //66 ;R@B--44 92>@ &--66:u}}<. <.$$V, %UmA.F7OF5M F7OMM$$V,i :r   r   N__name__
__module____qualname____firstlineno____doc__default_priorityr4   __static_attributes__r   r   r   r   r      s    * 5- 5-r   r   c                  *    ] tR t^btRtRtR R ltRtR# )AnonymousHyperlinksaa  
Link anonymous references to targets.  Given::

    <paragraph>
        <reference anonymous="1">
            internal
        <reference anonymous="1">
            external
    <target anonymous="1" ids="id1">
    <target anonymous="1" ids="id2" refuri="http://external">

Corresponding references are linked via "refid" or resolved via "refuri"::

    <paragraph>
        <reference anonymous="1" refid="id1">
            text
        <reference anonymous="1" refuri="http://external">
            external
    <target anonymous="1" ids="id1">
    <target anonymous="1" ids="id2" refuri="http://external">
i  c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r    AnonymousHyperlinks.__annotate__|   s     $ $t $r   c                	   V P                   P                  \        P                  4       Uu. uF  pVP	                  R 4      '       g   K  VNK   	  ppV P                   P                  \        P
                  4       Uu. uF  pVP	                  R 4      '       g   K  VNK   	  pp\        V4      \        V4      8w  d   V P                   P                  P                  R\        V4      : R\        V4      : R24      pV P                   P                  V4      pV Fm  p\        P                  ! VP                  VP                  VR7      pV P                   P                  V4      pVP                  V4       VP                  V4       Ko  	  R# \        W#4       F  w  riVP                  R4      '       g   VP                  R4      '       d   K5  RV	n         V	P                  R4      '       d   V	R,          VR&   RVn        Ki  V	R	,          '       g'   V P                   P$                  V	R,          ,          p	Kb  V	R	,          ^ ,          VR&   V P                   P'                  V4       K  	  R# u upi u upi )
	anonymouszAnonymous hyperlink mismatch: z references but z+ targets.
See "backrefs" attribute for IDs.r   Nr   r   Tr   )r   r   r   	referencegetr    r%   reportererrorset_idproblematic	rawsourceadd_backrefreplace_selfzipr$   
referencedresolvedr   r0   )
r1   nodeanonymous_refsanonymous_targetsmsgmsgidrefprbprbidr    s
   &         r   r4   AnonymousHyperlinks.apply|   s   !]]225??C&CTxx$ DC 	 & "]]225<<@&@Txx$ D@ 	 & ~#&7"88--((.. (#.?*@BCC MM((-E%''mmS]]%A,,S1&  % & ~AKC{{7##s{{8'<'< $F>>(++$*8$4CM#'CL!%==!%!2!26'?!C #)%=#3CLMM,,S1! B'&&s   I)
I)=I.I.r   Nr6   r   r   r   r?   r?   b   s    , $ $r   r?   c                  f    ] tR t^tRtRtR R ltR R ltR R ltR	 R
 lt	R R lt
R R ltRtR# )IndirectHyperlinksa  
a) Indirect external references::

       <paragraph>
           <reference refname="indirect-external">
               indirect external
       <target ids="id1" names="direct-external"
           refuri="http://indirect">
       <target ids="id2" names="indirect-external"
           refname="direct-external">

   The "refuri" attribute is migrated back to all indirect targets
   from the final direct target (i.e. a target not referring to
   another indirect target)::

       <paragraph>
           <reference refname="indirect-external">
               indirect external
       <target ids="id1" names="direct-external"
           refuri="http://indirect">
       <target ids="id2" names="indirect-external"
           refuri="http://indirect">

   Once the attribute is migrated, the preexisting "refname" attribute
   is dropped.

b) Indirect internal references::

       <target ids="id1" names="final-target">
       <paragraph>
           <reference refname="indirect-internal">
               indirect internal
       <target ids="id2" names="indirect-internal-2"
           refname="final target">
       <target ids="id3" names="indirect-internal"
           refname="indirect-internal-2">

   Targets which indirectly refer to an internal target become one-hop
   indirect (their "refid" attributes are directly set to the internal
   target's "id"). References which indirectly refer to an internal
   target become direct internal references::

       <target ids="id1" names="final-target">
       <paragraph>
           <reference refid="id1">
               indirect internal
       <target ids="id2" names="indirect-internal-2" refid="id1">
       <target ids="id3" names="indirect-internal" refid="id1">
i  c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   IndirectHyperlinks.__annotate__   s     5 5t 5r   c                	    V P                   P                   F7  pVP                  '       g   V P                  V4       V P	                  V4       K9  	  R # N)r   indirect_targetsrP   resolve_indirect_targetresolve_indirect_referencesr1   r    s   & r   r4   IndirectHyperlinks.apply   s;    mm44F???,,V4,,V4 5r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r]      s     * * *r   c                	   VP                  R 4      pVf   VR,          pMxV P                  P                  P                  V4      pV'       gL   V P                  P                  P                   F  pV! V4      '       g   K   R# 	  V P                  V4       R# V P                  P                  V,          pVP                  VR7       \        V\        P                  4      '       di   VP                  '       gW   VP                  R 4      '       d@   \        VR4      '       d   V P                  V4       R# ^Vn        V P                  V4       V=VP                  R4      '       d   VR,          VR&   RV9   d   VR MVP                  R4      '       d)   VR,          VR&   V P                  P!                  V4       MBVR,          '       d!   W1R&   V P                  P!                  V4       MV P                  V4       R# Ve   VR  RVn        R# )r   Nr   r2   multiply_indirectr   r   T)rF   r   nameidstransformerunknown_reference_resolversnonexistent_indirect_targetr   note_referenced_byr!   r   r    rP   r$   circular_indirect_referencerh   ra   r0   )r1   r    r   reftarget_idresolver_function	reftargets   &&    r   ra   *IndirectHyperlinks.resolve_indirect_target   s   **Y'?!'?L==0044W=L 11MM &(00  N 44V<MM%%l3	$$$5y%,,//&&&!!),,v233008'(F$((3(X&&(2F8& 7Ow'''0F7OMM$$V,".w((0008y!r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r]     s     G GT Gr   c                	    VR ,          V P                   P                  9   d   V P                  VR4       R# V P                  VR4       R# )r   z>which is a duplicate, and cannot be used as a unique referencezwhich does not existN)r   ri   indirect_target_errorrc   s   &&r   rl   .IndirectHyperlinks.nonexistent_indirect_target  sC    ) 5 55&&v 0N O &&v/EFr   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r]     s     K KT Kr   c                	*    V P                  VR 4       R# )zforming a circular referenceN)ru   rc   s   &&r   rn   .IndirectHyperlinks.circular_indirect_reference  s    ""6+IJr   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r]     s      D r   c           	     	   R p. pVR,          '       d   RVR,          ^ ,          ,          pVR,           F8  pVP                  V P                  P                  P                  V. 4      4       K:  	  VR,           F8  pVP                  V P                  P                  P                  V. 4      4       K:  	  VR,          '       d   VRVR,          ^ ,          ,          ,          pV P                  P
                  P                  RV: RVR,          : RV: R	2VR
7      pV P                  P                  V4      p\        P                  ! V4       Fm  p	\        P                  ! V	P                  V	P                  VR7      p
V P                  P                  V
4      pVP                  V4       V	P                  V
4       Ko  	  RVn        R# ) r   z"%s" r   z	(id="%s")zIndirect hyperlink target z refers to target "r   z", .	base_noderD   TN)r*   r   refnamesrF   refidsrG   rH   rI   r   uniqr   rJ   rK   rL   rM   rP   )r1   r    explanationnamingreflistr3   r2   rT   rU   rV   rW   rX   s   &&&         r   ru   (IndirectHyperlinks.indirect_target_error  se   '??vgq11F7OODNN4==1155dB?@ $--BNN4==//33B;<  %==kF5M!$444Fmm$$**	**K9DJ + L $$S)::g&C##--e=CMM((-EOOE"S! ' r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r]   ,  s     %: %:T %:r   c                	   VP                  R 4      '       d   R pV P                  P                  pMVP                  R4      '       d   RpRpMR# W,          pVR,           F  pV P                  P                  P	                  V. 4      pV'       d   VP                  VR7       V Fh  pVP                  '       d   K  VR WGV&   V'       d	   V! V4       RVn        \        V\        P                  4      '       g   KW  V P                  V4       Kj  	  K  	  VR,           F  pV P                  P                  P	                  V. 4      pV'       d   VP                  VR7       V Fh  pVP                  '       d   K  VR  WGV&   V'       d	   V! V4       RVn        \        V\        P                  4      '       g   KW  V P                  V4       Kj  	  K  	  R# )	r   r   Nr   r3   r   Tr   rg   )r$   r   r0   r   rF   rm   rP   r!   r   r    rb   r   )	r1   r    attnamecall_methodattvalr3   r   rV   r2   s	   &&       r   rb   .IndirectHyperlinks.resolve_indirect_references,  st   >>'""G--22K^^H%%GK7OODmm,,00r:G))t)4<<<	N%G$#c5<<0044S9 	 $ --Bmm**..r26G))R)0<<<L%G$#c5<<0044S9 	  r   r   N)r7   r8   r9   r:   r;   r<   r4   ra   rl   rn   ru   rb   r=   r   r   r   r[   r[      s6    0d 5*XGK.%: %:r   r[   c                  *    ] tR tRtRtRtR R ltRtR# )ExternalTargetsiT  a  
Given::

    <paragraph>
        <reference refname="direct-external">
            direct external
    <target ids="id1" names="direct-external" refuri="http://direct">

The "refname" attribute is replaced by the direct "refuri" attribute::

    <paragraph>
        <reference refuri="http://direct">
            direct external
    <target ids="id1" names="direct-external" refuri="http://direct">
i  c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   ExternalTargets.__annotate__h  s     , ,t ,r   c                	   V P                   P                  \        P                  4       F  pVP	                  R 4      '       g   K  VR ,          pVR,           Fn  pV P                   P
                  P                  V. 4      pV'       d   VP                  VR7       V F%  pVP                  '       d   K  VR W%R &   RVn        K'  	  Kp  	  K  	  R# )r   r   r   r   TN)	r   r   r   r    r$   r   rF   rm   rP   )r1   r    r   r3   r   rV   s   &     r   r4   ExternalTargets.applyh  s    mm++ELL9F~~h'')"7OOD"mm4488rBG11t1<&<<<$	N(.H'+  '	 , :r   r   Nr6   r   r   r   r   r   T  s      , ,r   r   c                  2    ] tR tRtRtR R ltR R ltRtR# )	InternalTargetsix  i  c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   InternalTargets.__annotate__|  s     3 3t 3r   c                	    V P                   P                  \        P                  4       FF  pVP	                  R 4      '       d   K  VP	                  R4      '       d   K5  V P                  V4       KH  	  R# )r   r   N)r   r   r   r    r$   resolve_reference_idsrc   s   & r   r4   InternalTargets.apply|  sJ    mm++ELL9F>>(++FNN74K4K**62 :r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r     s     $ $t $r   c                V   VR,           F  pV P                   P                  P                  V4      pV P                   P                  P                  V. 4      pV'       d   VP	                  VR7       V F-  pVP
                  '       d   K  V'       d   VR W5R&   RVn        K/  	  K  	  R# )a^  
Given::

    <paragraph>
        <reference refname="direct-internal">
            direct internal
    <target ids="id1" names="direct-internal">

The "refname" attribute is replaced by "refid" linking to the target's
"id"::

    <paragraph>
        <reference refid="id1">
            direct internal
    <target ids="id1" names="direct-internal">
r   r   r   r   TN)r   ri   rF   r   rm   rP   )r1   r    r3   r   r   rV   s   &&    r   r   %InternalTargets.resolve_reference_ids  s    " 7OODMM))--d3Emm,,00r:G))t)4<<<I#(L#  $r   r   N)r7   r8   r9   r:   r<   r4   r   r=   r   r   r   r   r   x  s    3
$ $r   r   c                  n    ] tR tRtRtRtRt . ROtR R ltR t	R R	 lt
R
 R ltR R ltR R ltRtR# )	Footnotesi  a2  
Assign numbers to autonumbered footnotes, and resolve links to footnotes,
citations, and their references.

Given the following ``document`` as input::

    <document>
        <paragraph>
            A labeled autonumbered footnote reference:
            <footnote_reference auto="1" ids="id1" refname="footnote">
        <paragraph>
            An unlabeled autonumbered footnote reference:
            <footnote_reference auto="1" ids="id2">
        <footnote auto="1" ids="id3">
            <paragraph>
                Unlabeled autonumbered footnote.
        <footnote auto="1" ids="footnote" names="footnote">
            <paragraph>
                Labeled autonumbered footnote.

Auto-numbered footnotes have attribute ``auto="1"`` and no label.
Auto-numbered footnote_references have no reference text (they're
empty elements). When resolving the numbering, a ``label`` element
is added to the beginning of the ``footnote``, and reference text
to the ``footnote_reference``.

The transformed result will be::

    <document>
        <paragraph>
            A labeled autonumbered footnote reference:
            <footnote_reference auto="1" ids="id1" refid="footnote">
                2
        <paragraph>
            An unlabeled autonumbered footnote reference:
            <footnote_reference auto="1" ids="id2" refid="id3">
                1
        <footnote auto="1" ids="id3" backrefs="id2">
            <label>
                1
            <paragraph>
                Unlabeled autonumbered footnote.
        <footnote auto="1" ids="footnote" names="footnote" backrefs="id1">
            <label>
                2
            <paragraph>
                Labeled autonumbered footnote.

Note that the footnotes are not in the same order as the references.

The labels and reference text are added to the auto-numbered ``footnote``
and ``footnote_reference`` elements.  Footnote elements are backlinked to
their references via "refids" attributes.  References are assigned "id"
and "refid" attributes.

After adding labels and reference text, the "auto" attributes can be
ignored.
il  Nc                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   Footnotes.__annotate__  s     / /t /r   c                	    . V n         V P                  P                  pV P                  V4      V P                  n        V P	                  V4       V P                  4        V P                  4        R # r_   )autofootnote_labelsr   autofootnote_startnumber_footnotesnumber_footnote_referencessymbolize_footnotesresolve_footnotes_and_citations)r1   startnums   & r   r4   Footnotes.apply  sV    #% ==33+/+@+@+J(''1  ",,.r   c                   V P                   P                   EF  p \        V4      pV^,          pW0P                   P                  9  g   K1   TP	                  ^ \
        P                  ! RT4      4       TR,           F  pT P                   P                  P                  T. 4       F  pT\
        P                  ! T4      ,          pTP                  R4       \        TR,          4      \        TR,          4      u;8X  d	   ^8X  g   Q h Q hTR,          ^ ,          TR&   TP                  TR,          ^ ,          4       T P                   P                  T4       RTn        K  	  K  	  TR,          '       d   EKb  TR,          '       d   EKt  TR,          P                  T4       T P                   P!                  Y"4       T P"                  P                  T4       EK  	  V# )z
Assign numbers to autonumbered footnotes.

For labeled autonumbered footnotes, copy the number over to
corresponding footnote references.
Tr|   r   r   r   r   dupnames)r   autofootnotesstrri   insertr   labelfootnote_refsrF   Textdelattrr%   rL   r0   rP   appendnote_explicit_targetr   )r1   r   footnoter   r3   rV   s   &&    r   r   Footnotes.number_footnotes  sn    33HHA 5 55OOAu{{2u56 ))==66::4DC5::e,,CKK	*x/3s5z?GaGGGGG#+E?1#5CL((UA7MM,,S1#'CL E * G$$Xj-A-A!((/228F((//6' 4( r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r     s     ! !d !r   c           	        ^ pV P                   P                   EF  pVP                  '       g   VP                  R4      '       d   K/   V P                  V,          pT\        P                  ! T4      ,          pT P                   P                   T,          pT P                   P"                  T,          pYR&   T P                   P%                  T4       \        TR,          4      ^8X  g   Q hTP                  TR,          ^ ,          4       RTn        T^,          pEK  	  R#   \
         Ed$    \        T P                  4      pT^8  d   RMRpT P                   P                  P                  RT RT R2TR7      pT P                   P                  T4      pT P                   P                  TR  F  pTP                  '       g   TP                  R	4      '       d   K.  \        P                  ! TP                  TP                  TR
7      p	T P                   P                  T	4      p
TP                  T
4       TP                  T	4       K  	    R# i ; i)z3Assign numbers to autonumbered footnote references.r   sr|   z0Too many autonumbered footnote references: only z corresponding footnotez available.r~   Nr   rD   r   T)r   autofootnote_refsrP   r$   r   
IndexErrorr%   rG   rH   rI   r   rJ   rK   rL   rM   r   ri   r   r0   )r1   r   irV   r   nr   rT   rU   rW   rX   r2   r   s   &&           r   r   $Footnotes.number_footnote_references  s   ==22C|||s{{733003$ 5::e$$C&&u-B}}((,HLMM$$S)s5z?a'''  UA/CLFA= 3
  001q5Cbmm,,22""#$;A3kK$' 3 ) ,,S1==::12>C|||s{{9'='= ++--eEC MM005EOOE*$$S) ? !s   	D!!B9IA0IIc                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r   ;  s     # #T #r   c           	        . pV P                   P                   F  p\        V P                   P                  \	        V P
                  4      4      w  r4V P
                  V,          V^,           ,          pVP                  V4       VP                  ^ \        P                  ! RV4      4       V P                   ;P                  ^,          un        V P                   P                  V4       K  	  ^ pV P                   P                   F  p V\        P                  ! W,          4      ,          pT P                   P                  T,          p\	        TR,          4      ^8X  g   Q hTR,          ^ ,          TR&   T P                   P-                  T4       TP)                  TR,          ^ ,          4       T^,          pK  	  R#   \         Ed    T P                   P                  P                  R\	        T4      ,          TR7      pT P                   P                  T4      p	T P                   P                  TR  F  pTP                   '       g   TP#                  R4      '       d   K.  \        P$                  ! TP&                  TP&                  T	R7      p
T P                   P                  T
4      pTP)                  T4       TP+                  T
4       K  	    R# i ; i)z<Add symbols indexes to "[*]"-style footnotes and references.r|   zOToo many symbol footnote references: only %s corresponding footnotes available.r~   Nr   rD   r   )r   symbol_footnotesdivmodsymbol_footnote_startr%   symbolsr   r   r   r   rI   symbol_footnote_refsr   r   rG   rH   rP   r$   rJ   rK   rL   rM   r0   )r1   labelsr   repsindex	labeltextr   rV   rT   rU   rW   rX   s   &           r   r   Footnotes.symbolize_footnotes;  s+   66H !D!D!$T\\!24KDU+tax8IMM)$OOAu{{2y9:MM//14/MM  * 7 ==55Cuzz&),,  }}55a8Hx'1,,,#E?1-CLMM$$S)  UA/FA/ 6  mm,,22;=@[I # 3 % ,,S1====abAC|||s{{7';'; ++--eEC MM005EOOE*$$S) B s   #F==B"K A0KKc                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r   `  s     ? ? ?r   c                   V P                   P                   F]  pVR,           FM  pW P                   P                  9   g   K  V P                   P                  V,          pV P                  W4       KO  	  K_  	  V P                   P                   F]  pVR,           FM  pW P                   P
                  9   g   K  V P                   P
                  V,          pV P                  WC4       KO  	  K_  	  R# )zI
Link manually-labeled footnotes and citations to/from their
references.
r   N)r   	footnotesr   resolve_references	citationscitation_refs)r1   r   r   r   citations   &    r   r   )Footnotes.resolve_footnotes_and_citations`  s    
 //H!'**MM777"mm99%@G++H> + 0
 //H!'**MM777"mm99%@G++H> + 0r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r   p  s      4 r   c                	H   \        VR ,          4      ^8X  g   Q hVR ,          ^ ,          pV Fk  pVP                  '       d   K  VP                  R4       W4R&   \        VR ,          4      ^8X  g   Q hVP                  VR ,          ^ ,          4       RVn        Km  	  RVn        R# )r   r   r   TN)r%   rP   r   rL   )r1   noter   r2   rV   s   &&&  r   r   Footnotes.resolve_referencesp  s    4;1$$$%[^C|||KK	"Ls5z?a'''SZ]+CL  r   )r   )
*u   †u   ‡   §   ¶#u   ♠u   ♥u   ♦u   ♣)r7   r8   r9   r:   r;   r<   r   r   r4   r   r   r   r   r   r=   r   r   r   r   r     sE    9v 9G"/:!F#J?  r   r   c                      ] tR tRtRtR# )#CircularSubstitutionDefinitionErrori~  r   N)r7   r8   r9   r:   r=   r   r   r   r   r   ~  s    r   r   c                  &    ] tR tRtRt^t R tRtR# )Substitutionsi  a  
Given the following ``document`` as input::

    <document>
        <paragraph>
            The
            <substitution_reference refname="biohazard">
                biohazard
             symbol is deservedly scary-looking.
        <substitution_definition names="biohazard">
            <image alt="biohazard" uri="biohazard.png">

The ``substitution_reference`` will simply be replaced by the
contents of the corresponding ``substitution_definition``.

The transformed result will be::

    <document>
        <paragraph>
            The
            <image alt="biohazard" uri="biohazard.png">
             symbol is deservedly scary-looking.
        <substitution_definition names="biohazard">
            <image alt="biohazard" uri="biohazard.png">
c           	     	<   V P                   P                  pV P                   P                  p/ p\        V P                   P                  R R4      p\        V P                   P                  \        P                  4      4      pV EF  pRpVR,          pW9   d   Tp	M"VP                  4       p
VP                  V
R4      p	V	f0   V P                   P                  P                  RV,          VR7      pMRW,          p\        VP                  4       4      V8  d-   V P                   P                  P                  RV	,          4      pV'       d   V P                   P                  V4      p\        P                   ! VP"                  VP"                  VR7      pV P                   P                  V4      pVP%                  V4       VP'                  V4       EKO  VP(                  pVP+                  V4      pR	XP,                  9   g   R
VP,                  9   d^   V^ 8  dW   \/        VV^,
          ,          \        P0                  4      '       d)   VV^,
          ,          P3                  4       VV^,
          &   RVP,                  9   g   R
VP,                  9   dn   \        V4      V^,           8  dW   \/        VV^,           ,          \        P0                  4      '       d)   VV^,           ,          P5                  4       VV^,           &   VP7                  4       p VP                  \        P                  4       Fl  pVVR,          P                  4       ,          pVVP9                  V. 4      9   d   \:        hVV,          P=                  V	4       VVR&   VP=                  V4       Kn  	  TP'                  TPF                  4       TPF                   FI  p\/        T\        PH                  4      '       g   K%  RT9   g   K.  T P                   PK                  T4       KK  	  EK  	  R#   \:         Edw    TP(                  p\/        T\        P>                  4      '       do   T P                   P                  P                  R\        P@                  ! TP"                  TP"                  4      TPB                  TR7      pTP'                  T4       MTpTPE                  R4      '       d   TR,          pK"  T P                   P                  P                  RT,          TR7      pT P                   P                  T4      p\        P                   ! TP"                  TP"                  TR7      pT P                   P                  T4      pTP%                  T4       TP'                  T4        EK  i ; i)line_length_limiti'  r|   r   Nz(Undefined substitution referenced: "%s".r~   z;Substitution definition "%s" exceeds the line-length-limit.rD   ltrimtrimrtrimz
ref-originz*Circular substitution definition detected:)liner   z2Circular substitution definition referenced: "%s".)&r   substitution_defssubstitution_namesr,   settingslistr   r   substitution_referencelowerrF   rG   rH   r%   astextrI   rJ   rK   rL   rM   r"   r   
attributesr!   r   rstriplstripdeepcopy
setdefaultr   r   substitution_definitionliteral_blockr   r$   childrenReferentialnote_refname)r1   defsnormednestedr   
subreflistrV   rT   r   keynormed_namesubdefrU   rW   rX   r"   r   subdef_copy
nested_refnested_name
ref_originrQ   s   &                     r   r4   Substitutions.apply  s   }}..11#DMM$:$:$7@ $--//0L0LMN
CC)nG%mmojjd3{mm,,22@ +. 3 0 v}}'*;;--006624789C ,,S1''mmS]]%A,,S1&  %ZZFLL%E6,,,V...19F519,=,1JJ"8 "8(.uqy(9(@(@(BF519%6,,,V...K%!)+"6%!)#4ejjAA(.uqy(9(@(@(BF519% //+K!"-"5"544#6J"(I)>)D)D)F"GK"f&7&7R&HHAA;'..s3/2J|,%%j1#6@ [112 $,,dE$5$566 !D(2248 -[ d 7 fe&C&CDD--0066D++F,<,<,2,<,<>#[[F	 7 <C
 '', "%J$,,\::%/%=
--0066 ")*5? 7 AC !MM005E++s}}ECC MM005EOOE*$$S)/s   BPB>VB>VVr   Nr6   r   r   r   r   r     s    4 >Z9r   r   c                  >    ] tR tRtRtRt R R ltR R ltR tR	t	R
# )TargetNotesi  zv
Creates a footnote for each external target in the text, and corresponding
footnote references after each reference.
i  c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   TargetNotes.__annotate__
  s     : :t :r   c                	x    \         P                  ! WVR 7       VP                  P                  R. 4      V n        R# ))	startnodeclassN)r   __init__detailsrF   classes)r1   r   r  s   &&&r   r
  TargetNotes.__init__
  s,    4Y? ((,,Wb9r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r    s     . .t .r   c                	Z   / p. pV P                   P                  \        P                  4       F  pVP	                  R 4      '       g   K  VR,          p. pV F8  pVP                  V P                   P                  P                  V. 4      4       K:  	  V'       g   Ko  V P                  VR ,          VV4      pVR ,          V9  g   K  WqVR ,          &   VP                  V4       K  	  V P                   P                  \        P                  4       F|  pVP                  R4      '       g   K  VP	                  R 4      '       g   K5  V P                  VR ,          V.V4      pVR ,          V9  g   K`  WqVR ,          &   VP                  V4       K~  	  V P                  P                  V4       R# )r   r   rC   N)r   r   r   r    r$   r*   r   rF   make_target_footnoter   rE   r  rM   )	r1   notesnodelistr    r   refsr3   r   rV   s	   &        r   r4   TargetNotes.apply  sS   mm++ELL9F>>(++7OEDDMM2266tR@A 001A4168Hhu,*2fX&') :  ==((9C77;''{{8$$44S]SE5:<x=-+3#h-(OOH- : 	##H-r   c           	     	   W9   d3   W1,          p\        VR ,          4      ^8X  g   Q hVR ,          ^ ,          pM\        P                  ! 4       pV P                  P	                  V4      pRV,           p^VR&   V.VR &   \        P
                  ! 4       pV\        P                  ! RWR7      ,          pWG,          pV P                  P                  V4       V P                  P                  WD4       V EFn  p\        V\        P                  4      '       d   K&  \        P                  ! V^R7      p	V	R;;,          V P                  ,          uu&   V P                  P                  V	4       V P                  P                  V	4       VP                  P!                  V4      ^,           p
V	.p\"        P$                  ! V P                  P&                  4      '       gl   V P                  '       d4   VP)                  ^ \        P*                  ! RV P                  R7      4       M&VP)                  ^ \        P,                  ! R4      4       VP                  P)                  W4       EKq  	  V# )	r   zTARGET_NOTE: autor|   )r   )r   r  r   )textClasses)r%   r   r   r   rI   	paragraphrE   note_autofootnoter   r!   r    footnote_referencer  note_autofootnote_refnote_footnote_refr"   r   r   get_trim_footnote_ref_spacer   r   inliner   )r1   r   r  r  r   footnote_namefootnote_idfootnote_paragraphrV   refnoder   r   s   &&&&        r   r   TargetNotes.make_target_footnote-  s   ?}Hx()Q...$W-a0M~~'H--..x8K ,k9M HV!.HW!&!2%//"f"LL*HMM++H5MM..xBC#u||,,..}1MGI$,,.MM//8MM++G4JJ$$S)A-EiG44T]]5K5KLL<<<NN5<<S$,,GI NN1ejjo6JJe-   r   )r  N)
r7   r8   r9   r:   r;   r<   r
  r4   r  r=   r   r   r   r  r    s#    
 :
.<"r   r  c                  *    ] tR tRtRtRtR R ltRtR# )CitationReferencesR  zResolve <citation_references>.

The 'use_bibtex'__ configuration setting indicates that citation entries
are fetched from a BibTeX database by the backend (LaTeX).

__ https://docutils.sourceforge.io/docs/user/config.html#use-bibtex
i  c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   CitationReferences.__annotate___  s     % %t %r   c                	   \        V P                  P                  R . 4      '       g   R# V P                  P                  \        P
                  4       F  pVP                  '       g;   V P                  P                  P                  VP                  R4      4      '       d   KQ  VP                  4       '       g   Ki  VP                  R4       RVn        K  	  R# )
use_bibtexNr   T)r,   r   r   r   r   citation_referencerP   ri   rF   r   r   r1   rQ   s   & r   r4   CitationReferences.apply_  s    t}}--|R@@MM))%*B*BCD
 }}} 5 5 9 9$((9:M N N{{}}Y' $ Dr   r   Nr6   r   r   r   r'  r'  R  s     % %r   r'  c                  *    ] tR tRtRtRtR R ltRtR# )DanglingReferencesin  u  
Check for dangling references (incl. footnote & citation) and for
unreferenced targets.

Provisional : pending deprecation
  Docutils readers will add separate transforms for resolving
  refnames to refids and for reporting unresolved references
  instead of this transform (to make space for reference-resolving
  transforms added by extensions or applications) in Docutils 1.0.
  This transform will be removed in Docutils 2.0.
r(  c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   DanglingReferences.__annotate__~  s     0 0t 0r   c                	L   \        V P                  V P                  P                  P                  4      pV P                  P	                  V4       V P                  P                  \        P                  4       F  pVP                  '       d   K  VP                  R 4      '       d   K0  VR,          '       d   VR,          ^ ,          pM)VR,          '       d   VR,          ^ ,          pM	VR,          pV P                  P                  P                  RV,          VR7       K  	  R# )rC   r   r   r   z(Hyperlink target "%s" is not referenced.r~   N)DanglingReferencesVisitorr   rj   rk   walkr   r   r    rO   rF   rG   info)r1   visitorr    r   s   &   r   r4   DanglingReferences.apply~  s    +MMMM%%AAC 	7# mm++ELL9F$$$::k**
 '??#G_Q/FE]]#E]1-F $G_F&&++>(. , 0! :r   r   Nr6   r   r   r   r1  r1  n  s    
 0 0r   r1  c                  F    ] tR tRtRtR R ltR R ltR R lt];tt	R	t
R
# )r5  i  u   Provisional : pending deprecation

This auxiliary class is used by the `DanglingReferences` transform
which will no longer be used in Docutils 1.0.
It will be removed in Docutils 2.0.
c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   &DanglingReferencesVisitor.__annotate__  s     G G Gr   c                	\    \         P                  P                  W4       Wn        W n        R # r_   )r   SparseNodeVisitorr
  r   rk   )r1   r   rk   s   &&&r   r
  "DanglingReferencesVisitor.__init__  s!    ((8 +F(r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r<    s      T r   c                	    R # r_   r   r.  s   &&r   unknown_visit'DanglingReferencesVisitor.unknown_visit  s    r   c                   V ^8  d   QhRR/# r
   r   )r   s   "r   r   r<    s     2 2t 2r   c                	   VP                   '       g   VP                  R 4      '       g   R# VR ,          pV P                  P                  P	                  V4      pVe>   VR  W1R&   V P                  P
                  V,          P                  VR7       RVn         R# V P                   F  pV! V4      '       g   K   R# 	  W P                  P                  9   d-   V P                  P                  P                  RV R2VR7      pMRV9   g   R	V9   d   R
pRV9  d   VR,          pMRV9  d
   VR,          pR	V9  d   VR,          pM VP                  R	4      '       g
   VR,          pRV9   g   RV9   d
   VR,          p\        P                  ! RV4      .pM. pV P                  P                  P                  ! RV R2.VO5RV/ pV P                  P                  V4      p\        P                  ! VP                  VP                  VR7      p	 VR,          ^ ,          p
VP#                  V
4       VP%                  V	4       R#   \          d    T P                  P                  T	4      p
 LLi ; i)r   Nr   rg   Tz>Duplicate target name, cannot be used as a unique reference: "z".r~   <>z%Did you want to embed a URI or alias?z
Opening bracket missing.z <z7
The embedded reference must be preceded by whitespace.z
Closing bracket missing.zD
The embedded reference must be the last text before the end string.z< z >z9
Whitespace around the embedded reference is not allowed.r|   zUnknown target name: "r   rD   r   )rP   r$   r   ri   rF   r   rm   rk   rG   rH   endswithr   r  rI   rJ   rK   r   rL   rM   )r1   rQ   r   r2   rp   rT   hintr  rU   rW   rX   s   &&         r   visit_reference)DanglingReferencesVisitor.visit_reference  sA   ===Y 7 7y/]]""&&w/>YMMMb!444; DM!%!A!A && "B mm+++--((..&ir+6: / <C g~>g%88D( / 0Dg%88D ))#.. 7 8D7?dgo 0 1D ??2t45--((...wir:00*.0C $$S)eL	.KNE 	#  	.MM((-E	.s   I &I-,I-)r   rk   N)r7   r8   r9   r:   r;   r
  rB  rJ  visit_footnote_referencevisit_citation_referencer=   r   r   r   r5  r5    s'    G
2h ;JI7r   r5  N)r;   
__future__r   __docformat__docutilsr   r   docutils.transformsr   r   r?   r[   r   r   r   	Exceptionr   r   r  r'  r1  r>  r5  r   r   r   <module>rS     s   
 #" ! )N-y N-b>) >Bn: n:b!,i !,H%$i %$P[	 [|	) 	z9I z9zP) Pf% %8)0 )0XDJ 7 7 DJr   