September 30, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Walter Bright | Or you can use ) instead of ). "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 smiley becomes: > > :$(RPAREN) > > | |||
Permalink
ReplySeptember 30, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Kris | "Kris" <fu@bar.com> wrote in message news:dhi7fm$glp$1@digitaldaemon.com... > Pardon the naiive question, but does this mean one cannot (naturally) use > parens (or some other manner of punctuation) within documentation? You can if they match. The argument parser counts them. It also skips parens between "", '', or <!-- -->. It's only the stray ones that'll cause a problem. | |||
September 30, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Derek Parnell | "Derek Parnell" <derek@psych.ward> wrote in message news:1xqvtq2pbycrs$.12nvgnf5vclyi.dlg@40tude.net... > 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. It should show up as an expansion of the $(COPYRIGHT) macro. The reason for that is that often people like to put the copyright notice in unusual places in the DDOC macro. | |||
September 30, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Walter Bright | On Thu, 29 Sep 2005 21:07:48 -0700, Walter Bright wrote: > "Derek Parnell" <derek@psych.ward> wrote in message news:1xqvtq2pbycrs$.12nvgnf5vclyi.dlg@40tude.net... >> 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. > > It should show up as an expansion of the $(COPYRIGHT) macro. The reason for that is that often people like to put the copyright notice in unusual places in the DDOC macro. You misunderstand. I know what it is supposed to do, but I can't work out how to get it to do what it is supposed to do! For example, this doc ... /** A summary line. Author: Me, Myself, and I. Copyright: whatever */ module testdoc; produces this output ... <html><head> <META http-equiv="content-type" content="text/html; charset=utf-8"> <title>testdoc</title> </head><body> <h1>testdoc</h1> <!-- Generated by Ddoc from testdoc.d --> A summary line. <br><br> <b>Author:</b><br><br> Me, Myself, and I. <br><br> <dl></dl> <hr><small>Page generated by <a href="http://www.digitalmars.com/d/ddoc.html">Ddoc</a>.</small> </body></html> Not a copyright in sight. -- Derek (skype: derek.j.parnell) Melbourne, Australia 30/09/2005 2:54:02 PM | |||
September 30, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Derek Parnell | "Derek Parnell" <derek@psych.ward> wrote in message news:kt94sqgzcrsc$.19mc3tnw25crk$.dlg@40tude.net... > On Thu, 29 Sep 2005 21:07:48 -0700, Walter Bright wrote: > > It should show up as an expansion of the $(COPYRIGHT) macro. The reason for > > that is that often people like to put the copyright notice in unusual places > > in the DDOC macro. > > You misunderstand. I know what it is supposed to do, but I can't work out how to get it to do what it is supposed to do! > > For example, this doc ... > > /** > A summary line. > > Author: Me, Myself, and I. > Copyright: whatever > > */ > module testdoc; > > produces this output ... > > <html><head> > <META http-equiv="content-type" content="text/html; charset=utf-8"> > <title>testdoc</title> > </head><body> > <h1>testdoc</h1> > <!-- Generated by Ddoc from testdoc.d --> > A summary line. > <br><br> > <b>Author:</b><br><br> > Me, Myself, and I. > <br><br> > > <dl></dl> > > <hr><small>Page generated by <a href="http://www.digitalmars.com/d/ddoc.html">Ddoc</a>.</small> </body></html> > > Not a copyright in sight. The internal version of the DDOC macro doesn't have a $COPYRIGHT) in it. You'll need to copy the DDOC macro, insert the $(COPYRIGHT) where you want it to be, and store the result in a .ddoc file. | |||
September 30, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Derek Parnell | Thanks, Derek (and Walter). That clarifies nicely. - Kris "Derek Parnell" <derek@psych.ward> wrote in message news:1k5jr85h4w1mq$.n7omn2dakl54.dlg@40tude.net... > 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 | |||
September 30, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Walter Bright | Hi Walter, Can the DDoc parser emit tagged source code (just XML) ? If it could, it would enable a 'cottage industry' of formatters and the like ~ removing the need for Ddoc itself to emit pretty formatting output (which is rather subjective anyway) in X number of file formats; or do cross-referencing, color-coding, or whatever. Theoretically, there would be an XML document emitted per module, replete with Section identifiers, type info, visibility info, external references, and so on. In addition, you might provide a set of D classes to construct and traverse the resultant tree (via the files). This generator/reader pair would be kept in lockstep (by you), whilst anyone else with an interest could develop formatters based upon the content exposed via those D classes. This would, of course, free you from the vagaries of HTML, PostScript, etc. It would also support the (more) rapid development of cross-referencing documentation, color-coded/linked source, and many other useful goodies. The hard part for a formatting/documentation tool is extracting relevant (i.e. marked up) content from the source code. Once that is done (by you), then the creativity and abundant talents of the community can be brought to bear on remaining tasks. Naturally, it would be great if you were to provide a basic formatting tool yourself; but by supporting a two stage process you could provide the means for accellerating the pace quite considerably, as well as opening up the door to creative avenue. Currently, it appears as though macros are used to provide for formatting ~ while macros are certainly useful, I suspect we'll need something more powerful to do cross-referencing and so on (e.g. the D language itself). Again, to be most effective this would require some limited form of annotated/tagged source-code. I understand this notion is something that Pragma had been considering in the past, and is somewhat related to avaML -- http://www.badros.com/greg/JavaML/ -- although the latter was not at all focused upon documentation, and serves simply an illustration. My 2 cents. - Kris "Walter Bright" <newshound@digitalmars.com> wrote in message news:dhg1dv$1gi2$1@digitaldaemon.com... > Another extensive update of Ddoc, www.digitalmars.com/d/ddoc.html, due to all the suggestions. > > http://www.digitalmars.com/d/changelog.html > > | |||
September 30, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Kris | I vote for direct XML output too. You may want to include a XSL-Stylesheet by default, so you can easily view the XML in your browser (just like the HTML output). | |||
October 01, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
Posted in reply to Kris | "Kris" <fu@bar.com> wrote in message news:dhk4u9$29dt$1@digitaldaemon.com... > Hi Walter, > > Can the DDoc parser emit tagged source code (just XML) ? If it could, it would enable a 'cottage industry' of formatters and the like ~ removing the > need for Ddoc itself to emit pretty formatting output (which is rather subjective anyway) in X number of file formats; or do cross-referencing, color-coding, or whatever. I agree, but I think Markus has already produced a template file that will cause the output to be in XML. If this is inadequate, we can fix it. > Theoretically, there would be an XML document emitted per module, replete with Section identifiers, type info, visibility info, external references, and so on. In addition, you might provide a set of D classes to construct and traverse the resultant tree (via the files). This generator/reader pair > would be kept in lockstep (by you), whilst anyone else with an interest could develop formatters based upon the content exposed via those D classes. That does sound pretty cool. > This would, of course, free you from the vagaries of HTML, PostScript, etc. > It would also support the (more) rapid development of cross-referencing documentation, color-coded/linked source, and many other useful goodies. > > The hard part for a formatting/documentation tool is extracting relevant (i.e. marked up) content from the source code. Once that is done (by you), then the creativity and abundant talents of the community can be brought to > bear on remaining tasks. My original goal for open sourcing the front end was so that people could build ancilliary tools out of it. This has turned out to be a more daunting task for third party tool developers than I'd anticipated. > Naturally, it would be great if you were to provide a basic formatting tool > yourself; but by supporting a two stage process you could provide the means > for accellerating the pace quite considerably, as well as opening up the door to creative avenue. Currently, it appears as though macros are used to > provide for formatting ~ while macros are certainly useful, I suspect we'll > need something more powerful to do cross-referencing and so on (e.g. the D > language itself). I agree that text macros have their limits. Their main attraction is they are simple to understand and simple to implement. > Again, to be most effective this would require some limited form of annotated/tagged source-code. I understand this notion is something that Pragma had been considering in the past, and is somewhat related to avaML -- http://www.badros.com/greg/JavaML/ -- although the latter was not > at all focused upon documentation, and serves simply an illustration. I'll check it out. | |||
October 03, 2005 Re: DMD 0.134 release (Ddoc update) | ||||
|---|---|---|---|---|
| ||||
 Posted in reply to Walter Bright | Walter Bright wrote: > "Kris" <fu@bar.com> wrote in message news:dhk4u9$29dt$1@digitaldaemon.com... > > [snip] > >>It would also support the (more) rapid development of cross-referencing >>documentation, color-coded/linked source, and many other useful goodies. >> >>The hard part for a formatting/documentation tool is extracting relevant >>(i.e. marked up) content from the source code. Once that is done (by you), >>then the creativity and abundant talents of the community can be brought > > to > >>bear on remaining tasks. > > > My original goal for open sourcing the front end was so that people could > build ancilliary tools out of it. This has turned out to be a more daunting > task for third party tool developers than I'd anticipated. > I've said this before, but right here feels like a great spot to reiterate: =P To satisfy your original goal, it would be better to make the front-end a dynamic library with an exposed, simple, C API. This would free third-party tool developers from the "daunting task" of dealing with the C++ classes and the headache of nicking out the back-end functions. It would also allow third-party tool developers to write their tools in the D language, since it can easily interface with C functions/libraries. Some simple, well-defined set of good ol' C structs and C functions should do the trick. DMDFE already exists for this purpose, I know, but what good is it if we have to rely on Ben Hinkle (or future maintainer) to consistently update it? No offense to Ben, of course - he's doing a fantastic job and has lots of D-related projects going on. BTW, it should be a dynamic library (DLL, SO) so as to use the host OS's native binary format to handle symbolic linking instead of dealing with static libs and the COFF vs. OMF incompatibilities. > > [snip] > | |||
Copyright © 1999-2021 by the D Language Foundation