[Coco] the future of the NitrOS-9 wiki

[Greg]

As far as I am aware, markdown doesn't support some of the formatting 
that was used in the mediawiki, so we'll need to figure out some 
alternatives if we stick with the markdown format. I'm specifically 
thinking of some of the complex tables that use colspan or rowspan as 
seen in the Memory Modules page:

http://nitros9.sourceforge.net/wiki/index.php/Memory_Modules

I think SourceForge really botched the conversion to markdown, so it 
left the wiki in a very bad state. Compare these two pages as one 
example:

http://nitros9.sourceforge.net/wiki/index.php/Interactive_Debugger
https://sourceforge.net/p/nitros9/wiki/Interactive_Debugger/

Note that the Register Names section should be in a table with :A = 
Accumulator A, but the markdown has :A as a heading and equals sign is 
missing. Also note that pretty much everything in braces (e.g. [:X]) has 
been converted to links in markdown so these need to be fixed.

https://sourceforge.net/p/nitros9/wiki/Relocating_Macro_Assembler/

Syntax highlighting is enabled in some of the listings and looks really 
odd, so this needs to be fixed. The table under 6809 Instructions and 
Addressing Modes is no longer a table.

https://sourceforge.net/p/nitros9/wiki/Commands/

Character encoding was used on this page to prevent these characters 
sequences from being interpreted as wiki markup, but these characters 
were apparently double encoded in the conversion.

I went through some of the pages a couple of years ago trying to fix 
some of these issues, but I couldn't remember how the botched tables 
should be formatted.

I think the differences boil down to these:

* Mediawiki supports very complex markup, including embedded HTML and 
HTML attributes to customize the markup
* MediaWiki has a powerful diff engine that makes it easy to determine 
who edited what
* Mediawiki requires a lot of CPU to parse the markup and render the 
HTML
* MediaWiki docs are ready to roll as they exist right now
* Is there any risk that SourceForge will pull MediaWiki support without 
notice again?

* Markdown is a very simplistic markup language that's easy to learn, 
but it doesn't support complex formatting
* Markdown is significantly easier to parse and render
* Markdown docs require a significant amount of effort to fix the 
botched conversion

I prefer wiki format due to its flexibility, but I'm not objectively 
opposed to markdown if everyone prefers markdown.

On 5/7/2016 6:31:01 AM, "Tormod Volden" <lists.tormod at gmail.com> wrote:

>-- because better documentation is the only way to save NitrOS-9 and
>the OS-9 legacy from dying out --
>
>MediaWiki vs Markdown (Allura)
>
>The NitrOS-9 wiki was originally written in a MediaWiki format (same
>as used on wikipedia.org), and this was a built-in (as "hosted app")
>wiki engine at SourceForge until June 2014. At this point SourceForge
>moved the built-in wiki infrastructure to their Allura platform, which
>uses a Markdown format (also very popular these days). In the process
>they converted all project wikis to the new format, with various luck.
>Many may have noticed that the current NitrOS-9 wiki lacks some images
>and some tables look odd.
>
>Prior to this, they were documenting how to port a project wiki from
>the built-in wiki engine to a MediaWiki engine that the project can
>run on its own (SourceForge provides mysql data base instances and
>everything needed). Meanwhile this documentation seems to have
>disappeared, but I found it [1] through the Internet Archive. They
>also kept backups of the old MediaWiki content.
>
>This week I finally got to try out this MediaWiki setup and recovered
>the old NitrOS-9 wiki from the backups. The result can be seen at
>http://nitros9.sourceforge.net/wiki/
>
>Note that it misses a few changes that have been done last year on the
>official, converted wiki at https://sourceforge.net/p/nitros9/wiki/
>
>(Also, the logo was just something I quickly sketched together. Is
>there a proper NitrOS-9 logo?)
>
>So this gives us the following choice:
>
>1. Continue using the official, converted wiki in Markdown format
>todo: we should fix up images and tables
>advantages:
>- Standard and supported at SourceForge
>- Uses normal SourceForge accounts
>- No administration needed
>
>or
>
>2. Use the rescued MediaWiki
>todo: we must incorporate last year's few fixes
>advantages:
>- Much more features, e.g. RecentChanges and other SpecialPages
>- Looks much better in my opinion
>- MediaWiki is well maintained as standard on wikipedia etc
>
>
>When it comes to speed and performance I am not sure, they are both a
>bit slow and it varies a lot, probably depending on cache and server
>load. I have not enabled caching on MediaWiki AFAIK.
>
>The above advantages on each side seems pretty minor to me. It is more
>a question of what would contributors like to work with!
>
>Voicing your opinion in this thread does not automatically mean you
>are taking on responsibility :) Though of course your voice will carry
>more weight if you are already working on the wiki, or have good
>intentions to do so.
>
>Best regards,
>Tormod
>
>PS. Aaron, this might be a question for the DriveWire4 wiki as well. I
>can do the MediaWiki setup there also if you like.
>
>[1] 
>https://web.archive.org/web/20151008101534/http://sourceforge.net/p/forge/community-docs/Migrating%20MediaWiki%20from%20Hosted%20Apps/