Update help 4.1.0

[JohannaOtt]

Within this issue todos on the HS Documentation shall be documented.
This issue is valid for Release 4.1.0

Intro:
There are some parts of the help that are outdated - others need an update. These are the pages/things affected from my point of view and those that were already collected in a different ticket. If anyone finds other parts that need to be reviewed - please don't hesitate to add them.

Documentation routine

Report as enumeration
Report IN PROGRESS [IN PROGRESS (your acronym) ] to indicate when you start with the specific doc change 
Report DONE [DONE (your acronym) ] to indicate when the specific doc change has been done and comitted
For each release a new HS Doc Task issue will be created by @Claudia-WE

List of required changes on HS Documentation

DONE (kl) 1. General

• Remove the 'Hale Plug-in for FME' part from the contents overview.
• Check screenshots and update where necessary (I think they are done on Linux - as the majority of users is working on Windows it make make sense to replace them with screenshots taken from a hale studio instance running on Windows.

DONE (kl) 2. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/introduction/introduction_dhp.html?cp=0_0_2

• Update information on data harmonisation panel - link leads to wetransform homepage, can be misleading

DONE (kl) 3. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/getting_started/help.html?cp=0_2_0

• "The online help misses some information that is provided on-the-fly in hale studio, e.g. the transformation function reference and the detailed reference for I/O providers" is not true any more. There is online help available for the detailed reference of I/O providers at http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user.ioproviders/overview/InstanceReader.html?cp=0_6_2_0_0 - please clarify with the developers as I might misunderstand something

DONE (kl) 4. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/getting_started/main_workflow.html?cp=0_2_1

• Link to tutorial video leads to wetransform start page

DONE (kl) 5. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/getting_started/install_plugins.html?cp=0_2_3

• add information on available hale pro plugins
• reword 'third-party' plugins as there are wetransform plugins as well

DONE (kl) 6. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/concepts/contexts.html?cp=0_3_0_1

• add information on the language used for contexts - maybe a link to http://help.halestudio.org/latest/index.jsp?topic=%2Feu.esdihumboldt.hale.doc.user%2Fhtml%2Freference%2Fcql_filter.html would be sufficient
• OR remove the page as the information is also contained in http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/tasks/schema/define_context.html?cp=0_5_0_1

DONE (kl) 7. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/views/schema_explorer.html?cp=0_4_0

• An explanation should be added on how to get the occurring values of an attribute displayed. It is mentioned that there is such a function in a screenshot here http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/tasks/schema/define_context.html?cp=0_5_0_1, but it is not explained how to get there.

DONE (kl) 8. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/tasks/schema/define_context.html?cp=0_5_0_1

• mention that for condition contexts on the source schema, there is now the option to add CQL or ECQL filters
• add a link to http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/reference/cql_filter.html?cp=0_6_1 where CQL filters are explained

DONE (kl) 9. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/tasks/schema/inspire_schema.html?cp=0_5_0_3

• maybe rename the page to 'Using schema presets' and add descriptions for other presets than INSPIRE that were added during the last years
• change link to INSPIRE Data Specifications to https://inspire.ec.europa.eu/data-specifications/2892

DONE (kl) 10. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/tasks/data/validate_data.html?cp=0_5_1_2

• remove part about status item in lower right corner - this is not true anymore

DONE (kl) 11. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/tasks/haleconnect/shareproject.html?cp=0_5_3_2

• typo in options part: "the created or update project" -> "the created or updated project"

DONE (kl) 12. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/tasks/save_project.html?cp=0_5_5

• add information to hale project (.hale) format that it is deprecated and only kept for backwards compatibility

DONE (kl) 13. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/tasks/transform_cli.html?cp=0_5_6

• "Please note that this reference documentation is generated from the I/O providers present in your local hale studio installation (including eventual additional plugins and custom implementations), so it is only available in the local hale studio help and not in the online version on the web." (appears twice) is not true any more. There is online help available for the detailed reference of I/O providers at http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user.ioproviders/overview/InstanceReader.html?cp=0_6_2_0_0 - please clarify with the developers as I might misunderstand something
• format of the examples in the end is hard to read

DONE (kl) 14. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/reference/schema_elements.html?cp=0_6_0

• potential typo: "being defined as a XML attribute." --> "being defined as an XML attribute."

DONE (kl) 15. http://help.halestudio.org/latest/nav/0_6_2

• Probably needs new parts for the GeoJSON reader and writer
• Add new section for the Xplan reader and writer
  -Add new section for the GeoPackage reader and writer

16. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/reference/import/xml_schema.html?cp=0_6_2_0_2

• In the troubleshooting part, the proxy settings in hale studio are explained. As a lot of users need to set them, I would consider moving it to an own/different part where users would search for it.

17. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/reference/import/jdbc.html?cp=0_6_2_0_8

• information on how to import a schema and data using an SQL query is missing.

DONE (kl) 18. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.cst.functions.geometric.spatialjoin.html?cp=0_6_3_0_0

• Link to description is broken or no description is available. Some more description on what the function does or how to use it, should be added as e.g. available for the Groovy Retype function (also described in help for Spatial Join function does not explain clearly what the function does #637 - this could be closed once the bullet point is done)

DONE (kl) 19. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.hale.align.merge.html?cp=0_6_3_0_6

• Some more description on what the function does or how to use it, should be added as e.g. available for the Groovy Retype function (also described in extend help for Merge function #617 - this could be closed once the bullet point is done)

20. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.hale.align.join.html?cp=0_6_3_0_7

• needs more documentation/examples according to existing Jira ticket

DONE (kl) 21. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.cst.functions.geometric.aggregate.html?cp=0_6_3_1_6

• Some more description on what the function does should be added as e.g. what happens to multi geometries when they are used as input

DONE (kl) 22. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.cst.functions.geometric.interiorPoint.html?cp=0_6_3_1_8

• Some more description on what the function does should be added as e.g. how that point is determined (find input here https://wetransform.slack.com/archives/C1GEA01EE/p1590478714000800)

23. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.cst.functions.groovy.html?cp=0_6_3_1_9 and http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.cst.functions.groovy.greedy.html?cp=0_6_3_1_10

• The parts for "Groovy Script" and "Groovy Script (greedy)" seem to be the same. I would suggest to delete the "Groovy script (greedy)" section from "Groovy Script" and only explain the differences (maybe also with an example) in "Groovy script (greedy)".

DONE (kl) 24. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.hale.align.classification.html?cp=0_6_3_1_18

• needs more documentation/examples according to existing Jira ticket

25. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.hale.align.inline.html?cp=0_6_3_1_20

• Some more description on what the function does should be added

DONE (kl) 26. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.hale.align.assign.bound.html?cp=0_6_3_1_21

• Some more description on what the function does or which cases it is used for should be added

DONE (kl) 27. http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/pointofcontact.html?cp=0_8

• Link to community forum is outdated and should be replaced
• phone number, "+49 6151 155 408" is to be changed to "+49 6151 6290890".

DONE (kl) 28. add a new section for beginners with a first aid kit on useful links etc. according to #807

29. add a new section on the deegree configuration export (also described in deegree configuration export is not documented in the help #753 - this could be closed once the bullet point is done)

30. http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.cst.functions.groovy.html?cp=0_6_3_1_9

• The meaning of "withTransformationContext" when working with collectors does not seem to be clear to most of the users. It is needed when several operations are executed that are linked to each other in a way that they can have a negative influence on each other. E. g. if the collector is filled with A, read and changed with B and only read with C, it is important to use it to make sure, that the operations do not corrupt each other.
• The helper function to create a context ( _.context.collector()) can be used in a context without adding a parameter - in this case, transformationContext is used automatically.

INPROGRESS (fa) 31. Add function explanations for:

Create
Retype
Spatial Join
Ordinates to Point
Calculate Length
Calculate Area
Centroid
Compute Extent
Reproject Geometry
Interior Point
Generate sequential ID
Date extraction
Rename
Generate Unique Id
Network expansion
Aggregate
FormattedString
Assign
Generate Unique ID
Date Extraction
XPath expression
SQL expression
Inline transformation

32. Improve description of _.geom.spatialIndexQuery function

• According to https://haleconnect.com/#/transformation/org/163/1ca2a4b1-83db-473d-b1fb-d9af9e3caa21/tasks/f99i, it is not clear to customers what it does.
• The documentation is available via the UI and does not have a dedicated page in the help if I see that correctly:
  

33. Add information about base alignments

DONE (fa) 34. Review documentation for outdated screenshots and make the required updates

DONE (fa) 35. In the introduction section on the wetransform section: Fix link to the wetransform website.

DONE (fa) 36. Throughout the hale studio help: consistency of name: "hale»studio"

37. Customer feedback from EN open workshop 2021-02-12: Please add documentation / tutorial on how to create combined schemas (source and target) for use in hale studio.

38. Question in Forum: What is the difference between base alignment and alignment? Check whether this information is included in the help pages. If not, include.

39. Add documentation about the generation of .hsd files including a description of what they are and how they can be used.

41. Add documentation about the fact that autofill rules are re-executed if the files of an existing dataset are updated: https://www.wetransform.to/help/en/help-page-category-setup-haleconnect/help-page-subcategory-setup-haleconnect-thememetadata/2015/02/10/theme-edit-metadata/

42. Add part about Decimal number format pattern also to other GML writers than GML (Feature Collection). I tested it for GML (WFS Feature Collection) here and it is working for it, too, but is missing in the documentation. I assume it is functional for all GML writers.

[Kate-Lyndegaard]

@stempler Where can I find this page in git?
http://help.halestudio.org/latest/topic/eu.esdihumboldt.cst.doc.functions/functions/eu.esdihumboldt.hale.align.merge.html?cp=0_6_3_0_6

Are the function help pages auto-generated?

[florianesser]

@Kate-Lyndegaard The online help is generated from the application help. We update the online version when there is a new release.

[Kate-Lyndegaard]

@florianesser Unfortunately I cannot find this page in the application help..
I am looking here: eu.esdihumboldt.hale.doc.user --> html folder

[florianesser]

That particular page is auto-generated from this definition.

[Kate-Lyndegaard]

@florianesser Yeah, that's what I thought. This complicates adding screenshots and examples here, doesn't it? Would there be an easy way to do that? At a minimum, I could add text to the description if there is no limit on length.

[florianesser]

I'd say those pages are thought more as a technical reference and not so much as to contain a tutorial. If you'd like to create a tutorial for the Merge (or another) function with screenshot, I'd suggest that we set up a separate help section for that.

[stempler]

There is a mechanism for adding custom content to the function help, I'll check if I find an example.

[stempler]

The mathematical expression function uses the mechanism to add custom help content including images.

hale/cst/plugins/eu.esdihumboldt.cst.functions.numeric/plugin.xml

Line 18 in 1f6a2a8

help="help/mathematicalExpression/help.xhtml"

[florianesser]

Thanks a lot, @stempler !

[Kate-Lyndegaard]

@stempler Could you please shoot me a link to the FME Plug in so I can delete it? I really can't find it, sorry!

[stempler]

@Kate-Lyndegaard
To remove the FME content you need to remove the FME feature/plugins from the product files:

hale/doc/plugins/eu.esdihumboldt.hale.doc.application/Infocenter.product

Line 47 in 1f6a2a8

<plugin id="de.fhg.igd.hale.fme.doc"/>

hale/ui/plugins/eu.esdihumboldt.hale.ui.application/HALE.product

Line 104 in 1f6a2a8

<feature id="de.fhg.igd.hale.fme.feature"/>

[Kate-Lyndegaard]

@stempler I removed these two lines, however the plug in is still appearing. Any other places where this may be referenced?

[stempler]

@Kate-Lyndegaard When running hale studio locally from Eclipse? You probably have to update the run configuration by opening the HALE.product file and running it from there again.

[Kate-Lyndegaard]

@thorsten-reitz I have a question about topic #2 in this ticket: How would you like the following page updated, if at all? The link on this page leads to the wetransform homepage- is that correct? If not, could you please provide a link that should be there?

http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/introduction/introduction_dhp.html?cp=0_0_2

[thorsten-reitz]

The link actually leads to dhpanel.eu, but there is a forwarder to wetransform.to. In my view, the page on the data harmonisation panel can be removed, that is only confusing. We can replace it with a page on wetransform and on our value add offerings.

[Kate-Lyndegaard]

@stempler I have a question about topic #3 in this ticket. Do you agree that I can remove the sentence:
"The online help misses some information that is provided on-the-fly in hale studio, e.g. the transformation function reference and the detailed reference for I/O providers for use with the command line interface."

from this page: http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user/html/getting_started/help.html?cp=0_2_0 ?

There is online help available for the detailed reference of I/O providers at http://help.halestudio.org/latest/topic/eu.esdihumboldt.hale.doc.user.ioproviders/overview/InstanceReader.html?cp=0_6_2_0_0

[Kate-Lyndegaard]

The link actually leads to dhpanel.eu, but there is a forwarder to wetransform.to. In my view, the page on the data harmonisation panel can be removed, that is only confusing. We can replace it with a page on wetransform and on our value add offerings.

@thorsten-reitz Good idea- does team revenue have some boilerplate, or should I write something?

[stempler]

@stempler I have a question about topic #3 in this ticket. Do you agree that I can remove the sentence:
"The online help misses some information that is provided on-the-fly in hale studio, e.g. the transformation function reference and the detailed reference for I/O providers for use with the command line interface."

Yes, at some point we added the respective bundles needed for that. It bloats up the Infocenter product but allows the reference information to appear there.

[Kate-Lyndegaard]

@stempler @thorsten-reitz
I have a question about topic #4 in this ticket: Do you have a link to an existing hale studio video?
I also have a question about topic #5 : Do we have a write up about the hale studio plugins?

[thorsten-reitz]

I suppose we can use this one?
https://www.youtube.com/watch?v=BKNMV-Jp9HM

[thorsten-reitz]

@JohannaOtt are you aware of any open changes related to this issue? If it is OK for the release, please close it.

[JohannaOtt]

As far as I can see there a still some points that are not addressed yet (do not have a "DONE" prefixed).
@Claudia-WE is taking care of regularly creating new issues for the help update and moving open points there.