Collaborative Effort - Ruby Template, RDoc, and Localization

RickW · 29 Jan 2009, 08:52

Permission to use, copy, modify, and distribute this software for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies.

or a different phrase of your preference.

# Supports Organizer.rb

=begin rdoc
= ScriptName
Copyright 2009, Author
All Rights Reserved

== Disclaimer
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

== License
author's license statement

== Information
Author;; AuthorName
Organization;; AuthorAffiliationOrOrganizationIfAny
Name;; ScriptName
Version;; ScriptVersion
SU Version;; MinimumSketchUpVersion
Date;; Date
Description;; ScriptDescription
Usage;; ScriptUsageInstructions
History;;
1.000;; YYYY-MM-DD
   * description1
   * description2
1.001;; YYYY-MM-DD
   * description1
   * description2

=end

require "sketchup.rb"



unless file_loaded?(__FILE__)
   file_loaded(__FILE__)
   UI.add_context_menu_handler do |menu|
      menu.add_item("menuitem") { code } # CREATE A SINGLE MENU ITEM IN CONTEXT MENU
      submenu = menu.add_submenu("submenu") # CREATE A SUBMENU ITEM IN CONTEXT MENU
         submenu.add_item("menuitem1") { code }
         submenu.add_item("menuitem2") { code }
   end
   $submenu ? (organizer = $submenu) ; (organizer = UI.menu("Plugins"))
   organizer.add_item("menuitem") { code } # CREATE A SINGLE MENU ITEM
   submenu = organizer.add_submenu("submenu") # CREATE A SUBMENU ITEM
      submenu.add_item("menuitem1") { code }
      submenu.add_item("menuitem2") { code }
end

Feedback?
Does anyone really want to use the embedded documentation format?
Does anyone really want to use the embedded html (=begin html) format?
Does anyone have an idea for templating the menuitems for language localization?

EDIT 2009-01-29: added a descriptor for the minimum SketchUp version required (thanks Thomas). The "default" would be '4' since that is when ruby was added to SU.
EDIT 2011-10-19: changed the above code sample to match the revised code sample from a later post, in hopes of alleviating confusion. For posterity's sake, the original code sample is here:

# Supports Organizer.rb

=begin
Copyright 2009, Author
All Rights Reserved

THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

License;	author's license statement

Author;		AuthorName
Organization;	AuthorAffiliationOrOrganizationIfAny
Name;		ScriptName
Version;	ScriptVersion
SU Version;	MinimumSketchUpVersion
Date;		Date
Description;	ScriptDescription
Usage;		ScriptUsageInstructions
History;
	1.000	YYYY-MM-DD
		description1
		description2
	1.001	YYYY-MM-DD
		description1
		description2

=end

require "sketchup.rb"



unless file_loaded?(__FILE__)
	file_loaded(__FILE__)
	UI.add_context_menu_handler do |menu|
		menu.add_item("menuitem") { code } # CREATE A SINGLE MENU ITEM IN CONTEXT MENU
		submenu = menu.add_submenu("submenu") # CREATE A SUBMENU ITEM IN CONTEXT MENU
			submenu.add_item("menuitem1") { code }
			submenu.add_item("menuitem2") { code }
	end
	$submenu ? (organizer = $submenu) ; (organizer = UI.menu("Plugins"))
	organizer.add_item("menuitem") { code } # CREATE A SINGLE MENU ITEM
	submenu = organizer.add_submenu("submenu") # CREATE A SUBMENU ITEM
		submenu.add_item("menuitem1") { code }
		submenu.add_item("menuitem2") { code }
end

thomthom · 29 Jan 2009, 11:41

Looks good by the first glance.

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?

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.

Matt666 · 29 Jan 2009, 13:49

Good idea Rick!
Thank you for this suggestion...

Heven7_floor · 29 Jan 2009, 15:05

Great and beautiful idea ! Are there any helping for amateurish codding ? , such event block code suggestion ,as collection of necessary or most usage event
ex.

   Class *name...
      def initial
      ...
      end 
      def onMouseMove(flags, x, y, view)
      ...
      end
      def onLButtonDown(flags, x, y, view)
      ...
      end
   end

        as the one who expertise codder shall please to new face like me for most usefully event suggestion for SU script codding   :tada:

Gaieus · 29 Jan 2009, 21:46

@rickw said:

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*s** in all copies. Commercial distribution, in whole or in part, is expressly prohibited without the express**ed,** written consent of the author.*

Well, I AM a lawyer, too, and I think it's okay.
I used to be an English teacher, too...

Chris Fullmer · 29 Jan 2009, 22:29

@gaieus said:

Well, I AM a lawyer, too, and I think it's okay.
I used to be an English teacher, too...

Aren't you a little over-qualified to be goofing around on the forum all the time then?

scottlininger · 29 Jan 2009, 22:32

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

Gaieus · 29 Jan 2009, 22:58

@chris fullmer said:

...Aren't you a little over-qualified to be goofing around on the forum all the time then?

Wait till I have the time to finish my PhD thesis!

RickW · 30 Jan 2009, 07:24

@unknownuser said:

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

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

# Supports Organizer.rb

=begin rdoc
= ScriptName
Copyright 2009, Author
All Rights Reserved

== Disclaimer
THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

== License
author's license statement

== Information
Author;; AuthorName
Organization;; AuthorAffiliationOrOrganizationIfAny
Name;; ScriptName
Version;; ScriptVersion
SU Version;; MinimumSketchUpVersion
Date;; Date
Description;; ScriptDescription
Usage;; ScriptUsageInstructions
History;;
 1.000;; YYYY-MM-DD
   * description1
   * description2
 1.001;; YYYY-MM-DD
   * description1
   * description2

=end

require "sketchup.rb"



unless file_loaded?(__FILE__)
   file_loaded(__FILE__)
   UI.add_context_menu_handler do |menu|
      menu.add_item("menuitem") { code } # CREATE A SINGLE MENU ITEM IN CONTEXT MENU
      submenu = menu.add_submenu("submenu") # CREATE A SUBMENU ITEM IN CONTEXT MENU
         submenu.add_item("menuitem1") { code }
         submenu.add_item("menuitem2") { code }
   end
   $submenu ? (organizer = $submenu) ; (organizer = UI.menu("Plugins"))
   organizer.add_item("menuitem") { code } # CREATE A SINGLE MENU ITEM
   submenu = organizer.add_submenu("submenu") # CREATE A SUBMENU ITEM
      submenu.add_item("menuitem1") { code }
      submenu.add_item("menuitem2") { code }
end

thomthom · 30 Jan 2009, 07:34

@unknownuser said:

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 · 30 Jan 2009, 16:42

@rickw said:

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 · 30 Jan 2009, 18:51

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 · 30 Jan 2009, 20:31

@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 · 2 Feb 2009, 16:19

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

todd burch · 2 Feb 2009, 16:21

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 · 2 Feb 2009, 18:40

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 · 3 Feb 2009, 23:27

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 · 3 Feb 2009, 23:38

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 · 4 Feb 2009, 00:12

I smell a good application for an XML file.

todd burch · 4 Feb 2009, 00:25

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>