On 2015-12-17 12:45, Walter Bright wrote:

> You're not one of the people I was referring to, since you do help.

So do it for those who do help and not for those how don't ;)

> Your issue with Ddoc is that the latex pdf generator you used was
> broken? Latex meets your critera as being very widely used. Use another
> pdf generator. Nobody has chained you to Latex.

I could care less about generating a PDF. But apparently someone cared and added it to the process of building dlang.org. So if you're willing to remove that or replace Latex with something else, please go ahead.

> Jacob, I've adapted several books for Ddoc on their way to being Kindle
> ebooks. Ddoc works fine for the formatting. The WORK is simply not the
> formatting, it's the text creation/editting. If you're spending the bulk
> of your time fiddling with Ddoc rather than text creation, I suspect
> you've gone off the rails somewhere.

Well, see for yourself [1]. None of the comments are related to the content. The content is the easy part.

[1] https://github.com/D-Programming-Language/dlang.org/pull/1039

-- 
/Jacob Carlborg

On 2015-12-17 23:40, Andrei Alexandrescu wrote:

> We are already using vibe.d for the Phobos page-per-name documentation.
> As far as I can tell the initiative has been a qualified success.

What's left/stopping us from using this as the default documentation?

> The main problem there is that there are not enough folks to maintain
> the vibe-related artifacts. Basically when Sönke is busy with something
> else, any issue may wait indefinitely. (I haven't followed that lately,
> possibly things have improved as of late.)
>
> In order to make the use of vibe.d entirely successful across dlang.org
> and dconf.org, we need to show robust gains from using it for Phobos. As
> virtually the sole maintainer of dconf.org, I'd feel definitely
> motivated to use vibe.d if there was good evidence of thriving
> collaboration around the use of it on http://dlang.org/library.
>
> Jacob, are you willing to ramp up you contribution to the vibe.d-related
> parts of Phobos? That would go a long way toward convincing everyone of
> the productivity gains of using it instead of ddoc (or others).

I would like to but I'm very busy as well. In addition to that I have basically no knowledge of the internals of the vibe.d related parts. I had a look at some PR's for Dub (I think) that Sönke called out for help with. I didn't feel I could add much help to that.

Is there anything more specific you're thinking about?

-- 
/Jacob Carlborg

On Thursday, 17 December 2015 at 20:21:00 UTC, Adam D. Ruppe wrote:
> On Thursday, 17 December 2015 at 19:51:19 UTC, Walter Bright wrote:
>> That has nothing to do with Ddoc, and is more about the organization of the files on github. Switching to another framework does nothing for that.
>
> Well, I basically agree with that.
>
> I know it is hard to keep track of whose position is what in a thread like this, but my problem isn't with ddoc per se, it is more that the current process is very complicated and pretty opaque.

Yes. This. And tbh it's the opaqueness that's the biggest problem.

On 12/17/2015 11:47 PM, Jacob Carlborg wrote:
> Well, see for yourself [1]. None of the comments are related to the content. The
> content is the easy part.
>
> [1] https://github.com/D-Programming-Language/dlang.org/pull/1039

I did have a look. Most of the PR is code and content, not markup. And most of the markup that is there is straightforward, like marking pages with $(P ... ).

I've written quite a bit of the dlang site.

On 12/18/15 3:06 AM, Jacob Carlborg wrote:
> On 2015-12-17 23:40, Andrei Alexandrescu wrote:
>
>> We are already using vibe.d for the Phobos page-per-name documentation.
>> As far as I can tell the initiative has been a qualified success.
>
> What's left/stopping us from using this as the default documentation?

As I said: a growing number of people able and willing to maintain and improve it. -- Andrei

On Friday, 18 December 2015 at 13:15:54 UTC, Andrei Alexandrescu wrote:
> As I said: a growing number of people able and willing to maintain and improve it. -- Andrei

Which would grow "tremendously" if it was using an online interface backed by a database.

On Friday, 18 December 2015 at 13:15:54 UTC, Andrei Alexandrescu wrote:
> On 12/18/15 3:06 AM, Jacob Carlborg wrote:
>> On 2015-12-17 23:40, Andrei Alexandrescu wrote:
>>
>>> We are already using vibe.d for the Phobos page-per-name documentation.
>>> As far as I can tell the initiative has been a qualified success.
>>
>> What's left/stopping us from using this as the default documentation?
>
> As I said: a growing number of people able and willing to maintain and improve it. -- Andrei

Two issues with the ddox generated documentation:

1. `static if` code is not shown [1]
2. probably some aliases are too early "resolved"
  Look for the type of sz that would be wrong on 32-bit:
    http://dlang.org/phobos-prerelease/core_memory.html#.GC.malloc
    http://dlang.org/library-prerelease/core/memory/gc.malloc.html

[1] https://github.com/rejectedsoftware/ddox/issues/86

On Thu, Dec 17, 2015 at 06:50:34PM -0500, Andrei Alexandrescu via Digitalmars-d wrote: [...]
> * "Examples:" is a historical error. All instances should be "Example:". Just one diff making that change throughout would be a meaningful contribution.
[...]

I'm pretty sure ddoc'd unittests show up as "Examples:". Or was this changed recently?


T

-- 
Give a man a fish, and he eats once. Teach a man to fish, and he will sit forever.

On 12/18/2015 10:19 AM, H. S. Teoh via Digitalmars-d wrote:
> On Thu, Dec 17, 2015 at 06:50:34PM -0500, Andrei Alexandrescu via Digitalmars-d wrote:
> [...]
>> * "Examples:" is a historical error. All instances should be "Example:".
>> Just one diff making that change throughout would be a meaningful
>> contribution.
> [...]
>
> I'm pretty sure ddoc'd unittests show up as "Examples:". Or was this
> changed recently?

It should get changed to singular because it's grammatically incorrect. Most examples shown feature exactly one instance of using the demonstrated artifact. So it's incorrect to write "Examples:" followed by one example.

Conversely, if there are multiple uses of the discussed artifact, then "Example:" is not incorrect - it's one example featuring several uses.


Andrei

On Friday, 18 December 2015 at 01:17:26 UTC, JohnCK wrote:
> On Friday, 18 December 2015 at 00:43:11 UTC, H. S. Teoh wrote:
>> ... I find the online forum interface klunky and inefficient to use (though most would disagree),
>
> One thing that bothers me sometimes is the waste of space, as  you can see in this SS, there are 2 versions, the original with highlights and the other that I modified.
>
> http://i.imgur.com/lx2qA7d.png
>
> JohnCK.

Maybe what I said above sound silly, but I'd like to take and say that I forgot to explain that space is very important on tiny screens like Tablets, in my case Galaxy Tab 3 - 7" inches.

And I'd to take the opportunity to point out another problem that I've found in some pages like:

1) On the menu -> resources -> New Library reference preview, some links are not working, example:

https://dlang.org/library/std/algorithm/comparison.html  <- In the top of the page there is:  This is submodule of "std.algorithm" <- Wrong link.

And the same thing is happening for the other pages like: https://dlang.org/library/std/algorithm/iteration.html and goes on...

2) Finally, in this page: https://dlang.org/phobos/std_algorithm.html, someone use align text set as "JUSTIFY", see how beautiful is in my Tablet:

http://i.imgur.com/bJKy6p7.png  (I highlighted in red).

JohnCK.