Dear Rony,
I have collected the 12003 doc build from Jenkins and put it in my dropbox
<https://www.dropbox.com/sh/p66c7g01h4jz5ss/AAAZd_Q2yQddrTHagxPo_UiTa?dl=0>,
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 <rony.flatsc...@wu.ac.at>:
>
> 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
>>> <programlisting> 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
>>> <code> or <programlisting> 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.
>> <https://tdg.docbook.org/tdg/4.5/part2.html>
>> <https://tdg.docbook.org/tdg/4.5/part2.html>).
>> 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
>>>>> 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.
>> The idea of a less bold, but still bold font has come up for me because
>> there different kinds of boldness in types and therefore I thought that
>> there may be a possibility to have a less bold font to express boldness and
>> then have a possibility to compare. However, this is nothing very important,
>> especially at this point in time where there may be much more challenges
>> still left in the creation of the books.
>>
>> Also, experiments, discussions and exchanges like this have become possible
>> only, because you made it easy to create the ooRexx documentation, Gil! :)
>>
>> Summary of questions:
>>
>> Assuming that removing boldness from TOC is not really possible at this
>> time, should I try to 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?
>> ---rony
>>
>> [1] Current version of rexxpg.pdf:
>> <https://www.dropbox.com/sh/gxvvgskb04gdsqf/AACRo_ZLeFOdoBXUHroPY_-Ca?dl=0>
>> <https://www.dropbox.com/sh/gxvvgskb04gdsqf/AACRo_ZLeFOdoBXUHroPY_-Ca?dl=0>
>> P.S.: The reason why I did not notice that I would add markup to some of the
>> programlisting elements was that all text has been given in an endless
>> stream of lines empty lines displacing different elements which is possible
>> in such markup ("ignorable whitespace"). So I added empty lines before and
>> after such elements to make them stand out in the XML text.
>
> _______________________________________________
> 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
