-
>
> 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 <rony.flatsc...@wu.ac.at>
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
