Re: [jakartaee-platform-dev] Spec doc conversion: heads-up

["Kevin Sutter" <sutter@xxxxxxxxxx>]

PRs are encouraged
to update our helpful hints for Jakarta-izing the Specs.  :-)  Thanks!

---------------------------------------------------
Kevin Sutter 
STSM, MicroProfile and Jakarta EE architect @ IBM
e-mail:  sutter@xxxxxxxxxx     Twitter:  @kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)    
LinkedIn: https://www.linkedin.com/in/kevinwsutter



From:
       arjan
tijms <arjan.tijms@xxxxxxxxx>
To:
       jakartaee-platform
developer discussions <jakartaee-platform-dev@xxxxxxxxxxx>
Date:
       01/22/2020
09:11
Subject:
       [EXTERNAL]
Re: [jakartaee-platform-dev] Spec doc conversion: heads-up
Sent
by:        jakartaee-platform-dev-bounces@xxxxxxxxxxx

---

If it helps anyone, numbered images per
chapter is not a default feature of asciidoc, but I could get it to work
with this:

[#fig:001] 
image::authn-1.png[caption="Figure
{doc-part}-{counter:figure} ", reftext="Figure {doc-part}-{figure}",
title="Message Processing Model", align="center"]

An additional smaller issue is that vector
images have been reduced to low-resolution pngs. I'll see if I can redraw
some of them and include them as .svg. Not sure what source format would
be best acceptable, .odt perhaps? (technically .svg is editable too, but
not that easy).

Kind regards,
Arjan




On Wed, Jan 22, 2020 at 3:43 PM Kevin
Sutter <sutter@xxxxxxxxxx>
wrote:
Just to ensure
that everyone knows about this...  Based on our efforts for the Platform
and Web Profile Specs, we compiled some helpful hints.  I just referenced
these when I did the Jakarta-izing of the Managed Beans Spec and it helped
jog my memory.  Good luck!

https://github.com/jakartaee/specification-committee/blob/master/steps_javaee_to_jakartaee.adoc

---------------------------------------------------
Kevin Sutter 
STSM, MicroProfile and Jakarta EE architect @ IBM
e-mail:  sutter@xxxxxxxxxx    Twitter:  @kwsutter
phone: tl-553-3620 (office), 507-253-3620 (office)    
LinkedIn: https://www.linkedin.com/in/kevinwsutter



From:        Mark
Thomas <markt@xxxxxxxxxx>
To:        jakartaee-platform-dev@xxxxxxxxxxx
Date:        01/22/2020
08:29
Subject:        [EXTERNAL]
Re: [jakartaee-platform-dev] Spec doc conversion: heads-up
Sent by:        jakartaee-platform-dev-bounces@xxxxxxxxxxx

---

On 22/01/2020 11:54, Dmitry Kornilov wrote:
> I am currently working on JPA spec and facing the same issues. It’s
not difficult, but time consuming because there is no other way than doing
it manually section by section.

+1

Also, from experience of doing the EL and WebSocket specs watch for
escaping issues around code snippets.

I found there was a reasonable amount that could be done via search and
replace on the source but you have to review each one. You can't just do
a global search and replace.

And there was no getting away from the repeated cycles of generate PDF,
proof-read, correct, repeat.

Mark


> 
> - Dmitry
> 
>> On 22 Jan 2020, at 12:42, arjan tijms <arjan.tijms@xxxxxxxxx>
wrote:
>>
>> Hi,
>>
>> I just started with the JASPIC to Jakarta Authentication spec
document conversion, and just a heads-up for anyone who hasn't started
yet: it's quite labour intensive.
>>
>> Tables are completely missing, image captions are mistaken for
headings meaning section numbering and hierarchies are all wrong, even
chapter numbering can become all wrong, footnotes are missing, etc etc.
>>
>> This is far more than just a semi-automated search & replace
for terms as with the Javadocs adjustments for Jakarta EE 8.
>>
>> Basically it boils down to reading the entire document, adjusting
errors wherever you see them, compiling the PDF, checking it's correct
now and repeat that.
>>
>> Absolutely doable of course, but just taking a fair amount of
time.
>>
>> Kind regards,
>> Arjan
>>
>> _______________________________________________
>> jakartaee-platform-dev mailing list
>> jakartaee-platform-dev@xxxxxxxxxxx
>> To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
>> https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
> 
> _______________________________________________
> jakartaee-platform-dev mailing list
> jakartaee-platform-dev@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
> https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev
> 

_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev



_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev_______________________________________________
jakartaee-platform-dev mailing list
jakartaee-platform-dev@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://www.eclipse.org/mailman/listinfo/jakartaee-platform-dev