www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Re: Andrei's Google Talk

reply Jesse Phillips <jessekphillips+D gmail.com> writes:
Steven Schveighoffer Wrote:

 I wouldn't mind the current docs, but I'd like to have some document to  
 know what tags are defined and what they mean (like a ddocdoc), and how to  
 define new tags.  Maybe this already exists?

My two comments are, shouldn't paragraphs be handled with a blank line? And yes there is a document on ddoc http://digitalmars.com/d/2.0/ddoc.html
Aug 06 2010
next sibling parent reply "Nick Sabalausky" <a a.a> writes:
"Jesse Phillips" <jessekphillips+D gmail.com> wrote in message 
news:i3hr7p$1s1$1 digitalmars.com...
 Steven Schveighoffer Wrote:

 I wouldn't mind the current docs, but I'd like to have some document to
 know what tags are defined and what they mean (like a ddocdoc), and how 
 to
 define new tags.  Maybe this already exists?

My two comments are, shouldn't paragraphs be handled with a blank line?

YES. And along those exact lines, may I say I'm a big fan of the Natural Docs approach. IMO, comments should be [*easily*] readable *before* being run through a doc generator, not just after. Of course, in that regard (not to mention writeability) DDoc beats the snot out of C#'s horrid XML comments (I've never understood MS's enormous obsession with XML), but DDoc still has that same fundamental problem.
Aug 06 2010
next sibling parent bearophile <bearophileHUGS lycos.com> writes:
Nick Sabalausky:
 (I've never understood MS's enormous obsession with XML), but DDoc still has 
 that same fundamental problem.

I think that's a nice example of Conway's Law: http://en.wikipedia.org/wiki/Conway%27s_Law It means that C# is used in large formal organizations where XML is appreciated :-) Bye, bearophile
Aug 07 2010
prev sibling parent reply Justin Spahr-Summers <Justin.SpahrSummers gmail.com> writes:
On Sat, 7 Aug 2010 01:19:03 -0400, Nick Sabalausky <a a.a> wrote:
 
 "Jesse Phillips" <jessekphillips+D gmail.com> wrote in message 
 news:i3hr7p$1s1$1 digitalmars.com...
 Steven Schveighoffer Wrote:

 I wouldn't mind the current docs, but I'd like to have some document to
 know what tags are defined and what they mean (like a ddocdoc), and how 
 to
 define new tags.  Maybe this already exists?

My two comments are, shouldn't paragraphs be handled with a blank line?

YES. And along those exact lines, may I say I'm a big fan of the Natural Docs approach. IMO, comments should be [*easily*] readable *before* being run through a doc generator, not just after. Of course, in that regard (not to mention writeability) DDoc beats the snot out of C#'s horrid XML comments (I've never understood MS's enormous obsession with XML), but DDoc still has that same fundamental problem.

Just in case you haven't seen this page before: http://www.charlespetzold.com/etc/CSAML.html ;)
Aug 08 2010
next sibling parent BCS <none anon.com> writes:
Hello Justin Spahr-Summers,

 On Sat, 7 Aug 2010 01:19:03 -0400, Nick Sabalausky <a a.a> wrote:
 
 "Jesse Phillips" <jessekphillips+D gmail.com> wrote in message
 news:i3hr7p$1s1$1 digitalmars.com...
 
 Steven Schveighoffer Wrote:
 
 I wouldn't mind the current docs, but I'd like to have some
 document to
 know what tags are defined and what they mean (like a ddocdoc), and
 how
 to
 define new tags.  Maybe this already exists?

line?

And along those exact lines, may I say I'm a big fan of the Natural Docs approach. IMO, comments should be [*easily*] readable *before* being run through a doc generator, not just after. Of course, in that regard (not to mention writeability) DDoc beats the snot out of C#'s horrid XML comments (I've never understood MS's enormous obsession with XML), but DDoc still has that same fundamental problem.

http://www.charlespetzold.com/etc/CSAML.html ;)

I wonder how long that took to write. Just the typing must have taken some time but if you factor in the time take to recover from the laughter induce injuries it may have taken weeks! -- ... <IXOYE><
Aug 08 2010
prev sibling next sibling parent "Nick Sabalausky" <a a.a> writes:
"Justin Spahr-Summers" <Justin.SpahrSummers gmail.com> wrote in message 
news:MPG.26c91a1af538b8829896b8 news.digitalmars.com...
 On Sat, 7 Aug 2010 01:19:03 -0400, Nick Sabalausky <a a.a> wrote:
 "Jesse Phillips" <jessekphillips+D gmail.com> wrote in message
 news:i3hr7p$1s1$1 digitalmars.com...
 Steven Schveighoffer Wrote:

 I wouldn't mind the current docs, but I'd like to have some document 
 to
 know what tags are defined and what they mean (like a ddocdoc), and 
 how
 to
 define new tags.  Maybe this already exists?

My two comments are, shouldn't paragraphs be handled with a blank line?

YES. And along those exact lines, may I say I'm a big fan of the Natural Docs approach. IMO, comments should be [*easily*] readable *before* being run through a doc generator, not just after. Of course, in that regard (not to mention writeability) DDoc beats the snot out of C#'s horrid XML comments (I've never understood MS's enormous obsession with XML), but DDoc still has that same fundamental problem.

Just in case you haven't seen this page before: http://www.charlespetzold.com/etc/CSAML.html ;)

That's great! I hadn't seen that before. Love it. I did experience a couple seconds of sheer horror before I realized it was a joke :)
Aug 08 2010
prev sibling next sibling parent "Mike James" <foo bar.com> writes:
"Justin Spahr-Summers" <Justin.SpahrSummers gmail.com> wrote in message 
news:MPG.26c91a1af538b8829896b8 news.digitalmars.com...
 On Sat, 7 Aug 2010 01:19:03 -0400, Nick Sabalausky <a a.a> wrote:
 "Jesse Phillips" <jessekphillips+D gmail.com> wrote in message
 news:i3hr7p$1s1$1 digitalmars.com...
 Steven Schveighoffer Wrote:

 I wouldn't mind the current docs, but I'd like to have some document 
 to
 know what tags are defined and what they mean (like a ddocdoc), and 
 how
 to
 define new tags.  Maybe this already exists?

My two comments are, shouldn't paragraphs be handled with a blank line?

YES. And along those exact lines, may I say I'm a big fan of the Natural Docs approach. IMO, comments should be [*easily*] readable *before* being run through a doc generator, not just after. Of course, in that regard (not to mention writeability) DDoc beats the snot out of C#'s horrid XML comments (I've never understood MS's enormous obsession with XML), but DDoc still has that same fundamental problem.

Just in case you haven't seen this page before: http://www.charlespetzold.com/etc/CSAML.html ;)

Best April Fools joke I've seen in a while :-) No doubt someone will implement it for the exercise... -=mike=-
Aug 09 2010
prev sibling parent Adrian Matoga <epi atari8.info> writes:
On 2010-08-09 05:47, Justin Spahr-Summers wrote:
 On Sat, 7 Aug 2010 01:19:03 -0400, Nick Sabalausky <a a.a> wrote:
 "Jesse Phillips" <jessekphillips+D gmail.com> wrote in message 
 news:i3hr7p$1s1$1 digitalmars.com...
 Steven Schveighoffer Wrote:

 I wouldn't mind the current docs, but I'd like to have some document to
 know what tags are defined and what they mean (like a ddocdoc), and how 
 to
 define new tags.  Maybe this already exists?


And along those exact lines, may I say I'm a big fan of the Natural Docs approach. IMO, comments should be [*easily*] readable *before* being run through a doc generator, not just after. Of course, in that regard (not to mention writeability) DDoc beats the snot out of C#'s horrid XML comments (I've never understood MS's enormous obsession with XML), but DDoc still has that same fundamental problem.

Just in case you haven't seen this page before: http://www.charlespetzold.com/etc/CSAML.html ;)

But, you see, it was easy to believe it was truth. :)
Aug 09 2010
prev sibling parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Fri, 06 Aug 2010 16:27:37 -0400, Jesse Phillips  
<jessekphillips+D gmail.com> wrote:

 Steven Schveighoffer Wrote:

 I wouldn't mind the current docs, but I'd like to have some document to
 know what tags are defined and what they mean (like a ddocdoc), and how  
 to
 define new tags.  Maybe this already exists?

My two comments are, shouldn't paragraphs be handled with a blank line? And yes there is a document on ddoc http://digitalmars.com/d/2.0/ddoc.html

Thanks, I hadn't seen that page (looks like there's a missing parentheses in there too! ;) I'll have to see if I can get vim to read ddoc properly so I can edit it fine the next time. I agree 100%, get rid of all the $(P's. I'd rather see natural text. I'm a big fan of trac's wiki format, where formatting is pretty natural. i.e. a bulleted list looks like this: * item 1 * item 2 You still need tags for things like bold or italic, but those should be few and far between. And of course, you need macros for dynamic content generation. -Steve
Aug 10 2010