Re: mdocml's .Ql doesn't map to original and GNU mdoc(7)

[Steffen Nurpmeso <sdaoden@yandex.com>]

Hallo Ingo,

Ingo Schwarze <schwarze@usta.de> wrote:
 |Steffen Nurpmeso wrote on Thu, Jan 01, 2015 at 08:01:36PM +0100:
 |> seems to happily ignore to replace that style-centric
 |> 
 |>   -.It Sx \&Ql Ta single-quoted literal text: Ql text
 |> 
 |> with the definitely more correct semantics-centric
 |> 
 |>   +.It Sx \&Ql Ta format quoted literal text: Ql text
 |> 
 |> which the quoted literal mark-up command .Ql is all about.
 |
 |The mdoc(7) language is somewhat inconsistent in the following
 |respect: It contains many macros that are purely semantic, but also
 |some that are purely presentational (and even some abominations
 |that are a bit of both, like .Tn).  It's the same ailing that
 |traditional HTML had, and that is now mostly resolved in HTML5 -

I'll never forget the picture from a W3C conference meeting
with all those happy guys in that palm covered bay.  So it seemed
to me HTML5 resolved quite some issues after all.

 |no wonder since both mdoc(7) and traditional HTML date from the
 |same time, plus/minus less than five years.

I never have thought about a relationship in between that
simplified SGML and runoff...  Thinking of it, the latter term as
such is a strong relationship, though.  ;-)

 |The .Ql macro is one of those that are purely presentational.

It is an inline literal, formatted in a way that makes it obvious
that it is a literal, even on a TTY with only a single fixed-width
font.

 |It requests two things: "literal font" (which is a purely
 |presentational aspect) and "single quotes" (which is a purely
 |presentational aspect just as well).

No, no that is not how i see it.  I _think_ of it in terms of
<code></code> rather than <tt></tt>.  Because i only know .Dl
(which rather requires a leading .Pp) and ".Bd -literal" to
achieve the same for a block, no macro that i know of except .Ql
can be used to display some code inline.

That it uses typographic single quotes to mark the inner text as
a literal on a TTY is -- maybe, i think -- pretty random;  yet
single quotes stand out differently than double quotes which may
also have other regular uses.  Or say: using single quotes would
only fail to be recognized immediately as something remarkably
different (a "quoted literal") inside text that is enclosed in
double quotes.  Right?

 |So, for a one-line description, "single-quoted literal" is as
 |exact as it gets: both making it clear that this is purely
 |presentational, and stating precisely how it looks.
 |
 |Your proposed wording "format quoted literal" does *not* indicate
 |any semantic expressiveness either, so i don't understand why you
 |call it "semantics-centric".  Besides, it has two issues:

Ingo, it is your manual.  But please notice that someone who
is already heroic enough to use mdoc(7) (!) to document (!) her
code (!) instead of using man(7) (!) already has a walk through
hell (German «Leidensweg» is the thing i'm talking about).

 | 1. The word "format" is redundant.  It is implied by the purpose
 |    of the MACRO OVERVIEW list and applies to all macros.
 |    Consequently, not a single instance of that word exists
 |    in the whole section.

Yes.

 | 2. Dropping the word "single" seems wrong.  It merely loses
 |    precision for no good reason that i can see.  That's
 |    particularly bad since all the other entries for "Physical
 |    enclosures" explicitly name the enclosing character.
 |    So i don't understand why you call it "more correct".

I can only repeat that it actually took quite a lot of time,
including digging into a BSD history repository, to understand
that a mdoc(7) manual that uses .Ql quite a lot (mdoc(7) from GNU
troff) is displayed correctly in it's PDF form even if .Ql text is
*not* enclosed in single quotes.  And that GNU's mdoc(7) macros
are not buggy but reflect 1:1 the traditional mdoc(7) behaviour.
My impression was false because i personally was used to use
mdocml's mdoc(7), thinking it being more briefly and concise.

 |Happy New Year for you,

Ah, the Gregorian date fascism; and the noise; and the dirt!!
But i give it all back to you :-)

--steffen
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv