• Dear Cerberus X User!

    As we prepare to transition the forum ownership from Mike to Phil (TripleHead GmbH), we need your explicit consent to transfer your user data in accordance with our amended Terms and Rules in order to be compliant with data protection laws.

    Important: If you accept the amended Terms and Rules, you agree to the transfer of your user data to the future forum owner!

    Please read the new Terms and Rules below, check the box to agree, and click "Accept" to continue enjoying your Cerberus X Forum experience. The deadline for consent is April 5, 2024.

    Do not accept the amended Terms and Rules if you do not wish your personal data to be transferred to the future forum owner!

    Accepting ensures:

    - Continued access to your account with a short break for the actual transfer.

    - Retention of your data under the same terms.

    Without consent:

    - You don't have further access to your forum user account.

    - Your account and personal data will be deleted after April 5, 2024.

    - Public posts remain, but usernames indicating real identity will be anonymized. If you disagree with a fictitious name you have the option to contact us so we can find a name that is acceptable to you.

    We hope to keep you in our community and see you on the forum soon!

    All the best

    Your Cerberus X Team

My Go on the Cerberus X Documentation

Holzchopf

Well-known member
3rd Party Module Dev
Tutorial Author
Joined
Jul 31, 2017
Messages
500
Well hello to everyone!

I "allowed" myself to fiddle around with the Cerberus X documentation a bit. So far, I almost exclusively molested the language reference:
  • Added all hierarchy levels to the contents (for quick access)
  • Since the Contents are now longishly, they automatically split up into convenient columns)
  • Added headings for many categories (e.g. Literals of every Type, String and Array Methods, Property Methods etc)
  • Split the chapter Programs and declarations into two
  • Updated the Strict mode chapter as it falsely stated that in strict mode, all function calls need brackets, which is not entirely true (i.e. Print "I don't cause trouble" works fine)
  • Added chapter Literals
  • Added a table of data types to the Types chapter also including the short notation for types
  • Rearranged the type sub-chapters so they all follow the rule "type description", "special functionality", "type literals"
  • Added chapter Character literals
  • Made it absolutely clear that the table with the operators is actually in order (precedence)
  • Turned the list of assignments into a more convenient table
  • Added chapter Asset import (I think it's at the right place, since this language feature overloads the functionality of the Import keyword)
  • Added chapter Custom preprocessor directives
  • Added chapter Optimisation (I strongly believe this is a language feature and therefore should be placed in the language reference)
  • Added chapter I've seen... for strange syntax sightings (I mean, what do you search for in the docs when you see <T> in a code and have absolutely no idea what this is?)
  • Added Glossary (alphabetical index of all cue words I could think of or imagine someone else trying to learn Cerberus X could think of)
  • Turned a lot of "please see chapter XYZ" into ACTUAL CLICKABLE LINKS
  • Harmonised a lot of phrasings and/or formatting

I also touched the Home page, where I added a link to the Key codes reference.

And I improved the Resource paths reference by introducing the section about what the app's data directory actually is (so far, this is only mentioned in the Trans reference).

I upload them here, so you can already have a look. Extract the files to
Cerberus/docs/cerberusdoc/Home.cerberusdoc
Cerberus/docs/cerberusdoc/Programming/Resource paths.cerberusdoc
Cerberus/docs/cerberusdoc/Programming/Language reference.cerberusdoc
and rebuild the help to see what I've done. You can back-up these files before you overwrite them if you wan't.

I will look at the other chapters too. My goal is to put an updated documentation to the git repository once we're happy with the result.
 

Attachments

  • Language reference.zip
    23.6 KB · Views: 314
Dawlane has made changes already in his version which I want to implement. Did you take them in too?
 
I don't think so, I just worked on the files from the last official release... Where do I find his files? I'll look how they merge.
 
Thanks for checking! I'm glad there are no collisions =)
 
I think the documentation's Home page should be more appealing. For a landing page, I find it a bit too chaotic =/ I'm OK with all the Modules, Classes, Interfaces, Functions... pages just being alphabetical lists. But IMHO the Home page should use a tabular layout that also describes a bit what hides behind a link (a bit like the API reference). I.E:
Target SDKs | The build targets Cerberus X can handle and how to set up the necessary tools
API reference | Overview of the functionality of Cerberus X's standard APIs
File formats | Availability of different file formats for Cerberus X targets

and so on.

Any thoughts (before I get creative)?
 
Me too. I was also thinking about improving the docs, but because I am a german native with just a little experience in Cerberus I ditched it.
I was used to PureBasic docs and Cerberus aka Monkey docs were really annoying. So here are my thoughts:
- Get rid of those endless lists of things you only find, when you allready know the name: No Modules, Classes, Interfaces, Functions,Index
- Give the apis Link an other name: Call it 'Modules', because what you find there is a List of Modules with an Explanation of usage.
- Explain the term 'Module' on the start page as 'a package of built in functionality' or similar.
- I would go for a menu containing: Getting started, Language Reference, Modules(=old apis), Tutorials and Links
- Easy to spot links to the startpage of the docs and to the cerberus website.

It would also be nice to have a possibility to highlight important lines of code in the examples to distinguish the important stuff from the necessary boilerplate code you need for a runable example.

Maybe I can help a bit by writing simple examples for missing stuff. So tell me the topic and I write a minimalistic example.

To make things easy: Could you put a updated version of the docs online, so we don't have to mess with our own lifesaving docs ;-)
 
I read through your changes and find a lot of useful stuff in it. Now I think it is definitely time to split the Language Reference into multiple pages.

For the Explanation of the functions or methods I prefer the layout like in menu 'functions' when clicking on a link there, where you find the description right under the framed syntax. The table layout just doesn't work because of the big varieties in the width of the syntax phrase.
 
Good inputs, Phil! Actually the function and method descriptions for String and Array, as they are in the language reference right now, are somewhat redundant. You find lists of them in the keywords reference, when you open the String and Array pages. But there it's again just a list in which you only find what you're looking for if you're able to guess the name of the function you're looking for. To make the tables explaining the functions or methods a bit "nicer", I could imagine shorten the Method / Function column to just the method or function name (plus make it a clickable link to the corresponding docs).

So instead of
Code:
Method Length() Property | Returns the number of characters in the string.
it would just be
Code:
Length | Returns the number of characters in the string.
With "Length" being a link to to cerberus.lang/string/length

To make things easy: Could you put a updated version of the docs online, so we don't have to mess with our own lifesaving docs ;-)

Good idea! Will do that.
 
Btw: How do you edit the docs? Wich editor do you use?
 
Has anyone an idea what this "3rd party modules" is and how it's supposed to work? I think I could work it out by reading through (yet another un-documented source, yay) makedocs.cxs. But that's not going to happen soon.
 
OK I think I found it out just by accident. Apparently we're supposed to put our module documentations in a folder called "3rdparty.cerberusdoc" instead of "cerberusdoc", so they're listed in the "3rd party modules" page. As it clearly STATES FUCKING NOWHERE IN ANY KIND OF DOCUMENTATION FOR G*DS SAKE.

Also, if you put a .png file named yourmodulename.png, that will make an icon linking to yourmodulename in the header section (so yeah, on every page).

Do we get rid of this
2l8ef5.jpg

called "3rd party modules" documentation?

I haven't seen anyone ever using this 3rd party docs thing. Or the icon link feature - which I believe should not exist; no 3rd party module can be that important to get an always-accessible icon link.
 
And who on earth wrote makedocs? I guess a guy called George since the (basically THE) makedocs class is called George. You're trying to find any helpful comments? HA! But oh guess what nice thing I found instead:
Code:
        For Local it:=Eachin indexcats
            ...
            Local index:=it.Value
            ...
            For Local it:=Eachin index
                ...
            Next
            ...
        Next

The same index variable name USED TWICE in nested loops!

Let me show how to properly comment this mayhem:
Code:
        For Local it:=Eachin indexcats
            ...
            Local index:=it.Value
            ...
            For Local it:=Eachin index ' HAPPY DEBUGGING, SUCKERS!
                ...
            Next
            ...
        Next

I am SO disappointed right now. Not because of the quality of that source... but because I'm tempted to improve stuff like this - but I don't have the time for that.
 
pyro.png
3rd party modules = Playniax modules like Ignition X or Pyro for example. When MonkeyX and/or Playniax modules got often updated it was convenient to be able to store 3rd party modules and their docs in a special place. And to be able to access to those modules'doc by clicking an icon was convenient too.
 
Last edited:
So it's mainly thought to be used for "frameworks" and not every 3rd party module? Convinced. As apparently no one overuses this.
 
Back
Top Bottom