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 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
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 parent reply "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
next sibling 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 "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
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 reply "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
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 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