Text/Code highlight with jsDoc - jsdoc

jsDoc seems to support most of the MD syntax, but when it comes to highlighting a single reserved word or text, I cannot find a usable tag for that.
In the MD syntax I can use `word`, which would set a grey background and a different font, so you can see it clearly, same as on StackOverflow - word.
In jsDoc, whether I use `word` or <code>word</code>, the effect is just setting italic style to the word, which cannot be clearly seen as a reserved word.
Is there any syntax in jsDoc to clearly highlight a word or a text string, like `some text` in MD, to look like some text?
Alternatively, is there a way to customize it - provide my own CSS for a standard MD tag?

JSDoc documentation seems to be using <code> tag, and it highlights the text using a grey background like you want by setting it on the code tag properties defined on the usejavadoc.css file:
From http://usejsdoc.org/tags-name.html:
There is a guide on how to edit or create your own JSDoc template, with a section on how to override the default template layout file:
http://usejsdoc.org/about-configuring-default-template.html#overriding-the-default-template-s-layout-file
But for something as simple as this, you don't even have to go that far. Just edit the css fragment, before or after generation, and set the background-color you want for the code tag. You may do it before generation by editing this line and setting the background color you want:
https://github.com/jsdoc3/jsdoc/blob/5a58bdf5a551844f12b46be6436aefd3c41e0393/templates/default/static/styles/jsdoc-default.css#L257
Or, if that doesn't work, overriding the property by adding
code {
background-color: #DEDEDE !important;
}
to the file.
As an alternative you can use a framework like qooxdoo to generate your documentation using JSDoc-like comments. According to their API reference you may use <pre class="javascript"> for inline javascript syntax code highlighting, and it looks pretty nice: http://manual.qooxdoo.org/3.0/pages/development/api_jsdoc_ref.html#html

Related

How to align items to right side in MarkdownString of VSCode

While making VSCode Extension I have a requirement to show decorations on a file. Then while you hover over that decoration you can see the default hover with some information you want to show. I am using the following code to create the hover using MarkDownString for VSCode. Even after using "float:right;" in the span the view comment section won't move to the extreme right of the hover. It would just stay in the left. Can someone help me with the way to make it right aligned? Screenshot added below for reference.
const myContent = new MarkdownString(`<span style='float:right;'><a href='#'>View Comment</a></span>`);
myContent.isTrusted = true;
myContent.supportHtml = true;
const decoration = { range, hoverMessage:myContent };
Screenshot
I want the highlighted red box area to be in extreme right of the hover. [The image used is just for reference].
After trying the same thing, I found this question still unanswered.
The MarkdownString documentation states that:
When supportHtml is true, the markdown render will also allow a safe subset of html tags and attributes to be rendered. See https://github.com/microsoft/vscode/blob/6d2920473c6f13759c978dd89104c4270a83422d/src/vs/base/browser/markdownRenderer.ts#L296 for a list of all supported tags and attributes.
Looking at the code linked, we can see that while "span" is allowed the "style" and "class" attributes, they are very strictly filtered and only allow some of the vscode built-ins to be used.
So, while styling elements with inline CSS or even a custom class might be possible, there is another approach to this - using Markdown tables, which get translated into HTML tables and allow custom alignment.
For example, what I ended up using was something like:
new MarkdownString(`
| |
| ---: |
| the very long line we want the below link to right-align to |
| [Link text](https://linktarget "Link hover message") |
`)
The idea came from the github issue linked in the the source file mentioned above.
A couple of notes:
codicons are still supported inside Markdown tables;
the HTML table generated does not expand to 100% of the hover message box, so if you want to right-align the link text with a longer line, they have to be in the same Markdown table;
Markdown table detection is very picky about spaces and newlines, you might have to play a bit with the formatting of your string for vscode to correctly transform it into a HTML table;
the Markdown table header cannot be omitted, at least that was the conclusion of my testing; it can however be empty;
the resulting HTML table might add some small invisible borders, I haven't investigated, but my alignment with other rows in the hover seemed 1px off;
trying to bypass the Markdown table creation and writing my own HTML table broke codicons support, although I haven't investigated that too much either;

Configuring the font-style of VS Code's inlay-hints

How can I change the font's style for VS Code's "Inlay Hints" feature?
I attempted to search for an answer, but could only find how to change the color, not the style.
Here's an example:
I would like the word target in the image below to render italic.
I tried the following, however, it did not work...
{
scope: "inlayHint",
settings: {
fontStyle: "italic",
},
},
I also tried adding editor.inlayHint to the scope, but the attempt was without success.
Setting the Font-style to italic isn't Possible.
Not all is lost though, there's a workaround that actually works pretty well.
As I stated above, setting the font-style to italic is not possible. There is, however, a workaround, and it works pretty darn well. Before I explain the workaround, I think its important to note that the first solution I tried to use, was to set the font to an italic variant, unfortunately setting "editor.inlayHints.fontFamily" to an italic variant of a font was something that VS Code didn't seem to allow. I have seen this in many other situations. The idea is, since you can't do this "fontStyle": "italic", you just change the font to an italic version.
For example:
If I use Cascadia Code as my font, then — in theory — I can just us the following configuration:
// #file "settings.json"
{
"editor.inlayHints.fontFamily": "'Cascadia Code Italic'"
}
...however, it unfortunately doesn't work that way — or at-least not in this situation. Not only do italic varients not work, but neither do bold variants and/or expanded variants (i.e. 'Inconsolata SemiExpanded', 'Inconsolata Bold', etc...).
While moving forward, I will state the obvious:
There is no "editor.inlayHints.fontStyle" setting.
So what do we do?
Well we can set the font-family using "editor.inlayHints.fontFamily".
Its a bit suprising that we can set the font, but not the font's style. I am not sure why they designed it this way, but it's obvious that they built the feature with specific constraints for reasons that are beyond me (reading the feature's development feed on GitHub would probably help anyone who wanted to know more about why the feature works how it does). Nevertheless, we have a highly customizable setting, that actually gives us far more control than the setting that we established, does not exist, editor.inlayHints.font.
What I do, personally, which has a cool tricked-out look, is I find a
non-monospaced hand-written style of font — usually from Google Fonts — and I assign that to the font-family. It took me a while to find some fonts that work. Anyone who has ever played with fonts, trying to find which font works best for them to write code with, will know: Picking fonts that are used anywhere inside the editor (or inside your code) is going to require great scrutiny, and the longer you code, the more set in your ways you get, so this can actually be a time consuming setting to configure. It took me an hour to settle on a font, and I settled on using the "Sriracha" font-family. Siracha is oblique in appearance (looks italic), its readable in the editor, it renders well in the editor (which not all fonts are going to do), and its slightly bolder than the standard weight of the font I use wich is Cascadia Code.
My Configuration results in the following appearance:
When changing the font family, there are a couple other settings that help to configure this feature.
So, in other words, just do the following:
Download the italic &/or bold style font you wont from Google Fonts, Font Squirrel, or some other font source you perfer.
Set the font family using "editor.inlayHints.fontFamily".
Critique the fonts configuration using the other settings available below.
// #file "settings.json"
{
// Font Family
"editor.inlayHints.fontFamily": "/*NAME OF FONT FAMILY*/",
// Font Size
"editor.inlayHints.fontSize": 14, // <-- Set the font-size you want
// Theme Colors Override
"workbench.colorCustomizations": {
// Overrides Theme Default Colors for InlayHints feature
"editorInlayHint.background": "#00001CCC",
"editorInlayHint.foreground": "#99FFBBCC",
// Overrides Theme Parameter hints fg for InlayHints feature
"editorInlayHint.parameterBackground": "#00001CCC",
"editorInlayHint.parameterForeground": "#99FFBBCC",
// Overrides Theme Type hints fg for InlayHints feature
"editorInlayHint.typeBackground": "#08000088",
"editorInlayHint.typeForeground": "#DDEEFF88"
},
}
Really its quite simple.
By being able to set the inlayHints font family to anything we want, we can achieve any sort of font style we want.
In settings.json you need a line like
"editor.inlayHints.fontFamily": "'Myfontitalic'",
Now, it seems vscode has some trouble reading a font name with non alphanumeric characters, if for instance the italic version is "Myfont-Italic" or "Myfont Italic".
A solution is to copy and rename the font to a new name, like "Myfontitalic", without spaces or other characters.
What I did was for Ubuntu but the same idea should work on any Linux, and probably Windows, using other tools (fontforge?)
apt install fonttools font-manager to get ttx a utility to change font info (font-manager is also useful)
use a search, font-manager, font-viewer, ... to find the location of the font (usually /usr/share/fonts/... or ~/.local/share/fonts)
copy a fresh version somewhere (home), cp ~/.local/share/fonts/Myfont-Italic.otf ~/temp.otf and cd to go home
translate to an XML copy ttx temp.otf as temp.ttx
edit temp.ttx (vi, ...), and change all "Myfont-Italic", "Myfont Italic" ... (relevant names) to a unique "Myfontitalic" name, save.
translate back to otf (...) with ttx temp.ttx (creates Myfontitalic.otf if it was an otf file)
To install the new font (locally), either double-click on it in the file explorer ( ~/Myfontitalic.otf ) or use a tool. Restart font-manager, the new font should be visible.
Restart vscode and add the line above in settings.json.
on a Mac find the font variant name like this:
Open "Font Book" App
Expand the desired font and select a variant.
Click the (i) icon on the Font Book toolbar.
Use the PostScript Name name in VS Code - for example "editor.inlayHints.fontFamily": "DankMono-Italic"
No one tells you where to edit this and that makes it a pain in the butt.
File>Preferences>Settings, search for color customizations, click "Edit in settings.json"
{
"workbench.colorCustomizations": {
"editorInlayHint.background": "#00000000",
"editorInlayHint.foreground": "#666666FF",
},
}

Mark-up for bold and italic in emacs org-mode

In emacs org-mode, we can use mark-ups to set Emphasis and monospace.
e.g.
*bold*
/italic/
How can we make a word both bold and italic?
It seems neither */.../* nor /*...*/ works.
In fact, both of these do work.
/*test*/
exports to HTML as
<i><b>test</b></i>
*/test/* works similarly. LaTeX / PDF export also works as you expect.
Org itself doesn't fontify both the bold and italic, but the semantics are fine.
Expanding on #Chris answer covering semantics being there, if you're interested in visible fontification effect inside your org notes, you have three approaches:
Highlight parts of your text
Nesting works nicely as long as you don't need to start / end two tags at once.
Use multiple tags with escape symbols
The closest you can get is
The code is:
*\ /\ _\ ~fontification can be nested~\_\/\*
So you need \​​ ​ (backslash and space) to escape following opening tags and \ (backslash) to escape following closing tags.
The need for space is annoying, and in it looks like this when exported to html:
So yes, you can have multiple mark-ups at once, but you have to choose between seeing the effect in emacs or having it nicely formated on export.
Modify how markup looks in emacs
Alternatively you could change how mark-up looks in emacs without modyfing exporting format, i.e. to make bold look red you'd need this:
(add-to-list 'org-emphasis-alist
'("*" (:foreground "red")
))
as covered in this great question and answer.

How do I modify text while keeping the original fontification?

I'm writing a mode which is actually a glorified markdown reader. It's a read-only mode however, and though I'd like to change the faces for bold, italics, and links, I'd love to remove the decorations surrounding those faces. However, when I do so, I lose the fontification. Is there anyway to modify fontified-text to something that no longer matches any of the syntax regexes and still keep the fontification?
Org-mode does this for its link markup. I'm not a mode writer (yet), but Org-mode would be the first place I'd look for code that demonstrates how to do this. Oddly, it doesn't do it for any of its fontification: italic, bold, and underline all retain their markup.
Specifically, the code to hide the link markup is on line 4612 of org.el in version 7.01 of org-mode:
(if org-descriptive-links (add-to-invisibility-spec '(org-link)))
where add-to-invisibility-spec is actually supplied by a built in elisp file subr.el, and allows specific types of markup to be hidden. That would be the approach I would take, especially if the buffer is read-only.

How do you display code snippets in MS Word preserving format and syntax highlighting?

Does anyone know a way to display code in Microsoft Word documents that preserves coloring and formatting? Preferably, the method would also be unobtrusive and easy to update.
I have tried to include code as regular text which looks awful and gets in the way when editing regular text. I have also tried inserting objects, a WordPad document and Text Box, into the document then putting the code inside those objects. The code looks much better and is easier to avoid while editing the rest of the text. However, these objects can only span one page which makes editing a nightmare when several pages of code need to be added.
Lastly, I know that there are much better editors/formats that have no problem handling this but I am stuck working with MS word.
Here is the best way, for me, to add code inside word:
Go to Insert tab, Text section, click Object button (it's on the right)
Choose OpenDocument Text which will open a new embedded word document
Copy and paste your code from Visual Studio / Eclipse inside this embedded word page
Save and close
Advantages
The result looks very nice. Here are the advantages of this method:
The code keeps its original layout and colors
The code is separated from the rest of the document, as if it was a picture or a chart
Spelling errors won't be highlighted in the code (this is cool !)
And it takes only few seconds.
Download and install Notepad++ and do the following:
Paste your code in the window;
Select the programming language from the language menu;
Select the text to copy;
Right click and select Plugin commands -> Copy Text with Syntax Highlighting;
Paste it into MS Word and you are good to go!
Update 29/06/2013:
Notepad++ has a plugin called "NppExport" (comes pre-installed) that allows you to copy to RTF, HTML and ALL. It permits dozens of languages, whereas the aforementioned IDEs are limited to a handful each (without other plug-ins).
I use Copy all formats to clipboard and "paste as HTML" in MS word.
After reading a lot of related answers, I came across my own solution, which for me is the most suitable one.
Result looks like this:
As you can see, it is the same syntax highlighting like on Stack Overflow which is quite awesome.
Steps to reproduce:
on Stack Overflow
Goto Ask Question (preferably with Chrome)
Paste Code and add a language tag (e.g. Java) to get syntax hightlighting
Copy code from preview
in Word
Insert > Table > 1x1
Paste code (you may need to use Paste Special... > Formatted Text (RTF) from the Edit menu to not lose the syntax hilighting)
Table Design > Borders > No Border
Select code > Edit > Find > Replace
Search Document ^p (Paragraph Mark)
Replace With ^l (Manual Line Break)
(This is required to remove the gaps between some lines)
Select code again > Review > Language > check "Do not check spelling or grammar"
Finally add a caption using References > Insert Caption > New Label > name it "Listing" or sth
Sample code thanks to this guy
There is a nice Online Tool for that : https://www.troye.io/planetb/
Just copy the generated code and paste it into your word editing software. So far I've tried it on MS Word and WPS Writer, works really well.
Doesn't play nice with Firefox but works just fine on Chrome (and IE too, but who wants to use that).
One of the main benefits is that, unlike the Code Format Add-In for Word, it does NOT mess with your code, and respects various languages' syntax.
I tried many other options offered in other answers but I found this one to be the most efficient (quick and really effective).
There is also another online tool quoted in another answer (markup.su) but I find the planetB output more elegant (although less versatile).
Input :
Output :
I type my code in Visual Studio, and then copy-paste into word. it preserves the colors.
When I've done this, I've made extensive use of styles. It helps a lot.
What I do is create a paragraph style (perhaps called "Code Example" or something like that) which uses a monospaced font, carefully chosen tabs, a very light grey background, a thin black border above and below (that helps visibility a lot) and with spelling turned off. I also make sure that inter-line and inter-paragraph spacing are set right. I then create additional character styles on top (e.g., "Comment", "String", "Keyword", "Function Name Decl", "Variable Name Decl") which I layer on top; those set the color and whether the text is bold/italic. It's then pretty simple to go through and mark up a pasted example as being code and have it come out looking really good, and this is works well for short snippets. Long chunks of code probably should not normally be in something that's going to go on a dead tree. :-)
An advantage of doing it this way is that it is easy to adapt to whatever code you're doing; you don't have to rely on some IDE to figure out whatever is going on for you. (The main problem? Printed pages typically aren't as wide as editor windows so wrapping will suck...)
Maybe this is overly simple, but have you tried pasting in your code and setting the font on it to Courier New?
Try defining a style called 'code' and make it use a small fixed width font, it should look better then.
Use CTRL+SPACEBAR to reset style.
If you are using Sublime Text, you can copy the code from Sublime to MS Word preserving the syntax highlighting.
Install the package called SublimeHighlight.
In Sublime, using your cursor, select the code you want to copy, right click it, select 'copy as rtf', and paste into MS Word.
I'm using Easy Code Formatter. It's also an Office add-in. It allows you to select the coding style / and has a quick formatting button. Pretty neat.
In case you're like me and are too lazy or in a hurry and don't want to download additional software, you can use http://markup.su/highlighter/. It's very straight forward and supports several highlight themes and many programming languages. In my case I was using Visual Studio Code, which doesn't allow copying with format due to CSS involved in styling (as reported here).
Copy the text from the Preview box and then in Word go to Insert -> Textbox, paste the Preview from the website, highlight all the text, and then disable spell checking for that textbox.
This is what the code looks like finally.
The best way I found is by using the table.
Create a table with 1x1. Then copy the code and paste it.
If you're using the desktop app then it will inherit the code editor theme color and paste it accordingly, else you can change the table style to any color.
UPDATE ------------------
From Word 2021, you can directly paste the code and it will preserve the formatting. No need to create the table.
Thank you #RdC1965 for mentioning this.
This is a bit indirect, but it works very nicely. Get LiveWriter and install this plugin:
http://lvildosola.blogspot.com/2007/02/code-snippet-plugin-for-windows-live.html
Insert your code using the plugin into a blog post. Select all and copy it to Word.
It looks great and can include line numbers. It also spans pages decently.
HTH
Colby Africa
Vim has a nifty feature that converts code to HTML format preserving syntax highlighting, font style, background color and even line numbers. Run :TOhtml and vim creates a new buffer containing html markup.
Next, open this html file in a web browser and copy/paste whatever it rendered to Word. Vim tips wiki has more information.
In my experience copy-paste from eclipse and Notepad++ works directly with word.
For some reason I had a problem with a file that didn't preserve coloring. I made a new .java file, copy-paste code to that, then copy-paste to word and it worked...
As the other guys said, create a new paragraph style. What I do is use mono-spaced font like courier new, small size close to 8px for fonts, single spaced with no space between paragraphs, make tab stops small (0.5cm,1cm,..,5cm), put a simple line border around the text and disable grammar checks. That way i achieved the line braking of eclipse so I don't have to do anything more.
Hope I helped ;)
This is the simplest approach I follow. Consider I want to paste java code.
I paste the code here so that spaces, tabs and flower brackets are neatly formated http://www.tutorialspoint.com/online_java_formatter.htm
Then I paste the code got from step 1 here so that the colors, fonts are added to the code http://markup.su/highlighter/
Then paste the preview code got from step 2 to the MS word. Finally it will look like this
You can use VS code to keep code format and highlighting. Directly copy and paste code from VS.
you can simply use this Add-in on any office program.
Go to insert tab, then Get Add-ins, and search for Easy Syntax Highlighter
It supports
185 languages and 89 themes.
Automatic language detection.
Multi-language code highlighting.
Use a monospaced font like Lucida Console, which comes with Windows. If you cut/paste from Visual Studio or something that supports syntax highlighting, you can often preserve the colour scheme of the syntax highlighter.
Answer for people trying to resolve this issue in 2019:
Most answers to this question are outdated by now. I wish there was a way to reinspect old questions and answers every now and then!
The method I found for this question that works with Office 365 and its associated programs can be found here.
I'm using Word 2010 and I like copying and paste from a github gist. Just remember to keep source formatting!
I then change the font to DejaVu Sans Mono.
You can opt to copy with or without the numbering.
Copying into Eclipse and paste it in Word is also another option.
You can also use SciTE to paste code if you don't want to install heavy IDEs and then download plugins for all the code you're making. Simply choose your language from the language menu, type your code, high-light code, select Edit->Copy as RTF, paste into Word with formatting (default paste).
SciTE supports the following languages but probably has support for others: Abaqus*, Ada, ANS.1 MIB definition files*, APDL, Assembler (NASM, MASM), Asymptote*, AutoIt*, Avenue*, Batch files (MS-DOS), Baan*, Bash*, BlitzBasic*, Bullant*, C/C++/C#, Clarion, cmake*, conf (Apache), CSound, CSS*, D, diff files*, E-Script*, Eiffel*, Erlang*, Flagship (Clipper / XBase), Flash (ActionScript), Fortran*, Forth*, GAP*, Gettext, Haskell, HTML*, HTML with embedded JavaScript, VBScript, PHP and ASP*, Gui4Cli*, IDL - both MSIDL and XPIDL*, INI, properties* and similar, InnoSetup*, Java*, JavaScript*, LISP*, LOT*, Lout*, Lua*, Make, Matlab*, Metapost*, MMIXAL, MSSQL, nnCron, NSIS*, Objective Caml*, Opal, Octave*, Pascal/Delphi*, Perl, most of it except for some ambiguous cases*, PL/M*, Progress*, PostScript*, POV-Ray*, PowerBasic*, PowerShell*, PureBasic*, Python*, R*, Rebol*, Ruby*, Scheme*, scriptol*, Specman E*, Spice, Smalltalk, SQL and PLSQL, TADS3*, TeX and LaTeX, Tcl/Tk*, VB and VBScript*, Verilog*, VHDL*, XML*, YAML*.
If you are using Intellij IDEA, just copy the code from the IDE and paste it in the word document.
A web site for coloration with lots of languages.
http://hilite.me/
You can host one yourself since it is open source. The code is on github.
There really isn't a clean way to do it, and it could still look fishy based on your exact style settings.
What you could try to do is to first run a code-to-HTML conversion (there are many programs that do that), and then try to open up the HTML file with word, that might hopefully provide you with the formatted and pretty code, and then copy and paste it into your document.
I was also looking for it and ended up creating something for my code display.
Here's a good way:
Create a rectangular form and place your text inside.
Change the font to Consolas and size ~10.
Change the text font to gray near-black (gray 25%, darker 75%)
Use darker colors to highlight your text if needed and choose one to be the contour.
I have created an easier method using tables, as they are easier to create, manage, and more consistent (with the possibility to save the table's style inside the document itself), but I couldn't find a better way for code colouring scheme, sorry for that.
Steps:
Create a 3x3 table.
Select the table, and make its borders invisible ("No Borders" option), and activate "View Gridlines" option.
Make the adjustments to cells' spacing and columns' widths to get the desired aspect. (You will have to get in "Table Properties" for fine tuning).
Create a "Paragraph Style" with the name of "Code" just for your code snippets (as mentioned in https://stackoverflow.com/a/25092977/8533804)
Create another "Paragraph Style" with the name of "Code_numberline" that will be based upon the previous created style, but this you will add a numbering line in its definition (this will automate line numbering).
Apply "Code_numberline" to the first column, and "Code" to the 3 column.
Add a fill in the middle column.
Save that table style and enjoy!
The best presentation for code in documents is in a fixed-width font (as it should appear in an IDE), with either a faint, shaded background or a light border to distinguish the block from other text.
If its Java source code copy it to Visual Studio and then copy it back to Word.