empty pages in documentation navigation tree

[jodygarnett]

Describe the bug

A number of pages are empty in the documentation navigation tree, usually these are lost during major version updates (2 -> 3, 3 -> 4), but I am concerned that some may of been lost during recent mkdocs format conversion.

Initial report:

• user-guide/publishing/restricting-information-to-metadata-sections/ - the 3.12.x page is empty, the 2.10.x manual does not cover this topic
• user-guide/workflow/versioning - the 3.12.x page talks about svn versioning, probably not necessary now that 4.x has change history and ability to restore?

review

• version-3.0.0 - empty on 3.12 also
• restricting-information-to-metadata-sections - empty in 3.12 also - is this a feature? there is a todo comment ...
• tagging-with-keywords - empty in 3.12 also - Is this a feature?
• versioning - removed functionality? remove page ...
• changing-layout - empty in 3.12 also - Is this a feature?
• metadata - placeholder sentence
• harvesting-geonetwork - use info box to phrase this as migration guidance
• linking-source - seems okay
• linking-others - marked as todo
• version-3.4.1 - just short ( linked to issues / pull-requests )
• batchupdate - table of contents, address with change to nav tree
• version-3.10.1 - is fine
• linking-records - table of contents, address with change to nav tree
• managing-categories - fine
• version-3.10.2 - fine
• linking-documents - table of contents page, address with nav change

Additional context

Please check prior sphinx-build docs in case of mkdocs format conversion problem.

• https://github.com/geonetwork/doc
• https://geonetwork-opensource.org/manuals/3.12.x/eng/
• https://geonetwork-opensource.org/manuals/2.10.4/eng/users/
• https://geonetwork-opensource.org/manuals/2.10.4/eng/developer/

We can re-convert any missing pages a file at a time.

[jodygarnett]

Some linux fun:

wc -l `find . -type f -name '*.md'` | sort   

Produces the following list of files that are suspiciously empty:

       1 ./docs/overview/change-log/version-3.0.0.md
       1 ./docs/user-guide/publishing/restricting-information-to-metadata-sections.md
       1 ./docs/user-guide/tag-information/tagging-with-keywords.md
       1 ./docs/user-guide/workflow/versioning.md
       3 ./docs/customizing-application/changing-layout.md
       3 ./docs/devel/docs/index.md
       3 ./docs/devel/index.md
       3 ./docs/overview/license/index.md
       3 ./docs/tutorials/customui/view/index.md
       3 ./docs/tutorials/hookcustomizations/schemaplugins/index.md
       3 ./docs/user-guide/analyzing/metadata.md
       3 ./docs/user-guide/harvesting/harvesting-geonetwork.md
       4 ./docs/user-guide/analyzing/index.md
       4 ./docs/user-guide/tag-information/index.md
       5 ./docs/administrator-guide/managing-classification-systems/index.md
       5 ./docs/administrator-guide/managing-metadata-standards/index.md
       5 ./docs/annexes/index.md
       5 ./docs/tutorials/customui/search/index.md
       5 ./docs/user-guide/associating-resources/linking-source.md
       5 ./docs/user-guide/publishing/index.md
       6 ./docs/tutorials/customui/index.md
       6 ./docs/tutorials/index.md
       6 ./docs/tutorials/introduction/edit/index.md
       6 ./docs/user-guide/associating-resources/linking-others.md
       7 ./docs/contributing/index.md
       7 ./docs/customizing-application/search-ui/index.md
       7 ./docs/overview/change-log/version-3.4.1.md
       7 ./docs/overview/index.md
       7 ./docs/user-guide/workflow/batchupdate.md
       8 ./docs/maintainer-guide/index.md
       8 ./docs/overview/change-log/index.md
       8 ./docs/overview/change-log/version-3.10.1.md
       8 ./docs/tutorials/inspire/index.md
       8 ./docs/user-guide/associating-resources/linking-records.md
       8 ./docs/user-guide/workflow/index.md
       9 ./docs/administrator-guide/configuring-the-catalog/index.md
       9 ./docs/administrator-guide/managing-classification-systems/managing-categories.md
       9 ./docs/overview/change-log/version-3.10.2.md
       9 ./docs/user-guide/associating-resources/linking-documents.md

[jodygarnett]

Q: I have updated page on use of geonetwork 2.0 harvester, but is that even still present in then GN4 codebase?

[jodygarnett]

The next step for me is to remove the six blank pages, I have checked the sphinx 4.x, 3.x and 2.x manuals for content.

Assessment from chat with Juan:

• restricting-information-to-metadata-sections functionality exists in 4.x --> placeholder page needed
• tagging-with-keywords Juan is not aware of such functionality --> remove
• versioning - keep Juan confirmed functionality exists in 4.x --> copy 3.12.x docs
• changing-layout - unclear intent of doc page, maybe the List of templates for search results setting of the User Interface setttings?
• metadata - placeholder sentence
• linking-others not sure what to write, it is an option in the menu --> placeholder sentence

Does anyone wish to speak up before these pages are removed? It would be fine to keep these pages with a placeholder sentence if the feature exists (not very helpful but it would be something)

[jodygarnett]

linking-others:

Use Link to other resources to define an association to other records in this catalogue or a remote catalogue. The association created is assigned assigned a type (such as a cross-reference) indicating the nature of the relationship.

[jodygarnett]

It looks like some items remain empty

[aurisnoctis]

@jodygarnett Hello and thanks for this cue to me who was confused by empty pages in the documentation.

However, it seems, even more pages are empty now compared to your report at the top of this issue

user-guide/workflow/versioning - the 3.12.x page talks about svn versioning, probably not necessary now that 4.x has change history and ability to restore?

https://docs.geonetwork-opensource.org/3.12/user-guide/workflow/versioning/ is empty now. We have version 3 and I am not sure we can have versioning or not.

[jodygarnett]

The versioning is now super easy, you can see changes and restore. We do need someone to write content for that page.
I am only going to worry about the 4.2.x+ branches.

You should update as 3.12 reached end of life earlier this year.

[aurisnoctis]

@jodygarnett Thanks for the information. We had compatibility issues with version 4: we need support for the OAI-PMH protocol and it isn't supported in version 4, only in version 3 - correct? This is why we're deliberately still on version 3.

[jodygarnett]

You may consider porting the OAI-PMH protocol to version 4 - if that is the only thing holding you back. It is not very much difference for version 4 for the protocols. Most of the change is the use of Elasticsearch.

It is not a sustainable approach to stay on an old version. You may wish to ask if any other folks are interested in OAI-PMH support (often collaborating on development / testing / funding can be effective). Indeed that is all of this is one :P

[aurisnoctis]

Hi @jodygarnett thanks for our input! We are doing so many (dev) things with so few people in the public sector - the to-do lists are so long that I doubt we can contribute with code (reviews) to this ourselves anytime soon, unfortunately. Nonetheless, we'd like to keep Geonetwork for the growing need to manage and harvest metadata in an automated way.

I followed up on the issue here and @ticheler asked me to contact him about the missing code review, which I just did.

[jodygarnett]

Yeah this is an example of where open source is not free - it is paid for with time. Do ask on the geonetwork-devel list if other parties are interested in OAI-PMH also. Talk with @ticheler - ideally several folks can provide funding (if not time) for a GeoNetwork version 4 migration path.

[aurisnoctis]

@jodygarnett OK, where do I find the "geonetwork-devel list"? And wouldn't I have to rather a kind of user list instead of a dev list to find out if other users would be interested?

Thanks again 🙏

[jodygarnett]

Both would be good to contact, indeed.

[aurisnoctis]

Sorry again for hijacking this thread - where do I find both? Thank you 🙏

[jodygarnett]

This page of the website has the email list information https://geonetwork-opensource.org/community.html
You need to sign up to the mailing list before you can send a message.

In the coming weeks we will move to a forum (which allows sign-in using GitHub).