Request to integrate the link to manual.md into the command palette via Printing: Manual

[Neohiro79]

Hey Peter, I finally got your nice smooth update :-)

I realised, that the original issue, having to "search" for "how to get the f* manual" of your extension got completely lost. However, I could find a link in your plugin description to this site:

https://github.com/PeterWone/vsc-print/blob/master/manual.md

While we know now that pressing F1 won't show up the help inside VSC at all - but the command palette - is it possible to make an integration of this specific "helpdesk-link" - or even better opening the .md-file itself inside VSC as tab when typing "Printing: Manual" into this command palette?

After Pressing F1 right now this command palette only shows Printing: Browse for stylesheets and Printing: Print (which triggers the print dialog now perfectly)

---

As a nice side-effect you could write an article someday :-) about how to properly integrate a helpfile into VSC extensions, which might help a lot VSC extension developers or users out there in the future - if there isn't any of this already implemented 'somewhere'.

---

You could even implement a specific "extension-helpdesk" icon if you have time to do so (like you did with the print-icon) in this topbar of VSC where ALL extension-developers could "push" their specific extension-helpfile.md into via a special API-call to your extension.

When clicking on that icon, you would see / be able to search for your specific "extension-name" by typing it in or choosing just like it is realised in the command palette right now - then opening this specific helpfile.md as tab ...

Just some thoughts, no bugs :-) ...

[PeterWone]

The biggest issue with presenting documentation via a palette command is nobody is expecting it so no-one would look for the manual that way until after they already read the manual, which somewhat defeats the purpose.

That said, it’s a damn fine idea to establish this as a convention. I’m going to give it some thought.

Here are some possibilities that come to me right off the cuff:

• Re-instate the CUA meaning for F1, and bind Shift+F1 or F4 to the command palette (neither are in use, I checked)
• Help can be HTML in a browser or markdown in the preview pane
• Could be on the web or local files
• To the extent that context can be determined, provide context sensitive help the way apps did in the golden era of Windows.
• With a clearly defined convention, extensions could contribute contexts and related topics and content

Remapping keys is easy, it doesn’t even require code, it’s just an entry in the contributions section of package.json, but some people won’t like it so it would have to be a setting defaulted to off.

Sent from Mailhttps://go.microsoft.com/fwlink/?LinkId=550986 for Windows 10

From: Neohiro79mailto:notifications@github.com Sent: Friday, 20 November 2020 4:27 PM To: PeterWone/vsc-printmailto:vsc-print@noreply.github.com Cc: Subscribedmailto:subscribed@noreply.github.com Subject: [PeterWone/vsc-print] Request to integrate the link to manual.md into the command palette via Printing: Manual (#70)

Hey Peter, I finally got your nice smooth update :-)

I realised, that the original issue, having to "search" for "how to get the f* manual" of your extension got completely lost. I could find a link in your plugin description to this site:

https://github.com/PeterWone/vsc-print/blob/master/manual.md

While we know now that pressing F1 won't show up the help inside VSC at all - but the command palette - is it possible to make an integration of this specific "helpdesk-link" - or even better opening the .md-file itself inside VSC as tab when typing "Printing: Manual" into this command palette?

After Pressing F1 right now this command palette only shows Printing: Browse for stylesheets and Printing: Print (which triggers the print dialog now perfectly)

As a good side-effect you could write an article someday about how to properly integrate a helpfile into VSC extensions, which might help a lot VSC extension developers or users out there in the future.

Heck, you could even implement a specific "extension-helpdesk" icon (like you did with the print-icon) in this topbar of VSC) where ALL extension-developers could "push" their specific extension-helpfile.md into via a special API-call to your extension.

When clicking on that icon, you would see or be able to search for you specific "extension-name" by typing it in or choosing just like in the command palette - and then opening this specific helpfile.md as tab ...

Just some thoughts, no bugs :-) ...

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHubhttps://github.com/PeterWone/vsc-print/issues/70, or unsubscribehttps://github.com/notifications/unsubscribe-auth/ABJ6QOELLKGFZAYUGIWJBOTSQYD4BANCNFSM4T4LP5HQ.

[Neohiro79]

In that case I might think it would work better with the icon, when "pressed" it just opens up my help and that's it.

The conventions they use are what they are - they just use them, and we have to deal with them.

I personally would've either tried to find "somewhere" the hint to the manual or description of the plugin than thinking about pressing F1. But if I do - I will immediately see the "command-palette" then "extension name: help" and can just 'go' there.

I'm completely fine with this - no remapping or whatsoever needed.

Just a new entry for the extension for this command-palette and an icon to press and see the results.

What can one potentially ask more ;-)

[PeterWone]

@Neohiro79 so what do you think? The options are

• Spawn a browser loading the rendered manual
• Open the markdown in a markdown preview pane

I think spawning a browser is more convenient for multi-monitor setups, but it's more complex to set up since I'd need a way to inhibit the inclusion of the script that shows the print dialog and closes the browser tab after printing.

Preview pane can be done quickly, browser version is in my opinion better but will have to wait for me to have time, probably months.

Note: I already did a proof of concept using the preview pane. Dismal docs on how, had to trawl the vscode source to find out how. It works nicely. Next step is context sensitivity but that needs a lot of thought.

[PeterWone]

Update your repo and run the extension in debug mode to try this in 0.8.4 which is not released on the marketplace.

If you want to install it as though it were packaged and published then

1. pull the code
2. open it in VS Code
3. run npm i in the vscode console
4. run gulp package in the vscode console

This will produce a VSIX that you can install using the ellipsis button in the extensions pane of vscode.

[Neohiro79]

So basically, if I download the whole repo as zipfile and unzip it into the extension folder of VSC it does not work from startup?

How do I enable this debug-mode again to make it work?

[PeterWone]

To get the repo

1. Get the clone URI onto your clipboard (just click the clipboard button next to it) or copy from here https://github.com/PeterWone/vsc-print.git
2. In VS Code press F1 and type CLONE
3. Press Enter to get this
4. Paste the URI https://github.com/PeterWone/vsc-print.git and press Enter
5. A file dialog will open, tell it where you want the repo
6. Open the repo in VS Code
7. Open the VS Code Terminal pane
8. Type npm i then press Enter

To build a VSIX

1. Get the repo
2. Load it in VS Code
3. Open the Terminal pane
4. Ensure gulp-cli is installed npm i gulp-cli -g
5. Type gulp package then press Enter

To run in debug mode

1. Get the repo
2. Load it in VS Code
3. Press F5

VS Code knows it's an extension from config files that are part of the project. From this it knows that if you try to run it then it must launch the extension host and suppress loading of installed extensions. This is how you run vNext without removing the release version.

[PeterWone]

Don't worry about the vulnerabilities. They apply in a web page in a browser, which this isn't.

[Neohiro79]

Thank you so much for these perfect desciptions!

It first didn't work as described, since I don't need to press enter after clone (else it wanted me to login to my git account, saying no repositories found since there aren't any yet)

It worked till the gulp-package at least:

The problem with gulp (maybe missing something - install something more here?)

[Neohiro79]

It worked! 👍

[PeterWone]

See updated instructions. You need the gulp-cli

npm i gulp-cli -g

[PeterWone]

Here's your chance to contribute to the codebase.

1. Fork the repo so you can check stuff into your own fork,
2. Clone your fork
3. Open the clone of your fork in vscode,
4. Add gulp-cli to the devDependencies section of package.json with

npm i gulp-cli --save-dev

5. Check it in locally
6. Push to your fork
7. Create a pull request
8. I will add it to the master repo and github will start marking your comments with CONTRIBUTOR

[Neohiro79]

This will produce a VSIX that you can install using the ellipsis button in the extensions pane of vscode.

I didn't see any of this ellipsis button you were talking about.

So I also tried F5.

So after F5 is pressed a new VSC window popps up, but when I open a file and press F1 there is no icon or helpfile opening up - do I need to be in a specific folder or have a specific file open to see the changes

Where do I find this ellipsis button?

[PeterWone]

Ellipsis is the name for the three-dots symbol

[Neohiro79]

[Neohiro79]

It's the wrong extension, your's isn't even in there.

[PeterWone]

The VSIX is generated in the project folder. Copy the path.

[Neohiro79]

Oh - ok. Worked! I've found and installed the VSIX file:

Now how do I see the changes?

[PeterWone]

I see you speak German. (Well I think it's German. I can't read it.)

Are you interested in maintaining the German UI translation?

I have no further time today but I can walk you through it. Basically you get the English file side by side in your editor and update the entries to add new ones with the German translation, and delete any that aren't in the English version.

That and the translations for the manual and the other docs.

[Neohiro79]

Yeah. You guessed right :-) Thanx to god I am also used to the english language - which I like much more.

Yeah, sure. If it's only one or some file(s) no problem.

But I need to figure out how this whole git-process of fetch, fork, push, pull, pull-request and whatever funny things works ...

[Neohiro79]

Do I need to add another command or can I close VSC without loosing this "VSIX" installation in VSC or whatever that is?

[PeterWone]

If you installed from a VSIX it's permanent, if you run in the extension host it isn't.

[Neohiro79]

Yeah, I did as you described - searched in the local repo and chose this ".vsix" container file.

I didn't pressed F5 beforehand and opened any other VSC instance if it is that what you mean.

[PeterWone]

A VSIX does the same as installing (or updating) from the marketplace.

For a given language the work items are

• Manual
• Change log
• Readme
• UI strings

The manual and readme don’t change much. The change log gets a new entry for each release which also appears in the readme (copy it) and as you know the extension is mature so there’s only a few per year.

[PeterWone]

Congratulations, you built and installed an OOB release (out of band) from a repository.

[Neohiro79]

:-) Yeah, I will look into it then send them to you once I've found them. I guess I first need to figure out how this clone and pull / request whatever shit works to send them to your repo.

[Neohiro79]

Congratulations, you built and installed an OOB release (out of band) from a repository.

Thanx to you perfect guided tour and descriptions! 👍

[PeterWone]

For someone fluent in both languages and equipped with the right keyboard for the target language it's a half hour job tops.

I will walk you through it some other time. I am way too busy for any more today. If you have skype we can screen share and get you set up. If you take on the German translation then the most complex parts of the setup only need doing once and then you make changes to the same clone on your computer and push to the same fork and creating a PR is the same every time.

The worst mistake you can make is messing up the JSON syntax and I don't need to read German to find and fix that.

You can even check it yourself using

gulp package

which will throw errors if you break something. It will even tell you if you missed one.

[Neohiro79]

Ok, sure. Just contact me for the skype thing the next days, we can stay in contact, since I don't know when I will have the time to go through it firsthand.

[Neohiro79]

With JSON I am familiar by the way, so there's nothing to worry about from that end, only Git and it's frankenstein-api is something I've tried to avoid to use till today ...

[PeterWone]

I'm sure you are familiar with JSON but it's easy when pasting updated content to accidentally lose a closing quote. Happens to me all the time patching the French version. I slap the English into Bing translate which unlike me always gets conjugation and number agreement right, plus it puts in all the accents which are a pain to type on a US English keyboard. Then I proofread the translation, laugh about stupid machines, fix it and copy/paste into the corresponding entry in the French file. It's convenient but slight mouse selection errors can easily clobber a closing quote or put one too many in.

Even though I am capable of manually rewriting the translation I usually do it by rewriting the English version to make it less ambiguous, because this is usually an improvement to both.

Often machine translators fail because they are unable to use a priori subject knowledge to narrow interpretation. Rewriting to remove the dependence on implicit context is always a good idea so I guess you could say I'm using a machine translator to do static analysis of natural language.

[PeterWone]

@Neohiro79 are you happy that this issue is dealt with and ready to close?

[Neohiro79]

@PeterWone if you talk about this very issue here to "open the manual" (which it does perfectly well now), yes, superb!

Ready to close :-)