DMD 0.134 release (Ddoc update)

Sep 29, 2005

Walter Bright

Sep 29, 2005

Sep 29, 2005

Sep 29, 2005

Sep 29, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Sep 30, 2005

Oct 01, 2005

Oct 03, 2005

Oct 03, 2005

On Thu, 29 Sep 2005 08:25:40 +0200, Walter Bright <newshound@digitalmars.com> wrote: > Another extensive update of Ddoc, www.digitalmars.com/d/ddoc.html, due to > all the suggestions. Shouldn't there be sections like "Todo:", "Note:" in DDoc? They could be useful I think. BTW I've got a questions. Currently ddoc generates rather simple documentation. Is it going to be simple but efficient way of documentation D or plan is to grow into crossreference doc generator like let say Doxygen. -- Dawid Ciężarkiewicz

"Dawid Ciezarkiewicz" <araelx@gmail.com> wrote in message news:op.sxvj9hny58xlqs@localhost.localdomain... > On Thu, 29 Sep 2005 08:25:40 +0200, Walter Bright <newshound@digitalmars.com> wrote: > > > Another extensive update of Ddoc, www.digitalmars.com/d/ddoc.html, due to > > all the suggestions. > > Shouldn't there be sections like "Todo:", "Note:" in DDoc? They could be useful I think. > > BTW I've got a questions. Currently ddoc generates rather simple documentation. Is it going to be simple but efficient way of documentation D or plan is to grow into crossreference doc generator like let say Doxygen. Certainly Ddoc will grow in capability. But it's already a big productivity booster for writing documentation.

Walter Bright wrote: > Another extensive update of Ddoc, www.digitalmars.com/d/ddoc.html, due to all the suggestions. > > http://www.digitalmars.com/d/changelog.html This works much better for XML output. I still have one problem, though: Colons appearing in the text are problematic, i experienced it with some smilies in my docs. I attached an example d source plus ddoc definition, where the ddoc generator puts the bracket following the smily in some strange place... Briefly described: If a colon appears in the ddoc text, for example: /** * Bugs: This functions is useless :) */ void useless() { } Then ddoc will put a bracket in the output, right after the last DDOC_DECL_DD. I'm still working on XML output, and i think i'll do a nice example of XML to XHTML and XML to XSL-FO conversion, so you can have your docs exported to PDF (for example using Apache FOP).

September 29, 2005

Re: DMD 0.134 release (Ddoc update)

Posted by Kris
in reply to Markus Dangl

Permalink

Kris

Posted in reply to Markus Dangl

Permalink

I'll echo that sentiment -- people use all manner of (natural) language constructs within the documentation proper; including (gasp) punctuation. There's seven different uses of punctuation within this paragraph alone: I'd be horrified to find any of it being treated as "section names".

:)



"Markus Dangl" <danglm@in.tum.de> wrote in message news:dhhpaj$6lu$1@digitaldaemon.com...
> Walter Bright wrote:
> > Another extensive update of Ddoc, www.digitalmars.com/d/ddoc.html, due
to
> > all the suggestions.
> >
> > http://www.digitalmars.com/d/changelog.html
>
> This works much better for XML output. I still have one problem, though: Colons appearing in the text are problematic, i experienced it with some smilies in my docs. I attached an example d source plus ddoc definition, where the ddoc generator puts the bracket following the smily in some strange place...
>
> Briefly described: If a colon appears in the ddoc text, for example:
>
> /**
>   * Bugs: This functions is useless :)
>   */
> void useless()
> {
> }
>
> Then ddoc will put a bracket in the output, right after the last DDOC_DECL_DD.
>
> I'm still working on XML output, and i think i'll do a nice example of XML to XHTML and XML to XSL-FO conversion, so you can have your docs exported to PDF (for example using Apache FOP).
>


----------------------------------------------------------------------------
----


> DDOC =<body>$(BODY)</body>
> DDOC_DECL      =
> DDOC_DECL_DD   = <desc>$0</desc>
> DDOC_SECTIONS  = $0
> DDOC_SUMMARY   =
> DDOC_DESCRIPTION =
> DDOC_SECTION_H =
> DDOC_SECTION   =
> DDOC_MEMBERS   = $0
> DDOC_PARAMS    = <params>$0</params>
> DDOC_PARAM_ROW = <row>$0</row>
> DDOC_PARAM_ID  = <id>$0</id>
> DDOC_PARAM_DESC  = <pdesc>$0</pdesc>
> DDOC_PSYMBOL  =
> DDOC_KEYWORD  =
> DDOC_PARAM    =
> DDOC_AUTHORS   =
> DDOC_BUGS      =
> DDOC_COPYRIGHT =
> DDOC_DATE      =
> DDOC_DEPRECATED =
> DDOC_EXAMPLES  =
> DDOC_HISTORY   =
> DDOC_LICENSE   =
> DDOC_RETURNS   =
> DDOC_SEE_ALSO  =
> DDOC_STANDARDS =
> DDOC_THROWS    =
> DDOC_VERSION   =
> D_CODE =
> B = $0
> I = $0
> U = $0
> P = $0
> DL = $0
> DT = $0
> DD = $0
> TABLE = $0
> TR = $0
> TH = $0
> TD = $0
> OL = $0
> UL = $0
> LI = $0
> BIG = $0
> SMALL = $0
> BR = $0
> RED = $0
> BLUE =  $0
> GREEN = $0
> YELLOW = $0
> BLACK = $0
> WHITE = $0
> LINK = $0
> LINK2 = $+
>


----------------------------------------------------------------------------
----


>
> /**
>  * The smilie in the description of parameter "c"
>  * causes ddoc to put a bracket where no bracket belongs...
>  *
>  * Seems like colons are problematic...
>  *
>  * Params:
>  *      a = Some int value.
>  *      b = You may pass any char
>  *          but it will never be used
>  *          anyways.
>  *      c = A double value :)
>  */
> void foo3(int a, char b, double c)
> {
> }
>
> int main(char[][] args)
> {
> }
>

The problem isn't the :. It's the ). The macro process sees the ) and considers it the end of the macro invocation. To fix, add the macro definition: RPAREN=) and then the smily becomes: :$(RPAREN)

On Thu, 29 Sep 2005 17:53:07 -0700, Walter Bright wrote: > The problem isn't the :. It's the ). The macro process sees the ) and considers it the end of the macro invocation. > > To fix, add the macro definition: > > RPAREN=) > > and then the smily becomes: > > :$(RPAREN) Or SMILEY=:) then use /** * Bugs: This functions is useless $(SMILEY) */ -- Derek (skype: derek.j.parnell) Melbourne, Australia 30/09/2005 12:01:56 PM

Pardon the naiive question, but does this mean one cannot (naturally) use parens (or some other manner of punctuation) within documentation? - Kris "Walter Bright" <newshound@digitalmars.com> wrote in message news:dhi5u2$fl1$1@digitaldaemon.com... > The problem isn't the :. It's the ). The macro process sees the ) and considers it the end of the macro invocation. > > To fix, add the macro definition: > > RPAREN=) > > and then the smily becomes: > > :$(RPAREN) > >

On Thu, 29 Sep 2005 19:21:41 -0700, Kris wrote: > Pardon the naiive question, but does this mean one cannot (naturally) use > parens (or some other manner of punctuation) within documentation? Not quite... You can't use *unmatched* parenthesis easily. For instance if you have ... /** This module is the greatest thing since sliced bread (tm) according to my mother. */ Then you will have no problems. But if you had coded 'tm)' or '(tm' instead, you get issues. The reason is that your text gets inserted into one of the predefined macros this ... $(DDOC_SECTIONS This module is the greatest thing since sliced bread (tm) according to my mother.) And as you can see, the 'tm)' would prematurely end the DDOC_SECTIONS macro and '(tm' would cause the DDOC_SECTIONS macro to extend to the end of the file. -- Derek (skype: derek.j.parnell) Melbourne, Australia 30/09/2005 12:29:01 PM

On Wed, 28 Sep 2005 23:25:40 -0700, Walter Bright wrote: > Another extensive update of Ddoc, www.digitalmars.com/d/ddoc.html, due to all the suggestions. > > http://www.digitalmars.com/d/changelog.html I'm having a lot of trouble getting the 'Copyright:' section to show up. In fact, I cannot work out how to do it. -- Derek (skype: derek.j.parnell) Melbourne, Australia 30/09/2005 12:34:43 PM

Forums