Switch to documentation tables based on xcore

[sgrossberndt]

Ok, we're finally in a state now to easily deploy, render and compare the state of the current documentation rendering and the state of the new xcore rendering.

Also there is a new rudimentary starting page https://vdvde.github.io/OJP/ which shows the available documentation renderings based on branches.

The new documentation rendering found some issues, most in SIRI but one also is in OJP:

*** Create report for domain: name="ojp"
*** Item without type, path: "choice[]/siri:TrainRef"
*** Item without type, path: "choice[]/siri:CompoundTrainRef"

[trurlurl]

@sgrossberndt - Very nice that it now (almost) works!

I've spotted a few more problems, see below.

As for the missing sections 1.11 to 1.24 in the table of contents - I think this is by design and not inappropriate, since it concerns nested, unnamed types. There are similarly missing sections 12.32 ff. They all concern SIRI groups, and the tables (i.e., those not figuring in the table of contents) are replicated in both the OJP and the SIRI file. I don't know whether the replication in the OJP file somehow makes sense, e.g., for the links to work? So my question would rather be: could/should they be removed from the OJP file? But they don't do much harm, in my view.

Further small problems:

1. Number formatting looks a bit arbitrary at first glance (but isn't). The impression would be cleaner if always the same formatting were applied. For easening the transfer to MS Word spaces should be avoided.

2. In the case of it should rather say, instead of "contains one of the following...": "contains none or one of the following...".

3. Many of the links in https://vdvde.github.io/OJP/ do not work - is this because merging has not been done yet?

Are we (aka @sgrossberndt) able to do the suggested improvements on our own?

[sgrossberndt]

@sgrossberndt - Very nice that it now (almost) works!

yes 🎉

I've spotted a few more problems, see below.

As for the missing sections 1.11 to 1.24 in the table of contents - I think this is by design and not inappropriate, since it concerns nested, unnamed types. There are similarly missing sections 12.32 ff. They all concern SIRI groups, and the tables (i.e., those not figuring in the table of contents) are replicated in both the OJP and the SIRI file. I don't know whether the replication in the OJP file somehow makes sense, e.g., for the links to work? So my question would rather be: could/should they be removed from the OJP file? But they don't do much harm, in my view.

I'd like to have someone explain to me why these unnamed complex types are part of ojp.html. I don't see a reason for it. If they were only part of siri.html, I wouldn't mind.

Further small problems:

1. Number formatting looks a bit arbitrary at first glance (but isn't). The impression would be cleaner if always the same formatting were applied. For easening the transfer to MS Word spaces should be avoided.

I agree.

2. In the case of _<xs:choice minoccurs="0">_ it should rather say, instead of "contains _one_ of the following...": "contains _none or one_ of the following...".

I agree.

3. Many of the links in https://vdvde.github.io/OJP/ do not work - is this because merging has not been done yet?

I only did a first version which still contained links to release/1.0 which did not have a rendered documentation back then. I excluded those links now in https://github.com/VDVde/OJP/commit/246645e49d5c8a9b697e4f49a4c7ffda00842683. Once 2.0 has been released it will be visible as release/2.0 and we could add a link to main again.

Are we (aka @sgrossberndt) able to do the suggested improvements on our own?

I am not able to do those suggested improvements.

[ue71603]

Hans-Jürgen will have a look at it until next week.

[sgrossberndt]

Please review this pull request by comparing the state of the current documentation and the state of the new xcore documentation rendered using this pull request.

[ue71603]

@trurlurl Will you do the first comparison?

[trurlurl]

For me, everything looks fine now!

[sgrossberndt]

I propose to add a space before the (↔ so the definitions break to the next line (as done manually in 2.8 in this example (while 2.7 does not have the space): This improves readability a lot as otherwise the description column is very small

[sgrossberndt]

I propose to add a space before the (↔ so the definitions break to the next line (as done manually in 2.8 in this example (while 2.7 does not have the space): This improves readability a lot as otherwise the description column is very small

@skinkie The issue of a line break here is the only reason why it has not been merged yet: https://vdvde.github.io/OJP/feature/documentation-tables-xcore/documentation-tables/ojp.html#element_ojp__OJPLineInformationDelivery

[trurlurl]

@sgrossberndt I agree, this is a good idea how to "nudge" column widths and to improve readability and layout. I think inserting a space (or newline) in the following line in file xco.html.xqm should do that: ! ('(', <em>↔ {string()}</em>, ')') Would you give it a try?

[sgrossberndt]

Looks good to me. Please review and re-vote