Replace the depreciated Antora family resource identifier with the actual valid once

[mmattel]

WHAT Needs to be Documented?

Based on a discussion with @movavelinux (Antora) at https://antora.zulipchat.com, we use depreciated family resource identifiers. This should be fixed, the proper family identifyer can be found at: https://docs.antora.org/antora/2.3/page/resource-id/#id-coordinates

{partialsdir}--> partial$
{examplesdir} --> example$

Note that {attachmentsdir} has to be kept for the time being.

From @mojavelinux

attribute references for the family directory in the resource ID are deprecated and will be removed in Antora 4 (maybe even Antora 3).

the problem with that approach is that it was tied to the file structure and it was limited to references in the same module.

with the new syntax, you can refer to a partial, example, page, or attachment located anywhere.

(the attachment fix won't be available until Antora 3.0.0-alpha.10, so if you're still using 2.3, then you still have to use {attachmentsdir}.

{modulesdir}/pages/_partials/nav.adoc

We also have to rename the _partials directory and relocate it:

This is also the wrong directory for partials. The partials should now be located in {modulesdir}/partials

https://docs.antora.org/antora/2.3/family-directories/

WHERE Does This Need To Be Documented (Link)?

We have to do a search and replace in all modules, in all repos. A PR will be created there too and referenced.

WHY Should This Change Be Made?

Depreciated/legacy family identifyers will most likely get removed with Antora 3

(Optional) What Type Of Content Change Is This?

• New Content Addition
• Old Content Deprecation
• Existing Content Simplification
• Bug Fix to Existing Content

(Optional) Which Manual Does This Relate To?

• Admin Manual
• Developer Manual
• User Manual
• Other

@EParzefall fyi

[mmattel]

I did some intense 🥵 tests with following results:

• Exchanging depreciated family coordinates
  -- eg.: {examplesdir} with the correct one example$ ✅
  -- see: https://docs.antora.org/antora/2.3/page/resource-id/#id-coordinates
  -- needed to revert because of pdf generation issue, see at the bottom ⛔
• Relocating <module_name>/pages/_partials to <module_name>/partials ✅
  -- using the new family coordinate {partialsdir} with the correct one partial$ ✅
  -- needed to revert using the family coordinate because of pdf generation issue, see at the bottom ⛔
• Moving the navigation files into the partial directory to enable full access from other doc repos ✅
  -- note that this is extremely important for the upcoming manual structure change !!
• Relocating <module_name>/assets/images/ to <module_name>/images ✅
  (note that no family coordinate change is necessary)
• Adopting the find-orphaned scripts for the new family coordinates and nav file location ✅
• Adopting the find-orphaned scripts using the old attribute way ✅
• Adopting the makepdf script for the new family directories (using the old way with attributes) and nav file location ✅

The bad news is, that pdf generation does not work when exchanging the family coordinates from depreciated to new 💣 🔥 This is because the family name cant be resolved like we did with attributes. I have filed an issue in Zulip, see: https://antora.zulipchat.com/#narrow/stream/282400-users/topic/Antora.20family.20coordinates.20.E2.80.93.20asciidoctor-pdf

Summary, we can prepare having the correct family directory structure including the location of the nav.adoc file, but have to wait using the family resource identifiers until the pdf generation is fixed.

@michl19 fyi too

[mojavelinux]

The bad news is, that pdf generation does not work when exchanging the family coordinates from depreciated to new

This is precisely why I have advised against using Asciidoctor PDF the way this project is using it, outside of the Antora build. Asciidoctor PDF by itself is not aware of Antora's structure or references and, as a result, you're inevitably going to run into problems doing it this way. And you should not try to modify your content to cater to Asciidoctor PDF. The right way to do it is to allow Antora to invoke Asciidoctor PDF with documents it has prepared. And that's precisely the extension the Antora project is currently working on creating (which got slightly held up by the Antora 3 release). I have provided more details in the chat.