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>).
>
> 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>
>
> 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
