discuss@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Stephen Gregoratto <dev@sgregoratto.me>
Cc: discuss@mandoc.bsd.lv
Subject: Re: docbook2mdoc-1.0.0 released
Date: Thu, 25 Apr 2019 19:02:00 +0200	[thread overview]
Message-ID: <20190425170200.GC66649@athene.usta.de> (raw)
In-Reply-To: <20190421112632.z7fawjteacah4ypt@BlackBox>

Hi Stephen,

Stephen Gregoratto wrote on Sun, Apr 21, 2019 at 09:26:32PM +1000:

> My vote goes to Fl -option due to how mandoc handles Fl Fl
> in HTML output.

That isn't a very strong argument.
Best markup practice ought to be governed by what the markup means,
not by how individual output modes represent it.

> Take this example:
> 
>   .Bl -tag -width Ds
>   .It Fl Fl option
>   Foo
>   .It Fl -option
>   Bar
>   .El
> 
> On mandoc 1.14.5, the option list is output as follows:
> 
> <dl class="Bl-tag">
>   <dt>
>     <code class="Fl">-</code><code class="Fl">-option</code>
>   </dt>
>   <dd>Foo</dd>
>   <dt>
>     <a class="permalink" href="#-option">
>       <code class="Fl" id="-option">--option</code>
>     </a>
>   </dt>
>   <dd>Bar</dd>
> </dl>
> 
> Notice how the Fl -option gets enclosed in an "<a>" link whilst the Fl 
> Fl option doesn't? This comes in handy when you have to reference the 
> option later as it can link to it's definition in the option list.

Right.  This is because in the case of ".It Fl", mandoc is able to
figure out that this is likely the authoritative description of the
command line option.  By contrast, in the case of ".It Fl Fl",
mandoc is not able to figure out what is going on.  The first "Fl"
is empty, so it cannot be linked to.  A later "Fl" in ".It" cannot
safely be linked to either.  If "Fl" appears in the middle of other
macros, that is usually *not* the authoritative description of the
option.  Hence mandoc writes no permalink, nor a tag in terminal
output mode.

So in an indirect sense, your argument is sound after all.
The idiom "Fl Fl" is not a good idea because it obscures the
semantics.  The loss of the permalink (and of the tag in terminal
output) is a symptom of that degraded semantic clarity.

> On reflection this does seem like a workaround for buggy output.

No, the output is not buggy, but carefully designed.

It is not a bug, but a feature that not every .Fl macro creates a
permalink.  As a matter of fact, the majority of .Fl macros should
not create permalinks.  Most of them are merely passing mentions
of options in the middle of text describing other matters.

Macros only create permalinks when there are clear indications
that they introduce an authoritative description.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

  reply	other threads:[~2019-04-25 17:02 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-04-17 19:24 Ingo Schwarze
2019-04-20 19:03 ` Jan Stary
2019-04-20 22:56   ` Anthony J. Bentley
2019-04-21 12:32     ` hyphen-minus, was: " Ingo Schwarze
2019-04-21 16:32       ` Anthony J. Bentley
2019-04-21 11:26   ` Stephen Gregoratto
2019-04-25 17:02     ` Ingo Schwarze [this message]
2019-04-21 15:29   ` Ingo Schwarze

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190425170200.GC66649@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=dev@sgregoratto.me \
    --cc=discuss@mandoc.bsd.lv \
    --subject='Re: docbook2mdoc-1.0.0 released' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).