Collaborative Effort - Ruby Template, RDoc, and Localization

thomthom

Purely my bias, but I'd lean toward the RDoc comment style. Either way, this looks extremely helpful!

I'm in favour of using an existing method of documentation.

scottlininger

Using RD or RDoc style would be more consistent with the =begin/=end usage (rather than using it for block comments). Something like this?

Exactly. I didn't run this though RDoc to see the output, but my point is that RDoc is the closest thing to a docs standard that I'm aware of. Might as well build something that could be run through RDoc and give sensible output.

Now you should extend the template list and build a Ruby plugin wizard! (only half joking.)

thomthom

This is shaping up good.

I'm wondering, for the changelog, does the RDoc have a syntax for lists? Just thinking there's something that might denote a list item. I don't find enough space on one line to describe a change some times. I've up til now used a * to indicate list items.

Like this:


# Changelog
# 1.0.0 - 13.12.2008
#       * Select Active Instances
#       * Select Instances
#       * Select Active Group Copies
#       * Select Group Copies
#       * Convert Group Copies to Instances
#
# 1.1.2 - 16.12.2008
#       * Select Loop from edge

If the description breaks to another line the * makes it clear when the next item starts.
So if there's an RDoc syntax for this I suggest we use that.

Also, in addition to SU version, OS Platform is useful as some scripts works only on either Mac or PC.

And, I'm wondering if it's worth to include a Webdialog engine, since some plugins fail due to the user having an old IE version installed. (Not sure how it's on OSX. The rendering engine is webkit, right? but does it change if you update Safari?)

RickW

@thomthom said:

I want to have a look into how easy it is to reliably extract plugin data in regards to auto updaters etc. Maybe include an compatible list, a list that states which SU version it's compatible. And optionally, and list of plugins that might be incompatible with?

It should be straightforward, using a regexp to parse the file. The fields are known (that's the point of this exercise), so writing a parser should be easy. The challenge, IMO, is to keep it easily human-readable, while allowing machine readability.

@thomthom said:

What I'd like as alternative for the text is where it's allowed to copy, modify and distribute for non-commercial use. I'm not really sure how it's best phrased these sort of things.

I'm not an attorney, but this might work:
Permission to use, copy, modify, and distribute this software for noncommercial purposes and without fee is hereby granted, provided that the above copyright notice appear in all copies. Commercial distribution, in whole or in part, is expressly prohibited without the expressed, written consent of the author.

Edited per Gai. I found both "express written" and "expressed written" online, didn't know if one was more correct for legal jargon.

RickW

There is a list syntax. See the RDoc docs for more info.

todd burch

I'm on this like a Hobo on a Bologna sandwich.

Get your requests in now, during the early design stages. We're gonna have a GUI!!!

Stay tuned. Todd

RickW

Developers,

Please note that the menu information is also part of the template, designed to function with Organizer.rb (even though Organizer.rb is NOT required for the menu to work).

If you choose to not use this menu template, please also remove the top line of the header "# Supports Organizer.rb". Otherwise, users trying to use OrganizerEdit to make your work compatible with Organizer will not be able to do so. Then I'll get support requests, and I'll have to forward them on to you to fix the issues

Here is the documentation for creating Organizer-compatible menus (though the work has already been done in this template)

RickW

I'm considering adding this to the ruby template, but wanted to get input. After a rather infamous incident recently, I thought about easing the localization effort for menus, and came up with this:

create a "menus" subfolder in the Plugins folder (to keep things tidy)
in that folder, create a text file with the same name as your .rb file, with the extension ".menu" and put each menu item text string on a separate line, like this (the submenu, submenu2, etc names are only to illustrate where they are in the menu structure for this particular example):

context menu label
submenu label
submenu item label
submenu2 label
submenu2 item1 label
submenu2 item2 label
submenu2 item3 label
submenu2 item4 label
submenu2 item5 label
submenu2 item6 label

# This file may be translated for localization

use the following example code to read the lines from the .menu file into your menu structure:

unless file_loaded?(__FILE__)
	file_loaded(__FILE__)
	menunames = IO.readlines(File.dirname(__FILE__)+"/menus/"+File.basename(__FILE__, ".rb")+".menu").collect{|x| x.chop}
	UI.add_context_menu_handler do |menu|
		menu.add_item(menunames[0]) { code }
	end
	$submenu ? (organizer = $submenu) ; (organizer = UI.menu("Plugins"))
	submenu = organizer.add_submenu(menunames[1])
		submenu.add_item(menunames[2]) { code }
		submenu2 = submenu.add_submenu(menunames[3])
			submenu2.add_item(menunames[4]) { code }
			submenu2.add_item(menunames[5]) { code }

			submenu2.add_separator

			submenu2.add_item(menunames[6]) { code }
			submenu2.add_item(menunames[7]) { code }
			submenu2.add_item(menunames[8]) { code }
			submenu2.add_item(menunames[9]) { code }
end

This particular example does everything except submenus and separators for the context menu.

As I see it, this will make localization a breeze, since someone only has to translate the .menu file, which is plain text. It also eliminates copyright problems, since the code is unchanged.

Thoughts?

thomthom

So use user completely replaces the menu language file?

Just wondering about packaging. What if you want to include multiple language packs? (Or maybe this isn't the scope for this? This is purely a bare minimum way of allowing localization?)

todd burch

I smell a good application for an XML file.

todd burch

Maybe something like this:


<?xml version="1.0" encoding="UTF-8"?> 
<menufile>
	<mainmenu name="Tools">
		<item>My Ruby Script V1.0</item> 
		<submenu text="First Submenu">
			<item>Function 1</item>
			<item>Function 2</item>
			<sep/> 
			<item>Function 3</item>
		</submenu>
		<submenu text="Help">
			<item>Contact Author</item>
			<item>User's Guide</item>
			<item>YouTube Video</item>
		</submenu>
	</mainmenu>
</menufile>

RickW

@thomthom said:

So use user completely replaces the menu language file?

Just wondering about packaging. What if you want to include multiple language packs? (Or maybe this isn't the scope for this? This is purely a bare minimum way of allowing localization?)

Someone replaces the contents of that file, yes. As far as Smustard goes, my goal is to have all our menu items converted over, and users could download "language packs" of the whole library of .menu files for their language (we'll see how quickly that gets done).

My goals in leaving it plain text is that it is most accessible (IMO) that way and it requires the least amount of processing in the ruby script, but there might be drawbacks. Input is definitely welcome.

Obviously, for other authors, the issue is slightly more complicated, but only slightly. Each menu file could be appended with the proper country extension (for example, "myrubyscript-de.menu", "myrubyscript-mx.menu", "myrubyscript-enUS.menu" etc) and then the user removes the extension for the one they want to use ("myrubyscript.menu"). For Windowizer4, I tried making it automatic based on the SU-reported locale, but that was not reliable and so most users ended up renaming the .html file anyway.

thomthom

I see. Very interesting that integration with your site.

While I'm positive to the XML format, my vote still goes to plain text as it'll be more understandable for more people.

However, I'm wondering if the menu folder would have a set of subfolder for each language, so the users could switch between. I'm thinking in regards to the cases where there might be multiple people using a computer with different language preferences.


menus
  + en
  + no
  + fr

Aidus

I wonder why people need such things

thomthom

@aidus said:

I wonder why people need such things

Why people need/want the UI in their own native/preferred language?

tomot

@rickw said:

I'm considering adding this to the ruby template, but wanted to get input. After a rather infamous incident recently, I thought about easing the localization effort for menus, and came up with this:

I have certainly benefited from looking at your coded Rubies, which have allowed me to mimic procedures for developing a bases upon which I was able to develop my own Rubies for distribution freely to his SU forum.
That being said, I feel since Google bought SU. We have been more or less a rudderless ship. With each Ruby developer taking his or her own approach towards developing more advanced GUI solutions, under the Ruby umbrella.
I applaud your efforts towards bringing some order to the Ruby script writing chaos. I also see you have taken it upon yourself to direct a task which I think should be directed by SU Google staff.

But it appears they are again missing in action. Unless perhaps via private email you have their blessing in this endeavor.

We also had a few weeks ago a new young gun who was offering to implement a new GUI within SU using the Python as a second scripting language. I looked at that thread through different eyes then those that responded, by dismissing it outright. As a result of a few negative comments his alternative solution was shot down by a few SU forum members.

Again not a comment for or against was posted by SU Google staff.

I don't know where Google wants to take SU. It would certainly be refreshing to get some direction from them.

BTW: don't shoot the messenger, please!

RickW

@tomot said:

I applaud your efforts towards bringing some order to the Ruby script writing chaos. I also see you have taken it upon yourself to direct a task which I think should be directed by SU Google staff.

But it appears they are again missing in action. Unless perhaps via private email you have their blessing in this endeavor.

Actually, Scott Lininger did provide input on the template file. I do know from private correspondence that they are very busy on some things and may not be responding as much as they would like, and hope Scott will have some time for input on this as well.

But yes, it is a rather self-appointed task

I've thought about the xml vs. plain text issue. I suppose a standalone menu-generating script could be required and then called to create the menus by parsing the xml (which would need a <code> section added to Todd's example, I think). The drawback to me is that it becomes one more thing to write, distribute, support, and incorporate in the script, in addition to the extra menu file/s (which bothers me as well, but what do you do?). The benefit is that it clearly delimits each field's function.

Jim

FYI, I merged the thread about menu localization into this thread.

thomthom

I was thinking, if the plugins where made using the RDoc format, with HTML formatting. Then it should be possible to generate a documentation resource for then if they're collected into a joint repository. From what I understand, the Ruby docs http://www.ruby-doc.org/, are generated directly from the source.

With a joint repository, using this header, we can get a plugin manager working, as well as a central help system. I think that at the moment that I'm in favour of HTML formatting.

August

Hi Todd,

@unknownuser said:

Get your requests in now, during the early design stages.

I've done lots and lots of API doc, sometimes writing SED scripts to extract info from header files etc., but I'm not really at the SOTA when it comes to RDoc, JavaDoc, Doxygen, etc.

I'd like to help in this project, if I can, but it looks from the discussion like I'm way down on the curve compared to other folks.

Could you put together an outline of what it might take to catch up?

One thing I'm going to throw out here that might make a difference if it's still early stages.

I've been seeing over and over in other doc projects that the idea of going from the code comments to a Wiki seems to be catching on. From a Wiki, you have immediate collaboration on updating the doc and there are lots of ways of going from Wiki to PDF and/or print.

And if it's just about any Wiki besides SharePoint, you have some kind of standard markup format for the Wiki text that can be a very simple rework of the code comments format. Then the Wiki manages the cross-references and the formatting and display and you don't have to reinvent all of that in your HTML output from the code comments.

The piece I've been looking for and have not been seeing anywhere is going backwards from the collaborative Wiki edits to merge those changes back into the source so that the "master" does live in the code and can be updated when the code is changed.

Any interest in pursuing that idea? Building systems that do the code>Wiki>PDF and Wiki>Code round trip is something I've been brainstorming about doing professionally, so getting into that with this project might just add to my portfolio.

Let me know what you think,
August