In article <bioko7$c8l$1@digitaldaemon.com>, Matthew Wilson says...
>This has merit, but the counter argument is that browsers are ubiquitous, and it is therefore exceedingly unlikely to not have access to something that can show you the code in an eminently readable format

The trouble with this argument is that browsers are only a _display_ tool, not an editing tool. To edit html without seeing all the nasty bits, you have to edit it through a WYSIWYG editor like Dreamweaver or FrontPage. I don't want to use an HTML editor to edit code just so that my variable names are rendered in red text.

I've seen a number of handy tools for php and perl that take source code as input and output a prettied-up, color-coded html version of the source code. People use these tools for posting their code into web tutorials and whatnot. I personally think that's pretty cool.

I also think it's pretty cool to embed xml tags in certain types of comments, for the purpose of generating api documentation. I think it's a lot more handy to write a <doc> </doc> set of comments than it is to use /// (which can be hard to spot) to use for auto-doc generation.

But I don't think it's handy to have a bunch of <font color="red"></font> tags around my class declarations, just so that they'll look pretty in a browser. That's not helpful documentation. That's crazy.

Agree with all that. ;)

"Benji Smith" <dlanguage@xxagg.com> wrote in message news:bion60$gh2$1@digitaldaemon.com...
> In article <bioko7$c8l$1@digitaldaemon.com>, Matthew Wilson says...
> >This has merit, but the counter argument is that browsers are ubiquitous, and it is therefore exceedingly unlikely to not have access to something that can show you the code in an eminently readable format
>
> The trouble with this argument is that browsers are only a _display_ tool,
not
> an editing tool. To edit html without seeing all the nasty bits, you have
to
> edit it through a WYSIWYG editor like Dreamweaver or FrontPage. I don't
want to
> use an HTML editor to edit code just so that my variable names are
rendered in
> red text.
>
> I've seen a number of handy tools for php and perl that take source code
as
> input and output a prettied-up, color-coded html version of the source
code.
> People use these tools for posting their code into web tutorials and
whatnot. I
> personally think that's pretty cool.
>
> I also think it's pretty cool to embed xml tags in certain types of
comments,
> for the purpose of generating api documentation. I think it's a lot more
handy
> to write a <doc> </doc> set of comments than it is to use /// (which can
be hard
> to spot) to use for auto-doc generation.
>
> But I don't think it's handy to have a bunch of <font color="red"></font>
tags
> around my class declarations, just so that they'll look pretty in a
browser.
> That's not helpful documentation. That's crazy.
>
>

Hear Hear!

In article <bionc5$gn3$1@digitaldaemon.com>, Matthew Wilson says...
>
>Agree with all that. ;)
>
>"Benji Smith" <dlanguage@xxagg.com> wrote in message news:bion60$gh2$1@digitaldaemon.com...
>> In article <bioko7$c8l$1@digitaldaemon.com>, Matthew Wilson says...
>> >This has merit, but the counter argument is that browsers are ubiquitous, and it is therefore exceedingly unlikely to not have access to something that can show you the code in an eminently readable format
>>
>> The trouble with this argument is that browsers are only a _display_ tool,
>not
>> an editing tool. To edit html without seeing all the nasty bits, you have
>to
>> edit it through a WYSIWYG editor like Dreamweaver or FrontPage. I don't
>want to
>> use an HTML editor to edit code just so that my variable names are
>rendered in
>> red text.
>>
>> I've seen a number of handy tools for php and perl that take source code
>as
>> input and output a prettied-up, color-coded html version of the source
>code.
>> People use these tools for posting their code into web tutorials and
>whatnot. I
>> personally think that's pretty cool.
>>
>> I also think it's pretty cool to embed xml tags in certain types of
>comments,
>> for the purpose of generating api documentation. I think it's a lot more
>handy
>> to write a <doc> </doc> set of comments than it is to use /// (which can
>be hard
>> to spot) to use for auto-doc generation.
>>
>> But I don't think it's handy to have a bunch of <font color="red"></font>
>tags
>> around my class declarations, just so that they'll look pretty in a
>browser.
>> That's not helpful documentation. That's crazy.
>>
>>
>
>

> >This has merit, but the counter argument is that browsers are ubiquitous, and it is therefore exceedingly unlikely to not have access to something that can show you the code in an eminently readable format

For sure, it is good if any browser could display the text readable but by default, we may prefer not to have syntax highlighting in the code so that it will be more readable in a text editor.

>
> The trouble with this argument is that browsers are only a _display_ tool,
not
> an editing tool. To edit html without seeing all the nasty bits, you have
to
> edit it through a WYSIWYG editor like Dreamweaver or FrontPage. I don't
want to
> use an HTML editor to edit code just so that my variable names are
rendered in
> red text.

So, all HTML tags should be optional...

OTOH, I think that it will be possible to make an editor that would allows to edit D code without needing to display all the TAGs. Maybe a good editor would allow the programmer to enter <doc> and automatically hide the TAG and display the documentation in another color and add the closing TAG automatically.

With time, I think we will have good editor for that and it will become the norm to uses them...

I think that we could have tools that will add TAGs for syntax highlighting when saving or exporting the file... and we should have the ability to strip them if desired...

>
> I've seen a number of handy tools for php and perl that take source code
as
> input and output a prettied-up, color-coded html version of the source
code.
> People use these tools for posting their code into web tutorials and
whatnot. I
> personally think that's pretty cool.
>
> I also think it's pretty cool to embed xml tags in certain types of
comments,
> for the purpose of generating api documentation. I think it's a lot more
handy
> to write a <doc> </doc> set of comments than it is to use /// (which can
be hard
> to spot) to use for auto-doc generation.

And also, we need a way to tell the documentation tool what comments make
the doc... The tool should be able to extract other information from the
code
like function prototypes, preconditions, invariants,... and we should be
able to
add our own comments for the documentation to any declaration or statement.

And we might eventually have editor that would be able to automatically
embed
some TAGs that might be interesting for documentation purpose (like when
a function was last modified or a file...) Also, some information like the
revision
history could be between special TAG that the editor would now and allows to
display or hide easily...

A thing that might help ensure that the file is more or less readable in
text
is too allows to make reference to declarations that follows so that
documentation tools could uses it and the compiler could validate the
documentation (all parameters, all functions are documented).

An example:

<doc>
<doc decl=foo>This function does something.
<doc type=detail>Here we migh have more detailled description</doc>
</doc>
<doc decl=a> This parameter is the number of iteration to makes.
</doc>
void foo(int a)
{
    for (int i = 0; i != a; ++i)
    {
        <doc type=impl>Here we might have implementation doc</doc>
        // And we can have normal comments for code only documentation...
        do_something...
    }
}

Note that instead of type attribute, we mioght one to uses a style (CSS)
attribute so that it would be easy to apply different style to different
part
of the doc: We would have predefined classes for each kind of
supported documentation...

A documentation tool would then be able from the source to generate
much more usefull doc since the tool would know the purpose of
the comments (function prototype and parameters, function description,
function implementation notes,...)

>
> But I don't think it's handy to have a bunch of <font color="red"></font>
tags
> around my class declarations, just so that they'll look pretty in a
browser.
> That's not helpful documentation. That's crazy.
>
>

I also agree... A tool might add them from the source when we want to
display it
on the WEB. Ideally, a style sheet would be used so that we won't have one
file with keyword in red and another in blue,....

We should also be able to remove those syntax highlithing TAGs without removing other TAGs like the ones for the documentation.

> I think it'd be great, as long as its compatible with Doxygen *and*
javadoc,
> so that any libraries documented using either format does not have to be upgraded until the poor overworked developer is able to do so.

I also vote for doxygen. It does wonders for C++. I hope it is flexible enough to easily add new language support.

Philippe Mori wrote:

> A documentation tool would then be able from the source to generate
> much more usefull doc since the tool would know the purpose of
> the comments (function prototype and parameters, function description,
> function implementation notes,...)

Besides, D promotes a style of mixing interface and implementation. I'm not sure whether i approve the style by itself or not, but it definately takes some viewer/editor support. Like, Scintilla component used in modern IDEs can roll together parts which one need not usually see.

This basically boils down to excluding implementation from the documentation and making it available optionally. Besides, usually the documentation needn't be in exactly the same order as code, although D reliefs the constraints on code placement and thus this problem is less severe.

Another thing is that writing raw, simple code is much more pleasant than HTML or point-and-click, which is simply distracting. The ultimate experience of working with TeX, or any other simple and legible language. Something which we cannot have with HTML.

It is probably wise to define a snorkel-free documentation format, which would work well in raw text. Finally, i recall some people in this newsgroup use VIM only, and that for good reasons. Do they have to be "impaired" or "disabled" because of that?

-eye/midiclub