www.digitalmars.com         C & C++   DMDScript  

D - Code documentation - 1 attachment

reply Juarez Rudsatz <juarez correio.com> writes:
Hi all!

    	I am sending a very preliminary version of a specification for 
implementing a sintax for document source files using the /* */ comments.
    	It's a preliminary version and contain, certainly, design and 
language errors.
    	Please read the attached html file and send your comments.

Juarez Rudsatz
Jul 12 2002
next sibling parent reply "anderson" <anderson firestar.com.au> writes:
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Source code documentation with coddocThis is very complete and I can't =
think of much to add. =20

Is it possible to have html links in documentation, or better yet html =
code? I know "see" has this ablity, but what about in a general comment. =
For example In some cases you may want to insert a picture of what your =
talking about.
Jul 12 2002
parent reply "OddesE" <OddesE_XYZ hotmail.com> writes:
Source code documentation with coddoc"anderson" <anderson firestar.com.au>
wrote in message news:agoaa2$16a9 $1 digitaldaemon.com...

 This is very complete and I can't think of much to add.

 Is it possible to have html links in documentation,
 or better yet html code?
 I know "see" has this ablity, but what about in a general
 comment. For example In some cases you may want to insert
 a picture of what your talking about.



I agree, this is a very useful feature, and most
tools support this.


--
Stijn
OddesE_XYZ hotmail.com
http://OddesE.cjb.net
_________________________________________________
Remove _XYZ from my address when replying by mail
Jul 14 2002
parent "Robert M. Münch" <robert.muench robertmuench.de> writes:
"OddesE" <OddesE_XYZ hotmail.com> schrieb im Newsbeitrag
news:agt6tf$9to$1 digitaldaemon.com...


 I agree, this is a very useful feature, and most
 tools support this.


Hi, if you want to write TXT in a very easy manner and get good looking HTML
out of  it have a look at my make-doc-pro on my homepage. This is a Rebol
script and you will find some getting-started infos too. My homepage has
been done with this tool.

If you have any questions let me know.

--
Robert M. Münch
IT & Management Freelancer
Mobile: +49 (0)177 2452 802
Fax   : +49 (0)721 8408 9112
Web   : http://www.robertmuench.de
Jul 15 2002
prev sibling next sibling parent reply "OddesE" <OddesE_XYZ hotmail.com> writes:
Source code documentation with coddocI read the document, and I think it is
a very good initiative.
We definitely need some kind of standard for this, or we will
end up with a whole bunch of similar standards that differ in
just enough respect to be a pain in the you-know-where.

I do propose one big and a whole bunch of small alterations
to the standard. I have marked sections that I have added in
green, comments in red and sections that I think should be
deleted in gray.

The text that still is black also had changes in them, but
these are just small things such as corrected spelling
errors, they don't change the standard in any way.

The modified file is attached.


--
Stijn
OddesE_XYZ hotmail.com
http://OddesE.cjb.net
_________________________________________________
Remove _XYZ from my address when replying by mail



begin 666 ddoc-xml.html

M4W1R:6-T+R]%3B(-"B  (" B:'1T<#HO+W=W=RYW,RYO<F<O5%(O>&AT;6PQ


M(F=E;F5R871O<B( 8V]N=&5N=#TB2%1-3"!4:61Y(&9O<B!7:6YD;W=S("AV

M+F]R9R( +SX-"CQT:71L93Y3;W5R8V4 8V]D92!D;V-U;65N=&%T:6]N('=I
M=&  8V]D9&]C/"]T:71L93X-"CPO:&5A9#X-"CQB;V1Y/ T*/&9O;G0 8V]L
M;W(](F=R965N(CX-"CQH,3Y!8G-T<F%C=#PO
M;G1A=&EO;B!M;V1E;"!D97-C<FEB97, =&AE(&9O<FUA="!C;VUM96YT<R!I
M;B!T:&4-"B  ('-O=7)C92!C;V1E(&]F(&$ <')O9W)A;2!M=7-T(&%D:&5R
M92!T;R!T;R!B92!E>'1R86-T86)L90T*("  8GD 82!D;V-U;65N=&%T:6]N

M;F9O<FUA=&EO;B!T;R!C<F5A=&4 8G)O=W-A8FQE(&]R('!R:6YT86)L92!D
M;V-U;65N=&%T:6]N+ T*("  9F]R(&EN<W1A;F-E(&EN(&%N(&AT;6PL('!D

M=6UE;G0 :7, 8W)E871E9"!W:71H('1H92!P=7)P;W-E(&]F('-P96-I9GEI
M;F< 80T*("  8VQE87( 86YD(&5A<WD 9&]C=6UE;G1A=&EO;B!M;V1E;"!F

M=#X-
M=&EO;B!C;VUM96YT<R!A<F4 82!M971H;V0 ;V8 <F5D=6-I;F< =V]R:R!B
M>2!M;W9I;F<-"B  (&1O8W5M96YT871I;VX 9G)O;2!A('-E<&%R871E(&1O

M9&]C=6UE;G1A=&EO;B!D;V-U;65N="!C;W5L9"!E87-I;'D 8F4 9V5N97)A
M=&5D+B!!<PT*("  979E<GD <')O9W)A;6UE<B!K;F]W<RP 9&]C=6UE;G1A
M=&EO;B!T96YD<R!T;R!B92!I;F-O;7!L971E+"!O=70-"B  (&]F(&1A=&4L
M('=R;VYG+"!O<B!N;VXM97AI<W1E;G0N($UO=FEN9R!T:&4 9&]C=6UE;G1A


M;VQS(&9O<B!G96YE<F%T:6YG(&1O8W5M96YT871I;VX ;V8 05!))W, 87)E
M(&-O;6UO;2!T;V1A>2X-"B  (%1H97D <')O=FED92!A('-I;7!L92!M971H
M;V0 9F]R('!R;V=R86UM:6YG(&%N9"!D;V-U;65N=&EN9R!A= T*("  =&AE
M('-A;64 =&EM92X 5&AE(&1O8W5M96YT871I;VX <F5M86EN<R!C;&]S92!T

M(&%N9"!F;W( =&AE(&%P<&QI8V%T:6]N('!R;V=R86UM97(-"B  ('=I;&P 
M8F4 :6X 82!M;W)E(')E861A8FQE(&%N9"!E87-Y('1O('-E87)C:"!F;W)M
M870N(%1H97D 9&5C<F5A<V4-"B  ('1H92!W;W)K(&]F(&-R96%T:6YG(&%N

M<FET:6YG(&ET(&EN(&$ <V5P87)A=&4 =V]R9"!P<F]C97-S;W(N($UO<W0 
M9&]C=6UE;G1A=&EO; T*("  9V5N97)A=&]R<R!W:6QL(&5V96X 8F4 86)L
M92!T;R!G96YE<F%T92!D96-E;G0 9&]C=6UE;G1A=&EO; T*("  9G)O;2!S
M;W5R8V4 8V]D92!W:71H(&YO(&1O8W5M96YT871I;VX 8V]M;65N=', :6X 
M:70 870 86QL+ T*("  :G5S="!F<F]M('!A<G-I;F< =&AE(&-O9&4 :71S

M:&4 <V]U<F-E(&-O9&4 8V%N(&=R96%T;'D :6UP<F]V92!T:&4 =F%L=64 
M;V8-"B  ('1H92!G96YE<F%T960 9&]C=6UE;G1A=&EO;B!H;W=E=F5R+CPO
M<#X-" T*/& Q/DAO=R!C;VUM96YT<R!A<F4 9&]C=6UE;G1E9#PO
M"CQF;VYT(&-O;&]R/2)R960B/ T*/' ^22!W;W5L9"!C:&%N9V4 ;W( ;6%Y


M8V]M<&]S960 8GD 82!S970 ;V8 <W1R=6-T=7)E<PT*("  :6X ;&%N9W5A
M9V4N($9O<B!E86-H('-T<G5C='5R92!W92!C86X <')O=FED92!A(&-O;6UE
M;G0-"B  ('!R;W9I9&EN9R!A(&1E<V-R:7!T:6]N(&]F(&ET(&9U;F-T:6]N

M92!P87)A;65T97)S(&]R(&UO9'5L97, ;W( 871T86-H:6YG(&$ <W!E8VEF
M:6,-"B  (&%T=')I8G5T92!C;VYT86EN:6YG(&EN9F]R;6%T:6]N(')E;&%T
M:6]N960N(%1H92!C;VUM96YT<R!A<F4 <'5T+ T*("  9V5N97)A;&QY+"!B
M969O<F4 =&AE('-P96-I9FEC871I;VX ;V8 =&AE(&9E871U<F4N/"]P/ T*

M=6YC=&EO;B!W:71H(&1O8W5M96YT871I;VX :6X :71S(&-O;6UE;G1S(#H\

M:6]N(&ES(&$ <VEM<&QE(&5X86UP;&4-"B  ("  ("HJ+PT*("  ("  :6YT



M(%=O;&9R86YG($%M861E=7, 36]Z87)T("9L=#MW86U ;75S:6,N;W)G)F=T
M.PT*("  ("  ("H-"B  ("  (" J(%1H:7, 8VQA<W, <&QA>7, 82!S:6YF

M;&5A<FYI;F< ;75S:6, ;W( 9F]R(&QE87)N:6YG($0 9&]C=6UE;G1A=&EO


M=', 87)E('!A<G-E9#PO
M=7-E(&$ =F%R:6%T:6]N(&]F('1H92!S=&%N9&%R9 T*("  9&]C=6UE;G1A
M=&EO;B!F;W( 1"X 5&AE>2!S=&%R="!W:71H('1H92!S=')I;F< )R\J*B9A
M8W5T93L-"B  (&%N9"!F:6YI<V  =VET:"!T:&4 <W1R:6YG("<J*B\F86-U
M=&4[.CPO<#X-" T*/'!R93X-"B  ("  ("\J*B!4:&ES(&ES(&$ 9&]C=6UE
M;G1E9"!C;VUM96YT("HJ+PT*("  ("  ='EP961E9B!I;G0 ;F]R;6%L=F%L


M86-U=&4[.CPO<#X-" T*/'!R93X-"B  ("  ("\O*B!4:&ES(&ES(&$ 9&]C


M8V4 82!S:6YG;&4 ;&EN92!C;VUM96YT(&)E:&EN9"!T:&4 <V]U<F-E(&QI


M(%1H:7, :7, 82!D;V-U;65N=&5D(&-O;6UE;G0-"CPO<')E/ T*/"]F;VYT

M;F5S+B!4:&4 97AT<F$ 8FQA;FMS+ T*("  =&%B=6QA=&EO;B!A;F0 ;F5W
M(&QI;F5S(&%R92!S=')I<'!E9"P :G5S="!A<R!W:71H(&AT;6PZ/"]P/ T*




M87)A9W)A<& L('EO=2!C86X 861D(&$ 8FQA;FL ;&EN92!W:&5R92!Y;W4 
M=V%N="!T;R!S=&%R= T*("  82!N97< <&%R86=R87!H.CPO<#X-" T*/'!R



M;G0 <W1Y;&4 ;V9T96X =7-E9"!B>2!P<F]G<F%M;65R<R!W:&5R90T*("  
M979E<GD ;&EN92!I;B!T:&4 8V]M;65N="!B;&]C:R!S=&%R=', =VET:"!A
M;B!A<W1E<FES:R H*BD-"B  (&%L:6=N960 =VET:"!T:&4 9FER<W0 87-T
M97)I<VL :6X =&AE('-T87)T(&-O;6UE;G0 =&%G+ T*("  =&AE(&9I<G-T
M(&%S=&5R:7-K(&]F('1H92!C;VUM96YT(&QI;F5S(&%R92!S=')I<'!E9"!I
M9 T*("  979E<GD 8V]M;65N="!L:6YE('-T87)T<R!W:71H(&%N(&%S=&5R
M:7-K(&%S('1H92!F:7)S= T*("  ;F]N+7=H:71E<W!A8V4 8VAA<F%C=&5R
M.CPO<#X-" T*/'!R93X-"B  ("  ("\J* T*("  ("  ("H 5&AI<R!C;VUM




M87)T('1A9R!O<B!B969O<F4-"B  ('1H92!E;F0 =&%G(&%R92!O;6ET960Z


M(&]M:71E9 T*("  ("  ("HJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ*BHJ

M/ T*/' ^07, >6]U('=I;&P <V5E(&EN('1H92!N97AT('-E8W1I;VX 22!P

M<F5T='D 8FEG+B!)('-A>2!W92!C:&%N9V4 =&AE('=A>0T*("  =&%G<R!A
M<F4 9&5S8W)I8F5D('1O(&$ ;65T:&]D('1H870 :7, 97-S96YT:6%L;'D 

M<B!T:&ES.CPO<#X-"CQU;#X-"B  (#QL:3YX;6P :7, 82!S=&%N9&%R9"X 
M(#LI/"]L:3X-"B  (#QL:3YX;6P :&%S(&)E96X =V5L;"!T:&]U9VAT(&]U
M="!A;F0 =VEL;"!M;W-T(&QI:V5L>0T*("  ("  (&)E(&UO<F4 96%S>2!T

M("  =V4 <')O8F%B;'D 9&]N)W0 979E;B!H879E('1O(&1O('1H:7,L(&)E
M8V%U<V4 =V4-"B  ("  ("!C86X =7-E(&%N(&5X:7-T:6YG('!A<G-E<BX\
M+VQI/ T*("  /&QI/GAM;"!I<R!W96QL(&MN;W=N('-O('!E;W!L92!W:6QL
M('!R;V)A8FQY('5N9&5R<W1A;F0-"B  ("  ("!I="!E87-I97(N/"]L:3X-
M"B  (#QL:3Y4:&ES('=A>2!W92!D;VXG="!H879E('1O(&1I9F9E<F5N=&EA
M=&4 8F5T=V5E; T*("  ("  ('-I;F=L92UL:6YE(&%N9"!M=6QT:2UL:6YE
M('1A9W,N/"]L:3X-"B  (#QL:3Y9;W4 8V%N('=R:71E(&$ 9'1D(&]R('-C


M("  ("  :68 =&AE(&-O9&4 :7, ;VL 8V]U;&0 8F4 875T;VUA=&EC+CPO

M9F]R('1R86YS;&%T:6YG('1H90T*("  ("  ('AM;"!C;V1E('1O(&]T:&5R
M(&1O8W5M96YT(&9O<FUA=',N/"]L:3X-"B  (#QL:3Y4:&4 8V]D92!T;R!P

M("  ("  ;W( 9'1D)W, 86YD('1R86YS9F]R;6EN9R!I="!I;G1O(&]T:&5R
M(&1O8W5M96YT<R!U<VEN9PT*("  ("  ('-T>6QE<VAE971S(&AA<R!A;')E
M861Y(&)E96X =W)I='1E;BP 86YD(&ES(&%V86EL86)L92P-"B  ("  ("!F
M;W( 9G)E92P ;VX 86QM;W-T(&%N>2!P;&%T9F]R;2!A;F0 :6X 86QM;W-T
M(&%N>0T*("  ("  (&QA;F=U86=E+B!4:&ES('=O=6QD(&=R96%T;'D <VEM


M:6YG(&%N9"!T<F%N<VQA=&EN9R!T:&4 8V]M;65N=', =V]U;&0 =&AE;B!B

M("<O+RHG(&]R("<O+R9L=#LG/"]L:3X-"B  (#QL:3Y);B!T:&4 8V%S92!O
M9B G+RHJ)R!F:6YD('1H92!C;W)R97-P;VYD:6YG(&5N9"!T86< )RHJ+R<\
M+VQI/ T*("  /&QI/D5X=')A8W0 86QL('1E>'0 8F5T=V5E;B!T:&4 <W1A
M<G0 =&%G(&%N9"!T:&4 96YD('1A9R!O<B!E;VP\+VQI/ T*("  /&QI/D5X
M=')A8W0 <W5P97)F;'5O=7, 87-T97)I<VMS(" J*2!F<F]M('1H:7, =&5X
M="!A<R!D97-C<FEB960-"B  ("  ("!I;B!A;B!E87)L:65R('-E8W1I;VX\
M+VQI/ T*("  /&QI/E1E<W0 =&AE(')E<W5L=&EN9R!T97AT(&9O<B!X;6P 
M8V]M<&QI86YC92!U<VEN9R!T:&4 9&1O8PT*("  ("  (&1T9"!O<B!S8VAE
M;6$N/"]L:3X-"B  (#QL:3Y)9B!T:&4 =&5S="!F86EL<RP :7-S=64 =V%R
M;FEN9W,L(&5L<V4 <')O8V5E9#PO
M92!R97-U;'1I;F< =&5X="!I;G1O(&AT;6PL('!D9BP =V]R9"!D;V-U;65N
M= T*("  ("  (&]R('=H871E=F5R(&9O<FUA="!D97-I<F5D('5S:6YG('1H
M92!C;W)R97-P;VYD:6YG('-T>6QE<VAE970N/"]L:3X-"B  (#QL:3Y);G-E
M<G0 =&AE('1R86YS;&%T960 =&5X="!I;G1O('1H92!D;V-U;65N=&%T:6]N
M(&%T('1H90T*("  ("  (&-O<G)E8W0 ;&]C871I;VXN/"]L:3X-"CPO;VP^

M"CQP/E1H92!C;VUM96YT(&-A;B!A;'-O(&AA=F4 96UB961D960 >&UL('1A
M9W, =VAI8V  <W!E8VEF>2!T:&4-"B  (&1O8W5M96YT871I;VX ;V8 <W!E

M("  (" J("9L=#MA=71H;W(F9W0[5VEL;&EA;2!3:&%K97-P96%R929L=#LO



M('-E<F5R86P =&%G<R!A;F0 =&5X="!I;B!T:&4 8V]M;65N=#H

M;&EA;2!3:&%K97-P96%R929L=#LO875T:&]R)F=T.PT*("  ("  ("H )FQT
M.W9E<G-I;VXF9W0[,2XP)FQT.R]V97)S:6]N)F=T.PT*("  ("  ("H-"B  
M("  (" J(%1H:7, ;6]D=6QE(&EM<&QE;65N=', =&AE(&QO9VEC(&9O<B!U

M;B!O9B!M>2!I9&5A<RX 270 ;6%G:6-A;&QY('1R86YS;&%T97, 86QL(&ED



M"CQP/DD =V]U;&0 <V-R87  =&AI<RP 8F5C875S92!W:71H('AM;"!T86=S
M(&ET(&ES(&YO(&QO;F=E< T*("  ;F5C97-S87)Y('1O(&UA:V4 86YY(&1I

M+CPO<#X-"CPO9F]N=#X-" T*/&9O;G0 8V]L;W(](F=R87DB/ T*/& S/E1Y

M('1Y<&5S(#H
M97-C<FEB960 :6X ;VYE(&QI;F4N(%1H92!T86< 96YD(&%T('1H92!N97=L
M:6YE(&-A<F%C=&5R+B!!<R!E>&%M<&QE('1H97)E(&%R92!T:&4 =F5R<VEO

M"CQL:3Y486< <&%R86=R87!H<R!A<F4 =&%G97, 9&5S8W)I8F5D(&EN(&]N
M92!O<B!M;W)E(&QI;F5S+B!4:&4 =&%G(&5N9"!A="!T:&4 ;F5X="!T86< 


M;VX 8V]M;65N=', ;6%Y('!R96-E9&4 =&AE(&1E8VQA<F%T:6]N.CPO<#X-
M" T*/'!R93X-"B  ("  ("\J* T*("  ("  ("H )FQT.V%U=&AO<B9G=#M7

M;'0[875T:&]R)F=T.U=O;&9G86YG($%M861E=7, 36]Z87)T)FQT.R]A=71H


M;V1E($1O8W5M96YT871I;VXF;'0[+V-A=&5G;W)Y)F=T.PT*("  ("  ("H 
M)FQT.W-E929G=#M$(%!R;V=R86UM:6YG(%1U=&]R:6%L)FQT.R]S964F9W0[

M87, 86X 97AA;7!L92!O9B!D;V-U;65N=&EN9R!C;V1E('=I=&  8V]D9&]C
M+ T*("  ("  ("H 270 :7, 86X 97AA;7!L92!O9B!U<VEN9R!T:&4 8V]M
M;65N=', 9F]R(&=E;F5R871I;F< 9&]C=6UE;G1A=&EO;BX-"B  ("  ("HJ

M<CTB9W)E96XB/ T*/' ^270 :7, 86QS;R!A;&QO=V5D('1O('!L86-E(&1O

M;&%R871I;VX =7-I;F< =&AE('-P96-I86P <W1A<G0 =&%G("9A8W5T93LO
M+R9L=#LF86-U=&4[+ T*("  5&AE<V4 8V]M;65N=', ;6%Y(&]N;'D <W!A
M;B!O;F4 ;&EN92!H;W=E=F5R+B!";W1H(&9O<FUS(&UA>0T*("  8F4 ;6EX
M960 9G)E96QY+CPO<#X-"CPO9F]N=#X-" T*/& T/D-L87-S+"!3=')U8W1U
M<F4 ;W( 56YI;VX 1FEE;&1S/"]H-#X-" T*/&9O;G0 8V]L;W(](F=R965N
M(CX-"CQP/E1H:7, :7, 86X 97AA;7!L92!O9B!A('-T<G5C="!W:71H(&1O

M.CPO<#X-
M(%1H92!B>71E(')E<')E<V5N=&EN9R!T:&4 <F5D('9A;'5E(&9O<B!C;VQO



M92!V86QU92!F;W( 8V]L;W(-"B  ("!5:6YT."!U;G5S960[("\O/"!4:&ES
M(&)Y=&4 :7, <F5S97)V960 9F]R(&9U='5R92!U<V4-"B  ?0T*/"]P<F4^


M=&AI<RX 270 9&]E<VXG="!A9&0 ;75C:"!V86QU92!)('1H:6YK+CPO9F]N
M=#X-" T*/&9O;G0 8V]L;W(](F=R87DB/ T*/' ^06QT97)N871I=F5L>2!S
M:6UP;&4 <')O8V5D=7)E<R!A;F0 8VQA<W, ;65T:&]D<R!C86X 8F4-"B  
M(&1O8W5M96YT960 869T97( :71S(&1E8VQA<F%T:6]N+B!4:&4 9&]C=6UE
M;G1A=&EO;B!M87D <W1A<G0-"B  (&%F=&5R('1H92!E;F-L;W-I;F< <&%R

M=&]C;VP <')O=&]C;VPL(&-H87);72!M97-S86=E*0T*(" O*BH-"B  ("H 
M5&AI<R!F=6YC=&EO;B!S96YD(&$ ;65S<V%G92!T:')O=6=T:"!T:&4 4')O
M=&]C;VP 9&5F:6YE9 T*("  *B!A;F0 <F5T=7)N('1H92!T:6UE('=A<W1E
M9"!D=7)I;F< <V5N9&EN9RX 268 82!P<F]B;&5M(&AA<'!E;G,-"B  ("H 


M8W1I;VX ;W( 82!M971H;V0 87)E(&%V86EL86)L92!I; T*("  =&AI<R!F



M;F4 ;V8 =&AE(&%U=&AO<G,-"B  (&]F(&$ ;6]D=6QE+B!)="!H87, =&AE
M(&9O;&QO=VEN9R!O<'1I;VYA;"!P<F]P97)T:65S.CPO<#X-" T*/'1A8FQE
M(&)O<F1E<CTB,2( 8V]L;W(](F)L86-K(CX-"CQT<CX-"B  /'1H/B9N8G-P
M.U!R;W!E<G1Y)FYB<W [/"]T:#X-"B  /'1H(&%L:6=N/2)L969T(CXF;F)S
M<#M

M=&AE(&%U=&AO<G, ;F%T:6]N86QI='DF;F)S<#L\+W1D/ T*/"]T<CX-"CQT
M<CX-"B  /'1D/B9N8G-P.VQA;F<\+W1D/ T*(" \=&0^)FYB<W [4W!E8VEF


M<#M3<&5C:69I97, =&AE(&%U=&AO<G, 8FER=&AD871E)FYB<W [/"]T9#X-

M8G-P.U-P96-I9FEE<R!T:&4 875T:&]R<R!O8V-U<&%T:6]N(&%T('1H92!T
M:6UE(&]F('=R:71I;F<F;F)S<#L\+W1D/ T*/"]T<CX-"CQT<CX-"B  /'1D
M/B9N8G-P.VUA:6P\+W1D/ T*(" \=&0^)FYB<W [4W!E8VEF:65S(&%N(&5M
M86EL(&%D9')E<W, =VAE<F4 =&AE(&%U=&AO<B!C86X 8F4 <F5A8VAE9"9N


M=&%R=&5D(&]R(&IO:6YE9"!I;B!T:&4 9&5V96QO<&UE;G0F;F)S<#L\+W1D
M/ T*/"]T<CX-"CQT<CX-"B  /'1D/B9N8G-P.W-I=&4\+W1D/ T*(" \=&0^
M)FYB<W [<W!E8VEF:65S(&%N('5R;"!T;R!T:&4 875T:&]R<R!W96)S:71E
M)FYB<W [/"]T9#X-
M:&4 9F]L;&]W:6YG(&%R92!E>&%M<&QE<R!O9B!A=71H;W( =&%G<RP =VAI



M:6%M0&QI=&5R871U<F4N;F5T(B!O;CTB,C P,BXP,RXP-" P-3HP-B(F9W0[
M5VEL;&EA;2!3:&%K97-P96%R929L=#LO875T:&]R)F=T.PT*("  (" J("9L
M=#MA=71H;W( ;6%I;#TB=V%M0&UU<VEC+F]R9R( ;&%N9STB9V5R;6%N(B9G
M=#M7;VQF9V%N9R!!;6%D975S($UO>F%R="9L=#LO875T:&]R)F=T.PT*("  
M(" J("9L=#MA=71H;W( <VET93TB=W=W+F1A;G1E+FQI=&5R871U<F4N;F5T
M(B9G=#M
M.V%U=&AO<B9G=#M*;VYA=&AA;B!$;V4F;'0[+V%U=&AO<B9G=#L-"B  ("  
M*B F;'0[875T:&]R('=O<FL](F-O;7!I;&5R('=A;'1E<B(F9W0[5V%L=&5R
M($)R:6=H="9L=#LO875T:&]R)F=T.PT*("  ("HJ+PT*("  (&UO9'5L92!L

M<#Y486< 86YD('!R;W!E<G1Y(&-O;G1E;G1S(&%R92!G96YE<F%L;'D ;F]T
M(&-H96-K960 9F]R('-Y;G1A>"X-"B  (%1H:7, ;65A;G, ;VYE(&-O=6QD
M(&5N=&5R(&%N(&EN=F%L:60 92UM86EL(&%D9')E<W, 9F]R(&5X86UP;&4N


M<F4 9&ES<&QA>65D(&EN('1H92!D;V-U;65N=&%T:6]N(&%S('1H92!A=71H

M;&]R/2)R960B/ T*/' ^375L='!L92!A=71H;W)S(&EN(&]N92!T86< :7, 



M96UA:6P ;W( 8F]T:"!B=70 ;75S="!F;VQL;W< =&AE(&9O<FUA=#H ;F%M
M92 F;'0[96UA:6PF9W0[+ T*("  02!D;V-U;65N=&%T:6]N(&-O;6UE;G0 
M;6%Y(&-O;G1A:6X ;6]R92!T:&%N(&]N92!A=71H;W( =&%G+ T*("  06QT
M97)N871I=F5L>2P 82!S:6YG;&4 875T:&]R('1A9VQI;F4 ;6%Y(&UE;G1I
M;VX <V5V97)A; T*("  875T:&]R<RP <V5P87)A=&5D(&)Y(&-O;6UA<SH\

M9G)A;F< 06UA9&5U<R!-;WIA<G0 )FQT.W=A;4!M=7-I8RYO<F<F9W0[+"!*
M;VAA;F5S(%-E8F%S=&EA;B!"86-H("9L=#MB86-H0&UU<VEC+F]R9R9G=#LL



M;VQO<CTB<F5D(CX-"CQP/E1H:7, 8V%N(&)E('-C<F%P<&5D+"!B96-A=7-E


M:&4 875T:&]R('1A9R!C86X :&%V92!A(&1A=&4 8V]M<&QE;65N="!S<&5C
M:69I960-"B  (&)Y('1H92!W;W)D(")O;B(N(%1H92!D871E(&9O<FUA="!U
M<V5D(&ES('1H92!I;G1E<FYA=&EO;F%L($E33RX-"B  (%-E92!T:&4 97AA

M<CH 5VEL;&EA;2!3:&%K97-P96%R92 F;'0[=VEL;&EA;4!L:71E<F%T=7)E
M+FYE="9G=#L




M871I;VX 9F]R('1H92!M;V1U;&4L(&-L87-S(&]R(&UE=&AO9#PO<#X-" T*
M/'1A8FQE(&)O<F1E<CTB,2( 8V]L;W(](F)L86-K(CX-"CQT<CX-"B  /'1H
M/B9N8G-P.U!R;W!E<G1Y)FYB<W [/"]T:#X-"B  /'1H(&%L:6=N/2)L969T
M(CXF;F)S<#M

M8W)E871I;VX 9&%T92!O9B!T:&4 9&]C=6UE;G0F;F)S<#L\+W1D/ T*/"]T

M=#MC;W!Y<FEG:'0 9&%T93TB,C P,2(F9W0[4&%V96P (D5V:6Q/;F4B($UI
M;F%Y978F;'0[+V-O<'ER:6=H="9G=#L-
M:&ES(&UO9'5L92!P<F]V:61E<R!A(&-L87-S(&QI8G)A<GD 9F]R('=I;F1O

M<R!N96-E<W-A<GD 9F]R(&-R96%T:6YG('=I;F1O=V5D(&%P<&QI8V%T:6]N
M<PT*("  ("  ("H <W5C:"!A<R!E9&ET(&-O;G1R;VQS+"!L:7-T(&-O;G1R

M:&5R(&-O;G1R;VQS+B!)="!I<R!A;'-O('!O<W-I8FQE('1O(&1E<FEV92!Y
M;W5R(&]W; T*("  ("  ("H 8W5S=&]M(&-O;G1R;VQS+ T*("  ("  *BHO

M,CYL:6-E;G-E/"]H,CX-" T*/' ^5&AE(&QI8V5N<V4 <&%R86=R87!H('-H

M;R!L:6-E;G-I;F< =&5R;7, 86YD('!E<FUI<W-I;VX ;V8 =7-E+CPO<#X-
M" T*/&9O;G0 8V]L;W(](F=R965N(CX-"CQT86)L92!B;W)D97(](C$B(&-O


M;F)S<#L\+W1H/ T*/"]T<CX-"CQT<CX-"B  /'1D/B9N8G-P.W-I=&4F;F)S
M<#L\+W1D/ T*(" \=&0^)FYB<W [=7)L(&]F('=E8G-I=&4 8V]N=&%I;FEN
M9R!T:&4 ;&EC96YC92!O<B!E>'1R82!I;F9O<FUA=&EO;B!P97)T86EN:6YG
M('1H92!L:6-E;F-E)FYB<W [/"]T9#X-


M8W5M96YT871I;VX 8V]M;65N=', 9F]R(&UO9'5L92!D96-L87)A=&EO;G,Z

M92!S:71E/2)H='1P.B\O=W=W+F=N=2YO<F<O8V]P>6QE9G0O9W!L+FAT;6PB
M)F=T.PT*("  ("  ("H 4&5R;6ES<VEO;B!T;R!U<V4L(&-O<'DL(&UO9&EF

M*B!A;F0 :71S(&1O8W5M96YT871I;VX 9F]R(&%N>2!P=7)P;W-E(&ES(&AE
M<F5B>2!G<F%N=&5D('=I=&AO=70 9F5E+ T*("  ("  ("H <')O=FED960 
M=&AA="!T:&4 86)O=F4 8V]P>7)I9VAT(&YO=&EC92!A<'!E87( :6X 86QL
M(&-O<&EE<R!A;F0-"B  ("  (" J('1H870 8F]T:"!T:&%T(&-O<'ER:6=H

M("  ("  *B!I;B!S=7!P;W)T:6YG(&1O8W5M96YT871I;VXN("!!=71H;W( 

M<W5I=&%B:6QI='D ;V8 =&AI<R!S;V9T=V%R92!F;W( 86YY('!U<G!O<V4N

M<F5S<R!O<B!I;7!L:65D('=A<G)A;G1Y+ T*("  ("  ("H )FQT.R]L:6-E
M;F-E)F=T.PT*("  ("  ("H-"B  ("  (" J(%1H:7, ;6]D=6QE('!R;W9I
M9&5S(&$ 8VQA<W, ;&EB<F%R>2!F;W( =VEN9&]W<R!P<F]G<F%M;6EN9RX-
M"B  ("  (" J($ET(&-O;G1A:6YS(&-O;G1R;VQS(&YE8V5S<V%R>2!F;W( 

M(&%S(&5D:70 8V]N=')O;',L(&QI<W0 8V]N=')O;',L(&UE;G5S+"!S=&%T
M=7, 8F%R<R!A;F0-"B  ("  (" J(&UA;GD ;W1H97( 8V]N=')O;',N($ET





M/'1R/ T*(" \=& ^)FYB<W [4')O<&5R='DF;F)S<#L\+W1H/ T*(" \=&  
M86QI9VX](FQE9G0B/B9N8G-P.T1E<V-R:7!T:6]N)FYB<W [/"]T:#X-"CPO

M=&0^)FYB<W [4W1A='5S(&]F('1H92!R96QE87-E+"!S=6-H(&%S(&%L<&AA
M+"!B971A+"!P<F5R96QE87-E+"!C86YD:61A=&4L('5N<W1A8FQE+"!S=&%B
M;&4L(&9I;F%L)FYB<W [/"]T9#X-


M;VX 8V]M;65N=', 9F]R('1Y<&4 9&5C;&%R871I;VYS.CPO<#X-" T*/'!R
M93X-"B  ("  ("\J* T*("  ("  ("H )FQT.W9E<G-I;VX <W1A='5S/2)B
M971A(B9G=#LR
M("  (&UO9'5L92!I;7!O<G1E9#L-
M<F5D(CX-"CQP/DD 9&]N)W0 =&AI;FL :70 :7, ;F5C97-S87)Y('1O(&5N
M9F]R8V4 =&AE(&1I9F9E<F5N="!V86QU97,-"B  (&9O<B!S=&%T=7,N/"]P

M;W)M871I;VX :6X 82!V97)S:6]N('!A<F%G<F%P:"!H87, ='=O('!A<G1S

M:6]N('-T<FEN9RX 3&%S="!I<R!O<'1I;VYA;"!A;F0 :&%V90T*("  =&AE







M=&%B;&4 8F]R9&5R/2(Q(B!C;VQO<CTB8FQA8VLB/ T*/'1R/ T*(" \=& ^
M)FYB<W [4')O<&5R='DF;F)S<#L\+W1H/ T*(" \=&  86QI9VX](FQE9G0B
M/B9N8G-P.T1E<V-R:7!T:6]N)FYB<W [/"]T:#X-
M(#QT9#XF;F)S<#MH<F5F)FYB<W [/"]T9#X-"B  /'1D/B9N8G-P.T$ =7)L

M/"]T86)L93X-"CPO9F]N=#X-" T*/' ^5&AE(&9O;&QO=VEN9R!A<F4 97AA
M;7!L97, ;V8 <V5E('1A9W,L('=H:6-H(&UA>2!B92!U<V5D(&EN(&%N>0T*
M("  9&]C=6UE;G1A=&EO;B!C;VUM96YT('1O(&EN9&EC871E(&$ 8W)O<W,M
M<F5F97)E;F-E('1O(&$ ='EP92P-"B  (&UE=&AO9"P 8V]N<W1R=6-T;W(L
M(&9I96QD+"!E>'1E<FYA;"!D;V-U;65N="P ;W( 86YY('1E>'0Z/"]P/ T*

M:6\F;'0[+W-E929G=#L-"B  ("  (" J("9L=#MS964F9W0[<W1R:6YG)FQT

M;'0[+W-E929G=#L-"B  ("  (" J("9L=#MS964F9W0[=&AR96%D<RYT:')E

M.U)A;F1O;4%C8V5S<T9I;&4N4F%N9&]M06-C97-S1FEL92A&:6QE*29L=#LO
M<V5E)F=T.PT*("  ("  ("H )FQT.W-E929G=#M286YD;VU!8V-E<W-&:6QE
M+E)A;F1O;4%C8V5S<T9I;&4H1FEL92P 4W1R:6YG*29L=#LO<V5E)F=T.PT*
M("  ("  ("H )FQT.W-E929G=#M


M9W)A;6UI;F< 5'5T;W)I86PF;'0[+W-E929G=#L-"B  ("  ("HJ+PT*("  

M87)A8W1E<B B+B( <V5P87)A=&5S('1H92!N86UE(&]F(&$ ;6]D=6QE(&]F
M(&$ 8VQA<W,-"B  (&%N9"!T:&4 ;F%M92!O9B!A(&-L87-S(&9R;VT =&AE

M;VYS=')U8W1O<G,N(%1H92!O<F1E<B!O9B!S96%R8VAI;F< :7, <&%C:V%G
M92P-"B  (&UO9'5L92P ='EP92P ;65T:&]D+B!/;F4 ;V8 <V5V97)A;"!O
M=F5R;&]A9&5D(&UE=&AO9', ;W(-"B  (&-O;G-T<G5C=&]R<R!M87D 8F4 

M("!O9B!A<F=U;65N="!T>7!E<R!A9G1E<B!T:&4 ;65T:&]D(&]R(&-O;G-T
M<G5C=&]R(&YA;64N(#PO<#X-
M;WAY9V5N('!A<G-E<R!T:&4 8V]M;65N=',L(&%N9"!E=F5R>2!W;W)D('1H
M870 ;6%T8VAE<PT*("  =&AE(&YA;64 ;V8 82!T>7!E+"!F=6YC=&EO;B!O
M<B!G;&]B86P =F%R:6%B;&4 :7,-"B  (&%U=&]M871I8V%L;'D ='5R;F5D
M(&EN=&\ 82!L:6YK('1O('1H92!P87)T(&]F('1H90T*("  9&]C=6UE;G1A
M=&EO;B!D97-C<FEB:6YG('1H870 96QE;65N="X 22!F;W5N9"!T:&%T('9E
M<GD-"B  ('5S969U;"!A;F0 :70 ;6%Y(&)E('=I<V4 =&\ <F5Q=6ER92!T


M96YT('=A<R!A9&1E9"!T;R!T:&4-"B  ($%022!S<&5C:69I8V%T:6]N("AI
M9B!D:69F97)E;G0 9G)O;2!T:&4 :6UP;&5M96YT871I;VXI+ T*("  270 
M8V]U;&0 8F4 =7-E9"!I;B!A('1Y<&4 :6X <F5F97)E;F-E('1O('1H92!P
M<F5V:6]U<PT*("  ;6]D=6QE('9E<G-I;VXL(&]R(&EN(&$ ;65T:&]D(&EN
M(')E9F5R96YC92!T;R!T:&4-"B  ('!R979I;W5S(&-L87-S('9E<G-I;VXN

M:6YC92!T86<L('=H:6-H(&UA>2!B90T*("  =7-E9"!I;B!D;V-U;65N=&%T
M:6]N(&-O;6UE;G1S(&9O<B!D96-L87)A=&EO;G, ;V8 ;65T:&]D<SH\+W ^

M871U<STB86QP:&$B)F=T.S N,R9L=#LO=F5R<VEO;B9G=#L-"B  ("  (" J


M"B  ("  ("  (" O*BH-"B  ("  ("  ("  *B F;'0[<VEN8V4F9W0[,"XR
M)FQT.R]S:6YC929G=#L-"B  ("  ("  ("  * T*("  ("  ("  (" J(%1H
M:7, ;65T:&]D(&ES(&EN=')O9'5C960 :6X =F5R<VEO;B P+C( ;V8 =&AI
M<R!C;&%S<PT*("  ("  ("  ("HJ+PT*("  ("  ("  ('9O:60 :6YI='=I
M9&=E=', >PT*("  ("  ("  ("XN+ T*("  ("  ("  ('T-"B  ("  ('T-

M<GD =&%G;&EN92!S<&5C:69I97, :6X =VAA="!C871E9V]R>2!T:&4-"B  
M('1Y<&4 ;W( ;65T:&]D(&ES(&=R;W5P960N($ET(&-O=6QD(&)E('5S960 
M:6X 8VQA<W-E<PT*("  =&\ 8VQA<W-I9GD =&AE('!R;W!E<G1I97,L(&UE
M=&AO9', 86YD(&UE;6)E<G, :6X 80T*("  8VQO<V5D('-C;W!E+CPO<#X-
M" T*/' ^5&AE(&9O;&QO=VEN9R!I<R!A;B!E>&%M<&QE(&]F(&$ 8V%T96=O
M<GD =&%G+"!W:&EC: T*("  ;6%Y(&)E('5S960 :6X 9&]C=6UE;G1A=&EO


M<GDF9W0[5&5M<&5R871U<F4 :&%N9&QI;F< <F]U=&EN97,F;'0[+V-A=&5G



M92!D;V-U;65N=&%T:6]N+CPO<#X-" T*/' ^5&AE(&9O;&QO=VEN9R!I<R!A
M;B!E>&%M<&QE('1A9RP =VAI8V  ;6%Y(&)E('5S960-"B  (&EN(&1O8W5M
M96YT871I;VX 8V]M;65N=', 9F]R('!R;W9I9&EN9R!U<V5R(&5X86UP;&5S
M.CPO<#X-" T*/'!R93X-"B  ("  ("\J* T*("  ("  ("H )FQT.V5X86UP


M;7E296=%>'  /2!N97< 4F5G17AP*");02U:82UZ7&(A72HB*3L-"B  ("  




M;W(](F=R965N(CX-"CQP/E1H92!F;W)M871T:6YG(&EN('1H92!D;V-U;65N
M=&%T:6]N(')E;6%I;G, 97AA8W1L>2!T:&4-"B  ('-A;64 87, :70 :7, 

M=F5D+B!!(&YO;BUP<F]P;W)T:6]N86P 9F]N="P <W5C:"!A<R!C;W5R:65R


M;G1A8W0N/"]P/CPO9F]N=#X-
M9FEE<R!K;F]W;B!I<W-U97, :6X ='EP97,L(&UE=&AO9', ;W( <F]U=&EN

M<CTB,2( 8V]L;W(](F)L86-K(CX-"CQT<CX-"B  /'1H/B9N8G-P.U!R;W!E
M<G1Y)FYB<W [/"]T:#X-"B  /'1H(&%L:6=N/2)L969T(CXF;F)S<#M$97-C

M<V5V97)I='DF;F)S<#L\+W1D/ T*(" \=&0^)FYB<W [4V5V97)I='D ;V8 
M=&AE(&)U9RP <W5C:"!A<R!L;W<L(&UE9&EU;2P :&EG:"P <V5V97)E+"!C
M<FET:6-A;#PO
M5&AE(&9O;&QO=VEN9R!I<R!A;B!E>&%M<&QE(&]F(&$ 8G5G('1A9VQI;F4L
M('=H:6-H(&UA>0T*("  8F4 =7-E9"!I;B!D;V-U;65N=&%T:6]N(&-O;6UE
M;G1S(&9O<B!D96-L87)A=&EO;G, ;V8-"B  (&9U;F-T:6]N<R!O<B!C;&%S
M<V5S.CPO<#X-" T*/'!R93X-"B  ("  ("\J* T*("  ("  ("H )FQT.V)U
M9R!S979E<FET>3TB:&EG:"(F9W0[5VEN9&]W<R Y>"!D;V5S(&YO="!P87-S

M*B\-"B  ("  (&EN="!M96UO<GE5<V5D('L-"B  ("  ("XN+ T*("  ("  

M<FL =&\ 8F4 9&]N92P <W5C:"!A<R!I;7!L96UE;G1I;F<L(&]P=&EM:7II
M;F<-"B  (&]R(&1O8W5M96YT:6YG(&-E<G1A:6X ='EP97, 86YD(&UE=&AO


M8W5M96YT871I;VX 8V]M;65N=', 9F]R(&1E8VQA<F%T:6]N<R!O9B!A(&-L
M87-S.CPO<#X-" T*/'!R93X-"B  ("  ("\J* T*("  ("  ("H )FQT.W9E
M<G-I;VXF9W0[,2XP)FQT.R]V97)S:6]N)F=T.PT*("  ("  ("H )FQT.W1O
M9&\F9W0[36]D:69Y('1O('!E<FUI="!E=F%L=6%T:6]N(&]F(&$ <W1R:6YG
M(&-A<F%C=&5R(&)Y(&-A<F%C=&5R)FQT.R]T;V1O)F=T.PT*("  ("  *BHO


M<&5C:69Y(&$ =&5X="!T;R!B=6EL9"!A(&=L;W-S87)Y(&)Y('-U8FIE8W0N
M(%1H92!G;&]S<V%R>2!T86< :7, 82!T86=L:6YE(&)U="!A(&1O8W5M96YT
M871I;VX 8V]M;65N="!M87D 8V]N=&%I;B!M;W)E('1H86X ;VYE(&=L;W-S

M92!O9B!A('1O9&\ =&%G;&EN92P =VAI8V  ;6%Y(&)E('5S960 :6X 9&]C
M=6UE;G1A=&EO;B!C;VUM96YT<R!F;W( 9&5C;&%R871I;VYS(&]F(&$ 9G5N

M9VQO<W-A<GDF9W0[1&5L971I;F< 9FEL97,F;'0[+V=L;W-S87)Y)F=T.PT*
M("  ("  ("H )FQT.V=L;W-S87)Y)F=T.T5R87-I;F< 9FEL97,F;'0[+V=L

M<W1R:6YG(&9I;&5N86UE*7L-"B  ("  ("XN+ T*("  ("  ?0T*/"]P<F4^

M<R!A;B!E>&%M<&QE(&]F(&%N(')E<W5M92!T86=L:6YE+ T*("  =VAI8V  
M;6%Y(&)E('5S960 9F]R('-H;W)T(&1E<V-R:6)I;F< 82!A<G1I9F%C=#H\

M9W0[26YT97)F86-E1&ES8V]N;F5C="!D:7-C;VYN96-T<R!A;B!)0V]N;F5C
M=&EO;E!O:6YT(&EN=&5R9F%C92XF;'0[+W)E<W5M929G=#L-"B  ("  (" J


M(" J('1H870 =V%S('!R979I;W5S;'D ;6%D92!B>2!T:&4 26YT97)F86-E

M(&%R92!W<F%P<&5R<R!F;W( =&AE($%C=&EV95  979E;G0M:&%N9&QI;F< 
M;65C:&%N:7-M+ T*("  ("  ("H =&AE("!)0V]N;F5C=&EO;E!O:6YT0V]N

M(" J*B\-"B  ("  ('9O:60 26YT97)F86-E1&ES8V]N;F5C="A)56YK;F]W





M/ T*(" \=& ^)FYB<W [4')O<&5R='DF;F)S<#L\+W1H/ T*(" \=&  86QI
M9VX](FQE9G0B/B9N8G-P.T1E<V-R:7!T:6]N)FYB<W [/"]T:#X-"CPO='(^

M8G-P.TYA;64 ;V8 =&AE('!A<F%M971E<B!D97-C<FEB960 *&UA;F1A=&]R
M>2DF;F)S<#L

M("!W:&EC:"!M87D 8F4 =7-E9"!I;B!D;V-U;65N=&%T:6]N(&-O;6UE;G1S
M(&9O<B!M971H;V0-"B  (&%N9"!C;VYS=')U8W1O<B!D96-L87)A=&EO;G,Z

M;F%M93TB9FEL92(F9W0[5&AE(&9I;&4 =&\ 8F4 <V5A<F-H960F;'0[+W!A
M<F%M)F=T.PT*("  ("  ("H )FQT.W!A<F%M(&YA;64](G!A='1E<FXB)F=T
M.U1H92!P871T97)N('1O(&)E(&UA=&-H960 9'5R:6YG('1H92!S96%R8V N

M<&QE('-T<FEN9R!O<B!A(')E9W5L87( 97AP<F5S<VEO;BXF;'0[+W!A<F%M
M)F=T.PT*("  ("  ("H )FQT.W!A<F%M(&YA;64](F-O=6YT(B9G=#M4:&4 
M;6%X(&YU;6)E<B!O9B!L:6YE<R!T;R!B<FEN9W, 9F]R(&5A8V -"B  ("  
M(" J(&UA=&-H+B!/(&9O<B!A;&P ;&EN97,[)FQT.R]P87)A;29G=#L-"B  


M;6%T8VA,:6YE<RA&:6QE(&9I;&4L(&-H87);72!P871T97)N+"!I;G0 8V]U

M971E<B!P87)A9W)A<&  <VAO=6QD(&-O;G-I<W0 ;V8 =&AE(&YA;64-"B  
M(&]F('1H92!P87)A;65T97( 9F]L;&]W960 8GD 82!S:&]R="!D97-C<FEP

M86UE(&ES(&$ <')O<&5R='D ;V8 =&AE('!A<F%M('1A9RP =&AE(&]R9&5R
M(&]F('1H90T*("  <&%R86T =&%G<R!I<R!N;W0 :6UP;W)T86YT+CPO<#X-
M"CPO9F]N=#X-" T*/&9O;G0 8V]L;W(](F=R87DB/ T*/' ^02!D;V-U;65N
M=&%T:6]N(&-O;6UE;G0 ;6%Y(&-O;G1A:6X ;6]R92!T:&%N(&]N92!P87)A
M;65T97(-"B  ('1A9RX 5&AE('5S=6%L(&-O;G9E;G1I;VX :7, =&AA="!I
M9B!A;GD <&%R86UE=&5R('!A<F%G<F%P:',-"B  (&%R92!P<F5S96YT(&EN
M(&$ 9&]C=6UE;G1A=&EO;B!C;VUM96YT+"!T:&5N('1H97)E('-H;W5L9"!B
M90T*("  ;VYE('!A<F%M971E<B!P87)A9W)A<&  9F]R(&5A8V  <&%R86UE
M=&5R(&]F('1H92!M971H;V0 ;W(-"B  (&-O;G-T<G5C=&]R+"!A;F0 =&AE
M('!A<F%M971E<G, <&%R86=R87!H<R!S:&]U;&0 87!P96%R(&EN('1H90T*
M("  ;W)D97( :6X =VAI8V  =&AE('!A<F%M971E<G, 87)E(&1E8VQA<F5D
M+CPO<#X-"CPO9F]N=#X-" T*/& R/E1A9W, 9F]R(&EM<&]R=',\+V R/ T*

M<#X-"CPO9F]N=#X-
M9F]L;&]W:6YG(&ES(&%N(&5X86UP;&4 ;V8 86X :6UP;W)T('!A<F%G<F%P


M(" O*BH-"B  ("  (" J(&UY;6]D=6QE.B!M;V1U;&4 =VET:"!A=7AI;&EA
M<GD <F]U=&EN97,-"B  ("  (" J(&,N<W1D:6\Z(&YE961E9"!F;W( <')I



M<#Y4:&4 :6YF;W)M871I;VX :6X 86X :6UP;W)T('!A<F%G<F%P:"!S:&]U
M;&0 8V]N<VES="!O9 T*("  =&AE(&YA;64 ;V8 86X ;6]D=6QE("AW:&EC

M92D 9F]L;&]W960 8GD 82!S:&]R="!D97-C<FEP=&EO;B!O9B!T:&4-"B  

M96YT871I;VX 8V]M;65N="!M87D 8V]N=&%I;B!M;W)E('1H86X ;VYE(&UO



M<F]U=&EN97,-"B  ("  ("HJ+PT*("  ("  :6UP;W)T(&UY;6]D=6QE.PT*


M(" O*BH-"B  ("  (" J($YE961E9"!F;W( <F5A9&EN9R!A;F0 =W)I=&EN



M<')E/ T*("  ("  :6UP;W)T(&UY;6]D=6QE.R O+SP 075X:6QI87)Y(')O

M('!R:6YT9B!F=6YC=&EO; T*("  ("  :6UP;W)T('-T<F5A;3L (" O+SP 

M93X-"CPO9F]N=#X-

M<'1I;VX <&%R86=R87!H+ T*("  =VAI8V  ;6%Y(&)E('5S960 :6X 9&]C

M=6-T;W( 9&5C;&%R871I;VYS.CPO<#X-" T*/'!R93X-"B  ("  ('9O:60 


M("  ("  +R\J('1H92!W:61G970 9&]E<R!N;W0 :&%V92!A(&9L86YG92P 

M("  ("  =&AR;W< ;F5W(%5N9FQA;F=E9%=I9&=E=$5R<F]R*"9A8W5T93M-
M:7-S:6YG(&9L86YG929A8W5T93LI.PT*("  ("  ("  ("  ("!I9B H(7=I

M("  ("  ("  ("  ("  ("  ("H =&AE('=I9&=E="!C86YN;W0 8F4 =7-E
M9"X 5&AI<R!H87!P96YS(&)E8V%U<V4 :70 =V%S(&YO= T*("  ("  ("  
M("  ("  ("  ("  (" J(&EN:71I86QI>F5D+"!I="!W87, ;F]T(&%T=&%C
M:&5D('1O(&$ ;6%N86=E<BP :70 =V%S(&YO= T*("  ("  ("  ("  ("  


M;W< ;F5W(%5N=7-A8FQE5VED9V5T17)R;W(H*3L-"B  ("  ("  ("  ("  
M:68 *'=I9&=E="Y);E5S92D-"B  ("  ("  ("  ("  ("  ("  ("!T:')O
M=R!N97< 3&]C:U=I9&=E=$5R<F]R*")7:61G970 :7, 86QR96%D>2!I;B!U

M;B!E>&-E<'1I;VX <&%R86=R87!H(&ES(&%T=&%C:&5D('=I=&  =&AE(&UE
M=&AO9 T*("  =VAI8V  =&AE(&5R<F]R(&ES('1H<F]W960N($9O<B!D;V-U
M;65N=&EN9R!T:&4 97AC97!T:6]N('5S92!A(&YO<FUA; T*("  =&%G(&]N

M;W)M871I;VX :6X 86X 97AC97!T:6]N('!A<F%G<F%P:"!S:&]U;&0 8V]N

M<W1A;F-E<R!T:&%T(&-A=7-E('1H92!E>&-E<'1I;VX-"B  ('1O(&)E('1H
M<F]W;BX 5VAE;B!A;B!E>&-E<'1I;VX :&%S(&YO(&-O;6UE;G0 8G5T(&AA


M(&UE86X =&AA="!I9B!A;B!E>&-E<'1I;VX :7, =&AR;W=N('=I=&  82!L


M;V-K5VED9V5T17)R;W(H(E=I9&=E="!I<R!A;')E861Y(&EN('5S92(I.R!W
M;W5L9 T*("  9VEV92 B5VED9V5T(&ES(&%L<F5A9'D :6X =7-E(B!A<R!T

M8FQE+"!B96-A=7-E(&ET(&UI9VAT(&)E(&UI>&5D('=I=&  <&%R86UE=&5R
M<SH-"B  ('1H<F]W(&YE=R!,;V-K5VED9V5T17)R;W(H(E=I9&=E=" E9"!I

M"CQP/D$ ;65T:&]D(&UA>2!C;VYT86EN(&UO<F4 =&AA;B!O;F4 97AC97!T

M,CX-" T*/' ^5&AE(&9O;&QO=VEN9R!I<R!A;B!E>&%M<&QE(&]F(&%N(')E
M='5R;B!P87)A9W)A<& L('=H:6-H(&UA>2!B92!U<V5D(&EN(&1O8W5M96YT
M871I;VX 8V]M;65N=', 9F]R(&UE=&AO9"!A;F0 9G5N8W1I;VYS(&1E8VQA

M="!K;F]W(&%B;W5T(&%L;"!T:&ES+BXN4V5E;7, <F5A;&QY(&-O;VPL(&)U
M="!M87EB90T*("  86QS;R!R96%L;'D 8V]M<&QE>"!F;W( =&AE(&1O8W5M



M='(Q("9L=#L <W1R,BD-"B  ("  ("  ("  ("  ("  ("  (" O*BH 8V]N
M9&ET:6]N(#H :68 =&AE(&9I<G-T('-T<FEN9R!I<R!S;6%L;&5R('1H86X 
M<V5C;VYD+ T*("  ("  ("  ("  ("  ("  ("  (" J(')E='5R;B Z(&$ 


M(&EF("AS='(Q(#T

M("  ("  ("  ("  <F5T=7)N(#T ,#L-"B  ("  ("  ("  ("  :68 *'-T
M<C$ /3T <W1R,BD-"B  ("  ("  ("  ("  ("  ("  (" O*BH 8V]N9&ET
M:6]N(#H :68 =&AE(&9I<G-T('-T<FEN9R!I<R!G<F5A=&5R('1H86X <V5C
M;VYD+ T*("  ("  ("  ("  ("  ("  ("  ("\O*B!R971U<FXZ(&$ ;F5G


M(&$ <F5T=7)N('!A<F%G<F%P:"!H87, 82!S<&5C:6%L(&EN=&5R;F%L('-T

M<B\^8V]N<VES=', ;V8 82!S:&]R="!D97-C<FEP=&EO;B!O9B!T:&4 8V]N
M9&ET:6]N(&]F(')E='5R;BX 268 ;VUM:71E9"!T:&5N('1H92!R971U<FX 
M=F%L=64 :7, ;F]T(&1O8W5M96YT960N/"]L:3X-"B  /&QI/CQB/G)E='5R
M;CH\+V(^/&)R+SYC;VYS:7-T<R!O9B!A('-H;W)T(&1E<V-R:7!T:6]N(&]F
M('1H92!R971U<FYE9"!V86QU92X 268 ;VUM:71E9"!A;F0 =&AE(')E='5R
M;B!I<R!A(&-O;G-T86YT('1H96X =&AE(&-O;G-T86YT(&ES('5S960 87, 
M<F5T=7)N+B!/=&AE<G=I<V4 =&AE(')E='5R;B!V86QU92!I<R!N;W0 9&]C
M=6UE;G1E9"X\+VQI/ T*/"]U;#X-"CQP/D$ 9&]C=6UE;G1A=&EO;B!C;VUM
M96YT(&9O<B!A(&9U;F-T:6]N(&UA>2!C;VYT86EN(&%T(&UO<W0 ;VYE(')E


M(&-A;B!B92!D;V-U;65N=&5D+B!4:&5R92!A<F4 ;F\ ;65A;FEN9R!I;B!I
M;F-L=61E(&1O8W5M96YT871I;VX 9F]R('1H92!F;VQL;W=I;F< =&%G<SH\

M9#PO

M;F< 9&]C=6UE;G1A=&EO;B!C;VUM96YT<R!C;W5L9"!I;F-L=61E(&%U=&]M
M871I8V%L;'D =&AE(&EN9F]R;6%T:6]N(&%N9"!S:&]W(&]R(&AI9&4 9F]L

M=')I8G5T97, 8V%N(&)E(&-O;6UE;G1E9#H\<#X-"CQU;#X-"B  /&QI/F1E
M<')E8V%T960\+VQI/ T*(" \;&D^;W9E<G)I9&4\+VQI/ T*(" \;&D^86)S
M=')A8W0\+VQI/ T*(" \;&D^8V]N<W0\+VQI/ T*(" \;&D^9FEN86P\+VQI


M;F1L:6YG(&UE=&AO9',-"B  ("  ("H )FQT.W-E929G=#MS=')E86TF;'0[
M+W-E929G=#L-





M;&P 8F4 :6YC;'5D960 :6X 9&]C=6UE;G1A=&EO;B!F;VQL;W=I;F< =&AE
M('9E<G-I;VYI;F< <V-H96UE+CPO<#X-" T*/& Q/D-O;7!I;&%T;VX <')O






M/"]H,CX-" T*/& Q/D)E<W0 <')A8W1I8V5S/"]H,3X-" T*/& R/D$ 4W1Y

M=&EP<R!A;F0 8V]N=F5N=&EO;G, 9F]R('=R:71I;F< 9&5S8W)I<'1I;VYS


M<#Y7:&5N('-P96-I9GEI;F< 9&%T82!S=6-H(&%S(&1A=&5S(&%N9"!T:6UE
M<R!U<V4 86-C97!T960-"B  ('-T86YD87)D<R!S=6-H(&%S($E33SH\+W ^


M"CQH-#Y/;6ET('!A<F5N=&AE<V5S(&9O<B!T:&4 9V5N97)A;"!F;W)M(&]F

M<FEN9R!T;R!A(&UE=&AO9"!O<B!C;VYS=')U8W1O<B!T:&%T(&AA<R!M=6QT
M:7!L92!F;W)M<RP 86YD('EO=2!M96%N('1O(')E9F5R('1O(&$ <W!E8VEF
M:6, 9F]R;2P =7-E('!A<F5N=&AE<V5S(&%N9"!A<F=U;65N="!T>7!E<RX 
M1F]R(&5X86UP;&4L($%R<F%Y3&ES="!H87, ='=O(&%D9"!M971H;V1S.B!A



M+W!R93X-" T*/' ^2&]W979E<BP :68 <F5F97)R:6YG('1O(&)O=&  9F]R
M;7, ;V8 =&AE(&UE=&AO9"P ;VUI="!T:&4 <&%R96YT:&5S97, 86QT;V=E
M=&AE<BX 270 :7, ;6ES;&5A9&EN9R!T;R!I;F-L=61E(&5M<'1Y('!A<F5N
M=&AE<V5S+"!B96-A=7-E('1H870 =V]U;&0 :6UP;'D 82!P87)T:6-U;&%R
M(&9O<FT ;V8 =&AE(&UE=&AO9"X 5&AE(&EN=&5N="!H97)E(&ES('1O(&1I
M<W1I;F=U:7-H('1H92!G96YE<F%L(&UE=&AO9"!F<F]M(&%N>2!O9B!I=', 
M<&%R=&EC=6QA<B!F;W)M<RX 26YC;'5D92!T:&4 =V]R9" B;65T:&]D(B!T
M;R!D:7-T:6YG=6ES:"!I="!A<R!A(&UE=&AO9"!A;F0 ;F]T(&$ 9FEE;&0N

M;R!I;G-E<G0 :71E;7,N("  (" H<')E9F5R<F5D*0T*("!4:&4 861D*"D 
M;65T:&]D(&5N86)L97, >6]U('1O(&EN<V5R="!I=&5M<RX (" H879O:60 
M=VAE;B!Y;W4 ;65A;B B86QL(&9O<FUS(B!O9B!T:&4 861D(&UE=&AO9"D-


M=', ;V8 8G)E=FET>2!T:&ES(&-O=6QD(&)E('5S960N(%1H:7, :&]L9', 
M97-P96-I86QL>2!I;B!T:&4 :6YI=&EA;"!S=6UM87)Y(&%N9"!I;B!P87)A

M<G-O;B H9&5S8W)I<'1I=F4I(&YO=" R;F0 <&5R<V]N("AP<F5S8W)I<'1I


M=&EV92X\<#X-" T*/'!R93X-"B  1V5T<R!T:&4 ;&%B96PN("  (" H<')E
M9F5R<F5D*0T*("!'970 =&AE(&QA8F5L+B  ("  ("AA=F]I9"D-"CPO<')E

M8B!P:')A<V4N/"]H-#X-"CQP/D$ ;65T:&]D(&EM<&QE;65N=', 86X ;W!E
M<F%T:6]N+"!S;R!I="!U<W5A;&QY('-T87)T<R!W:71H(&$ =F5R8B!P:')A
M<V4N/"]H-#X-" T*/'!R93X-"B  1V5T<R!T:&4 ;&%B96P ;V8 =&AI<R!B


M93X-" T*/& T/D-L87-S+VEN=&5R9F%C92]F:65L9"!D97-C<FEP=&EO;G, 
M8V%N(&]M:70 =&AE('-U8FIE8W0N/"]H-#X-" T*/' ^('1H97D 8V%N('-I
M;7!L>2!S=&%T92!T:&4 ;V)J96-T+B!4:&5S92!!4$D ;V9T96X 9&5S8W)I
M8F4 =&AI;F=S(')A=&AE<B!T:&%N(&%C=&EO;G, ;W( 8F5H879I;W)S.CPO
M<#X-" T*/'!R93X-"B  02!B=71T;VX ;&%B96PN("  ("  ("  (" H<')E
M9F5R<F5D*0T*("!4:&ES(&9I96QD(&ES(&$ 8G5T=&]N(&QA8F5L+B  ("AA

M:&4B/"]H-#X-" T*/' ^5VAE;B!R969E<G)I;F< =&\ 86X ;V)J96-T(&-R
M96%T960 9G)O;2!T:&4 8W5R<F5N="!C;&%S<R!I<R!P<F5F97)R960 =7-E
M(&$ ;6]R92!S<&5C:69I8R!W;W)D+B!&;W( 97AA;7!L92P =&AE(&1E<V-R
M:7!T:6]N(&]F('1H92!G9714;V]L:VET(&UE=&AO9"!S:&]U;&0 <F5A9"!A
M<R!F;VQL;W=S.CPO<#X-" T*/'!R93X-"B  1V5T<R!T:&4 =&]O;&MI="!F


M93X-" T*/& T/D%D9"!D97-C<FEP=&EO;B!B97EO;F0 =&AE($%022!N86UE

M=6UE;G1I;F<B+"!M96%N:6YG('1H97D =&5L;"!Y;W4 8F%S:6-A;&QY('=H
M870 =&AE($%022!D;V5S+B!)9B!T:&4 9&]C(&-O;6UE;G0 ;65R96QY(')E
M<&5A=', =&AE($%022!N86UE(&EN('-E;G1E;F-E(&9O<FTL(&ET(&ES(&YO
M="!P<F]V:61I;F< ;6]R92!I;F9O<FUA=&EO;BX 1F]R(&5X86UP;&4L(&EF
M(&UE=&AO9"!D97-C<FEP=&EO;B!U<V5S(&]N;'D =&AE('=O<F1S('1H870 
M87!P96%R(&EN('1H92!M971H;V0 ;F%M92P =&AE;B!I="!I<R!A9&1I;F< 
M;F]T:&EN9R!A="!A;&P =&\ =VAA="!Y;W4 8V]U;&0 :6YF97(N(%1H92!I
M9&5A;"!C;VUM96YT(&=O97, 8F5Y;VYD('1H;W-E('=O<F1S(&%N9"!S:&]U
M;&0 86QW87ES(')E=V%R9"!Y;W4 =VET:"!S;VUE(&)I="!O9B!I;F9O<FUA
M=&EO;B!T:&%T('=A<R!N;W0 :6UM961I871E;'D ;V)V:6]U<R!F<F]M('1H

M87ES(&YO=&AI;F< 8F5Y;VYD('=H870 >6]U(&MN;W< 9G)O;2!R96%D:6YG
M('1H92!M971H;V0 ;F%M92X 5&AE('=O<F1S(")S970B+" B=&]O;"(L(")T
M:7 B+"!A;F0 (G1E>'0B(&%R92!S:6UP;'D <F5P96%T960 :6X 82!S96YT
M96YC92X 270G<R!B971T97( /&(^879O:60\+V(^('1H:7, 9F]R;2!O9B!D

M92!T;V]L('1I<"!T97AT+ T*("  * T*("  *B F;'0[<&%R86T ;F%M93TB
M=&5X="(F9W0[5&AE('1E>'0 ;V8 =&AE('1O;VP =&EP+B9L=#LO<&%R86TF


M(&-O;7!L971E;'D 9&5F:6YE<R!W:&%T(&$ =&]O;"!T:7  :7,L(&EN('1H
M92!L87)G97( 8V]N=&5X="!O9B!R96=I<W1E<FEN9R!A;F0 8F5I;F< 9&ES
M<&QA>65D(&EN(')E<W!O;G-E('1O('1H92!C=7)S;W(N(%1H:7, 9F]R;2!I
M<R!P<F5F97)R960 :6X 8V]M<&%R:7-O;B!W:71H('1H92!F:7)S="X\+W ^


M87ES('=H96X =&AE(&-U<G-O<B!L:6YG97)S(&]V97( =&AE(&-O;7!O;F5N
M="X-"B  ("H-"B  ("H )FQT.W!A<F%M(&YA;64](G1E>'0B)F=T.U1H92!S

M('1H92!T;V]L('1I<"!I<R!T=7)N960 ;V9F(&9O<B!T:&ES(&-O;7!O;F5N
M="XF;'0[+W!A<F%M)F=T.PT*("  *B\-"B  <'5B;&EC('9O:60 <V5T5&]O


M92!A=V%R92!T:&%T('1H92!C;VUM;VX =V]R9"!A<R B9FEE;&0B(&-A;B!H
M879E(&UA;GD ;65A;FEN9W, 86YD(&-A;B!C;VYF=7-E('1H92!R96%D97(N

M;F]W;B!A<R( :6YS=&5A9"!O9B B86MA(BP =7-E(")T:&%T(&ES(B!O<B B
M=&\ 8F4 <W!E8VEF:6,B(&EN<W1E860 ;V8 (FDN92XB+"!U<V4 (F9O<B!E
M>&%M<&QE(B!I;G-T96%D(&]F(")E+F<N(BP 86YD('5S92 B:6X ;W1H97( 
M=V]R9',B(&]R(")N86UE;'DB(&EN<W1E860 ;V8 (G9I>BXB/"]P/ T*/"]B

`
end
Jul 14 2002
next sibling parent "anderson" <anderson firestar.com.au> writes:
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Some good points. I like the XML (although it'll mean more typing). What =
will happen if the D file is saved as a html? You'd have to do a bit of =
stuffing I supose. Parhaps that should be in the documentation.
  "OddesE" <OddesE_XYZ hotmail.com> wrote in message =
news:agt6me$9ht$1 digitaldaemon.com...
  Source code documentation with coddocI read the document, and I think =
it is
  a very good initiative.
  We definitely need some kind of standard for this, or we will
  end up with a whole bunch of similar standards that differ in
  just enough respect to be a pain in the you-know-where.

  I do propose one big and a whole bunch of small alterations
  to the standard. I have marked sections that I have added in
  green, comments in red and sections that I think should be
  deleted in gray.

  The text that still is black also had changes in them, but
  these are just small things such as corrected spelling
  errors, they don't change the standard in any way.

  The modified file is attached.


  --
  Stijn
  OddesE_XYZ hotmail.com
  http://OddesE.cjb.net
  _________________________________________________
  Remove _XYZ from my address when replying by mail
Jul 14 2002
prev sibling next sibling parent reply Juarez Rudsatz <juarez nowhere.com> writes:
Hi,

    	I busy right now. I will read carefuly all posts and reply late. I 
think the initiative must not be closed. And many "D" people should 
contribute. 

"OddesE" <OddesE_XYZ hotmail.com> wrote in
news:agt6me$9ht$1 digitaldaemon.com: 


 Source code documentation with coddocI read the document, and I think
 it is a very good initiative.
 We definitely need some kind of standard for this, or we will
 end up with a whole bunch of similar standards that differ in
 just enough respect to be a pain in the you-know-where.
 
 I do propose one big and a whole bunch of small alterations
 to the standard. I have marked sections that I have added in
 green, comments in red and sections that I think should be
 deleted in gray.
 
 The text that still is black also had changes in them, but
 these are just small things such as corrected spelling
 errors, they don't change the standard in any way.
 
 The modified file is attached.
 
 --
 Stijn
 OddesE_XYZ hotmail.com
 http://OddesE.cjb.net
 _________________________________________________
Jul 15 2002
parent reply "Sean L. Palmer" <seanpalmer earthlink.net> writes:
Some D people Just Don't Care that much about Standardized Documentation.
I'm sure you guys will come up with something good.

Sean

"Juarez Rudsatz" <juarez nowhere.com> wrote in message
news:Xns924C7EB89CDB6juarezcom 63.105.9.61...

     I busy right now. I will read carefuly all posts and reply late. I
 think the initiative must not be closed. And many "D" people should
 contribute.
Jul 15 2002
parent "OddesE" <OddesE_XYZ hotmail.com> writes:
"Sean L. Palmer" <seanpalmer earthlink.net> wrote in message
news:agv4b1$2cb9$1 digitaldaemon.com...

 Some D people Just Don't Care that much about Standardized Documentation.
 I'm sure you guys will come up with something good.

 Sean




Have you ever used programs like DoxyGen or JavaDoc?
They rule! I have an assertion that says:
"If your public class or function is not documented,
it might as well be private."
It is a little rough, but think of the undocumented
Windows API functions, or undocumented Delphi classes
or functions, and it is (kinda :) true.

Good documentation helps code-reuse, and thus it
is important.

Tools like Javadoc have really helped, but Javadoc
is a standard tool in the Java SDK. If we as the
D community want such tools too, we have to find
someone crazy enough to build one. It would be cool
if it would be built to a standard that was reached
in concensus, instead of to the whims of whoever
was designing it at that point...

Fortunately Walter has made all the parsing code
open source and published it, so that should help
someone wanting to do an implementation.


--
Stijn
OddesE_XYZ hotmail.com
http://OddesE.cjb.net
_________________________________________________
Remove _XYZ from my address when replying by mail
Jul 16 2002
prev sibling parent reply Juarez Rudsatz <juarez nowhere.com> writes:
I wanna discuss the proposal about xml:

<quoted from="post" author="OddesE" day="dom">

As you will see in the next section I propose a change in the standard that 
is pretty big. I say we change the way tags are described to a method that 
is essentially xml compliant. There are a few reasons for this:

- xml is a standard. ;) 
- xml has been well thought out and will most likely be more easy to write 
a parser for, but better still, we probably don't even have to do this, 
because we can use an existing parser. 
xml is well known so people will probably understand it easier. 
- This way we don't have to differentiate between single-line and multi-
line tags. 
- You can write a dtd or schema which states the rules for comments in a 
machine readable way, so checking if the code is ok could be automatic. 
- You can write an xslt stylesheet for translating the xml code to other 
document formats. 
- The code to parse xml, check it's syntax using schema's or dtd's and 
transforming it into other documents using stylesheets has already been 
written, and is available, for free, on almost any platform and in almost 
any language. This would greatly simplify the creation of a DDoc 
application. 

</quoted>
  

Basically the reasons for adopting xml as commenting are:

- xml is standart and well known
- The syntax is strong
- Could be easy write a program to parse comments with xml
- You can use already coded programs to simplify generation of programs

    	I have thinked about using xml. But IMHO xml don't satisfy all 
objectives of a documentation tool.
    	Some of objectives for me are:

1 - Programmer must do the minimal effort possible
2 - The documentation in source code must be clear
3 - Syntax must be strong and non ambigous
4 - Syntax must be flexible enough for the tools generate many formats as 
possible

I have looked in documentation of some tools, like Javadoc, doxygen and so 
on. My motivation for using the format proposed is :

* author: name
* <author>name</author>
*  author: name

    	The first is more intuitiv, clear and easy to write. The tools can 
easily parse documents like this and couldn't be so hard to write a lexer 
or a parse for this.
    	The xml form is not so clear as the first and adds unnecessary 
garbage, the closing tag. Once the comments can have a visual effect 
newlines can be used for end-of-element parsing. I think using xml we pass 
to programmer the work what must be of compiler. So IMHO the xml fails in 
(1) and (2).
    	All good points for xml came from it can satisfy (3) and (4). 
    	For (4) I have thinked in a simple solution : decouple the document 
generation from document parsing. The tool must not generate a final 
document. Is best, for example, generate a xml docbook and than apply a new 
tool for generating the document, jade, xlst, etc... But this is work for a 
compiler ( for human knowledge to general programming format like xml ).
    	The problem is (3) yet. I don't sure syntax proposed is non-ambiguos 
or easy to parse. But the problems must be stripped or remodeled. For 
example, the tag parameters in the proposed syntax are ugly.
    	
    	I think this is the first point to discuss and define. And maturing a 
little bit more could be good. 
    	The all post until now have been good and showed anothers 
perspectives for the documentation. Let's continue...

Juarez Rudsatz

"OddesE" <OddesE_XYZ hotmail.com> wrote in
news:agt6me$9ht$1 digitaldaemon.com: 


 Source code documentation with coddocI read the document, and I think
 it is a very good initiative.
 We definitely need some kind of standard for this, or we will
 end up with a whole bunch of similar standards that differ in
 just enough respect to be a pain in the you-know-where.
 
 I do propose one big and a whole bunch of small alterations
 to the standard. I have marked sections that I have added in
 green, comments in red and sections that I think should be
 deleted in gray.
 
 The text that still is black also had changes in them, but
 these are just small things such as corrected spelling
 errors, they don't change the standard in any way.
 
 The modified file is attached.
Jul 16 2002
next sibling parent reply "anderson" <anderson firestar.com.au> writes:
If the docgen program supported both XML and ":" (and I'm not saying that's
a good idea), which would you end up using? I would and up using the ":"
format because it's so much faster to type. It requires no duplication, only
one shift key and looks neat.
Jul 16 2002
parent reply "Sean L. Palmer" <seanpalmer earthlink.net> writes:
XML and HTML are meant to be generated by tools, not typed in by hand.
Right-click, select Insert Documentation | Comment....  Just like
autocomplete does today, the editor could watch for /* and // and create
comment blocks for you.  During save or before passing to the compiler it
could transform them back to /*abc*/ and //abc with special tags.  I suppose
you guys are deciding what the tags should be.

Sean

"anderson" <anderson firestar.com.au> wrote in message
news:ah2uid$63r$1 digitaldaemon.com...

 If the docgen program supported both XML and ":" (and I'm not saying


that's

 a good idea), which would you end up using? I would and up using the ":"
 format because it's so much faster to type. It requires no duplication,


only

 one shift key and looks neat.
Jul 17 2002
parent reply "anderson" <anderson firestar.com.au> writes:
"Sean L. Palmer" <seanpalmer earthlink.net> wrote in message
news:ah379p$hbh$1 digitaldaemon.com...

 XML and HTML are meant to be generated by tools, not typed in by hand.
 Right-click, select Insert Documentation | Comment....  Just like
 autocomplete does today, the editor could watch for /* and // and create
 comment blocks for you.  During save or before passing to the compiler it
 could transform them back to /*abc*/ and //abc with special tags.  I


suppose

 you guys are deciding what the tags should be.



 Sean


Exactly. OddesE was suggesting that we use XML for the text comment
formating, not the generator. The most of these tags are definded in Juarez
Rudastz first document. They may just need a bit of tweeking (where I don't
know).
Jul 17 2002
parent reply "OddesE" <OddesE_XYZ hotmail.com> writes:
I guess you are all right... :)
When writing the document I was also running into
the fact that the xml is too verbose to type by hand.
I think Juarez solution, parse source code comments,
generate intermediate xml and from that generate
resulting documentation, is best. I just wanted to show
another way of doing it.
But there still remain some issues with Juarez'
proposed syntax. Especially when to know if a tag
closes...EOL is good for single line tags, but what
if I have an author with a really long name or
something? Maybe we could use some kind of 'continue
on next line tag, like this:

/**
 * author: My author with a very long name must :-->
 * be continued on the next line.
**/

Or, how about mixing them?
Use the colon notation for single line tags, which
must end at the end of line, and use xml-style notation
if you need more than one line:

/**
 * author: OddesE
 * <author>My author with a very long name must
 * be continued on the next line.</author>
**/

With the very long contents of the second tag,
having to write a closing tag becomes less of a
burden. Plus, in practice allmost all tags are
one line, so generally you would have the
advantage of the colon notation.


--
Stijn
OddesE_XYZ hotmail.com
http://OddesE.cjb.net
_________________________________________________
Remove _XYZ from my address when replying by mail
Jul 17 2002
parent reply "anderson" <anderson firestar.com.au> writes:
 something? Maybe we could use some kind of 'continue
 on next line tag, like this:

 /**
  * author: My author with a very long name must :-->
  * be continued on the next line.
 **/


If line continuation must be known then I'd propose _ like VB uses. But I
don't think it's nessary.


 Or, how about mixing them?
 Use the colon notation for single line tags, which
 must end at the end of line, and use xml-style notation
 if you need more than one line:

 /**
  * author: OddesE
  * <author>My author with a very long name must
  * be continued on the next line.</author>
 **/


I thought of that also but tossed out the idea. A return is simple enough to
determine a new line.


 /**
  * author: OddesE
  * author: My author with a very long name must
  * be continued on the next line.
 **/


The end of a tag definition can be found at either the start of the next tag
or the end of the comment.


 With the very long contents of the second tag,
 having to write a closing tag becomes less of a
 burden. Plus, in practice allmost all tags are
 one line, so generally you would have the
 advantage of the colon notation.


I'd also propose that </> be used to indicate end of line (If it must be
known). But I don't think this is necessary.

And if you want to use XML code still.

/**
 * author: OddesE
 * <author>My author with a very long name must
 * be continued on the next line.</>
**/

But that's still worse then.

/**
 * author: OddesE
 * author: My author with a very long name must
 * be continued on the next line.
**/

Even javaDoc did that.

It should be noted that XML is used for hierarchical data. ie <B><I></I></B>
and this documentation form doesn't need that.
Jul 17 2002
next sibling parent Juarez Rudsatz <juarez nowhere.com> writes:
Hi all,

    	Some comments :

"anderson" <anderson firestar.com.au> wrote in
news:ah41br$1dih$1 digitaldaemon.com: 


 
 I thought of that also but tossed out the idea. A return is simple
 enough to determine a new line.
 

 /**
  * author: OddesE
  * author: My author with a very long name must
  * be continued on the next line.
 **/


 
 The end of a tag definition can be found at either the start of the
 next tag or the end of the comment.
 

 With the very long contents of the second tag,
 having to write a closing tag becomes less of a
 burden. Plus, in practice allmost all tags are
 one line, so generally you would have the
 advantage of the colon notation.




    	I think exists a regular expression, commonly used in lex, for 
lexing the format. If one regexp could be found then the sintax is not 
ambiguos. Please correct if I am wrong.

STARTDOC = '/**'['*']*\b
ENDDOC = ['*']'**/'
SINLINEDOC = '//*'\b
IDENTATION = [\b\t]*'*'\b
TAG = [a-z][a-z]*':'
TEXT = .

    	Someone could correct this ?
Jul 17 2002
prev sibling parent reply "OddesE" <OddesE_XYZ hotmail.com> writes:
"anderson" <anderson firestar.com.au> wrote in message
news:ah41br$1dih$1 digitaldaemon.com...


<SNIP suggestion by me for mixing xml and colon syntax>

 I thought of that also but tossed out the idea. A return is simple enough


to

 determine a new line.


 /**
  * author: OddesE
  * author: My author with a very long name must
  * be continued on the next line.
 **/


 The end of a tag definition can be found at either the start of the next


tag

 or the end of the comment.


Ok, but what about this:

/**
 * author: OddesE
 * author: My author with a very long name must
 * be continued on the next line.
 * This module serves the purpose of demonstrating
 * examples of code comments.
**/
module test;


Ways to prevent problems here could be:
- Mandating that properties come after the comment text
- Mandating an empty line between properties and comment text
- Line-continue tokens such as suggested
- Closing tags such as suggested

I guess that mandating an empty line between properties and
comment tags is easy and looks natural:

/**
 * author: OddesE
 * author: My author with a very long name must
 * be continued on the next line.
 *
 * This module serves the purpose of demonstrating
 * examples of code comments.
**/
module test;

Ofcourse there are no problems when the comment text
is followed by properties instead of being preceded
by them.



 It should be noted that XML is used for hierarchical data. ie


<B><I></I></B>

 and this documentation form doesn't need that.


I guess you are right about that.


--
Stijn
OddesE_XYZ hotmail.com
http://OddesE.cjb.net
_________________________________________________
Remove _XYZ from my address when replying by mail



 Jul 19 2002



  parent  Juarez Rudsatz <juarez nowhere.com>  writes:


"OddesE" <OddesE_XYZ hotmail.com> wrote in news:ah95mq$2afp$1
 digitaldaemon.com:


 
 I guess that mandating an empty line between properties and
 comment tags is easy and looks natural:
 


    	I agree with the comment about the statement can be writed before the 
tags or need a empty line. 



 Jul 19 2002



prev sibling  parent reply Juarez Rudsatz <juarez nowhere.com>  writes:


Juarez Rudsatz <juarez nowhere.com> wrote in
news:Xns924D92B1EB48Djuarezcorreiocom 63.105.9.61: 


          The problem is (3) yet. I don't sure syntax proposed is
          non-ambiguos 
 or easy to parse. But the problems must be stripped or remodeled. For 
 example, the tag parameters in the proposed syntax are ugly.
 


    	I have seen the form is used in mail specification for parameters:

MIME-version: 1.0
MIME-encoding: 7 bit

    	Enabling this "subtags" could be a good form of dealing with 
parameters for comments ? What do you think ? There are another good way ?

E.g.:

/**
 * copyright: Pavel "EvilOne" Minayev
 * copyright-date: 2001
 * license : GPL
 * license-site : http://www.gnu.org/copyleft/gpl.html
 * version : 2.95.0.3
 * version-status : stable
 * bug : Windows 9x does not pass the correct memory used
 * bug-severity : low
 **/



 Jul 17 2002



  parent  "anderson" <anderson firestar.com.au>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable


"Juarez Rudsatz" <juarez nowhere.com> wrote in message =
news:Xns924E86EA83162juarezcorreiocom 63.105.9.61...

 Juarez Rudsatz <juarez nowhere.com> wrote in
 news:Xns924D92B1EB48Djuarezcorreiocom 63.105.9.61:=20
=20

          The problem is (3) yet. I don't sure syntax proposed is
          non-ambiguos=20
 or easy to parse. But the problems must be stripped or remodeled. =




For=20

 example, the tag parameters in the proposed syntax are ugly.
=20


=20
     I have seen the form is used in mail specification for parameters:
=20
 MIME-version: 1.0
 MIME-encoding: 7 bit
=20
     Enabling this "subtags" could be a good form of dealing with=20
 parameters for comments ? What do you think ? There are another good =


way ?

=20
 E.g.:
=20
 /**
  * copyright: Pavel "EvilOne" Minayev
  * copyright-date: 2001
  * license : GPL
  * license-site : http://www.gnu.org/copyleft/gpl.html
  * version : 2.95.0.3
  * version-status : stable
  * bug : Windows 9x does not pass the correct memory used
  * bug-severity : low
  **/


Looks good, although I don't know how often I'd use it. It'd be good for =
project programming. I guess if its there... I'd be nice if there was =
some central base for bug produced by the gen (perhaps optional). This =
way you could quickly find bugs to attempt to fix.

How about,

* bug-fixed : Windows 9x does not pass the correct memory used

for fixed bugs (simply add the -fixed to bug)
Also bugs should have optional titles as it makes things easier to fix =
if bugs have long definitions.

* bug-name : Win9x memory error

And also how about a company logo that will be placed on every page =
(next to copy write)

* logo : logo.gif=20

And a=20

* Updated : 2002.10.10

Although that could be determined though the file's attributes by =
default for the class; file dates are not always a correct indication of =
an update and not every method in a class will be updated every time.


-------------------------------------------------------------------------=
-------


On another note

I'd think it would be also be nice to have the gen program produce html =
documents from a html templates. Of corse there would be a default one =
that comes with the program that you could customise.

You'd probably have these templates:

Index.htm - Frame based page
SideBar.htm - Hierarchical side bar
Class.htm - Class layout template
Method.htm - Methods layout
Property.htm - Property layout

Of course more though needs to be put into that.

Basically the generation program would copy the files as needed and look =
for special tags in the files to replace with code from the files. A bit =
of though will have to go into how list will be produced. Perhaps an XML =
derivative (without need for closing except on lists) could be used as =
tags in the html template files.

For example
(Although I don't like the extra typyness of xml it could be used for =
lists.)

...Sample html template code for Class...

//Other html code...

[CLASS]
<H1>[CLASS NAME]</H1>
Version : <B>[CLASS VERSION]</B>

[METHOD LIST]

<H2>[METHOD NAME/]</H2>
[COMMENT/]
<I>[AUTHOR/]</I>
<TAB>Version: <B>[VERSION/]</B></TAB>
[/METHOD LIST]

[/CLASS]

//Other html code...

The gen would search for the square brackets (I don't care what is used, =
except <> will be confided with html) and replace them with actual =
comments.

This way pages could be enhanced for the particular operation. I know =
it's good to have a common standard, but what if - say a company want to =
make all the pages in the same style as there webpage. It would be far =
easier to do this with template html. Also this would mean the layout of =
the gen could be improved over time. If I had time (an I don't) I'd =
program this myself in D as it doesn't look like a very tough job (but I =
could be wrong).



 Jul 17 2002



prev sibling next sibling parent reply "anderson" <anderson firestar.com.au>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Source code documentation with coddocThis is more of a doc generation =
suggestion.  I think it would be good if of doc generator had some =
infromation about the line number where the code begins. This would help =
enable furture IDE's to use the documentation as a basics for the IDE =
layout.

I know I've said this before, but It would be cool if the docgen could =
produce code in an uml format.

PS - Robert M. M=FCnch tool produces quite nice output, and I'd =
recommend it for this "Code documentation attachement". Also it mite be =
an idea for the D Journal if documents are to be produced to some =
standard (although it may mean extra reformating work). It handles code =
segments especially well (by picking up tabs).



 Jul 15 2002



  parent reply "Robert M. Münch" <robert.muench robertmuench.de>  writes:


Source code documentation with coddocHi, thanks a lot. There is something
that comes to mind: D can compile HTML files! So it maybe best to include D
code into the documentation and not documentation into D code. My script
could easly be changed to produce a compileable output file. With this we
would be able to move more into the WEB idea of litteral programming. Code
is already recognized as mentioned. What do you think? Robert


"anderson" <anderson firestar.com.au> schrieb im Newsbeitrag
news:ah0fv5$m3f$1 digitaldaemon.com...
PS - Robert M. Münch tool produces quite nice output, and I'd recommend it
for this "Code documentation attachement". Also it mite be an idea for the D
Journal if documents are to be produced to some standard (although it may
mean extra reformating work). It handles code segments especially well (by
picking up tabs).



 Jul 16 2002



 next sibling parent  "Sean L. Palmer" <seanpalmer earthlink.net>  writes:


Just have the documentation have hyperlinks to the appropriate section of
the D file, and the D file has marker tags you can hyperlink to, one for
each thingy such as class or function.  It'd also be nice for a member
function to have a hyperlink to the class declaration, an import module
directive to have a hyperlink to that module, etc.  In fact these could be
generated automatically;  perhaps the compiler could insert them if
requested to do so.

Sean

"Robert M. Münch" <robert.muench robertmuench.de> wrote in message
news:ah0ggd$niq$1 digitaldaemon.com...

 Source code documentation with coddocHi, thanks a lot. There is something
 that comes to mind: D can compile HTML files! So it maybe best to include


D

 code into the documentation and not documentation into D code. My script
 could easly be changed to produce a compileable output file. With this we
 would be able to move more into the WEB idea of litteral programming. Code
 is already recognized as mentioned. What do you think? Robert


 "anderson" <anderson firestar.com.au> schrieb im Newsbeitrag
 news:ah0fv5$m3f$1 digitaldaemon.com...
 PS - Robert M. Münch tool produces quite nice output, and I'd recommend it
 for this "Code documentation attachement". Also it mite be an idea for the


D

 Journal if documents are to be produced to some standard (although it may
 mean extra reformating work). It handles code segments especially well (by
 picking up tabs).





 Jul 16 2002



prev sibling next sibling parent reply "anderson" <anderson firestar.com.au>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Perhaps, there could be automatic hierarchical generation in some docgen =
like program. I think something along these lines was mentioned before =
(except it was compiler based). The hierarchical generator would simply =
scan all the D html files and built a code map, possibly using a UML =
derivative.  It would also generate a framed index file. So I still see =
a need for tags.=20

  The program could reformat these tags and automatically add things =
like see. This would provide a way to have automatically generated =
comments in the code itself not just the html. Now if someone is using a =
text editor for D, this could make things messy so the html (or xhtml) =
would have to be kept neat in a text form as well. There could also be =
special tags to indicate not to do certain things.=20

      /**
       * <author>Micky mouse</author>
       * <version>1.0</version>
       *
       *  The does blah blah blah blah blah blah blah blah blah blah =
blah blah=20
      *   blah blah blah blah blah blah blah blah blah blah blah blah =
blah blah=20
      *   blah blah blah blah blah=20
      **/
void func(int a)
{
...
}

Would change to
  void func(int a)
      Parameters

      a : Unknown
    =20



      The does blah blah blah blah blah blah blah blah blah blah blah =
blah blah blah blah blah blah blah blah blah blah blah blah blah blah =
blah blah blah blah blah blah=20

      Micky mouse

      See
             func2, func3
          =20




      V 1.0
    =20


      =20

      {

      ...
      }=20

=20


Anyway that's just an idea of a possible layout (athough it'll need alot =
more work).  The docGen should reconise both formats so that it can =
reconise what it has generated. Also classes could be done in a UML =
style by dividing the varaibles from the functions.

"Robert M. M=FCnch" <robert.muench robertmuench.de> wrote in message =
news:ah0ggd$niq$1 digitaldaemon.com...

 Source code documentation with coddocHi, thanks a lot. There is =


something

 that comes to mind: D can compile HTML files! So it maybe best to =


include D

 code into the documentation and not documentation into D code. My =


script

 could easly be changed to produce a compileable output file. With this =


we

 would be able to move more into the WEB idea of litteral programming. =


Code

 is already recognized as mentioned. What do you think? Robert
=20
=20
 "anderson" <anderson firestar.com.au> schrieb im Newsbeitrag
 news:ah0fv5$m3f$1 digitaldaemon.com...
 PS - Robert M. M=FCnch tool produces quite nice output, and I'd =


recommend it

 for this "Code documentation attachement". Also it mite be an idea for =


the D

 Journal if documents are to be produced to some standard (although it =


may

 mean extra reformating work). It handles code segments especially well =


(by

 picking up tabs).
=20
=20





 Jul 16 2002



  parent reply "OddesE" <OddesE_XYZ hotmail.com>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

  "anderson" <anderson firestar.com.au> wrote in message =
news:ah0pub$111p$1 digitaldaemon.com...
  Perhaps, there could be automatic hierarchical generation in some =
docgen like program. I think something along these lines was mentioned =
before (except it was compiler based). The hierarchical generator would =
simply scan all the D html files and built a code map, possibly using a =
UML derivative.  It would also generate a framed index file. So I still =
see a need for tags.=20

    The program could reformat these tags and automatically add things =
like see. This would provide a way to have automatically generated =
comments in the code itself not just the html. Now if someone is using a =
text editor for D, this could make things messy so the html (or xhtml) =
would have to be kept neat in a text form as well. There could also be =
special tags to indicate not to do certain things. =20

        /**
         * <author>Micky mouse</author>
         * <version>1.0</version>
         *
         *  The does blah blah blah blah blah blah blah blah blah blah =
blah blah=20
        *   blah blah blah blah blah blah blah blah blah blah blah blah =
blah blah=20
        *   blah blah blah blah blah=20
        **/
  void func(int a)
  {
  ...
  }

  Would change to
    void func(int a)
        Parameters

        a : Unknown
      =20



        The does blah blah blah blah blah blah blah blah blah blah blah =
blah blah blah blah blah blah blah blah blah blah blah blah blah blah =
blah blah blah blah blah blah=20

        Micky mouse

        See
               func2, func3
            =20


        =20

        V 1.0
      =20




        {

        ...
        }=20

  =20


  Anyway that's just an idea of a possible layout (athough it'll need =
alot more work).  The docGen should reconise both formats so that it can =
reconise what it has generated. Also classes could be done in a UML =
style by dividing the varaibles from the functions.

  "Robert M. M=FCnch" <robert.muench robertmuench.de> wrote in message =
news:ah0ggd$niq$1 digitaldaemon.com...
  > Source code documentation with coddocHi, thanks a lot. There is =
something
  > that comes to mind: D can compile HTML files! So it maybe best to =
include D
  > code into the documentation and not documentation into D code. My =
script
  > could easly be changed to produce a compileable output file. With =
this we
  > would be able to move more into the WEB idea of litteral =
programming. Code
  > is already recognized as mentioned. What do you think? Robert
  >=20
  >=20
  > "anderson" <anderson firestar.com.au> schrieb im Newsbeitrag
  > news:ah0fv5$m3f$1 digitaldaemon.com...
  > PS - Robert M. M=FCnch tool produces quite nice output, and I'd =
recommend it
  > for this "Code documentation attachement". Also it mite be an idea =
for the D
  > Journal if documents are to be produced to some standard (although =
it may
  > mean extra reformating work). It handles code segments especially =
well (by
  > picking up tabs).
  >=20
  >=20

Yes I definitely agree with this.
Putting the code in an .html file is a nice feature for demo programs=20
that get posted on web sites, but it doesn't work so well for pure=20
documentation. I don't know if the people that mentioned this have=20
tried javadoc or doxygen, but creating documentation from source code=20
and embedding source code in .html are just two completely different=20
things. I don't see myself typing all the .html to create fancy layout=20
like above when writing a .d program. Also Javadoc and Doxygen create=20
hierarchical structures of your classes, summary and index files,=20
links from one class to the others that are mentioned and to its=20
parents, etc, etc, etc. Am I supposed to do this all by hand?

Even if I was willing and capable of doing all this by hand, I could=20
never benefit from other people using it to and all formats would be=20
radically different.

Just search the web for Java documentation. Notice how it is all=20
uniform and looks alike? This is because all this documentation is=20
generated using Javadoc. The 'embed d code in a .html file' technique=20
is not an option for documentation generation.


--=20
Stijn
OddesE_XYZ hotmail.com
http://OddesE.cjb.net
_________________________________________________
Remove _XYZ from my address when replying by mail



 Jul 16 2002



 next sibling parent  "anderson" <anderson firestar.com.au>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Sorry must have been a brake down in my comunication. I think javaDoc is =
cool. The code segment should be left out, parhaps an optional line =
number instead. In a D IDE it'd be good to have a switch that turns =
automatic html formating that could be toggled on and off that would do =
formating simular to the javaDoc (but with code segs).
  "OddesE" <OddesE_XYZ hotmail.com> wrote in message =
news:ah19po$1hh9$1 digitaldaemon.com...
    "anderson" <anderson firestar.com.au> wrote in message =
news:ah0pub$111p$1 digitaldaemon.com...
    Perhaps, there could be automatic hierarchical generation in some =
docgen like program. I think something along these lines was mentioned =
before (except it was compiler based). The hierarchical generator would =
simply scan all the D html files and built a code map, possibly using a =
UML derivative.  It would also generate a framed index file. So I still =
see a need for tags.=20

      The program could reformat these tags and automatically add things =
like see. This would provide a way to have automatically generated =
comments in the code itself not just the html. Now if someone is using a =
text editor for D, this could make things messy so the html (or xhtml) =
would have to be kept neat in a text form as well. There could also be =
special tags to indicate not to do certain things. =20

          /**
           * <author>Micky mouse</author>
           * <version>1.0</version>
           *
           *  The does blah blah blah blah blah blah blah blah blah blah =
blah blah=20
          *   blah blah blah blah blah blah blah blah blah blah blah =
blah blah blah=20
          *   blah blah blah blah blah=20
          **/
    void func(int a)
    {
    ...
    }

    Would change to
      void func(int a)
          Parameters

          a : Unknown
        =20



          The does blah blah blah blah blah blah blah blah blah blah =
blah blah blah blah blah blah blah blah blah blah blah blah blah blah =
blah blah blah blah blah blah blah=20

          Micky mouse

          See
                 func2, func3
              =20


          =20

          V 1.0
        =20




          {

          ...
          }=20

    =20


    Anyway that's just an idea of a possible layout (athough it'll need =
alot more work).  The docGen should reconise both formats so that it can =
reconise what it has generated. Also classes could be done in a UML =
style by dividing the varaibles from the functions.

    "Robert M. M=FCnch" <robert.muench robertmuench.de> wrote in message =
news:ah0ggd$niq$1 digitaldaemon.com...
    > Source code documentation with coddocHi, thanks a lot. There is =
something
    > that comes to mind: D can compile HTML files! So it maybe best to =
include D
    > code into the documentation and not documentation into D code. My =
script
    > could easly be changed to produce a compileable output file. With =
this we
    > would be able to move more into the WEB idea of litteral =
programming. Code
    > is already recognized as mentioned. What do you think? Robert
    >=20
    >=20
    > "anderson" <anderson firestar.com.au> schrieb im Newsbeitrag
    > news:ah0fv5$m3f$1 digitaldaemon.com...
    > PS - Robert M. M=FCnch tool produces quite nice output, and I'd =
recommend it
    > for this "Code documentation attachement". Also it mite be an idea =
for the D
    > Journal if documents are to be produced to some standard (although =
it may
    > mean extra reformating work). It handles code segments especially =
well (by
    > picking up tabs).
    >=20
    >=20

  Yes I definitely agree with this.
  Putting the code in an .html file is a nice feature for demo programs=20
  that get posted on web sites, but it doesn't work so well for pure=20
  documentation. I don't know if the people that mentioned this have=20
  tried javadoc or doxygen, but creating documentation from source code=20
  and embedding source code in .html are just two completely different=20
  things. I don't see myself typing all the .html to create fancy layout =

  like above when writing a .d program. Also Javadoc and Doxygen create=20
  hierarchical structures of your classes, summary and index files,=20
  links from one class to the others that are mentioned and to its=20
  parents, etc, etc, etc. Am I supposed to do this all by hand?

  Even if I was willing and capable of doing all this by hand, I could=20
  never benefit from other people using it to and all formats would be=20
  radically different.

  Just search the web for Java documentation. Notice how it is all=20
  uniform and looks alike? This is because all this documentation is=20
  generated using Javadoc. The 'embed d code in a .html file' technique=20
  is not an option for documentation generation.


  --=20
  Stijn
  OddesE_XYZ hotmail.com
  http://OddesE.cjb.net
  _________________________________________________
  Remove _XYZ from my address when replying by mail



 Jul 16 2002



prev sibling next sibling parent reply "Robert M. Münch" <robert.muench robertmuench.de>  writes:


"OddesE" <OddesE_XYZ hotmail.com> schrieb im Newsbeitrag
news:ah19po$1hh9$1 digitaldaemon.com....


tried javadoc or doxygen, but creating documentation from source code
and embedding source code in .html are just two completely different
things. I don't see myself typing all the .html to create fancy layout
like above when writing a .d program.


Hi, you don't have to that's what the generator will do for you.


Also Javadoc and Doxygen create
hierarchical structures of your classes, summary and index files,
links from one class to the others that are mentioned and to its
parents, etc, etc, etc. Am I supposed to do this all by hand?


No, but these are just some special sections/summaries/references the
generator can include.


Just search the web for Java documentation. Notice how it is all
uniform and looks alike? This is because all this documentation is
generated using Javadoc. The 'embed d code in a .html file' technique
is not an option for documentation generation.


Well, the literate programming people will say something different. Here is
a short example of how such a file could look like:

===Introduction
Bla bla

---Colors
Colors for syntax highlighting, default values are my preferences in
Microsoft Visual Studio editor

    class Colors
    {
     static char[] keyword = "0000FF";
     static char[] number = "008000";
     static char[] string = "000080";
     static char[] comment = "808080";
    }

etc.

The indented code will be compileable by D the rest will be used to generate
HTML output. That's easy! Adding all kinf of special source-code
documentation features shouldn't be a problem. Robert



 Jul 16 2002



  parent reply "anderson" <anderson firestar.com.au>  writes:


 Well, the literate programming people will say something different. Here


is

 a short example of how such a file could look like:

 ===Introduction
 Bla bla

 ---Colors
 Colors for syntax highlighting, default values are my preferences in
 Microsoft Visual Studio editor

     class Colors
     {
      static char[] keyword = "0000FF";
      static char[] number = "008000";
      static char[] string = "000080";
      static char[] comment = "808080";
     }

 etc.

 The indented code will be compileable by D the rest will be used to


generate

 HTML output. That's easy! Adding all kinf of special source-code
 documentation features shouldn't be a problem. Robert


I know you've looked into Javadoc and Doxygen, but they also remove all the
code body parts which your app doesn't do. In most documentation cases it is
important to hide the body and only show the header stuff. This means that
the hierarchical structures / summary and index files are the most important
aspects of the doc generation program.



 Jul 16 2002



  parent reply "Robert M. Münch" <robert.muench robertmuench.de>  writes:


"anderson" <anderson firestar.com.au> schrieb im Newsbeitrag
news:ah1mdt$1ugv$1 digitaldaemon.com...


 I know you've looked into Javadoc and Doxygen, but they also remove all


the

 code body parts which your app doesn't do.


Hi, my app doesn't do anything at the moment. I'm just thinking loud... It's
no problem to just keep the header stuff. But sometimes it even makes sense
to comment/explain your body. So both things should be supported very easy.


 In most documentation cases it is
 important to hide the body and only show the header stuff. This means that
 the hierarchical structures / summary and index files are the most


important

 aspects of the doc generation program.


As said, these are just summaries of all the information collected while
generating the output. So there is no problem to generate all kind of
summaries in different level of detail. The question I find most interesting
is how can we write code comfortable and add documentation where it needs to
be. What kind of syntax should be used, what features are needed, what's the
best usage pattern... etc. Of course it's a question of style but I don't
like hughe comment boxes and special comment characters sequences to
indicate what I want the output to look like. Of couse markup is needed but
it should be as userfriendly as possible.

--
Robert M. Münch
IT & Management Freelancer
Mobile: +49 (0)177 2452 802
Fax   : +49 (0)721 8408 9112
Web   : http://www.robertmuench.de



 Jul 16 2002



 next sibling parent reply "Sean L. Palmer" <seanpalmer earthlink.net>  writes:


I'd prefer the boxes to be done with HTML frames instead of ascii art.

Actual source code could go into <CODE> <D> for (int i=0; i<100; ++i) {
printf("D rocks!"); }</D> </CODE> blocks.  Which of course the editor
wouldn't show you.

Sean

"Robert M. Münch" <robert.muench robertmuench.de> wrote in message
news:ah345k$c5o$1 digitaldaemon.com...

 As said, these are just summaries of all the information collected while
 generating the output. So there is no problem to generate all kind of
 summaries in different level of detail. The question I find most


interesting

 is how can we write code comfortable and add documentation where it needs


to

 be. What kind of syntax should be used, what features are needed, what's


the

 best usage pattern... etc. Of course it's a question of style but I don't
 like hughe comment boxes and special comment characters sequences to
 indicate what I want the output to look like. Of couse markup is needed


but

 it should be as userfriendly as possible.





 Jul 17 2002



  parent reply "anderson" <anderson firestar.com.au>  writes:


Yes interesting point.

You could write a book on D IDE's before they even come out. More then most
languages I think that D would greatly from having it's own IDE. D code
would become much neater on the web then other code more efficiently
produced. I wouldn't be surprised if the D IDE had "an upload to web button"
included (just kidding).  I suppose D could probably go a lot further
(without abandoning the humble text editor) in supporting the IDE of the
future, but I can't think of it how.

At the moment were stuck with 1990 style IDE's, with a language that was
made for much classier IDE's. Most languages were born in the days of text
editors, so they never though about support for IDE's. Instead the IDE's

support IDE's. Those language (with exception of Java) I wouldn't dare
attempt without the supporting IDE. D supports the best of both worlds

which is a downer. Besides D is in it's alpha stage so a GUI object language
is long off I suppose.

"Sean L. Palmer" <seanpalmer earthlink.net> wrote in message
news:ah371f$h3i$1 digitaldaemon.com...

 I'd prefer the boxes to be done with HTML frames instead of ascii art.

 Actual source code could go into <CODE> <D> for (int i=0; i<100; ++i) {
 printf("D rocks!"); }</D> </CODE> blocks.  Which of course the editor
 wouldn't show you.

 Sean





 Jul 17 2002



  parent  "Walter" <walter digitalmars.com>  writes:


"anderson" <anderson firestar.com.au> wrote in message
news:ah5a2g$2rcv$1 digitaldaemon.com...

 Yes interesting point.

 You could write a book on D IDE's before they even come out. More then


most

 languages I think that D would greatly from having it's own IDE. D code
 would become much neater on the web then other code more efficiently
 produced. I wouldn't be surprised if the D IDE had "an upload to web


button"

 included (just kidding).  I suppose D could probably go a lot further
 (without abandoning the humble text editor) in supporting the IDE of the
 future, but I can't think of it how.


I have some familiarity with syntax directed editors, and how it is
impossible to get right for C and C++ without writing a nearly complete
compiler front end. In D, since the tokens and syntax is completely
independent of semantic analysis, it becomes easy to write syntax aware
editors.



 Aug 13 2002



prev sibling  parent  Juarez Rudsatz <juarez nowhere.com>  writes:


Hi all,

    	I have thinked in tag like "glossary" and "category" for generating 
indexes of hierarquical structures following different subjects.
    	It's possible generate indexes for each type of statement, classes, 
modules, functions, contants.
    	This appear to be sufficient IMHO. What do you think?

"Robert M. Münch" <robert.muench robertmuench.de> wrote in
news:ah345k$c5o$1 digitaldaemon.com: 


 "anderson" <anderson firestar.com.au> schrieb im Newsbeitrag
 news:ah1mdt$1ugv$1 digitaldaemon.com...
 

 I know you've looked into Javadoc and Doxygen, but they also remove
 all 


 the

 code body parts which your app doesn't do.


 
 Hi, my app doesn't do anything at the moment. I'm just thinking
 loud... It's no problem to just keep the header stuff. But sometimes
 it even makes sense to comment/explain your body. So both things
 should be supported very easy. 
 

 In most documentation cases it is
 important to hide the body and only show the header stuff. This means
 that the hierarchical structures / summary and index files are the
 most 


 important

 aspects of the doc generation program.


 
 As said, these are just summaries of all the information collected
 while generating the output. So there is no problem to generate all
 kind of summaries in different level of detail. The question I find
 most interesting is how can we write code comfortable and add
 documentation where it needs to be. What kind of syntax should be
 used, what features are needed, what's the best usage pattern... etc.
 Of course it's a question of style but I don't like hughe comment
 boxes and special comment characters sequences to indicate what I want
 the output to look like. Of couse markup is needed but it should be as
 userfriendly as possible. 
 
 --
 Robert M. Münch





 Jul 17 2002



prev sibling  parent reply "Sean L. Palmer" <seanpalmer earthlink.net>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Using a text editor as your main programming environment is dead.  Let's =
move on.

Sean
  Yes I definitely agree with this.
  Putting the code in an .html file is a nice feature for demo programs=20
  that get posted on web sites, but it doesn't work so well for pure=20
  documentation. I don't know if the people that mentioned this have=20
  tried javadoc or doxygen, but creating documentation from source code=20
  and embedding source code in .html are just two completely different=20
  things. I don't see myself typing all the .html to create fancy layout =

  like above when writing a .d program. Also Javadoc and Doxygen create=20
  hierarchical structures of your classes, summary and index files,=20
  links from one class to the others that are mentioned and to its=20
  parents, etc, etc, etc. Am I supposed to do this all by hand?

  Even if I was willing and capable of doing all this by hand, I could=20
  never benefit from other people using it to and all formats would be=20
  radically different.

  Just search the web for Java documentation. Notice how it is all=20
  uniform and looks alike? This is because all this documentation is=20
  generated using Javadoc. The 'embed d code in a .html file' technique=20
  is not an option for documentation generation.


  --=20
  Stijn
  OddesE_XYZ hotmail.com
  http://OddesE.cjb.net



 Jul 16 2002



  parent reply Jason Mills <jmills cs.mun.ca>  writes:


Sean L. Palmer wrote:

 Using a text editor as your main programming environment is dead.  Let's 
 move on.


I disagree. I do most of my programming using a text editor (vim/gvim) 
and the command line, so I'm not sure what you mean by the above 
statement. Given that I have not been following this thread closely, I 
may have misinterpreted you.


Jason



 Sean
 
     Yes I definitely agree with this.
     Putting the code in an .html file is a nice feature for demo programs
     that get posted on web sites, but it doesn't work so well for pure
     documentation. I don't know if the people that mentioned this have
     tried javadoc or doxygen, but creating documentation from source code
     and embedding source code in .html are just two completely different
     things. I don't see myself typing all the .html to create fancy layout
     like above when writing a .d program. Also Javadoc and Doxygen create
     hierarchical structures of your classes, summary and index files,
     links from one class to the others that are mentioned and to its
     parents, etc, etc, etc. Am I supposed to do this all by hand?
      
     Even if I was willing and capable of doing all this by hand, I could
     never benefit from other people using it to and all formats would be
     radically different.
      
     Just search the web for Java documentation. Notice how it is all
     uniform and looks alike? This is because all this documentation is
     generated using Javadoc. The 'embed d code in a .html file' technique
     is not an option for documentation generation.
      
 
     -- 
     Stijn
     OddesE_XYZ hotmail.com <mailto:OddesE_XYZ hotmail.com>
     http://OddesE.cjb.net
 





 Jul 16 2002



  parent reply "Sean L. Palmer" <seanpalmer earthlink.net>  writes:


There exist technological advancements that allow you to browse and edit
code easily, configure how you want the code to be displayed (important on
large teams where everyone has their own style preferences and you can't get
a team to agree on indentation and spacing issues,) and integrate debugging,
source control, creating whatever makefile or linker script you need, and
many other tools such as bitmap and dialog editors.  You may not need all of
this, but I kinda like it.

I guess to each his own, I'm not stopping you from living in the stone age,
but there are electric lights and running water nowadays.  ;)   That said,
I've seen some pretty sophisticated text editors and I expect they'll keep
becoming stronger as well, to the point where they may just become IDE's, or
a tool for integrating tools.

Just like ASCII is giving way to UNICODE, plain text is quickly becoming
obsolete.  With the profusion of HTML, XML, and other editors, surely one
format will be nice enough for everyone to standardize on.  I sure would
like the ability to put foreign characters and wierd math symbols into my
source code.  But ASCII/ANSI have very little in the way of choices.  I
would like to see a mathematical expression editor that translates during
save to D code with overloaded operators.  ;)

Sean


"Jason Mills" <jmills cs.mun.ca> wrote in message
news:3D348934.9030609 cs.mun.ca...

 Sean L. Palmer wrote:

 Using a text editor as your main programming environment is dead.  Let's
 move on.


 I disagree. I do most of my programming using a text editor (vim/gvim)
 and the command line, so I'm not sure what you mean by the above
 statement. Given that I have not been following this thread closely, I
 may have misinterpreted you.


 Jason



 Sean

     Yes I definitely agree with this.
     Putting the code in an .html file is a nice feature for demo




programs

     that get posted on web sites, but it doesn't work so well for pure
     documentation. I don't know if the people that mentioned this have
     tried javadoc or doxygen, but creating documentation from source




code

     and embedding source code in .html are just two completely different
     things. I don't see myself typing all the .html to create fancy




layout

     like above when writing a .d program. Also Javadoc and Doxygen




create

     hierarchical structures of your classes, summary and index files,
     links from one class to the others that are mentioned and to its
     parents, etc, etc, etc. Am I supposed to do this all by hand?

     Even if I was willing and capable of doing all this by hand, I could
     never benefit from other people using it to and all formats would be
     radically different.

     Just search the web for Java documentation. Notice how it is all
     uniform and looks alike? This is because all this documentation is
     generated using Javadoc. The 'embed d code in a .html file'




technique

     is not an option for documentation generation.


     --
     Stijn
     OddesE_XYZ hotmail.com <mailto:OddesE_XYZ hotmail.com>
     http://OddesE.cjb.net







 Jul 17 2002



  parent reply Jason Mills <jmills cs.mun.ca>  writes:


 There exist technological advancements that allow you to browse and
 edit code easily,


Any reasonable text editor with script capabilities can do this.


 configure how you want the code to be displayed (important on large
 teams where everyone has their own style preferences and you can't get
 a team to agree on indentation and spacing issues,)


Any reasonable text editor can do this as well, and much easier and with 
much more configuration options in most cases.


 and integrate debugging, source control, creating whatever makefile or
 linker script you need, and


I admit, these are not so easily done in a text editor, but doable just
the same.


 many other tools such as bitmap and dialog editors.  You may not need
 all of this, but I kinda like it.


Yes, I agree bitmap and dialog editors are useful. However, in some
decent GUI toolkits, dialog editors are not really necessary, especially
if the toolkit dynamically lays out you dialog controls for you.
Consider Java.


 I guess to each his own, I'm not stopping you from living in the stone
 age, but there are electric lights and running water nowadays.  ;)


I guess me and some well respected people in the software industry like
living in the stone age ;) (e.g. see Allen Holub's editorial, Java
Solutions, a supplement to C/C++ Users Journal).  I have read many
articles of those who have replaced their sophisticated IDE's and CASE
tools, which suppose to increase productivity, with good programming
text editors (e.g. gvim, emacs, etc.).

Most programming is done in a text editor, so why does so many that come
with IDEs stink? I use Visual C++ at work sometimes, but I find myself
using gvim as my primary text editor for that reason. In addition I can
use the same text editor, configured the way I like, for any programming
language I happen to be coding in at the moment, including D, while
others using IDE's often have to learn a new editor for each different
IDE. In effect, the programming never really becomes proficient with any
editor.


 That said, I've seen some pretty sophisticated text editors and I
 expect they'll keep becoming stronger as well, to the point where they
 may just become IDE's, or a tool for integrating tools.


Yes, and they behave the way you want them to behave.


 Just like ASCII is giving way to UNICODE, plain text is quickly
 becoming obsolete.  With the profusion of HTML, XML, and other
 editors, surely one format will be nice enough for everyone to
 standardize on.


But what is HTML and XML if it's not plain text? So is plain text really
becoming obsolete? You can argue the opposite. E.g. instead of saving
data as binary files, much data is now being saved as XML (plain text).


 I sure would like the ability to put foreign characters and wierd math
 symbols into my source code.  But ASCII/ANSI have very little in the
 way of choices.  I would like to see a mathematical expression editor
 that translates during save to D code with overloaded operators.  ;)


My main reason for staring this discussion is: when making decisions
about D, don't forget the stone age folks like me who may have an
interest in D ...  there may be more of us than you think ;)

Jason



 Jul 17 2002



  parent  "anderson" <anderson firestar.com.au>  writes:


"Jason Mills" <jmills cs.mun.ca> wrote in message
news:3D355879.2060807 cs.mun.ca...


 In addition I can
 use the same text editor, configured the way I like, for any programming
 language I happen to be coding in at the moment, including D, while
 others using IDE's often have to learn a new editor for each different
 IDE.

 Jason


I note that you said "often", but there are many multi-language IDE's out
there including "PC-grasp", "epsilon", "Scintilla" and also all those built
in ones that came with UNIX (which I forget). It's a matter of preference if
you use an IDE or not. IDE's simplify a lot of common tasks such as
compilation. Having to write/modify a make file everytime you write program
is just another task you add to add to do. Alternatively having to workout
how to make a multi-language IDE D proficient is another big task also
(Although it only needs to be done once).

Most IDE's use interface standards which makes switchingfrom one IDE to
another easier. The only real problems faced is learning how to set things
up and how to use the language specific tool (which you probably don't need
anyway).



 Jul 17 2002



prev sibling next sibling parent  "anderson" <anderson firestar.com.au>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Perhaps, there could be automatic hierarchical generation in some docgen =
like program. I think something along these lines was mentioned before =
(except it was compiler based). The hierarchical generator would simply =
scan all the D html files and built a code map, possibly using a UML =
derivative.  It would also generate a framed index file. So I still see =
a need for tags.=20

  The program could reformat these tags and automatically add things =
like see. This would provide a way to have automatically generated =
comments in the code itself not just the html. Now if someone is using a =
text editor for D, this could make things messy so the html (or xhtml) =
would have to be kept neat in a text form as well. There could also be =
special tags to indicate not to do certain things.=20

      /**
       * <author>Micky mouse</author>
       * <version>1.0</version>
       *
       *  The does blah blah blah blah blah blah blah blah blah blah =
blah blah=20
      *   blah blah blah blah blah blah blah blah blah blah blah blah =
blah blah=20
      *   blah blah blah blah blah=20
      **/
void func(int a)
{
...
}

Would change to
  void func(int a)
      Parameters

      a : Unknown
    =20



      The does blah blah blah blah blah blah blah blah blah blah blah =
blah blah blah blah blah blah blah blah blah blah blah blah blah blah =
blah blah blah blah blah blah=20

      Micky mouse

      See
             func2, func3
          =20




      V 1.0
    =20


      =20

      {

      ...
      }=20

=20


Anyway that's just an idea of a possible layout (athough it'll need alot =
more work).  The docGen should reconise both formats so that it can =
reconise what it has generated. Also classes could be done in a UML =
style by dividing the varaibles from the functions.

"Robert M. M=FCnch" <robert.muench robertmuench.de> wrote in message =
news:ah0ggd$niq$1 digitaldaemon.com...

 Source code documentation with coddocHi, thanks a lot. There is =


something

 that comes to mind: D can compile HTML files! So it maybe best to =


include D

 code into the documentation and not documentation into D code. My =


script

 could easly be changed to produce a compileable output file. With this =


we

 would be able to move more into the WEB idea of litteral programming. =


Code

 is already recognized as mentioned. What do you think? Robert
=20
=20
 "anderson" <anderson firestar.com.au> schrieb im Newsbeitrag
 news:ah0fv5$m3f$1 digitaldaemon.com...
 PS - Robert M. M=FCnch tool produces quite nice output, and I'd =


recommend it

 for this "Code documentation attachement". Also it mite be an idea for =


the D

 Journal if documents are to be produced to some standard (although it =


may

 mean extra reformating work). It handles code segments especially well =


(by

 picking up tabs).
=20
=20





 Jul 16 2002



prev sibling  parent reply Karl Bochert <kbochert ix.netcom.com>  writes:


On Tue, 16 Jul 2002 09:08:15 +0200, "Robert M. Münch"
<robert.muench robertmuench.de> wrote:

 Source code documentation with coddocHi, thanks a lot. There is something
 that comes to mind: D can compile HTML files! So it maybe best to include D
 code into the documentation and not documentation into D code. My script
 could easly be changed to produce a compileable output file. With this we
 would be able to move more into the WEB idea of litteral programming. Code
 is already recognized as mentioned. What do you think? Robert
 
 


Hmm.. Maybe it's time we thought in terms of coding our documentation
rather than documenting our code.



 Jul 16 2002



  parent reply "Walter" <walter digitalmars.com>  writes:


"Karl Bochert" <kbochert ix.netcom.com> wrote in message
news:1103_1026833775 bose...

 Hmm.. Maybe it's time we thought in terms of coding our documentation
 rather than documenting our code.


In D, you code the contracts!



 Aug 13 2002



  parent reply andy <acoliver apache.org>  writes:


Walter wrote:

 "Karl Bochert" <kbochert ix.netcom.com> wrote in message
 news:1103_1026833775 bose...
 

Hmm.. Maybe it's time we thought in terms of coding our documentation
rather than documenting our code.


 
 
 In D, you code the contracts!
 
 


Poor developers will always find a way to rationalize not writing 
documentation.



 Aug 14 2002



 next sibling parent  Pavel Minayev <evilone omen.ru>  writes:


On Wed, 14 Aug 2002 08:03:38 -0400 andy <acoliver apache.org> wrote:


 In D, you code the contracts!


 
 Poor developers will always find a way to rationalize not writing 
 documentation.


Contracts ARE docs.



 Aug 14 2002



prev sibling  parent reply "Sean L. Palmer" <seanpalmer earthlink.net>  writes:


Think of me what you will, but a given programming team has to have a
certain standard of skill for all members.  That usually at least means that
they are able to read existing code and figure out what it does.  Commenting
the obvious does not make anyone more productive.  Where you really need
comments are places where the code is doing more than is apparent at first
perusal.  Comment the code that is hard to read, not the code that is
self-explanatory to anyone with a "D for Dummies" book.

To me, standardized comment blocks look pretty, but are universally poorly
maintained and usually give you mostly redundant information.

I like putting documentation directly into the code itself whenever
possible... DBC contracts and asserts in D take that one step further.
Unlike a comment, a contract can be enforced by the compiler.  And actual
working code, once you know how to read it, never gets out of sync with
itself, as comments are wont to do.

Sean

"andy" <acoliver apache.org> wrote in message
news:3D5A471A.7040607 apache.org...

 Walter wrote:

 "Karl Bochert" <kbochert ix.netcom.com> wrote in message
 news:1103_1026833775 bose...


Hmm.. Maybe it's time we thought in terms of coding our documentation
rather than documenting our code.



 In D, you code the contracts!


 Poor developers will always find a way to rationalize not writing
 documentation.





 Aug 15 2002



  parent  "Walter" <walter digitalmars.com>  writes:


"Sean L. Palmer" <seanpalmer earthlink.net> wrote in message
news:ajflbd$j95$1 digitaldaemon.com...

 To me, standardized comment blocks look pretty, but are universally poorly
 maintained and usually give you mostly redundant information.


That's been my experience, too.


 I like putting documentation directly into the code itself whenever
 possible... DBC contracts and asserts in D take that one step further.
 Unlike a comment, a contract can be enforced by the compiler.  And actual
 working code, once you know how to read it, never gets out of sync with
 itself, as comments are wont to do.


The neat thing about contracts is that they can't get out of sync with the
code, even if poorly written. Contracts are a major productivity enhancer




 Aug 15 2002



prev sibling next sibling parent reply "anderson" <anderson firestar.com.au>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Source code documentation with coddocHow about a "requires" tag. =
Requirements could be auto generated but the doc program, but sometimes =
users may wish to add more details. I find it useful to quickly findout =
what is needed for a class without having to read through the sentenced =
documentation.

requires: STL, opengl.d



 Jul 16 2002



  parent reply Juarez Rudsatz <juarez nowhere.com>  writes:


"anderson" <anderson firestar.com.au> wrote in
news:ah2u5e$5or$1 digitaldaemon.com: 


 Source code documentation with coddocHow about a "requires" tag.
 Requirements could be auto generated but the doc program, but
 sometimes users may wish to add more details. I find it useful to
 quickly findout what is needed for a class without having to read
 through the sentenced documentation. 
 
 requires: STL, opengl.d
 


How this differs from having code in "import" statement ?



 Jul 17 2002



  parent  "anderson" <anderson firestar.com.au>  writes:


"Juarez Rudsatz" <juarez nowhere.com> wrote in message
news:Xns924E82C49F90juarezcorreiocom 63.105.9.61...

 "anderson" <anderson firestar.com.au> wrote in
 news:ah2u5e$5or$1 digitaldaemon.com:


 Source code documentation with coddocHow about a "requires" tag.
 Requirements could be auto generated but the doc program, but
 sometimes users may wish to add more details. I find it useful to
 quickly findout what is needed for a class without having to read
 through the sentenced documentation.

 requires: STL, opengl.d


 How this differs from having code in "import" statement ?


Sorry I was tring to indicate that the program should pick up things in the
import statement, but if they were entered by the user the the program would
add them if they didn't exist (the user may be planning to add it later).

Here's a more valid example,

requires: A fast 3d card, opengl multi-texturing extention, Index.dba,
texture.bmp

These are things that can't be picked up by the doc generator but should be
added in the same area include ones are does. Note that this should also be
avaliable per-function as well.



 Jul 17 2002



prev sibling next sibling parent reply Juarez Rudsatz <juarez nowhere.com>  writes:


Hi all!

    	I am sending the second version of this especification.
    	Is not concluded yet. 
    	Let's comment, criticize, speculate, think, talk ....

Juarez Rudsatz

Juarez Rudsatz <juarez correio.com> wrote in
news:Xns9249C9E0B98EEjuarezcom 63.105.9.61: 


 Hi all!
 
          I am sending a very preliminary version of a specification
          for 
 implementing a sintax for document source files using the /* */
 comments. 
          It's a preliminary version and contain, certainly, design and
 language errors.
          Please read the attached html file and send your comments.
 





 Aug 21 2002



 next sibling parent  "anderson" <anderson firestar.com.au>  writes:


Source code documentation with coddocTag copyrigth ??? Spelling

"Juarez Rudsatz" <juarez nowhere.com> wrote in message
news:Xns9271CD52FD128juarezcorreiocom 63.105.9.61...
Hi all!

    I am sending the second version of this especification.
    Is not concluded yet.
    Let's comment, criticize, speculate, think, talk ....

Juarez Rudsatz

Juarez Rudsatz <juarez correio.com> wrote in
news:Xns9249C9E0B98EEjuarezcom 63.105.9.61:


 Hi all!

          I am sending a very preliminary version of a specification
          for
 implementing a sintax for document source files using the /* */
 comments.
          It's a preliminary version and contain, certainly, design and
 language errors.
          Please read the attached html file and send your comments.





Abstract
A documentation model describes the format comments in the source code of a
program must adhere to to be extractable by a documentation tool, which can
then use the extracted information to create browsable or printable
documentation, for instance in an html, pdf or word document format.
This document is created with the purpose of specifying a clear and easy
documentation model for the programming language D.
Introduction
Documentation comments are a method of reducing work by moving documentation
from a separate document into the code itself in a way the documentation
document could easily be generated. As every programmer knows, documentation
tends to be incomplete, out of date, wrong, or non-existent. Moving the
documentation into the code makes it easy to maintain with the program or
library
Tools for generating documentation of API's are commom today. They provide a
simple method for programming and documenting at the same time. The
documentation remains close to the source code for the API programmer, and
for the application programmer will be in a more readable and easy to search
format. They decrease the work of creating and maintaining documentation
compared to writing it in a separate word processor. Most documentation
generators will even be able to generate decent documentation from source
code with no documentation comments in it at all, just from parsing the code
itself. Adding good structured comments to the source code can greatly
improve the value of the generated documentation however.
How source code is documented
Each feature of source code is composed by a set of language structures. For
each structure is attached a comment providing a description of it
functionality, a explaination of a component or classifying its atributes.
See some examples below :
A function being documented:
 /**
  * This function is a simple example
 **/
 int function(int x) {
  return x;
 }

A class being documented
 /**
  * author: Wolfrang Amadeus Mozart <wam music.org>
  *
  * This class plays a sinfonie of Mozart. It can be used for learning music
  * or for learning D documentation
 **/
 class sinfonie{
 ...
 }

How tags are parsed
Documented comments use a variation of the standart documentation for D.
They starts with the string '/**´ and finish with the string '**´:
 /** This is a documented comment **/
 typedef int normalvalue;

Alternatively a single line format can be used with the string '//*´:
 //* This is a documented comment
 typedef int normalvalue;

To place a single line comment behind the source line, as is common, use
'//<´:
      typedef int normalvalue; //< This is a documented comment

The documentation can span several lines. The extra blanks, tabulation and
new lines are stripped, just as with html:
 /**
 This comment will have
 many lines
 as needed
 **/

If the documentation should be divided into more than one paragraph, you can
add a blank line where you want to start a new paragraph:
 /**
 This is a paragraph

 And this is another
 **/

To allow the comment style often used by programmers where every line in the
comment block starts with an asterisk (*) aligned with the first asterisk in
the start comment tag, the first asterisk of the comment lines are stripped
if every comment line starts with an asterisk as the first non-whitespace
character:
 /**
  * This comment will have
  * many lines
  * as needed.
  *
  * And this is the second paragraph.
 **/

Aditional repeated chars at begin or at end are omited:
 /***********************************
  * The repeated chars are omited
 ***********************************/

The comment can have also a "tag" which specifies the documentation of an
specific atribute:
 /**
  * author: William Shakespeare <william literature.net>
 **/
 module literature;

The former tag specifies the author of the module. You can combine sereral
tags and text in the comment:
 /**
  * author: William Shakespeare <william literature.net>
  * version: 1.0
  *
  * This module implements the logic for understanding the real
interpretation of my ideas.
  * It magically translate all ideas hidden from the simple reading and show
to you.
 **/
 module literature;

Types of Tags
The tags can be of two types :
Taglines are tags described in one line. The tag end at the newline
caracter. As example there are the version, since, category and glossary
tags.
Tag paragraphs are tages described in one or more lines. The tag end is at
the next tag or the end of comment.
Position of Tags
Tags may be put before any declaration:
 /**
  * author: William Shakespeare <william literature.net> on 2002.03.04 05:06
  * author: Wolfrang Amadeus Mozart <wam music.org> on 2002.04.06 08:16
  * version: 0.3 alpha
  * category: Example of Code Documentation
  * see: anotherexample, example, "D Programming Tutorial"
  *
  * This module is provided as example of documenting code with coddoc. It
is
  * a example of how use the coments for generating documentation.
 **/
 module docexample;

It is also allowed to place documentation comments after the declaration
using the special start tag ´//<´. These comments may only span one line
however. Both forms may be mixed freely.
This is an example of a struct with documentation comments:
 struct SDL_Color {
  Uint8 r;  //< The byte representing the red value for color
  Uint8 g;  //< The byte representing the green value for color
  Uint8 b;  //< The byte representing the blue value for color
  Uint8 unused;  //< This byte is reserved for future use
 }

Especific tags
Tag author
The following are examples of author taglines, which may be used in
documentation comments for module and types declarations:
 /**
  * author: William Shakespeare<william literature.net>
  * author: Dante Aglieri
  * author: Jules Verne
 **/
 module literature;

Tag copyrigth
The copyright tag may be used to describe the copyright holder information
for the module, class or method
 /**
  * copyright: Pavel "EvilOne" Minayev (c) 2001-2002
  *
  * This module provides a class library for windows programming.
  * It contains controls necessary for creating windowed applications
  * such as edit controls, list controls, menus, status bars and
  * many other controls. It is also possible to derive your own
  * custom controls.
 **/
 module wind;

Tag license
The following is an example of a license paragraph, which may be used in
documentation comments for module declarations:
 /**
  * license:
  * Permission to use, copy, modify, distribute and sell this software
  * and its documentation for any purpose is hereby granted without fee,
  * provided that the above copyright notice appear in all copies and
  * that both that copyright notice and this permission notice appear
  * in supporting documentation.  Author makes no representations about
  * the suitability of this software for any purpose. It is provided
  * "as is" without express or implied warranty.
 **/

The license paragraph should contain all information applicable to licensing
terms and permission of use.
Tag version
The following is an example of a version tagline, which may be used in
documentation comments for type declarations:
 /**
  * version: 2.93.1 beta
 **/
 module imported;

Tag since
Specify in what version when the name was added to the API specification (if
different from the implementation). It could be used in type in reference to
module version or in method in reference to class version.
The following is an example of a since paragraph, which may be used in
documentation comments for declarations of methods:
 /**
  * version: 0.3 alpha
  *
  * This class is on the third version
 **/
 class widgetfarm : farm {
  /**
   * since: 0.2
   *
   * This method is introduced in version 0.2 of this class
  **/
  void initwidgets {
   ...
  }
 }

Tag see
The following are examples of see paragraphs, which may be used in any
documentation comment to indicate a cross-reference to a type, method,
constructor, field, URL, or any text:
 /**
  * see: c.stdio
  * see: string
  * see: string.equals
  * see: threads.thread.wait(int)
  * see: RandomAccessFile.RandomAccessFile(File)
  * see: RandomAccessFile.RandomAccessFile(File, String)
  * see: Character.MAX_RADIX
  * see: "D Language Specification" at
http://www.digitalmars.com/d/spec.html
  * see: "D Programming Tutorial"
 **/
 class implementation;

The character "." separates the name of a module of a class and the name of
a class from the name of one of its fields, methods, or constructors. The
order of searching is package, module, type, method. One of several
overloaded methods or constructors may be selected by including a
parenthesized list of argument types after the method or constructor name.
Tag category
The category tagline specify in what category the type or method is gruped.
It could be used in classes to classify the properties, methods and members
in a closed scope.
The following is an example of a category paragraph, which may be used in
documentation comments for declarations of a functions:
 /**
  * category: Temperature handling routines
 **/
 int temperature {
 ...
 }

Tag example
Adds a example copied verbatim to documentation.
The following is an example of a example paragraph, which may be used in
documentation comments for providing user examples:
 /**
  * example:
  *
  * // This ilustrate how to use a regexp to match a string
  * RegExp myRegExp = new RegExp("[A-Za-z\b!]*");
  * if (RegExp.Match("Hello World!")
  *   printf("Hello World!");
 **/
 class RegExp
 {
 ...
 }

The formatting in the documentation remains exactly the same as it is in the
source code. No whitespace is removed. A non-proportional font, such as
courier is used for the examples, so simple ASCII drawings will survive the
translation intact.
Tag bug
Specify known issue in types, methods or routines.
The following is an example of a bug paragraph, which may be used in
documentation comments for declarations of a functions:
 /**
  * bug: Severity High. Windows 9x dont pass the correct memory used
 **/
 int memoryUsed {
 ...
 }

Tag todo
Specify work to be done, such as implementing, optimizing or or documenting
certain types and methods.
The following is an example of a todo paragraph, which may be used in
documentation comments for declarations of a class:
 /**
  * version: 1.0
  * todo: modify to permit evaluate a string caracter by caracter
 **/
 class RegExp
 {
 ...
 }

Tag glossary
Specify a text to build a glossary by subject. The glossary tag is a tagline
but a documentation comment may contain more than one glossary tag.
The following is an example of a todo tagline, which may be used in
documentation comments for declarations of a function:
 /**
  * glossary: Deleting files
  * glossary: Erasing files
 **/
 void delelefile(string filename){
 ...
 }

Tag summary
The following is an example of an summary tagline, which may be used for
short describing a artifact:
 /**
  * summary: InterfaceDisconnect disconnects an IConnectionPoint interface.
  *
  * InterfaceDisconnect disconnects an IConnectionPoint interface connection
  * that was previously made by the InterfaceConnect procedure.
  * These procedures are wrappers for the ActiveX event-handling mechanism,
  * the  IConnectionPointContainer and IConnectionPoint interfaces.
 **/
 void InterfaceDisconnect(IUnknown Source, ClassIID IID);

Generic tags
Tags for parameters
The following are examples of parameters paragraphs, which may be used in
documentation comments for method and constructor declarations:
 /**
  * file: the file to be searched
  * pattern: the pattern to be matched during the search. The pattern could
  * consist of a simple string or a regular expression.
  * count: the max number of lines to brings for each match. O for all
lines;
  *
  * Matches lines in a file which follow a pattern.
 **/
 char[] matchLines(File file, char[] pattern, int count);

The information in a parameter paragraph should consist of the name of the
parameter followed by a short description.
A documentation comment may contain more than one parameter tag. The usual
convention is that if any parameter paragraphs are present in a
documentation comment, then there should be one parameter paragraph for each
parameter of the method or constructor, and the parameters paragraphs should
appear in the order in which the parameters are declared but this is not
mandatory.
Tags for imports
The following is an example of an import paragraph, which may be used in
documentation comments for modules imports:
 /**
  * Auxiliary routines
 **/
 import mymodule;

The information in an import paragraph should consist of the name of an
module (which may be a simple name or a qualified name) followed by a short
description of the need or dependency reason.
Additionaly, modules can be documented together simply by specifying the
name of module contained in the colon list.
 /**
  * mymodule: Auxiliary rotines
  * c.stdio: needed for printf function
  * stream: needed for reading and writing to files
 **/
 import mymodule, c.stdio, stream;

Tags for exceptions
The following is an example of an exception paragraph, which may be used in
documentation comments for method and constructor declarations:
 void verifyWidget(Widget widget)
 {
  if (!widget.flanged)
   //* the widget does not have a flange, or its flange has size zero
   throw new UnflangedWidgetError(´Missing flange´);
  if (!widget.canUse)
   /**
    * the widget cannot be used. This happens because it was not
    * initialized, it was not attached to a manager, it was not
    * configured or it is hided.
   **/
   throw new UnusableWidgetError();
  if (widget.InUse)
   throw new LockWidgetError("Widget is already in use"); //< the widget is
already used
 }

The comment in an exception paragraph is attached with the method which the
error is throwed. For documenting the exception use a normal tag once a
exception is a class.
The information in an exception paragraph should consist by a short
description of the circumstances that cause the exception to be thrown.
Tags for return values
The following is an example of an return paragraph, which may be used in
documentation comments for method and functions declarations:
 byte cmpString(char[] str1, char[] str2)
 {
  if (str1 < str2)
   /** if the first string is smaller than second.
    * return a positive number
    */
   return 1;
  if (str1 == str2)
   //* if strings are equal return zero
   return = 0;
  if (str1 == str2)
   /** if the first string is greater than second.
   //* return a negative number
   return = -1;
 }

Tags for Attributes
Not all Attributes statements can be documented. There are no meaning in
include documentation for the following tags:
private
protected
public
export
Nevertheless the tool implementing documentation comments could include
automatically the information and show or hide following user command.
The following attributes can be commented:
deprecated
override
abstract
const
final
static
 /**
  * As of D 2.0, replaced by stream handling methods
  * see: stream
 **/
 deprecated
 {
  char[] read(File f)
  {
  ...
  }

  int write(File f, char[] buffer)
  {
  ..
  }
 }

Tags for Contracts
Contracts are a breakthrough technique to reduce the programming effort for
large projects. Contracts are the concept of preconditions, postconditions,
errors, and invariants. Contracts form part of the specification for a
program, moving it from the documentation to the code itself.
The comment in an assert contract is attached with the method which the
contract is verified. For documenting the contract use a normal tag
explaining the reason os such restriction. Assert contract without a
documentation comment is not added in the documentation.
Not all contracts can be documented. Following tags are not documented:
out contracts in methods
unittest contracts
There are no meaning in include documentation for these contracts because
they are commonly used for verification of accuracy of results and for
determining if the code is working properly.
The following contracts can be commented:
in contracts in methods
class invariants
In Contracts
The following is an example of documentation of an assert contract in a
function in contract:
 int div(int x , int y)
 in
 {
  //* The divisor cannot be zero.
  assert(y != 0);
 }
 body
 {
  return x / y;
 }

Class Invariants
The following is an example of documentation of an assert contract in a
class invariant:
 class Date
 {
 int day;
 int hour;

 invariant()
 {
  //* The day must be between 1 and 31
  assert(1 <= day && day <= 31);
  //* The hour must be between 0 and 23
  assert(0 <= hour && hour < 24);
 }

Tags and versioning
Tags will be included in documentation following the versioning scheme.
Tags and inheritance
Inherited classes and structs will inherit tags for all methods defined in
ancestral which are not modified by an new documentation comment.
Compilaton process
The compiler will parse each file and generate a new file containing the
comments stripped from source and all information about the feature being
documented.
The format of all files generated is the docboock format. Each source file
generates one new file containing a section in a docbook book. The document
must be also a valid XML 1.0 document.
Users could use a docbook processor for generate documentation in html
format, text format, pdf format or any available format.
Users can also write their own preprocessor since the output of code
documentation will be a simple xml document.
Sugested comments for statements
Tags in simple types
Tags in simple procedures
Tags in functions
Tags in structures
Tags in classes
Best practices
A Style Guide
The following are useful tips and conventions for writing descriptions in
doc comments.
When specifying data use formal and standard notation
When specifying data such as dates and times use accepted standards such as
ISO. This way foreign readers will not be confused by month, day positions.
 module greataddon;  //< should be ready 2002.12.31 00:00:00.

Omit parentheses for the general form of methods and constructors
When referring to a method or constructor that has multiple forms, and you
mean to refer to a specific form, use parentheses and argument types. For
example, ArrayList has two add methods: add(Object) and add(int, Object).
 The add(int, Object) method adds an item at a specified position in this
arraylist.

However, if referring to both forms of the method, omit the parentheses
altogether. It is misleading to include empty parentheses, because that
would imply a particular form of the method. The intent here is to
distinguish the general method from any of its particular forms. Include the
word "method" to distinguish it as a method and not a field.
 The add method enables you to insert items.   (preferred)
 The add() method enables you to insert items.  (avoid when you mean "all
forms" of the add method)

Okay to use phrases instead of complete sentences
In the interests of brevity this could be used. This holds especially in the
initial summary and in parameter tag descriptions.
Use 3rd person (descriptive) not 2nd person (prescriptive).
The description is in 3rd person declarative rather than 2nd person
imperative.
 Gets the label.   (preferred)
 Get the label.   (avoid)

Method descriptions begin with a verb phrase.
A method implements an operation, so it usually starts with a verb phrase.
 Gets the label of this button.     (preferred)
 This method gets the label of this button.  (avoid)

Class/interface/field descriptions can omit the subject.
they can simply state the object. These API often describe things rather
than actions or behaviors:
 A button label.      (preferred)
 This field is a button label.  (avoid)

Use "this" instead of "the"
When referring to an object created from the current class is preferred use
a more specific word. For example, the description of the getToolkit method
should read as follows:
 Gets the toolkit for this component.  (preferred)
 Gets the toolkit for the component.   (avoid)

Add description beyond the API name.
The best API names are "self-documenting", meaning they tell you basically
what the API does. If the doc comment merely repeats the API name in
sentence form, it is not providing more information. For example, if method
description uses only the words that appear in the method name, then it is
adding nothing at all to what you could infer. The ideal comment goes beyond
those words and should always reward you with some bit of information that
was not immediately obvious from the API name.
The description below says nothing beyond what you know from reading the
method name. The words "set", "tool", "tip", and "text" are simply repeated
in a sentence. It's better avoid this form of documentate.
 /**
  * Sets the tool tip text.
  *
  * text:  The text of the tool tip.
 **/
 public void setToolTipText(String text);

This description more completely defines what a tool tip is, in the larger
context of registering and being displayed in response to the cursor. This
form is preferred in comparison with the first.
 /**
  * Registers the text to display in a tool tip.   The text
  * displays when the cursor lingers over the component.
  *
  * text:  The string to display.  If the text is null,
  * the tool tip is turned off for this component.
  */
 public void setToolTipText(String text);

Be clear when using the term common term.
Be aware that the common word as "field" can have many meanings and can
confuse the reader.
Avoid Latin
Use "also known as" instead of "aka", use "that is" or "to be specific"
instead of "i.e.", use "for example" instead of "e.g.", and use "in other
words" or "namely" instead of "viz."



 Aug 22 2002



prev sibling  parent reply "anderson" <anderson firestar.com.au>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

Source code documentation with coddocThe last email got muddled?

Simple typo - Copyright is spells wrong for one of the headings in that =
doc.
  "Juarez Rudsatz" <juarez nowhere.com> wrote in message =
news:Xns9271CD52FD128juarezcorreiocom 63.105.9.61...
  Hi all!

      I am sending the second version of this especification.
      Is not concluded yet.=20
      Let's comment, criticize, speculate, think, talk ....

  Juarez Rudsatz

  Juarez Rudsatz <juarez correio.com> wrote in
  news:Xns9249C9E0B98EEjuarezcom 63.105.9.61:=20

  > Hi all!
  >=20
  >          I am sending a very preliminary version of a specification
  >          for=20
  > implementing a sintax for document source files using the /* */
  > comments.=20
  >          It's a preliminary version and contain, certainly, design =
and
  > language errors.
  >          Please read the attached html file and send your comments.
  >=20



-------------------------------------------------------------------------=
-----


  Abstract
  A documentation model describes the format comments in the source code =
of a program must adhere to to be extractable by a documentation tool, =
which can then use the extracted information to create browsable or =
printable documentation, for instance in an html, pdf or word document =
format.

  This document is created with the purpose of specifying a clear and =
easy documentation model for the programming language D.

  Introduction
  Documentation comments are a method of reducing work by moving =
documentation from a separate document into the code itself in a way the =
documentation document could easily be generated. As every programmer =
knows, documentation tends to be incomplete, out of date, wrong, or =
non-existent. Moving the documentation into the code makes it easy to =
maintain with the program or library

  Tools for generating documentation of API's are commom today. They =
provide a simple method for programming and documenting at the same =
time. The documentation remains close to the source code for the API =
programmer, and for the application programmer will be in a more =
readable and easy to search format. They decrease the work of creating =
and maintaining documentation compared to writing it in a separate word =
processor. Most documentation generators will even be able to generate =
decent documentation from source code with no documentation comments in =
it at all, just from parsing the code itself. Adding good structured =
comments to the source code can greatly improve the value of the =
generated documentation however.

  How source code is documented
  Each feature of source code is composed by a set of language =
structures. For each structure is attached a comment providing a =
description of it functionality, a explaination of a component or =
classifying its atributes.

  See some examples below :

  A function being documented:
	/**
	 * This function is a simple example
	**/
	int function(int x) {
		return x;
	}

  A class being documented
	/**
	 * author: Wolfrang Amadeus Mozart <wam music.org>
	 *
	 * This class plays a sinfonie of Mozart. It can be used for learning =
music
	 * or for learning D documentation
	**/
	class sinfonie{
	...
	}

  How tags are parsed
  Documented comments use a variation of the standart documentation for =
D. They starts with the string '/**=B4 and finish with the string =
'**=B4:

	/** This is a documented comment **/
	typedef int normalvalue;

  Alternatively a single line format can be used with the string =
'//*=B4:

	//* This is a documented comment
	typedef int normalvalue;

  To place a single line comment behind the source line, as is common, =
use '//<=B4:

      typedef int normalvalue; //< This is a documented comment

  The documentation can span several lines. The extra blanks, tabulation =
and new lines are stripped, just as with html:

	/**
	This comment will have
	many lines
	as needed
	**/

  If the documentation should be divided into more than one paragraph, =
you can add a blank line where you want to start a new paragraph:

	/**
	This is a paragraph

	And this is another
	**/

  To allow the comment style often used by programmers where every line =
in the comment block starts with an asterisk (*) aligned with the first =
asterisk in the start comment tag, the first asterisk of the comment =
lines are stripped if every comment line starts with an asterisk as the =
first non-whitespace character:

	/**
	 * This comment will have
	 * many lines
	 * as needed.
	 *
	 * And this is the second paragraph.
	**/

  Aditional repeated chars at begin or at end are omited:

	/***********************************
	 * The repeated chars are omited
	***********************************/

  The comment can have also a "tag" which specifies the documentation of =
an specific atribute:

	/**
	 * author: William Shakespeare <william literature.net>
	**/
	module literature;

  The former tag specifies the author of the module. You can combine =
sereral tags and text in the comment:

	/**
	 * author: William Shakespeare <william literature.net>
	 * version: 1.0
	 *
	 * This module implements the logic for understanding the real =
interpretation of my ideas.
	 * It magically translate all ideas hidden from the simple reading and =
show to you.
	**/
	module literature;

  Types of Tags
  The tags can be of two types :

    a.. Taglines are tags described in one line. The tag end at the =
newline caracter. As example there are the version, since, category and =
glossary tags.=20
    b.. Tag paragraphs are tages described in one or more lines. The tag =
end is at the next tag or the end of comment.=20
  Position of Tags
  Tags may be put before any declaration:

	/**
	 * author: William Shakespeare <william literature.net> on 2002.03.04 =
05:06
	 * author: Wolfrang Amadeus Mozart <wam music.org> on 2002.04.06 08:16
	 * version: 0.3 alpha
	 * category: Example of Code Documentation
	 * see: anotherexample, example, "D Programming Tutorial"
	 *
	 * This module is provided as example of documenting code with coddoc. =
It is
	 * a example of how use the coments for generating documentation.
	**/
	module docexample;

  It is also allowed to place documentation comments after the =
declaration using the special start tag =B4//<=B4. These comments may =
only span one line however. Both forms may be mixed freely.

  This is an example of a struct with documentation comments:

	struct SDL_Color {
		Uint8 r;		//< The byte representing the red value for color
		Uint8 g;		//< The byte representing the green value for color
		Uint8 b;		//< The byte representing the blue value for color
		Uint8 unused;		//< This byte is reserved for future use
	}

  Especific tags
  Tag author
  The following are examples of author taglines, which may be used in =
documentation comments for module and types declarations:

	/**
	 * author: William Shakespeare<william literature.net>
	 * author: Dante Aglieri
	 * author: Jules Verne
	**/
	module literature;

  Tag copyrigth
  The copyright tag may be used to describe the copyright holder =
information for the module, class or method=20
	/**
	 * copyright: Pavel "EvilOne" Minayev (c) 2001-2002
	 *
	 * This module provides a class library for windows programming.
	 * It contains controls necessary for creating windowed applications
	 * such as edit controls, list controls, menus, status bars and
	 * many other controls. It is also possible to derive your own
	 * custom controls.
	**/
	module wind;

  Tag license
  The following is an example of a license paragraph, which may be used =
in documentation comments for module declarations:

	/**
	 * license:
	 * Permission to use, copy, modify, distribute and sell this software
	 * and its documentation for any purpose is hereby granted without fee,
	 * provided that the above copyright notice appear in all copies and
	 * that both that copyright notice and this permission notice appear
	 * in supporting documentation.  Author makes no representations about
	 * the suitability of this software for any purpose. It is provided
	 * "as is" without express or implied warranty.
	**/

  The license paragraph should contain all information applicable to =
licensing terms and permission of use.

  Tag version
  The following is an example of a version tagline, which may be used in =
documentation comments for type declarations:

	/**
	 * version: 2.93.1 beta
	**/
	module imported;

  Tag since
  Specify in what version when the name was added to the API =
specification (if different from the implementation). It could be used =
in type in reference to module version or in method in reference to =
class version.

  The following is an example of a since paragraph, which may be used in =
documentation comments for declarations of methods:

	/**
	 * version: 0.3 alpha
	 *
	 * This class is on the third version
	**/
	class widgetfarm : farm {
		/**
		 * since: 0.2
		 *
		 * This method is introduced in version 0.2 of this class
		**/
		void initwidgets {
		 ...
		}
	}

  Tag see
  The following are examples of see paragraphs, which may be used in any =
documentation comment to indicate a cross-reference to a type, method, =
constructor, field, URL, or any text:

	/**
	 * see: c.stdio
	 * see: string
	 * see: string.equals
	 * see: threads.thread.wait(int)
	 * see: RandomAccessFile.RandomAccessFile(File)
	 * see: RandomAccessFile.RandomAccessFile(File, String)
	 * see: Character.MAX_RADIX
	 * see: "D Language Specification" at =
http://www.digitalmars.com/d/spec.html
	 * see: "D Programming Tutorial"
	**/
	class implementation;

  The character "." separates the name of a module of a class and the =
name of a class from the name of one of its fields, methods, or =
constructors. The order of searching is package, module, type, method. =
One of several overloaded methods or constructors may be selected by =
including a parenthesized list of argument types after the method or =
constructor name.=20

  Tag category
  The category tagline specify in what category the type or method is =
gruped. It could be used in classes to classify the properties, methods =
and members in a closed scope.

  The following is an example of a category paragraph, which may be used =
in documentation comments for declarations of a functions:

	/**
	 * category: Temperature handling routines
	**/
	int temperature {
	...
	}

  Tag example
  Adds a example copied verbatim to documentation.

  The following is an example of a example paragraph, which may be used =
in documentation comments for providing user examples:

	/**
	 * example:
	 *
	 * // This ilustrate how to use a regexp to match a string
	 * RegExp myRegExp =3D new RegExp("[A-Za-z\b!]*");
	 * if (RegExp.Match("Hello World!")
	 *   printf("Hello World!");
	**/
	class RegExp
	{
	...
	}

  The formatting in the documentation remains exactly the same as it is =
in the source code. No whitespace is removed. A non-proportional font, =
such as courier is used for the examples, so simple ASCII drawings will =
survive the translation intact.

  Tag bug
  Specify known issue in types, methods or routines.

  The following is an example of a bug paragraph, which may be used in =
documentation comments for declarations of a functions:

	/**
	 * bug: Severity High. Windows 9x dont pass the correct memory used
	**/
	int memoryUsed {
	...
	}

  Tag todo
  Specify work to be done, such as implementing, optimizing or or =
documenting certain types and methods.

  The following is an example of a todo paragraph, which may be used in =
documentation comments for declarations of a class:

	/**
	 * version: 1.0
	 * todo: modify to permit evaluate a string caracter by caracter
	**/
	class RegExp
	{
	...
	}

  Tag glossary
  Specify a text to build a glossary by subject. The glossary tag is a =
tagline but a documentation comment may contain more than one glossary =
tag.

  The following is an example of a todo tagline, which may be used in =
documentation comments for declarations of a function:

	/**
	 * glossary: Deleting files
	 * glossary: Erasing files
	**/
	void delelefile(string filename){
	...
	}

  Tag summary
  The following is an example of an summary tagline, which may be used =
for short describing a artifact:

	/**
	 * summary: InterfaceDisconnect disconnects an IConnectionPoint =
interface.
	 *
	 * InterfaceDisconnect disconnects an IConnectionPoint interface =
connection
	 * that was previously made by the InterfaceConnect procedure.
	 * These procedures are wrappers for the ActiveX event-handling =
mechanism,
	 * the  IConnectionPointContainer and IConnectionPoint interfaces.
	**/
	void InterfaceDisconnect(IUnknown Source, ClassIID IID);

  Generic tags
  Tags for parameters
  The following are examples of parameters paragraphs, which may be used =
in documentation comments for method and constructor declarations:

	/**
	 * file: the file to be searched
	 * pattern: the pattern to be matched during the search. The pattern =
could
	 * consist of a simple string or a regular expression.
	 * count: the max number of lines to brings for each match. O for all =
lines;
	 *
	 * Matches lines in a file which follow a pattern.
	**/
	char[] matchLines(File file, char[] pattern, int count);

  The information in a parameter paragraph should consist of the name of =
the parameter followed by a short description.

  A documentation comment may contain more than one parameter tag. The =
usual convention is that if any parameter paragraphs are present in a =
documentation comment, then there should be one parameter paragraph for =
each parameter of the method or constructor, and the parameters =
paragraphs should appear in the order in which the parameters are =
declared but this is not mandatory.

  Tags for imports
  The following is an example of an import paragraph, which may be used =
in documentation comments for modules imports:

	/**
	 * Auxiliary routines
	**/
	import mymodule;

  The information in an import paragraph should consist of the name of =
an module (which may be a simple name or a qualified name) followed by a =
short description of the need or dependency reason.

  Additionaly, modules can be documented together simply by specifying =
the name of module contained in the colon list.

	/**
	 * mymodule: Auxiliary rotines
	 * c.stdio: needed for printf function
	 * stream: needed for reading and writing to files
	**/
	import mymodule, c.stdio, stream;

  Tags for exceptions
  The following is an example of an exception paragraph, which may be =
used in documentation comments for method and constructor declarations:

	void verifyWidget(Widget widget)
	{
		if (!widget.flanged)
			//* the widget does not have a flange, or its flange has size zero
			throw new UnflangedWidgetError(=B4Missing flange=B4);
		if (!widget.canUse)
			/**
			 * the widget cannot be used. This happens because it was not
			 * initialized, it was not attached to a manager, it was not
			 * configured or it is hided.
			**/
			throw new UnusableWidgetError();
		if (widget.InUse)
			throw new LockWidgetError("Widget is already in use"); //< the widget =
is already used
	}

  The comment in an exception paragraph is attached with the method =
which the error is throwed. For documenting the exception use a normal =
tag once a exception is a class.

  The information in an exception paragraph should consist by a short =
description of the circumstances that cause the exception to be thrown.=20

  Tags for return values
  The following is an example of an return paragraph, which may be used =
in documentation comments for method and functions declarations:

	byte cmpString(char[] str1, char[] str2)
	{
		if (str1 < str2)
			/** if the first string is smaller than second.
			 * return a positive number
			 */
			return 1;
		if (str1 =3D=3D str2)
			//* if strings are equal return zero
			return =3D 0;
		if (str1 =3D=3D str2)
			/** if the first string is greater than second.
			//* return a negative number
			return =3D -1;
	}

  Tags for Attributes
  Not all Attributes statements can be documented. There are no meaning =
in include documentation for the following tags:

    a.. private=20
    b.. protected=20
    c.. public=20
    d.. export=20
  Nevertheless the tool implementing documentation comments could =
include automatically the information and show or hide following user =
command.

  The following attributes can be commented:


    a.. deprecated=20
    b.. override=20
    c.. abstract=20
    d.. const=20
    e.. final=20
    f.. static=20
	/**
	 * As of D 2.0, replaced by stream handling methods
	 * see: stream
	**/
	deprecated
	{
		char[] read(File f)
		{
		...
		}

		int write(File f, char[] buffer)
		{
		..
		}
	}

  Tags for Contracts
  Contracts are a breakthrough technique to reduce the programming =
effort for large projects. Contracts are the concept of preconditions, =
postconditions, errors, and invariants. Contracts form part of the =
specification for a program, moving it from the documentation to the =
code itself.


  The comment in an assert contract is attached with the method which =
the contract is verified. For documenting the contract use a normal tag =
explaining the reason os such restriction. Assert contract without a =
documentation comment is not added in the documentation.

  Not all contracts can be documented. Following tags are not =
documented:

    a.. out contracts in methods=20
    b.. unittest contracts=20
  There are no meaning in include documentation for these contracts =
because they are commonly used for verification of accuracy of results =
and for determining if the code is working properly.

  The following contracts can be commented:


    a.. in contracts in methods=20
    b.. class invariants=20
  In Contracts
  The following is an example of documentation of an assert contract in =
a function in contract:

	int div(int x , int y)
	in
	{
		//* The divisor cannot be zero.
		assert(y !=3D 0);
	}
	body
	{
		return x / y;
	}

  Class Invariants
  The following is an example of documentation of an assert contract in =
a class invariant:

	class Date
	{
	int day;
	int hour;

	invariant()
	{
		//* The day must be between 1 and 31
		assert(1 <=3D day && day <=3D 31);
		//* The hour must be between 0 and 23
		assert(0 <=3D hour && hour < 24);
	}

  Tags and versioning
  Tags will be included in documentation following the versioning =
scheme.

  Tags and inheritance
  Inherited classes and structs will inherit tags for all methods =
defined in ancestral which are not modified by an new documentation =
comment.

  Compilaton process
  The compiler will parse each file and generate a new file containing =
the comments stripped from source and all information about the feature =
being documented.

  The format of all files generated is the docboock format. Each source =
file generates one new file containing a section in a docbook book. The =
document must be also a valid XML 1.0 document.

  Users could use a docbook processor for generate documentation in html =
format, text format, pdf format or any available format.

  Users can also write their own preprocessor since the output of code =
documentation will be a simple xml document.


  Sugested comments for statements
  Tags in simple types
  Tags in simple procedures
  Tags in functions
  Tags in structures
  Tags in classes
  Best practices
  A Style Guide
  The following are useful tips and conventions for writing descriptions =
in doc comments.

  When specifying data use formal and standard notation
  When specifying data such as dates and times use accepted standards =
such as ISO. This way foreign readers will not be confused by month, day =
positions.

	module greataddon;  //< should be ready 2002.12.31 00:00:00.

  Omit parentheses for the general form of methods and constructors
  When referring to a method or constructor that has multiple forms, and =
you mean to refer to a specific form, use parentheses and argument =
types. For example, ArrayList has two add methods: add(Object) and =
add(int, Object).

	The add(int, Object) method adds an item at a specified position in =
this arraylist.

  However, if referring to both forms of the method, omit the =
parentheses altogether. It is misleading to include empty parentheses, =
because that would imply a particular form of the method. The intent =
here is to distinguish the general method from any of its particular =
forms. Include the word "method" to distinguish it as a method and not a =
field.

	The add method enables you to insert items.			(preferred)
	The add() method enables you to insert items.		(avoid when you mean =
"all forms" of the add method)

  Okay to use phrases instead of complete sentences
  In the interests of brevity this could be used. This holds especially =
in the initial summary and in parameter tag descriptions.

  Use 3rd person (descriptive) not 2nd person (prescriptive).
  The description is in 3rd person declarative rather than 2nd person =
imperative.


	Gets the label.			(preferred)
	Get the label.			(avoid)

  Method descriptions begin with a verb phrase.
  A method implements an operation, so it usually starts with a verb =
phrase.

	Gets the label of this button.					(preferred)
	This method gets the label of this button.		(avoid)

  Class/interface/field descriptions can omit the subject.
  they can simply state the object. These API often describe things =
rather than actions or behaviors:

	A button label.						(preferred)
	This field is a button label.		(avoid)

  Use "this" instead of "the"
  When referring to an object created from the current class is =
preferred use a more specific word. For example, the description of the =
getToolkit method should read as follows:

	Gets the toolkit for this component.		(preferred)
	Gets the toolkit for the component.			(avoid)

  Add description beyond the API name.
  The best API names are "self-documenting", meaning they tell you =
basically what the API does. If the doc comment merely repeats the API =
name in sentence form, it is not providing more information. For =
example, if method description uses only the words that appear in the =
method name, then it is adding nothing at all to what you could infer. =
The ideal comment goes beyond those words and should always reward you =
with some bit of information that was not immediately obvious from the =
API name.

  The description below says nothing beyond what you know from reading =
the method name. The words "set", "tool", "tip", and "text" are simply =
repeated in a sentence. It's better avoid this form of documentate.

	/**
	 * Sets the tool tip text.
	 *
	 * text:  The text of the tool tip.
	**/
	public void setToolTipText(String text);

  This description more completely defines what a tool tip is, in the =
larger context of registering and being displayed in response to the =
cursor. This form is preferred in comparison with the first.

	/**
	 * Registers the text to display in a tool tip.   The text
	 * displays when the cursor lingers over the component.
	 *
	 * text:  The string to display.  If the text is null,
	 * the tool tip is turned off for this component.
	 */
	public void setToolTipText(String text);

  Be clear when using the term common term.

  Be aware that the common word as "field" can have many meanings and =
can confuse the reader.


  Avoid Latin
  Use "also known as" instead of "aka", use "that is" or "to be =
specific" instead of "i.e.", use "for example" instead of "e.g.", and =
use "in other words" or "namely" instead of "viz."



 Aug 22 2002



  parent  Juarez Rudsatz <juarez nowhere.com>  writes:


"anderson" <anderson firestar.com.au> wrote in
news:ak2i1a$1agt$1 digitaldaemon.com: 


 Source code documentation with coddocThe last email got muddled?


Sorry, I am not a native english speaker. I have not understood what you 
writed. Can you explain please ?



 Aug 23 2002



prev sibling next sibling parent reply Juarez Rudsatz <juarez nowhere.com>  writes:


A new update in code documentation syntax. I think this have evolved much 
since the first version. But need more discution until reach a solid stage.
Maybe it is time of balancing the costs against the benefits.
Please take a look at the specification and send your comments, preferences 
and questions. This is a not so prioritary project, but it could bring good 
advantages for the language by having a start in this direction.

Saudaçġes

Juarez Rudsatz

Juarez Rudsatz <juarez correio.com> wrote in
news:Xns9249C9E0B98EEjuarezcom 63.105.9.61: 


 Hi all!
 
          I am sending a very preliminary version of a specification
          for 
 implementing a sintax for document source files using the /* */
 comments. 
          It's a preliminary version and contain, certainly, design and
 language errors.
          Please read the attached html file and send your comments.
 





 Sep 04 2002



 next sibling parent reply Mac Reiter <Mac_member pathlink.com>  writes:


Nested numbered lists will have a problem with the following:







If indentation is a controlling mechanism, it needs to be documented as such.
You'll also need to document whether whitespace or tabs are to be used, how
translations between whitespace and tabs will be performed (some editors do
auto-indentation to align with previous lines, which can cause followup lines to
use spaces when the original line used tabs:







It might be better to take the list ending blank line and also use it for
sublists:








Of course, this just delays the inevitable:










Two blank lines in a row (the direct extension of my previous suggestion) is not
particularly obvious when you read it.  It may be necessary to make a
terminating symbol to end a (sub)list:





#x

#x

Or some such...

Mac
In article <Xns927FC90E25C36juarezcom 63.105.9.61>, Juarez Rudsatz says...

A new update in code documentation syntax. I think this have evolved much 
since the first version. But need more discution until reach a solid stage.
Maybe it is time of balancing the costs against the benefits.
Please take a look at the specification and send your comments, preferences 
and questions. This is a not so prioritary project, but it could bring good 
advantages for the language by having a start in this direction.

Saudaçġes

Juarez Rudsatz

Juarez Rudsatz <juarez correio.com> wrote in
news:Xns9249C9E0B98EEjuarezcom 63.105.9.61: 


 Hi all!
 
          I am sending a very preliminary version of a specification
          for 
 implementing a sintax for document source files using the /* */
 comments. 
          It's a preliminary version and contain, certainly, design and
 language errors.
          Please read the attached html file and send your comments.
 







 Sep 04 2002



  parent reply Juarez Rudsatz <juarez nowhere.com>  writes:


Mac Reiter <Mac_member pathlink.com> wrote in
news:al6380$2uv9$1 digitaldaemon.com: 


 Nested numbered lists will have a problem with the following:
 





 
 If indentation is a controlling mechanism, it needs to be documented
 as such. 


No identation is not a good method of controling lists or any 
documentation structure, IMHO. However you could use it for better 
looking in the source code. 

I have thinked in this rules:

1. On Unordered lists changing the bullet (+-o) define a child list
2. On Ordered lists changing the sequence number define a child list

So, tha above code could be rendered in html as :

<ol>
    	<li>Top list, item 1</li>
    	<li>Top list, item 2</li>
    	<ol>
    	    	<li>Nest list, item 1</li>
    	    	<li>Nest list, item 2</li>
    	    	<li>Which list?, item 3</li>
    	</ol>
</ol>


 It might be better to take the list ending blank line and also use it
 for sublists:
 




 




this will increase the rules for implemantation and does not look nice.

<ol>
    	<li>Top list, item 1</li>
    	<li>Top list, item 2</li>
    	<ol>
    	    	<li>Nest list, item 1</li>
    	    	<li>Nest list, item 2</li>
    	</ol>
</ol>
<ol>
    	<li>Top list, item 3</li>
</ol>
 

 Of course, this just delays the inevitable:
 






 



<ol>
    	<li>Top list, item 1</li>
    	<li>Top list, item 2</li>
    	<ol>
    	    	<li>Nest list, item 1</li>
    	    	<li>Nest list, item 2</li>
    	    	<ol>
    	    	    	<li>Deep list, item 1</li>
    	    	    	<li>Deep list, item 2</li>
    	    	</ol>
    	</ol>
<ol>
    	<li>Which list?, item 3</li>
</ol>
 

 Two blank lines in a row (the direct extension of my previous
 suggestion) is not particularly obvious when you read it.  It may be
 necessary to make a terminating symbol to end a (sub)list:
 




 #x

 #x


The more simple aproach is consider #x as valid text and this a multi-
line issue. 

<ol>
    	<li>Top list, item 1</li>
    	<li>Top list, item 2 #x</li>
    	<ol>
    	    	<li>Nest list, item 1</li>
    	    	<li>Nest list, item 2 #x</li>
    	</ol>
</ol>
<ol>
    	<li>Top list, item 3</li>
</ol>

There are no need of list terminators if following the 2 golden rules. 
Its just polute the visual IMHO.

What you think ? It is consistent ? There are some bug ? Looks nice ?

Saudaçġes

Juarez Rudsatz



 Sep 06 2002



  parent reply Pavel Minayev <evilone omen.ru>  writes:


Juarez Rudsatz wrote:


 So, tha above code could be rendered in html as :
 
 <ol>
     	<li>Top list, item 1</li>
     	<li>Top list, item 2</li>
     	<ol>
     	    	<li>Nest list, item 1</li>
     	    	<li>Nest list, item 2</li>
     	    	<li>Which list?, item 3</li>
     	</ol>
 </ol>



list?!


 What you think ? It is consistent ? There are some bug ? Looks nice ?


It seems like you're trying to solve a "dangling else"-like C problem... 
not aware of any solution better than C one though.



 Sep 07 2002



  parent reply Suporte Internet <suporte spica.mps.com.br>  writes:


Pavel Minayev <evilone omen.ru> wrote:

 Juarez Rudsatz wrote:
 

 So, tha above code could be rendered in html as :
 
 <ol>
       <li>Top list, item 1</li>
       <li>Top list, item 2</li>
       <ol>
               <li>Nest list, item 1</li>
               <li>Nest list, item 2</li>
               <li>Which list?, item 3</li>
       </ol>
 </ol>


 

 list?!
 

 What you think ? It is consistent ? There are some bug ? Looks nice ?


 
 It seems like you're trying to solve a "dangling else"-like C problem... 
 not aware of any solution better than C one though.


Good obsevation !
But what could be the solution?

1. Requering a empty item what will not render?






2. Use a terminator for lists?



#x


3. Use a empty line as that terminator?






Here continue the text out of list

4. Using a optional different sintax for last item?







5. Using tabs, for list level?





Any comment?



 Sep 09 2002



  parent reply Pavel Minayev <evilone omen.ru>  writes:


Suporte Internet wrote:


 Good obsevation !
 But what could be the solution?


My suggestion would be to use some kind of symbol, for example period, 
to indicate nesting level:










 Sep 09 2002



  parent  Juarez Rudsatz <juarez nowhere.com>  writes:


Pavel Minayev <evilone omen.ru> wrote in news:aliq8p$1vev$1
 digitaldaemon.com:


 Good obsevation !
 But what could be the solution?


 
 My suggestion would be to use some kind of symbol, for example period, 
 to indicate nesting level:
 








Maybe a "nested" number:







 Sep 11 2002



prev sibling next sibling parent reply "anderson" <anderson firestar.com.au>  writes:


	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable


"Juarez Rudsatz" <juarez nowhere.com> wrote in message =
news:Xns927FC90E25C36juarezcom 63.105.9.61...

 A new update in code documentation syntax. I think this have evolved =


much=20

 since the first version. But need more discution until reach a solid =


stage.

 Maybe it is time of balancing the costs against the benefits.
 Please take a look at the specification and send your comments, =


preferences=20

 and questions. This is a not so prioritary project, but it could bring =


good=20

 advantages for the language by having a start in this direction.
=20
 Sauda=E7=F5es
=20
 Juarez Rudsatz



Looking great. This docGen thing will add value to D.=20

My suggestion,=20

Parhaps there could be a way to modularise the docGen, so that files =
that don't change don't need to be re-worked with doc gen. That may not =
need to be in the documentation though. Also it would be nice if users =
could specify a webpage where the latest docgen document resides. That =
way local versions could remain current.

ie
/*
 * web version: www.something.com/Documents/
*/

Parhaps this could be done with see, however I think it could be neetly =
formated into the headers(or footer) of the page.

The above may produce something like (for the car page):

Find the latest of this webpage

Note that the docgen would point directly to the wepage =
www.something.com/Documents/Car.html, and web version is just in generic =
form. The class rocket ship under www.something.com/Documents/ would =
point to (www.something.com/Documents/Rocket Ship.html)

Of course theres the possiblily of bad links, like when the =
webpage\class structure changes. In these cases a default docgen page =
could also be created to capture these errors.

It would be nice if the docgen produced pages into separt folders =
depending on the package which they reside, optionally or a zip file. =
That's more a docgen compiler thing then a spec thing.

Joel Anderson

PS -
copyrigth ?? -> copyright



 Sep 05 2002



 next sibling parent  Juarez Rudsatz <juarez nowhere.com>  writes:


"anderson" <anderson firestar.com.au> wrote in
news:al7dgi$2nua$1 digitaldaemon.com: 


 Parhaps there could be a way to modularise the docGen, so that files
 that don't change don't need to be re-worked with doc gen. That may
 not need to be in the documentation though 


I have thinked in make :










 Sep 05 2002



prev sibling next sibling parent  Juarez Rudsatz <juarez nowhere.com>  writes:


"anderson" <anderson firestar.com.au> wrote in
news:al7dgi$2nua$1 digitaldaemon.com: 


 Also it would be nice if users could specify a webpage where the
 latest docgen document resides. That way local versions could remain
 current. 
 
 ie
 /*
  * web version: www.something.com/Documents/
 */
 
 Parhaps this could be done with see, however I think it could be
 neetly formated into the headers(or footer) of the page. 
 
 The above may produce something like (for the car page):
 
 Find the latest of this webpage
 
 Note that the docgen would point directly to the wepage
 www.something.com/Documents/Car.html, and web version is just in
 generic form. The class rocket ship under www.something.com/Documents/
 would point to (www.something.com/Documents/Rocket Ship.html) 
 
 Of course theres the possiblily of bad links, like when the
 webpage\class structure changes. In these cases a default docgen page
 could also be created to capture these errors. 
 


What about two alternatives :

1. The user can include in the module source file:

/**
 * see: "D Language Specification" at 
http://www.digitalmars.com/d/spec.html
 **/
import foo;

and the compiler can detect the url and generate a html like:

<p>
  <b>See Also:</b>"D Language Specification" at <a 
href="http://www.digitalmars.com/d/spec.html">
http://www.digitalmars.com/d/spec.html</a>

But this is a quality of implementation issue.

2. The user can include a hand generated docbook chapter with references or 
another instruction and compile and generate the html, pdf, tex, text or 
what he want.



 Sep 05 2002



prev sibling next sibling parent  Juarez Rudsatz <juarez nowhere.com>  writes:


"anderson" <anderson firestar.com.au> wrote in
news:al7dgi$2nua$1 digitaldaemon.com: 


 It would be nice if the docgen produced pages into separt folders
 depending on the package which they reside, optionally or a zip file.
 That's more a docgen compiler thing then a spec thing. 
 


I think initialy in two compilers:

1. A stripper    	:-)
2. A indexer
3. A formatter

The stripper extracts the documentation and generate a new file by each 
source file parsed. This file must be a xml docbook, but a best format can 
be discussed. 
The indexer take a lot of these files and generate the indexes, glossaries 
and categories and a sample docbook book index file.
The user can now compile the documentation in his preferred format using 
his preferred docbook toolset.
The formater simply will help the user putting empty comments in 
declarations.

The first two compilers need to be a part of specification ( maybe v15 
:-)).

I have thinked about a form of parametrizing the preferences like :

o    	I dont wanna variable in documentation.
o    	I dont wanna declarations without comment in documentation.
o    	I wanna the oposite...

What you think about all?



 Sep 05 2002



prev sibling  parent reply Juarez Rudsatz <juarez nowhere.com>  writes:


"anderson" <anderson firestar.com.au> wrote in news:al7dgi$2nua$1
 digitaldaemon.com:


 copyrigth ?? -> copyright


copyrigth , lenght, widht, heigth, ligth !

I newer write this correctly !!! 
Portuguese is much more simple !!! :-)



 Sep 05 2002



  parent  "anderson" <anderson firestar.com.au>  writes:


I'm a bad speller myself, and I can't blame a second language :) I don't
mind if someone corrects me (not implying that you don't). One thing though,
"copyright" is something that a spell checker should pickup so it's even
less of a small deal.

"Juarez Rudsatz" <juarez nowhere.com> wrote in message
news:Xns9280BF864E127juarezcom 63.105.9.61...

 "anderson" <anderson firestar.com.au> wrote in news:al7dgi$2nua$1
  digitaldaemon.com:


 copyrigth ?? -> copyright


 copyrigth , lenght, widht, heigth, ligth !

 I newer write this correctly !!!
 Portuguese is much more simple !!! :-)





 Sep 06 2002



prev sibling  parent reply Jason Mills <jmills cs.mun.ca>  writes:


Juarez Rudsatz wrote:

 A new update in code documentation syntax. I think this have evolved much 
 since the first version. But need more discution until reach a solid stage.
 Maybe it is time of balancing the costs against the benefits.
 Please take a look at the specification and send your comments, preferences 
 and questions. This is a not so prioritary project, but it could bring good 
 advantages for the language by having a start in this direction.
 


I quickly scanned through the document and a couple of things did stand
out to me (I'll do a more thorough read later).

<quote>

Alternatively a single line format can be used with the string '///´:

   /// This is a documented comment
   typedef int normalvalue;

</quote>

Can we use single line comments in place of the /** **/ style comments,
as shown below:


   ///
   /// author: Wolfrang Amadeus Mozart <wam music.org>
   ///
   /// This class plays a sinfonie of Mozart. It can be used for learning
   /// music or for learning D documentation
   ///
   class sinfonie{
   ...
   }



<quote>

To place a single line comment behind the source line, as is common, use
'///<´:

   typedef int normalvalue; ///< This is a documented comment

</quote>


Just wondering... but why use ///< and not simply /// like the single
line comments above?

Jason



 Sep 05 2002



 next sibling parent reply Pavel Minayev <evilone omen.ru>  writes:


Jason Mills wrote:


 To place a single line comment behind the source line, as is common, use
 '///<´:
 
   typedef int normalvalue; ///< This is a documented comment
 
 </quote>
 
 
 Just wondering... but why use ///< and not simply /// like the single
 line comments above?


So that the doc generator knows which line is commented (next or 
previous). It's doxygen syntax.



 Sep 05 2002



  parent reply Juarez Rudsatz <juarez nowhere.com>  writes:


Pavel Minayev <evilone omen.ru> wrote in news:al7oem$8d7$1
 digitaldaemon.com:


 So that the doc generator knows which line is commented (next or 
 previous). It's doxygen syntax.
 


Yes. Maybe the easiest form of making a compiler for documentation will be 
writing a extension for doxygen.



 Sep 05 2002



  parent  Jason Mills <jmills cs.mun.ca>  writes:


Juarez Rudsatz wrote:

 Pavel Minayev <evilone omen.ru> wrote in news:al7oem$8d7$1
  digitaldaemon.com:
 
 

So that the doc generator knows which line is commented (next or 
previous). It's doxygen syntax.


 
 
 Yes. Maybe the easiest form of making a compiler for documentation will be 
 writing a extension for doxygen.


I have used doxygen for some C++ documentation, it's great. Maybe the
easiest (best) solution to standard D source code documentation is to
adopt doxygen style comments, i.e. use the doxygen spec and write an
extension for doxygen as you suggested. A programmer could than use the
same style comments for D, C++, and Java (and other languages doxygen
supports).

Jason



 Sep 06 2002



prev sibling  parent reply Juarez Rudsatz <juarez nowhere.com>  writes:


Jason Mills <jmills cs.mun.ca> wrote in news:al7edl$2pih$1
 digitaldaemon.com:


 Can we use single line comments in place of the /** **/ style comments,
 as shown below:
 
 
    ///
    /// author: Wolfrang Amadeus Mozart <wam music.org>
    ///
    /// This class plays a sinfonie of Mozart. It can be used for learning
    /// music or for learning D documentation
    ///
    class sinfonie{
    ...
    }
 
 


I think it's ugly. But I think is valid.
These are also:

 /** 
   * author: Wolfrang Amadeus Mozart <wam music.org>
  **/
 /** 
   * This class plays a sinfonie of Mozart. It can be used for learning
   * music or for learning D documentation
  **/
   class sinfonie{
   ...
   }

The rule I have thinked is the comment, if are in a body (not between { } )
is attached to next declaration.

What this looks in your eyes ?



 Sep 05 2002



  parent  Jason Mills <jmills cs.mun.ca>  writes:


Can we use single line comments in place of the /** **/ style comments,
as shown below:


   ///
   /// author: Wolfrang Amadeus Mozart <wam music.org>
   ///
   /// This class plays a sinfonie of Mozart. It can be used for learning
   /// music or for learning D documentation
   ///
   class sinfonie{
   ...
   }


 
 
 I think it's ugly. But I think is valid.


I (and some of my co-workers) like using /// as above.


 These are also:
 
  /** 
    * author: Wolfrang Amadeus Mozart <wam music.org>
   **/
  /** 
    * This class plays a sinfonie of Mozart. It can be used for learning
    * music or for learning D documentation
   **/
    class sinfonie{
    ...
    }
 
 The rule I have thinked is the comment, if are in a body (not between { } )
 is attached to next declaration.
 
 What this looks in your eyes ?


This *looks* like two seperate comments, but I guess it could be treated 
as one.



 Sep 06 2002



prev sibling  parent  Juarez Rudsatz <juarez nowhere.com>  writes:


PCFET0NUWVBFIGh0bWwgUFVCTElDICItLy9XM0MvL0RURCBYSFRNTCAxLjAg
U3RyaWN0Ly9FTiINCiAgICAiaHR0cDovL3d3dy53My5vcmcvVFIveGh0bWwx
L0RURC94aHRtbDEtc3RyaWN0LmR0ZCI+DQo8aHRtbCB4bWxucz0iaHR0cDov
L3d3dy53My5vcmcvMTk5OS94aHRtbCI+DQo8aGVhZD4NCjxtZXRhIG5hbWU9
ImdlbmVyYXRvciIgY29udGVudD0iSFRNTCBUaWR5LCBzZWUgd3d3LnczLm9y
ZyIgLz4NCjx0aXRsZT5Tb3VyY2UgY29kZSBkb2N1bWVudGF0aW9uIHdpdGgg
Y29kZG9jPC90aXRsZT4NCjwvaGVhZD4NCjxib2R5Pg0KPGgxPkFic3RyYWN0
PC9oMT4NCg0KPHA+QSBkb2N1bWVudGF0aW9uIG1vZGVsIGRlc2NyaWJlcyB0
aGUgZm9ybWF0IGNvbW1lbnRzIGluIHRoZSBzb3VyY2UgY29kZSBvZiBhIHBy
b2dyYW0gbXVzdCBhZGhlcmUgdG8gdG8gYmUgZXh0cmFjdGFibGUgYnkgYSBk
b2N1bWVudGF0aW9uIHRvb2wsIHdoaWNoIGNhbiB0aGVuIHVzZSB0aGUgZXh0
cmFjdGVkIGluZm9ybWF0aW9uIHRvIGNyZWF0ZSBicm93c2FibGUgb3IgcHJp
bnRhYmxlIGRvY3VtZW50YXRpb24sIGZvciBpbnN0YW5jZSBpbiBhbiBodG1s
LCBwZGYgb3Igd29yZCBkb2N1bWVudCBmb3JtYXQuPC9wPg0KDQo8cD5UaGlz
IGRvY3VtZW50IGlzIGNyZWF0ZWQgd2l0aCB0aGUgcHVycG9zZSBvZiBzcGVj
aWZ5aW5nIGEgY2xlYXIgYW5kIGVhc3kgZG9jdW1lbnRhdGlvbiBtb2RlbCBm
b3IgdGhlIHByb2dyYW1taW5nIGxhbmd1YWdlIEQuPC9wPg0KDQo8aDE+SW50
cm9kdWN0aW9uPC9oMT4NCg0KRG9jdW1lbnRhdGlvbiBjb21tZW50cyBhcmUg
YSBtZXRob2Qgb2YgcmVkdWNpbmcgd29yayBieSBtb3ZpbmcgZG9jdW1lbnRh
dGlvbiBmcm9tIGEgc2VwYXJhdGUgZG9jdW1lbnQgaW50byB0aGUgY29kZSBp
dHNlbGYgaW4gYSB3YXkgdGhlIGRvY3VtZW50YXRpb24gZG9jdW1lbnQgY291
bGQgZWFzaWx5IGJlIGdlbmVyYXRlZC4gQXMgZXZlcnkgcHJvZ3JhbW1lciBr
bm93cywgZG9jdW1lbnRhdGlvbiB0ZW5kcyB0byBiZSBpbmNvbXBsZXRlLCBv
dXQgb2YgZGF0ZSwgd3JvbmcsIG9yIG5vbi1leGlzdGVudC4gTW92aW5nIHRo
ZSBkb2N1bWVudGF0aW9uIGludG8gdGhlIGNvZGUgbWFrZXMgaXQgZWFzeSB0
byBtYWludGFpbiB3aXRoIHRoZSBwcm9ncmFtIG9yIGxpYnJhcnk8L3A+DQoN
CjxwPlRvb2xzIGZvciBnZW5lcmF0aW5nIGRvY3VtZW50YXRpb24gb2YgQVBJ
J3MgYXJlIGNvbW1vbSB0b2RheS4gVGhleSBwcm92aWRlIGEgc2ltcGxlIG1l
dGhvZCBmb3IgcHJvZ3JhbW1pbmcgYW5kIGRvY3VtZW50aW5nIGF0IHRoZSBz
YW1lIHRpbWUuIFRoZSBkb2N1bWVudGF0aW9uIHJlbWFpbnMgY2xvc2UgdG8g
dGhlIHNvdXJjZSBjb2RlIGZvciB0aGUgQVBJIHByb2dyYW1tZXIsIGFuZCBm
b3IgdGhlIGFwcGxpY2F0aW9uIHByb2dyYW1tZXIgd2lsbCBiZSBpbiBhIG1v
cmUgcmVhZGFibGUgYW5kIGVhc3kgdG8gc2VhcmNoIGZvcm1hdC4gVGhleSBk
ZWNyZWFzZSB0aGUgd29yayBvZiBjcmVhdGluZyBhbmQgbWFpbnRhaW5pbmcg
ZG9jdW1lbnRhdGlvbiBjb21wYXJlZCB0byB3cml0aW5nIGl0IGluIGEgc2Vw
YXJhdGUgd29yZCBwcm9jZXNzb3IuIE1vc3QgZG9jdW1lbnRhdGlvbiBnZW5l
cmF0b3JzIHdpbGwgZXZlbiBiZSBhYmxlIHRvIGdlbmVyYXRlIGRlY2VudCBk
b2N1bWVudGF0aW9uIGZyb20gc291cmNlIGNvZGUgd2l0aCBubyBkb2N1bWVu
dGF0aW9uIGNvbW1lbnRzIGluIGl0IGF0IGFsbCwganVzdCBmcm9tIHBhcnNp
bmcgdGhlIGNvZGUgaXRzZWxmLiBBZGRpbmcgZ29vZCBzdHJ1Y3R1cmVkIGNv
bW1lbnRzIHRvIHRoZSBzb3VyY2UgY29kZSBjYW4gZ3JlYXRseSBpbXByb3Zl
IHRoZSB2YWx1ZSBvZiB0aGUgZ2VuZXJhdGVkIGRvY3VtZW50YXRpb24gaG93
ZXZlci48L3A+DQoNCjxoMT5Ib3cgc291cmNlIGNvZGUgaXMgZG9jdW1lbnRl
ZDwvaDE+DQoNCjxwPkVhY2ggZmVhdHVyZSBvZiBzb3VyY2UgY29kZSBpcyBj
b21wb3NlZCBieSBhIHNldCBvZiBsYW5ndWFnZSBzdHJ1Y3R1cmVzLiBGb3Ig
ZWFjaCBzdHJ1Y3R1cmUgaXMgYXR0YWNoZWQgYSBjb21tZW50IHByb3ZpZGlu
ZyBhIGRlc2NyaXB0aW9uIG9mIGl0IGZ1bmN0aW9uYWxpdHksIGEgZXhwbGFp
bmF0aW9uIG9mIGEgY29tcG9uZW50IG9yIGNsYXNzaWZ5aW5nIGl0cyBhdHJp
YnV0ZXMuPC9wPg0KDQo8cD5TZWUgc29tZSBleGFtcGxlcyBiZWxvdyA6PC9w
Pg0KDQo8aDU+QSBmdW5jdGlvbiBiZWluZyBkb2N1bWVudGVkOjwvaDU+DQoN
CjxwcmU+DQoJLyoqDQoJICogVGhpcyBmdW5jdGlvbiBpcyBhIHNpbXBsZSBl
eGFtcGxlDQoJKiovDQoJaW50IGZ1bmN0aW9uKGludCB4KSB7DQoJCXJldHVy
biB4Ow0KCX0NCjwvcHJlPg0KDQo8aDU+QSBjbGFzcyBiZWluZyBkb2N1bWVu
dGVkPC9oNT4NCg0KPHByZT4NCgkvKioNCgkgKiBhdXRob3I6IFdvbGZyYW5n
IEFtYWRldXMgTW96YXJ0ICZsdDt3YW1AbXVzaWMub3JnJmd0Ow0KCSAqDQoJ
ICogVGhpcyBjbGFzcyBwbGF5cyBhIHNpbmZvbmllIG9mIE1vemFydC4gSXQg
Y2FuIGJlIHVzZWQgZm9yIGxlYXJuaW5nIG11c2ljDQoJICogb3IgZm9yIGxl
YXJuaW5nIEQgZG9jdW1lbnRhdGlvbg0KCSoqLw0KCWNsYXNzIHNpbmZvbmll
ew0KCS4uLg0KCX0NCjwvcHJlPg0KDQo8aDE+SG93IHRhZ3MgYXJlIHBhcnNl
ZDwvaDE+DQoNCjxwPkRvY3VtZW50ZWQgY29tbWVudHMgdXNlIGEgdmFyaWF0
aW9uIG9mIHRoZSBzdGFuZGFydCBkb2N1bWVudGF0aW9uIGZvciBELiBUaGV5
IHN0YXJ0cyB3aXRoIHRoZSBzdHJpbmcgJy8qKiZhY3V0ZTsgYW5kIGZpbmlz
aCB3aXRoIHRoZSBzdHJpbmcgJyoqJmFjdXRlOzo8L3A+DQoNCjxwcmU+DQoJ
LyoqIFRoaXMgaXMgYSBkb2N1bWVudGVkIGNvbW1lbnQgKiovDQoJdHlwZWRl
ZiBpbnQgbm9ybWFsdmFsdWU7DQo8L3ByZT4NCg0KPHA+QWx0ZXJuYXRpdmVs
eSBhIHNpbmdsZSBsaW5lIGZvcm1hdCBjYW4gYmUgdXNlZCB3aXRoIHRoZSBz
dHJpbmcgJy8vLyZhY3V0ZTs6PC9wPg0KDQo8cHJlPg0KCS8vLyBUaGlzIGlz
IGEgZG9jdW1lbnRlZCBjb21tZW50DQoJdHlwZWRlZiBpbnQgbm9ybWFsdmFs
dWU7DQo8L3ByZT4NCg0KPHA+VG8gcGxhY2UgYSBzaW5nbGUgbGluZSBjb21t
ZW50IGJlaGluZCB0aGUgc291cmNlIGxpbmUsIGFzIGlzIGNvbW1vbiwgdXNl
ICcvLy8mbHQ7tDo8L3A+DQoNCjxwcmU+DQogICAgICB0eXBlZGVmIGludCBu
b3JtYWx2YWx1ZTsgLy8vJmx0IFRoaXMgaXMgYSBkb2N1bWVudGVkIGNvbW1l
bnQNCjwvcHJlPg0KDQo8cD5UaGUgZG9jdW1lbnRhdGlvbiBjYW4gc3BhbiBz
ZXZlcmFsIGxpbmVzLiBUaGUgZXh0cmEgYmxhbmtzLCB0YWJ1bGF0aW9uIGFu
ZCBuZXcgbGluZXMgYXJlIHN0cmlwcGVkLCBqdXN0IGFzIHdpdGggaHRtbDo8
L3A+DQoNCjxwcmU+DQoJLyoqDQoJVGhpcyBjb21tZW50IHdpbGwgaGF2ZQ0K
CW1hbnkgbGluZXMNCglhcyBuZWVkZWQNCgkqKi8NCjwvcHJlPg0KDQo8cD5J
ZiB0aGUgZG9jdW1lbnRhdGlvbiBzaG91bGQgYmUgZGl2aWRlZCBpbnRvIG1v
cmUgdGhhbiBvbmUgcGFyYWdyYXBoLCB5b3UgY2FuIGFkZCBhIGJsYW5rIGxp
bmUgd2hlcmUgeW91IHdhbnQgdG8gc3RhcnQgYSBuZXcgcGFyYWdyYXBoOjwv
cD4NCg0KPHByZT4NCgkvKioNCglUaGlzIGlzIGEgcGFyYWdyYXBoDQoNCglB
bmQgdGhpcyBpcyBhbm90aGVyDQoJKiovDQo8L3ByZT4NCg0KPHA+VG8gYWxs
b3cgdGhlIGNvbW1lbnQgc3R5bGUgb2Z0ZW4gdXNlZCBieSBwcm9ncmFtbWVy
cyB3aGVyZSBldmVyeSBsaW5lIGluIHRoZSBjb21tZW50IGJsb2NrIHN0YXJ0
cyB3aXRoIGFuIGFzdGVyaXNrICgqKSBhbGlnbmVkIHdpdGggdGhlIGZpcnN0
IGFzdGVyaXNrIGluIHRoZSBzdGFydCBjb21tZW50IHRhZywgdGhlIGZpcnN0
IGFzdGVyaXNrIG9mIHRoZSBjb21tZW50IGxpbmVzIGFyZSBzdHJpcHBlZCBp
ZiBldmVyeSBjb21tZW50IGxpbmUgc3RhcnRzIHdpdGggYW4gYXN0ZXJpc2sg
YXMgdGhlIGZpcnN0IG5vbi13aGl0ZXNwYWNlIGNoYXJhY3Rlcjo8L3A+DQoN
CjxwcmU+DQoJLyoqDQoJICogVGhpcyBjb21tZW50IHdpbGwgaGF2ZQ0KCSAq
IG1hbnkgbGluZXMNCgkgKiBhcyBuZWVkZWQuDQoJICoNCgkgKiBBbmQgdGhp
cyBpcyB0aGUgc2Vjb25kIHBhcmFncmFwaC4NCgkqKi8NCjwvcHJlPg0KDQo8
cD5BZGl0aW9uYWwgcmVwZWF0ZWQgY2hhcnMgYXQgYmVnaW4gb3IgYXQgZW5k
IGFyZSBvbWl0ZWQ6PC9wPg0KDQo8cHJlPg0KCS8qKioqKioqKioqKioqKioq
KioqKioqKioqKioqKioqKioqKg0KCSAqIFRoZSByZXBlYXRlZCBjaGFycyBh
cmUgb21pdGVkDQoJKioqKioqKioqKioqKioqKioqKioqKioqKioqKioqKioq
KiovDQo8L3ByZT4NCg0KPHA+VGhlIGNvbW1lbnQgY2FuIGhhdmUgYWxzbyBh
ICJ0YWciIHdoaWNoIHNwZWNpZmllcyB0aGUgZG9jdW1lbnRhdGlvbiBvZiBh
biBzcGVjaWZpYyBhdHJpYnV0ZTo8L3A+DQoNCjxwcmU+DQoJLyoqDQoJICog
YXV0aG9yOiBXaWxsaWFtIFNoYWtlc3BlYXJlICZsdDt3aWxsaWFtQGxpdGVy
YXR1cmUubmV0Jmd0Ow0KCSoqLw0KCW1vZHVsZSBsaXRlcmF0dXJlOw0KPC9w
cmU+DQoNCjxwPlRoZSBmb3JtZXIgdGFnIHNwZWNpZmllcyB0aGUgYXV0aG9y
IG9mIHRoZSBtb2R1bGUuIFlvdSBjYW4gY29tYmluZSBzZXJlcmFsIHRhZ3Mg
YW5kIHRleHQgaW4gdGhlIGNvbW1lbnQ6PC9wPg0KDQo8cHJlPg0KCS8qKg0K
CSAqIGF1dGhvcjogV2lsbGlhbSBTaGFrZXNwZWFyZSAmbHQ7d2lsbGlhbUBs
aXRlcmF0dXJlLm5ldCZndDsNCgkgKiB2ZXJzaW9uOiAxLjANCgkgKg0KCSAq
IFRoaXMgbW9kdWxlIGltcGxlbWVudHMgdGhlIGxvZ2ljIGZvciB1bmRlcnN0
YW5kaW5nIHRoZSByZWFsIGludGVycHJldGF0aW9uIG9mIG15IGlkZWFzLg0K
CSAqIEl0IG1hZ2ljYWxseSB0cmFuc2xhdGUgYWxsIGlkZWFzIGhpZGRlbiBm
cm9tIHRoZSBzaW1wbGUgcmVhZGluZyBhbmQgc2hvdyB0byB5b3UuDQoJKiov
DQoJbW9kdWxlIGxpdGVyYXR1cmU7DQo8L3ByZT4NCg0KPGgzPlR5cGVzIG9m
IFRhZ3M8L2gzPg0KDQo8cD5UaGUgdGFncyBjYW4gYmUgb2YgdGhyZWUgdHlw
ZXMgOjwvcD4NCg0KPHVsPg0KPGxpPlRhZ2xpbmVzIGFyZSB0YWdzIGRlc2Ny
aWJlZCBpbiBvbmUgbGluZS4gVGhlIHRhZyBlbmQgYXQgdGhlIG5ld2xpbmUg
Y2FyYWN0ZXIuIEFzIGV4YW1wbGUgdGhlcmUgYXJlIHRoZSB2ZXJzaW9uLCBz
aW5jZSwgY2F0ZWdvcnkgYW5kIGdsb3NzYXJ5IHRhZ3MuPC9saT4NCg0KPGxp
PlRhZyBwYXJhZ3JhcGhzIGFyZSB0YWdlcyBkZXNjcmliZWQgaW4gb25lIG9y
IG1vcmUgbGluZXMuIFRoZSB0YWcgZW5kIGlzIGF0IHRoZSBuZXh0IHRhZyBv
ciB0aGUgZW5kIG9mIGNvbW1lbnQuPC9saT4NCg0KPC91bD4NCg0KPGgzPkxp
c3RzPC9oMz4NCg0KPHA+VGhlcmUgaXMgb2Z0ZW4gYSBuZWVkIHRvIGFkZCBM
aXN0cyAoYm90aCBidWxsZXRlZCBvciBlbnVtZXJhdGVkIGxpc3RzIGFyZSBz
dXBwb3J0ZWQpIHRvIHRoZSBkb2N1bWVudGF0aW9uIHRleHQuIEJlY2F1c2Ug
aW4gZGlmZmVyZW50IG91dHB1dCBmb3JtYXRzIGxpc3RzIGFuZCB0YWJsZXMg
YXJlIGdlbmVyYXRlZCBpbiB2ZXJ5IGRpZmZlcmVudCB3YXlzLCB0aGUgcGFy
c2VyIG5lZWRzIHRvIHVuZGVyc3RhbmQgeW91ciBsaXN0IGluIG9yZGVyIHRv
IGdlbmVyYXRlIHByb3BlciBsaXN0cyBhbmQgdGFibGVzIGluIHRoZSB0YXJn
ZXQgZm9ybWF0LjwvcD4NCg0KPHA+VGhlIGZvbGxvd2luZyBkZWZpbmVzIGEg
YnVsbGV0ZWQgbGlzdCB0aGF0IGlzIHVuZGVyc3Rvb2QgYXMgc3VjaCBieSB0
aGUgcGFyc2VyOjwvcD4NCg0KPHByZT4NCgkvKioNCgkgKiBUaGUgbW9zdCBk
ZWxpY2lvdXMgZnJ1aXRzOg0KCSAqIC0gT3JhbmdlDQogCSAqIC0gQmVyZ2Ft
b3RhDQoJICogLSBBcHBsZQ0KCSoqLw0KPC9wcmU+DQoNCjxwPkJ1bGxldGVk
IGxpc3RzIHN0YXJ0IHdpdGggYSBidWxsZXQgY2hhcmFjdGVyLiBCeSBkZWZh
dWx0IHRoaXMgaXMgb25lIGNoYXJhY3RlciBvdXQgb2YgIistbyIuIEJldHdl
ZW4gdGhlIGJ1bGxldCBjaGFyYWN0ZXIgYW5kIHRoZSBpdGVtIHRleHQgdGhl
cmUgbXVzdCBiZSBhdCBsZWFzdCBvbmUgc3BhY2UgYW5kIHRoZSBpdGVtIHRl
eHQgbXVzdCBzdGFydCBvbiB0aGUgc2FtZSBsaW5lIGFzIHRoZSBidWxsZXQg
Y2hhcmFjdGVyLjwvcD4NCg0KPHA+TnVtYmVyZWQgbGlzdCB3b3JrIGluIHRo
ZSBzYW1lIHdheTo8L3A+DQoNCjxwcmU+DQoJLyoqDQoJICogVGhpcyBpcyBv
cmRlciBvZiB0aGUgdGhpbmtzOg0KCSAqICMxIERvY3VtZW50IHlvdXIgc291
cmNlDQoJICogIzIgR2VuZXJhdGUgZG9jYm9vayBmcm9tIHlvdXIgZmlsZXMN
CiAJICogIzMgR2VuZXJhdGUgaHRtbCBtYW51YWwgZnJvbSBkb2Nib29rDQoJ
KiovDQo8L3ByZT4NCg0KPHA+QSBudW1iZXJlZCBsaXN0IGl0ZW0gc3RhcnRz
IHdpdGggYSBudW1iZXIgZm9sbG93ZWQgYnkgdGhlIGxpc3Qgc3ltYm9sLiBB
cyB3aXRoIHRoZSBidWxsZXRlZCBsaXN0LCB0aGVyZSBtdXN0IGJlIGF0IGxl
YXN0IG9uZSBzcGFjZSBiZXR3ZWVuIHRoZSBkb3QgYW5kIHRoZSBpdGVtIHRl
eHQgYW5kIHRoZSBpdGVtIHRleHQgbXVzdCBzdGFydCBvbiB0aGUgc2FtZSBs
aW5lIGFzIHRoZSBudW1iZXIuPC9wPg0KDQo8cD5UaGUgZm9sbG93aW5nIGV4
YW1wbGUgZGVmaW5lcyBhIG51bWJlcmVkIGxpc3Qgd2hpY2ggaGFzIG9uZSBt
dWx0aS1saW5lIGl0ZW06PC9wPg0KDQo8cHJlPg0KCS8qKg0KCSAqIFRoZSBt
b3N0IGRlbGljaW91cyBmcnVpdHM6DQoJICogbyBPcmFuZ2UNCiAJICogbyBC
ZXJnYW1vdGEuIEEgU291dGggQW1lcmljYSBmcnVpdC4NCiAJICoJIEl0IHNl
ZW1zIGxpa2UgYSBPcmFuZ2UgYnV0IGlzIHNtYWxsZXINCiAJICoJIGFzIGlz
IHN3ZWV0ZXIuDQoJICogbyBBcHBsZQ0KCSoqLw0KPC9wcmU+DQoNCjxwPkZv
ciB3cml0aW5nIG5vcm1hbCB0ZXh0IGFmdGVyIHRoZSBsaXN0LCBzaW1wbHkg
cHJvdmlkZSBhIGJsYW5rIGxpbmUgYWZ0ZXIgdGhlIGxpc3QuIFRoaXMgaXMg
dGhlIGVuZGluZyBtZWNhbmlzbSBmb3IgdGhlIGxpc3QuDQoNCjxwcmU+DQoJ
LyoqDQoJICogWW91IG5lZWQgaW5zdGFuY2UgdGhlIGNvbm5lY3Rpb24gZG9p
bmcgYmVmb3JlOg0KCSAqICMxIENyZWF0aW5nIGEgbmV3IGNvbm5lY3Rpb24N
CgkgKiAjMiBTZXR0aW5nIHRoZSBwYXJhbWV0ZXJzDQoJICogIzMgT3Blbmlu
ZyB0aGUgY29ubmVjdGlvbg0KCSAqDQoJICogQW5kIGZvbGxvd2luZyB5b3Ug
Y2FuIHJlYWQgeW91ciBpbmZvcm1hdGlvbi4NCgkqKi8NCjwvcHJlPg0KDQo8
cD5Ud28gb3IgbW9yZSBsaXN0cyBjYW4gYWxzbyBiZSBuZXN0ZWQuIE9ubHkg
aXMgbmVlZCBjaGFuZ2UgdGhlIHR5cGUgb2YgdGhlIGJ1bGxldGVkIGNoYXJh
Y3Rlcjo8L3A+DQoNCjxwcmU+DQoJLyoqDQoJICogVGhpcyBpcyB0aGUgcG9z
c2liaWxpdHkgb2YgcHJvYmxlbToNCgkgKiArIE5vIHNwYWNlIG9uIGRpc2sN
CgkgKiArIE5vIHBlcm1pc3Npb24gdG8gd3JpdGUgdGhlIGZpbGUNCgkgKiAJ
CS0gVGhlIG1lZGlhIGlzIHJlYWQtb25seQ0KCSAqCQktIFRoZSB1c2VyIGRv
bid0IGhhdmUgcGVybWlzc2lvbiB0byB3cml0ZQ0KIAkgKiArIERpc2sgZmFp
bHVyZQ0KIAkgKgkJLSBObyBkaXNrIGNvbm5lY3RlZA0KIAkgKgkJLSBEaXNr
IGRhbWFnZWQNCgkqKi8NCjwvcHJlPg0KDQo8cD5OdW1lcmVkIGxpc3RzIGNh
biBhbHNvYmUgbmVzdGVkLiBZb3Ugb25seSBuZWVkIHJlc3RhcnQgdGhlIHNl
cXVlbmNlLiBUaGUgbnVtZXJlZCBhbmQgYnVsbGV0ZWQgY2FuIGJlIG1peGVk
Og0KDQo8cHJlPg0KCS8qKg0KCSAqIFBoYXNlcyBvZiBDb21waWxhdGlvbjoN
CgkgKiAjMSBhc2NpaS93aGlkZSBjaGFyDQoJICogIzIgbGV4aWNhbCBhbmFs
eXNpcw0KIAkgKiAjMyBzeW50YXggYW5hbHlzaXMNCiAJICogIzQgc2VtYW50
aWMgYW5hbHlzaXMNCgkgKiAJCSMxIHRlbXBsYXRlcyBhcmUgaW5zdGFudGll
ZA0KCSAqCQkjMiBzZW1hbnRpYyB2ZXJpZmljYXRpb24gaXMgcHJvY2VkZWQN
CgkgKiAjNSBvcHRpbWl6YXRpb24NCgkgKgkJIzEgcmVtb3Rpb24gb2YgdW51
c2VkIGNvZGUNCgkgKgkJIzIgc2ltcGxpZmljYXRpb24gb2YgY29tcGxleCBz
dGF0ZW1lbnRzDQoJICoJCSMzIHJlbW90aW9uIG9mIHVubmVjZXNzYXJ5IGNh
bGxzDQoJICogIzYgY29kZSBnZW5lcmF0aW9uDQoJKiovDQo8L3ByZT4NCg0K
PGgzPlBvc2l0aW9uIG9mIFRhZ3M8L2gzPg0KDQo8cD5UYWdzIG1heSBiZSBw
dXQgYmVmb3JlIGFueSBkZWNsYXJhdGlvbjo8L3A+DQoNCjxwcmU+DQoJLyoq
DQoJICogYXV0aG9yOiBXaWxsaWFtIFNoYWtlc3BlYXJlICZsdDt3aWxsaWFt
QGxpdGVyYXR1cmUubmV0Jmd0OyBvbiAyMDAyLjAzLjA0IDA1OjA2DQoJICog
YXV0aG9yOiBXb2xmcmFuZyBBbWFkZXVzIE1vemFydCAmbHQ7d2FtQG11c2lj
Lm9yZyZndDsgb24gMjAwMi4wNC4wNiAwODoxNg0KCSAqIHZlcnNpb246IDAu
MyBhbHBoYQ0KCSAqIGNhdGVnb3J5OiBFeGFtcGxlIG9mIENvZGUgRG9jdW1l
bnRhdGlvbg0KCSAqIHNlZTogYW5vdGhlcmV4YW1wbGUsIGV4YW1wbGUsICJE
IFByb2dyYW1taW5nIFR1dG9yaWFsIg0KCSAqDQoJICogVGhpcyBtb2R1bGUg
aXMgcHJvdmlkZWQgYXMgZXhhbXBsZSBvZiBkb2N1bWVudGluZyBjb2RlIHdp
dGggY29kZG9jLiBJdCBpcw0KCSAqIGEgZXhhbXBsZSBvZiBob3cgdXNlIHRo
ZSBjb21lbnRzIGZvciBnZW5lcmF0aW5nIGRvY3VtZW50YXRpb24uDQoJKiov
DQoJbW9kdWxlIGRvY2V4YW1wbGU7DQo8L3ByZT4NCg0KPHA+SXQgaXMgYWxz
byBhbGxvd2VkIHRvIHBsYWNlIGRvY3VtZW50YXRpb24gY29tbWVudHMgYWZ0
ZXIgdGhlIGRlY2xhcmF0aW9uIHVzaW5nIHRoZSBzcGVjaWFscyBzdGFydCB0
YWdzICcvLy8mbHQnIG9yICcvKiombHQ7Jy4gVGhlIGNvbW1lbnRzIHdpdGgg
c3RhcnQgdGFnICcvLy8mbHQ7JyBtYXkgb25seSBzcGFuIG9uZSBsaW5lIGhv
d2V2ZXIuIEJvdGggZm9ybXMgbWF5IGJlIG1peGVkIGZyZWVseS48L3A+DQoN
CjxwPlRoaXMgaXMgYW4gZXhhbXBsZSBvZiBhIHN0cnVjdCB3aXRoIGRvY3Vt
ZW50YXRpb24gY29tbWVudHM6PC9wPg0KDQo8cHJlPg0KCXN0cnVjdCBTRExf
Q29sb3Igew0KCQlVaW50OCByOwkJLy8vJmx0OyBUaGUgYnl0ZSByZXByZXNl
bnRpbmcgdGhlIHJlZCB2YWx1ZSBmb3IgY29sb3INCgkJVWludDggZzsJCS8v
LyZsdDsgVGhlIGJ5dGUgcmVwcmVzZW50aW5nIHRoZSBncmVlbiB2YWx1ZSBm
b3IgY29sb3INCgkJVWludDggYjsJCS8vLyZsdDsgVGhlIGJ5dGUgcmVwcmVz
ZW50aW5nIHRoZSBibHVlIHZhbHVlIGZvciBjb2xvcg0KCQlVaW50OCB1bnVz
ZWQ7CQkvKiombHQ7IFRoaXMgYnl0ZSBpcyByZXNlcnZlZCBmb3IgZnV0dXJl
IHVzZQ0KCQkJCQkJcGxlYXNlIGRvbid0IHJlbHkgb24gaXQgYmVjYXVsZCB5
b3Ugd2lsbCBtYWtlIGEgbWlzdGFrZS4gKiovDQoJfQ0KPC9wcmU+DQoNCjxo
MT5Fc3BlY2lmaWMgdGFnczwvaDE+DQoNCjxoMj5UYWcgYXV0aG9yPC9oMj4N
Cg0KPHA+VGhlIGZvbGxvd2luZyBhcmUgZXhhbXBsZXMgb2YgYXV0aG9yIHRh
Z2xpbmVzLCB3aGljaCBtYXkgYmUgdXNlZCBpbiBkb2N1bWVudGF0aW9uIGNv
bW1lbnRzIGZvciBtb2R1bGUgYW5kIHR5cGVzIGRlY2xhcmF0aW9uczo8L3A+
DQoNCjxwcmU+DQoJLyoqDQoJICogYXV0aG9yOiBXaWxsaWFtIFNoYWtlc3Bl
YXJlJmx0O3dpbGxpYW1AbGl0ZXJhdHVyZS5uZXQmZ3Q7DQoJICogYXV0aG9y
OiBEYW50ZSBBZ2xpZXJpDQoJICogYXV0aG9yOiBKdWxlcyBWZXJuZQ0KCSoq
Lw0KCW1vZHVsZSBsaXRlcmF0dXJlOw0KPC9wcmU+DQoNCjxoMj5UYWcgY29w
eXJpZ3RoPC9oMj4NCg0KVGhlIGNvcHlyaWdodCB0YWcgbWF5IGJlIHVzZWQg
dG8gZGVzY3JpYmUgdGhlIGNvcHlyaWdodCBob2xkZXIgaW5mb3JtYXRpb24g
Zm9yIHRoZSBtb2R1bGUsIGNsYXNzIG9yIG1ldGhvZA0KDQoNCjxwcmU+DQoJ
LyoqDQoJICogY29weXJpZ2h0OiBQYXZlbCAiRXZpbE9uZSIgTWluYXlldiAo
YykgMjAwMS0yMDAyDQoJICoNCgkgKiBUaGlzIG1vZHVsZSBwcm92aWRlcyBh
IGNsYXNzIGxpYnJhcnkgZm9yIHdpbmRvd3MgcHJvZ3JhbW1pbmcuDQoJICog
SXQgY29udGFpbnMgY29udHJvbHMgbmVjZXNzYXJ5IGZvciBjcmVhdGluZyB3
aW5kb3dlZCBhcHBsaWNhdGlvbnMNCgkgKiBzdWNoIGFzIGVkaXQgY29udHJv
bHMsIGxpc3QgY29udHJvbHMsIG1lbnVzLCBzdGF0dXMgYmFycyBhbmQNCgkg
KiBtYW55IG90aGVyIGNvbnRyb2xzLiBJdCBpcyBhbHNvIHBvc3NpYmxlIHRv
IGRlcml2ZSB5b3VyIG93bg0KCSAqIGN1c3RvbSBjb250cm9scy4NCgkqKi8N
Cgltb2R1bGUgd2luZDsNCjwvcHJlPg0KDQo8aDI+VGFnIGxpY2Vuc2U8L2gy
Pg0KDQo8cD5UaGUgZm9sbG93aW5nIGlzIGFuIGV4YW1wbGUgb2YgYSBsaWNl
bnNlIHBhcmFncmFwaCwgd2hpY2ggbWF5IGJlIHVzZWQgaW4gZG9jdW1lbnRh
dGlvbiBjb21tZW50cyBmb3IgbW9kdWxlIGRlY2xhcmF0aW9uczo8L3A+DQoN
CjxwcmU+DQoJLyoqDQoJICogbGljZW5zZToNCgkgKiBQZXJtaXNzaW9uIHRv
IHVzZSwgY29weSwgbW9kaWZ5LCBkaXN0cmlidXRlIGFuZCBzZWxsIHRoaXMg
c29mdHdhcmUNCgkgKiBhbmQgaXRzIGRvY3VtZW50YXRpb24gZm9yIGFueSBw
dXJwb3NlIGlzIGhlcmVieSBncmFudGVkIHdpdGhvdXQgZmVlLA0KCSAqIHBy
b3ZpZGVkIHRoYXQgdGhlIGFib3ZlIGNvcHlyaWdodCBub3RpY2UgYXBwZWFy
IGluIGFsbCBjb3BpZXMgYW5kDQoJICogdGhhdCBib3RoIHRoYXQgY29weXJp
Z2h0IG5vdGljZSBhbmQgdGhpcyBwZXJtaXNzaW9uIG5vdGljZSBhcHBlYXIN
CgkgKiBpbiBzdXBwb3J0aW5nIGRvY3VtZW50YXRpb24uICBBdXRob3IgbWFr
ZXMgbm8gcmVwcmVzZW50YXRpb25zIGFib3V0DQoJICogdGhlIHN1aXRhYmls
aXR5IG9mIHRoaXMgc29mdHdhcmUgZm9yIGFueSBwdXJwb3NlLiBJdCBpcyBw
cm92aWRlZA0KCSAqICJhcyBpcyIgd2l0aG91dCBleHByZXNzIG9yIGltcGxp
ZWQgd2FycmFudHkuDQoJKiovDQo8L3ByZT4NCg0KPHA+VGhlIGxpY2Vuc2Ug
cGFyYWdyYXBoIHNob3VsZCBjb250YWluIGFsbCBpbmZvcm1hdGlvbiBhcHBs
aWNhYmxlIHRvIGxpY2Vuc2luZyB0ZXJtcyBhbmQgcGVybWlzc2lvbiBvZiB1
c2UuPC9wPg0KDQo8aDI+VGFnIHZlcnNpb248L2gyPg0KDQo8cD5UaGUgZm9s
bG93aW5nIGlzIGFuIGV4YW1wbGUgb2YgYSB2ZXJzaW9uIHRhZ2xpbmUsIHdo
aWNoIG1heSBiZSB1c2VkIGluIGRvY3VtZW50YXRpb24gY29tbWVudHMgZm9y
IHR5cGUgZGVjbGFyYXRpb25zOjwvcD4NCg0KPHByZT4NCgkvKioNCgkgKiB2
ZXJzaW9uOiAyLjkzLjEgYmV0YQ0KCSoqLw0KCW1vZHVsZSBpbXBvcnRlZDsN
CjwvcHJlPg0KDQo8aDI+VGFnIHNpbmNlPC9oMj4NCg0KPHA+U3BlY2lmeSBp
biB3aGF0IHZlcnNpb24gd2hlbiB0aGUgbmFtZSB3YXMgYWRkZWQgdG8gdGhl
IEFQSSBzcGVjaWZpY2F0aW9uIChpZiBkaWZmZXJlbnQgZnJvbSB0aGUgaW1w
bGVtZW50YXRpb24pLiBJdCBjb3VsZCBiZSB1c2VkIGluIHR5cGUgaW4gcmVm
ZXJlbmNlIHRvIG1vZHVsZSB2ZXJzaW9uIG9yIGluIG1ldGhvZCBpbiByZWZl
cmVuY2UgdG8gY2xhc3MgdmVyc2lvbi48L3A+DQoNCjxwPlRoZSBmb2xsb3dp
bmcgaXMgYW4gZXhhbXBsZSBvZiBhIHNpbmNlIHBhcmFncmFwaCwgd2hpY2gg
bWF5IGJlIHVzZWQgaW4gZG9jdW1lbnRhdGlvbiBjb21tZW50cyBmb3IgZGVj
bGFyYXRpb25zIG9mIG1ldGhvZHM6PC9wPg0KDQo8cHJlPg0KCS8qKg0KCSAq
IHZlcnNpb246IDAuMyBhbHBoYQ0KCSAqDQoJICogVGhpcyBjbGFzcyBpcyBv
biB0aGUgdGhpcmQgdmVyc2lvbg0KCSoqLw0KCWNsYXNzIHdpZGdldGZhcm0g
OiBmYXJtIHsNCgkJLyoqDQoJCSAqIHNpbmNlOiAwLjINCgkJICoNCgkJICog
VGhpcyBtZXRob2QgaXMgaW50cm9kdWNlZCBpbiB2ZXJzaW9uIDAuMiBvZiB0
aGlzIGNsYXNzDQoJCSoqLw0KCQl2b2lkIGluaXR3aWRnZXRzIHsNCgkJIC4u
Lg0KCQl9DQoJfQ0KPC9wcmU+DQoNCjxoMj5UYWcgc2VlPC9oMj4NCg0KPHA+
VGhlIGZvbGxvd2luZyBhcmUgZXhhbXBsZXMgb2Ygc2VlIHBhcmFncmFwaHMs
IHdoaWNoIG1heSBiZSB1c2VkIGluIGFueSBkb2N1bWVudGF0aW9uIGNvbW1l
bnQgdG8gaW5kaWNhdGUgYSBjcm9zcy1yZWZlcmVuY2UgdG8gYSB0eXBlLCBt
ZXRob2QsIGNvbnN0cnVjdG9yLCBmaWVsZCwgVVJMLCBvciBhbnkgdGV4dDo8
L3A+DQoNCjxwcmU+DQoJLyoqDQoJICogc2VlOiBjLnN0ZGlvDQoJICogc2Vl
OiBzdHJpbmcNCgkgKiBzZWU6IHN0cmluZy5lcXVhbHMNCgkgKiBzZWU6IHRo
cmVhZHMudGhyZWFkLndhaXQoaW50KQ0KCSAqIHNlZTogUmFuZG9tQWNjZXNz
RmlsZS5SYW5kb21BY2Nlc3NGaWxlKEZpbGUpDQoJICogc2VlOiBSYW5kb21B
Y2Nlc3NGaWxlLlJhbmRvbUFjY2Vzc0ZpbGUoRmlsZSwgU3RyaW5nKQ0KCSAq
IHNlZTogQ2hhcmFjdGVyLk1BWF9SQURJWA0KCSAqIHNlZTogIkQgTGFuZ3Vh
Z2UgU3BlY2lmaWNhdGlvbiIgYXQgaHR0cDovL3d3dy5kaWdpdGFsbWFycy5j
b20vZC9zcGVjLmh0bWwNCgkgKiBzZWU6ICJEIFByb2dyYW1taW5nIFR1dG9y
aWFsIg0KCSoqLw0KCWNsYXNzIGltcGxlbWVudGF0aW9uOw0KPC9wcmU+DQoN
CjxwPlRoZSBjaGFyYWN0ZXIgIi4iIHNlcGFyYXRlcyB0aGUgbmFtZSBvZiBh
IG1vZHVsZSBvZiBhIGNsYXNzIGFuZCB0aGUgbmFtZSBvZiBhIGNsYXNzIGZy
b20gdGhlIG5hbWUgb2Ygb25lIG9mIGl0cyBmaWVsZHMsIG1ldGhvZHMsIG9y
IGNvbnN0cnVjdG9ycy4gVGhlIG9yZGVyIG9mIHNlYXJjaGluZyBpcyBwYWNr
YWdlLCBtb2R1bGUsIHR5cGUsIG1ldGhvZC4gT25lIG9mIHNldmVyYWwgb3Zl
cmxvYWRlZCBtZXRob2RzIG9yIGNvbnN0cnVjdG9ycyBtYXkgYmUgc2VsZWN0
ZWQgYnkgaW5jbHVkaW5nIGEgcGFyZW50aGVzaXplZCBsaXN0IG9mIGFyZ3Vt
ZW50IHR5cGVzIGFmdGVyIHRoZSBtZXRob2Qgb3IgY29uc3RydWN0b3IgbmFt
ZS4NCg0KPGgyPlRhZyBjYXRlZ29yeTwvaDI+DQoNCjxwPlRoZSBjYXRlZ29y
eSB0YWdsaW5lIHNwZWNpZnkgaW4gd2hhdCBjYXRlZ29yeSB0aGUgdHlwZSBv
ciBtZXRob2QgaXMgZ3J1cGVkLiBJdCBjb3VsZCBiZSB1c2VkIGluIGNsYXNz
ZXMgdG8gY2xhc3NpZnkgdGhlIHByb3BlcnRpZXMsIG1ldGhvZHMgYW5kIG1l
bWJlcnMgaW4gYSBjbG9zZWQgc2NvcGUuPC9wPg0KDQo8cD5UaGUgZm9sbG93
aW5nIGlzIGFuIGV4YW1wbGUgb2YgYSBjYXRlZ29yeSBwYXJhZ3JhcGgsIHdo
aWNoIG1heSBiZSB1c2VkIGluIGRvY3VtZW50YXRpb24gY29tbWVudHMgZm9y
IGRlY2xhcmF0aW9ucyBvZiBhIGZ1bmN0aW9uczo8L3A+DQoNCjxwcmU+DQoJ
LyoqDQoJICogY2F0ZWdvcnk6IFRlbXBlcmF0dXJlIGhhbmRsaW5nIHJvdXRp
bmVzDQoJKiovDQoJaW50IHRlbXBlcmF0dXJlIHsNCgkuLi4NCgl9DQo8L3By
ZT4NCg0KPGgyPlRhZyBleGFtcGxlPC9oMj4NCg0KPHA+QWRkcyBhIGV4YW1w
bGUgY29waWVkIHZlcmJhdGltIHRvIGRvY3VtZW50YXRpb24uPC9wPg0KDQo8
cD5UaGUgZm9sbG93aW5nIGlzIGFuIGV4YW1wbGUgb2YgYSBleGFtcGxlIHBh
cmFncmFwaCwgd2hpY2ggbWF5IGJlIHVzZWQgaW4gZG9jdW1lbnRhdGlvbiBj
b21tZW50cyBmb3IgcHJvdmlkaW5nIHVzZXIgZXhhbXBsZXM6PC9wPg0KDQo8
cHJlPg0KCS8qKg0KCSAqIGV4YW1wbGU6DQoJICoNCgkgKiAvLyBUaGlzIGls
dXN0cmF0ZSBob3cgdG8gdXNlIGEgcmVnZXhwIHRvIG1hdGNoIGEgc3RyaW5n
DQoJICogUmVnRXhwIG15UmVnRXhwID0gbmV3IFJlZ0V4cCgiW0EtWmEtelxi
IV0qIik7DQoJICogaWYgKFJlZ0V4cC5NYXRjaCgiSGVsbG8gV29ybGQhIikN
CgkgKiAgIHByaW50ZigiSGVsbG8gV29ybGQhIik7DQoJKiovDQoJY2xhc3Mg
UmVnRXhwDQoJew0KCS4uLg0KCX0NCjwvcHJlPg0KDQo8cD5UaGUgZm9ybWF0
dGluZyBpbiB0aGUgZG9jdW1lbnRhdGlvbiByZW1haW5zIGV4YWN0bHkgdGhl
IHNhbWUgYXMgaXQgaXMgaW4gdGhlIHNvdXJjZSBjb2RlLiBObyB3aGl0ZXNw
YWNlIGlzIHJlbW92ZWQuIEEgbm9uLXByb3BvcnRpb25hbCBmb250LCBzdWNo
IGFzIGNvdXJpZXIgaXMgdXNlZCBmb3IgdGhlIGV4YW1wbGVzLCBzbyBzaW1w
bGUgQVNDSUkgZHJhd2luZ3Mgd2lsbCBzdXJ2aXZlIHRoZSB0cmFuc2xhdGlv
biBpbnRhY3QuPC9wPg0KDQo8aDI+VGFnIGJ1ZzwvaDI+DQoNCjxwPlNwZWNp
Znkga25vd24gaXNzdWUgaW4gdHlwZXMsIG1ldGhvZHMgb3Igcm91dGluZXMu
PC9wPg0KDQo8cD5UaGUgZm9sbG93aW5nIGlzIGFuIGV4YW1wbGUgb2YgYSBi
dWcgcGFyYWdyYXBoLCB3aGljaCBtYXkgYmUgdXNlZCBpbiBkb2N1bWVudGF0
aW9uIGNvbW1lbnRzIGZvciBkZWNsYXJhdGlvbnMgb2YgYSBmdW5jdGlvbnM6
PC9wPg0KDQo8cHJlPg0KCS8qKg0KCSAqIGJ1ZzogU2V2ZXJpdHkgSGlnaC4g
V2luZG93cyA5eCBkb250IHBhc3MgdGhlIGNvcnJlY3QgbWVtb3J5IHVzZWQN
CgkqKi8NCglpbnQgbWVtb3J5VXNlZCB7DQoJLi4uDQoJfQ0KPC9wcmU+DQoN
CjxoMj5UYWcgdG9kbzwvaDI+DQoNCjxwPlNwZWNpZnkgd29yayB0byBiZSBk
b25lLCBzdWNoIGFzIGltcGxlbWVudGluZywgb3B0aW1pemluZyBvciBvciBk
b2N1bWVudGluZyBjZXJ0YWluIHR5cGVzIGFuZCBtZXRob2RzLjwvcD4NCg0K
PHA+VGhlIGZvbGxvd2luZyBpcyBhbiBleGFtcGxlIG9mIGEgdG9kbyBwYXJh
Z3JhcGgsIHdoaWNoIG1heSBiZSB1c2VkIGluIGRvY3VtZW50YXRpb24gY29t
bWVudHMgZm9yIGRlY2xhcmF0aW9ucyBvZiBhIGNsYXNzOjwvcD4NCg0KPHBy
ZT4NCgkvKioNCgkgKiB2ZXJzaW9uOiAxLjANCgkgKiB0b2RvOiBtb2RpZnkg
dG8gcGVybWl0IGV2YWx1YXRlIGEgc3RyaW5nIGNhcmFjdGVyIGJ5IGNhcmFj
dGVyDQoJKiovDQoJY2xhc3MgUmVnRXhwDQoJew0KCS4uLg0KCX0NCjwvcHJl
Pg0KDQo8aDI+VGFnIGdsb3NzYXJ5PC9oMj4NCg0KPHA+U3BlY2lmeSBhIHRl
eHQgdG8gYnVpbGQgYSBnbG9zc2FyeSBieSBzdWJqZWN0LiBUaGUgZ2xvc3Nh
cnkgdGFnIGlzIGEgdGFnbGluZSBidXQgYSBkb2N1bWVudGF0aW9uIGNvbW1l
bnQgbWF5IGNvbnRhaW4gbW9yZSB0aGFuIG9uZSBnbG9zc2FyeSB0YWcuPC9w
Pg0KDQo8cD5UaGUgZm9sbG93aW5nIGlzIGFuIGV4YW1wbGUgb2YgYSB0b2Rv
IHRhZ2xpbmUsIHdoaWNoIG1heSBiZSB1c2VkIGluIGRvY3VtZW50YXRpb24g
Y29tbWVudHMgZm9yIGRlY2xhcmF0aW9ucyBvZiBhIGZ1bmN0aW9uOjwvcD4N
Cg0KPHByZT4NCgkvKioNCgkgKiBnbG9zc2FyeTogRGVsZXRpbmcgZmlsZXMN
CgkgKiBnbG9zc2FyeTogRXJhc2luZyBmaWxlcw0KCSoqLw0KCXZvaWQgZGVs
ZWxlZmlsZShzdHJpbmcgZmlsZW5hbWUpew0KCS4uLg0KCX0NCjwvcHJlPg0K
DQo8aDI+VGFnIHN1bW1hcnk8L2gyPg0KDQo8cD5UaGUgZm9sbG93aW5nIGlz
IGFuIGV4YW1wbGUgb2YgYW4gc3VtbWFyeSB0YWdsaW5lLCB3aGljaCBtYXkg
YmUgdXNlZCBmb3Igc2hvcnQgZGVzY3JpYmluZyBhIGFydGlmYWN0OjwvcD4N
Cg0KPHByZT4NCgkvKioNCgkgKiBzdW1tYXJ5OiBJbnRlcmZhY2VEaXNjb25u
ZWN0IGRpc2Nvbm5lY3RzIGFuIElDb25uZWN0aW9uUG9pbnQgaW50ZXJmYWNl
Lg0KCSAqDQoJICogSW50ZXJmYWNlRGlzY29ubmVjdCBkaXNjb25uZWN0cyBh
biBJQ29ubmVjdGlvblBvaW50IGludGVyZmFjZSBjb25uZWN0aW9uDQoJICog
dGhhdCB3YXMgcHJldmlvdXNseSBtYWRlIGJ5IHRoZSBJbnRlcmZhY2VDb25u
ZWN0IHByb2NlZHVyZS4NCgkgKiBUaGVzZSBwcm9jZWR1cmVzIGFyZSB3cmFw
cGVycyBmb3IgdGhlIEFjdGl2ZVggZXZlbnQtaGFuZGxpbmcgbWVjaGFuaXNt
LA0KCSAqIHRoZSAgSUNvbm5lY3Rpb25Qb2ludENvbnRhaW5lciBhbmQgSUNv
bm5lY3Rpb25Qb2ludCBpbnRlcmZhY2VzLg0KCSoqLw0KCXZvaWQgSW50ZXJm
YWNlRGlzY29ubmVjdChJVW5rbm93biBTb3VyY2UsIENsYXNzSUlEIElJRCk7
DQo8L3ByZT4NCg0KPGgxPkdlbmVyaWMgdGFnczwvaDE+DQoNCjxoMj5UYWdz
IGZvciBwYXJhbWV0ZXJzPC9oMj4NCg0KPHA+VGhlIGZvbGxvd2luZyBhcmUg
ZXhhbXBsZXMgb2YgcGFyYW1ldGVycyBwYXJhZ3JhcGhzLCB3aGljaCBtYXkg
YmUgdXNlZCBpbiBkb2N1bWVudGF0aW9uIGNvbW1lbnRzIGZvciBtZXRob2Qg
YW5kIGNvbnN0cnVjdG9yIGRlY2xhcmF0aW9uczo8L3A+DQoNCjxwcmU+DQoJ
LyoqDQoJICogZmlsZTogdGhlIGZpbGUgdG8gYmUgc2VhcmNoZWQNCgkgKiBw
YXR0ZXJuOiB0aGUgcGF0dGVybiB0byBiZSBtYXRjaGVkIGR1cmluZyB0aGUg
c2VhcmNoLiBUaGUgcGF0dGVybiBjb3VsZA0KCSAqIGNvbnNpc3Qgb2YgYSBz
aW1wbGUgc3RyaW5nIG9yIGEgcmVndWxhciBleHByZXNzaW9uLg0KCSAqIGNv
dW50OiB0aGUgbWF4IG51bWJlciBvZiBsaW5lcyB0byBicmluZ3MgZm9yIGVh
Y2ggbWF0Y2guIE8gZm9yIGFsbCBsaW5lczsNCgkgKg0KCSAqIE1hdGNoZXMg
bGluZXMgaW4gYSBmaWxlIHdoaWNoIGZvbGxvdyBhIHBhdHRlcm4uDQoJKiov
DQoJY2hhcltdIG1hdGNoTGluZXMoRmlsZSBmaWxlLCBjaGFyW10gcGF0dGVy
biwgaW50IGNvdW50KTsNCjwvcHJlPg0KDQo8cD5UaGUgaW5mb3JtYXRpb24g
aW4gYSBwYXJhbWV0ZXIgcGFyYWdyYXBoIHNob3VsZCBjb25zaXN0IG9mIHRo
ZSBuYW1lIG9mIHRoZSBwYXJhbWV0ZXIgZm9sbG93ZWQgYnkgYSBzaG9ydCBk
ZXNjcmlwdGlvbi48L3A+DQoNCjxwPkEgZG9jdW1lbnRhdGlvbiBjb21tZW50
IG1heSBjb250YWluIG1vcmUgdGhhbiBvbmUgcGFyYW1ldGVyIHRhZy4gVGhl
IHVzdWFsIGNvbnZlbnRpb24gaXMgdGhhdCBpZiBhbnkgcGFyYW1ldGVyIHBh
cmFncmFwaHMgYXJlIHByZXNlbnQgaW4gYSBkb2N1bWVudGF0aW9uIGNvbW1l
bnQsIHRoZW4gdGhlcmUgc2hvdWxkIGJlIG9uZSBwYXJhbWV0ZXIgcGFyYWdy
YXBoIGZvciBlYWNoIHBhcmFtZXRlciBvZiB0aGUgbWV0aG9kIG9yIGNvbnN0
cnVjdG9yLCBhbmQgdGhlIHBhcmFtZXRlcnMgcGFyYWdyYXBocyBzaG91bGQg
YXBwZWFyIGluIHRoZSBvcmRlciBpbiB3aGljaCB0aGUgcGFyYW1ldGVycyBh
cmUgZGVjbGFyZWQgYnV0IHRoaXMgaXMgbm90IG1hbmRhdG9yeS48L3A+DQoN
CjxoMj5UYWdzIGZvciBpbXBvcnRzPC9oMj4NCg0KPHA+VGhlIGZvbGxvd2lu
ZyBpcyBhbiBleGFtcGxlIG9mIGFuIGltcG9ydCBwYXJhZ3JhcGgsIHdoaWNo
IG1heSBiZSB1c2VkIGluIGRvY3VtZW50YXRpb24gY29tbWVudHMgZm9yIG1v
ZHVsZXMgaW1wb3J0czo8L3A+DQoNCjxwcmU+DQoJLyoqDQoJICogQXV4aWxp
YXJ5IHJvdXRpbmVzDQoJKiovDQoJaW1wb3J0IG15bW9kdWxlOw0KPC9wcmU+
DQoNCjxwPlRoZSBpbmZvcm1hdGlvbiBpbiBhbiBpbXBvcnQgcGFyYWdyYXBo
IHNob3VsZCBjb25zaXN0IG9mIHRoZSBuYW1lIG9mIGFuIG1vZHVsZSAod2hp
Y2ggbWF5IGJlIGEgc2ltcGxlIG5hbWUgb3IgYSBxdWFsaWZpZWQgbmFtZSkg
Zm9sbG93ZWQgYnkgYSBzaG9ydCBkZXNjcmlwdGlvbiBvZiB0aGUgbmVlZCBv
ciBkZXBlbmRlbmN5IHJlYXNvbi48L3A+DQo8cD5BZGRpdGlvbmFseSwgbW9k
dWxlcyBjYW4gYmUgZG9jdW1lbnRlZCB0b2dldGhlciBzaW1wbHkgYnkgc3Bl
Y2lmeWluZyB0aGUgbmFtZSBvZiBtb2R1bGUgY29udGFpbmVkIGluIHRoZSBj
b2xvbiBsaXN0LjwvcD4NCjxwcmU+DQoJLyoqDQoJICogbXltb2R1bGU6IEF1
eGlsaWFyeSByb3RpbmVzDQoJICogYy5zdGRpbzogbmVlZGVkIGZvciBwcmlu
dGYgZnVuY3Rpb24NCgkgKiBzdHJlYW06IG5lZWRlZCBmb3IgcmVhZGluZyBh
bmQgd3JpdGluZyB0byBmaWxlcw0KCSoqLw0KCWltcG9ydCBteW1vZHVsZSwg
Yy5zdGRpbywgc3RyZWFtOw0KPC9wcmU+DQoNCjxoMj5UYWdzIGZvciBleGNl
cHRpb25zPC9oMj4NCg0KPHA+VGhlIGZvbGxvd2luZyBpcyBhbiBleGFtcGxl
IG9mIGFuIGV4Y2VwdGlvbiBwYXJhZ3JhcGgsIHdoaWNoIG1heSBiZSB1c2Vk
IGluIGRvY3VtZW50YXRpb24gY29tbWVudHMgZm9yIG1ldGhvZCBhbmQgY29u
c3RydWN0b3IgZGVjbGFyYXRpb25zOjwvcD4NCg0KPHByZT4NCgl2b2lkIHZl
cmlmeVdpZGdldChXaWRnZXQgd2lkZ2V0KQ0KCXsNCgkJaWYgKCF3aWRnZXQu
ZmxhbmdlZCkNCgkJCS8vLyB0aGUgd2lkZ2V0IGRvZXMgbm90IGhhdmUgYSBm
bGFuZ2UsIG9yIGl0cyBmbGFuZ2UgaGFzIHNpemUgemVybw0KCQkJdGhyb3cg
bmV3IFVuZmxhbmdlZFdpZGdldEVycm9yKCZhY3V0ZTtNaXNzaW5nIGZsYW5n
ZSZhY3V0ZTspOw0KCQlpZiAoIXdpZGdldC5jYW5Vc2UpDQoJCQkvKioNCgkJ
CSAqIHRoZSB3aWRnZXQgY2Fubm90IGJlIHVzZWQuIFRoaXMgaGFwcGVucyBi
ZWNhdXNlIGl0IHdhcyBub3QNCgkJCSAqIGluaXRpYWxpemVkLCBpdCB3YXMg
bm90IGF0dGFjaGVkIHRvIGEgbWFuYWdlciwgaXQgd2FzIG5vdA0KCQkJICog
Y29uZmlndXJlZCBvciBpdCBpcyBoaWRlZC4NCgkJCSoqLw0KCQkJdGhyb3cg
bmV3IFVudXNhYmxlV2lkZ2V0RXJyb3IoKTsNCgkJaWYgKHdpZGdldC5JblVz
ZSkNCgkJCXRocm93IG5ldyBMb2NrV2lkZ2V0RXJyb3IoIldpZGdldCBpcyBh
bHJlYWR5IGluIHVzZSIpOyAvLy8mbHQ7IHRoZSB3aWRnZXQgaXMgYWxyZWFk
eSB1c2VkDQoJfQ0KPC9wcmU+DQoNCjxwPlRoZSBjb21tZW50IGluIGFuIGV4
Y2VwdGlvbiBwYXJhZ3JhcGggaXMgYXR0YWNoZWQgd2l0aCB0aGUgbWV0aG9k
IHdoaWNoIHRoZSBlcnJvciBpcyB0aHJvd2VkLiBGb3IgZG9jdW1lbnRpbmcg
dGhlIGV4Y2VwdGlvbiB1c2UgYSBub3JtYWwgdGFnIG9uY2UgYSBleGNlcHRp
b24gaXMgYSBjbGFzcy48L3A+DQoNCjxwPlRoZSBpbmZvcm1hdGlvbiBpbiBh
biBleGNlcHRpb24gcGFyYWdyYXBoIHNob3VsZCBjb25zaXN0IGJ5IGEgc2hv
cnQgZGVzY3JpcHRpb24gb2YgdGhlIGNpcmN1bXN0YW5jZXMgdGhhdCBjYXVz
ZSB0aGUgZXhjZXB0aW9uIHRvIGJlIHRocm93bi4NCg0KPGgyPlRhZ3MgZm9y
IHJldHVybiB2YWx1ZXM8L2gyPg0KDQo8cD5UaGUgZm9sbG93aW5nIGlzIGFu
IGV4YW1wbGUgb2YgYW4gcmV0dXJuIHBhcmFncmFwaCwgd2hpY2ggbWF5IGJl
IHVzZWQgaW4gZG9jdW1lbnRhdGlvbiBjb21tZW50cyBmb3IgbWV0aG9kIGFu
ZCBmdW5jdGlvbnMgZGVjbGFyYXRpb25zOjwvcD4NCg0KPHByZT4NCglieXRl
IGNtcFN0cmluZyhjaGFyW10gc3RyMSwgY2hhcltdIHN0cjIpDQoJew0KCQlp
ZiAoc3RyMSAmbHQ7IHN0cjIpDQoJCQkvKiogaWYgdGhlIGZpcnN0IHN0cmlu
ZyBpcyBzbWFsbGVyIHRoYW4gc2Vjb25kLg0KCQkJICogcmV0dXJuIGEgcG9z
aXRpdmUgbnVtYmVyDQoJCQkgKi8NCgkJCXJldHVybiAxOw0KCQlpZiAoc3Ry
MSA9PSBzdHIyKQ0KCQkJLy8vIGlmIHN0cmluZ3MgYXJlIGVxdWFsIHJldHVy
biB6ZXJvDQoJCQlyZXR1cm4gPSAwOw0KCQlpZiAoc3RyMSA9PSBzdHIyKQ0K
CQkJLy8vIGlmIHRoZSBmaXJzdCBzdHJpbmcgaXMgZ3JlYXRlciB0aGFuIHNl
Y29uZC4NCgkJCS8vLyByZXR1cm4gYSBuZWdhdGl2ZSBudW1iZXINCgkJCXJl
dHVybiA9IC0xOw0KCX0NCjwvcHJlPg0KDQo8cD5UaGUgY29tbWVudCBpbiBh
biByZXR1cm4gcGFyYWdyYXBoIGlzIGF0dGFjaGVkIHdpdGggdGhlIG1ldGhv
ZCByZXR1cm5pbmcgaXRzZWxmLjwvcD4NCg0KPHA+VGhlIGluZm9ybWF0aW9u
IGluIGFuIHJldHVybiBwYXJhZ3JhcGggc2hvdWxkIGNvbnNpc3QgYnkgYSBz
aG9ydCBkZXNjcmlwdGlvbiBvZiB0aGUgZG9tYWluIHNldCByZXR1cm5lZCBi
eSB0aGUgZnVuY3Rpb24gYW5kIGEgc2hvcnQgZXhwbGFuYXRpb24gYWJvdXQg
dGhlIGltYWdlIHNldC4NCg0KPGgyPlRhZ3MgZm9yIEF0dHJpYnV0ZXM8L2gy
Pg0KDQo8cD5Ob3QgYWxsIEF0dHJpYnV0ZXMgc3RhdGVtZW50cyBjYW4gYmUg
ZG9jdW1lbnRlZC4gVGhlcmUgYXJlIG5vIG1lYW5pbmcgaW4gaW5jbHVkZSBk
b2N1bWVudGF0aW9uIGZvciB0aGUgZm9sbG93aW5nIHRhZ3M6PC9wPg0KPHVs
Pg0KCTxsaT5wcml2YXRlPC9saT4NCgk8bGk+cHJvdGVjdGVkPC9saT4NCgk8
bGk+cHVibGljPC9saT4NCgk8bGk+ZXhwb3J0PC9saT4NCjwvdWw+DQoNCjxw
Pk5ldmVydGhlbGVzcyB0aGUgdG9vbCBpbXBsZW1lbnRpbmcgZG9jdW1lbnRh
dGlvbiBjb21tZW50cyBjb3VsZCBpbmNsdWRlIGF1dG9tYXRpY2FsbHkgdGhl
IGluZm9ybWF0aW9uIGFuZCBzaG93IG9yIGhpZGUgZm9sbG93aW5nIHVzZXIg
Y29tbWFuZC48L3A+DQo8cD5UaGUgZm9sbG93aW5nIGF0dHJpYnV0ZXMgY2Fu
IGJlIGNvbW1lbnRlZDo8cD4NCjx1bD4NCgk8bGk+ZGVwcmVjYXRlZDwvbGk+
DQoJPGxpPm92ZXJyaWRlPC9saT4NCgk8bGk+YWJzdHJhY3Q8L2xpPg0KCTxs
aT5jb25zdDwvbGk+DQoJPGxpPmZpbmFsPC9saT4NCgk8bGk+c3RhdGljPC9s
aT4NCjwvdWw+DQoNCjxwcmU+DQoJLyoqDQoJICogQXMgb2YgRCAyLjAsIHJl
cGxhY2VkIGJ5IHN0cmVhbSBoYW5kbGluZyBtZXRob2RzDQoJICogc2VlOiBz
dHJlYW0NCgkqKi8NCglkZXByZWNhdGVkDQoJew0KCQljaGFyW10gcmVhZChG
aWxlIGYpDQoJCXsNCgkJLi4uDQoJCX0NCg0KCQlpbnQgd3JpdGUoRmlsZSBm
LCBjaGFyW10gYnVmZmVyKQ0KCQl7DQoJCS4uDQoJCX0NCgl9DQo8L3ByZT4N
Cg0KPGgyPlRhZ3MgZm9yIENvbnRyYWN0czwvaDI+DQoNCjxwPkNvbnRyYWN0
cyBhcmUgYSBicmVha3Rocm91Z2ggdGVjaG5pcXVlIHRvIHJlZHVjZSB0aGUg
cHJvZ3JhbW1pbmcgZWZmb3J0IGZvciBsYXJnZSBwcm9qZWN0cy4gQ29udHJh
Y3RzIGFyZSB0aGUgY29uY2VwdCBvZiBwcmVjb25kaXRpb25zLCBwb3N0Y29u
ZGl0aW9ucywgZXJyb3JzLCBhbmQgaW52YXJpYW50cy4gQ29udHJhY3RzIGZv
cm0gcGFydCBvZiB0aGUgc3BlY2lmaWNhdGlvbiBmb3IgYSBwcm9ncmFtLCBt
b3ZpbmcgaXQgZnJvbSB0aGUgZG9jdW1lbnRhdGlvbiB0byB0aGUgY29kZSBp
dHNlbGYuPHA+DQoNCjxwPlRoZSBjb21tZW50IGluIGFuIGFzc2VydCBjb250
cmFjdCBpcyBhdHRhY2hlZCB3aXRoIHRoZSBtZXRob2Qgd2hpY2ggdGhlIGNv
bnRyYWN0IGlzIHZlcmlmaWVkLiBGb3IgZG9jdW1lbnRpbmcgdGhlIGNvbnRy
YWN0IHVzZSBhIG5vcm1hbCB0YWcgZXhwbGFpbmluZyB0aGUgcmVhc29uIG9z
IHN1Y2ggcmVzdHJpY3Rpb24uIEFzc2VydCBjb250cmFjdCB3aXRob3V0IGEg
ZG9jdW1lbnRhdGlvbiBjb21tZW50IGlzIG5vdCBhZGRlZCBpbiB0aGUgZG9j
dW1lbnRhdGlvbi48L3A+DQoNCjxwPk5vdCBhbGwgY29udHJhY3RzIGNhbiBi
ZSBkb2N1bWVudGVkLiBGb2xsb3dpbmcgdGFncyBhcmUgbm90IGRvY3VtZW50
ZWQ6PC9wPg0KDQo8dWw+DQoJPGxpPm91dCBjb250cmFjdHMgaW4gbWV0aG9k
czwvbGk+DQoJPGxpPnVuaXR0ZXN0IGNvbnRyYWN0czwvbGk+DQo8L3VsPg0K
DQo8cD5UaGVyZSBhcmUgbm8gbWVhbmluZyBpbiBpbmNsdWRlIGRvY3VtZW50
YXRpb24gZm9yIHRoZXNlIGNvbnRyYWN0cyBiZWNhdXNlIHRoZXkgYXJlIGNv
bW1vbmx5IHVzZWQgZm9yIHZlcmlmaWNhdGlvbiBvZiBhY2N1cmFjeSBvZiBy
ZXN1bHRzIGFuZCBmb3IgZGV0ZXJtaW5pbmcgaWYgdGhlIGNvZGUgaXMgd29y
a2luZyBwcm9wZXJseS48L3A+DQoNCjxwPlRoZSBmb2xsb3dpbmcgY29udHJh
Y3RzIGNhbiBiZSBjb21tZW50ZWQ6PHA+DQo8dWw+DQoJPGxpPmluIGNvbnRy
YWN0cyBpbiBtZXRob2RzPC9saT4NCgk8bGk+Y2xhc3MgaW52YXJpYW50czwv
bGk+DQo8L3VsPg0KDQo8aDM+SW4gQ29udHJhY3RzPC9oMz4NCg0KPHA+VGhl
IGZvbGxvd2luZyBpcyBhbiBleGFtcGxlIG9mIGRvY3VtZW50YXRpb24gb2Yg
YW4gYXNzZXJ0IGNvbnRyYWN0IGluIGEgZnVuY3Rpb24gaW4gY29udHJhY3Q6
PC9wPg0KDQo8cHJlPg0KCWludCBkaXYoaW50IHggLCBpbnQgeSkNCglpbg0K
CXsNCgkJLy8vIFRoZSBkaXZpc29yIGNhbm5vdCBiZSB6ZXJvLg0KCQlhc3Nl
cnQoeSAhPSAwKTsNCgl9DQoJYm9keQ0KCXsNCgkJcmV0dXJuIHggLyB5Ow0K
CX0NCjwvcHJlPg0KDQo8aDM+Q2xhc3MgSW52YXJpYW50czwvaDM+DQoNCjxw
PlRoZSBmb2xsb3dpbmcgaXMgYW4gZXhhbXBsZSBvZiBkb2N1bWVudGF0aW9u
IG9mIGFuIGFzc2VydCBjb250cmFjdCBpbiBhIGNsYXNzIGludmFyaWFudDo8
L3A+DQoNCjxwcmU+DQoJY2xhc3MgRGF0ZQ0KCXsNCgkJaW50IGRheTsNCgkJ
aW50IGhvdXI7DQoNCgkJaW52YXJpYW50KCkNCgkJew0KCQkJLy8vIFRoZSBk
YXkgbXVzdCBiZSBiZXR3ZWVuIDEgYW5kIDMxDQoJCQlhc3NlcnQoMSA8PSBk
YXkgJiYgZGF5IDw9IDMxKTsNCgkJCS8vLyBUaGUgaG91ciBtdXN0IGJlIGJl
dHdlZW4gMCBhbmQgMjMNCgkJCWFzc2VydCgwIDw9IGhvdXIgJiYgaG91ciA8
IDI0KTsNCgkJfQ0KCX0NCjwvcHJlPg0KDQo8aDE+VGFncyBhbmQgdmVyc2lv
bmluZzwvaDE+DQoNCjxwPlRhZ3Mgd2lsbCBiZSBpbmNsdWRlZCBpbiBkb2N1
bWVudGF0aW9uIGZvbGxvd2luZyB0aGUgdmVyc2lvbmluZyBzY2hlbWUuPC9w
Pg0KDQo8aDE+VGFncyBhbmQgaW5oZXJpdGFuY2U8L2gxPg0KDQo8cD5Jbmhl
cml0ZWQgY2xhc3NlcyBhbmQgc3RydWN0cyB3aWxsIGluaGVyaXQgdGFncyBm
b3IgYWxsIG1ldGhvZHMgZGVmaW5lZCBpbiBhbmNlc3RyYWwgd2hpY2ggYXJl
IG5vdCBtb2RpZmllZCBieSBhbiBuZXcgZG9jdW1lbnRhdGlvbiBjb21tZW50
LjwvcD4NCg0KPGgxPkNvbXBpbGF0b24gcHJvY2VzczwvaDE+DQoNCjxwPlRo
ZSBjb21waWxlciB3aWxsIHBhcnNlIGVhY2ggZmlsZSBhbmQgZ2VuZXJhdGUg
YSBuZXcgZmlsZSBjb250YWluaW5nIHRoZSBjb21tZW50cyBzdHJpcHBlZCBm
cm9tIHNvdXJjZSBhbmQgYWxsIGluZm9ybWF0aW9uIGFib3V0IHRoZSBmZWF0
dXJlIGJlaW5nIGRvY3VtZW50ZWQuPC9wPg0KDQo8cD5UaGUgZm9ybWF0IG9m
IGFsbCBmaWxlcyBnZW5lcmF0ZWQgaXMgdGhlIGRvY2Jvb2NrIGZvcm1hdC4g
RWFjaCBzb3VyY2UgZmlsZSBnZW5lcmF0ZXMgb25lIG5ldyBmaWxlIGNvbnRh
aW5pbmcgYSBzZWN0aW9uIGluIGEgZG9jYm9vayBib29rLiBUaGUgZG9jdW1l
bnQgbXVzdCBiZSBhbHNvIGEgdmFsaWQgWE1MIDEuMCBkb2N1bWVudC48L3A+
DQoNCjxwPlVzZXJzIGNvdWxkIHVzZSBhIGRvY2Jvb2sgcHJvY2Vzc29yIGZv
ciBnZW5lcmF0ZSBkb2N1bWVudGF0aW9uIGluIGh0bWwgZm9ybWF0LCB0ZXh0
IGZvcm1hdCwgcGRmIGZvcm1hdCBvciBhbnkgYXZhaWxhYmxlIGZvcm1hdC48
L3A+DQoNCjxwPlVzZXJzIGNhbiBhbHNvIHdyaXRlIHRoZWlyIG93biBwcmVw
cm9jZXNzb3Igc2luY2UgdGhlIG91dHB1dCBvZiBjb2RlIGRvY3VtZW50YXRp
b24gd2lsbCBiZSBhIHNpbXBsZSB4bWwgZG9jdW1lbnQuPHA+DQoNCjxoMT5T
dWdlc3RlZCBjb21tZW50cyBmb3Igc3RhdGVtZW50czwvaDE+DQoNCjxoMj5U
YWdzIGluIHNpbXBsZSB0eXBlcyBhbmQgdmFyaWFibGVzPC9oMj4NCg0KPGgy
PlRhZ3MgaW4gc2ltcGxlIGZ1bmN0aW9uczwvaDI+DQoNCjxoMj5UYWdzIGlu
IHN0cnVjdHVyZXMgYW5kIGNsYXNzZXM8L2gyPg0KDQo8aDE+QmVzdCBwcmFj
dGljZXM8L2gxPg0KDQo8aDI+QSBTdHlsZSBHdWlkZTwvaDI+DQoNCjxwPlRo
ZSBmb2xsb3dpbmcgYXJlIHVzZWZ1bCB0aXBzIGFuZCBjb252ZW50aW9ucyBm
b3Igd3JpdGluZyBkZXNjcmlwdGlvbnMgaW4gZG9jIGNvbW1lbnRzLjwvcD4N
Cg0KPGg1PldoZW4gc3BlY2lmeWluZyBkYXRhIHVzZSBmb3JtYWwgYW5kIHN0
YW5kYXJkIG5vdGF0aW9uPC9oNT4NCg0KPHA+V2hlbiBzcGVjaWZ5aW5nIGRh
dGEgc3VjaCBhcyBkYXRlcyBhbmQgdGltZXMgdXNlIGFjY2VwdGVkIHN0YW5k
YXJkcyBzdWNoIGFzIElTTy4gVGhpcyB3YXkgZm9yZWlnbiByZWFkZXJzIHdp
bGwgbm90IGJlIGNvbmZ1c2VkIGJ5IG1vbnRoLCBkYXkgcG9zaXRpb25zLjwv
cD4NCg0KPHByZT4NCgltb2R1bGUgZ3JlYXRhZGRvbjsgIC8vLyZsdDsgc2hv
dWxkIGJlIHJlYWR5IDIwMDIuMTIuMzEgMDA6MDA6MDAuDQo8L3ByZT4NCg0K
PGg1Pk9taXQgcGFyZW50aGVzZXMgZm9yIHRoZSBnZW5lcmFsIGZvcm0gb2Yg
bWV0aG9kcyBhbmQgY29uc3RydWN0b3JzPC9oNT4NCjxwPldoZW4gcmVmZXJy
aW5nIHRvIGEgbWV0aG9kIG9yIGNvbnN0cnVjdG9yIHRoYXQgaGFzIG11bHRp
cGxlIGZvcm1zLCBhbmQgeW91IG1lYW4gdG8gcmVmZXIgdG8gYSBzcGVjaWZp
YyBmb3JtLCB1c2UgcGFyZW50aGVzZXMgYW5kIGFyZ3VtZW50IHR5cGVzLiBG
b3IgZXhhbXBsZSwgQXJyYXlMaXN0IGhhcyB0d28gYWRkIG1ldGhvZHM6IGFk
ZChPYmplY3QpIGFuZCBhZGQoaW50LCBPYmplY3QpLjwvcD4NCg0KPHByZT4N
CglUaGUgYWRkKGludCwgT2JqZWN0KSBtZXRob2QgYWRkcyBhbiBpdGVtIGF0
IGEgc3BlY2lmaWVkIHBvc2l0aW9uIGluIHRoaXMgYXJyYXlsaXN0Lg0KPC9w
cmU+DQoNCjxwPkhvd2V2ZXIsIGlmIHJlZmVycmluZyB0byBib3RoIGZvcm1z
IG9mIHRoZSBtZXRob2QsIG9taXQgdGhlIHBhcmVudGhlc2VzIGFsdG9nZXRo
ZXIuIEl0IGlzIG1pc2xlYWRpbmcgdG8gaW5jbHVkZSBlbXB0eSBwYXJlbnRo
ZXNlcywgYmVjYXVzZSB0aGF0IHdvdWxkIGltcGx5IGEgcGFydGljdWxhciBm
b3JtIG9mIHRoZSBtZXRob2QuIFRoZSBpbnRlbnQgaGVyZSBpcyB0byBkaXN0
aW5ndWlzaCB0aGUgZ2VuZXJhbCBtZXRob2QgZnJvbSBhbnkgb2YgaXRzIHBh
cnRpY3VsYXIgZm9ybXMuIEluY2x1ZGUgdGhlIHdvcmQgIm1ldGhvZCIgdG8g
ZGlzdGluZ3Vpc2ggaXQgYXMgYSBtZXRob2QgYW5kIG5vdCBhIGZpZWxkLjwv
cD4NCg0KPHByZT4NCglUaGUgYWRkIG1ldGhvZCBlbmFibGVzIHlvdSB0byBp
bnNlcnQgaXRlbXMuCQkJKHByZWZlcnJlZCkNCglUaGUgYWRkKCkgbWV0aG9k
IGVuYWJsZXMgeW91IHRvIGluc2VydCBpdGVtcy4JCShhdm9pZCB3aGVuIHlv
dSBtZWFuICJhbGwgZm9ybXMiIG9mIHRoZSBhZGQgbWV0aG9kKQ0KPC9wcmU+
DQoNCjxoNT5Pa2F5IHRvIHVzZSBwaHJhc2VzIGluc3RlYWQgb2YgY29tcGxl
dGUgc2VudGVuY2VzPC9oNT4NCg0KPHA+SW4gdGhlIGludGVyZXN0cyBvZiBi
cmV2aXR5IHRoaXMgY291bGQgYmUgdXNlZC4gVGhpcyBob2xkcyBlc3BlY2lh
bGx5IGluIHRoZSBpbml0aWFsIHN1bW1hcnkgYW5kIGluIHBhcmFtZXRlciB0
YWcgZGVzY3JpcHRpb25zLjwvcD4NCg0KPGg1PlVzZSAzcmQgcGVyc29uIChk
ZXNjcmlwdGl2ZSkgbm90IDJuZCBwZXJzb24gKHByZXNjcmlwdGl2ZSkuPC9o
NT4NCg0KPHA+VGhlIGRlc2NyaXB0aW9uIGlzIGluIDNyZCBwZXJzb24gZGVj
bGFyYXRpdmUgcmF0aGVyIHRoYW4gMm5kIHBlcnNvbiBpbXBlcmF0aXZlLjxw
Pg0KDQo8cHJlPg0KCUdldHMgdGhlIGxhYmVsLgkJCShwcmVmZXJyZWQpDQoJ
R2V0IHRoZSBsYWJlbC4JCQkoYXZvaWQpDQo8L3ByZT4NCg0KPGg1Pk1ldGhv
ZCBkZXNjcmlwdGlvbnMgYmVnaW4gd2l0aCBhIHZlcmIgcGhyYXNlLjwvaDU+
DQo8cD5BIG1ldGhvZCBpbXBsZW1lbnRzIGFuIG9wZXJhdGlvbiwgc28gaXQg
dXN1YWxseSBzdGFydHMgd2l0aCBhIHZlcmIgcGhyYXNlLjwvaDU+DQoNCjxw
cmU+DQoJR2V0cyB0aGUgbGFiZWwgb2YgdGhpcyBidXR0b24uCQkJCQkocHJl
ZmVycmVkKQ0KCVRoaXMgbWV0aG9kIGdldHMgdGhlIGxhYmVsIG9mIHRoaXMg
YnV0dG9uLgkJKGF2b2lkKQ0KPC9wcmU+DQoNCjxoNT5DbGFzcy9pbnRlcmZh
Y2UvZmllbGQgZGVzY3JpcHRpb25zIGNhbiBvbWl0IHRoZSBzdWJqZWN0Ljwv
aDU+DQoNCjxwPiB0aGV5IGNhbiBzaW1wbHkgc3RhdGUgdGhlIG9iamVjdC4g
VGhlc2UgQVBJIG9mdGVuIGRlc2NyaWJlIHRoaW5ncyByYXRoZXIgdGhhbiBh
Y3Rpb25zIG9yIGJlaGF2aW9yczo8L3A+DQoNCjxwcmU+DQoJQSBidXR0b24g
bGFiZWwuCQkJCQkJKHByZWZlcnJlZCkNCglUaGlzIGZpZWxkIGlzIGEgYnV0
dG9uIGxhYmVsLgkJKGF2b2lkKQ0KPC9wcmU+DQoNCjxoNT5Vc2UgInRoaXMi
IGluc3RlYWQgb2YgInRoZSI8L2g1Pg0KDQo8cD5XaGVuIHJlZmVycmluZyB0
byBhbiBvYmplY3QgY3JlYXRlZCBmcm9tIHRoZSBjdXJyZW50IGNsYXNzIGlz
IHByZWZlcnJlZCB1c2UgYSBtb3JlIHNwZWNpZmljIHdvcmQuIEZvciBleGFt
cGxlLCB0aGUgZGVzY3JpcHRpb24gb2YgdGhlIGdldFRvb2xraXQgbWV0aG9k
IHNob3VsZCByZWFkIGFzIGZvbGxvd3M6PC9wPg0KDQo8cHJlPg0KCUdldHMg
dGhlIHRvb2xraXQgZm9yIHRoaXMgY29tcG9uZW50LgkJKHByZWZlcnJlZCkN
CglHZXRzIHRoZSB0b29sa2l0IGZvciB0aGUgY29tcG9uZW50LgkJCShhdm9p
ZCkNCjwvcHJlPg0KDQo8aDU+QWRkIGRlc2NyaXB0aW9uIGJleW9uZCB0aGUg
QVBJIG5hbWUuPC9oNT4NCg0KPHA+VGhlIGJlc3QgQVBJIG5hbWVzIGFyZSAi
c2VsZi1kb2N1bWVudGluZyIsIG1lYW5pbmcgdGhleSB0ZWxsIHlvdSBiYXNp
Y2FsbHkgd2hhdCB0aGUgQVBJIGRvZXMuIElmIHRoZSBkb2MgY29tbWVudCBt
ZXJlbHkgcmVwZWF0cyB0aGUgQVBJIG5hbWUgaW4gc2VudGVuY2UgZm9ybSwg
aXQgaXMgbm90IHByb3ZpZGluZyBtb3JlIGluZm9ybWF0aW9uLiBGb3IgZXhh
bXBsZSwgaWYgbWV0aG9kIGRlc2NyaXB0aW9uIHVzZXMgb25seSB0aGUgd29y
ZHMgdGhhdCBhcHBlYXIgaW4gdGhlIG1ldGhvZCBuYW1lLCB0aGVuIGl0IGlz
IGFkZGluZyBub3RoaW5nIGF0IGFsbCB0byB3aGF0IHlvdSBjb3VsZCBpbmZl
ci4gVGhlIGlkZWFsIGNvbW1lbnQgZ29lcyBiZXlvbmQgdGhvc2Ugd29yZHMg
YW5kIHNob3VsZCBhbHdheXMgcmV3YXJkIHlvdSB3aXRoIHNvbWUgYml0IG9m
IGluZm9ybWF0aW9uIHRoYXQgd2FzIG5vdCBpbW1lZGlhdGVseSBvYnZpb3Vz
IGZyb20gdGhlIEFQSSBuYW1lLjwvcD4NCg0KPHA+VGhlIGRlc2NyaXB0aW9u
IGJlbG93IHNheXMgbm90aGluZyBiZXlvbmQgd2hhdCB5b3Uga25vdyBmcm9t
IHJlYWRpbmcgdGhlIG1ldGhvZCBuYW1lLiBUaGUgd29yZHMgInNldCIsICJ0
b29sIiwgInRpcCIsIGFuZCAidGV4dCIgYXJlIHNpbXBseSByZXBlYXRlZCBp
biBhIHNlbnRlbmNlLiBJdCdzIGJldHRlciA8Yj5hdm9pZDwvYj4gdGhpcyBm
b3JtIG9mIGRvY3VtZW50YXRlLjwvcD4NCg0KPHByZT4NCgkvKioNCgkgKiBT
ZXRzIHRoZSB0b29sIHRpcCB0ZXh0Lg0KCSAqDQoJICogdGV4dDogIFRoZSB0
ZXh0IG9mIHRoZSB0b29sIHRpcC4NCgkqKi8NCglwdWJsaWMgdm9pZCBzZXRU
b29sVGlwVGV4dChTdHJpbmcgdGV4dCk7DQo8L3ByZT4NCg0KPHA+VGhpcyBk
ZXNjcmlwdGlvbiBtb3JlIGNvbXBsZXRlbHkgZGVmaW5lcyB3aGF0IGEgdG9v
bCB0aXAgaXMsIGluIHRoZSBsYXJnZXIgY29udGV4dCBvZiByZWdpc3Rlcmlu
ZyBhbmQgYmVpbmcgZGlzcGxheWVkIGluIHJlc3BvbnNlIHRvIHRoZSBjdXJz
b3IuIFRoaXMgZm9ybSBpcyBwcmVmZXJyZWQgaW4gY29tcGFyaXNvbiB3aXRo
IHRoZSBmaXJzdC48L3A+DQoNCjxwcmU+DQoJLyoqDQoJICogUmVnaXN0ZXJz
IHRoZSB0ZXh0IHRvIGRpc3BsYXkgaW4gYSB0b29sIHRpcC4gICBUaGUgdGV4
dA0KCSAqIGRpc3BsYXlzIHdoZW4gdGhlIGN1cnNvciBsaW5nZXJzIG92ZXIg
dGhlIGNvbXBvbmVudC4NCgkgKg0KCSAqIHRleHQ6ICBUaGUgc3RyaW5nIHRv
IGRpc3BsYXkuICBJZiB0aGUgdGV4dCBpcyBudWxsLA0KCSAqIHRoZSB0b29s
IHRpcCBpcyB0dXJuZWQgb2ZmIGZvciB0aGlzIGNvbXBvbmVudC4NCgkgKi8N
CglwdWJsaWMgdm9pZCBzZXRUb29sVGlwVGV4dChTdHJpbmcgdGV4dCk7DQo8
L3ByZT4NCg0KPHA+QmUgY2xlYXIgd2hlbiB1c2luZyB0aGUgdGVybSBjb21t
b24gdGVybS48L3A+DQoNCjxwPkJlIGF3YXJlIHRoYXQgdGhlIGNvbW1vbiB3
b3JkIGFzICJmaWVsZCIgY2FuIGhhdmUgbWFueSBtZWFuaW5ncyBhbmQgY2Fu
IGNvbmZ1c2UgdGhlIHJlYWRlci48cD4NCg0KPGg1PkF2b2lkIExhdGluPC9o
NT4NCg0KPHA+VXNlICJhbHNvIGtub3duIGFzIiBpbnN0ZWFkIG9mICJha2Ei
LCB1c2UgInRoYXQgaXMiIG9yICJ0byBiZSBzcGVjaWZpYyIgaW5zdGVhZCBv
ZiAiaS5lLiIsIHVzZSAiZm9yIGV4YW1wbGUiIGluc3RlYWQgb2YgImUuZy4i
LCBhbmQgdXNlICJpbiBvdGhlciB3b3JkcyIgb3IgIm5hbWVseSIgaW5zdGVh
ZCBvZiAidml6LiI8L3A+DQoNCjwvYm9keT4NCjwvaHRtbD4NCg0K



 Sep 04 2002