collapse collapse
* User Info
 
 
Welcome, Guest. Please login or register.
* Search

* Board Stats
  • stats Total Members: 989
  • stats Total Posts: 18366
  • stats Total Topics: 2501
  • stats Total Categories: 7
  • stats Total Boards: 35
  • stats Most Online: 1144

Author Topic: Help Files  (Read 5449 times)

0 Members and 1 Guest are viewing this topic.

Offline Visceru

  • BeBot Rookie
  • *
  • Posts: 10
  • Karma: +0/-0
Help Files
« on: June 18, 2007, 10:50:09 pm »
I notice in the patch notes that the custom/help folder has been added, and in the docu-wiki it's mentioned that help files are now all internal to the PHP modules through the $this -> help[] array.

Firstly, what lead to the decision to put the online documentation into the php files?  I intend to document all the commands properly for a guild of users that wants to migrate from IGN.  Documentation is by far the primary reason they are still using IGN, and they require a real level of online help for people new to chat bots instead of the meager user help BeBot currently has.  As it stands, I can add all the documentation I want to the PHP, but then it all gets overwritten and deleted when a new version of the bot is released.

An alternative would be that I get involved with the development and contribute docs to the SVN.  But I was hoping to elicit help from a couple of other friends in writing the text.  They aren't programmers and wouldn't be comfortable editing string values in the help[] array.


So that brings me to my second question. :)  Are you planning to use the custom/help folder (or a root/help folder for that matter) at all in the future?  I notice there isn't any code in the bot currently that reads from it.  What kind of format might be used if it were?  Any chance of an .xml file per module? I think it'd be better to separate documentation from code.  It'd also be fantastic if people implementing these modules would document them for the bot's online help instead of pointing people to the wiki, or even worse, just leaving the help regurgitating "no help found" for everything.

Offline Alreadythere

  • BeBot Maintainer
  • BeBot Hero
  • ******
  • Posts: 1288
  • Karma: +0/-0
Re: Help Files
« Reply #1 on: June 18, 2007, 11:31:36 pm »
There are currently no plans to move back to external help files. The custom/help/ folder was just a relict that didn't get removed yet.

We moved to a new help system because it was more files to keep up to date, reading outside files could offer potential security problems, and linking between help for one command and any alias it might have would require two files, as windows doesn't support any soft linking. Besides, for most commands there was no current help anyways, so changing the system resolved in not much new work. And with the new help system the formatting is the same for all help output.

You are more then welcome to help us with the help for commands. Even your friends without any php experience can help, just have them write the help as unformatted text, and insert it into the help array via copy and paste.

Most modules should have at least basic help already in SVN.

Offline Visceru

  • BeBot Rookie
  • *
  • Posts: 10
  • Karma: +0/-0
Re: Help Files
« Reply #2 on: June 19, 2007, 12:33:04 am »
Thanks for the reply.  I agree that unifying the help file format is nice. I'll have a think about getting to work. It'll be some time before I get the chance to do much, but nice to know all this.

In the meantime I hope any new features added are being documented in the online help by everyone adding them! :)

Offline Vhab

  • Contributor
  • *******
  • Posts: 180
  • Karma: +0/-0
    • VhaBot Forum
Re: Help Files
« Reply #3 on: June 19, 2007, 06:47:10 am »
If you're really uncomfortable with writing them into the plugins, you can always just write the help text, post it on the forums and wait for one of the code monkeys to pick it up and commit to svn :P

Offline Visceru

  • BeBot Rookie
  • *
  • Posts: 10
  • Karma: +0/-0
Re: Help Files
« Reply #4 on: June 25, 2007, 09:11:19 pm »
No no I'm a coder myself, I'm comfortable with the mechanics, just not so much of the idea.  Although I see the logic of putting it in there, and understand the decision to do so, it goes against my desire for a few reasons.

One reason is for localisation.  I would prefer the docs to be seperate to allow the whole documentation to be localised into different languages easily.

But my main reason that I've decided I won't be contributing to the SVN is because the documentation I write is all in character (IC), and thus is not appropriate for the majority audience of BeBot.

For instance, here's an excerpt from the afk command:

AFK:  "Allows you to flag yourself as being away from your comlink.  The AI will increase security on incoming messages, locking any would-be request and notifying him or her that their transmission has been scrambled and will be unheard by you."

Thus, every single module, whether modified in function by me or not will have to be overwritten with one in the \custom\modules folder, as every command needs documentation.  And then every time the bot gets updated I will have to check whether the files have actually changed, and rewrite all my docs into the custom folders.

So....  Lots of work :(

 

* Recent Posts
Com bot module by bitnykk
[November 25, 2024, 05:36:11 pm ]


0.8.x updates for AO by bitnykk
[June 23, 2024, 03:19:47 pm ]


0.8.x updates for AoC by bitnykk
[June 23, 2024, 03:19:44 pm ]


[AoC] special char for items module by bitnykk
[February 09, 2024, 09:41:18 pm ]


BeBot still alive & kicking ! by bitnykk
[December 17, 2023, 12:58:44 am ]

* Who's Online
  • Dot Guests: 89
  • Dot Hidden: 0
  • Dot Users: 0

There aren't any users online.
* Forum Staff
bitnykk admin bitnykk
Administrator
Khalem admin Khalem
Administrator
WeZoN gmod WeZoN
Global Moderator
SimplePortal 2.3.7 © 2008-2024, SimplePortal