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] Question on documentation, Rexxref, 8.74. SysTempFileName

[Erich Steinböck]

Hi P.O.,
yes, SysTempFileName is expected to now work identically on all platforms.
Providing a test case would be great
___
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel

Re: [Oorexx-devel] Question on documentation, Rexxref, 8.74. SysTempFileName

[P.O. Jonsson]

Dear Gil,

I guess running it on all platforms once does not qualify for a test :-). I´ll 
leave it to someone with more insight to do it then, or are you telling me I 
should write a test case for it? I can do that. 

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



> Am 22.03.2020 um 21:39 schrieb Gil Barmwater :
> 
> P.O.,
> 
> See RFE #745; the last comment says that the tests and doc updates are still 
> to be done.
> Gil
> On 3/22/2020 11:18 AM, P.O. Jonsson wrote:
>> Dear developers,
>> 
>> SysTempFileName now works differently (read: better) compared to ooRexx 4 
>> for Linux/macOS and I wanted to amend the documentation accordingly. 
>> 
>> From what I can see from using SysTempFileName() it behaves exactly the same 
>> for all platforms, Is this correctly understood, or is there a difference 
>> that I have not spotted?
>> 
>> If there is indeed no difference I will remove the separate sections for 
>> Win/Linux and amend the code snippet accordingly.
>> 
>> Hälsningar/Regards/Grüsse,
>> P.O. Jonsson
>> oor...@jonases.se 
>> 
>> 
>> ___
>> 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

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