Re: [jakarta.ee-spec.committee] convention for class names in specs?

["Kevin Sutter" <sutter@xxxxxxxxxx>]

Do we really care
whether the class names are fixed width or not?  As long as a given
spec is consistent within itself, isn't that sufficient?  That way,
if Scott likes fixed width for CDI and I like a readable font for ManagedBeans,
we're both happy.  (Just using this as an example.)

BTW, through my
reading of these various specs, I think I have also seen the convention
of italicizing the class and/or method names.  Again, I'm not trying
to advocate for this usage either.  Just showing that there may be
preferences on a per team basis and I personally think that's okay.

---------------------------------------------------
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:
       Bill
Shannon <bill.shannon@xxxxxxxxxx>
To:
       Jakarta
specification committee <jakarta.ee-spec.committee@xxxxxxxxxxx>,
Scott Stark <sstark@xxxxxxxxxx>
Date:
       01/17/2020
13:06
Subject:
       [EXTERNAL]
Re: [jakarta.ee-spec.committee] convention for class names in specs?
Sent
by:        jakarta.ee-spec.committee-bounces@xxxxxxxxxxx

---

Ok, early returns are leaning towards
fixed width font.  Let's hear from
some more people!  (I suppose I should put this out to the community
list.)

Are we really voting to make our specs *less* readable?

I don't suppose anyone wants to go so far as to say that every mention
of
a class name ought to be a hyperlink to the javadocs for that class?
(Please, no.)

Scott Stark wrote on 1/17/20 10:00 AM:
> I prefer that code elements use the fixed width font wherever they
> appear, but do agree this does tend to make the main text less
> readable.
> 
> On Fri, Jan 17, 2020 at 2:02 AM Bill Shannon <bill.shannon@xxxxxxxxxx>
wrote:
>>
>> What's our preferred convention for use of class names in spec
documents?
>>
>> Should class names (and other Java programming language elements)
appear
>> in a fixed width font in the document?
>>
>> Or should they use the same font as the surrounding text?
>>
>> (This is ignoring blocks of code, which I believe should always
be in a
>> fixed width font.)
>>
>> The "pro" is that using a fixed width font makes it
clear that this is
>> a Java class name being referred to.
>>
>> The "con" is that it clutters up the text making it
harder to read with
>> lots of font changes.
>>
>> Comments?
>> _______________________________________________
>> jakarta.ee-spec.committee mailing list
>> jakarta.ee-spec.committee@xxxxxxxxxxx
>> To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
>> https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee
>>
> 
> _______________________________________________
> jakarta.ee-spec.committee mailing list
> jakarta.ee-spec.committee@xxxxxxxxxxx
> To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
> https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee
> 
_______________________________________________
jakarta.ee-spec.committee mailing list
jakarta.ee-spec.committee@xxxxxxxxxxx
To change your delivery options, retrieve your password, or unsubscribe
from this list, visit
https://www.eclipse.org/mailman/listinfo/jakarta.ee-spec.committee