Ddoc: add class "simple-cheatsheet" #4397
Conversation
So that DDOX can choose not to display them.
.simple-cheatsheet tables play the same role as the listings that DDOX
generates. Having them both, and right after another, is confusing for
the reader, and doesn't add any value.
There are similar tables in
* std.experimental.ndslice.{iteration,selection},
* std.format,
* std.net.curl, and
* std.range.primitives,
but they contain additional information or are embedded in text. So their
presence should be less confusing.
|
Companion pull request for dlang.org: dlang/dlang.org#1323 |
|
How about a |
Sure. Added it in the dlang.org PR (dlang/dlang.org#1323), and here. I've called it |
|
Hmm, on second thought I'm not sure about this. I only realized this when looking at the final diff: the cheatsheets include minimal examples that provide a much better overview of the functions than the first paragraph of their DDoc. Keeping in mind that some day we might throw away the Phobos DDoc documentation and use DDox exclusively, it would mean throwing away the cheat sheets completely. Perhaps we should instead go in the other direction (hide the automatically-generated DDoc overview in the modules with cheat sheets)? That has its disadvantages too, e.g. forgetting to update the cheat sheet would mean that a symbol is not reachable via HTML links. |
My thoughts exactly. We're pretty bad at keeping things in sync manually. Also, the other way seems to be more difficult. My idea would be to define a macro |
|
Here's an experience report from a new user who didn't like the cheat cheet for std.algorithm.comparison: |
|
FWIW I disagree very strongly with that assessment. Perhaps longer English descriptions are more useful for people new to programming, but as you acquire experience across multiple programming languages, reading the documentation becomes more of a task of "finding the name of the function which I already know what it does". This is also the use case for people who already are familiar with Phobos' repertoire, but just don't remember the exact names for all functions. Having small examples is a much simpler way to confirm that the function does what you think it does, and removes the ambiguities of English phrasing or the need to parse English at all. |
Makes sense, but the DDOX listing may need more meat to be useful. I've been toying with the idea of changing the actual summaries of the functions to something more similar to the cheat sheet snippet. I.e., make the summary one sentence + one small example. The more complete description would follow, and then the rest as usual. That would eliminate the schism between cheat sheet and generated listing, but is it |
|
It's one solution. IIRC Sönke suggested more options in another thread. |
Yeah, over here: http://forum.dlang.org/post/niv2tl$2lqb$1@digitalmars.com. He suggests a special section or macro that DDOX would recognize and extract for the listing. He also mentions the problem: Another instance of duplication, because Ddoc wouldn't be able to build the cheat sheet that way. |
There was a problem hiding this comment.
Perhaps we should instead go in the other direction (hide the automatically-generated DDoc overview in the modules with cheat sheets)? That has its disadvantages too, e.g. forgetting to update the cheat sheet would mean that a symbol is not reachable via HTML links.
I also think that hiding the automatically-generated DDoc overview is the way to go.
@aG0aep6G are you still interested in pushing SIMPLE_CHEATSHEET?
Moreover, I think I think the table looks nicer without "Cheat Sheet" heading, but that could be easily adjusted at dlang.org:
Uhh, no. I had pretty much forgotten about this. If anyone decides that this PR here is the way to go, I'm up for fixing any issues it might have. But I don't care either way. If you want to go the other direction, by all means, go ahead. |
Hmm when I look at http://dlang.org/library/std/range.html, it still looks ugly due to the duplicated information. If there's an easy way to disable the listing with Ddox when a cheatsheet macro is present, I would say we go for it (we have to maintain the cheatsheets anyways).
Same here. I am going to make the decision easier for you as I am closing this PR - it's full of merge conflicts and submitting a new PR wouldn't be an overhead and would highly increase the chances of it being merged. |
You should probably revert dlang/dlang.org#1323 as it doesn't make sense without the PR here. |
|
You might actually just want to change the cheatsheet to embrace the idea of duplicated information, like caption it "Most common functions organized by category" (well, maybe not literally say that but word it somehow) then at the end be like "Complete listing follows". So yes, it duplicates in some sense, but it also reorganizes and prioritizes the information in the table. In ddoc, the complete listing is the all on one page stuff, and in ddox it is a more detailed navigation, but still shows all functions alphabetized rather than categorized/prioritized by hand. I mean, as it is, the cheatsheets don't show everything.... and indeed, I don't think they should, it is a "cheatsheet", not a "textbook"! |
So that DDOX can choose not to display them.
.simple-cheatsheet tables play the same role as the listings that DDOX
generates. Having them both, and right after another, is confusing for
the reader, and doesn't add any value.
There are similar tables in
but they contain additional information or are embedded in text. So their
presence should be less confusing.