Role of the wiki

[aplteam]

What exactly is the role of the wiki? Fully-fledged documentation or rather a kind of overview for the most important features?

That affects whether the run function should go into the wiki at all. Same for the messages stuff I've added today. For an overview this is too detailed I guess.

[PaulMansour]

I don't think there needs to be more documentation than the wiki. Everything should be there. We can add a page for the run function. What is the "messages stuff"?

[aplteam]

See the page "Session options"

[aplteam]

I am very much in favour of accessing detailed information about any acre command with

      ]??acre.{command}

Also, I don't want to depend on an Internet connection.

[norberturkiewicz]

This is off topic but I hate that Dyalog took a non-standard approach to the help command in their shell...

]acre.{command] -? or --help

would have been so much better and consistent with the world.

[aplteam]

I think that can quite easily be achieved although only as an option. I am going to suggest that.

I think -- could be reserved for user command-specific stuff.

On 30 January 2018 at 16:00, Norbert Jurkiewicz notifications@github.com wrote:

This is off topic but I hate that Dyalog took a non-standard approach to the help command in their shell...

]acre.{command] -? or --help

would have been so much better and consistent with the world.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/the-carlisle-group/Acre-Desktop/issues/52#issuecomment-361640111, or mute the thread https://github.com/notifications/unsubscribe-auth/APt0ndwm7YmZsPKCO3kQ7WResQiYBYiDks5tPzycgaJpZM4RvaV4 .

[PaulMansour]

I am very much in favour of accessing detailed information about any acre command with

That's fine. The Wiki should still be comprehensive.

[aplteam]

When people visit the acre-desktop "homepage" on GitHub they are likely to look at the ReadMe in order to get a general idea of what acre-desktop is doing. They might look at a number of pages in order to get an idea of what the (main) commands are doing, but that's most likely the extend of it.

When they start working with acre-desktop they are unlikely to want to go to the wiki for looking up details, they surely want to have such pieces of information available in the session.

For that reason I suggest to keep the wiki documentation simple, though it should certainly be enough to get somebody going. But when it comes to details like how to...

• fetch results of commands under program control
• hook into acre with the run method
• "redirect" messages normally printed to the session
• ...

then I would suggest to not blur matters by adding them to the wiki.

Ideally we should have one source for the documentation, but I cannot see how if we entertain both the wiki and the local help.

[PaulMansour]

Knock yourself out, and write all the docs you want.

[PaulMansour]

Ok, that was as little snarky, I didn't really mean that. ;)

[PaulMansour]

I thought you just wanted command help to spill into the session with you do ]command ? or something. You would like comprehensive help and documentation in the session? With GUI? And with the wiki being just an intro?

[aplteam]

]?Foo Gives just the syntax

]??Foo gives the help for that page

]???Foo shows the help page for Foo with the GUI.

And the wiki as an intro, yes.

On 31 January 2018 at 13:38, Paul Mansour notifications@github.com wrote:

I thought you just wanted command help to spill into the session with you do ]command ? or something. You would like comprehensive help and documentation in the session? With GUI? And with the wiki being just an intro?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/the-carlisle-group/Acre-Desktop/issues/52#issuecomment-361934339, or mute the thread https://github.com/notifications/unsubscribe-auth/APt0naOaVg1EruX7JaNqTbQRkn2B0B8jks5tQGzHgaJpZM4RvaV4 .

[norberturkiewicz]

Why not have acre command help point and open the wiki webpage?

You may not always be online... but how often is that really these days.

I didn’t try ]??acre.{command} yet but some summary help will be useful.

[PaulMansour]

Kai, what about things that are not commands? Do we need a full fledged help system?

[PaulMansour]

I was hoping Acre Desktop would be simple enough that the wiki would do. That may not be the case. Perhaps we need full fledged docs. If so, separate project? or part of Acre-Desktop?

[PaulMansour]

To answer the original question, "what is the role of the wiki"?, I don't really know. I started writing it to flesh out ideas and design. It morphed into quasi documentation as the design and implementation both progressed.

[aplteam]

If so then as part of acre. All the markdown files are then available within the project. They can be read and changed and searched, and the help system can be generated from that.

But you might be right that we possibly just need the ]??Foo part. Not sure.

[PhilLast]

Minimal at present but what we have currently is:

      ]?acre.CreateProject
Command "acre.CreateProject".                            

 Create a new project                                    
 Syntax: ]CreateProject folder space [codecase]          

Script location: "C:\Users\Phil\Desktop\acre\acre.dyalog"

      ]?acre.Erase
Command "acre.Erase".                                    

 Erase an item or items from an open project             
 Syntax: ]Erase item(s)                                  

Script location: "C:\Users\Phil\Desktop\acre\acre.dyalog"

Is doesn't distinguish between ?, ?? and ???.

We also have the syntax for most commands given no argument

      ]acre.changes
Syntax: ]Changes project-space | item