On Tuesday, 27 February 2018 at 10:02:13 UTC, Basile B. wrote:
> Awesome work. IDEs could use this, i don't know how yet but i'll maybe try something one day.

Yeah, webfreak was talking to me about that on irc and I've had people ask me about the main dpldocs site being an api (to which I reply "it is already a REST api returning a XML representation.... called a static html page". which i think is good - this html is a bit verbose bu that's because i wrote it with a lot of semantic information included in the tags, it can be machine parsed and analyzed. need a lib for it? use my dom.d :P )

But anyway, once I see someone with a prototype and we can identify specific needs through use, then I'm open to adding more stuff to help that effort. Until then tho my feeling is YAGNI and I am keeping the code on this server simple - try the IDE integration just showing the HTML in a web view first, or scraping the html for plain text, and we'll see how that looks as the first draft.

> Are the doc persistent on your server ?
> For example is http://iz.dpldocs.info/v0.6.4/iz.html here forever ?

Logically yes, in reality, maybe but I'm in the shell right now `rm -r`ing from time to time as I update the generator, and then your page will be automatically rebuild on the next request with the new generator version.

But that has already stabilized quite a bit so a lot of those files may in fact sit there for a very long time. I may also clear some if i ever hit a disk space limit tho...

but in any case, if a page is requested, it will be there, even if it has to be unzipped/regenerated first. Just be a bit patient waiting for the load in those events.

On Tuesday, 27 February 2018 at 14:42:11 UTC, Adam D. Ruppe wrote:
> On Tuesday, 27 February 2018 at 10:02:13 UTC, Basile B. wrote:
>> Awesome work. IDEs could use this, i don't know how yet but i'll maybe try something one day.
>
> Yeah, webfreak was talking to me about that on irc and I've had people ask me about the main dpldocs site being an api (to which I reply "it is already a REST api returning a XML representation.... called a static html page". which i think is good - this html is a bit verbose bu that's because i wrote it with a lot of semantic information included in the tags, it can be machine parsed and analyzed. need a lib for it? use my dom.d :P )
>
> But anyway, once I see someone with a prototype and we can identify specific needs through use, then I'm open to adding more stuff to help that effort.

I think that nothing more is needed.

The idea is to use DCD to get the d source where a symbol is declared, from this file it's possible to guess the html page for this symbol. Actually i already do this for phobos (using the official html) and it works fine.

At first glance i can say that this will work perfectly for DUB packages. Once DCD gives a file, the IDE just have to look the parent folders to get the SemVer tag.
If the file is in a git repository things might be more complicated.

The only difference with what is done right now (in Coedit) is the url structure.
For now it's  "<module>.html#<symbol>" or "<package>_<module>.html#<symbol>".
While with ardrox it's <module>.<symbol>.html.

On 2/26/18 12:51 PM, Adam D. Ruppe wrote:
> ... I just have a built-in, simple, unified syntax: [symbol|alt text] where alt text is optional and symbol is looked up according to D scope rules. (you can also define custom symbols for things like author name links).
> 
> I link to the source automatically too, including to the specific line of the correct overload for functions, so no need for macros to do those.

Out of curiosity, what prompted [symbol|alt text] instead of going with the Markdown construct of [alt text][symbol]? I ask because if I'm able to get my Markdown support merged into DDoc, I'd like to support [symbol] and [alt text][symbol] links.

On Tuesday, 27 February 2018 at 16:00:26 UTC, David Gileadi wrote:
> Out of curiosity, what prompted [symbol|alt text] instead of going with the Markdown construct of [alt text][symbol]?

Well, markdown is [alt text](url), and adrdox actually DOES support that as well:

http://dpldocs.info/experimental-docs/adrdox.syntax.html#markdown-style-links

(I just added that last Friday though for gtkd docs compatibility!)

Though it does NOT support a symbol in there, just a URL right now. Maybe I can add it, but I always start conservative - allow the least syntax with the most restrictions I can, then loosen them as I'm sure it isn't annoying.


But anyway, the [symbol|alt text] comes from Wikipedia's markup actually, which is the first thing that comes to my mind to easily cross-link articles. On wikipedia, you use brackets to indicate a word as a link: `director = [[Avery Brooks]]`, for example, will link to that article. Similarly, `[[Star Trek: Deep Space Nine (season 6)|6]]` will just show the text "6", while linking to the page in there.

So I took that and generalized it a bit so it supports other URLs too, then simplified it to just one set of [] instead of two.


The big advantage for [] over markdown links is it is lighter syntax in the simple case:

/// See also: [intersect]

knows to link to the symbol `intersect`. Whereas:

/// See also: [intersect](intersect)

would be the equivalent markdown style, but it is repeated... so you might skip the alt text:

/// See also: (intersect)

but that conflicts with very common parenthetical text like "I think that's silly (sorta)..." and I wouldn't want "sorta" to be linked there!

So I just went with [].

On 2/27/18 9:21 AM, Adam D. Ruppe wrote:
> On Tuesday, 27 February 2018 at 16:00:26 UTC, David Gileadi wrote:
>> Out of curiosity, what prompted [symbol|alt text] instead of going with the Markdown construct of [alt text][symbol]?
> 
> Well, markdown is [alt text](url), and adrdox actually DOES support that as well:
> 
> http://dpldocs.info/experimental-docs/adrdox.syntax.html#markdown-style-links 
> 
> 
> (I just added that last Friday though for gtkd docs compatibility!)
> 
> Though it does NOT support a symbol in there, just a URL right now. Maybe I can add it, but I always start conservative - allow the least syntax with the most restrictions I can, then loosen them as I'm sure it isn't annoying.
> 
> 
> But anyway, the [symbol|alt text] comes from Wikipedia's markup actually, which is the first thing that comes to my mind to easily cross-link articles. On wikipedia, you use brackets to indicate a word as a link: `director = [[Avery Brooks]]`, for example, will link to that article. Similarly, `[[Star Trek: Deep Space Nine (season 6)|6]]` will just show the text "6", while linking to the page in there.
> 
> So I took that and generalized it a bit so it supports other URLs too, then simplified it to just one set of [] instead of two.
> 
> 
> The big advantage for [] over markdown links is it is lighter syntax in the simple case:
> 
> /// See also: [intersect]
> 
> knows to link to the symbol `intersect`. Whereas:
> 
> /// See also: [intersect](intersect)
> 
> would be the equivalent markdown style, but it is repeated... so you might skip the alt text:
> 
> /// See also: (intersect)
> 
> but that conflicts with very common parenthetical text like "I think that's silly (sorta)..." and I wouldn't want "sorta" to be linked there!
> 
> So I just went with [].

Markdown actually supports two kinds of links: inline links (which you describe above and I'm very happy you support) and reference links [1].

A reference link can be like [alt text][reference] or you can do the shortcut version if your alt text is the same as the reference name: [reference]. I currently support both forms in my upcoming Markdown PR, but they only link to references that are defined elsewhere in the document, like my [1] at the bottom of this message. What I want to do is automatically include references for symbols in the current scope, to support links to symbols via [symbol] and [alt text][symbol].


[1]: http://spec.commonmark.org/0.28/#reference-link

On Tuesday, 27 February 2018 at 16:39:08 UTC, David Gileadi wrote:
> Markdown actually supports two kinds of links: inline links (which you describe above and I'm very happy you support) and reference links [1].

Oh, I have something similar to that too.

http://dpldocs.info/experimental-docs/adrdox.syntax.html#footnotes

I actually didn't realize markdown had such... mine is probably not quite compatible... but [text][text] is an uncommon enough pattern it might just be workable. I doubt I'd ever write [link][link] without a space in between...

> What I want to do is automatically include references for symbols in the current scope, to support links to symbols via [symbol] and [alt text][symbol].

Yeah, that might work on both generators.

On 2/27/18 2:59 PM, Adam D. Ruppe wrote:
> On Tuesday, 27 February 2018 at 16:39:08 UTC, David Gileadi wrote:
>> Markdown actually supports two kinds of links: inline links (which you describe above and I'm very happy you support) and reference links [1].
> 
> Oh, I have something similar to that too.
> 
> http://dpldocs.info/experimental-docs/adrdox.syntax.html#footnotes
> 
> I actually didn't realize markdown had such... mine is probably not quite compatible... but [text][text] is an uncommon enough pattern it might just be workable. I doubt I'd ever write [link][link] without a space in between...
> 
>> What I want to do is automatically include references for symbols in the current scope, to support links to symbols via [symbol] and [alt text][symbol].
> 
> Yeah, that might work on both generators.

I hope so. I'm happy that D documentation is nicer to use. Thanks for working on it!

On 2/27/18 3:18 PM, David Gileadi wrote:
> On 2/27/18 2:59 PM, Adam D. Ruppe wrote:
>> On Tuesday, 27 February 2018 at 16:39:08 UTC, David Gileadi wrote:
>>> Markdown actually supports two kinds of links: inline links (which you describe above and I'm very happy you support) and reference links [1].
>>
>> Oh, I have something similar to that too.
>>
>> http://dpldocs.info/experimental-docs/adrdox.syntax.html#footnotes
>>
>> I actually didn't realize markdown had such... mine is probably not quite compatible... but [text][text] is an uncommon enough pattern it might just be workable. I doubt I'd ever write [link][link] without a space in between...
>>
>>> What I want to do is automatically include references for symbols in the current scope, to support links to symbols via [symbol] and [alt text][symbol].
>>
>> Yeah, that might work on both generators.
> 
> I hope so. I'm happy that D documentation is nicer to use. Thanks for working on it!

Whoops, should have been "...D documentation is *getting* nicer to use."

On Tuesday, 27 February 2018 at 15:49:37 UTC, Basile B. wrote:
>
> At first glance i can say that this will work perfectly for DUB packages. Once DCD gives a file, the IDE just have to look the parent folders to get the SemVer tag.
> If the file is in a git repository things might be more complicated.

In most cases its pretty easy from a git repo too, just run 'git describe'. That'll give you the latest (annotated) tag (which SHOULD be the semver number, and generally is for dub projects) and no other output. Nothing to parse or scrape.

If theres been extra commits since the last tag, then there's a little extra suffix appended to git describe's output, but its trivial enough to parse/remove if you need to.

On Monday, 26 February 2018 at 14:59:07 UTC, Adam D. Ruppe wrote:
> Many of you will already know this from the other thread or from my twitter, but I just added a on-demand downloader to my dpldocs.info domain to fetch and build docs for any* dub

Would be cool if you could add support for creating docs from any dub project stored on github and not only the ones on code.dlang.org.

e.g. create docs for https://github.com/anton-dutov/db:

http://githubdoc.dpldocs.info/anton-dutov/db/v6.0.22/db.html

or something like that.