My Go on the Cerberus X Documentation

Paul59

Active Member
CX Code Contributor
Joined
Dec 13, 2018
Location
UK
Code:
Function ShowMouse : Void ()
Shows the mouse pointer if the underlying operation system supports a mouse.

Shows the mouse pointer if the underlying operating system supports a mouse.
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
Thanks Paul.

Guys, I need your advice once more: Currently, examples are extracted from the "examples:" section in documentation, and what's between <pre> </pre> tags gets put into a .cxs file in docs/html/examples. So far so good. But (!) if an example section contains more than one <pre> block, everything between the first opening tag and the last closing tag is considered one example. E.g:

For
HTML:
<pre>
Print "Hello World"
</pre>

<pre>
Print "That's how you concatenate "+2+" strings"
</pre>
the resulting _example.cxs becomes:
Code:
Print "Hello World"
</pre>

<pre>
Print "That's how you concatenate "+2+" strings"
Which is obviously not valid CX code and could confuse CX beginners.

Now I consider these options:
  • Ignore, because there should never be multiple examples to one identifier
  • Only put the first pre block into an _example.cxs
  • Put both pre blocks into different _example.cxs

What do you think?
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
The interlink between them: cerberusdoc files can contain "Example:" sections. What follows these in <pre> </pre> blocks is written to docs/html/examples/WHATEVER_example.cxs. And my question was about cerberusdoc files having multiple <pre> </pre> blocks in one "Example:" section.

Edit
Just to be clear: That's a hypothetical question - no Cerberus X documentation .cerberusdoc file actually contains multiple pre blocks. But if they did, they would currently (existing Makedocs) behave as described above. I too think creating a separate _example.cxs per pre block is the best solution.
 

MikeHart

Administrator
Joined
Jun 19, 2017
Location
Germany
Just to be clear: That's a hypothetical question - no Cerberus X documentation .cerberusdoc file actually contains multiple pre blocks.
Mmmh, my framework fantomCX does just that. And for each pre section there is a code file build.
 

Paul59

Active Member
CX Code Contributor
Joined
Dec 13, 2018
Location
UK
Thanks Paul.

Code:
Print "That's how you concatenate "+2+" strings"
What do you think?
I realize you're not talking about that example per se but I'd present that line as:

Code:
 Print "This is how you join" + " two strings"
The reader may not know the word 'concatenate', it looks like three strings, it's not obvious what +2+ does and there's no hint about spacing :)
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
my framework fantomCX does just that
You made me download your framework, you prankster :D That's what I get for not being 100% clear. So let me try again:

I'm talking of multiple <pre> blocks in one single "Example:" section. That's nowhere to be found. Not even in your Framework - I just checked it: all 56 <pre> blocks are in a separate "Example:" section. :rolleyes:

@Paul59 : You're basically right. But worry not! I'm not going to put this example anywhere, it was literally just an example to show my point ;)
 
Last edited:

MikeHart

Administrator
Joined
Jun 19, 2017
Location
Germany
I'm talking of multiple <pre> blocks in one single "Example:" section. That's nowhere to be found. Not even in your Framework - I just checked it: all 56 <pre> blocks are in a separate "Example:" section. :rolleyes:
:p:p:p

Who would do that? I fail to see a purpose right now. But lately I say that things are not meant to be that way and boom, they are.
CX is surprising me every day :D
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
Thanks Dubbsta!

Who would do that? I fail to see a purpose right now.
You're right, I thought too far. You know what? I realised there's going to be a problem with multiple examples per example section anyway: The template only takes one ${EXAMPLE_URL} and Makedocs only provides one. So a second one would not show up. The good thing is when being the first to properly document a feature, you can help to define the feature ;) Means I'm going to write in the Makedocs help page that only one <pre> Block per "Example:" section turns out well.
 

Paul59

Active Member
CX Code Contributor
Joined
Dec 13, 2018
Location
UK
From 'Cerberus X naming conventions':

You are of course free to use your own convention, but for the sake of consistency it is recommended that this convention be used for the public interface of any modules you create intended for use by the Cerberus X community.

You are of course free to use your own convention, but for the sake of consistency it is recommended that this convention be used for the public interface of any modules you create which are intended for use by the Cerberus X community.
 

Paul59

Active Member
CX Code Contributor
Joined
Dec 13, 2018
Location
UK
I wonder if the the following has been addressed in the new docs (or perhaps I'm not using it right?), but I find it one of the most frustrating 'features':

When using Help->Index from Ted some entries have multiple copies and there's no way to figure out which is the relevant one - 'Compare' for example has 16 (!) entries.
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
That's a new feature meant to anti-frustrate: In the case of Compare, the old doccer just took you to one of those 16 entries. You can imagine how high the chances were that you were shown the correct one. The new doccer takes you to the index, where you can select the right entry. That's also why below the method/function name the scope is shown, so you find the corresponding one easily. Same goes for every method/function that has multiple possible meanings. Identifiers that are unique still take you to the right page immediately.
 

Paul59

Active Member
CX Code Contributor
Joined
Dec 13, 2018
Location
UK
That's a new feature meant to anti-frustrate: In the case of Compare, the old doccer just took you to one of those 16 entries. You can imagine how high the chances were that you were shown the correct one. The new doccer takes you to the index, where you can select the right entry. That's also why below the method/function name the scope is shown, so you find the corresponding one easily. Same goes for every method/function that has multiple possible meanings. Identifiers that are unique still take you to the right page immediately.
Sorry I meant maybe I wasn't using the old docs right (via Ted) - I've just looked at the new docs online via the website link and they are excellent, well done. Having these available from within the IDE will be great.
 

Holzchopf

Moderator
Joined
Jul 31, 2017
Location
Bern, Switzerland
Oh sorry I just realised I misunderstood you :oops: I thought you were talking about a the new docs and were wondering why it took you to the index when hitting F1 on one of those. Well, in that case I'm glad that I wasn't the only one unhappy about the Compare, Compare(1), Compare(2) etc. with no clue which one was which. So yeah, that one's definitely been addressed :D

And thanks btw!
 

Paul59

Active Member
CX Code Contributor
Joined
Dec 13, 2018
Location
UK
@Holzchopf Great work on the docs, it's much better from within the IDE :D

Not sure if this suggestion would involve too much work but an A-Z index along the top of each section with anchors in the document would be perfect!

helpindex.png
 
Top Bottom