Things that need to happen:

• Start a new repo here on pagure
• Organize sources into an Antora module - see the template's readme for instructions: https://pagure.io/fedora-docs/template
• Change internal references (<<id,text>>) into xrefs using Antora's page ID (xref:file.adoc#anchor[text]) - https://docs.antora.org/antora/2.0/page/page-id/\
• Ping me and I'll figure out where exactly we should link this from

There is a working version of the ported webpage here:
https://pagure.io/java-packaging-howto/tree/master

@mkoncek Hi, I checked the new repo, almost everything is fine but I found a couple small issues. I opened https://pagure.io/java-packaging-howto/pull-request/1 fixing them. Please merge the PR when you can and then we can publish this.

@pbokoc Does the source repository have to reside on the Fedora architecture or can it stay on GitHub as it originally is?

Thanks for working on this, @mkoncek and @pbokoc.

As one of upstream authors of Java Packaging HOWTO I would prefer to keep using the existing code repository on GitHub for various reasons. If a repository on pagure.io is required then we could rely on Pagure mirroring feature to have the repository mirrored to pagure.io and publish documentation from the mirror.

Secondly, the documentation must remain to be buildable using only software that is packaged in Fedora, without downloading any prebuilt binary blobs from the Internet (such as antora image from docker.io). I'm fine with using Antora as one of possibilities, but it can't be the only way to build Java Packaging HOWTO.

@mkoncek @mizdebsk

• It's fine to keep the sources on Github if you prefer, we can pull from any repo as long as it's publicly accessible.

• Regarding buildability with something packaged in Fedora, I'm afraid that's a bit of a problem. Antora requires a specific directory structure due to its modular design. We could work around that by creating an index file in the repository root that would include all other source files, and then we should be able to build the doc with for example asciidoctor which is packaged in Fedora; you'd just have to make sure to consider both build systems when adding any pages. THe bigger issue is that Antora also uses a different xref syntax for internal links. There is a way around it with conditional macros but that would massively increase maintenance burden and it would make the sources harder to read in places where xrefs are used. Basically you'd have to put in each xref twice, once with the Antora syntax and once with the standard ID syntax, and determine which one should be used with a condition (ifdef/ifndef). It's possible but it's going to suck.

I can provide full details about how it works if you're interested in trying it out. I understand that you don't want to use something not packaged in Fedora, the concern has come up before - but you should understand that working around that is going to require some sacrifices.

Alright, it's finally up now. The howto itself is here: https://docs.fedoraproject.org/en-US/java-packaging-howto/ and it's listed under Packaging Guidelines -> Programming Languages -> Java -> Java Packaging HOWTO in the site's navigation: https://docs.fedoraproject.org/en-US/packaging-guidelines/Java/

I'll talk to @mkoncek about publishing updates; I think I'll make a new issue under the HOWTO repo for that so we can close this one now.