Re: Some feedback on the website.
On Thursday, 17 December 2015 at 13:44:31 UTC, John Colvin wrote: On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright wrote: On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote: Having said that, though, using ddoc for the website leads to other problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the associated relative/absolute URL nightmare that a proper web authoring system would have taken care of by default). Annoying, and maybe you have to spend a couple minutes picking the right one if you've forgotten for the moment => absolute nightmare? Come on. How does a user who happens to spot a mistake in the docs and wants to help work this out? This is happening to me right now. I have a live editor open in github to edit the template doc page. I'm trying to link to std.traits and cannot find how. FULL_XREF is used on the same page, but I don't know what arguments it can accept.
Re: Some feedback on the website.
On 2015-12-21 04:44, Vladimir Panteleev wrote: There is no definitive answer for when something is "good enough" If nobody knows what it takes to make Ddox the default, how do we know that it's not already good enough? but to get you started: https://github.com/rejectedsoftware/ddox/issues Finally :) -- /Jacob Carlborg
Re: Some feedback on the website.
On Saturday, 19 December 2015 at 10:54:36 UTC, Jacob Carlborg wrote: On 2015-12-18 14:15, Andrei Alexandrescu wrote: As I said: a growing number of people able and willing to maintain and improve it. -- Andrei I'm not sure if there's some miscommunications here. But more contributors will not magically help. There most be a reason for why Ddox is not the default documentation. Some features that are missing, some parts that are not good enough or similar. There needs to be a list of criteria for when Ddox can be made default. The contributors can work on these tasks that will improve Ddox which will eventually lead to making Ddox default. I'm asking for specifics. If nobody has the answer for this we don't know why Ddox is not good enough. And if we don't know that we can't really know that it's not good enough. And if that's the case it could be made the default right now. There is no definitive answer for when something is "good enough", but to get you started: https://github.com/rejectedsoftware/ddox/issues Note that many of these are essentially DMD JSON output bugs/limitations.
Re: Some feedback on the website.
On Sat, Dec 19, 2015 at 09:58:44AM -0500, Andrei Alexandrescu via Digitalmars-d wrote: > On 12/19/15 12:01 AM, Jakob Ovrum wrote: > >After further changes I was able to add `Params:` and `Returns:` with > >some valuable information, but it also comes with a fair amount of > >redundancy. I think a lot of our current functions have more than > >adequately documented parameters and return values, just without > >using sections. Some redundancy can be a good thing, but for most of > >those functions I don't see how simple-mindedly adding purely > >redundant information is impactful. > > > >The important thing is not those sections but that parameters and > >return values are documented. > > Agreed there's got to be measure in everything. I'm thinking in those > cases the existing documentation should be reformatted with the > standard sections. > > When you do standard-formatted documentation for many functions at > once, it seems kinda trite. But for folks who work on some program and > want to look up one function, reliance on a standard uniform format is > very helpful. [...] Yes, Walter has said the same thing before. Where the description is too short to warrant being in both a standard section and in prose, put it in the standard section. I'd even propose that it's OK to leave the function description blank if the info in the standard Params: and Returns: sections already fully define what it does. This isn't as literary, but we're writing reference documentation, not an essay contest, and consistently having information in standard sections makes it more useful as a reference. T -- "Hi." "'Lo."
Re: Some feedback on the website.
On 2015-12-18 14:15, Andrei Alexandrescu wrote: As I said: a growing number of people able and willing to maintain and improve it. -- Andrei I'm not sure if there's some miscommunications here. But more contributors will not magically help. There most be a reason for why Ddox is not the default documentation. Some features that are missing, some parts that are not good enough or similar. There needs to be a list of criteria for when Ddox can be made default. The contributors can work on these tasks that will improve Ddox which will eventually lead to making Ddox default. I'm asking for specifics. If nobody has the answer for this we don't know why Ddox is not good enough. And if we don't know that we can't really know that it's not good enough. And if that's the case it could be made the default right now. -- /Jacob Carlborg
Re: Some feedback on the website.
On 2015-12-19 06:01, Jakob Ovrum wrote: After further changes I was able to add `Params:` and `Returns:` with some valuable information, but it also comes with a fair amount of redundancy. Ok, cool. I missed that. -- /Jacob Carlborg
Re: Some feedback on the website.
On 2015-12-18 12:07, Walter Bright wrote: 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'm talking about the comments in the PR, not the contents of the PR. It shows that the problems I had was with Ddoc and styling, not the content. -- /Jacob Carlborg
Re: Some feedback on the website.
On 12/19/15 12:01 AM, Jakob Ovrum wrote: After further changes I was able to add `Params:` and `Returns:` with some valuable information, but it also comes with a fair amount of redundancy. I think a lot of our current functions have more than adequately documented parameters and return values, just without using sections. Some redundancy can be a good thing, but for most of those functions I don't see how simple-mindedly adding purely redundant information is impactful. The important thing is not those sections but that parameters and return values are documented. Agreed there's got to be measure in everything. I'm thinking in those cases the existing documentation should be reformatted with the standard sections. When you do standard-formatted documentation for many functions at once, it seems kinda trite. But for folks who work on some program and want to look up one function, reliance on a standard uniform format is very helpful. Andrei
Re: Some feedback on the website.
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
Re: Some feedback on the website.
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.
Re: Some feedback on the website.
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.
Re: Some feedback on the website.
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.
Re: Some feedback on the website.
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.
Re: Some feedback on the website.
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
Re: Some feedback on the website.
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
Re: Some feedback on the website.
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
Re: Some feedback on the website.
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.
Re: Some feedback on the website.
On Friday, 18 December 2015 at 07:37:40 UTC, Jacob Carlborg wrote: On 2015-12-18 00:50, Andrei Alexandrescu wrote: * Many functions don't have "Parameters:", "Returns:", or "Throws:" sections. Those that respectively take parameters, return non-void, or throw, should have one each. I think we need to be better at enforcing this in the pull requests. I see a lot of this [2] in PR's. After further changes I was able to add `Params:` and `Returns:` with some valuable information, but it also comes with a fair amount of redundancy. I think a lot of our current functions have more than adequately documented parameters and return values, just without using sections. Some redundancy can be a good thing, but for most of those functions I don't see how simple-mindedly adding purely redundant information is impactful. The important thing is not those sections but that parameters and return values are documented.
Re: Some feedback on the website.
On 2015-12-16 21:54, Walter Bright wrote: I'm not so sure. There are lots of tools to develop websites. Let's say A, B, and C. If we picked "B", we most assuredly would have analogous threads here saying "I won't use anything but A" and "Everybody else uses C." Anything that is explicitly created for web development would be better. I've heard all sorts of excuses for decades about why people won't chip in, and I know they are excuses because when the excuse is fixed, they still won't chip in. This excuse sounds the same as the rest. The thing is, if you know html, then you know Ddoc. Ddoc is just a stupidly simple text-substitution macro system a programmer should be able to learn in a few minutes. I know HTML, and I know there's no problem with underscores in HTML. Yet Ddoc is causing issues with underscores because Latex is used to generate the PDF [1]. [1] http://forum.dlang.org/post/n4tpdd$2kun$1...@digitalmars.com -- /Jacob Carlborg
Re: Some feedback on the website.
On 2015-12-16 23:32, H. S. Teoh via Digitalmars-d wrote:
This is a limitation of ddoc that needs to be fixed. Historically,
template functions used to be written like this:
template amap(Args...)
{
auto amap(Args args) {
implementation();
}
}
Then a shorthand was introduced (the so-called "eponymous template"
syntax), such that the above incantation could be abbreviated to:
auto amap(Args...)(Args args) {
implementation();
}
It would appear that ddoc came after eponymous templates became the
norm, so currently, ddoc only understands ddoc comments attached to the
latter syntax, while it fails to recognize that the former syntax is
actually equivalent. Several other functions in Phobos suffer from the
resulting formatting disparity, IIRC map(), and maybe reduce(), and one
or two others. It's rare enough that we don't encounter it very often,
but the functions affected happen to be ones that are likely to be
frequently used, so we really ought to fix this limitation in ddoc.
How would Ddoc know that you want to document the function and not the
template? Just assume so if there's only one symbol in the template? It
still needs to be possible to individually document the template and the
function, and least when there's more than one symbol in the template.
--
/Jacob Carlborg
Re: Some feedback on the website.
On 2015-12-16 21:59, Andrei Alexandrescu wrote: If some of these are unnecessary, they can be easily fixed. There's no problem with breaking other people's code etc. Which would you eliminate? A sane doc generation system would need at most two macros/syntaxes/functions to create links. One macro accepting a symbol name (fully qualified or not) used for cross-referencing and one macro used for page and external links, accepting a relative or an absolute URL. It's also possible to manged without any of these at all. The doc tool could automatically do cross-referencing and detect URL's. -- /Jacob Carlborg
Re: Some feedback on the website.
On 2015-12-17 00:46, Andrei Alexandrescu wrote: Overall I think a few additions to the macro engine could be very beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to expand b if a is nonempty and c otherwise. Oh, God, please no. Just use vibe.d and be done with it. We obviously need a proper programming language to generate dconf.org. -- /Jacob Carlborg
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 08:06:28 UTC, Jacob Carlborg wrote: On 2015-12-17 00:46, Andrei Alexandrescu wrote: Overall I think a few additions to the macro engine could be very beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to expand b if a is nonempty and c otherwise. Oh, God, please no. Just use vibe.d and be done with it. We obviously need a proper programming language to generate dconf.org. That would be a whole re-write of the website though. It would be preferable of course. The official D site being run through one of it's more popular libraries (it's most popular library maybe?) can only be a good thing.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 22:32:25 UTC, H. S. Teoh wrote:
On Wed, Dec 16, 2015 at 10:00:50PM +, Meta via
Digitalmars-d wrote:
There's also weird stuff like this, with an outer template and
a documented inner template function.
http://dlang.org/phobos/std_parallelism.html#.TaskPool.amap.amap
This is a limitation of ddoc that needs to be fixed.
Historically, template functions used to be written like this:
template amap(Args...)
{
auto amap(Args args) {
implementation();
}
}
Then a shorthand was introduced (the so-called "eponymous
template" syntax), such that the above incantation could be
abbreviated to:
auto amap(Args...)(Args args) {
implementation();
}
It would appear that ddoc came after eponymous templates became
the norm, so currently, ddoc only understands ddoc comments
attached to the latter syntax, while it fails to recognize that
the former syntax is actually equivalent. Several other
functions in Phobos suffer from the resulting formatting
disparity, IIRC map(), and maybe reduce(), and one or two
others. It's rare enough that we don't encounter it very often,
but the functions affected happen to be ones that are likely to
be frequently used, so we really ought to fix this limitation
in ddoc.
I think in this particular case it can only be done with a nested
template, because there are two variadic parameters.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright wrote: On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote: Having said that, though, using ddoc for the website leads to other problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the associated relative/absolute URL nightmare that a proper web authoring system would have taken care of by default). Annoying, and maybe you have to spend a couple minutes picking the right one if you've forgotten for the moment => absolute nightmare? Come on. How does a user who happens to spot a mistake in the docs and wants to help work this out?
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 08:06:28 UTC, Jacob Carlborg wrote: We obviously need a proper programming language to generate dconf.org. I can't agree with this. I think there's too many conditionals already. Build the docs on posix and you miss out on Windows functions. Ugh.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 07:53:02 UTC, Jacob Carlborg wrote: No sane person would use raw HTML. I hope no one takes that suggestion serious. HTML + a couple simple helper tools is a different story though. That's basically what ddoc is anyway, but it has the weird behavior of just thinly wrapping html in macros $(DIVID $(B $(LINK2 seriously wtf)) In IRC I mentioned XSLT as a bit of a joke, but it solves the problem of reusing skeleton layouts too. There's LOTS of ways to do this, and the language in which the doc pages are written is different than the framework which brings them all together and does other post processing.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 07:51:42 UTC, Jacob Carlborg wrote: On 2015-12-17 00:43, BLM768 wrote: One is to make as much of it as possible in plain old static HTML. Stuff like the articles rarely changes, after all. This is an horrible idea. No sane person would use raw HTML. The only advantage is that it's HTML so there's documentation available. Yeah. I didn't think that one through. The idea I had in my head was to build a template in (mostly) raw HTML, write each article as an HTML snippet, and use either a framework or a build script to paste them together, so it's not _completely_ raw, just enough so you actually see the HTML. The main thing was to move away from building all the tags with macros. But yeah, I didn't express that clearly enough (or think through it properly).
Re: Some feedback on the website.
On 12/17/2015 5:44 AM, John Colvin wrote: On Thursday, 17 December 2015 at 11:47:23 UTC, Walter Bright wrote: On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote: Having said that, though, using ddoc for the website leads to other problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the associated relative/absolute URL nightmare that a proper web authoring system would have taken care of by default). Annoying, and maybe you have to spend a couple minutes picking the right one if you've forgotten for the moment => absolute nightmare? Come on. How does a user who happens to spot a mistake in the docs and wants to help work this out? 1. he can file a bugzilla issue 2. he can click on the "Improve this page" 3. to find out what LREF does: grep LREF *.ddoc If what a trivial text macro does is beyond his ken, and/or using grep, I wonder if he should be improving programming documentation at all. I do expect this to be part of the baseline knowledge a programmer should have. I wouldn't expect an accountant to know this stuff.
Re: Some feedback on the website.
On 12/17/15 2:43 PM, Adam D. Ruppe wrote: On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright wrote: 3. to find out what LREF does: grep LREF *.ddoc So, you're working on Phobos and see a LREF macro. me@arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc me@arsd:~/d/dmd2/src/phobos$ where is it? I happen to know it is hidden in the dlang.org repo, but would someone who saw a problem in the Phobos docs know that? They seem to be generated from the source code except when they aren't. You can't assume everybody knows all the institutional knowledge you do! A document discussing this kind of stuff would be golden. Maybe a good topic for next week's TWiD? -- Andrei
Re: Some feedback on the website.
On 12/16/15 6:47 PM, BLM768 wrote: On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote: [snip] ...and as I read some older posts, I see that mine is completely redundant. ;) Seriously, though, I'm willing to help prototype something. I've got time before the next semester starts. If you have some time and motivation to improve the documentation, there's tremendous opportunity for impact. So much low-hanging fruit, all well before we explore switching to a different way of building the site. And whatever improvements you make won't compete with future changes. There's so much opportunity there it hurts. -- Andrei
Re: Some feedback on the website.
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. I have more hatred toward the makefiles than toward the doc format. BTW, when I was working on Phobos docs, Phobos had its own std.ddoc in the Phobos repo. std.ddoc was destroyed ages ago, the file no longer exists!
Re: Some feedback on the website.
On 12/16/2015 10:47 AM, deadalnix wrote: Honestly for D code itself, ddoc does just fine, but for the website, plain html or some known template format like . This is what people know. I've never heard of .
Re: Some feedback on the website.
On 12/17/2015 4:27 AM, John Colvin wrote: The number of macros bothers me, but mostly it's the complete lack of documentation and guidelines on where/how to use them*. It's pretty unreasonable to expect someone submitting a passing doc fix to 1) find where the macros are defined 2) decipher them 3) use the "right" one** It's just too much unpleasant work for people to bother with. *If there is documentation and guidelines on this and I don't know about it, consider what it would be like for someone who doesn't spend many hours a week on the various subdomains of dlang.org: it might as well not exist! **there must be some reasons for the existence of all of those macros, so presumably there are good and bad choices for certain situations, even if nothing is obviously broken using the bad choice. Sure, we might say "submit something naïve and then people will help you fix it", but that's still a barrier to entry; 1) how were they supposed to know we felt that way about submissions? 2) people don't like looking stupid. Documentation in the std.ddoc files would certainly help. $(COMMENT this is comment) is a convention that works well. PRs to add explanatory comments are welcome.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote: My feedback: add the ability to edit posts in the forum You can't edit email.
Re: Some feedback on the website.
On 12/17/2015 11:43 AM, Adam D. Ruppe wrote: On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright wrote: 3. to find out what LREF does: grep LREF *.ddoc So, you're working on Phobos and see a LREF macro. me@arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc me@arsd:~/d/dmd2/src/phobos$ where is it? I happen to know it is hidden in the dlang.org repo, but would someone who saw a problem in the Phobos docs know that? They seem to be generated from the source code except when they aren't. 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. BTW, when I was working on Phobos docs, Phobos had its own std.ddoc in the Phobos repo. You can't assume everybody knows all the institutional knowledge you do! 1. digitalmars.D.learn 2. Linux: locate std.ddoc
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 22:28:25 UTC, Andrei Alexandrescu wrote: On 12/17/15 4:17 PM, deadalnix wrote: But, to start, let's take action. Andrei, does dlang.org has any kind of analytic setup ? We use webalizer. -- Andrei I would suggest using something more powerful. Log analysis is one thing, but modern tools can do more. If you are not comfortable with sending data to google, I suggest using piwik : https://piwik.org/ . Some more setup, but you are 100% in control of the data.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 19:50:40 UTC, Andrei Alexandrescu wrote: On 12/16/15 6:47 PM, BLM768 wrote: On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote: [snip] ...and as I read some older posts, I see that mine is completely redundant. ;) Seriously, though, I'm willing to help prototype something. I've got time before the next semester starts. If you have some time and motivation to improve the documentation, there's tremendous opportunity for impact. So much low-hanging fruit, all well before we explore switching to a different way of building the site. And whatever improvements you make won't compete with future changes. There's so much opportunity there it hurts. -- Andrei Yes, I'm kind of disappointed I brought up ddoc in there, because everything has been ignored now, while in there, there are many thing more important than using ddoc or not. And I'd say there is also way more impact changes to do than cleaning the doc as you mention. Searching the doc is late in the tunnel. Clearing the home page has much higher impact options. But, to start, let's take action. Andrei, does dlang.org has any kind of analytic setup ? If not, would you mind setting up something as google analytic ? That should give us data on what changes are impactful.
Re: Some feedback on the website.
On 12/17/15 4:17 PM, deadalnix wrote: But, to start, let's take action. Andrei, does dlang.org has any kind of analytic setup ? We use webalizer. -- Andrei
Re: Some feedback on the website.
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
Re: Some feedback on the website.
On 2015-12-18 00:50, Andrei Alexandrescu wrote: * Many functions don't have "Parameters:", "Returns:", or "Throws:" sections. Those that respectively take parameters, return non-void, or throw, should have one each. I think we need to be better at enforcing this in the pull requests. I see a lot of this [2] in PR's. * All functions should have an example. * "Examples:" is a historical error. All instances should be "Example:". Just one diff making that change throughout would be a meaningful contribution. The documentation for Ddco mentions "Examples:" [1]. Does it have a special meaning or is it just a convention? [1] http://dlang.org/spec/ddoc.html [2] https://github.com/D-Programming-Language/phobos/pull/3855#discussion_r46769338 -- /Jacob Carlborg
Re: Some feedback on the website.
On 12/17/15 5:32 PM, deadalnix wrote: On Thursday, 17 December 2015 at 22:28:25 UTC, Andrei Alexandrescu wrote: On 12/17/15 4:17 PM, deadalnix wrote: But, to start, let's take action. Andrei, does dlang.org has any kind of analytic setup ? We use webalizer. -- Andrei I would suggest using something more powerful. Log analysis is one thing, but modern tools can do more. If you are not comfortable with sending data to google, I suggest using piwik : https://piwik.org/ . Some more setup, but you are 100% in control of the data. I've used piwik, too. I think we're in good shape with analytics. Exploring alternative analytics engines would be a distraction. I just looked over the analytics and what we need now is good content and beautiful css. -- Andrei
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 19:50:40 UTC, Andrei Alexandrescu wrote: If you have some time and motivation to improve the documentation, there's tremendous opportunity for impact. So much low-hanging fruit, all well before we explore switching to a different way of building the site. And whatever improvements you make won't compete with future changes. There's so much opportunity there it hurts. -- Andrei As long as the main page still works, then yeah, that's first priority. Is there a particular spot that stands out as needing the most improvement? I'm no Phobos expert, but I can at least fill any glaring holes.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 20:08:32 UTC, Anon wrote: On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote: My feedback: add the ability to edit posts in the forum You can't edit email. So your point is that the Dlang forum is implemented more like a mailing list than a forum? This means that your point is really that it would be a lot of work to implement this feature (perhaps even migrating to a different type of framework).
Re: Some feedback on the website.
On 12/17/15 3:06 AM, Jacob Carlborg wrote: Oh, God, please no. Just use vibe.d and be done with it. We obviously need a proper programming language to generate dconf.org. 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. 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). Andrei
Re: Some feedback on the website.
On 12/17/2015 06:33 PM, BLM768 wrote: On Thursday, 17 December 2015 at 19:50:40 UTC, Andrei Alexandrescu wrote: If you have some time and motivation to improve the documentation, there's tremendous opportunity for impact. So much low-hanging fruit, all well before we explore switching to a different way of building the site. And whatever improvements you make won't compete with future changes. There's so much opportunity there it hurts. -- Andrei As long as the main page still works, then yeah, that's first priority. Is there a particular spot that stands out as needing the most improvement? I'm no Phobos expert, but I can at least fill any glaring holes. There's a bunch to do. * Many functions don't have "Parameters:", "Returns:", or "Throws:" sections. Those that respectively take parameters, return non-void, or throw, should have one each. * All functions should have an example. * "Examples:" is a historical error. All instances should be "Example:". Just one diff making that change throughout would be a meaningful contribution. * Overloaded functions should be collected together, connected with "/// ditto". * Examples on the site and on the library pages should be editable and runnable just like the one on the homepage. * Eliminating those redundant macros that everybody's talking about. Andrei
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 23:30:46 UTC, jmh530 wrote: On Thursday, 17 December 2015 at 20:08:32 UTC, Anon wrote: On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote: My feedback: add the ability to edit posts in the forum You can't edit email. Maybe I can answer your questions: So your point is that the Dlang forum is implemented more like a mailing list than a forum? Yes. This means that your point is really that it would be a lot of work to implement this feature (perhaps even migrating to a different type of framework). I think shouldn't count on that. JohnCK.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 08:15:49 UTC, wobbles wrote: That would be a whole re-write of the website though. We could of course also use ddoc and write a generator to whatever template language we like. The rest is peanuts.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 20:05:03 UTC, Vladimir Panteleev wrote: On Tuesday, 15 December 2015 at 21:45:02 UTC, deadalnix wrote: On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu wrote: On 12/15/15 5:54 AM, tcak wrote: The harder it is made for people to contribute the system for fixations, the lesser changes are seen. I don't think we've had many contributions via the "Improve this page" button. I don't know how representative it is, but once in a while, i forgot all of this is in DDoc, I notice something, what to do a quick patch, and end up being reminded this is in DDoc and I have no idea how to fix the thing, because suddenly, what looked like a quick fix end up being learning a new macro language. DDoc itself is very simple. The problem is the endless number of macros we use on dlang.org. E.g. all the different ways to link to something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, XREF, XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF, COREMODREF, OBJREF... There is also no strong reason to use e.g. DIVCID instead of plain HTML. The number of macros bothers me, but mostly it's the complete lack of documentation and guidelines on where/how to use them*. It's pretty unreasonable to expect someone submitting a passing doc fix to 1) find where the macros are defined 2) decipher them 3) use the "right" one** It's just too much unpleasant work for people to bother with. *If there is documentation and guidelines on this and I don't know about it, consider what it would be like for someone who doesn't spend many hours a week on the various subdomains of dlang.org: it might as well not exist! **there must be some reasons for the existence of all of those macros, so presumably there are good and bad choices for certain situations, even if nothing is obviously broken using the bad choice. Sure, we might say "submit something naïve and then people will help you fix it", but that's still a barrier to entry; 1) how were they supposed to know we felt that way about submissions? 2) people don't like looking stupid.
Re: Some feedback on the website.
On 12/16/2015 11:12 AM, H. S. Teoh via Digitalmars-d wrote: Having said that, though, using ddoc for the website leads to other problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the associated relative/absolute URL nightmare that a proper web authoring system would have taken care of by default). Annoying, and maybe you have to spend a couple minutes picking the right one if you've forgotten for the moment => absolute nightmare? Come on.
Re: Some feedback on the website.
On 12/16/2015 11:49 PM, Jacob Carlborg wrote: I already help, and I use Ddoc, that's how I know it's crap ;). You're not one of the people I was referring to, since you do help. I wrote the documentation for interfacing with Objective-C [1]. It was very frustrating, especially since the PDF generator broke because latex can't handle underscores as in "D_ObjectiveC". I did get some help in the pull request but not from someone that knew how this actually worked. It was most guesses. If a more widely tool had been used I might have been able to find out how this actually works and fixed it. Instead I had to revert to use a hack like wrapping the text in the $(D_CODE) macro. 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. > Of course, you will always have the issues you mention above. But if you choose > a tool that is created for web design and is widely used you will most likely > have less of these issues. Most importantly, when something doesn't work there's > documentation online to get help from. Amazon broke the PDF reader in their latest Kindle. I filed a bug report, but there's nothing I can do about it, and Amazon hasn't/won't fix it. They've sold millions of the things. 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.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 19:27:56 UTC, Walter Bright wrote: 3. to find out what LREF does: grep LREF *.ddoc So, you're working on Phobos and see a LREF macro. me@arsd:~/d/dmd2/src/phobos$ grep -R LREF *.ddoc me@arsd:~/d/dmd2/src/phobos$ where is it? I happen to know it is hidden in the dlang.org repo, but would someone who saw a problem in the Phobos docs know that? They seem to be generated from the source code except when they aren't. You can't assume everybody knows all the institutional knowledge you do!
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 19:31:10 UTC, Walter Bright wrote: On 12/16/2015 10:47 AM, deadalnix wrote: Honestly for D code itself, ddoc does just fine, but for the website, plain html or some known template format like . This is what people know. I've never heard of . My feedback: add the ability to edit posts in the forum
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 19:51:33 UTC, Andrei Alexandrescu wrote: A document discussing this kind of stuff would be golden. Maybe a good topic for next week's TWiD? -- Andrei If someone writes it, certainly, but I barely know it myself. I have only successfully build the dlang.org site locally once and that was after you walked through it and I forgot it all since then (except that I remember all the negative emotion of the process like frustration) Our documentation is lacking documentation... BTW, on the topic of TWiD, I actually do write it in DDoc, but there's also a post-processor I run on the generated HTML to make up for the lack of things like indexes and some links, and I still feel it is a bit of a pain to use. Missing parenthesis often leak through to show macros in the end, and having to replace $ in links (your message IDs always have them so when I link to your threads, I do a $ -> $(DOLLAR) find/replace, but gotta be careful to run it only once!) I'm not unhappy with it and don't want to change it, but I'm not terribly happy with it either and kinda wish I did it differently. Overall, my feeling is just... meh. Ddoc is good for inline documentation, and it can become awesome if we do a little more work to it (and yes, I might do it myself if I can ever find the time), but for stand-alone pages... meh, it gets the job done, at least with a bit of help.
Re: Some feedback on the website.
On Thursday, 17 December 2015 at 23:50:34 UTC, Andrei Alexandrescu wrote: * "Examples:" is a historical error. All instances should be "Example:". Just one diff making that change throughout would be a meaningful contribution. Like so? https://github.com/blm768/phobos/commit/5f08c058abd2bafe91056d5223d45ed5c07a748c Sed for the win! (With manual review of the changes, of course.) I'll open a pull request in a moment.
Re: Some feedback on the website.
On Thu, Dec 17, 2015 at 11:30:46PM +, jmh530 via Digitalmars-d wrote: > On Thursday, 17 December 2015 at 20:08:32 UTC, Anon wrote: > >On Thursday, 17 December 2015 at 20:04:44 UTC, jmh530 wrote: > >>My feedback: add the ability to edit posts in the forum > > > >You can't edit email. > > So your point is that the Dlang forum is implemented more like a > mailing list than a forum? This means that your point is really that > it would be a lot of work to implement this feature (perhaps even > migrating to a different type of framework). Some of us (including myself) do not use the forum.dlang.org interface at all, but actually receive messages in email form. I prefer it that way because I find the online forum interface klunky and inefficient to use (though most would disagree), whereas in email form I can navigate and manage discussion threads with far greater efficiency. I would hate to have to actually start up a resource-hogging browser just to read forum posts. T -- Making non-nullable pointers is just plugging one hole in a cheese grater. -- Walter Bright
Re: Some feedback on the website.
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.
Re: Some feedback on the website.
On 2015-12-16 14:50, Andrei Alexandrescu wrote: What standardized format was dominant in 2001? Thanks! -- Andrei 2001? According to the changelog Ddoc was added 2005 [1]. I hadn't really started to use D back then and barely programming at all. I would say Javadoc, Doxygen or Markdown, without knowing how standardized they were back then (if they existed). But most important, Ddoc should not be used for website. I would prefer a template language with a proper server side language. Something like Haml, which allows to use filters where Markdown is one of the filters [2]. Good when writing longer texts. vibe.d's diet templates seems to be a good choice, it's indirectly based on Haml. Not sure if it supports filters though. [1] http://www.digitalmars.com/d/1.0/changelog1.html#new0132 [2] http://haml.info/docs/yardoc/file.REFERENCE.html#filters -- /Jacob Carlborg
Re: Some feedback on the website.
On Tuesday, 15 December 2015 at 21:45:02 UTC, deadalnix wrote: On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu wrote: On 12/15/15 5:54 AM, tcak wrote: The harder it is made for people to contribute the system for fixations, the lesser changes are seen. I don't think we've had many contributions via the "Improve this page" button. I don't know how representative it is, but once in a while, i forgot all of this is in DDoc, I notice something, what to do a quick patch, and end up being reminded this is in DDoc and I have no idea how to fix the thing, because suddenly, what looked like a quick fix end up being learning a new macro language. DDoc itself is very simple. The problem is the endless number of macros we use on dlang.org. E.g. all the different ways to link to something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, XREF, XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF, COREMODREF, OBJREF... There is also no strong reason to use e.g. DIVCID instead of plain HTML.
Re: Some feedback on the website.
On 12/16/2015 03:59 PM, JohnCK wrote: On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote: I'm not so sure... Like they say: "A father will never agree that his child is ugly!" To me it seems he's making a few good points. -- Andrei
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 19:12:04 UTC, H. S. Teoh wrote: On Wed, Dec 16, 2015 at 06:47:26PM +, deadalnix via Digitalmars-d wrote: [...] Using ddoc for the website may be NIH, but the ability to easily display snippets of D code without jumping through hoops is a big plus. Trying to do syntax-highlighted D code in plain HTML (or any other web authoring system, for that matter) is an exercise in masochism. Re. syntax highlighting -- it looks like Pygments supports D. http://pygments.org/languages/
Re: Some feedback on the website.
On 2015-12-16 20:33, Andrei Alexandrescu wrote: What's the issue there? -- Andrei One problem is that it doesn't work for symbols arbitrary nested packages. That is, XREF only forks for "a.b.c" not "a.b.c.d". -- /Jacob Carlborg
Re: Some feedback on the website.
On 12/16/2015 5:50 AM, Andrei Alexandrescu wrote: On 12/16/15 3:00 AM, Jacob Carlborg wrote: On 2015-12-16 02:15, Andrei Alexandrescu wrote: It seems knowing ddoc is part of knowing D. -- Andrei I'm wondering how you can think it's perfectly acceptable to invent our own (crappy) language for documentation and at the same time loudly complain that SDLang is use for Dub config files and not a (more widely) standardized format. What standardized format was dominant in 2001? Thanks! -- Andrei To be fair, Ddoc came along later. But Jacob has a good point. I looked at 2 other systems in common use at the time - Javadoc, which I thought was aesthetically ugly, and Doxygen, which is aesthetically ugly and way overly complex, as well as being C++ specific. I wanted a system that looked good even without processing, i.e. it looked good in the the source code for basic use. Javadoc, Doxygen, both failed at that. Ddoc looks good in its basic use, is ridiculously simple, and has proven powerful enough to generate html, pdf, Latex, and Kindle ebook results from the same source. Ddoc has its shortcomings, too, like unittest. But it has achieved its goal, like unittest, which is to be so easy to use and built in that it it becomes completely natural to use it. I regard unittest and Ddoc as being extremely successful in that they have transformed D programming. (This is true of Javadoc as well, but not for Doxygen.) BTW, I've also used Ddoc to create several ebooks which I've published on Amazon, and for all the web sites I've created. It works very nicely for that. I don't think Doxygen nor Javadoc is useable in that way. It's kinda weird to run a history book through dmd to get an ebook out, but also kinda cool :-)
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 02:33:15PM -0500, Andrei Alexandrescu via Digitalmars-d wrote: > On 12/16/2015 02:12 PM, H. S. Teoh via Digitalmars-d wrote: > > the ongoing fiasco with XREF, LREF, whatever-REF and the > >associated relative/absolute URL nightmare > > What's the issue there? -- Andrei See: https://github.com/D-Programming-Language/phobos/pull/3852 https://github.com/D-Programming-Language/dlang.org/pull/1082 and their associated bugzilla tickets. T -- People say I'm arrogant, and I'm proud of it.
Re: Some feedback on the website.
On 2015-12-16 20:12, H. S. Teoh via Digitalmars-d wrote: Using ddoc for the website may be NIH, but the ability to easily display snippets of D code without jumping through hoops is a big plus. Trying to do syntax-highlighted D code in plain HTML (or any other web authoring system, for that matter) is an exercise in masochism. There's DScanner [1]. [1] https://github.com/Hackerpilot/Dscanner/#syntax-highlighting -- /Jacob Carlborg
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 19:44:13 UTC, Jacob Carlborg wrote: There's DScanner [1]. [1] https://github.com/Hackerpilot/Dscanner/#syntax-highlighting Aye, and post-processing html to clean up the edge cases, reuse headers, etc. is really easy to do - easier than running bleeding-edge dmd over a makefile that requires three repos...
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote: I'm not so sure... Like they say: "A father will never agree that his child is ugly!" :) John.
Re: Some feedback on the website.
On 12/16/2015 03:05 PM, Vladimir Panteleev wrote: DDoc itself is very simple. The problem is the endless number of macros we use on dlang.org. I see that as a blessing. E.g. all the different ways to link to something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, XREF, XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF, COREMODREF, OBJREF... If some of these are unnecessary, they can be easily fixed. There's no problem with breaking other people's code etc. Which would you eliminate? There is also no strong reason to use e.g. DIVCID instead of plain HTML. I agree. I added that more for completeness, easier typing, and so I can rely on editors showing the closing paren. Andrei
Re: Some feedback on the website.
On 12/16/2015 02:12 PM, H. S. Teoh via Digitalmars-d wrote: the ongoing fiasco with XREF, LREF, whatever-REF and the associated relative/absolute URL nightmare What's the issue there? -- Andrei
Re: Some feedback on the website.
On 12/15/2015 12:31 AM, Gary Willoughby wrote: We've all said time and time again if ddoc wasn't used for the entire site more people would help with it. Ddoc makes sense for the documentation but not everything else. I'm not so sure. There are lots of tools to develop websites. Let's say A, B, and C. If we picked "B", we most assuredly would have analogous threads here saying "I won't use anything but A" and "Everybody else uses C." > more people would help with it. I've heard all sorts of excuses for decades about why people won't chip in, and I know they are excuses because when the excuse is fixed, they still won't chip in. This excuse sounds the same as the rest. The thing is, if you know html, then you know Ddoc. Ddoc is just a stupidly simple text-substitution macro system a programmer should be able to learn in a few minutes. I do agree that the macros defined in the site's .ddoc files are ridiculously overlapping, redundant, etc. That all could use a redesign and an overhaul, but that isn't Ddoc's fault. It's just like any piece of crap code that has suffered from too many quick hacks layered on to it.
Re: Some feedback on the website.
On 12/16/2015 12:21 AM, ZombineDev wrote: Well DDoc may have it's disadvantages, but I'm certain that the documentation would have been far worse if it wasn't for it. No need to speculate :-) Before Ddoc, the Phobos documentation was horrific, probably the worst I'd ever seen. It was so bad it was unusual for there to be any correct documentation for a particular function, or even anything at all. Ddoc utterly transformed that, almost overnight. It's hard to underestimate the positive impact Ddoc has had on D documentation.
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 08:05:03PM +, Vladimir Panteleev via Digitalmars-d wrote: > On Tuesday, 15 December 2015 at 21:45:02 UTC, deadalnix wrote: > >On Tuesday, 15 December 2015 at 13:42:29 UTC, Andrei Alexandrescu wrote: > >>On 12/15/15 5:54 AM, tcak wrote: > >>>The harder it is made for people to contribute the system for > >>>fixations, the lesser changes are seen. > >> > >>I don't think we've had many contributions via the "Improve this > >>page" button. > >> > > > >I don't know how representative it is, but once in a while, i forgot > >all of this is in DDoc, I notice something, what to do a quick patch, > >and end up being reminded this is in DDoc and I have no idea how to > >fix the thing, because suddenly, what looked like a quick fix end up > >being learning a new macro language. > > DDoc itself is very simple. The problem is the endless number of > macros we use on dlang.org. E.g. all the different ways to link to > something: A, AHTTP, AHTTPS, ALOCAL, LINK, LINK2, WEB, LREF, XREF, > XREF2, CXREF, ECXREF, MYREF, FULL_XREF, STDMODREF, COREMODREF, > OBJREF... There is also no strong reason to use e.g. DIVCID instead of > plain HTML. Yeah, this is like spaghetti code written with C macros, where all macro names are in the same namespace, there is no scoping (everything is global), and undocumented so nobody knows what's already there or when to use what, and reinvents their own unhelpfully-named macros. Worse yet, sometimes people write their own implementations of existing macros with the same name so it's far from obvious which macro is actually in force when a particular part of the website is being processed -- this actually happens in the dlang.org repo: try grepping for XREF or LREF sometime, and see how many different definitions there are, for example. Or how many different macros there are for generating hyperlinks -- when should each one be used? Who knows. Read the code^Wmacro definitions to find out. Also, the lack of flexibility in number of macro arguments means you end up with LINK, LINK2, LINK3, etc., with no obvious indication what the difference is and where you should use which macro. It's like a worst-case scenario C library that has printf1, printf2, printf3, ..., instead of printf, fprintf, snprintf, etc., and people are expected to remember which numerical suffix does what. It's relatively easy to keep track of this in single-person projects -- Walter's using ddoc for creating ebooks, for example -- but in large collaborative projects these seemingly-minor issues lead to spaghetti macro-ni soup. The messy, inconsistent tangle that is the dlang.org macros constitute a high barrier-to-entry for would-be contributors. Mostly people just end up copy-n-pasting stuff without understanding what's really going on. We're at the ironical situation where ddoc macros need their usage documented -- by another ddoc page? :-P T -- There is no gravity. The earth sucks.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 20:59:46 UTC, JohnCK wrote: On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote: I'm not so sure... Like they say: "A father will never agree that his child is ugly!" :) John. Please don't go there. This is not about if ddoc is good or not, this is about making the website better. In that regard, I think it is fair to asses that people that know webdev don't know ddoc an vice versa. So using ddoc is probably not the best bet here.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 21:06:48 UTC, Andrei Alexandrescu wrote: On 12/16/2015 03:59 PM, JohnCK wrote: On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote: I'm not so sure... Like they say: "A father will never agree that his child is ugly!" To me it seems he's making a few good points. -- Andrei Ops, just to clarify, I
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 18:47:26 UTC, deadalnix wrote: On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote: What would you have done instead? Honestly for D code itself, ddoc does just fine, but for the website, plain html or some known template format like . This is what people know. Yep. Completely agree.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote: Also, ddoc always appeared to me like a big NIH syndrome. What would you have done instead? Honestly for D code itself, ddoc does just fine, but for the website, plain html or some known template format like . This is what people know.
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 06:47:26PM +, deadalnix via Digitalmars-d wrote: > On Wednesday, 16 December 2015 at 13:52:05 UTC, Andrei Alexandrescu wrote: > >>Also, ddoc always appeared to me like a big NIH syndrome. > > > >What would you have done instead? > > > > Honestly for D code itself, ddoc does just fine, but for the website, > plain html or some known template format like . This is what people > know. Using ddoc for the website may be NIH, but the ability to easily display snippets of D code without jumping through hoops is a big plus. Trying to do syntax-highlighted D code in plain HTML (or any other web authoring system, for that matter) is an exercise in masochism. Having said that, though, using ddoc for the website leads to other problems (e.g., the ongoing fiasco with XREF, LREF, whatever-REF and the associated relative/absolute URL nightmare that a proper web authoring system would have taken care of by default). T -- Жил-был король когда-то, при нём блоха жила.
Re: Some feedback on the website.
On 12/16/2015 05:32 PM, H. S. Teoh via Digitalmars-d wrote: While I'm on the fence about the value of ddoc as a website programming language (not as a documentation generator, where it is excellent IMO), I'm doubtful of the value of converting wholesale to a different format at this present time. That's a lot of effort and drain of our scant resources, with only unverifiable claims of increased participation from nebulous crowds who so far haven't showed any signs of interest in participating yet. It's something we could perhaps consider in the long term, but right now there are far more important things we need to work on. Like actually improving what docs are currently there. Very very very wise words. Thanks! -- Andrei
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 01:00:19PM -0800, Walter Bright via Digitalmars-d wrote: > On 12/16/2015 12:21 AM, ZombineDev wrote: > >Well DDoc may have it's disadvantages, but I'm certain that the > >documentation would have been far worse if it wasn't for it. > > No need to speculate :-) Before Ddoc, the Phobos documentation was > horrific, probably the worst I'd ever seen. It was so bad it was > unusual for there to be any correct documentation for a particular > function, or even anything at all. > > Ddoc utterly transformed that, almost overnight. It's hard to > underestimate the positive impact Ddoc has had on D documentation. I don't think anybody is questioning the value of ddoc as a *documentation generator*. The issue here is whether it has the same value as a *website programming language*. Very different things. T -- "640K ought to be enough" -- Bill G. (allegedly), 1984. "The Internet is not a primary goal for PC usage" -- Bill G., 1995. "Linux has no impact on Microsoft's strategy" -- Bill G., 1999.
Re: Some feedback on the website.
On 12/16/2015 7:32 AM, Jack Stouffer wrote: 3. "Who wants to spend hours and hours of work writing a DDoc to Markdown converter or manually convert all existing pages? Do we have any volunteers?" I can't even get consistent documentation of the parameters to a function: For example: http://dlang.org/phobos/std_parallelism.html#.Task What are 'fun' and 'Args' supposed to be? No example(s). http://dlang.org/phobos/std_functional.html Not a single appearance of 'Params:' or 'Returns:. Inconsistent use of 'Example:' and 'Examples:'. Many missing examples. Etc. There's plenty to be done to improve things that converting all the pages to another format will not help with.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 21:57:05 UTC, Walter Bright wrote: On 12/16/2015 7:32 AM, Jack Stouffer wrote: 3. "Who wants to spend hours and hours of work writing a DDoc to Markdown converter or manually convert all existing pages? Do we have any volunteers?" I can't even get consistent documentation of the parameters to a function: For example: http://dlang.org/phobos/std_parallelism.html#.Task What are 'fun' and 'Args' supposed to be? No example(s). http://dlang.org/phobos/std_functional.html Not a single appearance of 'Params:' or 'Returns:. Inconsistent use of 'Example:' and 'Examples:'. Many missing examples. Etc. There's plenty to be done to improve things that converting all the pages to another format will not help with. There's also weird stuff like this, with an outer template and a documented inner template function. http://dlang.org/phobos/std_parallelism.html#.TaskPool.amap.amap
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 10:00:50PM +, Meta via Digitalmars-d wrote:
> On Wednesday, 16 December 2015 at 21:57:05 UTC, Walter Bright wrote:
[...]
> >There's plenty to be done to improve things that converting all the
> >pages to another format will not help with.
While I'm on the fence about the value of ddoc as a website programming
language (not as a documentation generator, where it is excellent IMO),
I'm doubtful of the value of converting wholesale to a different format
at this present time. That's a lot of effort and drain of our scant
resources, with only unverifiable claims of increased participation from
nebulous crowds who so far haven't showed any signs of interest in
participating yet. It's something we could perhaps consider in the long
term, but right now there are far more important things we need to work
on. Like actually improving what docs are currently there.
> There's also weird stuff like this, with an outer template and a
> documented inner template function.
>
> http://dlang.org/phobos/std_parallelism.html#.TaskPool.amap.amap
This is a limitation of ddoc that needs to be fixed. Historically,
template functions used to be written like this:
template amap(Args...)
{
auto amap(Args args) {
implementation();
}
}
Then a shorthand was introduced (the so-called "eponymous template"
syntax), such that the above incantation could be abbreviated to:
auto amap(Args...)(Args args) {
implementation();
}
It would appear that ddoc came after eponymous templates became the
norm, so currently, ddoc only understands ddoc comments attached to the
latter syntax, while it fails to recognize that the former syntax is
actually equivalent. Several other functions in Phobos suffer from the
resulting formatting disparity, IIRC map(), and maybe reduce(), and one
or two others. It's rare enough that we don't encounter it very often,
but the functions affected happen to be ones that are likely to be
frequently used, so we really ought to fix this limitation in ddoc.
T
--
Valentine's Day: an occasion for florists to reach into the wallets of nominal
lovers in dire need of being reminded to profess their hypothetical love for
their long-forgotten.
Re: Some feedback on the website.
On 12/16/2015 04:09 PM, H. S. Teoh via Digitalmars-d wrote: Also, the lack of flexibility in number of macro arguments means you end up with LINK, LINK2, LINK3, etc., with no obvious indication what the difference is and where you should use which macro. (Well the obvious indication is the number innit :o).) A _simple_ way to handle arity might be worth adding to ddoc. Any ideas? Andrei
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 23:01:47 UTC, Walter Bright wrote: Exactly. We'll never get anywhere chasing people who say "I'll help only if you convert to my way of doing things." I've done enough of that in the past, and concluded they're just seeing how long you'll dance to their tune and have no real intention of ever helping - there will just be another excuse. It's funny how much "better" one's own ideas seem until one realizes that implementing them usually takes just as much effort as with someone else's idea, and work is almost always the limiting factor. On the subject of "one's own ideas", here's mine, FWIW: First, my background thoughts. We seem to have four main "sections" of the site: the forums (built on DFeed), the wiki (built on MediaWiki), the language docs (DDoc), and the "main" site (in DDoc/HTML). The first three are using technologies which were explicitly designed for what they do, and they work quite nicely. The only thing left is the "main" site (the download page, articles, etc.), which doesn't fit into the models of the first two technologies and is somewhat clumsy for some people to edit because it's built on more than just "common" Web standards. I can think of a couple of ideas for making the main page more palatable to Web developers. One is to make as much of it as possible in plain old static HTML. Stuff like the articles rarely changes, after all. Another idea is to use a Web application framework. There's a significant advantage there: we can have one master "layout" template, and almost any content we want (forums, DDoc-generated HTML, static HTML, and so on) can be rendered in that template with relatively minimal code. There are lots of frameworks that shouldn't be hard to use. I'm sure that someone has already suggested doing it in vibe.d, and that probably got shot down due to a technical issue or something, but it would be interesting from a PR standpoint.
Re: Some feedback on the website.
On 12/16/2015 3:43 PM, BLM768 wrote: One is to make as much of it as possible in plain old static HTML. I've done that before, a lot. Ddoc cut the work involved in that in half, and I mean in half. It also made it easy to change the look of a whole site, rather than being a mess of tedium. No way I'm going back to that.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 21:30:32 UTC, H. S. Teoh wrote: I don't think anybody is questioning the value of ddoc as a *documentation generator*. The issue here is whether it has the same value as a *website programming language*. Very different things. That I agree! JohnCK.
Re: Some feedback on the website.
On 12/16/2015 04:17 PM, deadalnix wrote: In that regard, I think it is fair to asses that people that know webdev don't know ddoc an vice versa. So using ddoc is probably not the best bet here. Yah, agreed (though I have to say it's not that fair to my tushy :o)). -- Andrei
Re: Some feedback on the website.
On 12/16/2015 06:29 PM, H. S. Teoh via Digitalmars-d wrote: Allow overloading by number of arguments, maybe? (This sounds suspiciously like a slippery slope, though...) That'll have trouble with $0 and $+. Or allow argument list slicing, D-style? Not sure if this would solve all the necessary cases. Overall I think a few additions to the macro engine could be very beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) to expand b if a is nonempty and c otherwise. Andrei
Re: Some feedback on the website.
On 12/16/2015 06:43 PM, BLM768 wrote: One is to make as much of it as possible in plain old static HTML. Stuff like the articles rarely changes, after all. But I dislike typing HTML. DDoc improves on that significantly. Another idea is to use a Web application framework. There's a significant advantage there: we can have one master "layout" template, and almost any content we want (forums, DDoc-generated HTML, static HTML, and so on) can be rendered in that template with relatively minimal code. Ironically Ddoc does exactly that, and quite nicely. Andrei
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 23:43:41 UTC, BLM768 wrote: [snip] ...and as I read some older posts, I see that mine is completely redundant. ;) Seriously, though, I'm willing to help prototype something. I've got time before the next semester starts.
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 03:04:51PM -0800, Walter Bright via Digitalmars-d wrote: > On 12/16/2015 12:59 PM, JohnCK wrote: > >On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote: > >>I'm not so sure... > > > >Like they say: "A father will never agree that his child is ugly!" > > > >:) > > I've pontificated before about design mistakes in D that I've made. I > also think that a lot of the dmd code I wrote is ugly crap. It would be interesting to hear what you think are design mistakes. And also, perhaps for the longer term, how you'd have done things differently if you could turn back time. :-) T -- Questions are the beginning of intelligence, but the fear of God is the beginning of wisdom.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 21:18:43 UTC, JohnCK wrote: On Wednesday, 16 December 2015 at 21:06:48 UTC, Andrei Alexandrescu wrote: On 12/16/2015 03:59 PM, JohnCK wrote: On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote: I'm not so sure... Like they say: "A father will never agree that his child is ugly!" To me it seems he's making a few good points. -- Andrei Ops, just to clarify, I Ops again, so just to clarify, I'm not saying the ddocs is that ugly, but let's face it, like others said it has some flaws or otherwise it wouldn't be so discussed every time. JohnCK.
Re: Some feedback on the website.
On Wednesday, 16 December 2015 at 21:17:43 UTC, deadalnix wrote: On Wednesday, 16 December 2015 at 20:59:46 UTC, JohnCK wrote: On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote: I'm not so sure... Like they say: "A father will never agree that his child is ugly!" :) John. Please don't go there... Dude just read my message above. Furthermore It was just a joke with Walter. JohnCK.
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 12:54:35PM -0800, Walter Bright via Digitalmars-d wrote: [...] > I do agree that the macros defined in the site's .ddoc files are > ridiculously overlapping, redundant, etc. That all could use a > redesign and an overhaul, but that isn't Ddoc's fault. It's just like > any piece of crap code that has suffered from too many quick > hacks layered on to it. I think you hit the nail on the head. The current dlang.org macros are a gigantic, inconsistent mess. I think some serious refactoring is in order here. T -- MACINTOSH: Most Applications Crash, If Not, The Operating System Hangs
Re: Some feedback on the website.
On 12/16/2015 2:32 PM, H. S. Teoh via Digitalmars-d wrote: I'm doubtful of the value of converting wholesale to a different format at this present time. That's a lot of effort and drain of our scant resources, with only unverifiable claims of increased participation from nebulous crowds who so far haven't showed any signs of interest in participating yet. Exactly. We'll never get anywhere chasing people who say "I'll help only if you convert to my way of doing things." I've done enough of that in the past, and concluded they're just seeing how long you'll dance to their tune and have no real intention of ever helping - there will just be another excuse.
Re: Some feedback on the website.
On 12/16/2015 12:59 PM, JohnCK wrote: On Wednesday, 16 December 2015 at 20:54:35 UTC, Walter Bright wrote: I'm not so sure... Like they say: "A father will never agree that his child is ugly!" :) I've pontificated before about design mistakes in D that I've made. I also think that a lot of the dmd code I wrote is ugly crap.
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 06:18:22PM -0500, Andrei Alexandrescu via Digitalmars-d wrote: > On 12/16/2015 04:09 PM, H. S. Teoh via Digitalmars-d wrote: > >Also, the lack of flexibility in number of macro arguments means you > >end up with LINK, LINK2, LINK3, etc., with no obvious indication what > >the difference is and where you should use which macro. > > (Well the obvious indication is the number innit :o).) But does the number mean the number of arguments, or the number of arguments past the mandatory arguments, or an incremental poor man's macro version number, or ...? I think some agreed-on common naming conventions for ddoc macros (perhaps just restricted to dlang.org / phobos / etc.) would go a long way in alleviating this issue. Right now it's just a random grab-bag where it's every man for himself and anything goes. > A _simple_ way to handle arity might be worth adding to ddoc. Any > ideas? [...] Allow overloading by number of arguments, maybe? (This sounds suspiciously like a slippery slope, though...) Or allow argument list slicing, D-style? Not sure if this would solve all the necessary cases. T -- Answer: Because it breaks the logical sequence of discussion. / Question: Why is top posting bad?
Re: Some feedback on the website.
On Wed, Dec 16, 2015 at 06:46:46PM -0500, Andrei Alexandrescu via Digitalmars-d wrote: > On 12/16/2015 06:29 PM, H. S. Teoh via Digitalmars-d wrote: > >Allow overloading by number of arguments, maybe? (This sounds > >suspiciously like a slippery slope, though...) > > That'll have trouble with $0 and $+. Not if we adopt the rule that if there are more arguments than the overload with the most number of arguments, then that overload is invoked. OTOH, I just realized that macro definitions don't indicate the number of parameters. Perhaps overloads should be defined with different syntax? E.g.: // old syntax: NON_OVERLOADABLE = blah $0 blah $1 blah $+ // new (additional) syntax: OVERLOADABLE(a) = blah $a blah OVERLOADABLE(a,b) = blah $a blah $b blah OVERLOADABLE(a,b,c) = blah $a blah $b blah $c blah Having parameter names will also help readability; currently, with $1, $2, $3 it's non-obvious what each parameter is supposed to be without reading the macro definition. The old parameterless syntax then can be reserved for truly variadic macros. > >Or allow argument list slicing, D-style? Not sure if this would > >solve all the necessary cases. > > Overall I think a few additions to the macro engine could be very > beneficial. E.g. while working on dconf.org I could use $(IF a, b, c) > to expand b if a is nonempty and c otherwise. [...] This will make ddoc Turing-complete, which may or may not be what you want. :-D (Although IIRC ddoc does impose a limit on recursion depth, so perhaps it won't *quite* be Turing complete just yet...) T -- I think the conspiracy theorists are out to get us...
Re: Some feedback on the website.
On 12/16/2015 6:34 PM, Adam D. Ruppe wrote: Well, it would complicate a bit as you add more to it (like changing the title on other pages...) but not a whole lot. You don't use it like I do. I use it to do abstractions, like sections, lists, etc., and then just change the markup to completely change the html generated.
Re: Some feedback on the website.
On 12/16/2015 07:04 PM, Adam D. Ruppe wrote: On Wednesday, 16 December 2015 at 23:55:34 UTC, Walter Bright wrote: I've done that before, a lot. Ddoc cut the work involved in that in half, and I mean in half. So does a simple `cat head.html body.html foot.html > output.html` loop. There's plenty of ways to achieve this. H... that's not so simple. -- Andrei
