Guys, what you are talking about is just a special case of 'literate programming', implemented and popularized by Donald Knuth ages ago. Web contains a lot of literature and actually usable tools (under all platforms) for doing it.

Using a single language independent tool is a better idea than forcing such things in the language specs.

- Rajiv

"OddesE" <OddesE_XYZ@hotmail.com> wrote in message news:a2fegt$bf1$1@digitaldaemon.com...
> "Sean L. Palmer" <spalmer@iname.com> wrote in message news:a2e7up$2kgh$1@digitaldaemon.com...
> > > Mmm, no I don't agree.
> > > ......<snip>......
> > > On top of that is the fact that if you use the source in HTML
> > > feature to document your code, your products would have
> > > to be open source. Not that I don't like open-source, but
> > > sometimes it is just not possible.
> >
> > What the HELL are you blabbering about?  You need to back that remark up with facts.
> >
> > Sean
> >
>
> Dear Sean, what remark did you mean?
>
> > > On top of that is the fact that if you use the source in HTML
> > > feature to document your code, your products would have
> > > to be open source.
>
> If this one, my argument is that if the source code is in the
> documentation, I can't distribute that documentation to others
> without revealing the source.
> You could ofcourse write some tool to strip out the source from
> the .html file, but then what is the point? I'd rather use some
> JavaDoc style tool to convert my source files to documentation
> files that I can distribute, preferably with the option to select the
> output format as .html, .pdf or whatever.
> I think the source-in-HTML feature is really cool for websites
> that want to demonstrate a little program on their website, but
> I don't think it is suitable for documenting large, possibly secret
> projects to people that have to *use* the code, but not see it.
>
> >> Not that I don't like open-source, but
> > > sometimes it is just not possible.
>
> If this one, then I would have to say that there are
> many companies that keep their source private, such
> as Microsoft.
>
>
> --
> Stijn
> OddesE_XYZ@hotmail.com
> http://OddesE.cjb.net
> __________________________________________
> Remove _XYZ from my address when replying by mail
>
>
>

Sorry, I meant the first one.  And probably shouldn't have been so snappy. ;)

I don't see how using source embedded in HTML causes any project to have to be "open source".

Documentation can always be extracted for external developers in any case. D is easy enough to parse that the documentation extractor could also grab the function parameter lists or whatever it needed, and omit the rest of the source.

Maybe you're using the term "open-source" in a way that is different from what I understand the term to mean.

Sean

"OddesE" <OddesE_XYZ@hotmail.com> wrote in message news:a2fegt$bf1$1@digitaldaemon.com...
> "Sean L. Palmer" <spalmer@iname.com> wrote in message news:a2e7up$2kgh$1@digitaldaemon.com...
> > > Mmm, no I don't agree.
> > > ......<snip>......
> > > On top of that is the fact that if you use the source in HTML
> > > feature to document your code, your products would have
> > > to be open source. Not that I don't like open-source, but
> > > sometimes it is just not possible.
> >
> > What the HELL are you blabbering about?  You need to back that remark up with facts.
> >
> > Sean
> >
>
> Dear Sean, what remark did you mean?
>
> > > On top of that is the fact that if you use the source in HTML
> > > feature to document your code, your products would have
> > > to be open source.
>
> If this one, my argument is that if the source code is in the
> documentation, I can't distribute that documentation to others
> without revealing the source.
> You could ofcourse write some tool to strip out the source from
> the .html file, but then what is the point? I'd rather use some
> JavaDoc style tool to convert my source files to documentation
> files that I can distribute, preferably with the option to select the
> output format as .html, .pdf or whatever.
> I think the source-in-HTML feature is really cool for websites
> that want to demonstrate a little program on their website, but
> I don't think it is suitable for documenting large, possibly secret
> projects to people that have to *use* the code, but not see it.
>
> >> Not that I don't like open-source, but
> > > sometimes it is just not possible.
>
> If this one, then I would have to say that there are
> many companies that keep their source private, such
> as Microsoft.
>
>
> --
> Stijn
> OddesE_XYZ@hotmail.com
> http://OddesE.cjb.net
> __________________________________________
> Remove _XYZ from my address when replying by mail

"OddesE" <OddesE_XYZ@hotmail.com> wrote in message news:a2ffcr$c8a$1@digitaldaemon.com...
> I think the javadoc invention /** */ proves that there
> is a need for something like this, but it seems that most
> of you don't agree. Ah well, just a thought.

No, I do agree that it'd be nice to have some unique way to flag documentation (separately from comments and also separate from whatever method is used to turn off sections of code for debugging purposes)

Not sure what it should be though.

Sean

If this D/XML (DML) idea catches on as an improved version of D-in-HTML, then you can just write your comments in any XML-compliant dialect you like, XHTML being one of those.  Everything in the "d" namespace would be D code, so it would be fairly easy to strip out documentation.

With DML, there is probalby going to be minimal need for a JavaDoc like tool since you can get the function name, arguments, etc. from the "d" XML elements.

   Dan

"OddesE" <OddesE_XYZ@hotmail.com> wrote in message news:a2ffcr$c8a$1@digitaldaemon.com...
> "Russell Borogove" <kaleja@estarcion.com> wrote in message news:3C4A90F8.5050409@estarcion.com...
> > OddesE wrote:
> >
> >
> > > Ah, I'm sorry If I wasn't clear...
> > > I meant that the syntax
> > >
> > > documentation
> > > {
> > >    Documentation for javadoc like tools
> > > }
> > >
> > > Would be like /** */ but then specialized.
> > > I didn't mean for anything within the braces
> > > to be interpreted by the compiler...
> > > Maybe it should be more like:
> > >
> > > /*documentation
> > >    Documentation for javadoc like tools
> > > */
> > >
> > > Or something...
> > >
> > > But I would like language support for something
> > > like this.
> >
> > So use:
> >
> > version (Documentation)
> > {
> > ...
> > }
> >
> > :)
> >
> > -RB
> >
>
> What do you mean?
> the version keyword is for code...Everything within it should be
> syntactically correct. If I would write something like:
>
> version (Documentation)
> {
>     Name:            MyFunc
>     Descr.:           Prints out the text "Hello World.\n"
>     Parameter:      -
>     Result:            -
>     Exceptions:     -
> }
>
> The compiler would signal an error.
> I could ofcourse write:
>
> version (Documentation)
> {
>     /*
>         Name:            MyFunc
>         Descr.:           Prints out the text "Hello World.\n"
>         Parameters:     -
>         Result:            -
>         Exceptions:     -
>     */
> }
>
> But then what is the point?
> I would like some language support for documentation,
> not just comments, there is a difference between them.
> /*doc  doc*/  would signal documentation. If you had a
> function like this:
>
> /*doc
>     Name:            MyFunc
>     Descr.:           Prints out the text "Hello World.\n"
>     Parameters:    -
>     Result:            -
>     Exceptions:     -
> doc*/
> void MyFunc()
> {
>     // Call printf to print out "Hello World.\n"
>     printf ("Hello World.\n");
> }
>
> You would be able to remove the function and its
> documentation from the program by placing normal
> comments /*   */  around them.
>
> I think the javadoc invention /** */ proves that there
> is a need for something like this, but it seems that most
> of you don't agree. Ah well, just a thought.
>
>
> --
> Stijn
> OddesE_XYZ@hotmail.com
> http://OddesE.cjb.net
> __________________________________________
> Remove _XYZ from my address when replying by mail
>
>
>

Yes, I've thought about that along with the DML (D in XML) thread.  If you haven't heard about Knuth's ideas, take a look at http://sunburn.stanford.edu/~knuth/cweb.html

I think the most significant difference is that the CTANGLE and CWEAVE processes are simplified by the use of XML and XSLT so you don't need any special software (assuming of course that you already have XML software available which is pretty much the case these days on Windows platforms). Of course to support some of the more nifty features of "web", there is probably a need for another XSLT tranform to turn a .DWEB file into .DML which could then turned into D code (perhaps internal to the compiler) using the D.XSL XSLT stylesheet.

   Dan

"Rajiv Bhagwat" <dataflow@vsnl.com> wrote in message news:a2gaq7$slq$1@digitaldaemon.com...
> Guys, what you are talking about is just a special case of 'literate programming', implemented and popularized by Donald Knuth ages ago. Web contains a lot of literature and actually usable tools (under all
platforms)
> for doing it.
>
> Using a single language independent tool is a better idea than forcing
such
> things in the language specs.
>
> - Rajiv
>
> "OddesE" <OddesE_XYZ@hotmail.com> wrote in message news:a2fegt$bf1$1@digitaldaemon.com...
> > "Sean L. Palmer" <spalmer@iname.com> wrote in message news:a2e7up$2kgh$1@digitaldaemon.com...
> > > > Mmm, no I don't agree.
> > > > ......<snip>......
> > > > On top of that is the fact that if you use the source in HTML
> > > > feature to document your code, your products would have
> > > > to be open source. Not that I don't like open-source, but
> > > > sometimes it is just not possible.
> > >
> > > What the HELL are you blabbering about?  You need to back that remark
up
> > > with facts.
> > >
> > > Sean
> > >
> >
> > Dear Sean, what remark did you mean?
> >
> > > > On top of that is the fact that if you use the source in HTML
> > > > feature to document your code, your products would have
> > > > to be open source.
> >
> > If this one, my argument is that if the source code is in the
> > documentation, I can't distribute that documentation to others
> > without revealing the source.
> > You could ofcourse write some tool to strip out the source from
> > the .html file, but then what is the point? I'd rather use some
> > JavaDoc style tool to convert my source files to documentation
> > files that I can distribute, preferably with the option to select the
> > output format as .html, .pdf or whatever.
> > I think the source-in-HTML feature is really cool for websites
> > that want to demonstrate a little program on their website, but
> > I don't think it is suitable for documenting large, possibly secret
> > projects to people that have to *use* the code, but not see it.
> >
> > >> Not that I don't like open-source, but
> > > > sometimes it is just not possible.
> >
> > If this one, then I would have to say that there are
> > many companies that keep their source private, such
> > as Microsoft.
> >
> >
> > --
> > Stijn
> > OddesE_XYZ@hotmail.com
> > http://OddesE.cjb.net
> > __________________________________________
> > Remove _XYZ from my address when replying by mail
> >
> >
> >
>
>