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 <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
--
Gil Barmwater
_______________________________________________
Oorexx-devel mailing list
Oorexx-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/oorexx-devel
