[documentation] Ensure Helios has 3.0.0 documentation

[eclipse-ocl-bot]

| --- | --- | | Bugzilla Link | 304642 | | Status | CLOSED FIXED | | Importance | P3 normal | | Reported | Mar 04, 2010 02:57 EDT | | Modified | May 29, 2012 13:21 EDT | | Version | 3.0.0 | | Reporter | Ed Willink |

Description

In response to Kenn's prod I have updated the MDT/OCL project documentation link to point at http://help.eclipse.org/galileo/index.jsp?nav=/26, which is the Galileo doc plugin.

I've no idea how this comes about, but I doubt that we are doing whatever is necessary to ensure that similar web material is available for 3.0.0. Perhaps it's just the doc plugin from the buckybuild.

---

We have moved on quite a bit particularly with the bug 191689 delegates. We should therefore aim to review every single item of documentation.

• doc plugin
• wiki
• new and noteworthy
• doc URL
• article URL

to make them accurate, and hopefully to share as much content as possible by file sharing rather than rewriting.

[eclipse-ocl-bot]

By Adolfo Sanchez-Barbudo Herrera on Mar 05, 2010 09:10

This is my first review of the documentation:

• Minor changes which I have committed.
• I have verified that all the links are properly working.

The main problem related to the documentation:

• There are several images in PNG and SVG formats, which I don't any idea how to obtain . Some of them should be revised so that, for instance, TypeType is removed from the image in AdvancedTopic -> Creating Metamodel Bindings.
• The previous OCL Compatibility API Reference: It doesn't appear in the help content. However, I believe that this TOC came from the the removed org.eclipse.emf.ocl plugins, so I guess we are OK with this.

Some desirable aspects to update in the documentation:

1. OCL Overview -> updating the list of features which are supported by OCL.
2. Programmers guide -> OCL Relationship to Metamodels: There is an interesting table which resumes the supported OCL specifications features for both Ecore and UML bindings.
3. Move the OclInEcore wiki entry to the Programmer's Guide TOC or to the Tutorials TOC.

I suppose that reviewing the solved bugzillas could help in the tasks 1 and 2. If there is no volunteers I could try a patch for reviewing.\ I'll also tackle the task_ 3, but I would like to know more opinions about where to place it in the TOC.

Cheers,\ Adolfo

[eclipse-ocl-bot]

By Adolfo Sanchez-Barbudo Herrera on Jun 07, 2010 07:41

Using this bugzilla to follow the OclInEcore tutorial.

The OCLInEcore documentation was finally introduced by Ed into the OCL's Help Contents in the form of a useful Tutorial. Since this tutorial is different frome original wiki entry. I think that both could sensibly coexist.

I guess that the documentation will stay as is for Helios.

Any idea about the images so that we can change them the next release ?

Cheers,\ Adolfo.

[eclipse-ocl-bot]

By Ed Willink on Jun 07, 2010 11:15

The OCLinEcore documentation is very thin.

There is no documentation of the concrete syntax; jst hints in the tutorial.

I expect to replace OCLinEcore by UnifiedOCL that is Ecore/UML blind.

After reading Acceleo and Xtext documentation, we should also have

Full OCL standard library documentation.\ Full OCL stnyax documentation.

[eclipse-ocl-bot]

By Adolfo Sanchez-Barbudo Herrera on Jun 07, 2010 11:25

(In reply to comment #3)

The OCLinEcore documentation is very thin.

There is no documentation of the concrete syntax; jst hints in the tutorial.

I expect to replace OCLinEcore by UnifiedOCL that is Ecore/UML blind.

After reading Acceleo and Xtext documentation, we should also have

Full OCL standard library documentation. Full OCL stnyax documentation.

Shouldn't this documentation be the OMG Specification ?. Are you proposing (any kind of) copy-paste-format the concrete and/or abstract syntax from the specification ?.

[eclipse-ocl-bot]

By Ed Willink on Oct 14, 2010 02:22

The OCL Interpreter Tutorial covers only Ecore, but seems to lack sufficient clues to enable naive users to replace EXTLibraryPackage by their own package.

The corresponding information for UML is completely missing.

[eclipse-ocl-bot]

By Ed Willink on May 24, 2011 12:23

Re-using this Bugzilla to prigress the revamp of the documentation for Indigo.

I'll post a first patch shortly illustrating the capabilities of borrowing Xtext's wikitext set-up.

[eclipse-ocl-bot]

By Ed Willink on May 24, 2011 14:08

Created attachment 196473 non-binary files for Textile wikitext

In the attached:

., /doc, /doc/images and /styles are source material /libs needs populating manually with libraries - see Readme.txt toc.xml, /build, /manual, /help, /html are autogenerated

the binary /manual/ocl.pdf to follow

Clearly there is a lot of content to do, but at least it's in .textile and .png files with the rest auto-generated so updates should be quite reliable.

There is no required releng activity. The OCL Documentation launch can be run interactively and the products updated in CVS. When there is time, it would be good to fetch the JARs from Orbit and build on Hudson.

Please +1 if you are happy to migrate to this style of documentation generation so that further .textile and .png content can be added when written with review on Saturday/Sunday.

In so far as possible, I would like to retain all existing content, just refreshing to reflect the Indigo status.

:notepad_spiral: Bug304642.patch

[eclipse-ocl-bot]

By Ed Willink on May 24, 2011 14:09

Created attachment 196474 Example binary result from wikitext

ocl.pdf

[eclipse-ocl-bot]

By Adolfo Sanchez-Barbudo Herrera on May 25, 2011 05:37

Ed,

I'm OK to introduce this kind of tooling to deal with the documentation....

We would need to try some test builds as soon as possible. I'm not sure if all will magically work, for example, the build.properties will property to add the new folders to be included in the doc jar...

I think it's strictly necessary that we maintain the previous documentation, as long as it's updated/makes sense in the current state of the project.

BTW, have you tried the Eclipse Help ? After applying your patch it doesn't work in my second instance, actually if you open the toc.xml file there is an error:

The entity "rsquo" was referenced, but not declared. toc.xml /org.eclipse.ocl.doc line 17 Problem

It looks like the html symbols are not supported by the toc.xml file ...

Finally, I asked this question the last year. What are we going to do with the old-fashioned images ? Perhaps, recreating them with the ecore tools diagram ?

Best Regards,\ Adolfo.

[eclipse-ocl-bot]

By Ed Willink on May 25, 2011 14:14

(In reply to comment #9)\ I'll commit and try a couple of builds tonight.

I would like to migrate everything to textile but that's a fair amount of effort. For some things HTML works, so it may only be for the PDF that textile is really needed. If a non-trivial amount gets lost we may have to revert to the previous structure and manually do textile2html for new bits.

custiomBuild.xml or something likes to see all the images in doc/images. I tried a bit of hierarchy, but things collapsed, so for OCLinEcore tutorial I've moved all images across flat with a 4100- prefix, corresponding to the pretty arbitrary 4100-oclinecore-tutorial.textile. It seems all images will at least moce so redrawing is an option.

I'll check nested Eclipse before committing.

If successful we can hope for an RC4 to get more documentation done.

I'm looking for a diagram drawing tool for Eclipse OCL and OMG OCL. I would prefer Papyrus, but I'm not sure that it's ready; I can't see how to load an existing UML file; no initialize-diagram action. Papyrus also lacks pretty colours and gradients, but these can be added globally; my suggestion of an appearance 'profile' was received enthusiastically with a please submit patch.

I'm almost inclined to go for UML2 Tools or Ecore Diagram.

But I'd like something with a good future before redrawing all the IBM proprietary outputs.

[eclipse-ocl-bot]

By Ed Willink on May 25, 2011 15:06

(In reply to comment #9)

The entity "rsquo" was referenced, but not declared. toc.xml
/org.eclipse.ocl.doc line 17 Problem

It looks like the html symbols are not supported by the toc.xml file ...

Yes. I get the same problem. Seems we should avoid 's in titles. So it's now the Users Guide.

[eclipse-ocl-bot]

By Ed Willink on May 29, 2011 12:45

Created attachment 196852 Support for auto-generated OCL std lib documentation

Attached adds documentation comments to OCL-2.4.oclstdlib and provides the Acceleo generation scripts.

No need to rush this for Indigo; the PrettyPrinter is evolving and the attached uses an enhanced version in org.omg.ocl.

This will be upgraded in the pivot plugin after Indigo.

:notepad_spiral: Bug304642.patch

[eclipse-ocl-bot]

By Ed Willink on May 29, 2011 12:51

(In reply to comment #11)

(In reply to comment #9)

The entity "rsquo" was referenced, but not declared. toc.xml
/org.eclipse.ocl.doc line 17 Problem

It looks like the html symbols are not supported by the toc.xml file ...

Yes. I get the same problem. Seems we should avoid 's in titles. So it's now the Users Guide.

I had similar problems with e.g. Bag and tracked the problem to styles.xsl.

Unfortunately the scripts all XSLT 1.0 (Xalan) and the output serializer insists on translating & but not < etc. I know this was manageable on XSLT 2.o with Saxon, so one day we might use Saxon for tooling; not viable for Orbit. Or we might even do an M2M or M2T rather than XSLT. I'd forgotten how painful XSLT is.

Since I can't get Xalan to output < titles in the TOC have to be e.g. Bag_lt_Tgt

[eclipse-ocl-bot]

By Ed Willink on May 30, 2011 11:43

Created attachment 196912 The new OCLinEcore Tutorial Example project

:compression: org.eclipse.ocl.examples.project.oclinecoretutorial.zip

[eclipse-ocl-bot]

By Ed Willink on May 30, 2011 11:46

Created attachment 196913 Integration of the new example

Attached upgrades the root Example project to offer the new example.

Adolfo: I could only see Athena builds that reference the raw example projects.

Please +1 to add this example, and attachment 196912 as ready to play with for impatient Getting Starters.

I'll upgrade the .textile, and .png when approved.

:notepad_spiral: Bug304642.patch

[eclipse-ocl-bot]

By Adolfo Sanchez-Barbudo Herrera on May 31, 2011 09:22

Ed,

I've tested your new example. I'm OK with it (+1).

If I don't miss anything else, you will only have to update the examples feature to have everything in place.

Regards,\ Adolfo.

[eclipse-ocl-bot]

By Ed Willink on May 31, 2011 09:33

(In reply to comment #16)

If I don't miss anything else, you will only have to update the examples feature to have everything in place.

I'm at work with no CVS access till 17:30 GMT, so could you please commit this for me.

[eclipse-ocl-bot]

By Adolfo Sanchez-Barbudo Herrera on May 31, 2011 10:52

All right... Doing it right now. It will be part of RC3.

Regards,\ Adolfo.

[eclipse-ocl-bot]

By Adolfo Sanchez-Barbudo Herrera on May 31, 2011 11:04

Committed to HEAD.

In the end, the dependency was included in the o.e.o.examples buckminster.cspex because the new example is not a plugin at all.

Next: running an N-build to check the proper content prior to do the RC3 build

[eclipse-ocl-bot]

By Adolfo Sanchez-Barbudo Herrera on May 31, 2011 11:53

Ed,

Good news. OclInEcoreTutorial example and OCL Help's looks in place using the last successful (no-signing) build's p2 repository [1]...

Next: RC3 (I'm not sure if signing is already fixed or it's not...)

[1] https://hudson.eclipse.org/hudson/job/buckminster-mdt-ocl-core-3.1-nightly/557/artifact/MDT-OCL.p2.repository/

Regards,\ Adolfo.

[eclipse-ocl-bot]

By Ed Willink on Jun 02, 2011 16:27

Created attachment 197271 Getting Started, Essential OCL and Complete OCL syntax documentation

:notepad_spiral: Bug304642.patch

[eclipse-ocl-bot]

By Ed Willink on Jun 02, 2011 16:30

Created attachment 197273 Essential OCL and Complete OCL syntax images

:compression: images.zip

[eclipse-ocl-bot]

By Ed Willink on Jun 02, 2011 17:57

Created attachment 197281 Missing trailing blank line

:notepad_spiral: Bug304642.patch

[eclipse-ocl-bot]

By Ed Willink on Jun 05, 2011 13:46

Created attachment 197363 Additional tools documentation

:notepad_spiral: Bug304642.patch

[eclipse-ocl-bot]

By Ed Willink on Jun 05, 2011 13:48

Created attachment 197364 Additional tools images

:compression: images.zip

[eclipse-ocl-bot]

By Ed Willink on Jun 06, 2011 04:22

Created attachment 197372 Partial OCLstdlib syntax documentation

:compression: images.zip

[eclipse-ocl-bot]

By Ed Willink on Jun 06, 2011 04:23

Created attachment 197373 Delegates and Partial OCLstdlib syntax documentation

:notepad_spiral: Bug304642.patch

[eclipse-ocl-bot]

By Ed Willink on Jun 06, 2011 13:33

Created attachment 197430 Better OCLstdlib syntax documentation

:notepad_spiral: Bug304642.patch

[eclipse-ocl-bot]

By Ed Willink on Jun 06, 2011 13:34

Created attachment 197431 EXtra

1400-library.png

[eclipse-ocl-bot]

By Ed Willink on Jun 06, 2011 13:36

Created attachment 197432 Extra image

1400-library.png

[eclipse-ocl-bot]

By Ed Willink on Jun 06, 2011 16:21

Documentation now much improved. New bug for Juno.

[eclipse-ocl-bot]

By Ed Willink on May 29, 2012 13:21

Closing all bugs resolved in Indigo.