I have been trying to see how far one could go in creating source code documentation by mixing D and DHTML. The idea is to turn the source code into its own dynamic 'Table of Contents'.

You can see an example of this here: http://home.mindspring.com/~jonf4/d_docs/base.html

As I am not a D programmer, I used one of Daniel Yukio Yokomiso's Deimos library files as an example.

So, is this a good idea ?

It seems like too much work to write the required HTML by hand. It ought to be possible to use the D parser to create a d2html program that uses the parse tree generate the HTML.

Any thoughts ?

thanks cool... could be very helpful..

ben
"Jon Frechette" <jonf4@mindspring.com> wrote in message
news:balari$2in7$1@digitaldaemon.com...
> I have been trying to see how far one could go in creating source code documentation by mixing D and DHTML. The idea is to turn the source code into its own dynamic 'Table of Contents'.
>
> You can see an example of this here: http://home.mindspring.com/~jonf4/d_docs/base.html
>
> As I am not a D programmer, I used one of Daniel Yukio Yokomiso's Deimos library files as an example.
>
> So, is this a good idea ?
>
> It seems like too much work to write the required HTML by hand. It ought
to
> be possible to use the D parser to create a d2html program that uses the parse tree generate the HTML.
>
> Any thoughts ?
>
>

If D source code was XML, something like this might be easier.  See http://jdanielsmith.org/DML.

   Dan

"Jon Frechette" <jonf4@mindspring.com> wrote in message news:balari$2in7$1@digitaldaemon.com...
> I have been trying to see how far one could go in creating source code documentation by mixing D and DHTML. The idea is to turn the source code into its own dynamic 'Table of Contents'.
>
> You can see an example of this here: http://home.mindspring.com/~jonf4/d_docs/base.html
>
> As I am not a D programmer, I used one of Daniel Yukio Yokomiso's Deimos library files as an example.
>
> So, is this a good idea ?
>
> It seems like too much work to write the required HTML by hand. It ought
to
> be possible to use the D parser to create a d2html program that uses the parse tree generate the HTML.
>
> Any thoughts ?
>
>

In article <bb0fhh$1fgs$1@digitaldaemon.com>, J. Daniel Smith says...
>
>If D source code was XML, something like this might be easier.  See http://jdanielsmith.org/DML.
>
>   Dan
>
>"Jon Frechette" <jonf4@mindspring.com> wrote in message news:balari$2in7$1@digitaldaemon.com...
>> I have been trying to see how far one could go in creating source code documentation by mixing D and DHTML. The idea is to turn the source code into its own dynamic 'Table of Contents'.
>>
>> You can see an example of this here: http://home.mindspring.com/~jonf4/d_docs/base.html
>>
>> As I am not a D programmer, I used one of Daniel Yukio Yokomiso's Deimos library files as an example.
>>
>> So, is this a good idea ?
>>
>> It seems like too much work to write the required HTML by hand. It ought
>to
>> be possible to use the D parser to create a d2html program that uses the parse tree generate the HTML.
>>
>> Any thoughts ?

XML would certainly be good for storage and transmission of
D code. This way you could use widely available standard tools
to present D code in various forms and media.

Somehow however, this should be invisible to the programmer. When he writes code he needs as little distraction as possible.

If we assume that the D compiler understands to skip XML as it now understands to skip HTML, then we could use input and output filters in our text editors. (Emacs and Vim make it trivial, and I guess most good editors do.) While we're at it, the output filter could check that every procedure etc. have Javadoc style comments, and if they don't it would add them at file-save time. The next time the programmer edits the file he'd be able to add the required content in the pre-filled templates. (Of course, even these Javadoc style comments could be in XML in the disk file too, but on screen they would have to be something simpler. For this Javadoc style is sufficient.

Maybe the above was not so clearly written. What I mean is, souce code files on disk would be XML, but once in the editor they would be D code with "normal" comments plus Javadoc style function comments.

Storing source code as XML could bring other benefits. If the
code is stored in a dababase, we might be able to search it
with more advanced criteria than we now can. If we have an
advanced IDE, it could show us on demand the facts that are
not normally presented to the programmer. These include
GPL comment headers (Which are long, and really are of no
use to the programmer.), date, organization, project name,
and whatever else others than the programmer want there.

Without such an IDE, anybody could view the file in Notepad or `less', to see "everything".

I wrote this XSLT a while ago, it doesn't do the same thing as your design, instead it syntax highlights raw d source (without markup). It is slow, and the amount of recursion involved often crashes or halts XSLT processors when blocks of code are large (I recomend using a new <code>...</code> block for every line of the source, just to be on the safe side).

The arrival of regexps in XSLT 2.0 will reduce the amount of recursion, but the standard is not widely supported yet.

Alix...

-- 
             Alix Pexton
Webmaster - http://www.theDjournal.com

             Alix@theDjournal.com


J. Daniel Smith wrote:
> If D source code was XML, something like this might be easier.  See http://jdanielsmith.org/DML.
> 
>    Dan
> 
> "Jon Frechette" <jonf4@mindspring.com> wrote in message news:balari$2in7$1@digitaldaemon.com...
> 
>>I have been trying to see how far one could go in creating source code documentation by mixing D and DHTML. The idea is to turn the source code into its own dynamic 'Table of Contents'.
>>
>>You can see an example of this here: http://home.mindspring.com/~jonf4/d_docs/base.html
>>
>>As I am not a D programmer, I used one of Daniel Yukio Yokomiso's Deimos library files as an example.
>>
>>So, is this a good idea ?
>>
>>It seems like too much work to write the required HTML by hand. It ought
> 
> to
> 
>>be possible to use the D parser to create a d2html program that uses the parse tree generate the HTML.
>>
>>Any thoughts ?
>>
>>
> 
> 
> 

The D compiler wouldn't "skip XML", rather it would know (perhaps through a XSLT stylesheet) how to process a D-like language based on XML.  And yes, through the magic of some (mythical) IDE, the XML would be invisible to the programmer; you would see syntax highlighted D code even though the actual source code was "messy" XML.

There was an article in DDJ about this (although unrelated to D) a few months ago (http://www.ddj.com/articles/2003/0303/), but it's not available on-line.  Take a look at http://xplusplus.sourceforge.net/indexPage.htm for similar ideas.

   Dan

"Georg Wrede" <Georg_member@pathlink.com> wrote in message news:bb1ovg$2tfe$1@digitaldaemon.com...
> In article <bb0fhh$1fgs$1@digitaldaemon.com>, J. Daniel Smith says...
> >
> >If D source code was XML, something like this might be easier.  See http://jdanielsmith.org/DML.
> >
> >   Dan
> >
> >"Jon Frechette" <jonf4@mindspring.com> wrote in message news:balari$2in7$1@digitaldaemon.com...
> >> I have been trying to see how far one could go in creating source code documentation by mixing D and DHTML. The idea is to turn the source
code
> >> into its own dynamic 'Table of Contents'.
> >>
> >> You can see an example of this here: http://home.mindspring.com/~jonf4/d_docs/base.html
> >>
> >> As I am not a D programmer, I used one of Daniel Yukio Yokomiso's
Deimos
> >> library files as an example.
> >>
> >> So, is this a good idea ?
> >>
> >> It seems like too much work to write the required HTML by hand. It
ought
> >to
> >> be possible to use the D parser to create a d2html program that uses
the
> >> parse tree generate the HTML.
> >>
> >> Any thoughts ?
>
> XML would certainly be good for storage and transmission of
> D code. This way you could use widely available standard tools
> to present D code in various forms and media.
>
> Somehow however, this should be invisible to the programmer. When he writes code he needs as little distraction as possible.
>
> If we assume that the D compiler understands to skip XML as it now understands to skip HTML, then we could use input and output filters in our text editors. (Emacs and Vim make it trivial, and I guess most good editors do.) While we're at it, the output filter could check that every procedure etc. have Javadoc style comments, and if they don't it would add them at file-save time. The next time the programmer edits the file he'd be able to add the required content in the pre-filled templates. (Of course, even these Javadoc style comments could be in XML in the disk file too, but on screen they would have to be something simpler. For this Javadoc style is sufficient.
>
> Maybe the above was not so clearly written. What I mean is, souce code files on disk would be XML, but once in the editor they would be D code with "normal" comments plus Javadoc style function comments.
>
> Storing source code as XML could bring other benefits. If the
> code is stored in a dababase, we might be able to search it
> with more advanced criteria than we now can. If we have an
> advanced IDE, it could show us on demand the facts that are
> not normally presented to the programmer. These include
> GPL comment headers (Which are long, and really are of no
> use to the programmer.), date, organization, project name,
> and whatever else others than the programmer want there.
>
> Without such an IDE, anybody could view the file in Notepad or `less', to see "everything".
>
>
>