Using a text editor as your main programming environment is dead.  Let's move on.

Sean
  Yes I definitely agree with this.
  Putting the code in an .html file is a nice feature for demo programs
  that get posted on web sites, but it doesn't work so well for pure
  documentation. I don't know if the people that mentioned this have
  tried javadoc or doxygen, but creating documentation from source code
  and embedding source code in .html are just two completely different
  things. I don't see myself typing all the .html to create fancy layout
  like above when writing a .d program. Also Javadoc and Doxygen create
  hierarchical structures of your classes, summary and index files,
  links from one class to the others that are mentioned and to its
  parents, etc, etc, etc. Am I supposed to do this all by hand?

  Even if I was willing and capable of doing all this by hand, I could
  never benefit from other people using it to and all formats would be
  radically different.

  Just search the web for Java documentation. Notice how it is all
  uniform and looks alike? This is because all this documentation is
  generated using Javadoc. The 'embed d code in a .html file' technique
  is not an option for documentation generation.


  -- 
  Stijn
  OddesE_XYZ@hotmail.com
  http://OddesE.cjb.net

Sean L. Palmer wrote:
> Using a text editor as your main programming environment is dead.  Let's move on.

I disagree. I do most of my programming using a text editor (vim/gvim) and the command line, so I'm not sure what you mean by the above statement. Given that I have not been following this thread closely, I may have misinterpreted you.


Jason


> Sean
> 
>     Yes I definitely agree with this.
>     Putting the code in an .html file is a nice feature for demo programs
>     that get posted on web sites, but it doesn't work so well for pure
>     documentation. I don't know if the people that mentioned this have
>     tried javadoc or doxygen, but creating documentation from source code
>     and embedding source code in .html are just two completely different
>     things. I don't see myself typing all the .html to create fancy layout
>     like above when writing a .d program. Also Javadoc and Doxygen create
>     hierarchical structures of your classes, summary and index files,
>     links from one class to the others that are mentioned and to its
>     parents, etc, etc, etc. Am I supposed to do this all by hand?
>          Even if I was willing and capable of doing all this by hand, I could
>     never benefit from other people using it to and all formats would be
>     radically different.
>          Just search the web for Java documentation. Notice how it is all
>     uniform and looks alike? This is because all this documentation is
>     generated using Javadoc. The 'embed d code in a .html file' technique
>     is not an option for documentation generation.
>      
> 
>     --     Stijn
>     OddesE_XYZ@hotmail.com <mailto:OddesE_XYZ@hotmail.com>
>     http://OddesE.cjb.net
> 

Source code documentation with coddocHow about a "requires" tag. Requirements could be auto generated but the doc program, but sometimes users may wish to add more details. I find it useful to quickly findout what is needed for a class without having to read through the sentenced documentation.

requires: STL, opengl.d

If the docgen program supported both XML and ":" (and I'm not saying that's a good idea), which would you end up using? I would and up using the ":" format because it's so much faster to type. It requires no duplication, only one shift key and looks neat.

"anderson" <anderson@firestar.com.au> schrieb im Newsbeitrag news:ah1mdt$1ugv$1@digitaldaemon.com...

> I know you've looked into Javadoc and Doxygen, but they also remove all
the
> code body parts which your app doesn't do.

Hi, my app doesn't do anything at the moment. I'm just thinking loud... It's no problem to just keep the header stuff. But sometimes it even makes sense to comment/explain your body. So both things should be supported very easy.

> In most documentation cases it is
> important to hide the body and only show the header stuff. This means that
> the hierarchical structures / summary and index files are the most
important
> aspects of the doc generation program.

As said, these are just summaries of all the information collected while generating the output. So there is no problem to generate all kind of summaries in different level of detail. The question I find most interesting is how can we write code comfortable and add documentation where it needs to be. What kind of syntax should be used, what features are needed, what's the best usage pattern... etc. Of course it's a question of style but I don't like hughe comment boxes and special comment characters sequences to indicate what I want the output to look like. Of couse markup is needed but it should be as userfriendly as possible.

--
Robert M. Münch
IT & Management Freelancer
Mobile: +49 (0)177 2452 802
Fax   : +49 (0)721 8408 9112
Web   : http://www.robertmuench.de

There exist technological advancements that allow you to browse and edit code easily, configure how you want the code to be displayed (important on large teams where everyone has their own style preferences and you can't get a team to agree on indentation and spacing issues,) and integrate debugging, source control, creating whatever makefile or linker script you need, and many other tools such as bitmap and dialog editors.  You may not need all of this, but I kinda like it.

I guess to each his own, I'm not stopping you from living in the stone age, but there are electric lights and running water nowadays.  ;)   That said, I've seen some pretty sophisticated text editors and I expect they'll keep becoming stronger as well, to the point where they may just become IDE's, or a tool for integrating tools.

Just like ASCII is giving way to UNICODE, plain text is quickly becoming obsolete.  With the profusion of HTML, XML, and other editors, surely one format will be nice enough for everyone to standardize on.  I sure would like the ability to put foreign characters and wierd math symbols into my source code.  But ASCII/ANSI have very little in the way of choices.  I would like to see a mathematical expression editor that translates during save to D code with overloaded operators.  ;)

Sean


"Jason Mills" <jmills@cs.mun.ca> wrote in message news:3D348934.9030609@cs.mun.ca...
> Sean L. Palmer wrote:
> > Using a text editor as your main programming environment is dead.  Let's move on.
>
> I disagree. I do most of my programming using a text editor (vim/gvim) and the command line, so I'm not sure what you mean by the above statement. Given that I have not been following this thread closely, I may have misinterpreted you.
>
>
> Jason
>
>
> > Sean
> >
> >     Yes I definitely agree with this.
> >     Putting the code in an .html file is a nice feature for demo
programs
> >     that get posted on web sites, but it doesn't work so well for pure
> >     documentation. I don't know if the people that mentioned this have
> >     tried javadoc or doxygen, but creating documentation from source
code
> >     and embedding source code in .html are just two completely different
> >     things. I don't see myself typing all the .html to create fancy
layout
> >     like above when writing a .d program. Also Javadoc and Doxygen
create
> >     hierarchical structures of your classes, summary and index files,
> >     links from one class to the others that are mentioned and to its
> >     parents, etc, etc, etc. Am I supposed to do this all by hand?
> >
> >     Even if I was willing and capable of doing all this by hand, I could
> >     never benefit from other people using it to and all formats would be
> >     radically different.
> >
> >     Just search the web for Java documentation. Notice how it is all
> >     uniform and looks alike? This is because all this documentation is
> >     generated using Javadoc. The 'embed d code in a .html file'
technique
> >     is not an option for documentation generation.
> >
> >
> >     --
> >     Stijn
> >     OddesE_XYZ@hotmail.com <mailto:OddesE_XYZ@hotmail.com>
> >     http://OddesE.cjb.net

I'd prefer the boxes to be done with HTML frames instead of ascii art.

Actual source code could go into <CODE> <D> for (int i=0; i<100; ++i) {
printf("D rocks!"); }</D> </CODE> blocks.  Which of course the editor
wouldn't show you.

Sean

"Robert M. Münch" <robert.muench@robertmuench.de> wrote in message news:ah345k$c5o$1@digitaldaemon.com...
> As said, these are just summaries of all the information collected while generating the output. So there is no problem to generate all kind of summaries in different level of detail. The question I find most
interesting
> is how can we write code comfortable and add documentation where it needs
to
> be. What kind of syntax should be used, what features are needed, what's
the
> best usage pattern... etc. Of course it's a question of style but I don't like hughe comment boxes and special comment characters sequences to indicate what I want the output to look like. Of couse markup is needed
but
> it should be as userfriendly as possible.

XML and HTML are meant to be generated by tools, not typed in by hand. Right-click, select Insert Documentation | Comment....  Just like autocomplete does today, the editor could watch for /* and // and create comment blocks for you.  During save or before passing to the compiler it could transform them back to /*abc*/ and //abc with special tags.  I suppose you guys are deciding what the tags should be.

Sean

"anderson" <anderson@firestar.com.au> wrote in message news:ah2uid$63r$1@digitaldaemon.com...
> If the docgen program supported both XML and ":" (and I'm not saying
that's
> a good idea), which would you end up using? I would and up using the ":" format because it's so much faster to type. It requires no duplication,
only
> one shift key and looks neat.

> There exist technological advancements that allow you to browse and
> edit code easily,

Any reasonable text editor with script capabilities can do this.

> configure how you want the code to be displayed (important on large
> teams where everyone has their own style preferences and you can't get
> a team to agree on indentation and spacing issues,)

Any reasonable text editor can do this as well, and much easier and with much more configuration options in most cases.

> and integrate debugging, source control, creating whatever makefile or
> linker script you need, and

I admit, these are not so easily done in a text editor, but doable just
the same.

> many other tools such as bitmap and dialog editors.  You may not need
> all of this, but I kinda like it.

Yes, I agree bitmap and dialog editors are useful. However, in some
decent GUI toolkits, dialog editors are not really necessary, especially
if the toolkit dynamically lays out you dialog controls for you.
Consider Java.

> I guess to each his own, I'm not stopping you from living in the stone
> age, but there are electric lights and running water nowadays.  ;)

I guess me and some well respected people in the software industry like
living in the stone age ;) (e.g. see Allen Holub's editorial, Java
Solutions, a supplement to C/C++ Users Journal).  I have read many
articles of those who have replaced their sophisticated IDE's and CASE
tools, which suppose to increase productivity, with good programming
text editors (e.g. gvim, emacs, etc.).

Most programming is done in a text editor, so why does so many that come
with IDEs stink? I use Visual C++ at work sometimes, but I find myself
using gvim as my primary text editor for that reason. In addition I can
use the same text editor, configured the way I like, for any programming
language I happen to be coding in at the moment, including D, while
others using IDE's often have to learn a new editor for each different
IDE. In effect, the programming never really becomes proficient with any
editor.

> That said, I've seen some pretty sophisticated text editors and I
> expect they'll keep becoming stronger as well, to the point where they
> may just become IDE's, or a tool for integrating tools.

Yes, and they behave the way you want them to behave.

> Just like ASCII is giving way to UNICODE, plain text is quickly
> becoming obsolete.  With the profusion of HTML, XML, and other
> editors, surely one format will be nice enough for everyone to
> standardize on.

But what is HTML and XML if it's not plain text? So is plain text really
becoming obsolete? You can argue the opposite. E.g. instead of saving
data as binary files, much data is now being saved as XML (plain text).

> I sure would like the ability to put foreign characters and wierd math
> symbols into my source code.  But ASCII/ANSI have very little in the
> way of choices.  I would like to see a mathematical expression editor
> that translates during save to D code with overloaded operators.  ;)

My main reason for staring this discussion is: when making decisions
about D, don't forget the stone age folks like me who may have an
interest in D ...  there may be more of us than you think ;)

Jason

"Sean L. Palmer" <seanpalmer@earthlink.net> wrote in message news:ah379p$hbh$1@digitaldaemon.com...
> XML and HTML are meant to be generated by tools, not typed in by hand. Right-click, select Insert Documentation | Comment....  Just like autocomplete does today, the editor could watch for /* and // and create comment blocks for you.  During save or before passing to the compiler it could transform them back to /*abc*/ and //abc with special tags.  I
suppose
> you guys are deciding what the tags should be.
>

> Sean

Exactly. OddesE was suggesting that we use XML for the text comment formating, not the generator. The most of these tags are definded in Juarez Rudastz first document. They may just need a bit of tweeking (where I don't know).