Migrate wiki to github

[suborb]

The machine the wiki is on:

• Is old and slow
• Costs @suborb money every month
• Only @suborb has access to

Steps to do this:

• Enable wiki on the GitHub project
• Run the migration script
• Upload the wiki
• Fix up any migration errors
• Move examples into examples directory in the main repo
• Provide a redirect script on z88dk.org so google links remain mostly valid

If anyone wants to pick this up I can provide a tarball of the content or I'll get around to doing it myself fairly soon.

[suborb]

The import made a bit of a mess of the files and the features of the GitHub wiki are a bit restrictive (flat structure etc).

However, with a custom side bar then we should be able to enforce some structure on it.

[aralbrec]

I'm thinking we have to redo from scratch to create a proper structure and have the import as the catch-all for forwarding existing links or to document things not yet integrated to the github wiki.

I'll take a look to see how things went a little later this evening.

[suborb]

There's some good information buried in there, but I'm left thinking that some of it is in the wrong place:

• Function documentation should be in the header files and we should use doxygen to generate docs for them - https://gist.github.com/vidavidorra/548ffbcdae99d752da02 could be useful here
• Examples should be as code in the main repo

A general update is needed as well, we've got CVS links about the place (though a sed will sort those out)

[aralbrec]

We lack a coherent introduction as front page that links to everything. I agree there is a lot of good information in the existing docs but there is also outdated information, incomplete information and plain wrong information (stuff that is now obsolete). I do think we should end up re-writing or copy/pasting+reformatting into some kind of outline that will organize everything well.

I agree examples should be in the repo. The trouble with doxygen is that edits will be done in the codebase; I think the git wiki can allow editing by outside contributors more easily? The original idea with the headers was for it to act more like a tutorial overview and a way to organize presentation of the library by having a list there with brief description that could be linked to for details. doxygen documentation tends to be terse and non-tutorial in nature.

I'd go for coming up with an outline first if someone wants to propose one? I can maybe look at this sometime tomorrow but I'm not the world's best technical writer.

[pauloscustodio]

I have the z80asm documentation update bugging me, as the existing documentation is getting more and more outdated with each change. A simple way to edit the documents on-line in the wiki will help overcome the resistance to get into documentation writing mode.

[zx70]

I never loved doxygen, but I'll look closer at it, probably there's some "advanced user trick" to improve the documentation (e.g. with examples, preambles. etc...).