Re: Antora-based website progress

[Cesar Hernandez]

Hi David,

The deployed preview looks pretty good. Thanks for the effort so far
executed!

>>>3. There are a lot of pages that are basically empty.  Maybe someone had
an idea that documenting something would be a good idea and added an empty
page for it.  Since these have been around for many years with no change, I
think it’s time to remove these.
If they are empty, I don't see a reason to keep them.

>>>4. There are a lot of pages explaining svn, tomcat <= 6, OpenEJB 1 and
3, etc. Is there any reason to keep these?
I would suggest creating an Archive category.

>>>5. There are several pages with helpful links to people's
people.apache.org accounts.  This is surely not appropriate, and I think
all of these are seriously out of date.  Is there any reason to keep these?
I think we can update those links to redirect readers to dev and/or the
user's mailing list.

There are many threads related to the website update so I'll try t
summarize my vision on this latest website update effort:

1) Keep current tomee-site generator as the main content and website layout
2) Once set up as a production-ready instance, keep the Antora setup for
the project documentation. This means that the current website link:
https://tomee.apache.org/docs.html will be redirected to the Antora
awesomeness UI.

In short, keep Antora usage for what it was made for, documentation. Keep
JBake for the static website layout and content.

[1] "Antora The multi-repository documentation site generator for tech
writers who  writing in AsciiDoc."https://antora.org/
[2] "Jbake Static site/blog generator for developers & designers"
https://jbake.org/


El vie., 13 mar. 2020 a las 14:43, Me via Boomerang ()
escribió:

> Message moved to top of Inbox by Boomerang (view this conversation
> 
> ).
>
> Don't want this notification email in the future? Go to
> https://b4g.baydin.com/settings and uncheck the 'At the top of your
> Inbox' option under Settings. Please note that your Boomeranged messages
> would no longer return to the top of your Inbox.
>
> Like Boomerang? Tell a friend! Click here
> 
> .
>


-- 
Atentamente:
César Hernández.

Re: Antora-based website progress

[Jean-Louis Monteiro]

Wow, that's awesome.
Antora is made for this kind of thing and I believe you did a great job in
trying it out.

The result is very good and you have done a great job, not only trying, but
getting something done.
Thanks for the huge contribution.
--
Jean-Louis Monteiro
http://twitter.com/jlouismonteiro
http://www.tomitribe.com


On Sat, Mar 7, 2020 at 9:06 PM Jonathan S. Fisher 
wrote:

> This is incredible, and beautiful! Thank you for putting in the work to
> make this happen!
>
> On Fri, Mar 6, 2020 at 9:06 PM David Jencks 
> wrote:
>
> > Preview at https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <
> > https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
> >
> > Current state:
> >
> > - all content from old source locations on the site (AFAICT, I’ve stopped
> > looking). This includes all the .md and .mdtext from tomee-site.
> > - no asciidoc syntax errors
> > - no internal broken links
> > - (easy) content deduplication
> >
> > There are still some content fixes left to do such as swizzle
> > elimination.  I don’t think these are currently any worse on the preview
> > than on the live site.
> >
> > I think the main remaining questions about the website organization
> relate
> > to duplicate and useless or obsolete content.  To me, history makes clear
> > that maintaining the website is difficult for the community and generally
> > neglected.  I think the highest priority should be making it smaller and
> > better organized so there’s less to maintain and when someone has an
> > interest in working on it it’s not an insuperable task to figure out how.
> >
> > The current preview organization has:
> >
> > - content from tomee-site-generator and tomee-site under “common”;
> there’s
> > only one version
> > - content from tomee branches under “tomee” with three versions.  Almost
> > all of this content also appears in “common”; see (1)
> > - content from the tomee master examples under “examples”, with 3
> language
> > versions.
> > - the beginnings of embedded JavaDoc, see
> >
> https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html
> > <
> >
> https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html
> > >
> >
> > I think the largest remaining questions about the website organization
> > relate to duplicate and useless or obsolete content.  To me, history
> makes
> > clear that maintaining the website is difficult for the community and
> > generally neglected.  I think the highest priority should be making it
> > smaller and better organized so there’s less to maintain and when someone
> > has an interest in working on it it’s not an insuperable task to figure
> out
> > how.
> >
> > 1. Previously, except for perhaps a couple of pages, the 8.0, 7.1, and
> 7.0
> > doc branches were identical except for different asciidoc syntax errors.
> > Now that I’ve brought in the previous .mdtext content from tomee-site git
> > repo and fixed the syntax errors, there are 4 identical copies.  I’ve
> made
> > this obvious by eliminating the full text of all but one and using
> > include:: directives in the other 3.  I think much of this content is
> > somewhere between outdated and wrong, so having 4 identical copies seems
> > like a less than ideal situation.  I think it’s extremely unlikely any of
> > this content is going to change, although some might be removed.  I’d
> > suggest keeping only the copy in “common” and leaving the versioned
> > branches for release-specific content, with a pointer to the common docs.
> >
> > 2. I haven’t examined the situation in detail, but I think that the
> > examples are pretty much the same for 7, 7.1, and 8.  I don’t think old
> > examples will ever change, but new ones added.  Therefore I suggest
> having
> > only one “examples” component with each example saying “since version
> xxx”.
> >
> > 3. There are a lot of pages that are basically empty.  Maybe someone had
> > an idea that documenting something would be a good idea and added an
> empty
> > page for it.  Since these have been around for many years with no
> change, I
> > think it’s time to remove these.
> >
> > 4. There are a lot of pages explaining svn, tomcat <= 6, OpenEJB 1 and 3,
> > etc. Is there any reason to keep these?
> >
> > 5. There are several pages with helpful links to peoples
> people.apache.org
> > accounts.  This is surely not appropriate, and I think all of these are
> > seriously out of date.  Is there any reason to keep these?
> >
> >
> > ———
> >
> > JavaDoc
> >
> > I’ve experimented with javadoc a bit.  In my tomee-site antora branch
> > there’s a small example of using maven to build a java 11 style javadoc
> jar
> > from a few bits of stuff pulled into the jbake-built javadoc. This makes
> > more sense to me than running the javadoc tool every time you want to
> > preview the website. I also have an experimental Antora plugin that adds
> > the javadoc to the generated website.  There are several ways to do this,
> > but I like the idea 

Re: Antora-based website progress

[Jonathan S. Fisher]

This is incredible, and beautiful! Thank you for putting in the work to
make this happen!

On Fri, Mar 6, 2020 at 9:06 PM David Jencks 
wrote:

> Preview at https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
>
> Current state:
>
> - all content from old source locations on the site (AFAICT, I’ve stopped
> looking). This includes all the .md and .mdtext from tomee-site.
> - no asciidoc syntax errors
> - no internal broken links
> - (easy) content deduplication
>
> There are still some content fixes left to do such as swizzle
> elimination.  I don’t think these are currently any worse on the preview
> than on the live site.
>
> I think the main remaining questions about the website organization relate
> to duplicate and useless or obsolete content.  To me, history makes clear
> that maintaining the website is difficult for the community and generally
> neglected.  I think the highest priority should be making it smaller and
> better organized so there’s less to maintain and when someone has an
> interest in working on it it’s not an insuperable task to figure out how.
>
> The current preview organization has:
>
> - content from tomee-site-generator and tomee-site under “common”; there’s
> only one version
> - content from tomee branches under “tomee” with three versions.  Almost
> all of this content also appears in “common”; see (1)
> - content from the tomee master examples under “examples”, with 3 language
> versions.
> - the beginnings of embedded JavaDoc, see
> https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html
> <
> https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html
> >
>
> I think the largest remaining questions about the website organization
> relate to duplicate and useless or obsolete content.  To me, history makes
> clear that maintaining the website is difficult for the community and
> generally neglected.  I think the highest priority should be making it
> smaller and better organized so there’s less to maintain and when someone
> has an interest in working on it it’s not an insuperable task to figure out
> how.
>
> 1. Previously, except for perhaps a couple of pages, the 8.0, 7.1, and 7.0
> doc branches were identical except for different asciidoc syntax errors.
> Now that I’ve brought in the previous .mdtext content from tomee-site git
> repo and fixed the syntax errors, there are 4 identical copies.  I’ve made
> this obvious by eliminating the full text of all but one and using
> include:: directives in the other 3.  I think much of this content is
> somewhere between outdated and wrong, so having 4 identical copies seems
> like a less than ideal situation.  I think it’s extremely unlikely any of
> this content is going to change, although some might be removed.  I’d
> suggest keeping only the copy in “common” and leaving the versioned
> branches for release-specific content, with a pointer to the common docs.
>
> 2. I haven’t examined the situation in detail, but I think that the
> examples are pretty much the same for 7, 7.1, and 8.  I don’t think old
> examples will ever change, but new ones added.  Therefore I suggest having
> only one “examples” component with each example saying “since version xxx”.
>
> 3. There are a lot of pages that are basically empty.  Maybe someone had
> an idea that documenting something would be a good idea and added an empty
> page for it.  Since these have been around for many years with no change, I
> think it’s time to remove these.
>
> 4. There are a lot of pages explaining svn, tomcat <= 6, OpenEJB 1 and 3,
> etc. Is there any reason to keep these?
>
> 5. There are several pages with helpful links to peoples people.apache.org
> accounts.  This is surely not appropriate, and I think all of these are
> seriously out of date.  Is there any reason to keep these?
>
>
> ———
>
> JavaDoc
>
> I’ve experimented with javadoc a bit.  In my tomee-site antora branch
> there’s a small example of using maven to build a java 11 style javadoc jar
> from a few bits of stuff pulled into the jbake-built javadoc. This makes
> more sense to me than running the javadoc tool every time you want to
> preview the website. I also have an experimental Antora plugin that adds
> the javadoc to the generated website.  There are several ways to do this,
> but I like the idea of having the javadoc content inside the Antora page
> layout: this is what the preview has.  I’m having trouble figuring out how
> to make the antora navigation and javadoc search work in this context.
> Also, javadoc jars now include some gpl2 licensed scripts, so I’m a bit
> unclear as to whether it’s even in line with Apache policy to show
> generated javadoc on an apache site.  The gpl code doesn’t do much, so I
> think it’s plausible to replace it with MIT or apache licensed code.
>
> I could use some help with:
> - constructing a full javadoc jar with maven, having the same source
> 

Antora-based website progress

[David Jencks]

Preview at https://tomee-preview.s3-us-west-2.amazonaws.com/index.html 


Current state:

- all content from old source locations on the site (AFAICT, I’ve stopped 
looking). This includes all the .md and .mdtext from tomee-site.
- no asciidoc syntax errors
- no internal broken links
- (easy) content deduplication

There are still some content fixes left to do such as swizzle elimination.  I 
don’t think these are currently any worse on the preview than on the live site.

I think the main remaining questions about the website organization relate to 
duplicate and useless or obsolete content.  To me, history makes clear that 
maintaining the website is difficult for the community and generally neglected. 
 I think the highest priority should be making it smaller and better organized 
so there’s less to maintain and when someone has an interest in working on it 
it’s not an insuperable task to figure out how.

The current preview organization has:

- content from tomee-site-generator and tomee-site under “common”; there’s only 
one version
- content from tomee branches under “tomee” with three versions.  Almost all of 
this content also appears in “common”; see (1)
- content from the tomee master examples under “examples”, with 3 language 
versions.
- the beginnings of embedded JavaDoc, see 
https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html 


I think the largest remaining questions about the website organization relate 
to duplicate and useless or obsolete content.  To me, history makes clear that 
maintaining the website is difficult for the community and generally neglected. 
 I think the highest priority should be making it smaller and better organized 
so there’s less to maintain and when someone has an interest in working on it 
it’s not an insuperable task to figure out how.

1. Previously, except for perhaps a couple of pages, the 8.0, 7.1, and 7.0 doc 
branches were identical except for different asciidoc syntax errors.  Now that 
I’ve brought in the previous .mdtext content from tomee-site git repo and fixed 
the syntax errors, there are 4 identical copies.  I’ve made this obvious by 
eliminating the full text of all but one and using include:: directives in the 
other 3.  I think much of this content is somewhere between outdated and wrong, 
so having 4 identical copies seems like a less than ideal situation.  I think 
it’s extremely unlikely any of this content is going to change, although some 
might be removed.  I’d suggest keeping only the copy in “common” and leaving 
the versioned branches for release-specific content, with a pointer to the 
common docs.

2. I haven’t examined the situation in detail, but I think that the examples 
are pretty much the same for 7, 7.1, and 8.  I don’t think old examples will 
ever change, but new ones added.  Therefore I suggest having only one 
“examples” component with each example saying “since version xxx”.

3. There are a lot of pages that are basically empty.  Maybe someone had an 
idea that documenting something would be a good idea and added an empty page 
for it.  Since these have been around for many years with no change, I think 
it’s time to remove these.

4. There are a lot of pages explaining svn, tomcat <= 6, OpenEJB 1 and 3, etc. 
Is there any reason to keep these?

5. There are several pages with helpful links to peoples people.apache.org 
accounts.  This is surely not appropriate, and I think all of these are 
seriously out of date.  Is there any reason to keep these?


———

JavaDoc

I’ve experimented with javadoc a bit.  In my tomee-site antora branch there’s a 
small example of using maven to build a java 11 style javadoc jar from a few 
bits of stuff pulled into the jbake-built javadoc. This makes more sense to me 
than running the javadoc tool every time you want to preview the website. I 
also have an experimental Antora plugin that adds the javadoc to the generated 
website.  There are several ways to do this, but I like the idea of having the 
javadoc content inside the Antora page layout: this is what the preview has.  
I’m having trouble figuring out how to make the antora navigation and javadoc 
search work in this context.  Also, javadoc jars now include some gpl2 licensed 
scripts, so I’m a bit unclear as to whether it’s even in line with Apache 
policy to show generated javadoc on an apache site.  The gpl code doesn’t do 
much, so I think it’s plausible to replace it with MIT or apache licensed code.

I could use some help with:
- constructing a full javadoc jar with maven, having the same source contents 
as the jbake javadoc
- figuring out the css and script problems with the embedded javadoc.  This is 
implausible now, since I haven’t pushed the Antora UI project I’m using, but I 
hope to do this soon.  If anyone is interested in working on this I can push