DOCUMENTATION REVOTE

[lillo]

The registration problem happens if you try to register to the wiki using a name with a single word... It seems you must use two words for it to work; by myself "Lillo" didn't work (same as what happened to you: didn't comply with namewiki standards), but "LilloWiki" did the job.

[Antoni Gual]

Just an idea..

v1ctor: You are not writing docs because you feel not fluent in english.
Perhaps you are writing everything down in portuguese....and in a computer.
If this is the case perhaps we could borrow your notes and translate them....

[urger]

Hmm, it seems to be rejecting all of my attempts to sign up :-s

[rdc]

In the value tags, what values should we use? Also, how should the structure be set up? Is it going to be broken up into Functions-Statements-GfxLib, etc? It might save some time and be a little more clear if you set up the structure with all the keywords organized the way you want them pointing to blank pages.

That way there will be consistent value tags and a consistent structure, and we won't miss keywords that may be new and not listed anywhere. I'm sure you could write a little prog to take your lexicon and spit out what is needed I would think.

[rdc]

Let me clarify the value tag issue: There are some keywords that may be both functions and statements, such as screen and mid. What convention should be used? Just lump them together into the same topic? Or make two entries, one for the function one for the statement?

[Jofers]

Well, I have the draft table of contents at:
http://freebasic.wikicities.com/wiki/Table_of_Contents

and a draft keyword page at:
http://freebasic.wikicities.com/wiki/Bload

urger made a style draft here:
http://freebasic.wikicities.com/wiki/Style_sample

This is something we should agree on before making (or converting) any docs.

For keywords that are both statements or functions, or have multiple meanings in different contexts (get/put), there should simply be two pages.

[urger]

Let me clarify the value tag issue: There are some keywords that may be both functions and statements, such as screen and mid. What convention should be used? Just lump them together into the same topic? Or make two entries, one for the function one for the statement?

I like the idea of three seperate entries, one being Command(Statement) and the other being Command(function). Then third would be just Command, which would be a disambugation page with a link to both the statement and the funtion pages and nothing more.

I'll set up an example of this as soon as I get back from my next final.

[v3cz0r]

Yeah, that wiki script while easily extendable is pretty restrict with names, you must registry following its CapitalCapital convention, so your nick can become a reference and a page too.

The {{fbdoc}} is just to make parsing easier later to convert to other formats (wiki->xml->anything else), they will mark whem one section starts and they don't have to come in some predefined order (but we must follow one, course), and are optional.

All page names must follow the CapCap style, so the keywords tag is a bit more complex, the value field must contain the real page (KwDefine for example) and the keyword name (#DEFINE), separated by a | (yeah, too much PHP :P).

Access to pages can be controlled with that wiki script, so i could add only who is part of the doc team to have write access to them if people start to vandalize pages. They could only post comments then.

FB functions can be used as statements (if you were talking about say SCREEN as statement, not about the compound ones, for example) and some statements like OPEN/GET can be uses as functions, i don't know if putting them in different sections would be better.. or if we should do like the QB quick help, listing everything on a single section, but separated by category.

No, i didn't write anything in any language, translating would be even more difficult and i hate to write comments in portuguese, they are always too long ;).

If the format is okay, i will write the script to load that wiki with Nex's docs - that's what i've atm. You can then transfer what was done in XML or CHM, and updating what is missing.

New sections can be created then, sorted alphabetically, and so on, KeywordsList will be pretty much the gfxlib/Nex format, everything else can follow their own formatting.

[rdc]

The format looks fine to me and I think easily lived with. As far as the dual nature of some statements, I looked over the VB help and Delphi help, and the consensus seems to be to create two pages, one for the statement, one for the function. Using the mid example, VB has a single page that has links to the two different pages. Maybe in the keyword list, there is simply something like:

Mid
* Statement
* Function

With statement or function going to the appropriate pages. Not sure how that would work with the parsing later down the road.

[Jofers]

I'm all for making an index similar to the quickhelp one, with pages titled "Keyword statement", "Keyword function", etc.

Vic, I'm having trouble organizing the table of contents over. You can cut from one section to the next, but how do you nest? Can there be an end marker for sections, for when it's needed... So that when the parser hits an end marker, it can shove everything since the last section into a child section, allowing for nests?

example:

Code:

{{fbdoc item="section" value="parentitle"}}
stuff in parent

{{fbdoc item="section" value="childtitle"}}
stuff
morestuff
{{fbdoc item="endsection"}}

{{fbdoc item="section" value="nextsection"}}

this would all be interpreted as:

Code:

PARENTTITLE
    stuff in parent

    CHILDTITLE
        stuff
        morestuff

NEXTSECTION

This isn't for keyword pages, but rather every other page in the doucmentation, namely link pages and articles (such as those describing operators, etc).

Also, how do you want to organize articles, such as pages describing operators, procedures, pointers, arrays, the compiler, history, etc? Should there be a general layout (intro, body, etc) or just type as you see fit?