I’ve rebased my branches on current work, added 9.0 docs and implemented javax/jakarta via an attribute, and pushed the preview.
You can see the javax/jakarta at work by looking at different versions of https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/9.0/jpa-concepts.html#_valid_resource_local_unit_usage I think a few pages got added to explain 9.0 but I don’t think they are in the right place in any of my branches. Could someone point me to all the new pages? I asked about this in perhaps february with no response, but I’ll try again since the situation is now 25% worse. With the exception of a few pages getting dropped as time went on, there are now 5 identical copies of every page in the docs component. The original is in tomes-site, where I found it. In order to prevent the sort of unintended drift that plagues the current site, the other copies are all made to be identical with include stubs, like this: include::{common-vc}::page$unix-daemon.adoc[] I’m not sure supplying identical copies of the documentation that claim to be for different versions is entirely desirable. Presumably we need two copies for javax/jakarta, but I’m not sure the one in tomee-site (from CMS) or the identical 7.0, 7.1, and 8.0 versions are truly essential. Next I may look into the examples. IIUC the java source for them is going to remain as javax for the foreseeable future. I think that means that the README’s should also remain javax-only. Among other things this should enable easy inclusion of source-code snippets and avoid confusion when the doc says jakarta and the source says javax. I suggested earlier that there’s no need for more than one version of the examples. I haven’t changed my mind on this and although someone didn’t seem to like the idea, I didn’t see any arguments why having more than one version was a good idea. Since IMO the largest problem with the docs site is that there’s too much outdated useless and wrong content, and it’s nearly totally disorganized, I think reducing the size will make everything else easier. BTW if anyone wants to try editing asciidoc I recommend using intellij tools with the asciidctor plugin. It’s fairly Antora-aware and is by far the best tool I’ve found. IDEA CE works fine for this. David Jencks > On Aug 7, 2020, at 10:56 PM, David Jencks <david.a.jen...@gmail.com> wrote: > > > >> On Aug 7, 2020, at 6:16 PM, David Blevins <david.blev...@gmail.com> wrote: >> >>> On Aug 7, 2020, at 5:02 PM, David Jencks <david.a.jen...@gmail.com> wrote: >>> >>> It’s possible to customize antora to do some sorts of editing on the fly, >>> but I really don’t recommend it. The first two possibilities are also >>> pretty bad ideas near Antora. >> >> Do you have a link on the editing capabilities? > > As far as I know no one has ever done this, and as I said I think it’s a > really bad idea. However, Antora is flexible enough so this is possible. > > IMO magic is really bad news in something like a website that no one is > really interested in dedicating themselves to. Any time you have something > happening that is the least bit non-standard and non-obvious you dramatically > increase the barriers to contribution and maintenance. Maven is sort of > awful, but it’s fairly consistent, and it pretty much brought about a > revolution in build systems by a great deal of transparency and consistency. > I’m going to argue really strongly against any solution that isn’t entirely > visible from the source. The two solutions I know of are two copies of the > docs, with the EE prefix hardcoded, and one copy with the prefix as an > attribute, i.e. asciidoctor “variable”. > > Lets look for a solution that is completely visible in the adoc source. I > think an ee prefix attribute will do that, lets try it. > >> >> Recommended or not, is it possible to do either of the last two and what >> would that look like? > > It would look like incomprehensible magic, and no one would be able to figure > out how the result was obtained. At least I wouldn’t be able to if I stepped > away for a week. > >> >>> I think we should take a look at the attribute idea in action before ruling >>> it out. For one thing, it might be possible to check for non-use of the >>> attribute by grepping for javax or jakarta, maybe in a pre-commit hook. >> >> We can certainly take a look. Even if the feature doesn't get used for this >> problem doesn't mean learning about it is bad -- we may see another valuable >> way to use it. >> >> In terms of commit hooks, if I had to chose between writing tool/script to >> force a developer to do something or writing a tool/script to do it for >> them, I'll always favor the latter if that's possible. > > Well, the commit hook might replace either of ‘javax’ or ‘jakarta’ with > {ee-prefix}. I imagine there would need to be a way to use the other prefix > in a particular document. That could be another 2 attributes. > > David Jencks > >> >> >> -David >> >
