Walter Bright wrote:
<snip>
> Sample pages generated by Ddoc:
> 
> www.digitalmars.com/d/phobos/std_math.html
> www.digitalmars.com/d/phobos/std_path.html

Already noticed a bug: it drops spaces, screwing up wordwrapping

const char[1]sep;
char[] defaultExt(char[]filename,char[]ext);

ought to be

const char[1] sep;
char[] defaultExt(char[] filename, char[] ext);

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:- C++@ a->--- UB@ P+ L E@ W++@ N+++ o K-@ w++@ O? M V? PS- PE- Y? PGP- t- 5? X? R b DI? D G e++>++++ h-- r-- !y
------END GEEK CODE BLOCK------

My e-mail is valid but not my primary mailbox.  Please keep replies on the 'group where everyone may benefit.

In article <dgnng9$2tb8$1@digitaldaemon.com>, Walter Bright says...
>
>No bugs fixed, just the new Ddoc documentation generator. It's not perfect, and the presentation highlighting and layout is more utilitarian than sublime, but it really does cut down on the work of generating reasonable looking documentation by about half.
>

Walter, Ddoc doesn't seem to like templates in the source, I get an error when I run the below D source with the -D switch.

(Sample test for Ddoc)

# /**
#  * <font face="Courier New">
#  * <li>Source          : isNegative.d </li>
#  * <li>Author          : David L. 'SpottedTiger' Davis</li>
#  * <li>D Compiler      : dmd v0.131</li>
#  * <li>Source Platform : Intel x86 / WinXP SP2</li>
#  * <li>Target Platform : An Intel x86-Based OS like MS Windows</li>
#  * </font>
#  */
#
# /+ When uncommented, an error occurs
# template isNegative(T)
# {
#     bool isNegative(out T v) { return true; }
# }
# +/
#
# debug( isneg )
# {
# int main()
# {
#     return 0;
# }
# }

Output using "dmd isneg.d -D -debug=isneg" :
---------
doctest

int main();

Source : isNegative.d Author : David L. 'SpottedTiger' Davis D Compiler : dmd v0.131 Source Platform : Intel x86 / WinXP SP2 Target Platform : An Intel x86-Based OS like MS Windows

--------------------------------------------------------------------------
Last modified: Tue Sep 20 13:03:20 2005

Also why does the top comments end up under the very first function? Plus I thought that if I wrapped my comments with the "<li>  </li>" tags that my spaces would remain as is (I used a fixed-width font like "Courier New"), but they're still pulled out.

Well, as in anything new, there are always some growing pains to work though, and Walter I do want to thank you for what you've done on the Ddoc feature thus far. But, I really hope it doesn't take you away from fixing bugs for too long, and I'd still love to see D v1.0 out the door sometime in the near future. <g>

David L.

-------------------------------------------------------------------
"Dare to reach for the Stars...Dare to Dream, Build, and Achieve!"
-------------------------------------------------------------------

MKoD: http://spottedtiger.tripod.com/D_Language/D_Main_XP.html

Awesome!  A few thoughts that I had while playing with this:

It would be nice if there were a way to run the documenter without generating an object file.

If the destination path does not exist, there should be an option to have it created (or perhaps this should be the default behavior).

There should be an option to have the destination path mimic the module name. For example, if I have three modules:

module mylib.p1.m1;
module mylib.p1.m2;
module mylib.p2.m1;

The files would go in these directories:

mylib/p1
mylib/p1
mylib/p2

We need a way to document templates, and embedded code should retain the template parameter names if instantiation is required.  ie.

template fn(T) {
T fn() {}
}

should be documented as returning a value of type T.

I'll admit to not having tried documenting templates yet, so perhaps it already works this way.  My only other issues at the moment have to do with formatting: documenting classes is somewhat confusing because the output does not make it clear which elements are class members.


Sean

Walter Bright wrote:
> No bugs fixed, just the new Ddoc documentation generator. It's not perfect,
> and the presentation highlighting and layout is more utilitarian than
> sublime, but it really does cut down on the work of generating reasonable
> looking documentation by about half.
> 
> I also found several errors in the pages converted to Ddoc format -
> inconsistencies between the code and the previous documentation. Hopefully,
> Ddoc will relegate such errors to the past.
> 
> It's pretty close to what we discussed in the newsgroup recently. Thanks to
> all for the very helpful suggestions.
> 
> http://www.digitalmars.com/d/changelog.html
> 
> Ddoc spec:
> 
> www.digitalmars.com/d/ddoc.html
> 
> Sample pages generated by Ddoc:
> 
> www.digitalmars.com/d/phobos/std_math.html
> www.digitalmars.com/d/phobos/std_path.html
> www.digitalmars.com/d/phobos/std_outbuffer.html
> www.digitalmars.com/d/phobos/std_stream.html
> 
> 

Very nice.

How do we control (from Ddoc) the emphasis used on highlighted example code?  There should be some Ddoc special section for emphasis to define how to emphasize keywords, operators, whitespace, identifiers, etc.

"David L. Davis" <SpottedTiger@yahoo.com> wrote in message news:dgpgjc$1gqt$1@digitaldaemon.com...
> Also why does the top comments end up under the very first function?

Because that's the first declaration following them. Adding a module declaration should resolve it.

> Plus I
> thought that if I wrapped my comments with the "<li>  </li>" tags that my
spaces
> would remain as is (I used a fixed-width font like "Courier New"), but
they're
> still pulled out.

No. You'll need to use <pre> or &nbsp;. <tt> might work.

> Well, as in anything new, there are always some growing pains to work
though,
> and Walter I do want to thank you for what you've done on the Ddoc feature
thus
> far. But, I really hope it doesn't take you away from fixing bugs for too
long,
> and I'd still love to see D v1.0 out the door sometime in the near future.
<g>

Documentation that sucks is holding D back. Ddoc will cut the effort needed to write new documentation by about 50%, and will cut by 99% the effort needed to upgrade to a better presentation. (I won't have to edit scores of files by hand anymore.)

"James Dunne" <james.jdunne@gmail.com> wrote in message news:dgpj8r$1j8d$1@digitaldaemon.com...
> How do we control (from Ddoc) the emphasis used on highlighted example code?  There should be some Ddoc special section for emphasis to define how to emphasize keywords, operators, whitespace, identifiers, etc.

Currently, it's not possible unless you do it manually using <pre> ... </pre> tags.

Eventually, I'd like to improve the code highlighter to wrap each grammar element in a style tag, and then with a style sheet you'll be able to completely control the emphasis on example code.

In article <dgplnc$1lts$1@digitaldaemon.com>, Walter Bright says...
>
>"David L. Davis" <SpottedTiger@yahoo.com> wrote in message news:dgpgjc$1gqt$1@digitaldaemon.com...
>> Also why does the top comments end up under the very first function?
>
>Because that's the first declaration following them. Adding a module declaration should resolve it.

Adding a "module isneg;" did solve this issue...but unless I missed it, I did't see this piece of information in Ddoc documentation. Could you please add it in. Thanks.

>> Plus I
>> thought that if I wrapped my comments with the "<li>  </li>" tags that my
>spaces
>> would remain as is (I used a fixed-width font like "Courier New"), but
>they're
>> still pulled out.
>
>No. You'll need to use <pre> or &nbsp;. <tt> might work.

Excellent! The "<pre><tt>Author    : Whoever</tt></pre>" worked great, all my whitespace stayed in place. <g>

>> Well, as in anything new, there are always some growing pains to work
>though,
>> and Walter I do want to thank you for what you've done on the Ddoc feature
>thus
>> far. But, I really hope it doesn't take you away from fixing bugs for too
>long,
>> and I'd still love to see D v1.0 out the door sometime in the near future.
><g>
>
>Documentation that sucks is holding D back. Ddoc will cut the effort needed to write new documentation by about 50%, and will cut by 99% the effort needed to upgrade to a better presentation. (I won't have to edit scores of files by hand anymore.)
>

Roger! I agree. It is time well spend improving the documentation, especially if it's saving your time on moving D forward! And it's very useful / helpful for the rest of us as well.

David L.

-------------------------------------------------------------------
"Dare to reach for the Stars...Dare to Dream, Build, and Achieve!"
-------------------------------------------------------------------

Walter Bright wrote:
> "James Dunne" <james.jdunne@gmail.com> wrote in message
> news:dgpj8r$1j8d$1@digitaldaemon.com...
> 
>>How do we control (from Ddoc) the emphasis used on highlighted example
>>code?  There should be some Ddoc special section for emphasis to define
>>how to emphasize keywords, operators, whitespace, identifiers, etc.
> 
> 
> Currently, it's not possible unless you do it manually using <pre> ...
> </pre> tags.
> 
> Eventually, I'd like to improve the code highlighter to wrap each grammar
> element in a style tag, and then with a style sheet you'll be able to
> completely control the emphasis on example code.
> 

Precisely what I meant. =P

"Walter Bright" <newshound@digitalmars.com> wrote in message news:dgpmsk$1n46$1@digitaldaemon.com...
>
> "James Dunne" <james.jdunne@gmail.com> wrote in message news:dgpj8r$1j8d$1@digitaldaemon.com...
> > How do we control (from Ddoc) the emphasis used on highlighted example code?  There should be some Ddoc special section for emphasis to define how to emphasize keywords, operators, whitespace, identifiers, etc.
>
> Currently, it's not possible unless you do it manually using <pre> ... </pre> tags.
>
> Eventually, I'd like to improve the code highlighter to wrap each grammar element in a style tag, and then with a style sheet you'll be able to completely control the emphasis on example code.
>
>

Awesome idea

Nice!

I tried it on Mango, but it GPF'd quite quickly. As you say, it's a good start.

I'd like to suggest a few things:

1)

# /********************
#    this kind of comment
# ********************/

winds up like this:

# this kind of comment *****************

can that be resolved by the doc generator?


2) clickable links between the various files/symbols add a huge amount of value

3) it would be nice to support custom rendering for the various documentation sections.

4) private classes are included. Should they be?

5) a distinction between overridden methods, abstract methods, and so on would be very useful. I mean, perhaps located in a seperate section?

6) a "project description" page, or pages, are really useful for guiding the uninitiated. Doxygen supports this via the @mainpage directive, and references to other parts of the doc are automatically generated ~ one of the better features of Doxygen (I think).

- Kris




"Walter Bright" <newshound@digitalmars.com> wrote in message news:dgnng9$2tb8$1@digitaldaemon.com...
> No bugs fixed, just the new Ddoc documentation generator. It's not
perfect,
> and the presentation highlighting and layout is more utilitarian than sublime, but it really does cut down on the work of generating reasonable looking documentation by about half.
>
> I also found several errors in the pages converted to Ddoc format - inconsistencies between the code and the previous documentation.
Hopefully,
> Ddoc will relegate such errors to the past.
>
> It's pretty close to what we discussed in the newsgroup recently. Thanks
to
> all for the very helpful suggestions.
>
> http://www.digitalmars.com/d/changelog.html
>
> Ddoc spec:
>
> www.digitalmars.com/d/ddoc.html
>
> Sample pages generated by Ddoc:
>
> www.digitalmars.com/d/phobos/std_math.html www.digitalmars.com/d/phobos/std_path.html www.digitalmars.com/d/phobos/std_outbuffer.html www.digitalmars.com/d/phobos/std_stream.html
>
>