Documentation project for PureBasic?

[Dräc]

Ok.
I have “finished” the first issue of Part 2

In each page of this issue, you can find:

- an synthetic overview thanks to the box at the beginning of the page.
To be synthetic, this box can contains examples
- following a definition and explanations
- Important precisions and remarks are distinguish from the rest of the text for a quick localisation.
Thus, it is easy to add items at this place (used of == chapter == tag)
- Some links are embedded, used to connect pages and notion together. It is a feature to insure the minimum of redundant information.

The particularity of the approach adopted to write this part, consists into exposed that a constant is not rigorously something like #Pi, but every number or real or string you can write.
# notation is used with variable just to indicate to the compilator that the variable value doesn’t change…

This consideration explains the TOC of Part2.

Don’t by afraid about color or style, it is just a first example to illustrate some dispositions.
For example, it is important to distinguish the different remarks. The current disposition is to used background color delimitation.
I hope that one of use have good design capability to improve this!

Actually, I search the mean to upload images (just for test, not too much) and hide/show feature as TOC object does.

By doing this exercise, I have some remarks:
Are you interesting about defined a common
- Layout according to the context?
- Template and style?
I meet problem into mixing a template and table, when the table is part of the argument.
Therefore some remark structures are not homogeneous in the current issue.

Rq1: I write this here, because I haven’t yet a logon to the PureBasic Documentation Project area.

Rq2: Finally, because my English is far to be perfect, some sentences could be improved.
Wiki project it is a good exercise for me to improve my English…

[Blade]

- I like the box, very useful when explaining concepts, don't know if is needed in reference pages.

- Great usage of templates too, this way, editing the style will be so easy.

- Embedded links are a must for this kind of projects!

- My english is not so good too, despite I've fixed something from Fred and you , I really can't make long phrases without "loosing focus"
... like now...
Let's hope more people will join this nice project...

[Dräc]

Following two suggestions from Comtois:

The used, at the top of the article, of the template ArticleOnSeveralPages to provide Previous/Next pages access.
An example is done for Part 2

The used of Geshi for syntax highlighter in code examples.
The official site: http://qbnz.com/highlighter/
An example of code Syntax Highlighter definition is already in-build at this location:
http://www.games-creators.org/wiki/Source:Pb.php
I think, it is a good idea. If you are ok too, it is up to Andre to upload the Geshi features to the project…

All these inspirations come from a great french site called Games Creator Network (http://www.games-creators.org/index.php) using the wiki technology too.
Certainly, people know such other site, which can be a real source of ideas…

[Dräc]

My previous post illustrates that some people are motivate to contribute to the documentation project, if several translations of the documentation were supported.

For example, Comtois and Prog1984 for the French version.

What I’m proposed is to include the multilanguage management in the current and future pages.

First, understand how to manage differents language with MediaWiki

Than, translate current english articles into each desired language (German, Italian, French …)
After, pertinent remarks / articles can be written in a language other than English in order to be incorporated in English articles too!

Then, we can status that English should be the official language, but that an article can beneficed from other contributors that english writers, no?

What are your position about that ?

[Blade]

Geshi is a great idea. The coloring will be automatic, right?

My previous post illustrates that some people are motivate to contribute to the documentation project, if several translations of the documentation were supported.

Isn't Games Creator Network only in french?

After, pertinent remarks / articles can be written in a language other than English in order to be incorporated in English articles too!

I don't understand. Let's take the german forum. If some kind german people don't post in this forum stuff taken from there, I will never know if they post a great example or are talking about important things...

Back to us.
Really someone will translate all the french/german/etc pages in the english version?

[Dräc]

Geshi is a great idea. The coloring will be automatic, right?

Yes, once the definition file defined, the coloration is automatic!

My previous post illustrates that some people are motivate to contribute to the documentation project, if several translations of the documentation were supported.

Isn't Games Creator Network only in french?

Motivate people comes from the french forum of PureBasic

After, pertinent remarks / articles can be written in a language other than English in order to be incorporated in English articles too!

I don't understand. Let's take the german forum. If some kind german people don't post in this forum stuff taken from there, I will never know if they post a great example or are talking about important things...

Back to us.
Really someone will translate all the french/german/etc pages in the english version?

Ok, I know that is perhaps illusive to have a coherent documentation in several languages.
But, my idea is the following:

If the different versions adopt the same TOC, it will be easer the connect pages together.

I think it is the minimum that can work!

Next, we can also adopt the same page structuration.

[Blade]

If the different versions adopt the same TOC, it will be easer the connect pages together.

Yes, this is a must.

[Dräc]

After discussion, contributors for a french version are in agreement with the presented approach (a common TOC).

[Dräc]

To dispose of different translations, if I understand the documentation, the solution is simple:

It consists to provide links between each version of a page according a common banner in the page.
The only condition to perform this, it is to distinguish each version of an article by the title (of course ).
Because a possibility exists that a title can be the same for different versions of an article, the documentation proposes to add a target according to the language.
(de) for German, (it) for Italian, (fr) for French…

For example the article named “Variables” in English have the same name in French.

Thus, three possibilities:
1- The more easy (but not esthetical): add the target at the end of the title. This target appeared also un the title.
Ex: for French, “Variable (fr)” or “Variable_fr”, etc…
2- The more pratical and esthetical: to benefit of a special code according to the language which is not displayed in the title.
For example, for French versions, the link should have the following format [[fr:Variables]] for a final shown title: « Variables ».
But apparently, that need to install a special feature and I don’t know if it is available for MediaWiki system (but works on Wikipedia ).
@Andre: do you think it is possible and easy to perform that solution?
3- Or simply to provide sub-directories: de/, en/, fr/

Here the two links dealing with the two solutions:

http://meta.wikimedia.org/wiki/Meta:Interlanguage_links

http://en.wikipedia.org/wiki/Wikipedia: ... uage_links

[Andre]

I can't see any more progress on english & french sites of PureWikithe last weeks.
Come on guys!

Comming from german PB community there was formed a "German PureBasic DokuTeam" where the members are writing on a large Wiki book "PureBasic for beginners" (german).

Myself I've added already a lot of the english PB manual (library command descriptions) - see Part 11 on the main site index. Rest of english additions as well the german & french sites must still be done. Any help is welcome!

For this I've written an output module for the PB DocMaker to get PureWiki compatible command descriptions. Download archive as well other actual news you can see on the Current Events page.

[koehler]

Wow, that sure died quick. Bummer, maybe jumping to 3 languages wasn't the best way after all?

[dell_jockey]

How do I get on board?

[Andre]

Wow, that sure died quick. Bummer, maybe jumping to 3 languages wasn't the best way after all?

No, 3 languages aren't too much. At least the german Wiki is growing a lot.

How do I get on board?

Everyone can take part on PureWiki.
There is already a index on the main site. From that it's easy to write new articles.

It makes sense to to register an account if you're regularly writing.

[DevilDog]

I started to read this thread but it's quite long.

The wiki idea makes the most sense. Was that what was decided?

If so, I think the problem may be that not enough people know about it.

So what's the solution to making sure it's always visible?

How about making a new topic in the forum specifically for the Wiki documentation?

This way it's always visible at the highest level to forum visitors and will encourage people review/contribute to the Wiki.

The main PB website should also have a link to the Wiki site.

[Amiga5k]

As documentations go, PB's is not the worst I've seen (BlitzMax's is really bad...), but may just need to be re-organized a bit with lots (at least one for every command) of example code. Tutorials are very helpful, too, and many more should be included in the standard distribution, IMHO.

Using a "I've never used ANY programming languages" approach in a "User Guide" can help get the user up and running, while the Reference Manual would delve deeper into the how's and why's of the commands. It's an approach that I've always found most useful.

The only "problem" I have with the wiki is that you would have to be online to read it (although a stand alone version could be created on a periodic basis - say every few months or so).

Any talk of improving the documentation is welcome, though.

Russell