Syntax highlighting added to Wiki

Discussion about the site's wikis, including bugs/issues encountered.

Moderator: Moderators

User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Syntax highlighting added to Wiki

Post by koitsu »

This morning I added syntax highlighting support to the Wiki. The syntax highlighter is called GeSHi. es I am aware the documentation link on their page returns 404; I can't do anything about that, so use Google to look for documentation hosted on other sites (or download it yourself and look in the docs/ directory).

The MediaWiki bits are documented here.

You use the Wiki tag <source lang="..."> to enable syntax highlighting, then use </source> when finished. If you forget the lang parameter or make a mess, you'll visually (at Preview/Save time) get an error. There are other parameters that you can specify too; please see the above MediaWiki link. You can also use <syntaxhighlight> as an alternate tag if you want, but I find <source> to be more convenient.

The highlighter supports many languages (see attachment for the official list that's on the server), but most relevant is the fact that it supports 3 different types of 6502 models:
  • 6502acme -- MOS 6502 (6510) ACME Cross Assembler format
  • 6502kickass -- MOS 6502 (6510) Kick Assembler format
  • 6502tasm -- MOS 6502 (6510) TASM/64TASS 1.46 Assembler format
6502acme and 6502tasm tend to look fairly similar, while 6502kickass has nice colouring for labels but was doing things like breaking badly (colouring-wise) on apostrophes.

You do not need to <pre> or space-indent your code to use this (I imagine many will find that useful); you can still do all that if you want of course.

I went through most of the Wiki pages (searching for opcodes like bpl, bmi, and rts) and edited them to use <source lang="6502tasm">. I'm sure I missed some, obviously, but my wrists/fingers were getting sore. Here's an example:

http://wiki.nesdev.com/w/index.php/VRC7 ... rite_Delay

I'll state up front that the colour scheme for 6502tasm is not exactly what I'd like (ex. the extreme light-grey for comments is hard for me to read,). There are ways to modify the colours used in the CSS for the highlighter for those languages (within MediaWiki itself), so if we all come up with recommended improvements (please learn how to use things like Tools/Web Developer/Style Editor in Firefox, and/or Firebug for Firefox!) and want to make our own "theme" for the source code, that's great. I'm always open to suggestions. Upload screenshots of what looks good to you, with the ideal CSS changes, and any of us who are Wiki admins can put them into place.

Changing the syntax highlighter language itself (ex. "make address labels named PPUADDR bold and black") is something I would rather stay away from -- the reason is that if we upgrade MediaWiki (and especially the extension itself), it's extremely likely we'd lost those changes (meaning we have to start keeping a patch repository and so on -- we used to do this, and it's difficult to manage). However, if someone did make a new language called (for example) nesdev that was specific to all our needs (and was NES-specific), I'd be willing to make an exception and deal with keeping track of that one-off.

Hope this helps or at least gets people editing. :-)

Footnote: warning to those poking about: avoid looking at "Recent changes". I spent almost 3 hours (I think?) messing about with unrelated things (mainly MediaWiki templates) which failed miserably, so you'll see all sorts of template-related things in there, followed by a bunch of template deletes. I did get a couple templates working like {{sub}} and {{sup}} though (for sub- and superscript -- see MediaWiki's Template page on those for how to use them), so my efforts there weren't a total failure. Templates in MediaWiki are such a pain in the ass. I think I spent the past 4 hours just on the wiki. Gruhhh...
Attachments
highlighters.txt
(1.72 KiB) Downloaded 934 times
User avatar
thefox
Posts: 3134
Joined: Mon Jan 03, 2005 10:36 am
Location: 🇫🇮
Contact:

Re: Syntax highlighting added to Wiki

Post by thefox »

Font should be bigger.
Download STREEMERZ for NES from fauxgame.com! — Some other stuff I've done: fo.aspekt.fi
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Syntax highlighting added to Wiki

Post by koitsu »

Font is the same size as <pre>; nothing there has changed.

Here's a test sandbox.

Using the Inspector in Firefox to look at the relevant "computed" CSS attributes, the only thing I see different that pertains to the "size" of the font (presumably height) is the line-height (16.5167px for pre, 15.2333px for 6502tasm et al).

Please provide screenshots of what you're seeing otherwise.
User avatar
thefox
Posts: 3134
Joined: Mon Jan 03, 2005 10:36 am
Location: 🇫🇮
Contact:

Re: Syntax highlighting added to Wiki

Post by thefox »

Google Chrome Version 29.0.1547.57 m (on Windows 7):
wiki-font.png
Download STREEMERZ for NES from fauxgame.com! — Some other stuff I've done: fo.aspekt.fi
User avatar
thefox
Posts: 3134
Joined: Mon Jan 03, 2005 10:36 am
Location: 🇫🇮
Contact:

Re: Syntax highlighting added to Wiki

Post by thefox »

More info:

Chrome's Developer Tools shows the "Computed style" font-size as 13px for the normal pre and 10px for the one with the syntax highlighting. Not really sure where the smaller font size comes from, though.
Download STREEMERZ for NES from fauxgame.com! — Some other stuff I've done: fo.aspekt.fi
User avatar
rainwarrior
Posts: 8731
Joined: Sun Jan 22, 2012 12:03 pm
Location: Canada
Contact:

Re: Syntax highlighting added to Wiki

Post by rainwarrior »

Cool!
zzo38
Posts: 1096
Joined: Mon Feb 07, 2011 12:46 pm

Re: Syntax highlighting added to Wiki

Post by zzo38 »

Can you add the format used by NESASM/Unofficial MagicKit? (Unofficial MagicKit is a more powerful macro assembler so syntax highlighting might be more difficult.)
(Free Hero Mesh - FOSS puzzle game engine)
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Syntax highlighting added to Wiki

Post by koitsu »

zzo38 wrote:Can you add the format used by NESASM/Unofficial MagicKit? (Unofficial MagicKit is a more powerful macro assembler so syntax highlighting might be more difficult.)
Please see (fully read) my initial post.
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Syntax highlighting added to Wiki

Post by koitsu »

thefox wrote:Chrome's Developer Tools shows the "Computed style" font-size as 13px for the normal pre and 10px for the one with the syntax highlighting. Not really sure where the smaller font size comes from, though.
In cases like this it's almost always something to do with CSS inheritance, or it has to do with the differing line-height (though AFAIK that's not supposed to affect font size, just the "height of the line"; I believe overlap occurs if they're too small). They're the same size (as <pre>) here, using Firefox 23.

I'm more familiar with Firebug than Firefox's native Developer Tools, so I'll spend some time poking around in that today to see if I can figure out the inheritance. If push comes to shove, I can always exclusively set the font sizes in the CSS natively (hence how we'd get a "different colour theme" as mentioned initially).
Attachments
Untitled-1.png
Untitled-1.png (11.71 KiB) Viewed 25253 times
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Syntax highlighting added to Wiki

Post by koitsu »

Okay, I can reproduce the problem in Chrome (but not Firefox or IE8). I'll poke about to see if I can figure out what the deal is. Fucking "browser differences" in 2013, always makes me blow a gasket.
User avatar
blargg
Posts: 3715
Joined: Mon Sep 27, 2004 8:33 am
Location: Central Texas, USA
Contact:

Re: Syntax highlighting added to Wiki

Post by blargg »

Those light gray comments are hard to read due to being so light. The green text is also a hair difficult to read, also because of reduced contrast (oddly an online contrast checker flagged the red but not the green).
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Syntax highlighting added to Wiki

Post by koitsu »

Okay, here we go:

Code: Select all

<div dir="ltr" class="mw-geshi mw-code mw-content-ltr">
  <div class="_6502acme source-6502acme">
    <pre class="de1">
      <span class="co1">;</span>
      <span class="co1">; Have some start-of-line comments</span>
      <span class="co1">;</span>
@label:            <span class="co1">; Nonsensical code</span>
Using Chrome, I can see that the initial container <div> (uses classes mw-geshi, mw-code, and mw-content-ltr) still results in a font-size of 13px. However, the subsequent <div> (uses classes _6502acme and source-6502acme) results in a font-size of 10px -- however I don't think this is really the case (meaning I think the developer tool may have a bug or is behaving very oddly, I'll explain in a moment). Adding a font-size: 13px; to either of those 6502acme-related classes fixes the problem, but I'd much rather know how/why the font is getting changed. Those two classes don't do anything with the font size:

Code: Select all

.source-6502acme {line-height: normal;}
._6502acme.source-6502acme  {font-family:monospace;}
So I moved on to the <pre> with the de1 class:

Code: Select all

._6502acme.source-6502acme .de1, ._6502acme.source-6502acme .de2 {font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;}
I toggled the font attribute in Chrome and voilà -- looks correct now. The font-size there is being set explicitly to 1em (the 1.2em part is line-height). So where does this CSS come from? It's hard-coded into the main geshi.php code of all places:

Code: Select all

 450     /**
 451      *  The style for the actual code
 452      * @var string
 453      */
 454     var $code_style = 'font: normal normal 1em/1.2em monospace; margin:0; padding:0; background:none; vertical-align:top;';
Not per-language either, just flat out "let's use this for everything". It's fairly obvious to me whoever decided this has/had no idea why explicitly setting the font size there is a Bad Idea(tm) because of how it conflicts with the already-chosen defaults per stock MediaWiki CSS templates. They should have just said font-family: monospace and that's all.

Seems some other people have complained about this problem too -- and the 2nd reply in that thread is wrong in so many ways too (especially the "doesn't enforce any CSS rules on its own" -- uh huh, and what do you think the above does? Sigh, Internet people...). My point is that most/all of the font-related style crap in $code_style shouldn't be there at all, because all it does is stomp over the already-established MediaWiki styles.

I also can't tell who/what introduced this idiocy because it looks like they changed from SVN to git and probably repos, so it's been there since at least April 2012 from what I can tell.

Blabbering aside, is it fixable? I think so, but I'm not entirely sure. I will be tinkering momentarily.
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Syntax highlighting added to Wiki

Post by koitsu »

blargg wrote:Those light gray comments are hard to read due to being so light. The green text is also a hair difficult to read, also because of reduced contrast (oddly an online contrast checker flagged the red but not the green).
Yeah, mentioned that initially, but I need mock-ups (pref. screenshots) of what people would like. All the syntax highlighting colours/styles are adjustable with ease, but the community needs to hash out what they'd prefer and I'm happy to put it all into place. If there are existing syntax highlighters folks out there use, provide a PNG or GIF (not JPEG!) screenshot of some code and I can pull out the RGB values + make appropriate changes to the CSS.
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Syntax highlighting added to Wiki

Post by koitsu »

Okay, for whatever reason, this does not appear to be fixable through proper CSS means. The problem has to do with the inheritance order used by GeSHi. In fact, even setting font-family: monospace in Chrome at all causes it to start behaving oddly with font sizes and line heights -- I am not going to get into a battle with that. I started finding other places where this was being done (per-element for example), and I was just like "you gotta be kidding me".

Simple version: GeSHi -- what a pile.

Because I've already changed a bunch of our Wiki pages (hours worth) to use a syntax highlighter, I will begin looking at others. There are many, including some which are JavaScript-based (which would take load off the server). I imagine I can come up with the necessary 6502 highlighting code bits once I find one that behaves decently.

I will likely have to go through all the pages again and fix their syntaxes and so on. I shouldn't have gone through and edited all our Wiki pages to use this thing until I had tested it fully in a sandbox first and asked for community feedback first. But I can tell say up front I really did not expect Chrome to bring out oddities like this (I am not blaming Chrome; this is just pure developer idiocy on the part of GeSHi, or at least the MediaWiki version). So in turn this is my own doing/my own fault and thus I should be the one to correct it all.
User avatar
koitsu
Posts: 4201
Joined: Sun Sep 19, 2004 9:28 pm
Location: A world gone mad

Re: Syntax highlighting added to Wiki

Post by koitsu »

@thefox --

I remembered/found this post of yours, mentioning Alex Gorbatchev's SyntaxHighlighter.

There's a MediaWiki SyntaxHighlighter extension which is exactly that. However, that dudes' "implementation" is kind of half-ass, meaning he doesn't implement a bunch of the configuration tie-ins for certain things (hard to explain tersely), so I may have to modify the underlying code.

Anyway -- possibly you could provide the "brush" (what he calls it) for your 6502 syntax highlighting and I can work it into the MediaWiki extension for the nesdev wiki? It'd be a "one-off" but in the case of one extension I can manage that. :-)
Locked