Oolite Wiki

[hiran]

So the code I created can read the Expansion Manager's OXP list, download the OXPs, read their manifest|equipment|shipdata and come up with a set of HTML pages that we can browse. This first draft created content takes roughly 6 MB - already zipped.

How can I best share that file with others? Pastebin only allows cut'n'paste which would not work out for a zip archive.

[Cholmondely]

So the code I created can read the Expansion Manager's OXP list, download the OXPs, read their manifest|equipment|shipdata and come up with a set of HTML pages that we can browse. This first draft created content takes roughly 6 MB - already zipped.

How can I best share that file with others? Pastebin only allows cut'n'paste which would not work out for a zip archive.

Hiran, why don't you post say 3 on the wiki. I can then start editing them and let you know about the problems with the system from my perspective? If the worst comes to the worst, and it ends up as a mess, it will still make things a little simpler from my end.

[hiran]

Hiran, why don't you post say 3 on the wiki. I can then start editing them and let you know about the problems with the system from my perspective? If the worst comes to the worst, and it ends up as a mess, it will still make things a little simpler from my end.

Sharing just three of the files would probably not show the mass of files/pages that need to be managed.
But I received some hint, so you can check out https://bb.oolite.space/viewtopic.php?p=275530#p275530 .....

[Cholmondely]

... check out https://bb.oolite.space/viewtopic.php?p=275530#p275530 .....

Oh my giddy Aunt! I managed to find an index page in the morass of material. Clicking on BlOomberg markets (3rd down in the Expansions column) the resulting page reads:

Expansion BlOomberg Markets

Varies the in-game economy by generating random events that affect commodity prices. Depends on Snoopers.

Read more... - links to wiki page
category Mechanics
author Ramirez, Svengali
tags

Equipment: No equipment
Ships: No ships.

Clicking on Extracts from the Tre Clan another 1 1/2 pages down yields:

Expansion Extracts from the Tre Clan

Adds the 'Extracts from the Tre Clan Addresses on Interplanetary Life' book to your ship's library, containing selected lectures from an experienced trader.
category Equipment
author cim
tags

Equipment: No equipment
Ships: No ships.

Now, the current version of BlOomberg Markets depends on GNN.oxz, the successor to Snoopers.oxz. And Extracts from the Tre Clan similarly requires the Ship's Library.oxz.

In this light these entries for Extracts are confusing: category Equipment combined with Equipment: No equipment

All this may help a little (if it creates a new wiki page and if the new page is tagged as a mechanics .oxp or equipment .oxp), but I'm unsure it helps all that much. Dumping the read me contents on the new page (for later editing) would help a bit more.

I only clicked on these two (because I know a bit about them).

What do you think?

[hiran]

Oh my giddy Aunt! I managed to find an index page in the morass of material.

I did not tell anyone that opening *any* of the files reveals a link in the upper left corner "Back to index", which means you would not have had to search if you just knew. But point taken, that is not very intuitive. It does not cost me much to move all files down one folder so the index is more evident.

Now, the current version of BlOomberg Markets depends on GNN.oxz, the successor to Snoopers.oxz. And Extracts from the Tre Clan similarly requires the Ship's Library.oxz.

In this light these entries for Extracts are confusing: category Equipment combined with Equipment: No equipment

Please do not shoot the messenger. I just created a tool to extract information from the OXPs. The one you chose contains the category 'equipment' in it's manifest, but then the equipment.plist file either does not exist or is empty. One could argue whether such OXPs should exist at all, but as a matter of fact this one does.

All this may help a little (if it creates a new wiki page and if the new page is tagged as a mechanics .oxp or equipment .oxp), but I'm unsure it helps all that much. Dumping the read me contents on the new page (for later editing) would help a bit more.

This is the first draft of automatically generated pages. I am thinking of dumping the readme information as well - but there seems no documented standard where to put documentation (see http://wiki.alioth.net/index.php/OXP_howto or in http://wiki.alioth.net/index.php/OXP_standards).
This results in different OXPs coming with different files and different file formats that contain readme information. So this is a topic on it's own. Up until now I just used the short description and the information_url from the manifest.

I only clicked on these two (because I know a bit about them).

What do you think?

My first thought? Thank you for the feedback!

Well, it is a start. It also shows that until now there was very little management or quality control applied on the OXP metadata.
Which may change over time: If the code I create is well accepted it can also perform various checks and come up with notifications or reports. But someone would have to followup with the expansion authors.

I hope others would also chime in and share their thoughts. Until then I'll try to find a solution for readme files.

[hiran]

To give a better overview of the readme.txt challenge: Have a look at these creative names. And it is just an excerpt of the full list.
I will dump the content of these files into the expansion overview, however we still lack good descriptions for ships or equipment. No guarantees for the guys providing RTF though...

At least for each equipment there is a page that refers to the expansion, so users will have a chance to find something after all.


http://wiki.alioth.net/img_auth.php/8/85/Trident_Down_2.5.2.oxz!Trident Down readme.rtf
http://wiki.alioth.net/img_auth.php/9/95/Oolite.oxp.Thargoid.Armoury.oxz!Readme & License.txt
http://wiki.alioth.net/img_auth.php/7/72/BlOomberg_Markets_2.7.oxz!BlOomberg Markets v2.6.2 Readme.rtf
http://wiki.alioth.net/img_auth.php/4/48/Oolite.oxp.zzz.Montana05.GalTech_cylon_raider_Fix.OXZ!read_me.txt
http://wiki.alioth.net/img_auth.php/e/e4/CommsLogMFD.oxz!readme.txt
http://wiki.alioth.net/img_auth.php/6/62/Oolite.oxp.zzz.Montana05.Far_Arm_Ships.OXZ!Far Arm ships 3.0.1 ReadMe.txt
http://wiki.alioth.net/img_auth.php/0/05/Rescue_stations_1.5.4.oxz!rescue_stations_readme_and_licence.txt
http://wiki.alioth.net/img_auth.php/4/4d/Auto_Eject_1.2.oxz!readMe.rtf
http://wiki.alioth.net/img_auth.php/0/0e/Generation_Ships.oxz!readme.txt
http://wiki.alioth.net/img_auth.php/b/bd/AssassinsGuild-1.3.3.oxz!readme.txt
http://wiki.alioth.net/img_auth.php/b/bd/AssassinsGuild-1.3.3.oxz!v1.3.3 readme.txt
http://wiki.alioth.net/img_auth.php/4/47/Delightful_Docking_v1.1.oxz!Music/Blue Danube readme.rtf
http://wiki.alioth.net/img_auth.php/4/47/Delightful_Docking_v1.1.oxz!readme.rtf
http://wiki.alioth.net/img_auth.php/5/5a/AutoCrosshairs_1.1.1.oxz!Auto Crosshairs READ ME.txt
http://wiki.alioth.net/img_auth.php/2/2b/AutoPrimeEquipment.oxz!readme.txt
http://wiki.alioth.net/img_auth.php/7/76/Liners_v1.7.0.oxz!readme.rtf
http://wiki.alioth.net/img_auth.php/e/e2/Santa_1.2.oxz!readme.txt


[hiran]

Now there is an update available at https://app.box.com/s/6t0u4dj0y5g4adjo4ji6ggn06xnyvpa2
Some of the changes mentioned above are already in. Comments welcome.

[montana05]


http://wiki.alioth.net/img_auth.php/4/48/Oolite.oxp.zzz.Montana05.GalTech_cylon_raider_Fix.OXZ!read_me.txt
http://wiki.alioth.net/img_auth.php/6/62/Oolite.oxp.zzz.Montana05.Far_Arm_Ships.OXZ!Far Arm ships 3.0.1 ReadMe.txt


Cylon Raider Fix is not a real OXP, the readme.txt is merely a change log. I am still not sure if I should open wiki pages for the fixes, they are only there because of license problems.

Far Ams actually got a wiki page, including all ships : http://wiki.alioth.net/index.php/Far_Arm_ships, as you can see its there called Far Arm.

[hiran]


http://wiki.alioth.net/img_auth.php/4/48/Oolite.oxp.zzz.Montana05.GalTech_cylon_raider_Fix.OXZ!read_me.txt
http://wiki.alioth.net/img_auth.php/6/62/Oolite.oxp.zzz.Montana05.Far_Arm_Ships.OXZ!Far Arm ships 3.0.1 ReadMe.txt


Cylon Raider Fix is not a real OXP, the readme.txt is merely a change log. I am still not sure if I should open wiki pages for the fixes, they are only there because of license problems.

Far Ams actually got a wiki page, including all ships : http://wiki.alioth.net/index.php/Far_Arm_ships, as you can see its there called Far Arm.

It seems you are (at least sometimes) an OXP developer. Where would you prefer to put documentation for OXPs? What could be the favourite format?
Somehow I believe it makes sense to package the documentation within the OXP, and then to automatically distribute it to wherever it pleases. This could be the wiki, a ship's manual or whatever. But the flow of information would be defined.

Now as you say some OXP's are no real OXPs (I am not sure if I understand that), and some readme files are not meant to be read (why are they called readme then?), wouldn't that cry for a standard where to place documentation inside an OXP?

[montana05]

It seems you are (at least sometimes) an OXP developer.

All my own OXP's are currently on hold, for the past months I just take the work of others, update it for the latest Oolite release and upload them to the manager.

some OXP's are no real OXPs (I am not sure if I understand that)

Technically it is an OXP but standalone these packages do nothing. Most of these fixes are overriding existing work, usually because the license restricts modifying the original code.

and some readme files are not meant to be read

It's just my personal concept, there is no standard for it. My readme.txt usually only contain a quick overview and the change-log. It is unlikely that a plain user will read it so the info's there are mainly for developers. The wiki page, on the other hand, most of the time includes lore, pictures and a lot of details and is meant to help you to decide if you want to install this package.

[hiran]

Good point you made, @montana05. Now I believe we have to anticipate different constellations. Right now I would not know how to distinguish them by looking at an OXP:

• An OXP may require another one. Depending on the reason we probably want to treat only the new one or both OXPs as an 'official' one.
  In the case you mentioned your OXP contains a fix for the otherwise incompatible but also unmodifyable OXP. Here we probably only want to publish the wrapper and shadow the original one

• In other cases, where one OXP bases or accomplishes another one we want to publish both.

• Yet other cases, where OXPs peacefully coexist and all of them get equally published

Then there is different documentation for different target groups and use cases:

• Developer Documentation (may help understand, extend and maintain the OXP)

• Teaser (pre-installation: may help users to decide whether they want this OXP installed)

• Manual (post-installation: may help users actually use OXP, the ships, planets, equipment etc.)

• Changelog

• Legal notes (that might come in addition to the license mentioned in the manifest)

So far I have seen three formats of providing documentation:

• Plain ASCII files:
  easy to maintain but does not allow any markup, not to talk about including graphics. So it may be a bit boring to read just text.

• RTF files
  allows markup but requires the files to be made accessible to a suitable reader. I believe in practice noone extracts an OXP just to scan for RTFs...

• Wiki Entries
  the most versatile, most accessible and I believe therefore most used one. But it resides outside the OXP and thus follows a different lifecycle

Would it not make sense to define a structure that does not require documentation but shows where to place it? Later, when submitting an OXP to be registered in the Expansion Manager some minimum quality checks could be applied.

[montana05]

Would it not make sense to define a structure that does not require documentation but shows where to place it? Later, when submitting an OXP to be registered in the Expansion Manager some minimum quality checks could be applied.

Here is a typical manifest.plist:


{
"identifier" = "oolite.oxp.zzz.Montana05.SIRF";
"required_oolite_version" = "1.88";
"title" = "S.I.R.F.";
"version" = "2.61";
"author" = "milinks, tinker, Montana05";
"category" = "Dockables";
"description" = "System Independent Repair Facilities could be found in medium to high Tech level systems with reasonably safe governments. They provide alternative shipyards and trading. This package includes 3 NPC ships as well, for more details please check the wiki page.";
"information_url" = "http://wiki.alioth.net/index.php/S.I.R.F.";
"license" = "CC BY-NC-SA 4.0";
"tags" = ( "station", "ships" );
"requires_oxps" =
(
{
"identifier" = "oolite.oxp.zzz.Montana05.resource_pack_01";
"version" = "0.53";
"description" = "Adds effects, additional cargo and commodities plus new escape pods required by this OXP.";
}
);
"conflict_oxps" =
(
{
"identifier" = "oolite.oxp.zzz.Montana05.SIRF_compact";
"version" = "1.00";
"description" = "This original version and the simplified version are using the same keys and extensions and therefore can't coexist.";
}
);
}


"information_url" = already got a pointer to where additional information are offered, usually wiki

[hiran]

"information_url" = already got a pointer to where additional information are offered, usually wiki

I am aware of that field in the manifest. It is definitely better than nothing.

But while I was searching for user's manual how to actually benefit from installed expansions, equipment or ships, you told me that the provided documentation should simply be information to decide whether to have that information installed.

On the other hand, if other OXP developers think similarly I may better rest my case.

[Cholmondely]

"information_url" = already got a pointer to where additional information are offered, usually wiki

I am aware of that field in the manifest. It is definitely better than nothing.

But while I was searching for user's manual how to actually benefit from installed expansions, equipment or ships, you told me that the provided documentation should simply be information to decide whether to have that information installed.

On the other hand, if other OXP developers think similarly I may better rest my case.

Sadly, we are dealing with human beings here, rather than computers! Whatever the intentions behind the .oxp documentation system, not everybody will have followed them to the letter - as you have found. Different people will have different ideas regarding what to write about their OXP and where to put it.

A-a-a-and - even if we lay down the law in black and white, people won't follow it scrupulously in the future. I'm sure it's more than enough hassle to get the OXP's up and running in the first place (and ensuring that they run on cantankerous contraptions like my AppleMac with its innate semicolon fixation), without having to also worry about dotting and crossing every i & t regarding documentation. Especially for those like yourself whose mother-tongue is not the Queen's English.

I'm not advocating this, I'm just trying to be realistic.

Personally, I'd much rather focus on
(i) getting everything onto our wiki rather than lay down laws for what people should do in the future
(ii) making sure that there is relevant information there to help people make better choices when they look at the 700 oxz's on the http://www.oolite.org/oxps/ list and the hundreds on the OXP list and the Guide to Unlisted OXP page.
(iii) do something about "flagging up" such goodies as Phkb's experimental OXPs (and their equivalents) which in my honest opinion need a higher profile.

Now this is my opinion. It's not Holy Writ. And I am very well aware that OXP developers will now put a Manifest.plist in their OXZs to ensure it gets on the Expansions Manager (there are a fair number of older oxp's without either requires.plist's or ReadMe's). But again, personally speaking, I would rather encourage than discourage.




And speaking of encouraging - well done with the extraction process!

I am not to sure how to use it, not being a whizz with computers as you obviously are. If we can, we will - and if we can't, I suppose that we'll tweak!

But anyway - thank you, Hiran! Thank you for thinking of it, and thank you for taking the trouble.

[maik]

"information_url" = already got a pointer to where additional information are offered, usually wiki

I am aware of that field in the manifest. It is definitely better than nothing.

But while I was searching for user's manual how to actually benefit from installed expansions, equipment or ships, you told me that the provided documentation should simply be information to decide whether to have that information installed.

On the other hand, if other OXP developers think similarly I may better rest my case.

Sadly, we are dealing with human beings here, rather than computers! Whatever the intentions behind the .oxp documentation system, not everybody will have followed them to the letter - as you have found. Different people will have different ideas regarding what to write about their OXP and where to put it.

A-a-a-and - even if we lay down the law in black and white, people won't follow it scrupulously in the future. I'm sure it's more than enough hassle to get the OXP's up and running in the first place (and ensuring that they run on cantankerous contraptions like my AppleMac with its innate semicolon fixation), without having to also worry about dotting and crossing every i & t regarding documentation. Especially for those like yourself whose mother-tongue is not the Queen's English.

I'm not advocating this, I'm just trying to be realistic.

Personally, I'd much rather focus on
(i) getting everything onto our wiki rather than lay down laws for what people should do in the future
(ii) making sure that there is relevant information there to help people make better choices when they look at the 700 oxz's on the http://www.oolite.org/oxps/ list and the hundreds on the OXP list and the Guide to Unlisted OXP page.
(iii) do something about "flagging up" such goodies as Phkb's experimental OXPs (and their equivalents) which in my honest opinion need a higher profile.

Now this is my opinion. It's not Holy Writ. And I am very well aware that OXP developers will now put a Manifest.plist in their OXZs to ensure it gets on the Expansions Manager (there are a fair number of older oxp's without either requires.plist's or ReadMe's). But again, personally speaking, I would rather encourage than discourage.




And speaking of encouraging - well done with the extraction process!

I am not to sure how to use it, not being a whizz with computers as you obviously are. If we can, we will - and if we can't, I suppose that we'll tweak!

But anyway - thank you, Hiran! Thank you for thinking of it, and thank you for taking the trouble.

Based on my experience, Cholmondely is spot on. Setting up rules and expecting people to follow them is already not working well in business, I expect less for volunteers. Most people don’t go to the trouble of finding them, reading them, understanding them, and always remembering to follow them. It works okay-ish when you have internal audit doing regular reviews, but they always find issues that need correction (i.e. someone did not even follow rules concerning internal controls).

I see value in the intention, so let’s see what could be done: I work in manufacturing, one principle that helps a lot is poka-yoke: you fool-proof processes. One possible translation to our topic here is: have an OXP author fill in relevant info about the OXP in a form and have software based on that create maybe a manifest, maybe description both for the OXP manager and for the wiki from that etc. The author does not need to know the rules, but during the upload fills in what is asked (or confirms prior values if it is an update). Unfortunately this means work to create it, but it gives a lot of structure for future uploads and does not require parsing intents from prior less structured approaches.

Does that have merit? It obviously does not immediately provide a way to get wiki pages for all OXPs which are missing one, but over time, when they are updated, we get there. We would also have to manually create redirects for wiki pages which are automatically created although a page already exists but with another name. Should also be a temporary issue though.