scdoc: redesign method rendering #2948

nhthn · 2017-06-14T20:06:15Z

towards #2943. removes cluttersome gray backgrounds and horizontal lines, displays instance methods with a leading "." (except for binary operators) and classes with a leading "ClassName.".

again i can't post screenshots, just try it. to me it's a huge improvement :)

This commit redesigns the way methods are displayed in SCDoc. Cluttersome gray backgrounds and horizontal lines were removed, instance methods now display as ".add(...)" instead of "- add (...)", class methods now display as "SinOsc.ar(...)" instead of "* ar(...)".

This commit improves clarity in SCDoc's method rendering by removing the leading . for method names that contain a valid binary operator character.

This commit indents wrapped code in method rendering to help visually emphasize the method name.

telephon · 2017-06-15T08:22:18Z

SCClassLibrary/SCDoc/SCDocRenderer.sc

@@ -2,6 +2,7 @@
 HTML renderer
 */
 SCDocHTMLRenderer {
+	classvar <binaryOperatorCharacters = "!@%&*-+=|<>?/";


it might be good to make this a method of Symbol::isBinaryOperator. Then we have a central place to look this up.

telephon · 2017-06-15T08:23:35Z

SCClassLibrary/SCDoc/SCDocRenderer.sc

+					// "." to reduce confusion.
+					if(mname.asString.any(this.binaryOperatorCharacters.contains(_)), { "" }, { "." })
+				},
+				\genericMethod, { "" }


what is a generic method ?

no idea. see line 566

ok, seems like a method without known class. Well, not an issue.

mossheim · 2017-06-15T21:58:21Z

[ used to be images here, removed them since they're misleading ]

I like some of these changes, but others feel a little strange. No left margin makes it difficult to see the - or *. Extra vertical padding makes lists of unimplemented methods very spacious. And, that full-width red background for extensions makes less sense to me visually now...

~~These are from the Object helpfile btw~~

nhthn · 2017-06-15T22:19:12Z

that doesn't look the way it should. did you run make install and everything?

edit i think you gotta hit "refresh". the method names should be black and monospace.

mossheim · 2017-06-15T22:27:10Z

ah i was wondering if i did something wrong. nope, just copy-pasted into my existing files because I thought that would be enough. will try again later tonight

nhthn · 2017-06-15T22:28:35Z

you need to run SCDoc.parseAndRender(SCDoc.documents["Classes/String"]), etc. to force refresh a particular document. or SCDoc.renderAll if you don't mind waiting

mossheim · 2017-06-15T22:32:45Z

Damn that's nice. Still the same comment about full-width background highlighting though, for NOTEs and extensions notices. The other thing i notice is that now subheaders are roughly the same size as the monospace method names, so they don't really feel like heading text anymore

With the recent removal of gray backgrounds from methods in SCDoc, it makes sense to remove backgrounds from these as well. They are a bit easier to miss, but they're also not terribly important to users either.

nhthn · 2017-06-15T22:41:31Z

i think notes should stay highlighted, since they need to stand out. in fact, they stand out even more now with the removal of other backgrounds. you're right about extensions/superclass methods, i've removed their backgrounds.

i'll also fiddle around with the font sizes. i like the size of the method names, so i'll probably just make the other headers larger.

This helps visually distinguish ordinary h3's from methods.

telephon · 2017-06-16T07:49:00Z

This will be a very nice improvement – let us know when you are ready.

nhthn · 2017-06-16T18:03:55Z

it's done, unless anyone has feedback ofc.

telephon · 2017-06-16T18:28:48Z

I think we can still fine-tune if we get further feedback …

telephon · 2017-06-16T19:08:45Z

One thing could be improved is the amount of space that this section takes:

Maybe there is a simple way of compressing the information and functionality in such blocks?

nhthn · 2017-06-16T19:28:18Z

good idea, although that's probably best done in a separate PR

nuss · 2017-06-18T12:31:49Z

I am not really convinced about this change to the docs. First, it seems not to be 100% consistent: E. g. I have a class that only has class methods. In that case method names are still being rendered with a * in front, not ClassName.method. The * itself appears at the left edge of the document without any padding - see screenshot:

Also, adding the class name in front of the method name like ClassName.methodName for class methods while having no notion of the necessity of a receiver for instance methods (.someInstanceMethod) doesn't really clarify the difference between class and instance methods. I can't remember how I learned about that difference when reading the docs but once I found out it had immediately been clear to me what the difference between * method and - method was when looking at some help file.
Leaving out lines and backgrounds may be justified sometimes. However, I have the feeling they made sense somehow. E. g. there may be different sections with headlines within help files. Previously, while headlines were rendered without backgrounds method names (resp. method signatures) were rendered with a light grey background. Now this distinction is gone. Also, the font size in method names is bigger than the one in section headlines (compare above screenshot with the one below). I think that is somehow blurring the structure within a document.

gusano · 2017-06-18T13:18:24Z

@nuss can you post your file? I cannot reproduce it locally (linux)..

nuss · 2017-06-18T13:41:08Z

The issue about the class method names being rendered with a * instead of the class name in front seems to have disappeared magically... I could've sworn I did re-render the docs (probably I didn't...)

mossheim · 2017-06-18T15:01:39Z

@nuss I had the same experience too--I think the terminology spat out by the scdoc system is a little confusing re: "indexing" and "rendering"

nuss · 2017-06-18T15:12:25Z

@brianlheim @gusano yeah, that has confused me too in the beginning. But I got used to it and my usual workflow for rendering the docs is:

SCDoc.renderAll; // render all .schelp files to html
SCDoc.indexAllDocuments(true); // rebuild the docmap

... I thought I had done this but - maybe - I just didn't. Anyway, class methods are being displayed correctly now.

crucialfelix · 2017-06-18T19:26:37Z

Looks better already. I'm sure there is more fine tuning to do.

…

On Sun, Jun 18, 2017, 17:12 Stefan Nussbaumer ***@***.***> wrote: @brianlheim <https://github.com/brianlheim> @gusano <https://github.com/gusano> yeah, that has confused me too in the beginning. But I got used to it and my usual workflow for rendering the docs is: SCDoc.renderAll; // render all .schelp files to html SCDoc.indexAllDocuments(true); // rebuild the docmap ... I thought I had done this but - maybe - I just didn't. Anyway, class methods are being displayed correctly now. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#2948 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AANWcp8miihqrbHXAPcQQGtV4jq4D-Mqks5sFT5agaJpZM4N6YDl> .

telephon · 2017-06-18T19:29:40Z

#2227

(a little better)

Nathan Ho added 2 commits June 14, 2017 12:45

scdoc: remove leading . for binary operators

ab91d2a

This commit improves clarity in SCDoc's method rendering by removing the leading . for method names that contain a valid binary operator character.

nhthn added the comp: SCDoc scdoc syntax, parser, and renderer. for changes to schelp files, use "comp: help" label Jun 14, 2017

nhthn added this to the 3.9 milestone Jun 14, 2017

scdoc: add hanging indent to methods

dd56724

This commit indents wrapped code in method rendering to help visually emphasize the method name.

telephon reviewed Jun 15, 2017

View reviewed changes

nhthn mentioned this pull request Jun 15, 2017

Implement methods to classify sclang method names #2952

Closed

scdoc: unhighlight extension and superclass methods

577f278

With the recent removal of gray backgrounds from methods in SCDoc, it makes sense to remove backgrounds from these as well. They are a bit easier to miss, but they're also not terribly important to users either.

Nathan Ho added 2 commits June 15, 2017 15:43

scdoc: fix some bad indentation

1a86897

scdoc: increase font size of h3 headers

f987728

This helps visually distinguish ordinary h3's from methods.

telephon added the Work In Progress (WIP) - don't merge yet label Jun 16, 2017

telephon removed the Work In Progress (WIP) - don't merge yet label Jun 16, 2017

telephon merged commit a372bae into supercollider:master Jun 17, 2017

nhthn deleted the topic/scdoc-methods branch August 12, 2017 21:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

scdoc: redesign method rendering #2948

scdoc: redesign method rendering #2948

nhthn commented Jun 14, 2017 •

edited

Loading

telephon Jun 15, 2017

telephon Jun 15, 2017

nhthn Jun 15, 2017

telephon Jun 15, 2017

mossheim commented Jun 15, 2017 •

edited

Loading

nhthn commented Jun 15, 2017 •

edited

Loading

mossheim commented Jun 15, 2017

nhthn commented Jun 15, 2017

mossheim commented Jun 15, 2017

nhthn commented Jun 15, 2017

telephon commented Jun 16, 2017

nhthn commented Jun 16, 2017

telephon commented Jun 16, 2017

telephon commented Jun 16, 2017

nhthn commented Jun 16, 2017

nuss commented Jun 18, 2017

gusano commented Jun 18, 2017

nuss commented Jun 18, 2017

mossheim commented Jun 18, 2017

nuss commented Jun 18, 2017

crucialfelix commented Jun 18, 2017 via email

telephon commented Jun 18, 2017

scdoc: redesign method rendering #2948

scdoc: redesign method rendering #2948

Conversation

nhthn commented Jun 14, 2017 • edited Loading

telephon Jun 15, 2017

Choose a reason for hiding this comment

telephon Jun 15, 2017

Choose a reason for hiding this comment

nhthn Jun 15, 2017

Choose a reason for hiding this comment

telephon Jun 15, 2017

Choose a reason for hiding this comment

mossheim commented Jun 15, 2017 • edited Loading

nhthn commented Jun 15, 2017 • edited Loading

mossheim commented Jun 15, 2017

nhthn commented Jun 15, 2017

mossheim commented Jun 15, 2017

nhthn commented Jun 15, 2017

telephon commented Jun 16, 2017

nhthn commented Jun 16, 2017

telephon commented Jun 16, 2017

telephon commented Jun 16, 2017

nhthn commented Jun 16, 2017

nuss commented Jun 18, 2017

gusano commented Jun 18, 2017

nuss commented Jun 18, 2017

mossheim commented Jun 18, 2017

nuss commented Jun 18, 2017

crucialfelix commented Jun 18, 2017 via email

telephon commented Jun 18, 2017

nhthn commented Jun 14, 2017 •

edited

Loading

mossheim commented Jun 15, 2017 •

edited

Loading

nhthn commented Jun 15, 2017 •

edited

Loading