Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Rick McGuire]

I have multiple objections to this being included as is:

1) Wrong license
2) No ooRexx copyright statement
3) We don't put change logs in commentary. Source control is what manages
change logs.
4) We don't identify specific authors in any of our source files. Once
contributed, it is community owned.
5) I have the same objection to the name. If this is going to be part of
the project files, than it should not have the rgf_* name.
6) The scope of this goes beyond the need for the doc tooling. It would be
better if the relevant bits are just moved into createClassHierarchy.rex

createClassHierarchy.rex also has problems 1-4.

Rick

On Tue, Mar 24, 2020 at 2:31 PM Erich Steinböck 
wrote:

> ooRexx only accepts Common Public License v1.0
> You are providing your rgf_util2.rex under ASF 2.0
>
> On Mon, Mar 23, 2020 at 7:14 PM Rony G. Flatscher 
> wrote:
>
>> Hi Erich,
>>
>> On 22.03.2020 11:56, Erich Steinböck wrote:
>> > I agree with Gil.  Let's stay with our current coding/tagging style and
>> the typographic conventions.
>> I concur as well, see my follow-up to Gil's mail.
>> > Also, rgf_util2.rex is unacceptable for inclusion in our svn.  Please
>> fix the copyright or remove
>> > it from the svn, and please also do so for any other of your current or
>> future commits.
>>
>> What is the problem (I really do not understand)? What constitutes a
>> "fix"?
>>
>> ---rony
>>
>> ___
> Oorexx-devel mailing list
> Oorexx-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/oorexx-devel
>
___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Erich Steinböck]

ooRexx only accepts Common Public License v1.0
You are providing your rgf_util2.rex under ASF 2.0

On Mon, Mar 23, 2020 at 7:14 PM Rony G. Flatscher 
wrote:

> Hi Erich,
>
> On 22.03.2020 11:56, Erich Steinböck wrote:
> > I agree with Gil.  Let's stay with our current coding/tagging style and
> the typographic conventions.
> I concur as well, see my follow-up to Gil's mail.
> > Also, rgf_util2.rex is unacceptable for inclusion in our svn.  Please
> fix the copyright or remove
> > it from the svn, and please also do so for any other of your current or
> future commits.
>
> What is the problem (I really do not understand)? What constitutes a "fix"?
>
> ---rony
>
>
___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Erich Steinböck]

-
>
> have classnames, literals and the like marked up with the methodname tag
> in title elements to see its effect on the TOC formatting?
> Is it o.k. to use the methodname tag for marking up keywords, subkeywords
> and directives?

- I totally disagree with intentional mis-tagging.
-
- Only tag as much as it makes things more clear while still keeping the
document readable.
-
- And please never tag in a heading.
-
-

On Mon, Mar 23, 2020 at 7:11 PM Rony G. Flatscher 
wrote:

> Hi Gil,
> On 20.03.2020 19:07, Gil Barmwater wrote:
>
> I finally have had an opportunity to look into this issue. I downloaded
> your version of rexxpg and opened it next to the one that comes with the
> ooRexx build which is "pre-split" so it has none of the changes that you
> have made. One thing I noticed was that you have added tags "inside" the
> examples which I had not seen before. My understanding of the
>  tag was that it was supposed to show code examples or
> snippets "as-is" with the possible exception of syntax highlighting, a
> separate issue. Now, as you have demonstrated, you CAN "tag" parts of a
>  or  section but I don't see the benefit of doing so.
>
> You assume too much, there was no intention to mark-up text in
> programlisting elements! :)
>
> After splitting the book I noticed that the programmer's guide had much
> text that was not marked up. As with marking up the EventSemaphore or
> MutexSemaphore class I looked around those xml files to see what tags would
> be used to mark up the text and used it myself short of knowing the DocBook
> tags and when and where to apply them.
>
> Similarly, tagging words in the section titles causes the TOC (which is
> automatically generated) to display them accordingly. So, if it were me
> doing the work, I would only use the tags in the paragraphs where they draw
> the distinction between the prose and the "names" of important things.
>
> That is exactly what I have been trying to do as it is a *lot* of work to
> read and look through the text and marking up the text accordingly (this
> has not been work of a few hours but of a few days by now!).
>
> Ad TOC: I was under impression, after skimming through the css files, that
> the boldness in TOCs would be removed, cf. "css/common.css", lines 743-746:
>
> /* no bold in toc */
> .toc * {
>   font-weight: inherit;
> }
>
>
> Thought that the HTML formatting would follow the DocBook rendering, hence
> asking for a means to remove or at least reducing the boldness in the TOC.
>
> The overhauled version currently applies the mark-up to all the respective
> text, e.g. all class names in titles get marked up with the "classname"
> tag. However, they show as bold as do literals like .environment and .local
> which looks quite distracting for me.
>
> As this boldness in the TOC seems to be quite disturbing my original
> question about a possibility to remove/reduce the boldness from/in the TOC.
>
> Text that denotes classnames, literals and such IMHO should be
> distinguishable in its type from regular text in titles as well. One way to
> achieve that - which I know now - would be to mark-up such text with the
> methodname tag, which gets formatted to monospaced-normal according to the
> Conventions explanation.
>
> Would that be something everyone could agree upon in theory?
>
> If so I would change that title markup accordingly to render a new version
> of rexxpg for assessment and comparison to finally decide upon it. (I just
> would like to save me the work if everyone thinks it is not worth to test.)
>
> Again, just my opinion. Our documents have always only used the three
> types of typographic conventions described in the the Preface of each book.
> Deviating from that "standard" needs a whole lot more discussion and
> consideration IMHO.
>
> I agree.
>
> While analyzing and overhauling the markup in the past days I created a
> "test" book that includes the markup that the ooRexx books use, which are
> by far not all the elements that DocBook defines as I have found out (cf.
> 
> ).
>
> The directory "oorexx/en_US" seems to have all the files from some DocBook
> distribution. Its Conventions.xml demonstrates many more elements, such
> that I have included them in the aforementioned "test" book just to see -
> after formatting the test book - which elements render how and whether
> there are elements that we do not use but might be useful.
>
> There could be much more said after all that work and research, but maybe
> at another occasion.
>
> After almost finishing the overhaul, there is another markup that may need
> agreement: marking up keywords (and subkeywords) and directives. I have
> applied the methodname tag (monospaced-normal) for them, short of better
> matching tag names, thinking that they ought to be set the same as method
> names.
>
> Please take a look at that and please give feedback ASAP whether that is
> o.k.?
>
> 

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[P.O. Jonsson]

Dear Rony,

I have collected the 12003 doc build from Jenkins and put it in my dropbox 
, 
where you can collect them. Rexxpg is r12001 still.

It is quite easy to get them from Jenkins, just log in to Jenkins, select the 
job ooRexx-docs-build -> Workspace -> PDF_files

If you want to make a new build of the complete documentation make sure that 
Win32 or Win64 is not building at the same time, I have not tested this in 
parallel on the same machine (yet).

Hälsningar/Regards/Grüsse,
P.O. Jonsson
oor...@jonases.se



> Am 24.03.2020 um 14:18 schrieb Rony G. Flatscher :
> 
> Forgot to check in my changes that have led to yesterday's rendering of the 
> rexxpg book, checked in with r12003.
> 
> ---rony
> On 23.03.2020 19:09, Rony G. Flatscher wrote:
>> Hi Gil,
>> On 20.03.2020 19:07, Gil Barmwater wrote:
>>> I finally have had an opportunity to look into this issue. I downloaded 
>>> your version of rexxpg and opened it next to the one that comes with the 
>>> ooRexx build which is "pre-split" so it has none of the changes that you 
>>> have made. One thing I noticed was that you have added tags "inside" the 
>>> examples which I had not seen before. My understanding of the 
>>>  tag was that it was supposed to show code examples or 
>>> snippets "as-is" with the possible exception of syntax highlighting, a 
>>> separate issue. Now, as you have demonstrated, you CAN "tag" parts of a 
>>>  or  section but I don't see the benefit of doing so.
>> You assume too much, there was no intention to mark-up text in 
>> programlisting elements! :)
>> 
>> After splitting the book I noticed that the programmer's guide had much text 
>> that was not marked up. As with marking up the EventSemaphore or 
>> MutexSemaphore class I looked around those xml files to see what tags would 
>> be used to mark up the text and used it myself short of knowing the DocBook 
>> tags and when and where to apply them.
>>> Similarly, tagging words in the section titles causes the TOC (which is 
>>> automatically generated) to display them accordingly. So, if it were me 
>>> doing the work, I would only use the tags in the paragraphs where they draw 
>>> the distinction between the prose and the "names" of important things.
>> That is exactly what I have been trying to do as it is a *lot* of work to 
>> read and look through the text and marking up the text accordingly (this has 
>> not been work of a few hours but of a few days by now!). 
>> 
>> Ad TOC: I was under impression, after skimming through the css files, that 
>> the boldness in TOCs would be removed, cf. "css/common.css", lines 743-746:
>> /* no bold in toc */
>> .toc * {
>>  font-weight: inherit;
>> }
>> 
>> Thought that the HTML formatting would follow the DocBook rendering, hence 
>> asking for a means to remove or at least reducing the boldness in the TOC.
>> 
>> The overhauled version currently applies the mark-up to all the respective 
>> text, e.g. all class names in titles get marked up with the "classname" tag. 
>> However, they show as bold as do literals like .environment and .local which 
>> looks quite distracting for me.
>> 
>> As this boldness in the TOC seems to be quite disturbing my original 
>> question about a possibility to remove/reduce the boldness from/in the TOC.
>> 
>> Text that denotes classnames, literals and such IMHO should be 
>> distinguishable in its type from regular text in titles as well. One way to 
>> achieve that - which I know now - would be to mark-up such text with the 
>> methodname tag, which gets formatted to monospaced-normal according to the 
>> Conventions explanation. 
>> Would that be something everyone could agree upon in theory? 
>> If so I would change that title markup accordingly to render a new version 
>> of rexxpg for assessment and comparison to finally decide upon it. (I just 
>> would like to save me the work if everyone thinks it is not worth to test.)
>>> Again, just my opinion. Our documents have always only used the three types 
>>> of typographic conventions described in the the Preface of each book. 
>>> Deviating from that "standard" needs a whole lot more discussion and 
>>> consideration IMHO. 
>> I agree.
>> 
>> While analyzing and overhauling the markup in the past days I created a 
>> "test" book that includes the markup that the ooRexx books use, which are by 
>> far not all the elements that DocBook defines as I have found out (cf. 
>>  
>> ). 
>> The directory "oorexx/en_US" seems to have all the files from some DocBook 
>> distribution. Its Conventions.xml demonstrates many more elements, such that 
>> I have included them in the aforementioned "test" book just to see - after 
>> formatting the test book - which elements render how and whether there are 
>> elements that we do not use but might be useful. 
>> There could be much more said 

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Chip Davis]

Gosh, Gil.  Don't say _that_.  These days you're better off saying, 
"My hemorrhoids are flaring up and I can't sit at the computer" than 
let people speculate that you've come down with SARS-CoV2 ... :-X


On 3/24/2020 10:57 AM, Gil Barmwater wrote:


FYI - my "silence" on this thread is not due to lack of interest or 
having no comment but rather to being a bit "under the weather" at 
the moment. As soon as I am able, I will offer my thoughts.




___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Gil Barmwater]

FYI - my "silence" on this thread is not due to lack of interest or 
having no comment but rather to being a bit "under the weather" at the 
moment. As soon as I am able, I will offer my thoughts.


Gil

On 3/24/2020 9:18 AM, Rony G. Flatscher wrote:


Forgot to check in my changes that have led to yesterday's rendering 
of the rexxpg book, checked in with r12003.


---rony

On 23.03.2020 19:09, Rony G. Flatscher wrote:


Hi Gil,

On 20.03.2020 19:07, Gil Barmwater wrote:
I finally have had an opportunity to look into this issue. I 
downloaded your version of rexxpg and opened it next to the one that 
comes with the ooRexx build which is "pre-split" so it has none of 
the changes that you have made. One thing I noticed was that you 
have added tags "inside" the examples which I had not seen before. 
My understanding of the  tag was that it was 
supposed to show code examples or snippets "as-is" with the possible 
exception of syntax highlighting, a separate issue. Now, as you have 
demonstrated, you CAN "tag" parts of a  or  
section but I don't see the benefit of doing so. 


You assume too much, there was no intention to mark-up text in 
programlisting elements! :)


After splitting the book I noticed that the programmer's guide had 
much text that was not marked up. As with marking up the 
EventSemaphore or MutexSemaphore class I looked around those xml 
files to see what tags would be used to mark up the text and used it 
myself short of knowing the DocBook tags and when and where to apply 
them.


Similarly, tagging words in the section titles causes the TOC (which 
is automatically generated) to display them accordingly. So, if it 
were me doing the work, I would only use the tags in the paragraphs 
where they draw the distinction between the prose and the "names" of 
important things. 


That is exactly what I have been trying to do as it is a *lot* of 
work to read and look through the text and marking up the text 
accordingly (this has not been work of a few hours but of a few days 
by now!).


Ad TOC: I was under impression, after skimming through the css files, 
that the boldness in TOCs would be removed, cf. "css/common.css", 
lines 743-746:


/* no bold in toc */
.toc * {
font-weight: inherit;
}

Thought that the HTML formatting would follow the DocBook rendering, 
hence asking for a means to remove or at least reducing the boldness 
in the TOC.


The overhauled version currently applies the mark-up to all the 
respective text, e.g. all class names in titles get marked up with 
the "classname" tag. However, they show as bold as do literals like 
.environment and .local which looks quite distracting for me.


As this boldness in the TOC seems to be quite disturbing my original 
question about a possibility to remove/reduce the boldness from/in 
the TOC.


Text that denotes classnames, literals and such IMHO should be 
distinguishable in its type from regular text in titles as well. One 
way to achieve that - which I know now - would be to mark-up such 
text with the methodname tag, which gets formatted to 
monospaced-normal according to the Conventions explanation.


Would that be something everyone could agree upon in theory?

If so I would change that title markup accordingly to render a new 
version of rexxpg for assessment and comparison to finally decide 
upon it. (I just would like to save me the work if everyone thinks it 
is not worth to test.)


Again, just my opinion. Our documents have always only used the 
three types of typographic conventions described in the the Preface 
of each book. Deviating from that "standard" needs a whole lot more 
discussion and consideration IMHO.


I agree.

While analyzing and overhauling the markup in the past days I created 
a "test" book that includes the markup that the ooRexx books use, 
which are by far not all the elements that DocBook defines as I have 
found out (cf. ).


The directory "oorexx/en_US" seems to have all the files from some 
DocBook distribution. Its Conventions.xml demonstrates many more 
elements, such that I have included them in the aforementioned "test" 
book just to see - after formatting the test book - which elements 
render how and whether there are elements that we do not use but 
might be useful.


There could be much more said after all that work and research, but 
maybe at another occasion.


After almost finishing the overhaul, there is another markup that may 
need agreement: marking up keywords (and subkeywords) and directives. 
I have applied the methodname tag (monospaced-normal) for them, short 
of better matching tag names, thinking that they ought to be set the 
same as method names.


Please take a look at that and please give feedback ASAP whether that 
is o.k.?


If it is o.k. the "Document Conventions" need to be changed 
accordingly as well.




On 3/20/2020 9:15 AM, Rony G. Flatscher wrote:

On 19.03.2020 14:31, Gil Barmwater wrote:
Having 

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[P.O. Jonsson]

Dear Rony,

The build of documentation on Jenkins has not run since the 20th, the revision 
for rexxpg is 11998.

I am rebuilding the documentation now, in an hour I can see if it built ok.

(The Win slave had rebooted without reconnecting, this happens every now & 
then. MS.)

Hälsningar/Regards/Grüsse,
P.O. Jonsson
oor...@jonases.se



> Am 24.03.2020 um 14:18 schrieb Rony G. Flatscher :
> 
> Forgot to check in my changes that have led to yesterday's rendering of the 
> rexxpg book, checked in with r12003.
> 
> ---rony
> On 23.03.2020 19:09, Rony G. Flatscher wrote:
>> Hi Gil,
>> On 20.03.2020 19:07, Gil Barmwater wrote:
>>> I finally have had an opportunity to look into this issue. I downloaded 
>>> your version of rexxpg and opened it next to the one that comes with the 
>>> ooRexx build which is "pre-split" so it has none of the changes that you 
>>> have made. One thing I noticed was that you have added tags "inside" the 
>>> examples which I had not seen before. My understanding of the 
>>>  tag was that it was supposed to show code examples or 
>>> snippets "as-is" with the possible exception of syntax highlighting, a 
>>> separate issue. Now, as you have demonstrated, you CAN "tag" parts of a 
>>>  or  section but I don't see the benefit of doing so.
>> You assume too much, there was no intention to mark-up text in 
>> programlisting elements! :)
>> 
>> After splitting the book I noticed that the programmer's guide had much text 
>> that was not marked up. As with marking up the EventSemaphore or 
>> MutexSemaphore class I looked around those xml files to see what tags would 
>> be used to mark up the text and used it myself short of knowing the DocBook 
>> tags and when and where to apply them.
>>> Similarly, tagging words in the section titles causes the TOC (which is 
>>> automatically generated) to display them accordingly. So, if it were me 
>>> doing the work, I would only use the tags in the paragraphs where they draw 
>>> the distinction between the prose and the "names" of important things.
>> That is exactly what I have been trying to do as it is a *lot* of work to 
>> read and look through the text and marking up the text accordingly (this has 
>> not been work of a few hours but of a few days by now!). 
>> 
>> Ad TOC: I was under impression, after skimming through the css files, that 
>> the boldness in TOCs would be removed, cf. "css/common.css", lines 743-746:
>> /* no bold in toc */
>> .toc * {
>>  font-weight: inherit;
>> }
>> 
>> Thought that the HTML formatting would follow the DocBook rendering, hence 
>> asking for a means to remove or at least reducing the boldness in the TOC.
>> 
>> The overhauled version currently applies the mark-up to all the respective 
>> text, e.g. all class names in titles get marked up with the "classname" tag. 
>> However, they show as bold as do literals like .environment and .local which 
>> looks quite distracting for me.
>> 
>> As this boldness in the TOC seems to be quite disturbing my original 
>> question about a possibility to remove/reduce the boldness from/in the TOC.
>> 
>> Text that denotes classnames, literals and such IMHO should be 
>> distinguishable in its type from regular text in titles as well. One way to 
>> achieve that - which I know now - would be to mark-up such text with the 
>> methodname tag, which gets formatted to monospaced-normal according to the 
>> Conventions explanation. 
>> Would that be something everyone could agree upon in theory? 
>> If so I would change that title markup accordingly to render a new version 
>> of rexxpg for assessment and comparison to finally decide upon it. (I just 
>> would like to save me the work if everyone thinks it is not worth to test.)
>>> Again, just my opinion. Our documents have always only used the three types 
>>> of typographic conventions described in the the Preface of each book. 
>>> Deviating from that "standard" needs a whole lot more discussion and 
>>> consideration IMHO. 
>> I agree.
>> 
>> While analyzing and overhauling the markup in the past days I created a 
>> "test" book that includes the markup that the ooRexx books use, which are by 
>> far not all the elements that DocBook defines as I have found out (cf. 
>>  
>> ). 
>> The directory "oorexx/en_US" seems to have all the files from some DocBook 
>> distribution. Its Conventions.xml demonstrates many more elements, such that 
>> I have included them in the aforementioned "test" book just to see - after 
>> formatting the test book - which elements render how and whether there are 
>> elements that we do not use but might be useful. 
>> There could be much more said after all that work and research, but maybe at 
>> another occasion. 
>> After almost finishing the overhaul, there is another markup that may need 
>> agreement: marking up keywords (and subkeywords) and directives. I have 
>> applied the methodname tag 

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Rony G. Flatscher]

Forgot to check in my changes that have led to yesterday's rendering of the 
rexxpg book, checked in
with r12003.

---rony

On 23.03.2020 19:09, Rony G. Flatscher wrote:
>
> Hi Gil,
>
> On 20.03.2020 19:07, Gil Barmwater wrote:
>> I finally have had an opportunity to look into this issue. I downloaded your 
>> version of rexxpg
>> and opened it next to the one that comes with the ooRexx build which is 
>> "pre-split" so it has
>> none of the changes that you have made. One thing I noticed was that you 
>> have added tags "inside"
>> the examples which I had not seen before. My understanding of the 
>>  tag was that
>> it was supposed to show code examples or snippets "as-is" with the possible 
>> exception of syntax
>> highlighting, a separate issue. Now, as you have demonstrated, you CAN "tag" 
>> parts of a  or
>>  section but I don't see the benefit of doing so. 
>
> You assume too much, there was no intention to mark-up text in programlisting 
> elements! :)
>
> After splitting the book I noticed that the programmer's guide had much text 
> that was not marked
> up. As with marking up the EventSemaphore or MutexSemaphore class I looked 
> around those xml files
> to see what tags would be used to mark up the text and used it myself short 
> of knowing the DocBook
> tags and when and where to apply them.
>
>> Similarly, tagging words in the section titles causes the TOC (which is 
>> automatically generated)
>> to display them accordingly. So, if it were me doing the work, I would only 
>> use the tags in the
>> paragraphs where they draw the distinction between the prose and the "names" 
>> of important things. 
>
> That is exactly what I have been trying to do as it is a *lot* of work to 
> read and look through
> the text and marking up the text accordingly (this has not been work of a few 
> hours but of a few
> days by now!). 
>
> Ad TOC: I was under impression, after skimming through the css files, that 
> the boldness in TOCs
> would be removed, cf. "css/common.css", lines 743-746:
>
> /* no bold in toc */
> .toc * {
>   font-weight: inherit;
> }
>
> Thought that the HTML formatting would follow the DocBook rendering, hence 
> asking for a means to
> remove or at least reducing the boldness in the TOC.
>
> The overhauled version currently applies the mark-up to all the respective 
> text, e.g. all class
> names in titles get marked up with the "classname" tag. However, they show as 
> bold as do literals
> like .environment and .local which looks quite distracting for me.
>
> As this boldness in the TOC seems to be quite disturbing my original question 
> about a possibility
> to remove/reduce the boldness from/in the TOC.
>
> Text that denotes classnames, literals and such IMHO should be 
> distinguishable in its type from
> regular text in titles as well. One way to achieve that - which I know now - 
> would be to mark-up
> such text with the methodname tag, which gets formatted to monospaced-normal 
> according to the
> Conventions explanation.
>
> Would that be something everyone could agree upon in theory?
>
> If so I would change that title markup accordingly to render a new version of 
> rexxpg for
> assessment and comparison to finally decide upon it. (I just would like to 
> save me the work if
> everyone thinks it is not worth to test.)
>
>> Again, just my opinion. Our documents have always only used the three types 
>> of typographic
>> conventions described in the the Preface of each book. Deviating from that 
>> "standard" needs a
>> whole lot more discussion and consideration IMHO.
>
> I agree.
>
> While analyzing and overhauling the markup in the past days I created a 
> "test" book that includes
> the markup that the ooRexx books use, which are by far not all the elements 
> that DocBook defines
> as I have found out (cf. ).
>
> The directory "oorexx/en_US" seems to have all the files from some DocBook 
> distribution. Its
> Conventions.xml demonstrates many more elements, such that I have included 
> them in the
> aforementioned "test" book just to see - after formatting the test book - 
> which elements render
> how and whether there are elements that we do not use but might be useful.
>
> There could be much more said after all that work and research, but maybe at 
> another occasion.
>
> After almost finishing the overhaul, there is another markup that may need 
> agreement: marking up
> keywords (and subkeywords) and directives. I have applied the methodname tag 
> (monospaced-normal)
> for them, short of better matching tag names, thinking that they ought to be 
> set the same as
> method names.
>
> Please take a look at that and please give feedback ASAP whether that is o.k.?
>
> If it is o.k. the "Document Conventions" need to be changed accordingly as 
> well.
>
>>
>> On 3/20/2020 9:15 AM, Rony G. Flatscher wrote:
>>> On 19.03.2020 14:31, Gil Barmwater wrote:
 Having spent some time looking at the 

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Rony G. Flatscher]

Hi Erich,

On 22.03.2020 11:56, Erich Steinböck wrote:
> I agree with Gil.  Let's stay with our current coding/tagging style and the 
> typographic conventions.
I concur as well, see my follow-up to Gil's mail.
> Also, rgf_util2.rex is unacceptable for inclusion in our svn.  Please fix the 
> copyright or remove
> it from the svn, and please also do so for any other of your current or 
> future commits.

What is the problem (I really do not understand)? What constitutes a "fix"?

---rony






___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Rony G. Flatscher]

Hi Gil,

On 20.03.2020 19:07, Gil Barmwater wrote:
> I finally have had an opportunity to look into this issue. I downloaded your 
> version of rexxpg and
> opened it next to the one that comes with the ooRexx build which is 
> "pre-split" so it has none of
> the changes that you have made. One thing I noticed was that you have added 
> tags "inside" the
> examples which I had not seen before. My understanding of the 
>  tag was that it was
> supposed to show code examples or snippets "as-is" with the possible 
> exception of syntax
> highlighting, a separate issue. Now, as you have demonstrated, you CAN "tag" 
> parts of a  or
>  section but I don't see the benefit of doing so. 

You assume too much, there was no intention to mark-up text in programlisting 
elements! :)

After splitting the book I noticed that the programmer's guide had much text 
that was not marked up.
As with marking up the EventSemaphore or MutexSemaphore class I looked around 
those xml files to see
what tags would be used to mark up the text and used it myself short of knowing 
the DocBook tags and
when and where to apply them.

> Similarly, tagging words in the section titles causes the TOC (which is 
> automatically generated)
> to display them accordingly. So, if it were me doing the work, I would only 
> use the tags in the
> paragraphs where they draw the distinction between the prose and the "names" 
> of important things. 

That is exactly what I have been trying to do as it is a *lot* of work to read 
and look through the
text and marking up the text accordingly (this has not been work of a few hours 
but of a few days by
now!). 

Ad TOC: I was under impression, after skimming through the css files, that the 
boldness in TOCs
would be removed, cf. "css/common.css", lines 743-746:

/* no bold in toc */
.toc * {
font-weight: inherit;
}

Thought that the HTML formatting would follow the DocBook rendering, hence 
asking for a means to
remove or at least reducing the boldness in the TOC.

The overhauled version currently applies the mark-up to all the respective 
text, e.g. all class
names in titles get marked up with the "classname" tag. However, they show as 
bold as do literals
like .environment and .local which looks quite distracting for me.

As this boldness in the TOC seems to be quite disturbing my original question 
about a possibility to
remove/reduce the boldness from/in the TOC.

Text that denotes classnames, literals and such IMHO should be distinguishable 
in its type from
regular text in titles as well. One way to achieve that - which I know now - 
would be to mark-up
such text with the methodname tag, which gets formatted to monospaced-normal 
according to the
Conventions explanation.

Would that be something everyone could agree upon in theory?

If so I would change that title markup accordingly to render a new version of 
rexxpg for assessment
and comparison to finally decide upon it. (I just would like to save me the 
work if everyone thinks
it is not worth to test.)

> Again, just my opinion. Our documents have always only used the three types 
> of typographic
> conventions described in the the Preface of each book. Deviating from that 
> "standard" needs a
> whole lot more discussion and consideration IMHO.

I agree.

While analyzing and overhauling the markup in the past days I created a "test" 
book that includes
the markup that the ooRexx books use, which are by far not all the elements 
that DocBook defines as
I have found out (cf. ).

The directory "oorexx/en_US" seems to have all the files from some DocBook 
distribution. Its
Conventions.xml demonstrates many more elements, such that I have included them 
in the
aforementioned "test" book just to see - after formatting the test book - which 
elements render how
and whether there are elements that we do not use but might be useful.

There could be much more said after all that work and research, but maybe at 
another occasion.

After almost finishing the overhaul, there is another markup that may need 
agreement: marking up
keywords (and subkeywords) and directives. I have applied the methodname tag 
(monospaced-normal) for
them, short of better matching tag names, thinking that they ought to be set 
the same as method names.

Please take a look at that and please give feedback ASAP whether that is o.k.?

If it is o.k. the "Document Conventions" need to be changed accordingly as well.

>
> On 3/20/2020 9:15 AM, Rony G. Flatscher wrote:
>> On 19.03.2020 14:31, Gil Barmwater wrote:
>>> Having spent some time looking at the documentation while developing the 
>>> system to build the
>>> books, I found that we actually have a set of conventions on how things are 
>>> displayed. This is
>>> part of every document, under the title "Typographic Conventions", right 
>>> near the beginning of the
>>> book. So this proposal seems rather extreme to me as it could have a major 
>>> impact on all our

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Erich Steinböck]

Rony,
I agree with Gil.  Let's stay with our current coding/tagging style and the
typographic conventions.

Also, rgf_util2.rex is unacceptable for inclusion in our svn.  Please fix
the copyright or remove it from the svn, and please also do so for any
other of your current or future commits.
___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Gil Barmwater]

Hi Rony,

I finally have had an opportunity to look into this issue. I downloaded 
your version of rexxpg and opened it next to the one that comes with the 
ooRexx build which is "pre-split" so it has none of the changes that you 
have made. One thing I noticed was that you have added tags "inside" the 
examples which I had not seen before. My understanding of the 
 tag was that it was supposed to show code examples or 
snippets "as-is" with the possible exception of syntax highlighting, a 
separate issue. Now, as you have demonstrated, you CAN "tag" parts of a 
 or  section but I don't see the benefit of doing 
so. Similarly, tagging words in the section titles causes the TOC (which 
is automatically generated) to display them accordingly. So, if it were 
me doing the work, I would only use the tags in the paragraphs where 
they draw the distinction between the prose and the "names" of important 
things. Again, just my opinion. Our documents have always only used the 
three types of typographic conventions described in the the Preface of 
each book. Deviating from that "standard" needs a whole lot more 
discussion and consideration IMHO.


Gil

On 3/20/2020 9:15 AM, Rony G. Flatscher wrote:

On 19.03.2020 14:31, Gil Barmwater wrote:

Having spent some time looking at the documentation while developing the system 
to build the
books, I found that we actually have a set of conventions on how things are 
displayed. This is
part of every document, under the title "Typographic Conventions", right near 
the beginning of the
book. So this proposal seems rather extreme to me as it could have a major 
impact on all our
documents. Just my opinion.


Gil, of course there is no intention to have any negative impact on the 
documentation!

The current boldness is quite strong and looking at the rexxpg book (also in 
the TOC!) the bolded,
monotype text stands out prominently. Hence wondering whether removing the 
boldness (but leaving it)
to semi-bold would be possible at all. And if it was possible it still needs to 
be assessed whether
it negatively impacts the overall look-and feel of the books.

---rony




___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel


--
Gil Barmwater



___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Rony G. Flatscher]

On 20.03.2020 14:23, René Jansen wrote:
> just want to correct one terminology issue: a monotype font is a font from a 
> specific foundry, a monospaced (or non-proportional) font is what you mean.

Ah, yes, thank you René, also: 
.

---rony

___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[René Jansen]

just want to correct one terminology issue: a monotype font is a font from a 
specific foundry, a monospaced (or non-proportional) font is what you mean.

> On 20 Mar 2020, at 14:15, Rony G. Flatscher  wrote:
> 
> On 19.03.2020 14:31, Gil Barmwater wrote:
>> 
>> Having spent some time looking at the documentation while developing the 
>> system to build the
>> books, I found that we actually have a set of conventions on how things are 
>> displayed. This is
>> part of every document, under the title "Typographic Conventions", right 
>> near the beginning of the
>> book. So this proposal seems rather extreme to me as it could have a major 
>> impact on all our
>> documents. Just my opinion.
>> 
> Gil, of course there is no intention to have any negative impact on the 
> documentation!
> 
> The current boldness is quite strong and looking at the rexxpg book (also in 
> the TOC!) the bolded,
> monotype text stands out prominently. Hence wondering whether removing the 
> boldness (but leaving it)
> to semi-bold would be possible at all. And if it was possible it still needs 
> to be assessed whether
> it negatively impacts the overall look-and feel of the books.
> 
> ---rony
> 
> 
> 
> 
> ___
> Oorexx-devel mailing list
> Oorexx-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/oorexx-devel



___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Rony G. Flatscher]

On 19.03.2020 14:31, Gil Barmwater wrote:
>
> Having spent some time looking at the documentation while developing the 
> system to build the
> books, I found that we actually have a set of conventions on how things are 
> displayed. This is
> part of every document, under the title "Typographic Conventions", right near 
> the beginning of the
> book. So this proposal seems rather extreme to me as it could have a major 
> impact on all our
> documents. Just my opinion.
>
Gil, of course there is no intention to have any negative impact on the 
documentation!

The current boldness is quite strong and looking at the rexxpg book (also in 
the TOC!) the bolded,
monotype text stands out prominently. Hence wondering whether removing the 
boldness (but leaving it)
to semi-bold would be possible at all. And if it was possible it still needs to 
be assessed whether
it negatively impacts the overall look-and feel of the books.

---rony




___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Documentation: using less bold font for some elements ?

[Gil Barmwater]

Having spent some time looking at the documentation while developing the 
system to build the books, I found that we actually have a set of 
conventions on how things are displayed. This is part of every document, 
under the title "Typographic Conventions", right near the beginning of 
the book. So this proposal seems rather extreme to me as it could have a 
major impact on all our documents. Just my opinion. Gil


On 3/19/2020 6:55 AM, Rony G. Flatscher wrote:


While working on the documentation I learned the following elements 
being typeset in monotype font, however all are using the boldest 
version of the font which in the case of rexxpg makes some elements 
stand out far too strong.


So the question would be whether it was possible to format the 
monotype elements like "code" to not be as bold (maybe semi-bold) or 
alternatively, not being bold at all but italicized instead?


These elements are typeset the same way (monotype and in the boldest 
possible font, it seems):


  * code
  * computeroutput
  * filename
  * literal

Just look up the rexxpg book where the boldness communicates an 
importness above all other text and is distracting (like in the table 
of context).


What do you think?

---rony



___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel


--
Gil Barmwater

___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel