Wiki improvements

Forum for discussion about the documentation project.
Post Reply
coderJeff
Site Admin
Posts: 4308
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Wiki improvements

Post by coderJeff »

I have been making some improvements to the wiki & the doc generating tools.

I found some pages that have been dead for years, and they really just need to go. I am planning to completely remove the pages (and history) from the wiki. You can see what they were by looking at the page history.

Dead Pages - never maintained:
CodeLibGame CodeLibGfx CodeLibGraphics CodeLibMath CodeLibOSSpecific CodeLibSound CodeLibText CodeLibWeb

Dead pages where content is moved elsewhere.
CVSCompile : Delete me! Content moved to DevBuild.
CVSCygwin : Delete me! Content moved to DevBuild.
CVSDOSWin32 : Delete me! Content moved to DevBuild.
CVSLinux : Delete me! Content moved to DevBuild.
CVSWin32MSYS : Delete me! Content moved to DevBuild.
DevCompilationProcess : Delete me!
DevDirTree : Delete me! moved to DevNormalVsStandalone
FreeImage : Delete me!
Git : Delete me! Content moved to DevGettingTheSourceCode.
SVNCompile : Delete me! Content moved to DevBuild.
SVNCygwin : Delete me! Content moved to DevBuild.
SVNDOSWin32 : Delete me! Content moved to DevBuild.
SVNFreeBSD : Delete me! Content moved to DevBuild.
SVNLinux : Delete me! Content moved to DevBuild.
SVNWin32MSYS : Delete me! Content moved to DevBuild.

Pages not needed - was just part of the default install when wiki was upgraded 5 years ago
SandBox
SysInfo
WikkaConfig

Pages that need to be rewritten - the wiki has lots of formating available, but we only use a subset to work with the documentation generators.
FormattingRules
TableMarkup
TableMarkupReference
review of https://www.freebasic.net/wiki/wikka.ph ... FBWikiHelp
St_W
Posts: 1617
Joined: Feb 11, 2009 14:24
Location: Austria
Contact:

Re: Wiki improvements

Post by St_W »

I don't think that the articles are a big loss, the most valuable of it being its history, but isn't there an option to delete the pages while keeping their history or archiving those pages and their history?

A Sandbox page could be useful (Wikipedia has one too: https://en.wikipedia.org/wiki/Wikipedia:Sandbox), but of course that has to be excluded from official documentation, etc.

Regarding the documentation of formatting options in the wiki: as author of the fbdoc application you are probably the best choice for documenting the formatting option it supports (which is basically a subset of what the wiki software supports, afaik) ;-)
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Wiki improvements

Post by badidea »

Also some dead links on https://www.freebasic.net/wiki/wikka.ph ... odeLibrary. At least two.

Is there no 'special pages' on this wiki server? Like: https://en.wikipedia.org/wiki/Special:LonelyPages
This way you can find pages that were once linked, but 'orphan' now.

Also, is it possible to add more tutorials or snippets to the wiki? E.g. a selection of the best posted code on the forum? With a page that structures or categorises the code? Like:
* File I/O (XML, QML, Tab-separated, Directory listing, ...)
* String manipulation (...)
* Graphics (Bitmap loading, Animations, PNG, Polygon drawing, ...)
* Human interface devices (Mouse, Keyboard, ...)
* Games(Square grid, hexagonal grid, isometric grid, ...)
* Math & Physics (...)
* Sound (...)
* Network (TCP/IP, UDP, http, ...)
* GUI (FLTK, GTK, ...)
* Data structures (lists, Trees, Queues, ...)
* Database (MySQL, ...)
* Windows specific (GUI, ...)
* Linux specific (...)
* ...

Ideally tutorials / snippets with a screen capture on the same wiki-page of the output if applicable. Something like this: http://doc.qt.io/qt-5/qtwidgets-widgets ... ample.html. Although I do not intend put complete games like this on the wiki.

And the pages will require some screening / reviewing / controlling to prevent chaos. The Qt community wiki contains a lot of useless pages. This one for example, lost al formatting and did not work https://wiki.qt.io/Drag_and_Drop_within_a_GridView. Last edit by me, to get the code at least working. That was before I realised that this whole wiki was a big mess.

Edit: No, I am not a robot! I know how cars and roads look like :-)
coderJeff
Site Admin
Posts: 4308
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

@St_W, yes, there is no option to keep a page (plus history) and also have it hidden. If the page exists, it appears in the PageIndex. My opinion is that if it is relevant information it should be visible and maintained, otherwise just get rid of it. FYI, all the pages, typically before a release, and recently monthly, have been committed to fbc repo in ./doc/manual/cache/*.wakka so there is some history there. If the wiki was ever completely lost and no database backup, we could recreate it from the git repo.

@badidea,
Special Pages
- OrphanedPages shows pages not linked from any other page. Has many false positives depending on how the page is linked. [[link]] vs {fbdoc} action link.
- WantedPages shows pages that are linked but have no page. Have to be careful with this. Just because wiki sees the CamelCaseWord as a link, doesn't mean we actually want a page for it.
- MissingDocs is a user maintained page, the wish-list for what needs to be updated or added.
- CommunityTutorials is for tutorials, and yes, more can be added. The FBWikiFaq Page describes How do I add my tutorial to the community tutorials? though the answer is incorrect about the login (wiki logins are currently disabled due to spam problems).
- CodeLibrary? The guy who created the page hasn't updated it in years and years. You are volunteering to verify, yes? :)

The content addition sounds great: I don't know how to generate excitement or interest in maintaining the wiki & documentation. Yeah, I've spent a lot of free time on the docs & tools, and yeah, I probably know quite a bit about it, but I can't do it all. And, I'll work on the parts I can; that's the best I can do.
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Wiki improvements

Post by badidea »

coderJeff wrote:You are volunteering to verify, yes? :)
Maybe... I'll start with looking what is already there. Get myself familiar with WikkaWiki and the formatting guidelines.
Just requested an account: viewtopic.php?f=9&t=25849&p=242093#p242093
St_W
Posts: 1617
Joined: Feb 11, 2009 14:24
Location: Austria
Contact:

Re: Wiki improvements

Post by St_W »

coderJeff wrote:FYI, all the pages, typically before a release, and recently monthly, have been committed to fbc repo in ./doc/manual/cache/*.wakka so there is some history there. If the wiki was ever completely lost and no database backup, we could recreate it from the git repo.
Yes, I know, but this doesn't include the history (except if these versions were committed in the repo). btw in previous times even the server-side software for the website and the wiki have been committed in SVN.
IMHO the code library doesn't really fit into the wiki anyway; there should be some dedicated site for that (like the FB archive was)

and btw, if we are talking about possible wiki improvements:
There are quite some dead links in the wiki and e.g. the tutorials would need a review as practically all of them were never updated after being written. Just mentioning in case there are volunteers :-)
badidea
Posts: 2586
Joined: May 24, 2007 22:10
Location: The Netherlands

Re: Wiki improvements

Post by badidea »

St_W wrote:Just mentioning in case there are volunteers :-)
Still busy reading the wiki :-)
sancho3
Posts: 358
Joined: Sep 30, 2017 3:22

Re: Wiki improvements

Post by sancho3 »

the tutorials would need a review as practically all of them were never updated after being written. Just mentioning in case there are volunteers :-)
I will run through some of them.
I will list them as I finish looking at them.

#1 Getting Started With FreeBasic by SJ Zero
Its short and the information there is still current. The examples run fine.
Is there anything else I should look out for?

#2 Using Libraries in FreeBasic by SJ Zero
Three dead links network, TrueType font support, and audio near the beginning.
Examples use $Include which is only available in FBLite and QB.
No mention of requiring DLL's for the libraries as well as the .bi files.

#3 Using the Mouse in FreeBASIC by MystikShadows
The description for both GetMouse and SetMouse are missing the Clip parameter.
Unimportant spelling errors.
Under the title "the coding begins" he mentions that "Of course you don't have to declare your variables" which is mistaken.
The example code runs fine.
St_W
Posts: 1617
Joined: Feb 11, 2009 14:24
Location: Austria
Contact:

Re: Wiki improvements

Post by St_W »

sancho3 wrote:I will run through some of them.
I will list them as I finish looking at them.
Thank you very much for your efforts. IMHO you could fix smaller issues instantly instead of documenting them (if you want to) - should be less work and the changes are recorded in the wiki's page history anyway, in case anybody would be curious about them. Of course you can also do bigger changes instantly if you think you're capable of doing it.
Sometimes the formatting could be improved (e.g. use freebasic syntax highlighting ("%%(freebasic)") in code-boxes instead of generic code-boxes ("%%") ), but the biggest issues are probably outdated/obsolete content and dead links.
sancho3
Posts: 358
Joined: Sep 30, 2017 3:22

Re: Wiki improvements

Post by sancho3 »

Ok, I will edit as I go.
I will figure out how to get a wiki sign up. And I will figure out how to format and edit and some sort of mark to show that the file has been edited.
Patience on this please.
coderJeff
Site Admin
Posts: 4308
Joined: Nov 04, 2005 14:23
Location: Ontario, Canada
Contact:

Re: Wiki improvements

Post by coderJeff »

@MrSwiss, if you read this, what do you want to do with this page?:
https://www.freebasic.net/wiki/wikka.ph ... it_MrSwiss
Thanks, I appreciate your interest.
fxm
Moderator
Posts: 12066
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

MrSwiss wrote:NOTE:
AndAlso: if the first evaluation returns FALSE (0), the second evaluation is *skipped.
OrElse: if the first evaluation returns TRUE (Not 0), the second evaluation is *skipped.
Therefore, the evaluation(s) could also be called: Boolean (contrary to: binary And/Or).

* = code continues on the next line, after the evaluation is finished.
Why the next line?
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Post by MrSwiss »

@coderJeff,

that page is just a first test on, how to extend/modify, an existing page.
In case, there is a better way available, plse. advise.
The only 'live' changes, made by me so far, where: expl. code changes for 64bit compat.

This didn't require any formatting!

The problem(s) encountered so far are: there isn't any "Style-/Formatting Guide" and
it is therefore less than intuitive, to work on such things.
Secondly, but related to above, using any *key-word* prompts later to: "create new page" ???
(already existing but, probably not found: KeyPg... instead of, ProPg... prefix?)

@fxm,

while testing only, I wouln't put any weight on "ninceities/details/correctness".
> Why the next line?
May not be needed at all ...
fxm
Moderator
Posts: 12066
Joined: Apr 22, 2009 12:46
Location: Paris suburbs, FRANCE

Re: Wiki improvements

Post by fxm »

Because the program can also continue on the same code line:

Code: Select all

If 0 = 1 AndAlso 0 = 0 Then Else print "Second condition skipped but program continues on the same code line"
Sleep
MrSwiss
Posts: 3910
Joined: Jun 02, 2013 9:27
Location: Switzerland

Re: Wiki improvements

Post by MrSwiss »

fxm, not helpful at all (see prev. post) ...
Better would be: a Formatting-Guide, for the WIKI!
(Would help others too, to get quicker "off the ground")
Post Reply