www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Documentation 'quick index'

reply Piotr Szturmaj <bncrbme jadamspam.pl> writes:
Hi,

I'm trying to make ddoc index more readable. Here are some early
results:

http://bot.neostrada.pl/dpl.org/std.datetime.html

Do you know some free icons of class, enum, function, etc? I'm thinking
of something like this: http://msdn.microsoft.com/en-us/library
/y47ychfe%28v=vs.80%29.aspx

Thanks
Nov 28 2011
next sibling parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
On Mon, 28 Nov 2011 22:38:49 +0200, Piotr Szturmaj <bncrbme jadamspam.pl>  
wrote:


 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html


I think that for something like this to have full benefit, DDoc would need  
to be fixed so that generated anchors include their context.


 Do you know some free icons of class, enum, function, etc? I'm thinking
 of something like this: http://msdn.microsoft.com/en-us/library
 /y47ychfe%28v=vs.80%29.aspx


Try looking at some FOSS IDEs: Eclipse, CodeBlocks, KDevelop, etc.

-- 
Best regards,
  Vladimir                            mailto:vladimir thecybershadow.net
Nov 28 2011
next sibling parent Piotr Szturmaj <bncrbme jadamspam.pl> writes:
Vladimir Panteleev wrote:

 On Mon, 28 Nov 2011 22:38:49 +0200, Piotr Szturmaj
 <bncrbme jadamspam.pl> wrote:


 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html


 I think that for something like this to have full benefit, DDoc would
 need to be fixed so that generated anchors include their context.


Yes, DDoc may be changed to inject mangled names. With javascript 
demangler they may be very helpful.


 Do you know some free icons of class, enum, function, etc? I'm thinking
 of something like this: http://msdn.microsoft.com/en-us/library
 /y47ychfe%28v=vs.80%29.aspx


 Try looking at some FOSS IDEs: Eclipse, CodeBlocks, KDevelop, etc.


Will do, thanks.
Nov 28 2011
prev sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On Monday, November 28, 2011 22:45:17 Vladimir Panteleev wrote:

 On Mon, 28 Nov 2011 22:38:49 +0200, Piotr Szturmaj <bncrbme jadamspam.pl>
 
 wrote:

 Hi,
 
 I'm trying to make ddoc index more readable. Here are some early
 results:
 
 http://bot.neostrada.pl/dpl.org/std.datetime.html


 
 I think that for something like this to have full benefit, DDoc would need
 to be fixed so that generated anchors include their context.


Yeah. I'd have made std.datetime's links similar to what's in std.algorithm, 
but as long as anchors aren't unique, there's not much point.

Whether this specific proposal is really the best way to go or not, I don't 
know, but there's no question that the links should represent the hierarchy of 
the module.

- Jonathan M Davis
Nov 28 2011
parent reply Piotr Szturmaj <bncrbme jadamspam.pl> writes:
Jonathan M Davis wrote:

 On Monday, November 28, 2011 22:45:17 Vladimir Panteleev wrote:

 On Mon, 28 Nov 2011 22:38:49 +0200, Piotr Szturmaj<bncrbme jadamspam.pl>

 wrote:

 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html


 I think that for something like this to have full benefit, DDoc would need
 to be fixed so that generated anchors include their context.


 Yeah. I'd have made std.datetime's links similar to what's in std.algorithm,
 but as long as anchors aren't unique, there's not much point.


I think that <a name="mangledName"></a> would be the best approach. This 
would make tree generation easier (currently it parses text near to 
anchor) and all anchors would be unique.


 Whether this specific proposal is really the best way to go or not, I don't
 know, but there's no question that the links should represent the hierarchy of
 the module.


Do you mean sort order? This can be made switchable with single checkbox.
Nov 28 2011
parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Monday, November 28, 2011 22:17:02 Piotr Szturmaj wrote:

 Jonathan M Davis wrote:

 On Monday, November 28, 2011 22:45:17 Vladimir Panteleev wrote:

 On Mon, 28 Nov 2011 22:38:49 +0200, Piotr
 Szturmaj<bncrbme jadamspam.pl>
 
 wrote:

 Hi,
 
 I'm trying to make ddoc index more readable. Here are some early
 results:
 
 http://bot.neostrada.pl/dpl.org/std.datetime.html


 
 I think that for something like this to have full benefit, DDoc would
 need to be fixed so that generated anchors include their context.


 
 Yeah. I'd have made std.datetime's links similar to what's in
 std.algorithm, but as long as anchors aren't unique, there's not much
 point.


 
 I think that <a name="mangledName"></a> would be the best approach. This
 would make tree generation easier (currently it parses text near to
 anchor) and all anchors would be unique.


Using the mangled name would help deal with overloaded functions but would be 
completely unnecessary for classes and structs. Simply doing something like 
#SysTime.year would make it unique enough for them. But the manged names may 
be preferable, since then overloaded functions could be distintguished (though 
the anchors would then be a lot less human-readable).


 Whether this specific proposal is really the best way to go or not, I
 don't know, but there's no question that the links should represent the
 hierarchy of the module.


 
 Do you mean sort order? This can be made switchable with single checkbox.


No. I mean the hierarchy - as in understanding the difference between free 
functions and member functions. The links at the top should show member 
functions (and member variables if they're not private) as being part of the 
type that they're part of, not as free functions. The example that the OP 
gives does that, whereas the current situation just gives a list of links with 
no regard to what they point to. So, while some of the details of his 
presentation may not be the best, the basic idea is solid. Unfortunately, as 
long as the links are non-unique, it doesn't help much - particularly for 
std.datetime.

- Jonathan M Davis
Nov 28 2011
prev sibling next sibling parent reply "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Mon, 28 Nov 2011 15:38:49 -0500, Piotr Szturmaj <bncrbme jadamspam.pl>  
wrote:


 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html

 Do you know some free icons of class, enum, function, etc? I'm thinking
 of something like this: http://msdn.microsoft.com/en-us/library
 /y47ychfe%28v=vs.80%29.aspx


Just an FYI, this does not render properly on opera.  I have only have a  
top-level index that does not operate (and yes, I have javascript on).

My personal opinion is that the index should not rely on javascript  
whatsoever.  If anything, a collapsable index of everything should be  
available at the top (expanded by default if javascript is disabled).   
There should only be one level -- show all or hide all.

In general, DDoc suffers from so many deficiencies, fixing the index seems  
like wasted effort.  I'd prefer improvements like have one page per item  
(class, function, etc) similar to doxygen.  This would turn behemoths such  
as std.datetime into manageable doc pages.  I also think a vastly  
important (and for some reason ignored by ddoc) feature of documentation  
generators is cross referencing.  The whole benefit of having a computer  
generate documentation from source is that it knows how the source is  
related.  That should all be reflected.  For instance, I should be able to  
have a clickable inheritance tree for a class, and be able to have  
clickable links to overridden methods.  Any examples should have clickable  
links to the items being used.  These improvements would improve the docs  
by 2 orders of magnitude, whereas fixing the index is a trivial  
improvement.

Not that the index couldn't use improvement, however I understand the  
reluctance to take up the bigger ddoc tasks, I would not be able to do it.

-Steve
Nov 28 2011
parent Jacob Carlborg <doob me.com> writes:
On 2011-11-28 22:18, Steven Schveighoffer wrote:

 On Mon, 28 Nov 2011 15:38:49 -0500, Piotr Szturmaj
 <bncrbme jadamspam.pl> wrote:


 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html

 Do you know some free icons of class, enum, function, etc? I'm thinking
 of something like this: http://msdn.microsoft.com/en-us/library
 /y47ychfe%28v=vs.80%29.aspx


 Just an FYI, this does not render properly on opera. I have only have a
 top-level index that does not operate (and yes, I have javascript on).

 My personal opinion is that the index should not rely on javascript
 whatsoever. If anything, a collapsable index of everything should be
 available at the top (expanded by default if javascript is disabled).
 There should only be one level -- show all or hide all.

 In general, DDoc suffers from so many deficiencies, fixing the index
 seems like wasted effort. I'd prefer improvements like have one page per
 item (class, function, etc) similar to doxygen. This would turn
 behemoths such as std.datetime into manageable doc pages. I also think a
 vastly important (and for some reason ignored by ddoc) feature of
 documentation generators is cross referencing. The whole benefit of
 having a computer generate documentation from source is that it knows
 how the source is related. That should all be reflected. For instance, I
 should be able to have a clickable inheritance tree for a class, and be
 able to have clickable links to overridden methods. Any examples should
 have clickable links to the items being used. These improvements would
 improve the docs by 2 orders of magnitude, whereas fixing the index is a
 trivial improvement.

 Not that the index couldn't use improvement, however I understand the
 reluctance to take up the bigger ddoc tasks, I would not be able to do it.

 -Steve


I completely agree. Descent has quite a good ddoc generator, I think it 
cross references everything. But on the other hand it uses frames.

-- 
/Jacob Carlborg
Nov 28 2011
prev sibling next sibling parent reply Mike Wey <mike-wey example.com> writes:
On 11/28/2011 09:38 PM, Piotr Szturmaj wrote:

 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html

 Do you know some free icons of class, enum, function, etc? I'm thinking
 of something like this: http://msdn.microsoft.com/en-us/library
 /y47ychfe%28v=vs.80%29.aspx

 Thanks


CandyDoc comes with class, struct and other images:
http://www.dsource.org/projects/helix/browser/trunk/doc/candydoc/img/outline

-- 
Mike Wey
Nov 28 2011
parent Jacob Carlborg <doob me.com> writes:
On 2011-11-28 23:22, Mike Wey wrote:

 On 11/28/2011 09:38 PM, Piotr Szturmaj wrote:

 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html

 Do you know some free icons of class, enum, function, etc? I'm thinking
 of something like this: http://msdn.microsoft.com/en-us/library
 /y47ychfe%28v=vs.80%29.aspx

 Thanks


 CandyDoc comes with class, struct and other images:
 http://www.dsource.org/projects/helix/browser/trunk/doc/candydoc/img/outline


They are quite close to what Eclipse and Descent uses, but I think the 
ones Descent uses looks better.

-- 
/Jacob Carlborg
Nov 28 2011
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-11-28 21:38, Piotr Szturmaj wrote:

 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html

 Do you know some free icons of class, enum, function, etc? I'm thinking
 of something like this: http://msdn.microsoft.com/en-us/library
 /y47ychfe%28v=vs.80%29.aspx

 Thanks


Have a look at the icons Eclipse uses. You can also take a look at the 
icons used by Descent: 
http://dsource.org/projects/descent/browser/trunk/descent.ui/icons

-- 
/Jacob Carlborg
Nov 28 2011
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
On 2011-11-28 21:38, Piotr Szturmaj wrote:

 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html


That starts to look like CandyDoc.

-- 
/Jacob Carlborg
Nov 28 2011
prev sibling parent "Marco Leise" <Marco.Leise gmx.de> writes:
Am 28.11.2011, 21:38 Uhr, schrieb Piotr Szturmaj <bncrbme jadamspam.pl>:


 Hi,

 I'm trying to make ddoc index more readable. Here are some early
 results:

 http://bot.neostrada.pl/dpl.org/std.datetime.html

 Do you know some free icons of class, enum, function, etc? I'm thinking
 of something like this: http://msdn.microsoft.com/en-us/library
 /y47ychfe%28v=vs.80%29.aspx

 Thanks


I think the computer screen for the module could be replaced with the red  
D, as modules are the main organization unit and also .d files.
Nov 28 2011