My Go on the Cerberus X Documentation

[Paul59]

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]

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

<pre>
Print "Hello World"
</pre>

<pre>
Print "That's how you concatenate "+2+" strings"
</pre>

the resulting _example.cxs becomes:

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?

 

[MikeHart]

Last one.

 

[MikeHart]

But.. are you talking about cerberusdoc files or the created html files?

 

[Holzchopf]

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]

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]

Thanks Paul.

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:

 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]

my framework fantomCX does just that

You made me download your framework, you prankster 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.

@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

 

[MikeHart]

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.

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

 

[Dubbsta]

docs are looking good! thx!

 

[Holzchopf]

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]

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.

 

[Holzchopf]

I can note that for a future update. Is the former sentence too unclear or is the wording not correct?

 

[Paul59]

I can note that for a future update. Is the former sentence too unclear or is the wording not correct?

Just needs those two word added I think

 

[MikeHart]

I can note that for a future update.

Done!

 

[Paul59]

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]

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]

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]

Oh sorry I just realised I misunderstood you 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

And thanks btw!

 

[Paul59]

@Holzchopf Great work on the docs, it's much better from within the IDE

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!