"Martin M. Pedersen" <mmp@www.moeller-pedersen.dk> wrote in message news:adg5d2$1osp$1@digitaldaemon.com...

> I like HTML documentation too, and I normally use Doxygen to make it. It
is
> a great tool that also allows the documentation to be generated in e.g. Latex, CHM, RTF, and XML, thereby reducing maintenance cost even further. Latex and RTF are good for printed documentation, while HTML is not. XML
is
> good for further processing. For these reasons, I prefer the Doxygen (or JavaDoc) approach for documentation.

Doxygen and other similar tools are good to document the source code of the program, or an interface of a library. They were not intended to be used for purpose of making "generic" documentation, like the D reference guide.

"Walter" <walter@digitalmars.com> wrote in message news:adg4ej$1o24$1@digitaldaemon.com...

> I agree with you that things should be customized to work as expected on
the
> particular machine it is implemented on. But I disagree about
documentation.
> I find that html is a great way to do documentation, and it works well on win32. Just typing in the name of the file will bring it up all nicely formatted in a browser window. It enables the online documents to be identical (saves on maintenance costs). It's much better than windows help is.

The only problem with HTML docs, they cannot be searched for
topics/keywords.
However, there are solutions of that problem, varying across the platforms.
I think it would be a good idea to compile it into CHM for Windows
distribution...

It's just that there's so many loose .GIF files that way.  ;(   And it's not as searchable.

That wasn't my main point.  HTML help is fine.

Sean

"Walter" <walter@digitalmars.com> wrote in message news:adg4ej$1o24$1@digitaldaemon.com...
>
> "Sean L. Palmer" <seanpalmer@earthlink.net> wrote in message news:adbgf6$1gc3$1@digitaldaemon.com...
> > Don't troll.  The Win32 version of DMD is a Windows program and should behave as other Windows programs do.  I could care less what the future Linux version of DMD does.  It'll probably use lots of command line
> switches
> > and environment variables, because that seems to be the UNIX way of
doing
> > things.  On Windows, the docs should be in .CHM format, on Linux, docs
> will
> > likely be in MAN format or maybe just a textfile.  Mac versions of DMD
> will
> > be different still.
>
> I agree with you that things should be customized to work as expected on
the
> particular machine it is implemented on. But I disagree about
documentation.
> I find that html is a great way to do documentation, and it works well on win32. Just typing in the name of the file will bring it up all nicely formatted in a browser window. It enables the online documents to be identical (saves on maintenance costs). It's much better than windows help is.

"Walter" <walter@digitalmars.com> wrote in message news:adg4ej$1o24$1@digitaldaemon.com...
> I agree with you that things should be customized to work as expected on
the
> particular machine it is implemented on. But I disagree about
documentation.
> I find that html is a great way to do documentation, and it works well on win32. Just typing in the name of the file will bring it up all nicely formatted in a browser window. It enables the online documents to be identical (saves on maintenance costs). It's much better than windows help is.

And I forgot to mention - if you don't have an html browser, you can still read the documentation because it's ascii. This is better than, say Microsoft Word files or Adobe Acrobat files in which the text cannot be extracted without a specialized file reader.

"Pavel Minayev" <evilone@omen.ru> wrote in message news:adg7f4$1r5b$1@digitaldaemon.com...
> The only problem with HTML docs, they cannot be searched for topics/keywords.

Yes, though I am using Atomz as a workaround for that.

> However, there are solutions of that problem, varying across the
platforms.
> I think it would be a good idea to compile it into CHM for Windows distribution...

If there was a reliable html->chm compiler that might be a possibility (reliable in that no tweaking is necessary). Otherwise, I doubt it is worth the effort.

Oh, the only gif files I use are the logo and the silly cartoons I drew up one day <g>.

"Sean L. Palmer" <seanpalmer@earthlink.net> wrote in message news:adgb2d$1unv$1@digitaldaemon.com...
> It's just that there's so many loose .GIF files that way.  ;(   And it's
not
> as searchable.
>
> That wasn't my main point.  HTML help is fine.
>
> Sean

I like the HTML. Even windows uses html for alot of it's help documention. It would be nice to have a search feature however.

"Walter" <walter@digitalmars.com> wrote in message news:adgd45$20t0$2@digitaldaemon.com...
>
> "Pavel Minayev" <evilone@omen.ru> wrote in message news:adg7f4$1r5b$1@digitaldaemon.com...
> > The only problem with HTML docs, they cannot be searched for topics/keywords.
>
> Yes, though I am using Atomz as a workaround for that.
>
> > However, there are solutions of that problem, varying across the
> platforms.
> > I think it would be a good idea to compile it into CHM for Windows distribution...
>
> If there was a reliable html->chm compiler that might be a possibility (reliable in that no tweaking is necessary). Otherwise, I doubt it is
worth
> the effort.
>
>

"Walter" <walter@digitalmars.com> wrote in message news:adgd45$20t0$2@digitaldaemon.com...

> If there was a reliable html->chm compiler that might be a possibility (reliable in that no tweaking is necessary). Otherwise, I doubt it is
worth
> the effort.

I don't think you need tweaking to make a CHM out of a set of HTMLs. The only thing that needs to be done, one must create a hierarchical table of contents.

"Martin M. Pedersen" <mmp@www.moeller-pedersen.dk> wrote in message news:adg5d2$1osp$1@digitaldaemon.com...
> "Walter" <walter@digitalmars.com> wrote in message news:adg4ej$1o24$1@digitaldaemon.com...
> > I agree with you that things should be customized to work as expected on
> the
> > particular machine it is implemented on. But I disagree about
> documentation.
> > I find that html is a great way to do documentation, and it works well
on
> > win32.
>
> I like HTML documentation too, and I normally use Doxygen to make it. It
is
> a great tool that also allows the documentation to be generated in e.g. Latex, CHM, RTF, and XML, thereby reducing maintenance cost even further. Latex and RTF are good for printed documentation, while HTML is not. XML
is
> good for further processing. For these reasons, I prefer the Doxygen (or JavaDoc) approach for documentation.
>
> Regards,
> Martin M. Pedersen
>
>


I agree with you on this. Doxygen and JavaDoc rule!
I even proposed special syntax in the language to
support such tools, so we would have a standard
for writing documentation too...
I guess in the absence of such a standard the
wisest thing to do for future DDoc writers would
be to analyse DoxyGen and JavaDoc, to decide on
the best format.


--
Stijn
OddesE_XYZ@hotmail.com
http://OddesE.cjb.net
_________________________________________________
Remove _XYZ from my address when replying by mail

<snip>
> I agree with you on this. Doxygen and JavaDoc rule!
<snip>
> wisest thing to do for future DDoc writers would
> be to analyse DoxyGen and JavaDoc, to decide on
> the best format.
<snip>

I agree i'd be nice to have something like that in D. Parhaps there's a way to improve on DoxyGen and JavaDoc to make the output even more intuative.

--Just a thought

For example I'd be good if the generated doc would beable to compare differn't versions/depresiations and even generate something simular to the Walters "Converting C to D" page.

Perhaps the commenting would be something like this

/*
Title = ...
Version = "D" (or a number)
Description = you no longer need to ...
AlsoSee = Func1, Func2 ...
Arg1 = ...
Arg2 = ...
Returns = ...

Version = "C" (or a number)
Description = you have to ....
*/
bool Func(int Arg1, int Arg2)
{

}

And version would be optional. The topmost version would be considered the latest version. Older version documentation would only be placed in the versioning docs. The latest version would be used for the main hieratically documents. Perhaps there could be a special commenting character in D for this instead of /* */. I'd be nice if this was built into the complier, but that's probably to much extra work, and could be done in a make/bat (yuk) file instead.

Perhaps DoxyGen and JavaDoc already have something like that, which I missed.

But I'd agree that this would probably be to complex for at least the initial version.