tomee-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Jencks <david.a.jen...@gmail.com>
Subject Re: (new) website content sanity check :-)
Date Thu, 20 Feb 2020 00:54:12 GMT
I have a new idea for clarifying the website duplication.

Antora lets you include the same page in several components by using “include stubs”,
i.e. a page that only has an include:: preprocessor directive, pointing to the single copy.
(includes work in plain asciidoc, but there’s no practical way to refer to the originating
page without Antora page coordinates).

Intellij tools such as IDEA and WebStorm have a nice diff fe total.ature and customizable
live templates.  I made a live template to insert the include:: to the “actual copy” of
the page.

My workflow is to compare a page in 8.0@tomee (i.e. my antora clone of master of the tomee
git repo) with the same page in the tomes-site antora branch using WebStorm’s side-by-side
diff.  I combine the asciidoc to get something that is more correct than either source, edit
any other errors I see, put the corrected version in tomee-site, and replace the tomee master
copy with an include stub.

One of the edits is including the jbake attributes from master.

This reduces the number of duplicates by one, and indicates:
- on master that the page is duplicated in common
- on tomee-site that the page is duplicated in master, and edited to look OK.

I now have only 2 errors in 8.0@tomee, 367 in common, and 386 total.

David Jencks

> On Feb 17, 2020, at 4:39 PM, David Jencks <david.a.jencks@gmail.com> wrote:
> 
> I pushed another preview update.  This has all the content I’ve found and except for
a few pages from svn that seem to originate as html and some pages currently generated by
the tomee-stie-generator  I believe it has all the content that is supposed to be published.
> 
> There are about 450 errors noted by Antora building this.  These are asciidoc syntax
errors (mostly section level errors) and broken links.
> 
> AFAICT most of the content is duplicated in 4 places: what I’m calling “common”,
8.0, 7.1, and 7.0.  Fixing only one copy would be considerably quicker than comparing and
fixing 4.
> 
> My extremely biased opinion is that the content is approximately as good shape as the
live site.  There is decidedly less organization and navigation.  Some pages are worse, and
some are better, but it’s all presented uniformly.
> 
> TomEE Documentation AWS <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
> 
> Thanks
> David Jencks
> 
>> On Feb 16, 2020, at 7:41 PM, David Jencks <david.a.jencks@gmail.com <mailto:david.a.jencks@gmail.com>>
wrote:
>> 
>> Thanks for the more info, and I have plenty to do so no hurry, if you do have some
time some quick questions…
>> 
>> is https://svn.apache.org/repos/asf/tomee/site/trunk/content <https://svn.apache.org/repos/asf/tomee/site/trunk/content>
the “same as” the website content, so modulo .md and mdtext > html conversion I can
look at it and act like that’s the website to mimic? (also module files that have no source)
>> 
>> Is all the source from tomee-site, tomee-site-generator (including java-generated
content), and tomee?  So anything not present in some format from one of these that’s in
the above svn repo can be left out?
>> 
>> I’d think there must be some configuration for the Builder tomee-site-staging but
I can’t find it.
>> 
>> IMO the site in any form is in such a mess that it’s hard to know where to work
first.  There are tons of broken formatting, both in the existing site and the .adoc translations,
and loads of broken links that have no plausible target.  For instance one of the pages you
note  has 
>> 
>> \{include:OPENEJBx30:Singleton Beans}
>> 
>> I didn’t touch that one :-) It’s a bit confusing because there’s no OPENEJBx30
anywhere in sight, but I expect it’s supposed to refer to the same component/version.  When
I get to it it will turn into a redirect.
>> 
>> I’m mostly concentrating on finding all the sources, getting them into some sort
of semi-coherent structure, and fixing formatting and links that asciidoctor complains about.
 I thought I was nearly done, but now there are a lot more files :-)
>> 
>> After the automatically recognized problems are fixed, examining the pages for other
problems can start.
>> 
>> Thanks for the hints!
>> 
>> David Jencks
>> 
>> 
>> 
>>> On Feb 16, 2020, at 6:58 PM, David Blevins <david.blevins@gmail.com <mailto:david.blevins@gmail.com>>
wrote:
>>> 
>>> Hi David,
>>> 
>>> Looks like you got there in the end.  I attempted to give a heads up on that
in my first email about the Apache CMS, but all this is complicated.  Read this then go back
and read my first email on the "Documentation Site" thread and hopefully it makes more sense.
>>> 
>>> It's very hard to describe it with magically the right level of detail.  Here's
the way too short version.
>>> 
>>> - https://github.com/apache/tomee-site-generator <https://github.com/apache/tomee-site-generator>
spits html into here
>>> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/ <https://svn.apache.org/repos/asf/tomee/site/trunk/content/>
which triggers this Apache CMS job
>>> - https://ci.apache.org/builders/tomee-site-staging <https://ci.apache.org/builders/tomee-site-staging>
which takes any html and also converts the mdtext and puts them here
>>> - /usr/local/websites/tomee/trunk which is a private svn repo that publishes
to here
>>> - http://tomee.staging.apache.org <http://tomee.staging.apache.org/> which
can only get published if a human visits here
>>> - https://cms.apache.org/tomee/publish <https://cms.apache.org/tomee/publish>
and clicks the button so all html (CMS and otherwise) get published here
>>> - http://tomee.apache.org/ <http://tomee.apache.org/>
>>> 
>>> What we truly need more than a switch from Jbake to Antora is to get rid of the
Apache CMS as that would cut out 4 of those 7 bullets leaving us with:
>>> 
>>> - https://github.com/apache/tomee-site-generator <https://github.com/apache/tomee-site-generator>
spits html into here
>>> - https://github.com/apache/tomee-<some-new-repo> <https://github.com/apache/tomee-%3Csome-new-repo%3E>
which causes Apache's new infra to publish here
>>> - http://tomee.apache.org/ <http://tomee.apache.org/>
>>> 
>>> Unfortunately this repo appears to be a honeypot (dead end that can only confuse).
 It used to be a mirror of svn.apache.org/repos/asf/tomee/site/trunk/content <http://svn.apache.org/repos/asf/tomee/site/trunk/content>,
but it looks like the sync stopped about 2 years ago.
>>> 
>>> 
>>> All the work of the last 10 days or so has been on replacing the Javadoc and
Jbake parts, which have room for improvement and Antora can definitely be part of that improvement,
but the big win is ditching the CMS, which technically could happen now.  
>>> 
>>> Replacing the CMS probably needs its own email.
>>> 
>>> I mentioned this in the first email as well; the issue you pointed out at the
start with the badly formatted page actually wasn't an issue with Jbake.  It was one of many
legacy CMS files that wasn't fully converted out of the specialized Markdown format.  These
issues exist in your Antora prototype as well:
>>> 
>>> - https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/singleton-ejb.html
<https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/singleton-ejb.html>
>>> 
>>> And truthfully our content issues date back to our Confluence-based website days
as there's still a very small bit of Confluence wiki markup hanging around:
>>> 
>>> - https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/local-server.html
<https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/local-server.html>
>>> 
>>> Every time we make website-tech switch, the content takes a hit and yesterday's
content issues get rolled into the newly-created content issues.
>>> 
>>> Though I see our content issues as unrelated to Jbake or Antora and are just
plain content issues fixable with either solution, I still support some Antora usage.  I do
think we need to scale back what we're aiming at with Antora, however.
>>> 
>>> I'll try to post on that, but it takes me hours to write emails and I still have
a board report to do and I'm traveling in the morning, so no promises :)
>>> 
>>> 
>>> -- 
>>> David Blevins
>>> http://twitter.com/dblevins <http://twitter.com/dblevins>
>>> http://www.tomitribe.com <http://www.tomitribe.com/>
>>> 
>>>> On Feb 16, 2020, at 3:56 PM, David Jencks <david.a.jencks@gmail.com <mailto:david.a.jencks@gmail.com>>
wrote:
>>>> 
>>>> I’ve discovered that the svn repo automatically converts .mdtext files
to .html, so my conclusions about how much of tomee-site are currently published are wrong.
 I’ll redo my calculations.
>>>> 
>>>> Thanks
>>>> David Jencks
>>>> 
>>>>> On Feb 16, 2020, at 8:40 AM, David Jencks <david.a.jencks@gmail.com
<mailto:david.a.jencks@gmail.com>> wrote:
>>>>> 
>>>>> Hi,
>>>>> 
>>>>> I’d like some verification that my conclusions about content are reasonable….
>>>>> 
>>>>> The content sources I know about are:
>>>>> 
>>>>> tomee (7-8 docs and examples)
>>>>> 
>>>>> tomee-site-generator (older content)
>>>>> 
>>>>> tomee-site (?)
>>>>> 
>>>>> My understanding is the site is published using svnpubsub, so that svn
repo reflects what is actually visible on the site.
>>>>> 
>>>>> After doing some set arithmetic I’ve discovered that there is no content
on the current site necessarily from tomee-site; there’s a lot of overlap in content between
tomee-site and tomee-site-generator, but nothing from tomee-site that is missing from tomee-site-generator
is on the website.
>>>>> 
>>>>> Is this reasonable?
>>>>> 
>>>>> Is there anything from tomee-site not currently published that _should_
be added to the site?  According to my calculations, there are about 445 pages in tomee-site
that aren’t currently published. 
>>>>> 
>>>>> If anyone wants to study the situation, I recommend looking at my git
repos where all the content I’ve found is similarly organized, and the summary in 
>>>>> comparison.json <https://github.com/djencks/tomee/blob/antora/docs/comparison.json
<https://github.com/djencks/tomee/blob/antora/docs/comparison.json>>
>>>>> 
>>>>> calculated using old-new-compare.js <https://github.com/djencks/tomee/blob/antora/docs/old-new-compare.js
<https://github.com/djencks/tomee/blob/antora/docs/old-new-compare.js>>
>>>>> 
>>>>> There’s also quite a bit of content with no source; as I’ve mentioned
before I think this is a never-cleaned-up leftover from a previous version of the site.
>>>>> 
>>>>> Thanks
>>>>> David Jencks
>>>>> 
>>>>> ps. by “necessarily” I mean all the pages in svn that could have
come from tomee-site, could also have come from tomee-site-generator.  I don’t really know
where they actually came from, although I could probably calculate it.
>>>>> 
>>>>> pps. For nitpickers: there may appear to be two unique files at tomee-site.
 One, security/index, is the same as security/security; I’ve provided a redirect.  The other,
documentation, is some sort of site index or navigation page, possibly generated.  I heavily
edited the version in my repo before realizing it was not needed as-is.
>> 
> 


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message