improve key/mouse ref page

[Brynn]

Hi Friends,
I find the Content section of the Key/Mouse Reference page is very difficult to use. It uses dots and | to separate the links, which just wrap around in a column that's barely 2 inches wide on my screen. It's only organized from beginning to end.

I think it would be much more useful for that section to be organized in an outline format, that echoes how the shortcuts are organized. For example, and here, using dots to make indents.

Tools
Dialogs
...Open
...Toggle visibility
...Within a dialog
Controls bar
...Access
...Navigate
...Change values
Canvas
...Zoom
etc.

Yes, it would make it much longer, but still not nearly as long as the whole page. It might actually allow it to be narrower, although I'm not sure if that would be a benefit or not.

I'm tempted to also suggest the Content section should be on the left and shortcuts covering the middle to right side of the page. But maybe there's some reason for it to be backwards like that.

I'd be glad to make the edits myself, on that page, except that I'm told it's not made like a regular webpage. I don't know anything about scripting, but the offer still stands, if it's a possibility to edit with the django editor.

Anyway, thank you very much :-)

[jazzynico (jazzynico)]

One possibility to improve readability would be to add the following styles to the website's CSS:

a.toc-group {font-size: 0.9em}
a.toc-section {font-weight: bold;}

Another solution could be to use <ul> and <li> elements to organize the TOC, instead of the current list of <a> elements (as suggested by Brynn). But it would be far less compact, and I'm not sure it's a real improvement for such a long TOC. Note that it would affect the standalone version of the K&M files (the ones in the doc/ folder of the Inkscape installation).

[jazzynico (jazzynico)]

Also, the only thing that can be changed in the inkscape-docs project is the HTML structure of the file. Everything else depends on the webserver's CSS.

I'll try to attach a modified version (with <ul>s and <li>s) later this week.

[jazzynico (jazzynico)]

New test file attached (with <ul> and <li> formatted TOC).
Please test.

[Brynn (brynn4inks-deactivatedaccount)]

Wow - looks great!

I notice the toc is on top of the shortcuts, instead of beside. I guess that's just for this test file?

How thorough of a test do you need? If it needs to be very thorough, I would probably need an English version. Based on testing 8 or 10 links, it seems to be fine. That's just comparing a sequence of letters though. I can't tell if the shortcuts actually match with the category. (Actually I can't really determine which shortcuts are which.)

Thanks for your very quick work!

[Hachmann (marenhachmann)]

Hi Nicolas,

@Brynn: you do not need to test the links in the toc. I think Nicolas would like us to check what it looks like with the web site's css.

I do have the css files, but I don't have the docs deploy script (or at least I don't know how to use it) on my dev server.

So I can only do what a good Firefox user can do, and download the old keys+mouse reference html, then insert the new one into the file. I must have messed up the divs somehow - the beginning of the page is alright, though. Couldn't find the error, and don't have a lot of time now. See attachment.

It doesn't seem to work as a django cms snippet...: http://staging.inkscape.org/de/keytest/

I think the TOC is much too long now, just as you hinted at, Nicolas :/

[Hachmann (marenhachmann)]

(@Brynn: to see what it looks like, save the file to your computer and open with Firefox. It will load the css from the internet, from the Inkscape web server.)

[Hachmann (marenhachmann)]

Maybe it would work with just the outer list items, and then the items of the inner lists separated by | as before?

[Hachmann (marenhachmann)]

Perhaps like this (attachment)?...

[Brynn (brynn4inks-deactivatedaccount)]

"@Brynn: you do not need to test the links in the toc. I think Nicolas would like us to check what it looks like with the web site's css."

Oh ok. Sorry for misunderstanding.

"(@Brynn: to see what it looks like, save the file to your computer and open with Firefox. It will load the css from the internet, from the Inkscape web server."

Well, I had originally opened it with Ff, directly from the link above. I don't have a local/dev website/server (for Inkscape).

But I can see the page you made on staging.

I don't think it would be too long, if it was *beside* the rest of the content, like it is on the current K/M Ref page (instead of on top of it). You'll have to explain to me why that can't happen, because that must be some technical reason that I'm missing.

If it's because it's wider this way, that doesn't have to be a reason not to have them side by side. The toc area can still be the same width as it is now (or even a 10 or 20 pixels wider). If some longer lines need to wrap, that's ok, because the basic structure would be in place, to help people find what they need.

Otherwise, I don't understand why it's on top instead of beside.

[Hachmann (marenhachmann)]

@Brynn:

You don't need a dev server to try this out.

It's not on the side (yet) though. We'd have to make it broader than the current one, I agree.
The styling for that wider 'aside' is not available on the Inkscape webserver.
Martin would have to add it for us, but we need to make one first :)

The page on staging did not work as I thought, so forget about that one, please :)

Just try it out as I described, and comment again :)
I will try how it looks with a float on the right, maybe tomorrow.

[jazzynico (jazzynico)]

To ease testing (and because we will need it for the standalone version of the reference anyways), I'm going to change the styles in the CSS file linked to the K&M page. That way you won't need to install it on the server to test.

[Brynn (brynn4inks-deactivatedaccount)]

There's something I'm missing about this. The current K/M page has it beside. And the current page is on the website. Can't the text in that 'beside' section be rearranged into lists or outline format?

However, the only reason I'm concerned about that, is to answer potential complaints that this makes the page too long. It'already a huge long page anyway. And this makes it only about 10% longer (by counting PageDowns). (49 vs 54)

Even so, the page is incredibly more useful this way. We don't need to scan the whole page, to find the section we want anymore. We can use that toc area, and not have to scroll around at all. So in that sense, it makes the page (effectively) much, much shorter, by removing the need to scan the whole page to find something.

[Brynn (brynn4inks-deactivatedaccount)]

correction -- 49 vs 52

[jazzynico (jazzynico)]

New CSS file, with left floating TOC.
To test it, Install the CSS in the same folder as the HTML file and open the HTML file in your favorite browser.
The changes only affect the local CSS for the standalone Keys and mouse reference. If accepted, it will be needed to backport them to the website and update all the K&M HTML files to reflect the new TOC structure.

[jazzynico (jazzynico)]

@Brynn - Could you please test the keys.en.html file in the doc/ folder of your Inkscape installation?
The style is not the same as for the website, and I'd like to know your opinion on it.

[jazzynico (jazzynico)]

Screenshots of the 3 different versions of the K&M.

[Hachmann (marenhachmann)]

@Nico - Brynn does still not have a dev server. She's *editing* the website and helping with decision-making and finding bugs and she's also poking Martin and me so we get things done, but she's not developing it. I'm also only barely helping with development, Martin is doing the biggest part of the work alone.

I will try making a docs directory next week when I get back from our yearly OpenSource/Linux event. No time for this now :/

From your screenshots, I think the new standalone version is closest to what Brynn would like to see. We can make something similar for the website.

[Hachmann (marenhachmann)]

Didn't see #11 before writing, Nicolas. Sorry! That's okay, too, I only hope the server actually serve that css file...

[Brynn (brynn4inks-deactivatedaccount)]

Yes, the new standalone version in message #18 looks awesome!

[Hachmann (marenhachmann)]

Okay, so I've tried the deploy-docs script we have, for testing your pages locally, Nicolas.
Unfortunately, it doesn't work, there's a file missing in our repo that seems to contain a bunch of environment variables.
I've asked Martin for help, and he promised to take a look - but he's busy giving his talk right now.

Sorry for the delay :/

[Hachmann (marenhachmann)]

With the next CSS, the toc (in the currently available page) is too wide (40% instead of 25%) :/

Nicolas, can you point me to the files you'd like me to test now?

[jazzynico (jazzynico)]

Maren, the CSS attached comment #16 is the one I used to generate the new standalone version. It's not the one used on the website, and applies to the standalone files only.
I'm now waiting for comments on the screenshots before generating new K&M files (online and standalone) with the changed TOC structure. Then, you or Martin will need to modify the website's TOC if you want the online version of the files to look like the standalone version.

[Hachmann (marenhachmann)]

Tbh, I think it's maybe better we make that toc independent of the website's css, or you (or Martin, or me) will always have to look and check if things are still looking right - this is probably not a lot of fun for either of us.

The CSS changes from the live version to my trunk version demonstrate the issue... (the middle section overlays the toc of the current live version, for example - it's unreadable...)

I'm sorry I've suggested that to you, it wasn't a good idea. I thought that using classes that exist would make it easier and more consistent, but instead this would only generate more issues... :(

I really feel bad about this... :/

Brynn likes it (#18), I'm okay with it, too. If you could include the css (only for positioning, background color, the vertical lines, and the key-boxes, and probably best with some prefixes for the classes or wrapping that prevents our main css taking over), then I'll check if it works and we'll be done...

[jazzynico (jazzynico)]

Change applied rev. 527.
New K&M HTML files updated (and keys.css added) in inkscape-docs-export-website rev. 13.
The new files classes now use a specific kmr prefix so that there's no problem with the website's CSS.

[su_v (suv-lp)]

On 2015-12-16 09:54 (+0100), jazzynico wrote:
> Change applied rev. 527.
> New K&M HTML files updated (and keys.css added) in inkscape-docs-export-website rev. 13.
> The new files classes now use a specific kmr prefix so that there's no problem with the website's CSS.
>
> ** Changed in: inkscape-docs
> Status: In Progress => Fix Committed
>

The reference as currently displayed on the site [1] seems to have lost
a lot of formatting (I find it hard to differ what is the shortcut, the
command, and any additional comments explaining details of the specific
shortcut). Any chance the old styling can be restored?

[1] https://inkscape.org/en/doc/keys091.html

[jazzynico (jazzynico)]

@Martin, could you please replace the website's CSS file for the K&M reference with the one exported in the inkscape-docs-export-website repo (see http://bazaar.launchpad.net/~inkscape.dev/inkscape-docs-export-website/trunk/revision/13)? Or modify the way the website works to use that keys.css file directly?

Thanks!

[Hachmann (marenhachmann)]

There's also a duplicate page title on the page suv linked to (in German, too, didn't check other languages), not sure where that comes from...

Is there a <h1> tag inside the reference html?

I seem to remember it only needs a title, which will then be taken as heading.

[jazzynico (jazzynico)]

Yes, there's a h1 in a div. The only thing that changed is that div's class attribute value changed from "header" to "kmr-header". But in that specific case, I think we could revert to the old value.

[Hachmann (marenhachmann)]

Just in case it helps:

The current website has a css file called docs.css (https://inkscape.global.ssl.fastly.net/static/css/docs.css), which contains some older contents of the file that is /tutorials/tutorial-html.css in jazzynico's docs directory.

The stylesheet linked in the head of the tutorials html files does not end up in the final page's html.
The stylesheet linked in the body of the key reference html files ends up in the html, but it cannot be found.
docs.css is loaded for every document in the /doc/ 'directory'.

Would it make sense to unify the new keys.css and the tutorial-html.css to have at least only one extra file first, before Martin updates that file?

[Hachmann (marenhachmann)]

The page still looks very bad - we should fix its CSS rather sooner than later.

I've played with inserting it into the docs.css file in my browser, and the inserted current keys.css is messing with the body font-style and other things.

Could you fix the css / the docs contents so that it cannot interfere with the site-wide CSS, jazzynico?
This concerns body, headings, table and img tags.

[jazzynico (jazzynico)]

Thanks for your tests Maren!

Just fixed in the docs (rev. 532) and the export-website (rev. 15) repos.
Now body, headings, table and img elements use a kmr class.
To fix the h1 issue (comments #29 and #30), I've also reverted the heading class to its original value.

[Hachmann (marenhachmann)]

Thanks, Nicolas, works and looks nice :)

Nitpicking:

- The main heading is still duplicated - probably because the title is already used as heading. If you remove the h1, jazzynico, I think it will look correct.

Thoughts:
- If we now copy the contents of keys.css into docs.css (hopefully it won't interfere with the tutorials' CSS? Didn't test.), then there would be only a single file to replace manually on the server.
- The link to the not-found keys.css file should probably be removed, if we go that way. But we need Martin's feedback for this.

@Martin: would you do that when the single file version is ready or should I ask eternal tyro?
Or would you make it possible to automatically fetch *.css files from Nico's directory and copy them into static, so the docs can be edited independently without you/whoever having to intervene manually?
Not sure how this plays with only-loading-docs-css-for-docs-pages... Maybe a prefix could work?
Please tell us your preference, so the page can be fixed. It looks *really* awful currently.

[Martin Owens (doctormo)]

;-) there's not a single link in this bug report.

I've just had a look, there's no reason why css files can't be packages with the docs directory that gets deployed automatically. ET could be brought in to see if it works, but the idea is to make sure this kind of thing is hands off.

[Hachmann (marenhachmann)]

? There are a few links in the comments - not sure what you mean here, Martin.
They're scattered a bit, though...

So, what do we need to do next? (and who will need to do it?)

For example, how should the css files be linked? They can either be pulled in by the documents themselves, or they are just automagically 'applied' to everything in the docs directory.
Currently it works the second way, but the first way is in the docs...

https://inkscape.global.ssl.fastly.net/static/css/docs.css
http://bazaar.launchpad.net/~inkscape.dev/inkscape-docs-export-website/trunk/
https://inkscape.org/en/doc/keys091.html

[Hachmann (marenhachmann)]

@doctormo:

I've tried fixing this, but the server just doesn't serve the copied static files.

When you have time, could you take a look at the attached patch?

(copies all css files into css static directory when the docs are updated, then adds them into the template)

If we don't copy the files, we'd need to edit the redirects file, AFAIU (where we don't have access and where I don't understand the syntax...)

What I don't like about my current solution is that it traverses the directories every time the page is accessed...
The deploy-docs script could create a txt file instead and it could be included into the template (but first I'd like to know if the whole idea is nonsense).

[Hachmann (marenhachmann)]

Oh, and it's probably bettter to copy the docs css into a seperate subdirectory, so it can't overwrite the main website's css...

[Martin Owens (doctormo)]

Maren,

The patch is fairly good, but I would do this:

 - Create an app.py file and generate the list of css files at app initialisation time. That way it's only done once per load.
 - We can add the docs static dir into the inkscape/settings.py static dirs so that collect static picks them all up, this would allow collectstatic to do the work of copying and keeping up to date.
  * But having said that, it might take a few trys and failures to get the right setting for the docs directories.

thoughts?

[Hachmann (marenhachmann)]

Thank you for taking the time to look and help, Martin!

Questions:

- When is 'app initialisation time'?
The css file list should be generated when the deploy-docs script is run, to take into account any new files Nicolas may have created, right?
(I'm currently assuming that apps are initialized at server start, so not so very often - could lead to CSS and html to not match)

- How often is collect-static run on the web server? Should it also be run when an updated branch is pulled, so we don't have a CSS and a docs html that don't fit to each other? (thanks for the hint with the static in the settings... I'll look that up.)

- Is there a way to prevent Nicolas from accidentally overwriting the main website CSS (just think what would happen if he chose to create a 'main.css') when collect-static copies the files? Mmmh... yes. We could just add a prefix.

(and what would be a good place to save the css list file? data/media/doc?)

[Martin Owens (doctormo)]

 - App initialisation is done on webserver load. We touch data/wsgi.conf to re-initialise, you can see the end of the deploy update script for an example. We can do the touch on docs update.

 - Collect static is currently on manual, when deploy update is run which is currently not automatic.

[Martin Owens (doctormo)]

What's the list of css files and is there a call for such an automatic system?

[Hachmann (marenhachmann)]

(I'd find it useful, because that would make jazzynico independent of our reaction times, and would not require him to make any immediate changes - so the reason is of purely organizational nature... Knowing that each of us doesn't always have time when the other does.)

[Hachmann (marenhachmann)]

Martin, I've been working under the assumption that this comment of yours was the goal:

See also your comment https://bugs.launchpad.net/inkscape-web/+bug/1492650/comments/35

[Martin Owens (doctormo)]

Yes, it's the ideal situation. But we must be careful to walk the line between introducing highly complex machinery to cope with adding the css needed.

So I think making collect static do the right thing should be the goal.

[Hachmann (marenhachmann)]

@Brynn: would you take a look at https://inkscape.org/doc/keys091.html and tell us if that's better now?

@jazzynico: I've (temporarily) fixed this now by just copying the keys and mouse css into the docs.css file in inkscape-web.

The duplicate heading is hidden by display:none, and can be removed in the original file. Inkscape-web takes the heading info from the page's title.

You can also remove all references to any CSS files in your files, then the page will load faster. The docs CSS file is automatically 'attached' to any page in the /docs directory.

Martin is working on some design toolbar, that, some day, might allow you to edit the CSS online(? or locally?) and then to commit the changes to the repo with a button-click.

[Brynn (brynn4inks-deactivatedaccount)]

Omgosh! 100% improvement!! I see that you and jazzynico have worked very hard on this. And not just me, but all Inkscape users will appreciate it very much.

The only thing I see that possibly could be improved (very minor) is the background color block for each section. I like that very much! But the colors somehow need to be....sort of "equalized"....well I can't think of the right words.

It looks like you tried very hard not to use the same color twice. But I think it might help the general appearance if you had a set of maybe 5 or 6 colors, and just use them in the same order, repeating, top to bottom (e.g. - red, green, blue, yellow, purple, red, green, blue, yellow, purple, etc.).

But the main thing is they need to have the same or at least similar transparency or lightness, no matter if the colors repeat or not. For a quick fix, it's the Canvas and Palette sections that seem out of place. Also Pencil, and possibly Star and Spiral, maybe Zoom . Some of the colors are so light I can barely notice them, but then some don't seem to be transparent at all. I know they probably aren't really transparent, but the lightness needs to be in the same range as all the other blocks.

Hhmm, should I make a screenshot? Possibly your screen displays differently than mine?

Btw, what "RFE"?

[Hachmann (marenhachmann)]

Request for Enhancement (learnt that from V ;-) )

[Hachmann (marenhachmann)]

(already asked for a change: https://bugs.launchpad.net/inkscape-docs/+bug/1486403)

[Jabiertxof (jabiertxof)]

Looks so good!

[Jabiertxof (jabiertxof)]

To improve maybe a scroll to top button, and a fixed position sort section menu for a 12

[jazzynico (jazzynico)]

The report is so long I don't remember what's left to do... As far as I can tell, the website issues (duplicate title, style not applied) are fixed, but I see there some other request. Could you please confirm what's needed now (or a bit later, maybe...).
Thanks!

[Hachmann (marenhachmann)]

Summary:

- Jabier was asking for a scroll-to-top button (and I do not understand the second half of #51)

- Brynn was asking for the background colors which are different between the blocks to be more similar in lightness, and to just alternate regularly. Examples given: Canvas and Palette sections seem out of place. Also Pencil, and possibly Star and Spiral, maybe Zoom

- The duplicate heading can be removed, it is taken from the title of the page.

- The links to any stylesheets can be removed, they are loaded automatically for the docs pages, and the links do not work anyway.

[Hachmann (marenhachmann)]

(none of these are urgent, we can also separate them out into a new report, if you prefer, jazzynico.)

[Brynn (brynn4inks-deactivatedaccount)]

The issues I originally mentioned are fixed very, very well! The only minor issue I see are the multi-colored backgrounds. Maybe better to rotate through the same 3 colors, or even just alternate 2 colors.

Thanks for everyone's hard and good work!

[Hachmann (marenhachmann)]

@Brynn: I've separated out the color issue, it's here now:
https://bugs.launchpad.net/inkscape-docs/+bug/1751159

[Hachmann (marenhachmann)]

@Jabier: I've also separated out the scroll to top button to its own report:
https://bugs.launchpad.net/inkscape-docs/+bug/1751160

[Hachmann (marenhachmann)]

As the rest of this report is implemented, I will close as Fix Released.