Re: Documentation site

[David Jencks]

Possibly there’s some duplication in the new site:

individual addresses in sitemaps, without translations:
old sitemap page count: 560 old-sitemap-addr.txt
new sitemap page count: 1423 new-sitemap-addr-en-only.txt

comparison of unique page names (without path, source, or version info):
old-not-new count: 1 old-not-new-index.txt
new-not-old count: 119 new-not-old-index.txt

If anyone has ideas how to identify it, I’d like to hear them.

Is the live-site sitemap actually accurate?

thanks
David Jencks

> On Feb 9, 2020, at 11:55 AM, David Jencks  wrote:
> 
> I think I’ve found all the existing content sources and incorporated them in 
> to the Antora-built site.
> 
> Sources:
> 
> * tomee  docs (moved to antora structure) (versions master = 8.0, 7.1, and 
> 7.0)
> * tomee examples (script to copy/rename to antora structure for appropriate 
> language)  (version master = 8.0 only)
> * tomee-site-generator (converted to adoc and moved to antora structure) 
> (currently labeled version 0.1)
> * tomee-site (converted to adoc and moved to antora structure) (currently 
> labeled version 0.0)
> 
> Comparing the live site-map.xml and the ones generated for the Antora-built 
> site, there is one file missing (index-old.html
> http://tomee.apache.org/examples/index-old.html 
> ) which I don’t think is 
> necessary or appropriate to move, and 119 new files that didn’t appear in the 
> existing site. They are listed in tomee@antora docs/new-not-old-index.txt.
> 
> The old-new diffs are only whether some version of the file stem appears in 
> each site, I haven’t tried to figure out how to compare which versions each 
> page appears in.
> 
> So far I’ve made no attempt to incorporate javadoc.
> 
> If you are not quite familiar with Antora structure looking at the preview at 
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html 
>  will probably 
> help understand the questions.  In particular in the lower left corner 
> there’s the “component drawer” where you can select the component and version 
> to view.
> 
> Questions:
> 
> * How should the content be arranged into components and versions?
> 
> ** current state:
> 
> *** There are two components, tomee and examples.
> 
> *** The tomee component has versions 8.0, 7.1, and 7.0 (from tomee/docs) and 
> 0.1 (from tomee-site-generator) and 0.0 (tomee-site)
> 
> *** The examples component has versions 8.0-en, 8.0-sp, 8.0-pt for the 
> different languages
> 
> ** Sub-questions:
> 
> *** Is all of the content I’ve put under tomee actually version specific, or 
> is there some content that is conceptually unversioned (general information 
> about tomee, perhaps).  This could be separated into a separate unversioned 
> component.
> 
> *** Is some or all of the content I’ve put in 0.1 and 0.0 actually associated 
> with a real version such as 1.7 or OpenEJB v???
> 
> *** Is there a need to maintain earlier versions of the examples 
> documentation, or is just “current” enough?  It looks like there are earlier 
> examples directories in the 7.1.x and 7.0.x branches, and it would certainly 
> be possible to convert them and include them in the site, but I think that 
> might make the site harder to use and less informative.
> 
> * How should the content with a version be organized on the source tree and 
> in the navigation?  The source-tree questions certainly don’t need immediate 
> answers.
> 
> ** Source tree: Antora source structure is 
> modules//pages/.  The ‘default’ module name is 
> ‘ROOT’, which is what I’ve used. Antora can deal directly with content in 
> subfolders of ‘pages’ (some of which has appeared reflecting the original 
> arrangement) and additional modules (useful to keep each module a manageable 
> size).  
> 
> *** To what extent would it be useful to break the content up into modules?
> 
> *** The examples are grouped in the navigation but are flat in the file 
> system.  Would it be appropriate to reflect the doc grouping in the file 
> system layout?
> 
> ** Navigation current state:
> 
> *** The 8.0, 7.1, and 7.0 tomee versions have navigation adapted from 
> documentation.adoc This seems more or less reasonable for now.
> 
> *** The 0.1 and 0.0 tomee versions have navigation generated by just listing 
> all the pages.
> 
> *** The examples have navigation adapted from the existing examples 
> navigation.
> 
> ** Sub-questions:
> 
> *** How should the 0.1 and 0.0 be organized? Is there an existing page that 
> is a starting point, as documentation.adoc is for more current content?
> 
> *** What other changes or refinements are appropriate?
> 
> ** Other:
> 
> *** can the conglomerated javadoc be generated by maven rather than the 
> custom script now used?  Starting with a javadoc jar seems simpler than 
> building it as part of the site generation.
> 
> =
> Where is it?
> preview:  

Re: Documentation site

[David Jencks]

I think I’ve found all the existing content sources and incorporated them in to 
the Antora-built site.

Sources:

* tomee  docs (moved to antora structure) (versions master = 8.0, 7.1, and 7.0)
* tomee examples (script to copy/rename to antora structure for appropriate 
language)  (version master = 8.0 only)
* tomee-site-generator (converted to adoc and moved to antora structure) 
(currently labeled version 0.1)
* tomee-site (converted to adoc and moved to antora structure) (currently 
labeled version 0.0)

Comparing the live site-map.xml and the ones generated for the Antora-built 
site, there is one file missing (index-old.html
http://tomee.apache.org/examples/index-old.html) which I don’t think is 
necessary or appropriate to move, and 119 new files that didn’t appear in the 
existing site. They are listed in tomee@antora docs/new-not-old-index.txt.

The old-new diffs are only whether some version of the file stem appears in 
each site, I haven’t tried to figure out how to compare which versions each 
page appears in.

So far I’ve made no attempt to incorporate javadoc.

If you are not quite familiar with Antora structure looking at the preview at 
https://tomee-preview.s3-us-west-2.amazonaws.com/index.html 
 will probably 
help understand the questions.  In particular in the lower left corner there’s 
the “component drawer” where you can select the component and version to view.

Questions:

* How should the content be arranged into components and versions?

** current state:

*** There are two components, tomee and examples.

*** The tomee component has versions 8.0, 7.1, and 7.0 (from tomee/docs) and 
0.1 (from tomee-site-generator) and 0.0 (tomee-site)

*** The examples component has versions 8.0-en, 8.0-sp, 8.0-pt for the 
different languages

** Sub-questions:

*** Is all of the content I’ve put under tomee actually version specific, or is 
there some content that is conceptually unversioned (general information about 
tomee, perhaps).  This could be separated into a separate unversioned component.

*** Is some or all of the content I’ve put in 0.1 and 0.0 actually associated 
with a real version such as 1.7 or OpenEJB v???

*** Is there a need to maintain earlier versions of the examples documentation, 
or is just “current” enough?  It looks like there are earlier examples 
directories in the 7.1.x and 7.0.x branches, and it would certainly be possible 
to convert them and include them in the site, but I think that might make the 
site harder to use and less informative.

* How should the content with a version be organized on the source tree and in 
the navigation?  The source-tree questions certainly don’t need immediate 
answers.

** Source tree: Antora source structure is 
modules//pages/.  The ‘default’ module name is 
‘ROOT’, which is what I’ve used. Antora can deal directly with content in 
subfolders of ‘pages’ (some of which has appeared reflecting the original 
arrangement) and additional modules (useful to keep each module a manageable 
size).  

*** To what extent would it be useful to break the content up into modules?

*** The examples are grouped in the navigation but are flat in the file system. 
 Would it be appropriate to reflect the doc grouping in the file system layout?

** Navigation current state:

*** The 8.0, 7.1, and 7.0 tomee versions have navigation adapted from 
documentation.adoc This seems more or less reasonable for now.

*** The 0.1 and 0.0 tomee versions have navigation generated by just listing 
all the pages.

*** The examples have navigation adapted from the existing examples navigation.

** Sub-questions:

*** How should the 0.1 and 0.0 be organized? Is there an existing page that is 
a starting point, as documentation.adoc is for more current content?

*** What other changes or refinements are appropriate?

** Other:

*** can the conglomerated javadoc be generated by maven rather than the custom 
script now used?  Starting with a javadoc jar seems simpler than building it as 
part of the site generation.

=
Where is it?
preview:  https://tomee-preview.s3-us-west-2.amazonaws.com/index.html 
 
git repos:
tomee  (antora, antora-tomee-7.1.x, 
antora-tomee-7.0.x) Some instructions are in docs/INSTRUCTIONS.adoc
tomee-site-generator  (antora)
tomee-site  (antora)

Thanks!

David Jencks


> On Feb 8, 2020, at 10:32 PM, David Jencks  wrote:
> 
> I now have the adoc content from master, 7.1.0.x, 7.0.0.x, the example 
> README.adoc from master (sorted by language), and the formerly .md files from 
> tomee-site-generator.
> 
> 

Re: Documentation site

[David Jencks]

I now have the adoc content from master, 7.1.0.x, 7.0.0.x, the example 
README.adoc from master (sorted by language), and the formerly .md files from 
tomee-site-generator.

The preview is still at 
https://tomee-preview.s3-us-west-2.amazonaws.com/index.html 
. The other urls 
have changed slightly (Tomee => tomee).

I think there are still 133 pages on the existing website that I haven’t 
located source for. If anyone has an idea where they might come from please let 
me know:

add-my-offering.htmlhttp://tomee.apache.org/add-my-offering.html
apache-openejb-3.1.3.html
http://tomee.apache.org/download/apache-openejb-3.1.3.html
apache-openejb-3.1.4.html
http://tomee.apache.org/download/apache-openejb-3.1.4.html
blogs.htmlhttp://tomee.apache.org/blogs.html
buildbot.htmlhttp://tomee.apache.org/examples/buildbot.html
contact.htmlhttp://tomee.apache.org/misc/contact.html
ejb-+-jpa-+-jsf-+-jax-rs.html
http://tomee.apache.org/ejb-+-jpa-+-jsf-+-jax-rs.html
ejb-2.1-compatibility-example.html
http://tomee.apache.org/ejb-2.1-compatibility-example.html
ejb-3-annotation-example.html
http://tomee.apache.org/ejb-3-annotation-example.html
ejb-3-annotation-examples.html
http://tomee.apache.org/ejb-3-annotation-examples.html
ejb-3-example.htmlhttp://tomee.apache.org/ejb-3-example.html
ejb-3-examples.htmlhttp://tomee.apache.org/ejb-3-examples.html
ejb-3-howto.htmlhttp://tomee.apache.org/ejb-3-howto.html
ejb-3-sample-applications.html
http://tomee.apache.org/ejb-3-sample-applications.html
ejb-3-sample.htmlhttp://tomee.apache.org/ejb-3-sample.html
ejb-3-samples.htmlhttp://tomee.apache.org/ejb-3-samples.html
ejb-3-tutorial.htmlhttp://tomee.apache.org/ejb-3-tutorial.html
ejb-3-tutorials.htmlhttp://tomee.apache.org/ejb-3-tutorials.html
ejb-3.0-specification.html
http://tomee.apache.org/ejb-3.0-specification.html
ejb-31-annotation-example.html
http://tomee.apache.org/ejb-31-annotation-example.html
ejb-31-annotation-examples.html
http://tomee.apache.org/ejb-31-annotation-examples.html
ejb-31-example.htmlhttp://tomee.apache.org/ejb-31-example.html
ejb-31-examples.htmlhttp://tomee.apache.org/ejb-31-examples.html
ejb-31-howto.htmlhttp://tomee.apache.org/ejb-31-howto.html
ejb-31-sample-applications.html
http://tomee.apache.org/ejb-31-sample-applications.html
ejb-31-sample.htmlhttp://tomee.apache.org/ejb-31-sample.html
ejb-31-samples.htmlhttp://tomee.apache.org/ejb-31-samples.html
ejb-31-tutorial.htmlhttp://tomee.apache.org/ejb-31-tutorial.html
ejb-31-tutorials.htmlhttp://tomee.apache.org/ejb-31-tutorials.html
ejb-annotation-example.html
http://tomee.apache.org/ejb-annotation-example.html
ejb-annotation-examples.html
http://tomee.apache.org/ejb-annotation-examples.html
ejb-example.htmlhttp://tomee.apache.org/ejb-example.html
ejb-glossary.htmlhttp://tomee.apache.org/ejb-glossary.html
ejb-howto.htmlhttp://tomee.apache.org/ejb-howto.html
ejb-sample-applications.html
http://tomee.apache.org/ejb-sample-applications.html
ejb-sample.htmlhttp://tomee.apache.org/ejb-sample.html
ejb-samples.htmlhttp://tomee.apache.org/ejb-samples.html
ejb-servlet.htmlhttp://tomee.apache.org/ejb-servlet.html
ejb-tutorial.htmlhttp://tomee.apache.org/ejb-tutorial.html
ejb-tutorials.htmlhttp://tomee.apache.org/ejb-tutorials.html
ejb3-annotation-example.html
http://tomee.apache.org/ejb3-annotation-example.html
ejb3-annotation-examples.html
http://tomee.apache.org/ejb3-annotation-examples.html
ejb3-example.htmlhttp://tomee.apache.org/ejb3-example.html
ejb3-examples.htmlhttp://tomee.apache.org/ejb3-examples.html
ejb3-howto.htmlhttp://tomee.apache.org/ejb3-howto.html
ejb3-sample-applications.html
http://tomee.apache.org/ejb3-sample-applications.html
ejb3-sample.htmlhttp://tomee.apache.org/ejb3-sample.html
ejb3-samples.htmlhttp://tomee.apache.org/ejb3-samples.html
ejb3-tutorial.htmlhttp://tomee.apache.org/ejb3-tutorial.html
ejb3-tutorials.htmlhttp://tomee.apache.org/ejb3-tutorials.html
example.htmlhttp://tomee.apache.org/example.html
examples-table.htmlhttp://tomee.apache.org/examples-table.html
faq_openejb-jar.html.html
http://tomee.apache.org/faq_openejb-jar.html.html
getting-started-with-eclipse-and-webby.html
http://tomee.apache.org/getting-started-with-eclipse-and-webby.html
heritage.htmlhttp://tomee.apache.org/misc/heritage.html
index-old.htmlhttp://tomee.apache.org/examples/index-old.html
injection-of-datasource-example.html
http://tomee.apache.org/injection-of-datasource-example.html
injection-of-entitymanager-example.html

Re: Documentation site

[David Jencks]

Hi Guillermo,

I’m not yet at the point of thinking about css or even UI changes.  If you want 
to you and you aren’t already familiar with Antora UI bundles you could take a 
look.

I think the I18n Asciidoc proposal would be too inconvenient for Tomee…. my 
experience with related systems was pretty horrible.  As I understand, Tomee 
has the (normally english) original adoc file in the same directory as any 
contributed translations.  I think this is going to continue to work well, as 
it’s really easy to understand what to do…. just take the adoc file and 
translate it, keeping the structure if appropriate.

I suppose it might be possible to, for each untranslated page and each 
language, generate a page saying “translate me” and perhaps with a 
google-translate rendition.  That seems a bit in the future though.

I was just thinking about the problems of how to organize and present the 
translations in Antora.

Thanks!
David Jencks

> On Feb 7, 2020, at 11:16 AM, Guillermo García  wrote:
> 
> On Thu, Feb 6, 2020 at 11:14 PM David Jencks 
> wrote:
>> 
>> After building myself a couple of tiny websites using Antora (
> https://antora.org) I’ve become somewhat interested in site generation from
> asciidoc
>> Does this seem like a direction worth pursuing?  I’m willing to spend a
> few days organizing stuff better, fixing the warnings and errors, and
> sprucing up the UI (I can change colors and remove the irrelevant stuff
> from the header, but advanced css is beyond me at this point).
> 
> Hi David,
> 
> It's a great approach. Count with me in CSS related changes. Just create
> the corresponding JIRA ticket and assign it to my JIRA user: bitcoder.
> 
>> There are also a couple of directions of experimentation I might like to
> pursue:
>> 
>> — Antora doesn’t have a good strategy for multi-language sites.  Since
> there’s at least some translation going on here, this seems like a good
> place to try out solutions.  I haven’t found the translations yet :-)
> Provisionally my first idea would be to represent languages as versions:
> 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages.   You
> could pick your language in the lower left component-version selector (on
> the preview only tomee/8.0 is present)
> 
> 
> Not sure how i18n is being provided for TomEE documentation.  We could find
> a way to track which parts of a translation need to be updated when the
> source document changes by using a localization management tool, like the
> po4a [1] perl module.
> 
> Besides, there's some interesting proposal [2] to use localization in the
> AsciiDoc project coming in next releases.
> 
>> 
>> ...
>> 
>> thanks
>> David Jencks
>> 
>> ps. My google search for the docs brought up this:
>> 
>> https://tomee.apache.org/latest/docs/documentation.html
>> 
>> which doesn’t look good.
>> 
> 
> It was my first impression too when I was reached the TomEE documentation.
> I already fixed some weird characters for the documentation.adoc in
> TOMEE-2767 [3], I am just waiting for changes to be deployed.
> 
> --
> Guillermo Garcia
> 
> 
> [1] https://github.com/mquinson/po4a
> [2] https://github.com/asciidoctor/asciidoctor/wiki/Design-Doc:-i18n
> [3] https://issues.apache.org/jira/browse/TOMEE-2767

Re: Documentation site

[David Jencks]

> On Feb 7, 2020, at 3:50 PM, David Blevins  wrote:
> 
>> On Feb 7, 2020, at 2:47 PM, David Jencks  wrote:
>> 
>> That’s great info and good points!
>> 
>> To build a site with Antora you basically need to be able to write a little 
>> yaml :-)
> 
> Famous last words :)

Indeed!


> 
>> Lets see how far I get with a bit of effort.  Is there a way to find all the 
>> source for the live CMS (and nothing that’s been replaced)?

Perhaps there are better tools now…. I ran kramdown-asciidoc on the .md files 
in tomee-site-generator, moved them into antora structure, came up with a nav 
file that just lists them alphabetically, and now they are another component in 
the preview.  They still need a little sed-based TLC and perhaps even human 
editing, but they mostly look OK (with a few problems).

Several pages look like someone had a great idea and stopped after writing the 
title… e.g. azure.adoc.  I’m not sure what to do with those.

I haven’t identified the existing navigation to these pages, and I don’t 
understand yet how it relates to the already-adoc content.

I think my next steps are to clean up the adoc and start to understand the 
desired organization.

In terms of organization, the existing docs look like there are versions for 
each 7+ tomee version but I’ve only found the git master branch with I presume 
the latest.

Anyway, the preview now shows a little bit how Antora can show different 
versions, although in this case I’m abusing the feature because the content is 
completely different.

Hints welcome!

David Jencks

> 
> This is now the bulk of what would have to be replaced:
> 
> - https://github.com/apache/tomee-site-generator
> 
> The main entry point is here:
> 
> - 
> https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/JBake.java#L32
> 
> The main exit point and integration with the CMS is here:
> 
> - 
> https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/SvnPub.java#L87
> 
> That will generate HTML and put it here.  
> 
> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/
> 
> However, everything that says '.mdtext' is rendered by the CMS and shows up 
> on the internet using our old black and white Twitter bootstrap look and 
> feel.  This happens when you go to here and click publish:
> 
> - https://cms.apache.org/tomee/publish
> 
> Once that is done there is html generated and sitting an an svn repository 
> somewhere (I can't remember where).
> 
> Apache will publish sites from git.  Ultimately, we need to get to a place 
> where we're doing either Jbake->HTML->Git or Antora->HTML->Git.  No SVN or 
> CMS.
> 
> Almost all of the '.mdtext' files have been committed here:
> 
> - 
> https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content
> - 
> https://github.com/apache/tomee-site-generator/blob/master/src/main/jbake/content/comparison.md
> 
> That page doesn't render by JBake as it's missing the appropriate JBake 
> header, so this CMS page still lives:
> 
> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/comparison.mdtext
> 
> Among the complexities is the fact that we're pulling documentation from a 
> few repositories:
> 
> - 
> https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Configuration.java#L20
> 
> We collapse all the source code down to one directory so we can generate one 
> big javadoc tree:
> 
> - 
> https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L54
> - 
> https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L144
> 
> There's code to attempt to get a list of contributors, including their 
> pictures:
> 
> - 
> https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Contributors.java#L47
> - http://tomee.apache.org/community/contributors.html
> 
> That code really needs to be replaced with something that pulls that data 
> from Github because the list of contributors is way way higher:
> 
> - https://github.com/apache/tomee/graphs/contributors
> 
> 
> Anyway, at least some pointers.
> 
> Not entirely sure I answered the question.
> 
> 
> -David
> 

Re: Documentation site

[David Blevins]

> On Feb 7, 2020, at 2:47 PM, David Jencks  wrote:
> 
> That’s great info and good points!
> 
> To build a site with Antora you basically need to be able to write a little 
> yaml :-)

Famous last words :)

> Lets see how far I get with a bit of effort.  Is there a way to find all the 
> source for the live CMS (and nothing that’s been replaced)?

This is now the bulk of what would have to be replaced:

 - https://github.com/apache/tomee-site-generator

The main entry point is here:

 - 
https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/JBake.java#L32

The main exit point and integration with the CMS is here:

 - 
https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/SvnPub.java#L87

That will generate HTML and put it here.  

 - https://svn.apache.org/repos/asf/tomee/site/trunk/content/

However, everything that says '.mdtext' is rendered by the CMS and shows up on 
the internet using our old black and white Twitter bootstrap look and feel.  
This happens when you go to here and click publish:

 - https://cms.apache.org/tomee/publish

Once that is done there is html generated and sitting an an svn repository 
somewhere (I can't remember where).

Apache will publish sites from git.  Ultimately, we need to get to a place 
where we're doing either Jbake->HTML->Git or Antora->HTML->Git.  No SVN or CMS.

Almost all of the '.mdtext' files have been committed here:

 - 
https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content
 - 
https://github.com/apache/tomee-site-generator/blob/master/src/main/jbake/content/comparison.md

That page doesn't render by JBake as it's missing the appropriate JBake header, 
so this CMS page still lives:

 - https://svn.apache.org/repos/asf/tomee/site/trunk/content/comparison.mdtext

Among the complexities is the fact that we're pulling documentation from a few 
repositories:

 - 
https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Configuration.java#L20

We collapse all the source code down to one directory so we can generate one 
big javadoc tree:

 - 
https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L54
 - 
https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Javadocs.java#L144

There's code to attempt to get a list of contributors, including their pictures:

 - 
https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/Contributors.java#L47
 - http://tomee.apache.org/community/contributors.html

That code really needs to be replaced with something that pulls that data from 
Github because the list of contributors is way way higher:

 - https://github.com/apache/tomee/graphs/contributors


Anyway, at least some pointers.

Not entirely sure I answered the question.


-David

Re: Documentation site

[David Jencks]

That’s great info and good points!

To build a site with Antora you basically need to be able to write a little 
yaml :-)

Lets see how far I get with a bit of effort.  Is there a way to find all the 
source for the live CMS (and nothing that’s been replaced)?

Thanks,
David Jencks

> On Feb 7, 2020, at 2:34 PM, David Blevins  wrote:
> 
> Here's the status of the site in general.
> 
> The original site was written using the Apache CMS (2011).  Several 
> extensions were made to it to get functionality it didn't have.  The CMS and 
> the extensions were written in Perl which nobody knows.  Much of the 
> extensions were around our examples.  Others were to hint css so some pages 
> could leverage twitter bootstrap capabilities.  I knew enough to write the 
> extensions, but eventually I became too busy and that left nobody knowing how 
> it all works.
> 
> Work on a new site started using JBake (Dec 2016, early 2017).  Some custom 
> code was written to replace features of the CMS and extensions.  The site 
> went live with around 30% of the content migrated and the rest left as-is, 
> still live and online being served by the CMS.  The justification being it 
> was all old content anyway and not worth migrating.  It was not deleted 
> either.  That left us with two live sites indexed by Google and confused 
> users who couldn't really understand what was current and what was not and 
> why some pages looked different than others.  The momentum behind the new 
> site stopped, considering the job done.
> 
> Work restarted on the JBake setup (Dec 2018, early 2019) to try and eliminate 
> the CMS further, fix issues with the site, add versioning of content, add 
> support for new languages and publish the Javadoc.  We overall went from 30% 
> JBake and 70% CMS to 90% Jbake and 10% CMS.  Some of the CMS content, 
> however, still needs significant love.  We still have CMS pages indexed on 
> Google that need to be replaced.
> 
> So our overall status is we still have live CMS content.  Here's one example:
> 
> - http://tomee.apache.org/comparison.html
> 
> We have some pages that use CMS formatting and therefore don't render and 
> need to be manually addressed:
> 
> - https://tomee.apache.org/latest/docs/documentation.html
> 
> 
> 
> My personal perspective is that anything is a good idea as long as there's a 
> person there to make it real.  It doesn't matter what technology we use to 
> build the site as much as it matters that there's a person there willing to 
> do the work till it's 100% done.
> 
> If someone wants to add a third site building framework on top of the other 
> two, leaving or losing interest before 100% of all content completely 
> converted over.  I would probably not be a fan.
> 
> If someone wants to completely transition us onto one single system including 
> all content, without exception, leaving no trace of any past site building 
> tech.  Sounds good.
> 
> Using something non-Java does eliminate most people's ability to help which 
> is what killed the CMS.  I have looked at Antora and its features are great 
> and so is Dan.  But not being written in Java made it just out of reach for 
> me and I know I would not be able to help at all.
> 
> I definitely would not support going live on a third website-building setup 
> with the other two in any way still serving content.  Our well-intentioned 
> plans to finish the transitions later have never worked out in practice.
> 
> I definitely would *love* to have one fabulous David Jencks active on the 
> project, so despite our past failures I'd support the attempt because getting 
> you active on the project is way bigger than any website.  If this is what 
> you're passionate about, then giddy-up. :)
> 
> 
> -- 
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
> 
>> On Feb 6, 2020, at 8:14 PM, David Jencks  wrote:
>> 
>> After building myself a couple of tiny websites using Antora 
>> (https://antora.org) I’ve become somewhat interested in site generation from 
>> asciidoc.
>> 
>> I looked at the current TomEE documentation site and am not entirely 
>> thrilled with the appearance.
>> 
>> I spent a couple of hours finding things, arranging the docs into an antora 
>> structure, and setting up some configuration.
>> 
>> You can see the results here:
>> 
>> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html 
>> <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
>> 
>> The source for this is at https://github.com/djencks/tomee, antora branch.
>> 
>> This makes no attempt to be a reasonable structure: I just found 
>> documentation.adoc, converte

Re: Documentation site

[David Blevins]

Here's the status of the site in general.

The original site was written using the Apache CMS (2011).  Several extensions 
were made to it to get functionality it didn't have.  The CMS and the 
extensions were written in Perl which nobody knows.  Much of the extensions 
were around our examples.  Others were to hint css so some pages could leverage 
twitter bootstrap capabilities.  I knew enough to write the extensions, but 
eventually I became too busy and that left nobody knowing how it all works.

Work on a new site started using JBake (Dec 2016, early 2017).  Some custom 
code was written to replace features of the CMS and extensions.  The site went 
live with around 30% of the content migrated and the rest left as-is, still 
live and online being served by the CMS.  The justification being it was all 
old content anyway and not worth migrating.  It was not deleted either.  That 
left us with two live sites indexed by Google and confused users who couldn't 
really understand what was current and what was not and why some pages looked 
different than others.  The momentum behind the new site stopped, considering 
the job done.

Work restarted on the JBake setup (Dec 2018, early 2019) to try and eliminate 
the CMS further, fix issues with the site, add versioning of content, add 
support for new languages and publish the Javadoc.  We overall went from 30% 
JBake and 70% CMS to 90% Jbake and 10% CMS.  Some of the CMS content, however, 
still needs significant love.  We still have CMS pages indexed on Google that 
need to be replaced.

So our overall status is we still have live CMS content.  Here's one example:

 - http://tomee.apache.org/comparison.html

We have some pages that use CMS formatting and therefore don't render and need 
to be manually addressed:

 - https://tomee.apache.org/latest/docs/documentation.html



My personal perspective is that anything is a good idea as long as there's a 
person there to make it real.  It doesn't matter what technology we use to 
build the site as much as it matters that there's a person there willing to do 
the work till it's 100% done.

If someone wants to add a third site building framework on top of the other 
two, leaving or losing interest before 100% of all content completely converted 
over.  I would probably not be a fan.

If someone wants to completely transition us onto one single system including 
all content, without exception, leaving no trace of any past site building 
tech.  Sounds good.

Using something non-Java does eliminate most people's ability to help which is 
what killed the CMS.  I have looked at Antora and its features are great and so 
is Dan.  But not being written in Java made it just out of reach for me and I 
know I would not be able to help at all.

I definitely would not support going live on a third website-building setup 
with the other two in any way still serving content.  Our well-intentioned 
plans to finish the transitions later have never worked out in practice.

I definitely would *love* to have one fabulous David Jencks active on the 
project, so despite our past failures I'd support the attempt because getting 
you active on the project is way bigger than any website.  If this is what 
you're passionate about, then giddy-up. :)


-- 
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com

> On Feb 6, 2020, at 8:14 PM, David Jencks  wrote:
> 
> After building myself a couple of tiny websites using Antora 
> (https://antora.org) I’ve become somewhat interested in site generation from 
> asciidoc.
> 
> I looked at the current TomEE documentation site and am not entirely thrilled 
> with the appearance.
> 
> I spent a couple of hours finding things, arranging the docs into an antora 
> structure, and setting up some configuration.
> 
> You can see the results here:
> 
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html 
> <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
> 
> The source for this is at https://github.com/djencks/tomee, antora branch.
> 
> This makes no attempt to be a reasonable structure: I just found 
> documentation.adoc, converted it to an Antora nav file, and picked docs.adoc 
> for the home page.
> 
> Does this seem like a direction worth pursuing?  I’m willing to spend a few 
> days organizing stuff better, fixing the warnings and errors, and sprucing up 
> the UI (I can change colors and remove the irrelevant stuff from the header, 
> but advanced css is beyond me at this point).
> 
> There are also a couple of directions of experimentation I might like to 
> pursue:
> 
> — Antora doesn’t have a good strategy for multi-language sites.  Since 
> there’s at least some translation going on here, this seems like a good place 
> to try out solutions.  I haven’t found the translations yet :-) Provisionally 
> my first idea would be to represent languages as ver

Re: Documentation site

[Guillermo García]

On Thu, Feb 6, 2020 at 11:14 PM David Jencks 
wrote:
>
> After building myself a couple of tiny websites using Antora (
https://antora.org) I’ve become somewhat interested in site generation from
asciidoc
> Does this seem like a direction worth pursuing?  I’m willing to spend a
few days organizing stuff better, fixing the warnings and errors, and
sprucing up the UI (I can change colors and remove the irrelevant stuff
from the header, but advanced css is beyond me at this point).

Hi David,

It's a great approach. Count with me in CSS related changes. Just create
the corresponding JIRA ticket and assign it to my JIRA user: bitcoder.

> There are also a couple of directions of experimentation I might like to
pursue:
>
> — Antora doesn’t have a good strategy for multi-language sites.  Since
there’s at least some translation going on here, this seems like a good
place to try out solutions.  I haven’t found the translations yet :-)
Provisionally my first idea would be to represent languages as versions:
8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages.   You
could pick your language in the lower left component-version selector (on
the preview only tomee/8.0 is present)


Not sure how i18n is being provided for TomEE documentation.  We could find
a way to track which parts of a translation need to be updated when the
source document changes by using a localization management tool, like the
po4a [1] perl module.

Besides, there's some interesting proposal [2] to use localization in the
AsciiDoc project coming in next releases.

>
> ...
>
> thanks
> David Jencks
>
> ps. My google search for the docs brought up this:
>
> https://tomee.apache.org/latest/docs/documentation.html
>
> which doesn’t look good.
>

It was my first impression too when I was reached the TomEE documentation.
I already fixed some weird characters for the documentation.adoc in
TOMEE-2767 [3], I am just waiting for changes to be deployed.

--
Guillermo Garcia


[1] https://github.com/mquinson/po4a
[2] https://github.com/asciidoctor/asciidoctor/wiki/Design-Doc:-i18n
[3] https://issues.apache.org/jira/browse/TOMEE-2767

Re: Documentation site

[David Jencks]

Thanks for the pointers!

David

> On Feb 7, 2020, at 1:26 AM, Daniel Dias Dos Santos 
>  wrote:
> 
> Hello David,
> 
> fantastic your experiment. :  )
> 
> the translation are in the examples folder:
> 
> https://github.com/apache/tomee/tree/master/examples
> 
> and about the site of documentation is in address :
> 
> https://tomee.apache.org/docs.html
> 
> :  )
> --
> 
> *Daniel Dias dos Santos*
> Java Developer
> SouJava & JCP Member
> GitHub: https://github.com/Daniel-Dos
> Linkedin: www.linkedin.com/in/danieldiasjava
> Twitter: http://twitter.com/danieldiasjava
> 
> 
> Em sex., 7 de fev. de 2020 às 01:14, David Jencks 
> escreveu:
> 
>> After building myself a couple of tiny websites using Antora (
>> https://antora.org) I’ve become somewhat interested in site generation
>> from asciidoc.
>> 
>> I looked at the current TomEE documentation site and am not entirely
>> thrilled with the appearance.
>> 
>> I spent a couple of hours finding things, arranging the docs into an
>> antora structure, and setting up some configuration.
>> 
>> You can see the results here:
>> 
>> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <
>> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
>> 
>> The source for this is at https://github.com/djencks/tomee, antora branch.
>> 
>> This makes no attempt to be a reasonable structure: I just found
>> documentation.adoc, converted it to an Antora nav file, and picked
>> docs.adoc for the home page.
>> 
>> Does this seem like a direction worth pursuing?  I’m willing to spend a
>> few days organizing stuff better, fixing the warnings and errors, and
>> sprucing up the UI (I can change colors and remove the irrelevant stuff
>> from the header, but advanced css is beyond me at this point).
>> 
>> There are also a couple of directions of experimentation I might like to
>> pursue:
>> 
>> — Antora doesn’t have a good strategy for multi-language sites.  Since
>> there’s at least some translation going on here, this seems like a good
>> place to try out solutions.  I haven’t found the translations yet :-)
>> Provisionally my first idea would be to represent languages as versions:
>> 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages.   You
>> could pick your language in the lower left component-version selector (on
>> the preview only tomee/8.0 is present)
>> 
>> - I think there might be some javadoc somewhere :-)  Antora also doesn’t
>> have a good strategy for including externally generated content.  I have an
>> idea around this that just might work :-)
>> 
>> On my GitHub clone I only see a master branch, which I assume is the tomee
>> 8 line.  Where are the earlier versions? Where is their documentation?
>> Antora is really good at building sites with many versions of the docs (as
>> long as the source is in asciidoc).
>> 
>> thanks
>> David Jencks
>> 
>> ps. My google search for the docs brought up this:
>> 
>> https://tomee.apache.org/latest/docs/documentation.html
>> 
>> which doesn’t look good.
>> 
>> 
>> 

Re: Documentation site

[Daniel Dias Dos Santos]

Hello David,

fantastic your experiment. :  )

the translation are in the examples folder:

https://github.com/apache/tomee/tree/master/examples

and about the site of documentation is in address :

https://tomee.apache.org/docs.html

:  )
--

*Daniel Dias dos Santos*
Java Developer
SouJava & JCP Member
GitHub: https://github.com/Daniel-Dos
Linkedin: www.linkedin.com/in/danieldiasjava
Twitter: http://twitter.com/danieldiasjava


Em sex., 7 de fev. de 2020 às 01:14, David Jencks 
escreveu:

> After building myself a couple of tiny websites using Antora (
> https://antora.org) I’ve become somewhat interested in site generation
> from asciidoc.
>
> I looked at the current TomEE documentation site and am not entirely
> thrilled with the appearance.
>
> I spent a couple of hours finding things, arranging the docs into an
> antora structure, and setting up some configuration.
>
> You can see the results here:
>
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <
> https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
>
> The source for this is at https://github.com/djencks/tomee, antora branch.
>
> This makes no attempt to be a reasonable structure: I just found
> documentation.adoc, converted it to an Antora nav file, and picked
> docs.adoc for the home page.
>
> Does this seem like a direction worth pursuing?  I’m willing to spend a
> few days organizing stuff better, fixing the warnings and errors, and
> sprucing up the UI (I can change colors and remove the irrelevant stuff
> from the header, but advanced css is beyond me at this point).
>
> There are also a couple of directions of experimentation I might like to
> pursue:
>
> — Antora doesn’t have a good strategy for multi-language sites.  Since
> there’s at least some translation going on here, this seems like a good
> place to try out solutions.  I haven’t found the translations yet :-)
> Provisionally my first idea would be to represent languages as versions:
> 8.0 is english, 8.0-sp, 8.0-pt, 8.0-ru etc are the other languages.   You
> could pick your language in the lower left component-version selector (on
> the preview only tomee/8.0 is present)
>
> - I think there might be some javadoc somewhere :-)  Antora also doesn’t
> have a good strategy for including externally generated content.  I have an
> idea around this that just might work :-)
>
> On my GitHub clone I only see a master branch, which I assume is the tomee
> 8 line.  Where are the earlier versions? Where is their documentation?
> Antora is really good at building sites with many versions of the docs (as
> long as the source is in asciidoc).
>
> thanks
> David Jencks
>
> ps. My google search for the docs brought up this:
>
> https://tomee.apache.org/latest/docs/documentation.html
>
> which doesn’t look good.
>
>
>

Documentation site

[David Jencks]

After building myself a couple of tiny websites using Antora 
(https://antora.org) I’ve become somewhat interested in site generation from 
asciidoc.

I looked at the current TomEE documentation site and am not entirely thrilled 
with the appearance.

I spent a couple of hours finding things, arranging the docs into an antora 
structure, and setting up some configuration.

You can see the results here:

https://tomee-preview.s3-us-west-2.amazonaws.com/index.html 
<https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>

The source for this is at https://github.com/djencks/tomee, antora branch.

This makes no attempt to be a reasonable structure: I just found 
documentation.adoc, converted it to an Antora nav file, and picked docs.adoc 
for the home page.

Does this seem like a direction worth pursuing?  I’m willing to spend a few 
days organizing stuff better, fixing the warnings and errors, and sprucing up 
the UI (I can change colors and remove the irrelevant stuff from the header, 
but advanced css is beyond me at this point).

There are also a couple of directions of experimentation I might like to pursue:

— Antora doesn’t have a good strategy for multi-language sites.  Since there’s 
at least some translation going on here, this seems like a good place to try 
out solutions.  I haven’t found the translations yet :-) Provisionally my first 
idea would be to represent languages as versions: 8.0 is english, 8.0-sp, 
8.0-pt, 8.0-ru etc are the other languages.   You could pick your language in 
the lower left component-version selector (on the preview only tomee/8.0 is 
present)

- I think there might be some javadoc somewhere :-)  Antora also doesn’t have a 
good strategy for including externally generated content.  I have an idea 
around this that just might work :-)

On my GitHub clone I only see a master branch, which I assume is the tomee 8 
line.  Where are the earlier versions? Where is their documentation?  Antora is 
really good at building sites with many versions of the docs (as long as the 
source is in asciidoc).

thanks
David Jencks

ps. My google search for the docs brought up this:

https://tomee.apache.org/latest/docs/documentation.html

which doesn’t look good.