DOCUMENTATION REVOTE

[rdc]

I undertsand the need for some sort of format, but looking over the doc spec, it is a bit too much for me. I think if you want to follow this format, then maybe someone could write a little app that has the necessary fields that we could fill in and spits out the proper format. This way it is consistent (no human error), has the proper format and won't be such a chore to produce the docs.

[v3cz0r]

coWiki could be the answer, it stores all data as XML into the database, and everything seems to be really nice coded using design patterns, the only problem is.. php 5 is needed to run it, because the new class features.. fb.net is hosted on a server with php 4.x, nothing is perfect..

With the wiki hosted at fb.net i could dump the db and convert the files with some automatic tool, if docs follow a format like used for xbasic: http://www.xbasic.org/wiki/index.php?pag...riteString

[Jofers]

Would you like to switch to that format? The draft I have up there divides keyword pages into:

title (description)
usage (syntax + attributes)
details (remarks, I guess)
examples (any standalone examples)
related links

The markup in there is pretty nicely formatted, but the tables are bloody insane. You could do enough formatting with plain ol' unattributed markup

<table class='something'>
<tr>
<td> <- no class or valign or any of that.

which is the kind I like best.

The present drafts are divvied into DIVs, but they use mediawiki formatting for sections and bullets, to be easier.

== SECTION ==
<div id="subsection">
* bullet
* bullet
</div>

[v3cz0r]

Alright, wiki created: http://www.freebasic.net/wiki/

I added the #DEFINE test, if the formatting seems okay, i will write a script to convert Nex's doc to the wiki format, so it can be edited later and new items can be added..

I added the fbdoc action, so you can define new:

Categories: {{fbdoc item="category" value="Some category"}}

Keywords: {{fbdoc item="keyword" value="KwSomeKeyword|KEYWORDNAME"}}

Set the title: {{fbdoc item="title" value="Keyword Name"}}

And sections:

Syntax: {{fbdoc item="syntax"}}

Description: {{fbdoc item="desc"}}

Examples: {{fbdoc item="ex"}}

Differences: {{fbdoc item="diff"}}

See also: {{fbdoc item="see"}}

More can be added later if requested..

Parsing that code won't be any hard, when one section starts, the older one ends and so on.. editing will be piece-of-cake too, IMO :P

[SotSvart]

Exellent! I think this could work out fine.. Is there any protection against jerks that just want to f**k things up?

Is it possible to add the defult format code to the edit window when you open a new empty command? You could offcourse cut and past, but this would make life a little bit more easy..

[aetherfox]

I like this new wiki. I've neverh eard of it, I don't think, but it looks good. I'll start contributing soon.

I rekon all the fb tutorials should go on on this as well.

[urger]

Exellent! I think this could work out fine.. Is there any protection against jerks that just want to f**k things up?

If you ever encounter a vandalized page you can use the history tab to search the archives for the last non vandalized version and then reset the vandalized page to that one. The wiki stores all changes so removing them is realitivly trivial.

[urger]

Problem with the wiki at Freebasic.net, it won;t accept any members, throwing up an error that a username is not compliant with "wikiname" conventions.

[urger]

I've created a proposed style for the command references based on what others have been saying. http://freebasic.wikicities.com/wiki/Style_sample

[aetherfox]

The fb.net wiki doesn't want to accept me either...