Thread overview | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
November 28, 2011 Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
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 |
November 28, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Piotr Szturmaj | 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 |
November 28, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Vladimir Panteleev | 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. |
November 28, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Vladimir Panteleev | 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
|
November 28, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Jonathan M Davis | 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. |
November 28, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Piotr Szturmaj | 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
|
November 28, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Piotr Szturmaj | 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 |
November 28, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Piotr Szturmaj | 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 |
November 29, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Piotr Szturmaj | 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 |
November 29, 2011 Re: Documentation 'quick index' | ||||
---|---|---|---|---|
| ||||
Posted in reply to Piotr Szturmaj | 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 |
Copyright © 1999-2021 by the D Language Foundation