www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Improve anchors for ddoc (dlang.org)

reply "Martin Nowak" <dawg dawgfoto.de> writes:
Basically every caption in the language reference should have an anchor
so that one can refer to it.

http://www.dlang.org/template.html#class-templates    // <- missing
https://github.com/D-Programming-Language/d-programming-language.org/blob/master/template.dd#L749

http://www.dlang.org/template.html#function-templates
https://github.com/D-Programming-Language/d-programming-language.org/blob/master/template.dd#L805


For the library reference different scoped members with same names collide.
http://www.dlang.org/phobos/std_range.html#popFront

Listing a flat popFront in the jump-to header is pretty useless.
Each entry that has more than one member could have it's own jump-to.

std.range

Jump to: RangeA, RangeB, ...

...

struct RangeA;
-----------------------------
Jump to: front, popFront, ...
Feb 18 2012
next sibling parent "Yao Gomez" <yao.gomez gmail.com> writes:
On Saturday, 18 February 2012 at 17:24:13 UTC, Martin Nowak wrote:
 Basically every caption in the language reference should have 
 an anchor
 so that one can refer to it.

 http://www.dlang.org/template.html#class-templates    // <- 
 missing
 https://github.com/D-Programming-Language/d-programming-language.org/blob/master/template.dd#L749

 http://www.dlang.org/template.html#function-templates
 https://github.com/D-Programming-Language/d-programming-language.org/blob/master/template.dd#L805

Yes, totally agree about that. I think that an index with links to each section should be included at the beginning of some of the longer language reference pages, like for example this one: http://www.dlang.org/function There's a list of links at the beginning, but they link to the related specification part.
 For the library reference different scoped members with same 
 names collide.
 http://www.dlang.org/phobos/std_range.html#popFront

 Listing a flat popFront in the jump-to header is pretty useless.
 Each entry that has more than one member could have it's own 
 jump-to.

 std.range

 Jump to: RangeA, RangeB, ...

 ...

 struct RangeA;
 -----------------------------
 Jump to: front, popFront, ...

I think that this is a limitation of how DDOC generates the documents, the Javascript method that creates the list at the top of each Phobos module takes the first reference to that symbol, regardless of whether it corresponds to that or not. Either the doc gen capabilities should be enhanced, or the Javascript code should be improved to cope with this limitation.
Feb 18 2012
prev sibling next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
On Saturday, 18 February 2012 at 17:24:13 UTC, Martin Nowak wrote:
 For the library reference different scoped members with same 
 names collide.
 http://www.dlang.org/phobos/std_range.html#popFront

I've had a little solution in mind for this for a long time, but never went all the way in getting it integrated http://arsdnet.net/d-web-site/std_stdio.html I have a little html processor that loads the html ddoc puts out, then modifies it to fix the anchors and create summary charts for each group of things. I just forked dmd, gonna see if I can fix the generation up front. Then, maybe, I'll see about integrating my program into the docs build process.
Feb 18 2012
parent reply Jacob Carlborg <doob me.com> writes:
On 2012-02-18 21:58, Adam D. Ruppe wrote:
 On Saturday, 18 February 2012 at 17:24:13 UTC, Martin Nowak wrote:
 For the library reference different scoped members with same names
 collide.
 http://www.dlang.org/phobos/std_range.html#popFront

I've had a little solution in mind for this for a long time, but never went all the way in getting it integrated http://arsdnet.net/d-web-site/std_stdio.html I have a little html processor that loads the html ddoc puts out, then modifies it to fix the anchors and create summary charts for each group of things.

That's not the correct way to handle the problem. The ddoc generator should be fixed, not add another tool that tries to fix the problem.
 I just forked dmd, gonna see if I can fix the generation
 up front. Then, maybe, I'll see about integrating my program
 into the docs build process.

-- /Jacob Carlborg
Feb 18 2012
parent reply Jacob Carlborg <doob me.com> writes:
On 2012-02-19 00:27, Adam D. Ruppe wrote:
 On Saturday, 18 February 2012 at 22:45:12 UTC, Jacob Carlborg wrote:
 That's not the correct way to handle the problem. The ddoc generator
 should be fixed, not add another tool that tries to fix the problem.

Yea, I'm doing the anchors in ddoc (see my other thread, I also want to fix the encoding probblem). But I still think more complex things like tables shouldn't be in the compiler. It complicates it a lot. Eventually, you'll want something external anyway to do things like listings, tags, overview, search. But, the anchor should be a relatively easy fix.

The compiler should try to provide as much information as possible (that makes sense), anchors, cross-referencing, inheritance hierarchy, and so on. Then it's up to the user how to use/display that information. Either using plain HTML or combined with JavaScript or similar. The ddoc generator in Descent can already handle these things: anchors, cross-referencing, inheritance hierarchy and so on. -- /Jacob Carlborg
Feb 18 2012
parent reply Jacob Carlborg <doob me.com> writes:
On 2012-02-19 01:20, Adam D. Ruppe wrote:
 On Saturday, 18 February 2012 at 23:45:30 UTC, Jacob Carlborg wrote:
 The compiler should try to provide as much information as possible
 (that makes sense), anchors, cross-referencing, inheritance hierarchy,
 and so on.

Simple patch here: https://github.com/adamdruppe/dmd/commit/654d39fe17397e0a80c95ce500f09ae49130bf2d A problem with dmd is it always calls that macro, even if you just referenced the name in the description. So, the anchors will be repeated.... but they are right now too! Nevertheless, these little changes at least let the anchors be *correct*, provided that we fix the macros to use $2 instead of $0 with them. Automatic cross referencing would be great too, but we can do that with a link macro and I'm not sure how to make it automatic...

Both manual and automatic cross-referencing would be good. Automatic cross-referencing, for example: struct Foo {} /// Foo bar (); When the documentation is generated for "bar" it should automatically create a link for "Foo" pointing to its documentation. Manual cross-referencing, for example: /// See_Also: $(ref getFoo) void setFoo (int foo); /// See_Also: $(ref setFoo) int getFoo (); When the documentation is generated for "setFoo" and "getFoo" it should expand the macro "ref" (or whatever it should be called) to a link to "setFoo" and "getFoo". This should handle the same function name in different modules. I guess this is will be possible when anchors are working properly. BTW, Descent already handle both of these. -- /Jacob Carlborg
Feb 19 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-02-19 18:03, Adam D. Ruppe wrote:
 On Sunday, 19 February 2012 at 16:55:53 UTC, Jacob Carlborg wrote:
 Manual cross-referencing, for example:

That might not be too hard in the compiler... though by the time it gets to doc.c, the function is a string... I'm getting to know the compiler better though. I'm pretty sure this won't be hard to add. Then I'll clean up my stuff and see about making pull requests for it. Three things right now: 1) proper output encoding (breaking change - no more embedded html outside macros) 2) better anchors (breaking change, but super minor. use $1 instead of $0 in our PSYMBOL macro to get the old behavior) 3) automatic linking
 BTW, Descent already handle both of these.

I haven't seen their code though.

This is an example of documentation generate by Descent: http://dl.dropbox.com/u/18386187/orange_descent_docs/index.html This is the source code (or at least a part of it) that generates the ddoc in Descent: http://dsource.org/projects/descent/browser/trunk/descent.ui/src/descent/internal/ui/javadocexport/JavadocWizard.java -- /Jacob Carlborg
Feb 19 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Saturday, February 18, 2012 23:45:12 Jacob Carlborg wrote:
 That's not the correct way to handle the problem. The ddoc generator
 should be fixed, not add another tool that tries to fix the problem.

Agreed. - Jonathan M Davis
Feb 18 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Saturday, 18 February 2012 at 22:45:12 UTC, Jacob Carlborg 
wrote:
 That's not the correct way to handle the problem. The ddoc 
 generator should be fixed, not add another tool that tries to 
 fix the problem.

Yea, I'm doing the anchors in ddoc (see my other thread, I also want to fix the encoding probblem). But I still think more complex things like tables shouldn't be in the compiler. It complicates it a lot. Eventually, you'll want something external anyway to do things like listings, tags, overview, search. But, the anchor should be a relatively easy fix.
Feb 18 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Saturday, 18 February 2012 at 23:27:43 UTC, Adam D. Ruppe 
wrote:
 But, the anchor should be a relatively easy fix.

Yeah, a very easy fix. Previously, it changed the name of the thing to become: "$(DDOC_PSYMBOL %s)", toChars() and this macro looked like DDOC_PSYMBOL=<u>$0</u> say we have a struct Test in the module cool. we'd get <u>Test</u> If we make it "$(DDOC_PSYMBOL %s, %s)", toChars(), toPrettyChars() in the compiler, we can change the macro to: DDOC_PSYMBOL=<u>$1</u> to keep the current look. But, we also have $0... $(DDOC_PSYMBOL Test, cool.Test) $1 = Test $2 = the full name, cool.Test We now have more stuff to use. All existing macros will have to change from $0 to $1 to keep the current behavior. I wonder how many people's docs this will break? It is an easy, easy fix though, and I'll fix the default macros too.
Feb 18 2012
prev sibling next sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Saturday, 18 February 2012 at 23:45:30 UTC, Jacob Carlborg 
wrote:
 The compiler should try to provide as much information as 
 possible (that makes sense), anchors, cross-referencing, 
 inheritance hierarchy, and so on.

Simple patch here: https://github.com/adamdruppe/dmd/commit/654d39fe17397e0a80c95ce500f09ae49130bf2d A problem with dmd is it always calls that macro, even if you just referenced the name in the description. So, the anchors will be repeated.... but they are right now too! Nevertheless, these little changes at least let the anchors be *correct*, provided that we fix the macros to use $2 instead of $0 with them. Automatic cross referencing would be great too, but we can do that with a link macro and I'm not sure how to make it automatic...
Feb 18 2012
prev sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
On Sunday, 19 February 2012 at 16:55:53 UTC, Jacob Carlborg wrote:
 Manual cross-referencing, for example:

That might not be too hard in the compiler... though by the time it gets to doc.c, the function is a string... I'm getting to know the compiler better though. I'm pretty sure this won't be hard to add. Then I'll clean up my stuff and see about making pull requests for it. Three things right now: 1) proper output encoding (breaking change - no more embedded html outside macros) 2) better anchors (breaking change, but super minor. use $1 instead of $0 in our PSYMBOL macro to get the old behavior) 3) automatic linking
 BTW, Descent already handle both of these.

I haven't seen their code though.
Feb 19 2012